1/*****************************************************************************
2 * libvlc_media_player.h: libvlc_media_player external API
3 *****************************************************************************
4 * Copyright (C) 1998-2015 VLC authors and VideoLAN
5 * $Id: c431c235e92ced9e6e7d7712eb7ff0e73dc4f933 $
6 *
7 * Authors: Clément Stenac <zorglub@videolan.org>
8 * Jean-Paul Saman <jpsaman@videolan.org>
9 * Pierre d'Herbemont <pdherbemont@videolan.org>
10 *
11 * This program is free software; you can redistribute it and/or modify it
12 * under the terms of the GNU Lesser General Public License as published by
13 * the Free Software Foundation; either version 2.1 of the License, or
14 * (at your option) any later version.
15 *
16 * This program is distributed in the hope that it will be useful,
17 * but WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 * GNU Lesser General Public License for more details.
20 *
21 * You should have received a copy of the GNU Lesser General Public License
22 * along with this program; if not, write to the Free Software Foundation,
23 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
24 *****************************************************************************/
25
26#ifndef VLC_LIBVLC_MEDIA_PLAYER_H
27#define VLC_LIBVLC_MEDIA_PLAYER_H 1
28
29# ifdef __cplusplus
30extern "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
43typedef 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 */
49typedef 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 */
60enum
61{
62 libvlc_title_menu = 0x01,
63 libvlc_title_interactive = 0x02
64};
65
66typedef 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 */
76typedef 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 */
87typedef 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 */
98typedef 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 */
109typedef 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 */
125typedef 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 */
138typedef 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 */
155typedef 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 */
168typedef 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 */
177LIBVLC_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 */
186LIBVLC_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 */
197LIBVLC_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 */
205LIBVLC_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 */
215LIBVLC_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 */
225LIBVLC_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 */
233LIBVLC_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 */
243LIBVLC_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 */
251LIBVLC_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 */
260LIBVLC_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 */
268LIBVLC_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 */
275LIBVLC_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 */
290LIBVLC_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 */
307typedef 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 */
325typedef 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 */
338typedef 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 */
366typedef 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 */
377typedef 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 */
417LIBVLC_API
418void 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 */
440LIBVLC_API
441void 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 */
454LIBVLC_API
455void 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 */
493LIBVLC_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 */
501LIBVLC_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 */
543LIBVLC_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 */
555LIBVLC_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 */
565LIBVLC_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 */
575LIBVLC_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 */
586LIBVLC_API void libvlc_media_player_set_android_context( libvlc_media_player_t *p_mi,
587 void *p_awindow_handler );
588
589/**
590 * Set the EFL Evas Object.
591 *
592 * \version LibVLC 3.0.0 and later.
593 *
594 * \param p_mi the media player
595 * \param p_evas_object a valid EFL Evas Object (Evas_Object)
596 * \return -1 if an error was detected, 0 otherwise.
597 */
598LIBVLC_API int libvlc_media_player_set_evas_object( libvlc_media_player_t *p_mi,
599 void *p_evas_object );
600
601
602/**
603 * Callback prototype for audio playback.
604 *
605 * The LibVLC media player decodes and post-processes the audio signal
606 * asynchronously (in an internal thread). Whenever audio samples are ready
607 * to be queued to the output, this callback is invoked.
608 *
609 * The number of samples provided per invocation may depend on the file format,
610 * the audio coding algorithm, the decoder plug-in, the post-processing
611 * filters and timing. Application must not assume a certain number of samples.
612 *
613 * The exact format of audio samples is determined by libvlc_audio_set_format()
614 * or libvlc_audio_set_format_callbacks() as is the channels layout.
615 *
616 * Note that the number of samples is per channel. For instance, if the audio
617 * track sampling rate is 48000 Hz, then 1200 samples represent 25 milliseconds
618 * of audio signal - regardless of the number of audio channels.
619 *
620 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
621 * \param samples pointer to a table of audio samples to play back [IN]
622 * \param count number of audio samples to play back
623 * \param pts expected play time stamp (see libvlc_delay())
624 */
625typedef void (*libvlc_audio_play_cb)(void *data, const void *samples,
626 unsigned count, int64_t pts);
627
628/**
629 * Callback prototype for audio pause.
630 *
631 * LibVLC invokes this callback to pause audio playback.
632 *
633 * \note The pause callback is never called if the audio is already paused.
634 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
635 * \param pts time stamp of the pause request (should be elapsed already)
636 */
637typedef void (*libvlc_audio_pause_cb)(void *data, int64_t pts);
638
639/**
640 * Callback prototype for audio resumption.
641 *
642 * LibVLC invokes this callback to resume audio playback after it was
643 * previously paused.
644 *
645 * \note The resume callback is never called if the audio is not paused.
646 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
647 * \param pts time stamp of the resumption request (should be elapsed already)
648 */
649typedef void (*libvlc_audio_resume_cb)(void *data, int64_t pts);
650
651/**
652 * Callback prototype for audio buffer flush.
653 *
654 * LibVLC invokes this callback if it needs to discard all pending buffers and
655 * stop playback as soon as possible. This typically occurs when the media is
656 * stopped.
657 *
658 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
659 */
660typedef void (*libvlc_audio_flush_cb)(void *data, int64_t pts);
661
662/**
663 * Callback prototype for audio buffer drain.
664 *
665 * LibVLC may invoke this callback when the decoded audio track is ending.
666 * There will be no further decoded samples for the track, but playback should
667 * nevertheless continue until all already pending buffers are rendered.
668 *
669 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
670 */
671typedef void (*libvlc_audio_drain_cb)(void *data);
672
673/**
674 * Callback prototype for audio volume change.
675 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
676 * \param volume software volume (1. = nominal, 0. = mute)
677 * \param mute muted flag
678 */
679typedef void (*libvlc_audio_set_volume_cb)(void *data,
680 float volume, bool mute);
681
682/**
683 * Sets callbacks and private data for decoded audio.
684 *
685 * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks()
686 * to configure the decoded audio format.
687 *
688 * \note The audio callbacks override any other audio output mechanism.
689 * If the callbacks are set, LibVLC will <b>not</b> output audio in any way.
690 *
691 * \param mp the media player
692 * \param play callback to play audio samples (must not be NULL)
693 * \param pause callback to pause playback (or NULL to ignore)
694 * \param resume callback to resume playback (or NULL to ignore)
695 * \param flush callback to flush audio buffers (or NULL to ignore)
696 * \param drain callback to drain audio buffers (or NULL to ignore)
697 * \param opaque private pointer for the audio callbacks (as first parameter)
698 * \version LibVLC 2.0.0 or later
699 */
700LIBVLC_API
701void libvlc_audio_set_callbacks( libvlc_media_player_t *mp,
702 libvlc_audio_play_cb play,
703 libvlc_audio_pause_cb pause,
704 libvlc_audio_resume_cb resume,
705 libvlc_audio_flush_cb flush,
706 libvlc_audio_drain_cb drain,
707 void *opaque );
708
709/**
710 * Set callbacks and private data for decoded audio. This only works in
711 * combination with libvlc_audio_set_callbacks().
712 * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks()
713 * to configure the decoded audio format.
714 *
715 * \param mp the media player
716 * \param set_volume callback to apply audio volume,
717 * or NULL to apply volume in software
718 * \version LibVLC 2.0.0 or later
719 */
720LIBVLC_API
721void libvlc_audio_set_volume_callback( libvlc_media_player_t *mp,
722 libvlc_audio_set_volume_cb set_volume );
723
724/**
725 * Callback prototype to setup the audio playback.
726 *
727 * This is called when the media player needs to create a new audio output.
728 * \param opaque pointer to the data pointer passed to
729 * libvlc_audio_set_callbacks() [IN/OUT]
730 * \param format 4 bytes sample format [IN/OUT]
731 * \param rate sample rate [IN/OUT]
732 * \param channels channels count [IN/OUT]
733 * \return 0 on success, anything else to skip audio playback
734 */
735typedef int (*libvlc_audio_setup_cb)(void **data, char *format, unsigned *rate,
736 unsigned *channels);
737
738/**
739 * Callback prototype for audio playback cleanup.
740 *
741 * This is called when the media player no longer needs an audio output.
742 * \param opaque data pointer as passed to libvlc_audio_set_callbacks() [IN]
743 */
744typedef void (*libvlc_audio_cleanup_cb)(void *data);
745
746/**
747 * Sets decoded audio format via callbacks.
748 *
749 * This only works in combination with libvlc_audio_set_callbacks().
750 *
751 * \param mp the media player
752 * \param setup callback to select the audio format (cannot be NULL)
753 * \param cleanup callback to release any allocated resources (or NULL)
754 * \version LibVLC 2.0.0 or later
755 */
756LIBVLC_API
757void libvlc_audio_set_format_callbacks( libvlc_media_player_t *mp,
758 libvlc_audio_setup_cb setup,
759 libvlc_audio_cleanup_cb cleanup );
760
761/**
762 * Sets a fixed decoded audio format.
763 *
764 * This only works in combination with libvlc_audio_set_callbacks(),
765 * and is mutually exclusive with libvlc_audio_set_format_callbacks().
766 *
767 * \param mp the media player
768 * \param format a four-characters string identifying the sample format
769 * (e.g. "S16N" or "f32l")
770 * \param rate sample rate (expressed in Hz)
771 * \param channels channels count
772 * \version LibVLC 2.0.0 or later
773 */
774LIBVLC_API
775void libvlc_audio_set_format( libvlc_media_player_t *mp, const char *format,
776 unsigned rate, unsigned channels );
777
778/** \bug This might go away ... to be replaced by a broader system */
779
780/**
781 * Get the current movie length (in ms).
782 *
783 * \param p_mi the Media Player
784 * \return the movie length (in ms), or -1 if there is no media.
785 */
786LIBVLC_API libvlc_time_t libvlc_media_player_get_length( libvlc_media_player_t *p_mi );
787
788/**
789 * Get the current movie time (in ms).
790 *
791 * \param p_mi the Media Player
792 * \return the movie time (in ms), or -1 if there is no media.
793 */
794LIBVLC_API libvlc_time_t libvlc_media_player_get_time( libvlc_media_player_t *p_mi );
795
796/**
797 * Set the movie time (in ms). This has no effect if no media is being played.
798 * Not all formats and protocols support this.
799 *
800 * \param p_mi the Media Player
801 * \param i_time the movie time (in ms).
802 */
803LIBVLC_API void libvlc_media_player_set_time( libvlc_media_player_t *p_mi, libvlc_time_t i_time );
804
805/**
806 * Get movie position as percentage between 0.0 and 1.0.
807 *
808 * \param p_mi the Media Player
809 * \return movie position, or -1. in case of error
810 */
811LIBVLC_API float libvlc_media_player_get_position( libvlc_media_player_t *p_mi );
812
813/**
814 * Set movie position as percentage between 0.0 and 1.0.
815 * This has no effect if playback is not enabled.
816 * This might not work depending on the underlying input format and protocol.
817 *
818 * \param p_mi the Media Player
819 * \param f_pos the position
820 */
821LIBVLC_API void libvlc_media_player_set_position( libvlc_media_player_t *p_mi, float f_pos );
822
823/**
824 * Set movie chapter (if applicable).
825 *
826 * \param p_mi the Media Player
827 * \param i_chapter chapter number to play
828 */
829LIBVLC_API void libvlc_media_player_set_chapter( libvlc_media_player_t *p_mi, int i_chapter );
830
831/**
832 * Get movie chapter.
833 *
834 * \param p_mi the Media Player
835 * \return chapter number currently playing, or -1 if there is no media.
836 */
837LIBVLC_API int libvlc_media_player_get_chapter( libvlc_media_player_t *p_mi );
838
839/**
840 * Get movie chapter count
841 *
842 * \param p_mi the Media Player
843 * \return number of chapters in movie, or -1.
844 */
845LIBVLC_API int libvlc_media_player_get_chapter_count( libvlc_media_player_t *p_mi );
846
847/**
848 * Is the player able to play
849 *
850 * \param p_mi the Media Player
851 * \return boolean
852 *
853 * \libvlc_return_bool
854 */
855LIBVLC_API int libvlc_media_player_will_play( libvlc_media_player_t *p_mi );
856
857/**
858 * Get title chapter count
859 *
860 * \param p_mi the Media Player
861 * \param i_title title
862 * \return number of chapters in title, or -1
863 */
864LIBVLC_API int libvlc_media_player_get_chapter_count_for_title(
865 libvlc_media_player_t *p_mi, int i_title );
866
867/**
868 * Set movie title
869 *
870 * \param p_mi the Media Player
871 * \param i_title title number to play
872 */
873LIBVLC_API void libvlc_media_player_set_title( libvlc_media_player_t *p_mi, int i_title );
874
875/**
876 * Get movie title
877 *
878 * \param p_mi the Media Player
879 * \return title number currently playing, or -1
880 */
881LIBVLC_API int libvlc_media_player_get_title( libvlc_media_player_t *p_mi );
882
883/**
884 * Get movie title count
885 *
886 * \param p_mi the Media Player
887 * \return title number count, or -1
888 */
889LIBVLC_API int libvlc_media_player_get_title_count( libvlc_media_player_t *p_mi );
890
891/**
892 * Set previous chapter (if applicable)
893 *
894 * \param p_mi the Media Player
895 */
896LIBVLC_API void libvlc_media_player_previous_chapter( libvlc_media_player_t *p_mi );
897
898/**
899 * Set next chapter (if applicable)
900 *
901 * \param p_mi the Media Player
902 */
903LIBVLC_API void libvlc_media_player_next_chapter( libvlc_media_player_t *p_mi );
904
905/**
906 * Get the requested movie play rate.
907 * @warning Depending on the underlying media, the requested rate may be
908 * different from the real playback rate.
909 *
910 * \param p_mi the Media Player
911 * \return movie play rate
912 */
913LIBVLC_API float libvlc_media_player_get_rate( libvlc_media_player_t *p_mi );
914
915/**
916 * Set movie play rate
917 *
918 * \param p_mi the Media Player
919 * \param rate movie play rate to set
920 * \return -1 if an error was detected, 0 otherwise (but even then, it might
921 * not actually work depending on the underlying media protocol)
922 */
923LIBVLC_API int libvlc_media_player_set_rate( libvlc_media_player_t *p_mi, float rate );
924
925/**
926 * Get current movie state
927 *
928 * \param p_mi the Media Player
929 * \return the current state of the media player (playing, paused, ...) \see libvlc_state_t
930 */
931LIBVLC_API libvlc_state_t libvlc_media_player_get_state( libvlc_media_player_t *p_mi );
932
933/**
934 * How many video outputs does this media player have?
935 *
936 * \param p_mi the media player
937 * \return the number of video outputs
938 */
939LIBVLC_API unsigned libvlc_media_player_has_vout( libvlc_media_player_t *p_mi );
940
941/**
942 * Is this media player seekable?
943 *
944 * \param p_mi the media player
945 * \return true if the media player can seek
946 *
947 * \libvlc_return_bool
948 */
949LIBVLC_API int libvlc_media_player_is_seekable( libvlc_media_player_t *p_mi );
950
951/**
952 * Can this media player be paused?
953 *
954 * \param p_mi the media player
955 * \return true if the media player can pause
956 *
957 * \libvlc_return_bool
958 */
959LIBVLC_API int libvlc_media_player_can_pause( libvlc_media_player_t *p_mi );
960
961/**
962 * Check if the current program is scrambled
963 *
964 * \param p_mi the media player
965 * \return true if the current program is scrambled
966 *
967 * \libvlc_return_bool
968 * \version LibVLC 2.2.0 or later
969 */
970LIBVLC_API int libvlc_media_player_program_scrambled( libvlc_media_player_t *p_mi );
971
972/**
973 * Display the next frame (if supported)
974 *
975 * \param p_mi the media player
976 */
977LIBVLC_API void libvlc_media_player_next_frame( libvlc_media_player_t *p_mi );
978
979/**
980 * Navigate through DVD Menu
981 *
982 * \param p_mi the Media Player
983 * \param navigate the Navigation mode
984 * \version libVLC 2.0.0 or later
985 */
986LIBVLC_API void libvlc_media_player_navigate( libvlc_media_player_t* p_mi,
987 unsigned navigate );
988
989/**
990 * Set if, and how, the video title will be shown when media is played.
991 *
992 * \param p_mi the media player
993 * \param position position at which to display the title, or libvlc_position_disable to prevent the title from being displayed
994 * \param timeout title display timeout in milliseconds (ignored if libvlc_position_disable)
995 * \version libVLC 2.1.0 or later
996 */
997LIBVLC_API void libvlc_media_player_set_video_title_display( libvlc_media_player_t *p_mi, libvlc_position_t position, unsigned int timeout );
998
999/**
1000 * Add a slave to the current media player.
1001 *
1002 * \note If the player is playing, the slave will be added directly. This call
1003 * will also update the slave list of the attached libvlc_media_t.
1004 *
1005 * \version LibVLC 3.0.0 and later.
1006 *
1007 * \see libvlc_media_slaves_add
1008 *
1009 * \param p_mi the media player
1010 * \param i_type subtitle or audio
1011 * \param psz_uri Uri of the slave (should contain a valid scheme).
1012 * \param b_select True if this slave should be selected when it's loaded
1013 *
1014 * \return 0 on success, -1 on error.
1015 */
1016LIBVLC_API
1017int libvlc_media_player_add_slave( libvlc_media_player_t *p_mi,
1018 libvlc_media_slave_type_t i_type,
1019 const char *psz_uri, bool b_select );
1020
1021/**
1022 * Release (free) libvlc_track_description_t
1023 *
1024 * \param p_track_description the structure to release
1025 */
1026LIBVLC_API void libvlc_track_description_list_release( libvlc_track_description_t *p_track_description );
1027
1028/** \defgroup libvlc_video LibVLC video controls
1029 * @{
1030 */
1031
1032/**
1033 * Toggle fullscreen status on non-embedded video outputs.
1034 *
1035 * @warning The same limitations applies to this function
1036 * as to libvlc_set_fullscreen().
1037 *
1038 * \param p_mi the media player
1039 */
1040LIBVLC_API void libvlc_toggle_fullscreen( libvlc_media_player_t *p_mi );
1041
1042/**
1043 * Enable or disable fullscreen.
1044 *
1045 * @warning With most window managers, only a top-level windows can be in
1046 * full-screen mode. Hence, this function will not operate properly if
1047 * libvlc_media_player_set_xwindow() was used to embed the video in a
1048 * non-top-level window. In that case, the embedding window must be reparented
1049 * to the root window <b>before</b> fullscreen mode is enabled. You will want
1050 * to reparent it back to its normal parent when disabling fullscreen.
1051 *
1052 * \param p_mi the media player
1053 * \param b_fullscreen boolean for fullscreen status
1054 */
1055LIBVLC_API void libvlc_set_fullscreen( libvlc_media_player_t *p_mi, int b_fullscreen );
1056
1057/**
1058 * Get current fullscreen status.
1059 *
1060 * \param p_mi the media player
1061 * \return the fullscreen status (boolean)
1062 *
1063 * \libvlc_return_bool
1064 */
1065LIBVLC_API int libvlc_get_fullscreen( libvlc_media_player_t *p_mi );
1066
1067/**
1068 * Enable or disable key press events handling, according to the LibVLC hotkeys
1069 * configuration. By default and for historical reasons, keyboard events are
1070 * handled by the LibVLC video widget.
1071 *
1072 * \note On X11, there can be only one subscriber for key press and mouse
1073 * click events per window. If your application has subscribed to those events
1074 * for the X window ID of the video widget, then LibVLC will not be able to
1075 * handle key presses and mouse clicks in any case.
1076 *
1077 * \warning This function is only implemented for X11 and Win32 at the moment.
1078 *
1079 * \param p_mi the media player
1080 * \param on true to handle key press events, false to ignore them.
1081 */
1082LIBVLC_API
1083void libvlc_video_set_key_input( libvlc_media_player_t *p_mi, unsigned on );
1084
1085/**
1086 * Enable or disable mouse click events handling. By default, those events are
1087 * handled. This is needed for DVD menus to work, as well as a few video
1088 * filters such as "puzzle".
1089 *
1090 * \see libvlc_video_set_key_input().
1091 *
1092 * \warning This function is only implemented for X11 and Win32 at the moment.
1093 *
1094 * \param p_mi the media player
1095 * \param on true to handle mouse click events, false to ignore them.
1096 */
1097LIBVLC_API
1098void libvlc_video_set_mouse_input( libvlc_media_player_t *p_mi, unsigned on );
1099
1100/**
1101 * Get the pixel dimensions of a video.
1102 *
1103 * \param p_mi media player
1104 * \param num number of the video (starting from, and most commonly 0)
1105 * \param px pointer to get the pixel width [OUT]
1106 * \param py pointer to get the pixel height [OUT]
1107 * \return 0 on success, -1 if the specified video does not exist
1108 */
1109LIBVLC_API
1110int libvlc_video_get_size( libvlc_media_player_t *p_mi, unsigned num,
1111 unsigned *px, unsigned *py );
1112
1113/**
1114 * Get the mouse pointer coordinates over a video.
1115 * Coordinates are expressed in terms of the decoded video resolution,
1116 * <b>not</b> in terms of pixels on the screen/viewport (to get the latter,
1117 * you can query your windowing system directly).
1118 *
1119 * Either of the coordinates may be negative or larger than the corresponding
1120 * dimension of the video, if the cursor is outside the rendering area.
1121 *
1122 * @warning The coordinates may be out-of-date if the pointer is not located
1123 * on the video rendering area. LibVLC does not track the pointer if it is
1124 * outside of the video widget.
1125 *
1126 * @note LibVLC does not support multiple pointers (it does of course support
1127 * multiple input devices sharing the same pointer) at the moment.
1128 *
1129 * \param p_mi media player
1130 * \param num number of the video (starting from, and most commonly 0)
1131 * \param px pointer to get the abscissa [OUT]
1132 * \param py pointer to get the ordinate [OUT]
1133 * \return 0 on success, -1 if the specified video does not exist
1134 */
1135LIBVLC_API
1136int libvlc_video_get_cursor( libvlc_media_player_t *p_mi, unsigned num,
1137 int *px, int *py );
1138
1139/**
1140 * Get the current video scaling factor.
1141 * See also libvlc_video_set_scale().
1142 *
1143 * \param p_mi the media player
1144 * \return the currently configured zoom factor, or 0. if the video is set
1145 * to fit to the output window/drawable automatically.
1146 */
1147LIBVLC_API float libvlc_video_get_scale( libvlc_media_player_t *p_mi );
1148
1149/**
1150 * Set the video scaling factor. That is the ratio of the number of pixels on
1151 * screen to the number of pixels in the original decoded video in each
1152 * dimension. Zero is a special value; it will adjust the video to the output
1153 * window/drawable (in windowed mode) or the entire screen.
1154 *
1155 * Note that not all video outputs support scaling.
1156 *
1157 * \param p_mi the media player
1158 * \param f_factor the scaling factor, or zero
1159 */
1160LIBVLC_API void libvlc_video_set_scale( libvlc_media_player_t *p_mi, float f_factor );
1161
1162/**
1163 * Get current video aspect ratio.
1164 *
1165 * \param p_mi the media player
1166 * \return the video aspect ratio or NULL if unspecified
1167 * (the result must be released with free() or libvlc_free()).
1168 */
1169LIBVLC_API char *libvlc_video_get_aspect_ratio( libvlc_media_player_t *p_mi );
1170
1171/**
1172 * Set new video aspect ratio.
1173 *
1174 * \param p_mi the media player
1175 * \param psz_aspect new video aspect-ratio or NULL to reset to default
1176 * \note Invalid aspect ratios are ignored.
1177 */
1178LIBVLC_API void libvlc_video_set_aspect_ratio( libvlc_media_player_t *p_mi, const char *psz_aspect );
1179
1180/**
1181 * Create a video viewpoint structure.
1182 *
1183 * \version LibVLC 3.0.0 and later
1184 *
1185 * \return video viewpoint or NULL
1186 * (the result must be released with free() or libvlc_free()).
1187 */
1188LIBVLC_API libvlc_video_viewpoint_t *libvlc_video_new_viewpoint(void);
1189
1190/**
1191 * Update the video viewpoint information.
1192 *
1193 * \note It is safe to call this function before the media player is started.
1194 *
1195 * \version LibVLC 3.0.0 and later
1196 *
1197 * \param p_mi the media player
1198 * \param p_viewpoint video viewpoint allocated via libvlc_video_new_viewpoint()
1199 * \param b_absolute if true replace the old viewpoint with the new one. If
1200 * false, increase/decrease it.
1201 * \return -1 in case of error, 0 otherwise
1202 *
1203 * \note the values are set asynchronously, it will be used by the next frame displayed.
1204 */
1205LIBVLC_API int libvlc_video_update_viewpoint( libvlc_media_player_t *p_mi,
1206 const libvlc_video_viewpoint_t *p_viewpoint,
1207 bool b_absolute);
1208
1209/**
1210 * Get current video subtitle.
1211 *
1212 * \param p_mi the media player
1213 * \return the video subtitle selected, or -1 if none
1214 */
1215LIBVLC_API int libvlc_video_get_spu( libvlc_media_player_t *p_mi );
1216
1217/**
1218 * Get the number of available video subtitles.
1219 *
1220 * \param p_mi the media player
1221 * \return the number of available video subtitles
1222 */
1223LIBVLC_API int libvlc_video_get_spu_count( libvlc_media_player_t *p_mi );
1224
1225/**
1226 * Get the description of available video subtitles.
1227 *
1228 * \param p_mi the media player
1229 * \return list containing description of available video subtitles.
1230 * It must be freed with libvlc_track_description_list_release()
1231 */
1232LIBVLC_API libvlc_track_description_t *
1233 libvlc_video_get_spu_description( libvlc_media_player_t *p_mi );
1234
1235/**
1236 * Set new video subtitle.
1237 *
1238 * \param p_mi the media player
1239 * \param i_spu video subtitle track to select (i_id from track description)
1240 * \return 0 on success, -1 if out of range
1241 */
1242LIBVLC_API int libvlc_video_set_spu( libvlc_media_player_t *p_mi, int i_spu );
1243
1244/**
1245 * Get the current subtitle delay. Positive values means subtitles are being
1246 * displayed later, negative values earlier.
1247 *
1248 * \param p_mi media player
1249 * \return time (in microseconds) the display of subtitles is being delayed
1250 * \version LibVLC 2.0.0 or later
1251 */
1252LIBVLC_API int64_t libvlc_video_get_spu_delay( libvlc_media_player_t *p_mi );
1253
1254/**
1255 * Set the subtitle delay. This affects the timing of when the subtitle will
1256 * be displayed. Positive values result in subtitles being displayed later,
1257 * while negative values will result in subtitles being displayed earlier.
1258 *
1259 * The subtitle delay will be reset to zero each time the media changes.
1260 *
1261 * \param p_mi media player
1262 * \param i_delay time (in microseconds) the display of subtitles should be delayed
1263 * \return 0 on success, -1 on error
1264 * \version LibVLC 2.0.0 or later
1265 */
1266LIBVLC_API int libvlc_video_set_spu_delay( libvlc_media_player_t *p_mi, int64_t i_delay );
1267
1268/**
1269 * Get the full description of available titles
1270 *
1271 * \version LibVLC 3.0.0 and later.
1272 *
1273 * \param p_mi the media player
1274 * \param titles address to store an allocated array of title descriptions
1275 * descriptions (must be freed with libvlc_title_descriptions_release()
1276 * by the caller) [OUT]
1277 *
1278 * \return the number of titles (-1 on error)
1279 */
1280LIBVLC_API int libvlc_media_player_get_full_title_descriptions( libvlc_media_player_t *p_mi,
1281 libvlc_title_description_t ***titles );
1282
1283/**
1284 * Release a title description
1285 *
1286 * \version LibVLC 3.0.0 and later
1287 *
1288 * \param p_titles title description array to release
1289 * \param i_count number of title descriptions to release
1290 */
1291LIBVLC_API
1292 void libvlc_title_descriptions_release( libvlc_title_description_t **p_titles,
1293 unsigned i_count );
1294
1295/**
1296 * Get the full description of available chapters
1297 *
1298 * \version LibVLC 3.0.0 and later.
1299 *
1300 * \param p_mi the media player
1301 * \param i_chapters_of_title index of the title to query for chapters (uses current title if set to -1)
1302 * \param pp_chapters address to store an allocated array of chapter descriptions
1303 * descriptions (must be freed with libvlc_chapter_descriptions_release()
1304 * by the caller) [OUT]
1305 *
1306 * \return the number of chapters (-1 on error)
1307 */
1308LIBVLC_API int libvlc_media_player_get_full_chapter_descriptions( libvlc_media_player_t *p_mi,
1309 int i_chapters_of_title,
1310 libvlc_chapter_description_t *** pp_chapters );
1311
1312/**
1313 * Release a chapter description
1314 *
1315 * \version LibVLC 3.0.0 and later
1316 *
1317 * \param p_chapters chapter description array to release
1318 * \param i_count number of chapter descriptions to release
1319 */
1320LIBVLC_API
1321void libvlc_chapter_descriptions_release( libvlc_chapter_description_t **p_chapters,
1322 unsigned i_count );
1323
1324/**
1325 * Get current crop filter geometry.
1326 *
1327 * \param p_mi the media player
1328 * \return the crop filter geometry or NULL if unset
1329 */
1330LIBVLC_API char *libvlc_video_get_crop_geometry( libvlc_media_player_t *p_mi );
1331
1332/**
1333 * Set new crop filter geometry.
1334 *
1335 * \param p_mi the media player
1336 * \param psz_geometry new crop filter geometry (NULL to unset)
1337 */
1338LIBVLC_API
1339void libvlc_video_set_crop_geometry( libvlc_media_player_t *p_mi, const char *psz_geometry );
1340
1341/**
1342 * Get current teletext page requested or 0 if it's disabled.
1343 *
1344 * Teletext is disabled by default, call libvlc_video_set_teletext() to enable
1345 * it.
1346 *
1347 * \param p_mi the media player
1348 * \return the current teletext page requested.
1349 */
1350LIBVLC_API int libvlc_video_get_teletext( libvlc_media_player_t *p_mi );
1351
1352/**
1353 * Set new teletext page to retrieve.
1354 *
1355 * This function can also be used to send a teletext key.
1356 *
1357 * \param p_mi the media player
1358 * \param i_page teletex page number requested. This value can be 0 to disable
1359 * teletext, a number in the range ]0;1000[ to show the requested page, or a
1360 * \ref libvlc_teletext_key_t. 100 is the default teletext page.
1361 */
1362LIBVLC_API void libvlc_video_set_teletext( libvlc_media_player_t *p_mi, int i_page );
1363
1364/**
1365 * Get number of available video tracks.
1366 *
1367 * \param p_mi media player
1368 * \return the number of available video tracks (int)
1369 */
1370LIBVLC_API int libvlc_video_get_track_count( libvlc_media_player_t *p_mi );
1371
1372/**
1373 * Get the description of available video tracks.
1374 *
1375 * \param p_mi media player
1376 * \return list with description of available video tracks, or NULL on error.
1377 * It must be freed with libvlc_track_description_list_release()
1378 */
1379LIBVLC_API libvlc_track_description_t *
1380 libvlc_video_get_track_description( libvlc_media_player_t *p_mi );
1381
1382/**
1383 * Get current video track.
1384 *
1385 * \param p_mi media player
1386 * \return the video track ID (int) or -1 if no active input
1387 */
1388LIBVLC_API int libvlc_video_get_track( libvlc_media_player_t *p_mi );
1389
1390/**
1391 * Set video track.
1392 *
1393 * \param p_mi media player
1394 * \param i_track the track ID (i_id field from track description)
1395 * \return 0 on success, -1 if out of range
1396 */
1397LIBVLC_API
1398int libvlc_video_set_track( libvlc_media_player_t *p_mi, int i_track );
1399
1400/**
1401 * Take a snapshot of the current video window.
1402 *
1403 * If i_width AND i_height is 0, original size is used.
1404 * If i_width XOR i_height is 0, original aspect-ratio is preserved.
1405 *
1406 * \param p_mi media player instance
1407 * \param num number of video output (typically 0 for the first/only one)
1408 * \param psz_filepath the path of a file or a folder to save the screenshot into
1409 * \param i_width the snapshot's width
1410 * \param i_height the snapshot's height
1411 * \return 0 on success, -1 if the video was not found
1412 */
1413LIBVLC_API
1414int libvlc_video_take_snapshot( libvlc_media_player_t *p_mi, unsigned num,
1415 const char *psz_filepath, unsigned int i_width,
1416 unsigned int i_height );
1417
1418/**
1419 * Enable or disable deinterlace filter
1420 *
1421 * \param p_mi libvlc media player
1422 * \param psz_mode type of deinterlace filter, NULL to disable
1423 */
1424LIBVLC_API void libvlc_video_set_deinterlace( libvlc_media_player_t *p_mi,
1425 const char *psz_mode );
1426
1427/**
1428 * Get an integer marquee option value
1429 *
1430 * \param p_mi libvlc media player
1431 * \param option marq option to get \see libvlc_video_marquee_int_option_t
1432 */
1433LIBVLC_API int libvlc_video_get_marquee_int( libvlc_media_player_t *p_mi,
1434 unsigned option );
1435
1436/**
1437 * Get a string marquee option value
1438 *
1439 * \param p_mi libvlc media player
1440 * \param option marq option to get \see libvlc_video_marquee_string_option_t
1441 */
1442LIBVLC_API char *libvlc_video_get_marquee_string( libvlc_media_player_t *p_mi,
1443 unsigned option );
1444
1445/**
1446 * Enable, disable or set an integer marquee option
1447 *
1448 * Setting libvlc_marquee_Enable has the side effect of enabling (arg !0)
1449 * or disabling (arg 0) the marq filter.
1450 *
1451 * \param p_mi libvlc media player
1452 * \param option marq option to set \see libvlc_video_marquee_int_option_t
1453 * \param i_val marq option value
1454 */
1455LIBVLC_API void libvlc_video_set_marquee_int( libvlc_media_player_t *p_mi,
1456 unsigned option, int i_val );
1457
1458/**
1459 * Set a marquee string option
1460 *
1461 * \param p_mi libvlc media player
1462 * \param option marq option to set \see libvlc_video_marquee_string_option_t
1463 * \param psz_text marq option value
1464 */
1465LIBVLC_API void libvlc_video_set_marquee_string( libvlc_media_player_t *p_mi,
1466 unsigned option, const char *psz_text );
1467
1468/** option values for libvlc_video_{get,set}_logo_{int,string} */
1469enum libvlc_video_logo_option_t {
1470 libvlc_logo_enable,
1471 libvlc_logo_file, /**< string argument, "file,d,t;file,d,t;..." */
1472 libvlc_logo_x,
1473 libvlc_logo_y,
1474 libvlc_logo_delay,
1475 libvlc_logo_repeat,
1476 libvlc_logo_opacity,
1477 libvlc_logo_position
1478};
1479
1480/**
1481 * Get integer logo option.
1482 *
1483 * \param p_mi libvlc media player instance
1484 * \param option logo option to get, values of libvlc_video_logo_option_t
1485 */
1486LIBVLC_API int libvlc_video_get_logo_int( libvlc_media_player_t *p_mi,
1487 unsigned option );
1488
1489/**
1490 * Set logo option as integer. Options that take a different type value
1491 * are ignored.
1492 * Passing libvlc_logo_enable as option value has the side effect of
1493 * starting (arg !0) or stopping (arg 0) the logo filter.
1494 *
1495 * \param p_mi libvlc media player instance
1496 * \param option logo option to set, values of libvlc_video_logo_option_t
1497 * \param value logo option value
1498 */
1499LIBVLC_API void libvlc_video_set_logo_int( libvlc_media_player_t *p_mi,
1500 unsigned option, int value );
1501
1502/**
1503 * Set logo option as string. Options that take a different type value
1504 * are ignored.
1505 *
1506 * \param p_mi libvlc media player instance
1507 * \param option logo option to set, values of libvlc_video_logo_option_t
1508 * \param psz_value logo option value
1509 */
1510LIBVLC_API void libvlc_video_set_logo_string( libvlc_media_player_t *p_mi,
1511 unsigned option, const char *psz_value );
1512
1513
1514/** option values for libvlc_video_{get,set}_adjust_{int,float,bool} */
1515enum libvlc_video_adjust_option_t {
1516 libvlc_adjust_Enable = 0,
1517 libvlc_adjust_Contrast,
1518 libvlc_adjust_Brightness,
1519 libvlc_adjust_Hue,
1520 libvlc_adjust_Saturation,
1521 libvlc_adjust_Gamma
1522};
1523
1524/**
1525 * Get integer adjust option.
1526 *
1527 * \param p_mi libvlc media player instance
1528 * \param option adjust option to get, values of libvlc_video_adjust_option_t
1529 * \version LibVLC 1.1.1 and later.
1530 */
1531LIBVLC_API int libvlc_video_get_adjust_int( libvlc_media_player_t *p_mi,
1532 unsigned option );
1533
1534/**
1535 * Set adjust option as integer. Options that take a different type value
1536 * are ignored.
1537 * Passing libvlc_adjust_enable as option value has the side effect of
1538 * starting (arg !0) or stopping (arg 0) the adjust filter.
1539 *
1540 * \param p_mi libvlc media player instance
1541 * \param option adust option to set, values of libvlc_video_adjust_option_t
1542 * \param value adjust option value
1543 * \version LibVLC 1.1.1 and later.
1544 */
1545LIBVLC_API void libvlc_video_set_adjust_int( libvlc_media_player_t *p_mi,
1546 unsigned option, int value );
1547
1548/**
1549 * Get float adjust option.
1550 *
1551 * \param p_mi libvlc media player instance
1552 * \param option adjust option to get, values of libvlc_video_adjust_option_t
1553 * \version LibVLC 1.1.1 and later.
1554 */
1555LIBVLC_API float libvlc_video_get_adjust_float( libvlc_media_player_t *p_mi,
1556 unsigned option );
1557
1558/**
1559 * Set adjust option as float. Options that take a different type value
1560 * are ignored.
1561 *
1562 * \param p_mi libvlc media player instance
1563 * \param option adust option to set, values of libvlc_video_adjust_option_t
1564 * \param value adjust option value
1565 * \version LibVLC 1.1.1 and later.
1566 */
1567LIBVLC_API void libvlc_video_set_adjust_float( libvlc_media_player_t *p_mi,
1568 unsigned option, float value );
1569
1570/** @} video */
1571
1572/** \defgroup libvlc_audio LibVLC audio controls
1573 * @{
1574 */
1575
1576/**
1577 * Audio device types
1578 */
1579typedef enum libvlc_audio_output_device_types_t {
1580 libvlc_AudioOutputDevice_Error = -1,
1581 libvlc_AudioOutputDevice_Mono = 1,
1582 libvlc_AudioOutputDevice_Stereo = 2,
1583 libvlc_AudioOutputDevice_2F2R = 4,
1584 libvlc_AudioOutputDevice_3F2R = 5,
1585 libvlc_AudioOutputDevice_5_1 = 6,
1586 libvlc_AudioOutputDevice_6_1 = 7,
1587 libvlc_AudioOutputDevice_7_1 = 8,
1588 libvlc_AudioOutputDevice_SPDIF = 10
1589} libvlc_audio_output_device_types_t;
1590
1591/**
1592 * Audio channels
1593 */
1594typedef enum libvlc_audio_output_channel_t {
1595 libvlc_AudioChannel_Error = -1,
1596 libvlc_AudioChannel_Stereo = 1,
1597 libvlc_AudioChannel_RStereo = 2,
1598 libvlc_AudioChannel_Left = 3,
1599 libvlc_AudioChannel_Right = 4,
1600 libvlc_AudioChannel_Dolbys = 5
1601} libvlc_audio_output_channel_t;
1602
1603
1604/**
1605 * Gets the list of available audio output modules.
1606 *
1607 * \param p_instance libvlc instance
1608 * \return list of available audio outputs. It must be freed with
1609* \see libvlc_audio_output_list_release \see libvlc_audio_output_t .
1610 * In case of error, NULL is returned.
1611 */
1612LIBVLC_API libvlc_audio_output_t *
1613libvlc_audio_output_list_get( libvlc_instance_t *p_instance );
1614
1615/**
1616 * Frees the list of available audio output modules.
1617 *
1618 * \param p_list list with audio outputs for release
1619 */
1620LIBVLC_API
1621void libvlc_audio_output_list_release( libvlc_audio_output_t *p_list );
1622
1623/**
1624 * Selects an audio output module.
1625 * \note Any change will take be effect only after playback is stopped and
1626 * restarted. Audio output cannot be changed while playing.
1627 *
1628 * \param p_mi media player
1629 * \param psz_name name of audio output,
1630 * use psz_name of \see libvlc_audio_output_t
1631 * \return 0 if function succeeded, -1 on error
1632 */
1633LIBVLC_API int libvlc_audio_output_set( libvlc_media_player_t *p_mi,
1634 const char *psz_name );
1635
1636/**
1637 * Gets a list of potential audio output devices,
1638 * \see libvlc_audio_output_device_set().
1639 *
1640 * \note Not all audio outputs support enumerating devices.
1641 * The audio output may be functional even if the list is empty (NULL).
1642 *
1643 * \note The list may not be exhaustive.
1644 *
1645 * \warning Some audio output devices in the list might not actually work in
1646 * some circumstances. By default, it is recommended to not specify any
1647 * explicit audio device.
1648 *
1649 * \param mp media player
1650 * \return A NULL-terminated linked list of potential audio output devices.
1651 * It must be freed with libvlc_audio_output_device_list_release()
1652 * \version LibVLC 2.2.0 or later.
1653 */
1654LIBVLC_API libvlc_audio_output_device_t *
1655libvlc_audio_output_device_enum( libvlc_media_player_t *mp );
1656
1657/**
1658 * Gets a list of audio output devices for a given audio output module,
1659 * \see libvlc_audio_output_device_set().
1660 *
1661 * \note Not all audio outputs support this. In particular, an empty (NULL)
1662 * list of devices does <b>not</b> imply that the specified audio output does
1663 * not work.
1664 *
1665 * \note The list might not be exhaustive.
1666 *
1667 * \warning Some audio output devices in the list might not actually work in
1668 * some circumstances. By default, it is recommended to not specify any
1669 * explicit audio device.
1670 *
1671 * \param p_instance libvlc instance
1672 * \param aout audio output name
1673 * (as returned by libvlc_audio_output_list_get())
1674 * \return A NULL-terminated linked list of potential audio output devices.
1675 * It must be freed with libvlc_audio_output_device_list_release()
1676 * \version LibVLC 2.1.0 or later.
1677 */
1678LIBVLC_API libvlc_audio_output_device_t *
1679libvlc_audio_output_device_list_get( libvlc_instance_t *p_instance,
1680 const char *aout );
1681
1682/**
1683 * Frees a list of available audio output devices.
1684 *
1685 * \param p_list list with audio outputs for release
1686 * \version LibVLC 2.1.0 or later.
1687 */
1688LIBVLC_API void libvlc_audio_output_device_list_release(
1689 libvlc_audio_output_device_t *p_list );
1690
1691/**
1692 * Configures an explicit audio output device.
1693 *
1694 * If the module paramater is NULL, audio output will be moved to the device
1695 * specified by the device identifier string immediately. This is the
1696 * recommended usage.
1697 *
1698 * A list of adequate potential device strings can be obtained with
1699 * libvlc_audio_output_device_enum().
1700 *
1701 * However passing NULL is supported in LibVLC version 2.2.0 and later only;
1702 * in earlier versions, this function would have no effects when the module
1703 * parameter was NULL.
1704 *
1705 * If the module parameter is not NULL, the device parameter of the
1706 * corresponding audio output, if it exists, will be set to the specified
1707 * string. Note that some audio output modules do not have such a parameter
1708 * (notably MMDevice and PulseAudio).
1709 *
1710 * A list of adequate potential device strings can be obtained with
1711 * libvlc_audio_output_device_list_get().
1712 *
1713 * \note This function does not select the specified audio output plugin.
1714 * libvlc_audio_output_set() is used for that purpose.
1715 *
1716 * \warning The syntax for the device parameter depends on the audio output.
1717 *
1718 * Some audio output modules require further parameters (e.g. a channels map
1719 * in the case of ALSA).
1720 *
1721 * \param mp media player
1722 * \param module If NULL, current audio output module.
1723 * if non-NULL, name of audio output module
1724 (\see libvlc_audio_output_t)
1725 * \param device_id device identifier string
1726 * \return Nothing. Errors are ignored (this is a design bug).
1727 */
1728LIBVLC_API void libvlc_audio_output_device_set( libvlc_media_player_t *mp,
1729 const char *module,
1730 const char *device_id );
1731
1732/**
1733 * Get the current audio output device identifier.
1734 *
1735 * This complements libvlc_audio_output_device_set().
1736 *
1737 * \warning The initial value for the current audio output device identifier
1738 * may not be set or may be some unknown value. A LibVLC application should
1739 * compare this value against the known device identifiers (e.g. those that
1740 * were previously retrieved by a call to libvlc_audio_output_device_enum or
1741 * libvlc_audio_output_device_list_get) to find the current audio output device.
1742 *
1743 * It is possible that the selected audio output device changes (an external
1744 * change) without a call to libvlc_audio_output_device_set. That may make this
1745 * method unsuitable to use if a LibVLC application is attempting to track
1746 * dynamic audio device changes as they happen.
1747 *
1748 * \param mp media player
1749 * \return the current audio output device identifier
1750 * NULL if no device is selected or in case of error
1751 * (the result must be released with free() or libvlc_free()).
1752 * \version LibVLC 3.0.0 or later.
1753 */
1754LIBVLC_API char *libvlc_audio_output_device_get( libvlc_media_player_t *mp );
1755
1756/**
1757 * Toggle mute status.
1758 *
1759 * \param p_mi media player
1760 * \warning Toggling mute atomically is not always possible: On some platforms,
1761 * other processes can mute the VLC audio playback stream asynchronously. Thus,
1762 * there is a small race condition where toggling will not work.
1763 * See also the limitations of libvlc_audio_set_mute().
1764 */
1765LIBVLC_API void libvlc_audio_toggle_mute( libvlc_media_player_t *p_mi );
1766
1767/**
1768 * Get current mute status.
1769 *
1770 * \param p_mi media player
1771 * \return the mute status (boolean) if defined, -1 if undefined/unapplicable
1772 */
1773LIBVLC_API int libvlc_audio_get_mute( libvlc_media_player_t *p_mi );
1774
1775/**
1776 * Set mute status.
1777 *
1778 * \param p_mi media player
1779 * \param status If status is true then mute, otherwise unmute
1780 * \warning This function does not always work. If there are no active audio
1781 * playback stream, the mute status might not be available. If digital
1782 * pass-through (S/PDIF, HDMI...) is in use, muting may be unapplicable. Also
1783 * some audio output plugins do not support muting at all.
1784 * \note To force silent playback, disable all audio tracks. This is more
1785 * efficient and reliable than mute.
1786 */
1787LIBVLC_API void libvlc_audio_set_mute( libvlc_media_player_t *p_mi, int status );
1788
1789/**
1790 * Get current software audio volume.
1791 *
1792 * \param p_mi media player
1793 * \return the software volume in percents
1794 * (0 = mute, 100 = nominal / 0dB)
1795 */
1796LIBVLC_API int libvlc_audio_get_volume( libvlc_media_player_t *p_mi );
1797
1798/**
1799 * Set current software audio volume.
1800 *
1801 * \param p_mi media player
1802 * \param i_volume the volume in percents (0 = mute, 100 = 0dB)
1803 * \return 0 if the volume was set, -1 if it was out of range
1804 */
1805LIBVLC_API int libvlc_audio_set_volume( libvlc_media_player_t *p_mi, int i_volume );
1806
1807/**
1808 * Get number of available audio tracks.
1809 *
1810 * \param p_mi media player
1811 * \return the number of available audio tracks (int), or -1 if unavailable
1812 */
1813LIBVLC_API int libvlc_audio_get_track_count( libvlc_media_player_t *p_mi );
1814
1815/**
1816 * Get the description of available audio tracks.
1817 *
1818 * \param p_mi media player
1819 * \return list with description of available audio tracks, or NULL.
1820 * It must be freed with libvlc_track_description_list_release()
1821 */
1822LIBVLC_API libvlc_track_description_t *
1823 libvlc_audio_get_track_description( libvlc_media_player_t *p_mi );
1824
1825/**
1826 * Get current audio track.
1827 *
1828 * \param p_mi media player
1829 * \return the audio track ID or -1 if no active input.
1830 */
1831LIBVLC_API int libvlc_audio_get_track( libvlc_media_player_t *p_mi );
1832
1833/**
1834 * Set current audio track.
1835 *
1836 * \param p_mi media player
1837 * \param i_track the track ID (i_id field from track description)
1838 * \return 0 on success, -1 on error
1839 */
1840LIBVLC_API int libvlc_audio_set_track( libvlc_media_player_t *p_mi, int i_track );
1841
1842/**
1843 * Get current audio channel.
1844 *
1845 * \param p_mi media player
1846 * \return the audio channel \see libvlc_audio_output_channel_t
1847 */
1848LIBVLC_API int libvlc_audio_get_channel( libvlc_media_player_t *p_mi );
1849
1850/**
1851 * Set current audio channel.
1852 *
1853 * \param p_mi media player
1854 * \param channel the audio channel, \see libvlc_audio_output_channel_t
1855 * \return 0 on success, -1 on error
1856 */
1857LIBVLC_API int libvlc_audio_set_channel( libvlc_media_player_t *p_mi, int channel );
1858
1859/**
1860 * Get current audio delay.
1861 *
1862 * \param p_mi media player
1863 * \return the audio delay (microseconds)
1864 * \version LibVLC 1.1.1 or later
1865 */
1866LIBVLC_API int64_t libvlc_audio_get_delay( libvlc_media_player_t *p_mi );
1867
1868/**
1869 * Set current audio delay. The audio delay will be reset to zero each time the media changes.
1870 *
1871 * \param p_mi media player
1872 * \param i_delay the audio delay (microseconds)
1873 * \return 0 on success, -1 on error
1874 * \version LibVLC 1.1.1 or later
1875 */
1876LIBVLC_API int libvlc_audio_set_delay( libvlc_media_player_t *p_mi, int64_t i_delay );
1877
1878/**
1879 * Get the number of equalizer presets.
1880 *
1881 * \return number of presets
1882 * \version LibVLC 2.2.0 or later
1883 */
1884LIBVLC_API unsigned libvlc_audio_equalizer_get_preset_count( void );
1885
1886/**
1887 * Get the name of a particular equalizer preset.
1888 *
1889 * This name can be used, for example, to prepare a preset label or menu in a user
1890 * interface.
1891 *
1892 * \param u_index index of the preset, counting from zero
1893 * \return preset name, or NULL if there is no such preset
1894 * \version LibVLC 2.2.0 or later
1895 */
1896LIBVLC_API const char *libvlc_audio_equalizer_get_preset_name( unsigned u_index );
1897
1898/**
1899 * Get the number of distinct frequency bands for an equalizer.
1900 *
1901 * \return number of frequency bands
1902 * \version LibVLC 2.2.0 or later
1903 */
1904LIBVLC_API unsigned libvlc_audio_equalizer_get_band_count( void );
1905
1906/**
1907 * Get a particular equalizer band frequency.
1908 *
1909 * This value can be used, for example, to create a label for an equalizer band control
1910 * in a user interface.
1911 *
1912 * \param u_index index of the band, counting from zero
1913 * \return equalizer band frequency (Hz), or -1 if there is no such band
1914 * \version LibVLC 2.2.0 or later
1915 */
1916LIBVLC_API float libvlc_audio_equalizer_get_band_frequency( unsigned u_index );
1917
1918/**
1919 * Create a new default equalizer, with all frequency values zeroed.
1920 *
1921 * The new equalizer can subsequently be applied to a media player by invoking
1922 * libvlc_media_player_set_equalizer().
1923 *
1924 * The returned handle should be freed via libvlc_audio_equalizer_release() when
1925 * it is no longer needed.
1926 *
1927 * \return opaque equalizer handle, or NULL on error
1928 * \version LibVLC 2.2.0 or later
1929 */
1930LIBVLC_API libvlc_equalizer_t *libvlc_audio_equalizer_new( void );
1931
1932/**
1933 * Create a new equalizer, with initial frequency values copied from an existing
1934 * preset.
1935 *
1936 * The new equalizer can subsequently be applied to a media player by invoking
1937 * libvlc_media_player_set_equalizer().
1938 *
1939 * The returned handle should be freed via libvlc_audio_equalizer_release() when
1940 * it is no longer needed.
1941 *
1942 * \param u_index index of the preset, counting from zero
1943 * \return opaque equalizer handle, or NULL on error
1944 * \version LibVLC 2.2.0 or later
1945 */
1946LIBVLC_API libvlc_equalizer_t *libvlc_audio_equalizer_new_from_preset( unsigned u_index );
1947
1948/**
1949 * Release a previously created equalizer instance.
1950 *
1951 * The equalizer was previously created by using libvlc_audio_equalizer_new() or
1952 * libvlc_audio_equalizer_new_from_preset().
1953 *
1954 * It is safe to invoke this method with a NULL p_equalizer parameter for no effect.
1955 *
1956 * \param p_equalizer opaque equalizer handle, or NULL
1957 * \version LibVLC 2.2.0 or later
1958 */
1959LIBVLC_API void libvlc_audio_equalizer_release( libvlc_equalizer_t *p_equalizer );
1960
1961/**
1962 * Set a new pre-amplification value for an equalizer.
1963 *
1964 * The new equalizer settings are subsequently applied to a media player by invoking
1965 * libvlc_media_player_set_equalizer().
1966 *
1967 * The supplied amplification value will be clamped to the -20.0 to +20.0 range.
1968 *
1969 * \param p_equalizer valid equalizer handle, must not be NULL
1970 * \param f_preamp preamp value (-20.0 to 20.0 Hz)
1971 * \return zero on success, -1 on error
1972 * \version LibVLC 2.2.0 or later
1973 */
1974LIBVLC_API int libvlc_audio_equalizer_set_preamp( libvlc_equalizer_t *p_equalizer, float f_preamp );
1975
1976/**
1977 * Get the current pre-amplification value from an equalizer.
1978 *
1979 * \param p_equalizer valid equalizer handle, must not be NULL
1980 * \return preamp value (Hz)
1981 * \version LibVLC 2.2.0 or later
1982 */
1983LIBVLC_API float libvlc_audio_equalizer_get_preamp( libvlc_equalizer_t *p_equalizer );
1984
1985/**
1986 * Set a new amplification value for a particular equalizer frequency band.
1987 *
1988 * The new equalizer settings are subsequently applied to a media player by invoking
1989 * libvlc_media_player_set_equalizer().
1990 *
1991 * The supplied amplification value will be clamped to the -20.0 to +20.0 range.
1992 *
1993 * \param p_equalizer valid equalizer handle, must not be NULL
1994 * \param f_amp amplification value (-20.0 to 20.0 Hz)
1995 * \param u_band index, counting from zero, of the frequency band to set
1996 * \return zero on success, -1 on error
1997 * \version LibVLC 2.2.0 or later
1998 */
1999LIBVLC_API int libvlc_audio_equalizer_set_amp_at_index( libvlc_equalizer_t *p_equalizer, float f_amp, unsigned u_band );
2000
2001/**
2002 * Get the amplification value for a particular equalizer frequency band.
2003 *
2004 * \param p_equalizer valid equalizer handle, must not be NULL
2005 * \param u_band index, counting from zero, of the frequency band to get
2006 * \return amplification value (Hz); NaN if there is no such frequency band
2007 * \version LibVLC 2.2.0 or later
2008 */
2009LIBVLC_API float libvlc_audio_equalizer_get_amp_at_index( libvlc_equalizer_t *p_equalizer, unsigned u_band );
2010
2011/**
2012 * Apply new equalizer settings to a media player.
2013 *
2014 * The equalizer is first created by invoking libvlc_audio_equalizer_new() or
2015 * libvlc_audio_equalizer_new_from_preset().
2016 *
2017 * It is possible to apply new equalizer settings to a media player whether the media
2018 * player is currently playing media or not.
2019 *
2020 * Invoking this method will immediately apply the new equalizer settings to the audio
2021 * output of the currently playing media if there is any.
2022 *
2023 * If there is no currently playing media, the new equalizer settings will be applied
2024 * later if and when new media is played.
2025 *
2026 * Equalizer settings will automatically be applied to subsequently played media.
2027 *
2028 * To disable the equalizer for a media player invoke this method passing NULL for the
2029 * p_equalizer parameter.
2030 *
2031 * The media player does not keep a reference to the supplied equalizer so it is safe
2032 * for an application to release the equalizer reference any time after this method
2033 * returns.
2034 *
2035 * \param p_mi opaque media player handle
2036 * \param p_equalizer opaque equalizer handle, or NULL to disable the equalizer for this media player
2037 * \return zero on success, -1 on error
2038 * \version LibVLC 2.2.0 or later
2039 */
2040LIBVLC_API int libvlc_media_player_set_equalizer( libvlc_media_player_t *p_mi, libvlc_equalizer_t *p_equalizer );
2041
2042/**
2043 * Media player roles.
2044 *
2045 * \version LibVLC 3.0.0 and later.
2046 *
2047 * See \ref libvlc_media_player_set_role()
2048 */
2049typedef enum libvlc_media_player_role {
2050 libvlc_role_None = 0, /**< Don't use a media player role */
2051 libvlc_role_Music, /**< Music (or radio) playback */
2052 libvlc_role_Video, /**< Video playback */
2053 libvlc_role_Communication, /**< Speech, real-time communication */
2054 libvlc_role_Game, /**< Video game */
2055 libvlc_role_Notification, /**< User interaction feedback */
2056 libvlc_role_Animation, /**< Embedded animation (e.g. in web page) */
2057 libvlc_role_Production, /**< Audio editting/production */
2058 libvlc_role_Accessibility, /**< Accessibility */
2059 libvlc_role_Test /** Testing */
2060#define libvlc_role_Last libvlc_role_Test
2061} libvlc_media_player_role_t;
2062
2063/**
2064 * Gets the media role.
2065 *
2066 * \version LibVLC 3.0.0 and later.
2067 *
2068 * \param p_mi media player
2069 * \return the media player role (\ref libvlc_media_player_role_t)
2070 */
2071LIBVLC_API int libvlc_media_player_get_role(libvlc_media_player_t *p_mi);
2072
2073/**
2074 * Sets the media role.
2075 *
2076 * \param p_mi media player
2077 * \param role the media player role (\ref libvlc_media_player_role_t)
2078 * \return 0 on success, -1 on error
2079 */
2080LIBVLC_API int libvlc_media_player_set_role(libvlc_media_player_t *p_mi,
2081 unsigned role);
2082
2083/** @} audio */
2084
2085/** @} media_player */
2086
2087# ifdef __cplusplus
2088}
2089# endif
2090
2091#endif /* VLC_LIBVLC_MEDIA_PLAYER_H */
2092

source code of include/vlc/libvlc_media_player.h