audio_file/lib.rs
1//! # audio-file
2//!
3//! A simple library to read and write audio files on your disk.
4//!
5//! The library can read many formats and can write only to wav files.
6//!
7//! ## Quick Start
8//!
9//! ### Read Audio
10//!
11//! You can read most common audio formats. The default feature set enables all available codecs.
12//!
13//! ```rust
14//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
15//! let audio = audio_file::read::<f32>("test_data/test_1ch.wav", audio_file::ReadConfig::default())?;
16//! let sample_rate = audio.sample_rate;
17//! let num_channels = audio.num_channels;
18//! let samples = &audio.samples_interleaved;
19//! # Ok(())
20//! # }
21//! ```
22//!
23//! With `audio-blocks`, you can read straight into an `AudioBlock`, which adds simple channel-based read helpers:
24//!
25//! ```rust
26//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
27//! let (block, sample_rate) = audio_file::read_block::<f32>("test_data/test_1ch.wav", audio_file::ReadConfig::default())?;
28//! # Ok(())
29//! # }
30//! ```
31//!
32//! ### Write Audio
33//!
34//! You can only write wav files. The `audio_file::write` function expects interleaved samples.
35//!
36//! ```rust
37//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
38//! let samples = [0.0, 1.0, 0.0, 1.0, 0.0, 1.0]; // interleaved
39//! let num_channels = 2;
40//! let sample_rate = 48000;
41//! audio_file::write(
42//! "tmp.wav",
43//! &samples,
44//! num_channels,
45//! sample_rate,
46//! audio_file::WriteConfig::default(),
47//! )?;
48//! # Ok(())
49//! # }
50//! ```
51//!
52//! With the `audio-blocks` feature you can write any audio layout, e.g.:
53//!
54//! ```rust
55//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
56//! # use audio_file::*;
57//! let sample_rate = 48000;
58//!
59//! let block = InterleavedView::from_slice(&[0.0, 1.0, 0.0, 1.0, 0.0, 1.0], 2);
60//! audio_file::write_block("tmp.wav", block, sample_rate, audio_file::WriteConfig::default())?;
61//!
62//! let block = SequentialView::from_slice(&[0.0, 0.0, 0.0, 1.0, 1.0, 1.0], 2);
63//! audio_file::write_block("tmp.wav", block, sample_rate, audio_file::WriteConfig::default())?;
64//! # Ok(())
65//! # }
66//! ```
67//!
68//! ## Supported Input Codecs
69//!
70//! Default features enable all codecs (including royalty-encumbered formats) via `all-codecs`.
71//! To opt out, disable default features and enable only what you need.
72//!
73//! | Format | Feature Flag |
74//! |--------|--------------|
75//! | AAC | `aac` |
76//! | ADPCM | `adpcm` |
77//! | ALAC | `alac` |
78//! | FLAC | `flac` |
79//! | CAF | `caf` |
80//! | ISO MP4 | `isomp4` |
81//! | Matroska (MKV) | `mkv` |
82//! | MP1 | `mp1` |
83//! | MP2 | `mp2` |
84//! | MP3 | `mp3` |
85//! | Ogg | `ogg` |
86//! | PCM | `pcm` |
87//! | AIFF | `aiff` |
88//! | Vorbis | `vorbis` |
89//! | WAV | `wav` |
90//!
91//! Feature flags:
92//!
93//! - `all-codecs` enables all Symphonia codecs (this is the default).
94//! - `audio-blocks` enables `read_block` and `write_block`.
95//! - Individual codec flags (above) enable specific formats.
96//!
97//!
98//! ## Read and Write Options
99//!
100//! ### Reading
101//!
102//! When reading a file you can specify the following things:
103//!
104//! - Start and stop in frames or time
105//! - Start channel and number of channels
106//! - Optional resampling
107//!
108//! The crate will try to decode and store only the parts that you selected.
109//!
110//! ### Writing
111//!
112//! For writing audio you can select from the following sample formats:
113//!
114//! | Format | Description |
115//! |--------|-------------|
116//! | `Int8` | 8-bit integer |
117//! | `Int16` | 16-bit integer (default) |
118//! | `Int32` | 32-bit integer |
119//! | `Float32` | 32-bit float |
120//!
121//! `Int16` is the default, for broader compatibility.
122//!
123//! ### Some example configs:
124//!
125//! - resample to 22.05 kHz while reading
126//!
127//! ```rust
128//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
129//! let audio = audio_file::read::<f32>(
130//! "test_data/test_1ch.wav",
131//! audio_file::ReadConfig {
132//! sample_rate: Some(22_050),
133//! ..Default::default()
134//! },
135//! )?;
136//! # Ok(())
137//! # }
138//! ```
139//!
140//! - read the first 0.5 seconds
141//!
142//! ```rust
143//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
144//! # use std::time::Duration;
145//! let audio = audio_file::read::<f32>(
146//! "test_data/test_1ch.wav",
147//! audio_file::ReadConfig {
148//! stop: audio_file::Position::Time(Duration::from_secs_f32(0.5)),
149//! ..Default::default()
150//! },
151//! )?;
152//! # Ok(())
153//! # }
154//! ```
155//!
156//! - read from frame 300 to 400
157//!
158//! ```rust
159//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
160//! # use audio_file::*;
161//! let audio = audio_file::read::<f32>(
162//! "test_data/test_1ch.wav",
163//! audio_file::ReadConfig {
164//! start: audio_file::Position::Frame(300),
165//! stop: audio_file::Position::Frame(400),
166//! ..Default::default()
167//! },
168//! )?;
169//! # Ok(())
170//! # }
171//! ```
172//!
173//! - read only the first two channels
174//!
175//! ```rust
176//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
177//! # use audio_file::*;
178//! let audio = audio_file::read::<f32>(
179//! "test_data/test_4ch.wav",
180//! audio_file::ReadConfig {
181//! num_channels: Some(2),
182//! ..Default::default()
183//! },
184//! )?;
185//! # Ok(())
186//! # }
187//! ```
188//!
189//! - skip the first channel, reading channel 2 and 3
190//!
191//! ```rust
192//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
193//! let audio = audio_file::read::<f32>(
194//! "test_data/test_4ch.wav",
195//! audio_file::ReadConfig {
196//! start_channel: Some(1),
197//! num_channels: Some(2),
198//! ..Default::default()
199//! },
200//! )?;
201//! # Ok(())
202//! # }
203//! ```
204//!
205//! - write audio samples in `Float32`
206//!
207//! ```rust
208//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
209//! # let samples_interleaved: Vec<f32> = vec![];
210//! # let num_channels = 2u16;
211//! # let sample_rate = 48000u32;
212//! audio_file::write(
213//! "tmp.wav",
214//! &samples_interleaved,
215//! num_channels,
216//! sample_rate,
217//! audio_file::WriteConfig {
218//! sample_format: audio_file::SampleFormat::Float32,
219//! },
220//! )?;
221//! # Ok(())
222//! # }
223//! ```
224
225#[cfg(feature = "audio-blocks")]
226pub use audio_blocks::*;
227
228#[cfg(feature = "audio-blocks")]
229pub use reader::read_block;
230pub use reader::{Audio, Position, ReadConfig, ReadError, read};
231#[cfg(feature = "audio-blocks")]
232pub use writer::write_block;
233pub use writer::{SampleFormat, WriteConfig, WriteError, write};
234
235pub mod reader;
236pub mod resample;
237pub mod writer;