Audio I/O Reference¶
The mlx_audio.audio_io module provides functions for reading and writing audio files. It uses miniaudio for WAV decoding/encoding and ffmpeg for MP3, FLAC, OGG, Opus, Vorbis, and M4A/AAC formats.
Reading Audio¶
mlx_audio.audio_io.read(file, always_2d=False, dtype='float64')
¶
Read an audio file using miniaudio (or ffmpeg for M4A/AAC/OGG/Opus/WebM).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
Union[str, Path, BytesIO]
|
Path to the audio file or a BytesIO object. |
required |
always_2d
|
bool
|
If True, always return a 2D array (samples, channels). |
False
|
dtype
|
str
|
Data type for the output array. Supports 'float32', 'float64', 'int16'. |
'float64'
|
Returns:
| Type | Description |
|---|---|
ndarray
|
Tuple of (audio_data, sample_rate). |
int
|
audio_data is a numpy array with shape (samples,) for mono or (samples, channels) for multi-channel. |
Writing Audio¶
mlx_audio.audio_io.write(file, data, samplerate, format=None)
¶
Write audio data to a file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
Union[str, Path, BytesIO]
|
Path to the output file or a BytesIO object. |
required |
data
|
ndarray
|
Audio data as numpy array. Shape can be (samples,) for mono or (samples, channels) for multi-channel. |
required |
samplerate
|
int
|
Sample rate in Hz. |
required |
format
|
Optional[str]
|
Output format. Supports 'wav', 'flac', 'mp3', 'ogg', 'opus', 'vorbis', 'webm'. If None, inferred from file extension. |
None
|
Note
WAV uses miniaudio for encoding. MP3, FLAC, OGG, Opus, Vorbis, and WebM use ffmpeg (must be installed: brew install ffmpeg).
Soundfile-Compatible Aliases¶
Drop-in replacements for soundfile.read() and soundfile.write():
mlx_audio.audio_io.sf_read(file, always_2d=False)
¶
Read audio file (soundfile-compatible API).
This is a drop-in replacement for soundfile.read().
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
Union[str, Path, BytesIO]
|
Path to audio file or BytesIO object. |
required |
always_2d
|
bool
|
If True, always return 2D array. |
False
|
Returns:
| Type | Description |
|---|---|
Tuple[ndarray, int]
|
Tuple of (data, samplerate). |
mlx_audio.audio_io.sf_write(file, data, samplerate, format=None)
¶
Write audio file (soundfile-compatible API).
This is a drop-in replacement for soundfile.write().
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
Union[str, Path, BytesIO]
|
Path to output file or BytesIO object. |
required |
data
|
ndarray
|
Audio data as numpy array. |
required |
samplerate
|
int
|
Sample rate in Hz. |
required |
format
|
Optional[str]
|
Output format (wav, flac, mp3). |
None
|
Supported Formats¶
Reading¶
| Format | Backend | Notes |
|---|---|---|
| WAV | miniaudio | No external dependencies |
| MP3 | miniaudio | No external dependencies |
| FLAC | miniaudio | No external dependencies |
| Vorbis / OGG | ffmpeg | Requires ffmpeg |
| M4A / AAC | ffmpeg | Requires ffmpeg |
| Opus | ffmpeg | Requires ffmpeg |
Writing¶
| Format | Backend | Notes |
|---|---|---|
| WAV | miniaudio | No external dependencies |
| MP3 | ffmpeg | Requires ffmpeg |
| FLAC | ffmpeg | Requires ffmpeg |
| OGG | ffmpeg | Uses FLAC codec in OGG container |
| Opus | ffmpeg | Requires ffmpeg |
| PCM / Raw | native | Raw int16 bytes |
Installing ffmpeg¶
ffmpeg is required for non-WAV encoding and for M4A/AAC/OGG decoding:
Note
WAV format works without ffmpeg. If you only need WAV, no extra installation is required.