A VLC playlist contains a list of "playlist items". More...

Collaboration diagram for VLC playlist:

Modules
	Playlist randomizer helper
	Playlist helper to manage random playback.

Data Structures
struct	vlc_playlist_sort_criterion

struct	vlc_playlist_callbacks
	Playlist callbacks. More...

Typedefs
typedef struct input_item_t	input_item_t

typedef struct vlc_player_t	vlc_player_t

typedef struct vlc_playlist	vlc_playlist_t

typedef struct vlc_playlist_item	vlc_playlist_item_t

typedef struct vlc_playlist_listener_id	vlc_playlist_listener_id

Enumerations
enum	vlc_playlist_playback_repeat { VLC_PLAYLIST_PLAYBACK_REPEAT_NONE , VLC_PLAYLIST_PLAYBACK_REPEAT_CURRENT , VLC_PLAYLIST_PLAYBACK_REPEAT_ALL }

enum	vlc_playlist_playback_order { VLC_PLAYLIST_PLAYBACK_ORDER_NORMAL , VLC_PLAYLIST_PLAYBACK_ORDER_RANDOM }

enum	vlc_playlist_sort_key { VLC_PLAYLIST_SORT_KEY_TITLE , VLC_PLAYLIST_SORT_KEY_DURATION , VLC_PLAYLIST_SORT_KEY_ARTIST , VLC_PLAYLIST_SORT_KEY_ALBUM , VLC_PLAYLIST_SORT_KEY_ALBUM_ARTIST , VLC_PLAYLIST_SORT_KEY_GENRE , VLC_PLAYLIST_SORT_KEY_DATE , VLC_PLAYLIST_SORT_KEY_TRACK_NUMBER , VLC_PLAYLIST_SORT_KEY_DISC_NUMBER , VLC_PLAYLIST_SORT_KEY_URL , VLC_PLAYLIST_SORT_KEY_RATING , VLC_PLAYLIST_SORT_KEY_FILE_SIZE , VLC_PLAYLIST_SORT_KEY_FILE_MODIFIED }

enum	vlc_playlist_sort_order { VLC_PLAYLIST_SORT_ORDER_ASCENDING , VLC_PLAYLIST_SORT_ORDER_DESCENDING }

Functions
void	vlc_playlist_item_Hold (vlc_playlist_item_t *)
	Hold a playlist item. More...

void	vlc_playlist_item_Release (vlc_playlist_item_t *)
	Release a playlist item. More...

input_item_t *	vlc_playlist_item_GetMedia (vlc_playlist_item_t *)
	Return the media associated to the playlist item. More...

uint64_t	vlc_playlist_item_GetId (vlc_playlist_item_t *)
	Return a unique id for the playlist item instance. More...

vlc_playlist_t *	vlc_playlist_New (vlc_object_t *parent)
	Create a new playlist. More...

void	vlc_playlist_Delete (vlc_playlist_t *)
	Delete a playlist. More...

void	vlc_playlist_Lock (vlc_playlist_t *)
	Lock the playlist/player. More...

void	vlc_playlist_Unlock (vlc_playlist_t *)
	Unlock the playlist/player. More...

vlc_playlist_listener_id *	vlc_playlist_AddListener (vlc_playlist_t playlist, const struct vlc_playlist_callbacks cbs, void *userdata, bool notify_current_state)
	Add a playlist listener. More...

void	vlc_playlist_RemoveListener (vlc_playlist_t playlist, vlc_playlist_listener_id id)
	Remove a player listener. More...

size_t	vlc_playlist_Count (vlc_playlist_t *playlist)
	Return the number of items. More...

vlc_playlist_item_t *	vlc_playlist_Get (vlc_playlist_t *playlist, size_t index)
	Return the item at a given index. More...

void	vlc_playlist_Clear (vlc_playlist_t *playlist)
	Clear the playlist. More...

int	vlc_playlist_Insert (vlc_playlist_t playlist, size_t index, input_item_t const media[], size_t count)
	Insert a list of media at a given index. More...

static int	vlc_playlist_InsertOne (vlc_playlist_t playlist, size_t index, input_item_t media)
	Insert a media at a given index. More...

static int	vlc_playlist_Append (vlc_playlist_t playlist, input_item_t const media[], size_t count)
	Add a list of media at the end of the playlist. More...

static int	vlc_playlist_AppendOne (vlc_playlist_t playlist, input_item_t media)
	Add a media at the end of the playlist. More...

void	vlc_playlist_Move (vlc_playlist_t *playlist, size_t index, size_t count, size_t target)
	Move a slice of items to a given target index. More...

static void	vlc_playlist_MoveOne (vlc_playlist_t *playlist, size_t index, size_t target)
	Move an item to a given target index. More...

void	vlc_playlist_Remove (vlc_playlist_t *playlist, size_t index, size_t count)
	Remove a slice of items at a given index. More...

static void	vlc_playlist_RemoveOne (vlc_playlist_t *playlist, size_t index)
	Remove an item at a given index. More...

int	vlc_playlist_RequestInsert (vlc_playlist_t playlist, size_t index, input_item_t const media[], size_t count)
	Insert a list of media at a given index (if in range), or append. More...

int	vlc_playlist_RequestMove (vlc_playlist_t playlist, vlc_playlist_item_t const items[], size_t count, size_t target, ssize_t index_hint)
	Move a slice of items by value. More...

int	vlc_playlist_RequestRemove (vlc_playlist_t playlist, vlc_playlist_item_t const items[], size_t count, ssize_t index_hint)
	Remove a slice of items by value. More...

