Playback transport

play/pause/resume/stop/next/prev over the playlist, with auto-advance on EOF. More...

Collaboration diagram for Playback transport:

Files
file	components/services/audio/player.c
	Playback transport state machine over the playlist and pipeline.

Data Structures
struct	player_status_t
	Snapshot of the transport for the UI. More...

Enumerations
enum	player_state_t { PLAYER_STOPPED , PLAYER_PLAYING , PLAYER_PAUSED }
	Transport state. More...

Functions
esp_err_t	player_init (void)
	Register the player with the pipeline's end-of-track callback. Call once at startup.
esp_err_t	player_set_output (volume_output_t out)
	Select the output and keep the volume routing consistent.
void	player_poll (void)
	Complete a deferred Bluetooth start once the speaker acknowledges the volume.
esp_err_t	player_play (size_t index)
	Play the storage track at index (stops any current stream first).
esp_err_t	player_start (void)
	Start playback from the stopped state (e.g. first play after boot).
esp_err_t	player_pause (void)
	Pause the current playback (sink down, position kept).
esp_err_t	player_resume (void)
	Resume a paused playback.
esp_err_t	player_stop (void)
	Stop playback and power the output down.
esp_err_t	player_next (void)
	Skip to the next track (respecting the playlist's repeat/shuffle order).
esp_err_t	player_prev (void)
	Step to the previous track. Mirror of player_next.
esp_err_t	player_get_state (player_status_t *out)
	Read the current transport state and track.
void	player_save_resume (void)
	Persist the current track (path + position) so Now Playing re-selects it after boot.

Detailed Description

play/pause/resume/stop/next/prev over the playlist, with auto-advance on EOF.

Enumeration Type Documentation

player_state_t

enum player_state_t

Transport state.

Enumerator
PLAYER_STOPPED	Nothing playing.
PLAYER_PLAYING	A track is streaming to the active output.
PLAYER_PAUSED	Playback suspended; the sink is down, the stream position kept.

Function Documentation

player_get_state()

esp_err_t player_get_state

(

player_status_t *

out

)

Read the current transport state and track.

Parameters

[out]

out

Filled with the snapshot. Must not be NULL.

Returns

ESP_OK; ESP_ERR_INVALID_ARG if out is NULL.

player_init()

esp_err_t player_init

(

void

)

Register the player with the pipeline's end-of-track callback. Call once at startup.

Returns

ESP_OK.

player_next()

esp_err_t player_next

(

void

)

Skip to the next track (respecting the playlist's repeat/shuffle order).

Returns

ESP_OK; ESP_ERR_INVALID_STATE if stopped; ESP_ERR_NOT_FOUND at the end of the list with repeat off (playback stops); otherwise the pipeline/playlist error.

player_pause()

esp_err_t player_pause

(

void

)

Pause the current playback (sink down, position kept).

Returns

ESP_OK; ESP_ERR_INVALID_STATE if not currently playing.

player_play()

esp_err_t player_play

(

size_t

index

)

Play the storage track at index (stops any current stream first).

If the output is Bluetooth and the speaker has not yet acknowledged the volume, the stream is deferred (never blast) and ESP_OK is returned; player_poll() starts it on the ack.

Parameters

index

0-based storage index (as listed by the UI browser).

Returns

ESP_OK; ESP_ERR_INVALID_STATE if storage is not ready; ESP_ERR_INVALID_ARG if index is out of range; otherwise the pipeline error.

player_poll()

void player_poll

(

void

)

Complete a deferred Bluetooth start once the speaker acknowledges the volume.

Call periodically from the maintenance loop (after volume_poll()). A switch/play to a Bluetooth speaker holds the stream until the volume is acknowledged (never blast); this drives that held start to completion. A no-op when nothing is pending.

player_prev()

esp_err_t player_prev

(

void

)

Step to the previous track. Mirror of player_next.

Returns

As player_next.

player_resume()

esp_err_t player_resume

(

void

)

Resume a paused playback.

Returns

ESP_OK; ESP_ERR_INVALID_STATE if not currently paused.

player_save_resume()

void player_save_resume

(

void

)

Persist the current track (path + position) so Now Playing re-selects it after boot.

Call before any power-off. Writes "last_path"/"last_pos" to Settings service when a track is loaded (playing or paused); a no-op when stopped (the previous value is kept).

player_set_output()

esp_err_t player_set_output

(

volume_output_t

out

)

Select the output and keep the volume routing consistent.

Points the pipeline at the matching sink and tells the volume service where to send the pot. Selecting the output already in use is a no-op (playback is not disturbed). If a track is currently playing the live stream is re-routed onto the new sink immediately, continuing from its current position (the decoder stays open, no restart); otherwise the choice is just remembered for the next playback. This is the single switch point for both manual selection and a future automatic BT connect/disconnect switch.

Bluetooth is referenced only on this path, so a build without BT still links. Switching to VOLUME_OUT_BT primes the speaker's volume and, if a stream is live, holds it until the speaker acknowledges that volume before streaming (never blast) – the switch itself succeeds and player_poll() completes the deferred start. It is refused only when no speaker is connected. VOLUME_OUT_NONE is a valid software mute that cuts the active output.

Parameters

out	VOLUME_OUT_DAC (jack), VOLUME_OUT_BT (speaker), or VOLUME_OUT_NONE (mute).

Returns

ESP_OK; ESP_ERR_INVALID_STATE if out is Bluetooth and no speaker is connected; ESP_ERR_INVALID_ARG for any other value; otherwise the pipeline error if a live re-route fails.

player_start()

esp_err_t player_start

(

void

)

Start playback from the stopped state (e.g. first play after boot).

Plays the playlist's current track. When shuffle is on, the play order is re-shuffled first so a random track starts (see playlist_random). A no-op unless currently stopped. If the output is Bluetooth and the speaker has not yet acknowledged the volume, the stream is deferred (never blast) and ESP_OK is returned; player_poll() starts it on the ack.

Returns

ESP_OK; ESP_ERR_INVALID_STATE if not stopped or storage is not ready; otherwise the pipeline/playlist error.

player_stop()

esp_err_t player_stop

(

void

)

Stop playback and power the output down.

Returns

ESP_OK.