VLC  4.0.0-dev
vlc_player.h
Go to the documentation of this file.
1 /*****************************************************************************
2  * vlc_player.h: player interface
3  *****************************************************************************
4  * Copyright (C) 2018 VLC authors and VideoLAN
5  *
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.
10  *
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.
15  *
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  *****************************************************************************/
20 
21 #ifndef VLC_PLAYER_H
22 #define VLC_PLAYER_H 1
23 
24 #include <vlc_input.h>
25 #include <vlc_aout.h>
26 
27 /**
28  * @defgroup vlc_player Player
29  * @ingroup input
30  * VLC Player API
31  * @brief
32 @dot
33 digraph player_states {
34  label="Player state diagram";
35  new [style="invis"];
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"];
50 }
51 @enddot
52  * @{
53  * @file
54  * VLC Player API
55  */
56 
57 /**
58  * @defgroup vlc_player__instance Player instance
59  * @{
60  */
61 
62 /**
63  * Player opaque structure.
64  */
65 typedef struct vlc_player_t vlc_player_t;
66 
67 /**
68  * Player lock type (normal or reentrant)
69  */
71 {
72  /**
73  * Normal lock
74  *
75  * If the player is already locked, subsequent calls to vlc_player_Lock()
76  * will deadlock.
77  */
79 
80  /**
81  * Reentrant lock
82  *
83  * If the player is already locked, subsequent calls to vlc_player_Lock()
84  * will still succeed. To unlock the player, one call to
85  * vlc_player_Unlock() per vlc_player_Lock() is necessary.
86  */
88 };
89 
90 /**
91  * Action when the player is stopped
92  *
93  * @see vlc_player_SetMediaStoppedAction()
94  */
96  /** Continue (or stop if there is no next media), default behavior */
98  /** Pause when reaching the end of file */
100  /** Stop, even if there is a next media to play */
102  /** Exit VLC */
104 };
105 
106 /**
107  * Callbacks for the owner of the player.
108  *
109  * These callbacks are needed to control the player flow (via the
110  * vlc_playlist_t as a owner for example). It can only be set when creating the
111  * player via vlc_player_New().
112  *
113  * All callbacks are called with the player locked (cf. vlc_player_Lock()), and
114  * from any thread (even the current one).
115  */
117 {
118  /**
119  * Called when the player requires a new media
120  *
121  * @note The returned media must be already held with input_item_Hold()
122  *
123  * @param player locked player instance
124  * @param data opaque pointer set from vlc_player_New()
125  * @return the next media to play, held by the callee with input_item_Hold()
126  */
127  input_item_t *(*get_next)(vlc_player_t *player, void *data);
128 };
129 
130 /**
131  * Create a new player instance
132  *
133  * @param parent parent VLC object
134  * @param media_provider pointer to a media_provider structure or NULL, the
135  * structure must be valid during the lifetime of the player
136  * @param media_provider_data opaque data used by provider callbacks
137  * @return a pointer to a valid player instance or NULL in case of error
138  */
140 vlc_player_New(vlc_object_t *parent, enum vlc_player_lock_type lock_type,
141  const struct vlc_player_media_provider *media_provider,
142  void *media_provider_data);
143 
144 /**
145  * Delete a player instance
146  *
147  * This function stop any playback previously started and wait for their
148  * termination.
149  *
150  * @warning Blocking function if the player state is not STOPPED, don't call it
151  * from an UI thread in that case.
152  *
153  * @param player unlocked player instance created by vlc_player_New()
154  */
155 VLC_API void
157 
158 /**
159  * Lock the player.
160  *
161  * All player functions (except vlc_player_Delete()) need to be called while
162  * the player lock is held.
163  *
164  * @param player unlocked player instance
165  */
166 VLC_API void
168 
169 /**
170  * Unlock the player
171  *
172  * @param player locked player instance
173  */
174 VLC_API void
176 
177 /**
178  * Wait on a condition variable
179  *
180  * This call allow users to use their own condition with the player mutex.
181  *
182  * @param player locked player instance
183  * @param cond external condition
184  */
185 VLC_API void
187 
188 /**
189  * Setup an action when a media is stopped
190  *
191  * @param player locked player instance
192  * @param action action to do when a media is stopped
193  */
194 VLC_API void
196  enum vlc_player_media_stopped_action action);
197 
198 /**
199  * Ask to start in a paused state
200  *
201  * This function can be used before vlc_player_Start()
202  *
203  * @param player locked player instance
204  * @param start_paused true to start in a paused state, false to cancel it
205  */
206 VLC_API void
207 vlc_player_SetStartPaused(vlc_player_t *player, bool start_paused);
208 
209 /**
210  * Enable or disable pause on cork event
211  *
212  * If enabled, the player will automatically pause and resume on cork events.
213  * In that case, cork events won't be propagated via callbacks.
214  * @see vlc_player_cbs.on_cork_changed
215  *
216  * @param player locked player instance
217  * @param enabled true to enable
218  */
219 VLC_API void
220 vlc_player_SetPauseOnCork(vlc_player_t *player, bool enabled);
221 
222 /** @} vlc_player__instance */
223 
224 /**
225  * @defgroup vlc_player__playback Playback control
226  * @{
227  */
228 
229 /**
230  * State of the player
231  *
232  * During a normal playback (no errors), the user is expected to receive all
233  * events in the following order: STARTED, PLAYING, STOPPING, STOPPED.
234  *
235  * @note When playing more than one media in a row, the player stay at the
236  * PLAYING state when doing the transition from the current media to the next
237  * media (that can be gapless). This means that STOPPING, STOPPED states (for
238  * the current media) and STARTED, PLAYING states (for the next one) won't be
239  * sent. Nevertheless, the vlc_player_cbs.on_current_media_changed callback
240  * will be called during this transition.
241  */
242 enum vlc_player_state
243 {
244  /**
245  * The player is stopped
246  *
247  * Initial state, or triggered by an internal transition from the STOPPING
248  * state.
249  */
251 
252  /**
253  * The player is started
254  *
255  * Triggered by vlc_player_Start()
256  */
258 
259  /**
260  * The player is playing
261  *
262  * Triggered by vlc_player_Resume() or by an internal transition from the
263  * STARTED state.
264  */
266 
267  /**
268  * The player is paused
269  *
270  * Triggered by vlc_player_Pause().
271  */
273 
274  /**
275  * The player is stopping
276  *
277  * Triggered by vlc_player_Stop(), vlc_player_SetCurrentMedia() or by an
278  * internal transition (when the media reach the end of file for example).
279  */
281 };
282 
283 /**
284  * Error of the player
285  *
286  * @see vlc_player_GetError()
287  */
288 enum vlc_player_error
289 {
292 };
293 
294 /**
295  * Seek speed type
296  *
297  * @see vlc_player_SeekByPos()
298  * @see vlc_player_SeekByTime()
299  */
301 {
302  /** Do a precise seek */
304  /** Do a fast seek */
306 };
307 
308 /**
309  * Player seek/delay directive
310  *
311  * @see vlc_player_SeekByPos()
312  * @see vlc_player_SeekByTime()
313  * @see vlc_player_SetCategoryDelay()
314  */
316 {
317  /** Given time/position */
319  /** The current position +/- the given time/position */
321 };
322 
323 /**
324  * Menu (VCD/DVD/BD) and viewpoint navigations
325  *
326  * @see vlc_player_Navigate()
327  */
328 enum vlc_player_nav
329 {
330  /** Activate the navigation item selected */
332  /** Select a navigation item above or move the viewpoint up */
334  /** Select a navigation item under or move the viewpoint down */
336  /** Select a navigation item on the left or move the viewpoint left */
338  /** Select a navigation item on the right or move the viewpoint right */
340  /** Activate the popup Menu (for BD) */
342  /** Activate disc Root Menu */
344 };
345 
346 /**
347  * A to B loop state
348  */
350 {
354 };
355 
356 /** Player capability: can seek */
357 #define VLC_PLAYER_CAP_SEEK (1<<0)
358 /** Player capability: can pause */
359 #define VLC_PLAYER_CAP_PAUSE (1<<1)
360 /** Player capability: can change the rate */
361 #define VLC_PLAYER_CAP_CHANGE_RATE (1<<2)
362 /** Player capability: can seek back */
363 #define VLC_PLAYER_CAP_REWIND (1<<3)
364 
365 /** Player teletext key: Red */
366 #define VLC_PLAYER_TELETEXT_KEY_RED ('r' << 16)
367 /** Player teletext key: Green */
368 #define VLC_PLAYER_TELETEXT_KEY_GREEN ('g' << 16)
369 /** Player teletext key: Yellow */
370 #define VLC_PLAYER_TELETEXT_KEY_YELLOW ('y' << 16)
371 /** Player teletext key: Blue */
372 #define VLC_PLAYER_TELETEXT_KEY_BLUE ('b' << 16)
373 /** Player teletext key: Index */
374 #define VLC_PLAYER_TELETEXT_KEY_INDEX ('i' << 16)
375 
377 {
381 };
382 
383 /**
384  * Set the current media
385  *
386  * This function replaces the current and next medias.
387  *
388  * @note A successful call will always result of
389  * vlc_player_cbs.on_current_media_changed being called. This function is not
390  * blocking. If a media is currently being played, this media will be stopped
391  * and the requested media will be set after.
392  *
393  * @warning This function is either synchronous (if the player state is
394  * STOPPED) or asynchronous. In the later case, vlc_player_GetCurrentMedia()
395  * will return the old media, even after this call, and until the
396  * vlc_player_cbs.on_current_media_changed is called.
397  *
398  * @param player locked player instance
399  * @param media new media to play (will be held by the player)
400  * @return VLC_SUCCESS or a VLC error code
401  */
402 VLC_API int
404 
405 /**
406  * Get the current played media.
407  *
408  * @see vlc_player_cbs.on_current_media_changed
409  *
410  * @param player locked player instance
411  * @return a valid media or NULL (if no media is set)
412  */
415 
416 /**
417  * Helper that hold the current media
418  */
419 static inline input_item_t *
421 {
423  return item ? input_item_Hold(item) : NULL;
424 }
425 
426 /**
427  * Invalidate the next media.
428  *
429  * This function can be used to invalidate the media returned by the
430  * vlc_player_media_provider.get_next callback. This can be used when the next
431  * item from a playlist was changed by the user.
432  *
433  * Calling this function will trigger the
434  * vlc_player_media_provider.get_next callback to be called again.
435  *
436  * @param player locked player instance
437  */
438 VLC_API void
440 
441 /**
442  * Start the playback of the current media.
443  *
444  * @param player locked player instance
445  * @return VLC_SUCCESS or a VLC error code
446  */
447 VLC_API int
449 
450 /**
451  * Stop the playback of the current media
452  *
453  * @note This function is asynchronous. In case of success, the user should wait
454  * for the STOPPED state event to know when the stop is finished.
455  *
456  * @param player locked player instance
457  * @return VLC_SUCCESS if the player is being stopped, VLC_EGENERIC otherwise
458  * (no-op)
459  */
460 VLC_API int
462 
463 /**
464  * Pause the playback
465  *
466  * @param player locked player instance
467  */
468 VLC_API void
470 
471 /**
472  * Resume the playback from a pause
473  *
474  * @param player locked player instance
475  */
476 VLC_API void
478 
479 /**
480  * Pause and display the next video frame
481  *
482  * @param player locked player instance
483  */
484 VLC_API void
486 
487 /**
488  * Get the state of the player
489  *
490  * @note Since all players actions are asynchronous, this function won't
491  * reflect the new state immediately. Wait for the
492  * vlc_players_cbs.on_state_changed event to be notified.
493  *
494  * @see vlc_player_state
495  * @see vlc_player_cbs.on_state_changed
496  *
497  * @param player locked player instance
498  * @return the current player state
499  */
502 
503 /**
504  * Get the error state of the player
505  *
506  * @see vlc_player_cbs.on_capabilities_changed
507  *
508  * @param player locked player instance
509  * @return the current error state
510  */
513 
514 /**
515  * Helper to get the started state
516  */
517 static inline bool
519 {
520  switch (vlc_player_GetState(player))
521  {
525  return true;
526  default:
527  return false;
528  }
529 }
530 
531 /**
532  * Helper to get the paused state
533  */
534 static inline bool
536 {
538 }
539 
540 /**
541  * Helper to toggle the pause state
542  */
543 static inline void
545 {
546  if (vlc_player_IsStarted(player))
547  {
548  if (vlc_player_IsPaused(player))
549  vlc_player_Resume(player);
550  else
551  vlc_player_Pause(player);
552  }
553 }
554 
555 /**
556  * Get the player capabilities
557  *
558  * @see vlc_player_cbs.on_capabilities_changed
559  *
560  * @param player locked player instance
561  * @return the player capabilities, a bitwise mask of @ref VLC_PLAYER_CAP_SEEK,
562  * @ref VLC_PLAYER_CAP_PAUSE, @ref VLC_PLAYER_CAP_CHANGE_RATE, @ref
563  * VLC_PLAYER_CAP_REWIND
564  */
565 VLC_API int
567 
568 /**
569  * Helper to get the seek capability
570  */
571 static inline bool
573 {
575 }
576 
577 /**
578  * Helper to get the pause capability
579  */
580 static inline bool
582 {
584 }
585 
586 /**
587  * Helper to get the change-rate capability
588  */
589 static inline bool
591 {
593 }
594 
595 /**
596  * Helper to get the rewindable capability
597  */
598 static inline bool
600 {
602 }
603 
604 /**
605  * Get the rate of the player
606  *
607  * @see vlc_player_cbs.on_rate_changed
608  *
609  * @param player locked player instance
610  * @return rate of the player (< 1.f is slower, > 1.f is faster)
611  */
612 VLC_API float
614 
615 /**
616  * Change the rate of the player
617  *
618  * @note The rate is saved across several medias
619  *
620  * @param player locked player instance
621  * @param rate new rate (< 1.f is slower, > 1.f is faster)
622  */
623 VLC_API void
624 vlc_player_ChangeRate(vlc_player_t *player, float rate);
625 
626 /**
627  * Increment the rate of the player (faster)
628  *
629  * @param player locked player instance
630  */
631 VLC_API void
633 
634 /**
635  * Decrement the rate of the player (Slower)
636  *
637  * @param player locked player instance
638  */
639 VLC_API void
641 
642 /**
643  * Get the length of the current media
644  *
645  * @note A started and playing media doesn't have necessarily a valid length.
646  *
647  * @see vlc_player_cbs.on_length_changed
648  *
649  * @param player locked player instance
650  * @return a valid length or VLC_TICK_INVALID (if no media is set,
651  * playback is not yet started or in case of error)
652  */
655 
656 /**
657  * Get the time of the current media
658  *
659  * @note A started and playing media doesn't have necessarily a valid time.
660  *
661  * @see vlc_player_cbs.on_position_changed
662  *
663  * @param player locked player instance
664  * @return a valid time or VLC_TICK_INVALID (if no media is set, the media
665  * doesn't have any time, if playback is not yet started or in case of error)
666  */
669 
670 /**
671  * Get the position of the current media
672  *
673  * @see vlc_player_cbs.on_position_changed
674  *
675  * @param player locked player instance
676  * @return a valid position in the range [0.f;1.f] or -1.f (if no media is
677  * set,if playback is not yet started or in case of error)
678  */
679 VLC_API float
681 
682 /**
683  * Seek the current media by position
684  *
685  * @note This function can be called before vlc_player_Start() in order to set
686  * a starting position.
687  *
688  * @param player locked player instance
689  * @param position position in the range [0.f;1.f]
690  * @param speed precise of fast
691  * @param whence absolute or relative
692  */
693 VLC_API void
694 vlc_player_SeekByPos(vlc_player_t *player, float position,
695  enum vlc_player_seek_speed speed,
696  enum vlc_player_whence whence);
697 
698 /**
699  * Seek the current media by time
700  *
701  * @note This function can be called before vlc_player_Start() in order to set
702  * a starting position.
703  *
704  * @warning This function has an effect only if the media has a valid length.
705  *
706  * @param player locked player instance
707  * @param time a time in the range [0;length]
708  * @param speed precise of fast
709  * @param whence absolute or relative
710  */
711 VLC_API void
713  enum vlc_player_seek_speed speed,
714  enum vlc_player_whence whence);
715 
716 /**
717  * Helper to set the absolute position precisely
718  */
719 static inline void
720 vlc_player_SetPosition(vlc_player_t *player, float position)
721 {
724 }
725 
726 /**
727  * Helper to set the absolute position fast
728  */
729 static inline void
730 vlc_player_SetPositionFast(vlc_player_t *player, float position)
731 {
732  vlc_player_SeekByPos(player, position, VLC_PLAYER_SEEK_FAST,
734 }
735 
736 /**
737  * Helper to jump the position precisely
738  */
739 static inline void
740 vlc_player_JumpPos(vlc_player_t *player, float jumppos)
741 {
742  /* No fask seek for jumps. Indeed, jumps can seek to the current position
743  * if not precise enough or if the jump value is too small. */
746 }
747 
748 /**
749  * Helper to set the absolute time precisely
750  */
751 static inline void
753 {
756 }
757 
758 /**
759  * Helper to set the absolute time fast
760  */
761 static inline void
763 {
766 }
767 
768 /**
769  * Helper to jump the time precisely
770  */
771 static inline void
773 {
774  /* No fask seek for jumps. Indeed, jumps can seek to the current position
775  * if not precise enough or if the jump value is too small. */
778 }
779 
780 /**
781  * Display the player position on the vout OSD
782  *
783  * @param player locked player instance
784  */
785 VLC_API void
787 
788 /**
789  * Enable A to B loop of the current media
790  *
791  * This function need to be called 2 times with VLC_PLAYER_ABLOOP_A and
792  * VLC_PLAYER_ABLOOP_B to setup an A to B loop. It current the current
793  * time/position when called. The B time must be higher than the A time.
794  *
795  * @param player locked player instance
796  * @return VLC_SUCCESS or a VLC error code
797  */
798 VLC_API int
800 
801 /**
802  * Get the A to B loop status
803  *
804  * @note If the returned status is VLC_PLAYER_ABLOOP_A, then a_time and a_pos
805  * will be valid. If the returned status is VLC_PLAYER_ABLOOP_B, then all
806  * output parameters are valid. If the returned status is
807  * VLC_PLAYER_ABLOOP_NONE, then all output parameters are invalid.
808  *
809  * @see vlc_player_cbs.on_atobloop_changed
810  *
811  * @param player locked player instance
812  * @param a_time A time or VLC_TICK_INVALID (if the media doesn't have valid
813  * times)
814  * @param a_pos A position
815  * @param b_time B time or VLC_TICK_INVALID (if the media doesn't have valid
816  * times)
817  * @param b_pos B position
818  * @return A to B loop status
819  */
821 vlc_player_GetAtoBLoop(vlc_player_t *player, vlc_tick_t *a_time, float *a_pos,
822  vlc_tick_t *b_time, float *b_pos);
823 
824 /**
825  * Navigate (for DVD/Bluray menus or viewpoint)
826  *
827  * @param player locked player instance
828  * @param nav navigation key
829  */
830 VLC_API void
832 
833 /**
834  * Update the viewpoint
835  *
836  * @param player locked player instance
837  * @param viewpoint the viewpoint value
838  * @param whence absolute or relative
839  */
840 VLC_API void
842  const vlc_viewpoint_t *viewpoint,
843  enum vlc_player_whence whence);
844 
845 /**
846  * Check if the playing is recording
847  *
848  * @see vlc_player_cbs.on_recording_changed
849  *
850  * @param player locked player instance
851  * @return true if the player is recording
852  */
853 VLC_API bool
855 
856 /**
857  * Enable or disable recording for the current media
858  *
859  * @note A successful call will trigger the vlc_player_cbs.on_recording_changed
860  * event.
861  *
862  * @param player locked player instance
863  * @param enabled true to enable recording
864  */
865 VLC_API void
866 vlc_player_SetRecordingEnabled(vlc_player_t *player, bool enabled);
867 
868 /**
869  * Helper to toggle the recording state
870  */
871 static inline void
873 {
875 }
876 
877 /**
878  * Add an associated (or external) media to the current media
879  *
880  * @param player locked player instance
881  * @param cat SPU_ES or UNKNOWN_ES
882  * @param uri absolute uri of the external media
883  * @param select true to select the track of this external media
884  * @param notify true to notify the OSD
885  * @param check_ext true to check subtitles extension
886  */
887 VLC_API int
889  enum es_format_category_e cat, const char *uri,
890  bool select, bool notify, bool check_ext);
891 
892 /**
893  * Get the signal quality and strength of the current media
894  *
895  * @param player locked player instance
896  */
897 VLC_API int
898 vlc_player_GetSignal(vlc_player_t *player, float *quality, float *strength);
899 
900 /**
901  * Get the statistics of the current media
902  *
903  * @warning The returned pointer becomes invalid when the player is unlocked.
904  * The referenced structure can be safely copied.
905  *
906  * @see vlc_player_cbs.on_statistics_changed
907  *
908  * @param player locked player instance
909  * @return pointer to the player stats structure or NULL
910  */
911 VLC_API const struct input_stats_t *
913 
914 /**
915  * Restore the previous playback position of the current media
916  */
917 VLC_API void
919 
920 /**
921  * Get the V4L2 object used to do controls
922  *
923  * @param player locked player instance
924  * @return the V4L2 object or NULL if not any. This object must be used with
925  * the player lock held.
926  */
928 vlc_player_GetV4l2Object(vlc_player_t *player) VLC_DEPRECATED;
929 
930 /** @} vlc_player__playback */
931 
932 /**
933  * @defgroup vlc_player__titles Title and chapter control
934  * @{
935  */
936 
937 /**
938  * Player chapter structure
939  */
940 struct vlc_player_chapter
941 {
942  /** Chapter name, always valid */
943  const char *name;
944  /** Position of this chapter */
946 };
947 
948 /** vlc_player_title.flags: The title is a menu. */
949 #define VLC_PLAYER_TITLE_MENU 0x01
950 /** vlc_player_title.flags: The title is interactive. */
951 #define VLC_PLAYER_TITLE_INTERACTIVE 0x02
952 
953 /** Player title structure */
954 struct vlc_player_title
955 {
956  /** Title name, always valid */
957  const char *name;
958  /** Length of the title */
960  /** Bit flag of @ref VLC_PLAYER_TITLE_MENU and @ref
961  * VLC_PLAYER_TITLE_INTERACTIVE */
962  unsigned flags;
963  /** Number of chapters, can be 0 */
964  size_t chapter_count;
965  /** Array of chapters, can be NULL */
966  const struct vlc_player_chapter *chapters;
967 };
968 
969 /**
970  * Opaque structure representing a list of @ref vlc_player_title.
971  *
972  * @see vlc_player_GetTitleList()
973  * @see vlc_player_title_list_GetCount()
974  * @see vlc_player_title_list_GetAt()
975  */
977 
978 /**
979  * Hold the title list of the player
980  *
981  * This function can be used to pass this title list from a callback to an
982  * other thread.
983  *
984  * @see vlc_player_cbs.on_titles_changed
985  *
986  * @return the same instance
987  */
990 
991 /**
992  * Release of previously held title list
993  */
994 VLC_API void
996 
997 /**
998  * Get the number of title of a list
999  */
1000 VLC_API size_t
1002 
1003 /**
1004  * Get the title at a given index
1005  *
1006  * @param idx index in the range [0; count[
1007  * @return a valid title (can't be NULL)
1008  */
1009 VLC_API const struct vlc_player_title *
1011 
1012 /**
1013  * Get the title list of the current media
1014  *
1015  * @see vlc_player_cbs.on_titles_changed
1016  *
1017  * @param player locked player instance
1018  */
1021 
1022 /**
1023  * Get the selected title index for the current media
1024  *
1025  * @see vlc_player_cbs.on_title_selection_changed
1026  *
1027  * @param player locked player instance
1028  */
1029 VLC_API ssize_t
1031 
1032 /**
1033  * Helper to get the current selected title
1034  */
1035 static inline const struct vlc_player_title *
1039  if (!titles)
1040  return NULL;
1041  ssize_t selected_idx = vlc_player_GetSelectedTitleIdx(player);
1042  if (selected_idx < 0)
1043  return NULL;
1044  return vlc_player_title_list_GetAt(titles, selected_idx);
1045 }
1046 
1047 /**
1048  * Select a title index for the current media
1049  *
1050  * @note A successful call will trigger the
1051  * vlc_player_cbs.on_title_selection_changed event.
1052  *
1053  * @see vlc_player_title_list_GetAt()
1054  * @see vlc_player_title_list_GetCount()
1055  *
1056  * @param player locked player instance
1057  * @param index valid index in the range [0;count[
1058  */
1059 VLC_API void
1060 vlc_player_SelectTitleIdx(vlc_player_t *player, size_t index);
1061 
1062 /**
1063  * Select a title for the current media
1064  *
1065  * @note A successful call will trigger the
1066  * vlc_player_cbs.on_title_selection_changed event.
1067  *
1068  * @see vlc_player_title_list_GetAt()
1069  * @see vlc_player_title_list_GetCount()
1070  *
1071  * @param player locked player instance
1072  * @param title a valid title coming from the vlc_player_title_list
1073  */
1074 VLC_API void
1076  const struct vlc_player_title *title);
1077 
1078 /**
1079  * Select a chapter for the current media
1080  *
1081  * @note A successful call will trigger the
1082  * vlc_player_cbs.on_chapter_selection_changed event.
1083  *
1084  * @param player locked player instance
1085  * @param title the selected title
1086  * @param chapter_idx index from vlc_player_title.chapters
1087  */
1088 VLC_API void
1090  const struct vlc_player_title *title,
1091  size_t chapter_idx);
1092 
1093 /**
1094  * Select the next title for the current media
1095  *
1096  * @see vlc_player_SelectTitleIdx()
1097  */
1098 VLC_API void
1100 
1101 /**
1102  * Select the previous title for the current media
1103  *
1104  * @see vlc_player_SelectTitleIdx()
1105  */
1106 VLC_API void
1108 
1109 /**
1110  * Get the selected chapter index for the current media
1111  *
1112  * @see vlc_player_cbs.on_chapter_selection_changed
1113  *
1114  * @param player locked player instance
1115  */
1116 VLC_API ssize_t
1118 
1119 /**
1120  * Helper to get the current selected chapter
1121  */
1122 static inline const struct vlc_player_chapter *
1125  const struct vlc_player_title *title = vlc_player_GetSelectedTitle(player);
1126  if (!title || !title->chapter_count)
1127  return NULL;
1128  ssize_t chapter_idx = vlc_player_GetSelectedChapterIdx(player);
1129  return chapter_idx >= 0 ? &title->chapters[chapter_idx] : NULL;
1130 }
1131 
1132 /**
1133  * Select a chapter index for the current media
1134  *
1135  * @note A successful call will trigger the
1136  * vlc_player_cbs.on_chaper_selection_changed event.
1137  *
1138  * @see vlc_player_title.chapters
1139  *
1140  * @param player locked player instance
1141  * @param index valid index in the range [0;vlc_player_title.chapter_count[
1142  */
1143 VLC_API void
1144 vlc_player_SelectChapterIdx(vlc_player_t *player, size_t index);
1145 
1146 /**
1147  * Select the next chapter for the current media
1148  *
1149  * @see vlc_player_SelectChapterIdx()
1150  */
1151 VLC_API void
1153 
1154 /**
1155  * Select the previous chapter for the current media
1156  *
1157  * @see vlc_player_SelectChapterIdx()
1158  */
1159 VLC_API void
1161 
1162 /** @} vlc_player__titles */
1163 
1164 /**
1165  * @defgroup vlc_player__programs Program control
1166  * @{
1167  */
1168 
1169 /**
1170  * Player program structure.
1171  */
1172 struct vlc_player_program
1174  /** Id used for vlc_player_SelectProgram() */
1175  int group_id;
1176  /** Program name, always valid */
1177  const char *name;
1178  /** True if the program is selected */
1179  bool selected;
1180  /** True if the program is scrambled */
1181  bool scrambled;
1182 };
1183 
1184 /**
1185  * Duplicate a program
1186  *
1187  * This function can be used to pass a program from a callback to an other
1188  * context.
1189  *
1190  * @see vlc_player_cbs.on_program_list_changed
1191  *
1192  * @return a duplicated program or NULL on allocation error
1193  */
1194 VLC_API struct vlc_player_program *
1195 vlc_player_program_Dup(const struct vlc_player_program *prgm);
1196 
1197 /**
1198  * Delete a duplicated program
1199  */
1200 VLC_API void
1202 
1203 /**
1204  * Get the number of programs
1205  *
1206  * @warning The returned size becomes invalid when the player is unlocked.
1207  *
1208  * @param player locked player instance
1209  * @return number of programs, or 0 (in case of error, or if the media is not
1210  * started)
1211  */
1212 VLC_API size_t
1214 
1215 /**
1216  * Get the program at a specific index
1217  *
1218  * @warning The behaviour is undefined if the index is not valid.
1219  *
1220  * @warning The returned pointer becomes invalid when the player is unlocked.
1221  * The referenced structure can be safely copied with vlc_player_program_Dup().
1222  *
1223  * @param player locked player instance
1224  * @param index valid index in the range [0; count[
1225  * @return a valid program (can't be NULL if vlc_player_GetProgramCount()
1226  * returned a valid count)
1227  */
1228 VLC_API const struct vlc_player_program *
1229 vlc_player_GetProgramAt(vlc_player_t *player, size_t index);
1230 
1231 /**
1232  * Get a program from an ES group identifier
1233  *
1234  * @param player locked player instance
1235  * @param group_id a program ID (retrieved from
1236  * vlc_player_cbs.on_program_list_changed or vlc_player_GetProgramAt())
1237  * @return a valid program or NULL (if the program was terminated by the
1238  * playback thread)
1239  */
1240 VLC_API const struct vlc_player_program *
1242 
1243 /**
1244  * Select a program from an ES group identifier
1245  *
1246  * This function can be used to pre-select a program by its id before starting
1247  * the player. It has only effect for the current media. It can also be used
1248  * when the player is already started.
1249  *
1250  * @note Selecting a non-existing program will cause the player to no select
1251  * any programs. Therefore, all tracks will be disabled.
1252  *
1253  * @param player locked player instance
1254  * @param group_id a program ID (retrieved from
1255  * vlc_player_cbs.on_program_list_changed or vlc_player_GetProgramAt())
1256  */
1257 VLC_API void
1259 
1260 /**
1261  * Select the next program
1262  *
1263  * @param player locked player instance
1264  */
1265 VLC_API void
1267 
1268 /**
1269  * Select the previous program
1270  *
1271  * @param player locked player instance
1272  */
1273 VLC_API void
1275 
1276 /**
1277  * Helper to get the current selected program
1278  */
1279 static inline const struct vlc_player_program *
1282  size_t count = vlc_player_GetProgramCount(player);
1283  for (size_t i = 0; i < count; ++i)
1284  {
1285  const struct vlc_player_program *program =
1286  vlc_player_GetProgramAt(player, i);
1287  assert(program);
1288  if (program->selected)
1289  return program;
1290  }
1291  return NULL;
1292 }
1293 
1294 /** @} vlc_player__programs */
1295 
1296 /**
1297  * @defgroup vlc_player__tracks Tracks control
1298  * @{
1299  */
1300 
1301 /**
1302  * Player selection policy
1303  *
1304  * @see vlc_player_SelectEsId()
1305  */
1308  /**
1309  * Only one track per category is selected. Selecting a track with this
1310  * policy will disable all other tracks for the same category.
1311  */
1313  /**
1314  * Select multiple tracks for one category.
1315  *
1316  * Only one audio track can be selected at a time.
1317  * Two subtitle tracks can be selected simultaneously.
1318  * Multiple video tracks can be selected simultaneously.
1319  */
1321 };
1322 
1323 /**
1324  * Player track structure.
1325  *
1326  * A track is a representation of an ES identifier at a given time. Once the
1327  * player is unlocked, all content except the es_id pointer can be updated.
1328  *
1329  * @see vlc_player_cbs.on_track_list_changed
1330  * @see vlc_player_GetTrack
1331  */
1332 struct vlc_player_track
1334  /** Id used for any player actions, like vlc_player_SelectEsId() */
1335  vlc_es_id_t *es_id;
1336  /** Track name, always valid */
1337  const char *name;
1338  /** Es format */
1339  es_format_t fmt;
1340  /** True if the track is selected */
1341  bool selected;
1342 };
1343 
1344 /**
1345  * Duplicate a track
1346  *
1347  * This function can be used to pass a track from a callback to an other
1348  * context. The es_id will be held by the duplicated track.
1349  *
1350  * @warning The returned track won't be updated if the original one is modified
1351  * by the player.
1352  *
1353  * @see vlc_player_cbs.on_track_list_changed
1354  *
1355  * @return a duplicated track or NULL on allocation error
1356  */
1357 VLC_API struct vlc_player_track *
1358 vlc_player_track_Dup(const struct vlc_player_track *track);
1359 
1360 /**
1361  * Delete a duplicated track
1362  */
1363 VLC_API void
1365 
1366 /**
1367  * Get the number of tracks for an ES category
1368  *
1369  * @warning The returned size becomes invalid when the player is unlocked.
1370  *
1371  * @param player locked player instance
1372  * @param cat VIDEO_ES, AUDIO_ES or SPU_ES
1373  * @return number of tracks, or 0 (in case of error, or if the media is not
1374  * started)
1375  */
1376 VLC_API size_t
1378 
1379 /**
1380  * Get the track at a specific index for an ES category
1381  *
1382  * @warning The behaviour is undefined if the index is not valid.
1383  *
1384  * @warning The returned pointer becomes invalid when the player is unlocked.
1385  * The referenced structure can be safely copied with vlc_player_track_Dup().
1386  *
1387  * @param player locked player instance
1388  * @param cat VIDEO_ES, AUDIO_ES or SPU_ES
1389  * @param index valid index in the range [0; count[
1390  * @return a valid track (can't be NULL if vlc_player_GetTrackCount() returned
1391  * a valid count)
1392  */
1393 VLC_API const struct vlc_player_track *
1395  size_t index);
1396 
1397 /**
1398  * Helper to get the video track count
1399  */
1400 static inline size_t
1403  return vlc_player_GetTrackCount(player, VIDEO_ES);
1404 }
1405 
1406 /**
1407  * Helper to get a video track at a specific index
1408  */
1409 static inline const struct vlc_player_track *
1410 vlc_player_GetVideoTrackAt(vlc_player_t *player, size_t index)
1412  return vlc_player_GetTrackAt(player, VIDEO_ES, index);
1413 }
1414 
1415 /**
1416  * Helper to get the audio track count
1417  */
1418 static inline size_t
1421  return vlc_player_GetTrackCount(player, AUDIO_ES);
1422 }
1423 
1424 /**
1425  * Helper to get an audio track at a specific index
1426  */
1427 static inline const struct vlc_player_track *
1428 vlc_player_GetAudioTrackAt(vlc_player_t *player, size_t index)
1430  return vlc_player_GetTrackAt(player, AUDIO_ES, index);
1431 }
1432 
1433 /**
1434  * Helper to get the subtitle track count
1435  */
1436 static inline size_t
1439  return vlc_player_GetTrackCount(player, SPU_ES);
1440 }
1441 
1442 /**
1443  * Helper to get a subtitle track at a specific index
1444  */
1445 static inline const struct vlc_player_track *
1446 vlc_player_GetSubtitleTrackAt(vlc_player_t *player, size_t index)
1448  return vlc_player_GetTrackAt(player, SPU_ES, index);
1449 }
1450 
1451 /**
1452  * Get a track from an ES identifier
1453  *
1454  * @warning The returned pointer becomes invalid when the player is unlocked.
1455  * The referenced structure can be safely copied with vlc_player_track_Dup().
1456  *
1457  * @param player locked player instance
1458  * @param es_id an ES ID (retrieved from vlc_player_cbs.on_track_list_changed or
1459  * vlc_player_GetTrackAt())
1460  * @return a valid player track or NULL (if the track was terminated by the
1461  * playback thread)
1462  */
1463 VLC_API const struct vlc_player_track *
1465 
1466 /**
1467  * Get and the video output used by a ES identifier
1468  *
1469  * @warning A same vout can be associated with multiple ES during the lifetime
1470  * of the player. The information returned by this function becomes invalid
1471  * when the player is unlocked. The returned vout doesn't need to be released,
1472  * but must be held with vout_Hold() if it is accessed after the player is
1473  * unlocked.
1474  *
1475  * @param player locked player instance
1476  * @param es_id an ES ID (retrieved from vlc_player_cbs.on_track_list_changed or
1477  * vlc_player_GetTrackAt())
1478  * @param order if not null, the order of the vout
1479  * @return a valid vout or NULL (if the track is disabled, it it's not a video
1480  * or spu track, or if the vout failed to start)
1481  */
1484  enum vlc_vout_order *order);
1485 
1486 /**
1487  * Get the ES identifier of a video output
1488  *
1489  * @warning A same vout can be associated with multiple ES during the lifetime
1490  * of the player. The information returned by this function becomes invalid
1491  * when the player is unlocked. The returned es_id doesn't need to be released,
1492  * but must be held with vlc_es_id_Hold() if it accessed after the player is
1493  * unlocked.
1494  *
1495  * @param player locked player instance
1496  * @param vout vout (can't be NULL)
1497  * @return a valid ES identifier or NULL (if the vout is stopped)
1498  */
1501 
1502 /**
1503  * Helper to get the selected track from an ES category
1504  *
1505  * @warning The player can have more than one selected track for a same ES
1506  * category. This function will only return the first selected one. Use
1507  * vlc_player_GetTrackAt() and vlc_player_GetTrackCount() to iterate through
1508  * several selected tracks.
1509  */
1510 static inline const struct vlc_player_track *
1513  size_t count = vlc_player_GetTrackCount(player, cat);
1514  for (size_t i = 0; i < count; ++i)
1515  {
1516  const struct vlc_player_track *track =
1517  vlc_player_GetTrackAt(player, cat, i);
1518  assert(track);
1519  if (track->selected)
1520  return track;
1521  }
1522  return NULL;
1523 }
1524 
1525 /**
1526  * Select tracks by their string identifier
1527  *
1528  * This function can be used to pre-select a list of tracks before starting the
1529  * player. It has only effect for the current media. It can also be used when
1530  * the player is already started.
1531 
1532  * 'str_ids' can contain more than one track id, delimited with ','. "" or any
1533  * invalid track id will cause the player to unselect all tracks of that
1534  * category. NULL will disable the preference for newer tracks without
1535  * unselecting any current tracks.
1536  *
1537  * Example:
1538  * - (VIDEO_ES, "video/1,video/2") will select these 2 video tracks. If there
1539  * is only one video track with the id "video/0", no tracks will be selected.
1540  * - (SPU_ES, "${slave_url_md5sum}/spu/0) will select one spu added by an input
1541  * slave with the corresponding url.
1542  *
1543  * @note The string identifier of a track can be found via vlc_es_id_GetStrId().
1544  *
1545  * @param player locked player instance
1546  * @param cat VIDEO_ES, AUDIO_ES or SPU_ES
1547  * @param str_ids list of string identifier or NULL
1548  */
1549 VLC_API void
1551  enum es_format_category_e cat,
1552  const char *str_ids);
1553 
1554 /**
1555  * Select a track from an ES identifier
1556  *
1557  * @note A successful call will trigger the
1558  * vlc_player_cbs.on_track_selection_changed event.
1559  *
1560  * @param player locked player instance
1561  * @param es_id an ES ID (retrieved from vlc_player_cbs.on_track_list_changed or
1562  * vlc_player_GetTrackAt())
1563  * @param policy exclusive or simultaneous
1564  * @return the number of track selected for es_id category
1565  */
1566 VLC_API unsigned
1568  enum vlc_player_select_policy policy);
1569 
1570 
1571 /**
1572  * Helper to select a track
1573  */
1574 static inline unsigned
1576  const struct vlc_player_track *track,
1577  enum vlc_player_select_policy policy)
1578 {
1579  return vlc_player_SelectEsId(player, track->es_id, policy);
1580 }
1581 
1582 /**
1583  * Select multiple tracks from a list of ES identifiers.
1584  *
1585  * Any tracks of the category, not referenced in the list will be unselected.
1586  *
1587  * @warning there is no guarantee all requested tracks will be selected. The
1588  * behaviour is undefined if the list is not null-terminated.
1589  *
1590  * @note A successful call will trigger the
1591  * vlc_player_cbs.on_track_selection_changed event for each track that has
1592  * its selection state changed.
1593  *
1594  * @see VLC_PLAYER_SELECT_SIMULTANEOUS
1595  *
1596  * @param player locked player instance
1597  * @param cat VIDEO_ES, AUDIO_ES or SPU_ES
1598  * @param es_id_list a null-terminated list of ES identifiers. es_ids not
1599  * corresponding to the category will be ignored.
1600  * (ES IDs can be retrieved from vlc_player_cbs.on_track_list_changed or
1601  * vlc_player_GetTrackAt())
1602  * @return the number of track selected for that category
1603  */
1604 VLC_API unsigned
1606  enum es_format_category_e cat,
1607  vlc_es_id_t *const es_id_list[]);
1608 
1609 /**
1610  * Select the next track
1611  *
1612  * If the last track is already selected, a call to this function will disable
1613  * this last track. And a second call will select the first track.
1614  *
1615  * @warning This function has no effects if there are several tracks selected
1616  * for a same category. Therefore the default policy is
1617  * VLC_PLAYER_SELECT_EXCLUSIVE.
1618  *
1619  * @param player locked player instance
1620  * @param cat VIDEO_ES, AUDIO_ES or SPU_ES
1621  */
1622 VLC_API void
1624  enum es_format_category_e cat);
1625 
1626 /**
1627  * Select the Previous track
1628  *
1629  * If the first track is already selected, a call to this function will disable
1630  * this first track. And a second call will select the last track.
1631  *
1632  * @warning This function has no effects if there are several tracks selected
1633  * for a same category. Therefore the default policy is
1634  * VLC_PLAYER_SELECT_EXCLUSIVE.
1635  *
1636  * @param player locked player instance
1637  * @param cat VIDEO_ES, AUDIO_ES or SPU_ES
1638  */
1639 VLC_API void
1641  enum es_format_category_e cat);
1642 
1643 /**
1644  * Unselect a track from an ES identifier
1645  *
1646  * @warning Other tracks of the same category won't be touched.
1647  *
1648  * @note A successful call will trigger the
1649  * vlc_player_cbs.on_track_selection_changed event.
1650  *
1651  * @param player locked player instance
1652  * @param es_id an ES ID (retrieved from vlc_player_cbs.on_track_list_changed or
1653  * vlc_player_GetTrackAt())
1654  */
1655 VLC_API void
1657 
1658 /**
1659  * Helper to unselect a track
1660  */
1661 static inline void
1663  const struct vlc_player_track *track)
1664 {
1665  vlc_player_UnselectEsId(player, track->es_id);
1666 }
1667 
1668 /**
1669  * Helper to unselect all tracks from an ES category
1670  */
1671 static inline void
1674 {
1675  size_t count = vlc_player_GetTrackCount(player, cat);
1676  for (size_t i = 0; i < count; ++i)
1677  {
1678  const struct vlc_player_track *track =
1679  vlc_player_GetTrackAt(player, cat, i);
1680  assert(track);
1681  if (track->selected)
1682  vlc_player_UnselectTrack(player, track);
1683  }
1684 }
1685 
1686 /**
1687  * Restart a track from an ES identifier
1688  *
1689  * @note A successful call will trigger the
1690  * vlc_player_cbs.on_track_selection_changed event.
1691  *
1692  * @param player locked player instance
1693  * @param es_id an ES ID (retrieved from vlc_player_cbs.on_track_list_changed or
1694  * vlc_player_GetTrackAt())
1695  */
1696 VLC_API void
1698 
1699 /**
1700  * Helper to restart a track
1701  */
1702 static inline void
1704  const struct vlc_player_track *track)
1705 {
1706  vlc_player_RestartEsId(player, track->es_id);
1707 }
1708 
1709 /**
1710  * Helper to restart all selected tracks from an ES category
1711  */
1712 static inline void
1715 {
1716  size_t count = vlc_player_GetTrackCount(player, cat);
1717  for (size_t i = 0; i < count; ++i)
1718  {
1719  const struct vlc_player_track *track =
1720  vlc_player_GetTrackAt(player, cat, i);
1721  assert(track);
1722  if (track->selected)
1723  vlc_player_RestartTrack(player, track);
1724  }
1725 }
1726 
1727 /**
1728  * Select the language for an ES category
1729  *
1730  * @warning The language will only be set for all future played media.
1731  *
1732  * @param player locked player instance
1733  * @param cat AUDIO_ES or SPU_ES
1734  * @param lang comma separated, two or three letters country code, 'any' as a
1735  * fallback or NULL to reset the default state
1736  */
1737 VLC_API void
1739  enum es_format_category_e cat,
1740  const char *lang);
1741 
1742 /**
1743  * Get the language of an ES category
1744  *
1745  * @warning This only reflects the change made by
1746  * vlc_player_SelectCategoryLanguage(). The current playing track doesn't
1747  * necessarily correspond to the returned language.
1748  *
1749  * @see vlc_player_SelectCategoryLanguage
1750  *
1751  * @param player locked player instance
1752  * @param cat AUDIO_ES or SPU_ES
1753  * @return valid language or NULL, need to be freed
1754  */
1755 VLC_API char *
1757  enum es_format_category_e cat);
1758 
1759 /**
1760  * Helper to select the audio language
1761  */
1762 static inline void
1763 vlc_player_SelectAudioLanguage(vlc_player_t *player, const char *lang)
1766 }
1767 
1768 /**
1769  * Helper to select the subtitle language
1770  */
1771 static inline void
1772 vlc_player_SelectSubtitleLanguage(vlc_player_t *player, const char *lang)
1775 }
1776 
1777 /**
1778  * Enable or disable a track category
1779  *
1780  * If a track category is disabled, the player won't select any tracks of this
1781  * category automatically or via an user action (vlc_player_SelectTrack()).
1782  *
1783  * @param player locked player instance
1784  * @param cat VIDEO_ES, AUDIO_ES or SPU_ES
1785  * @param enabled true to enable
1786  */
1787 VLC_API void
1789  enum es_format_category_e cat, bool enabled);
1790 
1791 /**
1792  * Check if a track category is enabled
1793  *
1794  * @param player locked player instance
1795  * @param cat VIDEO_ES, AUDIO_ES or SPU_ES
1796  */
1797 VLC_API bool
1799  enum es_format_category_e cat);
1800 
1801 /**
1802  * Helper to enable or disable video tracks
1803  */
1804 static inline void
1805 vlc_player_SetVideoEnabled(vlc_player_t *player, bool enabled)
1807  vlc_player_SetTrackCategoryEnabled(player, VIDEO_ES, enabled);
1808 }
1809 
1810 /**
1811  * Helper to check if video tracks are enabled
1812  */
1813 static inline bool
1817 }
1818 
1819 /**
1820  * Helper to enable or disable audio tracks
1821  */
1822 static inline void
1823 vlc_player_SetAudioEnabled(vlc_player_t *player, bool enabled)
1825  vlc_player_SetTrackCategoryEnabled(player, AUDIO_ES, enabled);
1826 }
1827 
1828 /**
1829  * Helper to check if audio tracks are enabled
1830  */
1831 static inline bool
1835 }
1836 
1837 /**
1838  * Helper to enable or disable subtitle tracks
1839  */
1840 static inline void
1841 vlc_player_SetSubtitleEnabled(vlc_player_t *player, bool enabled)
1843  vlc_player_SetTrackCategoryEnabled(player, SPU_ES, enabled);
1844 }
1845 
1846 /**
1847  * Helper to check if subtitle tracks are enabled
1848  */
1849 static inline bool
1852  return vlc_player_IsTrackCategoryEnabled(player, SPU_ES);
1853 }
1854 
1855 /**
1856  * Helper to toggle subtitles
1857  */
1858 static inline void
1861  bool enabled = !vlc_player_IsSubtitleEnabled(player);
1862  vlc_player_SetSubtitleEnabled(player, enabled);
1863 }
1864 
1865 /**
1866  * Set the subtitle text scaling factor
1867  *
1868  * @note This function have an effect only if the subtitle track is a text type.
1869  *
1870  * @param player locked player instance
1871  * @param scale factor in the range [10;500] (default: 100)
1872  */
1873 VLC_API void
1874 vlc_player_SetSubtitleTextScale(vlc_player_t *player, unsigned scale);
1875 
1876 /**
1877  * Get the subtitle text scaling factor
1878  *
1879  * @param player locked player instance
1880  * @return scale factor
1881  */
1882 VLC_API unsigned
1884 
1885 /** @} vlc_player__tracks */
1886 
1887 /**
1888  * @defgroup vlc_player__tracks_sync Tracks synchronisation (delay)
1889  * @{
1890  */
1891 
1892 /**
1893  * Get the delay of an ES category for the current media
1894  *
1895  * @see vlc_player_cbs.on_category_delay_changed
1896  *
1897  * @param player locked player instance
1898  * @param cat AUDIO_ES or SPU_ES (VIDEO_ES not supported yet)
1899  * @return a valid delay or 0
1900  */
1903 
1904 /**
1905  * Set the delay of one category for the current media
1906  *
1907  * @note A successful call will trigger the
1908  * vlc_player_cbs.on_category_delay_changed event.
1909  *
1910  * @warning This has no effect on tracks where the delay was set by
1911  * vlc_player_SetEsIdDelay()
1912  *
1913  * @param player locked player instance
1914  * @param cat AUDIO_ES or SPU_ES (VIDEO_ES not supported yet)
1915  * @param delay a valid time
1916  * @param whence absolute or relative
1917  * @return VLC_SUCCESS or VLC_EGENERIC if the category is not handled
1918  */
1919 VLC_API int
1921  vlc_tick_t delay, enum vlc_player_whence whence);
1922 
1923 /**
1924  * Get the delay of a track
1925  *
1926  * @see vlc_player_cbs.on_track_delay_changed
1927  *
1928  * @param player locked player instance
1929  * @param es_id an ES ID (retrieved from vlc_player_cbs.on_track_list_changed or
1930  * vlc_player_GetTrackAt())
1931  * @return a valid delay or INT64_MAX is no delay is set for this track
1932  */
1935 
1936 /**
1937  * Set the delay of one track
1938  *
1939  * @note A successful call will trigger the
1940  * vlc_player_cbs.on_track_delay_changed event.
1941  *
1942  * @warning Setting the delay of one specific track will override previous and
1943  * future changes of delay made by vlc_player_SetCategoryDelay()
1944  *
1945  * @param player locked player instance
1946  * @param es_id an ES ID (retrieved from vlc_player_cbs.on_track_list_changed or
1947  * vlc_player_GetTrackAt())
1948  * @param delay a valid time or INT64_MAX to use default category delay
1949  * @param whence absolute or relative
1950  * @return VLC_SUCCESS or VLC_EGENERIC if the category of the es_id is not
1951  * handled (VIDEO_ES not supported yet)
1952  */
1953 VLC_API int
1955  vlc_tick_t delay, enum vlc_player_whence whence);
1956 
1957 /**
1958  * Helper to get the audio delay
1959  */
1960 static inline vlc_tick_t
1963  return vlc_player_GetCategoryDelay(player, AUDIO_ES);
1964 }
1965 
1966 /**
1967  * Helper to set the audio delay
1968  */
1969 static inline void
1971  enum vlc_player_whence whence)
1972 
1973 {
1974  vlc_player_SetCategoryDelay(player, AUDIO_ES, delay, whence);
1975 }
1976 
1977 /**
1978  * Helper to get the subtitle delay
1979  */
1980 static inline vlc_tick_t
1983  return vlc_player_GetCategoryDelay(player, SPU_ES);
1984 }
1985 
1986 /**
1987  * Helper to set the subtitle delay
1988  */
1989 static inline void
1991  enum vlc_player_whence whence)
1992 {
1993  vlc_player_SetCategoryDelay(player, SPU_ES, delay, whence);
1994 }
1995 
1996 /**
1997  * Set the associated subtitle FPS
1998  *
1999  * In order to correct the rate of the associated media according to this FPS
2000  * and the media video FPS.
2001  *
2002  * @note A successful call will trigger the
2003  * vlc_player_cbs.on_associated_subs_fps_changed event.
2004  *
2005  * @warning this function will change the rate of all external subtitle files
2006  * associated with the current media.
2007  *
2008  * @param player locked player instance
2009  * @param fps FPS of the subtitle file
2010  */
2011 VLC_API void
2012 vlc_player_SetAssociatedSubsFPS(vlc_player_t *player, float fps);
2013 
2014 /**
2015  * Get the associated subtitle FPS
2016  *
2017  * @param player locked player instance
2018  * @return fps
2019  */
2020 VLC_API float
2022 
2023 /** @} vlc_player__tracks_sync */
2024 
2025 /**
2026  * @defgroup vlc_player__teletext Teletext control
2027  * @{
2028  */
2029 
2030 /**
2031  * Check if the media has a teletext menu
2032  *
2033  * @see vlc_player_cbs.on_teletext_menu_changed
2034  *
2035  * @param player locked player instance
2036  * @return true if the media has a teletext menu
2037  */
2038 VLC_API bool
2040 
2041 /**
2042  * Enable or disable teletext
2043  *
2044  * This function has an effect only if the player has a teletext menu.
2045  *
2046  * @note A successful call will trigger the
2047  * vlc_player_cbs.on_teletext_enabled_changed event.
2048  *
2049  * @param player locked player instance
2050  * @param enabled true to enable
2051  */
2052 VLC_API void
2053 vlc_player_SetTeletextEnabled(vlc_player_t *player, bool enabled);
2054 
2055 /**
2056  * Check if teletext is enabled
2057  *
2058  * @see vlc_player_cbs.on_teletext_enabled_changed
2059  *
2060  * @param player locked player instance
2061  */
2062 VLC_API bool
2064 
2065 /**
2066  * Select a teletext page or do an action from a key
2067  *
2068  * This function has an effect only if the player has a teletext menu.
2069  *
2070  * @note Page keys can be the following: @ref VLC_PLAYER_TELETEXT_KEY_RED,
2071  * @ref VLC_PLAYER_TELETEXT_KEY_GREEN, @ref VLC_PLAYER_TELETEXT_KEY_YELLOW,
2072  * @ref VLC_PLAYER_TELETEXT_KEY_BLUE or @ref VLC_PLAYER_TELETEXT_KEY_INDEX.
2073 
2074  * @note A successful call will trigger the
2075  * vlc_player_cbs.on_teletext_page_changed event.
2076  *
2077  * @param player locked player instance
2078  * @param page a page in the range ]0;888] or a valid key
2079  */
2080 VLC_API void
2081 vlc_player_SelectTeletextPage(vlc_player_t *player, unsigned page);
2082 
2083 /**
2084  * Get the current teletext page
2085  *
2086  * @see vlc_player_cbs.on_teletext_page_changed
2087  *
2088  * @param player locked player instance
2089  */
2090 VLC_API unsigned
2092 
2093 /**
2094  * Enable or disable teletext transparency
2095  *
2096  * This function has an effect only if the player has a teletext menu.
2097 
2098  * @note A successful call will trigger the
2099  * vlc_player_cbs.on_teletext_transparency_changed event.
2100  *
2101  * @param player locked player instance
2102  * @param enabled true to enable
2103  */
2104 VLC_API void
2105 vlc_player_SetTeletextTransparency(vlc_player_t *player, bool enabled);
2106 
2107 /**
2108  * Check if teletext is transparent
2109  *
2110  * @param player locked player instance
2111  */
2112 VLC_API bool
2114 
2115 /** @} vlc_player__teletext */
2116 
2117 /**
2118  * @defgroup vlc_player__renderer External renderer control
2119  * @{
2120  */
2121 
2122 /**
2123  * Set the renderer
2124  *
2125  * Valid for the current media and all future ones.
2126  *
2127  * @note A successful call will trigger the vlc_player_cbs.on_renderer_changed
2128  * event.
2129  *
2130  * @param player locked player instance
2131  * @param renderer a valid renderer item or NULL (to disable it), the item will
2132  * be held by the player
2133  */
2134 VLC_API void
2136 
2137 /**
2138  * Get the renderer
2139  *
2140  * @see vlc_player_cbs.on_renderer_changed
2141  *
2142  * @param player locked player instance
2143  * @return the renderer item set by vlc_player_SetRenderer()
2144  */
2148 /** @} vlc_player__renderer */
2149 
2150 /**
2151  * @defgroup vlc_player__metadata Metadata callbacks
2152  * @{
2153  */
2154 
2155 /**
2156  * Player metadata listener opaque structure.
2157  *
2158  * This opaque structure is returned by vlc_player_AddMetadataListener() and
2159  * can be used to remove the listener via
2160  * vlc_player_RemoveMetadataListener().
2161  */
2163 
2164 /**
2165  * Player metadata option
2166  */
2169  /**
2170  * Ask for momentary loudness measurement
2171  *
2172  * Very low CPU usage.
2173  * @see vlc_player_metadata_cbs.on_momentary_loudness_changed
2174  */
2177  /**
2178  * Ask for all loudness measurements
2179  *
2180  * High CPU usage.
2181  * @see vlc_player_metadata_cbs.on_loudness_changed
2182  */
2184 };
2185 
2186 /**
2187  * Player metadata callbacks
2188  *
2189  * Can be registered with vlc_player_AddMetadataListener().
2190  *
2191  * @warning To avoid deadlocks, users should never call vlc_player_t functions
2192  * from these callbacks.
2193  */
2196  /**
2197  * Called when the momentary loudness measurement have changed
2198  *
2199  * @see VLC_PLAYER_METADATA_LOUDNESS_MOMEMTARY
2200  *
2201  * Only sent when audio is playing, approximately every 400ms (but can be
2202  * higher, depending on the input sample size).
2203  *
2204  * @param date Absolute date of the measurement. It is most likely in the
2205  * future (0 to 2seconds) depending on the audio output buffer size.
2206  * @param momentary_loudness Momentary loudness
2207  * @param data opaque pointer set by vlc_player_AddMetadataListener()
2208  */
2210  double momentary_loudness,
2211  void *data);
2212 
2213  /**
2214  * Called when loudness measurements have changed
2215  *
2216  * @see VLC_PLAYER_METADATA_LOUDNESS_FULL
2217  *
2218  * Only sent when audio is playing, approximately every 400ms (but can be
2219  * higher, depending on the input sample size).
2220  *
2221  * @param date Absolute date of the measurement. It is most likely in the
2222  * future (0 to 2seconds) depending on the audio output buffer size.
2223  * @param loudness loudness measurement
2224  * @param data opaque pointer set by vlc_player_AddMetadataListener()
2225  */
2226  void (*on_loudness_changed)(vlc_tick_t date,
2227  const struct vlc_audio_loudness *loudness,
2228  void *data);
2229 };
2230 
2231 /**
2232  * Add a metadata listener
2233  *
2234  * @note Every registered loudness meter need to be removed by the caller with
2235  * vlc_player_RemoveMetadataListener().
2236  *
2237  * @param player locked player instance
2238  * @param cbs pointer to a vlc_player_metadata_cbs union, the
2239  * structure must be valid during the lifetime of the player
2240  * @param cbs_data opaque pointer used by the callbacks
2241  * @return a valid listener id, or NULL in case of error (plugin missing)
2242  */
2245  enum vlc_player_metadata_option option,
2246  const union vlc_player_metadata_cbs *cbs,
2247  void *cbs_data);
2248 
2249 /**
2250  * Remove a metadata listener
2251  *
2252  * @param player player instance
2253  * @param listener_id listener id returned by vlc_player_AddMetadataListener()
2254  */
2255 VLC_API void
2258 
2259 
2260 /** @} vlc_player__metadata */
2261 
2262 /**
2263  * @defgroup vlc_player__aout Audio output control
2264  * @{
2265  */
2266 
2267 /**
2268  * Player aout listener opaque structure.
2269  *
2270  * This opaque structure is returned by vlc_player_aout_AddListener() and can
2271  * be used to remove the listener via vlc_player_aout_RemoveListener().
2272  */
2274 
2275 /**
2276  * Player aout callbacks
2277  *
2278  * Can be registered with vlc_player_aout_AddListener().
2279  *
2280  * @warning To avoid deadlocks, users should never call audio_output_t and
2281  * vlc_player_t functions from these callbacks.
2282  */
2283 struct vlc_player_aout_cbs
2285  /**
2286  * Called when the volume has changed
2287  *
2288  * @see vlc_player_aout_SetVolume()
2289  *
2290  * @param aout the main aout of the player
2291  * @param new_volume volume in the range [0;2.f]
2292  * @param data opaque pointer set by vlc_player_aout_AddListener()
2293  */
2294  void (*on_volume_changed)(audio_output_t *aout, float new_volume,
2295  void *data);
2296 
2297  /**
2298  * Called when the mute state has changed
2299  *
2300  * @see vlc_player_aout_Mute()
2301  *
2302  * @param aout the main aout of the player
2303  * @param new_mute true if muted
2304  * @param data opaque pointer set by vlc_player_aout_AddListener()
2305  */
2306  void (*on_mute_changed)(audio_output_t *aout, bool new_muted,
2307  void *data);
2308 
2309  /**
2310  * Called when the audio device has changed
2311  *
2312  * @param aout the main aout of the player
2313  * @param device the device name
2314  * @param data opaque pointer set by vlc_player_aout_AddListener()
2315  */
2316  void (*on_device_changed)(audio_output_t *aout, const char *device,
2317  void *data);
2318 };
2319 
2320 /**
2321  * Get the audio output
2322  *
2323  * @warning The returned pointer must be released with aout_Release().
2324  *
2325  * @param player player instance
2326  * @return a valid audio_output_t * or NULL (if there is no aouts)
2327  */
2330 
2331 /**
2332  * Reset the main audio output
2333  *
2334  * @warning The main aout can only by reset if it is not currently used by any
2335  * decoders (before any play).
2336  *
2337  * @param player player instance
2338  */
2339 VLC_API void
2341 
2342 /**
2343  * Add a listener callback for audio output events
2344  *
2345  * @note The player instance doesn't need to be locked for vlc_player_aout_*()
2346  * functions.
2347  * @note Every registered callbacks need to be removed by the caller with
2348  * vlc_player_aout_RemoveListener().
2349  *
2350  * @param player player instance
2351  * @param cbs pointer to a vlc_player_aout_cbs structure, the structure must be
2352  * valid during the lifetime of the player
2353  * @param cbs_data opaque pointer used by the callbacks
2354  * @return a valid listener id, or NULL in case of allocation error
2355  */
2358  const struct vlc_player_aout_cbs *cbs,
2359  void *cbs_data);
2360 
2361 /**
2362  * Remove a aout listener callback
2363  *
2364  * @param player player instance
2365  * @param listener_id listener id returned by vlc_player_aout_AddListener()
2366  */
2367 VLC_API void
2369  vlc_player_aout_listener_id *listener_id);
2370 
2371 /**
2372  * Get the audio volume
2373  *
2374  * @note The player instance doesn't need to be locked for vlc_player_aout_*()
2375  * functions.
2376  *
2377  * @see vlc_player_aout_cbs.on_volume_changed
2378  *
2379  * @param player player instance
2380  * @return volume in the range [0;2.f] or -1.f if there is no audio outputs
2381  * (independent of mute)
2382  */
2383 VLC_API float
2385 
2386 /**
2387  * Set the audio volume
2388  *
2389  * @note The player instance doesn't need to be locked for vlc_player_aout_*()
2390  * functions.
2391  *
2392  * @note A successful call will trigger the
2393  * vlc_player_vout_cbs.on_volume_changed event.
2394  *
2395  * @param player player instance
2396  * @param volume volume in the range [0;2.f]
2397  * @return VLC_SUCCESS or VLC_EGENERIC if there is no audio outputs
2398  */
2399 VLC_API int
2400 vlc_player_aout_SetVolume(vlc_player_t *player, float volume);
2401 
2402 /**
2403  * Increment the audio volume
2404  *
2405  * @see vlc_player_aout_SetVolume()
2406  *
2407  * @param player player instance
2408  * @param steps number of "volume-step"
2409  * @param result pointer to store the resulting volume (can be NULL)
2410  * @return VLC_SUCCESS or VLC_EGENERIC if there is no audio outputs
2411  */
2412 VLC_API int
2413 vlc_player_aout_IncrementVolume(vlc_player_t *player, int steps, float *result);
2414 
2415 /**
2416  * Helper to decrement the audio volume
2417  */
2418 static inline int
2419 vlc_player_aout_DecrementVolume(vlc_player_t *player, int steps, float *result)
2421  return vlc_player_aout_IncrementVolume(player, -steps, result);
2422 }
2423 
2424 /**
2425  * Check if the audio output is muted
2426  *
2427  * @note The player instance doesn't need to be locked for vlc_player_aout_*()
2428  * functions.
2429  *
2430  * @see vlc_player_aout_cbs.on_mute_changed
2431  *
2432  * @param player player instance
2433  * @return 0 if not muted, 1 if muted, -1 if there is no audio outputs
2434  */
2435 VLC_API int
2437 
2438 /**
2439  * Mute or unmute the audio output
2440  *
2441  * @note The player instance doesn't need to be locked for vlc_player_aout_*()
2442  * functions.
2443  *
2444  * @note A successful call will trigger the
2445  * vlc_player_aout_cbs.on_mute_changed event.
2446  *
2447  * @param player player instance
2448  * @param mute true to mute
2449  * @return VLC_SUCCESS or VLC_EGENERIC if there is no audio outputs
2450  */
2451 VLC_API int
2452 vlc_player_aout_Mute(vlc_player_t *player, bool mute);
2453 
2454 /**
2455  * Helper to toggle the mute state
2456  */
2457 static inline int
2460  return vlc_player_aout_Mute(player,
2461  !vlc_player_aout_IsMuted(player));
2462 }
2463 
2464 /**
2465  * Enable or disable an audio filter
2466  *
2467  * @see aout_EnableFilter()
2468  *
2469  * @return VLC_SUCCESS or VLC_EGENERIC if there is no audio outputs
2470  */
2471 VLC_API int
2472 vlc_player_aout_EnableFilter(vlc_player_t *player, const char *name, bool add);
2474 /** @} vlc_player__aout */
2475 
2476 /**
2477  * @defgroup vlc_player__vout Video output control
2478  * @{
2479  */
2480 
2481 /**
2482  * Player vout listener opaque structure.
2483  *
2484  * This opaque structure is returned by vlc_player_vout_AddListener() and can
2485  * be used to remove the listener via vlc_player_vout_RemoveListener().
2486  */
2488 
2489 /**
2490  * action of vlc_player_cbs.on_vout_changed callback
2491  */
2496 };
2497 
2498 /**
2499  * Player vout callbacks
2500  *
2501  * Can be registered with vlc_player_vout_AddListener().
2502  *
2503  * @note The state changed from the callbacks can be either applied on the
2504  * player (and all future video outputs), or on a specified video output. The
2505  * state is applied on the player when the vout argument is NULL.
2506  *
2507  * @warning To avoid deadlocks, users should never call vout_thread_t and
2508  * vlc_player_t functions from these callbacks.
2509  */
2510 struct vlc_player_vout_cbs
2512  /**
2513  * Called when the player and/or vout fullscreen state has changed
2514  *
2515  * @see vlc_player_vout_SetFullscreen()
2516  *
2517  * @param vout cf. vlc_player_vout_cbs note
2518  * @param enabled true when fullscreen is enabled
2519  * @param data opaque pointer set by vlc_player_vout_AddListener()
2520  */
2521  void (*on_fullscreen_changed)(vout_thread_t *vout, bool enabled,
2522  void *data);
2523 
2524  /**
2525  * Called when the player and/or vout wallpaper mode has changed
2526  *
2527  * @see vlc_player_vout_SetWallpaperModeEnabled()
2528  *
2529  * @param vout cf. vlc_player_vout_cbs note
2530  * @param enabled true when wallpaper mode is enabled
2531  * @param data opaque pointer set by vlc_player_vout_AddListener()
2532  */
2533  void (*on_wallpaper_mode_changed)(vout_thread_t *vout, bool enabled,
2534  void *data);
2535 };
2536 
2537 
2538 /**
2539  * Get and hold the main video output
2540  *
2541  * @warning the returned vout_thread_t * must be released with vout_Release().
2542  * @see vlc_players_cbs.on_vout_changed
2543  *
2544  * @note The player is guaranteed to always hold one valid vout. Only vout
2545  * variables can be changed from this instance. The vout returned before
2546  * playback is not necessarily the same one that will be used for playback.
2547  *
2548  * @param player player instance
2549  * @return a valid vout_thread_t * or NULL, cf. warning
2550  */
2553 
2554 /**
2555  * Get and hold the list of video output
2556  *
2557  * @warning All vout_thread_t * element of the array must be released with
2558  * vout_Release(). The returned array must be freed.
2559  *
2560  * @see vlc_players_cbs.on_vout_changed
2561  *
2562  * @param player player instance
2563  * @param count valid pointer to store the array count
2564  * @return a array of vout_thread_t * or NULL, cf. warning
2565  */
2567 vlc_player_vout_HoldAll(vlc_player_t *player, size_t *count);
2568 
2569 /**
2570  * Add a listener callback for video output events
2571  *
2572  * @note The player instance doesn't need to be locked for vlc_player_vout_*()
2573  * functions.
2574  * @note Every registered callbacks need to be removed by the caller with
2575  * vlc_player_vout_RemoveListener().
2576  *
2577  * @param player player instance
2578  * @param cbs pointer to a vlc_player_vout_cbs structure, the structure must be
2579  * valid during the lifetime of the player
2580  * @param cbs_data opaque pointer used by the callbacks
2581  * @return a valid listener id, or NULL in case of allocation error
2582  */
2585  const struct vlc_player_vout_cbs *cbs,
2586  void *cbs_data);
2587 
2588 /**
2589  * Remove a vout listener callback
2590  *
2591  * @param player player instance
2592  * @param listener_id listener id returned by vlc_player_vout_AddListener()
2593  */
2594 VLC_API void
2596  vlc_player_vout_listener_id *listener_id);
2597 
2598 /**
2599  * Check if the player is fullscreen
2600  *
2601  * @warning The fullscreen state of the player and all vouts can be different.
2602  *
2603  * @note The player instance doesn't need to be locked for vlc_player_vout_*()
2604  * functions.
2605  *
2606  * @see vlc_player_vout_cbs.on_fullscreen_changed
2607  *
2608  * @param player player instance
2609  * @return true if the player is fullscreen
2610  */
2611 VLC_API bool
2613 
2614 /**
2615  * Enable or disable the player fullscreen state
2616  *
2617  * This will have an effect on all current and future vouts.
2618  *
2619  * @note The player instance doesn't need to be locked for vlc_player_vout_*()
2620  * functions.
2621  * @note A successful call will trigger the
2622  * vlc_player_vout_cbs.on_fullscreen_changed event.
2623  *
2624  * @param player player instance
2625  * @param enabled true to enable fullscreen
2626  */
2627 VLC_API void
2628 vlc_player_vout_SetFullscreen(vlc_player_t *player, bool enabled);
2629 
2630 /**
2631  * Helper to toggle the player fullscreen state
2632  */
2633 static inline void
2637  !vlc_player_vout_IsFullscreen(player));
2638 }
2639 
2640 /**
2641  * Check if the player has wallpaper-mode enaled
2642  *
2643  * @warning The wallpaper-mode state of the player and all vouts can be
2644  * different.
2645  *
2646  * @note The player instance doesn't need to be locked for vlc_player_vout_*()
2647  * functions.
2648  *
2649  * @see vlc_player_vout_cbs.on_wallpaper_mode_changed
2650  *
2651  * @param player player instance
2652  * @return true if the player is fullscreen
2653  */
2654 VLC_API bool
2656 
2657 /**
2658  * Enable or disable the player wallpaper-mode
2659  *
2660  * This will have an effect on all current and future vouts.
2661  *
2662  * @note The player instance doesn't need to be locked for vlc_player_vout_*()
2663  * functions.
2664  * @note A successful call will trigger the
2665  * vlc_player_vout_cbs.on_wallpaper_mode_changed event.
2666  *
2667  * @param player player instance
2668  * @param enabled true to enable wallpaper-mode
2669  */
2670 VLC_API void
2672 
2673 /**
2674  * Helper to toggle the player wallpaper-mode state
2675  */
2676 static inline void
2681 }
2682 
2683 /**
2684  * Take a snapshot on all vouts
2685  *
2686  * @param player player instance
2687  */
2688 VLC_API void
2690 
2691 /**
2692  * Display an OSD message on all vouts
2693  *
2694  * @param player player instance
2695  * @param fmt format string
2696  */
2697 VLC_API void
2698 vlc_player_osd_Message(vlc_player_t *player, const char *fmt, ...);
2700 /** @} vlc_player__vout */
2701 
2702 /**
2703  * @defgroup vlc_player__events Player events
2704  * @{
2705  */
2706 
2707 /**
2708  * Player listener opaque structure.
2709  *
2710  * This opaque structure is returned by vlc_player_AddListener() and can be
2711  * used to remove the listener via vlc_player_RemoveListener().
2712  */
2714 
2715 /**
2716  * Action of vlc_player_cbs.on_track_list_changed,
2717  * vlc_player_cbs.on_program_list_changed callbacks
2718  */
2724 };
2725 
2726 /**
2727  * Player callbacks
2728  *
2729  * Can be registered with vlc_player_AddListener().
2730  *
2731  * All callbacks are called with the player locked (cf. vlc_player_Lock()) and
2732  * from any threads (and even synchronously from a vlc_player function in some
2733  * cases). It is safe to call any vlc_player functions from these callbacks
2734  * except vlc_player_Delete().
2735  *
2736  * @warning To avoid deadlocks, users should never call vlc_player functions
2737  * with an external mutex locked and lock this same mutex from a player
2738  * callback.
2739  */
2740 struct vlc_player_cbs
2742  /**
2743  * Called when the current media has changed
2744  *
2745  * @note This can be called from the PLAYING state (when the player plays
2746  * the next media internally) or from the STOPPED state (from
2747  * vlc_player_SetCurrentMedia() or from an internal transition).
2748  *
2749  * @see vlc_player_SetCurrentMedia()
2750  * @see vlc_player_InvalidateNextMedia()
2751  *
2752  * @param player locked player instance
2753  * @param new_media new media currently played or NULL (when there is no
2754  * more media to play)
2755  * @param data opaque pointer set by vlc_player_AddListener()
2756  */
2757  void (*on_current_media_changed)(vlc_player_t *player,
2758  input_item_t *new_media, void *data);
2759 
2760  /**
2761  * Called when the player state has changed
2762  *
2763  * @see vlc_player_state
2764  *
2765  * @param player locked player instance
2766  * @param new_state new player state
2767  * @param data opaque pointer set by vlc_player_AddListener()
2768  */
2769  void (*on_state_changed)(vlc_player_t *player,
2770  enum vlc_player_state new_state, void *data);
2771 
2772  /**
2773  * Called when a media triggered an error
2774  *
2775  * Can be called from any states. When it happens the player will stop
2776  * itself. It is safe to play an other media or event restart the player
2777  * (This will reset the error state).
2778  *
2779  * @param player locked player instance
2780  * @param error player error
2781  * @param data opaque pointer set by vlc_player_AddListener()
2782  */
2783  void (*on_error_changed)(vlc_player_t *player,
2784  enum vlc_player_error error, void *data);
2785 
2786  /**
2787  * Called when the player buffering (or cache) has changed
2788  *
2789  * This event is always called with the 0 and 1 values before a playback
2790  * (in case of success). Values in between depends on the media type.
2791  *
2792  * @param player locked player instance
2793  * @param new_buffering buffering in the range [0:1]
2794  * @param data opaque pointer set by vlc_player_AddListener()
2795  */
2796  void (*on_buffering_changed)(vlc_player_t *player,
2797  float new_buffering, void *data);
2798 
2799  /**
2800  * Called when the player rate has changed
2801  *
2802  * Triggered by vlc_player_ChangeRate(), not sent when the media starts
2803  * with the default rate (1.f)
2804  *
2805  * @param player locked player instance
2806  * @param new_rate player
2807  * @param data opaque pointer set by vlc_player_AddListener()
2808  */
2809  void (*on_rate_changed)(vlc_player_t *player,
2810  float new_rate, void *data);
2811 
2812  /**
2813  * Called when the media capabilities has changed
2814  *
2815  * Always called when the media is opening. Can be called during playback.
2816  *
2817  * @param player locked player instance
2818  * @param old_caps old player capabilities
2819  * @param new_caps new player capabilities
2820  * @param data opaque pointer set by vlc_player_AddListener()
2821  */
2822  void (*on_capabilities_changed)(vlc_player_t *player,
2823  int old_caps, int new_caps, void *data);
2824 
2825  /**
2826  * Called when the player position has changed
2827  *
2828  * @note A started and playing media doesn't have necessarily a valid time.
2829  *
2830  * @param player locked player instance
2831  * @param new_time a valid time or VLC_TICK_INVALID
2832  * @param new_pos a valid position
2833  * @param data opaque pointer set by vlc_player_AddListener()
2834  */
2835  void (*on_position_changed)(vlc_player_t *player,
2836  vlc_tick_t new_time, float new_pos, void *data);
2837 
2838  /**
2839  * Called when the media length has changed
2840  *
2841  * May be called when the media is opening or during playback.
2842  *
2843  * @note A started and playing media doesn't have necessarily a valid length.
2844  *
2845  * @param player locked player instance
2846  * @param new_length a valid time or VLC_TICK_INVALID
2847  * @param data opaque pointer set by vlc_player_AddListener()
2848  */
2849  void (*on_length_changed)(vlc_player_t *player,
2850  vlc_tick_t new_length, void *data);
2851 
2852  /**
2853  * Called when a track is added, removed, or updated
2854  *
2855  * @note The track is only valid from this callback context. Users should
2856  * duplicate this track via vlc_player_track_Dup() if they want to use it
2857  * from an other context.
2858  *
2859  * @param player locked player instance
2860  * @param action added, removed or updated
2861  * @param track valid track
2862  * @param data opaque pointer set by vlc_player_AddListener()
2863  */
2864  void (*on_track_list_changed)(vlc_player_t *player,
2866  const struct vlc_player_track *track, void *data);
2867 
2868  /**
2869  * Called when a new track is selected and/or unselected
2870  *
2871  * @note This event can be called with both unselected_id and selected_id
2872  * valid. This mean that a new track is replacing the old one.
2873  *
2874  * @param player locked player instance
2875  * @param unselected_id valid track id or NULL (when nothing is unselected)
2876  * @param selected_id valid track id or NULL (when nothing is selected)
2877  * @param data opaque pointer set by vlc_player_AddListener()
2878  */
2879  void (*on_track_selection_changed)(vlc_player_t *player,
2880  vlc_es_id_t *unselected_id, vlc_es_id_t *selected_id, void *data);
2881 
2882  /**
2883  * Called when a track delay has changed
2884  *
2885  * @param player locked player instance
2886  * @param es_id valid track id
2887  * @param delay a valid delay or INT64_MAX if the delay of this track is
2888  * canceled
2889  */
2890  void (*on_track_delay_changed)(vlc_player_t *player,
2891  vlc_es_id_t *es_id, vlc_tick_t delay, void *data);
2892 
2893  /**
2894  * Called when a new program is added, removed or updated
2895  *
2896  * @note The program is only valid from this callback context. Users should
2897  * duplicate this program via vlc_player_program_Dup() if they want to use
2898  * it from an other context.
2899  *
2900  * @param player locked player instance
2901  * @param action added, removed or updated
2902  * @param prgm valid program
2903  * @param data opaque pointer set by vlc_player_AddListener()
2904  */
2905  void (*on_program_list_changed)(vlc_player_t *player,
2907  const struct vlc_player_program *prgm, void *data);
2908 
2909  /**
2910  * Called when a new program is selected and/or unselected
2911  *
2912  * @note This event can be called with both unselected_id and selected_id
2913  * valid. This mean that a new program is replacing the old one.
2914  *
2915  * @param player locked player instance
2916  * @param unselected_id valid program id or -1 (when nothing is unselected)
2917  * @param selected_id valid program id or -1 (when nothing is selected)
2918  * @param data opaque pointer set by vlc_player_AddListener()
2919  */
2921  int unselected_id, int selected_id, void *data);
2922 
2923  /**
2924  * Called when the media titles has changed
2925  *
2926  * This event is not called when the opening media doesn't have any titles.
2927  * This title list and all its elements are constant. If an element is to
2928  * be updated, a new list will be sent from this callback.
2929  *
2930  * @note Users should hold this list with vlc_player_title_list_Hold() if
2931  * they want to use it from an other context.
2932  *
2933  * @param player locked player instance
2934  * @param titles valid title list or NULL
2935  * @param data opaque pointer set by vlc_player_AddListener()
2936  */
2937  void (*on_titles_changed)(vlc_player_t *player,
2938  vlc_player_title_list *titles, void *data);
2939 
2940  /**
2941  * Called when a new title is selected
2942  *
2943  * There are no events when a title is unselected. Titles are automatically
2944  * unselected when the title list changes. Titles and indexes are always
2945  * valid inside the vlc_player_title_list sent by
2946  * vlc_player_cbs.on_titles_changed.
2947  *
2948  * @param player locked player instance
2949  * @param new_title new selected title
2950  * @param new_idx index of this title
2951  * @param data opaque pointer set by vlc_player_AddListener()
2952  */
2953  void (*on_title_selection_changed)(vlc_player_t *player,
2954  const struct vlc_player_title *new_title, size_t new_idx, void *data);
2955 
2956  /**
2957  * Called when a new chapter is selected
2958  *
2959  * There are no events when a chapter is unselected. Chapters are
2960  * automatically unselected when the title list changes. Titles, chapters
2961  * and indexes are always valid inside the vlc_player_title_list sent by
2962  * vlc_player_cbs.on_titles_changed.
2963  *
2964  * @param player locked player instance
2965  * @param title selected title
2966  * @param title_idx selected title index
2967  * @param chapter new selected chapter
2968  * @param chapter_idx new selected chapter index
2969  * @param data opaque pointer set by vlc_player_AddListener()
2970  */
2972  const struct vlc_player_title *title, size_t title_idx,
2973  const struct vlc_player_chapter *new_chapter, size_t new_chapter_idx,
2974  void *data);
2975 
2976  /**
2977  * Called when the media has a teletext menu
2978  *
2979  * @param player locked player instance
2980  * @param has_teletext_menu true if the media has a teletext menu
2981  * @param data opaque pointer set by vlc_player_AddListener()
2982  */
2983  void (*on_teletext_menu_changed)(vlc_player_t *player,
2984  bool has_teletext_menu, void *data);
2985 
2986  /**
2987  * Called when teletext is enabled or disabled
2988  *
2989  * @see vlc_player_SetTeletextEnabled()
2990  *
2991  * @param player locked player instance
2992  * @param enabled true if teletext is enabled
2993  * @param data opaque pointer set by vlc_player_AddListener()
2994  */
2995  void (*on_teletext_enabled_changed)(vlc_player_t *player,
2996  bool enabled, void *data);
2997 
2998  /**
2999  * Called when the teletext page has changed
3000  *
3001  * @see vlc_player_SelectTeletextPage()
3002  *
3003  * @param player locked player instance
3004  * @param new_page page in the range ]0;888]
3005  * @param data opaque pointer set by vlc_player_AddListener()
3006  */
3007  void (*on_teletext_page_changed)(vlc_player_t *player,
3008  unsigned new_page, void *data);
3009 
3010  /**
3011  * Called when the teletext transparency has changed
3012  *
3013  * @see vlc_player_SetTeletextTransparency()
3014  *
3015  * @param player locked player instance
3016  * @param enabled true is the teletext overlay is transparent
3017  * @param data opaque pointer set by vlc_player_AddListener()
3018  */
3020  bool enabled, void *data);
3021 
3022  /**
3023  * Called when the player category delay has changed for the current media
3024  *
3025  * @see vlc_player_SetCategoryDelay()
3026  *
3027  * @param player locked player instance
3028  * @param cat AUDIO_ES or SPU_ES
3029  * @param new_delay audio delay
3030  * @param data opaque pointer set by vlc_player_AddListener()
3031  */
3032  void (*on_category_delay_changed)(vlc_player_t *player,
3033  enum es_format_category_e cat, vlc_tick_t new_delay, void *data);
3034 
3035  /**
3036  * Called when associated subtitle has changed
3037  *
3038  * @see vlc_player_SetAssociatedSubsFPS()
3039  *
3040  * @param player locked player instance
3041  * @param sub_fps subtitle fps
3042  * @param data opaque pointer set by vlc_player_AddListener()
3043  */
3045  float subs_fps, void *data);
3046 
3047  /**
3048  * Called when a new renderer item is set
3049  *
3050  * @see vlc_player_SetRenderer()
3051  *
3052  * @param player locked player instance
3053  * @param new_item a valid renderer item or NULL (if unset)
3054  * @param data opaque pointer set by vlc_player_AddListener()
3055  */
3056  void (*on_renderer_changed)(vlc_player_t *player,
3057  vlc_renderer_item_t *new_item, void *data);
3058 
3059  /**
3060  * Called when the player recording state has changed
3061  *
3062  * @see vlc_player_SetRecordingEnabled()
3063  *
3064  * @param player locked player instance
3065  * @param recording true if recording is enabled
3066  * @param data opaque pointer set by vlc_player_AddListener()
3067  */
3068  void (*on_recording_changed)(vlc_player_t *player,
3069  bool recording, void *data);
3070 
3071  /**
3072  * Called when the media signal has changed
3073  *
3074  * @param player locked player instance
3075  * @param new_quality signal quality
3076  * @param new_strength signal strength,
3077  * @param data opaque pointer set by vlc_player_AddListener()
3078  */
3079  void (*on_signal_changed)(vlc_player_t *player,
3080  float quality, float strength, void *data);
3081 
3082  /**
3083  * Called when the player has new statisics
3084  *
3085  * @note The stats structure is only valid from this callback context. It
3086  * can be copied in order to use it from an other context.
3087  *
3088  * @param player locked player instance
3089  * @param stats valid stats, only valid from this context
3090  * @param data opaque pointer set by vlc_player_AddListener()
3091  */
3092  void (*on_statistics_changed)(vlc_player_t *player,
3093  const struct input_stats_t *stats, void *data);
3094 
3095  /**
3096  * Called when the A to B loop has changed
3097  *
3098  * @see vlc_player_SetAtoBLoop()
3099  *
3100  * @param player locked player instance
3101  * @param state A, when only A is set, B when both A and B are set, None by
3102  * default
3103  * @param time valid time or VLC_TICK_INVALID of the current state
3104  * @param pos valid pos of the current state
3105  * @param data opaque pointer set by vlc_player_AddListener()
3106  */
3107  void (*on_atobloop_changed)(vlc_player_t *player,
3108  enum vlc_player_abloop new_state, vlc_tick_t time, float pos,
3109  void *data);
3110 
3111  /**
3112  * Called when media stopped action has changed
3113  *
3114  * @see vlc_player_SetMediaStoppedAction()
3115  *
3116  * @param player locked player instance
3117  * @param new_action action to execute when a media is stopped
3118  * @param data opaque pointer set by vlc_player_AddListener()
3119  */
3121  enum vlc_player_media_stopped_action new_action, void *data);
3122 
3123  /**
3124  * Called when the media meta has changed
3125  *
3126  * @param player locked player instance
3127  * @param media current media
3128  * @param data opaque pointer set by vlc_player_AddListener()
3129  */
3130  void (*on_media_meta_changed)(vlc_player_t *player,
3131  input_item_t *media, void *data);
3132 
3133  /**
3134  * Called when media epg has changed
3135  *
3136  * @param player locked player instance
3137  * @param media current media
3138  * @param data opaque pointer set by vlc_player_AddListener()
3139  */
3140  void (*on_media_epg_changed)(vlc_player_t *player,
3141  input_item_t *media, void *data);
3142 
3143  /**
3144  * Called when the media has new subitems
3145  *
3146  * @param player locked player instance
3147  * @param media current media
3148  * @param new_subitems node representing all media subitems
3149  * @param data opaque pointer set by vlc_player_AddListener()
3150  */
3151  void (*on_media_subitems_changed)(vlc_player_t *player,
3152  input_item_t *media, input_item_node_t *new_subitems, void *data);
3153 
3154  /**
3155  * Called when a vout is started or stopped
3156  *
3157  * @note In case, several media with only one video track are played
3158  * successively, the same vout instance will be started and stopped several
3159  * time.
3160  *
3161  * @param player locked player instance
3162  * @param action started or stopped
3163  * @param vout vout (can't be NULL)
3164  * @param order vout order
3165  * @param es_id the ES id associated with this vout
3166  * @param data opaque pointer set by vlc_player_AddListener()
3167  */
3168  void (*on_vout_changed)(vlc_player_t *player,
3170  enum vlc_vout_order order, vlc_es_id_t *es_id, void *data);
3171 
3172  /**
3173  * Called when the player is corked
3174  *
3175  * The player can be corked when the audio output loose focus or when a
3176  * renderer was paused from the outside.
3177  *
3178  * @note called only if pause on cork was not set to true (by
3179  * vlc_player_SetPauseOnCork())
3180  * @note a cork_count higher than 0 means the player is corked. In that
3181  * case, the user should pause the player and release all external resource
3182  * needed by the player. A value higher than 1 mean that the player was
3183  * corked more than one time (for different reasons). A value of 0 means
3184  * the player is no longer corked. In that case, the user could resume the
3185  * player.
3186  *
3187  * @param player locked player instance
3188  * @param cork_count 0 for uncorked, > 0 for corked
3189  * @param data opaque pointer set by vlc_player_AddListener()
3190  */
3191  void (*on_cork_changed)(vlc_player_t *player, unsigned cork_count,
3192  void *data);
3193 
3194  /**
3195  * Called to query the user about restoring the previous playback position
3196  *
3197  * If this callback isn't provided, the user won't be asked to restore
3198  * the previous playback position, effectively causing
3199  * VLC_PLAYER_RESTORE_PLAYBACK_POS_ASK to be handled as
3200  * VLC_PLAYER_RESTORE_PLAYBACK_POS_NEVER
3201  *
3202  * The implementation can react to this callback by calling
3203  * vlc_player_RestorePlaybackPos(), or by discarding the event.
3204  *
3205  * @param player locked player instance
3206  * @param data opaque pointer set by vlc_player_AddListener()
3207  */
3208  void (*on_playback_restore_queried)(vlc_player_t *player, void *data);
3209 };
3210 
3211 /**
3212  * Add a listener callback
3213  *
3214  * @note Every registered callbacks need to be removed by the caller with
3215  * vlc_player_RemoveListener().
3216  *
3217  * @param player locked player instance
3218  * @param cbs pointer to a vlc_player_cbs structure, the structure must be
3219  * valid during the lifetime of the player
3220  * @param cbs_data opaque pointer used by the callbacks
3221  * @return a valid listener id, or NULL in case of allocation error
3222  */
3225  const struct vlc_player_cbs *cbs, void *cbs_data);
3226 
3227 /**
3228  * Remove a listener callback
3229  *
3230  * @param player locked player instance
3231  * @param listener_id listener id returned by vlc_player_AddListener()
3232  */
3233 VLC_API void
3235  vlc_player_listener_id *listener_id);
3236 
3237 /** @} vlc_player__events */
3238 
3239 /**
3240  * @defgroup vlc_player__timer Player timer
3241  * @{
3242  */
3243 
3244 /**
3245  * Player timer opaque structure.
3246  */
3248 
3249 /**
3250  * Player timer point
3251  *
3252  * @see vlc_player_timer_cbs.on_update
3253  */
3256  /** Position in the range [0.0f;1.0] */
3257  float position;
3258  /** Rate of the player */
3259  double rate;
3260  /** Valid time >= VLC_TICK_0 or VLC_TICK_INVALID, subtract this time with
3261  * VLC_TICK_0 to get the original value. */
3262  vlc_tick_t ts;
3263  /** Valid length >= VLC_TICK_0 or VLC_TICK_INVALID */
3265  /** System date of this record (always valid), this date can be in the
3266  * future or in the past. The special value of INT64_MAX mean that the
3267  * clock was paused when this point was updated. In that case,
3268  * vlc_player_timer_point_Interpolate() will return the current ts/pos of
3269  * this point (there is nothing to interpolate). */
3271 };
3272 
3273 /**
3274  * Player smpte timecode
3275  *
3276  * @see vlc_player_timer_smpte_cbs
3277  */
3280  /** Hours [0;n] */
3281  unsigned hours;
3282  /** Minutes [0;59] */
3283  unsigned minutes;
3284  /** Seconds [0;59] */
3285  unsigned seconds;
3286  /** Frame number [0;n] */
3287  unsigned frames;
3288  /** Maximum number of digits needed to display the frame number */
3289  unsigned frame_resolution;
3290  /** True if the source is NTSC 29.97fps or 59.94fps DF */
3291  bool drop_frame;
3292 };
3293 
3294 /**
3295  * Player timer callbacks
3296  *
3297  * @see vlc_player_AddTimer
3298  */
3299 struct vlc_player_timer_cbs
3301  /**
3302  * Called when the state or the time changed.
3303  *
3304  * Get notified when the time is updated by the input or output source. The
3305  * input source is the 'demux' or the 'access_demux'. The output source are
3306  * audio and video outputs: an update is received each time a video frame
3307  * is displayed or an audio sample is written. The delay between each
3308  * updates may depend on the input and source type (it can be every 5ms,
3309  * 30ms, 1s or 10s...). The user of this timer may need to update the
3310  * position at a higher frequency from its own mainloop via
3311  * vlc_player_timer_point_Interpolate().
3312  *
3313  * @warning The player is not locked from this callback. It is forbidden
3314  * to call any player functions from here.
3315  *
3316  * @param value always valid, the time corresponding to the state
3317  * @param data opaque pointer set by vlc_player_AddTimer()
3318  */
3319  void (*on_update)(const struct vlc_player_timer_point *value, void *data);
3321  /**
3322  * The player is paused or a discontinuity occurred, likely caused by seek
3323  * from the user or because the playback is stopped. The player user should
3324  * stop its "interpolate" timer.
3325  *
3326  * @param system_date system date of this event, only valid when paused. It
3327  * can be used to interpolate the last updated point to this date in order
3328  * to get the last paused ts/position.
3329  * @param data opaque pointer set by vlc_player_AddTimer()
3330  */
3331  void (*on_discontinuity)(vlc_tick_t system_date, void *data);
3332 };
3333 
3334 /**
3335  * Player smpte timer callbacks
3336  *
3337  * @see vlc_player_AddSmpteTimer
3338  */
3341  /**
3342  * Called when a new frame is displayed
3343 
3344  * @warning The player is not locked from this callback. It is forbidden
3345  * to call any player functions from here.
3346  *
3347  * @param tc always valid, the timecode corresponding to the frame just
3348  * displayed
3349  * @param data opaque pointer set by vlc_player_AddTimer()
3350  */
3351  void (*on_update)(const struct vlc_player_timer_smpte_timecode *tc,
3352  void *data);
3353 };
3354 
3355 /**
3356  * Add a timer in order to get times updates
3357  *
3358  * @param player player instance (locked or not)
3359  * @param min_period corresponds to the minimum period between each updates,
3360  * use it to avoid flood from too many source updates, set it to
3361  * VLC_TICK_INVALID to receive all updates.
3362  * @param cbs pointer to a vlc_player_timer_cbs structure, the structure must
3363  * be valid during the lifetime of the player
3364  * @param cbs_data opaque pointer used by the callbacks
3365  * @return a valid vlc_player_timer_id or NULL in case of memory allocation
3366  * error
3367  */
3369 vlc_player_AddTimer(vlc_player_t *player, vlc_tick_t min_period,
3370  const struct vlc_player_timer_cbs *cbs,
3371  void *cbs_data);
3372 
3373 /**
3374  * Add a smpte timer in order to get accurate video frame updates
3375  *
3376  * @param player player instance (locked or not)
3377  * @param cbs pointer to a vlc_player_timer_smpte_cbs structure, the structure must
3378  * be valid during the lifetime of the player
3379  * @param cbs_data opaque pointer used by the callbacks
3380  * @return a valid vlc_player_timer_id or NULL in case of memory allocation
3381  * error
3382  */
3385  const struct vlc_player_timer_smpte_cbs *cbs,
3386  void *cbs_data);
3387 
3388 /**
3389  * Remove a player timer
3390  *
3391  * @param player player instance (locked or not)
3392  * @param timer timer created by vlc_player_AddTimer()
3393  */
3394 VLC_API void
3396 
3397 /**
3398  * Interpolate the last timer value to now
3399  *
3400  * @param point time update obtained via the vlc_player_timer_cbs.on_update()
3401  * callback
3402  * @param system_now current system date
3403  * @param out_ts pointer where to set the interpolated ts, subtract this time
3404  * with VLC_TICK_0 to get the original value.
3405  * @param out_pos pointer where to set the interpolated position
3406  * @return VLC_SUCCESS in case of success, an error in the interpolated ts is
3407  * negative (could happen during the buffering step)
3408  */
3409 VLC_API int
3411  vlc_tick_t system_now,
3412  vlc_tick_t *out_ts, float *out_pos);
3413 
3414 /**
3415  * Get the date of the next interval
3416  *
3417  * Can be used to setup an UI timer in order to update some widgets at specific
3418  * interval. A next_interval of VLC_TICK_FROM_SEC(1) can be used to update a
3419  * time widget when the media reaches a new second.
3420  *
3421  * @note The media time doesn't necessarily correspond to the system time, that
3422  * is why this function is needed and use the rate of the current point.
3423  *
3424  * @param point time update obtained via the vlc_player_timer_cbs.on_update()
3425  * @param system_now current system date
3426  * @param interpolated_ts ts returned by vlc_player_timer_point_Interpolate()
3427  * with the same system now
3428  * @param next_interval next interval
3429  * @return the absolute system date of the next interval
3430  */
3433  vlc_tick_t system_now,
3434  vlc_tick_t interpolated_ts,
3435  vlc_tick_t next_interval);
3436 
3437 /** @} vlc_player__timer */
3438 
3439 /** @} vlc_player */
3440 
3441 #endif
size_t count
Definition: core.c:392
#define VLC_API
Definition: fourcc_gen.c:31
vlc_vout_order
vout or spu_channel order
Definition: vlc_vout.h:71
static int vlc_player_aout_DecrementVolume(vlc_player_t *player, int steps, float *result)
Helper to decrement the audio volume.
Definition: vlc_player.h:2420
int vlc_player_aout_SetVolume(vlc_player_t *player, float volume)
Set the audio volume.
Definition: aout.c:135
int vlc_player_aout_Mute(vlc_player_t *player, bool mute)
Mute or unmute the audio output.
Definition: aout.c:171
int vlc_player_aout_IncrementVolume(vlc_player_t *player, int steps, float *result)
Increment the audio volume.
Definition: aout.c:147
float vlc_player_aout_GetVolume(vlc_player_t *player)
Get the audio volume.
Definition: aout.c:123
void vlc_player_aout_Reset(vlc_player_t *player)
Reset the main audio output.
Definition: aout.c:242
vlc_player_aout_listener_id * vlc_player_aout_AddListener(vlc_player_t *player, const struct vlc_player_aout_cbs *cbs, void *cbs_data)
Add a listener callback for audio output events.
Definition: aout.c:50
void vlc_player_aout_RemoveListener(vlc_player_t *player, vlc_player_aout_listener_id *listener_id)
Remove a aout listener callback.
Definition: aout.c:71
static int vlc_player_aout_ToggleMute(vlc_player_t *player)
Helper to toggle the mute state.
Definition: vlc_player.h:2459
int vlc_player_aout_EnableFilter(vlc_player_t *player, const char *name, bool add)
Enable or disable an audio filter.
Definition: aout.c:183
int vlc_player_aout_IsMuted(vlc_player_t *player)
Check if the audio output is muted.
Definition: aout.c:159
audio_output_t * vlc_player_aout_Hold(vlc_player_t *player)
Get the audio output.
Definition: aout.c:44
vlc_player_list_action
Action of vlc_player_cbs.on_track_list_changed, vlc_player_cbs.on_program_list_changed callbacks.
Definition: vlc_player.h:2721
vlc_player_listener_id * vlc_player_AddListener(vlc_player_t *player, const struct vlc_player_cbs *cbs, void *cbs_data)
Add a listener callback.
Definition: player.c:971
void vlc_player_RemoveListener(vlc_player_t *player, vlc_player_listener_id *listener_id)
Remove a listener callback.
Definition: player.c:990
@ VLC_PLAYER_LIST_ADDED
Definition: vlc_player.h:2722
@ VLC_PLAYER_LIST_UPDATED
Definition: vlc_player.h:2724
@ VLC_PLAYER_LIST_REMOVED
Definition: vlc_player.h:2723
void vlc_player_SetPauseOnCork(vlc_player_t *player, bool enabled)
Enable or disable pause on cork event.
Definition: player.c:1806
vlc_player_media_stopped_action
Action when the player is stopped.
Definition: vlc_player.h:96
void vlc_player_SetMediaStoppedAction(vlc_player_t *player, enum vlc_player_media_stopped_action action)
Setup an action when a media is stopped.
Definition: player.c:1204
void vlc_player_CondWait(vlc_player_t *player, vlc_cond_t *cond)
Wait on a condition variable.
Definition: player.c:964
void vlc_player_Delete(vlc_player_t *player)
Delete a player instance.
Definition: player.c:1874
vlc_player_t * vlc_player_New(vlc_object_t *parent, enum vlc_player_lock_type lock_type, const struct vlc_player_media_provider *media_provider, void *media_provider_data)
Create a new player instance.
Definition: player.c:1927
void vlc_player_Unlock(vlc_player_t *player)
Unlock the player.
Definition: player.c:958
void vlc_player_Lock(vlc_player_t *player)
Lock the player.
Definition: player.c:942
vlc_player_lock_type
Player lock type (normal or reentrant)
Definition: vlc_player.h:72
void vlc_player_SetStartPaused(vlc_player_t *player, bool start_paused)
Ask to start in a paused state.
Definition: player.c:1215
@ VLC_PLAYER_MEDIA_STOPPED_PAUSE
Pause when reaching the end of file.
Definition: vlc_player.h:100
@ VLC_PLAYER_MEDIA_STOPPED_CONTINUE
Continue (or stop if there is no next media), default behavior.
Definition: vlc_player.h:98
@ VLC_PLAYER_MEDIA_STOPPED_EXIT
Exit VLC.
Definition: vlc_player.h:104
@ VLC_PLAYER_MEDIA_STOPPED_STOP
Stop, even if there is a next media to play.
Definition: vlc_player.h:102
@ VLC_PLAYER_LOCK_REENTRANT
Reentrant lock.
Definition: vlc_player.h:88
@ VLC_PLAYER_LOCK_NORMAL
Normal lock.
Definition: vlc_player.h:79
void vlc_player_RemoveMetadataListener(vlc_player_t *player, vlc_player_metadata_listener_id *listener_id)
Remove a metadata listener.
Definition: metadata.c:201
vlc_player_metadata_listener_id * vlc_player_AddMetadataListener(vlc_player_t *player, enum vlc_player_metadata_option option, const union vlc_player_metadata_cbs *cbs, void *cbs_data)
Add a metadata listener.
Definition: metadata.c:158
vlc_player_metadata_option
Player metadata option.
Definition: vlc_player.h:2169
@ VLC_PLAYER_METADATA_LOUDNESS_MOMENTARY
Ask for momentary loudness measurement.
Definition: vlc_player.h:2176
@ VLC_PLAYER_METADATA_LOUDNESS_FULL
Ask for all loudness measurements.
Definition: vlc_player.h:2184
void vlc_player_InvalidateNextMedia(vlc_player_t *player)
Invalidate the next media.
Definition: player.c:1124
vlc_player_state
State of the player.
Definition: vlc_player.h:244
void vlc_player_NextVideoFrame(vlc_player_t *player)
Pause and display the next video frame.
Definition: player.c:1250
static bool vlc_player_CanPause(vlc_player_t *player)
Helper to get the pause capability.
Definition: vlc_player.h:582
void vlc_player_ChangeRate(vlc_player_t *player, float rate)
Change the rate of the player.
Definition: player.c:1293
int vlc_player_SetCurrentMedia(vlc_player_t *player, input_item_t *media)
Set the current media.
Definition: player.c:1001
vlc_player_abloop
A to B loop state.
Definition: vlc_player.h:351
void vlc_player_Resume(vlc_player_t *player)
Resume the playback from a pause.
Definition: player.c:1244
vlc_tick_t vlc_player_GetTime(vlc_player_t *player)
Get the time of the current media.
Definition: player.c:1357
enum vlc_player_abloop vlc_player_GetAtoBLoop(vlc_player_t *player, vlc_tick_t *a_time, float *a_pos, vlc_tick_t *b_time, float *b_pos)
Get the A to B loop status.
Definition: player.c:1532
static void vlc_player_JumpPos(vlc_player_t *player, float jumppos)
Helper to jump the position precisely.
Definition: vlc_player.h:741
vlc_player_restore_playback_pos
Definition: vlc_player.h:378
static void vlc_player_SetTime(vlc_player_t *player, vlc_tick_t time)
Helper to set the absolute time precisely.
Definition: vlc_player.h:753
void vlc_player_Navigate(vlc_player_t *player, enum vlc_player_nav nav)
Navigate (for DVD/Bluray menus or viewpoint)
Definition: player.c:1555
int vlc_player_SetAtoBLoop(vlc_player_t *player, enum vlc_player_abloop abloop)
Enable A to B loop of the current media.
Definition: player.c:1475
static bool vlc_player_CanSeek(vlc_player_t *player)
Helper to get the seek capability.
Definition: vlc_player.h:573
static void vlc_player_ToggleRecording(vlc_player_t *player)
Helper to toggle the recording state.
Definition: vlc_player.h:873
static void vlc_player_TogglePause(vlc_player_t *player)
Helper to toggle the pause state.
Definition: vlc_player.h:545
#define VLC_PLAYER_CAP_SEEK
Player capability: can seek.
Definition: vlc_player.h:358
void vlc_player_IncrementRate(vlc_player_t *player)
Increment the rate of the player (faster)
Definition: player.c:1338
int vlc_player_GetCapabilities(vlc_player_t *player)
Get the player capabilities.
Definition: player.c:1276
vlc_player_whence
Player seek/delay directive.
Definition: vlc_player.h:317
float vlc_player_GetRate(vlc_player_t *player)
Get the rate of the player.
Definition: player.c:1283
void vlc_player_RestorePlaybackPos(vlc_player_t *player)
Restore the previous playback position of the current media.
Definition: medialib.c:296
void vlc_player_Pause(vlc_player_t *player)
Pause the playback.
Definition: player.c:1238
static void vlc_player_SetPositionFast(vlc_player_t *player, float position)
Helper to set the absolute position fast.
Definition: vlc_player.h:731
vlc_object_t * vlc_player_GetV4l2Object(vlc_player_t *player) VLC_DEPRECATED
Get the V4L2 object used to do controls.
Definition: player.c:1851
vlc_player_seek_speed
Seek speed type.
Definition: vlc_player.h:302
float vlc_player_GetPosition(vlc_player_t *player)
Get the position of the current media.
Definition: player.c:1368
void vlc_player_UpdateViewpoint(vlc_player_t *player, const vlc_viewpoint_t *viewpoint, enum vlc_player_whence whence)
Update the viewpoint.
Definition: player.c:1593
static void vlc_player_SetTimeFast(vlc_player_t *player, vlc_tick_t time)
Helper to set the absolute time fast.
Definition: vlc_player.h:763
int vlc_player_Stop(vlc_player_t *player)
Stop the playback of the current media.
Definition: player.c:1186
bool vlc_player_IsRecording(vlc_player_t *player)
Check if the playing is recording.
Definition: player.c:1611
input_item_t * vlc_player_GetCurrentMedia(vlc_player_t *player)
Get the current played media.
Definition: player.c:1044
int vlc_player_Start(vlc_player_t *player)
Start the playback of the current media.
Definition: player.c:1137
static bool vlc_player_CanRewind(vlc_player_t *player)
Helper to get the rewindable capability.
Definition: vlc_player.h:600
static void vlc_player_SetPosition(vlc_player_t *player, float position)
Helper to set the absolute position precisely.
Definition: vlc_player.h:721
const struct input_stats_t * vlc_player_GetStatistics(vlc_player_t *player)
Get the statistics of the current media.
Definition: player.c:1798
#define VLC_PLAYER_CAP_REWIND
Player capability: can seek back.
Definition: vlc_player.h:364
static bool vlc_player_IsStarted(vlc_player_t *player)
Helper to get the started state.
Definition: vlc_player.h:519
void vlc_player_SeekByTime(vlc_player_t *player, vlc_tick_t time, enum vlc_player_seek_speed speed, enum vlc_player_whence whence)
Seek the current media by time.
Definition: player.c:1424
static input_item_t * vlc_player_HoldCurrentMedia(vlc_player_t *player)
Helper that hold the current media.
Definition: vlc_player.h:421
void vlc_player_SeekByPos(vlc_player_t *player, float position, enum vlc_player_seek_speed speed, enum vlc_player_whence whence)
Seek the current media by position.
Definition: player.c:1399
void vlc_player_DecrementRate(vlc_player_t *player)
Decrement the rate of the player (Slower)
Definition: player.c:1344
#define VLC_PLAYER_CAP_PAUSE
Player capability: can pause.
Definition: vlc_player.h:360
static bool vlc_player_IsPaused(vlc_player_t *player)
Helper to get the paused state.
Definition: vlc_player.h:536
void vlc_player_DisplayPosition(vlc_player_t *player)
Display the player position on the vout OSD.
Definition: player.c:1387
vlc_player_nav
Menu (VCD/DVD/BD) and viewpoint navigations.
Definition: vlc_player.h:330
enum vlc_player_state vlc_player_GetState(vlc_player_t *player)
Get the state of the player.
Definition: player.c:1262
vlc_player_error
Error of the player.
Definition: vlc_player.h:290
int vlc_player_GetSignal(vlc_player_t *player, float *quality, float *strength)
Get the signal quality and strength of the current media.
Definition: player.c:1783
static bool vlc_player_CanChangeRate(vlc_player_t *player)
Helper to get the change-rate capability.
Definition: vlc_player.h:591
vlc_tick_t vlc_player_GetLength(vlc_player_t *player)
Get the length of the current media.
Definition: player.c:1350
static void vlc_player_JumpTime(vlc_player_t *player, vlc_tick_t jumptime)
Helper to jump the time precisely.
Definition: vlc_player.h:773
int vlc_player_AddAssociatedMedia(vlc_player_t *player, enum es_format_category_e cat, const char *uri, bool select, bool notify, bool check_ext)
Add an associated (or external) media to the current media.
Definition: player.c:1052
enum vlc_player_error vlc_player_GetError(vlc_player_t *player)
Get the error state of the player.
Definition: player.c:1269
#define VLC_PLAYER_CAP_CHANGE_RATE
Player capability: can change the rate.
Definition: vlc_player.h:362
void vlc_player_SetRecordingEnabled(vlc_player_t *player, bool enabled)
Enable or disable recording for the current media.
Definition: player.c:1619
@ VLC_PLAYER_STATE_STOPPED
The player is stopped.
Definition: vlc_player.h:251
@ VLC_PLAYER_STATE_PAUSED
The player is paused.
Definition: vlc_player.h:273
@ VLC_PLAYER_STATE_STOPPING
The player is stopping.
Definition: vlc_player.h:281
@ VLC_PLAYER_STATE_STARTED
The player is started.
Definition: vlc_player.h:258
@ VLC_PLAYER_STATE_PLAYING
The player is playing.
Definition: vlc_player.h:266
@ VLC_PLAYER_ABLOOP_B
Definition: vlc_player.h:354
@ VLC_PLAYER_ABLOOP_A
Definition: vlc_player.h:353
@ VLC_PLAYER_ABLOOP_NONE
Definition: vlc_player.h:352
@ VLC_PLAYER_RESTORE_PLAYBACK_POS_NEVER
Definition: vlc_player.h:379
@ VLC_PLAYER_RESTORE_PLAYBACK_POS_ALWAYS
Definition: vlc_player.h:381
@ VLC_PLAYER_RESTORE_PLAYBACK_POS_ASK
Definition: vlc_player.h:380
@ VLC_PLAYER_WHENCE_RELATIVE
The current position +/- the given time/position.
Definition: vlc_player.h:321
@ VLC_PLAYER_WHENCE_ABSOLUTE
Given time/position.
Definition: vlc_player.h:319
@ VLC_PLAYER_SEEK_FAST
Do a fast seek.
Definition: vlc_player.h:306
@ VLC_PLAYER_SEEK_PRECISE
Do a precise seek.
Definition: vlc_player.h:304
@ VLC_PLAYER_NAV_RIGHT
Select a navigation item on the right or move the viewpoint right.
Definition: vlc_player.h:340
@ VLC_PLAYER_NAV_UP
Select a navigation item above or move the viewpoint up.
Definition: vlc_player.h:334
@ VLC_PLAYER_NAV_POPUP
Activate the popup Menu (for BD)
Definition: vlc_player.h:342
@ VLC_PLAYER_NAV_MENU
Activate disc Root Menu.
Definition: vlc_player.h:344
@ VLC_PLAYER_NAV_ACTIVATE
Activate the navigation item selected.
Definition: vlc_player.h:332
@ VLC_PLAYER_NAV_LEFT
Select a navigation item on the left or move the viewpoint left.
Definition: vlc_player.h:338
@ VLC_PLAYER_NAV_DOWN
Select a navigation item under or move the viewpoint down.
Definition: vlc_player.h:336
@ VLC_PLAYER_ERROR_GENERIC
Definition: vlc_player.h:292
@ VLC_PLAYER_ERROR_NONE
Definition: vlc_player.h:291
void vlc_player_SelectNextProgram(vlc_player_t *player)
Select the next program.
Definition: player.c:343
size_t vlc_player_GetProgramCount(vlc_player_t *player)
Get the number of programs.
Definition: player.c:260
const struct vlc_player_program * vlc_player_GetProgram(vlc_player_t *player, int group_id)
Get a program from an ES group identifier.
Definition: player.c:280
void vlc_player_SelectPrevProgram(vlc_player_t *player)
Select the previous program.
Definition: player.c:349
void vlc_player_SelectProgram(vlc_player_t *player, int group_id)
Select a program from an ES group identifier.
Definition: player.c:293
const struct vlc_player_program * vlc_player_GetProgramAt(vlc_player_t *player, size_t index)
Get the program at a specific index.
Definition: player.c:268
struct vlc_player_program * vlc_player_program_Dup(const struct vlc_player_program *prgm)
Duplicate a program.
Definition: track.c:69
static const struct vlc_player_program * vlc_player_GetSelectedProgram(vlc_player_t *player)
Helper to get the current selected program.
Definition: vlc_player.h:1281
void vlc_player_program_Delete(struct vlc_player_program *prgm)
Delete a duplicated program.
Definition: track.c:82
vlc_renderer_item_t * vlc_player_GetRenderer(vlc_player_t *player)
Get the renderer.
Definition: player.c:1468
void vlc_player_SetRenderer(vlc_player_t *player, vlc_renderer_item_t *renderer)
Set the renderer.
Definition: player.c:1448
void vlc_player_SetTeletextTransparency(vlc_player_t *player, bool enabled)
Enable or disable teletext transparency.
Definition: player.c:768
void vlc_player_SelectTeletextPage(vlc_player_t *player, unsigned page)
Select a teletext page or do an action from a key.
Definition: player.c:755
unsigned vlc_player_GetTeletextPage(vlc_player_t *player)
Get the current teletext page.
Definition: player.c:801
bool vlc_player_HasTeletextMenu(vlc_player_t *player)
Check if the media has a teletext menu.
Definition: player.c:782
void vlc_player_SetTeletextEnabled(vlc_player_t *player, bool enabled)
Enable or disable teletext.
Definition: player.c:742
bool vlc_player_IsTeletextEnabled(vlc_player_t *player)
Check if teletext is enabled.
Definition: player.c:789
bool vlc_player_IsTeletextTransparent(vlc_player_t *player)
Check if teletext is transparent.
Definition: player.c:808
int vlc_player_timer_point_Interpolate(const struct vlc_player_timer_point *point, vlc_tick_t system_now, vlc_tick_t *out_ts, float *out_pos)
Interpolate the last timer value to now.
Definition: timer.c:475
void vlc_player_RemoveTimer(vlc_player_t *player, vlc_player_timer_id *timer)
Remove a player timer.
Definition: timer.c:463
vlc_tick_t vlc_player_timer_point_GetNextIntervalDate(const struct vlc_player_timer_point *point, vlc_tick_t system_now, vlc_tick_t interpolated_ts, vlc_tick_t next_interval)
Get the date of the next interval.
Definition: timer.c:516
vlc_player_timer_id * vlc_player_AddTimer(vlc_player_t *player, vlc_tick_t min_period, const struct vlc_player_timer_cbs *cbs, void *cbs_data)
Add a timer in order to get times updates.
Definition: timer.c:419
vlc_player_timer_id * vlc_player_AddSmpteTimer(vlc_player_t *player, const struct vlc_player_timer_smpte_cbs *cbs, void *cbs_data)
Add a smpte timer in order to get accurate video frame updates.
Definition: timer.c:441
static const struct vlc_player_title * vlc_player_GetSelectedTitle(vlc_player_t *player)
Helper to get the current selected title.
Definition: vlc_player.h:1037
vlc_player_title_list * vlc_player_title_list_Hold(vlc_player_title_list *titles)
Hold the title list of the player.
Definition: title.c:31
void vlc_player_SelectPrevChapter(vlc_player_t *player)
Select the previous chapter for the current media.
Definition: player.c:930
ssize_t vlc_player_GetSelectedChapterIdx(vlc_player_t *player)
Get the selected chapter index for the current media.
Definition: player.c:896
void vlc_player_SelectNextChapter(vlc_player_t *player)
Select the next chapter for the current media.
Definition: player.c:918
void vlc_player_SelectNextTitle(vlc_player_t *player)
Select the next title for the current media.
Definition: player.c:872
void vlc_player_SelectChapterIdx(vlc_player_t *player, size_t index)
Select a chapter index for the current media.
Definition: player.c:906
void vlc_player_SelectTitle(vlc_player_t *player, const struct vlc_player_title *title)
Select a title for the current media.
Definition: player.c:853
void vlc_player_SelectTitleIdx(vlc_player_t *player, size_t index)
Select a title index for the current media.
Definition: player.c:844
void vlc_player_title_list_Release(vlc_player_title_list *titles)
Release of previously held title list.
Definition: title.c:38
vlc_player_title_list * vlc_player_GetTitleList(vlc_player_t *player)
Get the title list of the current media.
Definition: player.c:815
size_t vlc_player_title_list_GetCount(vlc_player_title_list *titles)
Get the number of title of a list.
Definition: title.c:171
void vlc_player_SelectChapter(vlc_player_t *player, const struct vlc_player_title *title, size_t chapter_idx)
Select a chapter for the current media.
Definition: player.c:862
static const struct vlc_player_chapter * vlc_player_GetSelectedChapter(vlc_player_t *player)
Helper to get the current selected chapter.
Definition: vlc_player.h:1124
void vlc_player_SelectPrevTitle(vlc_player_t *player)
Select the previous title for the current media.
Definition: player.c:884
const struct vlc_player_title * vlc_player_title_list_GetAt(vlc_player_title_list *titles, size_t idx)
Get the title at a given index.
Definition: title.c:164
ssize_t vlc_player_GetSelectedTitleIdx(vlc_player_t *player)
Get the selected title index for the current media.
Definition: player.c:822
static void vlc_player_SetSubtitleDelay(vlc_player_t *player, vlc_tick_t delay, enum vlc_player_whence whence)
Helper to set the subtitle delay.
Definition: vlc_player.h:1991
void vlc_player_SetAssociatedSubsFPS(vlc_player_t *player, float fps)
Set the associated subtitle FPS.
Definition: player.c:1105
int vlc_player_SetEsIdDelay(vlc_player_t *player, vlc_es_id_t *es_id, vlc_tick_t delay, enum vlc_player_whence whence)
Set the delay of one track.
Definition: player.c:1681
float vlc_player_GetAssociatedSubsFPS(vlc_player_t *player)
Get the associated subtitle FPS.
Definition: player.c:1117
static vlc_tick_t vlc_player_GetAudioDelay(vlc_player_t *player)
Helper to get the audio delay.
Definition: vlc_player.h:1962
static vlc_tick_t vlc_player_GetSubtitleDelay(vlc_player_t *player)
Helper to get the subtitle delay.
Definition: vlc_player.h:1982
static void vlc_player_SetAudioDelay(vlc_player_t *player, vlc_tick_t delay, enum vlc_player_whence whence)
Helper to set the audio delay.
Definition: vlc_player.h:1971
int vlc_player_SetCategoryDelay(vlc_player_t *player, enum es_format_category_e cat, vlc_tick_t delay, enum vlc_player_whence whence)
Set the delay of one category for the current media.
Definition: player.c:1634
vlc_tick_t vlc_player_GetCategoryDelay(vlc_player_t *player, enum es_format_category_e cat)
Get the delay of an ES category for the current media.
Definition: player.c:1668
vlc_tick_t vlc_player_GetEsIdDelay(vlc_player_t *player, vlc_es_id_t *es_id)
Get the delay of a track.
Definition: player.c:1721
void vlc_player_SelectPrevTrack(vlc_player_t *player, enum es_format_category_e cat)
Select the Previous track.
Definition: player.c:670
static const struct vlc_player_track * vlc_player_GetSubtitleTrackAt(vlc_player_t *player, size_t index)
Helper to get a subtitle track at a specific index.
Definition: vlc_player.h:1447
size_t vlc_player_GetTrackCount(vlc_player_t *player, enum es_format_category_e cat)
Get the number of tracks for an ES category.
Definition: player.c:355
vout_thread_t * vlc_player_GetEsIdVout(vlc_player_t *player, vlc_es_id_t *es_id, enum vlc_vout_order *order)
Get and the video output used by a ES identifier.
Definition: player.c:406
static bool vlc_player_IsAudioEnabled(vlc_player_t *player)
Helper to check if audio tracks are enabled.
Definition: vlc_player.h:1833
static void vlc_player_RestartTrackCategory(vlc_player_t *player, enum es_format_category_e cat)
Helper to restart all selected tracks from an ES category.
Definition: vlc_player.h:1714
void vlc_player_RestartEsId(vlc_player_t *player, vlc_es_id_t *es_id)
Restart a track from an ES identifier.
Definition: player.c:698
static const struct vlc_player_track * vlc_player_GetVideoTrackAt(vlc_player_t *player, size_t index)
Helper to get a video track at a specific index.
Definition: vlc_player.h:1411
void vlc_player_SelectTracksByStringIds(vlc_player_t *player, enum es_format_category_e cat, const char *str_ids)
Select tracks by their string identifier.
Definition: player.c:588
unsigned vlc_player_GetSubtitleTextScale(vlc_player_t *player)
Get the subtitle text scaling factor.
Definition: player.c:1777
static void vlc_player_UnselectTrackCategory(vlc_player_t *player, enum es_format_category_e cat)
Helper to unselect all tracks from an ES category.
Definition: vlc_player.h:1673
static void vlc_player_SetAudioEnabled(vlc_player_t *player, bool enabled)
Helper to enable or disable audio tracks.
Definition: vlc_player.h:1824
void vlc_player_track_Delete(struct vlc_player_track *track)
Delete a duplicated track.
Definition: track.c:149
char * vlc_player_GetCategoryLanguage(vlc_player_t *player, enum es_format_category_e cat)
Get the language of an ES category.
Definition: player.c:726
static void vlc_player_RestartTrack(vlc_player_t *player, const struct vlc_player_track *track)
Helper to restart a track.
Definition: vlc_player.h:1704
unsigned vlc_player_SelectEsIdList(vlc_player_t *player, enum es_format_category_e cat, vlc_es_id_t *const es_id_list[])
Select multiple tracks from a list of ES identifiers.
Definition: player.c:447
static size_t vlc_player_GetSubtitleTrackCount(vlc_player_t *player)
Helper to get the subtitle track count.
Definition: vlc_player.h:1438
void vlc_player_UnselectEsId(vlc_player_t *player, vlc_es_id_t *es_id)
Unselect a track from an ES identifier.
Definition: player.c:677
vlc_player_select_policy
Player selection policy.
Definition: vlc_player.h:1308
static size_t vlc_player_GetAudioTrackCount(vlc_player_t *player)
Helper to get the audio track count.
Definition: vlc_player.h:1420
static void vlc_player_SetSubtitleEnabled(vlc_player_t *player, bool enabled)
Helper to enable or disable subtitle tracks.
Definition: vlc_player.h:1842
vlc_es_id_t * vlc_player_GetEsIdFromVout(vlc_player_t *player, vout_thread_t *vout)
Get the ES identifier of a video output.
Definition: player.c:421
static void vlc_player_SetVideoEnabled(vlc_player_t *player, bool enabled)
Helper to enable or disable video tracks.
Definition: vlc_player.h:1806
void vlc_player_SelectCategoryLanguage(vlc_player_t *player, enum es_format_category_e cat, const char *lang)
Select the language for an ES category.
Definition: player.c:707
const struct vlc_player_track * vlc_player_GetTrackAt(vlc_player_t *player, enum es_format_category_e cat, size_t index)
Get the track at a specific index for an ES category.
Definition: player.c:368
static bool vlc_player_IsVideoEnabled(vlc_player_t *player)
Helper to check if video tracks are enabled.
Definition: vlc_player.h:1815
static size_t vlc_player_GetVideoTrackCount(vlc_player_t *player)
Helper to get the video track count.
Definition: vlc_player.h:1402
bool vlc_player_IsTrackCategoryEnabled(vlc_player_t *player, enum es_format_category_e cat)
Check if a track category is enabled.
Definition: player.c:1762
void vlc_player_SelectNextTrack(vlc_player_t *player, enum es_format_category_e cat)
Select the next track.
Definition: player.c:663
static const struct vlc_player_track * vlc_player_GetSelectedTrack(vlc_player_t *player, enum es_format_category_e cat)
Helper to get the selected track from an ES category.
Definition: vlc_player.h:1512
static void vlc_player_SelectSubtitleLanguage(vlc_player_t *player, const char *lang)
Helper to select the subtitle language.
Definition: vlc_player.h:1773
void vlc_player_SetTrackCategoryEnabled(vlc_player_t *player, enum es_format_category_e cat, bool enabled)
Enable or disable a track category.
Definition: player.c:1742
static void vlc_player_ToggleSubtitle(vlc_player_t *player)
Helper to toggle subtitles.
Definition: vlc_player.h:1860
static unsigned vlc_player_SelectTrack(vlc_player_t *player, const struct vlc_player_track *track, enum vlc_player_select_policy policy)
Helper to select a track.
Definition: vlc_player.h:1576
const struct vlc_player_track * vlc_player_GetTrack(vlc_player_t *player, vlc_es_id_t *es_id)
Get a track from an ES identifier.
Definition: player.c:398
static void vlc_player_SelectAudioLanguage(vlc_player_t *player, const char *lang)
Helper to select the audio language.
Definition: vlc_player.h:1764
void vlc_player_SetSubtitleTextScale(vlc_player_t *player, unsigned scale)
Set the subtitle text scaling factor.
Definition: player.c:1770
static const struct vlc_player_track * vlc_player_GetAudioTrackAt(vlc_player_t *player, size_t index)
Helper to get an audio track at a specific index.
Definition: vlc_player.h:1429
struct vlc_player_track * vlc_player_track_Dup(const struct vlc_player_track *track)
Duplicate a track.
Definition: track.c:157
unsigned vlc_player_SelectEsId(vlc_player_t *player, vlc_es_id_t *es_id, enum vlc_player_select_policy policy)
Select a track from an ES identifier.
Definition: player.c:561
static void vlc_player_UnselectTrack(vlc_player_t *player, const struct vlc_player_track *track)
Helper to unselect a track.
Definition: vlc_player.h:1663
static bool vlc_player_IsSubtitleEnabled(vlc_player_t *player)
Helper to check if subtitle tracks are enabled.
Definition: vlc_player.h:1851
@ VLC_PLAYER_SELECT_SIMULTANEOUS
Select multiple tracks for one category.
Definition: vlc_player.h:1321
@ VLC_PLAYER_SELECT_EXCLUSIVE
Only one track per category is selected.
Definition: vlc_player.h:1313
void vlc_player_vout_SetFullscreen(vlc_player_t *player, bool enabled)
Enable or disable the player fullscreen state.
Definition: vout.c:181
void vlc_player_vout_RemoveListener(vlc_player_t *player, vlc_player_vout_listener_id *listener_id)
Remove a vout listener callback.
Definition: vout.c:89
void vlc_player_vout_Snapshot(vlc_player_t *player)
Take a snapshot on all vouts.
Definition: vout.c:206
vlc_player_vout_action
action of vlc_player_cbs.on_vout_changed callback
Definition: vlc_player.h:2494
void vlc_player_osd_Message(vlc_player_t *player, const char *fmt,...)
Display an OSD message on all vouts.
Definition: osd.c:89
static void vlc_player_vout_ToggleFullscreen(vlc_player_t *player)
Helper to toggle the player fullscreen state.
Definition: vlc_player.h:2635
static void vlc_player_vout_ToggleWallpaperMode(vlc_player_t *player)
Helper to toggle the player wallpaper-mode state.
Definition: vlc_player.h:2678
vlc_player_vout_listener_id * vlc_player_vout_AddListener(vlc_player_t *player, const struct vlc_player_vout_cbs *cbs, void *cbs_data)
Add a listener callback for video output events.
Definition: vout.c:68
void vlc_player_vout_SetWallpaperModeEnabled(vlc_player_t *player, bool enabled)
Enable or disable the player wallpaper-mode.
Definition: vout.c:198
vout_thread_t ** vlc_player_vout_HoldAll(vlc_player_t *player, size_t *count)
Get and hold the list of video output.
Definition: vout.c:50
vout_thread_t * vlc_player_vout_Hold(vlc_player_t *player)
Get and hold the main video output.
Definition: vout.c:43
bool vlc_player_vout_IsWallpaperModeEnabled(vlc_player_t *player)
Check if the player has wallpaper-mode enaled.
Definition: vout.c:189
bool vlc_player_vout_IsFullscreen(vlc_player_t *player)
Check if the player is fullscreen.
Definition: vout.c:101
@ VLC_PLAYER_VOUT_STOPPED
Definition: vlc_player.h:2496
@ VLC_PLAYER_VOUT_STARTED
Definition: vlc_player.h:2495
const char name[16]
Definition: httpd.c:1267
input_item_t * input_item_Hold(input_item_t *p_item)
Holds an input item, i.e.
Definition: item.c:442
Audio output object.
Definition: vlc_aout.h:153
Definition: vlc_es.h:676
Definition: vlc_input_item.h:205
Describes an input and is used to spawn input_thread_t objects.
Definition: vlc_input_item.h:89
Definition: vlc_input_item.h:521
Audio loudness measurement.
Definition: vlc_aout.h:611
Condition variable.
Definition: vlc_threads.h:320
Opaque structure representing an ES (Elementary Stream) track.
Definition: es_out.c:96
VLC object common members.
Definition: vlc_objects.h:45
Player aout callbacks.
Definition: vlc_player.h:2285
void(* on_volume_changed)(audio_output_t *aout, float new_volume, void *data)
Called when the volume has changed.
Definition: vlc_player.h:2295
void(* on_mute_changed)(audio_output_t *aout, bool new_muted, void *data)
Called when the mute state has changed.
Definition: vlc_player.h:2307
void(* on_device_changed)(audio_output_t *aout, const char *device, void *data)
Called when the audio device has changed.
Definition: vlc_player.h:2317
Definition: player.h:159
Player callbacks.
Definition: vlc_player.h:2742
void(* on_program_list_changed)(vlc_player_t *player, enum vlc_player_list_action action, const struct vlc_player_program *prgm, void *data)
Called when a new program is added, removed or updated.
Definition: vlc_player.h:2906
void(* on_position_changed)(vlc_player_t *player, vlc_tick_t new_time, float new_pos, void *data)
Called when the player position has changed.
Definition: vlc_player.h:2836
void(* on_length_changed)(vlc_player_t *player, vlc_tick_t new_length, void *data)
Called when the media length has changed.
Definition: vlc_player.h:2850
void(* on_recording_changed)(vlc_player_t *player, bool recording, void *data)
Called when the player recording state has changed.
Definition: vlc_player.h:3069
void(* on_media_subitems_changed)(vlc_player_t *player, input_item_t *media, input_item_node_t *new_subitems, void *data)
Called when the media has new subitems.
Definition: vlc_player.h:3152
void(* on_category_delay_changed)(vlc_player_t *player, enum es_format_category_e cat, vlc_tick_t new_delay, void *data)
Called when the player category delay has changed for the current media.
Definition: vlc_player.h:3033
void(* on_teletext_page_changed)(vlc_player_t *player, unsigned new_page, void *data)
Called when the teletext page has changed.
Definition: vlc_player.h:3008
void(* on_capabilities_changed)(vlc_player_t *player, int old_caps, int new_caps, void *data)
Called when the media capabilities has changed.
Definition: vlc_player.h:2823
void(* on_signal_changed)(vlc_player_t *player, float quality, float strength, void *data)
Called when the media signal has changed.
Definition: vlc_player.h:3080
void(* on_title_selection_changed)(vlc_player_t *player, const struct vlc_player_title *new_title, size_t new_idx, void *data)
Called when a new title is selected.
Definition: vlc_player.h:2954
void(* on_atobloop_changed)(vlc_player_t *player, enum vlc_player_abloop new_state, vlc_tick_t time, float pos, void *data)
Called when the A to B loop has changed.
Definition: vlc_player.h:3108
void(* on_current_media_changed)(vlc_player_t *player, input_item_t *new_media, void *data)
Called when the current media has changed.
Definition: vlc_player.h:2758
void(* on_teletext_menu_changed)(vlc_player_t *player, bool has_teletext_menu, void *data)
Called when the media has a teletext menu.
Definition: vlc_player.h:2984
void(* on_statistics_changed)(vlc_player_t *player, const struct input_stats_t *stats, void *data)
Called when the player has new statisics.
Definition: vlc_player.h:3093
void(* on_media_meta_changed)(vlc_player_t *player, input_item_t *media, void *data)
Called when the media meta has changed.
Definition: vlc_player.h:3131
void(* on_track_selection_changed)(vlc_player_t *player, vlc_es_id_t *unselected_id, vlc_es_id_t *selected_id, void *data)
Called when a new track is selected and/or unselected.
Definition: vlc_player.h:2880
void(* on_associated_subs_fps_changed)(vlc_player_t *player, float subs_fps, void *data)
Called when associated subtitle has changed.
Definition: vlc_player.h:3045
void(* on_media_epg_changed)(vlc_player_t *player, input_item_t *media, void *data)
Called when media epg has changed.
Definition: vlc_player.h:3141
void(* on_vout_changed)(vlc_player_t *player, enum vlc_player_vout_action action, vout_thread_t *vout, enum vlc_vout_order order, vlc_es_id_t *es_id, void *data)
Called when a vout is started or stopped.
Definition: vlc_player.h:3169
void(* on_program_selection_changed)(vlc_player_t *player, int unselected_id, int selected_id, void *data)
Called when a new program is selected and/or unselected.
Definition: vlc_player.h:2921
void(* on_titles_changed)(vlc_player_t *player, vlc_player_title_list *titles, void *data)
Called when the media titles has changed.
Definition: vlc_player.h:2938
void(* on_cork_changed)(vlc_player_t *player, unsigned cork_count, void *data)
Called when the player is corked.
Definition: vlc_player.h:3192
void(* on_track_list_changed)(vlc_player_t *player, enum vlc_player_list_action action, const struct vlc_player_track *track, void *data)
Called when a track is added, removed, or updated.
Definition: vlc_player.h:2865
void(* on_teletext_enabled_changed)(vlc_player_t *player, bool enabled, void *data)
Called when teletext is enabled or disabled.
Definition: vlc_player.h:2996
void(* on_playback_restore_queried)(vlc_player_t *player, void *data)
Called to query the user about restoring the previous playback position.
Definition: vlc_player.h:3209
void(* on_track_delay_changed)(vlc_player_t *player, vlc_es_id_t *es_id, vlc_tick_t delay, void *data)
Called when a track delay has changed.
Definition: vlc_player.h:2891
void(* on_chapter_selection_changed)(vlc_player_t *player, const struct vlc_player_title *title, size_t title_idx, const struct vlc_player_chapter *new_chapter, size_t new_chapter_idx, void *data)
Called when a new chapter is selected.
Definition: vlc_player.h:2972
void(* on_media_stopped_action_changed)(vlc_player_t *player, enum vlc_player_media_stopped_action new_action, void *data)
Called when media stopped action has changed.
Definition: vlc_player.h:3121
void(* on_state_changed)(vlc_player_t *player, enum vlc_player_state new_state, void *data)
Called when the player state has changed.
Definition: vlc_player.h:2770
void(* on_buffering_changed)(vlc_player_t *player, float new_buffering, void *data)
Called when the player buffering (or cache) has changed.
Definition: vlc_player.h:2797
void(* on_error_changed)(vlc_player_t *player, enum vlc_player_error error, void *data)
Called when a media triggered an error.
Definition: vlc_player.h:2784
void(* on_renderer_changed)(vlc_player_t *player, vlc_renderer_item_t *new_item, void *data)
Called when a new renderer item is set.
Definition: vlc_player.h:3057
void(* on_teletext_transparency_changed)(vlc_player_t *player, bool enabled, void *data)
Called when the teletext transparency has changed.
Definition: vlc_player.h:3020
void(* on_rate_changed)(vlc_player_t *player, float new_rate, void *data)
Called when the player rate has changed.
Definition: vlc_player.h:2810
Player chapter structure.
Definition: vlc_player.h:942
const char * name
Chapter name, always valid.
Definition: vlc_player.h:944
vlc_tick_t time
Position of this chapter.
Definition: vlc_player.h:946
Definition: player.h:132
Callbacks for the owner of the player.
Definition: vlc_player.h:118
Definition: player.h:139
Player program structure.
Definition: vlc_player.h:1174
bool selected
True if the program is selected.
Definition: vlc_player.h:1180
const char * name
Program name, always valid.
Definition: vlc_player.h:1178
int group_id
Id used for vlc_player_SelectProgram()
Definition: vlc_player.h:1176
bool scrambled
True if the program is scrambled.
Definition: vlc_player.h:1182
Definition: player.h:231
Player timer callbacks.
Definition: vlc_player.h:3301
void(* on_discontinuity)(vlc_tick_t system_date, void *data)
The player is paused or a discontinuity occurred, likely caused by seek from the user or because the ...
Definition: vlc_player.h:3332
void(* on_update)(const struct vlc_player_timer_point *value, void *data)
Called when the state or the time changed.
Definition: vlc_player.h:3320
Definition: player.h:173
Player timer point.
Definition: vlc_player.h:3256
vlc_tick_t system_date
System date of this record (always valid), this date can be in the future or in the past.
Definition: vlc_player.h:3271
float position
Position in the range [0.0f;1.0].
Definition: vlc_player.h:3258
double rate
Rate of the player.
Definition: vlc_player.h:3260
vlc_tick_t length
Valid length >= VLC_TICK_0 or VLC_TICK_INVALID.
Definition: vlc_player.h:3265
vlc_tick_t ts
Valid time >= VLC_TICK_0 or VLC_TICK_INVALID, subtract this time with VLC_TICK_0 to get the original ...
Definition: vlc_player.h:3263
Player smpte timer callbacks.
Definition: vlc_player.h:3341
void(* on_update)(const struct vlc_player_timer_smpte_timecode *tc, void *data)
Called when a new frame is displayed.
Definition: vlc_player.h:3352
Player smpte timecode.
Definition: vlc_player.h:3280
unsigned seconds
Seconds [0;59].
Definition: vlc_player.h:3286
unsigned minutes
Minutes [0;59].
Definition: vlc_player.h:3284
unsigned hours
Hours [0;n].
Definition: vlc_player.h:3282
bool drop_frame
True if the source is NTSC 29.97fps or 59.94fps DF.
Definition: vlc_player.h:3292
unsigned frame_resolution
Maximum number of digits needed to display the frame number.
Definition: vlc_player.h:3290
unsigned frames
Frame number [0;n].
Definition: vlc_player.h:3288
Definition: player.h:50
Player title structure.
Definition: vlc_player.h:956
const struct vlc_player_chapter * chapters
Array of chapters, can be NULL.
Definition: vlc_player.h:967
size_t chapter_count
Number of chapters, can be 0.
Definition: vlc_player.h:965
vlc_tick_t length
Length of the title.
Definition: vlc_player.h:960
unsigned flags
Bit flag of VLC_PLAYER_TITLE_MENU and VLC_PLAYER_TITLE_INTERACTIVE.
Definition: vlc_player.h:963
const char * name
Title name, always valid.
Definition: vlc_player.h:958
Player track structure.
Definition: vlc_player.h:1334
bool selected
True if the track is selected.
Definition: vlc_player.h:1342
es_format_t fmt
Es format.
Definition: vlc_player.h:1340
const char * name
Track name, always valid.
Definition: vlc_player.h:1338
vlc_es_id_t * es_id
Id used for any player actions, like vlc_player_SelectEsId()
Definition: vlc_player.h:1336
Player vout callbacks.
Definition: vlc_player.h:2512
void(* on_wallpaper_mode_changed)(vout_thread_t *vout, bool enabled, void *data)
Called when the player and/or vout wallpaper mode has changed.
Definition: vlc_player.h:2534
void(* on_fullscreen_changed)(vout_thread_t *vout, bool enabled, void *data)
Called when the player and/or vout fullscreen state has changed.
Definition: vlc_player.h:2522
Definition: player.h:152
Definition: renderer_discovery.c:35
Viewpoints.
Definition: vlc_viewpoint.h:41
Video output thread descriptor.
Definition: vlc_vout.h:55
Player metadata callbacks.
Definition: vlc_player.h:2196
void(* on_loudness_changed)(vlc_tick_t date, const struct vlc_audio_loudness *loudness, void *data)
Called when loudness measurements have changed.
Definition: vlc_player.h:2227
void(* on_momentary_loudness_changed)(vlc_tick_t date, double momentary_loudness, void *data)
Called when the momentary loudness measurement have changed.
Definition: vlc_player.h:2210
Audio output modules interface.
es_format_category_e
ES Categories.
Definition: vlc_es.h:659
@ SPU_ES
Definition: vlc_es.h:663
@ AUDIO_ES
Definition: vlc_es.h:662
@ VIDEO_ES
Definition: vlc_es.h:661
Input thread interface.
int64_t vlc_tick_t
High precision date or time interval.
Definition: vlc_tick.h:35