VLC  4.0.0-dev
libvlc_media_player.h
Go to the documentation of this file.
1 /*****************************************************************************
2  * libvlc_media_player.h: libvlc_media_player external API
3  *****************************************************************************
4  * Copyright (C) 1998-2015 VLC authors and VideoLAN
5  *
6  * Authors: ClĂ©ment Stenac <zorglub@videolan.org>
7  * Jean-Paul Saman <jpsaman@videolan.org>
8  * Pierre d'Herbemont <pdherbemont@videolan.org>
9  *
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.
14  *
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.
19  *
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  *****************************************************************************/
24 
25 #ifndef VLC_LIBVLC_MEDIA_PLAYER_H
26 #define VLC_LIBVLC_MEDIA_PLAYER_H 1
27 
28 # ifdef __cplusplus
29 extern "C" {
30 # else
31 # include <stdbool.h>
32 # endif
33 
34 /** \defgroup libvlc_media_player LibVLC media player
35  * \ingroup libvlc
36  * A LibVLC media player plays one media (usually in a custom drawable).
37  * @{
38  * \file
39  * LibVLC simple media player external API
40  */
41 
43 
44 /**
45  * Description for video, audio tracks and subtitles. It contains
46  * id, name (description string) and pointer to next record.
47  */
49 {
50  int i_id;
51  char *psz_name;
53 
55 
56 /**
57  * Description for titles
58  */
59 enum
60 {
63 };
64 
66 {
67  int64_t i_duration; /**< duration in milliseconds */
68  char *psz_name; /**< title name */
69  unsigned i_flags; /**< info if item was recognized as a menu, interactive or plain content by the demuxer */
71 
72 /**
73  * Description for chapters
74  */
76 {
77  int64_t i_time_offset; /**< time-offset of the chapter in milliseconds */
78  int64_t i_duration; /**< duration of the chapter in milliseconds */
79  char *psz_name; /**< chapter name */
81 
82 /**
83  * Description for audio output. It contains
84  * name, description and pointer to next record.
85  */
86 typedef struct libvlc_audio_output_t
87 {
88  char *psz_name;
91 
93 
94 /**
95  * Description for audio output device.
96  */
98 {
99  struct libvlc_audio_output_device_t *p_next; /**< Next entry in list */
100  char *psz_device; /**< Device identifier string */
101  char *psz_description; /**< User-friendly device description */
102  /* More fields may be added here in later versions */
104 
105 /**
106  * Marq options definition
107  */
110  libvlc_marquee_Text, /** string argument */
120 
121 /**
122  * Navigation mode
123  */
125 {
133 
134 /**
135  * Enumeration of values used to set position (e.g. of video title).
136  */
137 typedef enum libvlc_position_t {
149 
150 /**
151  * Enumeration of teletext keys than can be passed via
152  * libvlc_video_set_teletext()
153  */
154 typedef enum libvlc_teletext_key_t {
161 
162 /**
163  * Opaque equalizer handle.
164  *
165  * Equalizer settings can be applied to a media player.
166  */
168 
169 /**
170  * Create an empty Media Player object
171  *
172  * \param p_libvlc_instance the libvlc instance in which the Media Player
173  * should be created.
174  * \return a new media player object, or NULL on error.
175  * It must be released by libvlc_media_player_release().
176  */
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  * It must be released by libvlc_media_player_release().
186  */
188 
189 /**
190  * Release a media_player after use
191  * Decrement the reference count of a media player object. If the
192  * reference count is 0, then libvlc_media_player_release() will
193  * release the media player object. If the media player object
194  * has been released, then it should not be used again.
195  *
196  * \param p_mi the Media Player to free
197  */
199 
200 /**
201  * Retain a reference to a media player object. Use
202  * libvlc_media_player_release() to decrement reference count.
203  *
204  * \param p_mi media player object
205  */
207 
208 /**
209  * Set the media that will be used by the media_player. If any,
210  * previous md will be released.
211  *
212  * \param p_mi the Media Player
213  * \param p_md the Media. Afterwards the p_md can be safely
214  * destroyed.
215  */
217  libvlc_media_t *p_md );
218 
219 /**
220  * Get the media used by the media_player.
221  *
222  * \param p_mi the Media Player
223  * \return the media associated with p_mi, or NULL if no
224  * media is associated
225  */
227 
228 /**
229  * Get the Event Manager from which the media player send event.
230  *
231  * \param p_mi the Media Player
232  * \return the event manager associated with p_mi
233  */
235 
236 /**
237  * is_playing
238  *
239  * \param p_mi the Media Player
240  * \retval true media player is playing
241  * \retval false media player is not playing
242  */
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  */
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  */
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  */
269 
270 /**
271  * Stop (no effect if there is no media)
272  *
273  * \param p_mi the Media Player
274  */
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  */
291  libvlc_renderer_item_t *p_item );
292 
293 /**
294  * Enumeration of the Video color primaries.
295  */
304 
305 /**
306  * Enumeration of the Video color spaces.
307  */
313 
314 /**
315  * Enumeration of the Video transfer functions.
316  */
327 
328 
329 /**
330  * Callback prototype to allocate and lock a picture buffer.
331  *
332  * Whenever a new video frame needs to be decoded, the lock callback is
333  * invoked. Depending on the video chroma, one or three pixel planes of
334  * adequate dimensions must be returned via the second parameter. Those
335  * planes must be aligned on 32-bytes boundaries.
336  *
337  * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]
338  * \param planes start address of the pixel planes (LibVLC allocates the array
339  * of void pointers, this callback must initialize the array) [OUT]
340  * \return a private pointer for the display and unlock callbacks to identify
341  * the picture buffers
342  */
343 typedef void *(*libvlc_video_lock_cb)(void *opaque, void **planes);
344 
345 /**
346  * Callback prototype to unlock a picture buffer.
347  *
348  * When the video frame decoding is complete, the unlock callback is invoked.
349  * This callback might not be needed at all. It is only an indication that the
350  * application can now read the pixel values if it needs to.
351  *
352  * \note A picture buffer is unlocked after the picture is decoded,
353  * but before the picture is displayed.
354  *
355  * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]
356  * \param picture private pointer returned from the @ref libvlc_video_lock_cb
357  * callback [IN]
358  * \param planes pixel planes as defined by the @ref libvlc_video_lock_cb
359  * callback (this parameter is only for convenience) [IN]
360  */
361 typedef void (*libvlc_video_unlock_cb)(void *opaque, void *picture,
362  void *const *planes);
363 
364 /**
365  * Callback prototype to display a picture.
366  *
367  * When the video frame needs to be shown, as determined by the media playback
368  * clock, the display callback is invoked.
369  *
370  * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]
371  * \param picture private pointer returned from the @ref libvlc_video_lock_cb
372  * callback [IN]
373  */
374 typedef void (*libvlc_video_display_cb)(void *opaque, void *picture);
375 
376 /**
377  * Callback prototype to configure picture buffers format.
378  * This callback gets the format of the video as output by the video decoder
379  * and the chain of video filters (if any). It can opt to change any parameter
380  * as it needs. In that case, LibVLC will attempt to convert the video format
381  * (rescaling and chroma conversion) but these operations can be CPU intensive.
382  *
383  * \param opaque pointer to the private pointer passed to
384  * libvlc_video_set_callbacks() [IN/OUT]
385  * \param chroma pointer to the 4 bytes video format identifier [IN/OUT]
386  * \param width pointer to the buffer width in pixels[IN/OUT]
387  * \param height pointer to the buffer height in pixels[IN/OUT]
388  * \param pitches table of scanline pitches in bytes for each pixel plane
389  * (the table is allocated by LibVLC) [OUT]
390  * \param lines table of scanlines count for each plane [OUT]
391  * \return the number of picture buffers allocated, 0 indicates failure
392  *
393  * \version LibVLC 4.0.0 and later.
394  * \param (width+1) - pointer to display width in pixels[IN]
395  * \param (height+1) - pointer to display height in pixels[IN]
396  *
397  * \note
398  * For each pixels plane, the scanline pitch must be bigger than or equal to
399  * the number of bytes per pixel multiplied by the pixel width.
400  * Similarly, the number of scanlines must be bigger than of equal to
401  * the pixel height.
402  * Furthermore, we recommend that pitches and lines be multiple of 32
403  * to not break assumptions that might be held by optimized code
404  * in the video decoders, video filters and/or video converters.
405  */
406 typedef unsigned (*libvlc_video_format_cb)(void **opaque, char *chroma,
407  unsigned *width, unsigned *height,
408  unsigned *pitches,
409  unsigned *lines);
410 
411 /**
412  * Callback prototype to configure picture buffers format.
413  *
414  * \param opaque private pointer as passed to libvlc_video_set_callbacks()
415  * (and possibly modified by @ref libvlc_video_format_cb) [IN]
416  */
417 typedef void (*libvlc_video_cleanup_cb)(void *opaque);
418 
419 
420 /**
421  * Set callbacks and private data to render decoded video to a custom area
422  * in memory.
423  * Use libvlc_video_set_format() or libvlc_video_set_format_callbacks()
424  * to configure the decoded format.
425  *
426  * \warning Rendering video into custom memory buffers is considerably less
427  * efficient than rendering in a custom window as normal.
428  *
429  * For optimal perfomances, VLC media player renders into a custom window, and
430  * does not use this function and associated callbacks. It is <b>highly
431  * recommended</b> that other LibVLC-based application do likewise.
432  * To embed video in a window, use libvlc_media_player_set_xid() or equivalent
433  * depending on the operating system.
434  *
435  * If window embedding does not fit the application use case, then a custom
436  * LibVLC video output display plugin is required to maintain optimal video
437  * rendering performances.
438  *
439  * The following limitations affect performance:
440  * - Hardware video decoding acceleration will either be disabled completely,
441  * or require (relatively slow) copy from video/DSP memory to main memory.
442  * - Sub-pictures (subtitles, on-screen display, etc.) must be blent into the
443  * main picture by the CPU instead of the GPU.
444  * - Depending on the video format, pixel format conversion, picture scaling,
445  * cropping and/or picture re-orientation, must be performed by the CPU
446  * instead of the GPU.
447  * - Memory copying is required between LibVLC reference picture buffers and
448  * application buffers (between lock and unlock callbacks).
449  *
450  * \param mp the media player
451  * \param lock callback to lock video memory (must not be NULL)
452  * \param unlock callback to unlock video memory (or NULL if not needed)
453  * \param display callback to display video (or NULL if not needed)
454  * \param opaque private pointer for the three callbacks (as first parameter)
455  * \version LibVLC 1.1.1 or later
456  */
460  libvlc_video_unlock_cb unlock,
461  libvlc_video_display_cb display,
462  void *opaque );
463 
464 /**
465  * Set decoded video chroma and dimensions.
466  * This only works in combination with libvlc_video_set_callbacks(),
467  * and is mutually exclusive with libvlc_video_set_format_callbacks().
468  *
469  * \param mp the media player
470  * \param chroma a four-characters string identifying the chroma
471  * (e.g. "RV32" or "YUYV")
472  * \param width pixel width
473  * \param height pixel height
474  * \param pitch line pitch (in bytes)
475  * \version LibVLC 1.1.1 or later
476  * \bug All pixel planes are expected to have the same pitch.
477  * To use the YCbCr color space with chrominance subsampling,
478  * consider using libvlc_video_set_format_callbacks() instead.
479  */
481 void libvlc_video_set_format( libvlc_media_player_t *mp, const char *chroma,
482  unsigned width, unsigned height,
483  unsigned pitch );
484 
485 /**
486  * Set decoded video chroma and dimensions. This only works in combination with
487  * libvlc_video_set_callbacks().
488  *
489  * \param mp the media player
490  * \param setup callback to select the video format (cannot be NULL)
491  * \param cleanup callback to release any allocated resources (or NULL)
492  * \version LibVLC 2.0.0 or later
493  */
497  libvlc_video_cleanup_cb cleanup );
498 
499 
500 /**
501  * Callback prototype called to initialize user data.
502  *
503  * \param opaque private pointer passed to the @a libvlc_video_set_output_callbacks() [IN]
504  * \return true on success
505  * \version LibVLC 4.0.0 or later
506  */
507 typedef bool (*libvlc_video_setup_cb)(void* opaque);
508 
509 
510 /**
511  * Callback prototype called to release user data
512  *
513  * \param opaque private pointer passed to the @a libvlc_video_set_output_callbacks() [IN]
514  * \version LibVLC 4.0.0 or later
515  */
516 typedef void (*libvlc_video_cleanup_cb)(void* opaque);
517 
518 /**
519  * Callback prototype called on video size changes
520  *
521  * \param opaque private pointer passed to the @a libvlc_video_set_output_callbacks() [IN]
522  * \param width video width in pixel [IN]
523  * \param height video height in pixel [IN]
524  * \version LibVLC 4.0.0 or later
525  */
526 typedef void (*libvlc_video_update_output_cb)(void* opaque, unsigned width, unsigned height);
527 
528 
529 /**
530  * Callback prototype called after performing drawing calls.
531  *
532  * \param opaque private pointer passed to the @a libvlc_video_set_output_callbacks() [IN]
533  * \version LibVLC 4.0.0 or later
534  */
535 typedef void (*libvlc_video_swap_cb)(void* opaque);
536 
537 /**
538  * Callback prototype to set up the OpenGL context for rendering
539  *
540  * \param opaque private pointer passed to the @a libvlc_video_set_output_callbacks() [IN]
541  * \param enter true to set the context as current, false to unset it [IN]
542  * \return true on success
543  * \version LibVLC 4.0.0 or later
544  */
545 typedef bool (*libvlc_video_makeCurrent_cb)(void* opaque, bool enter);
546 
547 /**
548  * Callback prototype to load opengl functions
549  *
550  * \param opaque private pointer passed to the @a libvlc_video_set_output_callbacks() [IN]
551  * \param fct_name name of the opengl function to load
552  * \return a pointer to the named OpenGL function the NULL otherwise
553  * \version LibVLC 4.0.0 or later
554  */
555 typedef void* (*libvlc_video_getProcAddress_cb)(void* opaque, const char* fct_name);
556 
557 /**
558  * Enumeration of the Video engine to be used on output.
559  * can be passed to @a libvlc_video_set_output_callbacks
560  */
561 typedef enum libvlc_video_engine_t {
565 
566 /**
567  * Set callbacks and data to render decoded video to a custom texture
568  *
569  * \warning VLC will perform video rendering in its own thread and at its own rate,
570  * You need to provide your own synchronisation mechanism.
571  *
572  * OpenGL context need to be created before playing a media.
573  *
574  * \param mp the media player
575  * \param engine the GPU engine to use
576  * \param setup_cb callback called to initialize user data
577  * \param cleanup_cb callback called to clean up user data
578  * \param update_output_cb callback called to get the size of the video
579  * \param swap_cb callback called after rendering a video frame (cannot be NULL)
580  * \param makeCurrent_cb callback called to enter/leave the opengl context (cannot be NULL for \ref libvlc_video_engine_opengl and for \ref libvlc_video_engine_gles2)
581  * \param getProcAddress_cb opengl function loading callback (cannot be NULL for \ref libvlc_video_engine_opengl and for \ref libvlc_video_engine_gles2)
582  * \param opaque private pointer passed to callbacks
583  *
584  * \retval true engine selected and callbacks set
585  * \retval false engine type unknown, callbacks not set
586  * \version LibVLC 4.0.0 or later
587  */
590  libvlc_video_engine_t engine,
591  libvlc_video_setup_cb setup_cb,
592  libvlc_video_cleanup_cb cleanup_cb,
593  libvlc_video_update_output_cb update_output_cb,
594  libvlc_video_swap_cb swap_cb,
595  libvlc_video_makeCurrent_cb makeCurrent_cb,
596  libvlc_video_getProcAddress_cb getProcAddress_cb,
597  void* opaque );
598 
599 
600 /**
601  * Enumeration of the Video engine to be used on output.
602  * can be passed to @a libvlc_video_direct3d_set_callbacks
603  */
605  /** Direct3D11 rendering engine */
607  /** Direct3D9 rendering engine */
610 
611 typedef struct
612 {
613  bool hardware_decoding; /** set if D3D11_CREATE_DEVICE_VIDEO_SUPPORT is needed for D3D11 */
615 
616 typedef struct
617 {
618  void *device_context; /** ID3D11DeviceContext* for D3D11, IDirect3D9 * for D3D9 */
619  int adapter; /** Adapter to use with the IDirect3D9 for D3D9 */
621 
622 /** Setup the rendering environment.
623  *
624  * \param opaque private pointer passed to the @a libvlc_video_direct3d_set_callbacks()
625  * on input. The callback can change this value on output to be
626  * passed to all the other callbacks set on @a libvlc_video_direct3d_set_callbacks(). [IN/OUT]
627  * \param cfg requested configuration of the video device [IN]
628  * \param out libvlc_video_direct3d_device_setup_t* to fill [OUT]
629  * \return true on success
630  * \version LibVLC 4.0.0 or later
631  *
632  * For \ref libvlc_video_direct3d_engine_d3d9 the output must be a IDirect3D9*.
633  * A reference to this object is held until the \ref LIBVLC_VIDEO_DEVICE_CLEANUP is called.
634  * the device must be created with D3DPRESENT_PARAMETERS.hDeviceWindow set to 0.
635  *
636  * For \ref libvlc_video_direct3d_engine_d3d11 the output must be a ID3D11DeviceContext*.
637  * A reference to this object is held until the \ref LIBVLC_VIDEO_DEVICE_CLEANUP is called.
638  * The ID3D11Device used to create ID3D11DeviceContext must have multithreading enabled.
639  */
640 typedef bool( *libvlc_video_direct3d_device_setup_cb )( void **opaque,
643 
644 /** Cleanup the rendering environment initialized during \ref libvlc_video_direct3d_device_setup_cb.
645  *
646  * \param opaque private pointer set on the opaque parameter of @a libvlc_video_direct3d_device_setup_cb() [IN]
647  * \version LibVLC 4.0.0 or later
648  */
649 typedef void( *libvlc_video_direct3d_device_cleanup_cb )( void *opaque );
650 
651 /** Set the callback to call when the host app resizes the rendering area.
652  *
653  * This allows text rendering and aspect ratio to be handled properly when the host
654  * rendering size changes.
655  *
656  * It may be called before the \ref libvlc_video_direct3d_device_setup_cb callback.
657  *
658  * \param opaque private pointer set on the opaque parameter of @a libvlc_video_direct3d_device_setup_cb() [IN]
659  * \param report_size_change callback which must be called when the host size changes. [IN]
660  * The callback is valid until another call to \ref libvlc_video_direct3d_set_resize_cb
661  * is done. This may be called from any thread.
662  * \param report_opaque private pointer to pass to the \ref report_size_change callback. [IN]
663  */
664 typedef void( *libvlc_video_direct3d_set_resize_cb )( void *opaque,
665  void (*report_size_change)(void *report_opaque, unsigned width, unsigned height),
666  void *report_opaque );
667 
668 typedef struct
669 {
670  unsigned width; /** rendering video width in pixel */
671  unsigned height; /** rendering video height in pixel */
672  unsigned bitdepth; /** rendering video bit depth in bits per channel */
673  bool full_range; /** video is full range or studio/limited range */
674  libvlc_video_color_space_t colorspace; /** video color space */
675  libvlc_video_color_primaries_t primaries; /** video color primaries */
676  libvlc_video_transfer_func_t transfer; /** video transfer function */
677  void *device; /** device used for rendering, IDirect3DDevice9* for D3D9 */
679 
680 typedef struct
681 {
682  int surface_format; /** the rendering DXGI_FORMAT for \ref libvlc_video_direct3d_engine_d3d11,
683  D3DFORMAT for \ref libvlc_video_direct3d_engine_d3d9 */
684  bool full_range; /** video is full range or studio/limited range */
685  libvlc_video_color_space_t colorspace; /** video color space */
686  libvlc_video_color_primaries_t primaries; /** video color primaries */
687  libvlc_video_transfer_func_t transfer; /** video transfer function */
689 
690 /** Update the rendering output setup.
691  *
692  * \param opaque private pointer set on the opaque parameter of @a libvlc_video_direct3d_device_setup_cb() [IN]
693  * \param cfg configuration of the video that will be rendered [IN]
694  * \param output configuration describing with how the rendering is setup [OUT]
695  * \version LibVLC 4.0.0 or later
696  *
697  * \note the configuration device for Direct3D9 is the IDirect3DDevice9 that VLC
698  * uses to render. The host must set a Render target and call Present()
699  * when it needs the drawing from VLC to be done. This object is not valid
700  * anymore after Cleanup is called.
701  *
702  * Tone mapping, range and color conversion will be done depending on the values
703  * set in the output structure.
704  */
705 typedef bool( *libvlc_video_direct3d_update_output_cb )( void *opaque,
706  const libvlc_video_direct3d_cfg_t *cfg,
707  libvlc_video_output_cfg_t *output );
708 
709 typedef struct
710 {
711  /* similar to SMPTE ST 2086 mastering display color volume */
712  uint16_t RedPrimary[2];
713  uint16_t GreenPrimary[2];
714  uint16_t BluePrimary[2];
715  uint16_t WhitePoint[2];
716  unsigned int MaxMasteringLuminance;
717  unsigned int MinMasteringLuminance;
721 
722 /** Tell the host the rendering is about to start/has finished.
723  *
724  * \param opaque private pointer set on the opaque parameter of @a libvlc_video_direct3d_device_setup_cb() [IN]
725  * \param enter true if the rendering is about to start, false if it's finished
726  * \param hdr10 libvlc_video_direct3d_hdr10_metadata_t* or NULL [IN]
727  * \return true on success
728  * \version LibVLC 4.0.0 or later
729  *
730  * On Direct3D11 the following may change on the provided ID3D11DeviceContext*
731  * between \ref enter being true and \ref enter being false:
732  * - IASetPrimitiveTopology()
733  * - IASetInputLayout()
734  * - IASetVertexBuffers()
735  * - IASetIndexBuffer()
736  * - VSSetConstantBuffers()
737  * - VSSetShader()
738  * - PSSetSamplers()
739  * - PSSetConstantBuffers()
740  * - PSSetShaderResources()
741  * - PSSetShader()
742  * - RSSetViewports()
743  * - DrawIndexed()
744  */
745 typedef bool( *libvlc_video_direct3d_start_end_rendering_cb )( void *opaque, bool enter, const libvlc_video_direct3d_hdr10_metadata_t *hdr10 );
746 
747 /** Tell the host the rendering for the given plane is about to start
748  *
749  * \param opaque private pointer set on the opaque parameter of @a libvlc_video_direct3d_device_setup_cb() [IN]
750  * \param plane number of the rendering plane to select
751  * \return true on success
752  * \version LibVLC 4.0.0 or later
753  *
754  * \note This is only used with \ref libvlc_video_direct3d_engine_d3d11.
755  *
756  * The host should call OMSetRenderTargets for Direct3D11. If this callback is
757  * not used (set to NULL in @a libvlc_video_direct3d_set_callbacks()) OMSetRenderTargets
758  * has to be set during the @a libvlc_video_direct3d_start_end_rendering_cb()
759  * entering call.
760  *
761  * The number of planes depend on the DXGI_FORMAT returned during the
762  * \ref LIBVLC_VIDEO_UPDATE_OUTPUT call. It's usually one plane except for
763  * semi-planar formats like DXGI_FORMAT_NV12 or DXGI_FORMAT_P010.
764  */
765 typedef bool( *libvlc_video_direct3d_select_plane_cb )( void *opaque, size_t plane );
766 
767 /**
768  * Set callbacks and data to render decoded video to a custom Direct3D output
769  *
770  * \warning VLC will perform video rendering in its own thread and at its own rate,
771  * You need to provide your own synchronisation mechanism.
772  *
773  * \param mp the media player
774  * \param engine the GPU engine to use
775  * \param setup_cb callback to setup and return the device to use (cannot be NULL)
776  * \param cleanup_cb callback to cleanup the device given by the \ref setup_cb callback
777  * \param resize_cb callback to set the resize callback
778  * \param update_output_cb callback to notify of the source format and get the
779  * rendering format used by the host (cannot be NULL)
780  * \param swap_cb callback to tell the host it should display the rendered picture (cannot be NULL)
781  * \param makeCurrent_cb callback to tell the host the rendering is starting/ended (cannot be NULL)
782  * \param select_plane_cb callback to select different D3D11 rendering targets
783  * \param opaque private pointer passed to the \ref cleanup_cb callback
784  *
785  * \retval true Direct3D selected and callbacks set
786  * \retval false Direct3D version, callbacks not set
787  * \version LibVLC 4.0.0 or later
788  */
791  libvlc_video_direct3d_engine_t engine,
796  libvlc_video_swap_cb swap_cb,
799  void* opaque );
800 
801 /**
802  * Set the NSView handler where the media player should render its video output.
803  *
804  * Use the vout called "macosx".
805  *
806  * The drawable is an NSObject that follow the VLCVideoViewEmbedding
807  * protocol:
808  *
809  * @code{.m}
810  * @protocol VLCVideoViewEmbedding <NSObject>
811  * - (void)addVoutSubview:(NSView *)view;
812  * - (void)removeVoutSubview:(NSView *)view;
813  * @end
814  * @endcode
815  *
816  * Or it can be an NSView object.
817  *
818  * If you want to use it along with Qt see the QMacCocoaViewContainer. Then
819  * the following code should work:
820  * @code{.mm}
821  * {
822  * NSView *video = [[NSView alloc] init];
823  * QMacCocoaViewContainer *container = new QMacCocoaViewContainer(video, parent);
824  * libvlc_media_player_set_nsobject(mp, video);
825  * [video release];
826  * }
827  * @endcode
828  *
829  * You can find a live example in VLCVideoView in VLCKit.framework.
830  *
831  * \param p_mi the Media Player
832  * \param drawable the drawable that is either an NSView or an object following
833  * the VLCVideoViewEmbedding protocol.
834  */
836 
837 /**
838  * Get the NSView handler previously set with libvlc_media_player_set_nsobject().
839  *
840  * \param p_mi the Media Player
841  * \return the NSView handler or 0 if none where set
842  */
844 
845 /**
846  * Set an X Window System drawable where the media player should render its
847  * video output. The call takes effect when the playback starts. If it is
848  * already started, it might need to be stopped before changes apply.
849  * If LibVLC was built without X11 output support, then this function has no
850  * effects.
851  *
852  * By default, LibVLC will capture input events on the video rendering area.
853  * Use libvlc_video_set_mouse_input() and libvlc_video_set_key_input() to
854  * disable that and deliver events to the parent window / to the application
855  * instead. By design, the X11 protocol delivers input events to only one
856  * recipient.
857  *
858  * \warning
859  * The application must call the XInitThreads() function from Xlib before
860  * libvlc_new(), and before any call to XOpenDisplay() directly or via any
861  * other library. Failure to call XInitThreads() will seriously impede LibVLC
862  * performance. Calling XOpenDisplay() before XInitThreads() will eventually
863  * crash the process. That is a limitation of Xlib.
864  *
865  * \param p_mi media player
866  * \param drawable X11 window ID
867  *
868  * \note
869  * The specified identifier must correspond to an existing Input/Output class
870  * X11 window. Pixmaps are <b>not</b> currently supported. The default X11
871  * server is assumed, i.e. that specified in the DISPLAY environment variable.
872  *
873  * \warning
874  * LibVLC can deal with invalid X11 handle errors, however some display drivers
875  * (EGL, GLX, VA and/or VDPAU) can unfortunately not. Thus the window handle
876  * must remain valid until playback is stopped, otherwise the process may
877  * abort or crash.
878  *
879  * \bug
880  * No more than one window handle per media player instance can be specified.
881  * If the media has multiple simultaneously active video tracks, extra tracks
882  * will be rendered into external windows beyond the control of the
883  * application.
884  */
886  uint32_t drawable);
887 
888 /**
889  * Get the X Window System window identifier previously set with
890  * libvlc_media_player_set_xwindow(). Note that this will return the identifier
891  * even if VLC is not currently using it (for instance if it is playing an
892  * audio-only input).
893  *
894  * \param p_mi the Media Player
895  * \return an X window ID, or 0 if none where set.
896  */
898 
899 /**
900  * Set a Win32/Win64 API window handle (HWND) where the media player should
901  * render its video output. If LibVLC was built without Win32/Win64 API output
902  * support, then this has no effects.
903  *
904  * \param p_mi the Media Player
905  * \param drawable windows handle of the drawable
906  */
907 LIBVLC_API void libvlc_media_player_set_hwnd ( libvlc_media_player_t *p_mi, void *drawable );
908 
909 /**
910  * Get the Windows API window handle (HWND) previously set with
911  * libvlc_media_player_set_hwnd(). The handle will be returned even if LibVLC
912  * is not currently outputting any video to it.
913  *
914  * \param p_mi the Media Player
915  * \return a window handle or NULL if there are none.
916  */
918 
919 /**
920  * Set the android context.
921  *
922  * \version LibVLC 3.0.0 and later.
923  *
924  * \param p_mi the media player
925  * \param p_awindow_handler org.videolan.libvlc.AWindow jobject owned by the
926  * org.videolan.libvlc.MediaPlayer class from the libvlc-android project.
927  */
929  void *p_awindow_handler );
930 
931 /**
932  * Callback prototype for audio playback.
933  *
934  * The LibVLC media player decodes and post-processes the audio signal
935  * asynchronously (in an internal thread). Whenever audio samples are ready
936  * to be queued to the output, this callback is invoked.
937  *
938  * The number of samples provided per invocation may depend on the file format,
939  * the audio coding algorithm, the decoder plug-in, the post-processing
940  * filters and timing. Application must not assume a certain number of samples.
941  *
942  * The exact format of audio samples is determined by libvlc_audio_set_format()
943  * or libvlc_audio_set_format_callbacks() as is the channels layout.
944  *
945  * Note that the number of samples is per channel. For instance, if the audio
946  * track sampling rate is 48000 Hz, then 1200 samples represent 25 milliseconds
947  * of audio signal - regardless of the number of audio channels.
948  *
949  * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
950  * \param samples pointer to a table of audio samples to play back [IN]
951  * \param count number of audio samples to play back
952  * \param pts expected play time stamp (see libvlc_delay())
953  */
954 typedef void (*libvlc_audio_play_cb)(void *data, const void *samples,
955  unsigned count, int64_t pts);
956 
957 /**
958  * Callback prototype for audio pause.
959  *
960  * LibVLC invokes this callback to pause audio playback.
961  *
962  * \note The pause callback is never called if the audio is already paused.
963  * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
964  * \param pts time stamp of the pause request (should be elapsed already)
965  */
966 typedef void (*libvlc_audio_pause_cb)(void *data, int64_t pts);
967 
968 /**
969  * Callback prototype for audio resumption.
970  *
971  * LibVLC invokes this callback to resume audio playback after it was
972  * previously paused.
973  *
974  * \note The resume callback is never called if the audio is not paused.
975  * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
976  * \param pts time stamp of the resumption request (should be elapsed already)
977  */
978 typedef void (*libvlc_audio_resume_cb)(void *data, int64_t pts);
979 
980 /**
981  * Callback prototype for audio buffer flush.
982  *
983  * LibVLC invokes this callback if it needs to discard all pending buffers and
984  * stop playback as soon as possible. This typically occurs when the media is
985  * stopped.
986  *
987  * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
988  */
989 typedef void (*libvlc_audio_flush_cb)(void *data, int64_t pts);
990 
991 /**
992  * Callback prototype for audio buffer drain.
993  *
994  * LibVLC may invoke this callback when the decoded audio track is ending.
995  * There will be no further decoded samples for the track, but playback should
996  * nevertheless continue until all already pending buffers are rendered.
997  *
998  * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
999  */
1000 typedef void (*libvlc_audio_drain_cb)(void *data);
1001 
1002 /**
1003  * Callback prototype for audio volume change.
1004  * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
1005  * \param volume software volume (1. = nominal, 0. = mute)
1006  * \param mute muted flag
1007  */
1008 typedef void (*libvlc_audio_set_volume_cb)(void *data,
1009  float volume, bool mute);
1010 
1011 /**
1012  * Sets callbacks and private data for decoded audio.
1013  *
1014  * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks()
1015  * to configure the decoded audio format.
1016  *
1017  * \note The audio callbacks override any other audio output mechanism.
1018  * If the callbacks are set, LibVLC will <b>not</b> output audio in any way.
1019  *
1020  * \param mp the media player
1021  * \param play callback to play audio samples (must not be NULL)
1022  * \param pause callback to pause playback (or NULL to ignore)
1023  * \param resume callback to resume playback (or NULL to ignore)
1024  * \param flush callback to flush audio buffers (or NULL to ignore)
1025  * \param drain callback to drain audio buffers (or NULL to ignore)
1026  * \param opaque private pointer for the audio callbacks (as first parameter)
1027  * \version LibVLC 2.0.0 or later
1028  */
1029 LIBVLC_API
1031  libvlc_audio_play_cb play,
1032  libvlc_audio_pause_cb pause,
1033  libvlc_audio_resume_cb resume,
1034  libvlc_audio_flush_cb flush,
1035  libvlc_audio_drain_cb drain,
1036  void *opaque );
1037 
1038 /**
1039  * Set callbacks and private data for decoded audio. This only works in
1040  * combination with libvlc_audio_set_callbacks().
1041  * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks()
1042  * to configure the decoded audio format.
1043  *
1044  * \param mp the media player
1045  * \param set_volume callback to apply audio volume,
1046  * or NULL to apply volume in software
1047  * \version LibVLC 2.0.0 or later
1048  */
1049 LIBVLC_API
1051  libvlc_audio_set_volume_cb set_volume );
1052 
1053 /**
1054  * Callback prototype to setup the audio playback.
1055  *
1056  * This is called when the media player needs to create a new audio output.
1057  * \param opaque pointer to the data pointer passed to
1058  * libvlc_audio_set_callbacks() [IN/OUT]
1059  * \param format 4 bytes sample format [IN/OUT]
1060  * \param rate sample rate [IN/OUT]
1061  * \param channels channels count [IN/OUT]
1062  * \return 0 on success, anything else to skip audio playback
1063  */
1064 typedef int (*libvlc_audio_setup_cb)(void **opaque, char *format, unsigned *rate,
1065  unsigned *channels);
1066 
1067 /**
1068  * Callback prototype for audio playback cleanup.
1069  *
1070  * This is called when the media player no longer needs an audio output.
1071  * \param opaque data pointer as passed to libvlc_audio_set_callbacks() [IN]
1072  */
1073 typedef void (*libvlc_audio_cleanup_cb)(void *data);
1074 
1075 /**
1076  * Sets decoded audio format via callbacks.
1077  *
1078  * This only works in combination with libvlc_audio_set_callbacks().
1079  *
1080  * \param mp the media player
1081  * \param setup callback to select the audio format (cannot be NULL)
1082  * \param cleanup callback to release any allocated resources (or NULL)
1083  * \version LibVLC 2.0.0 or later
1084  */
1085 LIBVLC_API
1087  libvlc_audio_setup_cb setup,
1088  libvlc_audio_cleanup_cb cleanup );
1089 
1090 /**
1091  * Sets a fixed decoded audio format.
1092  *
1093  * This only works in combination with libvlc_audio_set_callbacks(),
1094  * and is mutually exclusive with libvlc_audio_set_format_callbacks().
1095  *
1096  * \param mp the media player
1097  * \param format a four-characters string identifying the sample format
1098  * (e.g. "S16N" or "f32l")
1099  * \param rate sample rate (expressed in Hz)
1100  * \param channels channels count
1101  * \version LibVLC 2.0.0 or later
1102  */
1103 LIBVLC_API
1104 void libvlc_audio_set_format( libvlc_media_player_t *mp, const char *format,
1105  unsigned rate, unsigned channels );
1106 
1107 /** \bug This might go away ... to be replaced by a broader system */
1108 
1109 /**
1110  * Get the current movie length (in ms).
1111  *
1112  * \param p_mi the Media Player
1113  * \return the movie length (in ms), or -1 if there is no media.
1114  */
1116 
1117 /**
1118  * Get the current movie time (in ms).
1119  *
1120  * \param p_mi the Media Player
1121  * \return the movie time (in ms), or -1 if there is no media.
1122  */
1124 
1125 /**
1126  * Set the movie time (in ms). This has no effect if no media is being played.
1127  * Not all formats and protocols support this.
1128  *
1129  * \param p_mi the Media Player
1130  * \param b_fast prefer fast seeking or precise seeking
1131  * \param i_time the movie time (in ms).
1132  * \return 0 on success, -1 on error
1133  */
1135  libvlc_time_t i_time, bool b_fast );
1136 
1137 /**
1138  * Get movie position as percentage between 0.0 and 1.0.
1139  *
1140  * \param p_mi the Media Player
1141  * \return movie position, or -1. in case of error
1142  */
1144 
1145 /**
1146  * Set movie position as percentage between 0.0 and 1.0.
1147  * This has no effect if playback is not enabled.
1148  * This might not work depending on the underlying input format and protocol.
1149  *
1150  * \param p_mi the Media Player
1151  * \param b_fast prefer fast seeking or precise seeking
1152  * \param f_pos the position
1153  * \return 0 on success, -1 on error
1154  */
1156  float f_pos, bool b_fast );
1157 
1158 /**
1159  * Set movie chapter (if applicable).
1160  *
1161  * \param p_mi the Media Player
1162  * \param i_chapter chapter number to play
1163  */
1165 
1166 /**
1167  * Get movie chapter.
1168  *
1169  * \param p_mi the Media Player
1170  * \return chapter number currently playing, or -1 if there is no media.
1171  */
1173 
1174 /**
1175  * Get movie chapter count
1176  *
1177  * \param p_mi the Media Player
1178  * \return number of chapters in movie, or -1.
1179  */
1181 
1182 /**
1183  * Get title chapter count
1184  *
1185  * \param p_mi the Media Player
1186  * \param i_title title
1187  * \return number of chapters in title, or -1
1188  */
1190  libvlc_media_player_t *p_mi, int i_title );
1191 
1192 /**
1193  * Set movie title
1194  *
1195  * \param p_mi the Media Player
1196  * \param i_title title number to play
1197  */
1199 
1200 /**
1201  * Get movie title
1202  *
1203  * \param p_mi the Media Player
1204  * \return title number currently playing, or -1
1205  */
1207 
1208 /**
1209  * Get movie title count
1210  *
1211  * \param p_mi the Media Player
1212  * \return title number count, or -1
1213  */
1215 
1216 /**
1217  * Set previous chapter (if applicable)
1218  *
1219  * \param p_mi the Media Player
1220  */
1222 
1223 /**
1224  * Set next chapter (if applicable)
1225  *
1226  * \param p_mi the Media Player
1227  */
1229 
1230 /**
1231  * Get the requested movie play rate.
1232  * @warning Depending on the underlying media, the requested rate may be
1233  * different from the real playback rate.
1234  *
1235  * \param p_mi the Media Player
1236  * \return movie play rate
1237  */
1239 
1240 /**
1241  * Set movie play rate
1242  *
1243  * \param p_mi the Media Player
1244  * \param rate movie play rate to set
1245  * \return -1 if an error was detected, 0 otherwise (but even then, it might
1246  * not actually work depending on the underlying media protocol)
1247  */
1249 
1250 /**
1251  * Get current movie state
1252  *
1253  * \param p_mi the Media Player
1254  * \return the current state of the media player (playing, paused, ...) \see libvlc_state_t
1255  */
1257 
1258 /**
1259  * How many video outputs does this media player have?
1260  *
1261  * \param p_mi the media player
1262  * \return the number of video outputs
1263  */
1265 
1266 /**
1267  * Is this media player seekable?
1268  *
1269  * \param p_mi the media player
1270  * \retval true media player can seek
1271  * \retval false media player cannot seek
1272  */
1274 
1275 /**
1276  * Can this media player be paused?
1277  *
1278  * \param p_mi the media player
1279  * \retval true media player can be paused
1280  * \retval false media player cannot be paused
1281  */
1283 
1284 /**
1285  * Check if the current program is scrambled
1286  *
1287  * \param p_mi the media player
1288  * \retval true current program is scrambled
1289  * \retval false current program is not scrambled
1290  *
1291  * \version LibVLC 2.2.0 or later
1292  */
1294 
1295 /**
1296  * Display the next frame (if supported)
1297  *
1298  * \param p_mi the media player
1299  */
1301 
1302 /**
1303  * Navigate through DVD Menu
1304  *
1305  * \param p_mi the Media Player
1306  * \param navigate the Navigation mode
1307  * \version libVLC 2.0.0 or later
1308  */
1310  unsigned navigate );
1311 
1312 /**
1313  * Set if, and how, the video title will be shown when media is played.
1314  *
1315  * \param p_mi the media player
1316  * \param position position at which to display the title, or libvlc_position_disable to prevent the title from being displayed
1317  * \param timeout title display timeout in milliseconds (ignored if libvlc_position_disable)
1318  * \version libVLC 2.1.0 or later
1319  */
1320 LIBVLC_API void libvlc_media_player_set_video_title_display( libvlc_media_player_t *p_mi, libvlc_position_t position, unsigned int timeout );
1321 
1322 /**
1323  * Add a slave to the current media player.
1324  *
1325  * \note If the player is playing, the slave will be added directly. This call
1326  * will also update the slave list of the attached libvlc_media_t.
1327  *
1328  * \version LibVLC 3.0.0 and later.
1329  *
1330  * \see libvlc_media_slaves_add
1331  *
1332  * \param p_mi the media player
1333  * \param i_type subtitle or audio
1334  * \param psz_uri Uri of the slave (should contain a valid scheme).
1335  * \param b_select True if this slave should be selected when it's loaded
1336  *
1337  * \return 0 on success, -1 on error.
1338  */
1339 LIBVLC_API
1342  const char *psz_uri, bool b_select );
1343 
1344 /**
1345  * Release (free) libvlc_track_description_t
1346  *
1347  * \param p_track_description the structure to release
1348  */
1350 
1351 /** \defgroup libvlc_video LibVLC video controls
1352  * @{
1353  */
1354 
1355 /**
1356  * Toggle fullscreen status on non-embedded video outputs.
1357  *
1358  * @warning The same limitations applies to this function
1359  * as to libvlc_set_fullscreen().
1360  *
1361  * \param p_mi the media player
1362  */
1364 
1365 /**
1366  * Enable or disable fullscreen.
1367  *
1368  * @warning With most window managers, only a top-level windows can be in
1369  * full-screen mode. Hence, this function will not operate properly if
1370  * libvlc_media_player_set_xwindow() was used to embed the video in a
1371  * non-top-level window. In that case, the embedding window must be reparented
1372  * to the root window <b>before</b> fullscreen mode is enabled. You will want
1373  * to reparent it back to its normal parent when disabling fullscreen.
1374  *
1375  * \note This setting applies to any and all current or future active video
1376  * tracks and windows for the given media player. The choice of fullscreen
1377  * output for each window is left to the operating system.
1378  *
1379  * \param p_mi the media player
1380  * \param b_fullscreen boolean for fullscreen status
1381  */
1382 LIBVLC_API void libvlc_set_fullscreen(libvlc_media_player_t *p_mi, bool b_fullscreen);
1383 
1384 /**
1385  * Get current fullscreen status.
1386  *
1387  * \param p_mi the media player
1388  * \return the fullscreen status (boolean)
1389  *
1390  * \retval false media player is windowed
1391  * \retval true media player is in fullscreen mode
1392  */
1394 
1395 /**
1396  * Enable or disable key press events handling, according to the LibVLC hotkeys
1397  * configuration. By default and for historical reasons, keyboard events are
1398  * handled by the LibVLC video widget.
1399  *
1400  * \note On X11, there can be only one subscriber for key press and mouse
1401  * click events per window. If your application has subscribed to those events
1402  * for the X window ID of the video widget, then LibVLC will not be able to
1403  * handle key presses and mouse clicks in any case.
1404  *
1405  * \warning This function is only implemented for X11 and Win32 at the moment.
1406  *
1407  * \param p_mi the media player
1408  * \param on true to handle key press events, false to ignore them.
1409  */
1410 LIBVLC_API
1411 void libvlc_video_set_key_input( libvlc_media_player_t *p_mi, unsigned on );
1412 
1413 /**
1414  * Enable or disable mouse click events handling. By default, those events are
1415  * handled. This is needed for DVD menus to work, as well as a few video
1416  * filters such as "puzzle".
1417  *
1418  * \see libvlc_video_set_key_input().
1419  *
1420  * \warning This function is only implemented for X11 and Win32 at the moment.
1421  *
1422  * \param p_mi the media player
1423  * \param on true to handle mouse click events, false to ignore them.
1424  */
1425 LIBVLC_API
1426 void libvlc_video_set_mouse_input( libvlc_media_player_t *p_mi, unsigned on );
1427 
1428 /**
1429  * Get the pixel dimensions of a video.
1430  *
1431  * \param p_mi media player
1432  * \param num number of the video (starting from, and most commonly 0)
1433  * \param px pointer to get the pixel width [OUT]
1434  * \param py pointer to get the pixel height [OUT]
1435  * \return 0 on success, -1 if the specified video does not exist
1436  */
1437 LIBVLC_API
1438 int libvlc_video_get_size( libvlc_media_player_t *p_mi, unsigned num,
1439  unsigned *px, unsigned *py );
1440 
1441 /**
1442  * Get the mouse pointer coordinates over a video.
1443  * Coordinates are expressed in terms of the decoded video resolution,
1444  * <b>not</b> in terms of pixels on the screen/viewport (to get the latter,
1445  * you can query your windowing system directly).
1446  *
1447  * Either of the coordinates may be negative or larger than the corresponding
1448  * dimension of the video, if the cursor is outside the rendering area.
1449  *
1450  * @warning The coordinates may be out-of-date if the pointer is not located
1451  * on the video rendering area. LibVLC does not track the pointer if it is
1452  * outside of the video widget.
1453  *
1454  * @note LibVLC does not support multiple pointers (it does of course support
1455  * multiple input devices sharing the same pointer) at the moment.
1456  *
1457  * \param p_mi media player
1458  * \param num number of the video (starting from, and most commonly 0)
1459  * \param px pointer to get the abscissa [OUT]
1460  * \param py pointer to get the ordinate [OUT]
1461  * \return 0 on success, -1 if the specified video does not exist
1462  */
1463 LIBVLC_API
1464 int libvlc_video_get_cursor( libvlc_media_player_t *p_mi, unsigned num,
1465  int *px, int *py );
1466 
1467 /**
1468  * Get the current video scaling factor.
1469  * See also libvlc_video_set_scale().
1470  *
1471  * \param p_mi the media player
1472  * \return the currently configured zoom factor, or 0. if the video is set
1473  * to fit to the output window/drawable automatically.
1474  */
1476 
1477 /**
1478  * Set the video scaling factor. That is the ratio of the number of pixels on
1479  * screen to the number of pixels in the original decoded video in each
1480  * dimension. Zero is a special value; it will adjust the video to the output
1481  * window/drawable (in windowed mode) or the entire screen.
1482  *
1483  * Note that not all video outputs support scaling.
1484  *
1485  * \param p_mi the media player
1486  * \param f_factor the scaling factor, or zero
1487  */
1488 LIBVLC_API void libvlc_video_set_scale( libvlc_media_player_t *p_mi, float f_factor );
1489 
1490 /**
1491  * Get current video aspect ratio.
1492  *
1493  * \param p_mi the media player
1494  * \return the video aspect ratio or NULL if unspecified
1495  * (the result must be released with free() or libvlc_free()).
1496  */
1498 
1499 /**
1500  * Set new video aspect ratio.
1501  *
1502  * \param p_mi the media player
1503  * \param psz_aspect new video aspect-ratio or NULL to reset to default
1504  * \note Invalid aspect ratios are ignored.
1505  */
1506 LIBVLC_API void libvlc_video_set_aspect_ratio( libvlc_media_player_t *p_mi, const char *psz_aspect );
1507 
1508 /**
1509  * Create a video viewpoint structure.
1510  *
1511  * \version LibVLC 3.0.0 and later
1512  *
1513  * \return video viewpoint or NULL
1514  * (the result must be released with free()).
1515  */
1517 
1518 /**
1519  * Update the video viewpoint information.
1520  *
1521  * \note It is safe to call this function before the media player is started.
1522  *
1523  * \version LibVLC 3.0.0 and later
1524  *
1525  * \param p_mi the media player
1526  * \param p_viewpoint video viewpoint allocated via libvlc_video_new_viewpoint()
1527  * \param b_absolute if true replace the old viewpoint with the new one. If
1528  * false, increase/decrease it.
1529  * \return -1 in case of error, 0 otherwise
1530  *
1531  * \note the values are set asynchronously, it will be used by the next frame displayed.
1532  */
1534  const libvlc_video_viewpoint_t *p_viewpoint,
1535  bool b_absolute);
1536 
1537 /**
1538  * Get current video subtitle.
1539  *
1540  * \param p_mi the media player
1541  * \return the video subtitle selected, or -1 if none
1542  */
1544 
1545 /**
1546  * Get the number of available video subtitles.
1547  *
1548  * \param p_mi the media player
1549  * \return the number of available video subtitles
1550  */
1552 
1553 /**
1554  * Get the description of available video subtitles.
1555  *
1556  * \param p_mi the media player
1557  * \return list containing description of available video subtitles.
1558  * It must be freed with libvlc_track_description_list_release()
1559  */
1562 
1563 /**
1564  * Set new video subtitle.
1565  *
1566  * \param p_mi the media player
1567  * \param i_spu video subtitle track to select (i_id from track description)
1568  * \return 0 on success, -1 if out of range
1569  */
1570 LIBVLC_API int libvlc_video_set_spu( libvlc_media_player_t *p_mi, int i_spu );
1571 
1572 /**
1573  * Get the current subtitle delay. Positive values means subtitles are being
1574  * displayed later, negative values earlier.
1575  *
1576  * \param p_mi media player
1577  * \return time (in microseconds) the display of subtitles is being delayed
1578  * \version LibVLC 2.0.0 or later
1579  */
1581 
1582 /**
1583  * Set the subtitle delay. This affects the timing of when the subtitle will
1584  * be displayed. Positive values result in subtitles being displayed later,
1585  * while negative values will result in subtitles being displayed earlier.
1586  *
1587  * The subtitle delay will be reset to zero each time the media changes.
1588  *
1589  * \param p_mi media player
1590  * \param i_delay time (in microseconds) the display of subtitles should be delayed
1591  * \return 0 on success, -1 on error
1592  * \version LibVLC 2.0.0 or later
1593  */
1594 LIBVLC_API int libvlc_video_set_spu_delay( libvlc_media_player_t *p_mi, int64_t i_delay );
1595 
1596 /**
1597  * Get the full description of available titles
1598  *
1599  * \version LibVLC 3.0.0 and later.
1600  *
1601  * \param p_mi the media player
1602  * \param titles address to store an allocated array of title descriptions
1603  * descriptions (must be freed with libvlc_title_descriptions_release()
1604  * by the caller) [OUT]
1605  *
1606  * \return the number of titles (-1 on error)
1607  */
1609  libvlc_title_description_t ***titles );
1610 
1611 /**
1612  * Release a title description
1613  *
1614  * \version LibVLC 3.0.0 and later
1615  *
1616  * \param p_titles title description array to release
1617  * \param i_count number of title descriptions to release
1618  */
1619 LIBVLC_API
1621  unsigned i_count );
1622 
1623 /**
1624  * Get the full description of available chapters
1625  *
1626  * \version LibVLC 3.0.0 and later.
1627  *
1628  * \param p_mi the media player
1629  * \param i_chapters_of_title index of the title to query for chapters (uses current title if set to -1)
1630  * \param pp_chapters address to store an allocated array of chapter descriptions
1631  * descriptions (must be freed with libvlc_chapter_descriptions_release()
1632  * by the caller) [OUT]
1633  *
1634  * \return the number of chapters (-1 on error)
1635  */
1637  int i_chapters_of_title,
1638  libvlc_chapter_description_t *** pp_chapters );
1639 
1640 /**
1641  * Release a chapter description
1642  *
1643  * \version LibVLC 3.0.0 and later
1644  *
1645  * \param p_chapters chapter description array to release
1646  * \param i_count number of chapter descriptions to release
1647  */
1648 LIBVLC_API
1650  unsigned i_count );
1651 
1652 /**
1653  * Set/unset the video crop ratio.
1654  *
1655  * This function forces a crop ratio on any and all video tracks rendered by
1656  * the media player. If the display aspect ratio of a video does not match the
1657  * crop ratio, either the top and bottom, or the left and right of the video
1658  * will be cut out to fit the crop ratio.
1659  *
1660  * For instance, a ratio of 1:1 will force the video to a square shape.
1661  *
1662  * To disable video crop, set a crop ratio with zero as denominator.
1663  *
1664  * A call to this function overrides any previous call to any of
1665  * libvlc_video_set_crop_ratio(), libvlc_video_set_crop_border() and/or
1666  * libvlc_video_set_crop_window().
1667  *
1668  * \see libvlc_video_set_aspect_ratio()
1669  *
1670  * \param mp the media player
1671  * \param num crop ratio numerator (ignored if denominator is 0)
1672  * \param den crop ratio denominator (or 0 to unset the crop ratio)
1673  *
1674  * \version LibVLC 4.0.0 and later
1675  */
1676 LIBVLC_API
1678  unsigned num, unsigned den);
1679 
1680 /**
1681  * Set the video crop window.
1682  *
1683  * This function selects a sub-rectangle of video to show. Any pixels outside
1684  * the rectangle will not be shown.
1685  *
1686  * To unset the video crop window, use libvlc_video_set_crop_ratio() or
1687  * libvlc_video_set_crop_border().
1688  *
1689  * A call to this function overrides any previous call to any of
1690  * libvlc_video_set_crop_ratio(), libvlc_video_set_crop_border() and/or
1691  * libvlc_video_set_crop_window().
1692  *
1693  * \param mp the media player
1694  * \param x abscissa (i.e. leftmost sample column offset) of the crop window
1695  * \param y ordinate (i.e. topmost sample row offset) of the crop window
1696  * \param width sample width of the crop window (cannot be zero)
1697  * \param height sample height of the crop window (cannot be zero)
1698  *
1699  * \version LibVLC 4.0.0 and later
1700  */
1701 LIBVLC_API
1703  unsigned x, unsigned y,
1704  unsigned width, unsigned height);
1705 
1706 /**
1707  * Set the video crop borders.
1708  *
1709  * This function selects the size of video edges to be cropped out.
1710  *
1711  * To unset the video crop borders, set all borders to zero.
1712  *
1713  * A call to this function overrides any previous call to any of
1714  * libvlc_video_set_crop_ratio(), libvlc_video_set_crop_border() and/or
1715  * libvlc_video_set_crop_window().
1716  *
1717  * \param mp the media player
1718  * \param left number of sample columns to crop on the left
1719  * \param right number of sample columns to crop on the right
1720  * \param top number of sample rows to crop on the top
1721  * \param bottom number of sample rows to corp on the bottom
1722  *
1723  * \version LibVLC 4.0.0 and later
1724  */
1725 LIBVLC_API
1727  unsigned left, unsigned right,
1728  unsigned top, unsigned bottom);
1729 
1730 /**
1731  * Get current teletext page requested or 0 if it's disabled.
1732  *
1733  * Teletext is disabled by default, call libvlc_video_set_teletext() to enable
1734  * it.
1735  *
1736  * \param p_mi the media player
1737  * \return the current teletext page requested.
1738  */
1740 
1741 /**
1742  * Set new teletext page to retrieve.
1743  *
1744  * This function can also be used to send a teletext key.
1745  *
1746  * \param p_mi the media player
1747  * \param i_page teletex page number requested. This value can be 0 to disable
1748  * teletext, a number in the range ]0;1000[ to show the requested page, or a
1749  * \ref libvlc_teletext_key_t. 100 is the default teletext page.
1750  */
1752 
1753 /**
1754  * Get number of available video tracks.
1755  *
1756  * \param p_mi media player
1757  * \return the number of available video tracks (int)
1758  */
1760 
1761 /**
1762  * Get the description of available video tracks.
1763  *
1764  * \param p_mi media player
1765  * \return list with description of available video tracks, or NULL on error.
1766  * It must be freed with libvlc_track_description_list_release()
1767  */
1770 
1771 /**
1772  * Get current video track.
1773  *
1774  * \param p_mi media player
1775  * \return the video track ID (int) or -1 if no active input
1776  */
1778 
1779 /**
1780  * Set video track.
1781  *
1782  * \param p_mi media player
1783  * \param i_track the track ID (i_id field from track description)
1784  * \return 0 on success, -1 if out of range
1785  */
1786 LIBVLC_API
1787 int libvlc_video_set_track( libvlc_media_player_t *p_mi, int i_track );
1788 
1789 /**
1790  * Take a snapshot of the current video window.
1791  *
1792  * If i_width AND i_height is 0, original size is used.
1793  * If i_width XOR i_height is 0, original aspect-ratio is preserved.
1794  *
1795  * \param p_mi media player instance
1796  * \param num number of video output (typically 0 for the first/only one)
1797  * \param psz_filepath the path of a file or a folder to save the screenshot into
1798  * \param i_width the snapshot's width
1799  * \param i_height the snapshot's height
1800  * \return 0 on success, -1 if the video was not found
1801  */
1802 LIBVLC_API
1803 int libvlc_video_take_snapshot( libvlc_media_player_t *p_mi, unsigned num,
1804  const char *psz_filepath, unsigned int i_width,
1805  unsigned int i_height );
1806 
1807 /**
1808  * Enable or disable deinterlace filter
1809  *
1810  * \param p_mi libvlc media player
1811  * \param deinterlace state -1: auto (default), 0: disabled, 1: enabled
1812  * \param psz_mode type of deinterlace filter, NULL for current/default filter
1813  * \version LibVLC 4.0.0 and later
1814  */
1816  int deinterlace,
1817  const char *psz_mode );
1818 
1819 /**
1820  * Get an integer marquee option value
1821  *
1822  * \param p_mi libvlc media player
1823  * \param option marq option to get \see libvlc_video_marquee_option_t
1824  */
1826  unsigned option );
1827 
1828 /**
1829  * Enable, disable or set an integer marquee option
1830  *
1831  * Setting libvlc_marquee_Enable has the side effect of enabling (arg !0)
1832  * or disabling (arg 0) the marq filter.
1833  *
1834  * \param p_mi libvlc media player
1835  * \param option marq option to set \see libvlc_video_marquee_option_t
1836  * \param i_val marq option value
1837  */
1839  unsigned option, int i_val );
1840 
1841 /**
1842  * Set a marquee string option
1843  *
1844  * \param p_mi libvlc media player
1845  * \param option marq option to set \see libvlc_video_marquee_option_t
1846  * \param psz_text marq option value
1847  */
1849  unsigned option, const char *psz_text );
1850 
1851 /** option values for libvlc_video_{get,set}_logo_{int,string} */
1854  libvlc_logo_file, /**< string argument, "file,d,t;file,d,t;..." */
1861 };
1862 
1863 /**
1864  * Get integer logo option.
1865  *
1866  * \param p_mi libvlc media player instance
1867  * \param option logo option to get, values of libvlc_video_logo_option_t
1868  */
1870  unsigned option );
1871 
1872 /**
1873  * Set logo option as integer. Options that take a different type value
1874  * are ignored.
1875  * Passing libvlc_logo_enable as option value has the side effect of
1876  * starting (arg !0) or stopping (arg 0) the logo filter.
1877  *
1878  * \param p_mi libvlc media player instance
1879  * \param option logo option to set, values of libvlc_video_logo_option_t
1880  * \param value logo option value
1881  */
1883  unsigned option, int value );
1884 
1885 /**
1886  * Set logo option as string. Options that take a different type value
1887  * are ignored.
1888  *
1889  * \param p_mi libvlc media player instance
1890  * \param option logo option to set, values of libvlc_video_logo_option_t
1891  * \param psz_value logo option value
1892  */
1894  unsigned option, const char *psz_value );
1895 
1896 
1897 /** option values for libvlc_video_{get,set}_adjust_{int,float,bool} */
1905 };
1906 
1907 /**
1908  * Get integer adjust option.
1909  *
1910  * \param p_mi libvlc media player instance
1911  * \param option adjust option to get, values of libvlc_video_adjust_option_t
1912  * \version LibVLC 1.1.1 and later.
1913  */
1915  unsigned option );
1916 
1917 /**
1918  * Set adjust option as integer. Options that take a different type value
1919  * are ignored.
1920  * Passing libvlc_adjust_enable as option value has the side effect of
1921  * starting (arg !0) or stopping (arg 0) the adjust filter.
1922  *
1923  * \param p_mi libvlc media player instance
1924  * \param option adust option to set, values of libvlc_video_adjust_option_t
1925  * \param value adjust option value
1926  * \version LibVLC 1.1.1 and later.
1927  */
1929  unsigned option, int value );
1930 
1931 /**
1932  * Get float adjust option.
1933  *
1934  * \param p_mi libvlc media player instance
1935  * \param option adjust option to get, values of libvlc_video_adjust_option_t
1936  * \version LibVLC 1.1.1 and later.
1937  */
1939  unsigned option );
1940 
1941 /**
1942  * Set adjust option as float. Options that take a different type value
1943  * are ignored.
1944  *
1945  * \param p_mi libvlc media player instance
1946  * \param option adust option to set, values of libvlc_video_adjust_option_t
1947  * \param value adjust option value
1948  * \version LibVLC 1.1.1 and later.
1949  */
1951  unsigned option, float value );
1952 
1953 /** @} video */
1954 
1955 /** \defgroup libvlc_audio LibVLC audio controls
1956  * @{
1957  */
1958 
1959 /**
1960  * Audio channels
1961  */
1970 
1971 
1972 /**
1973  * Gets the list of available audio output modules.
1974  *
1975  * \param p_instance libvlc instance
1976  * \return list of available audio outputs. It must be freed with
1977 * \see libvlc_audio_output_list_release \see libvlc_audio_output_t .
1978  * In case of error, NULL is returned.
1979  */
1982 
1983 /**
1984  * Frees the list of available audio output modules.
1985  *
1986  * \param p_list list with audio outputs for release
1987  */
1988 LIBVLC_API
1990 
1991 /**
1992  * Selects an audio output module.
1993  * \note Any change will take be effect only after playback is stopped and
1994  * restarted. Audio output cannot be changed while playing.
1995  *
1996  * \param p_mi media player
1997  * \param psz_name name of audio output,
1998  * use psz_name of \see libvlc_audio_output_t
1999  * \return 0 if function succeeded, -1 on error
2000  */
2002  const char *psz_name );
2003 
2004 /**
2005  * Gets a list of potential audio output devices,
2006  * \see libvlc_audio_output_device_set().
2007  *
2008  * \note Not all audio outputs support enumerating devices.
2009  * The audio output may be functional even if the list is empty (NULL).
2010  *
2011  * \note The list may not be exhaustive.
2012  *
2013  * \warning Some audio output devices in the list might not actually work in
2014  * some circumstances. By default, it is recommended to not specify any
2015  * explicit audio device.
2016  *
2017  * \param mp media player
2018  * \return A NULL-terminated linked list of potential audio output devices.
2019  * It must be freed with libvlc_audio_output_device_list_release()
2020  * \version LibVLC 2.2.0 or later.
2021  */
2024 
2025 /**
2026  * Gets a list of audio output devices for a given audio output module,
2027  * \see libvlc_audio_output_device_set().
2028  *
2029  * \note Not all audio outputs support this. In particular, an empty (NULL)
2030  * list of devices does <b>not</b> imply that the specified audio output does
2031  * not work.
2032  *
2033  * \note The list might not be exhaustive.
2034  *
2035  * \warning Some audio output devices in the list might not actually work in
2036  * some circumstances. By default, it is recommended to not specify any
2037  * explicit audio device.
2038  *
2039  * \param p_instance libvlc instance
2040  * \param aout audio output name
2041  * (as returned by libvlc_audio_output_list_get())
2042  * \return A NULL-terminated linked list of potential audio output devices.
2043  * It must be freed with libvlc_audio_output_device_list_release()
2044  * \version LibVLC 2.1.0 or later.
2045  */
2048  const char *aout );
2049 
2050 /**
2051  * Frees a list of available audio output devices.
2052  *
2053  * \param p_list list with audio outputs for release
2054  * \version LibVLC 2.1.0 or later.
2055  */
2057  libvlc_audio_output_device_t *p_list );
2058 
2059 /**
2060  * Configures an explicit audio output device.
2061  *
2062  * If the module paramater is NULL, audio output will be moved to the device
2063  * specified by the device identifier string immediately. This is the
2064  * recommended usage.
2065  *
2066  * A list of adequate potential device strings can be obtained with
2067  * libvlc_audio_output_device_enum().
2068  *
2069  * However passing NULL is supported in LibVLC version 2.2.0 and later only;
2070  * in earlier versions, this function would have no effects when the module
2071  * parameter was NULL.
2072  *
2073  * If the module parameter is not NULL, the device parameter of the
2074  * corresponding audio output, if it exists, will be set to the specified
2075  * string. Note that some audio output modules do not have such a parameter
2076  * (notably MMDevice and PulseAudio).
2077  *
2078  * A list of adequate potential device strings can be obtained with
2079  * libvlc_audio_output_device_list_get().
2080  *
2081  * \note This function does not select the specified audio output plugin.
2082  * libvlc_audio_output_set() is used for that purpose.
2083  *
2084  * \warning The syntax for the device parameter depends on the audio output.
2085  *
2086  * Some audio output modules require further parameters (e.g. a channels map
2087  * in the case of ALSA).
2088  *
2089  * \param mp media player
2090  * \param module If NULL, current audio output module.
2091  * if non-NULL, name of audio output module
2092  (\see libvlc_audio_output_t)
2093  * \param device_id device identifier string
2094  * \return Nothing. Errors are ignored (this is a design bug).
2095  */
2097  const char *module,
2098  const char *device_id );
2099 
2100 /**
2101  * Get the current audio output device identifier.
2102  *
2103  * This complements libvlc_audio_output_device_set().
2104  *
2105  * \warning The initial value for the current audio output device identifier
2106  * may not be set or may be some unknown value. A LibVLC application should
2107  * compare this value against the known device identifiers (e.g. those that
2108  * were previously retrieved by a call to libvlc_audio_output_device_enum or
2109  * libvlc_audio_output_device_list_get) to find the current audio output device.
2110  *
2111  * It is possible that the selected audio output device changes (an external
2112  * change) without a call to libvlc_audio_output_device_set. That may make this
2113  * method unsuitable to use if a LibVLC application is attempting to track
2114  * dynamic audio device changes as they happen.
2115  *
2116  * \param mp media player
2117  * \return the current audio output device identifier
2118  * NULL if no device is selected or in case of error
2119  * (the result must be released with free()).
2120  * \version LibVLC 3.0.0 or later.
2121  */
2123 
2124 /**
2125  * Toggle mute status.
2126  *
2127  * \param p_mi media player
2128  * \warning Toggling mute atomically is not always possible: On some platforms,
2129  * other processes can mute the VLC audio playback stream asynchronously. Thus,
2130  * there is a small race condition where toggling will not work.
2131  * See also the limitations of libvlc_audio_set_mute().
2132  */
2134 
2135 /**
2136  * Get current mute status.
2137  *
2138  * \param p_mi media player
2139  * \return the mute status (boolean) if defined, -1 if undefined/unapplicable
2140  */
2142 
2143 /**
2144  * Set mute status.
2145  *
2146  * \param p_mi media player
2147  * \param status If status is true then mute, otherwise unmute
2148  * \warning This function does not always work. If there are no active audio
2149  * playback stream, the mute status might not be available. If digital
2150  * pass-through (S/PDIF, HDMI...) is in use, muting may be unapplicable. Also
2151  * some audio output plugins do not support muting at all.
2152  * \note To force silent playback, disable all audio tracks. This is more
2153  * efficient and reliable than mute.
2154  */
2155 LIBVLC_API void libvlc_audio_set_mute( libvlc_media_player_t *p_mi, int status );
2156 
2157 /**
2158  * Get current software audio volume.
2159  *
2160  * \param p_mi media player
2161  * \return the software volume in percents
2162  * (0 = mute, 100 = nominal / 0dB)
2163  */
2165 
2166 /**
2167  * Set current software audio volume.
2168  *
2169  * \param p_mi media player
2170  * \param i_volume the volume in percents (0 = mute, 100 = 0dB)
2171  * \return 0 if the volume was set, -1 if it was out of range
2172  */
2173 LIBVLC_API int libvlc_audio_set_volume( libvlc_media_player_t *p_mi, int i_volume );
2174 
2175 /**
2176  * Get number of available audio tracks.
2177  *
2178  * \param p_mi media player
2179  * \return the number of available audio tracks (int), or -1 if unavailable
2180  */
2182 
2183 /**
2184  * Get the description of available audio tracks.
2185  *
2186  * \param p_mi media player
2187  * \return list with description of available audio tracks, or NULL.
2188  * It must be freed with libvlc_track_description_list_release()
2189  */
2192 
2193 /**
2194  * Get current audio track.
2195  *
2196  * \param p_mi media player
2197  * \return the audio track ID or -1 if no active input.
2198  */
2200 
2201 /**
2202  * Set current audio track.
2203  *
2204  * \param p_mi media player
2205  * \param i_track the track ID (i_id field from track description)
2206  * \return 0 on success, -1 on error
2207  */
2208 LIBVLC_API int libvlc_audio_set_track( libvlc_media_player_t *p_mi, int i_track );
2209 
2210 /**
2211  * Get current audio channel.
2212  *
2213  * \param p_mi media player
2214  * \return the audio channel \see libvlc_audio_output_channel_t
2215  */
2217 
2218 /**
2219  * Set current audio channel.
2220  *
2221  * \param p_mi media player
2222  * \param channel the audio channel, \see libvlc_audio_output_channel_t
2223  * \return 0 on success, -1 on error
2224  */
2226 
2227 /**
2228  * Get current audio delay.
2229  *
2230  * \param p_mi media player
2231  * \return the audio delay (microseconds)
2232  * \version LibVLC 1.1.1 or later
2233  */
2235 
2236 /**
2237  * Set current audio delay. The audio delay will be reset to zero each time the media changes.
2238  *
2239  * \param p_mi media player
2240  * \param i_delay the audio delay (microseconds)
2241  * \return 0 on success, -1 on error
2242  * \version LibVLC 1.1.1 or later
2243  */
2244 LIBVLC_API int libvlc_audio_set_delay( libvlc_media_player_t *p_mi, int64_t i_delay );
2245 
2246 /**
2247  * Get the number of equalizer presets.
2248  *
2249  * \return number of presets
2250  * \version LibVLC 2.2.0 or later
2251  */
2253 
2254 /**
2255  * Get the name of a particular equalizer preset.
2256  *
2257  * This name can be used, for example, to prepare a preset label or menu in a user
2258  * interface.
2259  *
2260  * \param u_index index of the preset, counting from zero
2261  * \return preset name, or NULL if there is no such preset
2262  * \version LibVLC 2.2.0 or later
2263  */
2264 LIBVLC_API const char *libvlc_audio_equalizer_get_preset_name( unsigned u_index );
2265 
2266 /**
2267  * Get the number of distinct frequency bands for an equalizer.
2268  *
2269  * \return number of frequency bands
2270  * \version LibVLC 2.2.0 or later
2271  */
2273 
2274 /**
2275  * Get a particular equalizer band frequency.
2276  *
2277  * This value can be used, for example, to create a label for an equalizer band control
2278  * in a user interface.
2279  *
2280  * \param u_index index of the band, counting from zero
2281  * \return equalizer band frequency (Hz), or -1 if there is no such band
2282  * \version LibVLC 2.2.0 or later
2283  */
2284 LIBVLC_API float libvlc_audio_equalizer_get_band_frequency( unsigned u_index );
2285 
2286 /**
2287  * Create a new default equalizer, with all frequency values zeroed.
2288  *
2289  * The new equalizer can subsequently be applied to a media player by invoking
2290  * libvlc_media_player_set_equalizer().
2291  *
2292  * The returned handle should be freed via libvlc_audio_equalizer_release() when
2293  * it is no longer needed.
2294  *
2295  * \return opaque equalizer handle, or NULL on error
2296  * \version LibVLC 2.2.0 or later
2297  */
2299 
2300 /**
2301  * Create a new equalizer, with initial frequency values copied from an existing
2302  * preset.
2303  *
2304  * The new equalizer can subsequently be applied to a media player by invoking
2305  * libvlc_media_player_set_equalizer().
2306  *
2307  * The returned handle should be freed via libvlc_audio_equalizer_release() when
2308  * it is no longer needed.
2309  *
2310  * \param u_index index of the preset, counting from zero
2311  * \return opaque equalizer handle, or NULL on error
2312  * (it must be released with libvlc_audio_equalizer_release())
2313  * \version LibVLC 2.2.0 or later
2314  */
2316 
2317 /**
2318  * Release a previously created equalizer instance.
2319  *
2320  * The equalizer was previously created by using libvlc_audio_equalizer_new() or
2321  * libvlc_audio_equalizer_new_from_preset().
2322  *
2323  * It is safe to invoke this method with a NULL p_equalizer parameter for no effect.
2324  *
2325  * \param p_equalizer opaque equalizer handle, or NULL
2326  * \version LibVLC 2.2.0 or later
2327  */
2329 
2330 /**
2331  * Set a new pre-amplification value for an equalizer.
2332  *
2333  * The new equalizer settings are subsequently applied to a media player by invoking
2334  * libvlc_media_player_set_equalizer().
2335  *
2336  * The supplied amplification value will be clamped to the -20.0 to +20.0 range.
2337  *
2338  * \param p_equalizer valid equalizer handle, must not be NULL
2339  * \param f_preamp preamp value (-20.0 to 20.0 Hz)
2340  * \return zero on success, -1 on error
2341  * \version LibVLC 2.2.0 or later
2342  */
2343 LIBVLC_API int libvlc_audio_equalizer_set_preamp( libvlc_equalizer_t *p_equalizer, float f_preamp );
2344 
2345 /**
2346  * Get the current pre-amplification value from an equalizer.
2347  *
2348  * \param p_equalizer valid equalizer handle, must not be NULL
2349  * \return preamp value (Hz)
2350  * \version LibVLC 2.2.0 or later
2351  */
2353 
2354 /**
2355  * Set a new amplification value for a particular equalizer frequency band.
2356  *
2357  * The new equalizer settings are subsequently applied to a media player by invoking
2358  * libvlc_media_player_set_equalizer().
2359  *
2360  * The supplied amplification value will be clamped to the -20.0 to +20.0 range.
2361  *
2362  * \param p_equalizer valid equalizer handle, must not be NULL
2363  * \param f_amp amplification value (-20.0 to 20.0 Hz)
2364  * \param u_band index, counting from zero, of the frequency band to set
2365  * \return zero on success, -1 on error
2366  * \version LibVLC 2.2.0 or later
2367  */
2368 LIBVLC_API int libvlc_audio_equalizer_set_amp_at_index( libvlc_equalizer_t *p_equalizer, float f_amp, unsigned u_band );
2369 
2370 /**
2371  * Get the amplification value for a particular equalizer frequency band.
2372  *
2373  * \param p_equalizer valid equalizer handle, must not be NULL
2374  * \param u_band index, counting from zero, of the frequency band to get
2375  * \return amplification value (Hz); NaN if there is no such frequency band
2376  * \version LibVLC 2.2.0 or later
2377  */
2378 LIBVLC_API float libvlc_audio_equalizer_get_amp_at_index( libvlc_equalizer_t *p_equalizer, unsigned u_band );
2379 
2380 /**
2381  * Apply new equalizer settings to a media player.
2382  *
2383  * The equalizer is first created by invoking libvlc_audio_equalizer_new() or
2384  * libvlc_audio_equalizer_new_from_preset().
2385  *
2386  * It is possible to apply new equalizer settings to a media player whether the media
2387  * player is currently playing media or not.
2388  *
2389  * Invoking this method will immediately apply the new equalizer settings to the audio
2390  * output of the currently playing media if there is any.
2391  *
2392  * If there is no currently playing media, the new equalizer settings will be applied
2393  * later if and when new media is played.
2394  *
2395  * Equalizer settings will automatically be applied to subsequently played media.
2396  *
2397  * To disable the equalizer for a media player invoke this method passing NULL for the
2398  * p_equalizer parameter.
2399  *
2400  * The media player does not keep a reference to the supplied equalizer so it is safe
2401  * for an application to release the equalizer reference any time after this method
2402  * returns.
2403  *
2404  * \param p_mi opaque media player handle
2405  * \param p_equalizer opaque equalizer handle, or NULL to disable the equalizer for this media player
2406  * \return zero on success, -1 on error
2407  * \version LibVLC 2.2.0 or later
2408  */
2410 
2411 /**
2412  * Media player roles.
2413  *
2414  * \version LibVLC 3.0.0 and later.
2415  *
2416  * See \ref libvlc_media_player_set_role()
2417  */
2419  libvlc_role_None = 0, /**< Don't use a media player role */
2420  libvlc_role_Music, /**< Music (or radio) playback */
2421  libvlc_role_Video, /**< Video playback */
2422  libvlc_role_Communication, /**< Speech, real-time communication */
2423  libvlc_role_Game, /**< Video game */
2424  libvlc_role_Notification, /**< User interaction feedback */
2425  libvlc_role_Animation, /**< Embedded animation (e.g. in web page) */
2426  libvlc_role_Production, /**< Audio editting/production */
2427  libvlc_role_Accessibility, /**< Accessibility */
2428  libvlc_role_Test /** Testing */
2429 #define libvlc_role_Last libvlc_role_Test
2431 
2432 /**
2433  * Gets the media role.
2434  *
2435  * \version LibVLC 3.0.0 and later.
2436  *
2437  * \param p_mi media player
2438  * \return the media player role (\ref libvlc_media_player_role_t)
2439  */
2441 
2442 /**
2443  * Sets the media role.
2444  *
2445  * \param p_mi media player
2446  * \param role the media player role (\ref libvlc_media_player_role_t)
2447  * \return 0 on success, -1 on error
2448  */
2450  unsigned role);
2451 
2452 /** @} audio */
2453 
2454 /** @} media_player */
2455 
2456 # ifdef __cplusplus
2457 }
2458 # endif
2459 
2460 #endif /* VLC_LIBVLC_MEDIA_PLAYER_H */
LIBVLC_API void libvlc_media_player_release(libvlc_media_player_t *p_mi)
Release a media_player after use Decrement the reference count of a media player object.
Music (or radio) playback.
Definition: libvlc_media_player.h:2420
LIBVLC_API int libvlc_video_get_track(libvlc_media_player_t *p_mi)
Get current video track.
Definition: libvlc_media_player.h:159
LIBVLC_API void libvlc_video_set_crop_ratio(libvlc_media_player_t *mp, unsigned num, unsigned den)
Set/unset the video crop ratio.
Definition: libvlc_media_player.h:116
LIBVLC_API void libvlc_media_player_set_pause(libvlc_media_player_t *mp, int do_pause)
Pause or resume (no effect if there is no media)
Definition: libvlc_media_player.h:139
Definition: libvlc_media_player.h:126
Definition: libvlc_media_player.h:1857
Definition: libvlc_media_player.h:324
LIBVLC_API unsigned libvlc_audio_equalizer_get_band_count(void)
Get the number of distinct frequency bands for an equalizer.
string argument, "file,d,t;file,d,t;..."
Definition: libvlc_media_player.h:1854
Definition: libvlc_media_player.h:1965
LIBVLC_API float libvlc_media_player_get_position(libvlc_media_player_t *p_mi)
Get movie position as percentage between 0.0 and 1.0.
unsigned width
Definition: libvlc_media_player.h:670
unsigned int MinMasteringLuminance
Definition: libvlc_media_player.h:717
struct libvlc_track_description_t libvlc_track_description_t
Description for video, audio tracks and subtitles.
Definition: libvlc_media_player.h:62
Definition: libvlc_media_player.h:65
LIBVLC_API int libvlc_media_player_get_chapter(libvlc_media_player_t *p_mi)
Get movie chapter.
LIBVLC_API void libvlc_video_set_crop_window(libvlc_media_player_t *mp, unsigned x, unsigned y, unsigned width, unsigned height)
Set the video crop window.
LIBVLC_API int libvlc_audio_set_track(libvlc_media_player_t *p_mi, int i_track)
Set current audio track.
char * psz_name
chapter name
Definition: libvlc_media_player.h:79
int surface_format
Definition: libvlc_media_player.h:682
libvlc_video_adjust_option_t
option values for libvlc_video_{get,set}_adjust_{int,float,bool}
Definition: libvlc_media_player.h:1898
LIBVLC_API libvlc_media_player_t * libvlc_media_player_new_from_media(libvlc_media_t *p_md)
Create a Media Player object from a Media.
Definition: libvlc_media_player.h:300
Definition: libvlc_media_player.h:1901
Definition: libvlc_media_player.h:562
LIBVLC_API int libvlc_video_get_spu(libvlc_media_player_t *p_mi)
Get current video subtitle.
int64_t i_duration
duration of the chapter in milliseconds
Definition: libvlc_media_player.h:78
libvlc_video_color_space_t colorspace
video is full range or studio/limited range
Definition: libvlc_media_player.h:685
Definition: libvlc_media_player.h:311
Definition: libvlc_media_player.h:310
Definition: libvlc_media_player.h:709
LIBVLC_API int libvlc_video_get_track_count(libvlc_media_player_t *p_mi)
Get number of available video tracks.
void(* libvlc_audio_pause_cb)(void *data, int64_t pts)
Callback prototype for audio pause.
Definition: libvlc_media_player.h:966
libvlc_position_t
Enumeration of values used to set position (e.g.
Definition: libvlc_media_player.h:137
LIBVLC_API libvlc_time_t libvlc_media_player_get_time(libvlc_media_player_t *p_mi)
Get the current movie time (in ms).
LIBVLC_API void libvlc_video_set_crop_border(libvlc_media_player_t *mp, unsigned left, unsigned right, unsigned top, unsigned bottom)
Set the video crop borders.
int(* libvlc_audio_setup_cb)(void **opaque, char *format, unsigned *rate, unsigned *channels)
Callback prototype to setup the audio playback.
Definition: libvlc_media_player.h:1064
unsigned(* libvlc_video_format_cb)(void **opaque, char *chroma, unsigned *width, unsigned *height, unsigned *pitches, unsigned *lines)
Callback prototype to configure picture buffers format.
Definition: libvlc_media_player.h:406
LIBVLC_API int libvlc_audio_equalizer_set_amp_at_index(libvlc_equalizer_t *p_equalizer, float f_amp, unsigned u_band)
Set a new amplification value for a particular equalizer frequency band.
libvlc_state_t
Note the order of libvlc_state_t enum must match exactly the order of.
Definition: libvlc_media.h:85
Definition: libvlc_media_player.h:144
LIBVLC_API int libvlc_media_player_set_time(libvlc_media_player_t *p_mi, libvlc_time_t i_time, bool b_fast)
Set the movie time (in ms).
LIBVLC_API void libvlc_video_set_scale(libvlc_media_player_t *p_mi, float f_factor)
Set the video scaling factor.
bool(* libvlc_video_direct3d_select_plane_cb)(void *opaque, size_t plane)
Tell the host the rendering for the given plane is about to start.
Definition: libvlc_media_player.h:765
void *(* libvlc_video_lock_cb)(void *opaque, void **planes)
Callback prototype to allocate and lock a picture buffer.
Definition: libvlc_media_player.h:343
libvlc_video_marquee_option_t
Marq options definition.
Definition: libvlc_media_player.h:108
struct libvlc_event_manager_t libvlc_event_manager_t
Event manager that belongs to a libvlc object, and from whom events can be received.
Definition: libvlc.h:304
Definition: libvlc_media_player.h:140
LIBVLC_API void libvlc_audio_output_device_list_release(libvlc_audio_output_device_t *p_list)
Frees a list of available audio output devices.
Audio editting/production.
Definition: libvlc_media_player.h:2426
Definition: libvlc_media_player.h:110
LIBVLC_API int libvlc_video_set_spu_delay(libvlc_media_player_t *p_mi, int64_t i_delay)
Set the subtitle delay.
Definition: libvlc_media_player.h:297
Definition: libvlc_media_player.h:1856
Description for video, audio tracks and subtitles.
Definition: libvlc_media_player.h:48
libvlc_teletext_key_t
Enumeration of teletext keys than can be passed via libvlc_video_set_teletext()
Definition: libvlc_media_player.h:154
Definition: libvlc_media_player.h:115
LIBVLC_API void libvlc_video_set_aspect_ratio(libvlc_media_player_t *p_mi, const char *psz_aspect)
Set new video aspect ratio.
Definition: libvlc_media_player.h:322
libvlc_media_slave_type_t
Type of a media slave: subtitle or audio.
Definition: libvlc_media.h:295
struct libvlc_title_description_t libvlc_title_description_t
vlc_mutex_t lock
Definition: rand.c:32
Definition: libvlc_media_player.h:1963
void(* libvlc_video_cleanup_cb)(void *opaque)
Callback prototype to configure picture buffers format.
Definition: libvlc_media_player.h:417
LIBVLC_API void libvlc_audio_set_mute(libvlc_media_player_t *p_mi, int status)
Set mute status.
struct libvlc_media_t libvlc_media_t
Definition: libvlc_media.h:43
LIBVLC_API int libvlc_video_get_cursor(libvlc_media_player_t *p_mi, unsigned num, int *px, int *py)
Get the mouse pointer coordinates over a video.
LIBVLC_API libvlc_equalizer_t * libvlc_audio_equalizer_new(void)
Create a new default equalizer, with all frequency values zeroed.
bool full_range
the rendering DXGI_FORMAT for libvlc_video_direct3d_engine_d3d11, D3DFORMAT for libvlc_video_direct3d...
Definition: libvlc_media_player.h:684
#define LIBVLC_API
Definition: libvlc.h:42
Definition: libvlc_media_player.h:668
bool hardware_decoding
Definition: libvlc_media_player.h:613
LIBVLC_API void libvlc_media_player_set_android_context(libvlc_media_player_t *p_mi, void *p_awindow_handler)
Set the android context.
LIBVLC_API void libvlc_toggle_fullscreen(libvlc_media_player_t *p_mi)
Toggle fullscreen status on non-embedded video outputs.
LIBVLC_API int libvlc_audio_get_volume(libvlc_media_player_t *p_mi)
Get current software audio volume.
LIBVLC_API float libvlc_audio_equalizer_get_preamp(libvlc_equalizer_t *p_equalizer)
Get the current pre-amplification value from an equalizer.
libvlc_media_player_role
Media player roles.
Definition: libvlc_media_player.h:2418
string argument
Definition: libvlc_media_player.h:111
LIBVLC_API int libvlc_video_take_snapshot(libvlc_media_player_t *p_mi, unsigned num, const char *psz_filepath, unsigned int i_width, unsigned int i_height)
Take a snapshot of the current video window.
Definition: libvlc_media_player.h:157
Definition: libvlc_media_player.h:1900
LIBVLC_API void libvlc_media_player_set_xwindow(libvlc_media_player_t *p_mi, uint32_t drawable)
Set an X Window System drawable where the media player should render its video output.
void(* libvlc_audio_set_volume_cb)(void *data, float volume, bool mute)
Callback prototype for audio volume change.
Definition: libvlc_media_player.h:1008
LIBVLC_API void libvlc_audio_equalizer_release(libvlc_equalizer_t *p_equalizer)
Release a previously created equalizer instance.
LIBVLC_API int libvlc_media_player_get_role(libvlc_media_player_t *p_mi)
Gets the media role.
LIBVLC_API void libvlc_video_set_logo_string(libvlc_media_player_t *p_mi, unsigned option, const char *psz_value)
Set logo option as string.
LIBVLC_API void libvlc_media_player_set_hwnd(libvlc_media_player_t *p_mi, void *drawable)
Set a Win32/Win64 API window handle (HWND) where the media player should render its video output...
LIBVLC_API int libvlc_audio_get_track_count(libvlc_media_player_t *p_mi)
Get number of available audio tracks.
LIBVLC_API void libvlc_media_player_next_frame(libvlc_media_player_t *p_mi)
Display the next frame (if supported)
Definition: libvlc_media_player.h:1967
void(* libvlc_video_direct3d_set_resize_cb)(void *opaque, void(*report_size_change)(void *report_opaque, unsigned width, unsigned height), void *report_opaque)
Set the callback to call when the host app resizes the rendering area.
Definition: libvlc_media_player.h:664
Description for audio output.
Definition: libvlc_media_player.h:86
LIBVLC_API int libvlc_media_player_set_role(libvlc_media_player_t *p_mi, unsigned role)
Sets the media role.
LIBVLC_API libvlc_audio_output_t * libvlc_audio_output_list_get(libvlc_instance_t *p_instance)
Gets the list of available audio output modules.
LIBVLC_API void libvlc_video_set_deinterlace(libvlc_media_player_t *p_mi, int deinterlace, const char *psz_mode)
Enable or disable deinterlace filter.
void(* libvlc_audio_cleanup_cb)(void *data)
Callback prototype for audio playback cleanup.
Definition: libvlc_media_player.h:1073
LIBVLC_API libvlc_media_player_t * libvlc_media_player_new(libvlc_instance_t *p_libvlc_instance)
Create an empty Media Player object.
uint16_t MaxFrameAverageLightLevel
Definition: libvlc_media_player.h:719
Definition: libvlc_media_player.h:145
Definition: libvlc_media_player.h:141
LIBVLC_API int libvlc_audio_get_mute(libvlc_media_player_t *p_mi)
Get current mute status.
libvlc_video_color_primaries_t primaries
video color space
Definition: libvlc_media_player.h:675
int adapter
ID3D11DeviceContext* for D3D11, IDirect3D9 * for D3D9.
Definition: libvlc_media_player.h:619
LIBVLC_API int64_t libvlc_audio_get_delay(libvlc_media_player_t *p_mi)
Get current audio delay.
LIBVLC_API float libvlc_media_player_get_rate(libvlc_media_player_t *p_mi)
Get the requested movie play rate.
Definition: libvlc_media_player.h:1968
LIBVLC_API bool libvlc_media_player_is_seekable(libvlc_media_player_t *p_mi)
Is this media player seekable?
Definition: libvlc_media_player.h:146
LIBVLC_API void libvlc_video_set_callbacks(libvlc_media_player_t *mp, libvlc_video_lock_cb lock, libvlc_video_unlock_cb unlock, libvlc_video_display_cb display, void *opaque)
Set callbacks and private data to render decoded video to a custom area in memory.
LIBVLC_API void libvlc_media_player_next_chapter(libvlc_media_player_t *p_mi)
Set next chapter (if applicable)
LIBVLC_API int libvlc_audio_equalizer_set_preamp(libvlc_equalizer_t *p_equalizer, float f_preamp)
Set a new pre-amplification value for an equalizer.
LIBVLC_API float libvlc_audio_equalizer_get_amp_at_index(libvlc_equalizer_t *p_equalizer, unsigned u_band)
Get the amplification value for a particular equalizer frequency band.
Description for audio output device.
Definition: libvlc_media_player.h:97
Video game.
Definition: libvlc_media_player.h:2423
LIBVLC_API void libvlc_media_player_previous_chapter(libvlc_media_player_t *p_mi)
Set previous chapter (if applicable)
Definition: libvlc_media_player.h:298
Definition: libvlc_media_player.h:113
libvlc_video_color_space_t
Enumeration of the Video color spaces.
Definition: libvlc_media_player.h:308
unsigned bitdepth
rendering video height in pixel
Definition: libvlc_media_player.h:672
Definition: libvlc_media_player.h:299
LIBVLC_API void libvlc_video_set_adjust_float(libvlc_media_player_t *p_mi, unsigned option, float value)
Set adjust option as float.
int64_t i_time_offset
time-offset of the chapter in milliseconds
Definition: libvlc_media_player.h:77
Definition: libvlc_media_player.h:323
Definition: libvlc_media_player.h:131
struct libvlc_track_description_t * p_next
Definition: libvlc_media_player.h:52
LIBVLC_API void libvlc_media_player_set_title(libvlc_media_player_t *p_mi, int i_title)
Set movie title.
void(* libvlc_video_swap_cb)(void *opaque)
Callback prototype called after performing drawing calls.
Definition: libvlc_media_player.h:535
Definition: libvlc_media_player.h:563
LIBVLC_API void libvlc_set_fullscreen(libvlc_media_player_t *p_mi, bool b_fullscreen)
Enable or disable fullscreen.
LIBVLC_API unsigned libvlc_audio_equalizer_get_preset_count(void)
Get the number of equalizer presets.
LIBVLC_API int libvlc_audio_set_channel(libvlc_media_player_t *p_mi, int channel)
Set current audio channel.
LIBVLC_API void libvlc_audio_set_volume_callback(libvlc_media_player_t *mp, libvlc_audio_set_volume_cb set_volume)
Set callbacks and private data for decoded audio.
LIBVLC_API int64_t libvlc_video_get_spu_delay(libvlc_media_player_t *p_mi)
Get the current subtitle delay.
LIBVLC_API int libvlc_media_player_get_chapter_count_for_title(libvlc_media_player_t *p_mi, int i_title)
Get title chapter count.
LIBVLC_API void libvlc_video_set_teletext(libvlc_media_player_t *p_mi, int i_page)
Set new teletext page to retrieve.
LIBVLC_API bool libvlc_video_set_output_callbacks(libvlc_media_player_t *mp, libvlc_video_engine_t engine, libvlc_video_setup_cb setup_cb, libvlc_video_cleanup_cb cleanup_cb, libvlc_video_update_output_cb update_output_cb, libvlc_video_swap_cb swap_cb, libvlc_video_makeCurrent_cb makeCurrent_cb, libvlc_video_getProcAddress_cb getProcAddress_cb, void *opaque)
Set callbacks and data to render decoded video to a custom texture.
LIBVLC_API const char * libvlc_audio_equalizer_get_preset_name(unsigned u_index)
Get the name of a particular equalizer preset.
LIBVLC_API int libvlc_media_player_add_slave(libvlc_media_player_t *p_mi, libvlc_media_slave_type_t i_type, const char *psz_uri, bool b_select)
Add a slave to the current media player.
LIBVLC_API bool libvlc_video_direct3d_set_callbacks(libvlc_media_player_t *mp, libvlc_video_direct3d_engine_t engine, libvlc_video_direct3d_device_setup_cb setup_cb, libvlc_video_direct3d_device_cleanup_cb cleanup_cb, libvlc_video_direct3d_set_resize_cb resize_cb, libvlc_video_direct3d_update_output_cb update_output_cb, libvlc_video_swap_cb swap_cb, libvlc_video_direct3d_start_end_rendering_cb makeCurrent_cb, libvlc_video_direct3d_select_plane_cb select_plane_cb, void *opaque)
Set callbacks and data to render decoded video to a custom Direct3D output.
int i_type
Definition: httpd.c:1237
LIBVLC_API void libvlc_video_set_marquee_int(libvlc_media_player_t *p_mi, unsigned option, int i_val)
Enable, disable or set an integer marquee option.
char * psz_name
Definition: libvlc_media_player.h:88
LIBVLC_API libvlc_event_manager_t * libvlc_media_player_event_manager(libvlc_media_player_t *p_mi)
Get the Event Manager from which the media player send event.
int64_t i_duration
duration in milliseconds
Definition: libvlc_media_player.h:67
LIBVLC_API float libvlc_video_get_scale(libvlc_media_player_t *p_mi)
Get the current video scaling factor.
LIBVLC_API void libvlc_video_set_format_callbacks(libvlc_media_player_t *mp, libvlc_video_format_cb setup, libvlc_video_cleanup_cb cleanup)
Set decoded video chroma and dimensions.
Definition: libvlc_media_player.h:109
Definition: libvlc_media_player.h:129
LIBVLC_API int libvlc_video_get_adjust_int(libvlc_media_player_t *p_mi, unsigned option)
Get integer adjust option.
bool(* libvlc_video_makeCurrent_cb)(void *opaque, bool enter)
Callback prototype to set up the OpenGL context for rendering.
Definition: libvlc_media_player.h:545
LIBVLC_API int libvlc_video_get_logo_int(libvlc_media_player_t *p_mi, unsigned option)
Get integer logo option.
LIBVLC_API void libvlc_audio_set_format_callbacks(libvlc_media_player_t *mp, libvlc_audio_setup_cb setup, libvlc_audio_cleanup_cb cleanup)
Sets decoded audio format via callbacks.
struct libvlc_audio_output_t * p_next
Definition: libvlc_media_player.h:90
libvlc_video_color_primaries_t
Enumeration of the Video color primaries.
Definition: libvlc_media_player.h:296
struct libvlc_audio_output_device_t libvlc_audio_output_device_t
Description for audio output device.
Definition: libvlc_media_player.h:1964
LIBVLC_API int libvlc_audio_get_track(libvlc_media_player_t *p_mi)
Get current audio track.
size_t count
Definition: core.c:402
LIBVLC_API float libvlc_audio_equalizer_get_band_frequency(unsigned u_index)
Get a particular equalizer band frequency.
bool(* libvlc_video_direct3d_device_setup_cb)(void **opaque, const libvlc_video_direct3d_device_cfg_t *cfg, libvlc_video_direct3d_device_setup_t *out)
Setup the rendering environment.
Definition: libvlc_media_player.h:640
LIBVLC_API void libvlc_media_player_pause(libvlc_media_player_t *p_mi)
Toggle pause (no effect if there is no media)
Embedded animation (e.g.
Definition: libvlc_media_player.h:2425
LIBVLC_API int libvlc_media_player_set_equalizer(libvlc_media_player_t *p_mi, libvlc_equalizer_t *p_equalizer)
Apply new equalizer settings to a media player.
LIBVLC_API int libvlc_video_get_teletext(libvlc_media_player_t *p_mi)
Get current teletext page requested or 0 if it&#39;s disabled.
LIBVLC_API void libvlc_media_player_set_nsobject(libvlc_media_player_t *p_mi, void *drawable)
Set the NSView handler where the media player should render its video output.
void * device_context
Definition: libvlc_media_player.h:618
Definition: libvlc_media_player.h:309
Definition: libvlc_media_player.h:1966
LIBVLC_API char * libvlc_video_get_aspect_ratio(libvlc_media_player_t *p_mi)
Get current video aspect ratio.
void(* libvlc_video_display_cb)(void *opaque, void *picture)
Callback prototype to display a picture.
Definition: libvlc_media_player.h:374
Definition: libvlc_media_player.h:1855
char * psz_name
Definition: libvlc_media_player.h:51
Definition: libvlc_media_player.h:302
Definition: libvlc_media_player.h:616
bool full_range
rendering video bit depth in bits per channel
Definition: libvlc_media_player.h:673
LIBVLC_API void libvlc_media_player_navigate(libvlc_media_player_t *p_mi, unsigned navigate)
Navigate through DVD Menu.
Definition: libvlc_media_player.h:114
Definition: libvlc_media_player.h:1860
Definition: libvlc_media_player.h:320
Definition: libvlc_media_player.h:1903
LIBVLC_API void libvlc_media_player_set_video_title_display(libvlc_media_player_t *p_mi, libvlc_position_t position, unsigned int timeout)
Set if, and how, the video title will be shown when media is played.
struct libvlc_audio_output_device_t * p_next
Next entry in list.
Definition: libvlc_media_player.h:99
User interaction feedback.
Definition: libvlc_media_player.h:2424
Definition: libvlc_media_player.h:143
LIBVLC_API void libvlc_media_player_set_chapter(libvlc_media_player_t *p_mi, int i_chapter)
Set movie chapter (if applicable).
LIBVLC_API libvlc_track_description_t * libvlc_video_get_track_description(libvlc_media_player_t *p_mi)
Get the description of available video tracks.
Definition: libvlc_media_player.h:1899
libvlc_video_transfer_func_t
Enumeration of the Video transfer functions.
Definition: libvlc_media_player.h:317
LIBVLC_API void libvlc_video_set_marquee_string(libvlc_media_player_t *p_mi, unsigned option, const char *psz_text)
Set a marquee string option.
char psz_value[8]
Definition: vout_intf.c:99
char * psz_device
Device identifier string.
Definition: libvlc_media_player.h:100
LIBVLC_API void libvlc_title_descriptions_release(libvlc_title_description_t **p_titles, unsigned i_count)
Release a title description.
Description for chapters.
Definition: libvlc_media_player.h:75
Definition: libvlc_media_player.h:1904
Viewpoint.
Definition: libvlc_media.h:169
Definition: libvlc_media_player.h:680
LIBVLC_API int libvlc_audio_output_set(libvlc_media_player_t *p_mi, const char *psz_name)
Selects an audio output module.
LIBVLC_API void libvlc_video_set_format(libvlc_media_player_t *mp, const char *chroma, unsigned width, unsigned height, unsigned pitch)
Set decoded video chroma and dimensions.
LIBVLC_API int libvlc_media_player_set_position(libvlc_media_player_t *p_mi, float f_pos, bool b_fast)
Set movie position as percentage between 0.0 and 1.0.
LIBVLC_API void libvlc_audio_toggle_mute(libvlc_media_player_t *p_mi)
Toggle mute status.
void(* libvlc_video_direct3d_device_cleanup_cb)(void *opaque)
Cleanup the rendering environment initialized during libvlc_video_direct3d_device_setup_cb.
Definition: libvlc_media_player.h:649
LIBVLC_API libvlc_time_t libvlc_media_player_get_length(libvlc_media_player_t *p_mi)
Get the current movie length (in ms).
uint16_t MaxContentLightLevel
Definition: libvlc_media_player.h:718
struct libvlc_chapter_description_t libvlc_chapter_description_t
Description for chapters.
Definition: libvlc_media_player.h:142
LIBVLC_API int libvlc_media_player_get_full_title_descriptions(libvlc_media_player_t *p_mi, libvlc_title_description_t ***titles)
Get the full description of available titles.
Definition: libvlc_media_player.h:1859
void(* libvlc_audio_resume_cb)(void *data, int64_t pts)
Callback prototype for audio resumption.
Definition: libvlc_media_player.h:978
struct libvlc_equalizer_t libvlc_equalizer_t
Opaque equalizer handle.
Definition: libvlc_media_player.h:167
LIBVLC_API int libvlc_video_update_viewpoint(libvlc_media_player_t *p_mi, const libvlc_video_viewpoint_t *p_viewpoint, bool b_absolute)
Update the video viewpoint information.
Definition: libvlc_media_player.h:1853
void(* libvlc_video_update_output_cb)(void *opaque, unsigned width, unsigned height)
Callback prototype called on video size changes.
Definition: libvlc_media_player.h:526
char * psz_description
User-friendly device description.
Definition: libvlc_media_player.h:101
libvlc_navigate_mode_t
Navigation mode.
Definition: libvlc_media_player.h:124
Definition: libvlc_media_player.h:301
LIBVLC_API int libvlc_video_set_spu(libvlc_media_player_t *p_mi, int i_spu)
Set new video subtitle.
LIBVLC_API void libvlc_video_set_key_input(libvlc_media_player_t *p_mi, unsigned on)
Enable or disable key press events handling, according to the LibVLC hotkeys configuration.
Definition: libvlc_media_player.h:1858
LIBVLC_API int libvlc_audio_set_delay(libvlc_media_player_t *p_mi, int64_t i_delay)
Set current audio delay.
unsigned i_flags
info if item was recognized as a menu, interactive or plain content by the demuxer ...
Definition: libvlc_media_player.h:69
Don&#39;t use a media player role.
Definition: libvlc_media_player.h:2419
bool(* libvlc_video_direct3d_update_output_cb)(void *opaque, const libvlc_video_direct3d_cfg_t *cfg, libvlc_video_output_cfg_t *output)
Update the rendering output setup.
Definition: libvlc_media_player.h:705
void(* libvlc_audio_drain_cb)(void *data)
Callback prototype for audio buffer drain.
Definition: libvlc_media_player.h:1000
libvlc_video_color_space_t colorspace
video is full range or studio/limited range
Definition: libvlc_media_player.h:674
LIBVLC_API int libvlc_media_player_get_chapter_count(libvlc_media_player_t *p_mi)
Get movie chapter count.
void(* libvlc_audio_flush_cb)(void *data, int64_t pts)
Callback prototype for audio buffer flush.
Definition: libvlc_media_player.h:989
LIBVLC_API void libvlc_video_set_mouse_input(libvlc_media_player_t *p_mi, unsigned on)
Enable or disable mouse click events handling.
LIBVLC_API int libvlc_video_get_size(libvlc_media_player_t *p_mi, unsigned num, unsigned *px, unsigned *py)
Get the pixel dimensions of a video.
LIBVLC_API int libvlc_media_player_get_title_count(libvlc_media_player_t *p_mi)
Get movie title count.
void * device
video transfer function
Definition: libvlc_media_player.h:677
LIBVLC_API int libvlc_video_set_track(libvlc_media_player_t *p_mi, int i_track)
Set video track.
LIBVLC_API bool libvlc_media_player_is_playing(libvlc_media_player_t *p_mi)
is_playing
LIBVLC_API int libvlc_video_get_marquee_int(libvlc_media_player_t *p_mi, unsigned option)
Get an integer marquee option value.
Definition: libvlc_media_player.h:127
LIBVLC_API void libvlc_audio_set_format(libvlc_media_player_t *mp, const char *format, unsigned rate, unsigned channels)
Sets a fixed decoded audio format.
struct libvlc_instance_t libvlc_instance_t
This structure is opaque.
Definition: libvlc.h:76
LIBVLC_API libvlc_audio_output_device_t * libvlc_audio_output_device_enum(libvlc_media_player_t *mp)
Gets a list of potential audio output devices,.
LIBVLC_API void libvlc_video_set_adjust_int(libvlc_media_player_t *p_mi, unsigned option, int value)
Set adjust option as integer.
struct libvlc_audio_output_t libvlc_audio_output_t
Description for audio output.
LIBVLC_API float libvlc_video_get_adjust_float(libvlc_media_player_t *p_mi, unsigned option)
Get float adjust option.
LIBVLC_API libvlc_state_t libvlc_media_player_get_state(libvlc_media_player_t *p_mi)
Get current movie state.
Definition: libvlc_media_player.h:61
Direct3D9 rendering engine.
Definition: libvlc_media_player.h:608
unsigned int MaxMasteringLuminance
Definition: libvlc_media_player.h:716
LIBVLC_API int libvlc_media_player_play(libvlc_media_player_t *p_mi)
Play.
Speech, real-time communication.
Definition: libvlc_media_player.h:2422
Definition: libvlc_media_player.h:1902
struct libvlc_renderer_item_t libvlc_renderer_item_t
Definition: libvlc_events.h:36
Definition: libvlc_media_player.h:147
Definition: libvlc_media_player.h:118
void *(* libvlc_video_getProcAddress_cb)(void *opaque, const char *fct_name)
Callback prototype to load opengl functions.
Definition: libvlc_media_player.h:555
int i_id
Definition: libvlc_media_player.h:50
Definition: libvlc_media_player.h:155
LIBVLC_API void libvlc_media_player_retain(libvlc_media_player_t *p_mi)
Retain a reference to a media player object.
Definition: libvlc_media_player.h:117
Definition: libvlc_media_player.h:318
LIBVLC_API int libvlc_audio_set_volume(libvlc_media_player_t *p_mi, int i_volume)
Set current software audio volume.
LIBVLC_API int libvlc_media_player_set_renderer(libvlc_media_player_t *p_mi, libvlc_renderer_item_t *p_item)
Set a renderer to the media player.
LIBVLC_API void * libvlc_media_player_get_hwnd(libvlc_media_player_t *p_mi)
Get the Windows API window handle (HWND) previously set with libvlc_media_player_set_hwnd().
LIBVLC_API libvlc_track_description_t * libvlc_video_get_spu_description(libvlc_media_player_t *p_mi)
Get the description of available video subtitles.
int64_t libvlc_time_t
Definition: libvlc.h:78
Definition: libvlc_media_player.h:611
libvlc_video_direct3d_engine_t
Enumeration of the Video engine to be used on output.
Definition: libvlc_media_player.h:604
Definition: libvlc_media_player.h:128
LIBVLC_API bool libvlc_get_fullscreen(libvlc_media_player_t *p_mi)
Get current fullscreen status.
LIBVLC_API int libvlc_media_player_set_rate(libvlc_media_player_t *p_mi, float rate)
Set movie play rate.
Definition: libvlc_media_player.h:130
bool(* libvlc_video_direct3d_start_end_rendering_cb)(void *opaque, bool enter, const libvlc_video_direct3d_hdr10_metadata_t *hdr10)
Tell the host the rendering is about to start/has finished.
Definition: libvlc_media_player.h:745
LIBVLC_API void libvlc_audio_set_callbacks(libvlc_media_player_t *mp, libvlc_audio_play_cb play, libvlc_audio_pause_cb pause, libvlc_audio_resume_cb resume, libvlc_audio_flush_cb flush, libvlc_audio_drain_cb drain, void *opaque)
Sets callbacks and private data for decoded audio.
LIBVLC_API libvlc_track_description_t * libvlc_audio_get_track_description(libvlc_media_player_t *p_mi)
Get the description of available audio tracks.
LIBVLC_API unsigned libvlc_media_player_has_vout(libvlc_media_player_t *p_mi)
How many video outputs does this media player have?
LIBVLC_API void libvlc_video_set_logo_int(libvlc_media_player_t *p_mi, unsigned option, int value)
Set logo option as integer.
unsigned height
rendering video width in pixel
Definition: libvlc_media_player.h:671
Definition: libvlc_media_player.h:321
Definition: libvlc_media_player.h:112
libvlc_video_engine_t
Enumeration of the Video engine to be used on output.
Definition: libvlc_media_player.h:561
LIBVLC_API libvlc_video_viewpoint_t * libvlc_video_new_viewpoint(void)
Create a video viewpoint structure.
void(* libvlc_video_unlock_cb)(void *opaque, void *picture, void *const *planes)
Callback prototype to unlock a picture buffer.
Definition: libvlc_media_player.h:361
LIBVLC_API char * libvlc_audio_output_device_get(libvlc_media_player_t *mp)
Get the current audio output device identifier.
Definition: libvlc_media_player.h:319
void(* libvlc_audio_play_cb)(void *data, const void *samples, unsigned count, int64_t pts)
Callback prototype for audio playback.
Definition: libvlc_media_player.h:954
LIBVLC_API libvlc_audio_output_device_t * libvlc_audio_output_device_list_get(libvlc_instance_t *p_instance, const char *aout)
Gets a list of audio output devices for a given audio output module,.
LIBVLC_API void libvlc_audio_output_list_release(libvlc_audio_output_t *p_list)
Frees the list of available audio output modules.
LIBVLC_API void libvlc_track_description_list_release(libvlc_track_description_t *p_track_description)
Release (free) libvlc_track_description_t.
LIBVLC_API void libvlc_media_player_stop_async(libvlc_media_player_t *p_mi)
Stop (no effect if there is no media)
struct libvlc_media_player_t libvlc_media_player_t
Definition: libvlc_media_player.h:42
LIBVLC_API uint32_t libvlc_media_player_get_xwindow(libvlc_media_player_t *p_mi)
Get the X Window System window identifier previously set with libvlc_media_player_set_xwindow().
Direct3D11 rendering engine.
Definition: libvlc_media_player.h:606
Video playback.
Definition: libvlc_media_player.h:2421
LIBVLC_API void * libvlc_media_player_get_nsobject(libvlc_media_player_t *p_mi)
Get the NSView handler previously set with libvlc_media_player_set_nsobject().
LIBVLC_API void libvlc_audio_output_device_set(libvlc_media_player_t *mp, const char *module, const char *device_id)
Configures an explicit audio output device.
LIBVLC_API bool libvlc_media_player_can_pause(libvlc_media_player_t *p_mi)
Can this media player be paused?
LIBVLC_API bool libvlc_media_player_program_scrambled(libvlc_media_player_t *p_mi)
Check if the current program is scrambled.
LIBVLC_API void libvlc_media_player_set_media(libvlc_media_player_t *p_mi, libvlc_media_t *p_md)
Set the media that will be used by the media_player.
char * psz_name
title name
Definition: libvlc_media_player.h:68
Definition: libvlc_media_player.h:158
libvlc_video_color_primaries_t primaries
video color space
Definition: libvlc_media_player.h:686
LIBVLC_API libvlc_equalizer_t * libvlc_audio_equalizer_new_from_preset(unsigned u_index)
Create a new equalizer, with initial frequency values copied from an existing preset.
LIBVLC_API int libvlc_audio_get_channel(libvlc_media_player_t *p_mi)
Get current audio channel.
libvlc_video_logo_option_t
option values for libvlc_video_{get,set}_logo_{int,string}
Definition: libvlc_media_player.h:1852
Definition: libvlc_media_player.h:325
enum libvlc_media_player_role libvlc_media_player_role_t
Media player roles.
Definition: libvlc_media_player.h:156
LIBVLC_API int libvlc_media_player_get_title(libvlc_media_player_t *p_mi)
Get movie title.
Definition: libvlc_media_player.h:138
libvlc_video_transfer_func_t transfer
video color primaries
Definition: libvlc_media_player.h:676
libvlc_video_transfer_func_t transfer
video color primaries
Definition: libvlc_media_player.h:687
LIBVLC_API void libvlc_chapter_descriptions_release(libvlc_chapter_description_t **p_chapters, unsigned i_count)
Release a chapter description.
LIBVLC_API libvlc_media_t * libvlc_media_player_get_media(libvlc_media_player_t *p_mi)
Get the media used by the media_player.
bool(* libvlc_video_setup_cb)(void *opaque)
Callback prototype called to initialize user data.
Definition: libvlc_media_player.h:507
Accessibility.
Definition: libvlc_media_player.h:2427
LIBVLC_API int libvlc_video_get_spu_count(libvlc_media_player_t *p_mi)
Get the number of available video subtitles.
libvlc_audio_output_channel_t
Audio channels.
Definition: libvlc_media_player.h:1962
LIBVLC_API int libvlc_media_player_get_full_chapter_descriptions(libvlc_media_player_t *p_mi, int i_chapters_of_title, libvlc_chapter_description_t ***pp_chapters)
Get the full description of available chapters.
char * psz_description
Definition: libvlc_media_player.h:89