esphome::audio Namespace Reference

Data Structures
class	AudioDecoder
struct	AudioFile
class	AudioReadableBuffer
	Abstract interface for reading audio data from a buffer. More...
class	AudioReader
class	AudioResampler
class	AudioSinkCallback
	Abstract interface for writing decoded audio data to a sink. More...
class	AudioSinkTransferBuffer
class	AudioSourceTransferBuffer
class	AudioStreamInfo
class	AudioTransferBuffer
class	ConstAudioSourceBuffer
	A lightweight read-only audio buffer for const data sources (e.g., flash memory). More...
class	RingBufferAudioSource
	Zero-copy audio source that reads directly from a ring buffer's internal storage. More...

Enumerations
enum class	AudioFileType : uint8_t {   NONE = 0 , FLAC , MP3 , OPUS ,   WAV }
enum class	AudioDecoderState : uint8_t { DECODING = 0 , FINISHED , FAILED }
enum class	FileDecoderState : uint8_t {   MORE_TO_PROCESS , IDLE , POTENTIALLY_FAILED , FAILED ,   END_OF_FILE }
enum	HttpStatus {   HTTP_STATUS_OK = 200 , HTTP_STATUS_NO_CONTENT = 204 , HTTP_STATUS_PARTIAL_CONTENT = 206 , HTTP_STATUS_MULTIPLE_CHOICES = 300 ,   HTTP_STATUS_MOVED_PERMANENTLY = 301 , HTTP_STATUS_FOUND = 302 , HTTP_STATUS_SEE_OTHER = 303 , HTTP_STATUS_NOT_MODIFIED = 304 ,   HTTP_STATUS_TEMPORARY_REDIRECT = 307 , HTTP_STATUS_PERMANENT_REDIRECT = 308 , HTTP_STATUS_BAD_REQUEST = 400 , HTTP_STATUS_UNAUTHORIZED = 401 ,   HTTP_STATUS_FORBIDDEN = 403 , HTTP_STATUS_NOT_FOUND = 404 , HTTP_STATUS_METHOD_NOT_ALLOWED = 405 , HTTP_STATUS_NOT_ACCEPTABLE = 406 ,   HTTP_STATUS_LENGTH_REQUIRED = 411 , HTTP_STATUS_INTERNAL_ERROR = 500 }
enum class	AudioReaderState : uint8_t { READING = 0 , FINISHED , FAILED }
enum class	AudioResamplerState : uint8_t { RESAMPLING , FINISHED , FAILED }

Functions
const char *	audio_file_type_to_string (AudioFileType file_type)
	Helper function to convert file type to a const char string.
AudioFileType	detect_audio_file_type (const char *content_type, const char *url)
	Detect audio file type from a Content-Type header value and/or URL extension.
