Class espos_audio::AudioDriver¶

ClassList > espos_audio > AudioDriver

Abstract mono audio-out and mic-in device: one interface, one implementation per board. More...

#include <espos_audio/audio_driver.h>

Inherited by the following classes: espos_audio::NullAudio

Classes¶

Type	Name
struct	MicLevels

Public Functions¶

Type	Name
virtual bool	begin_stream (uint32_t, uint8_t, uint8_t) Begin a stream at `rate` Hz /`bits` per sample /`channels` .
virtual bool	can_capture () const True if this board can capture (a mic is wired to the codec ADC and init brought it up).
virtual uint32_t	capture_rate () const Sample rate of record_pcm() buffers.
virtual void	end_stream () End the active stream: drain the codec so the last chunk doesn't loop on the DMA ring, then leave the codec open for the next stream/clip.
virtual void	init () = 0
virtual float	mic_gain_db () const
virtual void	play_cue (const int16_t * samples, size_t frames) Like play_pcm() , but for a clip that must NOT be silently dropped: the wake cue is the user's only feedback that the panel heard them, and it fires exactly when the pipeline is taking the mic, so the disposable-clip policy (drop on a busy codec) loses precisely the one sound that matters.
virtual void	play_pcm (const int16_t * samples, size_t frames) = 0 Enqueue `frames` signed-16-bit mono samples for playback.
virtual bool	probe_mic_channels (MicLevels &)
virtual bool	ready () const = 0 True once init() brought the codec up successfully.
virtual size_t	record_pcm (int16_t , size_t) Read up to* `max_frames` signed-16-bit mono samples into`out` , BLOCKING until that many are captured (or a codec error).
virtual size_t	record_pcm2 (int16_t , size_t) Read up to* `max_frames` 2-channel interleaved [MIC1,MIC2] int16 frames into`out` (so`out` holds`2 * max_frames` samples), BLOCKING until that many frames are captured (or a codec error).
virtual uint32_t	sample_rate () const = 0 Sample rate the driver expects play_pcm() buffers to be in.
virtual void	set_enabled (bool) Mute / unmute without tearing down the codec.
virtual void	set_mic_gain_db (float) Analog mic preamp gain in dB, applied on the next capture open.
virtual void	set_volume (uint8_t) Output volume 0-100. Applied at the codec. Default no-op.
virtual void	start_capture () Start / stop the ADC capture path.
virtual void	start_capture2 () Open / close the 2-channel capture handle.
virtual void	stop_capture ()
virtual void	stop_capture2 ()
virtual bool	supports_dual_mic () const True if this board exposes a 2-channel [MIC1,MIC2] capture path (start_capture2/record_pcm2/stop_capture2).
virtual size_t	write_stream (const int16_t , size_t) Write* `frames` signed-16-bit mono samples into the active stream.
virtual	~AudioDriver () = default

Detailed Description¶

The application supplies the driver (an ES8311 codec, an I2S DAC, whatever the board has); espOS components take it by pointer and never assume a particular codec.

play_pcm() is non-blocking by contract, so it is safe to call from a UI or render task. espos_voice uses this same interface for both TTS playback and mic capture.

Public Functions Documentation¶

function begin_stream¶

Begin a stream at rate Hz /bits per sample /channels .

inline virtual bool espos_audio::AudioDriver::begin_stream (
    uint32_t,
    uint8_t,
    uint8_t
)

The driver may reconfigure the codec to match rate. Returns false if the format can't be played (caller should abandon the stream).

function can_capture¶

True if this board can capture (a mic is wired to the codec ADC and init brought it up).

inline virtual bool espos_audio::AudioDriver::can_capture () const

record_pcm() no-ops on a capture-less board.

function capture_rate¶

Sample rate of record_pcm() buffers.

inline virtual uint32_t espos_audio::AudioDriver::capture_rate () const

16 kHz matches Whisper's native rate, so a Wyoming mic stream needs no resampling.

function end_stream¶

End the active stream: drain the codec so the last chunk doesn't loop on the DMA ring, then leave the codec open for the next stream/clip.

inline virtual void espos_audio::AudioDriver::end_stream ()

function init¶

virtual void espos_audio::AudioDriver::init () = 0

function mic_gain_db¶

inline virtual float espos_audio::AudioDriver::mic_gain_db () const

function play_cue¶