void	vlc_playlist_Shuffle (vlc_playlist_t *playlist)
	Shuffle the playlist. More...

int	vlc_playlist_Sort (vlc_playlist_t *playlist, const struct vlc_playlist_sort_criterion criteria[], size_t count)
	Sort the playlist by a list of criteria. More...

ssize_t	vlc_playlist_IndexOf (vlc_playlist_t playlist, const vlc_playlist_item_t item)
	Return the index of a given item. More...

ssize_t	vlc_playlist_IndexOfMedia (vlc_playlist_t playlist, const input_item_t media)
	Return the index of a given media. More...

ssize_t	vlc_playlist_IndexOfId (vlc_playlist_t *playlist, uint64_t id)
	Return the index of a given item id. More...

enum vlc_playlist_playback_repeat	vlc_playlist_GetPlaybackRepeat (vlc_playlist_t *playlist)
	Return the playback "repeat" mode. More...

enum vlc_playlist_playback_order	vlc_playlist_GetPlaybackOrder (vlc_playlist_t *playlist)
	Return the playback order. More...

void	vlc_playlist_SetPlaybackRepeat (vlc_playlist_t *playlist, enum vlc_playlist_playback_repeat repeat)
	Change the playback "repeat" mode. More...

void	vlc_playlist_SetPlaybackOrder (vlc_playlist_t *playlist, enum vlc_playlist_playback_order order)
	Change the playback order. More...

ssize_t	vlc_playlist_GetCurrentIndex (vlc_playlist_t *playlist)
	Return the index of the current item. More...

bool	vlc_playlist_HasPrev (vlc_playlist_t *playlist)
	Indicate whether a previous item is available. More...

bool	vlc_playlist_HasNext (vlc_playlist_t *playlist)
	Indicate whether a next item is available. More...

int	vlc_playlist_Prev (vlc_playlist_t *playlist)
	Go to the previous item. More...

int	vlc_playlist_Next (vlc_playlist_t *playlist)
	Go to the next item. More...

int	vlc_playlist_GoTo (vlc_playlist_t *playlist, ssize_t index)
	Go to a given index. More...

int	vlc_playlist_RequestGoTo (vlc_playlist_t playlist, vlc_playlist_item_t item, ssize_t index_hint)
	Go to a given item. More...

vlc_player_t *	vlc_playlist_GetPlayer (vlc_playlist_t *playlist)
	Return the player owned by the playlist. More...

int	vlc_playlist_Start (vlc_playlist_t *playlist)
	Start the player. More...

void	vlc_playlist_Stop (vlc_playlist_t *playlist)
	Stop the player. More...

void	vlc_playlist_Pause (vlc_playlist_t *playlist)
	Pause the player. More...

void	vlc_playlist_Resume (vlc_playlist_t *playlist)
	Resume the player. More...

static int	vlc_playlist_PlayAt (vlc_playlist_t *playlist, size_t index)
	Go to the given index and plays the corresponding item. More...

void	vlc_playlist_Preparse (vlc_playlist_t playlist, input_item_t media)
	Preparse a media, and expand it in the playlist on subitems added. More...

int	vlc_playlist_Export (vlc_playlist_t playlist, const char filename, const char *type)
	Export the playlist to a file. More...

Detailed Description

A VLC playlist contains a list of "playlist items".

Each playlist item contains exactly one media (input item). In the future, it might contain associated data.

The API is intended to be simple, UI-friendly and allow for an implementation both correct (no race conditions) and performant for common use cases.

UI frameworks typically use "list models" to provide a list of items to a list view component. A list model requires to implement functions to:

return the total number of items,
return the item at a given index.

In addition, it must notify the view when changes occur when:

items are inserted (providing index and count),
items are removed (providing index and count),
items are moved (providing index, count, and target index),
items are updated (providing index and count),
the model is reset (the whole content should be considered changed).

The API directly exposes what list models require.

The core playlist may be modified from any thread, so it may not be used as a direct data source for a list model. In other words, the functions of a list model must not delegate the calls to the playlist. This would require locking the playlist individually for each call to get the count and retrieve each item (which is, in itself, not a good idea for UI responsiveness), and would not be sufficient to guarantee correctness: the playlist content could change between view calls so that a request to retrieve an item at a specific index could be invalid (which would break the list model expected behavior).

As a consequence, the UI playlist should be considered as a remote out-of-sync view of the core playlist. This implies that the UI needs to keep a copy of the playlist content.

Note that the copy must not be limited to the list of playlist items (pointers) themselves, but also to the item's content which is displayed and susceptible to change asynchronously (e.g. media metadata, like title or duration). The UI should never lock a media (input item) for rendering a playlist item; otherwise, the content could be changed (and exposed) before the list model notified the view of this change (which, again, would break the list model expected behavior).

It is very important that the copy held by the UI is only modified through the core playlist callbacks, to guarantee that the indexes notified are valid in the context of the list model. In other words, from the client, the playlist copy is a read-only "desynchronized" view of the core playlist.

Moreover, the events triggered by the playlist must be kept in order until they are handled. The callbacks may be called from any thread, with lock held (in practice, the thread from which a change is requested). A UI will typically need to handle the events in the UI thread, so it will usually post the events in an event loop, to handle them from the UI thread. In that case, be careful to always post the events in the event loop, even if the current thread is already the UI thread, not to break the order of events.

The playlist also handles the playback order and the repeat mode. It also manages a cursor to the "current" item, and exposes whether previous and next items (which depend on the playback order and repeat mode) are available.

