VLC  4.0.0-dev
Modules | Data Structures | Typedefs | Enumerations | Functions
Collaboration diagram for VLC playlist:

Modules

 Playlist randomizer helper
 

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
}
 
enum  vlc_playlist_sort_order { VLC_PLAYLIST_SORT_ORDER_ASCENDING, VLC_PLAYLIST_SORT_ORDER_DESCENDING }
 

Functions

VLC_EXPORT void vlc_playlist_item_Hold (vlc_playlist_item_t *)
 Hold a playlist item. More...
 
VLC_EXPORT void vlc_playlist_item_Release (vlc_playlist_item_t *)
 Release a playlist item. More...
 
VLC_EXPORT input_item_tvlc_playlist_item_GetMedia (vlc_playlist_item_t *)
 Return the media associated to the playlist item. More...
 
VLC_EXPORT uint64_t vlc_playlist_item_GetId (vlc_playlist_item_t *)
 Return a unique id for the playlist item instance. More...
 
VLC_EXPORT vlc_playlist_tvlc_playlist_New (vlc_object_t *parent)
 Create a new playlist. More...
 
VLC_EXPORT void vlc_playlist_Delete (vlc_playlist_t *)
 Delete a playlist. More...
 
VLC_EXPORT void vlc_playlist_Lock (vlc_playlist_t *)
 Lock the playlist/player. More...
 
VLC_EXPORT void vlc_playlist_Unlock (vlc_playlist_t *)
 Unlock the playlist/player. More...
 
VLC_EXPORT vlc_playlist_listener_idvlc_playlist_AddListener (vlc_playlist_t *playlist, const struct vlc_playlist_callbacks *cbs, void *userdata, bool notify_current_state)
 Add a playlist listener. More...
 
VLC_EXPORT void vlc_playlist_RemoveListener (vlc_playlist_t *, vlc_playlist_listener_id *)
 Remove a player listener. More...
 
VLC_EXPORT size_t vlc_playlist_Count (vlc_playlist_t *playlist)
 Return the number of items. More...
 
VLC_EXPORT vlc_playlist_item_tvlc_playlist_Get (vlc_playlist_t *playlist, size_t index)
 Return the item at a given index. More...
 
VLC_EXPORT void vlc_playlist_Clear (vlc_playlist_t *playlist)
 Clear the playlist. More...
 
VLC_EXPORT 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...
 
VLC_EXPORT 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...
 
VLC_EXPORT 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...
 
VLC_EXPORT 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...
 
VLC_EXPORT 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...
 
VLC_EXPORT 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...
 
VLC_EXPORT void vlc_playlist_Shuffle (vlc_playlist_t *playlist)
 Shuffle the playlist. More...
 
VLC_EXPORT 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...
 
VLC_EXPORT ssize_t vlc_playlist_IndexOf (vlc_playlist_t *playlist, const vlc_playlist_item_t *item)
 Return the index of a given item. More...
 
VLC_EXPORT ssize_t vlc_playlist_IndexOfMedia (vlc_playlist_t *playlist, const input_item_t *media)
 Return the index of a given media. More...
 
VLC_EXPORT ssize_t vlc_playlist_IndexOfId (vlc_playlist_t *playlist, uint64_t id)
 Return the index of a given item id. More...
 
VLC_EXPORT enum vlc_playlist_playback_repeat vlc_playlist_GetPlaybackRepeat (vlc_playlist_t *playlist)
 Return the playback "repeat" mode. More...
 
VLC_EXPORT enum vlc_playlist_playback_order vlc_playlist_GetPlaybackOrder (vlc_playlist_t *)
 Return the playback order. More...
 
VLC_EXPORT void vlc_playlist_SetPlaybackRepeat (vlc_playlist_t *playlist, enum vlc_playlist_playback_repeat repeat)
 Change the playback "repeat" mode. More...
 
VLC_EXPORT void vlc_playlist_SetPlaybackOrder (vlc_playlist_t *playlist, enum vlc_playlist_playback_order order)
 Change the playback order. More...
 
