git.sesse.net Git - vlc/blob - include/vlc/libvlc_media_player.h

   1 /*****************************************************************************
   2  * libvlc_media_player.h:  libvlc_media_player external API
   3  *****************************************************************************
   4  * Copyright (C) 1998-2010 VLC authors and VideoLAN
   5  * $Id$
   6  *
   7  * Authors: Clément Stenac <zorglub@videolan.org>
   8  *          Jean-Paul Saman <jpsaman@videolan.org>
   9  *          Pierre d'Herbemont <pdherbemont@videolan.org>
  10  *
  11  * This program is free software; you can redistribute it and/or modify it
  12  * under the terms of the GNU Lesser General Public License as published by
  13  * the Free Software Foundation; either version 2.1 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  19  * GNU Lesser General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Lesser General Public License
  22  * along with this program; if not, write to the Free Software Foundation,
  23  * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  24  *****************************************************************************/
  25
  26 /**
  27  * \file
  28  * This file defines libvlc_media_player external API
  29  */
  30
  31 #ifndef VLC_LIBVLC_MEDIA_PLAYER_H
  32 #define VLC_LIBVLC_MEDIA_PLAYER_H 1
  33
  34 # ifdef __cplusplus
  35 extern "C" {
  36 # else
  37 #  include <stdbool.h>
  38 # endif
  39
  40 /*****************************************************************************
  41  * Media Player
  42  *****************************************************************************/
  43 /** \defgroup libvlc_media_player LibVLC media player
  44  * \ingroup libvlc
  45  * A LibVLC media player plays one media (usually in a custom drawable).
  46  * @{
  47  */
  48
  49 typedef struct libvlc_media_player_t libvlc_media_player_t;
  50
  51 /**
  52  * Description for video, audio tracks and subtitles. It contains
  53  * id, name (description string) and pointer to next record.
  54  */
  55 typedef struct libvlc_track_description_t
  56 {
  57     int   i_id;
  58     char *psz_name;
  59     struct libvlc_track_description_t *p_next;
  60
  61 } libvlc_track_description_t;
  62
  63 /**
  64  * Description for audio output. It contains
  65  * name, description and pointer to next record.
  66  */
  67 typedef struct libvlc_audio_output_t
  68 {
  69     char *psz_name;
  70     char *psz_description;
  71     struct libvlc_audio_output_t *p_next;
  72
  73 } libvlc_audio_output_t;
  74
  75 /**
  76  * Description for audio output device.
  77  */
  78 typedef struct libvlc_audio_output_device_t
  79 {
  80     struct libvlc_audio_output_device_t *p_next; /**< Next entry in list */
  81     char *psz_device; /**< Device identifier string */
  82     char *psz_description; /**< User-friendly device description */
  83     /* More fields may be added here in later versions */
  84 } libvlc_audio_output_device_t;
  85
  86 /**
  87  * Rectangle type for video geometry
  88  */
  89 typedef struct libvlc_rectangle_t
  90 {
  91     int top, left;
  92     int bottom, right;
  93 } libvlc_rectangle_t;
  94
  95 /**
  96  * Marq options definition
  97  */
  98 typedef enum libvlc_video_marquee_option_t {
  99     libvlc_marquee_Enable = 0,
 100     libvlc_marquee_Text,                  /** string argument */
 101     libvlc_marquee_Color,
 102     libvlc_marquee_Opacity,
 103     libvlc_marquee_Position,
 104     libvlc_marquee_Refresh,
 105     libvlc_marquee_Size,
 106     libvlc_marquee_Timeout,
 107     libvlc_marquee_X,
 108     libvlc_marquee_Y
 109 } libvlc_video_marquee_option_t;
 110
 111 /**
 112  * Navigation mode
 113  */
 114 typedef enum libvlc_navigate_mode_t
 115 {
 116     libvlc_navigate_activate = 0,
 117     libvlc_navigate_up,
 118     libvlc_navigate_down,
 119     libvlc_navigate_left,
 120     libvlc_navigate_right
 121 } libvlc_navigate_mode_t;
 122
 123 /**
 124  * Create an empty Media Player object
 125  *
 126  * \param p_libvlc_instance the libvlc instance in which the Media Player
 127  *        should be created.
 128  * \return a new media player object, or NULL on error.
 129  */
 130 LIBVLC_API libvlc_media_player_t * libvlc_media_player_new( libvlc_instance_t *p_libvlc_instance );
 131
 132 /**
 133  * Create a Media Player object from a Media
 134  *
 135  * \param p_md the media. Afterwards the p_md can be safely
 136  *        destroyed.
 137  * \return a new media player object, or NULL on error.
 138  */
 139 LIBVLC_API libvlc_media_player_t * libvlc_media_player_new_from_media( libvlc_media_t *p_md );
 140
 141 /**
 142  * Release a media_player after use
 143  * Decrement the reference count of a media player object. If the
 144  * reference count is 0, then libvlc_media_player_release() will
 145  * release the media player object. If the media player object
 146  * has been released, then it should not be used again.
 147  *
 148  * \param p_mi the Media Player to free
 149  */
 150 LIBVLC_API void libvlc_media_player_release( libvlc_media_player_t *p_mi );
 151
 152 /**
 153  * Retain a reference to a media player object. Use
 154  * libvlc_media_player_release() to decrement reference count.
 155  *
 156  * \param p_mi media player object
 157  */
 158 LIBVLC_API void libvlc_media_player_retain( libvlc_media_player_t *p_mi );
 159
 160 /**
 161  * Set the media that will be used by the media_player. If any,
 162  * previous md will be released.
 163  *
 164  * \param p_mi the Media Player
 165  * \param p_md the Media. Afterwards the p_md can be safely
 166  *        destroyed.
 167  */
 168 LIBVLC_API void libvlc_media_player_set_media( libvlc_media_player_t *p_mi,
 169                                                    libvlc_media_t *p_md );
 170
 171 /**
 172  * Get the media used by the media_player.
 173  *
 174  * \param p_mi the Media Player
 175  * \return the media associated with p_mi, or NULL if no
 176  *         media is associated
 177  */
 178 LIBVLC_API libvlc_media_t * libvlc_media_player_get_media( libvlc_media_player_t *p_mi );
 179
 180 /**
 181  * Get the Event Manager from which the media player send event.
 182  *
 183  * \param p_mi the Media Player
 184  * \return the event manager associated with p_mi
 185  */
 186 LIBVLC_API libvlc_event_manager_t * libvlc_media_player_event_manager ( libvlc_media_player_t *p_mi );
 187
 188 /**
 189  * is_playing
 190  *
 191  * \param p_mi the Media Player
 192  * \return 1 if the media player is playing, 0 otherwise
 193  *
 194  * \libvlc_return_bool
 195  */
 196 LIBVLC_API int libvlc_media_player_is_playing ( libvlc_media_player_t *p_mi );
 197
 198 /**
 199  * Play
 200  *
 201  * \param p_mi the Media Player
 202  * \return 0 if playback started (and was already started), or -1 on error.
 203  */
 204 LIBVLC_API int libvlc_media_player_play ( libvlc_media_player_t *p_mi );
 205
 206 /**
 207  * Pause or resume (no effect if there is no media)
 208  *
 209  * \param mp the Media Player
 210  * \param do_pause play/resume if zero, pause if non-zero
 211  * \version LibVLC 1.1.1 or later
 212  */
 213 LIBVLC_API void libvlc_media_player_set_pause ( libvlc_media_player_t *mp,
 214                                                     int do_pause );
 215
 216 /**
 217  * Toggle pause (no effect if there is no media)
 218  *
 219  * \param p_mi the Media Player
 220  */
 221 LIBVLC_API void libvlc_media_player_pause ( libvlc_media_player_t *p_mi );
 222
 223 /**
 224  * Stop (no effect if there is no media)
 225  *
 226  * \param p_mi the Media Player
 227  */
 228 LIBVLC_API void libvlc_media_player_stop ( libvlc_media_player_t *p_mi );
 229
 230 /**
 231  * Callback prototype to allocate and lock a picture buffer.
 232  *
 233  * Whenever a new video frame needs to be decoded, the lock callback is
 234  * invoked. Depending on the video chroma, one or three pixel planes of
 235  * adequate dimensions must be returned via the second parameter. Those
 236  * planes must be aligned on 32-bytes boundaries.
 237  *
 238  * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]
 239  * \param planes start address of the pixel planes (LibVLC allocates the array
 240  *             of void pointers, this callback must initialize the array) [OUT]
 241  * \return a private pointer for the display and unlock callbacks to identify
 242  *         the picture buffers
 243  */
 244 typedef void *(*libvlc_video_lock_cb)(void *opaque, void **planes);
 245
 246 /**
 247  * Callback prototype to unlock a picture buffer.
 248  *
 249  * When the video frame decoding is complete, the unlock callback is invoked.
 250  * This callback might not be needed at all. It is only an indication that the
 251  * application can now read the pixel values if it needs to.
 252  *
 253  * \warning A picture buffer is unlocked after the picture is decoded,
 254  * but before the picture is displayed.
 255  *
 256  * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]
 257  * \param picture private pointer returned from the @ref libvlc_video_lock_cb
 258  *                callback [IN]
 259  * \param planes pixel planes as defined by the @ref libvlc_video_lock_cb
 260  *               callback (this parameter is only for convenience) [IN]
 261  */
 262 typedef void (*libvlc_video_unlock_cb)(void *opaque, void *picture,
 263                                        void *const *planes);
 264
 265 /**
 266  * Callback prototype to display a picture.
 267  *
 268  * When the video frame needs to be shown, as determined by the media playback
 269  * clock, the display callback is invoked.
 270  *
 271  * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]
 272  * \param picture private pointer returned from the @ref libvlc_video_lock_cb
 273  *                callback [IN]
 274  */
 275 typedef void (*libvlc_video_display_cb)(void *opaque, void *picture);
 276
 277 /**
 278  * Callback prototype to configure picture buffers format.
 279  * This callback gets the format of the video as output by the video decoder
 280  * and the chain of video filters (if any). It can opt to change any parameter
 281  * as it needs. In that case, LibVLC will attempt to convert the video format
 282  * (rescaling and chroma conversion) but these operations can be CPU intensive.
 283  *
 284  * \param opaque pointer to the private pointer passed to
 285  *               libvlc_video_set_callbacks() [IN/OUT]
 286  * \param chroma pointer to the 4 bytes video format identifier [IN/OUT]
 287  * \param width pointer to the pixel width [IN/OUT]
 288  * \param height pointer to the pixel height [IN/OUT]
 289  * \param pitches table of scanline pitches in bytes for each pixel plane
 290  *                (the table is allocated by LibVLC) [OUT]
 291  * \param lines table of scanlines count for each plane [OUT]
 292  * \return the number of picture buffers allocated, 0 indicates failure
 293  *
 294  * \note
 295  * For each pixels plane, the scanline pitch must be bigger than or equal to
 296  * the number of bytes per pixel multiplied by the pixel width.
 297  * Similarly, the number of scanlines must be bigger than of equal to
 298  * the pixel height.
 299  * Furthermore, we recommend that pitches and lines be multiple of 32
 300  * to not break assumption that might be made by various optimizations
 301  * in the video decoders, video filters and/or video converters.
 302  */
 303 typedef unsigned (*libvlc_video_format_cb)(void **opaque, char *chroma,
 304                                            unsigned *width, unsigned *height,
 305                                            unsigned *pitches,
 306                                            unsigned *lines);
 307
 308 /**
 309  * Callback prototype to configure picture buffers format.
 310  *
 311  * \param opaque private pointer as passed to libvlc_video_set_callbacks()
 312  *               (and possibly modified by @ref libvlc_video_format_cb) [IN]
 313  */
 314 typedef void (*libvlc_video_cleanup_cb)(void *opaque);
 315
 316
 317 /**
 318  * Set callbacks and private data to render decoded video to a custom area
 319  * in memory.
 320  * Use libvlc_video_set_format() or libvlc_video_set_format_callbacks()
 321  * to configure the decoded format.
 322  *
 323  * \param mp the media player
 324  * \param lock callback to lock video memory (must not be NULL)
 325  * \param unlock callback to unlock video memory (or NULL if not needed)
 326  * \param display callback to display video (or NULL if not needed)
 327  * \param opaque private pointer for the three callbacks (as first parameter)
 328  * \version LibVLC 1.1.1 or later
 329  */
 330 LIBVLC_API
 331 void libvlc_video_set_callbacks( libvlc_media_player_t *mp,
 332                                  libvlc_video_lock_cb lock,
 333                                  libvlc_video_unlock_cb unlock,
 334                                  libvlc_video_display_cb display,
 335                                  void *opaque );
 336
 337 /**
 338  * Set decoded video chroma and dimensions.
 339  * This only works in combination with libvlc_video_set_callbacks(),
 340  * and is mutually exclusive with libvlc_video_set_format_callbacks().
 341  *
 342  * \param mp the media player
 343  * \param chroma a four-characters string identifying the chroma
 344  *               (e.g. "RV32" or "YUYV")
 345  * \param width pixel width
 346  * \param height pixel height
 347  * \param pitch line pitch (in bytes)
 348  * \version LibVLC 1.1.1 or later
 349  * \bug All pixel planes are expected to have the same pitch.
 350  * To use the YCbCr color space with chrominance subsampling,
 351  * consider using libvlc_video_set_format_callbacks() instead.
 352  */
 353 LIBVLC_API
 354 void libvlc_video_set_format( libvlc_media_player_t *mp, const char *chroma,
 355                               unsigned width, unsigned height,
 356                               unsigned pitch );
 357
 358 /**
 359  * Set decoded video chroma and dimensions. This only works in combination with
 360  * libvlc_video_set_callbacks().
 361  *
 362  * \param mp the media player
 363  * \param setup callback to select the video format (cannot be NULL)
 364  * \param cleanup callback to release any allocated resources (or NULL)
 365  * \version LibVLC 2.0.0 or later
 366  */
 367 LIBVLC_API
 368 void libvlc_video_set_format_callbacks( libvlc_media_player_t *mp,
 369                                         libvlc_video_format_cb setup,
 370                                         libvlc_video_cleanup_cb cleanup );
 371
 372 /**
 373  * Set the NSView handler where the media player should render its video output.
 374  *
 375  * Use the vout called "macosx".
 376  *
 377  * The drawable is an NSObject that follow the VLCOpenGLVideoViewEmbedding
 378  * protocol:
 379  *
 380  * @begincode
 381  * \@protocol VLCOpenGLVideoViewEmbedding <NSObject>
 382  * - (void)addVoutSubview:(NSView *)view;
 383  * - (void)removeVoutSubview:(NSView *)view;
 384  * \@end
 385  * @endcode
 386  *
 387  * Or it can be an NSView object.
 388  *
 389  * If you want to use it along with Qt4 see the QMacCocoaViewContainer. Then
 390  * the following code should work:
 391  * @begincode
 392  * {
 393  *     NSView *video = [[NSView alloc] init];
 394  *     QMacCocoaViewContainer *container = new QMacCocoaViewContainer(video, parent);
 395  *     libvlc_media_player_set_nsobject(mp, video);
 396  *     [video release];
 397  * }
 398  * @endcode
 399  *
 400  * You can find a live example in VLCVideoView in VLCKit.framework.
 401  *
 402  * \param p_mi the Media Player
 403  * \param drawable the drawable that is either an NSView or an object following
 404  * the VLCOpenGLVideoViewEmbedding protocol.
 405  */
 406 LIBVLC_API void libvlc_media_player_set_nsobject ( libvlc_media_player_t *p_mi, void * drawable );
 407
 408 /**
 409  * Get the NSView handler previously set with libvlc_media_player_set_nsobject().
 410  *
 411  * \param p_mi the Media Player
 412  * \return the NSView handler or 0 if none where set
 413  */
 414 LIBVLC_API void * libvlc_media_player_get_nsobject ( libvlc_media_player_t *p_mi );
 415
 416 /**
 417  * Set the agl handler where the media player should render its video output.
 418  *
 419  * \param p_mi the Media Player
 420  * \param drawable the agl handler
 421  */
 422 LIBVLC_API void libvlc_media_player_set_agl ( libvlc_media_player_t *p_mi, uint32_t drawable );
 423
 424 /**
 425  * Get the agl handler previously set with libvlc_media_player_set_agl().
 426  *
 427  * \param p_mi the Media Player
 428  * \return the agl handler or 0 if none where set
 429  */
 430 LIBVLC_API uint32_t libvlc_media_player_get_agl ( libvlc_media_player_t *p_mi );
 431
 432 /**
 433  * Set an X Window System drawable where the media player should render its
 434  * video output. If LibVLC was built without X11 output support, then this has
 435  * no effects.
 436  *
 437  * The specified identifier must correspond to an existing Input/Output class
 438  * X11 window. Pixmaps are <b>not</b> supported. The caller shall ensure that
 439  * the X11 server is the same as the one the VLC instance has been configured
 440  * with. This function must be called before video playback is started;
 441  * otherwise it will only take effect after playback stop and restart.
 442  *
 443  * \param p_mi the Media Player
 444  * \param drawable the ID of the X window
 445  */
 446 LIBVLC_API void libvlc_media_player_set_xwindow ( libvlc_media_player_t *p_mi, uint32_t drawable );
 447
 448 /**
 449  * Get the X Window System window identifier previously set with
 450  * libvlc_media_player_set_xwindow(). Note that this will return the identifier
 451  * even if VLC is not currently using it (for instance if it is playing an
 452  * audio-only input).
 453  *
 454  * \param p_mi the Media Player
 455  * \return an X window ID, or 0 if none where set.
 456  */
 457 LIBVLC_API uint32_t libvlc_media_player_get_xwindow ( libvlc_media_player_t *p_mi );
 458
 459 /**
 460  * Set a Win32/Win64 API window handle (HWND) where the media player should
 461  * render its video output. If LibVLC was built without Win32/Win64 API output
 462  * support, then this has no effects.
 463  *
 464  * \param p_mi the Media Player
 465  * \param drawable windows handle of the drawable
 466  */
 467 LIBVLC_API void libvlc_media_player_set_hwnd ( libvlc_media_player_t *p_mi, void *drawable );
 468
 469 /**
 470  * Get the Windows API window handle (HWND) previously set with
 471  * libvlc_media_player_set_hwnd(). The handle will be returned even if LibVLC
 472  * is not currently outputting any video to it.
 473  *
 474  * \param p_mi the Media Player
 475  * \return a window handle or NULL if there are none.
 476  */
 477 LIBVLC_API void *libvlc_media_player_get_hwnd ( libvlc_media_player_t *p_mi );
 478
 479 /**
 480  * Callback prototype for audio playback.
 481  * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
 482  * \param samples pointer to the first audio sample to play back [IN]
 483  * \param count number of audio samples to play back
 484  * \param pts expected play time stamp (see libvlc_delay())
 485  */
 486 typedef void (*libvlc_audio_play_cb)(void *data, const void *samples,
 487                                      unsigned count, int64_t pts);
 488
 489 /**
 490  * Callback prototype for audio pause.
 491  * \note The pause callback is never called if the audio is already paused.
 492  * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
 493  * \param pts time stamp of the pause request (should be elapsed already)
 494  */
 495 typedef void (*libvlc_audio_pause_cb)(void *data, int64_t pts);
 496
 497 /**
 498  * Callback prototype for audio resumption (i.e. restart from pause).
 499  * \note The resume callback is never called if the audio is not paused.
 500  * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
 501  * \param pts time stamp of the resumption request (should be elapsed already)
 502  */
 503 typedef void (*libvlc_audio_resume_cb)(void *data, int64_t pts);
 504
 505 /**
 506  * Callback prototype for audio buffer flush
 507  * (i.e. discard all pending buffers and stop playback as soon as possible).
 508  * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
 509  */
 510 typedef void (*libvlc_audio_flush_cb)(void *data, int64_t pts);
 511
 512 /**
 513  * Callback prototype for audio buffer drain
 514  * (i.e. wait for pending buffers to be played).
 515  * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
 516  */
 517 typedef void (*libvlc_audio_drain_cb)(void *data);
 518
 519 /**
 520  * Callback prototype for audio volume change.
 521  * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
 522  * \param volume software volume (1. = nominal, 0. = mute)
 523  * \param mute muted flag
 524  */
 525 typedef void (*libvlc_audio_set_volume_cb)(void *data,
 526                                            float volume, bool mute);
 527
 528 /**
 529  * Set callbacks and private data for decoded audio.
 530  * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks()
 531  * to configure the decoded audio format.
 532  *
 533  * \param mp the media player
 534  * \param play callback to play audio samples (must not be NULL)
 535  * \param pause callback to pause playback (or NULL to ignore)
 536  * \param resume callback to resume playback (or NULL to ignore)
 537  * \param flush callback to flush audio buffers (or NULL to ignore)
 538  * \param drain callback to drain audio buffers (or NULL to ignore)
 539  * \param opaque private pointer for the audio callbacks (as first parameter)
 540  * \version LibVLC 2.0.0 or later
 541  */
 542 LIBVLC_API
 543 void libvlc_audio_set_callbacks( libvlc_media_player_t *mp,
 544                                  libvlc_audio_play_cb play,
 545                                  libvlc_audio_pause_cb pause,
 546                                  libvlc_audio_resume_cb resume,
 547                                  libvlc_audio_flush_cb flush,
 548                                  libvlc_audio_drain_cb drain,
 549                                  void *opaque );
 550
 551 /**
 552  * Set callbacks and private data for decoded audio.
 553  * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks()
 554  * to configure the decoded audio format.
 555  *
 556  * \param mp the media player
 557  * \param set_volume callback to apply audio volume,
 558  *                   or NULL to apply volume in software
 559  * \version LibVLC 2.0.0 or later
 560  */
 561 LIBVLC_API
 562 void libvlc_audio_set_volume_callback( libvlc_media_player_t *mp,
 563                                        libvlc_audio_set_volume_cb set_volume );
 564
 565 /**
 566  * Callback prototype to setup the audio playback.
 567  * This is called when the media player needs to create a new audio output.
 568  * \param opaque pointer to the data pointer passed to
 569  *               libvlc_audio_set_callbacks() [IN/OUT]
 570  * \param format 4 bytes sample format [IN/OUT]
 571  * \param rate sample rate [IN/OUT]
 572  * \param channels channels count [IN/OUT]
 573  * \return 0 on success, anything else to skip audio playback
 574  */
 575 typedef int (*libvlc_audio_setup_cb)(void **data, char *format, unsigned *rate,
 576                                      unsigned *channels);
 577
 578 /**
 579  * Callback prototype for audio playback cleanup.
 580  * This is called when the media player no longer needs an audio output.
 581  * \param opaque data pointer as passed to libvlc_audio_set_callbacks() [IN]
 582  */
 583 typedef void (*libvlc_audio_cleanup_cb)(void *data);
 584
 585 /**
 586  * Set decoded audio format. This only works in combination with
 587  * libvlc_audio_set_callbacks().
 588  *
 589  * \param mp the media player
 590  * \param setup callback to select the audio format (cannot be NULL)
 591  * \param cleanup callback to release any allocated resources (or NULL)
 592  * \version LibVLC 2.0.0 or later
 593  */
 594 LIBVLC_API
 595 void libvlc_audio_set_format_callbacks( libvlc_media_player_t *mp,
 596                                         libvlc_audio_setup_cb setup,
 597                                         libvlc_audio_cleanup_cb cleanup );
 598
 599 /**
 600  * Set decoded audio format.
 601  * This only works in combination with libvlc_audio_set_callbacks(),
 602  * and is mutually exclusive with libvlc_audio_set_format_callbacks().
 603  *
 604  * \param mp the media player
 605  * \param format a four-characters string identifying the sample format
 606  *               (e.g. "S16N" or "FL32")
 607  * \param rate sample rate (expressed in Hz)
 608  * \param channels channels count
 609  * \version LibVLC 2.0.0 or later
 610  */
 611 LIBVLC_API
 612 void libvlc_audio_set_format( libvlc_media_player_t *mp, const char *format,
 613                               unsigned rate, unsigned channels );
 614
 615 /** \bug This might go away ... to be replaced by a broader system */
 616
 617 /**
 618  * Get the current movie length (in ms).
 619  *
 620  * \param p_mi the Media Player
 621  * \return the movie length (in ms), or -1 if there is no media.
 622  */
 623 LIBVLC_API libvlc_time_t libvlc_media_player_get_length( libvlc_media_player_t *p_mi );
 624
 625 /**
 626  * Get the current movie time (in ms).
 627  *
 628  * \param p_mi the Media Player
 629  * \return the movie time (in ms), or -1 if there is no media.
 630  */
 631 LIBVLC_API libvlc_time_t libvlc_media_player_get_time( libvlc_media_player_t *p_mi );
 632
 633 /**
 634  * Set the movie time (in ms). This has no effect if no media is being played.
 635  * Not all formats and protocols support this.
 636  *
 637  * \param p_mi the Media Player
 638  * \param i_time the movie time (in ms).
 639  */
 640 LIBVLC_API void libvlc_media_player_set_time( libvlc_media_player_t *p_mi, libvlc_time_t i_time );
 641
 642 /**
 643  * Get movie position.
 644  *
 645  * \param p_mi the Media Player
 646  * \return movie position, or -1. in case of error
 647  */
 648 LIBVLC_API float libvlc_media_player_get_position( libvlc_media_player_t *p_mi );
 649
 650 /**
 651  * Set movie position. This has no effect if playback is not enabled.
 652  * This might not work depending on the underlying input format and protocol.
 653  *
 654  * \param p_mi the Media Player
 655  * \param f_pos the position
 656  */
 657 LIBVLC_API void libvlc_media_player_set_position( libvlc_media_player_t *p_mi, float f_pos );
 658
 659 /**
 660  * Set movie chapter (if applicable).
 661  *
 662  * \param p_mi the Media Player
 663  * \param i_chapter chapter number to play
 664  */
 665 LIBVLC_API void libvlc_media_player_set_chapter( libvlc_media_player_t *p_mi, int i_chapter );
 666
 667 /**
 668  * Get movie chapter.
 669  *
 670  * \param p_mi the Media Player
 671  * \return chapter number currently playing, or -1 if there is no media.
 672  */
 673 LIBVLC_API int libvlc_media_player_get_chapter( libvlc_media_player_t *p_mi );
 674
 675 /**
 676  * Get movie chapter count
 677  *
 678  * \param p_mi the Media Player
 679  * \return number of chapters in movie, or -1.
 680  */
 681 LIBVLC_API int libvlc_media_player_get_chapter_count( libvlc_media_player_t *p_mi );
 682
 683 /**
 684  * Is the player able to play
 685  *
 686  * \param p_mi the Media Player
 687  * \return boolean
 688  *
 689  * \libvlc_return_bool
 690  */
 691 LIBVLC_API int libvlc_media_player_will_play( libvlc_media_player_t *p_mi );
 692
 693 /**
 694  * Get title chapter count
 695  *
 696  * \param p_mi the Media Player
 697  * \param i_title title
 698  * \return number of chapters in title, or -1
 699  */
 700 LIBVLC_API int libvlc_media_player_get_chapter_count_for_title(
 701                        libvlc_media_player_t *p_mi, int i_title );
 702
 703 /**
 704  * Set movie title
 705  *
 706  * \param p_mi the Media Player
 707  * \param i_title title number to play
 708  */
 709 LIBVLC_API void libvlc_media_player_set_title( libvlc_media_player_t *p_mi, int i_title );
 710
 711 /**
 712  * Get movie title
 713  *
 714  * \param p_mi the Media Player
 715  * \return title number currently playing, or -1
 716  */
 717 LIBVLC_API int libvlc_media_player_get_title( libvlc_media_player_t *p_mi );
 718
 719 /**
 720  * Get movie title count
 721  *
 722  * \param p_mi the Media Player
 723  * \return title number count, or -1
 724  */
 725 LIBVLC_API int libvlc_media_player_get_title_count( libvlc_media_player_t *p_mi );
 726
 727 /**
 728  * Set previous chapter (if applicable)
 729  *
 730  * \param p_mi the Media Player
 731  */
 732 LIBVLC_API void libvlc_media_player_previous_chapter( libvlc_media_player_t *p_mi );
 733
 734 /**
 735  * Set next chapter (if applicable)
 736  *
 737  * \param p_mi the Media Player
 738  */
 739 LIBVLC_API void libvlc_media_player_next_chapter( libvlc_media_player_t *p_mi );
 740
 741 /**
 742  * Get the requested movie play rate.
 743  * @warning Depending on the underlying media, the requested rate may be
 744  * different from the real playback rate.
 745  *
 746  * \param p_mi the Media Player
 747  * \return movie play rate
 748  */
 749 LIBVLC_API float libvlc_media_player_get_rate( libvlc_media_player_t *p_mi );
 750
 751 /**
 752  * Set movie play rate
 753  *
 754  * \param p_mi the Media Player
 755  * \param rate movie play rate to set
 756  * \return -1 if an error was detected, 0 otherwise (but even then, it might
 757  * not actually work depending on the underlying media protocol)
 758  */
 759 LIBVLC_API int libvlc_media_player_set_rate( libvlc_media_player_t *p_mi, float rate );
 760
 761 /**
 762  * Get current movie state
 763  *
 764  * \param p_mi the Media Player
 765  * \return the current state of the media player (playing, paused, ...) \see libvlc_state_t
 766  */
 767 LIBVLC_API libvlc_state_t libvlc_media_player_get_state( libvlc_media_player_t *p_mi );
 768
 769 /**
 770  * Get movie fps rate
 771  *
 772  * \param p_mi the Media Player
 773  * \return frames per second (fps) for this playing movie, or 0 if unspecified
 774  */
 775 LIBVLC_API float libvlc_media_player_get_fps( libvlc_media_player_t *p_mi );
 776
 777 /** end bug */
 778
 779 /**
 780  * How many video outputs does this media player have?
 781  *
 782  * \param p_mi the media player
 783  * \return the number of video outputs
 784  */
 785 LIBVLC_API unsigned libvlc_media_player_has_vout( libvlc_media_player_t *p_mi );
 786
 787 /**
 788  * Is this media player seekable?
 789  *
 790  * \param p_mi the media player
 791  * \return true if the media player can seek
 792  *
 793  * \libvlc_return_bool
 794  */
 795 LIBVLC_API int libvlc_media_player_is_seekable( libvlc_media_player_t *p_mi );
 796
 797 /**
 798  * Can this media player be paused?
 799  *
 800  * \param p_mi the media player
 801  * \return true if the media player can pause
 802  *
 803  * \libvlc_return_bool
 804  */
 805 LIBVLC_API int libvlc_media_player_can_pause( libvlc_media_player_t *p_mi );
 806
 807
 808 /**
 809  * Display the next frame (if supported)
 810  *
 811  * \param p_mi the media player
 812  */
 813 LIBVLC_API void libvlc_media_player_next_frame( libvlc_media_player_t *p_mi );
 814
 815 /**
 816  * Navigate through DVD Menu
 817  *
 818  * \param p_mi the Media Player
 819  * \param navigate the Navigation mode
 820  * \version libVLC 2.0.0 or later
 821  */
 822 LIBVLC_API void libvlc_media_player_navigate( libvlc_media_player_t* p_mi,
 823                                               unsigned navigate );
 824
 825 /**
 826  * Release (free) libvlc_track_description_t
 827  *
 828  * \param p_track_description the structure to release
 829  */
 830 LIBVLC_API void libvlc_track_description_list_release( libvlc_track_description_t *p_track_description );
 831
 832 /**
 833  * \deprecated Use libvlc_track_description_list_release instead
 834  */
 835 LIBVLC_DEPRECATED LIBVLC_API
 836 void libvlc_track_description_release( libvlc_track_description_t *p_track_description );
 837
 838 /** \defgroup libvlc_video LibVLC video controls
 839  * @{
 840  */
 841
 842 /**
 843  * Toggle fullscreen status on non-embedded video outputs.
 844  *
 845  * @warning The same limitations applies to this function
 846  * as to libvlc_set_fullscreen().
 847  *
 848  * \param p_mi the media player
 849  */
 850 LIBVLC_API void libvlc_toggle_fullscreen( libvlc_media_player_t *p_mi );
 851
 852 /**
 853  * Enable or disable fullscreen.
 854  *
 855  * @warning With most window managers, only a top-level windows can be in
 856  * full-screen mode. Hence, this function will not operate properly if
 857  * libvlc_media_player_set_xwindow() was used to embed the video in a
 858  * non-top-level window. In that case, the embedding window must be reparented
 859  * to the root window <b>before</b> fullscreen mode is enabled. You will want
 860  * to reparent it back to its normal parent when disabling fullscreen.
 861  *
 862  * \param p_mi the media player
 863  * \param b_fullscreen boolean for fullscreen status
 864  */
 865 LIBVLC_API void libvlc_set_fullscreen( libvlc_media_player_t *p_mi, int b_fullscreen );
 866
 867 /**
 868  * Get current fullscreen status.
 869  *
 870  * \param p_mi the media player
 871  * \return the fullscreen status (boolean)
 872  *
 873  * \libvlc_return_bool
 874  */
 875 LIBVLC_API int libvlc_get_fullscreen( libvlc_media_player_t *p_mi );
 876
 877 /**
 878  * Enable or disable key press events handling, according to the LibVLC hotkeys
 879  * configuration. By default and for historical reasons, keyboard events are
 880  * handled by the LibVLC video widget.
 881  *
 882  * \note On X11, there can be only one subscriber for key press and mouse
 883  * click events per window. If your application has subscribed to those events
 884  * for the X window ID of the video widget, then LibVLC will not be able to
 885  * handle key presses and mouse clicks in any case.
 886  *
 887  * \warning This function is only implemented for X11 and Win32 at the moment.
 888  *
 889  * \param p_mi the media player
 890  * \param on true to handle key press events, false to ignore them.
 891  */
 892 LIBVLC_API
 893 void libvlc_video_set_key_input( libvlc_media_player_t *p_mi, unsigned on );
 894
 895 /**
 896  * Enable or disable mouse click events handling. By default, those events are
 897  * handled. This is needed for DVD menus to work, as well as a few video
 898  * filters such as "puzzle".
 899  *
 900  * \see libvlc_video_set_key_input().
 901  *
 902  * \warning This function is only implemented for X11 and Win32 at the moment.
 903  *
 904  * \param p_mi the media player
 905  * \param on true to handle mouse click events, false to ignore them.
 906  */
 907 LIBVLC_API
 908 void libvlc_video_set_mouse_input( libvlc_media_player_t *p_mi, unsigned on );
 909
 910 /**
 911  * Get the pixel dimensions of a video.
 912  *
 913  * \param p_mi media player
 914  * \param num number of the video (starting from, and most commonly 0)
 915  * \param px pointer to get the pixel width [OUT]
 916  * \param py pointer to get the pixel height [OUT]
 917  * \return 0 on success, -1 if the specified video does not exist
 918  */
 919 LIBVLC_API
 920 int libvlc_video_get_size( libvlc_media_player_t *p_mi, unsigned num,
 921                            unsigned *px, unsigned *py );
 922
 923 /**
 924  * Get current video height.
 925  * \deprecated Use libvlc_video_get_size() instead.
 926  *
 927  * \param p_mi the media player
 928  * \return the video pixel height or 0 if not applicable
 929  */
 930 LIBVLC_DEPRECATED LIBVLC_API
 931 int libvlc_video_get_height( libvlc_media_player_t *p_mi );
 932
 933 /**
 934  * Get current video width.
 935  * \deprecated Use libvlc_video_get_size() instead.
 936  *
 937  * \param p_mi the media player
 938  * \return the video pixel width or 0 if not applicable
 939  */
 940 LIBVLC_DEPRECATED LIBVLC_API
 941 int libvlc_video_get_width( libvlc_media_player_t *p_mi );
 942
 943 /**
 944  * Get the mouse pointer coordinates over a video.
 945  * Coordinates are expressed in terms of the decoded video resolution,
 946  * <b>not</b> in terms of pixels on the screen/viewport (to get the latter,
 947  * you can query your windowing system directly).
 948  *
 949  * Either of the coordinates may be negative or larger than the corresponding
 950  * dimension of the video, if the cursor is outside the rendering area.
 951  *
 952  * @warning The coordinates may be out-of-date if the pointer is not located
 953  * on the video rendering area. LibVLC does not track the pointer if it is
 954  * outside of the video widget.
 955  *
 956  * @note LibVLC does not support multiple pointers (it does of course support
 957  * multiple input devices sharing the same pointer) at the moment.
 958  *
 959  * \param p_mi media player
 960  * \param num number of the video (starting from, and most commonly 0)
 961  * \param px pointer to get the abscissa [OUT]
 962  * \param py pointer to get the ordinate [OUT]
 963  * \return 0 on success, -1 if the specified video does not exist
 964  */
 965 LIBVLC_API
 966 int libvlc_video_get_cursor( libvlc_media_player_t *p_mi, unsigned num,
 967                              int *px, int *py );
 968
 969 /**
 970  * Get the current video scaling factor.
 971  * See also libvlc_video_set_scale().
 972  *
 973  * \param p_mi the media player
 974  * \return the currently configured zoom factor, or 0. if the video is set
 975  * to fit to the output window/drawable automatically.
 976  */
 977 LIBVLC_API float libvlc_video_get_scale( libvlc_media_player_t *p_mi );
 978
 979 /**
 980  * Set the video scaling factor. That is the ratio of the number of pixels on
 981  * screen to the number of pixels in the original decoded video in each
 982  * dimension. Zero is a special value; it will adjust the video to the output
 983  * window/drawable (in windowed mode) or the entire screen.
 984  *
 985  * Note that not all video outputs support scaling.
 986  *
 987  * \param p_mi the media player
 988  * \param f_factor the scaling factor, or zero
 989  */
 990 LIBVLC_API void libvlc_video_set_scale( libvlc_media_player_t *p_mi, float f_factor );
 991
 992 /**
 993  * Get current video aspect ratio.
 994  *
 995  * \param p_mi the media player
 996  * \return the video aspect ratio or NULL if unspecified
 997  * (the result must be released with free() or libvlc_free()).
 998  */
 999 LIBVLC_API char *libvlc_video_get_aspect_ratio( libvlc_media_player_t *p_mi );
1000
1001 /**
1002  * Set new video aspect ratio.
1003  *
1004  * \param p_mi the media player
1005  * \param psz_aspect new video aspect-ratio or NULL to reset to default
1006  * \note Invalid aspect ratios are ignored.
1007  */
1008 LIBVLC_API void libvlc_video_set_aspect_ratio( libvlc_media_player_t *p_mi, const char *psz_aspect );
1009
1010 /**
1011  * Get current video subtitle.
1012  *
1013  * \param p_mi the media player
1014  * \return the video subtitle selected, or -1 if none
1015  */
1016 LIBVLC_API int libvlc_video_get_spu( libvlc_media_player_t *p_mi );
1017
1018 /**
1019  * Get the number of available video subtitles.
1020  *
1021  * \param p_mi the media player
1022  * \return the number of available video subtitles
1023  */
1024 LIBVLC_API int libvlc_video_get_spu_count( libvlc_media_player_t *p_mi );
1025
1026 /**
1027  * Get the description of available video subtitles.
1028  *
1029  * \param p_mi the media player
1030  * \return list containing description of available video subtitles
1031  */
1032 LIBVLC_API libvlc_track_description_t *
1033         libvlc_video_get_spu_description( libvlc_media_player_t *p_mi );
1034
1035 /**
1036  * Set new video subtitle.
1037  *
1038  * \param p_mi the media player
1039  * \param i_spu new video subtitle to select
1040  * \return 0 on success, -1 if out of range
1041  */
1042 LIBVLC_API int libvlc_video_set_spu( libvlc_media_player_t *p_mi, unsigned i_spu );
1043
1044 /**
1045  * Set new video subtitle file.
1046  *
1047  * \param p_mi the media player
1048  * \param psz_subtitle new video subtitle file
1049  * \return the success status (boolean)
1050  */
1051 LIBVLC_API int libvlc_video_set_subtitle_file( libvlc_media_player_t *p_mi, const char *psz_subtitle );
1052
1053 /**
1054  * Get the current subtitle delay. Positive values means subtitles are being
1055  * displayed later, negative values earlier.
1056  *
1057  * \param p_mi media player
1058  * \return time (in microseconds) the display of subtitles is being delayed
1059  * \version LibVLC 2.0.0 or later
1060  */
1061 LIBVLC_API int64_t libvlc_video_get_spu_delay( libvlc_media_player_t *p_mi );
1062
1063 /**
1064  * Set the subtitle delay. This affects the timing of when the subtitle will
1065  * be displayed. Positive values result in subtitles being displayed later,
1066  * while negative values will result in subtitles being displayed earlier.
1067  *
1068  * The subtitle delay will be reset to zero each time the media changes.
1069  *
1070  * \param p_mi media player
1071  * \param i_delay time (in microseconds) the display of subtitles should be delayed
1072  * \return 0 on success, -1 on error
1073  * \version LibVLC 2.0.0 or later
1074  */
1075 LIBVLC_API int libvlc_video_set_spu_delay( libvlc_media_player_t *p_mi, int64_t i_delay );
1076
1077 /**
1078  * Get the description of available titles.
1079  *
1080  * \param p_mi the media player
1081  * \return list containing description of available titles
1082  */
1083 LIBVLC_API libvlc_track_description_t *
1084         libvlc_video_get_title_description( libvlc_media_player_t *p_mi );
1085
1086 /**
1087  * Get the description of available chapters for specific title.
1088  *
1089  * \param p_mi the media player
1090  * \param i_title selected title
1091  * \return list containing description of available chapter for title i_title
1092  */
1093 LIBVLC_API libvlc_track_description_t *
1094         libvlc_video_get_chapter_description( libvlc_media_player_t *p_mi, int i_title );
1095
1096 /**
1097  * Get current crop filter geometry.
1098  *
1099  * \param p_mi the media player
1100  * \return the crop filter geometry or NULL if unset
1101  */
1102 LIBVLC_API char *libvlc_video_get_crop_geometry( libvlc_media_player_t *p_mi );
1103
1104 /**
1105  * Set new crop filter geometry.
1106  *
1107  * \param p_mi the media player
1108  * \param psz_geometry new crop filter geometry (NULL to unset)
1109  */
1110 LIBVLC_API
1111 void libvlc_video_set_crop_geometry( libvlc_media_player_t *p_mi, const char *psz_geometry );
1112
1113 /**
1114  * Get current teletext page requested.
1115  *
1116  * \param p_mi the media player
1117  * \return the current teletext page requested.
1118  */
1119 LIBVLC_API int libvlc_video_get_teletext( libvlc_media_player_t *p_mi );
1120
1121 /**
1122  * Set new teletext page to retrieve.
1123  *
1124  * \param p_mi the media player
1125  * \param i_page teletex page number requested
1126  */
1127 LIBVLC_API void libvlc_video_set_teletext( libvlc_media_player_t *p_mi, int i_page );
1128
1129 /**
1130  * Toggle teletext transparent status on video output.
1131  *
1132  * \param p_mi the media player
1133  */
1134 LIBVLC_API void libvlc_toggle_teletext( libvlc_media_player_t *p_mi );
1135
1136 /**
1137  * Get number of available video tracks.
1138  *
1139  * \param p_mi media player
1140  * \return the number of available video tracks (int)
1141  */
1142 LIBVLC_API int libvlc_video_get_track_count( libvlc_media_player_t *p_mi );
1143
1144 /**
1145  * Get the description of available video tracks.
1146  *
1147  * \param p_mi media player
1148  * \return list with description of available video tracks, or NULL on error
1149  */
1150 LIBVLC_API libvlc_track_description_t *
1151         libvlc_video_get_track_description( libvlc_media_player_t *p_mi );
1152
1153 /**
1154  * Get current video track.
1155  *
1156  * \param p_mi media player
1157  * \return the video track ID (int) or -1 if no active input
1158  */
1159 LIBVLC_API int libvlc_video_get_track( libvlc_media_player_t *p_mi );
1160
1161 /**
1162  * Set video track.
1163  *
1164  * \param p_mi media player
1165  * \param i_track the track ID (i_id field from track description)
1166  * \return 0 on success, -1 if out of range
1167  */
1168 LIBVLC_API
1169 int libvlc_video_set_track( libvlc_media_player_t *p_mi, int i_track );
1170
1171 /**
1172  * Take a snapshot of the current video window.
1173  *
1174  * If i_width AND i_height is 0, original size is used.
1175  * If i_width XOR i_height is 0, original aspect-ratio is preserved.
1176  *
1177  * \param p_mi media player instance
1178  * \param num number of video output (typically 0 for the first/only one)
1179  * \param psz_filepath the path where to save the screenshot to
1180  * \param i_width the snapshot's width
1181  * \param i_height the snapshot's height
1182  * \return 0 on success, -1 if the video was not found
1183  */
1184 LIBVLC_API
1185 int libvlc_video_take_snapshot( libvlc_media_player_t *p_mi, unsigned num,
1186                                 const char *psz_filepath, unsigned int i_width,
1187                                 unsigned int i_height );
1188
1189 /**
1190  * Enable or disable deinterlace filter
1191  *
1192  * \param p_mi libvlc media player
1193  * \param psz_mode type of deinterlace filter, NULL to disable
1194  */
1195 LIBVLC_API void libvlc_video_set_deinterlace( libvlc_media_player_t *p_mi,
1196                                                   const char *psz_mode );
1197
1198 /**
1199  * Get an integer marquee option value
1200  *
1201  * \param p_mi libvlc media player
1202  * \param option marq option to get \see libvlc_video_marquee_int_option_t
1203  */
1204 LIBVLC_API int libvlc_video_get_marquee_int( libvlc_media_player_t *p_mi,
1205                                                  unsigned option );
1206
1207 /**
1208  * Get a string marquee option value
1209  *
1210  * \param p_mi libvlc media player
1211  * \param option marq option to get \see libvlc_video_marquee_string_option_t
1212  */
1213 LIBVLC_API char *libvlc_video_get_marquee_string( libvlc_media_player_t *p_mi,
1214                                                       unsigned option );
1215
1216 /**
1217  * Enable, disable or set an integer marquee option
1218  *
1219  * Setting libvlc_marquee_Enable has the side effect of enabling (arg !0)
1220  * or disabling (arg 0) the marq filter.
1221  *
1222  * \param p_mi libvlc media player
1223  * \param option marq option to set \see libvlc_video_marquee_int_option_t
1224  * \param i_val marq option value
1225  */
1226 LIBVLC_API void libvlc_video_set_marquee_int( libvlc_media_player_t *p_mi,
1227                                                   unsigned option, int i_val );
1228
1229 /**
1230  * Set a marquee string option
1231  *
1232  * \param p_mi libvlc media player
1233  * \param option marq option to set \see libvlc_video_marquee_string_option_t
1234  * \param psz_text marq option value
1235  */
1236 LIBVLC_API void libvlc_video_set_marquee_string( libvlc_media_player_t *p_mi,
1237                                                      unsigned option, const char *psz_text );
1238
1239 /** option values for libvlc_video_{get,set}_logo_{int,string} */
1240 enum libvlc_video_logo_option_t {
1241     libvlc_logo_enable,
1242     libvlc_logo_file,           /**< string argument, "file,d,t;file,d,t;..." */
1243     libvlc_logo_x,
1244     libvlc_logo_y,
1245     libvlc_logo_delay,
1246     libvlc_logo_repeat,
1247     libvlc_logo_opacity,
1248     libvlc_logo_position
1249 };
1250
1251 /**
1252  * Get integer logo option.
1253  *
1254  * \param p_mi libvlc media player instance
1255  * \param option logo option to get, values of libvlc_video_logo_option_t
1256  */
1257 LIBVLC_API int libvlc_video_get_logo_int( libvlc_media_player_t *p_mi,
1258                                               unsigned option );
1259
1260 /**
1261  * Set logo option as integer. Options that take a different type value
1262  * are ignored.
1263  * Passing libvlc_logo_enable as option value has the side effect of
1264  * starting (arg !0) or stopping (arg 0) the logo filter.
1265  *
1266  * \param p_mi libvlc media player instance
1267  * \param option logo option to set, values of libvlc_video_logo_option_t
1268  * \param value logo option value
1269  */
1270 LIBVLC_API void libvlc_video_set_logo_int( libvlc_media_player_t *p_mi,
1271                                                unsigned option, int value );
1272
1273 /**
1274  * Set logo option as string. Options that take a different type value
1275  * are ignored.
1276  *
1277  * \param p_mi libvlc media player instance
1278  * \param option logo option to set, values of libvlc_video_logo_option_t
1279  * \param psz_value logo option value
1280  */
1281 LIBVLC_API void libvlc_video_set_logo_string( libvlc_media_player_t *p_mi,
1282                                       unsigned option, const char *psz_value );
1283
1284
1285 /** option values for libvlc_video_{get,set}_adjust_{int,float,bool} */
1286 enum libvlc_video_adjust_option_t {
1287     libvlc_adjust_Enable = 0,
1288     libvlc_adjust_Contrast,
1289     libvlc_adjust_Brightness,
1290     libvlc_adjust_Hue,
1291     libvlc_adjust_Saturation,
1292     libvlc_adjust_Gamma
1293 };
1294
1295 /**
1296  * Get integer adjust option.
1297  *
1298  * \param p_mi libvlc media player instance
1299  * \param option adjust option to get, values of libvlc_video_adjust_option_t
1300  * \version LibVLC 1.1.1 and later.
1301  */
1302 LIBVLC_API int libvlc_video_get_adjust_int( libvlc_media_player_t *p_mi,
1303                                                 unsigned option );
1304
1305 /**
1306  * Set adjust option as integer. Options that take a different type value
1307  * are ignored.
1308  * Passing libvlc_adjust_enable as option value has the side effect of
1309  * starting (arg !0) or stopping (arg 0) the adjust filter.
1310  *
1311  * \param p_mi libvlc media player instance
1312  * \param option adust option to set, values of libvlc_video_adjust_option_t
1313  * \param value adjust option value
1314  * \version LibVLC 1.1.1 and later.
1315  */
1316 LIBVLC_API void libvlc_video_set_adjust_int( libvlc_media_player_t *p_mi,
1317                                                  unsigned option, int value );
1318
1319 /**
1320  * Get float adjust option.
1321  *
1322  * \param p_mi libvlc media player instance
1323  * \param option adjust option to get, values of libvlc_video_adjust_option_t
1324  * \version LibVLC 1.1.1 and later.
1325  */
1326 LIBVLC_API float libvlc_video_get_adjust_float( libvlc_media_player_t *p_mi,
1327                                                     unsigned option );
1328
1329 /**
1330  * Set adjust option as float. Options that take a different type value
1331  * are ignored.
1332  *
1333  * \param p_mi libvlc media player instance
1334  * \param option adust option to set, values of libvlc_video_adjust_option_t
1335  * \param value adjust option value
1336  * \version LibVLC 1.1.1 and later.
1337  */
1338 LIBVLC_API void libvlc_video_set_adjust_float( libvlc_media_player_t *p_mi,
1339                                                    unsigned option, float value );
1340
1341 /** @} video */
1342
1343 /** \defgroup libvlc_audio LibVLC audio controls
1344  * @{
1345  */
1346
1347 /**
1348  * Audio device types
1349  */
1350 typedef enum libvlc_audio_output_device_types_t {
1351     libvlc_AudioOutputDevice_Error  = -1,
1352     libvlc_AudioOutputDevice_Mono   =  1,
1353     libvlc_AudioOutputDevice_Stereo =  2,
1354     libvlc_AudioOutputDevice_2F2R   =  4,
1355     libvlc_AudioOutputDevice_3F2R   =  5,
1356     libvlc_AudioOutputDevice_5_1    =  6,
1357     libvlc_AudioOutputDevice_6_1    =  7,
1358     libvlc_AudioOutputDevice_7_1    =  8,
1359     libvlc_AudioOutputDevice_SPDIF  = 10
1360 } libvlc_audio_output_device_types_t;
1361
1362 /**
1363  * Audio channels
1364  */
1365 typedef enum libvlc_audio_output_channel_t {
1366     libvlc_AudioChannel_Error   = -1,
1367     libvlc_AudioChannel_Stereo  =  1,
1368     libvlc_AudioChannel_RStereo =  2,
1369     libvlc_AudioChannel_Left    =  3,
1370     libvlc_AudioChannel_Right   =  4,
1371     libvlc_AudioChannel_Dolbys  =  5
1372 } libvlc_audio_output_channel_t;
1373
1374
1375 /**
1376  * Gets the list of available audio outputs
1377  *
1378  * \param p_instance libvlc instance
1379  * \return list of available audio outputs. It must be freed it with
1380 *          \see libvlc_audio_output_list_release \see libvlc_audio_output_t .
1381  *         In case of error, NULL is returned.
1382  */
1383 LIBVLC_API libvlc_audio_output_t *
1384 libvlc_audio_output_list_get( libvlc_instance_t *p_instance );
1385
1386 /**
1387  * Frees the list of available audio outputs
1388  *
1389  * \param p_list list with audio outputs for release
1390  */
1391 LIBVLC_API
1392 void libvlc_audio_output_list_release( libvlc_audio_output_t *p_list );
1393
1394 /**
1395  * Sets the audio output.
1396  * \note Any change will take be effect only after playback is stopped and
1397  * restarted. Audio output cannot be changed while playing.
1398  *
1399  * \param p_mi media player
1400  * \param psz_name name of audio output,
1401  *               use psz_name of \see libvlc_audio_output_t
1402  * \return 0 if function succeded, -1 on error
1403  */
1404 LIBVLC_API int libvlc_audio_output_set( libvlc_media_player_t *p_mi,
1405                                         const char *psz_name );
1406
1407 /**
1408  * Backward compatibility stub. Do not use in new code.
1409  * Use libvlc_audio_output_device_list_get() instead.
1410  * \return always 0.
1411  */
1412 LIBVLC_DEPRECATED LIBVLC_API
1413 int libvlc_audio_output_device_count( libvlc_instance_t *, const char * );
1414
1415 /**
1416  * Backward compatibility stub. Do not use in new code.
1417  * Use libvlc_audio_output_device_list_get() instead.
1418  * \return always NULL.
1419  */
1420 LIBVLC_DEPRECATED LIBVLC_API
1421 char *libvlc_audio_output_device_longname( libvlc_instance_t *, const char *,
1422                                            int );
1423
1424 /**
1425  * Backward compatibility stub. Do not use in new code.
1426  * Use libvlc_audio_output_device_list_get() instead.
1427  * \return always NULL.
1428  */
1429 LIBVLC_DEPRECATED LIBVLC_API
1430 char *libvlc_audio_output_device_id( libvlc_instance_t *, const char *, int );
1431
1432 /**
1433  * Gets a list of audio output devices for a given audio output.
1434  * \see libvlc_audio_output_device_set().
1435  *
1436  * \note Not all audio outputs support this. In particular, an empty (NULL)
1437  * list of devices does <b>not</b> imply that the specified audio output does
1438  * not work.
1439  *
1440  * \note The list might not be exhaustive.
1441  *
1442  * \warning Some audio output devices in the list might not actually work in
1443  * some circumstances. By default, it is recommended to not specify any
1444  * explicit audio device.
1445  *
1446  * \param p_instance libvlc instance
1447  * \param psz_aout audio output name
1448  *                 (as returned by libvlc_audio_output_list_get())
1449  * \return A NULL-terminated linked list of potential audio output devices.
1450  * It must be freed it with libvlc_audio_output_device_list_release()
1451  * \version LibVLC 2.1.0 or later.
1452  */
1453 LIBVLC_API libvlc_audio_output_device_t *
1454 libvlc_audio_output_device_list_get( libvlc_instance_t *p_instance,
1455                                      const char *aout );
1456
1457 /**
1458  * Frees a list of available audio output devices.
1459  *
1460  * \param p_list list with audio outputs for release
1461  * \version LibVLC 2.1.0 or later.
1462  */
1463 LIBVLC_API void libvlc_audio_output_device_list_release(
1464                                         libvlc_audio_output_device_t *p_list );
1465
1466 /**
1467  * Configures an explicit audio output device for a given audio output plugin.
1468  * A list of possible devices can be obtained with
1469  * libvlc_audio_output_device_list_get().
1470  *
1471  * \note This function does not select the specified audio output plugin.
1472  * libvlc_audio_output_set() is used for that purpose.
1473  *
1474  * \warning The syntax for the device parameter depends on the audio output.
1475  * This is not portable. Only use this function if you know what you are doing.
1476  * Some audio outputs do not support this function (e.g. PulseAudio, WASAPI).
1477  * Some audio outputs require further parameters (e.g. ALSA: channels map).
1478  *
1479  * \param p_mi media player
1480  * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
1481  * \param psz_device_id device
1482  * \return Nothing. Errors are ignored.
1483  */
1484 LIBVLC_API void libvlc_audio_output_device_set( libvlc_media_player_t *p_mi,
1485                                                 const char *psz_audio_output,
1486                                                 const char *psz_device_id );
1487
1488 /**
1489  * Get current audio device type. Device type describes something like
1490  * character of output sound - stereo sound, 2.1, 5.1 etc
1491  *
1492  * \param p_mi media player
1493  * \return the audio devices type \see libvlc_audio_output_device_types_t
1494  */
1495 LIBVLC_API int libvlc_audio_output_get_device_type( libvlc_media_player_t *p_mi );
1496
1497 /**
1498  * Set current audio device type.
1499  *
1500  * \param p_mi vlc instance
1501  * \param device_type the audio device type,
1502           according to \see libvlc_audio_output_device_types_t
1503  */
1504 LIBVLC_API void libvlc_audio_output_set_device_type( libvlc_media_player_t *p_mi,
1505                                                          int device_type );
1506
1507
1508 /**
1509  * Toggle mute status.
1510  *
1511  * \param p_mi media player
1512  * \warning Toggling mute atomically is not always possible: On some platforms,
1513  * other processes can mute the VLC audio playback stream asynchronously. Thus,
1514  * there is a small race condition where toggling will not work.
1515  * See also the limitations of libvlc_audio_set_mute().
1516  */
1517 LIBVLC_API void libvlc_audio_toggle_mute( libvlc_media_player_t *p_mi );
1518
1519 /**
1520  * Get current mute status.
1521  *
1522  * \param p_mi media player
1523  * \return the mute status (boolean) if defined, -1 if undefined/unapplicable
1524  */
1525 LIBVLC_API int libvlc_audio_get_mute( libvlc_media_player_t *p_mi );
1526
1527 /**
1528  * Set mute status.
1529  *
1530  * \param p_mi media player
1531  * \param status If status is true then mute, otherwise unmute
1532  * \warning This function does not always work. If there are no active audio
1533  * playback stream, the mute status might not be available. If digital
1534  * pass-through (S/PDIF, HDMI...) is in use, muting may be unapplicable. Also
1535  * some audio output plugins do not support muting at all.
1536  * \note To force silent playback, disable all audio tracks. This is more
1537  * efficient and reliable than mute.
1538  */
1539 LIBVLC_API void libvlc_audio_set_mute( libvlc_media_player_t *p_mi, int status );
1540
1541 /**
1542  * Get current software audio volume.
1543  *
1544  * \param p_mi media player
1545  * \return the software volume in percents
1546  * (0 = mute, 100 = nominal / 0dB)
1547  */
1548 LIBVLC_API int libvlc_audio_get_volume( libvlc_media_player_t *p_mi );
1549
1550 /**
1551  * Set current software audio volume.
1552  *
1553  * \param p_mi media player
1554  * \param i_volume the volume in percents (0 = mute, 100 = 0dB)
1555  * \return 0 if the volume was set, -1 if it was out of range
1556  */
1557 LIBVLC_API int libvlc_audio_set_volume( libvlc_media_player_t *p_mi, int i_volume );
1558
1559 /**
1560  * Get number of available audio tracks.
1561  *
1562  * \param p_mi media player
1563  * \return the number of available audio tracks (int), or -1 if unavailable
1564  */
1565 LIBVLC_API int libvlc_audio_get_track_count( libvlc_media_player_t *p_mi );
1566
1567 /**
1568  * Get the description of available audio tracks.
1569  *
1570  * \param p_mi media player
1571  * \return list with description of available audio tracks, or NULL
1572  */
1573 LIBVLC_API libvlc_track_description_t *
1574         libvlc_audio_get_track_description( libvlc_media_player_t *p_mi );
1575
1576 /**
1577  * Get current audio track.
1578  *
1579  * \param p_mi media player
1580  * \return the audio track ID or -1 if no active input.
1581  */
1582 LIBVLC_API int libvlc_audio_get_track( libvlc_media_player_t *p_mi );
1583
1584 /**
1585  * Set current audio track.
1586  *
1587  * \param p_mi media player
1588  * \param i_track the track ID (i_id field from track description)
1589  * \return 0 on success, -1 on error
1590  */
1591 LIBVLC_API int libvlc_audio_set_track( libvlc_media_player_t *p_mi, int i_track );
1592
1593 /**
1594  * Get current audio channel.
1595  *
1596  * \param p_mi media player
1597  * \return the audio channel \see libvlc_audio_output_channel_t
1598  */
1599 LIBVLC_API int libvlc_audio_get_channel( libvlc_media_player_t *p_mi );
1600
1601 /**
1602  * Set current audio channel.
1603  *
1604  * \param p_mi media player
1605  * \param channel the audio channel, \see libvlc_audio_output_channel_t
1606  * \return 0 on success, -1 on error
1607  */
1608 LIBVLC_API int libvlc_audio_set_channel( libvlc_media_player_t *p_mi, int channel );
1609
1610 /**
1611  * Get current audio delay.
1612  *
1613  * \param p_mi media player
1614  * \return the audio delay (microseconds)
1615  * \version LibVLC 1.1.1 or later
1616  */
1617 LIBVLC_API int64_t libvlc_audio_get_delay( libvlc_media_player_t *p_mi );
1618
1619 /**
1620  * Set current audio delay. The audio delay will be reset to zero each time the media changes.
1621  *
1622  * \param p_mi media player
1623  * \param i_delay the audio delay (microseconds)
1624  * \return 0 on success, -1 on error
1625  * \version LibVLC 1.1.1 or later
1626  */
1627 LIBVLC_API int libvlc_audio_set_delay( libvlc_media_player_t *p_mi, int64_t i_delay );
1628
1629 /** @} audio */
1630
1631 /** @} media_player */
1632
1633 # ifdef __cplusplus
1634 }
1635 # endif
1636
1637 #endif /* VLC_LIBVLC_MEDIA_PLAYER_H */