When a user requests to insert, move or remove items, or to set the current item, before the core playlist lock is successfully acquired, another client may have changed the list. Therefore, vlc_playlist_Request*() functions are exposed to resolve potential conflicts and apply the changes. The actual changes applied are notified through the callbacks.

Typedef Documentation

◆ input_item_t

typedef struct input_item_t input_item_t

◆ vlc_player_t

typedef struct vlc_player_t vlc_player_t

◆ vlc_playlist_item_t

typedef struct vlc_playlist_item vlc_playlist_item_t

◆ vlc_playlist_listener_id

typedef struct vlc_playlist_listener_id vlc_playlist_listener_id

◆ vlc_playlist_t

typedef struct vlc_playlist vlc_playlist_t

Enumeration Type Documentation

◆ vlc_playlist_playback_order

enum vlc_playlist_playback_order

Enumerator
VLC_PLAYLIST_PLAYBACK_ORDER_NORMAL
VLC_PLAYLIST_PLAYBACK_ORDER_RANDOM

◆ vlc_playlist_playback_repeat

enum vlc_playlist_playback_repeat

Enumerator
VLC_PLAYLIST_PLAYBACK_REPEAT_NONE
VLC_PLAYLIST_PLAYBACK_REPEAT_CURRENT
VLC_PLAYLIST_PLAYBACK_REPEAT_ALL

◆ vlc_playlist_sort_key

enum vlc_playlist_sort_key

Enumerator
VLC_PLAYLIST_SORT_KEY_TITLE
VLC_PLAYLIST_SORT_KEY_DURATION
VLC_PLAYLIST_SORT_KEY_ARTIST
VLC_PLAYLIST_SORT_KEY_ALBUM
VLC_PLAYLIST_SORT_KEY_ALBUM_ARTIST
VLC_PLAYLIST_SORT_KEY_GENRE
VLC_PLAYLIST_SORT_KEY_DATE
VLC_PLAYLIST_SORT_KEY_TRACK_NUMBER
VLC_PLAYLIST_SORT_KEY_DISC_NUMBER
VLC_PLAYLIST_SORT_KEY_URL
VLC_PLAYLIST_SORT_KEY_RATING
VLC_PLAYLIST_SORT_KEY_FILE_SIZE
VLC_PLAYLIST_SORT_KEY_FILE_MODIFIED

◆ vlc_playlist_sort_order

enum vlc_playlist_sort_order

Enumerator
VLC_PLAYLIST_SORT_ORDER_ASCENDING
VLC_PLAYLIST_SORT_ORDER_DESCENDING

Function Documentation

◆ vlc_playlist_AddListener()

vlc_playlist_listener_id * vlc_playlist_AddListener	(	vlc_playlist_t *	playlist,
		const struct vlc_playlist_callbacks *	cbs,
		void *	userdata,
		bool	notify_current_state
	)

Add a playlist listener.

Return an opaque listener identifier, to be passed to vlc_player_RemoveListener().

If notify_current_state is true, the callbacks are called once with the current state of the playlist. This is useful because when a client registers to the playlist, it may already contain items. Calling callbacks is a convenient way to initialize the client automatically.

Parameters

playlist	the playlist, locked
cbs	the callbacks (must be valid until the listener is removed)
userdata	userdata provided as a parameter in callbacks
notify_current_state	true to notify the current state immediately via callbacks

Returns: a listener identifier, or NULL if an error occurred

References vlc_playlist_listener_id::cbs, vlc_playlist::listeners, vlc_playlist_listener_id::node, unlikely, vlc_playlist_listener_id::userdata, vlc_list_append(), vlc_playlist_AssertLocked(), and vlc_playlist_NotifyCurrentState().

◆ vlc_playlist_Append()

static int vlc_playlist_Append	(	vlc_playlist_t *	playlist,
		input_item_t *const	media[],
		size_t	count
	)

inlinestatic

Add a list of media at the end of the playlist.

Parameters

playlist	the playlist, locked
media	the array of media to append
count	the number of media to append

Returns: VLC_SUCCESS on success, another value on error

References count, vlc_playlist_Count(), and vlc_playlist_Insert().

Referenced by vlc_playlist_AppendOne().

◆ vlc_playlist_AppendOne()

static int vlc_playlist_AppendOne	(	vlc_playlist_t *	playlist,
		input_item_t *	media
	)

inlinestatic

Add a media at the end of the playlist.

Parameters

playlist	the playlist, locked
media	the media to append

Returns: VLC_SUCCESS on success, another value on error

References vlc_playlist_Append().

Referenced by add_to_playlist().

◆ vlc_playlist_Clear()

void vlc_playlist_Clear ( vlc_playlist_t * playlist )

Clear the playlist.

Parameters

playlist the playlist, locked

References vlc_playlist::player, vlc_player_SetCurrentMedia(), vlc_playlist_AssertLocked(), vlc_playlist_ClearItems(), vlc_playlist_ItemsReset(), and VLC_UNUSED.

◆ vlc_playlist_Count()

size_t vlc_playlist_Count ( vlc_playlist_t * playlist )

Return the number of items.

Parameters

playlist the playlist, locked

References vlc_playlist::items, playlist_item_vector_t::size, and vlc_playlist_AssertLocked().

Referenced by libvlc_InternalPlay(), vlc_playlist_Append(), vlc_playlist_FindRealIndex(), vlc_playlist_RequestInsert(), vlc_playlist_RequestMove(), and vlc_playlist_view_Count().

◆ vlc_playlist_Delete()

void vlc_playlist_Delete ( vlc_playlist_t * playlist )

Delete a playlist.