VLC_EXPORT ssize_t vlc_playlist_GetCurrentIndex (vlc_playlist_t *playlist)
 Return the index of the current item. More...
 
VLC_EXPORT bool vlc_playlist_HasPrev (vlc_playlist_t *playlist)
 Indicate whether a previous item is available. More...
 
VLC_EXPORT bool vlc_playlist_HasNext (vlc_playlist_t *playlist)
 Indicate whether a next item is available. More...
 
VLC_EXPORT int vlc_playlist_Prev (vlc_playlist_t *playlist)
 Go to the previous item. More...
 
VLC_EXPORT int vlc_playlist_Next (vlc_playlist_t *playlist)
 Go to the next item. More...
 
VLC_EXPORT int vlc_playlist_GoTo (vlc_playlist_t *playlist, ssize_t index)
 Go to a given index. More...
 
VLC_EXPORT int vlc_playlist_RequestGoTo (vlc_playlist_t *playlist, vlc_playlist_item_t *item, ssize_t index_hint)
 Go to a given item. More...
 
VLC_EXPORT vlc_player_tvlc_playlist_GetPlayer (vlc_playlist_t *playlist)
 Return the player owned by the playlist. More...
 
VLC_EXPORT int vlc_playlist_Start (vlc_playlist_t *playlist)
 Start the player. More...
 
VLC_EXPORT void vlc_playlist_Stop (vlc_playlist_t *playlist)
 Stop the player. More...
 
VLC_EXPORT void vlc_playlist_Pause (vlc_playlist_t *playlist)
 Pause the player. More...
 
VLC_EXPORT 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...
 
VLC_EXPORT 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...
 
VLC_EXPORT 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:

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

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

◆ vlc_playlist_listener_id

◆ vlc_playlist_t

typedef struct vlc_playlist vlc_playlist_t

Enumeration Type Documentation

◆ vlc_playlist_playback_order

Enumerator
VLC_PLAYLIST_PLAYBACK_ORDER_NORMAL 
VLC_PLAYLIST_PLAYBACK_ORDER_RANDOM 

◆ vlc_playlist_playback_repeat

Enumerator
VLC_PLAYLIST_PLAYBACK_REPEAT_NONE 
VLC_PLAYLIST_PLAYBACK_REPEAT_CURRENT 
VLC_PLAYLIST_PLAYBACK_REPEAT_ALL 

◆ 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_order

Enumerator
VLC_PLAYLIST_SORT_ORDER_ASCENDING 
VLC_PLAYLIST_SORT_ORDER_DESCENDING 

Function Documentation

◆ vlc_playlist_AddListener()

VLC_EXPORT 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
playlistthe playlist, locked
cbsthe callbacks (must be valid until the listener is removed)
userdatauserdata provided as a parameter in callbacks
notify_current_statetrue 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, vlc_playlist_view::playlist, 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
playlistthe playlist, locked
mediathe array of media to append
countthe 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
playlistthe playlist, locked
mediathe media to append
Returns
VLC_SUCCESS on success, another value on error

References vlc_playlist_Append().

Referenced by add_to_playlist().

◆ vlc_playlist_Clear()

VLC_EXPORT void vlc_playlist_Clear ( vlc_playlist_t playlist)

◆ vlc_playlist_Count()

VLC_EXPORT size_t vlc_playlist_Count ( vlc_playlist_t playlist)

◆ vlc_playlist_Delete()

VLC_EXPORT void vlc_playlist_Delete ( vlc_playlist_t )

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()

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

Export the playlist to a file.

Parameters
filenamethe location where the exported file will be saved
typethe type of the playlist file to create (m3u, m3u8, xspf, ...)
Returns
VLC_SUCCESS on success, another value on error

◆ vlc_playlist_Get()

VLC_EXPORT 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
playlistthe playlist, locked
indexthe 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()

VLC_EXPORT ssize_t vlc_playlist_GetCurrentIndex ( vlc_playlist_t playlist)

Return the index of the current item.

