1 /***************************************************************************** 2 * libvlc_media_player.h: libvlc_media_player external API 3 ***************************************************************************** 4 * Copyright (C) 1998-2015 VLC authors and VideoLAN 5 * $Id: c431c235e92ced9e6e7d7712eb7ff0e73dc4f933 $ 6 * 7 * Authors: Clément Stenac <zorglub@videolan.org> 8 * Jean-Paul Saman <jpsaman@videolan.org> 9 * Pierre d'Herbemont <pdherbemont@videolan.org> 10 * 11 * This program is free software; you can redistribute it and/or modify it 12 * under the terms of the GNU Lesser General Public License as published by 13 * the Free Software Foundation; either version 2.1 of the License, or 14 * (at your option) any later version. 15 * 16 * This program is distributed in the hope that it will be useful, 17 * but WITHOUT ANY WARRANTY; without even the implied warranty of 18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 19 * GNU Lesser General Public License for more details. 20 * 21 * You should have received a copy of the GNU Lesser General Public License 22 * along with this program; if not, write to the Free Software Foundation, 23 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA. 24 *****************************************************************************/ 25 26 #ifndef VLC_LIBVLC_MEDIA_PLAYER_H 27 #define VLC_LIBVLC_MEDIA_PLAYER_H 1 28 29 # ifdef __cplusplus 30 extern "C" { 31 # else 32 # include <stdbool.h> 33 # endif 34 35 /** \defgroup libvlc_media_player LibVLC media player 36 * \ingroup libvlc 37 * A LibVLC media player plays one media (usually in a custom drawable). 38 * @{ 39 * \file 40 * LibVLC simple media player external API 41 */ 42 43 typedef struct libvlc_media_player_t libvlc_media_player_t; 44 45 /** 46 * Description for video, audio tracks and subtitles. It contains 47 * id, name (description string) and pointer to next record. 48 */ 49 typedef struct libvlc_track_description_t 50 { 51 int i_id; 52 char *psz_name; 53 struct libvlc_track_description_t *p_next; 54 55 } libvlc_track_description_t; 56 57 /** 58 * Description for titles 59 */ 60 enum 61 { 62 libvlc_title_menu = 0x01, 63 libvlc_title_interactive = 0x02 64 }; 65 66 typedef struct libvlc_title_description_t 67 { 68 int64_t i_duration; /**< duration in milliseconds */ 69 char *psz_name; /**< title name */ 70 unsigned i_flags; /**< info if item was recognized as a menu, interactive or plain content by the demuxer */ 71 } libvlc_title_description_t; 72 73 /** 74 * Description for chapters 75 */ 76 typedef struct libvlc_chapter_description_t 77 { 78 int64_t i_time_offset; /**< time-offset of the chapter in milliseconds */ 79 int64_t i_duration; /**< duration of the chapter in milliseconds */ 80 char *psz_name; /**< chapter name */ 81 } libvlc_chapter_description_t; 82 83 /** 84 * Description for audio output. It contains 85 * name, description and pointer to next record. 86 */ 87 typedef struct libvlc_audio_output_t 88 { 89 char *psz_name; 90 char *psz_description; 91 struct libvlc_audio_output_t *p_next; 92 93 } libvlc_audio_output_t; 94 95 /** 96 * Description for audio output device. 97 */ 98 typedef struct libvlc_audio_output_device_t 99 { 100 struct libvlc_audio_output_device_t *p_next; /**< Next entry in list */ 101 char *psz_device; /**< Device identifier string */ 102 char *psz_description; /**< User-friendly device description */ 103 /* More fields may be added here in later versions */ 104 } libvlc_audio_output_device_t; 105 106 /** 107 * Marq options definition 108 */ 109 typedef enum libvlc_video_marquee_option_t { 110 libvlc_marquee_Enable = 0, 111 libvlc_marquee_Text, /** string argument */ 112 libvlc_marquee_Color, 113 libvlc_marquee_Opacity, 114 libvlc_marquee_Position, 115 libvlc_marquee_Refresh, 116 libvlc_marquee_Size, 117 libvlc_marquee_Timeout, 118 libvlc_marquee_X, 119 libvlc_marquee_Y 120 } libvlc_video_marquee_option_t; 121 122 /** 123 * Navigation mode 124 */ 125 typedef enum libvlc_navigate_mode_t 126 { 127 libvlc_navigate_activate = 0, 128 libvlc_navigate_up, 129 libvlc_navigate_down, 130 libvlc_navigate_left, 131 libvlc_navigate_right, 132 libvlc_navigate_popup 133 } libvlc_navigate_mode_t; 134 135 /** 136 * Enumeration of values used to set position (e.g. of video title). 137 */ 138 typedef enum libvlc_position_t { 139 libvlc_position_disable=-1, 140 libvlc_position_center, 141 libvlc_position_left, 142 libvlc_position_right, 143 libvlc_position_top, 144 libvlc_position_top_left, 145 libvlc_position_top_right, 146 libvlc_position_bottom, 147 libvlc_position_bottom_left, 148 libvlc_position_bottom_right 149 } libvlc_position_t; 150 151 /** 152 * Enumeration of teletext keys than can be passed via 153 * libvlc_video_set_teletext() 154 */ 155 typedef enum libvlc_teletext_key_t { 156 libvlc_teletext_key_red = 'r' << 16, 157 libvlc_teletext_key_green = 'g' << 16, 158 libvlc_teletext_key_yellow = 'y' << 16, 159 libvlc_teletext_key_blue = 'b' << 16, 160 libvlc_teletext_key_index = 'i' << 16, 161 } libvlc_teletext_key_t; 162 163 /** 164 * Opaque equalizer handle. 165 * 166 * Equalizer settings can be applied to a media player. 167 */ 168 typedef struct libvlc_equalizer_t libvlc_equalizer_t; 169 170 /** 171 * Create an empty Media Player object 172 * 173 * \param p_libvlc_instance the libvlc instance in which the Media Player 174 * should be created. 175 * \return a new media player object, or NULL on error. 176 */ 177 LIBVLC_API libvlc_media_player_t * libvlc_media_player_new( libvlc_instance_t *p_libvlc_instance ); 178 179 /** 180 * Create a Media Player object from a Media 181 * 182 * \param p_md the media. Afterwards the p_md can be safely 183 * destroyed. 184 * \return a new media player object, or NULL on error. 185 */ 186 LIBVLC_API libvlc_media_player_t * libvlc_media_player_new_from_media( libvlc_media_t *p_md ); 187 188 /** 189 * Release a media_player after use 190 * Decrement the reference count of a media player object. If the 191 * reference count is 0, then libvlc_media_player_release() will 192 * release the media player object. If the media player object 193 * has been released, then it should not be used again. 194 * 195 * \param p_mi the Media Player to free 196 */ 197 LIBVLC_API void libvlc_media_player_release( libvlc_media_player_t *p_mi ); 198 199 /** 200 * Retain a reference to a media player object. Use 201 * libvlc_media_player_release() to decrement reference count. 202 * 203 * \param p_mi media player object 204 */ 205 LIBVLC_API void libvlc_media_player_retain( libvlc_media_player_t *p_mi ); 206 207 /** 208 * Set the media that will be used by the media_player. If any, 209 * previous md will be released. 210 * 211 * \param p_mi the Media Player 212 * \param p_md the Media. Afterwards the p_md can be safely 213 * destroyed. 214 */ 215 LIBVLC_API void libvlc_media_player_set_media( libvlc_media_player_t *p_mi, 216 libvlc_media_t *p_md ); 217 218 /** 219 * Get the media used by the media_player. 220 * 221 * \param p_mi the Media Player 222 * \return the media associated with p_mi, or NULL if no 223 * media is associated 224 */ 225 LIBVLC_API libvlc_media_t * libvlc_media_player_get_media( libvlc_media_player_t *p_mi ); 226 227 /** 228 * Get the Event Manager from which the media player send event. 229 * 230 * \param p_mi the Media Player 231 * \return the event manager associated with p_mi 232 */ 233 LIBVLC_API libvlc_event_manager_t * libvlc_media_player_event_manager ( libvlc_media_player_t *p_mi ); 234 235 /** 236 * is_playing 237 * 238 * \param p_mi the Media Player 239 * \return 1 if the media player is playing, 0 otherwise 240 * 241 * \libvlc_return_bool 242 */ 243 LIBVLC_API int libvlc_media_player_is_playing ( libvlc_media_player_t *p_mi ); 244 245 /** 246 * Play 247 * 248 * \param p_mi the Media Player 249 * \return 0 if playback started (and was already started), or -1 on error. 250 */ 251 LIBVLC_API int libvlc_media_player_play ( libvlc_media_player_t *p_mi ); 252 253 /** 254 * Pause or resume (no effect if there is no media) 255 * 256 * \param mp the Media Player 257 * \param do_pause play/resume if zero, pause if non-zero 258 * \version LibVLC 1.1.1 or later 259 */ 260 LIBVLC_API void libvlc_media_player_set_pause ( libvlc_media_player_t *mp, 261 int do_pause ); 262 263 /** 264 * Toggle pause (no effect if there is no media) 265 * 266 * \param p_mi the Media Player 267 */ 268 LIBVLC_API void libvlc_media_player_pause ( libvlc_media_player_t *p_mi ); 269 270 /** 271 * Stop (no effect if there is no media) 272 * 273 * \param p_mi the Media Player 274 */ 275 LIBVLC_API void libvlc_media_player_stop ( libvlc_media_player_t *p_mi ); 276 277 /** 278 * Set a renderer to the media player 279 * 280 * \note must be called before the first call of libvlc_media_player_play() to 281 * take effect. 282 * 283 * \see libvlc_renderer_discoverer_new 284 * 285 * \param p_mi the Media Player 286 * \param p_item an item discovered by libvlc_renderer_discoverer_start() 287 * \return 0 on success, -1 on error. 288 * \version LibVLC 3.0.0 or later 289 */ 290 LIBVLC_API int libvlc_media_player_set_renderer( libvlc_media_player_t *p_mi, 291 libvlc_renderer_item_t *p_item ); 292 293 /** 294 * Callback prototype to allocate and lock a picture buffer. 295 * 296 * Whenever a new video frame needs to be decoded, the lock callback is 297 * invoked. Depending on the video chroma, one or three pixel planes of 298 * adequate dimensions must be returned via the second parameter. Those 299 * planes must be aligned on 32-bytes boundaries. 300 * 301 * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN] 302 * \param planes start address of the pixel planes (LibVLC allocates the array 303 * of void pointers, this callback must initialize the array) [OUT] 304 * \return a private pointer for the display and unlock callbacks to identify 305 * the picture buffers 306 */ 307 typedef void *(*libvlc_video_lock_cb)(void *opaque, void **planes); 308 309 /** 310 * Callback prototype to unlock a picture buffer. 311 * 312 * When the video frame decoding is complete, the unlock callback is invoked. 313 * This callback might not be needed at all. It is only an indication that the 314 * application can now read the pixel values if it needs to. 315 * 316 * \note A picture buffer is unlocked after the picture is decoded, 317 * but before the picture is displayed. 318 * 319 * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN] 320 * \param picture private pointer returned from the @ref libvlc_video_lock_cb 321 * callback [IN] 322 * \param planes pixel planes as defined by the @ref libvlc_video_lock_cb 323 * callback (this parameter is only for convenience) [IN] 324 */ 325 typedef void (*libvlc_video_unlock_cb)(void *opaque, void *picture, 326 void *const *planes); 327 328 /** 329 * Callback prototype to display a picture. 330 * 331 * When the video frame needs to be shown, as determined by the media playback 332 * clock, the display callback is invoked. 333 * 334 * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN] 335 * \param picture private pointer returned from the @ref libvlc_video_lock_cb 336 * callback [IN] 337 */ 338 typedef void (*libvlc_video_display_cb)(void *opaque, void *picture); 339 340 /** 341 * Callback prototype to configure picture buffers format. 342 * This callback gets the format of the video as output by the video decoder 343 * and the chain of video filters (if any). It can opt to change any parameter 344 * as it needs. In that case, LibVLC will attempt to convert the video format 345 * (rescaling and chroma conversion) but these operations can be CPU intensive. 346 * 347 * \param opaque pointer to the private pointer passed to 348 * libvlc_video_set_callbacks() [IN/OUT] 349 * \param chroma pointer to the 4 bytes video format identifier [IN/OUT] 350 * \param width pointer to the pixel width [IN/OUT] 351 * \param height pointer to the pixel height [IN/OUT] 352 * \param pitches table of scanline pitches in bytes for each pixel plane 353 * (the table is allocated by LibVLC) [OUT] 354 * \param lines table of scanlines count for each plane [OUT] 355 * \return the number of picture buffers allocated, 0 indicates failure 356 * 357 * \note 358 * For each pixels plane, the scanline pitch must be bigger than or equal to 359 * the number of bytes per pixel multiplied by the pixel width. 360 * Similarly, the number of scanlines must be bigger than of equal to 361 * the pixel height. 362 * Furthermore, we recommend that pitches and lines be multiple of 32 363 * to not break assumptions that might be held by optimized code 364 * in the video decoders, video filters and/or video converters. 365 */ 366 typedef unsigned (*libvlc_video_format_cb)(void **opaque, char *chroma, 367 unsigned *width, unsigned *height, 368 unsigned *pitches, 369 unsigned *lines); 370 371 /** 372 * Callback prototype to configure picture buffers format. 373 * 374 * \param opaque private pointer as passed to libvlc_video_set_callbacks() 375 * (and possibly modified by @ref libvlc_video_format_cb) [IN] 376 */ 377 typedef void (*libvlc_video_cleanup_cb)(void *opaque); 378 379 380 /** 381 * Set callbacks and private data to render decoded video to a custom area 382 * in memory. 383 * Use libvlc_video_set_format() or libvlc_video_set_format_callbacks() 384 * to configure the decoded format. 385 * 386 * \warning Rendering video into custom memory buffers is considerably less 387 * efficient than rendering in a custom window as normal. 388 * 389 * For optimal perfomances, VLC media player renders into a custom window, and 390 * does not use this function and associated callbacks. It is <b>highly 391 * recommended</b> that other LibVLC-based application do likewise. 392 * To embed video in a window, use libvlc_media_player_set_xid() or equivalent 393 * depending on the operating system. 394 * 395 * If window embedding does not fit the application use case, then a custom 396 * LibVLC video output display plugin is required to maintain optimal video 397 * rendering performances. 398 * 399 * The following limitations affect performance: 400 * - Hardware video decoding acceleration will either be disabled completely, 401 * or require (relatively slow) copy from video/DSP memory to main memory. 402 * - Sub-pictures (subtitles, on-screen display, etc.) must be blent into the 403 * main picture by the CPU instead of the GPU. 404 * - Depending on the video format, pixel format conversion, picture scaling, 405 * cropping and/or picture re-orientation, must be performed by the CPU 406 * instead of the GPU. 407 * - Memory copying is required between LibVLC reference picture buffers and 408 * application buffers (between lock and unlock callbacks). 409 * 410 * \param mp the media player 411 * \param lock callback to lock video memory (must not be NULL) 412 * \param unlock callback to unlock video memory (or NULL if not needed) 413 * \param display callback to display video (or NULL if not needed) 414 * \param opaque private pointer for the three callbacks (as first parameter) 415 * \version LibVLC 1.1.1 or later 416 */ 417 LIBVLC_API 418 void libvlc_video_set_callbacks( libvlc_media_player_t *mp, 419 libvlc_video_lock_cb lock, 420 libvlc_video_unlock_cb unlock, 421 libvlc_video_display_cb display, 422 void *opaque ); 423 424 /** 425 * Set decoded video chroma and dimensions. 426 * This only works in combination with libvlc_video_set_callbacks(), 427 * and is mutually exclusive with libvlc_video_set_format_callbacks(). 428 * 429 * \param mp the media player 430 * \param chroma a four-characters string identifying the chroma 431 * (e.g. "RV32" or "YUYV") 432 * \param width pixel width 433 * \param height pixel height 434 * \param pitch line pitch (in bytes) 435 * \version LibVLC 1.1.1 or later 436 * \bug All pixel planes are expected to have the same pitch. 437 * To use the YCbCr color space with chrominance subsampling, 438 * consider using libvlc_video_set_format_callbacks() instead. 439 */ 440 LIBVLC_API 441 void libvlc_video_set_format( libvlc_media_player_t *mp, const char *chroma, 442 unsigned width, unsigned height, 443 unsigned pitch ); 444 445 /** 446 * Set decoded video chroma and dimensions. This only works in combination with 447 * libvlc_video_set_callbacks(). 448 * 449 * \param mp the media player 450 * \param setup callback to select the video format (cannot be NULL) 451 * \param cleanup callback to release any allocated resources (or NULL) 452 * \version LibVLC 2.0.0 or later 453 */ 454 LIBVLC_API 455 void libvlc_video_set_format_callbacks( libvlc_media_player_t *mp, 456 libvlc_video_format_cb setup, 457 libvlc_video_cleanup_cb cleanup ); 458 459 /** 460 * Set the NSView handler where the media player should render its video output. 461 * 462 * Use the vout called "macosx". 463 * 464 * The drawable is an NSObject that follow the VLCOpenGLVideoViewEmbedding 465 * protocol: 466 * 467 * @code{.m} 468 * \@protocol VLCOpenGLVideoViewEmbedding <NSObject> 469 * - (void)addVoutSubview:(NSView *)view; 470 * - (void)removeVoutSubview:(NSView *)view; 471 * \@end 472 * @endcode 473 * 474 * Or it can be an NSView object. 475 * 476 * If you want to use it along with Qt see the QMacCocoaViewContainer. Then 477 * the following code should work: 478 * @code{.mm} 479 * { 480 * NSView *video = [[NSView alloc] init]; 481 * QMacCocoaViewContainer *container = new QMacCocoaViewContainer(video, parent); 482 * libvlc_media_player_set_nsobject(mp, video); 483 * [video release]; 484 * } 485 * @endcode 486 * 487 * You can find a live example in VLCVideoView in VLCKit.framework. 488 * 489 * \param p_mi the Media Player 490 * \param drawable the drawable that is either an NSView or an object following 491 * the VLCOpenGLVideoViewEmbedding protocol. 492 */ 493 LIBVLC_API void libvlc_media_player_set_nsobject ( libvlc_media_player_t *p_mi, void * drawable ); 494 495 /** 496 * Get the NSView handler previously set with libvlc_media_player_set_nsobject(). 497 * 498 * \param p_mi the Media Player 499 * \return the NSView handler or 0 if none where set 500 */ 501 LIBVLC_API void * libvlc_media_player_get_nsobject ( libvlc_media_player_t *p_mi ); 502 503 /** 504 * Set an X Window System drawable where the media player should render its 505 * video output. The call takes effect when the playback starts. If it is 506 * already started, it might need to be stopped before changes apply. 507 * If LibVLC was built without X11 output support, then this function has no 508 * effects. 509 * 510 * By default, LibVLC will capture input events on the video rendering area. 511 * Use libvlc_video_set_mouse_input() and libvlc_video_set_key_input() to 512 * disable that and deliver events to the parent window / to the application 513 * instead. By design, the X11 protocol delivers input events to only one 514 * recipient. 515 * 516 * \warning 517 * The application must call the XInitThreads() function from Xlib before 518 * libvlc_new(), and before any call to XOpenDisplay() directly or via any 519 * other library. Failure to call XInitThreads() will seriously impede LibVLC 520 * performance. Calling XOpenDisplay() before XInitThreads() will eventually 521 * crash the process. That is a limitation of Xlib. 522 * 523 * \param p_mi media player 524 * \param drawable X11 window ID 525 * 526 * \note 527 * The specified identifier must correspond to an existing Input/Output class 528 * X11 window. Pixmaps are <b>not</b> currently supported. The default X11 529 * server is assumed, i.e. that specified in the DISPLAY environment variable. 530 * 531 * \warning 532 * LibVLC can deal with invalid X11 handle errors, however some display drivers 533 * (EGL, GLX, VA and/or VDPAU) can unfortunately not. Thus the window handle 534 * must remain valid until playback is stopped, otherwise the process may 535 * abort or crash. 536 * 537 * \bug 538 * No more than one window handle per media player instance can be specified. 539 * If the media has multiple simultaneously active video tracks, extra tracks 540 * will be rendered into external windows beyond the control of the 541 * application. 542 */ 543 LIBVLC_API void libvlc_media_player_set_xwindow(libvlc_media_player_t *p_mi, 544 uint32_t drawable); 545 546 /** 547 * Get the X Window System window identifier previously set with 548 * libvlc_media_player_set_xwindow(). Note that this will return the identifier 549 * even if VLC is not currently using it (for instance if it is playing an 550 * audio-only input). 551 * 552 * \param p_mi the Media Player 553 * \return an X window ID, or 0 if none where set. 554 */ 555 LIBVLC_API uint32_t libvlc_media_player_get_xwindow ( libvlc_media_player_t *p_mi ); 556 557 /** 558 * Set a Win32/Win64 API window handle (HWND) where the media player should 559 * render its video output. If LibVLC was built without Win32/Win64 API output 560 * support, then this has no effects. 561 * 562 * \param p_mi the Media Player 563 * \param drawable windows handle of the drawable 564 */ 565 LIBVLC_API void libvlc_media_player_set_hwnd ( libvlc_media_player_t *p_mi, void *drawable ); 566 567 /** 568 * Get the Windows API window handle (HWND) previously set with 569 * libvlc_media_player_set_hwnd(). The handle will be returned even if LibVLC 570 * is not currently outputting any video to it. 571 * 572 * \param p_mi the Media Player 573 * \return a window handle or NULL if there are none. 574 */ 575 LIBVLC_API void *libvlc_media_player_get_hwnd ( libvlc_media_player_t *p_mi ); 576 577 /** 578 * Set the android context. 579 * 580 * \version LibVLC 3.0.0 and later. 581 * 582 * \param p_mi the media player 583 * \param p_awindow_handler org.videolan.libvlc.AWindow jobject owned by the 584 * org.videolan.libvlc.MediaPlayer class from the libvlc-android project. 585 */ 586 LIBVLC_API void libvlc_media_player_set_android_context( libvlc_media_player_t *p_mi, 587 void *p_awindow_handler ); 588 589 /** 590 * Set the EFL Evas Object. 591 * 592 * \version LibVLC 3.0.0 and later. 593 * 594 * \param p_mi the media player 595 * \param p_evas_object a valid EFL Evas Object (Evas_Object) 596 * \return -1 if an error was detected, 0 otherwise. 597 */ 598 LIBVLC_API int libvlc_media_player_set_evas_object( libvlc_media_player_t *p_mi, 599 void *p_evas_object ); 600 601 602 /** 603 * Callback prototype for audio playback. 604 * 605 * The LibVLC media player decodes and post-processes the audio signal 606 * asynchronously (in an internal thread). Whenever audio samples are ready 607 * to be queued to the output, this callback is invoked. 608 * 609 * The number of samples provided per invocation may depend on the file format, 610 * the audio coding algorithm, the decoder plug-in, the post-processing 611 * filters and timing. Application must not assume a certain number of samples. 612 * 613 * The exact format of audio samples is determined by libvlc_audio_set_format() 614 * or libvlc_audio_set_format_callbacks() as is the channels layout. 615 * 616 * Note that the number of samples is per channel. For instance, if the audio 617 * track sampling rate is 48000 Hz, then 1200 samples represent 25 milliseconds 618 * of audio signal - regardless of the number of audio channels. 619 * 620 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN] 621 * \param samples pointer to a table of audio samples to play back [IN] 622 * \param count number of audio samples to play back 623 * \param pts expected play time stamp (see libvlc_delay()) 624 */ 625 typedef void (*libvlc_audio_play_cb)(void *data, const void *samples, 626 unsigned count, int64_t pts); 627 628 /** 629 * Callback prototype for audio pause. 630 * 631 * LibVLC invokes this callback to pause audio playback. 632 * 633 * \note The pause callback is never called if the audio is already paused. 634 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN] 635 * \param pts time stamp of the pause request (should be elapsed already) 636 */ 637 typedef void (*libvlc_audio_pause_cb)(void *data, int64_t pts); 638 639 /** 640 * Callback prototype for audio resumption. 641 * 642 * LibVLC invokes this callback to resume audio playback after it was 643 * previously paused. 644 * 645 * \note The resume callback is never called if the audio is not paused. 646 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN] 647 * \param pts time stamp of the resumption request (should be elapsed already) 648 */ 649 typedef void (*libvlc_audio_resume_cb)(void *data, int64_t pts); 650 651 /** 652 * Callback prototype for audio buffer flush. 653 * 654 * LibVLC invokes this callback if it needs to discard all pending buffers and 655 * stop playback as soon as possible. This typically occurs when the media is 656 * stopped. 657 * 658 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN] 659 */ 660 typedef void (*libvlc_audio_flush_cb)(void *data, int64_t pts); 661 662 /** 663 * Callback prototype for audio buffer drain. 664 * 665 * LibVLC may invoke this callback when the decoded audio track is ending. 666 * There will be no further decoded samples for the track, but playback should 667 * nevertheless continue until all already pending buffers are rendered. 668 * 669 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN] 670 */ 671 typedef void (*libvlc_audio_drain_cb)(void *data); 672 673 /** 674 * Callback prototype for audio volume change. 675 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN] 676 * \param volume software volume (1. = nominal, 0. = mute) 677 * \param mute muted flag 678 */ 679 typedef void (*libvlc_audio_set_volume_cb)(void *data, 680 float volume, bool mute); 681 682 /** 683 * Sets callbacks and private data for decoded audio. 684 * 685 * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks() 686 * to configure the decoded audio format. 687 * 688 * \note The audio callbacks override any other audio output mechanism. 689 * If the callbacks are set, LibVLC will <b>not</b> output audio in any way. 690 * 691 * \param mp the media player 692 * \param play callback to play audio samples (must not be NULL) 693 * \param pause callback to pause playback (or NULL to ignore) 694 * \param resume callback to resume playback (or NULL to ignore) 695 * \param flush callback to flush audio buffers (or NULL to ignore) 696 * \param drain callback to drain audio buffers (or NULL to ignore) 697 * \param opaque private pointer for the audio callbacks (as first parameter) 698 * \version LibVLC 2.0.0 or later 699 */ 700 LIBVLC_API 701 void libvlc_audio_set_callbacks( libvlc_media_player_t *mp, 702 libvlc_audio_play_cb play, 703 libvlc_audio_pause_cb pause, 704 libvlc_audio_resume_cb resume, 705 libvlc_audio_flush_cb flush, 706 libvlc_audio_drain_cb drain, 707 void *opaque ); 708 709 /** 710 * Set callbacks and private data for decoded audio. This only works in 711 * combination with libvlc_audio_set_callbacks(). 712 * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks() 713 * to configure the decoded audio format. 714 * 715 * \param mp the media player 716 * \param set_volume callback to apply audio volume, 717 * or NULL to apply volume in software 718 * \version LibVLC 2.0.0 or later 719 */ 720 LIBVLC_API 721 void libvlc_audio_set_volume_callback( libvlc_media_player_t *mp, 722 libvlc_audio_set_volume_cb set_volume ); 723 724 /** 725 * Callback prototype to setup the audio playback. 726 * 727 * This is called when the media player needs to create a new audio output. 728 * \param opaque pointer to the data pointer passed to 729 * libvlc_audio_set_callbacks() [IN/OUT] 730 * \param format 4 bytes sample format [IN/OUT] 731 * \param rate sample rate [IN/OUT] 732 * \param channels channels count [IN/OUT] 733 * \return 0 on success, anything else to skip audio playback 734 */ 735 typedef int (*libvlc_audio_setup_cb)(void **data, char *format, unsigned *rate, 736 unsigned *channels); 737 738 /** 739 * Callback prototype for audio playback cleanup. 740 * 741 * This is called when the media player no longer needs an audio output. 742 * \param opaque data pointer as passed to libvlc_audio_set_callbacks() [IN] 743 */ 744 typedef void (*libvlc_audio_cleanup_cb)(void *data); 745 746 /** 747 * Sets decoded audio format via callbacks. 748 * 749 * This only works in combination with libvlc_audio_set_callbacks(). 750 * 751 * \param mp the media player 752 * \param setup callback to select the audio format (cannot be NULL) 753 * \param cleanup callback to release any allocated resources (or NULL) 754 * \version LibVLC 2.0.0 or later 755 */ 756 LIBVLC_API 757 void libvlc_audio_set_format_callbacks( libvlc_media_player_t *mp, 758 libvlc_audio_setup_cb setup, 759 libvlc_audio_cleanup_cb cleanup ); 760 761 /** 762 * Sets a fixed decoded audio format. 763 * 764 * This only works in combination with libvlc_audio_set_callbacks(), 765 * and is mutually exclusive with libvlc_audio_set_format_callbacks(). 766 * 767 * \param mp the media player 768 * \param format a four-characters string identifying the sample format 769 * (e.g. "S16N" or "f32l") 770 * \param rate sample rate (expressed in Hz) 771 * \param channels channels count 772 * \version LibVLC 2.0.0 or later 773 */ 774 LIBVLC_API 775 void libvlc_audio_set_format( libvlc_media_player_t *mp, const char *format, 776 unsigned rate, unsigned channels ); 777 778 /** \bug This might go away ... to be replaced by a broader system */ 779 780 /** 781 * Get the current movie length (in ms). 782 * 783 * \param p_mi the Media Player 784 * \return the movie length (in ms), or -1 if there is no media. 785 */ 786 LIBVLC_API libvlc_time_t libvlc_media_player_get_length( libvlc_media_player_t *p_mi ); 787 788 /** 789 * Get the current movie time (in ms). 790 * 791 * \param p_mi the Media Player 792 * \return the movie time (in ms), or -1 if there is no media. 793 */ 794 LIBVLC_API libvlc_time_t libvlc_media_player_get_time( libvlc_media_player_t *p_mi ); 795 796 /** 797 * Set the movie time (in ms). This has no effect if no media is being played. 798 * Not all formats and protocols support this. 799 * 800 * \param p_mi the Media Player 801 * \param i_time the movie time (in ms). 802 */ 803 LIBVLC_API void libvlc_media_player_set_time( libvlc_media_player_t *p_mi, libvlc_time_t i_time ); 804 805 /** 806 * Get movie position as percentage between 0.0 and 1.0. 807 * 808 * \param p_mi the Media Player 809 * \return movie position, or -1. in case of error 810 */ 811 LIBVLC_API float libvlc_media_player_get_position( libvlc_media_player_t *p_mi ); 812 813 /** 814 * Set movie position as percentage between 0.0 and 1.0. 815 * This has no effect if playback is not enabled. 816 * This might not work depending on the underlying input format and protocol. 817 * 818 * \param p_mi the Media Player 819 * \param f_pos the position 820 */ 821 LIBVLC_API void libvlc_media_player_set_position( libvlc_media_player_t *p_mi, float f_pos ); 822 823 /** 824 * Set movie chapter (if applicable). 825 * 826 * \param p_mi the Media Player 827 * \param i_chapter chapter number to play 828 */ 829 LIBVLC_API void libvlc_media_player_set_chapter( libvlc_media_player_t *p_mi, int i_chapter ); 830 831 /** 832 * Get movie chapter. 833 * 834 * \param p_mi the Media Player 835 * \return chapter number currently playing, or -1 if there is no media. 836 */ 837 LIBVLC_API int libvlc_media_player_get_chapter( libvlc_media_player_t *p_mi ); 838 839 /** 840 * Get movie chapter count 841 * 842 * \param p_mi the Media Player 843 * \return number of chapters in movie, or -1. 844 */ 845 LIBVLC_API int libvlc_media_player_get_chapter_count( libvlc_media_player_t *p_mi ); 846 847 /** 848 * Is the player able to play 849 * 850 * \param p_mi the Media Player 851 * \return boolean 852 * 853 * \libvlc_return_bool 854 */ 855 LIBVLC_API int libvlc_media_player_will_play( libvlc_media_player_t *p_mi ); 856 857 /** 858 * Get title chapter count 859 * 860 * \param p_mi the Media Player 861 * \param i_title title 862 * \return number of chapters in title, or -1 863 */ 864 LIBVLC_API int libvlc_media_player_get_chapter_count_for_title( 865 libvlc_media_player_t *p_mi, int i_title ); 866 867 /** 868 * Set movie title 869 * 870 * \param p_mi the Media Player 871 * \param i_title title number to play 872 */ 873 LIBVLC_API void libvlc_media_player_set_title( libvlc_media_player_t *p_mi, int i_title ); 874 875 /** 876 * Get movie title 877 * 878 * \param p_mi the Media Player 879 * \return title number currently playing, or -1 880 */ 881 LIBVLC_API int libvlc_media_player_get_title( libvlc_media_player_t *p_mi ); 882 883 /** 884 * Get movie title count 885 * 886 * \param p_mi the Media Player 887 * \return title number count, or -1 888 */ 889 LIBVLC_API int libvlc_media_player_get_title_count( libvlc_media_player_t *p_mi ); 890 891 /** 892 * Set previous chapter (if applicable) 893 * 894 * \param p_mi the Media Player 895 */ 896 LIBVLC_API void libvlc_media_player_previous_chapter( libvlc_media_player_t *p_mi ); 897 898 /** 899 * Set next chapter (if applicable) 900 * 901 * \param p_mi the Media Player 902 */ 903 LIBVLC_API void libvlc_media_player_next_chapter( libvlc_media_player_t *p_mi ); 904 905 /** 906 * Get the requested movie play rate. 907 * @warning Depending on the underlying media, the requested rate may be 908 * different from the real playback rate. 909 * 910 * \param p_mi the Media Player 911 * \return movie play rate 912 */ 913 LIBVLC_API float libvlc_media_player_get_rate( libvlc_media_player_t *p_mi ); 914 915 /** 916 * Set movie play rate 917 * 918 * \param p_mi the Media Player 919 * \param rate movie play rate to set 920 * \return -1 if an error was detected, 0 otherwise (but even then, it might 921 * not actually work depending on the underlying media protocol) 922 */ 923 LIBVLC_API int libvlc_media_player_set_rate( libvlc_media_player_t *p_mi, float rate ); 924 925 /** 926 * Get current movie state 927 * 928 * \param p_mi the Media Player 929 * \return the current state of the media player (playing, paused, ...) \see libvlc_state_t 930 */ 931 LIBVLC_API libvlc_state_t libvlc_media_player_get_state( libvlc_media_player_t *p_mi ); 932 933 /** 934 * How many video outputs does this media player have? 935 * 936 * \param p_mi the media player 937 * \return the number of video outputs 938 */ 939 LIBVLC_API unsigned libvlc_media_player_has_vout( libvlc_media_player_t *p_mi ); 940 941 /** 942 * Is this media player seekable? 943 * 944 * \param p_mi the media player 945 * \return true if the media player can seek 946 * 947 * \libvlc_return_bool 948 */ 949 LIBVLC_API int libvlc_media_player_is_seekable( libvlc_media_player_t *p_mi ); 950 951 /** 952 * Can this media player be paused? 953 * 954 * \param p_mi the media player 955 * \return true if the media player can pause 956 * 957 * \libvlc_return_bool 958 */ 959 LIBVLC_API int libvlc_media_player_can_pause( libvlc_media_player_t *p_mi ); 960 961 /** 962 * Check if the current program is scrambled 963 * 964 * \param p_mi the media player 965 * \return true if the current program is scrambled 966 * 967 * \libvlc_return_bool 968 * \version LibVLC 2.2.0 or later 969 */ 970 LIBVLC_API int libvlc_media_player_program_scrambled( libvlc_media_player_t *p_mi ); 971 972 /** 973 * Display the next frame (if supported) 974 * 975 * \param p_mi the media player 976 */ 977 LIBVLC_API void libvlc_media_player_next_frame( libvlc_media_player_t *p_mi ); 978 979 /** 980 * Navigate through DVD Menu 981 * 982 * \param p_mi the Media Player 983 * \param navigate the Navigation mode 984 * \version libVLC 2.0.0 or later 985 */ 986 LIBVLC_API void libvlc_media_player_navigate( libvlc_media_player_t* p_mi, 987 unsigned navigate ); 988 989 /** 990 * Set if, and how, the video title will be shown when media is played. 991 * 992 * \param p_mi the media player 993 * \param position position at which to display the title, or libvlc_position_disable to prevent the title from being displayed 994 * \param timeout title display timeout in milliseconds (ignored if libvlc_position_disable) 995 * \version libVLC 2.1.0 or later 996 */ 997 LIBVLC_API void libvlc_media_player_set_video_title_display( libvlc_media_player_t *p_mi, libvlc_position_t position, unsigned int timeout ); 998 999 /** 1000 * Add a slave to the current media player. 1001 * 1002 * \note If the player is playing, the slave will be added directly. This call 1003 * will also update the slave list of the attached libvlc_media_t. 1004 * 1005 * \version LibVLC 3.0.0 and later. 1006 * 1007 * \see libvlc_media_slaves_add 1008 * 1009 * \param p_mi the media player 1010 * \param i_type subtitle or audio 1011 * \param psz_uri Uri of the slave (should contain a valid scheme). 1012 * \param b_select True if this slave should be selected when it's loaded 1013 * 1014 * \return 0 on success, -1 on error. 1015 */ 1016 LIBVLC_API 1017 int libvlc_media_player_add_slave( libvlc_media_player_t *p_mi, 1018 libvlc_media_slave_type_t i_type, 1019 const char *psz_uri, bool b_select ); 1020 1021 /** 1022 * Release (free) libvlc_track_description_t 1023 * 1024 * \param p_track_description the structure to release 1025 */ 1026 LIBVLC_API void libvlc_track_description_list_release( libvlc_track_description_t *p_track_description ); 1027 1028 /** \defgroup libvlc_video LibVLC video controls 1029 * @{ 1030 */ 1031 1032 /** 1033 * Toggle fullscreen status on non-embedded video outputs. 1034 * 1035 * @warning The same limitations applies to this function 1036 * as to libvlc_set_fullscreen(). 1037 * 1038 * \param p_mi the media player 1039 */ 1040 LIBVLC_API void libvlc_toggle_fullscreen( libvlc_media_player_t *p_mi ); 1041 1042 /** 1043 * Enable or disable fullscreen. 1044 * 1045 * @warning With most window managers, only a top-level windows can be in 1046 * full-screen mode. Hence, this function will not operate properly if 1047 * libvlc_media_player_set_xwindow() was used to embed the video in a 1048 * non-top-level window. In that case, the embedding window must be reparented 1049 * to the root window <b>before</b> fullscreen mode is enabled. You will want 1050 * to reparent it back to its normal parent when disabling fullscreen. 1051 * 1052 * \param p_mi the media player 1053 * \param b_fullscreen boolean for fullscreen status 1054 */ 1055 LIBVLC_API void libvlc_set_fullscreen( libvlc_media_player_t *p_mi, int b_fullscreen ); 1056 1057 /** 1058 * Get current fullscreen status. 1059 * 1060 * \param p_mi the media player 1061 * \return the fullscreen status (boolean) 1062 * 1063 * \libvlc_return_bool 1064 */ 1065 LIBVLC_API int libvlc_get_fullscreen( libvlc_media_player_t *p_mi ); 1066 1067 /** 1068 * Enable or disable key press events handling, according to the LibVLC hotkeys 1069 * configuration. By default and for historical reasons, keyboard events are 1070 * handled by the LibVLC video widget. 1071 * 1072 * \note On X11, there can be only one subscriber for key press and mouse 1073 * click events per window. If your application has subscribed to those events 1074 * for the X window ID of the video widget, then LibVLC will not be able to 1075 * handle key presses and mouse clicks in any case. 1076 * 1077 * \warning This function is only implemented for X11 and Win32 at the moment. 1078 * 1079 * \param p_mi the media player 1080 * \param on true to handle key press events, false to ignore them. 1081 */ 1082 LIBVLC_API 1083 void libvlc_video_set_key_input( libvlc_media_player_t *p_mi, unsigned on ); 1084 1085 /** 1086 * Enable or disable mouse click events handling. By default, those events are 1087 * handled. This is needed for DVD menus to work, as well as a few video 1088 * filters such as "puzzle". 1089 * 1090 * \see libvlc_video_set_key_input(). 1091 * 1092 * \warning This function is only implemented for X11 and Win32 at the moment. 1093 * 1094 * \param p_mi the media player 1095 * \param on true to handle mouse click events, false to ignore them. 1096 */ 1097 LIBVLC_API 1098 void libvlc_video_set_mouse_input( libvlc_media_player_t *p_mi, unsigned on ); 1099 1100 /** 1101 * Get the pixel dimensions of a video. 1102 * 1103 * \param p_mi media player 1104 * \param num number of the video (starting from, and most commonly 0) 1105 * \param px pointer to get the pixel width [OUT] 1106 * \param py pointer to get the pixel height [OUT] 1107 * \return 0 on success, -1 if the specified video does not exist 1108 */ 1109 LIBVLC_API 1110 int libvlc_video_get_size( libvlc_media_player_t *p_mi, unsigned num, 1111 unsigned *px, unsigned *py ); 1112 1113 /** 1114 * Get the mouse pointer coordinates over a video. 1115 * Coordinates are expressed in terms of the decoded video resolution, 1116 * <b>not</b> in terms of pixels on the screen/viewport (to get the latter, 1117 * you can query your windowing system directly). 1118 * 1119 * Either of the coordinates may be negative or larger than the corresponding 1120 * dimension of the video, if the cursor is outside the rendering area. 1121 * 1122 * @warning The coordinates may be out-of-date if the pointer is not located 1123 * on the video rendering area. LibVLC does not track the pointer if it is 1124 * outside of the video widget. 1125 * 1126 * @note LibVLC does not support multiple pointers (it does of course support 1127 * multiple input devices sharing the same pointer) at the moment. 1128 * 1129 * \param p_mi media player 1130 * \param num number of the video (starting from, and most commonly 0) 1131 * \param px pointer to get the abscissa [OUT] 1132 * \param py pointer to get the ordinate [OUT] 1133 * \return 0 on success, -1 if the specified video does not exist 1134 */ 1135 LIBVLC_API 1136 int libvlc_video_get_cursor( libvlc_media_player_t *p_mi, unsigned num, 1137 int *px, int *py ); 1138 1139 /** 1140 * Get the current video scaling factor. 1141 * See also libvlc_video_set_scale(). 1142 * 1143 * \param p_mi the media player 1144 * \return the currently configured zoom factor, or 0. if the video is set 1145 * to fit to the output window/drawable automatically. 1146 */ 1147 LIBVLC_API float libvlc_video_get_scale( libvlc_media_player_t *p_mi ); 1148 1149 /** 1150 * Set the video scaling factor. That is the ratio of the number of pixels on 1151 * screen to the number of pixels in the original decoded video in each 1152 * dimension. Zero is a special value; it will adjust the video to the output 1153 * window/drawable (in windowed mode) or the entire screen. 1154 * 1155 * Note that not all video outputs support scaling. 1156 * 1157 * \param p_mi the media player 1158 * \param f_factor the scaling factor, or zero 1159 */ 1160 LIBVLC_API void libvlc_video_set_scale( libvlc_media_player_t *p_mi, float f_factor ); 1161 1162 /** 1163 * Get current video aspect ratio. 1164 * 1165 * \param p_mi the media player 1166 * \return the video aspect ratio or NULL if unspecified 1167 * (the result must be released with free() or libvlc_free()). 1168 */ 1169 LIBVLC_API char *libvlc_video_get_aspect_ratio( libvlc_media_player_t *p_mi ); 1170 1171 /** 1172 * Set new video aspect ratio. 1173 * 1174 * \param p_mi the media player 1175 * \param psz_aspect new video aspect-ratio or NULL to reset to default 1176 * \note Invalid aspect ratios are ignored. 1177 */ 1178 LIBVLC_API void libvlc_video_set_aspect_ratio( libvlc_media_player_t *p_mi, const char *psz_aspect ); 1179 1180 /** 1181 * Create a video viewpoint structure. 1182 * 1183 * \version LibVLC 3.0.0 and later 1184 * 1185 * \return video viewpoint or NULL 1186 * (the result must be released with free() or libvlc_free()). 1187 */ 1188 LIBVLC_API libvlc_video_viewpoint_t *libvlc_video_new_viewpoint(void); 1189 1190 /** 1191 * Update the video viewpoint information. 1192 * 1193 * \note It is safe to call this function before the media player is started. 1194 * 1195 * \version LibVLC 3.0.0 and later 1196 * 1197 * \param p_mi the media player 1198 * \param p_viewpoint video viewpoint allocated via libvlc_video_new_viewpoint() 1199 * \param b_absolute if true replace the old viewpoint with the new one. If 1200 * false, increase/decrease it. 1201 * \return -1 in case of error, 0 otherwise 1202 * 1203 * \note the values are set asynchronously, it will be used by the next frame displayed. 1204 */ 1205 LIBVLC_API int libvlc_video_update_viewpoint( libvlc_media_player_t *p_mi, 1206 const libvlc_video_viewpoint_t *p_viewpoint, 1207 bool b_absolute); 1208 1209 /** 1210 * Get current video subtitle. 1211 * 1212 * \param p_mi the media player 1213 * \return the video subtitle selected, or -1 if none 1214 */ 1215 LIBVLC_API int libvlc_video_get_spu( libvlc_media_player_t *p_mi ); 1216 1217 /** 1218 * Get the number of available video subtitles. 1219 * 1220 * \param p_mi the media player 1221 * \return the number of available video subtitles 1222 */ 1223 LIBVLC_API int libvlc_video_get_spu_count( libvlc_media_player_t *p_mi ); 1224 1225 /** 1226 * Get the description of available video subtitles. 1227 * 1228 * \param p_mi the media player 1229 * \return list containing description of available video subtitles. 1230 * It must be freed with libvlc_track_description_list_release() 1231 */ 1232 LIBVLC_API libvlc_track_description_t * 1233 libvlc_video_get_spu_description( libvlc_media_player_t *p_mi ); 1234 1235 /** 1236 * Set new video subtitle. 1237 * 1238 * \param p_mi the media player 1239 * \param i_spu video subtitle track to select (i_id from track description) 1240 * \return 0 on success, -1 if out of range 1241 */ 1242 LIBVLC_API int libvlc_video_set_spu( libvlc_media_player_t *p_mi, int i_spu ); 1243 1244 /** 1245 * Get the current subtitle delay. Positive values means subtitles are being 1246 * displayed later, negative values earlier. 1247 * 1248 * \param p_mi media player 1249 * \return time (in microseconds) the display of subtitles is being delayed 1250 * \version LibVLC 2.0.0 or later 1251 */ 1252 LIBVLC_API int64_t libvlc_video_get_spu_delay( libvlc_media_player_t *p_mi ); 1253 1254 /** 1255 * Set the subtitle delay. This affects the timing of when the subtitle will 1256 * be displayed. Positive values result in subtitles being displayed later, 1257 * while negative values will result in subtitles being displayed earlier. 1258 * 1259 * The subtitle delay will be reset to zero each time the media changes. 1260 * 1261 * \param p_mi media player 1262 * \param i_delay time (in microseconds) the display of subtitles should be delayed 1263 * \return 0 on success, -1 on error 1264 * \version LibVLC 2.0.0 or later 1265 */ 1266 LIBVLC_API int libvlc_video_set_spu_delay( libvlc_media_player_t *p_mi, int64_t i_delay ); 1267 1268 /** 1269 * Get the full description of available titles 1270 * 1271 * \version LibVLC 3.0.0 and later. 1272 * 1273 * \param p_mi the media player 1274 * \param titles address to store an allocated array of title descriptions 1275 * descriptions (must be freed with libvlc_title_descriptions_release() 1276 * by the caller) [OUT] 1277 * 1278 * \return the number of titles (-1 on error) 1279 */ 1280 LIBVLC_API int libvlc_media_player_get_full_title_descriptions( libvlc_media_player_t *p_mi, 1281 libvlc_title_description_t ***titles ); 1282 1283 /** 1284 * Release a title description 1285 * 1286 * \version LibVLC 3.0.0 and later 1287 * 1288 * \param p_titles title description array to release 1289 * \param i_count number of title descriptions to release 1290 */ 1291 LIBVLC_API 1292 void libvlc_title_descriptions_release( libvlc_title_description_t **p_titles, 1293 unsigned i_count ); 1294 1295 /** 1296 * Get the full description of available chapters 1297 * 1298 * \version LibVLC 3.0.0 and later. 1299 * 1300 * \param p_mi the media player 1301 * \param i_chapters_of_title index of the title to query for chapters (uses current title if set to -1) 1302 * \param pp_chapters address to store an allocated array of chapter descriptions 1303 * descriptions (must be freed with libvlc_chapter_descriptions_release() 1304 * by the caller) [OUT] 1305 * 1306 * \return the number of chapters (-1 on error) 1307 */ 1308 LIBVLC_API int libvlc_media_player_get_full_chapter_descriptions( libvlc_media_player_t *p_mi, 1309 int i_chapters_of_title, 1310 libvlc_chapter_description_t *** pp_chapters ); 1311 1312 /** 1313 * Release a chapter description 1314 * 1315 * \version LibVLC 3.0.0 and later 1316 * 1317 * \param p_chapters chapter description array to release 1318 * \param i_count number of chapter descriptions to release 1319 */ 1320 LIBVLC_API 1321 void libvlc_chapter_descriptions_release( libvlc_chapter_description_t **p_chapters, 1322 unsigned i_count ); 1323 1324 /** 1325 * Get current crop filter geometry. 1326 * 1327 * \param p_mi the media player 1328 * \return the crop filter geometry or NULL if unset 1329 */ 1330 LIBVLC_API char *libvlc_video_get_crop_geometry( libvlc_media_player_t *p_mi ); 1331 1332 /** 1333 * Set new crop filter geometry. 1334 * 1335 * \param p_mi the media player 1336 * \param psz_geometry new crop filter geometry (NULL to unset) 1337 */ 1338 LIBVLC_API 1339 void libvlc_video_set_crop_geometry( libvlc_media_player_t *p_mi, const char *psz_geometry ); 1340 1341 /** 1342 * Get current teletext page requested or 0 if it's disabled. 1343 * 1344 * Teletext is disabled by default, call libvlc_video_set_teletext() to enable 1345 * it. 1346 * 1347 * \param p_mi the media player 1348 * \return the current teletext page requested. 1349 */ 1350 LIBVLC_API int libvlc_video_get_teletext( libvlc_media_player_t *p_mi ); 1351 1352 /** 1353 * Set new teletext page to retrieve. 1354 * 1355 * This function can also be used to send a teletext key. 1356 * 1357 * \param p_mi the media player 1358 * \param i_page teletex page number requested. This value can be 0 to disable 1359 * teletext, a number in the range ]0;1000[ to show the requested page, or a 1360 * \ref libvlc_teletext_key_t. 100 is the default teletext page. 1361 */ 1362 LIBVLC_API void libvlc_video_set_teletext( libvlc_media_player_t *p_mi, int i_page ); 1363 1364 /** 1365 * Get number of available video tracks. 1366 * 1367 * \param p_mi media player 1368 * \return the number of available video tracks (int) 1369 */ 1370 LIBVLC_API int libvlc_video_get_track_count( libvlc_media_player_t *p_mi ); 1371 1372 /** 1373 * Get the description of available video tracks. 1374 * 1375 * \param p_mi media player 1376 * \return list with description of available video tracks, or NULL on error. 1377 * It must be freed with libvlc_track_description_list_release() 1378 */ 1379 LIBVLC_API libvlc_track_description_t * 1380 libvlc_video_get_track_description( libvlc_media_player_t *p_mi ); 1381 1382 /** 1383 * Get current video track. 1384 * 1385 * \param p_mi media player 1386 * \return the video track ID (int) or -1 if no active input 1387 */ 1388 LIBVLC_API int libvlc_video_get_track( libvlc_media_player_t *p_mi ); 1389 1390 /** 1391 * Set video track. 1392 * 1393 * \param p_mi media player 1394 * \param i_track the track ID (i_id field from track description) 1395 * \return 0 on success, -1 if out of range 1396 */ 1397 LIBVLC_API 1398 int libvlc_video_set_track( libvlc_media_player_t *p_mi, int i_track ); 1399 1400 /** 1401 * Take a snapshot of the current video window. 1402 * 1403 * If i_width AND i_height is 0, original size is used. 1404 * If i_width XOR i_height is 0, original aspect-ratio is preserved. 1405 * 1406 * \param p_mi media player instance 1407 * \param num number of video output (typically 0 for the first/only one) 1408 * \param psz_filepath the path of a file or a folder to save the screenshot into 1409 * \param i_width the snapshot's width 1410 * \param i_height the snapshot's height 1411 * \return 0 on success, -1 if the video was not found 1412 */ 1413 LIBVLC_API 1414 int libvlc_video_take_snapshot( libvlc_media_player_t *p_mi, unsigned num, 1415 const char *psz_filepath, unsigned int i_width, 1416 unsigned int i_height ); 1417 1418 /** 1419 * Enable or disable deinterlace filter 1420 * 1421 * \param p_mi libvlc media player 1422 * \param psz_mode type of deinterlace filter, NULL to disable 1423 */ 1424 LIBVLC_API void libvlc_video_set_deinterlace( libvlc_media_player_t *p_mi, 1425 const char *psz_mode ); 1426 1427 /** 1428 * Get an integer marquee option value 1429 * 1430 * \param p_mi libvlc media player 1431 * \param option marq option to get \see libvlc_video_marquee_int_option_t 1432 */ 1433 LIBVLC_API int libvlc_video_get_marquee_int( libvlc_media_player_t *p_mi, 1434 unsigned option ); 1435 1436 /** 1437 * Get a string marquee option value 1438 * 1439 * \param p_mi libvlc media player 1440 * \param option marq option to get \see libvlc_video_marquee_string_option_t 1441 */ 1442 LIBVLC_API char *libvlc_video_get_marquee_string( libvlc_media_player_t *p_mi, 1443 unsigned option ); 1444 1445 /** 1446 * Enable, disable or set an integer marquee option 1447 * 1448 * Setting libvlc_marquee_Enable has the side effect of enabling (arg !0) 1449 * or disabling (arg 0) the marq filter. 1450 * 1451 * \param p_mi libvlc media player 1452 * \param option marq option to set \see libvlc_video_marquee_int_option_t 1453 * \param i_val marq option value 1454 */ 1455 LIBVLC_API void libvlc_video_set_marquee_int( libvlc_media_player_t *p_mi, 1456 unsigned option, int i_val ); 1457 1458 /** 1459 * Set a marquee string option 1460 * 1461 * \param p_mi libvlc media player 1462 * \param option marq option to set \see libvlc_video_marquee_string_option_t 1463 * \param psz_text marq option value 1464 */ 1465 LIBVLC_API void libvlc_video_set_marquee_string( libvlc_media_player_t *p_mi, 1466 unsigned option, const char *psz_text ); 1467 1468 /** option values for libvlc_video_{get,set}_logo_{int,string} */ 1469 enum libvlc_video_logo_option_t { 1470 libvlc_logo_enable, 1471 libvlc_logo_file, /**< string argument, "file,d,t;file,d,t;..." */ 1472 libvlc_logo_x, 1473 libvlc_logo_y, 1474 libvlc_logo_delay, 1475 libvlc_logo_repeat, 1476 libvlc_logo_opacity, 1477 libvlc_logo_position 1478 }; 1479 1480 /** 1481 * Get integer logo option. 1482 * 1483 * \param p_mi libvlc media player instance 1484 * \param option logo option to get, values of libvlc_video_logo_option_t 1485 */ 1486 LIBVLC_API int libvlc_video_get_logo_int( libvlc_media_player_t *p_mi, 1487 unsigned option ); 1488 1489 /** 1490 * Set logo option as integer. Options that take a different type value 1491 * are ignored. 1492 * Passing libvlc_logo_enable as option value has the side effect of 1493 * starting (arg !0) or stopping (arg 0) the logo filter. 1494 * 1495 * \param p_mi libvlc media player instance 1496 * \param option logo option to set, values of libvlc_video_logo_option_t 1497 * \param value logo option value 1498 */ 1499 LIBVLC_API void libvlc_video_set_logo_int( libvlc_media_player_t *p_mi, 1500 unsigned option, int value ); 1501 1502 /** 1503 * Set logo option as string. Options that take a different type value 1504 * are ignored. 1505 * 1506 * \param p_mi libvlc media player instance 1507 * \param option logo option to set, values of libvlc_video_logo_option_t 1508 * \param psz_value logo option value 1509 */ 1510 LIBVLC_API void libvlc_video_set_logo_string( libvlc_media_player_t *p_mi, 1511 unsigned option, const char *psz_value ); 1512 1513 1514 /** option values for libvlc_video_{get,set}_adjust_{int,float,bool} */ 1515 enum libvlc_video_adjust_option_t { 1516 libvlc_adjust_Enable = 0, 1517 libvlc_adjust_Contrast, 1518 libvlc_adjust_Brightness, 1519 libvlc_adjust_Hue, 1520 libvlc_adjust_Saturation, 1521 libvlc_adjust_Gamma 1522 }; 1523 1524 /** 1525 * Get integer adjust option. 1526 * 1527 * \param p_mi libvlc media player instance 1528 * \param option adjust option to get, values of libvlc_video_adjust_option_t 1529 * \version LibVLC 1.1.1 and later. 1530 */ 1531 LIBVLC_API int libvlc_video_get_adjust_int( libvlc_media_player_t *p_mi, 1532 unsigned option ); 1533 1534 /** 1535 * Set adjust option as integer. Options that take a different type value 1536 * are ignored. 1537 * Passing libvlc_adjust_enable as option value has the side effect of 1538 * starting (arg !0) or stopping (arg 0) the adjust filter. 1539 * 1540 * \param p_mi libvlc media player instance 1541 * \param option adust option to set, values of libvlc_video_adjust_option_t 1542 * \param value adjust option value 1543 * \version LibVLC 1.1.1 and later. 1544 */ 1545 LIBVLC_API void libvlc_video_set_adjust_int( libvlc_media_player_t *p_mi, 1546 unsigned option, int value ); 1547 1548 /** 1549 * Get float adjust option. 1550 * 1551 * \param p_mi libvlc media player instance 1552 * \param option adjust option to get, values of libvlc_video_adjust_option_t 1553 * \version LibVLC 1.1.1 and later. 1554 */ 1555 LIBVLC_API float libvlc_video_get_adjust_float( libvlc_media_player_t *p_mi, 1556 unsigned option ); 1557 1558 /** 1559 * Set adjust option as float. Options that take a different type value 1560 * are ignored. 1561 * 1562 * \param p_mi libvlc media player instance 1563 * \param option adust option to set, values of libvlc_video_adjust_option_t 1564 * \param value adjust option value 1565 * \version LibVLC 1.1.1 and later. 1566 */ 1567 LIBVLC_API void libvlc_video_set_adjust_float( libvlc_media_player_t *p_mi, 1568 unsigned option, float value ); 1569 1570 /** @} video */ 1571 1572 /** \defgroup libvlc_audio LibVLC audio controls 1573 * @{ 1574 */ 1575 1576 /** 1577 * Audio device types 1578 */ 1579 typedef enum libvlc_audio_output_device_types_t { 1580 libvlc_AudioOutputDevice_Error = -1, 1581 libvlc_AudioOutputDevice_Mono = 1, 1582 libvlc_AudioOutputDevice_Stereo = 2, 1583 libvlc_AudioOutputDevice_2F2R = 4, 1584 libvlc_AudioOutputDevice_3F2R = 5, 1585 libvlc_AudioOutputDevice_5_1 = 6, 1586 libvlc_AudioOutputDevice_6_1 = 7, 1587 libvlc_AudioOutputDevice_7_1 = 8, 1588 libvlc_AudioOutputDevice_SPDIF = 10 1589 } libvlc_audio_output_device_types_t; 1590 1591 /** 1592 * Audio channels 1593 */ 1594 typedef enum libvlc_audio_output_channel_t { 1595 libvlc_AudioChannel_Error = -1, 1596 libvlc_AudioChannel_Stereo = 1, 1597 libvlc_AudioChannel_RStereo = 2, 1598 libvlc_AudioChannel_Left = 3, 1599 libvlc_AudioChannel_Right = 4, 1600 libvlc_AudioChannel_Dolbys = 5 1601 } libvlc_audio_output_channel_t; 1602 1603 1604 /** 1605 * Gets the list of available audio output modules. 1606 * 1607 * \param p_instance libvlc instance 1608 * \return list of available audio outputs. It must be freed with 1609 * \see libvlc_audio_output_list_release \see libvlc_audio_output_t . 1610 * In case of error, NULL is returned. 1611 */ 1612 LIBVLC_API libvlc_audio_output_t * 1613 libvlc_audio_output_list_get( libvlc_instance_t *p_instance ); 1614 1615 /** 1616 * Frees the list of available audio output modules. 1617 * 1618 * \param p_list list with audio outputs for release 1619 */ 1620 LIBVLC_API 1621 void libvlc_audio_output_list_release( libvlc_audio_output_t *p_list ); 1622 1623 /** 1624 * Selects an audio output module. 1625 * \note Any change will take be effect only after playback is stopped and 1626 * restarted. Audio output cannot be changed while playing. 1627 * 1628 * \param p_mi media player 1629 * \param psz_name name of audio output, 1630 * use psz_name of \see libvlc_audio_output_t 1631 * \return 0 if function succeeded, -1 on error 1632 */ 1633 LIBVLC_API int libvlc_audio_output_set( libvlc_media_player_t *p_mi, 1634 const char *psz_name ); 1635 1636 /** 1637 * Gets a list of potential audio output devices, 1638 * \see libvlc_audio_output_device_set(). 1639 * 1640 * \note Not all audio outputs support enumerating devices. 1641 * The audio output may be functional even if the list is empty (NULL). 1642 * 1643 * \note The list may not be exhaustive. 1644 * 1645 * \warning Some audio output devices in the list might not actually work in 1646 * some circumstances. By default, it is recommended to not specify any 1647 * explicit audio device. 1648 * 1649 * \param mp media player 1650 * \return A NULL-terminated linked list of potential audio output devices. 1651 * It must be freed with libvlc_audio_output_device_list_release() 1652 * \version LibVLC 2.2.0 or later. 1653 */ 1654 LIBVLC_API libvlc_audio_output_device_t * 1655 libvlc_audio_output_device_enum( libvlc_media_player_t *mp ); 1656 1657 /** 1658 * Gets a list of audio output devices for a given audio output module, 1659 * \see libvlc_audio_output_device_set(). 1660 * 1661 * \note Not all audio outputs support this. In particular, an empty (NULL) 1662 * list of devices does <b>not</b> imply that the specified audio output does 1663 * not work. 1664 * 1665 * \note The list might not be exhaustive. 1666 * 1667 * \warning Some audio output devices in the list might not actually work in 1668 * some circumstances. By default, it is recommended to not specify any 1669 * explicit audio device. 1670 * 1671 * \param p_instance libvlc instance 1672 * \param aout audio output name 1673 * (as returned by libvlc_audio_output_list_get()) 1674 * \return A NULL-terminated linked list of potential audio output devices. 1675 * It must be freed with libvlc_audio_output_device_list_release() 1676 * \version LibVLC 2.1.0 or later. 1677 */ 1678 LIBVLC_API libvlc_audio_output_device_t * 1679 libvlc_audio_output_device_list_get( libvlc_instance_t *p_instance, 1680 const char *aout ); 1681 1682 /** 1683 * Frees a list of available audio output devices. 1684 * 1685 * \param p_list list with audio outputs for release 1686 * \version LibVLC 2.1.0 or later. 1687 */ 1688 LIBVLC_API void libvlc_audio_output_device_list_release( 1689 libvlc_audio_output_device_t *p_list ); 1690 1691 /** 1692 * Configures an explicit audio output device. 1693 * 1694 * If the module paramater is NULL, audio output will be moved to the device 1695 * specified by the device identifier string immediately. This is the 1696 * recommended usage. 1697 * 1698 * A list of adequate potential device strings can be obtained with 1699 * libvlc_audio_output_device_enum(). 1700 * 1701 * However passing NULL is supported in LibVLC version 2.2.0 and later only; 1702 * in earlier versions, this function would have no effects when the module 1703 * parameter was NULL. 1704 * 1705 * If the module parameter is not NULL, the device parameter of the 1706 * corresponding audio output, if it exists, will be set to the specified 1707 * string. Note that some audio output modules do not have such a parameter 1708 * (notably MMDevice and PulseAudio). 1709 * 1710 * A list of adequate potential device strings can be obtained with 1711 * libvlc_audio_output_device_list_get(). 1712 * 1713 * \note This function does not select the specified audio output plugin. 1714 * libvlc_audio_output_set() is used for that purpose. 1715 * 1716 * \warning The syntax for the device parameter depends on the audio output. 1717 * 1718 * Some audio output modules require further parameters (e.g. a channels map 1719 * in the case of ALSA). 1720 * 1721 * \param mp media player 1722 * \param module If NULL, current audio output module. 1723 * if non-NULL, name of audio output module 1724 (\see libvlc_audio_output_t) 1725 * \param device_id device identifier string 1726 * \return Nothing. Errors are ignored (this is a design bug). 1727 */ 1728 LIBVLC_API void libvlc_audio_output_device_set( libvlc_media_player_t *mp, 1729 const char *module, 1730 const char *device_id ); 1731 1732 /** 1733 * Get the current audio output device identifier. 1734 * 1735 * This complements libvlc_audio_output_device_set(). 1736 * 1737 * \warning The initial value for the current audio output device identifier 1738 * may not be set or may be some unknown value. A LibVLC application should 1739 * compare this value against the known device identifiers (e.g. those that 1740 * were previously retrieved by a call to libvlc_audio_output_device_enum or 1741 * libvlc_audio_output_device_list_get) to find the current audio output device. 1742 * 1743 * It is possible that the selected audio output device changes (an external 1744 * change) without a call to libvlc_audio_output_device_set. That may make this 1745 * method unsuitable to use if a LibVLC application is attempting to track 1746 * dynamic audio device changes as they happen. 1747 * 1748 * \param mp media player 1749 * \return the current audio output device identifier 1750 * NULL if no device is selected or in case of error 1751 * (the result must be released with free() or libvlc_free()). 1752 * \version LibVLC 3.0.0 or later. 1753 */ 1754 LIBVLC_API char *libvlc_audio_output_device_get( libvlc_media_player_t *mp ); 1755 1756 /** 1757 * Toggle mute status. 1758 * 1759 * \param p_mi media player 1760 * \warning Toggling mute atomically is not always possible: On some platforms, 1761 * other processes can mute the VLC audio playback stream asynchronously. Thus, 1762 * there is a small race condition where toggling will not work. 1763 * See also the limitations of libvlc_audio_set_mute(). 1764 */ 1765 LIBVLC_API void libvlc_audio_toggle_mute( libvlc_media_player_t *p_mi ); 1766 1767 /** 1768 * Get current mute status. 1769 * 1770 * \param p_mi media player 1771 * \return the mute status (boolean) if defined, -1 if undefined/unapplicable 1772 */ 1773 LIBVLC_API int libvlc_audio_get_mute( libvlc_media_player_t *p_mi ); 1774 1775 /** 1776 * Set mute status. 1777 * 1778 * \param p_mi media player 1779 * \param status If status is true then mute, otherwise unmute 1780 * \warning This function does not always work. If there are no active audio 1781 * playback stream, the mute status might not be available. If digital 1782 * pass-through (S/PDIF, HDMI...) is in use, muting may be unapplicable. Also 1783 * some audio output plugins do not support muting at all. 1784 * \note To force silent playback, disable all audio tracks. This is more 1785 * efficient and reliable than mute. 1786 */ 1787 LIBVLC_API void libvlc_audio_set_mute( libvlc_media_player_t *p_mi, int status ); 1788 1789 /** 1790 * Get current software audio volume. 1791 * 1792 * \param p_mi media player 1793 * \return the software volume in percents 1794 * (0 = mute, 100 = nominal / 0dB) 1795 */ 1796 LIBVLC_API int libvlc_audio_get_volume( libvlc_media_player_t *p_mi ); 1797 1798 /** 1799 * Set current software audio volume. 1800 * 1801 * \param p_mi media player 1802 * \param i_volume the volume in percents (0 = mute, 100 = 0dB) 1803 * \return 0 if the volume was set, -1 if it was out of range 1804 */ 1805 LIBVLC_API int libvlc_audio_set_volume( libvlc_media_player_t *p_mi, int i_volume ); 1806 1807 /** 1808 * Get number of available audio tracks. 1809 * 1810 * \param p_mi media player 1811 * \return the number of available audio tracks (int), or -1 if unavailable 1812 */ 1813 LIBVLC_API int libvlc_audio_get_track_count( libvlc_media_player_t *p_mi ); 1814 1815 /** 1816 * Get the description of available audio tracks. 1817 * 1818 * \param p_mi media player 1819 * \return list with description of available audio tracks, or NULL. 1820 * It must be freed with libvlc_track_description_list_release() 1821 */ 1822 LIBVLC_API libvlc_track_description_t * 1823 libvlc_audio_get_track_description( libvlc_media_player_t *p_mi ); 1824 1825 /** 1826 * Get current audio track. 1827 * 1828 * \param p_mi media player 1829 * \return the audio track ID or -1 if no active input. 1830 */ 1831 LIBVLC_API int libvlc_audio_get_track( libvlc_media_player_t *p_mi ); 1832 1833 /** 1834 * Set current audio track. 1835 * 1836 * \param p_mi media player 1837 * \param i_track the track ID (i_id field from track description) 1838 * \return 0 on success, -1 on error 1839 */ 1840 LIBVLC_API int libvlc_audio_set_track( libvlc_media_player_t *p_mi, int i_track ); 1841 1842 /** 1843 * Get current audio channel. 1844 * 1845 * \param p_mi media player 1846 * \return the audio channel \see libvlc_audio_output_channel_t 1847 */ 1848 LIBVLC_API int libvlc_audio_get_channel( libvlc_media_player_t *p_mi ); 1849 1850 /** 1851 * Set current audio channel. 1852 * 1853 * \param p_mi media player 1854 * \param channel the audio channel, \see libvlc_audio_output_channel_t 1855 * \return 0 on success, -1 on error 1856 */ 1857 LIBVLC_API int libvlc_audio_set_channel( libvlc_media_player_t *p_mi, int channel ); 1858 1859 /** 1860 * Get current audio delay. 1861 * 1862 * \param p_mi media player 1863 * \return the audio delay (microseconds) 1864 * \version LibVLC 1.1.1 or later 1865 */ 1866 LIBVLC_API int64_t libvlc_audio_get_delay( libvlc_media_player_t *p_mi ); 1867 1868 /** 1869 * Set current audio delay. The audio delay will be reset to zero each time the media changes. 1870 * 1871 * \param p_mi media player 1872 * \param i_delay the audio delay (microseconds) 1873 * \return 0 on success, -1 on error 1874 * \version LibVLC 1.1.1 or later 1875 */ 1876 LIBVLC_API int libvlc_audio_set_delay( libvlc_media_player_t *p_mi, int64_t i_delay ); 1877 1878 /** 1879 * Get the number of equalizer presets. 1880 * 1881 * \return number of presets 1882 * \version LibVLC 2.2.0 or later 1883 */ 1884 LIBVLC_API unsigned libvlc_audio_equalizer_get_preset_count( void ); 1885 1886 /** 1887 * Get the name of a particular equalizer preset. 1888 * 1889 * This name can be used, for example, to prepare a preset label or menu in a user 1890 * interface. 1891 * 1892 * \param u_index index of the preset, counting from zero 1893 * \return preset name, or NULL if there is no such preset 1894 * \version LibVLC 2.2.0 or later 1895 */ 1896 LIBVLC_API const char *libvlc_audio_equalizer_get_preset_name( unsigned u_index ); 1897 1898 /** 1899 * Get the number of distinct frequency bands for an equalizer. 1900 * 1901 * \return number of frequency bands 1902 * \version LibVLC 2.2.0 or later 1903 */ 1904 LIBVLC_API unsigned libvlc_audio_equalizer_get_band_count( void ); 1905 1906 /** 1907 * Get a particular equalizer band frequency. 1908 * 1909 * This value can be used, for example, to create a label for an equalizer band control 1910 * in a user interface. 1911 * 1912 * \param u_index index of the band, counting from zero 1913 * \return equalizer band frequency (Hz), or -1 if there is no such band 1914 * \version LibVLC 2.2.0 or later 1915 */ 1916 LIBVLC_API float libvlc_audio_equalizer_get_band_frequency( unsigned u_index ); 1917 1918 /** 1919 * Create a new default equalizer, with all frequency values zeroed. 1920 * 1921 * The new equalizer can subsequently be applied to a media player by invoking 1922 * libvlc_media_player_set_equalizer(). 1923 * 1924 * The returned handle should be freed via libvlc_audio_equalizer_release() when 1925 * it is no longer needed. 1926 * 1927 * \return opaque equalizer handle, or NULL on error 1928 * \version LibVLC 2.2.0 or later 1929 */ 1930 LIBVLC_API libvlc_equalizer_t *libvlc_audio_equalizer_new( void ); 1931 1932 /** 1933 * Create a new equalizer, with initial frequency values copied from an existing 1934 * preset. 1935 * 1936 * The new equalizer can subsequently be applied to a media player by invoking 1937 * libvlc_media_player_set_equalizer(). 1938 * 1939 * The returned handle should be freed via libvlc_audio_equalizer_release() when 1940 * it is no longer needed. 1941 * 1942 * \param u_index index of the preset, counting from zero 1943 * \return opaque equalizer handle, or NULL on error 1944 * \version LibVLC 2.2.0 or later 1945 */ 1946 LIBVLC_API libvlc_equalizer_t *libvlc_audio_equalizer_new_from_preset( unsigned u_index ); 1947 1948 /** 1949 * Release a previously created equalizer instance. 1950 * 1951 * The equalizer was previously created by using libvlc_audio_equalizer_new() or 1952 * libvlc_audio_equalizer_new_from_preset(). 1953 * 1954 * It is safe to invoke this method with a NULL p_equalizer parameter for no effect. 1955 * 1956 * \param p_equalizer opaque equalizer handle, or NULL 1957 * \version LibVLC 2.2.0 or later 1958 */ 1959 LIBVLC_API void libvlc_audio_equalizer_release( libvlc_equalizer_t *p_equalizer ); 1960 1961 /** 1962 * Set a new pre-amplification value for an equalizer. 1963 * 1964 * The new equalizer settings are subsequently applied to a media player by invoking 1965 * libvlc_media_player_set_equalizer(). 1966 * 1967 * The supplied amplification value will be clamped to the -20.0 to +20.0 range. 1968 * 1969 * \param p_equalizer valid equalizer handle, must not be NULL 1970 * \param f_preamp preamp value (-20.0 to 20.0 Hz) 1971 * \return zero on success, -1 on error 1972 * \version LibVLC 2.2.0 or later 1973 */ 1974 LIBVLC_API int libvlc_audio_equalizer_set_preamp( libvlc_equalizer_t *p_equalizer, float f_preamp ); 1975 1976 /** 1977 * Get the current pre-amplification value from an equalizer. 1978 * 1979 * \param p_equalizer valid equalizer handle, must not be NULL 1980 * \return preamp value (Hz) 1981 * \version LibVLC 2.2.0 or later 1982 */ 1983 LIBVLC_API float libvlc_audio_equalizer_get_preamp( libvlc_equalizer_t *p_equalizer ); 1984 1985 /** 1986 * Set a new amplification value for a particular equalizer frequency band. 1987 * 1988 * The new equalizer settings are subsequently applied to a media player by invoking 1989 * libvlc_media_player_set_equalizer(). 1990 * 1991 * The supplied amplification value will be clamped to the -20.0 to +20.0 range. 1992 * 1993 * \param p_equalizer valid equalizer handle, must not be NULL 1994 * \param f_amp amplification value (-20.0 to 20.0 Hz) 1995 * \param u_band index, counting from zero, of the frequency band to set 1996 * \return zero on success, -1 on error 1997 * \version LibVLC 2.2.0 or later 1998 */ 1999 LIBVLC_API int libvlc_audio_equalizer_set_amp_at_index( libvlc_equalizer_t *p_equalizer, float f_amp, unsigned u_band ); 2000 2001 /** 2002 * Get the amplification value for a particular equalizer frequency band. 2003 * 2004 * \param p_equalizer valid equalizer handle, must not be NULL 2005 * \param u_band index, counting from zero, of the frequency band to get 2006 * \return amplification value (Hz); NaN if there is no such frequency band 2007 * \version LibVLC 2.2.0 or later 2008 */ 2009 LIBVLC_API float libvlc_audio_equalizer_get_amp_at_index( libvlc_equalizer_t *p_equalizer, unsigned u_band ); 2010 2011 /** 2012 * Apply new equalizer settings to a media player. 2013 * 2014 * The equalizer is first created by invoking libvlc_audio_equalizer_new() or 2015 * libvlc_audio_equalizer_new_from_preset(). 2016 * 2017 * It is possible to apply new equalizer settings to a media player whether the media 2018 * player is currently playing media or not. 2019 * 2020 * Invoking this method will immediately apply the new equalizer settings to the audio 2021 * output of the currently playing media if there is any. 2022 * 2023 * If there is no currently playing media, the new equalizer settings will be applied 2024 * later if and when new media is played. 2025 * 2026 * Equalizer settings will automatically be applied to subsequently played media. 2027 * 2028 * To disable the equalizer for a media player invoke this method passing NULL for the 2029 * p_equalizer parameter. 2030 * 2031 * The media player does not keep a reference to the supplied equalizer so it is safe 2032 * for an application to release the equalizer reference any time after this method 2033 * returns. 2034 * 2035 * \param p_mi opaque media player handle 2036 * \param p_equalizer opaque equalizer handle, or NULL to disable the equalizer for this media player 2037 * \return zero on success, -1 on error 2038 * \version LibVLC 2.2.0 or later 2039 */ 2040 LIBVLC_API int libvlc_media_player_set_equalizer( libvlc_media_player_t *p_mi, libvlc_equalizer_t *p_equalizer ); 2041 2042 /** 2043 * Media player roles. 2044 * 2045 * \version LibVLC 3.0.0 and later. 2046 * 2047 * See \ref libvlc_media_player_set_role() 2048 */ 2049 typedef enum libvlc_media_player_role { 2050 libvlc_role_None = 0, /**< Don't use a media player role */ 2051 libvlc_role_Music, /**< Music (or radio) playback */ 2052 libvlc_role_Video, /**< Video playback */ 2053 libvlc_role_Communication, /**< Speech, real-time communication */ 2054 libvlc_role_Game, /**< Video game */ 2055 libvlc_role_Notification, /**< User interaction feedback */ 2056 libvlc_role_Animation, /**< Embedded animation (e.g. in web page) */ 2057 libvlc_role_Production, /**< Audio editting/production */ 2058 libvlc_role_Accessibility, /**< Accessibility */ 2059 libvlc_role_Test /** Testing */ 2060 #define libvlc_role_Last libvlc_role_Test 2061 } libvlc_media_player_role_t; 2062 2063 /** 2064 * Gets the media role. 2065 * 2066 * \version LibVLC 3.0.0 and later. 2067 * 2068 * \param p_mi media player 2069 * \return the media player role (\ref libvlc_media_player_role_t) 2070 */ 2071 LIBVLC_API int libvlc_media_player_get_role(libvlc_media_player_t *p_mi); 2072 2073 /** 2074 * Sets the media role. 2075 * 2076 * \param p_mi media player 2077 * \param role the media player role (\ref libvlc_media_player_role_t) 2078 * \return 0 on success, -1 on error 2079 */ 2080 LIBVLC_API int libvlc_media_player_set_role(libvlc_media_player_t *p_mi, 2081 unsigned role); 2082 2083 /** @} audio */ 2084 2085 /** @} media_player */ 2086 2087 # ifdef __cplusplus 2088 } 2089 # endif 2090 2091 #endif /* VLC_LIBVLC_MEDIA_PLAYER_H */ 2092