All playlist items are released, and listeners are removed and destroyed.

References vlc_playlist::listeners, vlc_playlist::randomizer, randomizer_Destroy(), vlc_list_is_empty(), vlc_playlist_ClearItems(), and vlc_playlist_PlayerDestroy().

Referenced by libvlc_InternalCleanup().

◆ vlc_playlist_Export()

int vlc_playlist_Export	(	vlc_playlist_t *	playlist,
		const char *	filename,
		const char *	type
	)

Export the playlist to a file.

Parameters

filename	the location where the exported file will be saved
type	the type of the playlist file to create (m3u, m3u8, xspf, ...)

Returns: VLC_SUCCESS on success, another value on error

References vlc_playlist_export::base_url, vlc_playlist_export::file, module_need, module_unneed, msg_Err, vlc_playlist::player, vlc_playlist_view::playlist, vlc_playlist_export::playlist_view, vlc_custom_create, VLC_EGENERIC, VLC_ENOMEM, vlc_fopen(), vlc_object_delete, vlc_path2uri(), vlc_player_GetObject(), vlc_playlist_AssertLocked(), vlc_strerror_c(), and VLC_SUCCESS.

◆ vlc_playlist_Get()

vlc_playlist_item_t * vlc_playlist_Get	(	vlc_playlist_t *	playlist,
		size_t	index
	)

Return the item at a given index.

The index must be in range (less than vlc_playlist_Count()).

Parameters

playlist	the playlist, locked
index	the index

Returns: the playlist item

References playlist_item_vector_t::data, vlc_playlist::items, and vlc_playlist_AssertLocked().

Referenced by vlc_playlist_FindRealIndex(), and vlc_playlist_view_Get().

◆ vlc_playlist_GetCurrentIndex()

ssize_t vlc_playlist_GetCurrentIndex ( vlc_playlist_t * playlist )

Return the index of the current item.

Parameters

playlist the playlist, locked

Returns: the index of the current item, -1 if none.

References vlc_playlist::current, and vlc_playlist_AssertLocked().

Referenced by libvlc_InternalPlay().

◆ vlc_playlist_GetPlaybackOrder()

enum vlc_playlist_playback_order vlc_playlist_GetPlaybackOrder ( vlc_playlist_t * playlist )

Return the playback order.

Parameters

playlist the playlist, locked

Returns: the playback order

References vlc_playlist::order, and vlc_playlist_AssertLocked().

◆ vlc_playlist_GetPlaybackRepeat()

enum vlc_playlist_playback_repeat vlc_playlist_GetPlaybackRepeat ( vlc_playlist_t * playlist )

Return the playback "repeat" mode.

Parameters

playlist the playlist, locked

Returns: the playback "repeat" mode

References vlc_playlist::repeat, and vlc_playlist_AssertLocked().

◆ vlc_playlist_GetPlayer()

vlc_player_t * vlc_playlist_GetPlayer ( vlc_playlist_t * playlist )

Return the player owned by the playlist.

Parameters

playlist the playlist (not necessarily locked)

Returns: the player

References vlc_playlist::player.

Referenced by PlaylistConfigureFromVariables().

◆ vlc_playlist_GoTo()

int vlc_playlist_GoTo	(	vlc_playlist_t *	playlist,
		ssize_t	index
	)

Go to a given index.

the index must be -1 or in range (less than vlc_playlist_Count()).

Parameters

playlist	the playlist, locked
index	the index to go to (-1 to none)

Returns: VLC_SUCCESS on success, another value on error

References playlist_item_vector_t::data, vlc_playlist::items, vlc_playlist::order, vlc_playlist::randomizer, randomizer_Select(), vlc_playlist_AssertLocked(), VLC_PLAYLIST_PLAYBACK_ORDER_RANDOM, vlc_playlist_SetCurrentIndex(), vlc_playlist_SetCurrentMedia(), and VLC_SUCCESS.

Referenced by libvlc_InternalPlay(), vlc_playlist_PlayAt(), and vlc_playlist_RequestGoTo().

◆ vlc_playlist_HasNext()

bool vlc_playlist_HasNext ( vlc_playlist_t * playlist )

Indicate whether a next item is available.

Parameters

playlist the playlist, locked

Return values

true	if a next item is available
false	if no next item is available

References vlc_playlist::has_next, and vlc_playlist_AssertLocked().

◆ vlc_playlist_HasPrev()

bool vlc_playlist_HasPrev ( vlc_playlist_t * playlist )

Indicate whether a previous item is available.

Parameters

playlist the playlist, locked

Return values

true	if a previous item is available
false	if no previous item is available

References vlc_playlist::has_prev, and vlc_playlist_AssertLocked().

◆ vlc_playlist_IndexOf()

ssize_t vlc_playlist_IndexOf	(	vlc_playlist_t *	playlist,
		const vlc_playlist_item_t *	item
	)

Return the index of a given item.

Parameters

playlist	the playlist, locked
item	the item to locate

Returns: the index of the item (-1 if not found)

References vlc_playlist::items, vlc_playlist_AssertLocked(), and vlc_vector_index_of.

Referenced by vlc_playlist_FindRealIndex(), vlc_playlist_RandomOrderGetNextIndex(), vlc_playlist_RandomOrderGetPrevIndex(), vlc_playlist_Shuffle(), and vlc_playlist_Sort().

◆ vlc_playlist_IndexOfId()

ssize_t vlc_playlist_IndexOfId	(	vlc_playlist_t *	playlist,
		uint64_t	id
	)

Return the index of a given item id.

Parameters

playlist	the playlist, locked
id	the id to locate

