Current track + next/prev navigation over the storage index (no hardware). More...

Collaboration diagram for Playlist service:

Data Structures
struct	playlist_track_t
	The resolved current track, filled by the navigation/read calls. More...

Enumerations
enum	playlist_repeat_t { PLAYLIST_REPEAT_OFF = 0 , PLAYLIST_REPEAT_ALL , PLAYLIST_REPEAT_ONE }
	How the ends of the list and end-of-track behave. More...

Functions
esp_err_t	playlist_sync (void)
	(Re)bind the playlist to the current storage index.
esp_err_t	playlist_current (playlist_track_t *out)
	Read the current track without changing the position.
esp_err_t	playlist_next (playlist_track_t *out)
	Advance to the next track and return it.
esp_err_t	playlist_prev (playlist_track_t *out)
	Step to the previous track and return it. Mirror of playlist_next.
esp_err_t	playlist_select (size_t index, playlist_track_t *out)
	Jump to a specific storage track and make it current.
esp_err_t	playlist_random (playlist_track_t *out)
	Re-shuffle the play order and restart at its first track.
void	playlist_set_repeat (playlist_repeat_t mode)
	Set the repeat mode. Default PLAYLIST_REPEAT_ALL.
playlist_repeat_t	playlist_get_repeat (void)
	Current repeat mode (for the UI and the transport's end-of-track policy).
void	playlist_set_shuffle (bool on)
	Turn shuffle on or off. Default off.
bool	playlist_get_shuffle (void)
	Whether shuffle is on.
size_t	playlist_queue_len (void)
	Number of tracks from the current one onward (current + upcoming); 0 if empty/not ready.
esp_err_t	playlist_queue_at (size_t row, playlist_track_t *out)
	Read the queue entry at `row` (0 = current track) without changing the position.
esp_err_t	playlist_queue_move_up (size_t row)
	Move the upcoming track at `row` one step earlier in the queue.
esp_err_t	playlist_queue_move_down (size_t row)
	Move the upcoming track at `row` one step later in the queue.
esp_err_t	playlist_queue_remove (size_t row)
	Remove the upcoming track at `row` from the play order for this session.

Detailed Description

Current track + next/prev navigation over the storage index (no hardware).

Enumeration Type Documentation

◆ playlist_repeat_t

enum playlist_repeat_t

How the ends of the list and end-of-track behave.

Enumerator
PLAYLIST_REPEAT_OFF	No wrap: next past the last (or prev before the first) is end-of-list.
PLAYLIST_REPEAT_ALL	Wrap: last->first and first->last on next/prev.
PLAYLIST_REPEAT_ONE	Same wrap as ALL for navigation; the transport reads this to replay the current track on natural end.

Function Documentation

◆ playlist_current()

esp_err_t playlist_current ( playlist_track_t * out )

Read the current track without changing the position.

Parameters

[out] out Filled with the current track; may be NULL to query state only.

Returns: ESP_OK; ESP_ERR_INVALID_STATE if storage is not ready; ESP_ERR_NOT_FOUND if empty.

◆ playlist_get_repeat()

playlist_repeat_t playlist_get_repeat ( void )

Current repeat mode (for the UI and the transport's end-of-track policy).

◆ playlist_get_shuffle()

bool playlist_get_shuffle ( void )

Whether shuffle is on.

◆ playlist_next()

esp_err_t playlist_next ( playlist_track_t * out )

Advance to the next track and return it.

Wraps to the first track when repeat is ALL/ONE; with repeat OFF, advancing past the last track leaves the position unchanged and returns ESP_ERR_NOT_FOUND (end of list).

Parameters

[out] out Filled with the new current track; may be NULL.

Returns: ESP_OK; ESP_ERR_INVALID_STATE if storage is not ready; ESP_ERR_NOT_FOUND if empty or at the end with repeat OFF.

◆ playlist_prev()

esp_err_t playlist_prev ( playlist_track_t * out )

Step to the previous track and return it. Mirror of playlist_next.

Parameters

[out] out Filled with the new current track; may be NULL.

Returns: ESP_OK; ESP_ERR_INVALID_STATE if storage is not ready; ESP_ERR_NOT_FOUND if empty or at the start with repeat OFF.

◆ playlist_queue_at()

esp_err_t playlist_queue_at	(	size_t	row,
		playlist_track_t *	out )

Read the queue entry at row (0 = current track) without changing the position.

Parameters

	row	0-based offset from the current track.
[out]	out	Filled with the track; must not be NULL.

Returns: ESP_OK; ESP_ERR_INVALID_STATE if storage is not ready; ESP_ERR_NOT_FOUND if row is past the end.

◆ playlist_queue_len()

size_t playlist_queue_len ( void )

Number of tracks from the current one onward (current + upcoming); 0 if empty/not ready.

◆ playlist_queue_move_down()

esp_err_t playlist_queue_move_down ( size_t row )

Move the upcoming track at row one step later in the queue.

Parameters

row	Queue row to move (>= 1, and not the last row).

Returns: ESP_OK; ESP_ERR_INVALID_STATE if storage is not ready; ESP_ERR_INVALID_ARG if row is the current track, the last row, or out of range.

◆ playlist_queue_move_up()

esp_err_t playlist_queue_move_up ( size_t row )

Move the upcoming track at row one step earlier in the queue.

Only upcoming tracks move, and never above the current track: row must be >= 2.

Parameters

row	Queue row to move (>= 2).

Returns: ESP_OK; ESP_ERR_INVALID_STATE if storage is not ready; ESP_ERR_INVALID_ARG if row is the current track, the first upcoming track, or out of range.

◆ playlist_queue_remove()

esp_err_t playlist_queue_remove ( size_t row )

Remove the upcoming track at row from the play order for this session.

Non-destructive: only the play order shrinks (the file stays on the card and reappears on the next playlist_sync()). The current track (row 0) cannot be removed.

Parameters

row	Queue row to remove (>= 1).

Returns: ESP_OK; ESP_ERR_INVALID_STATE if storage is not ready; ESP_ERR_INVALID_ARG if row is the current track or out of range.

◆ playlist_random()

esp_err_t playlist_random ( playlist_track_t * out )

Re-shuffle the play order and restart at its first track.

Unlike playlist_set_shuffle (which keeps the current track so playback is not interrupted), this draws a fresh permutation and moves the position to its head: the current track becomes random. Meant to start a shuffle session from the stopped state.

Parameters

[out] out Filled with the new current track; may be NULL.

Returns: ESP_OK; ESP_ERR_INVALID_STATE if storage is not ready; ESP_ERR_NOT_FOUND if empty.

◆ playlist_select()

esp_err_t playlist_select	(	size_t	index,
		playlist_track_t *	out )

Jump to a specific storage track and make it current.

Parameters

	index	0-based storage index (as listed by the storage service / UI browser).
[out]	out	Filled with the selected track; may be NULL.

Returns: ESP_OK; ESP_ERR_INVALID_STATE if storage is not ready; ESP_ERR_INVALID_ARG if index is out of range.

◆ playlist_set_repeat()

void playlist_set_repeat ( playlist_repeat_t mode )

Set the repeat mode. Default PLAYLIST_REPEAT_ALL.

Parameters

mode	The repeat mode.

◆ playlist_set_shuffle()

void playlist_set_shuffle ( bool on )

Turn shuffle on or off. Default off.

Rebuilds the play order while keeping the current track playing (it becomes the new order's starting point). Off restores ascending storage order. Takes effect immediately when storage is ready, otherwise on the next playlist_sync.

Parameters

on	true to shuffle, false for ascending order.

◆ playlist_sync()

esp_err_t playlist_sync ( void )

(Re)bind the playlist to the current storage index.

Call once after storage_init() and again after storage_rescan(). Rebuilds the play order for the current track count (identity, or a fresh shuffle when shuffle is on) and clamps the current position into range (if it fell past the new end it moves to the last track; an empty list leaves no current track). Requires storage to be ready.

Returns: ESP_OK; ESP_ERR_INVALID_STATE if storage is not ready.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ playlist_repeat_t

Function Documentation

◆ playlist_current()

◆ playlist_get_repeat()

◆ playlist_get_shuffle()

◆ playlist_next()

◆ playlist_prev()

◆ playlist_queue_at()

◆ playlist_queue_len()

◆ playlist_queue_move_down()

◆ playlist_queue_move_up()

◆ playlist_queue_remove()

◆ playlist_random()

◆ playlist_select()

◆ playlist_set_repeat()

◆ playlist_set_shuffle()

◆ playlist_sync()