1 /*****************************************************************************
2 * vlc_player.h: player interface
3 *****************************************************************************
4 * Copyright (C) 2018 VLC authors and VideoLAN
6 * This program is free software; you can redistribute it and/or modify it
7 * under the terms of the GNU Lesser General Public License as published by
8 * the Free Software Foundation; either version 2.1 of the License, or
9 * (at your option) any later version.
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU Lesser General Public License for more details.
16 * You should have received a copy of the GNU Lesser General Public License
17 * along with this program; if not, write to the Free Software Foundation,
18 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
19 *****************************************************************************/
22 #define VLC_PLAYER_H 1
24 #include <vlc_input.h>
28 * @defgroup player Player
33 digraph player_states {
34 label="Player state diagram";
36 started [label="Started" URL="@ref VLC_PLAYER_STATE_STARTED"];
37 playing [label="Playing" URL="@ref VLC_PLAYER_STATE_PLAYING"];
38 paused [label="Paused" URL="@ref VLC_PLAYER_STATE_PAUSED"];
39 stopping [label="Stopping" URL="@ref VLC_PLAYER_STATE_STOPPING"];
40 stopped [label="Stopped" URL="@ref VLC_PLAYER_STATE_STOPPED"];
41 new -> stopped [label="vlc_player_New()" URL="@ref vlc_player_New" fontcolor="green3"];
42 started -> playing [style="dashed" label=<<i>internal transition</i>>];
43 started -> stopping [label="vlc_player_Stop()" URL="@ref vlc_player_Stop" fontcolor="red"];
44 playing -> paused [label="vlc_player_Pause()" URL="@ref vlc_player_Pause" fontcolor="blue"];
45 paused -> playing [label="vlc_player_Resume()" URL="@ref vlc_player_Resume" fontcolor="blue3"];
46 paused -> stopping [label="vlc_player_Stop()" URL="@ref vlc_player_Stop" fontcolor="red"];
47 playing -> stopping [label="vlc_player_Stop()" URL="@ref vlc_player_Stop" fontcolor="red"];
48 stopping -> stopped [style="dashed" label=<<i>internal transition</i>>];
49 stopped -> started [label="vlc_player_Start()" URL="@ref vlc_player_Start" fontcolor="darkgreen"];
58 * Player opaque structure.
60 typedef struct vlc_player_t vlc_player_t
;
63 * Player listener opaque structure.
65 * This opaque structure is returned by vlc_player_AddListener() and can be
66 * used to remove the listener via vlc_player_RemoveListener().
68 typedef struct vlc_player_listener_id vlc_player_listener_id
;
71 * Player vout listener opaque structure.
73 * This opaque structure is returned by vlc_player_vout_AddListener() and can
74 * be used to remove the listener via vlc_player_vout_RemoveListener().
76 typedef struct vlc_player_vout_listener_id vlc_player_vout_listener_id
;
79 * Player aout listener opaque structure.
81 * This opaque structure is returned by vlc_player_aout_AddListener() and can
82 * be used to remove the listener via vlc_player_aout_RemoveListener().
84 typedef struct vlc_player_aout_listener_id vlc_player_aout_listener_id
;
87 * Player program structure.
89 struct vlc_player_program
91 /** Id used for vlc_player_SelectProgram() */
93 /** Program name, always valid */
95 /** True if the program is selected */
97 /** True if the program is scrambled */
102 * Player track structure.
104 struct vlc_player_track
106 /** Id used for any player actions, like vlc_player_SelectTrack() */
108 /** Track name, always valid */
112 /** True if the track is selected */
117 * Player chapter structure
119 struct vlc_player_chapter
121 /** Chapter name, always valid */
123 /** Position of this chapter */
127 /** vlc_player_title.flags: The title is a menu. */
128 #define VLC_PLAYER_TITLE_MENU 0x01
129 /** vlc_player_title.flags: The title is interactive. */
130 #define VLC_PLAYER_TITLE_INTERACTIVE 0x02
132 /** Player title structure */
133 struct vlc_player_title
135 /** Title name, always valid */
137 /** Length of the title */
139 /** Bit flag of @ref VLC_PLAYER_TITLE_MENU and @ref
140 * VLC_PLAYER_TITLE_INTERACTIVE */
142 /** Number of chapters, can be 0 */
143 size_t chapter_count
;
144 /** Array of chapters, can be NULL */
145 const struct vlc_player_chapter
*chapters
;
149 * Opaque structure representing a list of @ref vlc_player_title.
151 * @see vlc_player_GetTitleList()
152 * @see vlc_player_title_list_GetCount()
153 * @see vlc_player_title_list_GetAt()
155 typedef struct vlc_player_title_list vlc_player_title_list
;
158 * Menu (VCD/DVD/BD) and viewpoint navigations
160 * @see vlc_player_Navigate()
164 /** Activate the navigation item selected */
165 VLC_PLAYER_NAV_ACTIVATE
,
166 /** Select a navigation item above or move the viewpoint up */
168 /** Select a navigation item under or move the viewpoint down */
170 /** Select a navigation item on the left or move the viewpoint left */
172 /** Select a navigation item on the right or move the viewpoint right */
173 VLC_PLAYER_NAV_RIGHT
,
174 /** Activate the popup Menu (for BD) */
175 VLC_PLAYER_NAV_POPUP
,
176 /** Activate disc Root Menu */
181 * Action of vlc_player_cbs.on_track_list_changed,
182 * vlc_player_cbs.on_program_list_changed, and
183 * vlc_player_cbs.on_vout_list_changed callbacks
185 enum vlc_player_list_action
187 VLC_PLAYER_LIST_ADDED
,
188 VLC_PLAYER_LIST_REMOVED
,
189 VLC_PLAYER_LIST_UPDATED
,
193 * State of the player
195 * During a normal playback (no errors), the user is expected to receive all
196 * events in the following order: STARTED, PLAYING, STOPPING, STOPPED.
198 * @note When playing more than one media in a row, the player stay at the
199 * PLAYING state when doing the transition from the current media to the next
200 * media (that can be gapless). This means that STOPPING, STOPPED states (for
201 * the current media) and STARTED, PLAYING states (for the next one) won't be
202 * sent. Nevertheless, the vlc_player_cbs.on_current_media_changed callback
203 * will be called during this transition.
205 enum vlc_player_state
208 * The player is stopped
210 * Initial state, or triggered by an internal transition from the STOPPING
213 VLC_PLAYER_STATE_STOPPED
,
216 * The player is started
218 * Triggered by vlc_player_Start()
220 VLC_PLAYER_STATE_STARTED
,
223 * The player is playing
225 * Triggered by vlc_player_Resume() or by an internal transition from the
228 VLC_PLAYER_STATE_PLAYING
,
231 * The player is paused
233 * Triggered by vlc_player_Pause().
235 VLC_PLAYER_STATE_PAUSED
,
238 * The player is stopping
240 * Triggered by vlc_player_Stop(), vlc_player_SetCurrentMedia() or by an
241 * internal transition (when the media reach the end of file for example).
243 VLC_PLAYER_STATE_STOPPING
,
247 * Error of the player
249 * @see vlc_player_GetError()
251 enum vlc_player_error
253 VLC_PLAYER_ERROR_NONE
,
254 VLC_PLAYER_ERROR_GENERIC
,
260 * @see vlc_player_SeekByPos()
261 * @see vlc_player_SeekByTime()
263 enum vlc_player_seek_speed
265 /** Do a precise seek */
266 VLC_PLAYER_SEEK_PRECISE
,
267 /** Do a fast seek */
268 VLC_PLAYER_SEEK_FAST
,
272 * Player seek/delay directive
274 * @see vlc_player_SeekByPos()
275 * @see vlc_player_SeekByTime()
276 * @see vlc_player_SetAudioDelay()
277 * @see vlc_player_SetSubtitleDelay()
279 enum vlc_player_whence
281 /** Given time/position */
282 VLC_PLAYER_WHENCE_ABSOLUTE
,
283 /** The current position +/- the given time/position */
284 VLC_PLAYER_WHENCE_RELATIVE
,
288 * Action when the player is stopped
290 * @see vlc_player_SetMediaStoppedAction()
292 enum vlc_player_media_stopped_action
{
293 /** Continue (or stop if there is no next media), default behavior */
294 VLC_PLAYER_MEDIA_STOPPED_CONTINUE
,
295 /** Pause when reaching the end of file */
296 VLC_PLAYER_MEDIA_STOPPED_PAUSE
,
297 /** Stop, even if there is a next media to play */
298 VLC_PLAYER_MEDIA_STOPPED_STOP
,
300 VLC_PLAYER_MEDIA_STOPPED_EXIT
,
306 enum vlc_player_abloop
308 VLC_PLAYER_ABLOOP_NONE
,
314 * Subtitle synchronisation
316 * @see vlc_player_SetSubtitleSync()
318 enum vlc_player_subtitle_sync
320 VLC_PLAYER_SUBTITLE_SYNC_RESET
,
321 VLC_PLAYER_SUBTITLE_SYNC_MARK_AUDIO
,
322 VLC_PLAYER_SUBTITLE_SYNC_MARK_SUBTITLE
,
323 VLC_PLAYER_SUBTITLE_SYNC_APPLY
,
329 * @warning Temporary enum, waiting for a refined vout filter API
331 * @see vlc_player_vout_SetFilter()
333 enum vlc_vout_filter_type
335 VLC_VOUT_FILTER_VIDEO_SPLITTER
,
336 VLC_VOUT_FILTER_VIDEO_FILTER
,
337 VLC_VOUT_FILTER_SUB_SOURCE
,
338 VLC_VOUT_FILTER_SUB_FILTER
,
341 /** Player capability: can seek */
342 #define VLC_PLAYER_CAP_SEEK (1<<0)
343 /** Player capability: can pause */
344 #define VLC_PLAYER_CAP_PAUSE (1<<1)
345 /** Player capability: can change the rate */
346 #define VLC_PLAYER_CAP_CHANGE_RATE (1<<2)
347 /** Player capability: can seek back */
348 #define VLC_PLAYER_CAP_REWIND (1<<3)
350 /** Player teletext key: Red */
351 #define VLC_PLAYER_TELETEXT_KEY_RED ('r' << 16)
352 /** Player teletext key: Green */
353 #define VLC_PLAYER_TELETEXT_KEY_GREEN ('g' << 16)
354 /** Player teletext key: Yellow */
355 #define VLC_PLAYER_TELETEXT_KEY_YELLOW ('y' << 16)
356 /** Player teletext key: Blue */
357 #define VLC_PLAYER_TELETEXT_KEY_BLUE ('b' << 16)
358 /** Player teletext key: Index */
359 #define VLC_PLAYER_TELETEXT_KEY_INDEX ('i' << 16)
362 * Callbacks for the owner of the player.
364 * These callbacks are needed to control the player flow (via the
365 * vlc_playlist_t as a owner for example). It can only be set when creating the
366 * player via vlc_player_New().
368 * All callbacks are called with the player locked (cf. vlc_player_Lock()), and
369 * from any thread (even the current one).
371 struct vlc_player_media_provider
374 * Called when the player requires a new media
376 * @note The returned media must be already held with input_item_Hold()
378 * @param player locked player instance
379 * @param data opaque pointer set from vlc_player_New()
380 * @return the next media to play, held by the callee with input_item_Hold()
382 input_item_t
*(*get_next
)(vlc_player_t
*player
, void *data
);
388 * Can be registered with vlc_player_AddListener().
390 * All callbacks are called with the player locked (cf. vlc_player_Lock()) and
391 * from any threads (and even synchronously from a vlc_player function in some
392 * cases). It is safe to call any vlc_player functions from these callbacks
393 * except vlc_player_Delete().
395 * @warning To avoid deadlocks, users should never call vlc_player functions
396 * with an external mutex locked and lock this same mutex from a player
399 struct vlc_player_cbs
402 * Called when the current media has changed
404 * @note This can be called from the PLAYING state (when the player plays
405 * the next media internally) or from the STOPPED state (from
406 * vlc_player_SetCurrentMedia() or from an internal transition).
408 * @see vlc_player_SetCurrentMedia()
409 * @see vlc_player_InvalidateNextMedia()
411 * @param player locked player instance
412 * @param new_media new media currently played or NULL (when there is no
413 * more media to play)
414 * @param data opaque pointer set by vlc_player_AddListener()
416 void (*on_current_media_changed
)(vlc_player_t
*player
,
417 input_item_t
*new_media
, void *data
);
420 * Called when the player state has changed
422 * @see vlc_player_state
424 * @param player locked player instance
425 * @param new_state new player state
426 * @param data opaque pointer set by vlc_player_AddListener()
428 void (*on_state_changed
)(vlc_player_t
*player
,
429 enum vlc_player_state new_state
, void *data
);
432 * Called when a media triggered an error
434 * Can be called from any states. When it happens the player will stop
435 * itself. It is safe to play an other media or event restart the player
436 * (This will reset the error state).
438 * @param player locked player instance
439 * @param error player error
440 * @param data opaque pointer set by vlc_player_AddListener()
442 void (*on_error_changed
)(vlc_player_t
*player
,
443 enum vlc_player_error error
, void *data
);
446 * Called when the player buffering (or cache) has changed
448 * This event is always called with the 0 and 1 values before a playback
449 * (in case of success). Values in between depends on the media type.
451 * @param player locked player instance
452 * @param new_buffering buffering in the range [0:1]
453 * @param data opaque pointer set by vlc_player_AddListener()
455 void (*on_buffering_changed
)(vlc_player_t
*player
,
456 float new_buffering
, void *data
);
459 * Called when the player rate has changed
461 * Triggered by vlc_player_ChangeRate(), not sent when the media starts
462 * with the default rate (1.f)
464 * @param player locked player instance
465 * @param new_rate player
466 * @param data opaque pointer set by vlc_player_AddListener()
468 void (*on_rate_changed
)(vlc_player_t
*player
,
469 float new_rate
, void *data
);
472 * Called when the media capabilities has changed
474 * Always called when the media is opening. Can be called during playback.
476 * @param player locked player instance
477 * @param new_caps player capabilities
478 * @param data opaque pointer set by vlc_player_AddListener()
480 void (*on_capabilities_changed
)(vlc_player_t
*player
,
481 int new_caps
, void *data
);
484 * Called when the player position has changed
486 * @note A started and playing media doesn't have necessarily a valid time.
488 * @param player locked player instance
489 * @param new_time a valid time or VLC_TICK_INVALID
490 * @param new_pos a valid position
491 * @param data opaque pointer set by vlc_player_AddListener()
493 void (*on_position_changed
)(vlc_player_t
*player
,
494 vlc_tick_t new_time
, float new_pos
, void *data
);
497 * Called when the media length has changed
499 * May be called when the media is opening or during playback.
501 * @note A started and playing media doesn't have necessarily a valid length.
503 * @param player locked player instance
504 * @param new_length a valid time or VLC_TICK_INVALID
505 * @param data opaque pointer set by vlc_player_AddListener()
507 void (*on_length_changed
)(vlc_player_t
*player
,
508 vlc_tick_t new_length
, void *data
);
511 * Called when a track is added, removed, or updated
513 * @note The track is only valid from this callback context. Users should
514 * duplicate this track via vlc_player_track_Dup() if they want to use it
515 * from an other context.
517 * @param player locked player instance
518 * @param action added, removed or updated
519 * @param track valid track
520 * @param data opaque pointer set by vlc_player_AddListener()
522 void (*on_track_list_changed
)(vlc_player_t
*player
,
523 enum vlc_player_list_action action
,
524 const struct vlc_player_track
*track
, void *data
);
527 * Called when a new track is selected and/or unselected
529 * @note This event can be called with both unselected_id and selected_id
530 * valid. This mean that a new track is replacing the old one.
532 * @param player locked player instance
533 * @param unselected_id valid track id or NULL (when nothing is unselected)
534 * @param selected_id valid track id or NULL (when nothing is selected)
535 * @param data opaque pointer set by vlc_player_AddListener()
537 void (*on_track_selection_changed
)(vlc_player_t
*player
,
538 vlc_es_id_t
*unselected_id
, vlc_es_id_t
*selected_id
, void *data
);
541 * Called when a new program is added, removed or updated
543 * @note The program is only valid from this callback context. Users should
544 * duplicate this program via vlc_player_program_Dup() if they want to use
545 * it from an other context.
547 * @param player locked player instance
548 * @param action added, removed or updated
549 * @param prgm valid program
550 * @param data opaque pointer set by vlc_player_AddListener()
552 void (*on_program_list_changed
)(vlc_player_t
*player
,
553 enum vlc_player_list_action action
,
554 const struct vlc_player_program
*prgm
, void *data
);
557 * Called when a new program is selected and/or unselected
559 * @note This event can be called with both unselected_id and selected_id
560 * valid. This mean that a new program is replacing the old one.
562 * @param player locked player instance
563 * @param unselected_id valid program id or -1 (when nothing is unselected)
564 * @param selected_id valid program id or -1 (when nothing is selected)
565 * @param data opaque pointer set by vlc_player_AddListener()
567 void (*on_program_selection_changed
)(vlc_player_t
*player
,
568 int unselected_id
, int selected_id
, void *data
);
571 * Called when the media titles has changed
573 * This event is not called when the opening media doesn't have any titles.
574 * This title list and all its elements are constant. If an element is to
575 * be updated, a new list will be sent from this callback.
577 * @note Users should hold this list with vlc_player_title_list_Hold() if
578 * they want to use it from an other context.
580 * @param player locked player instance
581 * @param titles valid title list or NULL
582 * @param data opaque pointer set by vlc_player_AddListener()
584 void (*on_titles_changed
)(vlc_player_t
*player
,
585 vlc_player_title_list
*titles
, void *data
);
588 * Called when a new title is selected
590 * There are no events when a title is unselected. Titles are automatically
591 * unselected when the title list changes. Titles and indexes are always
592 * valid inside the vlc_player_title_list sent by
593 * vlc_player_cbs.on_titles_changed.
595 * @param player locked player instance
596 * @param new_title new selected title
597 * @param new_idx index of this title
598 * @param data opaque pointer set by vlc_player_AddListener()
600 void (*on_title_selection_changed
)(vlc_player_t
*player
,
601 const struct vlc_player_title
*new_title
, size_t new_idx
, void *data
);
604 * Called when a new chapter is selected
606 * There are no events when a chapter is unselected. Chapters are
607 * automatically unselected when the title list changes. Titles, chapters
608 * and indexes are always valid inside the vlc_player_title_list sent by
609 * vlc_player_cbs.on_titles_changed.
611 * @param player locked player instance
612 * @param title selected title
613 * @param title_idx selected title index
614 * @param chapter new selected chapter
615 * @param chapter_idx new selected chapter index
616 * @param data opaque pointer set by vlc_player_AddListener()
618 void (*on_chapter_selection_changed
)(vlc_player_t
*player
,
619 const struct vlc_player_title
*title
, size_t title_idx
,
620 const struct vlc_player_chapter
*new_chapter
, size_t new_chapter_idx
,
624 * Called when the media has a teletext menu
626 * @param player locked player instance
627 * @param has_teletext_menu true if the media has a teletext menu
628 * @param data opaque pointer set by vlc_player_AddListener()
630 void (*on_teletext_menu_changed
)(vlc_player_t
*player
,
631 bool has_teletext_menu
, void *data
);
634 * Called when teletext is enabled or disabled
636 * @see vlc_player_SetTeletextEnabled()
638 * @param player locked player instance
639 * @param enabled true if teletext is enabled
640 * @param data opaque pointer set by vlc_player_AddListener()
642 void (*on_teletext_enabled_changed
)(vlc_player_t
*player
,
643 bool enabled
, void *data
);
646 * Called when the teletext page has changed
648 * @see vlc_player_SelectTeletextPage()
650 * @param player locked player instance
651 * @param new_page page in the range ]0;888]
652 * @param data opaque pointer set by vlc_player_AddListener()
654 void (*on_teletext_page_changed
)(vlc_player_t
*player
,
655 unsigned new_page
, void *data
);
658 * Called when the teletext transparency has changed
660 * @see vlc_player_SetTeletextTransparency()
662 * @param player locked player instance
663 * @param enabled true is the teletext overlay is transparent
664 * @param data opaque pointer set by vlc_player_AddListener()
666 void (*on_teletext_transparency_changed
)(vlc_player_t
*player
,
667 bool enabled
, void *data
);
670 * Called when the player audio delay has changed
672 * @see vlc_player_SetAudioDelay()
674 * @param player locked player instance
675 * @param new_delay audio delay
676 * @param data opaque pointer set by vlc_player_AddListener()
678 void (*on_audio_delay_changed
)(vlc_player_t
*player
,
679 vlc_tick_t new_delay
, void *data
);
682 * Called when the player subtitle delay has changed
684 * @see vlc_player_SetSubtitleDelay()
686 * @param player locked player instance
687 * @param new_delay subtitle delay
688 * @param data opaque pointer set by vlc_player_AddListener()
690 void (*on_subtitle_delay_changed
)(vlc_player_t
*player
,
691 vlc_tick_t new_delay
, void *data
);
694 * Called when associated subtitle has changed
696 * @see vlc_player_SetAssociatedSubsFPS()
698 * @param player locked player instance
699 * @param sub_fps subtitle fps
700 * @param data opaque pointer set by vlc_player_AddListener()
702 void (*on_associated_subs_fps_changed
)(vlc_player_t
*player
,
703 float subs_fps
, void *data
);
706 * Called when a new renderer item is set
708 * @see vlc_player_SetRenderer()
710 * @param player locked player instance
711 * @param new_item a valid renderer item or NULL (if unset)
712 * @param data opaque pointer set by vlc_player_AddListener()
714 void (*on_renderer_changed
)(vlc_player_t
*player
,
715 vlc_renderer_item_t
*new_item
, void *data
);
718 * Called when the player recording state has changed
720 * @see vlc_player_SetRecordingEnabled()
722 * @param player locked player instance
723 * @param recording true if recording is enabled
724 * @param data opaque pointer set by vlc_player_AddListener()
726 void (*on_recording_changed
)(vlc_player_t
*player
,
727 bool recording
, void *data
);
730 * Called when the media signal has changed
732 * @param player locked player instance
733 * @param new_quality signal quality
734 * @param new_strength signal strength,
735 * @param data opaque pointer set by vlc_player_AddListener()
737 void (*on_signal_changed
)(vlc_player_t
*player
,
738 float quality
, float strength
, void *data
);
741 * Called when the player has new statisics
743 * @note The stats structure is only valid from this callback context. It
744 * can be copied in order to use it from an other context.
746 * @param player locked player instance
747 * @param stats valid stats, only valid from this context
748 * @param data opaque pointer set by vlc_player_AddListener()
750 void (*on_statistics_changed
)(vlc_player_t
*player
,
751 const struct input_stats_t
*stats
, void *data
);
754 * Called when the A to B loop has changed
756 * @see vlc_player_SetAtoBLoop()
758 * @param player locked player instance
759 * @param state A, when only A is set, B when both A and B are set, None by
761 * @param time valid time or VLC_TICK_INVALID of the current state
762 * @param pos valid pos of the current state
763 * @param data opaque pointer set by vlc_player_AddListener()
765 void (*on_atobloop_changed
)(vlc_player_t
*player
,
766 enum vlc_player_abloop new_state
, vlc_tick_t time
, float pos
,
770 * Called when media stopped action has changed
772 * @see vlc_player_SetMediaStoppedAction()
774 * @param player locked player instance
775 * @param new_action action to execute when a media is stopped
776 * @param data opaque pointer set by vlc_player_AddListener()
778 void (*on_media_stopped_action_changed
)(vlc_player_t
*player
,
779 enum vlc_player_media_stopped_action new_action
, void *data
);
782 * Called when the media meta has changed
784 * @param player locked player instance
785 * @param media current media
786 * @param data opaque pointer set by vlc_player_AddListener()
788 void (*on_media_meta_changed
)(vlc_player_t
*player
,
789 input_item_t
*media
, void *data
);
792 * Called when media epg has changed
794 * @param player locked player instance
795 * @param media current media
796 * @param data opaque pointer set by vlc_player_AddListener()
798 void (*on_media_epg_changed
)(vlc_player_t
*player
,
799 input_item_t
*media
, void *data
);
802 * Called when the media has new subitems
804 * @param player locked player instance
805 * @param media current media
806 * @param new_subitems node representing all media subitems
807 * @param data opaque pointer set by vlc_player_AddListener()
809 void (*on_media_subitems_changed
)(vlc_player_t
*player
,
810 input_item_t
*media
, input_item_node_t
*new_subitems
, void *data
);
813 * Called when a new vout is added or removed
815 * @param player locked player instance
816 * @param action added or removed
817 * @param vout new vout
818 * @param data opaque pointer set by vlc_player_AddListener()
820 void (*on_vout_list_changed
)(vlc_player_t
*player
,
821 enum vlc_player_list_action action
, vout_thread_t
*vout
, void *data
);
824 * Called when the player is corked
826 * The player can be corked when the audio output loose focus or when a
827 * renderer was paused from the outside.
829 * @note called only if pause on cork was not set to true (by
830 * vlc_player_SetPauseOnCork())
831 * @note a cork_count higher than 0 means the player is corked. In that
832 * case, the user should pause the player and release all external resource
833 * needed by the player. A value higher than 1 mean that the player was
834 * corked more than one time (for different reasons). A value of 0 means
835 * the player is no longer corked. In that case, the user could resume the
838 * @param player locked player instance
839 * @param cork_count 0 for uncorked, > 0 for corked
840 * @param data opaque pointer set by vlc_player_AddListener()
842 void (*on_cork_changed
)(vlc_player_t
*player
, unsigned cork_count
,
847 * Player vout callbacks
849 * Can be registered with vlc_player_vout_AddListener().
851 * These callbacks are *not* called with the player locked. It is safe to lock
852 * the player and call any vlc_player functions from these callbacks.
854 * @note The state changed from the callbacks can be either applied on the
855 * player (and all future video outputs), or on a specified video output. The
856 * state is applied on the player when the vout argument is NULL.
858 * @warning To avoid deadlocks, users should never call vout_thread_t functions
859 * from these callbacks.
861 struct vlc_player_vout_cbs
864 * Called when the player and/or vout fullscreen state has changed
866 * @see vlc_player_vout_SetFullscreen()
868 * @param player unlocked player instance
869 * @param vout cf. vlc_player_vout_cbs note
870 * @param enabled true when fullscreen is enabled
871 * @param data opaque pointer set by vlc_player_vout_AddListener()
873 void (*on_fullscreen_changed
)(vlc_player_t
*player
,
874 vout_thread_t
*vout
, bool enabled
, void *data
);
877 * Called when the player and/or vout wallpaper mode has changed
879 * @see vlc_player_vout_SetWallpaperModeEnabled()
881 * @param player unlocked player instance
882 * @param vout cf. vlc_player_vout_cbs note
883 * @param enabled true when wallpaper mode is enabled
884 * @param data opaque pointer set by vlc_player_vout_AddListener()
886 void (*on_wallpaper_mode_changed
)(vlc_player_t
*player
,
887 vout_thread_t
*vout
, bool enabled
, void *data
);
891 * Player aout callbacks
893 * Can be registered with vlc_player_aout_AddListener().
895 * These callbacks are *not* called with the player locked. It is safe to lock
896 * the player and call any vlc_player functions from these callbacks.
898 * @warning To avoid deadlocks, users should never call audio_output_t
899 * functions from these callbacks.
901 struct vlc_player_aout_cbs
904 * Called when the volume has changed
906 * @see vlc_player_aout_SetVolume()
908 * @param player unlocked player instance
909 * @param new_volume volume in the range [0;2.f]
910 * @param data opaque pointer set by vlc_player_vout_AddListener()
912 void (*on_volume_changed
)(vlc_player_t
*player
,
913 float new_volume
, void *data
);
916 * Called when the mute state has changed
918 * @see vlc_player_aout_Mute()
920 * @param player unlocked player instance
921 * @param new_mute true if muted
922 * @param data opaque pointer set by vlc_player_vout_AddListener()
924 void (*on_mute_changed
)(vlc_player_t
*player
,
925 bool new_muted
, void *data
);
931 * This function can be used to pass a track from a callback to an other
932 * context. The es_id will be held by the duplicated track.
934 * @see vlc_player_cbs.on_track_list_changed
936 * @return a duplicated track or NULL on allocation error
938 VLC_API
struct vlc_player_track
*
939 vlc_player_track_Dup(const struct vlc_player_track
*track
);
942 * Delete a duplicated track
945 vlc_player_track_Delete(struct vlc_player_track
*track
);
948 * Duplicate a program
950 * This function can be used to pass a program from a callback to an other
953 * @see vlc_player_cbs.on_program_list_changed
955 * @return a duplicated program or NULL on allocation error
957 VLC_API
struct vlc_player_program
*
958 vlc_player_program_Dup(const struct vlc_player_program
*prgm
);
961 * Delete a duplicated program
964 vlc_player_program_Delete(struct vlc_player_program
*prgm
);
967 * Hold the title list of the player
969 * This function can be used to pass this title list from a callback to an
972 * @see vlc_player_cbs.on_titles_changed
974 * @return the same instance
976 VLC_API vlc_player_title_list
*
977 vlc_player_title_list_Hold(vlc_player_title_list
*titles
);
980 * Release of previously held title list
983 vlc_player_title_list_Release(vlc_player_title_list
*titles
);
986 * Get the number of title of a list
989 vlc_player_title_list_GetCount(vlc_player_title_list
*titles
);
992 * Get the title at a given index
994 * @param idx index in the range [0; count[
995 * @return a valid title (can't be NULL)
997 VLC_API
const struct vlc_player_title
*
998 vlc_player_title_list_GetAt(vlc_player_title_list
*titles
, size_t idx
);
1001 * Create a new player instance
1003 * @param parent parent VLC object
1004 * @param media_provider pointer to a media_provider structure or NULL, the
1005 * structure must be valid during the lifetime of the player
1006 * @param media_provider_data opaque data used by provider callbacks
1007 * @return a pointer to a valid player instance or NULL in case of error
1009 VLC_API vlc_player_t
*
1010 vlc_player_New(vlc_object_t
*parent
,
1011 const struct vlc_player_media_provider
*media_provider
,
1012 void *media_provider_data
);
1015 * Delete a player instance
1017 * This function stop any playback previously started and wait for their
1020 * @warning Blocking function if the player state is not STOPPED, don't call it
1021 * from an UI thread in that case.
1023 * @param player unlocked player instance created by vlc_player_New()
1026 vlc_player_Delete(vlc_player_t
*player
);
1031 * All player functions (except vlc_player_Delete()) need to be called while
1032 * the player lock is held.
1034 * @param player unlocked player instance
1037 vlc_player_Lock(vlc_player_t
*player
);
1042 * @param player locked player instance
1045 vlc_player_Unlock(vlc_player_t
*player
);
1048 * Wait on a condition variable
1050 * This call allow users to use their own condition with the player mutex.
1052 * @param player locked player instance
1053 * @param cond external condition
1056 vlc_player_CondWait(vlc_player_t
*player
, vlc_cond_t
*cond
);
1059 * Add a listener callback
1061 * @note Every registered callbacks need to be removed by the caller with
1062 * vlc_player_RemoveListener().
1064 * @param player locked player instance
1065 * @param cbs pointer to a vlc_player_cbs structure, the structure must be
1066 * valid during the lifetime of the player
1067 * @param cbs_data opaque pointer used by the callbacks
1068 * @return a valid listener id, or NULL in case of allocation error
1070 VLC_API vlc_player_listener_id
*
1071 vlc_player_AddListener(vlc_player_t
*player
,
1072 const struct vlc_player_cbs
*cbs
, void *cbs_data
);
1075 * Remove a listener callback
1077 * @param player locked player instance
1078 * @param listener_id listener id returned by vlc_player_AddListener()
1081 vlc_player_RemoveListener(vlc_player_t
*player
,
1082 vlc_player_listener_id
*listener_id
);
1085 * Set the current media
1087 * This function replaces the current and next medias.
1089 * @note A successful call will always result of
1090 * vlc_player_cbs.on_current_media_changed being called. This function is not
1091 * blocking. If a media is currently being played, this media will be stopped
1092 * and the requested media will be set after.
1094 * @warning This function is either synchronous (if the player state is
1095 * STOPPED) or asynchronous. In the later case, vlc_player_GetCurrentMedia()
1096 * will return the old media, even after this call, and until the
1097 * vlc_player_cbs.on_current_media_changed is called.
1099 * @param player locked player instance
1100 * @param media new media to play (will be held by the player)
1101 * @return VLC_SUCCESS or a VLC error code
1104 vlc_player_SetCurrentMedia(vlc_player_t
*player
, input_item_t
*media
);
1107 * Get the current played media.
1109 * @see vlc_player_cbs.on_current_media_changed
1111 * @param player locked player instance
1112 * @return a valid media or NULL (if no media is set)
1114 VLC_API input_item_t
*
1115 vlc_player_GetCurrentMedia(vlc_player_t
*player
);
1118 * Helper that hold the current media
1120 static inline input_item_t
*
1121 vlc_player_HoldCurrentMedia(vlc_player_t
*player
)
1123 input_item_t
*item
= vlc_player_GetCurrentMedia(player
);
1124 return item
? input_item_Hold(item
) : NULL
;
1128 * Invalidate the next media.
1130 * This function can be used to invalidate the media returned by the
1131 * vlc_player_media_provider.get_next callback. This can be used when the next
1132 * item from a playlist was changed by the user.
1134 * Calling this function will trigger the
1135 * vlc_player_media_provider.get_next callback to be called again.
1137 * @param player locked player instance
1140 vlc_player_InvalidateNextMedia(vlc_player_t
*player
);
1143 * Ask to started in a paused state
1145 * This function can be used before vlc_player_Start()
1147 * @param player locked player instance
1148 * @param start_paused true to start in a paused state, false to cancel it
1151 vlc_player_SetStartPaused(vlc_player_t
*player
, bool start_paused
);
1154 * Setup an action when a media is stopped
1156 * @param player locked player instance
1157 * @param action action to do when a media is stopped
1160 vlc_player_SetMediaStoppedAction(vlc_player_t
*player
,
1161 enum vlc_player_media_stopped_action action
);
1164 * Start the playback of the current media.
1166 * @param player locked player instance
1167 * @return VLC_SUCCESS or a VLC error code
1170 vlc_player_Start(vlc_player_t
*player
);
1173 * Stop the playback of the current media
1175 * @note This function is asynchronous. Users should wait on
1176 * STOPPED state event to know when the stop is finished.
1178 * @param player locked player instance
1181 vlc_player_Stop(vlc_player_t
*player
);
1184 * Pause the playback
1186 * @param player locked player instance
1189 vlc_player_Pause(vlc_player_t
*player
);
1192 * Resume the playback from a pause
1194 * @param player locked player instance
1197 vlc_player_Resume(vlc_player_t
*player
);
1200 * Pause and display the next video frame
1202 * @param player locked player instance
1205 vlc_player_NextVideoFrame(vlc_player_t
*player
);
1208 * Get the state of the player
1210 * @note Since all players actions are asynchronous, this function won't
1211 * reflect the new state immediately. Wait for the
1212 * vlc_players_cbs.on_state_changed event to be notified.
1214 * @see vlc_player_state
1215 * @see vlc_player_cbs.on_state_changed
1217 * @param player locked player instance
1218 * @return the current player state
1220 VLC_API
enum vlc_player_state
1221 vlc_player_GetState(vlc_player_t
*player
);
1224 * Get the error state of the player
1226 * @see vlc_player_cbs.on_capabilities_changed
1228 * @param player locked player instance
1229 * @return the current error state
1231 VLC_API
enum vlc_player_error
1232 vlc_player_GetError(vlc_player_t
*player
);
1235 * Helper to get the started state
1238 vlc_player_IsStarted(vlc_player_t
*player
)
1240 switch (vlc_player_GetState(player
))
1242 case VLC_PLAYER_STATE_STARTED
:
1243 case VLC_PLAYER_STATE_PLAYING
:
1244 case VLC_PLAYER_STATE_PAUSED
:
1252 * Helper to get the paused state
1255 vlc_player_IsPaused(vlc_player_t
*player
)
1257 return vlc_player_GetState(player
) == VLC_PLAYER_STATE_PAUSED
;
1261 * Helper to toggle the pause state
1264 vlc_player_TogglePause(vlc_player_t
*player
)
1266 if (vlc_player_IsStarted(player
))
1268 if (vlc_player_IsPaused(player
))
1269 vlc_player_Resume(player
);
1271 vlc_player_Pause(player
);
1276 * Get the player capabilities
1278 * @see vlc_player_cbs.on_capabilities_changed
1280 * @param player locked player instance
1281 * @return the player capabilities, a bitwise mask of @ref VLC_PLAYER_CAP_SEEK,
1282 * @ref VLC_PLAYER_CAP_PAUSE, @ref VLC_PLAYER_CAP_CHANGE_RATE, @ref
1283 * VLC_PLAYER_CAP_REWIND
1286 vlc_player_GetCapabilities(vlc_player_t
*player
);
1289 * Helper to get the seek capability
1292 vlc_player_CanSeek(vlc_player_t
*player
)
1294 return vlc_player_GetCapabilities(player
) & VLC_PLAYER_CAP_SEEK
;
1298 * Helper to get the pause capability
1301 vlc_player_CanPause(vlc_player_t
*player
)
1303 return vlc_player_GetCapabilities(player
) & VLC_PLAYER_CAP_PAUSE
;
1307 * Helper to get the change-rate capability
1310 vlc_player_CanChangeRate(vlc_player_t
*player
)
1312 return vlc_player_GetCapabilities(player
) & VLC_PLAYER_CAP_CHANGE_RATE
;
1316 * Helper to get the rewindable capability
1319 vlc_player_CanRewind(vlc_player_t
*player
)
1321 return vlc_player_GetCapabilities(player
) & VLC_PLAYER_CAP_REWIND
;
1325 * Get the rate of the player
1327 * @see vlc_player_cbs.on_rate_changed
1329 * @param player locked player instance
1330 * @return rate of the player (< 1.f is slower, > 1.f is faster)
1333 vlc_player_GetRate(vlc_player_t
*player
);
1336 * Change the rate of the player
1338 * @note The rate is saved across several medias
1340 * @param player locked player instance
1341 * @param rate new rate (< 1.f is slower, > 1.f is faster)
1344 vlc_player_ChangeRate(vlc_player_t
*player
, float rate
);
1347 * Increment the rate of the player (faster)
1349 * @param player locked player instance
1352 vlc_player_IncrementRate(vlc_player_t
*player
);
1355 * Decrement the rate of the player (Slower)
1357 * @param player locked player instance
1360 vlc_player_DecrementRate(vlc_player_t
*player
);
1363 * Get the length of the current media
1365 * @note A started and playing media doesn't have necessarily a valid length.
1367 * @see vlc_player_cbs.on_length_changed
1369 * @param player locked player instance
1370 * @return a valid length or VLC_TICK_INVALID (if no media is set,
1371 * playback is not yet started or in case of error)
1374 vlc_player_GetLength(vlc_player_t
*player
);
1377 * Get the time of the current media
1379 * @note A started and playing media doesn't have necessarily a valid time.
1381 * @see vlc_player_cbs.vlc_player_cbs.on_position_changed
1383 * @param player locked player instance
1384 * @return a valid time or VLC_TICK_INVALID (if no media is set, the media
1385 * doesn't have any time, if playback is not yet started or in case of error)
1388 vlc_player_GetTime(vlc_player_t
*player
);
1391 * Get the position of the current media
1393 * @see vlc_player_cbs.on_position_changed
1395 * @param player locked player instance
1396 * @return a valid position in the range [0.f;1.f] or -1.f (if no media is
1397 * set,if playback is not yet started or in case of error)
1400 vlc_player_GetPosition(vlc_player_t
*player
);
1403 * Seek the current media by position
1405 * @note This function can be called before vlc_player_Start() in order to set
1406 * a starting position.
1408 * @param player locked player instance
1409 * @param position position in the range [0.f;1.f]
1410 * @param speed precise of fast
1411 * @param whence absolute or relative
1414 vlc_player_SeekByPos(vlc_player_t
*player
, float position
,
1415 enum vlc_player_seek_speed speed
,
1416 enum vlc_player_whence whence
);
1419 * Seek the current media by time
1421 * @note This function can be called before vlc_player_Start() in order to set
1422 * a starting position.
1424 * @warning This function has an effect only if the media has a valid length.
1426 * @param player locked player instance
1427 * @param time a time in the range [0;length]
1428 * @param speed precise of fast
1429 * @param whence absolute or relative
1432 vlc_player_SeekByTime(vlc_player_t
*player
, vlc_tick_t time
,
1433 enum vlc_player_seek_speed speed
,
1434 enum vlc_player_whence whence
);
1437 * Helper to set the absolute position precisely
1440 vlc_player_SetPosition(vlc_player_t
*player
, float position
)
1442 vlc_player_SeekByPos(player
, position
, VLC_PLAYER_SEEK_PRECISE
,
1443 VLC_PLAYER_WHENCE_ABSOLUTE
);
1447 * Helper to set the absolute position fast
1450 vlc_player_SetPositionFast(vlc_player_t
*player
, float position
)
1452 vlc_player_SeekByPos(player
, position
, VLC_PLAYER_SEEK_FAST
,
1453 VLC_PLAYER_WHENCE_ABSOLUTE
);
1457 * Helper to jump the position precisely
1460 vlc_player_JumpPos(vlc_player_t
*player
, float jumppos
)
1462 /* No fask seek for jumps. Indeed, jumps can seek to the current position
1463 * if not precise enough or if the jump value is too small. */
1464 vlc_player_SeekByPos(player
, jumppos
, VLC_PLAYER_SEEK_PRECISE
,
1465 VLC_PLAYER_WHENCE_RELATIVE
);
1469 * Helper to set the absolute time precisely
1472 vlc_player_SetTime(vlc_player_t
*player
, vlc_tick_t time
)
1474 vlc_player_SeekByTime(player
, time
, VLC_PLAYER_SEEK_PRECISE
,
1475 VLC_PLAYER_WHENCE_ABSOLUTE
);
1479 * Helper to set the absolute time fast
1482 vlc_player_SetTimeFast(vlc_player_t
*player
, vlc_tick_t time
)
1484 vlc_player_SeekByTime(player
, time
, VLC_PLAYER_SEEK_FAST
,
1485 VLC_PLAYER_WHENCE_ABSOLUTE
);
1489 * Helper to jump the time precisely
1492 vlc_player_JumpTime(vlc_player_t
*player
, vlc_tick_t jumptime
)
1494 /* No fask seek for jumps. Indeed, jumps can seek to the current position
1495 * if not precise enough or if the jump value is too small. */
1496 vlc_player_SeekByTime(player
, jumptime
, VLC_PLAYER_SEEK_PRECISE
,
1497 VLC_PLAYER_WHENCE_RELATIVE
);
1501 * Display the player position on the vout OSD
1503 * @param player locked player instance
1506 vlc_player_DisplayPosition(vlc_player_t
*player
);
1509 * Enable A to B loop of the current media
1511 * This function need to be called 2 times with VLC_PLAYER_ABLOOP_A and
1512 * VLC_PLAYER_ABLOOP_B to setup an A to B loop. It current the current
1513 * time/position when called. The B time must be higher than the A time.
1515 * @param player locked player instance
1516 * @return VLC_SUCCESS or a VLC error code
1519 vlc_player_SetAtoBLoop(vlc_player_t
*player
, enum vlc_player_abloop abloop
);
1522 * Get the A to B loop status
1524 * @note If the returned status is VLC_PLAYER_ABLOOP_A, then a_time and a_pos
1525 * will be valid. If the returned status is VLC_PLAYER_ABLOOP_B, then all
1526 * output parameters are valid. If the returned status is
1527 * VLC_PLAYER_ABLOOP_NONE, then all output parameters are invalid.
1529 * @see vlc_player_cbs.on_atobloop_changed
1531 * @param player locked player instance
1532 * @param a_time A time or VLC_TICK_INVALID (if the media doesn't have valid
1534 * @param a_pos A position
1535 * @param b_time B time or VLC_TICK_INVALID (if the media doesn't have valid
1537 * @param b_pos B position
1538 * @return A to B loop status
1540 VLC_API
enum vlc_player_abloop
1541 vlc_player_GetAtoBLoop(vlc_player_t
*player
, vlc_tick_t
*a_time
, float *a_pos
,
1542 vlc_tick_t
*b_time
, float *b_pos
);
1545 * Get the number of tracks for an ES category
1547 * @warning The returned size becomes invalid when the player is unlocked.
1549 * @param player locked player instance
1550 * @param cat VIDEO_ES, AUDIO_ES or SPU_ES
1551 * @return number of tracks, or 0 (in case of error, or if the media is not
1555 vlc_player_GetTrackCount(vlc_player_t
*player
, enum es_format_category_e cat
);
1558 * Get the track at a specific index for an ES category
1560 * @warning The behaviour is undefined if the index is not valid.
1562 * @warning The returned pointer becomes invalid when the player is unlocked.
1563 * The referenced structure can be safely copied with vlc_player_track_Dup().
1565 * @param player locked player instance
1566 * @param cat VIDEO_ES, AUDIO_ES or SPU_ES
1567 * @param index valid index in the range [0; count[
1568 * @return a valid track (can't be NULL if vlc_player_GetTrackCount() returned
1571 VLC_API
const struct vlc_player_track
*
1572 vlc_player_GetTrackAt(vlc_player_t
*player
, enum es_format_category_e cat
,
1576 * Helper to get the video track count
1578 static inline size_t
1579 vlc_player_GetVideoTrackCount(vlc_player_t
*player
)
1581 return vlc_player_GetTrackCount(player
, VIDEO_ES
);
1585 * Helper to get a video track at a specific index
1587 static inline const struct vlc_player_track
*
1588 vlc_player_GetVideoTrackAt(vlc_player_t
*player
, size_t index
)
1590 return vlc_player_GetTrackAt(player
, VIDEO_ES
, index
);
1594 * Helper to get the audio track count
1596 static inline size_t
1597 vlc_player_GetAudioTrackCount(vlc_player_t
*player
)
1599 return vlc_player_GetTrackCount(player
, AUDIO_ES
);
1603 * Helper to get an audio track at a specific index
1605 static inline const struct vlc_player_track
*
1606 vlc_player_GetAudioTrackAt(vlc_player_t
*player
, size_t index
)
1608 return vlc_player_GetTrackAt(player
, AUDIO_ES
, index
);
1612 * Helper to get the subtitle track count
1614 static inline size_t
1615 vlc_player_GetSubtitleTrackCount(vlc_player_t
*player
)
1617 return vlc_player_GetTrackCount(player
, SPU_ES
);
1621 * Helper to get a subtitle track at a specific index
1623 static inline const struct vlc_player_track
*
1624 vlc_player_GetSubtitleTrackAt(vlc_player_t
*player
, size_t index
)
1626 return vlc_player_GetTrackAt(player
, SPU_ES
, index
);
1630 * Get a track from an ES identifier
1632 * @warning The returned pointer becomes invalid when the player is unlocked.
1633 * The referenced structure can be safely copied with vlc_player_track_Dup().
1635 * @param player locked player instance
1636 * @param id an ES ID (retrieved from vlc_player_cbs.on_track_list_changed or
1637 * vlc_player_GetTrackAt())
1638 * @return a valid player track or NULL (if the track was terminated by the
1641 VLC_API
const struct vlc_player_track
*
1642 vlc_player_GetTrack(vlc_player_t
*player
, vlc_es_id_t
*es_id
);
1645 * Helper to get the selected track from an ES category
1647 * @warning The player can have more than one selected track for a same ES
1648 * category. This function will only return the first selected one. Use
1649 * vlc_player_GetTrackAt() and vlc_player_GetTrackCount() to iterate through
1650 * several selected tracks.
1652 static inline const struct vlc_player_track
*
1653 vlc_player_GetSelectedTrack(vlc_player_t
*player
, enum es_format_category_e cat
)
1655 size_t count
= vlc_player_GetTrackCount(player
, cat
);
1656 for (size_t i
= 0; i
< count
; ++i
)
1658 const struct vlc_player_track
*track
=
1659 vlc_player_GetTrackAt(player
, cat
, i
);
1661 if (track
->selected
)
1668 * Select a track from an ES identifier
1670 * @note A successful call will trigger the
1671 * vlc_player_cbs.on_track_selection_changed event.
1673 * @param player locked player instance
1674 * @param id an ES ID (retrieved from vlc_player_cbs.on_track_list_changed or
1675 * vlc_player_GetTrackAt())
1678 vlc_player_SelectTrack(vlc_player_t
*player
, vlc_es_id_t
*es_id
);
1681 * Select the next track
1683 * If the last track is already selected, a call to this function will disable
1684 * this last track. And a second call will select the first track.
1686 * @warning This function has no effects if there are several tracks selected
1687 * for a same category.
1689 * @param player locked player instance
1690 * @param cat VIDEO_ES, AUDIO_ES or SPU_ES
1693 vlc_player_SelectNextTrack(vlc_player_t
*player
,
1694 enum es_format_category_e cat
);
1697 * Select the Previous track
1699 * If the first track is already selected, a call to this function will disable
1700 * this first track. And a second call will select the last track.
1702 * @warning This function has no effects if there are several tracks selected
1703 * for a same category.
1705 * @param player locked player instance
1706 * @param cat VIDEO_ES, AUDIO_ES or SPU_ES
1709 vlc_player_SelectPrevTrack(vlc_player_t
*player
,
1710 enum es_format_category_e cat
);
1713 * Unselect a track from an ES identifier
1715 * @note A successful call will trigger the
1716 * vlc_player_cbs.on_track_selection_changed event.
1718 * @param player locked player instance
1719 * @param id an ES ID (retrieved from vlc_player_cbs.on_track_list_changed or
1720 * vlc_player_GetTrackAt())
1723 vlc_player_UnselectTrack(vlc_player_t
*player
, vlc_es_id_t
*es_id
);
1726 * Helper to unselect all tracks from an ES category
1729 vlc_player_UnselectTrackCategory(vlc_player_t
*player
,
1730 enum es_format_category_e cat
)
1732 size_t count
= vlc_player_GetTrackCount(player
, cat
);
1733 for (size_t i
= 0; i
< count
; ++i
)
1735 const struct vlc_player_track
*track
=
1736 vlc_player_GetTrackAt(player
, cat
, i
);
1738 if (track
->selected
)
1739 vlc_player_UnselectTrack(player
, track
->es_id
);
1744 * Restart a track from an ES identifier
1746 * @note A successful call will trigger the
1747 * vlc_player_cbs.on_track_selection_changed event.
1749 * @param player locked player instance
1750 * @param id an ES ID (retrieved from vlc_player_cbs.on_track_list_changed or
1751 * vlc_player_GetTrackAt())
1754 vlc_player_RestartTrack(vlc_player_t
*player
, vlc_es_id_t
*es_id
);
1757 * Helper to restart all selected tracks from an ES category
1760 vlc_player_RestartTrackCategory(vlc_player_t
*player
,
1761 enum es_format_category_e cat
)
1763 size_t count
= vlc_player_GetTrackCount(player
, cat
);
1764 for (size_t i
= 0; i
< count
; ++i
)
1766 const struct vlc_player_track
*track
=
1767 vlc_player_GetTrackAt(player
, cat
, i
);
1769 if (track
->selected
)
1770 vlc_player_RestartTrack(player
, track
->es_id
);
1775 * Select the default track for an ES category.
1777 * Tracks for this category will be automatically chosen according to the
1778 * language for all future played media.
1780 * @param player locked player instance
1781 * @param cat VIDEO_ES, AUDIO_ES or SPU_ES
1782 * @param lang language (TODO: define it) or NULL to reset the default state
1785 vlc_player_SelectDefaultTrack(vlc_player_t
*player
,
1786 enum es_format_category_e cat
, const char *lang
);
1789 * Helper to select the default video track
1792 vlc_player_SelectDefaultVideoTrack(vlc_player_t
*player
, const char *lang
)
1794 vlc_player_SelectDefaultTrack(player
, VIDEO_ES
, lang
);
1798 * Helper to select the default audio track
1801 vlc_player_SelectDefaultAudioTrack(vlc_player_t
*player
, const char *lang
)
1803 vlc_player_SelectDefaultTrack(player
, AUDIO_ES
, lang
);
1807 * Helper to select the default spu track
1810 vlc_player_SelectDefaultSubtitleTrack(vlc_player_t
*player
, const char *lang
)
1812 vlc_player_SelectDefaultTrack(player
, SPU_ES
, lang
);
1816 * Enable or disable a track category
1818 * If a track category is disabled, the player won't select any tracks of this
1819 * category automatically or via an user action (vlc_player_SelectTrack()).
1821 * @param player locked player instance
1822 * @param cat VIDEO_ES, AUDIO_ES or SPU_ES
1823 * @param enabled true to enable
1826 vlc_player_SetTrackCategoryEnabled(vlc_player_t
*player
,
1827 enum es_format_category_e cat
, bool enabled
);
1830 * Check if a track category is enabled
1832 * @param player locked player instance
1833 * @param cat VIDEO_ES, AUDIO_ES or SPU_ES
1836 vlc_player_IsTrackCategoryEnabled(vlc_player_t
*player
,
1837 enum es_format_category_e cat
);
1840 * Helper to enable or disable video tracks
1843 vlc_player_SetVideoEnabled(vlc_player_t
*player
, bool enabled
)
1845 vlc_player_SetTrackCategoryEnabled(player
, VIDEO_ES
, enabled
);
1849 * Helper to check if video tracks are enabled
1852 vlc_player_IsVideoEnabled(vlc_player_t
*player
)
1854 return vlc_player_IsTrackCategoryEnabled(player
, VIDEO_ES
);
1858 * Helper to enable or disable audio tracks
1861 vlc_player_SetAudioEnabled(vlc_player_t
*player
, bool enabled
)
1863 vlc_player_SetTrackCategoryEnabled(player
, AUDIO_ES
, enabled
);
1867 * Helper to check if audio tracks are enabled
1870 vlc_player_IsAudioEnabled(vlc_player_t
*player
)
1872 return vlc_player_IsTrackCategoryEnabled(player
, AUDIO_ES
);
1876 * Helper to enable or disable subtitle tracks
1879 vlc_player_SetSubtitleEnabled(vlc_player_t
*player
, bool enabled
)
1881 vlc_player_SetTrackCategoryEnabled(player
, SPU_ES
, enabled
);
1885 * Helper to check if subtitle tracks are enabled
1888 vlc_player_IsSubtitleEnabled(vlc_player_t
*player
)
1890 return vlc_player_IsTrackCategoryEnabled(player
, SPU_ES
);
1894 * Helper to toggle subtitles
1897 vlc_player_ToggleSubtitle(vlc_player_t
*player
)
1899 bool enabled
= !vlc_player_IsSubtitleEnabled(player
);
1900 return vlc_player_SetSubtitleEnabled(player
, enabled
);
1904 * Get the number of programs
1906 * @warning The returned size becomes invalid when the player is unlocked.
1908 * @param player locked player instance
1909 * @return number of programs, or 0 (in case of error, or if the media is not
1913 vlc_player_GetProgramCount(vlc_player_t
*player
);
1916 * Get the program at a specific index
1918 * @warning The behaviour is undefined if the index is not valid.
1920 * @warning The returned pointer becomes invalid when the player is unlocked.
1921 * The referenced structure can be safely copied with vlc_player_program_Dup().
1923 * @param player locked player instance
1924 * @param index valid index in the range [0; count[
1925 * @return a valid program (can't be NULL if vlc_player_GetProgramCount()
1926 * returned a valid count)
1928 VLC_API
const struct vlc_player_program
*
1929 vlc_player_GetProgramAt(vlc_player_t
*player
, size_t index
);
1932 * Get a program from an ES group identifier
1934 * @param player locked player instance
1935 * @param group_id a program ID (retrieved from
1936 * vlc_player_cbs.on_program_list_changed or vlc_player_GetProgramAt())
1937 * @return a valid program or NULL (if the program was terminated by the
1940 VLC_API
const struct vlc_player_program
*
1941 vlc_player_GetProgram(vlc_player_t
*player
, int group_id
);
1944 * Select a program from an ES group identifier
1946 * @param player locked player instance
1947 * @param group_id a program ID (retrieved from
1948 * vlc_player_cbs.on_program_list_changed or vlc_player_GetProgramAt())
1951 vlc_player_SelectProgram(vlc_player_t
*player
, int group_id
);
1954 * Select the next program
1956 * @param player locked player instance
1959 vlc_player_SelectNextProgram(vlc_player_t
*player
);
1962 * Select the previous program
1964 * @param player locked player instance
1967 vlc_player_SelectPrevProgram(vlc_player_t
*player
);
1970 * Check if the media has a teletext menu
1972 * @see vlc_player_cbs.on_teletext_menu_changed
1974 * @param player locked player instance
1975 * @return true if the media has a teletext menu
1978 vlc_player_HasTeletextMenu(vlc_player_t
*player
);
1981 * Enable or disable teletext
1983 * This function has an effect only if the player has a teletext menu.
1985 * @note A successful call will trigger the
1986 * vlc_player_cbs.on_teletext_enabled_changed event.
1988 * @param player locked player instance
1989 * @param enabled true to enable
1992 vlc_player_SetTeletextEnabled(vlc_player_t
*player
, bool enabled
);
1995 * Check if teletext is enabled
1997 * @see vlc_player_cbs.on_teletext_enabled_changed
1999 * @param player locked player instance
2002 vlc_player_IsTeletextEnabled(vlc_player_t
*player
);
2005 * Select a teletext page or do an action from a key
2007 * This function has an effect only if the player has a teletext menu.
2009 * @note Page keys can be the following: @ref VLC_PLAYER_TELETEXT_KEY_RED,
2010 * @ref VLC_PLAYER_TELETEXT_KEY_GREEN, @ref VLC_PLAYER_TELETEXT_KEY_YELLOW,
2011 * @ref VLC_PLAYER_TELETEXT_KEY_BLUE or @ref VLC_PLAYER_TELETEXT_KEY_INDEX.
2013 * @note A successful call will trigger the
2014 * vlc_player_cbs.on_teletext_page_changed event.
2016 * @param player locked player instance
2017 * @param page a page in the range ]0;888] or a valid key
2020 vlc_player_SelectTeletextPage(vlc_player_t
*player
, unsigned page
);
2023 * Get the current teletext page
2025 * @see vlc_player_cbs.on_teletext_page_changed
2027 * @param player locked player instance
2030 vlc_player_GetTeletextPage(vlc_player_t
*player
);
2033 * Enable or disable teletext transparency
2035 * This function has an effect only if the player has a teletext menu.
2037 * @note A successful call will trigger the
2038 * vlc_player_cbs.on_teletext_transparency_changed event.
2040 * @param player locked player instance
2041 * @param enabled true to enable
2044 vlc_player_SetTeletextTransparency(vlc_player_t
*player
, bool enabled
);
2047 * Check if teletext is transparent
2049 * @param player locked player instance
2052 vlc_player_IsTeletextTransparent(vlc_player_t
*player
);
2055 * Get the title list of the current media
2057 * @see vlc_player_cbs.on_titles_changed
2059 * @param player locked player instance
2061 VLC_API vlc_player_title_list
*
2062 vlc_player_GetTitleList(vlc_player_t
*player
);
2065 * Get the selected title index for the current media
2067 * @see vlc_player_cbs.on_title_selection_changed
2069 * @param player locked player instance
2072 vlc_player_GetSelectedTitleIdx(vlc_player_t
*player
);
2075 * Helper to get the current selected title
2077 static inline const struct vlc_player_title
*
2078 vlc_player_GetSelectedTitle(vlc_player_t
*player
)
2080 vlc_player_title_list
*titles
= vlc_player_GetTitleList(player
);
2083 ssize_t selected_idx
= vlc_player_GetSelectedTitleIdx(player
);
2084 if (selected_idx
< 0)
2086 return vlc_player_title_list_GetAt(titles
, selected_idx
);
2090 * Select a title index for the current media
2092 * @note A successful call will trigger the
2093 * vlc_player_cbs.on_title_selection_changed event.
2095 * @see vlc_player_title_list_GetAt()
2096 * @see vlc_player_title_list_GetCount()
2098 * @param player locked player instance
2099 * @param index valid index in the range [0;count[
2102 vlc_player_SelectTitleIdx(vlc_player_t
*player
, size_t index
);
2105 * Select a title for the current media
2107 * @note A successful call will trigger the
2108 * vlc_player_cbs.on_title_selection_changed event.
2110 * @see vlc_player_title_list_GetAt()
2111 * @see vlc_player_title_list_GetCount()
2113 * @param player locked player instance
2114 * @param title a valid title coming from the vlc_player_title_list
2117 vlc_player_SelectTitle(vlc_player_t
*player
,
2118 const struct vlc_player_title
*title
);
2121 * Select a chapter for the current media
2123 * @note A successful call will trigger the
2124 * vlc_player_cbs.on_chapter_selection_changed event.
2126 * @param player locked player instance
2127 * @param title the selected title
2128 * @param chapter_idx index from vlc_player_title.chapters
2131 vlc_player_SelectChapter(vlc_player_t
*player
,
2132 const struct vlc_player_title
*title
,
2133 size_t chapter_idx
);
2136 * Select the next title for the current media
2138 * @see vlc_player_SelectTitleIdx()
2141 vlc_player_SelectNextTitle(vlc_player_t
*player
);
2144 * Select the previous title for the current media
2146 * @see vlc_player_SelectTitleIdx()
2149 vlc_player_SelectPrevTitle(vlc_player_t
*player
);
2152 * Get the selected chapter index for the current media
2154 * @see vlc_player_cbs.on_chapter_selection_changed
2156 * @param player locked player instance
2159 vlc_player_GetSelectedChapterIdx(vlc_player_t
*player
);
2162 * Helper to get the current selected chapter
2164 static inline const struct vlc_player_chapter
*
2165 vlc_player_GetSelectedChapter(vlc_player_t
*player
)
2167 const struct vlc_player_title
*title
= vlc_player_GetSelectedTitle(player
);
2168 if (!title
|| !title
->chapter_count
)
2170 ssize_t chapter_idx
= vlc_player_GetSelectedChapterIdx(player
);
2171 return chapter_idx
>= 0 ? &title
->chapters
[chapter_idx
] : NULL
;
2175 * Select a chapter index for the current media
2177 * @note A successful call will trigger the
2178 * vlc_player_cbs.on_chaper_selection_changed event.
2180 * @see vlc_player_title.chapters
2182 * @param player locked player instance
2183 * @param index valid index in the range [0;vlc_player_title.chapter_count[
2186 vlc_player_SelectChapterIdx(vlc_player_t
*player
, size_t index
);
2189 * Select the next chapter for the current media
2191 * @see vlc_player_SelectChapterIdx()
2194 vlc_player_SelectNextChapter(vlc_player_t
*player
);
2197 * Select the previous chapter for the current media
2199 * @see vlc_player_SelectChapterIdx()
2202 vlc_player_SelectPrevChapter(vlc_player_t
*player
);
2205 * Add an associated (or external) media to the current media
2207 * @param player locked player instance
2208 * @param cat AUDIO_ES or SPU_ES
2209 * @param uri absolute uri of the external media
2210 * @param select true to select the track of this external media
2211 * @param notify true to notify the OSD
2212 * @param check_ext true to check subtitles extension
2215 vlc_player_AddAssociatedMedia(vlc_player_t
*player
,
2216 enum es_format_category_e cat
, const char *uri
,
2217 bool select
, bool notify
, bool check_ext
);
2220 * Set the associated subtitle FPS
2222 * In order to correct the rate of the associated media according to this FPS
2223 * and the media video FPS.
2225 * @note A successful call will trigger the
2226 * vlc_player_cbs.on_associated_subs_fps_changed event.
2228 * @warning this function will change the rate of all external subtitle files
2229 * associated with the current media.
2231 * @param player locked player instance
2232 * @param fps FPS of the subtitle file
2235 vlc_player_SetAssociatedSubsFPS(vlc_player_t
*player
, float fps
);
2238 * Get the associated subtitle FPS
2240 * @param player locked player instance
2244 vlc_player_GetAssociatedSubsFPS(vlc_player_t
*player
);
2249 * Valid for the current media and all future ones.
2251 * @note A successful call will trigger the vlc_player_cbs.on_renderer_changed
2254 * @param player locked player instance
2255 * @param renderer a valid renderer item or NULL (to disable it), the item will
2256 * be held by the player
2259 vlc_player_SetRenderer(vlc_player_t
*player
, vlc_renderer_item_t
*renderer
);
2264 * @see vlc_player_cbs.on_renderer_changed
2266 * @param player locked player instance
2267 * @return the renderer item set by vlc_player_SetRenderer()
2269 VLC_API vlc_renderer_item_t
*
2270 vlc_player_GetRenderer(vlc_player_t
*player
);
2273 * Navigate (for DVD/Bluray menus or viewpoint)
2275 * @param player locked player instance
2276 * @param nav navigation key
2279 vlc_player_Navigate(vlc_player_t
*player
, enum vlc_player_nav nav
);
2282 * Update the viewpoint
2284 * @param player locked player instance
2285 * @param viewpoint the viewpoint value
2286 * @param whence absolute or relative
2287 * @return VLC_SUCCESS or a VLC error code
2290 vlc_player_UpdateViewpoint(vlc_player_t
*player
,
2291 const vlc_viewpoint_t
*viewpoint
,
2292 enum vlc_player_whence whence
);
2295 * Check if the playing is recording
2297 * @see vlc_player_cbs.on_recording_changed
2299 * @param player locked player instance
2300 * @return true if the player is recording
2303 vlc_player_IsRecording(vlc_player_t
*player
);
2306 * Enable or disable recording for the current media
2308 * @note A successful call will trigger the vlc_player_cbs.on_recording_changed
2311 * @param player locked player instance
2312 * @param enabled true to enable recording
2315 vlc_player_SetRecordingEnabled(vlc_player_t
*player
, bool enabled
);
2318 * Helper to toggle the recording state
2321 vlc_player_ToggleRecording(vlc_player_t
*player
)
2323 vlc_player_SetRecordingEnabled(player
, !vlc_player_IsRecording(player
));
2327 * Get the audio delay for the current media
2329 * @see vlc_player_cbs.on_audio_delay_changed
2331 * @param player locked player instance
2334 vlc_player_GetAudioDelay(vlc_player_t
*player
);
2337 * Set the audio delay for the current media
2339 * @note A successful call will trigger the
2340 * vlc_player_cbs.on_audio_delay_changed event.
2342 * @param player locked player instance
2343 * @param delay a valid time
2344 * @param whence absolute or relative
2347 vlc_player_SetAudioDelay(vlc_player_t
*player
, vlc_tick_t delay
,
2348 enum vlc_player_whence whence
);
2351 * Get the subtitle delay for the current media
2353 * @see vlc_player_cbs.on_subtitle_delay_changed
2355 * @param player locked player instance
2358 vlc_player_GetSubtitleDelay(vlc_player_t
*player
);
2361 * Set subtitle synchronisation
2363 * This function can be used to synchronise subtitles with the audio.
2365 * Call this function with VLC_PLAYER_SUBTITLE_SYNC_MARK_AUDIO when your hear a
2366 * voice you want to synchronise with subtitles. Then, call this function with
2367 * VLC_PLAYER_SUBTITLE_SYNC_MARK_SUBTITLE when the subtitle corresponding to
2368 * the voice is displayed. Finally call this function with
2369 * VLC_PLAYER_SUBTITLE_SYNC_APPLY to apply the subtitle delay. Calling this
2370 * function with VLC_PLAYER_SUBTITLE_SYNC_RESET will reset the subtitle
2371 * synchronisation and set a subtitle delay of 0.
2373 * @param player locked player instance
2374 * @param sync synchronisation action
2377 vlc_player_SetSubtitleSync(vlc_player_t
*player
,
2378 enum vlc_player_subtitle_sync sync
);
2381 * Set the subtitle delay for the current media
2383 * @note A successful call will trigger the
2384 * vlc_player_cbs.on_subtitle_delay_changed event.
2386 * @param player locked player instance
2387 * @param delay a valid time
2388 * @param whence absolute or relative
2391 vlc_player_SetSubtitleDelay(vlc_player_t
*player
, vlc_tick_t delay
,
2392 enum vlc_player_whence whence
);
2395 * Set the subtitle text scaling factor
2397 * @note This function have an effect only if the subtitle track is a text type.
2399 * @param player locked player instance
2400 * @param scale factor in the range [10;500] (default: 100)
2403 vlc_player_SetSubtitleTextScale(vlc_player_t
*player
, unsigned scale
);
2406 * Get the subtitle text scaling factor
2408 * @param player locked player instance
2409 * @return scale factor
2412 vlc_player_GetSubtitleTextScale(vlc_player_t
*player
);
2415 * Get the signal quality and strength of the current media
2417 * @param player locked player instance
2420 vlc_player_GetSignal(vlc_player_t
*player
, float *quality
, float *strength
);
2423 * Get the statistics of the current media
2425 * @warning The returned pointer becomes invalid when the player is unlocked.
2426 * The referenced structure can be safely copied.
2428 * @see vlc_player_cbs.on_statistics_changed
2430 * @param player locked player instance
2431 * @return pointer to the player stats structure or NULL
2433 VLC_API
const struct input_stats_t
*
2434 vlc_player_GetStatistics(vlc_player_t
*player
);
2437 * Enable or disable pause on cork event
2439 * If enabled, the player will automatically pause and resume on cork events.
2440 * In that case, cork events won't be propagated via callbacks.
2441 * @see vlc_player_cbs.on_cork_changed
2443 * @param player locked player instance
2444 * @param enabled true to enable
2447 vlc_player_SetPauseOnCork(vlc_player_t
*player
, bool enabled
);
2450 * Get the audio output
2452 * @warning The returned pointer must be released with vlc_object_release().
2454 * @param player player instance
2455 * @return a valid audio_output_t * or NULL (if there is no aouts)
2457 VLC_API audio_output_t
*
2458 vlc_player_aout_Hold(vlc_player_t
*player
);
2461 * Add a listener callback for audio output events
2463 * @note The player instance doesn't need to be locked for vlc_player_aout_*()
2465 * @note Every registered callbacks need to be removed by the caller with
2466 * vlc_player_aout_RemoveListener().
2468 * @param player player instance
2469 * @param cbs pointer to a vlc_player_aout_cbs structure, the structure must be
2470 * valid during the lifetime of the player
2471 * @param cbs_data opaque pointer used by the callbacks
2472 * @return a valid listener id, or NULL in case of allocation error
2474 VLC_API vlc_player_aout_listener_id
*
2475 vlc_player_aout_AddListener(vlc_player_t
*player
,
2476 const struct vlc_player_aout_cbs
*cbs
,
2480 * Remove a aout listener callback
2482 * @param player player instance
2483 * @param listener_id listener id returned by vlc_player_aout_AddListener()
2486 vlc_player_aout_RemoveListener(vlc_player_t
*player
,
2487 vlc_player_aout_listener_id
*listener_id
);
2490 * Get the audio volume
2492 * @note The player instance doesn't need to be locked for vlc_player_aout_*()
2495 * @see vlc_player_aout_cbs.on_volume_changed
2497 * @param player player instance
2498 * @return volume in the range [0;2.f] or -1.f if there is no audio outputs
2499 * (independent of mute)
2502 vlc_player_aout_GetVolume(vlc_player_t
*player
);
2505 * Set the audio volume
2507 * @note The player instance doesn't need to be locked for vlc_player_aout_*()
2510 * @note A successful call will trigger the
2511 * vlc_player_vout_cbs.on_volume_changed event.
2513 * @param player player instance
2514 * @param volume volume in the range [0;2.f]
2515 * @return VLC_SUCCESS or VLC_EGENERIC if there is no audio outputs
2518 vlc_player_aout_SetVolume(vlc_player_t
*player
, float volume
);
2521 * Increment the audio volume
2523 * @see vlc_player_aout_SetVolume()
2525 * @param player player instance
2526 * @param steps number of "volume-step"
2527 * @param result pointer to store the resulting volume (can be NULL)
2528 * @return VLC_SUCCESS or VLC_EGENERIC if there is no audio outputs
2531 vlc_player_aout_IncrementVolume(vlc_player_t
*player
, int steps
, float *result
);
2534 * Helper to decrement the audio volume
2537 vlc_player_aout_DecrementVolume(vlc_player_t
*player
, int steps
, float *result
)
2539 return vlc_player_aout_IncrementVolume(player
, -steps
, result
);
2543 * Check if the audio output is muted
2545 * @note The player instance doesn't need to be locked for vlc_player_aout_*()
2548 * @see vlc_player_aout_cbs.on_mute_changed
2550 * @param player player instance
2551 * @return 0 if not muted, 1 if muted, -1 if there is no audio outputs
2554 vlc_player_aout_IsMuted(vlc_player_t
*player
);
2557 * Mute or unmute the audio output
2559 * @note The player instance doesn't need to be locked for vlc_player_aout_*()
2562 * @note A successful call will trigger the
2563 * vlc_player_aout_cbs.on_mute_changed event.
2565 * @param player player instance
2566 * @param mute true to mute
2567 * @return VLC_SUCCESS or VLC_EGENERIC if there is no audio outputs
2570 vlc_player_aout_Mute(vlc_player_t
*player
, bool mute
);
2573 * Helper to toggle the mute state
2576 vlc_player_aout_ToggleMute(vlc_player_t
*player
)
2578 return vlc_player_aout_Mute(player
,
2579 !vlc_player_aout_IsMuted(player
));
2583 * Enable or disable an audio filter
2585 * @see aout_EnableFilter()
2587 * @return VLC_SUCCESS or VLC_EGENERIC if there is no audio outputs
2590 vlc_player_aout_EnableFilter(vlc_player_t
*player
, const char *name
, bool add
);
2593 * Get and hold the main video output
2595 * @warning the returned vout_thread_t * must be released with
2596 * vlc_object_release().
2597 * @see vlc_players_cbs.on_vout_list_changed
2599 * @param player player instance
2600 * @return a valid vout_thread_t * or NULL, cf. warning
2602 VLC_API vout_thread_t
*
2603 vlc_player_vout_Hold(vlc_player_t
*player
);
2606 * Get and hold the list of video output
2608 * @warning All vout_thread_t * element of the array must be released with
2609 * vlc_object_release(). The returned array must be freed.
2611 * @see vlc_players_cbs.on_vout_list_changed
2613 * @param player player instance
2614 * @param count valid pointer to store the array count
2615 * @return a array of vout_thread_t * or NULL, cf. warning
2617 VLC_API vout_thread_t
**
2618 vlc_player_vout_HoldAll(vlc_player_t
*player
, size_t *count
);
2621 * Add a listener callback for video output events
2623 * @note The player instance doesn't need to be locked for vlc_player_vout_*()
2625 * @note Every registered callbacks need to be removed by the caller with
2626 * vlc_player_vout_RemoveListener().
2628 * @param player player instance
2629 * @param cbs pointer to a vlc_player_vout_cbs structure, the structure must be
2630 * valid during the lifetime of the player
2631 * @param cbs_data opaque pointer used by the callbacks
2632 * @return a valid listener id, or NULL in case of allocation error
2634 VLC_API vlc_player_vout_listener_id
*
2635 vlc_player_vout_AddListener(vlc_player_t
*player
,
2636 const struct vlc_player_vout_cbs
*cbs
,
2640 * Remove a vout listener callback
2642 * @param player player instance
2643 * @param listener_id listener id returned by vlc_player_vout_AddListener()
2646 vlc_player_vout_RemoveListener(vlc_player_t
*player
,
2647 vlc_player_vout_listener_id
*listener_id
);
2650 * Check if the player is fullscreen
2652 * @warning The fullscreen state of the player and all vouts can be different.
2654 * @note The player instance doesn't need to be locked for vlc_player_vout_*()
2657 * @see vlc_player_vout_cbs.on_fullscreen_changed
2659 * @param player player instance
2660 * @return true if the player is fullscreen
2663 vlc_player_vout_IsFullscreen(vlc_player_t
*player
);
2666 * Enable or disable the player fullscreen state
2668 * This will have an effect on all current and future vouts.
2670 * @note The player instance doesn't need to be locked for vlc_player_vout_*()
2672 * @note A successful call will trigger the
2673 * vlc_player_vout_cbs.on_fullscreen_changed event.
2675 * @param player player instance
2676 * @param enabled true to enable fullscreen
2679 vlc_player_vout_SetFullscreen(vlc_player_t
*player
, bool enabled
);
2682 * Helper to toggle the player fullscreen state
2685 vlc_player_vout_ToggleFullscreen(vlc_player_t
*player
)
2687 vlc_player_vout_SetFullscreen(player
,
2688 !vlc_player_vout_IsFullscreen(player
));
2692 * Check if the player has wallpaper-mode enaled
2694 * @warning The wallpaper-mode state of the player and all vouts can be
2697 * @note The player instance doesn't need to be locked for vlc_player_vout_*()
2700 * @see vlc_player_vout_cbs.on_wallpaper_mode_changed
2702 * @param player player instance
2703 * @return true if the player is fullscreen
2706 vlc_player_vout_IsWallpaperModeEnabled(vlc_player_t
*player
);
2709 * Enable or disable the player wallpaper-mode
2711 * This will have an effect on all current and future vouts.
2713 * @note The player instance doesn't need to be locked for vlc_player_vout_*()
2715 * @note A successful call will trigger the
2716 * vlc_player_vout_cbs.on_wallpaper_mode_changed event.
2718 * @param player player instance
2719 * @param enabled true to enable wallpaper-mode
2722 vlc_player_vout_SetWallpaperModeEnabled(vlc_player_t
*player
, bool enabled
);
2725 * Helper to toggle the player wallpaper-mode state
2728 vlc_player_vout_ToggleWallpaperMode(vlc_player_t
*player
)
2730 vlc_player_vout_SetWallpaperModeEnabled(player
,
2731 !vlc_player_vout_IsWallpaperModeEnabled(player
));
2735 * Set a filter chain to all vouts and all future vouts
2737 * @warning This is a temporary function, waiting for a refined vout filter
2740 * @param player instance
2741 * @param type filter type
2742 * @param value a valid chain of filter (separated with ',') or NULL
2745 vlc_player_vout_SetFilter(vlc_player_t
*player
, enum vlc_vout_filter_type type
,
2749 * Get the filter chain value applied to all vouts
2751 * @warning This is a temporary function, waiting for a refined vout filter
2754 * @param player instance
2755 * @param type filter type
2756 * @return an allocated string representing the filter chain, free it with
2757 * free(), can be NULL
2760 vlc_player_vout_GetFilter(vlc_player_t
*player
, enum vlc_vout_filter_type type
);
2763 * Take a snapshot on all vouts
2765 * @param player player instance
2768 vlc_player_vout_Snapshot(vlc_player_t
*player
);
2771 * Display an OSD message on all vouts
2773 * @param player player instance
2774 * @param fmt format string
2777 vlc_player_vout_OSDMessage(vlc_player_t
*player
, const char *fmt
, ...);