Returns: the index of the playlist item having the id (-1 if not found)

References playlist_item_vector_t::data, vlc_playlist_item::id, vlc_playlist::items, playlist_item_vector_t::size, and vlc_playlist_AssertLocked().

◆ vlc_playlist_IndexOfMedia()

ssize_t vlc_playlist_IndexOfMedia	(	vlc_playlist_t *	playlist,
		const input_item_t *	media
	)

Return the index of a given media.

Parameters

playlist	the playlist, locked
media	the media to locate

Returns: the index of the playlist item containing the media (-1 if not found)

References playlist_item_vector_t::data, vlc_playlist::items, vlc_playlist_item::media, playlist_item_vector_t::size, and vlc_playlist_AssertLocked().

Referenced by on_preparse_ended(), player_on_current_media_changed(), vlc_playlist_ExpandItemFromNode(), and vlc_playlist_NotifyMediaUpdated().

◆ vlc_playlist_Insert()

int vlc_playlist_Insert	(	vlc_playlist_t *	playlist,
		size_t	index,
		input_item_t *const	media[],
		size_t	count
	)

Insert a list of media at a given index.

The index must be in range (less than or equal to vlc_playlist_Count()).

Parameters

playlist	the playlist, locked \index index the index where the media are to be inserted
media	the array of media to insert
count	the number of media to insert

Returns: VLC_SUCCESS on success, another value on error

References count, playlist_item_vector_t::data, vlc_playlist::items, vlc_playlist::player, VLC_ENOMEM, vlc_player_InvalidateNextMedia(), vlc_playlist_AssertLocked(), vlc_playlist_ItemsInserted(), vlc_playlist_MediaToItems(), VLC_SUCCESS, vlc_vector_insert_hole, and vlc_vector_remove_slice.

Referenced by vlc_playlist_Append(), vlc_playlist_InsertOne(), and vlc_playlist_RequestInsert().

◆ vlc_playlist_InsertOne()

static int vlc_playlist_InsertOne	(	vlc_playlist_t *	playlist,
		size_t	index,
		input_item_t *	media
	)

inlinestatic

Insert a media at a given index.

The index must be in range (less than or equal to vlc_playlist_Count()).

Parameters

playlist	the playlist, locked \index index the index where the media is to be inserted
media	the media to insert

Returns: VLC_SUCCESS on success, another value on error

References vlc_playlist_Insert().

Referenced by intf_InsertItem().

◆ vlc_playlist_item_GetId()

uint64_t vlc_playlist_item_GetId ( vlc_playlist_item_t * item )

Return a unique id for the playlist item instance.

References vlc_playlist_item::id.

◆ vlc_playlist_item_GetMedia()

input_item_t * vlc_playlist_item_GetMedia ( vlc_playlist_item_t * item )

Return the media associated to the playlist item.

References vlc_playlist_item::media.

◆ vlc_playlist_item_Hold()

void vlc_playlist_item_Hold ( vlc_playlist_item_t * item )

Hold a playlist item.

Increment the refcount of the playlist item.

References vlc_playlist_item::rc, and vlc_atomic_rc_inc().

◆ vlc_playlist_item_Release()

void vlc_playlist_item_Release ( vlc_playlist_item_t * item )

Release a playlist item.

Decrement the refcount of the playlist item, and destroy it if necessary.

References input_item_Release(), vlc_playlist_item::media, vlc_playlist_item::rc, and vlc_atomic_rc_dec().

Referenced by vlc_playlist_ClearItems(), vlc_playlist_MediaToItems(), vlc_playlist_Remove(), and vlc_playlist_Replace().

◆ vlc_playlist_Lock()

void vlc_playlist_Lock ( vlc_playlist_t * playlist )

Lock the playlist/player.

The playlist and its player share the same lock, to avoid lock-order inversion issues.

Warning: Do not forget that the playlist and player lock are the same (or you could lock twice the same and deadlock).

Almost all playlist functions must be called with lock held (check their description).

The lock is not recursive.

References vlc_playlist::player, and vlc_player_Lock().

Referenced by add_to_playlist(), intf_InsertItem(), libvlc_InternalPlay(), on_preparse_ended(), on_subtree_added(), and PlaylistConfigureFromVariables().

◆ vlc_playlist_Move()

void vlc_playlist_Move	(	vlc_playlist_t *	playlist,
		size_t	index,
		size_t	count,
		size_t	target
	)

Move a slice of items to a given target index.

The slice and the target must be in range (both index+count and target+count less than or equal to vlc_playlist_Count()).

Parameters

playlist	the playlist, locked
index	the index of the first item to move
count	the number of items to move
target	the new index of the moved slice

References count, vlc_playlist::items, vlc_playlist::player, vlc_player_InvalidateNextMedia(), vlc_playlist_AssertLocked(), vlc_playlist_ItemsMoved(), and vlc_vector_move_slice.

Referenced by vlc_playlist_MoveBySlices(), vlc_playlist_MoveOne(), and vlc_playlist_Regroup().

◆ vlc_playlist_MoveOne()

static void vlc_playlist_MoveOne	(	vlc_playlist_t *	playlist,
		size_t	index,
		size_t	target
	)

inlinestatic

Move an item to a given target index.

The index and the target must be in range (index less than, and target less than or equal to, vlc_playlist_Count()).

Parameters

playlist	the playlist, locked
index	the index of the item to move
target	the new index of the moved item

References vlc_playlist_Move().

◆ vlc_playlist_New()

vlc_playlist_t * vlc_playlist_New ( vlc_object_t * parent )

Create a new playlist.

