# audio-file
A simple library to read and write audio files on your disk.
The library can read many formats and can write only to wav files.
## Quick Start
### Read Audio
You can read most common audio formats. The default feature set enables all available codecs.
```rust
let audio = audio_file::read::<f32>("test_data/test_1ch.wav", audio_file::ReadConfig::default())?;
let sample_rate = audio.sample_rate;
let num_channels = audio.num_channels;
let samples = &audio.samples_interleaved;
```
With `audio-blocks`, you can read straight into an `AudioBlock`, which adds simple channel-based read helpers:
```rust
let (block, sample_rate) = audio_file::read_block::<f32>("test_data/test_1ch.wav", audio_file::ReadConfig::default())?;
```
### Write Audio
You can only write wav files. The `audio_file::write` function expects interleaved samples.
```rust
let samples = [0.0, 1.0, 0.0, 1.0, 0.0, 1.0]; // interleaved
let num_channels = 2;
let sample_rate = 48000;
audio_file::write(
"tmp.wav",
&samples,
num_channels,
sample_rate,
audio_file::WriteConfig::default(),
)?;
```
With the `audio-blocks` feature you can write any audio layout, e.g.:
```rust
let sample_rate = 48000;
let block = InterleavedView::from_slice(&[0.0, 1.0, 0.0, 1.0, 0.0, 1.0], 2);
audio_file::write_block("tmp.wav", block, sample_rate, audio_file::WriteConfig::default())?;
let block = SequentialView::from_slice(&[0.0, 0.0, 0.0, 1.0, 1.0, 1.0], 2);
audio_file::write_block("tmp.wav", block, sample_rate, audio_file::WriteConfig::default())?;
```
## Supported Input Codecs
Default features enable all codecs (including royalty-encumbered formats) via `all-codecs`.
To opt out, disable default features and enable only what you need.
| AAC | `aac` |
| ADPCM | `adpcm` |
| ALAC | `alac` |
| FLAC | `flac` |
| CAF | `caf` |
| ISO MP4 | `isomp4` |
| Matroska (MKV) | `mkv` |
| MP1 | `mp1` |
| MP2 | `mp2` |
| MP3 | `mp3` |
| Ogg | `ogg` |
| PCM | `pcm` |
| AIFF | `aiff` |
| Vorbis | `vorbis` |
| WAV | `wav` |
Feature flags:
- `all-codecs` enables all Symphonia codecs (this is the default).
- `audio-blocks` enables `read_block` and `write_block`.
- Individual codec flags (above) enable specific formats.
## Read and Write Options
### Reading
When reading a file you can specify the following things:
- Start and stop in frames or time
- Start channel and number of channels
- Optional resampling
The crate will try to decode and store only the parts that you selected.
### Writing
For writing audio you can select from the following sample formats:
| `Int8` | 8-bit integer |
| `Int16` | 16-bit integer (default) |
| `Int32` | 32-bit integer |
| `Float32` | 32-bit float |
`Int16` is the default, for broader compatibility.
### Some example configs:
- resample to 22.05 kHz while reading
```rust
let audio = audio_file::read::<f32>(
"test_data/test_1ch.wav",
audio_file::ReadConfig {
sample_rate: Some(22_050),
..Default::default()
},
)?;
```
- read the first 0.5 seconds
```rust
let audio = audio_file::read::<f32>(
"test_data/test_1ch.wav",
audio_file::ReadConfig {
stop: audio_file::Position::Time(Duration::from_secs_f32(0.5)),
..Default::default()
},
)?;
```
- read from frame 300 to 400
```rust
let audio = audio_file::read::<f32>(
"test_data/test_1ch.wav",
audio_file::ReadConfig {
start: audio_file::Position::Frame(300),
stop: audio_file::Position::Frame(400),
..Default::default()
},
)?;
```
- read only the first two channels
```rust
let audio = audio_file::read::<f32>(
"test_data/test_4ch.wav",
audio_file::ReadConfig {
num_channels: Some(2),
..Default::default()
},
)?;
```
- skip the first channel, reading channel 2 and 3
```rust
let audio = audio_file::read::<f32>(
"test_data/test_4ch.wav",
audio_file::ReadConfig {
start_channel: Some(1),
num_channels: Some(2),
..Default::default()
},
)?;
```
- write audio samples in `Float32`
```rust
audio_file::write(
"tmp.wav",
&samples_interleaved,
num_channels,
sample_rate,
audio_file::WriteConfig {
sample_format: audio_file::SampleFormat::Float32,
},
)?;
```