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 as percentage between 0.0 and 1.0.
 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 as percentage between 0.0 and 1.0.
 652  * This has no effect if playback is not enabled.
 653  * This might not work depending on the underlying input format and protocol.
 654  *
 655  * \param p_mi the Media Player
 656  * \param f_pos the position
 657  */
 658 LIBVLC_API void libvlc_media_player_set_position( libvlc_media_player_t *p_mi, float f_pos );
 659
 660 /**
 661  * Set movie chapter (if applicable).
 662  *
 663  * \param p_mi the Media Player
 664  * \param i_chapter chapter number to play
 665  */
 666 LIBVLC_API void libvlc_media_player_set_chapter( libvlc_media_player_t *p_mi, int i_chapter );
 667
 668 /**
 669  * Get movie chapter.
 670  *
 671  * \param p_mi the Media Player
 672  * \return chapter number currently playing, or -1 if there is no media.
 673  */
 674 LIBVLC_API int libvlc_media_player_get_chapter( libvlc_media_player_t *p_mi );
 675
 676 /**
 677  * Get movie chapter count
 678  *
 679  * \param p_mi the Media Player
 680  * \return number of chapters in movie, or -1.
 681  */
 682 LIBVLC_API int libvlc_media_player_get_chapter_count( libvlc_media_player_t *p_mi );
 683
 684 /**
 685  * Is the player able to play
 686  *
 687  * \param p_mi the Media Player
 688  * \return boolean
 689  *
 690  * \libvlc_return_bool
 691  */
 692 LIBVLC_API int libvlc_media_player_will_play( libvlc_media_player_t *p_mi );
 693
 694 /**
 695  * Get title chapter count
 696  *
 697  * \param p_mi the Media Player
 698  * \param i_title title
 699  * \return number of chapters in title, or -1
 700  */
 701 LIBVLC_API int libvlc_media_player_get_chapter_count_for_title(
 702                        libvlc_media_player_t *p_mi, int i_title );
 703
 704 /**
 705  * Set movie title
 706  *
 707  * \param p_mi the Media Player
 708  * \param i_title title number to play
 709  */
 710 LIBVLC_API void libvlc_media_player_set_title( libvlc_media_player_t *p_mi, int i_title );
 711
 712 /**
 713  * Get movie title
 714  *
 715  * \param p_mi the Media Player
 716  * \return title number currently playing, or -1
 717  */
 718 LIBVLC_API int libvlc_media_player_get_title( libvlc_media_player_t *p_mi );
 719
 720 /**
 721  * Get movie title count
 722  *
 723  * \param p_mi the Media Player
 724  * \return title number count, or -1
 725  */
 726 LIBVLC_API int libvlc_media_player_get_title_count( libvlc_media_player_t *p_mi );
 727
 728 /**
 729  * Set previous chapter (if applicable)
 730  *
 731  * \param p_mi the Media Player
 732  */
 733 LIBVLC_API void libvlc_media_player_previous_chapter( libvlc_media_player_t *p_mi );
 734
 735 /**
 736  * Set next chapter (if applicable)
 737  *
 738  * \param p_mi the Media Player
 739  */
 740 LIBVLC_API void libvlc_media_player_next_chapter( libvlc_media_player_t *p_mi );
 741
 742 /**
 743  * Get the requested movie play rate.
 744  * @warning Depending on the underlying media, the requested rate may be
 745  * different from the real playback rate.
 746  *
 747  * \param p_mi the Media Player
 748  * \return movie play rate
 749  */
 750 LIBVLC_API float libvlc_media_player_get_rate( libvlc_media_player_t *p_mi );
 751
 752 /**
 753  * Set movie play rate
 754  *
 755  * \param p_mi the Media Player
 756  * \param rate movie play rate to set
 757  * \return -1 if an error was detected, 0 otherwise (but even then, it might
 758  * not actually work depending on the underlying media protocol)
 759  */
 760 LIBVLC_API int libvlc_media_player_set_rate( libvlc_media_player_t *p_mi, float rate );
 761
 762 /**
 763  * Get current movie state
 764  *
 765  * \param p_mi the Media Player
 766  * \return the current state of the media player (playing, paused, ...) \see libvlc_state_t
 767  */
 768 LIBVLC_API libvlc_state_t libvlc_media_player_get_state( libvlc_media_player_t *p_mi );
 769
 770 /**
 771  * Get movie fps rate
 772  *
 773  * \param p_mi the Media Player
 774  * \return frames per second (fps) for this playing movie, or 0 if unspecified
 775  */
 776 LIBVLC_API float libvlc_media_player_get_fps( libvlc_media_player_t *p_mi );
 777
 778 /** end bug */
 779
 780 /**
 781  * How many video outputs does this media player have?
 782  *
 783  * \param p_mi the media player
 784  * \return the number of video outputs
 785  */
 786 LIBVLC_API unsigned libvlc_media_player_has_vout( libvlc_media_player_t *p_mi );
 787
 788 /**
 789  * Is this media player seekable?
 790  *
 791  * \param p_mi the media player
 792  * \return true if the media player can seek
 793  *
 794  * \libvlc_return_bool
 795  */
 796 LIBVLC_API int libvlc_media_player_is_seekable( libvlc_media_player_t *p_mi );
 797
 798 /**
 799  * Can this media player be paused?
 800  *
 801  * \param p_mi the media player
 802  * \return true if the media player can pause
 803  *
 804  * \libvlc_return_bool
 805  */
 806 LIBVLC_API int libvlc_media_player_can_pause( libvlc_media_player_t *p_mi );
 807
 808
 809 /**
 810  * Display the next frame (if supported)
 811  *
 812  * \param p_mi the media player
 813  */
 814 LIBVLC_API void libvlc_media_player_next_frame( libvlc_media_player_t *p_mi );
 815
 816 /**
 817  * Navigate through DVD Menu
 818  *
 819  * \param p_mi the Media Player
 820  * \param navigate the Navigation mode
 821  * \version libVLC 2.0.0 or later
 822  */
 823 LIBVLC_API void libvlc_media_player_navigate( libvlc_media_player_t* p_mi,
 824                                               unsigned navigate );
 825
 826 /**
 827  * Release (free) libvlc_track_description_t
 828  *
 829  * \param p_track_description the structure to release
 830  */
 831 LIBVLC_API void libvlc_track_description_list_release( libvlc_track_description_t *p_track_description );
 832
 833 /**
 834  * \deprecated Use libvlc_track_description_list_release instead
 835  */
 836 LIBVLC_DEPRECATED LIBVLC_API
 837 void libvlc_track_description_release( libvlc_track_description_t *p_track_description );
 838
 839 /** \defgroup libvlc_video LibVLC video controls
 840  * @{
 841  */
 842
 843 /**
 844  * Toggle fullscreen status on non-embedded video outputs.
 845  *
 846  * @warning The same limitations applies to this function
 847  * as to libvlc_set_fullscreen().
 848  *
 849  * \param p_mi the media player
 850  */
 851 LIBVLC_API void libvlc_toggle_fullscreen( libvlc_media_player_t *p_mi );
 852
 853 /**
 854  * Enable or disable fullscreen.
 855  *
 856  * @warning With most window managers, only a top-level windows can be in
 857  * full-screen mode. Hence, this function will not operate properly if
 858  * libvlc_media_player_set_xwindow() was used to embed the video in a
 859  * non-top-level window. In that case, the embedding window must be reparented
 860  * to the root window <b>before</b> fullscreen mode is enabled. You will want
 861  * to reparent it back to its normal parent when disabling fullscreen.
 862  *
 863  * \param p_mi the media player
 864  * \param b_fullscreen boolean for fullscreen status
 865  */
 866 LIBVLC_API void libvlc_set_fullscreen( libvlc_media_player_t *p_mi, int b_fullscreen );
 867
 868 /**
 869  * Get current fullscreen status.
 870  *
 871  * \param p_mi the media player
 872  * \return the fullscreen status (boolean)
 873  *
 874  * \libvlc_return_bool
 875  */
 876 LIBVLC_API int libvlc_get_fullscreen( libvlc_media_player_t *p_mi );
 877
 878 /**
 879  * Enable or disable key press events handling, according to the LibVLC hotkeys
 880  * configuration. By default and for historical reasons, keyboard events are
 881  * handled by the LibVLC video widget.
 882  *
 883  * \note On X11, there can be only one subscriber for key press and mouse
 884  * click events per window. If your application has subscribed to those events
 885  * for the X window ID of the video widget, then LibVLC will not be able to
 886  * handle key presses and mouse clicks in any case.
 887  *
 888  * \warning This function is only implemented for X11 and Win32 at the moment.
 889  *
 890  * \param p_mi the media player
 891  * \param on true to handle key press events, false to ignore them.
 892  */
 893 LIBVLC_API
 894 void libvlc_video_set_key_input( libvlc_media_player_t *p_mi, unsigned on );
 895
 896 /**
 897  * Enable or disable mouse click events handling. By default, those events are
 898  * handled. This is needed for DVD menus to work, as well as a few video
 899  * filters such as "puzzle".
 900  *
 901  * \see libvlc_video_set_key_input().
 902  *
 903  * \warning This function is only implemented for X11 and Win32 at the moment.
 904  *
 905  * \param p_mi the media player
 906  * \param on true to handle mouse click events, false to ignore them.
 907  */
 908 LIBVLC_API
 909 void libvlc_video_set_mouse_input( libvlc_media_player_t *p_mi, unsigned on );
 910
 911 /**
 912  * Get the pixel dimensions of a video.
 913  *
 914  * \param p_mi media player
 915  * \param num number of the video (starting from, and most commonly 0)
 916  * \param px pointer to get the pixel width [OUT]
 917  * \param py pointer to get the pixel height [OUT]
 918  * \return 0 on success, -1 if the specified video does not exist
 919  */
 920 LIBVLC_API
 921 int libvlc_video_get_size( libvlc_media_player_t *p_mi, unsigned num,
 922                            unsigned *px, unsigned *py );
 923
 924 /**
 925  * Get current video height.
 926  * \deprecated Use libvlc_video_get_size() instead.
 927  *
 928  * \param p_mi the media player
 929  * \return the video pixel height or 0 if not applicable
 930  */
 931 LIBVLC_DEPRECATED LIBVLC_API
 932 int libvlc_video_get_height( libvlc_media_player_t *p_mi );
 933
 934 /**
 935  * Get current video width.
 936  * \deprecated Use libvlc_video_get_size() instead.
 937  *
 938  * \param p_mi the media player
 939  * \return the video pixel width or 0 if not applicable
 940  */
 941 LIBVLC_DEPRECATED LIBVLC_API
 942 int libvlc_video_get_width( libvlc_media_player_t *p_mi );
 943
 944 /**
 945  * Get the mouse pointer coordinates over a video.
 946  * Coordinates are expressed in terms of the decoded video resolution,
 947  * <b>not</b> in terms of pixels on the screen/viewport (to get the latter,
 948  * you can query your windowing system directly).
 949  *
 950  * Either of the coordinates may be negative or larger than the corresponding
 951  * dimension of the video, if the cursor is outside the rendering area.
 952  *
 953  * @warning The coordinates may be out-of-date if the pointer is not located
 954  * on the video rendering area. LibVLC does not track the pointer if it is
 955  * outside of the video widget.
 956  *
 957  * @note LibVLC does not support multiple pointers (it does of course support
 958  * multiple input devices sharing the same pointer) at the moment.
 959  *
 960  * \param p_mi media player
 961  * \param num number of the video (starting from, and most commonly 0)
 962  * \param px pointer to get the abscissa [OUT]
 963  * \param py pointer to get the ordinate [OUT]
 964  * \return 0 on success, -1 if the specified video does not exist
 965  */
 966 LIBVLC_API
 967 int libvlc_video_get_cursor( libvlc_media_player_t *p_mi, unsigned num,
 968                              int *px, int *py );
 969
 970 /**
 971  * Get the current video scaling factor.
 972  * See also libvlc_video_set_scale().
 973  *
 974  * \param p_mi the media player
 975  * \return the currently configured zoom factor, or 0. if the video is set
 976  * to fit to the output window/drawable automatically.
 977  */
 978 LIBVLC_API float libvlc_video_get_scale( libvlc_media_player_t *p_mi );
 979
 980 /**
 981  * Set the video scaling factor. That is the ratio of the number of pixels on
 982  * screen to the number of pixels in the original decoded video in each
 983  * dimension. Zero is a special value; it will adjust the video to the output
 984  * window/drawable (in windowed mode) or the entire screen.
 985  *
 986  * Note that not all video outputs support scaling.
 987  *
 988  * \param p_mi the media player
 989  * \param f_factor the scaling factor, or zero
 990  */
 991 LIBVLC_API void libvlc_video_set_scale( libvlc_media_player_t *p_mi, float f_factor );
 992
 993 /**
 994  * Get current video aspect ratio.
 995  *
 996  * \param p_mi the media player
 997  * \return the video aspect ratio or NULL if unspecified
 998  * (the result must be released with free() or libvlc_free()).
 999  */
