AudioData

Represents audio data with format information.

Properties:

Property	Type	Description
header	Header	Audio metadata header
channels	int	Number of channels
sample_rate	int	Sample rate in Hz
coding_format	str	Encoding or container format, e.g., "pcm", "mp3"
sample_format	PcmSampleFormat	PCM sample format, see "Sensor and State Snapshot APIs / PcmSampleFormat"
bitrate	int	Bitrate in bit/s

Read-only properties:

Property	Type	Description
data	bytes	Raw audio binary data
format	str	Alias property for coding_format
bit_depth	int	Bit depth derived from sample_format, e.g., S16LE → 16
timestamp	float	Timestamp in seconds, equivalent to header.timestamp
duration	Duration	Audio duration; precisely calculated from byte length for PCM, estimated from bitrate for compressed formats

AudioData

Signature:

AudioData(
    data: bytes,
    header: Header,
    channels: int = 1,
    sample_rate: int = 16000,
    coding_format: str = "pcm",
    sample_format: PcmSampleFormat = "S16LE",
    bitrate: int = 0,
)

Description:

Constructs an AudioData instance.

Parameters:

Parameter	Type	Required	Description
data	bytes	Yes	Raw audio binary data
header	Header	Yes	Audio metadata header
channels	int	No	Number of channels
sample_rate	int	No	Sample rate in Hz
coding_format	str	No	Encoding or container format, e.g. "pcm", "mp3"
sample_format	PcmSampleFormat	No	PCM sample format; see "Sensor and State Snapshot APIs / PcmSampleFormat"
bitrate	int	No	Bit rate in bit/s; used to estimate duration for compressed formats

Returns:

AudioData instance.

Raises:

None.

save

Signature:

AudioData.save(path: str) -> None

Description:

Save audio to a file. The file extension must be .wav, .pcm, or .mp3, and the data must be PCM; saving as .mp3 also requires ffmpeg to be installed on the system.

Parameters:

Parameter	Type	Required	Description
path	str	Yes	Output file path; the save format is selected automatically based on the extension

Returns:

None.

Raises:

ValueError: Unsupported extension, or coding_format is not "pcm".

RuntimeError: ffmpeg not found or encoding failed when saving as .mp3.

with_data

Signature:

AudioData.with_data(data: bytes) -> AudioData

Description:

Copy the current object and replace the audio data; all other format fields retain their original values. Returns a new object; the original is unchanged. Commonly used for chunk-based splitting or streaming.

Parameters:

Parameter	Type	Required	Description
data	bytes	Yes	New raw audio binary data

Returns:

AudioData, the new audio object.

Raises:

None.

concat

Signature:

@classmethod
AudioData.concat(
    chunks: Iterable[AudioData],
    *,
    header: Header | None = None,
) -> AudioData

Description:

Merge multiple audio chunks with identical formats. All chunks must share the same sample_rate / channels / sample_format / coding_format.

Parameters:

Parameter	Type	Required	Description
chunks	Iterable[AudioData]	Yes	Sequence of audio chunks to merge; at least one required
header	Header | None	No	Metadata header for the merged audio; if omitted, the first chunk's header is used

Returns:

AudioData, the new merged object.

Raises:

ValueError: chunks is empty, or chunks have inconsistent formats.

to_numpy

Signature:

AudioData.to_numpy() -> np.ndarray

Description:

Convert to a floating-point array in the range [-1.0, 1.0]. Shape is (n_samples, channels) for multi-channel audio, or (n_samples,) for mono.

Parameters:

No parameters.

Returns:

np.ndarray, dtype=np.float32.

Raises:

ValueError: coding_format is not "pcm".