Parameters
playlistthe 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()

VLC_EXPORT enum vlc_playlist_playback_order vlc_playlist_GetPlaybackOrder ( vlc_playlist_t )

Return the playback order.

Parameters
playlistthe playlist, locked
Returns
the playback order

References vlc_playlist::order, and vlc_playlist_AssertLocked().

◆ vlc_playlist_GetPlaybackRepeat()

VLC_EXPORT enum vlc_playlist_playback_repeat vlc_playlist_GetPlaybackRepeat ( vlc_playlist_t playlist)

Return the playback "repeat" mode.

Parameters
playlistthe playlist, locked
Returns
the playback "repeat" mode

References vlc_playlist::repeat, and vlc_playlist_AssertLocked().

◆ vlc_playlist_GetPlayer()

VLC_EXPORT vlc_player_t* vlc_playlist_GetPlayer ( vlc_playlist_t playlist)

Return the player owned by the playlist.

Parameters
playlistthe playlist (not necessarily locked)
Returns
the player

References vlc_playlist::player.

Referenced by PlaylistConfigureFromVariables().

◆ vlc_playlist_GoTo()

VLC_EXPORT 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
playlistthe playlist, locked
indexthe 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()

VLC_EXPORT bool vlc_playlist_HasNext ( vlc_playlist_t playlist)

Indicate whether a next item is available.

Parameters
playlistthe playlist, locked
Return values
trueif a next item is available
falseif no next item is available

References vlc_playlist::has_next, and vlc_playlist_AssertLocked().

◆ vlc_playlist_HasPrev()

VLC_EXPORT bool vlc_playlist_HasPrev ( vlc_playlist_t playlist)

Indicate whether a previous item is available.

Parameters
playlistthe playlist, locked
Return values
trueif a previous item is available
falseif no previous item is available

References vlc_playlist::has_prev, and vlc_playlist_AssertLocked().

◆ vlc_playlist_IndexOf()

VLC_EXPORT ssize_t vlc_playlist_IndexOf ( vlc_playlist_t playlist,
const vlc_playlist_item_t item 
)

Return the index of a given item.

Parameters
playlistthe playlist, locked
itemthe 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()

VLC_EXPORT ssize_t vlc_playlist_IndexOfId ( vlc_playlist_t playlist,
uint64_t  id 
)

Return the index of a given item id.

Parameters
playlistthe playlist, locked
idthe 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()

VLC_EXPORT ssize_t vlc_playlist_IndexOfMedia ( vlc_playlist_t playlist,
const input_item_t media 
)

Return the index of a given media.

Parameters
playlistthe playlist, locked
mediathe 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()

VLC_EXPORT 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
playlistthe playlist, locked \index index the index where the media are to be inserted
mediathe array of media to insert
countthe 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
playlistthe playlist, locked \index index the index where the media is to be inserted
mediathe media to insert
Returns
VLC_SUCCESS on success, another value on error

References vlc_playlist_Insert().

Referenced by intf_InsertItem().

◆ vlc_playlist_item_GetId()

VLC_EXPORT uint64_t vlc_playlist_item_GetId ( vlc_playlist_item_t )

Return a unique id for the playlist item instance.

References vlc_playlist_item::id.

◆ vlc_playlist_item_GetMedia()

VLC_EXPORT input_item_t* vlc_playlist_item_GetMedia ( vlc_playlist_item_t )

Return the media associated to the playlist item.

References vlc_playlist_item::media.

◆ vlc_playlist_item_Hold()

VLC_EXPORT void vlc_playlist_item_Hold ( vlc_playlist_item_t )

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()

VLC_EXPORT void vlc_playlist_item_Release ( vlc_playlist_item_t )

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()

VLC_EXPORT void vlc_playlist_Lock ( vlc_playlist_t )

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()

VLC_EXPORT 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
playlistthe playlist, locked
indexthe index of the first item to move
countthe number of items to move
targetthe 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
playlistthe playlist, locked
indexthe index of the item to move
targetthe new index of the moved item

