1 /*****************************************************************************
2 * libvlc_media_player.h: libvlc_media_player external API
3 *****************************************************************************
4 * Copyright (C) 1998-2010 the VideoLAN team
7 * Authors: Clément Stenac <zorglub@videolan.org>
8 * Jean-Paul Saman <jpsaman@videolan.org>
9 * Pierre d'Herbemont <pdherbemont@videolan.org>
11 * This program is free software; you can redistribute it and/or modify
12 * it under the terms of the GNU General Public License as published by
13 * the Free Software Foundation; either version 2 of the License, or
14 * (at your option) any later version.
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 General Public License for more details.
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, write to the Free Software
23 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
24 *****************************************************************************/
28 * This file defines libvlc_media_player external API
31 #ifndef VLC_LIBVLC_MEDIA_PLAYER_H
32 #define VLC_LIBVLC_MEDIA_PLAYER_H 1
40 /*****************************************************************************
42 *****************************************************************************/
43 /** \defgroup libvlc_media_player LibVLC media player
45 * A LibVLC media player plays one media (usually in a custom drawable).
49 typedef struct libvlc_media_player_t libvlc_media_player_t;
52 * Description for video, audio tracks and subtitles. It contains
53 * id, name (description string) and pointer to next record.
55 typedef struct libvlc_track_description_t
59 struct libvlc_track_description_t *p_next;
61 } libvlc_track_description_t;
64 * Description for audio output. It contains
65 * name, description and pointer to next record.
67 typedef struct libvlc_audio_output_t
70 char *psz_description;
71 struct libvlc_audio_output_t *p_next;
73 } libvlc_audio_output_t;
76 * Rectangle type for video geometry
78 typedef struct libvlc_rectangle_t
85 * Marq options definition
87 typedef enum libvlc_video_marquee_option_t {
88 libvlc_marquee_Enable = 0,
89 libvlc_marquee_Text, /** string argument */
91 libvlc_marquee_Opacity,
92 libvlc_marquee_Position,
93 libvlc_marquee_Refresh,
95 libvlc_marquee_Timeout,
98 } libvlc_video_marquee_option_t;
103 typedef enum libvlc_navigate_mode_t
105 libvlc_navigate_activate = 0,
107 libvlc_navigate_down,
108 libvlc_navigate_left,
109 libvlc_navigate_right
110 } libvlc_navigate_mode_t;
113 * Create an empty Media Player object
115 * \param p_libvlc_instance the libvlc instance in which the Media Player
117 * \return a new media player object, or NULL on error.
119 LIBVLC_API libvlc_media_player_t * libvlc_media_player_new( libvlc_instance_t *p_libvlc_instance );
122 * Create a Media Player object from a Media
124 * \param p_md the media. Afterwards the p_md can be safely
126 * \return a new media player object, or NULL on error.
128 LIBVLC_API libvlc_media_player_t * libvlc_media_player_new_from_media( libvlc_media_t *p_md );
131 * Release a media_player after use
132 * Decrement the reference count of a media player object. If the
133 * reference count is 0, then libvlc_media_player_release() will
134 * release the media player object. If the media player object
135 * has been released, then it should not be used again.
137 * \param p_mi the Media Player to free
139 LIBVLC_API void libvlc_media_player_release( libvlc_media_player_t *p_mi );
142 * Retain a reference to a media player object. Use
143 * libvlc_media_player_release() to decrement reference count.
145 * \param p_mi media player object
147 LIBVLC_API void libvlc_media_player_retain( libvlc_media_player_t *p_mi );
150 * Set the media that will be used by the media_player. If any,
151 * previous md will be released.
153 * \param p_mi the Media Player
154 * \param p_md the Media. Afterwards the p_md can be safely
157 LIBVLC_API void libvlc_media_player_set_media( libvlc_media_player_t *p_mi,
158 libvlc_media_t *p_md );
161 * Get the media used by the media_player.
163 * \param p_mi the Media Player
164 * \return the media associated with p_mi, or NULL if no
165 * media is associated
167 LIBVLC_API libvlc_media_t * libvlc_media_player_get_media( libvlc_media_player_t *p_mi );
170 * Get the Event Manager from which the media player send event.
172 * \param p_mi the Media Player
173 * \return the event manager associated with p_mi
175 LIBVLC_API libvlc_event_manager_t * libvlc_media_player_event_manager ( libvlc_media_player_t *p_mi );
180 * \param p_mi the Media Player
181 * \return 1 if the media player is playing, 0 otherwise
183 * \libvlc_return_bool
185 LIBVLC_API int libvlc_media_player_is_playing ( libvlc_media_player_t *p_mi );
190 * \param p_mi the Media Player
191 * \return 0 if playback started (and was already started), or -1 on error.
193 LIBVLC_API int libvlc_media_player_play ( libvlc_media_player_t *p_mi );
196 * Pause or resume (no effect if there is no media)
198 * \param mp the Media Player
199 * \param do_pause play/resume if zero, pause if non-zero
200 * \version LibVLC 1.1.1 or later
202 LIBVLC_API void libvlc_media_player_set_pause ( libvlc_media_player_t *mp,
206 * Toggle pause (no effect if there is no media)
208 * \param p_mi the Media Player
210 LIBVLC_API void libvlc_media_player_pause ( libvlc_media_player_t *p_mi );
213 * Stop (no effect if there is no media)
215 * \param p_mi the Media Player
217 LIBVLC_API void libvlc_media_player_stop ( libvlc_media_player_t *p_mi );
220 * Callback prototype to allocate and lock a picture buffer.
222 * Whenever a new video frame needs to be decoded, the lock callback is
223 * invoked. Depending on the video chroma, one or three pixel planes of
224 * adequate dimensions must be returned via the second parameter. Those
225 * planes must be aligned on 32-bytes boundaries.
227 * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]
228 * \param planes start address of the pixel planes (LibVLC allocates the array
229 * of void pointers, this callback must initialize the array) [OUT]
230 * \return a private pointer for the display and unlock callbacks to identify
231 * the picture buffers
233 typedef void *(*libvlc_video_lock_cb)(void *opaque, void **planes);
236 * Callback prototype to unlock a picture buffer.
238 * When the video frame decoding is complete, the unlock callback is invoked.
239 * This callback might not be needed at all. It is only an indication that the
240 * application can now read the pixel values if it needs to.
242 * \warning A picture buffer is unlocked after the picture is decoded,
243 * but before the picture is displayed.
245 * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]
246 * \param picture private pointer returned from the @ref libvlc_video_lock_cb
248 * \param planes pixel planes as defined by the @ref libvlc_video_lock_cb
249 * callback (this parameter is only for convenience) [IN]
251 typedef void (*libvlc_video_unlock_cb)(void *opaque, void *picture,
252 void *const *planes);
255 * Callback prototype to display a picture.
257 * When the video frame needs to be shown, as determined by the media playback
258 * clock, the display callback is invoked.
260 * \param opaque private pointer as passed to libvlc_video_set_callbacks() [IN]
261 * \param picture private pointer returned from the @ref libvlc_video_lock_cb
264 typedef void (*libvlc_video_display_cb)(void *opaque, void *picture);
267 * Callback prototype to configure picture buffers format.
268 * This callback gets the format of the video as output by the video decoder
269 * and the chain of video filters (if any). It can opt to change any parameter
270 * as it needs. In that case, LibVLC will attempt to convert the video format
271 * (rescaling and chroma conversion) but these operations can be CPU intensive.
273 * \param opaque pointer to the private pointer passed to
274 * libvlc_video_set_callbacks() [IN/OUT]
275 * \param chroma pointer to the 4 bytes video format identifier [IN/OUT]
276 * \param width pointer to the pixel width [IN/OUT]
277 * \param height pointer to the pixel height [IN/OUT]
278 * \param pitches table of scanline pitches in bytes for each pixel plane
279 * (the table is allocated by LibVLC) [OUT]
280 * \param lines table of scanlines count for each plane [OUT]
281 * \return the number of picture buffers allocated, 0 indicates failure
284 * For each pixels plane, the scanline pitch must be bigger than or equal to
285 * the number of bytes per pixel multiplied by the pixel width.
286 * Similarly, the number of scanlines must be bigger than of equal to
288 * Furthermore, we recommend that pitches and lines be multiple of 32
289 * to not break assumption that might be made by various optimizations
290 * in the video decoders, video filters and/or video converters.
292 typedef unsigned (*libvlc_video_format_cb)(void **opaque, char *chroma,
293 unsigned *width, unsigned *height,
298 * Callback prototype to configure picture buffers format.
300 * \param opaque private pointer as passed to libvlc_video_set_callbacks()
301 * (and possibly modified by @ref libvlc_video_format_cb) [IN]
303 typedef void (*libvlc_video_cleanup_cb)(void *opaque);
307 * Set callbacks and private data to render decoded video to a custom area
309 * Use libvlc_video_set_format() or libvlc_video_set_format_callbacks()
310 * to configure the decoded format.
312 * \param mp the media player
313 * \param lock callback to lock video memory (must not be NULL)
314 * \param unlock callback to unlock video memory (or NULL if not needed)
315 * \param display callback to display video (or NULL if not needed)
316 * \param opaque private pointer for the three callbacks (as first parameter)
317 * \version LibVLC 1.1.1 or later
320 void libvlc_video_set_callbacks( libvlc_media_player_t *mp,
321 libvlc_video_lock_cb lock,
322 libvlc_video_unlock_cb unlock,
323 libvlc_video_display_cb display,
327 * Set decoded video chroma and dimensions.
328 * This only works in combination with libvlc_video_set_callbacks(),
329 * and is mutually exclusive with libvlc_video_set_format_callbacks().
331 * \param mp the media player
332 * \param chroma a four-characters string identifying the chroma
333 * (e.g. "RV32" or "YUYV")
334 * \param width pixel width
335 * \param height pixel height
336 * \param pitch line pitch (in bytes)
337 * \version LibVLC 1.1.1 or later
338 * \bug All pixel planes are expected to have the same pitch.
339 * To use the YCbCr color space with chrominance subsampling,
340 * consider using libvlc_video_set_format_callbacks() instead.
343 void libvlc_video_set_format( libvlc_media_player_t *mp, const char *chroma,
344 unsigned width, unsigned height,
348 * Set decoded video chroma and dimensions. This only works in combination with
349 * libvlc_video_set_callbacks().
351 * \param mp the media player
352 * \param setup callback to select the video format (cannot be NULL)
353 * \param cleanup callback to release any allocated resources (or NULL)
354 * \version LibVLC 1.2.0 or later
357 void libvlc_video_set_format_callbacks( libvlc_media_player_t *mp,
358 libvlc_video_format_cb setup,
359 libvlc_video_cleanup_cb cleanup );
362 * Set the NSView handler where the media player should render its video output.
364 * Use the vout called "macosx".
366 * The drawable is an NSObject that follow the VLCOpenGLVideoViewEmbedding
370 * \@protocol VLCOpenGLVideoViewEmbedding <NSObject>
371 * - (void)addVoutSubview:(NSView *)view;
372 * - (void)removeVoutSubview:(NSView *)view;
376 * Or it can be an NSView object.
378 * If you want to use it along with Qt4 see the QMacCocoaViewContainer. Then
379 * the following code should work:
382 * NSView *video = [[NSView alloc] init];
383 * QMacCocoaViewContainer *container = new QMacCocoaViewContainer(video, parent);
384 * libvlc_media_player_set_nsobject(mp, video);
389 * You can find a live example in VLCVideoView in VLCKit.framework.
391 * \param p_mi the Media Player
392 * \param drawable the drawable that is either an NSView or an object following
393 * the VLCOpenGLVideoViewEmbedding protocol.
395 LIBVLC_API void libvlc_media_player_set_nsobject ( libvlc_media_player_t *p_mi, void * drawable );
398 * Get the NSView handler previously set with libvlc_media_player_set_nsobject().
400 * \param p_mi the Media Player
401 * \return the NSView handler or 0 if none where set
403 LIBVLC_API void * libvlc_media_player_get_nsobject ( libvlc_media_player_t *p_mi );
406 * Set the agl handler where the media player should render its video output.
408 * \param p_mi the Media Player
409 * \param drawable the agl handler
411 LIBVLC_API void libvlc_media_player_set_agl ( libvlc_media_player_t *p_mi, uint32_t drawable );
414 * Get the agl handler previously set with libvlc_media_player_set_agl().
416 * \param p_mi the Media Player
417 * \return the agl handler or 0 if none where set
419 LIBVLC_API uint32_t libvlc_media_player_get_agl ( libvlc_media_player_t *p_mi );
422 * Set an X Window System drawable where the media player should render its
423 * video output. If LibVLC was built without X11 output support, then this has
426 * The specified identifier must correspond to an existing Input/Output class
427 * X11 window. Pixmaps are <b>not</b> supported. The caller shall ensure that
428 * the X11 server is the same as the one the VLC instance has been configured
429 * with. This function must be called before video playback is started;
430 * otherwise it will only take effect after playback stop and restart.
432 * \param p_mi the Media Player
433 * \param drawable the ID of the X window
435 LIBVLC_API void libvlc_media_player_set_xwindow ( libvlc_media_player_t *p_mi, uint32_t drawable );
438 * Get the X Window System window identifier previously set with
439 * libvlc_media_player_set_xwindow(). Note that this will return the identifier
440 * even if VLC is not currently using it (for instance if it is playing an
443 * \param p_mi the Media Player
444 * \return an X window ID, or 0 if none where set.
446 LIBVLC_API uint32_t libvlc_media_player_get_xwindow ( libvlc_media_player_t *p_mi );
449 * Set a Win32/Win64 API window handle (HWND) where the media player should
450 * render its video output. If LibVLC was built without Win32/Win64 API output
451 * support, then this has no effects.
453 * \param p_mi the Media Player
454 * \param drawable windows handle of the drawable
456 LIBVLC_API void libvlc_media_player_set_hwnd ( libvlc_media_player_t *p_mi, void *drawable );
459 * Get the Windows API window handle (HWND) previously set with
460 * libvlc_media_player_set_hwnd(). The handle will be returned even if LibVLC
461 * is not currently outputting any video to it.
463 * \param p_mi the Media Player
464 * \return a window handle or NULL if there are none.
466 LIBVLC_API void *libvlc_media_player_get_hwnd ( libvlc_media_player_t *p_mi );
469 * Callback prototype for audio playback.
470 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
471 * \param samples pointer to the first audio sample to play back [IN]
472 * \param count number of audio samples to play back
473 * \param pts expected play time stamp (see libvlc_delay())
475 typedef void (*libvlc_audio_play_cb)(void *data, const void *samples,
476 unsigned count, int64_t pts);
479 * Callback prototype for audio pause.
480 * \note The pause callback is never called if the audio is already paused.
481 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
482 * \param pts time stamp of the pause request (should be elapsed already)
484 typedef void (*libvlc_audio_pause_cb)(void *data, int64_t pts);
487 * Callback prototype for audio resumption (i.e. restart from pause).
488 * \note The resume callback is never called if the audio is not paused.
489 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
490 * \param pts time stamp of the resumption request (should be elapsed already)
492 typedef void (*libvlc_audio_resume_cb)(void *data, int64_t pts);
495 * Callback prototype for audio buffer flush
496 * (i.e. discard all pending buffers and stop playback as soon as possible).
497 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
499 typedef void (*libvlc_audio_flush_cb)(void *data, int64_t pts);
502 * Callback prototype for audio buffer drain
503 * (i.e. wait for pending buffers to be played).
504 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
506 typedef void (*libvlc_audio_drain_cb)(void *data);
509 * Callback prototype for audio volume change.
510 * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
511 * \param volume software volume (1. = nominal, 0. = mute)
512 * \param mute muted flag
514 typedef void (*libvlc_audio_set_volume_cb)(void *data,
515 float volume, bool mute);
518 * Set callbacks and private data for decoded audio.
519 * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks()
520 * to configure the decoded audio format.
522 * \param mp the media player
523 * \param play callback to play audio samples (must not be NULL)
524 * \param pause callback to pause playback (or NULL to ignore)
525 * \param resume callback to resume playback (or NULL to ignore)
526 * \param flush callback to flush audio buffers (or NULL to ignore)
527 * \param drain callback to drain audio buffers (or NULL to ignore)
528 * \param opaque private pointer for the audio callbacks (as first parameter)
529 * \version LibVLC 1.2.0 or later
532 void libvlc_audio_set_callbacks( libvlc_media_player_t *mp,
533 libvlc_audio_play_cb play,
534 libvlc_audio_pause_cb pause,
535 libvlc_audio_resume_cb resume,
536 libvlc_audio_flush_cb flush,
537 libvlc_audio_drain_cb drain,
541 * Set callbacks and private data for decoded audio.
542 * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks()
543 * to configure the decoded audio format.
545 * \param mp the media player
546 * \param set_volume callback to apply audio volume,
547 * or NULL to apply volume in software
548 * \version LibVLC 1.2.0 or later
551 void libvlc_audio_set_volume_callback( libvlc_media_player_t *mp,
552 libvlc_audio_set_volume_cb set_volume );
555 * Callback prototype to setup the audio playback.
556 * This is called when the media player needs to create a new audio output.
557 * \param opaque pointer to the data pointer passed to
558 * libvlc_audio_set_callbacks() [IN/OUT]
559 * \param format 4 bytes sample format [IN/OUT]
560 * \param rate sample rate [IN/OUT]
561 * \param channels channels count [IN/OUT]
562 * \return 0 on success, anything else to skip audio playback
564 typedef int (*libvlc_audio_setup_cb)(void **data, char *format, unsigned *rate,
568 * Callback prototype for audio playback cleanup.
569 * This is called when the media player no longer needs an audio output.
570 * \param opaque data pointer as passed to libvlc_audio_set_callbacks() [IN]
572 typedef void (*libvlc_audio_cleanup_cb)(void *data);
575 * Set decoded audio format. This only works in combination with
576 * libvlc_audio_set_callbacks().
578 * \param mp the media player
579 * \param setup callback to select the audio format (cannot be NULL)
580 * \param cleanup callback to release any allocated resources (or NULL)
581 * \version LibVLC 1.2.0 or later
584 void libvlc_audio_set_format_callbacks( libvlc_media_player_t *mp,
585 libvlc_audio_setup_cb setup,
586 libvlc_audio_cleanup_cb cleanup );
589 * Set decoded audio format.
590 * This only works in combination with libvlc_audio_set_callbacks(),
591 * and is mutually exclusive with libvlc_audio_set_format_callbacks().
593 * \param mp the media player
594 * \param format a four-characters string identifying the sample format
595 * (e.g. "S16N" or "FL32")
596 * \param rate sample rate (expressed in Hz)
597 * \param channels channels count
598 * \version LibVLC 1.2.0 or later
601 void libvlc_audio_set_format( libvlc_media_player_t *mp, const char *format,
602 unsigned rate, unsigned channels );
604 /** \bug This might go away ... to be replaced by a broader system */
607 * Get the current movie length (in ms).
609 * \param p_mi the Media Player
610 * \return the movie length (in ms), or -1 if there is no media.
612 LIBVLC_API libvlc_time_t libvlc_media_player_get_length( libvlc_media_player_t *p_mi );
615 * Get the current movie time (in ms).
617 * \param p_mi the Media Player
618 * \return the movie time (in ms), or -1 if there is no media.
620 LIBVLC_API libvlc_time_t libvlc_media_player_get_time( libvlc_media_player_t *p_mi );
623 * Set the movie time (in ms). This has no effect if no media is being played.
624 * Not all formats and protocols support this.
626 * \param p_mi the Media Player
627 * \param i_time the movie time (in ms).
629 LIBVLC_API void libvlc_media_player_set_time( libvlc_media_player_t *p_mi, libvlc_time_t i_time );
632 * Get movie position.
634 * \param p_mi the Media Player
635 * \return movie position, or -1. in case of error
637 LIBVLC_API float libvlc_media_player_get_position( libvlc_media_player_t *p_mi );
640 * Set movie position. This has no effect if playback is not enabled.
641 * This might not work depending on the underlying input format and protocol.
643 * \param p_mi the Media Player
644 * \param f_pos the position
646 LIBVLC_API void libvlc_media_player_set_position( libvlc_media_player_t *p_mi, float f_pos );
649 * Set movie chapter (if applicable).
651 * \param p_mi the Media Player
652 * \param i_chapter chapter number to play
654 LIBVLC_API void libvlc_media_player_set_chapter( libvlc_media_player_t *p_mi, int i_chapter );
659 * \param p_mi the Media Player
660 * \return chapter number currently playing, or -1 if there is no media.
662 LIBVLC_API int libvlc_media_player_get_chapter( libvlc_media_player_t *p_mi );
665 * Get movie chapter count
667 * \param p_mi the Media Player
668 * \return number of chapters in movie, or -1.
670 LIBVLC_API int libvlc_media_player_get_chapter_count( libvlc_media_player_t *p_mi );
673 * Is the player able to play
675 * \param p_mi the Media Player
678 * \libvlc_return_bool
680 LIBVLC_API int libvlc_media_player_will_play( libvlc_media_player_t *p_mi );
683 * Get title chapter count
685 * \param p_mi the Media Player
686 * \param i_title title
687 * \return number of chapters in title, or -1
689 LIBVLC_API int libvlc_media_player_get_chapter_count_for_title(
690 libvlc_media_player_t *p_mi, int i_title );
695 * \param p_mi the Media Player
696 * \param i_title title number to play
698 LIBVLC_API void libvlc_media_player_set_title( libvlc_media_player_t *p_mi, int i_title );
703 * \param p_mi the Media Player
704 * \return title number currently playing, or -1
706 LIBVLC_API int libvlc_media_player_get_title( libvlc_media_player_t *p_mi );
709 * Get movie title count
711 * \param p_mi the Media Player
712 * \return title number count, or -1
714 LIBVLC_API int libvlc_media_player_get_title_count( libvlc_media_player_t *p_mi );
717 * Set previous chapter (if applicable)
719 * \param p_mi the Media Player
721 LIBVLC_API void libvlc_media_player_previous_chapter( libvlc_media_player_t *p_mi );
724 * Set next chapter (if applicable)
726 * \param p_mi the Media Player
728 LIBVLC_API void libvlc_media_player_next_chapter( libvlc_media_player_t *p_mi );
731 * Get the requested movie play rate.
732 * @warning Depending on the underlying media, the requested rate may be
733 * different from the real playback rate.
735 * \param p_mi the Media Player
736 * \return movie play rate
738 LIBVLC_API float libvlc_media_player_get_rate( libvlc_media_player_t *p_mi );
741 * Set movie play rate
743 * \param p_mi the Media Player
744 * \param rate movie play rate to set
745 * \return -1 if an error was detected, 0 otherwise (but even then, it might
746 * not actually work depending on the underlying media protocol)
748 LIBVLC_API int libvlc_media_player_set_rate( libvlc_media_player_t *p_mi, float rate );
751 * Get current movie state
753 * \param p_mi the Media Player
754 * \return the current state of the media player (playing, paused, ...) \see libvlc_state_t
756 LIBVLC_API libvlc_state_t libvlc_media_player_get_state( libvlc_media_player_t *p_mi );
761 * \param p_mi the Media Player
762 * \return frames per second (fps) for this playing movie, or 0 if unspecified
764 LIBVLC_API float libvlc_media_player_get_fps( libvlc_media_player_t *p_mi );
769 * How many video outputs does this media player have?
771 * \param p_mi the media player
772 * \return the number of video outputs
774 LIBVLC_API unsigned libvlc_media_player_has_vout( libvlc_media_player_t *p_mi );
777 * Is this media player seekable?
779 * \param p_mi the media player
780 * \return true if the media player can seek
782 * \libvlc_return_bool
784 LIBVLC_API int libvlc_media_player_is_seekable( libvlc_media_player_t *p_mi );
787 * Can this media player be paused?
789 * \param p_mi the media player
790 * \return true if the media player can pause
792 * \libvlc_return_bool
794 LIBVLC_API int libvlc_media_player_can_pause( libvlc_media_player_t *p_mi );
798 * Display the next frame (if supported)
800 * \param p_mi the media player
802 LIBVLC_API void libvlc_media_player_next_frame( libvlc_media_player_t *p_mi );
805 * Navigate through DVD Menu
807 * \param p_mi the Media Player
808 * \param navigate the Navigation mode
809 * \version libVLC 1.2.0 or later
811 LIBVLC_API void libvlc_media_player_navigate( libvlc_media_player_t* p_mi,
815 * Release (free) libvlc_track_description_t
817 * \param p_track_description the structure to release
819 LIBVLC_API void libvlc_track_description_release( libvlc_track_description_t *p_track_description );
821 /** \defgroup libvlc_video LibVLC video controls
826 * Toggle fullscreen status on non-embedded video outputs.
828 * @warning The same limitations applies to this function
829 * as to libvlc_set_fullscreen().
831 * \param p_mi the media player
833 LIBVLC_API void libvlc_toggle_fullscreen( libvlc_media_player_t *p_mi );
836 * Enable or disable fullscreen.
838 * @warning With most window managers, only a top-level windows can be in
839 * full-screen mode. Hence, this function will not operate properly if
840 * libvlc_media_player_set_xwindow() was used to embed the video in a
841 * non-top-level window. In that case, the embedding window must be reparented
842 * to the root window <b>before</b> fullscreen mode is enabled. You will want
843 * to reparent it back to its normal parent when disabling fullscreen.
845 * \param p_mi the media player
846 * \param b_fullscreen boolean for fullscreen status
848 LIBVLC_API void libvlc_set_fullscreen( libvlc_media_player_t *p_mi, int b_fullscreen );
851 * Get current fullscreen status.
853 * \param p_mi the media player
854 * \return the fullscreen status (boolean)
856 * \libvlc_return_bool
858 LIBVLC_API int libvlc_get_fullscreen( libvlc_media_player_t *p_mi );
861 * Enable or disable key press events handling, according to the LibVLC hotkeys
862 * configuration. By default and for historical reasons, keyboard events are
863 * handled by the LibVLC video widget.
865 * \note On X11, there can be only one subscriber for key press and mouse
866 * click events per window. If your application has subscribed to those events
867 * for the X window ID of the video widget, then LibVLC will not be able to
868 * handle key presses and mouse clicks in any case.
870 * \warning This function is only implemented for X11 and Win32 at the moment.
872 * \param p_mi the media player
873 * \param on true to handle key press events, false to ignore them.
876 void libvlc_video_set_key_input( libvlc_media_player_t *p_mi, unsigned on );
879 * Enable or disable mouse click events handling. By default, those events are
880 * handled. This is needed for DVD menus to work, as well as a few video
881 * filters such as "puzzle".
883 * \see libvlc_video_set_key_input().
885 * \warning This function is only implemented for X11 and Win32 at the moment.
887 * \param p_mi the media player
888 * \param on true to handle mouse click events, false to ignore them.
891 void libvlc_video_set_mouse_input( libvlc_media_player_t *p_mi, unsigned on );
894 * Get the pixel dimensions of a video.
896 * \param p_mi media player
897 * \param num number of the video (starting from, and most commonly 0)
898 * \param px pointer to get the pixel width [OUT]
899 * \param py pointer to get the pixel height [OUT]
900 * \return 0 on success, -1 if the specified video does not exist
903 int libvlc_video_get_size( libvlc_media_player_t *p_mi, unsigned num,
904 unsigned *px, unsigned *py );
907 * Get current video height.
908 * \deprecated Use libvlc_video_get_size() instead.
910 * \param p_mi the media player
911 * \return the video pixel height or 0 if not applicable
914 int libvlc_video_get_height( libvlc_media_player_t *p_mi );
917 * Get current video width.
918 * \deprecated Use libvlc_video_get_size() instead.
920 * \param p_mi the media player
921 * \return the video pixel width or 0 if not applicable
924 int libvlc_video_get_width( libvlc_media_player_t *p_mi );
927 * Get the mouse pointer coordinates over a video.
928 * Coordinates are expressed in terms of the decoded video resolution,
929 * <b>not</b> in terms of pixels on the screen/viewport (to get the latter,
930 * you can query your windowing system directly).
932 * Either of the coordinates may be negative or larger than the corresponding
933 * dimension of the video, if the cursor is outside the rendering area.
935 * @warning The coordinates may be out-of-date if the pointer is not located
936 * on the video rendering area. LibVLC does not track the pointer if it is
937 * outside of the video widget.
939 * @note LibVLC does not support multiple pointers (it does of course support
940 * multiple input devices sharing the same pointer) at the moment.
942 * \param p_mi media player
943 * \param num number of the video (starting from, and most commonly 0)
944 * \param px pointer to get the abscissa [OUT]
945 * \param py pointer to get the ordinate [OUT]
946 * \return 0 on success, -1 if the specified video does not exist
949 int libvlc_video_get_cursor( libvlc_media_player_t *p_mi, unsigned num,
953 * Get the current video scaling factor.
954 * See also libvlc_video_set_scale().
956 * \param p_mi the media player
957 * \return the currently configured zoom factor, or 0. if the video is set
958 * to fit to the output window/drawable automatically.
960 LIBVLC_API float libvlc_video_get_scale( libvlc_media_player_t *p_mi );
963 * Set the video scaling factor. That is the ratio of the number of pixels on
964 * screen to the number of pixels in the original decoded video in each
965 * dimension. Zero is a special value; it will adjust the video to the output
966 * window/drawable (in windowed mode) or the entire screen.
968 * Note that not all video outputs support scaling.
970 * \param p_mi the media player
971 * \param f_factor the scaling factor, or zero
973 LIBVLC_API void libvlc_video_set_scale( libvlc_media_player_t *p_mi, float f_factor );
976 * Get current video aspect ratio.
978 * \param p_mi the media player
979 * \return the video aspect ratio or NULL if unspecified
980 * (the result must be released with free() or libvlc_free()).
982 LIBVLC_API char *libvlc_video_get_aspect_ratio( libvlc_media_player_t *p_mi );
985 * Set new video aspect ratio.
987 * \param p_mi the media player
988 * \param psz_aspect new video aspect-ratio or NULL to reset to default
989 * \note Invalid aspect ratios are ignored.
991 LIBVLC_API void libvlc_video_set_aspect_ratio( libvlc_media_player_t *p_mi, const char *psz_aspect );
994 * Get current video subtitle.
996 * \param p_mi the media player
997 * \return the video subtitle selected, or -1 if none
999 LIBVLC_API int libvlc_video_get_spu( libvlc_media_player_t *p_mi );
1002 * Get the number of available video subtitles.
1004 * \param p_mi the media player
1005 * \return the number of available video subtitles
1007 LIBVLC_API int libvlc_video_get_spu_count( libvlc_media_player_t *p_mi );
1010 * Get the description of available video subtitles.
1012 * \param p_mi the media player
1013 * \return list containing description of available video subtitles
1015 LIBVLC_API libvlc_track_description_t *
1016 libvlc_video_get_spu_description( libvlc_media_player_t *p_mi );
1019 * Set new video subtitle.
1021 * \param p_mi the media player
1022 * \param i_spu new video subtitle to select
1023 * \return 0 on success, -1 if out of range
1025 LIBVLC_API int libvlc_video_set_spu( libvlc_media_player_t *p_mi, unsigned i_spu );
1028 * Set new video subtitle file.
1030 * \param p_mi the media player
1031 * \param psz_subtitle new video subtitle file
1032 * \return the success status (boolean)
1034 LIBVLC_API int libvlc_video_set_subtitle_file( libvlc_media_player_t *p_mi, const char *psz_subtitle );
1037 * Get the description of available titles.
1039 * \param p_mi the media player
1040 * \return list containing description of available titles
1042 LIBVLC_API libvlc_track_description_t *
1043 libvlc_video_get_title_description( libvlc_media_player_t *p_mi );
1046 * Get the description of available chapters for specific title.
1048 * \param p_mi the media player
1049 * \param i_title selected title
1050 * \return list containing description of available chapter for title i_title
1052 LIBVLC_API libvlc_track_description_t *
1053 libvlc_video_get_chapter_description( libvlc_media_player_t *p_mi, int i_title );
1056 * Get current crop filter geometry.
1058 * \param p_mi the media player
1059 * \return the crop filter geometry or NULL if unset
1061 LIBVLC_API char *libvlc_video_get_crop_geometry( libvlc_media_player_t *p_mi );
1064 * Set new crop filter geometry.
1066 * \param p_mi the media player
1067 * \param psz_geometry new crop filter geometry (NULL to unset)
1070 void libvlc_video_set_crop_geometry( libvlc_media_player_t *p_mi, const char *psz_geometry );
1073 * Get current teletext page requested.
1075 * \param p_mi the media player
1076 * \return the current teletext page requested.
1078 LIBVLC_API int libvlc_video_get_teletext( libvlc_media_player_t *p_mi );
1081 * Set new teletext page to retrieve.
1083 * \param p_mi the media player
1084 * \param i_page teletex page number requested
1086 LIBVLC_API void libvlc_video_set_teletext( libvlc_media_player_t *p_mi, int i_page );
1089 * Toggle teletext transparent status on video output.
1091 * \param p_mi the media player
1093 LIBVLC_API void libvlc_toggle_teletext( libvlc_media_player_t *p_mi );
1096 * Get number of available video tracks.
1098 * \param p_mi media player
1099 * \return the number of available video tracks (int)
1101 LIBVLC_API int libvlc_video_get_track_count( libvlc_media_player_t *p_mi );
1104 * Get the description of available video tracks.
1106 * \param p_mi media player
1107 * \return list with description of available video tracks, or NULL on error
1109 LIBVLC_API libvlc_track_description_t *
1110 libvlc_video_get_track_description( libvlc_media_player_t *p_mi );
1113 * Get current video track.
1115 * \param p_mi media player
1116 * \return the video track (int) or -1 if none
1118 LIBVLC_API int libvlc_video_get_track( libvlc_media_player_t *p_mi );
1123 * \param p_mi media player
1124 * \param i_track the track (int)
1125 * \return 0 on success, -1 if out of range
1128 int libvlc_video_set_track( libvlc_media_player_t *p_mi, int i_track );
1131 * Take a snapshot of the current video window.
1133 * If i_width AND i_height is 0, original size is used.
1134 * If i_width XOR i_height is 0, original aspect-ratio is preserved.
1136 * \param p_mi media player instance
1137 * \param num number of video output (typically 0 for the first/only one)
1138 * \param psz_filepath the path where to save the screenshot to
1139 * \param i_width the snapshot's width
1140 * \param i_height the snapshot's height
1141 * \return 0 on success, -1 if the video was not found
1144 int libvlc_video_take_snapshot( libvlc_media_player_t *p_mi, unsigned num,
1145 const char *psz_filepath, unsigned int i_width,
1146 unsigned int i_height );
1149 * Enable or disable deinterlace filter
1151 * \param p_mi libvlc media player
1152 * \param psz_mode type of deinterlace filter, NULL to disable
1154 LIBVLC_API void libvlc_video_set_deinterlace( libvlc_media_player_t *p_mi,
1155 const char *psz_mode );
1158 * Get an integer marquee option value
1160 * \param p_mi libvlc media player
1161 * \param option marq option to get \see libvlc_video_marquee_int_option_t
1163 LIBVLC_API int libvlc_video_get_marquee_int( libvlc_media_player_t *p_mi,
1167 * Get a string marquee option value
1169 * \param p_mi libvlc media player
1170 * \param option marq option to get \see libvlc_video_marquee_string_option_t
1172 LIBVLC_API char *libvlc_video_get_marquee_string( libvlc_media_player_t *p_mi,
1176 * Enable, disable or set an integer marquee option
1178 * Setting libvlc_marquee_Enable has the side effect of enabling (arg !0)
1179 * or disabling (arg 0) the marq filter.
1181 * \param p_mi libvlc media player
1182 * \param option marq option to set \see libvlc_video_marquee_int_option_t
1183 * \param i_val marq option value
1185 LIBVLC_API void libvlc_video_set_marquee_int( libvlc_media_player_t *p_mi,
1186 unsigned option, int i_val );
1189 * Set a marquee string option
1191 * \param p_mi libvlc media player
1192 * \param option marq option to set \see libvlc_video_marquee_string_option_t
1193 * \param psz_text marq option value
1195 LIBVLC_API void libvlc_video_set_marquee_string( libvlc_media_player_t *p_mi,
1196 unsigned option, const char *psz_text );
1198 /** option values for libvlc_video_{get,set}_logo_{int,string} */
1199 enum libvlc_video_logo_option_t {
1201 libvlc_logo_file, /**< string argument, "file,d,t;file,d,t;..." */
1206 libvlc_logo_opacity,
1207 libvlc_logo_position
1211 * Get integer logo option.
1213 * \param p_mi libvlc media player instance
1214 * \param option logo option to get, values of libvlc_video_logo_option_t
1216 LIBVLC_API int libvlc_video_get_logo_int( libvlc_media_player_t *p_mi,
1220 * Set logo option as integer. Options that take a different type value
1222 * Passing libvlc_logo_enable as option value has the side effect of
1223 * starting (arg !0) or stopping (arg 0) the logo filter.
1225 * \param p_mi libvlc media player instance
1226 * \param option logo option to set, values of libvlc_video_logo_option_t
1227 * \param value logo option value
1229 LIBVLC_API void libvlc_video_set_logo_int( libvlc_media_player_t *p_mi,
1230 unsigned option, int value );
1233 * Set logo option as string. Options that take a different type value
1236 * \param p_mi libvlc media player instance
1237 * \param option logo option to set, values of libvlc_video_logo_option_t
1238 * \param psz_value logo option value
1240 LIBVLC_API void libvlc_video_set_logo_string( libvlc_media_player_t *p_mi,
1241 unsigned option, const char *psz_value );
1244 /** option values for libvlc_video_{get,set}_adjust_{int,float,bool} */
1245 enum libvlc_video_adjust_option_t {
1246 libvlc_adjust_Enable = 0,
1247 libvlc_adjust_Contrast,
1248 libvlc_adjust_Brightness,
1250 libvlc_adjust_Saturation,
1255 * Get integer adjust option.
1257 * \param p_mi libvlc media player instance
1258 * \param option adjust option to get, values of libvlc_video_adjust_option_t
1259 * \version LibVLC 1.1.1 and later.
1261 LIBVLC_API int libvlc_video_get_adjust_int( libvlc_media_player_t *p_mi,
1265 * Set adjust option as integer. Options that take a different type value
1267 * Passing libvlc_adjust_enable as option value has the side effect of
1268 * starting (arg !0) or stopping (arg 0) the adjust filter.
1270 * \param p_mi libvlc media player instance
1271 * \param option adust option to set, values of libvlc_video_adjust_option_t
1272 * \param value adjust option value
1273 * \version LibVLC 1.1.1 and later.
1275 LIBVLC_API void libvlc_video_set_adjust_int( libvlc_media_player_t *p_mi,
1276 unsigned option, int value );
1279 * Get float adjust option.
1281 * \param p_mi libvlc media player instance
1282 * \param option adjust option to get, values of libvlc_video_adjust_option_t
1283 * \version LibVLC 1.1.1 and later.
1285 LIBVLC_API float libvlc_video_get_adjust_float( libvlc_media_player_t *p_mi,
1289 * Set adjust option as float. Options that take a different type value
1292 * \param p_mi libvlc media player instance
1293 * \param option adust option to set, values of libvlc_video_adjust_option_t
1294 * \param value adjust option value
1295 * \version LibVLC 1.1.1 and later.
1297 LIBVLC_API void libvlc_video_set_adjust_float( libvlc_media_player_t *p_mi,
1298 unsigned option, float value );
1302 /** \defgroup libvlc_audio LibVLC audio controls
1307 * Audio device types
1309 typedef enum libvlc_audio_output_device_types_t {
1310 libvlc_AudioOutputDevice_Error = -1,
1311 libvlc_AudioOutputDevice_Mono = 1,
1312 libvlc_AudioOutputDevice_Stereo = 2,
1313 libvlc_AudioOutputDevice_2F2R = 4,
1314 libvlc_AudioOutputDevice_3F2R = 5,
1315 libvlc_AudioOutputDevice_5_1 = 6,
1316 libvlc_AudioOutputDevice_6_1 = 7,
1317 libvlc_AudioOutputDevice_7_1 = 8,
1318 libvlc_AudioOutputDevice_SPDIF = 10
1319 } libvlc_audio_output_device_types_t;
1324 typedef enum libvlc_audio_output_channel_t {
1325 libvlc_AudioChannel_Error = -1,
1326 libvlc_AudioChannel_Stereo = 1,
1327 libvlc_AudioChannel_RStereo = 2,
1328 libvlc_AudioChannel_Left = 3,
1329 libvlc_AudioChannel_Right = 4,
1330 libvlc_AudioChannel_Dolbys = 5
1331 } libvlc_audio_output_channel_t;
1335 * Get the list of available audio outputs
1337 * \param p_instance libvlc instance
1338 * \return list of available audio outputs. It must be freed it with
1339 * \see libvlc_audio_output_list_release \see libvlc_audio_output_t .
1340 * In case of error, NULL is returned.
1342 LIBVLC_API libvlc_audio_output_t *
1343 libvlc_audio_output_list_get( libvlc_instance_t *p_instance );
1346 * Free the list of available audio outputs
1348 * \param p_list list with audio outputs for release
1350 LIBVLC_API void libvlc_audio_output_list_release( libvlc_audio_output_t *p_list );
1353 * Set the audio output.
1354 * Change will be applied after stop and play.
1356 * \param p_mi media player
1357 * \param psz_name name of audio output,
1358 * use psz_name of \see libvlc_audio_output_t
1359 * \return 0 if function succeded, -1 on error
1361 LIBVLC_API int libvlc_audio_output_set( libvlc_media_player_t *p_mi,
1362 const char *psz_name );
1365 * Get count of devices for audio output, these devices are hardware oriented
1366 * like analor or digital output of sound card
1368 * \param p_instance libvlc instance
1369 * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
1370 * \return number of devices
1372 LIBVLC_API int libvlc_audio_output_device_count( libvlc_instance_t *p_instance,
1373 const char *psz_audio_output );
1376 * Get long name of device, if not available short name given
1378 * \param p_instance libvlc instance
1379 * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
1380 * \param i_device device index
1381 * \return long name of device
1383 LIBVLC_API char * libvlc_audio_output_device_longname( libvlc_instance_t *p_instance,
1384 const char *psz_audio_output,
1388 * Get id name of device
1390 * \param p_instance libvlc instance
1391 * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
1392 * \param i_device device index
1393 * \return id name of device, use for setting device, need to be free after use
1395 LIBVLC_API char * libvlc_audio_output_device_id( libvlc_instance_t *p_instance,
1396 const char *psz_audio_output,
1400 * Set audio output device. Changes are only effective after stop and play.
1402 * \param p_mi media player
1403 * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
1404 * \param psz_device_id device
1406 LIBVLC_API void libvlc_audio_output_device_set( libvlc_media_player_t *p_mi,
1407 const char *psz_audio_output,
1408 const char *psz_device_id );
1411 * Get current audio device type. Device type describes something like
1412 * character of output sound - stereo sound, 2.1, 5.1 etc
1414 * \param p_mi media player
1415 * \return the audio devices type \see libvlc_audio_output_device_types_t
1417 LIBVLC_API int libvlc_audio_output_get_device_type( libvlc_media_player_t *p_mi );
1420 * Set current audio device type.
1422 * \param p_mi vlc instance
1423 * \param device_type the audio device type,
1424 according to \see libvlc_audio_output_device_types_t
1426 LIBVLC_API void libvlc_audio_output_set_device_type( libvlc_media_player_t *p_mi,
1431 * Toggle mute status.
1433 * \param p_mi media player
1435 LIBVLC_API void libvlc_audio_toggle_mute( libvlc_media_player_t *p_mi );
1438 * Get current mute status.
1440 * \param p_mi media player
1441 * \return the mute status (boolean)
1443 * \libvlc_return_bool
1445 LIBVLC_API int libvlc_audio_get_mute( libvlc_media_player_t *p_mi );
1450 * \param p_mi media player
1451 * \param status If status is true then mute, otherwise unmute
1453 LIBVLC_API void libvlc_audio_set_mute( libvlc_media_player_t *p_mi, int status );
1456 * Get current software audio volume.
1458 * \param p_mi media player
1459 * \return the software volume in percents
1460 * (0 = mute, 100 = nominal / 0dB)
1462 LIBVLC_API int libvlc_audio_get_volume( libvlc_media_player_t *p_mi );
1465 * Set current software audio volume.
1467 * \param p_mi media player
1468 * \param i_volume the volume in percents (0 = mute, 100 = 0dB)
1469 * \return 0 if the volume was set, -1 if it was out of range
1471 LIBVLC_API int libvlc_audio_set_volume( libvlc_media_player_t *p_mi, int i_volume );
1474 * Get number of available audio tracks.
1476 * \param p_mi media player
1477 * \return the number of available audio tracks (int), or -1 if unavailable
1479 LIBVLC_API int libvlc_audio_get_track_count( libvlc_media_player_t *p_mi );
1482 * Get the description of available audio tracks.
1484 * \param p_mi media player
1485 * \return list with description of available audio tracks, or NULL
1487 LIBVLC_API libvlc_track_description_t *
1488 libvlc_audio_get_track_description( libvlc_media_player_t *p_mi );
1491 * Get current audio track.
1493 * \param p_mi media player
1494 * \return the audio track (int), or -1 if none.
1496 LIBVLC_API int libvlc_audio_get_track( libvlc_media_player_t *p_mi );
1499 * Set current audio track.
1501 * \param p_mi media player
1502 * \param i_track the track (int)
1503 * \return 0 on success, -1 on error
1505 LIBVLC_API int libvlc_audio_set_track( libvlc_media_player_t *p_mi, int i_track );
1508 * Get current audio channel.
1510 * \param p_mi media player
1511 * \return the audio channel \see libvlc_audio_output_channel_t
1513 LIBVLC_API int libvlc_audio_get_channel( libvlc_media_player_t *p_mi );
1516 * Set current audio channel.
1518 * \param p_mi media player
1519 * \param channel the audio channel, \see libvlc_audio_output_channel_t
1520 * \return 0 on success, -1 on error
1522 LIBVLC_API int libvlc_audio_set_channel( libvlc_media_player_t *p_mi, int channel );
1525 * Get current audio delay.
1527 * \param p_mi media player
1528 * \return the audio delay (microseconds)
1529 * \version LibVLC 1.1.1 or later
1531 LIBVLC_API int64_t libvlc_audio_get_delay( libvlc_media_player_t *p_mi );
1534 * Set current audio delay. The audio delay will be reset to zero each time the media changes.
1536 * \param p_mi media player
1537 * \param i_delay the audio delay (microseconds)
1538 * \return 0 on success, -1 on error
1539 * \version LibVLC 1.1.1 or later
1541 LIBVLC_API int libvlc_audio_set_delay( libvlc_media_player_t *p_mi, int64_t i_delay );
1545 /** @} media_player */
1551 #endif /* VLC_LIBVLC_MEDIA_PLAYER_H */