Parameters

parent a VLC object

Returns: a pointer to a valid playlist instance, or NULL if an error occurred

References vlc_playlist::auto_preparse, vlc_playlist::current, vlc_playlist::has_next, vlc_playlist::has_prev, vlc_playlist::idgen, vlc_playlist::items, vlc_playlist::libvlc, vlc_playlist::listeners, vlc_playlist::order, vlc_playlist::randomizer, randomizer_Init(), vlc_playlist::repeat, unlikely, var_InheritBool(), vlc_list_init(), vlc_object_instance, VLC_PLAYLIST_PLAYBACK_ORDER_NORMAL, VLC_PLAYLIST_PLAYBACK_REPEAT_NONE, vlc_playlist_PlayerInit(), and vlc_vector_init.

Referenced by libvlc_GetMainPlaylist().

◆ vlc_playlist_Next()

int vlc_playlist_Next ( vlc_playlist_t * playlist )

Go to the next item.

Return VLC_EGENERIC if vlc_playlist_HasNext() returns false.

Parameters

playlist the playlist, locked

Returns: VLC_SUCCESS on success, another value on error

References _, playlist_item_vector_t::data, vlc_playlist::items, vlc_playlist::order, vlc_playlist::player, vlc_playlist::randomizer, randomizer_Next(), VLC_EGENERIC, vlc_player_osd_Message(), vlc_playlist_AssertLocked(), vlc_playlist_ComputeHasNext(), vlc_playlist_GetNextIndex(), VLC_PLAYLIST_PLAYBACK_ORDER_RANDOM, vlc_playlist_SetCurrentIndex(), vlc_playlist_SetCurrentMedia(), VLC_SUCCESS, and VLC_UNUSED.

◆ vlc_playlist_Pause()

void vlc_playlist_Pause ( vlc_playlist_t * playlist )

Pause the player.

Parameters

playlist the playlist, locked

References vlc_playlist::player, and vlc_player_Pause().

◆ vlc_playlist_PlayAt()

static int vlc_playlist_PlayAt	(	vlc_playlist_t *	playlist,
		size_t	index
	)

inlinestatic

Go to the given index and plays the corresponding item.

Parameters

playlist	the playlist, locked
index	the index to play at

Returns: VLC_SUCCESS on success, another value on error

References vlc_playlist_GoTo(), vlc_playlist_Start(), and VLC_SUCCESS.

◆ vlc_playlist_Preparse()

void vlc_playlist_Preparse	(	vlc_playlist_t *	playlist,
		input_item_t *	media
	)

Preparse a media, and expand it in the playlist on subitems added.

Parameters

playlist	the playlist (not necessarily locked)
media	the media to preparse

References vlc_playlist::libvlc, META_REQUEST_OPTION_FETCH_LOCAL, META_REQUEST_OPTION_SCOPE_LOCAL, preparser_callbacks, vlc_MetadataRequest(), and VLC_UNUSED.

Referenced by vlc_playlist_AutoPreparse().

◆ vlc_playlist_Prev()

int vlc_playlist_Prev ( vlc_playlist_t * playlist )

Go to the previous item.

Return VLC_EGENERIC if vlc_playlist_HasPrev() returns false.

Parameters

playlist the playlist, locked

Returns: VLC_SUCCESS on success, another value on error

References _, playlist_item_vector_t::data, vlc_playlist::items, vlc_playlist::order, vlc_playlist::player, vlc_playlist::randomizer, randomizer_Prev(), VLC_EGENERIC, vlc_player_osd_Message(), vlc_playlist_AssertLocked(), vlc_playlist_ComputeHasPrev(), vlc_playlist_GetPrevIndex(), VLC_PLAYLIST_PLAYBACK_ORDER_RANDOM, vlc_playlist_SetCurrentIndex(), vlc_playlist_SetCurrentMedia(), VLC_SUCCESS, and VLC_UNUSED.

◆ vlc_playlist_Remove()

void vlc_playlist_Remove	(	vlc_playlist_t *	playlist,
		size_t	index,
		size_t	count
	)

Remove a slice of items at a given index.

The slice must be in range (index+count less than or equal to vlc_playlist_Count()).

Parameters

playlist	the playlist, locked
index	the index of the first item to remove
count	the number of items to remove

References count, vlc_playlist::current, playlist_item_vector_t::data, vlc_playlist::items, vlc_playlist::player, vlc_player_InvalidateNextMedia(), vlc_playlist_AssertLocked(), vlc_playlist_item_Release(), vlc_playlist_ItemsRemoved(), vlc_playlist_ItemsRemoving(), vlc_playlist_SetCurrentMedia(), and vlc_vector_remove_slice.

Referenced by vlc_playlist_RemoveBySlices(), and vlc_playlist_RemoveOne().

◆ vlc_playlist_RemoveListener()

void vlc_playlist_RemoveListener	(	vlc_playlist_t *	playlist,
		vlc_playlist_listener_id *	id
	)

Remove a player listener.

Parameters

playlist	the playlist, locked
id	the listener identifier returned by vlc_playlist_AddListener()

References vlc_playlist_listener_id::node, vlc_list_remove(), vlc_playlist_AssertLocked(), and VLC_UNUSED.

◆ vlc_playlist_RemoveOne()

static void vlc_playlist_RemoveOne	(	vlc_playlist_t *	playlist,
		size_t	index
	)

inlinestatic

Remove an item at a given index.

The index must be in range (less than vlc_playlist_Count()).

Parameters

playlist	the playlist, locked
index	the index of the item to remove

References vlc_playlist_Remove().

