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 # endif
  37
  38 /*****************************************************************************
  39  * Media Player
  40  *****************************************************************************/
  41 /** \defgroup libvlc_media_player libvlc_media_player
  42  * \ingroup libvlc
  43  * LibVLC Media Player, object that let you play a media
  44  * in a custom drawable
  45  * @{
  46  */
  47
  48 typedef struct libvlc_media_player_t libvlc_media_player_t;
  49
  50 /**
  51  * Description for video, audio tracks and subtitles. It contains
  52  * id, name (description string) and pointer to next record.
  53  */
  54 typedef struct libvlc_track_description_t
  55 {
  56     int   i_id;
  57     char *psz_name;
  58     struct libvlc_track_description_t *p_next;
  59
  60 } libvlc_track_description_t;
  61
  62 /**
  63  * Description for audio output. It contains
  64  * name, description and pointer to next record.
  65  */
  66 typedef struct libvlc_audio_output_t
  67 {
  68     char *psz_name;
  69     char *psz_description;
  70     struct libvlc_audio_output_t *p_next;
  71
  72 } libvlc_audio_output_t;
  73
  74 /**
  75  * Rectangle type for video geometry
  76  */
  77 typedef struct libvlc_rectangle_t
  78 {
  79     int top, left;
  80     int bottom, right;
  81 } libvlc_rectangle_t;
  82
  83 /**
  84  * Marq options definition
  85  */
  86 typedef enum libvlc_video_marquee_option_t {
  87     libvlc_marquee_Enable = 0,
  88     libvlc_marquee_Text,                /** string argument */
  89     libvlc_marquee_Color,
  90     libvlc_marquee_Opacity,
  91     libvlc_marquee_Position,
  92     libvlc_marquee_Refresh,
  93     libvlc_marquee_Size,
  94     libvlc_marquee_Timeout,
  95     libvlc_marquee_X,
  96     libvlc_marquee_Y
  97 } libvlc_video_marquee_option_t;
  98
  99 /**
 100  * Create an empty Media Player object
 101  *
 102  * \param p_libvlc_instance the libvlc instance in which the Media Player
 103  *        should be created.
 104  * \return a new media player object, or NULL on error.
 105  */
 106 VLC_PUBLIC_API libvlc_media_player_t * libvlc_media_player_new( libvlc_instance_t * );
 107
 108 /**
 109  * Create a Media Player object from a Media
 110  *
 111  * \param p_md the media. Afterwards the p_md can be safely
 112  *        destroyed.
 113  * \return a new media player object, or NULL on error.
 114  */
 115 VLC_PUBLIC_API libvlc_media_player_t * libvlc_media_player_new_from_media( libvlc_media_t * );
 116
 117 /**
 118  * Release a media_player after use
 119  * Decrement the reference count of a media player object. If the
 120  * reference count is 0, then libvlc_media_player_release() will
 121  * release the media player object. If the media player object
 122  * has been released, then it should not be used again.
 123  *
 124  * \param p_mi the Media Player to free
 125  */
 126 VLC_PUBLIC_API void libvlc_media_player_release( libvlc_media_player_t * );
 127
 128 /**
 129  * Retain a reference to a media player object. Use
 130  * libvlc_media_player_release() to decrement reference count.
 131  *
 132  * \param p_mi media player object
 133  */
 134 VLC_PUBLIC_API void libvlc_media_player_retain( libvlc_media_player_t * );
 135
 136 /**
 137  * Set the media that will be used by the media_player. If any,
 138  * previous md will be released.
 139  *
 140  * \param p_mi the Media Player
 141  * \param p_md the Media. Afterwards the p_md can be safely
 142  *        destroyed.
 143  */
 144 VLC_PUBLIC_API void libvlc_media_player_set_media( libvlc_media_player_t *, libvlc_media_t * );
 145
 146 /**
 147  * Get the media used by the media_player.
 148  *
 149  * \param p_mi the Media Player
 150  * \return the media associated with p_mi, or NULL if no
 151  *         media is associated
 152  */
 153 VLC_PUBLIC_API libvlc_media_t * libvlc_media_player_get_media( libvlc_media_player_t * );
 154
 155 /**
 156  * Get the Event Manager from which the media player send event.
 157  *
 158  * \param p_mi the Media Player
 159  * \return the event manager associated with p_mi
 160  */
 161 VLC_PUBLIC_API libvlc_event_manager_t * libvlc_media_player_event_manager ( libvlc_media_player_t * );
 162
 163 /**
 164  * is_playing
 165  *
 166  * \param p_mi the Media Player
 167  * \return 1 if the media player is playing, 0 otherwise
 168  */
 169 VLC_PUBLIC_API int libvlc_media_player_is_playing ( libvlc_media_player_t * );
 170
 171 /**
 172  * Play
 173  *
 174  * \param p_mi the Media Player
 175  * \return 0 if playback started (and was already started), or -1 on error.
 176  */
 177 VLC_PUBLIC_API int libvlc_media_player_play ( libvlc_media_player_t * );
 178
 179 /**
 180  * Toggle pause (no effect if there is no media)
 181  *
 182  * \param p_mi the Media Player
 183  */
 184 VLC_PUBLIC_API void libvlc_media_player_pause ( libvlc_media_player_t * );
 185
 186 /**
 187  * Stop (no effect if there is no media)
 188  *
 189  * \param p_mi the Media Player
 190  */
 191 VLC_PUBLIC_API void libvlc_media_player_stop ( libvlc_media_player_t * );
 192
 193 /**
 194  * Set the NSView handler where the media player should render its video output.
 195  *
 196  * The object minimal_macosx expects is of kind NSObject and should
 197  * respect the protocol:
 198  *
 199  * @protocol VLCOpenGLVideoViewEmbedding <NSObject>
 200  * - (void)addVoutSubview:(NSView *)view;
 201  * - (void)removeVoutSubview:(NSView *)view;
 202  * @end
 203  *
 204  * You can find a live example in VLCVideoView in VLCKit.framework.
 205  *
 206  * \param p_mi the Media Player
 207  * \param drawable the NSView handler
 208  */
 209 VLC_PUBLIC_API void libvlc_media_player_set_nsobject ( libvlc_media_player_t *p_mi, void * drawable );
 210
 211 /**
 212  * Get the NSView handler previously set with libvlc_media_player_set_nsobject().
 213  *
 214  * \param p_mi the Media Player
 215  * \return the NSView handler or 0 if none where set
 216  */
 217 VLC_PUBLIC_API void * libvlc_media_player_get_nsobject ( libvlc_media_player_t *p_mi );
 218
 219 /**
 220  * Set the agl handler where the media player should render its video output.
 221  *
 222  * \param p_mi the Media Player
 223  * \param drawable the agl handler
 224  */
 225 VLC_PUBLIC_API void libvlc_media_player_set_agl ( libvlc_media_player_t *p_mi, uint32_t drawable );
 226
 227 /**
 228  * Get the agl handler previously set with libvlc_media_player_set_agl().
 229  *
 230  * \param p_mi the Media Player
 231  * \return the agl handler or 0 if none where set
 232  */
 233 VLC_PUBLIC_API uint32_t libvlc_media_player_get_agl ( libvlc_media_player_t *p_mi );
 234
 235 /**
 236  * Set an X Window System drawable where the media player should render its
 237  * video output. If LibVLC was built without X11 output support, then this has
 238  * no effects.
 239  *
 240  * The specified identifier must correspond to an existing Input/Output class
 241  * X11 window. Pixmaps are <b>not</b> supported. The caller shall ensure that
 242  * the X11 server is the same as the one the VLC instance has been configured
 243  * with.
 244  * If XVideo is <b>not</b> used, it is assumed that the drawable has the
 245  * following properties in common with the default X11 screen: depth, scan line
 246  * pad, black pixel. This is a bug.
 247  *
 248  * \param p_mi the Media Player
 249  * \param drawable the ID of the X window
 250  */
 251 VLC_PUBLIC_API void libvlc_media_player_set_xwindow ( libvlc_media_player_t *p_mi, uint32_t drawable );
 252
 253 /**
 254  * Get the X Window System window identifier previously set with
 255  * libvlc_media_player_set_xwindow(). Note that this will return the identifier
 256  * even if VLC is not currently using it (for instance if it is playing an
 257  * audio-only input).
 258  *
 259  * \param p_mi the Media Player
 260  * \return an X window ID, or 0 if none where set.
 261  */
 262 VLC_PUBLIC_API uint32_t libvlc_media_player_get_xwindow ( libvlc_media_player_t *p_mi );
 263
 264 /**
 265  * Set a Win32/Win64 API window handle (HWND) where the media player should
 266  * render its video output. If LibVLC was built without Win32/Win64 API output
 267  * support, then this has no effects.
 268  *
 269  * \param p_mi the Media Player
 270  * \param drawable windows handle of the drawable
 271  */
 272 VLC_PUBLIC_API void libvlc_media_player_set_hwnd ( libvlc_media_player_t *p_mi, void *drawable );
 273
 274 /**
 275  * Get the Windows API window handle (HWND) previously set with
 276  * libvlc_media_player_set_hwnd(). The handle will be returned even if LibVLC
 277  * is not currently outputting any video to it.
 278  *
 279  * \param p_mi the Media Player
 280  * \return a window handle or NULL if there are none.
 281  */
 282 VLC_PUBLIC_API void *libvlc_media_player_get_hwnd ( libvlc_media_player_t *p_mi );
 283
 284
 285
 286 /** \bug This might go away ... to be replaced by a broader system */
 287
 288 /**
 289  * Get the current movie length (in ms).
 290  *
 291  * \param p_mi the Media Player
 292  * \return the movie length (in ms), or -1 if there is no media.
 293  */
 294 VLC_PUBLIC_API libvlc_time_t libvlc_media_player_get_length( libvlc_media_player_t * );
 295
 296 /**
 297  * Get the current movie time (in ms).
 298  *
 299  * \param p_mi the Media Player
 300  * \return the movie time (in ms), or -1 if there is no media.
 301  */
 302 VLC_PUBLIC_API libvlc_time_t libvlc_media_player_get_time( libvlc_media_player_t * );
 303
 304 /**
 305  * Set the movie time (in ms). This has no effect if no media is being played.
 306  * Not all formats and protocols support this.
 307  *
 308  * \param p_mi the Media Player
 309  * \param the movie time (in ms).
 310  */
 311 VLC_PUBLIC_API void libvlc_media_player_set_time( libvlc_media_player_t *, libvlc_time_t );
 312
 313 /**
 314  * Get movie position.
 315  *
 316  * \param p_mi the Media Player
 317  * \return movie position, or -1. in case of error
 318  */
 319 VLC_PUBLIC_API float libvlc_media_player_get_position( libvlc_media_player_t * );
 320
 321 /**
 322  * Set movie position. This has no effect if playback is not enabled.
 323  * This might not work depending on the underlying input format and protocol.
 324  *
 325  * \param p_mi the Media Player
 326  * \param f_pos the position
 327  */
 328 VLC_PUBLIC_API void libvlc_media_player_set_position( libvlc_media_player_t *, float );
 329
 330 /**
 331  * Set movie chapter (if applicable).
 332  *
 333  * \param p_mi the Media Player
 334  * \param i_chapter chapter number to play
 335  */
 336 VLC_PUBLIC_API void libvlc_media_player_set_chapter( libvlc_media_player_t *, int );
 337
 338 /**
 339  * Get movie chapter.
 340  *
 341  * \param p_mi the Media Player
 342  * \return chapter number currently playing, or -1 if there is no media.
 343  */
 344 VLC_PUBLIC_API int libvlc_media_player_get_chapter( libvlc_media_player_t * );
 345
 346 /**
 347  * Get movie chapter count
 348  *
 349  * \param p_mi the Media Player
 350  * \return number of chapters in movie, or -1.
 351  */
 352 VLC_PUBLIC_API int libvlc_media_player_get_chapter_count( libvlc_media_player_t * );
 353
 354 /**
 355  * Is the player able to play
 356  *
 357  * \param p_mi the Media Player
 358  * \return boolean
 359  */
 360 VLC_PUBLIC_API int libvlc_media_player_will_play( libvlc_media_player_t * );
 361
 362 /**
 363  * Get title chapter count
 364  *
 365  * \param p_mi the Media Player
 366  * \param i_title title
 367  * \return number of chapters in title, or -1
 368  */
 369 VLC_PUBLIC_API int libvlc_media_player_get_chapter_count_for_title(
 370                        libvlc_media_player_t *, int );
 371
 372 /**
 373  * Set movie title
 374  *
 375  * \param p_mi the Media Player
 376  * \param i_title title number to play
 377  */
 378 VLC_PUBLIC_API void libvlc_media_player_set_title( libvlc_media_player_t *, int );
 379
 380 /**
 381  * Get movie title
 382  *
 383  * \param p_mi the Media Player
 384  * \return title number currently playing, or -1
 385  */
 386 VLC_PUBLIC_API int libvlc_media_player_get_title( libvlc_media_player_t * );
 387
 388 /**
 389  * Get movie title count
 390  *
 391  * \param p_mi the Media Player
 392  * \return title number count, or -1
 393  */
 394 VLC_PUBLIC_API int libvlc_media_player_get_title_count( libvlc_media_player_t * );
 395
 396 /**
 397  * Set previous chapter (if applicable)
 398  *
 399  * \param p_mi the Media Player
 400  */
 401 VLC_PUBLIC_API void libvlc_media_player_previous_chapter( libvlc_media_player_t * );
 402
 403 /**
 404  * Set next chapter (if applicable)
 405  *
 406  * \param p_mi the Media Player
 407  */
 408 VLC_PUBLIC_API void libvlc_media_player_next_chapter( libvlc_media_player_t * );
 409
 410 /**
 411  * Get movie play rate
 412  *
 413  * \param p_mi the Media Player
 414  * \return movie play rate, or zero in case of error
 415  */
 416 VLC_PUBLIC_API float libvlc_media_player_get_rate( libvlc_media_player_t * );
 417
 418 /**
 419  * Set movie play rate
 420  *
 421  * \param p_mi the Media Player
 422  * \param movie play rate to set
 423  * \return -1 if an error was detected, 0 otherwise (but even then, it might
 424  * not actually work depending on the underlying media protocol)
 425  */
 426 VLC_PUBLIC_API int libvlc_media_player_set_rate( libvlc_media_player_t *, float );
 427
 428 /**
 429  * Get current movie state
 430  *
 431  * \param p_mi the Media Player
 432  */
 433 VLC_PUBLIC_API libvlc_state_t libvlc_media_player_get_state( libvlc_media_player_t *);
 434
 435 /**
 436  * Get movie fps rate
 437  *
 438  * \param p_mi the Media Player
 439  * \return frames per second (fps) for this playing movie, or 0 if unspecified
 440  */
 441 VLC_PUBLIC_API float libvlc_media_player_get_fps( libvlc_media_player_t * );
 442
 443 /** end bug */
 444
 445 /**
 446  * How many video outputs does this media player have?
 447  *
 448  * \param p_md the media player
 449  * \return the number of video outputs
 450  */
 451 VLC_PUBLIC_API unsigned libvlc_media_player_has_vout( libvlc_media_player_t * );
 452
 453 /**
 454  * Is this media player seekable?
 455  *
 456  * \param p_input the input
 457  */
 458 VLC_PUBLIC_API int libvlc_media_player_is_seekable( libvlc_media_player_t *p_mi );
 459
 460 /**
 461  * Can this media player be paused?
 462  *
 463  * \param p_input the input
 464  */
 465 VLC_PUBLIC_API int libvlc_media_player_can_pause( libvlc_media_player_t *p_mi );
 466
 467
 468 /**
 469  * Display the next frame (if supported)
 470  *
 471  * \param p_input the libvlc_media_player_t instance
 472  */
 473 VLC_PUBLIC_API void libvlc_media_player_next_frame( libvlc_media_player_t *p_input );
 474
 475
 476
 477 /**
 478  * Release (free) libvlc_track_description_t
 479  *
 480  * \param p_track_description the structure to release
 481  */
 482 VLC_PUBLIC_API void libvlc_track_description_release( libvlc_track_description_t *p_track_description );
 483
 484 /** \defgroup libvlc_video libvlc_video
 485  * \ingroup libvlc_media_player
 486  * LibVLC Video handling
 487  * @{
 488  */
 489
 490 /**
 491  * Toggle fullscreen status on non-embedded video outputs.
 492  *
 493  * @warning The same limitations applies to this function
 494  * as to libvlc_set_fullscreen().
 495  *
 496  * \param p_mediaplayer the media player
 497  */
 498 VLC_PUBLIC_API void libvlc_toggle_fullscreen( libvlc_media_player_t * );
 499
 500 /**
 501  * Enable or disable fullscreen on non-embedded video outputs.
 502  *
 503  * @warning With most window managers, only a top-level windows can switch to
 504  * full-screen mode. Hence, this function will not operate properly if
 505  * libvlc_media_player_set_xid() or libvlc_media_player_set_hwnd() was
 506  * used to embed the video in a non-LibVLC widget. If you want to to render an
 507  * embedded LibVLC video full-screen, the parent embedding widget must expanded
 508  * to full screen (LibVLC cannot take care of that).
 509  * LibVLC will then automatically resize the video as appropriate.
 510  *
 511  * \param p_mediaplayer the media player
 512  * \param b_fullscreen boolean for fullscreen status
 513  */
 514 VLC_PUBLIC_API void libvlc_set_fullscreen( libvlc_media_player_t *, int );
 515
 516 /**
 517  * Get current fullscreen status.
 518  *
 519  * \param p_mediaplayer the media player
 520  * \return the fullscreen status (boolean)
 521  */
 522 VLC_PUBLIC_API int libvlc_get_fullscreen( libvlc_media_player_t * );
 523
 524 /**
 525  * Enable or disable key press events handling, according to the LibVLC hotkeys
 526  * configuration. By default and for historical reasons, keyboard events are
 527  * handled by the LibVLC video widget.
 528  *
 529  * \note On X11, there can be only one subscriber for key press and mouse
 530  * click events per window. If your application has subscribed to those events
 531  * for the X window ID of the video widget, then LibVLC will not be able to
 532  * handle key presses and mouse clicks in any case.
 533  *
 534  * \warning This function is only implemented for X11 at the moment.
 535  *
 536  * \param mp the media player
 537  * \param on true to handle key press events, false to ignore them.
 538  */
 539 VLC_PUBLIC_API
 540 void libvlc_video_set_key_input( libvlc_media_player_t *mp, unsigned on );
 541
 542 /**
 543  * Enable or disable mouse click events handling. By default, those events are
 544  * handled. This is needed for DVD menus to work, as well as a few video
 545  * filters such as "puzzle".
 546  *
 547  * \note See also \func libvlc_video_set_key_input().
 548  *
 549  * \warning This function is only implemented for X11 at the moment.
 550  *
 551  * \param mp the media player
 552  * \param on true to handle mouse click events, false to ignore them.
 553  */
 554 VLC_PUBLIC_API
 555 void libvlc_video_set_mouse_input( libvlc_media_player_t *mp, unsigned on );
 556
 557 /**
 558  * Get the pixel dimensions of a video.
 559  *
 560  * \param mp media player
 561  * \param num number of the video (starting from, and most commonly 0)
 562  * \param px pointer to get the pixel width [OUT]
 563  * \param py pointer to get the pixel height [OUT]
 564  * \return 0 on success, -1 if the specified video does not exist
 565  */
 566 VLC_PUBLIC_API
 567 int libvlc_video_get_size( libvlc_media_player_t *mp, unsigned num,
 568                            unsigned *px, unsigned *py );
 569
 570 /**
 571  * Get current video height.
 572  * You should use libvlc_video_get_size() instead.
 573  *
 574  * \param p_mediaplayer the media player
 575  * \return the video pixel height or 0 if not applicable
 576  */
 577 VLC_DEPRECATED_API
 578 int libvlc_video_get_height( libvlc_media_player_t * );
 579
 580 /**
 581  * Get current video width.
 582  * You should use libvlc_video_get_size() instead.
 583  *
 584  * \param p_mediaplayer the media player
 585  * \return the video pixel width or 0 if not applicable
 586  */
 587 VLC_DEPRECATED_API
 588 int libvlc_video_get_width( libvlc_media_player_t * );
 589
 590 /**
 591  * Get the current video scaling factor.
 592  * See also libvlc_video_set_scale().
 593  *
 594  * \param p_mediaplayer the media player
 595  * \return the currently configured zoom factor, or 0. if the video is set
 596  * to fit to the output window/drawable automatically.
 597  */
 598 VLC_PUBLIC_API float libvlc_video_get_scale( libvlc_media_player_t * );
 599
 600 /**
 601  * Set the video scaling factor. That is the ratio of the number of pixels on
 602  * screen to the number of pixels in the original decoded video in each
 603  * dimension. Zero is a special value; it will adjust the video to the output
 604  * window/drawable (in windowed mode) or the entire screen.
 605  *
 606  * Note that not all video outputs support scaling.
 607  *
 608  * \param p_mediaplayer the media player
 609  * \param i_factor the scaling factor, or zero
 610  */
 611 VLC_PUBLIC_API void libvlc_video_set_scale( libvlc_media_player_t *, float );
 612
 613 /**
 614  * Get current video aspect ratio.
 615  *
 616  * \param p_mediaplayer the media player
 617  * \return the video aspect ratio or NULL if unspecified
 618  * (the result must be released with free() or libvlc_free()).
 619  */
 620 VLC_PUBLIC_API char *libvlc_video_get_aspect_ratio( libvlc_media_player_t * );
 621
 622 /**
 623  * Set new video aspect ratio.
 624  *
 625  * \param p_mediaplayer the media player
 626  * \param psz_aspect new video aspect-ratio or NULL to reset to default
 627  * \note Invalid aspect ratios are ignored.
 628  */
 629 VLC_PUBLIC_API void libvlc_video_set_aspect_ratio( libvlc_media_player_t *, const char * );
 630
 631 /**
 632  * Get current video subtitle.
 633  *
 634  * \param p_mediaplayer the media player
 635  * \return the video subtitle selected, or -1 if none
 636  */
 637 VLC_PUBLIC_API int libvlc_video_get_spu( libvlc_media_player_t * );
 638
 639 /**
 640  * Get the number of available video subtitles.
 641  *
 642  * \param p_mediaplayer the media player
 643  * \return the number of available video subtitles
 644  */
 645 VLC_PUBLIC_API int libvlc_video_get_spu_count( libvlc_media_player_t * );
 646
 647 /**
 648  * Get the description of available video subtitles.
 649  *
 650  * \param p_mediaplayer the media player
 651  * \return list containing description of available video subtitles
 652  */
 653 VLC_PUBLIC_API libvlc_track_description_t *
 654         libvlc_video_get_spu_description( libvlc_media_player_t * );
 655
 656 /**
 657  * Set new video subtitle.
 658  *
 659  * \param p_mediaplayer the media player
 660  * \param i_spu new video subtitle to select
 661  * \return 0 on success, -1 if out of range
 662  */
 663 VLC_PUBLIC_API int libvlc_video_set_spu( libvlc_media_player_t *, unsigned );
 664
 665 /**
 666  * Set new video subtitle file.
 667  *
 668  * \param p_mediaplayer the media player
 669  * \param psz_subtitle new video subtitle file
 670  * \return the success status (boolean)
 671  */
 672 VLC_PUBLIC_API int libvlc_video_set_subtitle_file( libvlc_media_player_t *, const char * );
 673
 674 /**
 675  * Get the description of available titles.
 676  *
 677  * \param p_mediaplayer the media player
 678  * \return list containing description of available titles
 679  */
 680 VLC_PUBLIC_API libvlc_track_description_t *
 681         libvlc_video_get_title_description( libvlc_media_player_t * );
 682
 683 /**
 684  * Get the description of available chapters for specific title.
 685  *
 686  * \param p_mediaplayer the media player
 687  * \param i_title selected title
 688  * \return list containing description of available chapter for title i_title
 689  */
 690 VLC_PUBLIC_API libvlc_track_description_t *
 691         libvlc_video_get_chapter_description( libvlc_media_player_t *, int );
 692
 693 /**
 694  * Get current crop filter geometry.
 695  *
 696  * \param p_mediaplayer the media player
 697  * \return the crop filter geometry or NULL if unset
 698  */
 699 VLC_PUBLIC_API char *libvlc_video_get_crop_geometry( libvlc_media_player_t * );
 700
 701 /**
 702  * Set new crop filter geometry.
 703  *
 704  * \param p_mediaplayer the media player
 705  * \param psz_geometry new crop filter geometry (NULL to unset)
 706  */
 707 VLC_PUBLIC_API
 708 void libvlc_video_set_crop_geometry( libvlc_media_player_t *, const char * );
 709
 710 /**
 711  * Get current teletext page requested.
 712  *
 713  * \param p_mediaplayer the media player
 714  * \return the current teletext page requested.
 715  */
 716 VLC_PUBLIC_API int libvlc_video_get_teletext( libvlc_media_player_t * );
 717
 718 /**
 719  * Set new teletext page to retrieve.
 720  *
 721  * \param p_mediaplayer the media player
 722  * \param i_page teletex page number requested
 723  */
 724 VLC_PUBLIC_API void libvlc_video_set_teletext( libvlc_media_player_t *, int );
 725
 726 /**
 727  * Toggle teletext transparent status on video output.
 728  *
 729  * \param p_mediaplayer the media player
 730  */
 731 VLC_PUBLIC_API void libvlc_toggle_teletext( libvlc_media_player_t * );
 732
 733 /**
 734  * Get number of available video tracks.
 735  *
 736  * \param p_mi media player
 737  * \return the number of available video tracks (int)
 738  */
 739 VLC_PUBLIC_API int libvlc_video_get_track_count( libvlc_media_player_t * );
 740
 741 /**
 742  * Get the description of available video tracks.
 743  *
 744  * \param p_mi media player
 745  * \return list with description of available video tracks, or NULL on error
 746  */
 747 VLC_PUBLIC_API libvlc_track_description_t *
 748         libvlc_video_get_track_description( libvlc_media_player_t * );
 749
 750 /**
 751  * Get current video track.
 752  *
 753  * \param p_mi media player
 754  * \return the video track (int) or -1 if none
 755  */
 756 VLC_PUBLIC_API int libvlc_video_get_track( libvlc_media_player_t * );
 757
 758 /**
 759  * Set video track.
 760  *
 761  * \param p_mi media player
 762  * \param i_track the track (int)
 763  * \return 0 on success, -1 if out of range
 764  */
 765 VLC_PUBLIC_API
 766 int libvlc_video_set_track( libvlc_media_player_t *, int );
 767
 768 /**
 769  * Take a snapshot of the current video window.
 770  *
 771  * If i_width AND i_height is 0, original size is used.
 772  * If i_width XOR i_height is 0, original aspect-ratio is preserved.
 773  *
 774  * \param p_mi media player instance
 775  * \param num number of video output (typically 0 for the first/only one)
 776  * \param psz_filepath the path where to save the screenshot to
 777  * \param i_width the snapshot's width
 778  * \param i_height the snapshot's height
 779  * \return 0 on success, -1 if the video was not found
 780  */
 781 VLC_PUBLIC_API
 782 int libvlc_video_take_snapshot( libvlc_media_player_t *, unsigned num,
 783                                 const char *,unsigned int, unsigned int );
 784
 785 /**
 786  * Enable or disable deinterlace filter
 787  *
 788  * \param p_mi libvlc media player
 789  * \param psz_mode type of deinterlace filter, NULL to disable
 790  */
 791 VLC_PUBLIC_API void libvlc_video_set_deinterlace( libvlc_media_player_t *,
 792                                                   const char * );
 793
 794 /**
 795  * Get an integer marquee option value
 796  *
 797  * \param p_mi libvlc media player
 798  * \param option marq option to get \see libvlc_video_marquee_int_option_t
 799  */
 800 VLC_PUBLIC_API int libvlc_video_get_marquee_int( libvlc_media_player_t *,
 801                                                  unsigned );
 802
 803 /**
 804  * Get a string marquee option value
 805  *
 806  * \param p_mi libvlc media player
 807  * \param option marq option to get \see libvlc_video_marquee_string_option_t
 808  */
 809 VLC_PUBLIC_API char *libvlc_video_get_marquee_string( libvlc_media_player_t *,
 810                                                       unsigned );
 811
 812 /**
 813  * Enable, disable or set an integer marquee option
 814  *
 815  * Setting libvlc_marquee_Enable has the side effect of enabling (arg !0)
 816  * or disabling (arg 0) the marq filter.
 817  *
 818  * \param p_mi libvlc media player
 819  * \param option marq option to set \see libvlc_video_marquee_int_option_t
 820  * \param i_val marq option value
 821  */
 822 VLC_PUBLIC_API void libvlc_video_set_marquee_int( libvlc_media_player_t *,
 823                                                   unsigned, int );
 824
 825 /**
 826  * Set a marquee string option
 827  *
 828  * \param p_mi libvlc media player
 829  * \param option marq option to set \see libvlc_video_marquee_string_option_t
 830  * \param psz_text marq option value
 831  */
 832 VLC_PUBLIC_API void libvlc_video_set_marquee_string( libvlc_media_player_t *,
 833                                                      unsigned, const char * );
 834
 835 /** option values for libvlc_video_{get,set}_logo_{int,string} */
 836 enum libvlc_video_logo_option_t {
 837     libvlc_logo_enable,
 838     libvlc_logo_file,           /**< string argument, "file,d,t;file,d,t;..." */
 839     libvlc_logo_x,
 840     libvlc_logo_y,
 841     libvlc_logo_delay,
 842     libvlc_logo_repeat,
 843     libvlc_logo_opacity,
 844     libvlc_logo_position,
 845 };
 846
 847 /**
 848  * Get integer logo option.
 849  *
 850  * \param p_mi libvlc media player instance
 851  * \param option logo option to get, values of libvlc_video_logo_option_t
 852  */
 853 VLC_PUBLIC_API int libvlc_video_get_logo_int( libvlc_media_player_t *p_mi,
 854                                               unsigned option );
 855
 856 /**
 857  * Set logo option as integer. Options that take a different type value
 858  * are ignored.
 859  * Passing libvlc_logo_enable as option value has the side effect of
 860  * starting (arg !0) or stopping (arg 0) the logo filter.
 861  *
 862  * \param p_mi libvlc media player instance
 863  * \param option logo option to set, values of libvlc_video_logo_option_t
 864  * \param value logo option value
 865  */
 866 VLC_PUBLIC_API void libvlc_video_set_logo_int( libvlc_media_player_t *p_mi,
 867                                                unsigned option, int value );
 868
 869 /**
 870  * Set logo option as string. Options that take a different type value
 871  * are ignored.
 872  *
 873  * \param p_mi libvlc media player instance
 874  * \param option logo option to set, values of libvlc_video_logo_option_t
 875  * \param psz_value logo option value
 876  */
 877 VLC_PUBLIC_API void libvlc_video_set_logo_string( libvlc_media_player_t *p_mi,
 878                                       unsigned option, const char *psz_value );
 879
 880
 881 /** @} video */
 882
 883 /** \defgroup libvlc_audio libvlc_audio
 884  * \ingroup libvlc_media_player
 885  * LibVLC Audio handling
 886  * @{
 887  */
 888
 889 /**
 890  * Audio device types
 891  */
 892 typedef enum libvlc_audio_output_device_types_t {
 893     libvlc_AudioOutputDevice_Error  = -1,
 894     libvlc_AudioOutputDevice_Mono   =  1,
 895     libvlc_AudioOutputDevice_Stereo =  2,
 896     libvlc_AudioOutputDevice_2F2R   =  4,
 897     libvlc_AudioOutputDevice_3F2R   =  5,
 898     libvlc_AudioOutputDevice_5_1    =  6,
 899     libvlc_AudioOutputDevice_6_1    =  7,
 900     libvlc_AudioOutputDevice_7_1    =  8,
 901     libvlc_AudioOutputDevice_SPDIF  = 10
 902 } libvlc_audio_output_device_types_t;
 903
 904 /**
 905  * Audio channels
 906  */
 907 typedef enum libvlc_audio_output_channel_t {
 908     libvlc_AudioChannel_Error   = -1,
 909     libvlc_AudioChannel_Stereo  =  1,
 910     libvlc_AudioChannel_RStereo =  2,
 911     libvlc_AudioChannel_Left    =  3,
 912     libvlc_AudioChannel_Right   =  4,
 913     libvlc_AudioChannel_Dolbys  =  5
 914 } libvlc_audio_output_channel_t;
 915
 916
 917 /**
 918  * Get the list of available audio outputs
 919  *
 920  * \param p_instance libvlc instance
 921  * \return list of available audio outputs. It must be freed it with
 922 *          \see libvlc_audio_output_list_release \see libvlc_audio_output_t .
 923  *         In case of error, NULL is returned.
 924  */
 925 VLC_PUBLIC_API libvlc_audio_output_t *
 926         libvlc_audio_output_list_get( libvlc_instance_t * );
 927
 928 /**
 929  * Free the list of available audio outputs
 930  *
 931  * \param p_list list with audio outputs for release
 932  */
 933 VLC_PUBLIC_API void libvlc_audio_output_list_release( libvlc_audio_output_t * );
 934
 935 /**
 936  * Set the audio output.
 937  * Change will be applied after stop and play.
 938  *
 939  * \param mp media player
 940  * \param psz_name name of audio output,
 941  *               use psz_name of \see libvlc_audio_output_t
 942  * \return true if function succeded
 943  */
 944 VLC_PUBLIC_API int libvlc_audio_output_set( libvlc_media_player_t *,
 945                                             const char * );
 946
 947 /**
 948  * Get count of devices for audio output, these devices are hardware oriented
 949  * like analor or digital output of sound card
 950  *
 951  * \param p_instance libvlc instance
 952  * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
 953  * \return number of devices
 954  */
 955 VLC_PUBLIC_API int libvlc_audio_output_device_count( libvlc_instance_t *,
 956                                                      const char * );
 957
 958 /**
 959  * Get long name of device, if not available short name given
 960  *
 961  * \param p_instance libvlc instance
 962  * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
 963  * \param i_device device index
 964  * \return long name of device
 965  */
 966 VLC_PUBLIC_API char * libvlc_audio_output_device_longname( libvlc_instance_t *,
 967                                                            const char *,
 968                                                            int );
 969
 970 /**
 971  * Get id name of device
 972  *
 973  * \param p_instance libvlc instance
 974  * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
 975  * \param i_device device index
 976  * \return id name of device, use for setting device, need to be free after use
 977  */
 978 VLC_PUBLIC_API char * libvlc_audio_output_device_id( libvlc_instance_t *,
 979                                                      const char *,
 980                                                      int );
 981
 982 /**
 983  * Set audio output device. Changes are only effective after stop and play.
 984  *
 985  * \param mp media player
 986  * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
 987  * \param psz_device_id device
 988  */
 989 VLC_PUBLIC_API void libvlc_audio_output_device_set( libvlc_media_player_t *,
 990                                                     const char *,
 991                                                     const char * );
 992
 993 /**
 994  * Get current audio device type. Device type describes something like
 995  * character of output sound - stereo sound, 2.1, 5.1 etc
 996  *
 997  * \param mp media player
 998  * \return the audio devices type \see libvlc_audio_output_device_types_t
 999  */
