Audio playback

Speaker (audio output) driver interface. More...

Modules
	DA7212 on nRF5
	Audio playback implementation for a DA7212 codec fed by the nRF5 I2S peripheral.
	QEMU audio
	Audio playback implementation for the QEMU audio device.
	SF32LB52 audio
	Audio playback implementation for the SF32LB52 audio codec (AUDCODEC) DAC.

Data Structures
struct	BoardPowerOps
	Optional board-level power hooks. More...

Macros
#define	AUDIO_PLAYBACK_SAMPLE_RATE   (16000)
	PCM sample rate, in Hz, and rate of the clock seen by AudioPlaybackCB.

Typedefs
typedef const struct AudioDevice	AudioDevice
	Audio output device, defined by the driver implementation.
typedef void(*	AudioTransCB) (uint32_t *free_size)
	Request for more audio data.
typedef void(*	AudioPlaybackCB) (const int16_t *samples, size_t count, uint32_t sample_time, void *context)
	Observer of the mono PCM committed to DMA, including underrun silence.

Functions
bool	audio_set_playback_callback (AudioDevice *audio_device, AudioPlaybackCB cb, void *context)
	Register or unregister the playback observer.
void	audio_init (AudioDevice *audio_device)
	Initialize the audio device.
void	audio_start (AudioDevice *audio_device, AudioTransCB cb)
	Start playback.
uint32_t	audio_write (AudioDevice *audio_device, void *writeBuf, uint32_t size)
	Queue PCM data for playback.
void	audio_set_volume (AudioDevice *audio_device, int volume)
	Set the playback volume.
void	audio_stop (AudioDevice *audio_device)
	Stop playback.

Detailed Description

Speaker (audio output) driver interface.

The driver plays 16-bit mono PCM queued with audio_write(). Once started, it asks for more data through the AudioTransCB passed to audio_start() whenever queue space frees up. The per-implementation AudioDevice definitions live in the speaker driver groups.

static void prv_refill(uint32_t *free_size) {
  size_t len = MIN(*free_size, sizeof(s_pcm));
  generate_pcm(s_pcm, len);
  audio_write(AUDIO, s_pcm, len);
}
 
audio_init(AUDIO);
audio_set_volume(AUDIO, 80);
audio_start(AUDIO, prv_refill);
...
audio_stop(AUDIO);

Macro Definition Documentation

AUDIO_PLAYBACK_SAMPLE_RATE

#define AUDIO_PLAYBACK_SAMPLE_RATE   (16000)

PCM sample rate, in Hz, and rate of the clock seen by AudioPlaybackCB.

Typedef Documentation

AudioDevice

typedef const struct AudioDevice AudioDevice

Audio output device, defined by the driver implementation.

AudioPlaybackCB

typedef void(* AudioPlaybackCB) (const int16_t *samples, size_t count, uint32_t sample_time, void *context)

Observer of the mono PCM committed to DMA, including underrun silence.

Runs in the DMA ISR: copy the samples immediately, never block or keep the pointer.

Parameters

samples	Samples committed to DMA.
count	Number of samples.
sample_time	Presentation time of the first sample, on a wrapping AUDIO_PLAYBACK_SAMPLE_RATE clock derived from uptime and re-anchored whenever it drifts more than 8 ms from it.
context	User context given to audio_set_playback_callback().

AudioTransCB

typedef void(* AudioTransCB) (uint32_t *free_size)

Request for more audio data.

Invoked on the system task; the consumer may call audio_write() synchronously from it.

Parameters

[in,out]

free_size

Free queue space in bytes.

Function Documentation

audio_init()

void audio_init ( AudioDevice *  audio_device )

extern

Initialize the audio device.

Parameters

audio_device

Audio device.

audio_set_playback_callback()

bool audio_set_playback_callback	(	AudioDevice *	audio_device,
		AudioPlaybackCB	cb,
		void *	context
	)

Register or unregister the playback observer.

Provided by drivers that select SPEAKER_PLAYBACK_OBSERVER.

Parameters

audio_device	Audio device.
cb	Observer, or NULL to unregister synchronously.
context	User context passed to cb.

Returns

False if the device format (sample rate, channels) cannot be observed.

audio_set_volume()

void audio_set_volume ( AudioDevice *  audio_device, int  volume  )

extern

Set the playback volume.

Parameters

audio_device	Audio device.
volume	Volume from 0 to 100.

audio_start()

void audio_start ( AudioDevice *  audio_device, AudioTransCB  cb  )

extern

Start playback.

Parameters

audio_device	Audio device.
cb	Called whenever the device wants more data.

audio_stop()

void audio_stop ( AudioDevice *  audio_device )

extern

Stop playback.

Parameters

audio_device

Audio device.

audio_write()

uint32_t audio_write ( AudioDevice *  audio_device, void *  writeBuf, uint32_t  size  )

extern

Queue PCM data for playback.

Data that does not fit in the queue is dropped.

Parameters

audio_device	Audio device.
writeBuf	16-bit PCM samples.
size	Size of writeBuf in bytes; 0 only queries the free space.

Returns

Free queue space in bytes after the write.