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