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