Like play_pcm() , but for a clip that must NOT be silently dropped: the wake cue is the user's only feedback that the panel heard them, and it fires exactly when the pipeline is taking the mic, so the disposable-clip policy (drop on a busy codec) loses precisely the one sound that matters.

inline virtual void espos_audio::AudioDriver::play_cue (
    const int16_t * samples,
    size_t frames
)

May block briefly to get the codec; still must not be called from a task that cannot tolerate that. Default: fall back to play_pcm().

function play_pcm¶

Enqueue frames signed-16-bit mono samples for playback.

virtual void espos_audio::AudioDriver::play_pcm (
    const int16_t * samples,
    size_t frames
) = 0

Copies the buffer and returns immediately; the samples play on the driver's audio task. Passing a null buffer or zero frames is a no-op. If the queue is full the buffer is dropped (a chime is disposable — never block the caller waiting for audio).

function probe_mic_channels¶

inline virtual bool espos_audio::AudioDriver::probe_mic_channels (
    MicLevels &
)

function ready¶

True once init() brought the codec up successfully.

virtual bool espos_audio::AudioDriver::ready () const = 0

False if the board has no audio or init failed (play_pcm then no-ops). Lets a status endpoint report audio health without racing the boot log.

function record_pcm¶

Read up to max_frames signed-16-bit mono samples intoout , BLOCKING until that many are captured (or a codec error).

inline virtual size_t espos_audio::AudioDriver::record_pcm (
    int16_t *,
    size_t
)

Returns the number of frames read (0 on error / no capture). Call in a loop from a dedicated task while streaming mic audio.

function record_pcm2¶

Read up to max_frames 2-channel interleaved [MIC1,MIC2] int16 frames intoout (soout holds2 * max_frames samples), BLOCKING until that many frames are captured (or a codec error).

inline virtual size_t espos_audio::AudioDriver::record_pcm2 (
    int16_t *,
    size_t
)

Returns the number of FRAMES read (0 on error / unsupported). start_capture2() must precede it.

function sample_rate¶

Sample rate the driver expects play_pcm() buffers to be in.

virtual uint32_t espos_audio::AudioDriver::sample_rate () const = 0

Callers synthesise / resample to this. 16 kHz is plenty for alert tones and speech.

function set_enabled¶

Mute / unmute without tearing down the codec.

inline virtual void espos_audio::AudioDriver::set_enabled (
    bool
)

When muted the power amplifier is held disabled so a quiet helm stays quiet. Default no-op.

function set_mic_gain_db¶

Analog mic preamp gain in dB, applied on the next capture open.

inline virtual void espos_audio::AudioDriver::set_mic_gain_db (
    float
)

Boards without a settable PGA ignore it. Exposed because the right value is an EMPIRICAL trade-off: too low and the wake detector gets nothing, too high and the preamp compresses/colours the audio until a wake model scores it the same as silence. Sweep it, listen, then pick.

function set_volume¶

Output volume 0-100. Applied at the codec. Default no-op.

inline virtual void espos_audio::AudioDriver::set_volume (
    uint8_t
)

function start_capture¶

Start / stop the ADC capture path.

inline virtual void espos_audio::AudioDriver::start_capture ()

start_capture() must be called before record_pcm(); stop_capture() releases the ADC when voice-in ends so idle draws no capture bandwidth. Idempotent. Default no-op.

function start_capture2¶

Open / close the 2-channel capture handle.

inline virtual void espos_audio::AudioDriver::start_capture2 ()

Same refcounted, idempotent contract as start_capture()/stop_capture(), on an independent handle. Default no-op.

function stop_capture¶

inline virtual void espos_audio::AudioDriver::stop_capture ()

function stop_capture2¶

inline virtual void espos_audio::AudioDriver::stop_capture2 ()

function supports_dual_mic¶

True if this board exposes a 2-channel [MIC1,MIC2] capture path (start_capture2/record_pcm2/stop_capture2).

inline virtual bool espos_audio::AudioDriver::supports_dual_mic () const

When false the wake engine stays on the single-mic mono feed. Default false.

function write_stream¶

Write frames signed-16-bit mono samples into the active stream.

inline virtual size_t espos_audio::AudioDriver::write_stream (
    const int16_t *,
    size_t
)

BLOCKS until the codec accepts them (this is the flow control that paces the sender). Returns frames written, 0 if no stream is active.

function ~AudioDriver¶

virtual espos_audio::AudioDriver::~AudioDriver () = default

The documentation for this class was generated from the following file espos_audio/include/espos_audio/audio_driver.h