Referenced by vlc_playlist_Expand().

◆ vlc_playlist_RequestGoTo()

int vlc_playlist_RequestGoTo	(	vlc_playlist_t *	playlist,
		vlc_playlist_item_t *	item,
		ssize_t	index_hint
	)

Go to a given item.

If the index is known, use vlc_playlist_GoTo() instead.

This is a helper to apply a desynchronized "go to" request, i.e. the playlist content may have changed since the request had been submitted. This is typically the case for user requests (e.g. from UI), because the playlist lock has to be acquired after the user requested the change.

For optimization purpose, it is possible to pass an index_hint, which is the expected index of the first item of the slice (as known by the client). Hopefully, the index should often match, since conflicts are expected to be rare. Pass -1 not to pass any hint.

Parameters

playlist	the playlist, locked
item	the item to go to (NULL for none)
index_hint	the expected index of the item (-1 for none)

Returns: VLC_SUCCESS on success, another value on error

References vlc_playlist_AssertLocked(), vlc_playlist_FindRealIndex(), and vlc_playlist_GoTo().

◆ vlc_playlist_RequestInsert()

int vlc_playlist_RequestInsert	(	vlc_playlist_t *	playlist,
		size_t	index,
		input_item_t *const	media[],
		size_t	count
	)

Insert a list of media at a given index (if in range), or append.

Contrary to vlc_playlist_Insert(), the index need not be in range: if it is out of bounds, items will be appended.

This is an helper to apply a desynchronized insert request, i.e. the playlist content may have changed since the request had been submitted. This is typically the case for user requests (e.g. from UI), because the playlist lock has to be acquired after the user requested the change.

Parameters

playlist	the playlist, locked \index index the index where the media are to be inserted
media	the array of media to insert
count	the number of media to insert

Returns: VLC_SUCCESS on success, another value on error

References count, vlc_playlist_AssertLocked(), vlc_playlist_Count(), and vlc_playlist_Insert().

◆ vlc_playlist_RequestMove()

int vlc_playlist_RequestMove	(	vlc_playlist_t *	playlist,
		vlc_playlist_item_t *const	items[],
		size_t	count,
		size_t	target,
		ssize_t	index_hint
	)

Move a slice of items by value.

If the indices are known, use vlc_playlist_Move() instead.

This is an helper to apply a desynchronized move request, i.e. the playlist content may have changed since the request had been submitted. This is typically the case for user requests (e.g. from UI), because the playlist lock has to be acquired after the user requested the change.

For optimization purpose, it is possible to pass an index_hint, which is the expected index of the first item of the slice (as known by the client). Hopefully, the index should often match, since conflicts are expected to be rare. Pass -1 not to pass any hint.

Parameters

playlist	the playlist, locked
items	the array of items to move
count	the number of items to move
target	the new index of the moved slice
index_hint	the expected index of the first item (-1 for none)

Returns: VLC_SUCCESS on success, another value on error

References count, size_vector::data, size_vector::size, VLC_ENOMEM, vlc_playlist_AssertLocked(), vlc_playlist_Count(), vlc_playlist_FindIndices(), vlc_playlist_MoveBySlices(), VLC_SUCCESS, vlc_vector_destroy, VLC_VECTOR_INITIALIZER, and vlc_vector_reserve.

◆ vlc_playlist_RequestRemove()

int vlc_playlist_RequestRemove	(	vlc_playlist_t *	playlist,
		vlc_playlist_item_t *const	items[],
		size_t	count,
		ssize_t	index_hint
	)

Remove a slice of items by value.

If the indices are known, use vlc_playlist_Remove() instead.

This is an helper to apply a desynchronized remove request, i.e. the playlist content may have changed since the request had been submitted. This is typically the case for user requests (e.g. from UI), because the playlist lock has to be acquired after the user requested the change.

For optimization purpose, it is possible to pass an index_hint, which is the expected index of the first item of the slice (as known by the client). Hopefully, the index should often match, since conflicts are expected to be rare. Pass -1 not to pass any hint.

Parameters

playlist	the playlist, locked
items	the array of items to remove
count	the number of items to remove
index_hint	the expected index of the first item (-1 for none)

Returns: VLC_SUCCESS on success, another value on error

References cmp_size(), count, size_vector::data, size_vector::size, VLC_ENOMEM, vlc_playlist_AssertLocked(), vlc_playlist_FindIndices(), vlc_playlist_RemoveBySlices(), VLC_SUCCESS, vlc_vector_destroy, VLC_VECTOR_INITIALIZER, and vlc_vector_reserve.

◆ vlc_playlist_Resume()

void vlc_playlist_Resume ( vlc_playlist_t * playlist )

Resume the player.

Parameters

playlist the playlist, locked

References vlc_playlist::player, and vlc_player_Resume().

◆ vlc_playlist_SetPlaybackOrder()

void vlc_playlist_SetPlaybackOrder	(	vlc_playlist_t *	playlist,
		enum vlc_playlist_playback_order	order
	)

Change the playback order.

Parameters

playlist	the playlist, locked
order	the new playback order

References vlc_playlist::order, vlc_playlist_AssertLocked(), and vlc_playlist_PlaybackOrderChanged().

Referenced by PlaylistConfigureFromVariables().

◆ vlc_playlist_SetPlaybackRepeat()

void vlc_playlist_SetPlaybackRepeat	(	vlc_playlist_t *	playlist,
		enum vlc_playlist_playback_repeat	repeat
	)

Change the playback "repeat" mode.

Parameters

playlist	the playlist, locked
repeat	the new playback "repeat" mode

