1 /*****************************************************************************
2 * vlc_playlist.h : Playlist functions
3 *****************************************************************************
4 * Copyright (C) 1999-2004 VLC authors and VideoLAN
7 * Authors: Samuel Hocevar <sam@zoy.org>
9 * This program is free software; you can redistribute it and/or modify it
10 * under the terms of the GNU Lesser General Public License as published by
11 * the Free Software Foundation; either version 2.1 of the License, or
12 * (at your option) any later version.
14 * This program is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 * GNU Lesser General Public License for more details.
19 * You should have received a copy of the GNU Lesser General Public License
20 * along with this program; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
22 *****************************************************************************/
24 #ifndef VLC_PLAYLIST_H_
25 #define VLC_PLAYLIST_H_
31 #include <vlc_events.h>
33 TYPEDEF_ARRAY(playlist_item_t
*, playlist_item_array_t
)
38 * \defgroup playlist VLC playlist
39 * VLC playlist controls
42 * VLC playlist control interface
44 * The VLC playlist system has a tree structure. This allows advanced
45 * categorization, like for SAP streams (which are grouped by "sap groups").
47 * The base structure for all playlist operations is the playlist_item_t.
48 * This is essentially a node within the playlist tree. Each playlist item
49 * references an input_item_t which contains the input stream info, such as
50 * location, name and meta-data.
52 * A playlist item is uniquely identified by its input item:
53 * \ref playlist_ItemGetByInput(). A single input item cannot be used by more
54 * than one playlist item at a time; if necessary, a copy of the input item can
57 * The same playlist tree is visible to all user interfaces. To arbitrate
58 * access, a lock is used, see \ref playlist_Lock() and \ref playlist_Unlock().
60 * Under the playlist root item node, the top-level items are the main
61 * media sources and include:
62 * - the actual playlist,
63 * - the media library,
64 * - the service discovery root node, whose children are services discovery
67 * So, here is an example:
70 * - input 1 -> name = foo 1 uri = ...
71 * - input 2 -> name = foo 2 uri = ...
76 * - foo 2 (id 6 - input 2)
77 * - media library (id 2)
78 * - foo 1 (id 5 - input 1)
81 * Sometimes, an item creates subitems. This happens for the directory access
82 * for example. In that case, if the item is under the "playlist" top-level
83 * item and playlist is configured to be flat then the item will be deleted and
84 * replaced with new subitems. If the item is under another top-level item, it
85 * will be transformed to a node and removed from the list of all items without
88 * For "standard" item addition, you can use playlist_Add(), playlist_AddExt()
89 * (more options) or playlist_AddInput() if you already created your input
90 * item. This will add the item at the root of "Playlist" or of "Media library"
91 * in each of the two trees.
93 * You can create nodes with playlist_NodeCreate() and can create items from
94 * existing input items to be placed under any node with
95 * playlist_NodeAddInput().
97 * To delete an item, use playlist_NodeDelete( p_item ).
99 * The playlist defines the following event variables:
101 * - "item-change": It will contain a pointer to the input_item_t of a
102 * changed input item monitored by the playlist.
104 * - "playlist-item-append": It will contain a pointer to a playlist_item_t.
105 * - "playlist-item-deleted": It will contain a pointer to the playlist_item_t
106 * about to be deleted.
108 * - "leaf-to-parent": It will contain the playlist_item_t->i_id of an item that is transformed
111 * The playlist contains rate-variable which is propagated to current input if
112 * available also rate-slower/rate-faster is in use.
115 /** Helper structure to export to file part of the playlist */
116 typedef struct playlist_export_t
121 playlist_item_t
*p_root
;
124 /** playlist item / node */
125 struct playlist_item_t
127 input_item_t
*p_input
; /**< Linked input item */
129 playlist_item_t
**pp_children
; /**< Children nodes/items */
130 playlist_item_t
*p_parent
; /**< Item parent */
131 int i_children
; /**< Number of children, -1 if not a node */
132 unsigned i_nb_played
; /**< Times played */
134 int i_id
; /**< Playlist item specific id */
135 uint8_t i_flags
; /**< Flags \see playlist_item_flags_e */
139 PLAYLIST_DBL_FLAG
= 0x04, /**< Is it disabled ? */
140 PLAYLIST_RO_FLAG
= 0x08, /**< Write-enabled ? */
141 PLAYLIST_SUBITEM_STOP_FLAG
= 0x40, /**< Must playlist stop if the item gets subitems ?*/
142 PLAYLIST_NO_INHERIT_FLAG
= 0x80, /**< Will children inherit flags the R/O flag ? */
143 } playlist_item_flags_e
;
145 /** Playlist status */
147 { PLAYLIST_STOPPED
,PLAYLIST_RUNNING
,PLAYLIST_PAUSED
} playlist_status_t
;
149 /** Structure containing information about the playlist */
154 playlist_item_array_t items
; /**< Arrays of items */
156 playlist_item_array_t current
; /**< Items currently being played */
157 int i_current_index
; /**< Index in current array */
159 /* Predefined items */
160 playlist_item_t root
;
161 playlist_item_t
*p_playing
;
162 playlist_item_t
*p_media_library
;
165 /* A bit of macro magic to generate an enum out of the following list,
166 * and later, to generate a list of static functions out of the same list.
167 * There is also SORT_RANDOM, which is always last and handled specially.
169 #define VLC_DEFINE_SORT_FUNCTIONS \
172 DEF( SORT_TITLE_NODES_FIRST )\
175 DEF( SORT_DURATION )\
176 DEF( SORT_TITLE_NUMERIC )\
178 DEF( SORT_TRACK_NUMBER )\
179 DEF( SORT_DESCRIPTION )\
182 DEF( SORT_DISC_NUMBER )\
188 VLC_DEFINE_SORT_FUNCTIONS
190 NUM_SORT_FNS
=SORT_RANDOM
193 #ifndef VLC_INTERNAL_PLAYLIST_SORT_FUNCTIONS
194 #undef VLC_DEFINE_SORT_FUNCTIONS
203 #define PLAYLIST_END -1
211 /*****************************************************************************
213 *****************************************************************************/
216 #define PL_LOCK playlist_Lock( p_playlist )
217 #define PL_UNLOCK playlist_Unlock( p_playlist )
218 #define PL_ASSERT_LOCKED playlist_AssertLocked( p_playlist )
220 /** Playlist commands */
222 PLAYLIST_PLAY
, /**< No arg. res=can fail*/
223 PLAYLIST_VIEWPLAY
, /**< arg1= playlist_item_t*,*/
224 /** arg2 = playlist_item_t* , res=can fail */
225 PLAYLIST_TOGGLE_PAUSE
, /**< No arg res=can fail */
226 PLAYLIST_STOP
, /**< No arg res=can fail*/
227 PLAYLIST_SKIP
, /**< arg1=int, res=can fail*/
228 PLAYLIST_PAUSE
, /**< No arg */
229 PLAYLIST_RESUME
, /**< No arg */
232 #define playlist_Play(p) playlist_Control(p,PLAYLIST_PLAY, pl_Unlocked )
233 #define playlist_TogglePause(p) \
234 playlist_Control(p, PLAYLIST_TOGGLE_PAUSE, pl_Unlocked)
235 #define playlist_Stop(p) playlist_Control(p,PLAYLIST_STOP, pl_Unlocked )
236 #define playlist_Next(p) playlist_Control(p,PLAYLIST_SKIP, pl_Unlocked, 1)
237 #define playlist_Prev(p) playlist_Control(p,PLAYLIST_SKIP, pl_Unlocked, -1)
238 #define playlist_Skip(p,i) playlist_Control(p,PLAYLIST_SKIP, pl_Unlocked, (i) )
239 #define playlist_Pause(p) \
240 playlist_Control(p, PLAYLIST_PAUSE, pl_Unlocked)
241 #define playlist_Resume(p) \
242 playlist_Control(p, PLAYLIST_RESUME, pl_Unlocked)
245 * Locks the playlist.
247 * This function locks the playlist. While the playlist is locked, no other
248 * thread can modify the playlist tree layout or current playing item and node.
250 * Locking the playlist is necessary before accessing, either for reading or
251 * writing, any playlist item.
253 * \note Because of the potential for lock inversion / deadlocks, locking the
254 * playlist shall not be attemped while holding an input item lock. An input
255 * item lock can be acquired while holding the playlist lock.
257 * While holding the playlist lock, a thread shall not attempt to:
258 * - probe, initialize or deinitialize a module or a plugin,
259 * - install or deinstall a variable or event callback,
260 * - set a variable or trigger a variable callback, with the sole exception
261 * of the playlist core triggering add/remove/leaf item callbacks,
262 * - invoke a module/plugin callback other than:
264 * - logger message callback.
266 VLC_API
void playlist_Lock( playlist_t
* );
269 * Unlocks the playlist.
271 * This function unlocks the playlist, allowing other threads to lock it. The
272 * calling thread must have called playlist_Lock() before.
274 * This function invalidates all or any playlist item pointers.
275 * There are no ways to ensure that playlist items are not modified or deleted
276 * by another thread past this function call.
278 * To retain a reference to a playlist item while not holding the playlist
279 * lock, a thread should take a reference to the input item within the
280 * playlist item before unlocking. If this is not practical, then the thread
281 * can store the playlist item ID (i_id) before unlocking.
282 * Either way, this will not ensure that the playlist item is not deleted, so
283 * the thread must be ready to handle that case later when calling
284 * playlist_ItemGetByInput() or playlist_ItemGetById().
286 * Furthermore, if ID is used, then the playlist item might be deleted, and
287 * another item could be assigned the same ID. To avoid that problem, use
288 * the input item instead of the ID.
290 VLC_API
void playlist_Unlock( playlist_t
* );
292 VLC_API
void playlist_AssertLocked( playlist_t
* );
293 VLC_API
void playlist_Deactivate( playlist_t
* );
296 * Do a playlist action.
297 * If there is something in the playlist then you can do playlist actions.
298 * Possible queries are listed in vlc_common.h
299 * \param p_playlist the playlist to do the command on
300 * \param i_query the command to do
301 * \param b_locked TRUE if playlist is locked when entering this function
302 * \param variable number of arguments
304 VLC_API
void playlist_Control( playlist_t
*p_playlist
, int i_query
, bool b_locked
, ... );
306 static inline void playlist_ViewPlay(playlist_t
*pl
, playlist_item_t
*node
,
307 playlist_item_t
*item
)
309 playlist_Control(pl
, PLAYLIST_VIEWPLAY
, pl_Locked
, node
, item
);
312 /** Get current playing input. The object is retained.
314 VLC_API input_thread_t
* playlist_CurrentInput( playlist_t
*p_playlist
) VLC_USED
;
315 VLC_API input_thread_t
*playlist_CurrentInputLocked( playlist_t
*p_playlist
) VLC_USED
;
317 /** Get the duration of all items in a node.
319 VLC_API mtime_t
playlist_GetNodeDuration( playlist_item_t
* );
321 /** Clear the playlist
322 * \param b_locked TRUE if playlist is locked when entering this function
324 VLC_API
void playlist_Clear( playlist_t
*, bool );
326 /* Playlist sorting */
327 VLC_API
int playlist_TreeMove( playlist_t
*, playlist_item_t
*, playlist_item_t
*, int );
328 VLC_API
int playlist_TreeMoveMany( playlist_t
*, int, playlist_item_t
**, playlist_item_t
*, int );
329 VLC_API
int playlist_RecursiveNodeSort( playlist_t
*, playlist_item_t
*,int, int );
331 VLC_API playlist_item_t
* playlist_CurrentPlayingItem( playlist_t
* ) VLC_USED
;
332 VLC_API
int playlist_Status( playlist_t
* );
335 * Export a node of the playlist to a certain type of playlistfile
336 * \param b_playlist true for the playlist, false for the media library
337 * \param psz_filename the location where the exported file will be saved
338 * \param psz_type the type of playlist file to create (m3u, pls, ..)
339 * \return VLC_SUCCESS on success
341 VLC_API
int playlist_Export( playlist_t
*p_playlist
, const char *psz_name
,
342 bool b_playlist
, const char *psz_type
);
345 * Open a playlist file, add its content to the current playlist
347 VLC_API
int playlist_Import( playlist_t
*p_playlist
, const char *psz_file
);
349 /********************** Services discovery ***********************/
351 /** Add a service discovery module */
352 VLC_API
int playlist_ServicesDiscoveryAdd(playlist_t
*, const char *);
353 /** Remove a services discovery module by name */
354 VLC_API
int playlist_ServicesDiscoveryRemove(playlist_t
*, const char *);
355 /** Check whether a given SD is loaded */
356 VLC_API
bool playlist_IsServicesDiscoveryLoaded( playlist_t
*,const char *) VLC_DEPRECATED
;
357 /** Query a services discovery */
358 VLC_API
int playlist_ServicesDiscoveryControl( playlist_t
*, const char *, int, ... );
362 /********************************************************
364 ********************************************************/
366 /******************** Item addition ********************/
367 VLC_API
int playlist_Add( playlist_t
*, const char *, bool );
368 VLC_API
int playlist_AddExt( playlist_t
*, const char *, const char *, bool, int, const char *const *, unsigned, bool );
369 VLC_API
int playlist_AddInput( playlist_t
*, input_item_t
*, bool, bool );
370 VLC_API playlist_item_t
* playlist_NodeAddInput( playlist_t
*, input_item_t
*, playlist_item_t
*, int );
371 VLC_API
int playlist_NodeAddCopy( playlist_t
*, playlist_item_t
*, playlist_item_t
*, int );
373 /********************************** Item search *************************/
374 VLC_API playlist_item_t
* playlist_ItemGetById(playlist_t
*, int ) VLC_USED
;
375 VLC_API playlist_item_t
*playlist_ItemGetByInput(playlist_t
*,
376 const input_item_t
* )
379 VLC_API
int playlist_LiveSearchUpdate(playlist_t
*, playlist_item_t
*, const char *, bool );
381 /********************************************************
383 ********************************************************/
384 /* Node management */
385 VLC_API playlist_item_t
* playlist_NodeCreate( playlist_t
*, const char *, playlist_item_t
* p_parent
, int i_pos
, int i_flags
);
386 VLC_API playlist_item_t
* playlist_ChildSearchName(playlist_item_t
*, const char* ) VLC_USED
;
387 VLC_API
void playlist_NodeDelete( playlist_t
*, playlist_item_t
* );
389 /**************************
390 * Audio output management
391 **************************/
393 VLC_API audio_output_t
*playlist_GetAout( playlist_t
* );
395 #define AOUT_VOLUME_DEFAULT 256
396 #define AOUT_VOLUME_MAX 512
398 VLC_API
float playlist_VolumeGet( playlist_t
* );
399 VLC_API
int playlist_VolumeSet( playlist_t
*, float );
400 VLC_API
int playlist_VolumeUp( playlist_t
*, int, float * );
401 #define playlist_VolumeDown(a, b, c) playlist_VolumeUp(a, -(b), c)
402 VLC_API
int playlist_MuteSet( playlist_t
*, bool );
403 VLC_API
int playlist_MuteGet( playlist_t
* );
405 static inline int playlist_MuteToggle( playlist_t
*pl
)
407 int val
= playlist_MuteGet( pl
);
409 val
= playlist_MuteSet( pl
, !val
);
413 VLC_API
void playlist_EnableAudioFilter( playlist_t
*, const char *, bool );
415 /***********************************************************************
417 ***********************************************************************/
418 /** Tell if the playlist is empty */
419 static inline bool playlist_IsEmpty( playlist_t
*p_playlist
)
422 return p_playlist
->items
.i_size
== 0;
425 /** Tell the number of items in the current playing context */
426 static inline int playlist_CurrentSize( playlist_t
*p_playlist
)
429 return p_playlist
->current
.i_size
;