1000 LIBVLC_API char *libvlc_video_get_aspect_ratio( libvlc_media_player_t *p_mi );
1001
1002 /**
1003  * Set new video aspect ratio.
1004  *
1005  * \param p_mi the media player
1006  * \param psz_aspect new video aspect-ratio or NULL to reset to default
1007  * \note Invalid aspect ratios are ignored.
1008  */
1009 LIBVLC_API void libvlc_video_set_aspect_ratio( libvlc_media_player_t *p_mi, const char *psz_aspect );
1010
1011 /**
1012  * Get current video subtitle.
1013  *
1014  * \param p_mi the media player
1015  * \return the video subtitle selected, or -1 if none
1016  */
1017 LIBVLC_API int libvlc_video_get_spu( libvlc_media_player_t *p_mi );
1018
1019 /**
1020  * Get the number of available video subtitles.
1021  *
1022  * \param p_mi the media player
1023  * \return the number of available video subtitles
1024  */
1025 LIBVLC_API int libvlc_video_get_spu_count( libvlc_media_player_t *p_mi );
1026
1027 /**
1028  * Get the description of available video subtitles.
1029  *
1030  * \param p_mi the media player
1031  * \return list containing description of available video subtitles
1032  */
1033 LIBVLC_API libvlc_track_description_t *
1034         libvlc_video_get_spu_description( libvlc_media_player_t *p_mi );
1035
1036 /**
1037  * Set new video subtitle.
1038  *
1039  * \param p_mi the media player
1040  * \param i_spu new video subtitle to select
1041  * \return 0 on success, -1 if out of range
1042  */
1043 LIBVLC_API int libvlc_video_set_spu( libvlc_media_player_t *p_mi, unsigned i_spu );
1044
1045 /**
1046  * Set new video subtitle file.
1047  *
1048  * \param p_mi the media player
1049  * \param psz_subtitle new video subtitle file
1050  * \return the success status (boolean)
1051  */
1052 LIBVLC_API int libvlc_video_set_subtitle_file( libvlc_media_player_t *p_mi, const char *psz_subtitle );
1053
1054 /**
1055  * Get the current subtitle delay. Positive values means subtitles are being
1056  * displayed later, negative values earlier.
1057  *
1058  * \param p_mi media player
1059  * \return time (in microseconds) the display of subtitles is being delayed
1060  * \version LibVLC 2.0.0 or later
1061  */
1062 LIBVLC_API int64_t libvlc_video_get_spu_delay( libvlc_media_player_t *p_mi );
1063
1064 /**
1065  * Set the subtitle delay. This affects the timing of when the subtitle will
1066  * be displayed. Positive values result in subtitles being displayed later,
1067  * while negative values will result in subtitles being displayed earlier.
1068  *
1069  * The subtitle delay will be reset to zero each time the media changes.
1070  *
1071  * \param p_mi media player
1072  * \param i_delay time (in microseconds) the display of subtitles should be delayed
1073  * \return 0 on success, -1 on error
1074  * \version LibVLC 2.0.0 or later
1075  */
1076 LIBVLC_API int libvlc_video_set_spu_delay( libvlc_media_player_t *p_mi, int64_t i_delay );
1077
1078 /**
1079  * Get the description of available titles.
1080  *
1081  * \param p_mi the media player
1082  * \return list containing description of available titles
1083  */
1084 LIBVLC_API libvlc_track_description_t *
1085         libvlc_video_get_title_description( libvlc_media_player_t *p_mi );
1086
1087 /**
1088  * Get the description of available chapters for specific title.
1089  *
1090  * \param p_mi the media player
1091  * \param i_title selected title
1092  * \return list containing description of available chapter for title i_title
1093  */
1094 LIBVLC_API libvlc_track_description_t *
1095         libvlc_video_get_chapter_description( libvlc_media_player_t *p_mi, int i_title );
1096
1097 /**
1098  * Get current crop filter geometry.
1099  *
1100  * \param p_mi the media player
1101  * \return the crop filter geometry or NULL if unset
1102  */
1103 LIBVLC_API char *libvlc_video_get_crop_geometry( libvlc_media_player_t *p_mi );
1104
1105 /**
1106  * Set new crop filter geometry.
1107  *
1108  * \param p_mi the media player
1109  * \param psz_geometry new crop filter geometry (NULL to unset)
1110  */
1111 LIBVLC_API
1112 void libvlc_video_set_crop_geometry( libvlc_media_player_t *p_mi, const char *psz_geometry );
1113
1114 /**
1115  * Get current teletext page requested.
1116  *
1117  * \param p_mi the media player
1118  * \return the current teletext page requested.
1119  */
1120 LIBVLC_API int libvlc_video_get_teletext( libvlc_media_player_t *p_mi );
1121
1122 /**
1123  * Set new teletext page to retrieve.
1124  *
1125  * \param p_mi the media player
1126  * \param i_page teletex page number requested
1127  */
1128 LIBVLC_API void libvlc_video_set_teletext( libvlc_media_player_t *p_mi, int i_page );
1129
1130 /**
1131  * Toggle teletext transparent status on video output.
1132  *
1133  * \param p_mi the media player
1134  */
1135 LIBVLC_API void libvlc_toggle_teletext( libvlc_media_player_t *p_mi );
1136
1137 /**
1138  * Get number of available video tracks.
1139  *
1140  * \param p_mi media player
1141  * \return the number of available video tracks (int)
1142  */
1143 LIBVLC_API int libvlc_video_get_track_count( libvlc_media_player_t *p_mi );
1144
1145 /**
1146  * Get the description of available video tracks.
1147  *
1148  * \param p_mi media player
1149  * \return list with description of available video tracks, or NULL on error
1150  */
1151 LIBVLC_API libvlc_track_description_t *
1152         libvlc_video_get_track_description( libvlc_media_player_t *p_mi );
1153
1154 /**
1155  * Get current video track.
1156  *
1157  * \param p_mi media player
1158  * \return the video track ID (int) or -1 if no active input
1159  */
1160 LIBVLC_API int libvlc_video_get_track( libvlc_media_player_t *p_mi );
1161
1162 /**
1163  * Set video track.
1164  *
1165  * \param p_mi media player
1166  * \param i_track the track ID (i_id field from track description)
1167  * \return 0 on success, -1 if out of range
1168  */
1169 LIBVLC_API
1170 int libvlc_video_set_track( libvlc_media_player_t *p_mi, int i_track );
1171
1172 /**
1173  * Take a snapshot of the current video window.
1174  *
1175  * If i_width AND i_height is 0, original size is used.
1176  * If i_width XOR i_height is 0, original aspect-ratio is preserved.
1177  *
1178  * \param p_mi media player instance
1179  * \param num number of video output (typically 0 for the first/only one)
1180  * \param psz_filepath the path where to save the screenshot to
1181  * \param i_width the snapshot's width
1182  * \param i_height the snapshot's height
1183  * \return 0 on success, -1 if the video was not found
1184  */
1185 LIBVLC_API
1186 int libvlc_video_take_snapshot( libvlc_media_player_t *p_mi, unsigned num,
1187                                 const char *psz_filepath, unsigned int i_width,
1188                                 unsigned int i_height );
1189
1190 /**
1191  * Enable or disable deinterlace filter
1192  *
1193  * \param p_mi libvlc media player
1194  * \param psz_mode type of deinterlace filter, NULL to disable
1195  */
1196 LIBVLC_API void libvlc_video_set_deinterlace( libvlc_media_player_t *p_mi,
1197                                                   const char *psz_mode );
1198
1199 /**
1200  * Get an integer marquee option value
1201  *
1202  * \param p_mi libvlc media player
1203  * \param option marq option to get \see libvlc_video_marquee_int_option_t
1204  */
1205 LIBVLC_API int libvlc_video_get_marquee_int( libvlc_media_player_t *p_mi,
1206                                                  unsigned option );
1207
1208 /**
1209  * Get a string marquee option value
1210  *
1211  * \param p_mi libvlc media player
1212  * \param option marq option to get \see libvlc_video_marquee_string_option_t
1213  */
1214 LIBVLC_API char *libvlc_video_get_marquee_string( libvlc_media_player_t *p_mi,
1215                                                       unsigned option );
1216
1217 /**
1218  * Enable, disable or set an integer marquee option
1219  *
1220  * Setting libvlc_marquee_Enable has the side effect of enabling (arg !0)
1221  * or disabling (arg 0) the marq filter.
1222  *
1223  * \param p_mi libvlc media player
1224  * \param option marq option to set \see libvlc_video_marquee_int_option_t
1225  * \param i_val marq option value
1226  */
1227 LIBVLC_API void libvlc_video_set_marquee_int( libvlc_media_player_t *p_mi,
1228                                                   unsigned option, int i_val );
1229
1230 /**
1231  * Set a marquee string option
1232  *
1233  * \param p_mi libvlc media player
1234  * \param option marq option to set \see libvlc_video_marquee_string_option_t
1235  * \param psz_text marq option value
1236  */
1237 LIBVLC_API void libvlc_video_set_marquee_string( libvlc_media_player_t *p_mi,
1238                                                      unsigned option, const char *psz_text );
1239
1240 /** option values for libvlc_video_{get,set}_logo_{int,string} */
1241 enum libvlc_video_logo_option_t {
1242     libvlc_logo_enable,
1243     libvlc_logo_file,           /**< string argument, "file,d,t;file,d,t;..." */
1244     libvlc_logo_x,
1245     libvlc_logo_y,
1246     libvlc_logo_delay,
1247     libvlc_logo_repeat,
1248     libvlc_logo_opacity,
1249     libvlc_logo_position
1250 };
1251
1252 /**
1253  * Get integer logo option.
1254  *
1255  * \param p_mi libvlc media player instance
1256  * \param option logo option to get, values of libvlc_video_logo_option_t
1257  */
1258 LIBVLC_API int libvlc_video_get_logo_int( libvlc_media_player_t *p_mi,
1259                                               unsigned option );
1260
1261 /**
1262  * Set logo option as integer. Options that take a different type value
1263  * are ignored.
1264  * Passing libvlc_logo_enable as option value has the side effect of
1265  * starting (arg !0) or stopping (arg 0) the logo filter.
1266  *
1267  * \param p_mi libvlc media player instance
1268  * \param option logo option to set, values of libvlc_video_logo_option_t
1269  * \param value logo option value
1270  */
1271 LIBVLC_API void libvlc_video_set_logo_int( libvlc_media_player_t *p_mi,
1272                                                unsigned option, int value );
1273
1274 /**
1275  * Set logo option as string. Options that take a different type value
1276  * are ignored.
1277  *
1278  * \param p_mi libvlc media player instance
1279  * \param option logo option to set, values of libvlc_video_logo_option_t
1280  * \param psz_value logo option value
1281  */
1282 LIBVLC_API void libvlc_video_set_logo_string( libvlc_media_player_t *p_mi,
1283                                       unsigned option, const char *psz_value );
1284
1285
1286 /** option values for libvlc_video_{get,set}_adjust_{int,float,bool} */
1287 enum libvlc_video_adjust_option_t {
1288     libvlc_adjust_Enable = 0,
1289     libvlc_adjust_Contrast,
1290     libvlc_adjust_Brightness,
1291     libvlc_adjust_Hue,
1292     libvlc_adjust_Saturation,
1293     libvlc_adjust_Gamma
1294 };
1295
1296 /**
1297  * Get integer adjust option.
1298  *
1299  * \param p_mi libvlc media player instance
1300  * \param option adjust option to get, values of libvlc_video_adjust_option_t
1301  * \version LibVLC 1.1.1 and later.
1302  */
1303 LIBVLC_API int libvlc_video_get_adjust_int( libvlc_media_player_t *p_mi,
1304                                                 unsigned option );
1305
1306 /**
1307  * Set adjust option as integer. Options that take a different type value
1308  * are ignored.
1309  * Passing libvlc_adjust_enable as option value has the side effect of
1310  * starting (arg !0) or stopping (arg 0) the adjust filter.
1311  *
1312  * \param p_mi libvlc media player instance
1313  * \param option adust option to set, values of libvlc_video_adjust_option_t
1314  * \param value adjust option value
1315  * \version LibVLC 1.1.1 and later.
1316  */
1317 LIBVLC_API void libvlc_video_set_adjust_int( libvlc_media_player_t *p_mi,
1318                                                  unsigned option, int value );
1319
1320 /**
1321  * Get float adjust option.
1322  *
1323  * \param p_mi libvlc media player instance
1324  * \param option adjust option to get, values of libvlc_video_adjust_option_t
1325  * \version LibVLC 1.1.1 and later.
1326  */
1327 LIBVLC_API float libvlc_video_get_adjust_float( libvlc_media_player_t *p_mi,
1328                                                     unsigned option );
1329
1330 /**
1331  * Set adjust option as float. Options that take a different type value
1332  * are ignored.
1333  *
1334  * \param p_mi libvlc media player instance
1335  * \param option adust option to set, values of libvlc_video_adjust_option_t
1336  * \param value adjust option value
1337  * \version LibVLC 1.1.1 and later.
1338  */
1339 LIBVLC_API void libvlc_video_set_adjust_float( libvlc_media_player_t *p_mi,
1340                                                    unsigned option, float value );
1341
1342 /** @} video */
1343
1344 /** \defgroup libvlc_audio LibVLC audio controls
1345  * @{
1346  */
1347
1348 /**
1349  * Audio device types
1350  */
1351 typedef enum libvlc_audio_output_device_types_t {
1352     libvlc_AudioOutputDevice_Error  = -1,
1353     libvlc_AudioOutputDevice_Mono   =  1,
1354     libvlc_AudioOutputDevice_Stereo =  2,
1355     libvlc_AudioOutputDevice_2F2R   =  4,
1356     libvlc_AudioOutputDevice_3F2R   =  5,
1357     libvlc_AudioOutputDevice_5_1    =  6,
1358     libvlc_AudioOutputDevice_6_1    =  7,
1359     libvlc_AudioOutputDevice_7_1    =  8,
1360     libvlc_AudioOutputDevice_SPDIF  = 10
1361 } libvlc_audio_output_device_types_t;
1362
1363 /**
1364  * Audio channels
1365  */
1366 typedef enum libvlc_audio_output_channel_t {
1367     libvlc_AudioChannel_Error   = -1,
1368     libvlc_AudioChannel_Stereo  =  1,
1369     libvlc_AudioChannel_RStereo =  2,
1370     libvlc_AudioChannel_Left    =  3,
1371     libvlc_AudioChannel_Right   =  4,
1372     libvlc_AudioChannel_Dolbys  =  5
1373 } libvlc_audio_output_channel_t;
1374
1375
1376 /**
1377  * Gets the list of available audio outputs
1378  *
1379  * \param p_instance libvlc instance
1380  * \return list of available audio outputs. It must be freed it with
1381 *          \see libvlc_audio_output_list_release \see libvlc_audio_output_t .
1382  *         In case of error, NULL is returned.
1383  */
1384 LIBVLC_API libvlc_audio_output_t *
1385 libvlc_audio_output_list_get( libvlc_instance_t *p_instance );
1386
1387 /**
1388  * Frees the list of available audio outputs
1389  *
1390  * \param p_list list with audio outputs for release
1391  */
1392 LIBVLC_API
1393 void libvlc_audio_output_list_release( libvlc_audio_output_t *p_list );
1394
1395 /**
1396  * Sets the audio output.
1397  * \note Any change will take be effect only after playback is stopped and
1398  * restarted. Audio output cannot be changed while playing.
1399  *
1400  * \param p_mi media player
1401  * \param psz_name name of audio output,
1402  *               use psz_name of \see libvlc_audio_output_t
1403  * \return 0 if function succeded, -1 on error
1404  */
1405 LIBVLC_API int libvlc_audio_output_set( libvlc_media_player_t *p_mi,
1406                                         const char *psz_name );
1407
1408 /**
1409  * Backward compatibility stub. Do not use in new code.
1410  * Use libvlc_audio_output_device_list_get() instead.
1411  * \return always 0.
1412  */
1413 LIBVLC_DEPRECATED LIBVLC_API
1414 int libvlc_audio_output_device_count( libvlc_instance_t *, const char * );
1415
1416 /**
1417  * Backward compatibility stub. Do not use in new code.
1418  * Use libvlc_audio_output_device_list_get() instead.
1419  * \return always NULL.
1420  */
1421 LIBVLC_DEPRECATED LIBVLC_API
1422 char *libvlc_audio_output_device_longname( libvlc_instance_t *, const char *,
1423                                            int );
1424
1425 /**
1426  * Backward compatibility stub. Do not use in new code.
1427  * Use libvlc_audio_output_device_list_get() instead.
1428  * \return always NULL.
1429  */
1430 LIBVLC_DEPRECATED LIBVLC_API
1431 char *libvlc_audio_output_device_id( libvlc_instance_t *, const char *, int );
1432
1433 /**
1434  * Gets a list of audio output devices for a given audio output.
1435  * \see libvlc_audio_output_device_set().
1436  *
1437  * \note Not all audio outputs support this. In particular, an empty (NULL)
1438  * list of devices does <b>not</b> imply that the specified audio output does
1439  * not work.
1440  *
1441  * \note The list might not be exhaustive.
1442  *
1443  * \warning Some audio output devices in the list might not actually work in
1444  * some circumstances. By default, it is recommended to not specify any
1445  * explicit audio device.
1446  *
1447  * \param p_instance libvlc instance
1448  * \param psz_aout audio output name
1449  *                 (as returned by libvlc_audio_output_list_get())
1450  * \return A NULL-terminated linked list of potential audio output devices.
1451  * It must be freed it with libvlc_audio_output_device_list_release()
1452  * \version LibVLC 2.1.0 or later.
1453  */
1454 LIBVLC_API libvlc_audio_output_device_t *
1455 libvlc_audio_output_device_list_get( libvlc_instance_t *p_instance,
1456                                      const char *aout );
1457
1458 /**
1459  * Frees a list of available audio output devices.
1460  *
1461  * \param p_list list with audio outputs for release
1462  * \version LibVLC 2.1.0 or later.
1463  */
1464 LIBVLC_API void libvlc_audio_output_device_list_release(
1465                                         libvlc_audio_output_device_t *p_list );
1466
1467 /**
1468  * Configures an explicit audio output device for a given audio output plugin.
1469  * A list of possible devices can be obtained with
1470  * libvlc_audio_output_device_list_get().
1471  *
1472  * \note This function does not select the specified audio output plugin.
1473  * libvlc_audio_output_set() is used for that purpose.
1474  *
1475  * \warning The syntax for the device parameter depends on the audio output.
1476  * This is not portable. Only use this function if you know what you are doing.
1477  * Some audio outputs do not support this function (e.g. PulseAudio, WASAPI).
1478  * Some audio outputs require further parameters (e.g. ALSA: channels map).
1479  *
1480  * \param p_mi media player
1481  * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
1482  * \param psz_device_id device
1483  * \return Nothing. Errors are ignored.
1484  */
1485 LIBVLC_API void libvlc_audio_output_device_set( libvlc_media_player_t *p_mi,
1486                                                 const char *psz_audio_output,
1487                                                 const char *psz_device_id );
1488
1489 /**
1490  * Get current audio device type. Device type describes something like
1491  * character of output sound - stereo sound, 2.1, 5.1 etc
1492  *
1493  * \param p_mi media player
1494  * \return the audio devices type \see libvlc_audio_output_device_types_t
1495  */
1496 LIBVLC_API int libvlc_audio_output_get_device_type( libvlc_media_player_t *p_mi );
1497
1498 /**
1499  * Set current audio device type.
1500  *
1501  * \param p_mi vlc instance
1502  * \param device_type the audio device type,
1503           according to \see libvlc_audio_output_device_types_t
1504  */
1505 LIBVLC_API void libvlc_audio_output_set_device_type( libvlc_media_player_t *p_mi,
1506                                                          int device_type );
1507
1508
1509 /**
1510  * Toggle mute status.
1511  *
1512  * \param p_mi media player
1513  * \warning Toggling mute atomically is not always possible: On some platforms,
1514  * other processes can mute the VLC audio playback stream asynchronously. Thus,
1515  * there is a small race condition where toggling will not work.
1516  * See also the limitations of libvlc_audio_set_mute().
1517  */
1518 LIBVLC_API void libvlc_audio_toggle_mute( libvlc_media_player_t *p_mi );
1519
1520 /**
1521  * Get current mute status.
1522  *
1523  * \param p_mi media player
1524  * \return the mute status (boolean) if defined, -1 if undefined/unapplicable
1525  */
1526 LIBVLC_API int libvlc_audio_get_mute( libvlc_media_player_t *p_mi );
1527
1528 /**
1529  * Set mute status.
1530  *
1531  * \param p_mi media player
1532  * \param status If status is true then mute, otherwise unmute
1533  * \warning This function does not always work. If there are no active audio
1534  * playback stream, the mute status might not be available. If digital
1535  * pass-through (S/PDIF, HDMI...) is in use, muting may be unapplicable. Also
1536  * some audio output plugins do not support muting at all.
1537  * \note To force silent playback, disable all audio tracks. This is more
1538  * efficient and reliable than mute.
1539  */
1540 LIBVLC_API void libvlc_audio_set_mute( libvlc_media_player_t *p_mi, int status );
1541
1542 /**
1543  * Get current software audio volume.
1544  *
1545  * \param p_mi media player
1546  * \return the software volume in percents
1547  * (0 = mute, 100 = nominal / 0dB)
1548  */
1549 LIBVLC_API int libvlc_audio_get_volume( libvlc_media_player_t *p_mi );
1550
1551 /**
1552  * Set current software audio volume.
1553  *
1554  * \param p_mi media player
1555  * \param i_volume the volume in percents (0 = mute, 100 = 0dB)
1556  * \return 0 if the volume was set, -1 if it was out of range
1557  */
1558 LIBVLC_API int libvlc_audio_set_volume( libvlc_media_player_t *p_mi, int i_volume );
1559
1560 /**
1561  * Get number of available audio tracks.
1562  *
1563  * \param p_mi media player
1564  * \return the number of available audio tracks (int), or -1 if unavailable
1565  */
1566 LIBVLC_API int libvlc_audio_get_track_count( libvlc_media_player_t *p_mi );
1567
1568 /**
1569  * Get the description of available audio tracks.
1570  *
1571  * \param p_mi media player
1572  * \return list with description of available audio tracks, or NULL
1573  */
1574 LIBVLC_API libvlc_track_description_t *
1575         libvlc_audio_get_track_description( libvlc_media_player_t *p_mi );
1576
1577 /**
1578  * Get current audio track.
1579  *
1580  * \param p_mi media player
1581  * \return the audio track ID or -1 if no active input.
1582  */
1583 LIBVLC_API int libvlc_audio_get_track( libvlc_media_player_t *p_mi );
1584
1585 /**
1586  * Set current audio track.
1587  *
1588  * \param p_mi media player
1589  * \param i_track the track ID (i_id field from track description)
1590  * \return 0 on success, -1 on error
1591  */
1592 LIBVLC_API int libvlc_audio_set_track( libvlc_media_player_t *p_mi, int i_track );
1593
1594 /**
1595  * Get current audio channel.
1596  *
1597  * \param p_mi media player
1598  * \return the audio channel \see libvlc_audio_output_channel_t
1599  */
1600 LIBVLC_API int libvlc_audio_get_channel( libvlc_media_player_t *p_mi );
1601
1602 /**
1603  * Set current audio channel.
1604  *
1605  * \param p_mi media player
1606  * \param channel the audio channel, \see libvlc_audio_output_channel_t
1607  * \return 0 on success, -1 on error
1608  */
1609 LIBVLC_API int libvlc_audio_set_channel( libvlc_media_player_t *p_mi, int channel );
1610
1611 /**
1612  * Get current audio delay.
1613  *
1614  * \param p_mi media player
1615  * \return the audio delay (microseconds)
1616  * \version LibVLC 1.1.1 or later
1617  */
1618 LIBVLC_API int64_t libvlc_audio_get_delay( libvlc_media_player_t *p_mi );
1619
1620 /**
1621  * Set current audio delay. The audio delay will be reset to zero each time the media changes.
1622  *
1623  * \param p_mi media player
1624  * \param i_delay the audio delay (microseconds)
1625  * \return 0 on success, -1 on error
1626  * \version LibVLC 1.1.1 or later
1627  */
1628 LIBVLC_API int libvlc_audio_set_delay( libvlc_media_player_t *p_mi, int64_t i_delay );
1629
1630 /** @} audio */
1631
1632 /** @} media_player */
1633
1634 # ifdef __cplusplus
1635 }
1636 # endif
1637
1638 #endif /* VLC_LIBVLC_MEDIA_PLAYER_H */