References vlc_playlist::repeat, vlc_playlist_AssertLocked(), and vlc_playlist_PlaybackRepeatChanged().

Referenced by PlaylistConfigureFromVariables().

◆ vlc_playlist_Shuffle()

void vlc_playlist_Shuffle ( vlc_playlist_t * playlist )

Shuffle the playlist.

Parameters

playlist the playlist, locked

References current, vlc_playlist::current, playlist_item_vector_t::data, vlc_playlist::has_next, vlc_playlist::has_prev, vlc_playlist::items, nrand48(), playlist_item_vector_t::size, state, vlc_playlist_AssertLocked(), vlc_playlist_ComputeHasNext(), vlc_playlist_ComputeHasPrev(), vlc_playlist_IndexOf(), vlc_playlist_Notify, vlc_playlist_state_NotifyChanges(), vlc_playlist_state_Save(), and vlc_rand_bytes().

◆ vlc_playlist_Sort()

int vlc_playlist_Sort	(	vlc_playlist_t *	playlist,
		const struct vlc_playlist_sort_criterion	criteria[],
		size_t	count
	)

Sort the playlist by a list of criteria.

Parameters

playlist	the playlist, locked
criteria	the sort criteria (in order)
count	the number of criteria

Returns: VLC_SUCCESS on success, another value on error

References compare_meta(), count, sort_request::criteria, current, vlc_playlist::current, playlist_item_vector_t::data, vlc_playlist::has_next, vlc_playlist::has_prev, vlc_playlist_item_meta::item, vlc_playlist::items, playlist_item_vector_t::size, state, unlikely, VLC_ENOMEM, vlc_playlist_AssertLocked(), vlc_playlist_ComputeHasNext(), vlc_playlist_ComputeHasPrev(), vlc_playlist_DeleteMetaArray(), vlc_playlist_IndexOf(), vlc_playlist_NewMetaArray(), vlc_playlist_Notify, vlc_playlist_state_NotifyChanges(), vlc_playlist_state_Save(), vlc_qsort(), and VLC_SUCCESS.

◆ vlc_playlist_Start()

int vlc_playlist_Start ( vlc_playlist_t * playlist )

Start the player.

Parameters

playlist the playlist, locked

Returns: VLC_SUCCESS on success, another value on error

References vlc_playlist::player, and vlc_player_Start().

Referenced by add_to_playlist(), libvlc_InternalPlay(), and vlc_playlist_PlayAt().

◆ vlc_playlist_Stop()

void vlc_playlist_Stop ( vlc_playlist_t * playlist )

Stop the player.

Parameters

playlist the playlist, locked

References vlc_playlist::player, and vlc_player_Stop().

◆ vlc_playlist_Unlock()

void vlc_playlist_Unlock ( vlc_playlist_t * playlist )

Unlock the playlist/player.

References vlc_playlist::player, and vlc_player_Unlock().

Referenced by add_to_playlist(), intf_InsertItem(), libvlc_InternalPlay(), on_preparse_ended(), on_subtree_added(), and PlaylistConfigureFromVariables().

Modules

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ input_item_t

◆ vlc_player_t

◆ vlc_playlist_item_t

◆ vlc_playlist_listener_id

◆ vlc_playlist_t

Enumeration Type Documentation

◆ vlc_playlist_playback_order

◆ vlc_playlist_playback_repeat

◆ vlc_playlist_sort_key

◆ vlc_playlist_sort_order

Function Documentation

◆ vlc_playlist_AddListener()

◆ vlc_playlist_Append()

◆ vlc_playlist_AppendOne()

◆ vlc_playlist_Clear()

◆ vlc_playlist_Count()

◆ vlc_playlist_Delete()

◆ vlc_playlist_Export()

◆ vlc_playlist_Get()

◆ vlc_playlist_GetCurrentIndex()

◆ vlc_playlist_GetPlaybackOrder()

◆ vlc_playlist_GetPlaybackRepeat()

◆ vlc_playlist_GetPlayer()

◆ vlc_playlist_GoTo()

◆ vlc_playlist_HasNext()

◆ vlc_playlist_HasPrev()

◆ vlc_playlist_IndexOf()

◆ vlc_playlist_IndexOfId()

◆ vlc_playlist_IndexOfMedia()

◆ vlc_playlist_Insert()

◆ vlc_playlist_InsertOne()

◆ vlc_playlist_item_GetId()

◆ vlc_playlist_item_GetMedia()

◆ vlc_playlist_item_Hold()

◆ vlc_playlist_item_Release()

◆ vlc_playlist_Lock()

◆ vlc_playlist_Move()

◆ vlc_playlist_MoveOne()

◆ vlc_playlist_New()

◆ vlc_playlist_Next()

◆ vlc_playlist_Pause()

◆ vlc_playlist_PlayAt()

◆ vlc_playlist_Preparse()

◆ vlc_playlist_Prev()

◆ vlc_playlist_Remove()

◆ vlc_playlist_RemoveListener()

◆ vlc_playlist_RemoveOne()

◆ vlc_playlist_RequestGoTo()

◆ vlc_playlist_RequestInsert()

◆ vlc_playlist_RequestMove()

◆ vlc_playlist_RequestRemove()

◆ vlc_playlist_Resume()

◆ vlc_playlist_SetPlaybackOrder()

◆ vlc_playlist_SetPlaybackRepeat()

◆ vlc_playlist_Shuffle()

◆ vlc_playlist_Sort()

◆ vlc_playlist_Start()

◆ vlc_playlist_Stop()

◆ vlc_playlist_Unlock()