1000 VLC_PUBLIC_API int libvlc_audio_output_get_device_type(
1001         libvlc_media_player_t * );
1002
1003 /**
1004  * Set current audio device type.
1005  *
1006  * \param mp vlc instance
1007  * \param device_type the audio device type,
1008           according to \see libvlc_audio_output_device_types_t
1009  */
1010 VLC_PUBLIC_API void libvlc_audio_output_set_device_type( libvlc_media_player_t *,
1011                                                          int );
1012
1013
1014 /**
1015  * Toggle mute status.
1016  *
1017  * \param mp media player
1018  */
1019 VLC_PUBLIC_API void libvlc_audio_toggle_mute( libvlc_media_player_t * );
1020
1021 /**
1022  * Get current mute status.
1023  *
1024  * \param mp media player
1025  * \return the mute status (boolean)
1026  */
1027 VLC_PUBLIC_API int libvlc_audio_get_mute( libvlc_media_player_t * );
1028
1029 /**
1030  * Set mute status.
1031  *
1032  * \param mp media player
1033  * \param status If status is true then mute, otherwise unmute
1034  */
1035 VLC_PUBLIC_API void libvlc_audio_set_mute( libvlc_media_player_t *, int );
1036
1037 /**
1038  * Get current audio level.
1039  *
1040  * \param mp media player
1041  * \return the audio level (int)
1042  */
1043 VLC_PUBLIC_API int libvlc_audio_get_volume( libvlc_media_player_t * );
1044
1045 /**
1046  * Set current audio level.
1047  *
1048  * \param mp media player
1049  * \param i_volume the volume (int)
1050  * \return 0 if the volume was set, -1 if it was out of range
1051  */
1052 VLC_PUBLIC_API int libvlc_audio_set_volume( libvlc_media_player_t *, int );
1053
1054 /**
1055  * Get number of available audio tracks.
1056  *
1057  * \param p_mi media player
1058  * \return the number of available audio tracks (int), or -1 if unavailable
1059  */
1060 VLC_PUBLIC_API int libvlc_audio_get_track_count( libvlc_media_player_t * );
1061
1062 /**
1063  * Get the description of available audio tracks.
1064  *
1065  * \param p_mi media player
1066  * \return list with description of available audio tracks, or NULL
1067  */
1068 VLC_PUBLIC_API libvlc_track_description_t *
1069         libvlc_audio_get_track_description( libvlc_media_player_t * );
1070
1071 /**
1072  * Get current audio track.
1073  *
1074  * \param p_mi media player
1075  * \return the audio track (int), or -1 if none.
1076  */
1077 VLC_PUBLIC_API int libvlc_audio_get_track( libvlc_media_player_t * );
1078
1079 /**
1080  * Set current audio track.
1081  *
1082  * \param p_mi media player
1083  * \param i_track the track (int)
1084  * \return 0 on success, -1 on error
1085  */
1086 VLC_PUBLIC_API int libvlc_audio_set_track( libvlc_media_player_t *, int );
1087
1088 /**
1089  * Get current audio channel.
1090  *
1091  * \param mp media player
1092  * \return the audio channel \see libvlc_audio_output_channel_t
1093  */
1094 VLC_PUBLIC_API int libvlc_audio_get_channel( libvlc_media_player_t * );
1095
1096 /**
1097  * Set current audio channel.
1098  *
1099  * \param p_mi media player
1100  * \param channel the audio channel, \see libvlc_audio_output_channel_t
1101  * \return 0 on success, -1 on error
1102  */
1103 VLC_PUBLIC_API int libvlc_audio_set_channel( libvlc_media_player_t *, int );
1104
1105 /** @} audio */
1106
1107 /** @} media_player */
1108
1109 # ifdef __cplusplus
1110 }
1111 # endif
1112
1113 #endif /* VLC_LIBVLC_MEDIA_PLAYER_H */