References vlc_playlist_Move().

◆ vlc_playlist_New()

VLC_EXPORT vlc_playlist_t* vlc_playlist_New ( vlc_object_t parent)

◆ vlc_playlist_Next()

VLC_EXPORT int vlc_playlist_Next ( vlc_playlist_t playlist)

◆ vlc_playlist_Pause()

VLC_EXPORT void vlc_playlist_Pause ( vlc_playlist_t playlist)

Pause the player.

Parameters
playlistthe playlist, locked
Returns
VLC_SUCCESS on success, another value on error

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
playlistthe playlist, locked
indexthe 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()

VLC_EXPORT 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
playlistthe playlist (not necessarily locked)
libvlcthe libvlc instance
mediathe media to preparse

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

Referenced by vlc_playlist_AutoPreparse().

◆ vlc_playlist_Prev()

VLC_EXPORT int vlc_playlist_Prev ( vlc_playlist_t playlist)

◆ vlc_playlist_Remove()

VLC_EXPORT 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
playlistthe playlist, locked
indexthe index of the first item to remove
countthe 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()

VLC_EXPORT void vlc_playlist_RemoveListener ( vlc_playlist_t ,
vlc_playlist_listener_id  
)

Remove a player listener.

Parameters
playlistthe playlist, locked
idthe listener identifier returned by vlc_playlist_AddListener()

References vlc_playlist_listener_id::node, vlc_playlist_view::playlist, 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
playlistthe playlist, locked
indexthe index of the item to remove

References vlc_playlist_Remove().

Referenced by vlc_playlist_Expand().

◆ vlc_playlist_RequestGoTo()

VLC_EXPORT 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
playlistthe playlist, locked
itemthe item to go to (NULL for none)
index_hintthe 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()

VLC_EXPORT 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
playlistthe playlist, locked \index index the index where the media are to be inserted
mediathe array of media to insert
countthe 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()

VLC_EXPORT 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
playlistthe playlist, locked
itemsthe array of items to move
countthe number of items to move
targetthe new index of the moved slice
index_hintthe 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()

VLC_EXPORT 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
playlistthe playlist, locked
itemsthe array of items to remove
countthe number of items to remove
index_hintthe 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()

VLC_EXPORT void vlc_playlist_Resume ( vlc_playlist_t playlist)

Resume the player.

Parameters
playlistthe playlist, locked
Returns
VLC_SUCCESS on success, another value on error

References vlc_playlist::player, and vlc_player_Resume().

◆ vlc_playlist_SetPlaybackOrder()

VLC_EXPORT void vlc_playlist_SetPlaybackOrder ( vlc_playlist_t playlist,
enum vlc_playlist_playback_order  order 
)

Change the playback order.

Parameters
playlistthe playlist, locked
repeatthe new playback order

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

Referenced by PlaylistConfigureFromVariables().

◆ vlc_playlist_SetPlaybackRepeat()

VLC_EXPORT void vlc_playlist_SetPlaybackRepeat ( vlc_playlist_t playlist,
enum vlc_playlist_playback_repeat  repeat 
)

Change the playback "repeat" mode.

Parameters
playlistthe playlist, locked
repeatthe new playback "repeat" mode

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

Referenced by PlaylistConfigureFromVariables().

◆ vlc_playlist_Shuffle()

VLC_EXPORT void vlc_playlist_Shuffle ( vlc_playlist_t playlist)

◆ vlc_playlist_Sort()

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

◆ vlc_playlist_Start()

VLC_EXPORT int vlc_playlist_Start ( vlc_playlist_t playlist)

Start the player.

Parameters
playlistthe 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()

VLC_EXPORT void vlc_playlist_Stop ( vlc_playlist_t playlist)

Stop the player.

Parameters
playlistthe playlist, locked
Returns
VLC_SUCCESS on success, another value on error

References vlc_playlist::player, and vlc_player_Stop().

◆ vlc_playlist_Unlock()

VLC_EXPORT void vlc_playlist_Unlock ( vlc_playlist_t )