Audio data API
AudioData is available directly from speechflow and from speechflow.core.
It holds PCM samples and metadata for complete responses and streaming chunks.
Engine authors return finite float32 samples normalized to [-1, 1], normally
mono, with an explicit sample_rate in Hz.
The data array must be writable and independent of the engine's internal
buffers. Mono data has shape [samples]; multichannel data has shape
[samples, channels]. channels defaults to 1 and format to "pcm".
When engine.capabilities.sample_rate is None, each returned AudioData
still carries its actual sample rate.
AudioData is a plain container. It does not validate, normalize, or copy arrays
at construction time. The engine module is responsible for producing output that
meets these requirements. See the guide's example.
AudioData
dataclass
Lightweight container for PCM audio samples with metadata.
The data array holds float32 samples normalized to the range [-1, 1]
by convention. This range is enforced by engines that produce AudioData,
not by this class itself. AudioData performs no validation at construction
time — it is a plain data container.
Note: the format field name shadows the Python builtin format. This is
an accepted trade-off to keep the attribute name descriptive and consistent
with the broader codebase convention.