1 /*****************************************************************************
2 * libvlc_media_player.h: libvlc_media_player external API
3 *****************************************************************************
4 * Copyright (C) 1998-2015 VLC authors and VideoLAN
6 * Authors: Clément Stenac <zorglub@videolan.org>
7 * Jean-Paul Saman <jpsaman@videolan.org>
8 * Pierre d'Herbemont <pdherbemont@videolan.org>
10 * This program is free software; you can redistribute it and/or modify it
11 * under the terms of the GNU Lesser General Public License as published by
12 * the Free Software Foundation; either version 2.1 of the License, or
13 * (at your option) any later version.
15 * This program is distributed in the hope that it will be useful,
16 * but WITHOUT ANY WARRANTY; without even the implied warranty of
17 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 * GNU Lesser General Public License for more details.
20 * You should have received a copy of the GNU Lesser General Public License
21 * along with this program; if not, write to the Free Software Foundation,
22 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
23 *****************************************************************************/
25 #ifndef VLC_LIBVLC_MEDIA_PLAYER_H
26 #define VLC_LIBVLC_MEDIA_PLAYER_H 1
34 /** \defgroup libvlc_media_player LibVLC media player
36 * A LibVLC media player plays one media (usually in a custom drawable).
39 * LibVLC simple media player external API
42 typedef struct libvlc_media_player_t libvlc_media_player_t
;
45 * Description for titles
49 libvlc_title_menu
= 0x01,
50 libvlc_title_interactive
= 0x02
53 typedef struct libvlc_title_description_t
55 int64_t i_duration
; /**< duration in milliseconds */
56 char *psz_name
; /**< title name */
57 unsigned i_flags
; /**< info if item was recognized as a menu, interactive or plain content by the demuxer */
58 } libvlc_title_description_t
;
61 * Description for chapters
63 typedef struct libvlc_chapter_description_t
65 int64_t i_time_offset
; /**< time-offset of the chapter in milliseconds */
66 int64_t i_duration
; /**< duration of the chapter in milliseconds */
67 char *psz_name
; /**< chapter name */
68 } libvlc_chapter_description_t
;
71 * Description for audio output. It contains
72 * name, description and pointer to next record.
74 typedef struct libvlc_audio_output_t
77 char *psz_description
;
78 struct libvlc_audio_output_t
*p_next
;
80 } libvlc_audio_output_t
;
83 * Description for audio output device.
85 typedef struct libvlc_audio_output_device_t
87 struct libvlc_audio_output_device_t
*p_next
; /**< Next entry in list */
88 char *psz_device
; /**< Device identifier string */
89 char *psz_description
; /**< User-friendly device description */
90 /* More fields may be added here in later versions */
91 } libvlc_audio_output_device_t
;
94 * Marq options definition
96 typedef enum libvlc_video_marquee_option_t
{
97 libvlc_marquee_Enable
= 0,
98 libvlc_marquee_Text
, /** string argument */
100 libvlc_marquee_Opacity
,
101 libvlc_marquee_Position
,
102 libvlc_marquee_Refresh
,
104 libvlc_marquee_Timeout
,
107 } libvlc_video_marquee_option_t
;
112 typedef enum libvlc_navigate_mode_t
114 libvlc_navigate_activate
= 0,
116 libvlc_navigate_down
,
117 libvlc_navigate_left
,
118 libvlc_navigate_right
,
119 libvlc_navigate_popup
120 } libvlc_navigate_mode_t
;
123 * Enumeration of values used to set position (e.g. of video title).
125 typedef enum libvlc_position_t
{
126 libvlc_position_disable
=-1,
127 libvlc_position_center
,
128 libvlc_position_left
,
129 libvlc_position_right
,
131 libvlc_position_top_left
,
132 libvlc_position_top_right
,
133 libvlc_position_bottom
,
134 libvlc_position_bottom_left
,
135 libvlc_position_bottom_right
139 * Enumeration of teletext keys than can be passed via
140 * libvlc_video_set_teletext()
142 typedef enum libvlc_teletext_key_t
{
143 libvlc_teletext_key_red
= 'r' << 16,
144 libvlc_teletext_key_green
= 'g' << 16,
145 libvlc_teletext_key_yellow
= 'y' << 16,
146 libvlc_teletext_key_blue
= 'b' << 16,
147 libvlc_teletext_key_index
= 'i' << 16,
148 } libvlc_teletext_key_t
;
151 * Opaque equalizer handle.
153 * Equalizer settings can be applied to a media player.
155 typedef struct libvlc_equalizer_t libvlc_equalizer_t
;
158 * Create an empty Media Player object
160 * \param p_libvlc_instance the libvlc instance in which the Media Player
162 * \return a new media player object, or NULL on error.
163 * It must be released by libvlc_media_player_release().
165 LIBVLC_API libvlc_media_player_t
* libvlc_media_player_new( libvlc_instance_t
*p_libvlc_instance
);
168 * Create a Media Player object from a Media
170 * \param p_md the media. Afterwards the p_md can be safely
172 * \return a new media player object, or NULL on error.
173 * It must be released by libvlc_media_player_release().
175 LIBVLC_API libvlc_media_player_t
* libvlc_media_player_new_from_media( libvlc_media_t
*p_md
);
178 * Release a media_player after use
179 * Decrement the reference count of a media player object. If the
180 * reference count is 0, then libvlc_media_player_release() will
181 * release the media player object. If the media player object
182 * has been released, then it should not be used again.
184 * \param p_mi the Media Player to free
186 LIBVLC_API
void libvlc_media_player_release( libvlc_media_player_t
*p_mi
);
189 * Retain a reference to a media player object. Use
190 * libvlc_media_player_release() to decrement reference count.
192 * \param p_mi media player object
194 LIBVLC_API
void libvlc_media_player_retain( libvlc_media_player_t
*p_mi
);
197 * Set the media that will be used by the media_player. If any,
198 * previous md will be released.
200 * \param p_mi the Media Player
201 * \param p_md the Media. Afterwards the p_md can be safely
204 LIBVLC_API
void libvlc_media_player_set_media( libvlc_media_player_t
*p_mi
,
205 libvlc_media_t
*p_md
);
208 * Get the media used by the media_player.
210 * \param p_mi the Media Player
211 * \return the media associated with p_mi, or NULL if no
212 * media is associated
214 LIBVLC_API libvlc_media_t
* libvlc_media_player_get_media( libvlc_media_player_t
*p_mi
);
217 * Get the Event Manager from which the media player send event.
219 * \param p_mi the Media Player
220 * \return the event manager associated with p_mi
222 LIBVLC_API libvlc_event_manager_t
* libvlc_media_player_event_manager ( libvlc_media_player_t
*p_mi
);
227 * \param p_mi the Media Player
228 * \retval true media player is playing
229 * \retval false media player is not playing
231 LIBVLC_API
bool libvlc_media_player_is_playing(libvlc_media_player_t
*p_mi
);
236 * \param p_mi the Media Player
237 * \return 0 if playback started (and was already started), or -1 on error.
239 LIBVLC_API
int libvlc_media_player_play ( libvlc_media_player_t
*p_mi
);
242 * Pause or resume (no effect if there is no media)
244 * \param mp the Media Player
245 * \param do_pause play/resume if zero, pause if non-zero
246 * \version LibVLC 1.1.1 or later
248 LIBVLC_API
void libvlc_media_player_set_pause ( libvlc_media_player_t
*mp
,
252 * Toggle pause (no effect if there is no media)
254 * \param p_mi the Media Player
256 LIBVLC_API
void libvlc_media_player_pause ( libvlc_media_player_t
*p_mi
);
259 * Stop asynchronously
261 * \note This function is asynchronous. In case of success, the user should
262 * wait for the libvlc_MediaPlayerStopped event to know when the stop is
265 * \param p_mi the Media Player
266 * \return 0 if the player is being stopped, -1 otherwise (no-op)
267 * \version LibVLC 4.0.0 or later
269 LIBVLC_API
int libvlc_media_player_stop_async ( libvlc_media_player_t
*p_mi
);
272 * Set a renderer to the media player
274 * \note must be called before the first call of libvlc_media_player_play() to
277 * \see libvlc_renderer_discoverer_new
279 * \param p_mi the Media Player
280 * \param p_item an item discovered by libvlc_renderer_discoverer_start()
281 * \return 0 on success, -1 on error.
282 * \version LibVLC 3.0.0 or later
284 LIBVLC_API
int libvlc_media_player_set_renderer( libvlc_media_player_t
*p_mi
,
285 libvlc_renderer_item_t
*p_item
);
288 * Enumeration of the Video color primaries.
290 typedef enum libvlc_video_color_primaries_t
{
291 libvlc_video_primaries_BT601_525
= 1,
292 libvlc_video_primaries_BT601_625
= 2,
293 libvlc_video_primaries_BT709
= 3,
294 libvlc_video_primaries_BT2020
= 4,
295 libvlc_video_primaries_DCI_P3
= 5,
296 libvlc_video_primaries_BT470_M
= 6,
297 } libvlc_video_color_primaries_t
;
300 * Enumeration of the Video color spaces.
302 typedef enum libvlc_video_color_space_t
{
303 libvlc_video_colorspace_BT601
= 1,
304 libvlc_video_colorspace_BT709
= 2,
305 libvlc_video_colorspace_BT2020
= 3,
306 } libvlc_video_color_space_t
;
309 * Enumeration of the Video transfer functions.
311 typedef enum libvlc_video_transfer_func_t
{
312 libvlc_video_transfer_func_LINEAR
= 1,
313 libvlc_video_transfer_func_SRGB
= 2,
314 libvlc_video_transfer_func_BT470_BG
= 3,
315 libvlc_video_transfer_func_BT470_M
= 4,
316 libvlc_video_transfer_func_BT709
= 5,
317 libvlc_video_transfer_func_PQ
= 6,
318 libvlc_video_transfer_func_SMPTE_240
= 7,
319 libvlc_video_transfer_func_HLG
= 8,
320 } libvlc_video_transfer_func_t
;
324 * Callback prototype to allocate and lock a picture buffer.
326 * Whenever a new video frame needs to be decoded, the lock callback is
327 * invoked. Depending on the video chroma, one or three pixel planes of
328 * adequate dimensions must be returned via the second parameter. Those
329 * planes must be aligned on 32-bytes boundaries.
331 * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]
332 * \param planes start address of the pixel planes (LibVLC allocates the array
333 * of void pointers, this callback must initialize the array) [OUT]
334 * \return a private pointer for the display and unlock callbacks to identify
335 * the picture buffers
337 typedef void *(*libvlc_video_lock_cb
)(void *opaque
, void **planes
);
340 * Callback prototype to unlock a picture buffer.
342 * When the video frame decoding is complete, the unlock callback is invoked.
343 * This callback might not be needed at all. It is only an indication that the
344 * application can now read the pixel values if it needs to.
346 * \note A picture buffer is unlocked after the picture is decoded,
347 * but before the picture is displayed.
349 * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]
350 * \param picture private pointer returned from the @ref libvlc_video_lock_cb
352 * \param planes pixel planes as defined by the @ref libvlc_video_lock_cb
353 * callback (this parameter is only for convenience) [IN]
355 typedef void (*libvlc_video_unlock_cb
)(void *opaque
, void *picture
,
356 void *const *planes
);
359 * Callback prototype to display a picture.
361 * When the video frame needs to be shown, as determined by the media playback
362 * clock, the display callback is invoked.
364 * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]
365 * \param picture private pointer returned from the @ref libvlc_video_lock_cb
368 typedef void (*libvlc_video_display_cb
)(void *opaque
, void *picture
);
371 * Callback prototype to configure picture buffers format.
372 * This callback gets the format of the video as output by the video decoder
373 * and the chain of video filters (if any). It can opt to change any parameter
374 * as it needs. In that case, LibVLC will attempt to convert the video format
375 * (rescaling and chroma conversion) but these operations can be CPU intensive.
377 * \param opaque pointer to the private pointer passed to
378 * libvlc_video_set_callbacks() [IN/OUT]
379 * \param chroma pointer to the 4 bytes video format identifier [IN/OUT]
380 * \param width pointer to the buffer width in pixels[IN/OUT]
381 * \param height pointer to the buffer height in pixels[IN/OUT]
382 * \param pitches table of scanline pitches in bytes for each pixel plane
383 * (the table is allocated by LibVLC) [OUT]
384 * \param lines table of scanlines count for each plane [OUT]
385 * \return the number of picture buffers allocated, 0 indicates failure
387 * \version LibVLC 4.0.0 and later.
388 * \param (width+1) - pointer to display width in pixels[IN]
389 * \param (height+1) - pointer to display height in pixels[IN]
392 * For each pixels plane, the scanline pitch must be bigger than or equal to
393 * the number of bytes per pixel multiplied by the pixel width.
394 * Similarly, the number of scanlines must be bigger than of equal to
396 * Furthermore, we recommend that pitches and lines be multiple of 32
397 * to not break assumptions that might be held by optimized code
398 * in the video decoders, video filters and/or video converters.
400 typedef unsigned (*libvlc_video_format_cb
)(void **opaque
, char *chroma
,
401 unsigned *width
, unsigned *height
,
406 * Callback prototype to configure picture buffers format.
408 * \param opaque private pointer as passed to libvlc_video_set_format_callbacks()
409 * (and possibly modified by @ref libvlc_video_format_cb) [IN]
411 typedef void (*libvlc_video_cleanup_cb
)(void *opaque
);
415 * Set callbacks and private data to render decoded video to a custom area
417 * Use libvlc_video_set_format() or libvlc_video_set_format_callbacks()
418 * to configure the decoded format.
420 * \warning Rendering video into custom memory buffers is considerably less
421 * efficient than rendering in a custom window as normal.
423 * For optimal perfomances, VLC media player renders into a custom window, and
424 * does not use this function and associated callbacks. It is <b>highly
425 * recommended</b> that other LibVLC-based application do likewise.
426 * To embed video in a window, use libvlc_media_player_set_xid() or equivalent
427 * depending on the operating system.
429 * If window embedding does not fit the application use case, then a custom
430 * LibVLC video output display plugin is required to maintain optimal video
431 * rendering performances.
433 * The following limitations affect performance:
434 * - Hardware video decoding acceleration will either be disabled completely,
435 * or require (relatively slow) copy from video/DSP memory to main memory.
436 * - Sub-pictures (subtitles, on-screen display, etc.) must be blent into the
437 * main picture by the CPU instead of the GPU.
438 * - Depending on the video format, pixel format conversion, picture scaling,
439 * cropping and/or picture re-orientation, must be performed by the CPU
440 * instead of the GPU.
441 * - Memory copying is required between LibVLC reference picture buffers and
442 * application buffers (between lock and unlock callbacks).
444 * \param mp the media player
445 * \param lock callback to lock video memory (must not be NULL)
446 * \param unlock callback to unlock video memory (or NULL if not needed)
447 * \param display callback to display video (or NULL if not needed)
448 * \param opaque private pointer for the three callbacks (as first parameter)
449 * \version LibVLC 1.1.1 or later
452 void libvlc_video_set_callbacks( libvlc_media_player_t
*mp
,
453 libvlc_video_lock_cb lock
,
454 libvlc_video_unlock_cb unlock
,
455 libvlc_video_display_cb display
,
459 * Set decoded video chroma and dimensions.
460 * This only works in combination with libvlc_video_set_callbacks(),
461 * and is mutually exclusive with libvlc_video_set_format_callbacks().
463 * \param mp the media player
464 * \param chroma a four-characters string identifying the chroma
465 * (e.g. "RV32" or "YUYV")
466 * \param width pixel width
467 * \param height pixel height
468 * \param pitch line pitch (in bytes)
469 * \version LibVLC 1.1.1 or later
470 * \bug All pixel planes are expected to have the same pitch.
471 * To use the YCbCr color space with chrominance subsampling,
472 * consider using libvlc_video_set_format_callbacks() instead.
475 void libvlc_video_set_format( libvlc_media_player_t
*mp
, const char *chroma
,
476 unsigned width
, unsigned height
,
480 * Set decoded video chroma and dimensions. This only works in combination with
481 * libvlc_video_set_callbacks().
483 * \param mp the media player
484 * \param setup callback to select the video format (cannot be NULL)
485 * \param cleanup callback to release any allocated resources (or NULL)
486 * \version LibVLC 2.0.0 or later
489 void libvlc_video_set_format_callbacks( libvlc_media_player_t
*mp
,
490 libvlc_video_format_cb setup
,
491 libvlc_video_cleanup_cb cleanup
);
496 bool hardware_decoding
; /** set if D3D11_CREATE_DEVICE_VIDEO_SUPPORT is needed for D3D11 */
497 } libvlc_video_setup_device_cfg_t
;
503 void *device_context
; /** ID3D11DeviceContext* */
506 void *device
; /** IDirect3D9* */
507 int adapter
; /** Adapter to use with the IDirect3D9* */
510 } libvlc_video_setup_device_info_t
;
513 * Callback prototype called to initialize user data.
514 * Setup the rendering environment.
516 * \param opaque private pointer passed to the @a libvlc_video_set_output_callbacks()
517 * on input. The callback can change this value on output to be
518 * passed to all the other callbacks set on @a libvlc_video_set_output_callbacks().
520 * \param cfg requested configuration of the video device [IN]
521 * \param out libvlc_video_setup_device_info_t* to fill [OUT]
522 * \return true on success
523 * \version LibVLC 4.0.0 or later
525 * For \ref libvlc_video_engine_d3d9 the output must be a IDirect3D9*.
526 * A reference to this object is held until the \ref LIBVLC_VIDEO_DEVICE_CLEANUP is called.
527 * the device must be created with D3DPRESENT_PARAMETERS.hDeviceWindow set to 0.
529 * For \ref libvlc_video_engine_d3d11 the output must be a ID3D11DeviceContext*.
530 * A reference to this object is held until the \ref LIBVLC_VIDEO_DEVICE_CLEANUP is called.
531 * The ID3D11Device used to create ID3D11DeviceContext must have multithreading enabled.
533 typedef bool (*libvlc_video_output_setup_cb
)(void **opaque
,
534 const libvlc_video_setup_device_cfg_t
*cfg
,
535 libvlc_video_setup_device_info_t
*out
);
539 * Callback prototype called to release user data
541 * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]
542 * \version LibVLC 4.0.0 or later
544 typedef void (*libvlc_video_output_cleanup_cb
)(void* opaque
);
548 unsigned width
; /** rendering video width in pixel */
549 unsigned height
; /** rendering video height in pixel */
550 unsigned bitdepth
; /** rendering video bit depth in bits per channel */
551 bool full_range
; /** video is full range or studio/limited range */
552 libvlc_video_color_space_t colorspace
; /** video color space */
553 libvlc_video_color_primaries_t primaries
; /** video color primaries */
554 libvlc_video_transfer_func_t transfer
; /** video transfer function */
555 void *device
; /** device used for rendering, IDirect3DDevice9* for D3D9 */
556 } libvlc_video_render_cfg_t
;
561 int dxgi_format
; /** the rendering DXGI_FORMAT for \ref libvlc_video_engine_d3d11*/
562 uint32_t d3d9_format
; /** the rendering D3DFORMAT for \ref libvlc_video_engine_d3d9 */
563 int opengl_format
; /** the rendering GLint GL_RGBA or GL_RGB for \ref libvlc_video_engine_opengl and
564 for \ref libvlc_video_engine_gles2 */
565 void *p_surface
; /** currently unused */
567 bool full_range
; /** video is full range or studio/limited range */
568 libvlc_video_color_space_t colorspace
; /** video color space */
569 libvlc_video_color_primaries_t primaries
; /** video color primaries */
570 libvlc_video_transfer_func_t transfer
; /** video transfer function */
571 } libvlc_video_output_cfg_t
;
574 * Callback prototype called on video size changes.
575 * Update the rendering output setup.
577 * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]
578 * \param cfg configuration of the video that will be rendered [IN]
579 * \param output configuration describing with how the rendering is setup [OUT]
580 * \version LibVLC 4.0.0 or later
582 * \note the configuration device for Direct3D9 is the IDirect3DDevice9 that VLC
583 * uses to render. The host must set a Render target and call Present()
584 * when it needs the drawing from VLC to be done. This object is not valid
585 * anymore after Cleanup is called.
587 * Tone mapping, range and color conversion will be done depending on the values
588 * set in the output structure.
590 typedef bool (*libvlc_video_update_output_cb
)(void* opaque
, const libvlc_video_render_cfg_t
*cfg
,
591 libvlc_video_output_cfg_t
*output
);
595 * Callback prototype called after performing drawing calls.
597 * This callback is called outside of libvlc_video_makeCurrent_cb current/not-current
600 * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]
601 * \version LibVLC 4.0.0 or later
603 typedef void (*libvlc_video_swap_cb
)(void* opaque
);
606 * Callback prototype to set up the OpenGL context for rendering.
607 * Tell the host the rendering is about to start/has finished.
609 * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]
610 * \param enter true to set the context as current, false to unset it [IN]
611 * \return true on success
612 * \version LibVLC 4.0.0 or later
614 * On Direct3D11 the following may change on the provided ID3D11DeviceContext*
615 * between \ref enter being true and \ref enter being false:
616 * - IASetPrimitiveTopology()
617 * - IASetInputLayout()
618 * - IASetVertexBuffers()
619 * - IASetIndexBuffer()
620 * - VSSetConstantBuffers()
623 * - PSSetConstantBuffers()
624 * - PSSetShaderResources()
629 typedef bool (*libvlc_video_makeCurrent_cb
)(void* opaque
, bool enter
);
632 * Callback prototype to load opengl functions
634 * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]
635 * \param fct_name name of the opengl function to load
636 * \return a pointer to the named OpenGL function the NULL otherwise
637 * \version LibVLC 4.0.0 or later
639 typedef void* (*libvlc_video_getProcAddress_cb
)(void* opaque
, const char* fct_name
);
643 /* similar to SMPTE ST 2086 mastering display color volume */
644 uint16_t RedPrimary
[2];
645 uint16_t GreenPrimary
[2];
646 uint16_t BluePrimary
[2];
647 uint16_t WhitePoint
[2];
648 unsigned int MaxMasteringLuminance
;
649 unsigned int MinMasteringLuminance
;
650 uint16_t MaxContentLightLevel
;
651 uint16_t MaxFrameAverageLightLevel
;
652 } libvlc_video_frame_hdr10_metadata_t
;
654 typedef enum libvlc_video_metadata_type_t
{
655 libvlc_video_metadata_frame_hdr10
, /**< libvlc_video_frame_hdr10_metadata_t */
656 } libvlc_video_metadata_type_t
;
659 * Callback prototype to receive metadata before rendering.
661 * \param opaque private pointer passed to the @a libvlc_video_set_output_callbacks() [IN]
662 * \param type type of data passed in metadata [IN]
663 * \param metadata the type of metadata [IN]
664 * \version LibVLC 4.0.0 or later
666 typedef void (*libvlc_video_frameMetadata_cb
)(void* opaque
, libvlc_video_metadata_type_t type
, const void *metadata
);
669 * Enumeration of the Video engine to be used on output.
670 * can be passed to @a libvlc_video_set_output_callbacks
672 typedef enum libvlc_video_engine_t
{
673 /** Disable rendering engine */
674 libvlc_video_engine_disable
,
675 libvlc_video_engine_opengl
,
676 libvlc_video_engine_gles2
,
677 /** Direct3D11 rendering engine */
678 libvlc_video_engine_d3d11
,
679 /** Direct3D9 rendering engine */
680 libvlc_video_engine_d3d9
,
681 } libvlc_video_engine_t
;
683 /** Set the callback to call when the host app resizes the rendering area.
685 * This allows text rendering and aspect ratio to be handled properly when the host
686 * rendering size changes.
688 * It may be called before the \ref libvlc_video_output_setup_cb callback.
690 * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]
691 * \param report_size_change callback which must be called when the host size changes. [IN]
692 * The callback is valid until another call to \ref libvlc_video_output_set_resize_cb
693 * is done. This may be called from any thread.
694 * \param report_opaque private pointer to pass to the \ref report_size_change callback. [IN]
696 typedef void( *libvlc_video_output_set_resize_cb
)( void *opaque
,
697 void (*report_size_change
)(void *report_opaque
, unsigned width
, unsigned height
),
698 void *report_opaque
);
700 /** Tell the host the rendering for the given plane is about to start
702 * \param opaque private pointer set on the opaque parameter of @a libvlc_video_output_setup_cb() [IN]
703 * \param plane number of the rendering plane to select
704 * \return true on success
705 * \version LibVLC 4.0.0 or later
707 * \note This is only used with \ref libvlc_video_engine_d3d11.
709 * The host should call OMSetRenderTargets for Direct3D11. If this callback is
710 * not used (set to NULL in @a libvlc_video_set_output_callbacks()) OMSetRenderTargets
711 * has to be set during the @a libvlc_video_makeCurrent_cb()
714 * The number of planes depend on the DXGI_FORMAT returned during the
715 * \ref LIBVLC_VIDEO_UPDATE_OUTPUT call. It's usually one plane except for
716 * semi-planar formats like DXGI_FORMAT_NV12 or DXGI_FORMAT_P010.
718 * This callback is called between libvlc_video_makeCurrent_cb current/not-current
721 typedef bool( *libvlc_video_output_select_plane_cb
)( void *opaque
, size_t plane
);
724 * Set callbacks and data to render decoded video to a custom texture
726 * \warning VLC will perform video rendering in its own thread and at its own rate,
727 * You need to provide your own synchronisation mechanism.
729 * \param mp the media player
730 * \param engine the GPU engine to use
731 * \param setup_cb callback called to initialize user data
732 * \param cleanup_cb callback called to clean up user data
733 * \param resize_cb callback to set the resize callback
734 * \param update_output_cb callback to get the rendering format of the host (cannot be NULL)
735 * \param swap_cb callback called after rendering a video frame (cannot be NULL)
736 * \param makeCurrent_cb callback called to enter/leave the rendering context (cannot be NULL)
737 * \param getProcAddress_cb opengl function loading callback (cannot be NULL for \ref libvlc_video_engine_opengl and for \ref libvlc_video_engine_gles2)
738 * \param metadata_cb callback to provide frame metadata (D3D11 only)
739 * \param select_plane_cb callback to select different D3D11 rendering targets
740 * \param opaque private pointer passed to callbacks
742 * \retval true engine selected and callbacks set
743 * \retval false engine type unknown, callbacks not set
744 * \version LibVLC 4.0.0 or later
747 bool libvlc_video_set_output_callbacks( libvlc_media_player_t
*mp
,
748 libvlc_video_engine_t engine
,
749 libvlc_video_output_setup_cb setup_cb
,
750 libvlc_video_output_cleanup_cb cleanup_cb
,
751 libvlc_video_output_set_resize_cb resize_cb
,
752 libvlc_video_update_output_cb update_output_cb
,
753 libvlc_video_swap_cb swap_cb
,
754 libvlc_video_makeCurrent_cb makeCurrent_cb
,
755 libvlc_video_getProcAddress_cb getProcAddress_cb
,
756 libvlc_video_frameMetadata_cb metadata_cb
,
757 libvlc_video_output_select_plane_cb select_plane_cb
,
761 * Set the NSView handler where the media player should render its video output.
763 * Use the vout called "macosx".
765 * The drawable is an NSObject that follow the VLCVideoViewEmbedding
769 * @protocol VLCVideoViewEmbedding <NSObject>
770 * - (void)addVoutSubview:(NSView *)view;
771 * - (void)removeVoutSubview:(NSView *)view;
775 * Or it can be an NSView object.
777 * If you want to use it along with Qt see the QMacCocoaViewContainer. Then
778 * the following code should work:
781 * NSView *video = [[NSView alloc] init];
782 * QMacCocoaViewContainer *container = new QMacCocoaViewContainer(video, parent);
783 * libvlc_media_player_set_nsobject(mp, video);
788 * You can find a live example in VLCVideoView in VLCKit.framework.
790 * \param p_mi the Media Player
791 * \param drawable the drawable that is either an NSView or an object following
792 * the VLCVideoViewEmbedding protocol.
794 LIBVLC_API
void libvlc_media_player_set_nsobject ( libvlc_media_player_t
*p_mi
, void * drawable
);
797 * Get the NSView handler previously set with libvlc_media_player_set_nsobject().
799 * \param p_mi the Media Player
800 * \return the NSView handler or 0 if none where set
802 LIBVLC_API
void * libvlc_media_player_get_nsobject ( libvlc_media_player_t
*p_mi
);
805 * Set an X Window System drawable where the media player should render its
806 * video output. The call takes effect when the playback starts. If it is
807 * already started, it might need to be stopped before changes apply.
808 * If LibVLC was built without X11 output support, then this function has no
811 * By default, LibVLC will capture input events on the video rendering area.
812 * Use libvlc_video_set_mouse_input() and libvlc_video_set_key_input() to
813 * disable that and deliver events to the parent window / to the application
814 * instead. By design, the X11 protocol delivers input events to only one
818 * The application must call the XInitThreads() function from Xlib before
819 * libvlc_new(), and before any call to XOpenDisplay() directly or via any
820 * other library. Failure to call XInitThreads() will seriously impede LibVLC
821 * performance. Calling XOpenDisplay() before XInitThreads() will eventually
822 * crash the process. That is a limitation of Xlib.
824 * \param p_mi media player
825 * \param drawable X11 window ID
828 * The specified identifier must correspond to an existing Input/Output class
829 * X11 window. Pixmaps are <b>not</b> currently supported. The default X11
830 * server is assumed, i.e. that specified in the DISPLAY environment variable.
833 * LibVLC can deal with invalid X11 handle errors, however some display drivers
834 * (EGL, GLX, VA and/or VDPAU) can unfortunately not. Thus the window handle
835 * must remain valid until playback is stopped, otherwise the process may
839 * No more than one window handle per media player instance can be specified.
840 * If the media has multiple simultaneously active video tracks, extra tracks
841 * will be rendered into external windows beyond the control of the
844 LIBVLC_API
void libvlc_media_player_set_xwindow(libvlc_media_player_t
*p_mi
,
848 * Get the X Window System window identifier previously set with
849 * libvlc_media_player_set_xwindow(). Note that this will return the identifier
850 * even if VLC is not currently using it (for instance if it is playing an
853 * \param p_mi the Media Player
854 * \return an X window ID, or 0 if none where set.
856 LIBVLC_API
uint32_t libvlc_media_player_get_xwindow ( libvlc_media_player_t
*p_mi
);
859 * Set a Win32/Win64 API window handle (HWND) where the media player should
860 * render its video output. If LibVLC was built without Win32/Win64 API output
861 * support, then this has no effects.
863 * \param p_mi the Media Player
864 * \param drawable windows handle of the drawable
866 LIBVLC_API
void libvlc_media_player_set_hwnd ( libvlc_media_player_t
*p_mi
, void *drawable
);
869 * Get the Windows API window handle (HWND) previously set with
870 * libvlc_media_player_set_hwnd(). The handle will be returned even if LibVLC
871 * is not currently outputting any video to it.
873 * \param p_mi the Media Player
874 * \return a window handle or NULL if there are none.
876 LIBVLC_API
void *libvlc_media_player_get_hwnd ( libvlc_media_player_t
*p_mi
);
879 * Set the android context.
881 * \version LibVLC 3.0.0 and later.
883 * \param p_mi the media player
884 * \param p_awindow_handler org.videolan.libvlc.AWindow jobject owned by the
885 * org.videolan.libvlc.MediaPlayer class from the libvlc-android project.
887 LIBVLC_API
void libvlc_media_player_set_android_context( libvlc_media_player_t
*p_mi
,
888 void *p_awindow_handler
);
891 * Callback prototype for audio playback.
893 * The LibVLC media player decodes and post-processes the audio signal
894 * asynchronously (in an internal thread). Whenever audio samples are ready
895 * to be queued to the output, this callback is invoked.
897 * The number of samples provided per invocation may depend on the file format,
898 * the audio coding algorithm, the decoder plug-in, the post-processing
899 * filters and timing. Application must not assume a certain number of samples.
901 * The exact format of audio samples is determined by libvlc_audio_set_format()
902 * or libvlc_audio_set_format_callbacks() as is the channels layout.
904 * Note that the number of samples is per channel. For instance, if the audio
905 * track sampling rate is 48000 Hz, then 1200 samples represent 25 milliseconds
906 * of audio signal - regardless of the number of audio channels.
908 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
909 * \param samples pointer to a table of audio samples to play back [IN]
910 * \param count number of audio samples to play back
911 * \param pts expected play time stamp (see libvlc_delay())
913 typedef void (*libvlc_audio_play_cb
)(void *data
, const void *samples
,
914 unsigned count
, int64_t pts
);
917 * Callback prototype for audio pause.
919 * LibVLC invokes this callback to pause audio playback.
921 * \note The pause callback is never called if the audio is already paused.
922 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
923 * \param pts time stamp of the pause request (should be elapsed already)
925 typedef void (*libvlc_audio_pause_cb
)(void *data
, int64_t pts
);
928 * Callback prototype for audio resumption.
930 * LibVLC invokes this callback to resume audio playback after it was
933 * \note The resume callback is never called if the audio is not paused.
934 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
935 * \param pts time stamp of the resumption request (should be elapsed already)
937 typedef void (*libvlc_audio_resume_cb
)(void *data
, int64_t pts
);
940 * Callback prototype for audio buffer flush.
942 * LibVLC invokes this callback if it needs to discard all pending buffers and
943 * stop playback as soon as possible. This typically occurs when the media is
946 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
948 typedef void (*libvlc_audio_flush_cb
)(void *data
, int64_t pts
);
951 * Callback prototype for audio buffer drain.
953 * LibVLC may invoke this callback when the decoded audio track is ending.
954 * There will be no further decoded samples for the track, but playback should
955 * nevertheless continue until all already pending buffers are rendered.
957 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
959 typedef void (*libvlc_audio_drain_cb
)(void *data
);
962 * Callback prototype for audio volume change.
963 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
964 * \param volume software volume (1. = nominal, 0. = mute)
965 * \param mute muted flag
967 typedef void (*libvlc_audio_set_volume_cb
)(void *data
,
968 float volume
, bool mute
);
971 * Sets callbacks and private data for decoded audio.
973 * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks()
974 * to configure the decoded audio format.
976 * \note The audio callbacks override any other audio output mechanism.
977 * If the callbacks are set, LibVLC will <b>not</b> output audio in any way.
979 * \param mp the media player
980 * \param play callback to play audio samples (must not be NULL)
981 * \param pause callback to pause playback (or NULL to ignore)
982 * \param resume callback to resume playback (or NULL to ignore)
983 * \param flush callback to flush audio buffers (or NULL to ignore)
984 * \param drain callback to drain audio buffers (or NULL to ignore)
985 * \param opaque private pointer for the audio callbacks (as first parameter)
986 * \version LibVLC 2.0.0 or later
989 void libvlc_audio_set_callbacks( libvlc_media_player_t
*mp
,
990 libvlc_audio_play_cb play
,
991 libvlc_audio_pause_cb pause
,
992 libvlc_audio_resume_cb resume
,
993 libvlc_audio_flush_cb flush
,
994 libvlc_audio_drain_cb drain
,
998 * Set callbacks and private data for decoded audio. This only works in
999 * combination with libvlc_audio_set_callbacks().
1000 * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks()
1001 * to configure the decoded audio format.
1003 * \param mp the media player
1004 * \param set_volume callback to apply audio volume,
1005 * or NULL to apply volume in software
1006 * \version LibVLC 2.0.0 or later
1009 void libvlc_audio_set_volume_callback( libvlc_media_player_t
*mp
,
1010 libvlc_audio_set_volume_cb set_volume
);
1013 * Callback prototype to setup the audio playback.
1015 * This is called when the media player needs to create a new audio output.
1016 * \param opaque pointer to the data pointer passed to
1017 * libvlc_audio_set_callbacks() [IN/OUT]
1018 * \param format 4 bytes sample format [IN/OUT]
1019 * \param rate sample rate [IN/OUT]
1020 * \param channels channels count [IN/OUT]
1021 * \return 0 on success, anything else to skip audio playback
1023 typedef int (*libvlc_audio_setup_cb
)(void **opaque
, char *format
, unsigned *rate
,
1024 unsigned *channels
);
1027 * Callback prototype for audio playback cleanup.
1029 * This is called when the media player no longer needs an audio output.
1030 * \param opaque data pointer as passed to libvlc_audio_set_callbacks() [IN]
1032 typedef void (*libvlc_audio_cleanup_cb
)(void *data
);
1035 * Sets decoded audio format via callbacks.
1037 * This only works in combination with libvlc_audio_set_callbacks().
1039 * \param mp the media player
1040 * \param setup callback to select the audio format (cannot be NULL)
1041 * \param cleanup callback to release any allocated resources (or NULL)
1042 * \version LibVLC 2.0.0 or later
1045 void libvlc_audio_set_format_callbacks( libvlc_media_player_t
*mp
,
1046 libvlc_audio_setup_cb setup
,
1047 libvlc_audio_cleanup_cb cleanup
);
1050 * Sets a fixed decoded audio format.
1052 * This only works in combination with libvlc_audio_set_callbacks(),
1053 * and is mutually exclusive with libvlc_audio_set_format_callbacks().
1055 * \param mp the media player
1056 * \param format a four-characters string identifying the sample format
1057 * (e.g. "S16N" or "f32l")
1058 * \param rate sample rate (expressed in Hz)
1059 * \param channels channels count
1060 * \version LibVLC 2.0.0 or later
1063 void libvlc_audio_set_format( libvlc_media_player_t
*mp
, const char *format
,
1064 unsigned rate
, unsigned channels
);
1066 /** \bug This might go away ... to be replaced by a broader system */
1069 * Get the current movie length (in ms).
1071 * \param p_mi the Media Player
1072 * \return the movie length (in ms), or -1 if there is no media.
1074 LIBVLC_API libvlc_time_t
libvlc_media_player_get_length( libvlc_media_player_t
*p_mi
);
1077 * Get the current movie time (in ms).
1079 * \param p_mi the Media Player
1080 * \return the movie time (in ms), or -1 if there is no media.
1082 LIBVLC_API libvlc_time_t
libvlc_media_player_get_time( libvlc_media_player_t
*p_mi
);
1085 * Set the movie time (in ms). This has no effect if no media is being played.
1086 * Not all formats and protocols support this.
1088 * \param p_mi the Media Player
1089 * \param b_fast prefer fast seeking or precise seeking
1090 * \param i_time the movie time (in ms).
1091 * \return 0 on success, -1 on error
1093 LIBVLC_API
int libvlc_media_player_set_time( libvlc_media_player_t
*p_mi
,
1094 libvlc_time_t i_time
, bool b_fast
);
1097 * Get movie position as percentage between 0.0 and 1.0.
1099 * \param p_mi the Media Player
1100 * \return movie position, or -1. in case of error
1102 LIBVLC_API
float libvlc_media_player_get_position( libvlc_media_player_t
*p_mi
);
1105 * Set movie position as percentage between 0.0 and 1.0.
1106 * This has no effect if playback is not enabled.
1107 * This might not work depending on the underlying input format and protocol.
1109 * \param p_mi the Media Player
1110 * \param b_fast prefer fast seeking or precise seeking
1111 * \param f_pos the position
1112 * \return 0 on success, -1 on error
1114 LIBVLC_API
int libvlc_media_player_set_position( libvlc_media_player_t
*p_mi
,
1115 float f_pos
, bool b_fast
);
1118 * Set movie chapter (if applicable).
1120 * \param p_mi the Media Player
1121 * \param i_chapter chapter number to play
1123 LIBVLC_API
void libvlc_media_player_set_chapter( libvlc_media_player_t
*p_mi
, int i_chapter
);
1126 * Get movie chapter.
1128 * \param p_mi the Media Player
1129 * \return chapter number currently playing, or -1 if there is no media.
1131 LIBVLC_API
int libvlc_media_player_get_chapter( libvlc_media_player_t
*p_mi
);
1134 * Get movie chapter count
1136 * \param p_mi the Media Player
1137 * \return number of chapters in movie, or -1.
1139 LIBVLC_API
int libvlc_media_player_get_chapter_count( libvlc_media_player_t
*p_mi
);
1142 * Get title chapter count
1144 * \param p_mi the Media Player
1145 * \param i_title title
1146 * \return number of chapters in title, or -1
1148 LIBVLC_API
int libvlc_media_player_get_chapter_count_for_title(
1149 libvlc_media_player_t
*p_mi
, int i_title
);
1154 * \param p_mi the Media Player
1155 * \param i_title title number to play
1157 LIBVLC_API
void libvlc_media_player_set_title( libvlc_media_player_t
*p_mi
, int i_title
);
1162 * \param p_mi the Media Player
1163 * \return title number currently playing, or -1
1165 LIBVLC_API
int libvlc_media_player_get_title( libvlc_media_player_t
*p_mi
);
1168 * Get movie title count
1170 * \param p_mi the Media Player
1171 * \return title number count, or -1
1173 LIBVLC_API
int libvlc_media_player_get_title_count( libvlc_media_player_t
*p_mi
);
1176 * Set previous chapter (if applicable)
1178 * \param p_mi the Media Player
1180 LIBVLC_API
void libvlc_media_player_previous_chapter( libvlc_media_player_t
*p_mi
);
1183 * Set next chapter (if applicable)
1185 * \param p_mi the Media Player
1187 LIBVLC_API
void libvlc_media_player_next_chapter( libvlc_media_player_t
*p_mi
);
1190 * Get the requested movie play rate.
1191 * @warning Depending on the underlying media, the requested rate may be
1192 * different from the real playback rate.
1194 * \param p_mi the Media Player
1195 * \return movie play rate
1197 LIBVLC_API
float libvlc_media_player_get_rate( libvlc_media_player_t
*p_mi
);
1200 * Set movie play rate
1202 * \param p_mi the Media Player
1203 * \param rate movie play rate to set
1204 * \return -1 if an error was detected, 0 otherwise (but even then, it might
1205 * not actually work depending on the underlying media protocol)
1207 LIBVLC_API
int libvlc_media_player_set_rate( libvlc_media_player_t
*p_mi
, float rate
);
1210 * Get current movie state
1212 * \param p_mi the Media Player
1213 * \return the current state of the media player (playing, paused, ...) \see libvlc_state_t
1215 LIBVLC_API libvlc_state_t
libvlc_media_player_get_state( libvlc_media_player_t
*p_mi
);
1218 * How many video outputs does this media player have?
1220 * \param p_mi the media player
1221 * \return the number of video outputs
1223 LIBVLC_API
unsigned libvlc_media_player_has_vout( libvlc_media_player_t
*p_mi
);
1226 * Is this media player seekable?
1228 * \param p_mi the media player
1229 * \retval true media player can seek
1230 * \retval false media player cannot seek
1232 LIBVLC_API
bool libvlc_media_player_is_seekable(libvlc_media_player_t
*p_mi
);
1235 * Can this media player be paused?
1237 * \param p_mi the media player
1238 * \retval true media player can be paused
1239 * \retval false media player cannot be paused
1241 LIBVLC_API
bool libvlc_media_player_can_pause(libvlc_media_player_t
*p_mi
);
1244 * Check if the current program is scrambled
1246 * \param p_mi the media player
1247 * \retval true current program is scrambled
1248 * \retval false current program is not scrambled
1250 * \version LibVLC 2.2.0 or later
1252 LIBVLC_API
bool libvlc_media_player_program_scrambled( libvlc_media_player_t
*p_mi
);
1255 * Display the next frame (if supported)
1257 * \param p_mi the media player
1259 LIBVLC_API
void libvlc_media_player_next_frame( libvlc_media_player_t
*p_mi
);
1262 * Navigate through DVD Menu
1264 * \param p_mi the Media Player
1265 * \param navigate the Navigation mode
1266 * \version libVLC 2.0.0 or later
1268 LIBVLC_API
void libvlc_media_player_navigate( libvlc_media_player_t
* p_mi
,
1269 unsigned navigate
);
1272 * Set if, and how, the video title will be shown when media is played.
1274 * \param p_mi the media player
1275 * \param position position at which to display the title, or libvlc_position_disable to prevent the title from being displayed
1276 * \param timeout title display timeout in milliseconds (ignored if libvlc_position_disable)
1277 * \version libVLC 2.1.0 or later
1279 LIBVLC_API
void libvlc_media_player_set_video_title_display( libvlc_media_player_t
*p_mi
, libvlc_position_t position
, unsigned int timeout
);
1282 * Get the track list for one type
1284 * \version LibVLC 4.0.0 and later.
1286 * \note You need to call libvlc_media_parse_with_options() or play the media
1287 * at least once before calling this function. Not doing this will result in
1290 * \note This track list is a snapshot of the current tracks when this function
1291 * is called. If a track is updated after this call, the user will need to call
1292 * this function again to get the updated track.
1295 * The track list can be used to get track informations and to select specific
1298 * \param p_mi the media player
1299 * \param type type of the track list to request
1301 * \return a valid libvlc_media_tracklist_t or NULL in case of error, if there
1302 * is no track for a category, the returned list will have a size of 0, delete
1303 * with libvlc_media_tracklist_delete()
1305 LIBVLC_API libvlc_media_tracklist_t
*
1306 libvlc_media_player_get_tracklist( libvlc_media_player_t
*p_mi
,
1307 libvlc_track_type_t type
);
1311 * Get the selected track for one type
1313 * \version LibVLC 4.0.0 and later.
1315 * \warning More than one tracks can be selected for one type. In that case,
1316 * libvlc_media_player_get_tracklist() should be used.
1318 * \param p_mi the media player
1319 * \param type type of the selected track
1321 * \return a valid track or NULL if there is no selected tracks for this type,
1322 * release it with libvlc_media_track_release().
1324 LIBVLC_API libvlc_media_track_t
*
1325 libvlc_media_player_get_selected_track( libvlc_media_player_t
*p_mi
,
1326 libvlc_track_type_t type
);
1329 * Get a track from a track id
1331 * \version LibVLC 4.0.0 and later.
1333 * This function can be used to get the last updated informations of a track.
1335 * \param p_mi the media player
1336 * \param psz_id valid string representing a track id (cf. psz_id from \ref
1337 * libvlc_media_track_t)
1339 * \return a valid track or NULL if there is currently no tracks identified by
1340 * the string id, release it with libvlc_media_track_release().
1342 LIBVLC_API libvlc_media_track_t
*
1343 libvlc_media_player_get_track_from_id( libvlc_media_player_t
*p_mi
,
1344 const char *psz_id
);
1348 * Select a track or unselect all tracks for one type
1350 * \version LibVLC 4.0.0 and later.
1352 * \note Use libvlc_media_player_select_tracks() for multiple selection
1354 * \param p_mi the media player
1355 * \param type type of the selected track
1356 * \param track track to select or NULL to unselect all tracks of for this type
1359 libvlc_media_player_select_track( libvlc_media_player_t
*p_mi
,
1360 libvlc_track_type_t type
,
1361 const libvlc_media_track_t
*track
);
1364 * Select multiple tracks for one type
1366 * \version LibVLC 4.0.0 and later.
1368 * \note The internal track list can change between the calls of
1369 * libvlc_media_player_get_tracklist() and
1370 * libvlc_media_player_set_tracks(). If a track selection change but the
1371 * track is not present anymore, the player will just ignore it.
1373 * \note selecting multiple audio tracks is currently not supported.
1375 * \param p_mi the media player
1376 * \param type type of the selected track
1377 * \param tracks pointer to the track array
1378 * \param track_count number of tracks in the track array
1381 libvlc_media_player_select_tracks( libvlc_media_player_t
*p_mi
,
1382 libvlc_track_type_t type
,
1383 const libvlc_media_track_t
**tracks
,
1384 size_t track_count
);
1387 * Select tracks by their string identifier
1389 * \version LibVLC 4.0.0 and later.
1391 * This function can be used pre-select a list of tracks before starting the
1392 * player. It has only effect for the current media. It can also be used when
1393 * the player is already started.
1395 * 'str_ids' can contain more than one track id, delimited with ','. "" or any
1396 * invalid track id will cause the player to unselect all tracks of that
1397 * category. NULL will disable the preference for newer tracks without
1398 * unselecting any current tracks.
1401 * - (libvlc_track_video, "video/1,video/2") will select these 2 video tracks.
1402 * If there is only one video track with the id "video/0", no tracks will be
1404 * - (libvlc_track_type_t, "${slave_url_md5sum}/spu/0) will select one spu
1405 * added by an input slave with the corresponding url.
1407 * \note The string identifier of a track can be found via psz_id from \ref
1408 * libvlc_media_track_t
1410 * \note selecting multiple audio tracks is currently not supported.
1412 * \param p_mi the media player
1413 * \param type type to select
1414 * \param psz_ids list of string identifier or NULL
1417 libvlc_media_player_select_tracks_by_ids( libvlc_media_player_t
*p_mi
,
1418 libvlc_track_type_t type
,
1419 const char *psz_ids
);
1422 * Add a slave to the current media player.
1424 * \note If the player is playing, the slave will be added directly. This call
1425 * will also update the slave list of the attached libvlc_media_t.
1427 * \version LibVLC 3.0.0 and later.
1429 * \see libvlc_media_slaves_add
1431 * \param p_mi the media player
1432 * \param i_type subtitle or audio
1433 * \param psz_uri Uri of the slave (should contain a valid scheme).
1434 * \param b_select True if this slave should be selected when it's loaded
1436 * \return 0 on success, -1 on error.
1439 int libvlc_media_player_add_slave( libvlc_media_player_t
*p_mi
,
1440 libvlc_media_slave_type_t i_type
,
1441 const char *psz_uri
, bool b_select
);
1443 /** \defgroup libvlc_video LibVLC video controls
1448 * Toggle fullscreen status on non-embedded video outputs.
1450 * @warning The same limitations applies to this function
1451 * as to libvlc_set_fullscreen().
1453 * \param p_mi the media player
1455 LIBVLC_API
void libvlc_toggle_fullscreen( libvlc_media_player_t
*p_mi
);
1458 * Enable or disable fullscreen.
1460 * @warning With most window managers, only a top-level windows can be in
1461 * full-screen mode. Hence, this function will not operate properly if
1462 * libvlc_media_player_set_xwindow() was used to embed the video in a
1463 * non-top-level window. In that case, the embedding window must be reparented
1464 * to the root window <b>before</b> fullscreen mode is enabled. You will want
1465 * to reparent it back to its normal parent when disabling fullscreen.
1467 * \note This setting applies to any and all current or future active video
1468 * tracks and windows for the given media player. The choice of fullscreen
1469 * output for each window is left to the operating system.
1471 * \param p_mi the media player
1472 * \param b_fullscreen boolean for fullscreen status
1474 LIBVLC_API
void libvlc_set_fullscreen(libvlc_media_player_t
*p_mi
, bool b_fullscreen
);
1477 * Get current fullscreen status.
1479 * \param p_mi the media player
1480 * \return the fullscreen status (boolean)
1482 * \retval false media player is windowed
1483 * \retval true media player is in fullscreen mode
1485 LIBVLC_API
bool libvlc_get_fullscreen( libvlc_media_player_t
*p_mi
);
1488 * Enable or disable key press events handling, according to the LibVLC hotkeys
1489 * configuration. By default and for historical reasons, keyboard events are
1490 * handled by the LibVLC video widget.
1492 * \note On X11, there can be only one subscriber for key press and mouse
1493 * click events per window. If your application has subscribed to those events
1494 * for the X window ID of the video widget, then LibVLC will not be able to
1495 * handle key presses and mouse clicks in any case.
1497 * \warning This function is only implemented for X11 and Win32 at the moment.
1499 * \param p_mi the media player
1500 * \param on true to handle key press events, false to ignore them.
1503 void libvlc_video_set_key_input( libvlc_media_player_t
*p_mi
, unsigned on
);
1506 * Enable or disable mouse click events handling. By default, those events are
1507 * handled. This is needed for DVD menus to work, as well as a few video
1508 * filters such as "puzzle".
1510 * \see libvlc_video_set_key_input().
1512 * \warning This function is only implemented for X11 and Win32 at the moment.
1514 * \param p_mi the media player
1515 * \param on true to handle mouse click events, false to ignore them.
1518 void libvlc_video_set_mouse_input( libvlc_media_player_t
*p_mi
, unsigned on
);
1521 * Get the pixel dimensions of a video.
1523 * \param p_mi media player
1524 * \param num number of the video (starting from, and most commonly 0)
1525 * \param px pointer to get the pixel width [OUT]
1526 * \param py pointer to get the pixel height [OUT]
1527 * \return 0 on success, -1 if the specified video does not exist
1530 int libvlc_video_get_size( libvlc_media_player_t
*p_mi
, unsigned num
,
1531 unsigned *px
, unsigned *py
);
1534 * Get the mouse pointer coordinates over a video.
1535 * Coordinates are expressed in terms of the decoded video resolution,
1536 * <b>not</b> in terms of pixels on the screen/viewport (to get the latter,
1537 * you can query your windowing system directly).
1539 * Either of the coordinates may be negative or larger than the corresponding
1540 * dimension of the video, if the cursor is outside the rendering area.
1542 * @warning The coordinates may be out-of-date if the pointer is not located
1543 * on the video rendering area. LibVLC does not track the pointer if it is
1544 * outside of the video widget.
1546 * @note LibVLC does not support multiple pointers (it does of course support
1547 * multiple input devices sharing the same pointer) at the moment.
1549 * \param p_mi media player
1550 * \param num number of the video (starting from, and most commonly 0)
1551 * \param px pointer to get the abscissa [OUT]
1552 * \param py pointer to get the ordinate [OUT]
1553 * \return 0 on success, -1 if the specified video does not exist
1556 int libvlc_video_get_cursor( libvlc_media_player_t
*p_mi
, unsigned num
,
1560 * Get the current video scaling factor.
1561 * See also libvlc_video_set_scale().
1563 * \param p_mi the media player
1564 * \return the currently configured zoom factor, or 0. if the video is set
1565 * to fit to the output window/drawable automatically.
1567 LIBVLC_API
float libvlc_video_get_scale( libvlc_media_player_t
*p_mi
);
1570 * Set the video scaling factor. That is the ratio of the number of pixels on
1571 * screen to the number of pixels in the original decoded video in each
1572 * dimension. Zero is a special value; it will adjust the video to the output
1573 * window/drawable (in windowed mode) or the entire screen.
1575 * Note that not all video outputs support scaling.
1577 * \param p_mi the media player
1578 * \param f_factor the scaling factor, or zero
1580 LIBVLC_API
void libvlc_video_set_scale( libvlc_media_player_t
*p_mi
, float f_factor
);
1583 * Get current video aspect ratio.
1585 * \param p_mi the media player
1586 * \return the video aspect ratio or NULL if unspecified
1587 * (the result must be released with free() or libvlc_free()).
1589 LIBVLC_API
char *libvlc_video_get_aspect_ratio( libvlc_media_player_t
*p_mi
);
1592 * Set new video aspect ratio.
1594 * \param p_mi the media player
1595 * \param psz_aspect new video aspect-ratio or NULL to reset to default
1596 * \note Invalid aspect ratios are ignored.
1598 LIBVLC_API
void libvlc_video_set_aspect_ratio( libvlc_media_player_t
*p_mi
, const char *psz_aspect
);
1601 * Create a video viewpoint structure.
1603 * \version LibVLC 3.0.0 and later
1605 * \return video viewpoint or NULL
1606 * (the result must be released with free()).
1608 LIBVLC_API libvlc_video_viewpoint_t
*libvlc_video_new_viewpoint(void);
1611 * Update the video viewpoint information.
1613 * \note It is safe to call this function before the media player is started.
1615 * \version LibVLC 3.0.0 and later
1617 * \param p_mi the media player
1618 * \param p_viewpoint video viewpoint allocated via libvlc_video_new_viewpoint()
1619 * \param b_absolute if true replace the old viewpoint with the new one. If
1620 * false, increase/decrease it.
1621 * \return -1 in case of error, 0 otherwise
1623 * \note the values are set asynchronously, it will be used by the next frame displayed.
1625 LIBVLC_API
int libvlc_video_update_viewpoint( libvlc_media_player_t
*p_mi
,
1626 const libvlc_video_viewpoint_t
*p_viewpoint
,
1630 * Get the current subtitle delay. Positive values means subtitles are being
1631 * displayed later, negative values earlier.
1633 * \param p_mi media player
1634 * \return time (in microseconds) the display of subtitles is being delayed
1635 * \version LibVLC 2.0.0 or later
1637 LIBVLC_API
int64_t libvlc_video_get_spu_delay( libvlc_media_player_t
*p_mi
);
1640 * Set the subtitle text scale.
1642 * The scale factor is expressed as a percentage of the default size, where
1643 * 1.0 represents 100 percent.
1645 * A value of 0.5 would result in text half the normal size, and a value of 2.0
1646 * would result in text twice the normal size.
1648 * The minimum acceptable value for the scale factor is 0.1.
1650 * The maximum is 5.0 (five times normal size).
1652 * \param p_mi media player
1653 * \param f_scale scale factor in the range [0.1;5.0] (default: 1.0)
1654 * \version LibVLC 4.0.0 or later
1656 LIBVLC_API
void libvlc_video_set_spu_text_scale( libvlc_media_player_t
*p_mi
, float f_scale
);
1659 * Set the subtitle delay. This affects the timing of when the subtitle will
1660 * be displayed. Positive values result in subtitles being displayed later,
1661 * while negative values will result in subtitles being displayed earlier.
1663 * The subtitle delay will be reset to zero each time the media changes.
1665 * \param p_mi media player
1666 * \param i_delay time (in microseconds) the display of subtitles should be delayed
1667 * \return 0 on success, -1 on error
1668 * \version LibVLC 2.0.0 or later
1670 LIBVLC_API
int libvlc_video_set_spu_delay( libvlc_media_player_t
*p_mi
, int64_t i_delay
);
1673 * Get the full description of available titles
1675 * \version LibVLC 3.0.0 and later.
1677 * \param p_mi the media player
1678 * \param titles address to store an allocated array of title descriptions
1679 * descriptions (must be freed with libvlc_title_descriptions_release()
1680 * by the caller) [OUT]
1682 * \return the number of titles (-1 on error)
1684 LIBVLC_API
int libvlc_media_player_get_full_title_descriptions( libvlc_media_player_t
*p_mi
,
1685 libvlc_title_description_t
***titles
);
1688 * Release a title description
1690 * \version LibVLC 3.0.0 and later
1692 * \param p_titles title description array to release
1693 * \param i_count number of title descriptions to release
1696 void libvlc_title_descriptions_release( libvlc_title_description_t
**p_titles
,
1700 * Get the full description of available chapters
1702 * \version LibVLC 3.0.0 and later.
1704 * \param p_mi the media player
1705 * \param i_chapters_of_title index of the title to query for chapters (uses current title if set to -1)
1706 * \param pp_chapters address to store an allocated array of chapter descriptions
1707 * descriptions (must be freed with libvlc_chapter_descriptions_release()
1708 * by the caller) [OUT]
1710 * \return the number of chapters (-1 on error)
1712 LIBVLC_API
int libvlc_media_player_get_full_chapter_descriptions( libvlc_media_player_t
*p_mi
,
1713 int i_chapters_of_title
,
1714 libvlc_chapter_description_t
*** pp_chapters
);
1717 * Release a chapter description
1719 * \version LibVLC 3.0.0 and later
1721 * \param p_chapters chapter description array to release
1722 * \param i_count number of chapter descriptions to release
1725 void libvlc_chapter_descriptions_release( libvlc_chapter_description_t
**p_chapters
,
1729 * Set/unset the video crop ratio.
1731 * This function forces a crop ratio on any and all video tracks rendered by
1732 * the media player. If the display aspect ratio of a video does not match the
1733 * crop ratio, either the top and bottom, or the left and right of the video
1734 * will be cut out to fit the crop ratio.
1736 * For instance, a ratio of 1:1 will force the video to a square shape.
1738 * To disable video crop, set a crop ratio with zero as denominator.
1740 * A call to this function overrides any previous call to any of
1741 * libvlc_video_set_crop_ratio(), libvlc_video_set_crop_border() and/or
1742 * libvlc_video_set_crop_window().
1744 * \see libvlc_video_set_aspect_ratio()
1746 * \param mp the media player
1747 * \param num crop ratio numerator (ignored if denominator is 0)
1748 * \param den crop ratio denominator (or 0 to unset the crop ratio)
1750 * \version LibVLC 4.0.0 and later
1753 void libvlc_video_set_crop_ratio(libvlc_media_player_t
*mp
,
1754 unsigned num
, unsigned den
);
1757 * Set the video crop window.
1759 * This function selects a sub-rectangle of video to show. Any pixels outside
1760 * the rectangle will not be shown.
1762 * To unset the video crop window, use libvlc_video_set_crop_ratio() or
1763 * libvlc_video_set_crop_border().
1765 * A call to this function overrides any previous call to any of
1766 * libvlc_video_set_crop_ratio(), libvlc_video_set_crop_border() and/or
1767 * libvlc_video_set_crop_window().
1769 * \param mp the media player
1770 * \param x abscissa (i.e. leftmost sample column offset) of the crop window
1771 * \param y ordinate (i.e. topmost sample row offset) of the crop window
1772 * \param width sample width of the crop window (cannot be zero)
1773 * \param height sample height of the crop window (cannot be zero)
1775 * \version LibVLC 4.0.0 and later
1778 void libvlc_video_set_crop_window(libvlc_media_player_t
*mp
,
1779 unsigned x
, unsigned y
,
1780 unsigned width
, unsigned height
);
1783 * Set the video crop borders.
1785 * This function selects the size of video edges to be cropped out.
1787 * To unset the video crop borders, set all borders to zero.
1789 * A call to this function overrides any previous call to any of
1790 * libvlc_video_set_crop_ratio(), libvlc_video_set_crop_border() and/or
1791 * libvlc_video_set_crop_window().
1793 * \param mp the media player
1794 * \param left number of sample columns to crop on the left
1795 * \param right number of sample columns to crop on the right
1796 * \param top number of sample rows to crop on the top
1797 * \param bottom number of sample rows to corp on the bottom
1799 * \version LibVLC 4.0.0 and later
1802 void libvlc_video_set_crop_border(libvlc_media_player_t
*mp
,
1803 unsigned left
, unsigned right
,
1804 unsigned top
, unsigned bottom
);
1807 * Get current teletext page requested or 0 if it's disabled.
1809 * Teletext is disabled by default, call libvlc_video_set_teletext() to enable
1812 * \param p_mi the media player
1813 * \return the current teletext page requested.
1815 LIBVLC_API
int libvlc_video_get_teletext( libvlc_media_player_t
*p_mi
);
1818 * Set new teletext page to retrieve.
1820 * This function can also be used to send a teletext key.
1822 * \param p_mi the media player
1823 * \param i_page teletex page number requested. This value can be 0 to disable
1824 * teletext, a number in the range ]0;1000[ to show the requested page, or a
1825 * \ref libvlc_teletext_key_t. 100 is the default teletext page.
1827 LIBVLC_API
void libvlc_video_set_teletext( libvlc_media_player_t
*p_mi
, int i_page
);
1830 * Take a snapshot of the current video window.
1832 * If i_width AND i_height is 0, original size is used.
1833 * If i_width XOR i_height is 0, original aspect-ratio is preserved.
1835 * \param p_mi media player instance
1836 * \param num number of video output (typically 0 for the first/only one)
1837 * \param psz_filepath the path of a file or a folder to save the screenshot into
1838 * \param i_width the snapshot's width
1839 * \param i_height the snapshot's height
1840 * \return 0 on success, -1 if the video was not found
1843 int libvlc_video_take_snapshot( libvlc_media_player_t
*p_mi
, unsigned num
,
1844 const char *psz_filepath
, unsigned int i_width
,
1845 unsigned int i_height
);
1848 * Enable or disable deinterlace filter
1850 * \param p_mi libvlc media player
1851 * \param deinterlace state -1: auto (default), 0: disabled, 1: enabled
1852 * \param psz_mode type of deinterlace filter, NULL for current/default filter
1853 * \version LibVLC 4.0.0 and later
1855 LIBVLC_API
void libvlc_video_set_deinterlace( libvlc_media_player_t
*p_mi
,
1857 const char *psz_mode
);
1860 * Get an integer marquee option value
1862 * \param p_mi libvlc media player
1863 * \param option marq option to get \see libvlc_video_marquee_option_t
1865 LIBVLC_API
int libvlc_video_get_marquee_int( libvlc_media_player_t
*p_mi
,
1869 * Enable, disable or set an integer marquee option
1871 * Setting libvlc_marquee_Enable has the side effect of enabling (arg !0)
1872 * or disabling (arg 0) the marq filter.
1874 * \param p_mi libvlc media player
1875 * \param option marq option to set \see libvlc_video_marquee_option_t
1876 * \param i_val marq option value
1878 LIBVLC_API
void libvlc_video_set_marquee_int( libvlc_media_player_t
*p_mi
,
1879 unsigned option
, int i_val
);
1882 * Set a marquee string option
1884 * \param p_mi libvlc media player
1885 * \param option marq option to set \see libvlc_video_marquee_option_t
1886 * \param psz_text marq option value
1888 LIBVLC_API
void libvlc_video_set_marquee_string( libvlc_media_player_t
*p_mi
,
1889 unsigned option
, const char *psz_text
);
1891 /** option values for libvlc_video_{get,set}_logo_{int,string} */
1892 enum libvlc_video_logo_option_t
{
1894 libvlc_logo_file
, /**< string argument, "file,d,t;file,d,t;..." */
1899 libvlc_logo_opacity
,
1900 libvlc_logo_position
1904 * Get integer logo option.
1906 * \param p_mi libvlc media player instance
1907 * \param option logo option to get, values of libvlc_video_logo_option_t
1909 LIBVLC_API
int libvlc_video_get_logo_int( libvlc_media_player_t
*p_mi
,
1913 * Set logo option as integer. Options that take a different type value
1915 * Passing libvlc_logo_enable as option value has the side effect of
1916 * starting (arg !0) or stopping (arg 0) the logo filter.
1918 * \param p_mi libvlc media player instance
1919 * \param option logo option to set, values of libvlc_video_logo_option_t
1920 * \param value logo option value
1922 LIBVLC_API
void libvlc_video_set_logo_int( libvlc_media_player_t
*p_mi
,
1923 unsigned option
, int value
);
1926 * Set logo option as string. Options that take a different type value
1929 * \param p_mi libvlc media player instance
1930 * \param option logo option to set, values of libvlc_video_logo_option_t
1931 * \param psz_value logo option value
1933 LIBVLC_API
void libvlc_video_set_logo_string( libvlc_media_player_t
*p_mi
,
1934 unsigned option
, const char *psz_value
);
1937 /** option values for libvlc_video_{get,set}_adjust_{int,float,bool} */
1938 enum libvlc_video_adjust_option_t
{
1939 libvlc_adjust_Enable
= 0,
1940 libvlc_adjust_Contrast
,
1941 libvlc_adjust_Brightness
,
1943 libvlc_adjust_Saturation
,
1948 * Get integer adjust option.
1950 * \param p_mi libvlc media player instance
1951 * \param option adjust option to get, values of libvlc_video_adjust_option_t
1952 * \version LibVLC 1.1.1 and later.
1954 LIBVLC_API
int libvlc_video_get_adjust_int( libvlc_media_player_t
*p_mi
,
1958 * Set adjust option as integer. Options that take a different type value
1960 * Passing libvlc_adjust_enable as option value has the side effect of
1961 * starting (arg !0) or stopping (arg 0) the adjust filter.
1963 * \param p_mi libvlc media player instance
1964 * \param option adust option to set, values of libvlc_video_adjust_option_t
1965 * \param value adjust option value
1966 * \version LibVLC 1.1.1 and later.
1968 LIBVLC_API
void libvlc_video_set_adjust_int( libvlc_media_player_t
*p_mi
,
1969 unsigned option
, int value
);
1972 * Get float adjust option.
1974 * \param p_mi libvlc media player instance
1975 * \param option adjust option to get, values of libvlc_video_adjust_option_t
1976 * \version LibVLC 1.1.1 and later.
1978 LIBVLC_API
float libvlc_video_get_adjust_float( libvlc_media_player_t
*p_mi
,
1982 * Set adjust option as float. Options that take a different type value
1985 * \param p_mi libvlc media player instance
1986 * \param option adust option to set, values of libvlc_video_adjust_option_t
1987 * \param value adjust option value
1988 * \version LibVLC 1.1.1 and later.
1990 LIBVLC_API
void libvlc_video_set_adjust_float( libvlc_media_player_t
*p_mi
,
1991 unsigned option
, float value
);
1995 /** \defgroup libvlc_audio LibVLC audio controls
2002 typedef enum libvlc_audio_output_channel_t
{
2003 libvlc_AudioChannel_Error
= -1,
2004 libvlc_AudioChannel_Stereo
= 1,
2005 libvlc_AudioChannel_RStereo
= 2,
2006 libvlc_AudioChannel_Left
= 3,
2007 libvlc_AudioChannel_Right
= 4,
2008 libvlc_AudioChannel_Dolbys
= 5
2009 } libvlc_audio_output_channel_t
;
2013 * Gets the list of available audio output modules.
2015 * \param p_instance libvlc instance
2016 * \return list of available audio outputs. It must be freed with
2017 * \see libvlc_audio_output_list_release \see libvlc_audio_output_t .
2018 * In case of error, NULL is returned.
2020 LIBVLC_API libvlc_audio_output_t
*
2021 libvlc_audio_output_list_get( libvlc_instance_t
*p_instance
);
2024 * Frees the list of available audio output modules.
2026 * \param p_list list with audio outputs for release
2029 void libvlc_audio_output_list_release( libvlc_audio_output_t
*p_list
);
2032 * Selects an audio output module.
2033 * \note Any change will take be effect only after playback is stopped and
2034 * restarted. Audio output cannot be changed while playing.
2036 * \param p_mi media player
2037 * \param psz_name name of audio output,
2038 * use psz_name of \see libvlc_audio_output_t
2039 * \return 0 if function succeeded, -1 on error
2041 LIBVLC_API
int libvlc_audio_output_set( libvlc_media_player_t
*p_mi
,
2042 const char *psz_name
);
2045 * Gets a list of potential audio output devices,
2046 * \see libvlc_audio_output_device_set().
2048 * \note Not all audio outputs support enumerating devices.
2049 * The audio output may be functional even if the list is empty (NULL).
2051 * \note The list may not be exhaustive.
2053 * \warning Some audio output devices in the list might not actually work in
2054 * some circumstances. By default, it is recommended to not specify any
2055 * explicit audio device.
2057 * \param mp media player
2058 * \return A NULL-terminated linked list of potential audio output devices.
2059 * It must be freed with libvlc_audio_output_device_list_release()
2060 * \version LibVLC 2.2.0 or later.
2062 LIBVLC_API libvlc_audio_output_device_t
*
2063 libvlc_audio_output_device_enum( libvlc_media_player_t
*mp
);
2066 * Gets a list of audio output devices for a given audio output module,
2067 * \see libvlc_audio_output_device_set().
2069 * \note Not all audio outputs support this. In particular, an empty (NULL)
2070 * list of devices does <b>not</b> imply that the specified audio output does
2073 * \note The list might not be exhaustive.
2075 * \warning Some audio output devices in the list might not actually work in
2076 * some circumstances. By default, it is recommended to not specify any
2077 * explicit audio device.
2079 * \param p_instance libvlc instance
2080 * \param aout audio output name
2081 * (as returned by libvlc_audio_output_list_get())
2082 * \return A NULL-terminated linked list of potential audio output devices.
2083 * It must be freed with libvlc_audio_output_device_list_release()
2084 * \version LibVLC 2.1.0 or later.
2086 LIBVLC_API libvlc_audio_output_device_t
*
2087 libvlc_audio_output_device_list_get( libvlc_instance_t
*p_instance
,
2091 * Frees a list of available audio output devices.
2093 * \param p_list list with audio outputs for release
2094 * \version LibVLC 2.1.0 or later.
2096 LIBVLC_API
void libvlc_audio_output_device_list_release(
2097 libvlc_audio_output_device_t
*p_list
);
2100 * Configures an explicit audio output device.
2102 * If the module paramater is NULL, audio output will be moved to the device
2103 * specified by the device identifier string immediately. This is the
2104 * recommended usage.
2106 * A list of adequate potential device strings can be obtained with
2107 * libvlc_audio_output_device_enum().
2109 * However passing NULL is supported in LibVLC version 2.2.0 and later only;
2110 * in earlier versions, this function would have no effects when the module
2111 * parameter was NULL.
2113 * If the module parameter is not NULL, the device parameter of the
2114 * corresponding audio output, if it exists, will be set to the specified
2115 * string. Note that some audio output modules do not have such a parameter
2116 * (notably MMDevice and PulseAudio).
2118 * A list of adequate potential device strings can be obtained with
2119 * libvlc_audio_output_device_list_get().
2121 * \note This function does not select the specified audio output plugin.
2122 * libvlc_audio_output_set() is used for that purpose.
2124 * \warning The syntax for the device parameter depends on the audio output.
2126 * Some audio output modules require further parameters (e.g. a channels map
2127 * in the case of ALSA).
2129 * \param mp media player
2130 * \param module If NULL, current audio output module.
2131 * if non-NULL, name of audio output module
2132 (\see libvlc_audio_output_t)
2133 * \param device_id device identifier string
2134 * \return Nothing. Errors are ignored (this is a design bug).
2136 LIBVLC_API
void libvlc_audio_output_device_set( libvlc_media_player_t
*mp
,
2138 const char *device_id
);
2141 * Get the current audio output device identifier.
2143 * This complements libvlc_audio_output_device_set().
2145 * \warning The initial value for the current audio output device identifier
2146 * may not be set or may be some unknown value. A LibVLC application should
2147 * compare this value against the known device identifiers (e.g. those that
2148 * were previously retrieved by a call to libvlc_audio_output_device_enum or
2149 * libvlc_audio_output_device_list_get) to find the current audio output device.
2151 * It is possible that the selected audio output device changes (an external
2152 * change) without a call to libvlc_audio_output_device_set. That may make this
2153 * method unsuitable to use if a LibVLC application is attempting to track
2154 * dynamic audio device changes as they happen.
2156 * \param mp media player
2157 * \return the current audio output device identifier
2158 * NULL if no device is selected or in case of error
2159 * (the result must be released with free()).
2160 * \version LibVLC 3.0.0 or later.
2162 LIBVLC_API
char *libvlc_audio_output_device_get( libvlc_media_player_t
*mp
);
2165 * Toggle mute status.
2167 * \param p_mi media player
2168 * \warning Toggling mute atomically is not always possible: On some platforms,
2169 * other processes can mute the VLC audio playback stream asynchronously. Thus,
2170 * there is a small race condition where toggling will not work.
2171 * See also the limitations of libvlc_audio_set_mute().
2173 LIBVLC_API
void libvlc_audio_toggle_mute( libvlc_media_player_t
*p_mi
);
2176 * Get current mute status.
2178 * \param p_mi media player
2179 * \return the mute status (boolean) if defined, -1 if undefined/unapplicable
2181 LIBVLC_API
int libvlc_audio_get_mute( libvlc_media_player_t
*p_mi
);
2186 * \param p_mi media player
2187 * \param status If status is true then mute, otherwise unmute
2188 * \warning This function does not always work. If there are no active audio
2189 * playback stream, the mute status might not be available. If digital
2190 * pass-through (S/PDIF, HDMI...) is in use, muting may be unapplicable. Also
2191 * some audio output plugins do not support muting at all.
2192 * \note To force silent playback, disable all audio tracks. This is more
2193 * efficient and reliable than mute.
2195 LIBVLC_API
void libvlc_audio_set_mute( libvlc_media_player_t
*p_mi
, int status
);
2198 * Get current software audio volume.
2200 * \param p_mi media player
2201 * \return the software volume in percents
2202 * (0 = mute, 100 = nominal / 0dB)
2204 LIBVLC_API
int libvlc_audio_get_volume( libvlc_media_player_t
*p_mi
);
2207 * Set current software audio volume.
2209 * \param p_mi media player
2210 * \param i_volume the volume in percents (0 = mute, 100 = 0dB)
2211 * \return 0 if the volume was set, -1 if it was out of range
2213 LIBVLC_API
int libvlc_audio_set_volume( libvlc_media_player_t
*p_mi
, int i_volume
);
2216 * Get current audio channel.
2218 * \param p_mi media player
2219 * \return the audio channel \see libvlc_audio_output_channel_t
2221 LIBVLC_API
int libvlc_audio_get_channel( libvlc_media_player_t
*p_mi
);
2224 * Set current audio channel.
2226 * \param p_mi media player
2227 * \param channel the audio channel, \see libvlc_audio_output_channel_t
2228 * \return 0 on success, -1 on error
2230 LIBVLC_API
int libvlc_audio_set_channel( libvlc_media_player_t
*p_mi
, int channel
);
2233 * Get current audio delay.
2235 * \param p_mi media player
2236 * \return the audio delay (microseconds)
2237 * \version LibVLC 1.1.1 or later
2239 LIBVLC_API
int64_t libvlc_audio_get_delay( libvlc_media_player_t
*p_mi
);
2242 * Set current audio delay. The audio delay will be reset to zero each time the media changes.
2244 * \param p_mi media player
2245 * \param i_delay the audio delay (microseconds)
2246 * \return 0 on success, -1 on error
2247 * \version LibVLC 1.1.1 or later
2249 LIBVLC_API
int libvlc_audio_set_delay( libvlc_media_player_t
*p_mi
, int64_t i_delay
);
2252 * Get the number of equalizer presets.
2254 * \return number of presets
2255 * \version LibVLC 2.2.0 or later
2257 LIBVLC_API
unsigned libvlc_audio_equalizer_get_preset_count( void );
2260 * Get the name of a particular equalizer preset.
2262 * This name can be used, for example, to prepare a preset label or menu in a user
2265 * \param u_index index of the preset, counting from zero
2266 * \return preset name, or NULL if there is no such preset
2267 * \version LibVLC 2.2.0 or later
2269 LIBVLC_API
const char *libvlc_audio_equalizer_get_preset_name( unsigned u_index
);
2272 * Get the number of distinct frequency bands for an equalizer.
2274 * \return number of frequency bands
2275 * \version LibVLC 2.2.0 or later
2277 LIBVLC_API
unsigned libvlc_audio_equalizer_get_band_count( void );
2280 * Get a particular equalizer band frequency.
2282 * This value can be used, for example, to create a label for an equalizer band control
2283 * in a user interface.
2285 * \param u_index index of the band, counting from zero
2286 * \return equalizer band frequency (Hz), or -1 if there is no such band
2287 * \version LibVLC 2.2.0 or later
2289 LIBVLC_API
float libvlc_audio_equalizer_get_band_frequency( unsigned u_index
);
2292 * Create a new default equalizer, with all frequency values zeroed.
2294 * The new equalizer can subsequently be applied to a media player by invoking
2295 * libvlc_media_player_set_equalizer().
2297 * The returned handle should be freed via libvlc_audio_equalizer_release() when
2298 * it is no longer needed.
2300 * \return opaque equalizer handle, or NULL on error
2301 * \version LibVLC 2.2.0 or later
2303 LIBVLC_API libvlc_equalizer_t
*libvlc_audio_equalizer_new( void );
2306 * Create a new equalizer, with initial frequency values copied from an existing
2309 * The new equalizer can subsequently be applied to a media player by invoking
2310 * libvlc_media_player_set_equalizer().
2312 * The returned handle should be freed via libvlc_audio_equalizer_release() when
2313 * it is no longer needed.
2315 * \param u_index index of the preset, counting from zero
2316 * \return opaque equalizer handle, or NULL on error
2317 * (it must be released with libvlc_audio_equalizer_release())
2318 * \version LibVLC 2.2.0 or later
2320 LIBVLC_API libvlc_equalizer_t
*libvlc_audio_equalizer_new_from_preset( unsigned u_index
);
2323 * Release a previously created equalizer instance.
2325 * The equalizer was previously created by using libvlc_audio_equalizer_new() or
2326 * libvlc_audio_equalizer_new_from_preset().
2328 * It is safe to invoke this method with a NULL p_equalizer parameter for no effect.
2330 * \param p_equalizer opaque equalizer handle, or NULL
2331 * \version LibVLC 2.2.0 or later
2333 LIBVLC_API
void libvlc_audio_equalizer_release( libvlc_equalizer_t
*p_equalizer
);
2336 * Set a new pre-amplification value for an equalizer.
2338 * The new equalizer settings are subsequently applied to a media player by invoking
2339 * libvlc_media_player_set_equalizer().
2341 * The supplied amplification value will be clamped to the -20.0 to +20.0 range.
2343 * \param p_equalizer valid equalizer handle, must not be NULL
2344 * \param f_preamp preamp value (-20.0 to 20.0 Hz)
2345 * \return zero on success, -1 on error
2346 * \version LibVLC 2.2.0 or later
2348 LIBVLC_API
int libvlc_audio_equalizer_set_preamp( libvlc_equalizer_t
*p_equalizer
, float f_preamp
);
2351 * Get the current pre-amplification value from an equalizer.
2353 * \param p_equalizer valid equalizer handle, must not be NULL
2354 * \return preamp value (Hz)
2355 * \version LibVLC 2.2.0 or later
2357 LIBVLC_API
float libvlc_audio_equalizer_get_preamp( libvlc_equalizer_t
*p_equalizer
);
2360 * Set a new amplification value for a particular equalizer frequency band.
2362 * The new equalizer settings are subsequently applied to a media player by invoking
2363 * libvlc_media_player_set_equalizer().
2365 * The supplied amplification value will be clamped to the -20.0 to +20.0 range.
2367 * \param p_equalizer valid equalizer handle, must not be NULL
2368 * \param f_amp amplification value (-20.0 to 20.0 Hz)
2369 * \param u_band index, counting from zero, of the frequency band to set
2370 * \return zero on success, -1 on error
2371 * \version LibVLC 2.2.0 or later
2373 LIBVLC_API
int libvlc_audio_equalizer_set_amp_at_index( libvlc_equalizer_t
*p_equalizer
, float f_amp
, unsigned u_band
);
2376 * Get the amplification value for a particular equalizer frequency band.
2378 * \param p_equalizer valid equalizer handle, must not be NULL
2379 * \param u_band index, counting from zero, of the frequency band to get
2380 * \return amplification value (Hz); NaN if there is no such frequency band
2381 * \version LibVLC 2.2.0 or later
2383 LIBVLC_API
float libvlc_audio_equalizer_get_amp_at_index( libvlc_equalizer_t
*p_equalizer
, unsigned u_band
);
2386 * Apply new equalizer settings to a media player.
2388 * The equalizer is first created by invoking libvlc_audio_equalizer_new() or
2389 * libvlc_audio_equalizer_new_from_preset().
2391 * It is possible to apply new equalizer settings to a media player whether the media
2392 * player is currently playing media or not.
2394 * Invoking this method will immediately apply the new equalizer settings to the audio
2395 * output of the currently playing media if there is any.
2397 * If there is no currently playing media, the new equalizer settings will be applied
2398 * later if and when new media is played.
2400 * Equalizer settings will automatically be applied to subsequently played media.
2402 * To disable the equalizer for a media player invoke this method passing NULL for the
2403 * p_equalizer parameter.
2405 * The media player does not keep a reference to the supplied equalizer so it is safe
2406 * for an application to release the equalizer reference any time after this method
2409 * \param p_mi opaque media player handle
2410 * \param p_equalizer opaque equalizer handle, or NULL to disable the equalizer for this media player
2411 * \return zero on success, -1 on error
2412 * \version LibVLC 2.2.0 or later
2414 LIBVLC_API
int libvlc_media_player_set_equalizer( libvlc_media_player_t
*p_mi
, libvlc_equalizer_t
*p_equalizer
);
2417 * Media player roles.
2419 * \version LibVLC 3.0.0 and later.
2421 * See \ref libvlc_media_player_set_role()
2423 typedef enum libvlc_media_player_role
{
2424 libvlc_role_None
= 0, /**< Don't use a media player role */
2425 libvlc_role_Music
, /**< Music (or radio) playback */
2426 libvlc_role_Video
, /**< Video playback */
2427 libvlc_role_Communication
, /**< Speech, real-time communication */
2428 libvlc_role_Game
, /**< Video game */
2429 libvlc_role_Notification
, /**< User interaction feedback */
2430 libvlc_role_Animation
, /**< Embedded animation (e.g. in web page) */
2431 libvlc_role_Production
, /**< Audio editting/production */
2432 libvlc_role_Accessibility
, /**< Accessibility */
2433 libvlc_role_Test
/** Testing */
2434 #define libvlc_role_Last libvlc_role_Test
2435 } libvlc_media_player_role_t
;
2438 * Gets the media role.
2440 * \version LibVLC 3.0.0 and later.
2442 * \param p_mi media player
2443 * \return the media player role (\ref libvlc_media_player_role_t)
2445 LIBVLC_API
int libvlc_media_player_get_role(libvlc_media_player_t
*p_mi
);
2448 * Sets the media role.
2450 * \param p_mi media player
2451 * \param role the media player role (\ref libvlc_media_player_role_t)
2452 * \return 0 on success, -1 on error
2454 LIBVLC_API
int libvlc_media_player_set_role(libvlc_media_player_t
*p_mi
,
2459 /** @} media_player */
2465 #endif /* VLC_LIBVLC_MEDIA_PLAYER_H */