1 | /***************************************************************************** |
2 | * libvlc_media_player.h: libvlc_media_player external API |
3 | ***************************************************************************** |
4 | * Copyright (C) 1998-2010 VLC authors and VideoLAN |
5 | * $Id: 82c7ac2cfd2ecf05449a3ee22bcb2a23420d413a $ |
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 | /** |
27 | * \file |
28 | * This file defines libvlc_media_player external API |
29 | */ |
30 | |
31 | #ifndef VLC_LIBVLC_MEDIA_PLAYER_H |
32 | #define VLC_LIBVLC_MEDIA_PLAYER_H 1 |
33 | |
34 | # ifdef __cplusplus |
35 | extern "C" { |
36 | # else |
37 | # include <stdbool.h> |
38 | # endif |
39 | |
40 | /***************************************************************************** |
41 | * Media Player |
42 | *****************************************************************************/ |
43 | /** \defgroup libvlc_media_player LibVLC media player |
44 | * \ingroup libvlc |
45 | * A LibVLC media player plays one media (usually in a custom drawable). |
46 | * @{ |
47 | */ |
48 | |
49 | typedef struct libvlc_media_player_t libvlc_media_player_t; |
50 | |
51 | /** |
52 | * Description for video, audio tracks and subtitles. It contains |
53 | * id, name (description string) and pointer to next record. |
54 | */ |
55 | typedef struct libvlc_track_description_t |
56 | { |
57 | int i_id; |
58 | char *psz_name; |
59 | struct libvlc_track_description_t *p_next; |
60 | |
61 | } libvlc_track_description_t; |
62 | |
63 | /** |
64 | * Description for audio output. It contains |
65 | * name, description and pointer to next record. |
66 | */ |
67 | typedef struct libvlc_audio_output_t |
68 | { |
69 | char *psz_name; |
70 | char *psz_description; |
71 | struct libvlc_audio_output_t *p_next; |
72 | |
73 | } libvlc_audio_output_t; |
74 | |
75 | /** |
76 | * Description for audio output device. |
77 | */ |
78 | typedef struct libvlc_audio_output_device_t |
79 | { |
80 | struct libvlc_audio_output_device_t *p_next; /**< Next entry in list */ |
81 | char *psz_device; /**< Device identifier string */ |
82 | char *psz_description; /**< User-friendly device description */ |
83 | /* More fields may be added here in later versions */ |
84 | } libvlc_audio_output_device_t; |
85 | |
86 | /** |
87 | * Rectangle type for video geometry |
88 | */ |
89 | typedef struct libvlc_rectangle_t |
90 | { |
91 | int top, left; |
92 | int bottom, right; |
93 | } libvlc_rectangle_t; |
94 | |
95 | /** |
96 | * Marq options definition |
97 | */ |
98 | typedef enum libvlc_video_marquee_option_t { |
99 | libvlc_marquee_Enable = 0, |
100 | libvlc_marquee_Text, /** string argument */ |
101 | libvlc_marquee_Color, |
102 | libvlc_marquee_Opacity, |
103 | libvlc_marquee_Position, |
104 | libvlc_marquee_Refresh, |
105 | libvlc_marquee_Size, |
106 | libvlc_marquee_Timeout, |
107 | libvlc_marquee_X, |
108 | libvlc_marquee_Y |
109 | } libvlc_video_marquee_option_t; |
110 | |
111 | /** |
112 | * Navigation mode |
113 | */ |
114 | typedef enum libvlc_navigate_mode_t |
115 | { |
116 | libvlc_navigate_activate = 0, |
117 | libvlc_navigate_up, |
118 | libvlc_navigate_down, |
119 | libvlc_navigate_left, |
120 | libvlc_navigate_right |
121 | } libvlc_navigate_mode_t; |
122 | |
123 | /** |
124 | * Enumeration of values used to set position (e.g. of video title). |
125 | */ |
126 | typedef enum libvlc_position_t { |
127 | libvlc_position_disable=-1, |
128 | libvlc_position_center, |
129 | libvlc_position_left, |
130 | libvlc_position_right, |
131 | libvlc_position_top, |
132 | libvlc_position_top_left, |
133 | libvlc_position_top_right, |
134 | libvlc_position_bottom, |
135 | libvlc_position_bottom_left, |
136 | libvlc_position_bottom_right |
137 | } libvlc_position_t; |
138 | |
139 | /** |
140 | * Create an empty Media Player object |
141 | * |
142 | * \param p_libvlc_instance the libvlc instance in which the Media Player |
143 | * should be created. |
144 | * \return a new media player object, or NULL on error. |
145 | */ |
146 | LIBVLC_API libvlc_media_player_t * libvlc_media_player_new( libvlc_instance_t *p_libvlc_instance ); |
147 | |
148 | /** |
149 | * Create a Media Player object from a Media |
150 | * |
151 | * \param p_md the media. Afterwards the p_md can be safely |
152 | * destroyed. |
153 | * \return a new media player object, or NULL on error. |
154 | */ |
155 | LIBVLC_API libvlc_media_player_t * libvlc_media_player_new_from_media( libvlc_media_t *p_md ); |
156 | |
157 | /** |
158 | * Release a media_player after use |
159 | * Decrement the reference count of a media player object. If the |
160 | * reference count is 0, then libvlc_media_player_release() will |
161 | * release the media player object. If the media player object |
162 | * has been released, then it should not be used again. |
163 | * |
164 | * \param p_mi the Media Player to free |
165 | */ |
166 | LIBVLC_API void libvlc_media_player_release( libvlc_media_player_t *p_mi ); |
167 | |
168 | /** |
169 | * Retain a reference to a media player object. Use |
170 | * libvlc_media_player_release() to decrement reference count. |
171 | * |
172 | * \param p_mi media player object |
173 | */ |
174 | LIBVLC_API void libvlc_media_player_retain( libvlc_media_player_t *p_mi ); |
175 | |
176 | /** |
177 | * Set the media that will be used by the media_player. If any, |
178 | * previous md will be released. |
179 | * |
180 | * \param p_mi the Media Player |
181 | * \param p_md the Media. Afterwards the p_md can be safely |
182 | * destroyed. |
183 | */ |
184 | LIBVLC_API void libvlc_media_player_set_media( libvlc_media_player_t *p_mi, |
185 | libvlc_media_t *p_md ); |
186 | |
187 | /** |
188 | * Get the media used by the media_player. |
189 | * |
190 | * \param p_mi the Media Player |
191 | * \return the media associated with p_mi, or NULL if no |
192 | * media is associated |
193 | */ |
194 | LIBVLC_API libvlc_media_t * libvlc_media_player_get_media( libvlc_media_player_t *p_mi ); |
195 | |
196 | /** |
197 | * Get the Event Manager from which the media player send event. |
198 | * |
199 | * \param p_mi the Media Player |
200 | * \return the event manager associated with p_mi |
201 | */ |
202 | LIBVLC_API libvlc_event_manager_t * libvlc_media_player_event_manager ( libvlc_media_player_t *p_mi ); |
203 | |
204 | /** |
205 | * is_playing |
206 | * |
207 | * \param p_mi the Media Player |
208 | * \return 1 if the media player is playing, 0 otherwise |
209 | * |
210 | * \libvlc_return_bool |
211 | */ |
212 | LIBVLC_API int libvlc_media_player_is_playing ( libvlc_media_player_t *p_mi ); |
213 | |
214 | /** |
215 | * Play |
216 | * |
217 | * \param p_mi the Media Player |
218 | * \return 0 if playback started (and was already started), or -1 on error. |
219 | */ |
220 | LIBVLC_API int libvlc_media_player_play ( libvlc_media_player_t *p_mi ); |
221 | |
222 | /** |
223 | * Pause or resume (no effect if there is no media) |
224 | * |
225 | * \param mp the Media Player |
226 | * \param do_pause play/resume if zero, pause if non-zero |
227 | * \version LibVLC 1.1.1 or later |
228 | */ |
229 | LIBVLC_API void libvlc_media_player_set_pause ( libvlc_media_player_t *mp, |
230 | int do_pause ); |
231 | |
232 | /** |
233 | * Toggle pause (no effect if there is no media) |
234 | * |
235 | * \param p_mi the Media Player |
236 | */ |
237 | LIBVLC_API void libvlc_media_player_pause ( libvlc_media_player_t *p_mi ); |
238 | |
239 | /** |
240 | * Stop (no effect if there is no media) |
241 | * |
242 | * \param p_mi the Media Player |
243 | */ |
244 | LIBVLC_API void libvlc_media_player_stop ( libvlc_media_player_t *p_mi ); |
245 | |
246 | /** |
247 | * Callback prototype to allocate and lock a picture buffer. |
248 | * |
249 | * Whenever a new video frame needs to be decoded, the lock callback is |
250 | * invoked. Depending on the video chroma, one or three pixel planes of |
251 | * adequate dimensions must be returned via the second parameter. Those |
252 | * planes must be aligned on 32-bytes boundaries. |
253 | * |
254 | * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN] |
255 | * \param planes start address of the pixel planes (LibVLC allocates the array |
256 | * of void pointers, this callback must initialize the array) [OUT] |
257 | * \return a private pointer for the display and unlock callbacks to identify |
258 | * the picture buffers |
259 | */ |
260 | typedef void *(*libvlc_video_lock_cb)(void *opaque, void **planes); |
261 | |
262 | /** |
263 | * Callback prototype to unlock a picture buffer. |
264 | * |
265 | * When the video frame decoding is complete, the unlock callback is invoked. |
266 | * This callback might not be needed at all. It is only an indication that the |
267 | * application can now read the pixel values if it needs to. |
268 | * |
269 | * \warning A picture buffer is unlocked after the picture is decoded, |
270 | * but before the picture is displayed. |
271 | * |
272 | * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN] |
273 | * \param picture private pointer returned from the @ref libvlc_video_lock_cb |
274 | * callback [IN] |
275 | * \param planes pixel planes as defined by the @ref libvlc_video_lock_cb |
276 | * callback (this parameter is only for convenience) [IN] |
277 | */ |
278 | typedef void (*libvlc_video_unlock_cb)(void *opaque, void *picture, |
279 | void *const *planes); |
280 | |
281 | /** |
282 | * Callback prototype to display a picture. |
283 | * |
284 | * When the video frame needs to be shown, as determined by the media playback |
285 | * clock, the display callback is invoked. |
286 | * |
287 | * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN] |
288 | * \param picture private pointer returned from the @ref libvlc_video_lock_cb |
289 | * callback [IN] |
290 | */ |
291 | typedef void (*libvlc_video_display_cb)(void *opaque, void *picture); |
292 | |
293 | /** |
294 | * Callback prototype to configure picture buffers format. |
295 | * This callback gets the format of the video as output by the video decoder |
296 | * and the chain of video filters (if any). It can opt to change any parameter |
297 | * as it needs. In that case, LibVLC will attempt to convert the video format |
298 | * (rescaling and chroma conversion) but these operations can be CPU intensive. |
299 | * |
300 | * \param opaque pointer to the private pointer passed to |
301 | * libvlc_video_set_callbacks() [IN/OUT] |
302 | * \param chroma pointer to the 4 bytes video format identifier [IN/OUT] |
303 | * \param width pointer to the pixel width [IN/OUT] |
304 | * \param height pointer to the pixel height [IN/OUT] |
305 | * \param pitches table of scanline pitches in bytes for each pixel plane |
306 | * (the table is allocated by LibVLC) [OUT] |
307 | * \param lines table of scanlines count for each plane [OUT] |
308 | * \return the number of picture buffers allocated, 0 indicates failure |
309 | * |
310 | * \note |
311 | * For each pixels plane, the scanline pitch must be bigger than or equal to |
312 | * the number of bytes per pixel multiplied by the pixel width. |
313 | * Similarly, the number of scanlines must be bigger than of equal to |
314 | * the pixel height. |
315 | * Furthermore, we recommend that pitches and lines be multiple of 32 |
316 | * to not break assumption that might be made by various optimizations |
317 | * in the video decoders, video filters and/or video converters. |
318 | */ |
319 | typedef unsigned (*libvlc_video_format_cb)(void **opaque, char *chroma, |
320 | unsigned *width, unsigned *height, |
321 | unsigned *pitches, |
322 | unsigned *lines); |
323 | |
324 | /** |
325 | * Callback prototype to configure picture buffers format. |
326 | * |
327 | * \param opaque private pointer as passed to libvlc_video_set_callbacks() |
328 | * (and possibly modified by @ref libvlc_video_format_cb) [IN] |
329 | */ |
330 | typedef void (*libvlc_video_cleanup_cb)(void *opaque); |
331 | |
332 | |
333 | /** |
334 | * Set callbacks and private data to render decoded video to a custom area |
335 | * in memory. |
336 | * Use libvlc_video_set_format() or libvlc_video_set_format_callbacks() |
337 | * to configure the decoded format. |
338 | * |
339 | * \param mp the media player |
340 | * \param lock callback to lock video memory (must not be NULL) |
341 | * \param unlock callback to unlock video memory (or NULL if not needed) |
342 | * \param display callback to display video (or NULL if not needed) |
343 | * \param opaque private pointer for the three callbacks (as first parameter) |
344 | * \version LibVLC 1.1.1 or later |
345 | */ |
346 | LIBVLC_API |
347 | void libvlc_video_set_callbacks( libvlc_media_player_t *mp, |
348 | libvlc_video_lock_cb lock, |
349 | libvlc_video_unlock_cb unlock, |
350 | libvlc_video_display_cb display, |
351 | void *opaque ); |
352 | |
353 | /** |
354 | * Set decoded video chroma and dimensions. |
355 | * This only works in combination with libvlc_video_set_callbacks(), |
356 | * and is mutually exclusive with libvlc_video_set_format_callbacks(). |
357 | * |
358 | * \param mp the media player |
359 | * \param chroma a four-characters string identifying the chroma |
360 | * (e.g. "RV32" or "YUYV") |
361 | * \param width pixel width |
362 | * \param height pixel height |
363 | * \param pitch line pitch (in bytes) |
364 | * \version LibVLC 1.1.1 or later |
365 | * \bug All pixel planes are expected to have the same pitch. |
366 | * To use the YCbCr color space with chrominance subsampling, |
367 | * consider using libvlc_video_set_format_callbacks() instead. |
368 | */ |
369 | LIBVLC_API |
370 | void libvlc_video_set_format( libvlc_media_player_t *mp, const char *chroma, |
371 | unsigned width, unsigned height, |
372 | unsigned pitch ); |
373 | |
374 | /** |
375 | * Set decoded video chroma and dimensions. This only works in combination with |
376 | * libvlc_video_set_callbacks(). |
377 | * |
378 | * \param mp the media player |
379 | * \param setup callback to select the video format (cannot be NULL) |
380 | * \param cleanup callback to release any allocated resources (or NULL) |
381 | * \version LibVLC 2.0.0 or later |
382 | */ |
383 | LIBVLC_API |
384 | void libvlc_video_set_format_callbacks( libvlc_media_player_t *mp, |
385 | libvlc_video_format_cb setup, |
386 | libvlc_video_cleanup_cb cleanup ); |
387 | |
388 | /** |
389 | * Set the NSView handler where the media player should render its video output. |
390 | * |
391 | * Use the vout called "macosx". |
392 | * |
393 | * The drawable is an NSObject that follow the VLCOpenGLVideoViewEmbedding |
394 | * protocol: |
395 | * |
396 | * @begincode |
397 | * \@protocol VLCOpenGLVideoViewEmbedding <NSObject> |
398 | * - (void)addVoutSubview:(NSView *)view; |
399 | * - (void)removeVoutSubview:(NSView *)view; |
400 | * \@end |
401 | * @endcode |
402 | * |
403 | * Or it can be an NSView object. |
404 | * |
405 | * If you want to use it along with Qt4 see the QMacCocoaViewContainer. Then |
406 | * the following code should work: |
407 | * @begincode |
408 | * { |
409 | * NSView *video = [[NSView alloc] init]; |
410 | * QMacCocoaViewContainer *container = new QMacCocoaViewContainer(video, parent); |
411 | * libvlc_media_player_set_nsobject(mp, video); |
412 | * [video release]; |
413 | * } |
414 | * @endcode |
415 | * |
416 | * You can find a live example in VLCVideoView in VLCKit.framework. |
417 | * |
418 | * \param p_mi the Media Player |
419 | * \param drawable the drawable that is either an NSView or an object following |
420 | * the VLCOpenGLVideoViewEmbedding protocol. |
421 | */ |
422 | LIBVLC_API void libvlc_media_player_set_nsobject ( libvlc_media_player_t *p_mi, void * drawable ); |
423 | |
424 | /** |
425 | * Get the NSView handler previously set with libvlc_media_player_set_nsobject(). |
426 | * |
427 | * \param p_mi the Media Player |
428 | * \return the NSView handler or 0 if none where set |
429 | */ |
430 | LIBVLC_API void * libvlc_media_player_get_nsobject ( libvlc_media_player_t *p_mi ); |
431 | |
432 | /** |
433 | * Set the agl handler where the media player should render its video output. |
434 | * |
435 | * \param p_mi the Media Player |
436 | * \param drawable the agl handler |
437 | */ |
438 | LIBVLC_API void libvlc_media_player_set_agl ( libvlc_media_player_t *p_mi, uint32_t drawable ); |
439 | |
440 | /** |
441 | * Get the agl handler previously set with libvlc_media_player_set_agl(). |
442 | * |
443 | * \param p_mi the Media Player |
444 | * \return the agl handler or 0 if none where set |
445 | */ |
446 | LIBVLC_API uint32_t libvlc_media_player_get_agl ( libvlc_media_player_t *p_mi ); |
447 | |
448 | /** |
449 | * Set an X Window System drawable where the media player should render its |
450 | * video output. If LibVLC was built without X11 output support, then this has |
451 | * no effects. |
452 | * |
453 | * The specified identifier must correspond to an existing Input/Output class |
454 | * X11 window. Pixmaps are <b>not</b> supported. The caller shall ensure that |
455 | * the X11 server is the same as the one the VLC instance has been configured |
456 | * with. This function must be called before video playback is started; |
457 | * otherwise it will only take effect after playback stop and restart. |
458 | * |
459 | * \param p_mi the Media Player |
460 | * \param drawable the ID of the X window |
461 | */ |
462 | LIBVLC_API void libvlc_media_player_set_xwindow ( libvlc_media_player_t *p_mi, uint32_t drawable ); |
463 | |
464 | /** |
465 | * Get the X Window System window identifier previously set with |
466 | * libvlc_media_player_set_xwindow(). Note that this will return the identifier |
467 | * even if VLC is not currently using it (for instance if it is playing an |
468 | * audio-only input). |
469 | * |
470 | * \param p_mi the Media Player |
471 | * \return an X window ID, or 0 if none where set. |
472 | */ |
473 | LIBVLC_API uint32_t libvlc_media_player_get_xwindow ( libvlc_media_player_t *p_mi ); |
474 | |
475 | /** |
476 | * Set a Win32/Win64 API window handle (HWND) where the media player should |
477 | * render its video output. If LibVLC was built without Win32/Win64 API output |
478 | * support, then this has no effects. |
479 | * |
480 | * \param p_mi the Media Player |
481 | * \param drawable windows handle of the drawable |
482 | */ |
483 | LIBVLC_API void libvlc_media_player_set_hwnd ( libvlc_media_player_t *p_mi, void *drawable ); |
484 | |
485 | /** |
486 | * Get the Windows API window handle (HWND) previously set with |
487 | * libvlc_media_player_set_hwnd(). The handle will be returned even if LibVLC |
488 | * is not currently outputting any video to it. |
489 | * |
490 | * \param p_mi the Media Player |
491 | * \return a window handle or NULL if there are none. |
492 | */ |
493 | LIBVLC_API void *libvlc_media_player_get_hwnd ( libvlc_media_player_t *p_mi ); |
494 | |
495 | /** |
496 | * Callback prototype for audio playback. |
497 | * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN] |
498 | * \param samples pointer to the first audio sample to play back [IN] |
499 | * \param count number of audio samples to play back |
500 | * \param pts expected play time stamp (see libvlc_delay()) |
501 | */ |
502 | typedef void (*libvlc_audio_play_cb)(void *data, const void *samples, |
503 | unsigned count, int64_t pts); |
504 | |
505 | /** |
506 | * Callback prototype for audio pause. |
507 | * \note The pause callback is never called if the audio is already paused. |
508 | * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN] |
509 | * \param pts time stamp of the pause request (should be elapsed already) |
510 | */ |
511 | typedef void (*libvlc_audio_pause_cb)(void *data, int64_t pts); |
512 | |
513 | /** |
514 | * Callback prototype for audio resumption (i.e. restart from pause). |
515 | * \note The resume callback is never called if the audio is not paused. |
516 | * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN] |
517 | * \param pts time stamp of the resumption request (should be elapsed already) |
518 | */ |
519 | typedef void (*libvlc_audio_resume_cb)(void *data, int64_t pts); |
520 | |
521 | /** |
522 | * Callback prototype for audio buffer flush |
523 | * (i.e. discard all pending buffers and stop playback as soon as possible). |
524 | * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN] |
525 | */ |
526 | typedef void (*libvlc_audio_flush_cb)(void *data, int64_t pts); |
527 | |
528 | /** |
529 | * Callback prototype for audio buffer drain |
530 | * (i.e. wait for pending buffers to be played). |
531 | * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN] |
532 | */ |
533 | typedef void (*libvlc_audio_drain_cb)(void *data); |
534 | |
535 | /** |
536 | * Callback prototype for audio volume change. |
537 | * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN] |
538 | * \param volume software volume (1. = nominal, 0. = mute) |
539 | * \param mute muted flag |
540 | */ |
541 | typedef void (*libvlc_audio_set_volume_cb)(void *data, |
542 | float volume, bool mute); |
543 | |
544 | /** |
545 | * Set callbacks and private data for decoded audio. |
546 | * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks() |
547 | * to configure the decoded audio format. |
548 | * |
549 | * \param mp the media player |
550 | * \param play callback to play audio samples (must not be NULL) |
551 | * \param pause callback to pause playback (or NULL to ignore) |
552 | * \param resume callback to resume playback (or NULL to ignore) |
553 | * \param flush callback to flush audio buffers (or NULL to ignore) |
554 | * \param drain callback to drain audio buffers (or NULL to ignore) |
555 | * \param opaque private pointer for the audio callbacks (as first parameter) |
556 | * \version LibVLC 2.0.0 or later |
557 | */ |
558 | LIBVLC_API |
559 | void libvlc_audio_set_callbacks( libvlc_media_player_t *mp, |
560 | libvlc_audio_play_cb play, |
561 | libvlc_audio_pause_cb pause, |
562 | libvlc_audio_resume_cb resume, |
563 | libvlc_audio_flush_cb flush, |
564 | libvlc_audio_drain_cb drain, |
565 | void *opaque ); |
566 | |
567 | /** |
568 | * Set callbacks and private data for decoded audio. |
569 | * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks() |
570 | * to configure the decoded audio format. |
571 | * |
572 | * \param mp the media player |
573 | * \param set_volume callback to apply audio volume, |
574 | * or NULL to apply volume in software |
575 | * \version LibVLC 2.0.0 or later |
576 | */ |
577 | LIBVLC_API |
578 | void libvlc_audio_set_volume_callback( libvlc_media_player_t *mp, |
579 | libvlc_audio_set_volume_cb set_volume ); |
580 | |
581 | /** |
582 | * Callback prototype to setup the audio playback. |
583 | * This is called when the media player needs to create a new audio output. |
584 | * \param opaque pointer to the data pointer passed to |
585 | * libvlc_audio_set_callbacks() [IN/OUT] |
586 | * \param format 4 bytes sample format [IN/OUT] |
587 | * \param rate sample rate [IN/OUT] |
588 | * \param channels channels count [IN/OUT] |
589 | * \return 0 on success, anything else to skip audio playback |
590 | */ |
591 | typedef int (*libvlc_audio_setup_cb)(void **data, char *format, unsigned *rate, |
592 | unsigned *channels); |
593 | |
594 | /** |
595 | * Callback prototype for audio playback cleanup. |
596 | * This is called when the media player no longer needs an audio output. |
597 | * \param opaque data pointer as passed to libvlc_audio_set_callbacks() [IN] |
598 | */ |
599 | typedef void (*libvlc_audio_cleanup_cb)(void *data); |
600 | |
601 | /** |
602 | * Set decoded audio format. This only works in combination with |
603 | * libvlc_audio_set_callbacks(). |
604 | * |
605 | * \param mp the media player |
606 | * \param setup callback to select the audio format (cannot be NULL) |
607 | * \param cleanup callback to release any allocated resources (or NULL) |
608 | * \version LibVLC 2.0.0 or later |
609 | */ |
610 | LIBVLC_API |
611 | void libvlc_audio_set_format_callbacks( libvlc_media_player_t *mp, |
612 | libvlc_audio_setup_cb setup, |
613 | libvlc_audio_cleanup_cb cleanup ); |
614 | |
615 | /** |
616 | * Set decoded audio format. |
617 | * This only works in combination with libvlc_audio_set_callbacks(), |
618 | * and is mutually exclusive with libvlc_audio_set_format_callbacks(). |
619 | * |
620 | * \param mp the media player |
621 | * \param format a four-characters string identifying the sample format |
622 | * (e.g. "S16N" or "FL32") |
623 | * \param rate sample rate (expressed in Hz) |
624 | * \param channels channels count |
625 | * \version LibVLC 2.0.0 or later |
626 | */ |
627 | LIBVLC_API |
628 | void libvlc_audio_set_format( libvlc_media_player_t *mp, const char *format, |
629 | unsigned rate, unsigned channels ); |
630 | |
631 | /** \bug This might go away ... to be replaced by a broader system */ |
632 | |
633 | /** |
634 | * Get the current movie length (in ms). |
635 | * |
636 | * \param p_mi the Media Player |
637 | * \return the movie length (in ms), or -1 if there is no media. |
638 | */ |
639 | LIBVLC_API libvlc_time_t libvlc_media_player_get_length( libvlc_media_player_t *p_mi ); |
640 | |
641 | /** |
642 | * Get the current movie time (in ms). |
643 | * |
644 | * \param p_mi the Media Player |
645 | * \return the movie time (in ms), or -1 if there is no media. |
646 | */ |
647 | LIBVLC_API libvlc_time_t libvlc_media_player_get_time( libvlc_media_player_t *p_mi ); |
648 | |
649 | /** |
650 | * Set the movie time (in ms). This has no effect if no media is being played. |
651 | * Not all formats and protocols support this. |
652 | * |
653 | * \param p_mi the Media Player |
654 | * \param i_time the movie time (in ms). |
655 | */ |
656 | LIBVLC_API void libvlc_media_player_set_time( libvlc_media_player_t *p_mi, libvlc_time_t i_time ); |
657 | |
658 | /** |
659 | * Get movie position as percentage between 0.0 and 1.0. |
660 | * |
661 | * \param p_mi the Media Player |
662 | * \return movie position, or -1. in case of error |
663 | */ |
664 | LIBVLC_API float libvlc_media_player_get_position( libvlc_media_player_t *p_mi ); |
665 | |
666 | /** |
667 | * Set movie position as percentage between 0.0 and 1.0. |
668 | * This has no effect if playback is not enabled. |
669 | * This might not work depending on the underlying input format and protocol. |
670 | * |
671 | * \param p_mi the Media Player |
672 | * \param f_pos the position |
673 | */ |
674 | LIBVLC_API void libvlc_media_player_set_position( libvlc_media_player_t *p_mi, float f_pos ); |
675 | |
676 | /** |
677 | * Set movie chapter (if applicable). |
678 | * |
679 | * \param p_mi the Media Player |
680 | * \param i_chapter chapter number to play |
681 | */ |
682 | LIBVLC_API void libvlc_media_player_set_chapter( libvlc_media_player_t *p_mi, int i_chapter ); |
683 | |
684 | /** |
685 | * Get movie chapter. |
686 | * |
687 | * \param p_mi the Media Player |
688 | * \return chapter number currently playing, or -1 if there is no media. |
689 | */ |
690 | LIBVLC_API int libvlc_media_player_get_chapter( libvlc_media_player_t *p_mi ); |
691 | |
692 | /** |
693 | * Get movie chapter count |
694 | * |
695 | * \param p_mi the Media Player |
696 | * \return number of chapters in movie, or -1. |
697 | */ |
698 | LIBVLC_API int libvlc_media_player_get_chapter_count( libvlc_media_player_t *p_mi ); |
699 | |
700 | /** |
701 | * Is the player able to play |
702 | * |
703 | * \param p_mi the Media Player |
704 | * \return boolean |
705 | * |
706 | * \libvlc_return_bool |
707 | */ |
708 | LIBVLC_API int libvlc_media_player_will_play( libvlc_media_player_t *p_mi ); |
709 | |
710 | /** |
711 | * Get title chapter count |
712 | * |
713 | * \param p_mi the Media Player |
714 | * \param i_title title |
715 | * \return number of chapters in title, or -1 |
716 | */ |
717 | LIBVLC_API int libvlc_media_player_get_chapter_count_for_title( |
718 | libvlc_media_player_t *p_mi, int i_title ); |
719 | |
720 | /** |
721 | * Set movie title |
722 | * |
723 | * \param p_mi the Media Player |
724 | * \param i_title title number to play |
725 | */ |
726 | LIBVLC_API void libvlc_media_player_set_title( libvlc_media_player_t *p_mi, int i_title ); |
727 | |
728 | /** |
729 | * Get movie title |
730 | * |
731 | * \param p_mi the Media Player |
732 | * \return title number currently playing, or -1 |
733 | */ |
734 | LIBVLC_API int libvlc_media_player_get_title( libvlc_media_player_t *p_mi ); |
735 | |
736 | /** |
737 | * Get movie title count |
738 | * |
739 | * \param p_mi the Media Player |
740 | * \return title number count, or -1 |
741 | */ |
742 | LIBVLC_API int libvlc_media_player_get_title_count( libvlc_media_player_t *p_mi ); |
743 | |
744 | /** |
745 | * Set previous chapter (if applicable) |
746 | * |
747 | * \param p_mi the Media Player |
748 | */ |
749 | LIBVLC_API void libvlc_media_player_previous_chapter( libvlc_media_player_t *p_mi ); |
750 | |
751 | /** |
752 | * Set next chapter (if applicable) |
753 | * |
754 | * \param p_mi the Media Player |
755 | */ |
756 | LIBVLC_API void libvlc_media_player_next_chapter( libvlc_media_player_t *p_mi ); |
757 | |
758 | /** |
759 | * Get the requested movie play rate. |
760 | * @warning Depending on the underlying media, the requested rate may be |
761 | * different from the real playback rate. |
762 | * |
763 | * \param p_mi the Media Player |
764 | * \return movie play rate |
765 | */ |
766 | LIBVLC_API float libvlc_media_player_get_rate( libvlc_media_player_t *p_mi ); |
767 | |
768 | /** |
769 | * Set movie play rate |
770 | * |
771 | * \param p_mi the Media Player |
772 | * \param rate movie play rate to set |
773 | * \return -1 if an error was detected, 0 otherwise (but even then, it might |
774 | * not actually work depending on the underlying media protocol) |
775 | */ |
776 | LIBVLC_API int libvlc_media_player_set_rate( libvlc_media_player_t *p_mi, float rate ); |
777 | |
778 | /** |
779 | * Get current movie state |
780 | * |
781 | * \param p_mi the Media Player |
782 | * \return the current state of the media player (playing, paused, ...) \see libvlc_state_t |
783 | */ |
784 | LIBVLC_API libvlc_state_t libvlc_media_player_get_state( libvlc_media_player_t *p_mi ); |
785 | |
786 | /** |
787 | * Get movie fps rate |
788 | * |
789 | * \param p_mi the Media Player |
790 | * \return frames per second (fps) for this playing movie, or 0 if unspecified |
791 | */ |
792 | LIBVLC_API float libvlc_media_player_get_fps( libvlc_media_player_t *p_mi ); |
793 | |
794 | /** end bug */ |
795 | |
796 | /** |
797 | * How many video outputs does this media player have? |
798 | * |
799 | * \param p_mi the media player |
800 | * \return the number of video outputs |
801 | */ |
802 | LIBVLC_API unsigned libvlc_media_player_has_vout( libvlc_media_player_t *p_mi ); |
803 | |
804 | /** |
805 | * Is this media player seekable? |
806 | * |
807 | * \param p_mi the media player |
808 | * \return true if the media player can seek |
809 | * |
810 | * \libvlc_return_bool |
811 | */ |
812 | LIBVLC_API int libvlc_media_player_is_seekable( libvlc_media_player_t *p_mi ); |
813 | |
814 | /** |
815 | * Can this media player be paused? |
816 | * |
817 | * \param p_mi the media player |
818 | * \return true if the media player can pause |
819 | * |
820 | * \libvlc_return_bool |
821 | */ |
822 | LIBVLC_API int libvlc_media_player_can_pause( libvlc_media_player_t *p_mi ); |
823 | |
824 | |
825 | /** |
826 | * Display the next frame (if supported) |
827 | * |
828 | * \param p_mi the media player |
829 | */ |
830 | LIBVLC_API void libvlc_media_player_next_frame( libvlc_media_player_t *p_mi ); |
831 | |
832 | /** |
833 | * Navigate through DVD Menu |
834 | * |
835 | * \param p_mi the Media Player |
836 | * \param navigate the Navigation mode |
837 | * \version libVLC 2.0.0 or later |
838 | */ |
839 | LIBVLC_API void libvlc_media_player_navigate( libvlc_media_player_t* p_mi, |
840 | unsigned navigate ); |
841 | |
842 | /** |
843 | * Set if, and how, the video title will be shown when media is played. |
844 | * |
845 | * \param p_mi the media player |
846 | * \param position position at which to display the title, or libvlc_position_disable to prevent the title from being displayed |
847 | * \param timeout title display timeout in milliseconds (ignored if libvlc_position_disable) |
848 | * \version libVLC 2.1.0 or later |
849 | */ |
850 | LIBVLC_API void libvlc_media_player_set_video_title_display( libvlc_media_player_t *p_mi, libvlc_position_t position, unsigned int timeout ); |
851 | |
852 | /** |
853 | * Release (free) libvlc_track_description_t |
854 | * |
855 | * \param p_track_description the structure to release |
856 | */ |
857 | LIBVLC_API void libvlc_track_description_list_release( libvlc_track_description_t *p_track_description ); |
858 | |
859 | /** |
860 | * \deprecated Use libvlc_track_description_list_release instead |
861 | */ |
862 | LIBVLC_DEPRECATED LIBVLC_API |
863 | void libvlc_track_description_release( libvlc_track_description_t *p_track_description ); |
864 | |
865 | /** \defgroup libvlc_video LibVLC video controls |
866 | * @{ |
867 | */ |
868 | |
869 | /** |
870 | * Toggle fullscreen status on non-embedded video outputs. |
871 | * |
872 | * @warning The same limitations applies to this function |
873 | * as to libvlc_set_fullscreen(). |
874 | * |
875 | * \param p_mi the media player |
876 | */ |
877 | LIBVLC_API void libvlc_toggle_fullscreen( libvlc_media_player_t *p_mi ); |
878 | |
879 | /** |
880 | * Enable or disable fullscreen. |
881 | * |
882 | * @warning With most window managers, only a top-level windows can be in |
883 | * full-screen mode. Hence, this function will not operate properly if |
884 | * libvlc_media_player_set_xwindow() was used to embed the video in a |
885 | * non-top-level window. In that case, the embedding window must be reparented |
886 | * to the root window <b>before</b> fullscreen mode is enabled. You will want |
887 | * to reparent it back to its normal parent when disabling fullscreen. |
888 | * |
889 | * \param p_mi the media player |
890 | * \param b_fullscreen boolean for fullscreen status |
891 | */ |
892 | LIBVLC_API void libvlc_set_fullscreen( libvlc_media_player_t *p_mi, int b_fullscreen ); |
893 | |
894 | /** |
895 | * Get current fullscreen status. |
896 | * |
897 | * \param p_mi the media player |
898 | * \return the fullscreen status (boolean) |
899 | * |
900 | * \libvlc_return_bool |
901 | */ |
902 | LIBVLC_API int libvlc_get_fullscreen( libvlc_media_player_t *p_mi ); |
903 | |
904 | /** |
905 | * Enable or disable key press events handling, according to the LibVLC hotkeys |
906 | * configuration. By default and for historical reasons, keyboard events are |
907 | * handled by the LibVLC video widget. |
908 | * |
909 | * \note On X11, there can be only one subscriber for key press and mouse |
910 | * click events per window. If your application has subscribed to those events |
911 | * for the X window ID of the video widget, then LibVLC will not be able to |
912 | * handle key presses and mouse clicks in any case. |
913 | * |
914 | * \warning This function is only implemented for X11 and Win32 at the moment. |
915 | * |
916 | * \param p_mi the media player |
917 | * \param on true to handle key press events, false to ignore them. |
918 | */ |
919 | LIBVLC_API |
920 | void libvlc_video_set_key_input( libvlc_media_player_t *p_mi, unsigned on ); |
921 | |
922 | /** |
923 | * Enable or disable mouse click events handling. By default, those events are |
924 | * handled. This is needed for DVD menus to work, as well as a few video |
925 | * filters such as "puzzle". |
926 | * |
927 | * \see libvlc_video_set_key_input(). |
928 | * |
929 | * \warning This function is only implemented for X11 and Win32 at the moment. |
930 | * |
931 | * \param p_mi the media player |
932 | * \param on true to handle mouse click events, false to ignore them. |
933 | */ |
934 | LIBVLC_API |
935 | void libvlc_video_set_mouse_input( libvlc_media_player_t *p_mi, unsigned on ); |
936 | |
937 | /** |
938 | * Get the pixel dimensions of a video. |
939 | * |
940 | * \param p_mi media player |
941 | * \param num number of the video (starting from, and most commonly 0) |
942 | * \param px pointer to get the pixel width [OUT] |
943 | * \param py pointer to get the pixel height [OUT] |
944 | * \return 0 on success, -1 if the specified video does not exist |
945 | */ |
946 | LIBVLC_API |
947 | int libvlc_video_get_size( libvlc_media_player_t *p_mi, unsigned num, |
948 | unsigned *px, unsigned *py ); |
949 | |
950 | /** |
951 | * Get current video height. |
952 | * \deprecated Use libvlc_video_get_size() instead. |
953 | * |
954 | * \param p_mi the media player |
955 | * \return the video pixel height or 0 if not applicable |
956 | */ |
957 | LIBVLC_DEPRECATED LIBVLC_API |
958 | int libvlc_video_get_height( libvlc_media_player_t *p_mi ); |
959 | |
960 | /** |
961 | * Get current video width. |
962 | * \deprecated Use libvlc_video_get_size() instead. |
963 | * |
964 | * \param p_mi the media player |
965 | * \return the video pixel width or 0 if not applicable |
966 | */ |
967 | LIBVLC_DEPRECATED LIBVLC_API |
968 | int libvlc_video_get_width( libvlc_media_player_t *p_mi ); |
969 | |
970 | /** |
971 | * Get the mouse pointer coordinates over a video. |
972 | * Coordinates are expressed in terms of the decoded video resolution, |
973 | * <b>not</b> in terms of pixels on the screen/viewport (to get the latter, |
974 | * you can query your windowing system directly). |
975 | * |
976 | * Either of the coordinates may be negative or larger than the corresponding |
977 | * dimension of the video, if the cursor is outside the rendering area. |
978 | * |
979 | * @warning The coordinates may be out-of-date if the pointer is not located |
980 | * on the video rendering area. LibVLC does not track the pointer if it is |
981 | * outside of the video widget. |
982 | * |
983 | * @note LibVLC does not support multiple pointers (it does of course support |
984 | * multiple input devices sharing the same pointer) at the moment. |
985 | * |
986 | * \param p_mi media player |
987 | * \param num number of the video (starting from, and most commonly 0) |
988 | * \param px pointer to get the abscissa [OUT] |
989 | * \param py pointer to get the ordinate [OUT] |
990 | * \return 0 on success, -1 if the specified video does not exist |
991 | */ |
992 | LIBVLC_API |
993 | int libvlc_video_get_cursor( libvlc_media_player_t *p_mi, unsigned num, |
994 | int *px, int *py ); |
995 | |
996 | /** |
997 | * Get the current video scaling factor. |
998 | * See also libvlc_video_set_scale(). |
999 | * |
1000 | * \param p_mi the media player |
1001 | * \return the currently configured zoom factor, or 0. if the video is set |
1002 | * to fit to the output window/drawable automatically. |
1003 | */ |
1004 | LIBVLC_API float libvlc_video_get_scale( libvlc_media_player_t *p_mi ); |
1005 | |
1006 | /** |
1007 | * Set the video scaling factor. That is the ratio of the number of pixels on |
1008 | * screen to the number of pixels in the original decoded video in each |
1009 | * dimension. Zero is a special value; it will adjust the video to the output |
1010 | * window/drawable (in windowed mode) or the entire screen. |
1011 | * |
1012 | * Note that not all video outputs support scaling. |
1013 | * |
1014 | * \param p_mi the media player |
1015 | * \param f_factor the scaling factor, or zero |
1016 | */ |
1017 | LIBVLC_API void libvlc_video_set_scale( libvlc_media_player_t *p_mi, float f_factor ); |
1018 | |
1019 | /** |
1020 | * Get current video aspect ratio. |
1021 | * |
1022 | * \param p_mi the media player |
1023 | * \return the video aspect ratio or NULL if unspecified |
1024 | * (the result must be released with free() or libvlc_free()). |
1025 | */ |
1026 | LIBVLC_API char *libvlc_video_get_aspect_ratio( libvlc_media_player_t *p_mi ); |
1027 | |
1028 | /** |
1029 | * Set new video aspect ratio. |
1030 | * |
1031 | * \param p_mi the media player |
1032 | * \param psz_aspect new video aspect-ratio or NULL to reset to default |
1033 | * \note Invalid aspect ratios are ignored. |
1034 | */ |
1035 | LIBVLC_API void libvlc_video_set_aspect_ratio( libvlc_media_player_t *p_mi, const char *psz_aspect ); |
1036 | |
1037 | /** |
1038 | * Get current video subtitle. |
1039 | * |
1040 | * \param p_mi the media player |
1041 | * \return the video subtitle selected, or -1 if none |
1042 | */ |
1043 | LIBVLC_API int libvlc_video_get_spu( libvlc_media_player_t *p_mi ); |
1044 | |
1045 | /** |
1046 | * Get the number of available video subtitles. |
1047 | * |
1048 | * \param p_mi the media player |
1049 | * \return the number of available video subtitles |
1050 | */ |
1051 | LIBVLC_API int libvlc_video_get_spu_count( libvlc_media_player_t *p_mi ); |
1052 | |
1053 | /** |
1054 | * Get the description of available video subtitles. |
1055 | * |
1056 | * \param p_mi the media player |
1057 | * \return list containing description of available video subtitles |
1058 | */ |
1059 | LIBVLC_API libvlc_track_description_t * |
1060 | libvlc_video_get_spu_description( libvlc_media_player_t *p_mi ); |
1061 | |
1062 | /** |
1063 | * Set new video subtitle. |
1064 | * |
1065 | * \param p_mi the media player |
1066 | * \param i_spu video subtitle track to select (i_id from track description) |
1067 | * \return 0 on success, -1 if out of range |
1068 | */ |
1069 | LIBVLC_API int libvlc_video_set_spu( libvlc_media_player_t *p_mi, int i_spu ); |
1070 | |
1071 | /** |
1072 | * Set new video subtitle file. |
1073 | * |
1074 | * \param p_mi the media player |
1075 | * \param psz_subtitle new video subtitle file |
1076 | * \return the success status (boolean) |
1077 | */ |
1078 | LIBVLC_API int libvlc_video_set_subtitle_file( libvlc_media_player_t *p_mi, const char *psz_subtitle ); |
1079 | |
1080 | /** |
1081 | * Get the current subtitle delay. Positive values means subtitles are being |
1082 | * displayed later, negative values earlier. |
1083 | * |
1084 | * \param p_mi media player |
1085 | * \return time (in microseconds) the display of subtitles is being delayed |
1086 | * \version LibVLC 2.0.0 or later |
1087 | */ |
1088 | LIBVLC_API int64_t libvlc_video_get_spu_delay( libvlc_media_player_t *p_mi ); |
1089 | |
1090 | /** |
1091 | * Set the subtitle delay. This affects the timing of when the subtitle will |
1092 | * be displayed. Positive values result in subtitles being displayed later, |
1093 | * while negative values will result in subtitles being displayed earlier. |
1094 | * |
1095 | * The subtitle delay will be reset to zero each time the media changes. |
1096 | * |
1097 | * \param p_mi media player |
1098 | * \param i_delay time (in microseconds) the display of subtitles should be delayed |
1099 | * \return 0 on success, -1 on error |
1100 | * \version LibVLC 2.0.0 or later |
1101 | */ |
1102 | LIBVLC_API int libvlc_video_set_spu_delay( libvlc_media_player_t *p_mi, int64_t i_delay ); |
1103 | |
1104 | /** |
1105 | * Get the description of available titles. |
1106 | * |
1107 | * \param p_mi the media player |
1108 | * \return list containing description of available titles |
1109 | */ |
1110 | LIBVLC_API libvlc_track_description_t * |
1111 | libvlc_video_get_title_description( libvlc_media_player_t *p_mi ); |
1112 | |
1113 | /** |
1114 | * Get the description of available chapters for specific title. |
1115 | * |
1116 | * \param p_mi the media player |
1117 | * \param i_title selected title |
1118 | * \return list containing description of available chapter for title i_title |
1119 | */ |
1120 | LIBVLC_API libvlc_track_description_t * |
1121 | libvlc_video_get_chapter_description( libvlc_media_player_t *p_mi, int i_title ); |
1122 | |
1123 | /** |
1124 | * Get current crop filter geometry. |
1125 | * |
1126 | * \param p_mi the media player |
1127 | * \return the crop filter geometry or NULL if unset |
1128 | */ |
1129 | LIBVLC_API char *libvlc_video_get_crop_geometry( libvlc_media_player_t *p_mi ); |
1130 | |
1131 | /** |
1132 | * Set new crop filter geometry. |
1133 | * |
1134 | * \param p_mi the media player |
1135 | * \param psz_geometry new crop filter geometry (NULL to unset) |
1136 | */ |
1137 | LIBVLC_API |
1138 | void libvlc_video_set_crop_geometry( libvlc_media_player_t *p_mi, const char *psz_geometry ); |
1139 | |
1140 | /** |
1141 | * Get current teletext page requested. |
1142 | * |
1143 | * \param p_mi the media player |
1144 | * \return the current teletext page requested. |
1145 | */ |
1146 | LIBVLC_API int libvlc_video_get_teletext( libvlc_media_player_t *p_mi ); |
1147 | |
1148 | /** |
1149 | * Set new teletext page to retrieve. |
1150 | * |
1151 | * \param p_mi the media player |
1152 | * \param i_page teletex page number requested |
1153 | */ |
1154 | LIBVLC_API void libvlc_video_set_teletext( libvlc_media_player_t *p_mi, int i_page ); |
1155 | |
1156 | /** |
1157 | * Toggle teletext transparent status on video output. |
1158 | * |
1159 | * \param p_mi the media player |
1160 | */ |
1161 | LIBVLC_API void libvlc_toggle_teletext( libvlc_media_player_t *p_mi ); |
1162 | |
1163 | /** |
1164 | * Get number of available video tracks. |
1165 | * |
1166 | * \param p_mi media player |
1167 | * \return the number of available video tracks (int) |
1168 | */ |
1169 | LIBVLC_API int libvlc_video_get_track_count( libvlc_media_player_t *p_mi ); |
1170 | |
1171 | /** |
1172 | * Get the description of available video tracks. |
1173 | * |
1174 | * \param p_mi media player |
1175 | * \return list with description of available video tracks, or NULL on error |
1176 | */ |
1177 | LIBVLC_API libvlc_track_description_t * |
1178 | libvlc_video_get_track_description( libvlc_media_player_t *p_mi ); |
1179 | |
1180 | /** |
1181 | * Get current video track. |
1182 | * |
1183 | * \param p_mi media player |
1184 | * \return the video track ID (int) or -1 if no active input |
1185 | */ |
1186 | LIBVLC_API int libvlc_video_get_track( libvlc_media_player_t *p_mi ); |
1187 | |
1188 | /** |
1189 | * Set video track. |
1190 | * |
1191 | * \param p_mi media player |
1192 | * \param i_track the track ID (i_id field from track description) |
1193 | * \return 0 on success, -1 if out of range |
1194 | */ |
1195 | LIBVLC_API |
1196 | int libvlc_video_set_track( libvlc_media_player_t *p_mi, int i_track ); |
1197 | |
1198 | /** |
1199 | * Take a snapshot of the current video window. |
1200 | * |
1201 | * If i_width AND i_height is 0, original size is used. |
1202 | * If i_width XOR i_height is 0, original aspect-ratio is preserved. |
1203 | * |
1204 | * \param p_mi media player instance |
1205 | * \param num number of video output (typically 0 for the first/only one) |
1206 | * \param psz_filepath the path where to save the screenshot to |
1207 | * \param i_width the snapshot's width |
1208 | * \param i_height the snapshot's height |
1209 | * \return 0 on success, -1 if the video was not found |
1210 | */ |
1211 | LIBVLC_API |
1212 | int libvlc_video_take_snapshot( libvlc_media_player_t *p_mi, unsigned num, |
1213 | const char *psz_filepath, unsigned int i_width, |
1214 | unsigned int i_height ); |
1215 | |
1216 | /** |
1217 | * Enable or disable deinterlace filter |
1218 | * |
1219 | * \param p_mi libvlc media player |
1220 | * \param psz_mode type of deinterlace filter, NULL to disable |
1221 | */ |
1222 | LIBVLC_API void libvlc_video_set_deinterlace( libvlc_media_player_t *p_mi, |
1223 | const char *psz_mode ); |
1224 | |
1225 | /** |
1226 | * Get an integer marquee option value |
1227 | * |
1228 | * \param p_mi libvlc media player |
1229 | * \param option marq option to get \see libvlc_video_marquee_int_option_t |
1230 | */ |
1231 | LIBVLC_API int libvlc_video_get_marquee_int( libvlc_media_player_t *p_mi, |
1232 | unsigned option ); |
1233 | |
1234 | /** |
1235 | * Get a string marquee option value |
1236 | * |
1237 | * \param p_mi libvlc media player |
1238 | * \param option marq option to get \see libvlc_video_marquee_string_option_t |
1239 | */ |
1240 | LIBVLC_API char *libvlc_video_get_marquee_string( libvlc_media_player_t *p_mi, |
1241 | unsigned option ); |
1242 | |
1243 | /** |
1244 | * Enable, disable or set an integer marquee option |
1245 | * |
1246 | * Setting libvlc_marquee_Enable has the side effect of enabling (arg !0) |
1247 | * or disabling (arg 0) the marq filter. |
1248 | * |
1249 | * \param p_mi libvlc media player |
1250 | * \param option marq option to set \see libvlc_video_marquee_int_option_t |
1251 | * \param i_val marq option value |
1252 | */ |
1253 | LIBVLC_API void libvlc_video_set_marquee_int( libvlc_media_player_t *p_mi, |
1254 | unsigned option, int i_val ); |
1255 | |
1256 | /** |
1257 | * Set a marquee string option |
1258 | * |
1259 | * \param p_mi libvlc media player |
1260 | * \param option marq option to set \see libvlc_video_marquee_string_option_t |
1261 | * \param psz_text marq option value |
1262 | */ |
1263 | LIBVLC_API void libvlc_video_set_marquee_string( libvlc_media_player_t *p_mi, |
1264 | unsigned option, const char *psz_text ); |
1265 | |
1266 | /** option values for libvlc_video_{get,set}_logo_{int,string} */ |
1267 | enum libvlc_video_logo_option_t { |
1268 | libvlc_logo_enable, |
1269 | libvlc_logo_file, /**< string argument, "file,d,t;file,d,t;..." */ |
1270 | libvlc_logo_x, |
1271 | libvlc_logo_y, |
1272 | libvlc_logo_delay, |
1273 | libvlc_logo_repeat, |
1274 | libvlc_logo_opacity, |
1275 | libvlc_logo_position |
1276 | }; |
1277 | |
1278 | /** |
1279 | * Get integer logo option. |
1280 | * |
1281 | * \param p_mi libvlc media player instance |
1282 | * \param option logo option to get, values of libvlc_video_logo_option_t |
1283 | */ |
1284 | LIBVLC_API int libvlc_video_get_logo_int( libvlc_media_player_t *p_mi, |
1285 | unsigned option ); |
1286 | |
1287 | /** |
1288 | * Set logo option as integer. Options that take a different type value |
1289 | * are ignored. |
1290 | * Passing libvlc_logo_enable as option value has the side effect of |
1291 | * starting (arg !0) or stopping (arg 0) the logo filter. |
1292 | * |
1293 | * \param p_mi libvlc media player instance |
1294 | * \param option logo option to set, values of libvlc_video_logo_option_t |
1295 | * \param value logo option value |
1296 | */ |
1297 | LIBVLC_API void libvlc_video_set_logo_int( libvlc_media_player_t *p_mi, |
1298 | unsigned option, int value ); |
1299 | |
1300 | /** |
1301 | * Set logo option as string. Options that take a different type value |
1302 | * are ignored. |
1303 | * |
1304 | * \param p_mi libvlc media player instance |
1305 | * \param option logo option to set, values of libvlc_video_logo_option_t |
1306 | * \param psz_value logo option value |
1307 | */ |
1308 | LIBVLC_API void libvlc_video_set_logo_string( libvlc_media_player_t *p_mi, |
1309 | unsigned option, const char *psz_value ); |
1310 | |
1311 | |
1312 | /** option values for libvlc_video_{get,set}_adjust_{int,float,bool} */ |
1313 | enum libvlc_video_adjust_option_t { |
1314 | libvlc_adjust_Enable = 0, |
1315 | libvlc_adjust_Contrast, |
1316 | libvlc_adjust_Brightness, |
1317 | libvlc_adjust_Hue, |
1318 | libvlc_adjust_Saturation, |
1319 | libvlc_adjust_Gamma |
1320 | }; |
1321 | |
1322 | /** |
1323 | * Get integer adjust option. |
1324 | * |
1325 | * \param p_mi libvlc media player instance |
1326 | * \param option adjust option to get, values of libvlc_video_adjust_option_t |
1327 | * \version LibVLC 1.1.1 and later. |
1328 | */ |
1329 | LIBVLC_API int libvlc_video_get_adjust_int( libvlc_media_player_t *p_mi, |
1330 | unsigned option ); |
1331 | |
1332 | /** |
1333 | * Set adjust option as integer. Options that take a different type value |
1334 | * are ignored. |
1335 | * Passing libvlc_adjust_enable as option value has the side effect of |
1336 | * starting (arg !0) or stopping (arg 0) the adjust filter. |
1337 | * |
1338 | * \param p_mi libvlc media player instance |
1339 | * \param option adust option to set, values of libvlc_video_adjust_option_t |
1340 | * \param value adjust option value |
1341 | * \version LibVLC 1.1.1 and later. |
1342 | */ |
1343 | LIBVLC_API void libvlc_video_set_adjust_int( libvlc_media_player_t *p_mi, |
1344 | unsigned option, int value ); |
1345 | |
1346 | /** |
1347 | * Get float adjust option. |
1348 | * |
1349 | * \param p_mi libvlc media player instance |
1350 | * \param option adjust option to get, values of libvlc_video_adjust_option_t |
1351 | * \version LibVLC 1.1.1 and later. |
1352 | */ |
1353 | LIBVLC_API float libvlc_video_get_adjust_float( libvlc_media_player_t *p_mi, |
1354 | unsigned option ); |
1355 | |
1356 | /** |
1357 | * Set adjust option as float. Options that take a different type value |
1358 | * are ignored. |
1359 | * |
1360 | * \param p_mi libvlc media player instance |
1361 | * \param option adust option to set, values of libvlc_video_adjust_option_t |
1362 | * \param value adjust option value |
1363 | * \version LibVLC 1.1.1 and later. |
1364 | */ |
1365 | LIBVLC_API void libvlc_video_set_adjust_float( libvlc_media_player_t *p_mi, |
1366 | unsigned option, float value ); |
1367 | |
1368 | /** @} video */ |
1369 | |
1370 | /** \defgroup libvlc_audio LibVLC audio controls |
1371 | * @{ |
1372 | */ |
1373 | |
1374 | /** |
1375 | * Audio device types |
1376 | */ |
1377 | typedef enum libvlc_audio_output_device_types_t { |
1378 | libvlc_AudioOutputDevice_Error = -1, |
1379 | libvlc_AudioOutputDevice_Mono = 1, |
1380 | libvlc_AudioOutputDevice_Stereo = 2, |
1381 | libvlc_AudioOutputDevice_2F2R = 4, |
1382 | libvlc_AudioOutputDevice_3F2R = 5, |
1383 | libvlc_AudioOutputDevice_5_1 = 6, |
1384 | libvlc_AudioOutputDevice_6_1 = 7, |
1385 | libvlc_AudioOutputDevice_7_1 = 8, |
1386 | libvlc_AudioOutputDevice_SPDIF = 10 |
1387 | } libvlc_audio_output_device_types_t; |
1388 | |
1389 | /** |
1390 | * Audio channels |
1391 | */ |
1392 | typedef enum libvlc_audio_output_channel_t { |
1393 | libvlc_AudioChannel_Error = -1, |
1394 | libvlc_AudioChannel_Stereo = 1, |
1395 | libvlc_AudioChannel_RStereo = 2, |
1396 | libvlc_AudioChannel_Left = 3, |
1397 | libvlc_AudioChannel_Right = 4, |
1398 | libvlc_AudioChannel_Dolbys = 5 |
1399 | } libvlc_audio_output_channel_t; |
1400 | |
1401 | |
1402 | /** |
1403 | * Gets the list of available audio outputs |
1404 | * |
1405 | * \param p_instance libvlc instance |
1406 | * \return list of available audio outputs. It must be freed it with |
1407 | * \see libvlc_audio_output_list_release \see libvlc_audio_output_t . |
1408 | * In case of error, NULL is returned. |
1409 | */ |
1410 | LIBVLC_API libvlc_audio_output_t * |
1411 | libvlc_audio_output_list_get( libvlc_instance_t *p_instance ); |
1412 | |
1413 | /** |
1414 | * Frees the list of available audio outputs |
1415 | * |
1416 | * \param p_list list with audio outputs for release |
1417 | */ |
1418 | LIBVLC_API |
1419 | void libvlc_audio_output_list_release( libvlc_audio_output_t *p_list ); |
1420 | |
1421 | /** |
1422 | * Sets the audio output. |
1423 | * \note Any change will take be effect only after playback is stopped and |
1424 | * restarted. Audio output cannot be changed while playing. |
1425 | * |
1426 | * \param p_mi media player |
1427 | * \param psz_name name of audio output, |
1428 | * use psz_name of \see libvlc_audio_output_t |
1429 | * \return 0 if function succeded, -1 on error |
1430 | */ |
1431 | LIBVLC_API int libvlc_audio_output_set( libvlc_media_player_t *p_mi, |
1432 | const char *psz_name ); |
1433 | |
1434 | /** |
1435 | * Backward compatibility stub. Do not use in new code. |
1436 | * Use libvlc_audio_output_device_list_get() instead. |
1437 | * \return always 0. |
1438 | */ |
1439 | LIBVLC_DEPRECATED LIBVLC_API |
1440 | int libvlc_audio_output_device_count( libvlc_instance_t *, const char * ); |
1441 | |
1442 | /** |
1443 | * Backward compatibility stub. Do not use in new code. |
1444 | * Use libvlc_audio_output_device_list_get() instead. |
1445 | * \return always NULL. |
1446 | */ |
1447 | LIBVLC_DEPRECATED LIBVLC_API |
1448 | char *libvlc_audio_output_device_longname( libvlc_instance_t *, const char *, |
1449 | int ); |
1450 | |
1451 | /** |
1452 | * Backward compatibility stub. Do not use in new code. |
1453 | * Use libvlc_audio_output_device_list_get() instead. |
1454 | * \return always NULL. |
1455 | */ |
1456 | LIBVLC_DEPRECATED LIBVLC_API |
1457 | char *libvlc_audio_output_device_id( libvlc_instance_t *, const char *, int ); |
1458 | |
1459 | /** |
1460 | * Gets a list of audio output devices for a given audio output. |
1461 | * \see libvlc_audio_output_device_set(). |
1462 | * |
1463 | * \note Not all audio outputs support this. In particular, an empty (NULL) |
1464 | * list of devices does <b>not</b> imply that the specified audio output does |
1465 | * not work. |
1466 | * |
1467 | * \note The list might not be exhaustive. |
1468 | * |
1469 | * \warning Some audio output devices in the list might not actually work in |
1470 | * some circumstances. By default, it is recommended to not specify any |
1471 | * explicit audio device. |
1472 | * |
1473 | * \param p_instance libvlc instance |
1474 | * \param psz_aout audio output name |
1475 | * (as returned by libvlc_audio_output_list_get()) |
1476 | * \return A NULL-terminated linked list of potential audio output devices. |
1477 | * It must be freed it with libvlc_audio_output_device_list_release() |
1478 | * \version LibVLC 2.1.0 or later. |
1479 | */ |
1480 | LIBVLC_API libvlc_audio_output_device_t * |
1481 | libvlc_audio_output_device_list_get( libvlc_instance_t *p_instance, |
1482 | const char *aout ); |
1483 | |
1484 | /** |
1485 | * Frees a list of available audio output devices. |
1486 | * |
1487 | * \param p_list list with audio outputs for release |
1488 | * \version LibVLC 2.1.0 or later. |
1489 | */ |
1490 | LIBVLC_API void libvlc_audio_output_device_list_release( |
1491 | libvlc_audio_output_device_t *p_list ); |
1492 | |
1493 | /** |
1494 | * Configures an explicit audio output device for a given audio output plugin. |
1495 | * A list of possible devices can be obtained with |
1496 | * libvlc_audio_output_device_list_get(). |
1497 | * |
1498 | * \note This function does not select the specified audio output plugin. |
1499 | * libvlc_audio_output_set() is used for that purpose. |
1500 | * |
1501 | * \warning The syntax for the device parameter depends on the audio output. |
1502 | * This is not portable. Only use this function if you know what you are doing. |
1503 | * Some audio outputs do not support this function (e.g. PulseAudio, WASAPI). |
1504 | * Some audio outputs require further parameters (e.g. ALSA: channels map). |
1505 | * |
1506 | * \param p_mi media player |
1507 | * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t |
1508 | * \param psz_device_id device |
1509 | * \return Nothing. Errors are ignored. |
1510 | */ |
1511 | LIBVLC_API void libvlc_audio_output_device_set( libvlc_media_player_t *p_mi, |
1512 | const char *psz_audio_output, |
1513 | const char *psz_device_id ); |
1514 | |
1515 | /** |
1516 | * Stub for backward compatibility. |
1517 | * \return always -1. |
1518 | */ |
1519 | LIBVLC_DEPRECATED |
1520 | LIBVLC_API int libvlc_audio_output_get_device_type( libvlc_media_player_t *p_mi ); |
1521 | |
1522 | /** |
1523 | * Stub for backward compatibility. |
1524 | */ |
1525 | LIBVLC_DEPRECATED |
1526 | LIBVLC_API void libvlc_audio_output_set_device_type( libvlc_media_player_t *, |
1527 | int ); |
1528 | |
1529 | |
1530 | /** |
1531 | * Toggle mute status. |
1532 | * |
1533 | * \param p_mi media player |
1534 | * \warning Toggling mute atomically is not always possible: On some platforms, |
1535 | * other processes can mute the VLC audio playback stream asynchronously. Thus, |
1536 | * there is a small race condition where toggling will not work. |
1537 | * See also the limitations of libvlc_audio_set_mute(). |
1538 | */ |
1539 | LIBVLC_API void libvlc_audio_toggle_mute( libvlc_media_player_t *p_mi ); |
1540 | |
1541 | /** |
1542 | * Get current mute status. |
1543 | * |
1544 | * \param p_mi media player |
1545 | * \return the mute status (boolean) if defined, -1 if undefined/unapplicable |
1546 | */ |
1547 | LIBVLC_API int libvlc_audio_get_mute( libvlc_media_player_t *p_mi ); |
1548 | |
1549 | /** |
1550 | * Set mute status. |
1551 | * |
1552 | * \param p_mi media player |
1553 | * \param status If status is true then mute, otherwise unmute |
1554 | * \warning This function does not always work. If there are no active audio |
1555 | * playback stream, the mute status might not be available. If digital |
1556 | * pass-through (S/PDIF, HDMI...) is in use, muting may be unapplicable. Also |
1557 | * some audio output plugins do not support muting at all. |
1558 | * \note To force silent playback, disable all audio tracks. This is more |
1559 | * efficient and reliable than mute. |
1560 | */ |
1561 | LIBVLC_API void libvlc_audio_set_mute( libvlc_media_player_t *p_mi, int status ); |
1562 | |
1563 | /** |
1564 | * Get current software audio volume. |
1565 | * |
1566 | * \param p_mi media player |
1567 | * \return the software volume in percents |
1568 | * (0 = mute, 100 = nominal / 0dB) |
1569 | */ |
1570 | LIBVLC_API int libvlc_audio_get_volume( libvlc_media_player_t *p_mi ); |
1571 | |
1572 | /** |
1573 | * Set current software audio volume. |
1574 | * |
1575 | * \param p_mi media player |
1576 | * \param i_volume the volume in percents (0 = mute, 100 = 0dB) |
1577 | * \return 0 if the volume was set, -1 if it was out of range |
1578 | */ |
1579 | LIBVLC_API int libvlc_audio_set_volume( libvlc_media_player_t *p_mi, int i_volume ); |
1580 | |
1581 | /** |
1582 | * Get number of available audio tracks. |
1583 | * |
1584 | * \param p_mi media player |
1585 | * \return the number of available audio tracks (int), or -1 if unavailable |
1586 | */ |
1587 | LIBVLC_API int libvlc_audio_get_track_count( libvlc_media_player_t *p_mi ); |
1588 | |
1589 | /** |
1590 | * Get the description of available audio tracks. |
1591 | * |
1592 | * \param p_mi media player |
1593 | * \return list with description of available audio tracks, or NULL |
1594 | */ |
1595 | LIBVLC_API libvlc_track_description_t * |
1596 | libvlc_audio_get_track_description( libvlc_media_player_t *p_mi ); |
1597 | |
1598 | /** |
1599 | * Get current audio track. |
1600 | * |
1601 | * \param p_mi media player |
1602 | * \return the audio track ID or -1 if no active input. |
1603 | */ |
1604 | LIBVLC_API int libvlc_audio_get_track( libvlc_media_player_t *p_mi ); |
1605 | |
1606 | /** |
1607 | * Set current audio track. |
1608 | * |
1609 | * \param p_mi media player |
1610 | * \param i_track the track ID (i_id field from track description) |
1611 | * \return 0 on success, -1 on error |
1612 | */ |
1613 | LIBVLC_API int libvlc_audio_set_track( libvlc_media_player_t *p_mi, int i_track ); |
1614 | |
1615 | /** |
1616 | * Get current audio channel. |
1617 | * |
1618 | * \param p_mi media player |
1619 | * \return the audio channel \see libvlc_audio_output_channel_t |
1620 | */ |
1621 | LIBVLC_API int libvlc_audio_get_channel( libvlc_media_player_t *p_mi ); |
1622 | |
1623 | /** |
1624 | * Set current audio channel. |
1625 | * |
1626 | * \param p_mi media player |
1627 | * \param channel the audio channel, \see libvlc_audio_output_channel_t |
1628 | * \return 0 on success, -1 on error |
1629 | */ |
1630 | LIBVLC_API int libvlc_audio_set_channel( libvlc_media_player_t *p_mi, int channel ); |
1631 | |
1632 | /** |
1633 | * Get current audio delay. |
1634 | * |
1635 | * \param p_mi media player |
1636 | * \return the audio delay (microseconds) |
1637 | * \version LibVLC 1.1.1 or later |
1638 | */ |
1639 | LIBVLC_API int64_t libvlc_audio_get_delay( libvlc_media_player_t *p_mi ); |
1640 | |
1641 | /** |
1642 | * Set current audio delay. The audio delay will be reset to zero each time the media changes. |
1643 | * |
1644 | * \param p_mi media player |
1645 | * \param i_delay the audio delay (microseconds) |
1646 | * \return 0 on success, -1 on error |
1647 | * \version LibVLC 1.1.1 or later |
1648 | */ |
1649 | LIBVLC_API int libvlc_audio_set_delay( libvlc_media_player_t *p_mi, int64_t i_delay ); |
1650 | |
1651 | /** @} audio */ |
1652 | |
1653 | /** @} media_player */ |
1654 | |
1655 | # ifdef __cplusplus |
1656 | } |
1657 | # endif |
1658 | |
1659 | #endif /* VLC_LIBVLC_MEDIA_PLAYER_H */ |
1660 | |