Audio decoder

Decode an MP3 or WAV file into PCM for an Audio sink interface. More...

Collaboration diagram for Audio decoder:

Files
file	components/services/audio/mp3_frame.c
	MPEG Layer III header + Xing/Info/VBRI parsing (see mp3_frame.h).
file	components/services/audio/mp3_frame.h
	Internal MPEG-1/2 Layer III header + VBR-tag (Xing/Info/VBRI) parsing.

Data Structures
struct	decoder_format_t
	PCM format of the open stream, read once after decoder_open(). More...

Macros
#define	DECODER_READ_BUF_BYTES   (2304 * 4)
	Largest number of PCM bytes a single decoder_read() can emit.

Functions
esp_err_t	decoder_open (const char *path)
	Open an audio file, pick the backend, and read its format.
esp_err_t	decoder_format (decoder_format_t *fmt)
	Get the PCM format of the open stream.
esp_err_t	decoder_read (void *pcm, size_t cap_bytes, size_t *got_bytes)
	Decode the next chunk of audio into pcm.
esp_err_t	decoder_close (void)
	Close the stream and free the decoder. Safe to call when nothing is open.

Detailed Description

Decode an MP3 or WAV file into PCM for an Audio sink interface.

Macro Definition Documentation

DECODER_READ_BUF_BYTES

#define DECODER_READ_BUF_BYTES   (2304 * 4)

Largest number of PCM bytes a single decoder_read() can emit.

One MP3 frame is at most 1152 samples/channel; up-mixed to stereo that is 2304 samples, each emitted as a 4-byte 32-bit word. The pcm buffer passed to decoder_read() must be at least this big.

Function Documentation

decoder_close()

esp_err_t decoder_close

(

void

)

Close the stream and free the decoder. Safe to call when nothing is open.

Returns

ESP_OK.

decoder_format()

esp_err_t decoder_format

(

decoder_format_t *

fmt

)

Get the PCM format of the open stream.

Parameters

fmt	Filled with the stream format. Valid only between open and close.

Returns

ESP_OK; ESP_ERR_INVALID_STATE if no stream is open.

decoder_open()

esp_err_t decoder_open

(

const char *

path

)

Open an audio file, pick the backend, and read its format.

Detection is by file extension (.mp3 / .wav, case-insensitive), confirmed against the file's magic bytes (ID3/0xFFEx for MP3, RIFF/WAVE for WAV).

Parameters

path	POSIX path under the SD mount, e.g. "/sdcard/track.mp3".

Returns

ESP_OK; ESP_ERR_INVALID_STATE if a stream is already open; ESP_ERR_NOT_FOUND if the file cannot be opened; ESP_ERR_NOT_SUPPORTED if the format is unrecognised; ESP_FAIL on decode error.

decoder_read()

esp_err_t decoder_read	(	void *	pcm,
		size_t	cap_bytes,
		size_t *	got_bytes )

Decode the next chunk of audio into pcm.

Parameters

pcm	Output buffer; must be at least DECODER_READ_BUF_BYTES.
cap_bytes	Capacity of pcm in bytes.
got_bytes	Receives the number of bytes written; 0 means end of file.

Returns

ESP_OK; ESP_ERR_INVALID_STATE if no stream is open; ESP_ERR_INVALID_SIZE if cap_bytes is below DECODER_READ_BUF_BYTES; ESP_FAIL on decode error.