void	scale_audio_samples (const int16_t *audio_samples, int16_t *output_buffer, int16_t scale_factor, size_t samples_to_scale)
	ESPDEPRECATED ("Use esp_audio_libs::gain::apply() (from <gain.h>) instead. Removed in 2026.12.0.", "2026.6.0") void scale_audio_samples(const int16_t *audio_samples
	Scales Q15 fixed point audio samples.
int32_t	unpack_audio_sample_to_q31 (const uint8_t *data, size_t bytes_per_sample)
	Unpacks a quantized audio sample into a Q31 fixed-point number.
void	pack_q31_as_audio_sample (int32_t sample, uint8_t *data, size_t bytes_per_sample)
	Packs a Q31 fixed-point number as an audio sample with the specified number of bytes per sample.

Variables
int16_t *	output_buffer
int16_t int16_t	scale_factor
int16_t int16_t size_t	samples_to_scale

Enumeration Type Documentation

AudioDecoderState

enum class esphome::audio::AudioDecoderState : uint8_t

strong

Enumerator
DECODING
FINISHED
FAILED

Definition at line 40 of file audio_decoder.h.

AudioFileType

enum class esphome::audio::AudioFileType : uint8_t

strong

Enumerator
NONE
FLAC
MP3
OPUS
WAV

Definition at line 108 of file audio.h.

AudioReaderState

enum class esphome::audio::AudioReaderState : uint8_t

strong

Enumerator
READING
FINISHED
FAILED

Definition at line 16 of file audio_reader.h.

AudioResamplerState

enum class esphome::audio::AudioResamplerState : uint8_t

strong

Enumerator
RESAMPLING
FINISHED
FAILED

Definition at line 22 of file audio_resampler.h.

FileDecoderState

enum class esphome::audio::FileDecoderState : uint8_t

strong

Enumerator
MORE_TO_PROCESS
IDLE
POTENTIALLY_FAILED
FAILED
END_OF_FILE

Definition at line 47 of file audio_decoder.h.

HttpStatus

enum esphome::audio::HttpStatus

Enumerator
HTTP_STATUS_OK
HTTP_STATUS_NO_CONTENT
HTTP_STATUS_PARTIAL_CONTENT
HTTP_STATUS_MULTIPLE_CHOICES
HTTP_STATUS_MOVED_PERMANENTLY
HTTP_STATUS_FOUND
HTTP_STATUS_SEE_OTHER
HTTP_STATUS_NOT_MODIFIED
HTTP_STATUS_TEMPORARY_REDIRECT
HTTP_STATUS_PERMANENT_REDIRECT
HTTP_STATUS_BAD_REQUEST
HTTP_STATUS_UNAUTHORIZED
HTTP_STATUS_FORBIDDEN
HTTP_STATUS_NOT_FOUND
HTTP_STATUS_METHOD_NOT_ALLOWED
HTTP_STATUS_NOT_ACCEPTABLE
HTTP_STATUS_LENGTH_REQUIRED
HTTP_STATUS_INTERNAL_ERROR

Definition at line 28 of file audio_reader.cpp.

Function Documentation

audio_file_type_to_string()

const char * esphome::audio::audio_file_type_to_string

(

AudioFileType

file_type

)

Helper function to convert file type to a const char string.

Parameters

file_type

Returns

const char pointer to the readable file type

Definition at line 43 of file audio.cpp.

detect_audio_file_type()

AudioFileType esphome::audio::detect_audio_file_type	(	const char *	content_type,
		const char *	url )

Detect audio file type from a Content-Type header value and/or URL extension.

Tries Content-Type first, then falls back to URL extension. Either parameter may be null.

Parameters

content_type	Content-Type header value (may be null or empty)
url	URL to inspect for file extension (may be null or empty)

Returns

The detected AudioFileType, or NONE if unknown

Definition at line 66 of file audio.cpp.

ESPDEPRECATED()

esphome::audio::ESPDEPRECATED	(	"Use esp_audio_libs::gain::apply() (from <gain.h>) instead. Removed in 2026.12.0."	,
		"2026.6.0"	) const

Scales Q15 fixed point audio samples.

Scales in place if audio_samples == output_buffer.

Parameters

audio_samples	PCM int16 audio samples
output_buffer	Buffer to store the scaled samples
scale_factor	Q15 fixed point scaling factor
samples_to_scale	Number of samples to scale

pack_q31_as_audio_sample()

void esphome::audio::pack_q31_as_audio_sample ( int32_t sample, uint8_t * data, size_t bytes_per_sample )

inline

Packs a Q31 fixed-point number as an audio sample with the specified number of bytes per sample.

Packs the most significant bits - no dithering is applied.

Parameters

sample	Q31 fixed-point number to pack
data	Pointer to data array to store
bytes_per_sample	The audio data's bytes per sample

Definition at line 182 of file audio.h.

scale_audio_samples()

void esphome::audio::scale_audio_samples	(	const int16_t *	audio_samples,
		int16_t *	output_buffer,
		int16_t	scale_factor,
		size_t	samples_to_scale )

Definition at line 122 of file audio.cpp.

unpack_audio_sample_to_q31()

int32_t esphome::audio::unpack_audio_sample_to_q31 ( const uint8_t * data, size_t bytes_per_sample )

inline

Unpacks a quantized audio sample into a Q31 fixed-point number.

Parameters

data	Pointer to uint8_t array containing the audio sample
bytes_per_sample	The number of bytes per sample

Returns

Q31 sample

Definition at line 156 of file audio.h.

Variable Documentation

output_buffer

int16_t* esphome::audio::output_buffer

Definition at line 149 of file audio.h.

samples_to_scale

int16_t int16_t size_t esphome::audio::samples_to_scale

Definition at line 150 of file audio.h.

scale_factor

int16_t int16_t esphome::audio::scale_factor

Definition at line 149 of file audio.h.