playlist.h File Reference

Play order and navigation over the Storage service index: what to play next. More...

#include "esp_err.h"
#include <stddef.h>
#include <stdbool.h>

Go to the source code of this file.

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

Play order and navigation over the Storage service index: what to play next.

A thin state layer above the storage track index (current position + repeat/shuffle mode). It never touches the SD card, the decoder or a sink: it consumes the storage list BY INDEX and answers "which track now / next / previous" as a storage index plus a POSIX path ready for decoder_open(). The transport/player drives it; the dependency direction is player -> playlist -> storage.

It does NOT own the SD mount: every read/navigation call fails loud with ESP_ERR_INVALID_STATE when storage is not ready, and ESP_ERR_NOT_FOUND on an empty list, rather than ever exposing a silently invalid current index.

State is static and minimal (one position, two mode flags, one permutation table); no allocation happens per call. Call playlist_sync once after storage_init/storage_rescan to (re)bind to the current index before navigating.

Note

Développé avec l'assistance de Claude Opus 4.8 (Anthropic), sous la direction de Y. Dos Santos : spécification, revue et validation sur cible par l'auteur.