Files
craft-libs/crates/audio/README.md
T
FredApps 1d413b992d Merge pull request #1688 from storytold/codex/flac-main-reconcile
Reconcile native FLAC decoder with merged QOA support
2026-11-16 00:17:47 +01:00

797 lines
50 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# craft-audio
Audio file I/O and codecs for the Craft apps. Native implementations: WAV and AIFF read/write,
FLAC encoder, AAC and ALAC decoders/encoders, AC-3/E-AC-3 decoder/encoder, MP3 decoder/encoder, Opus
decoder/encoder, MP1/MP2 decoders.
Formats without a native decoder are decoded by [symphonia](#symphonia), which is to be replaced
by native decoders.
- Input is a byte slice or any [`ByteSource`](../media/README.md#bytesource) (a file, a shared
buffer); output is byte vectors or any `Write + Seek`. The crate opens no files itself.
- Decoded audio is planar `f32`, full scale ±1, in `AudioBuffer` (`sample_rate`, one `Vec<f32>`
per channel), in WAV channel order (L R C LFE, back, side) whenever the channel layout is known.
- Malformed input returns an error, never a panic (see [symphonia](#symphonia) for the one
exception). No `unsafe`. Readers and decoders are tested with corrupted and truncated input.
- Implemented from the published specifications, except ALAC, which is ported from Apple's
Apache-2.0 reference implementation (see [Origin](#origin)); tested against ffmpeg and
conformance vectors.
Builds for `wasm32-unknown-unknown`.
- Containers (MP4/MOV, Matroska/WebM, Ogg), bit I/O and the `Container`/`CodecId`/`CodecParams`
types come from [`craft-media`](../media/README.md). This crate never depends on video codecs.
## Cargo features
No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayout`, `AudioError`,
`EncodeOptions`, `ByteSource`, …) build with none.
| Feature | Provides | Pulls in |
|---|---|---|
| `decode` | `decode`, `probe`, `Decoder`, `tracks`, `TrackDecoder`; every format in [Format support](#format-support) | `decode-native`, `symphonia` |
| `decode-native` | the same, native formats only (others are `Unsupported`); `wav_pcm`, `aiff_pcm` (a file's integer PCM bit for bit, as `RawPcm`) | the six decoders below, craft-media `isobmff`/`matroska`/`ogg`, `log` |
| `symphonia` | the fallback for formats with no native decoder; turning it on is the same as `decode` | `decode-native`, symphonia |
| `encode` | every encoder, and every format of `encode` and `FileEncoder` | `lossless-encode`, `aac-encode`, `alac-encode`, `ac3-encode`, `eac3-encode`, `mp3-encode`, `opus-encode`, `vorbis-encode` |
| `lossless-encode` | WAV, AIFF and FLAC writing | `pcm-encode`, `flac-encode` |
| `pcm-encode` | `encode`, `FileEncoder` for WAV and AIFF; `wav_float_header`; `pcm_wav_file`, `pcm_wav_header`, `pcm_aiff_file`, `pcm_aiff_header` (minimal files around integer PCM bytes, for essence embedded in AAF / OMF) | none |
| `flac-decode` | `flac::decode` (whole `.flac` files) and `flac::Decoder` (single frames, for callers that demux FLAC themselves); native, CRC-checked, 4 to 32 bits. `decode` still uses symphonia for FLAC files | none |
| `flac-encode` | `encode`, `FileEncoder` for FLAC; `flac::Encoder`, the packet encoder for callers that mux FLAC themselves | craft-media `bitstream` |
| `aac-decode`, `aac-encode` | `aac::Decoder`, `aac::Encoder`; with `aac-decode`, `aac::latm_config` / `latm_split` for LOAS / LATM frames (AAC in MPEG transport streams); with `aac-encode`, `encode`, `FileEncoder` for AAC in M4A | craft-media `bitstream`; `aac-encode` also `isobmff` |
| `alac-decode` | `alac::Decoder` | none |
| `alac-encode` | `alac::Encoder`; `encode`, `FileEncoder` for ALAC in M4A | craft-media `isobmff` |
| `opus-decode`, `opus-encode` | `opus::Decoder`/`StreamDecoder`, `opus::Encoder` | none |
| `vorbis-encode` | `vorbis::encoder::Encoder` (pure Rust); `encode_ogg_vorbis`, `encode_ogg` and `encode` for Ogg Vorbis files (whole buffer; not `FileEncoder`) | craft-media `ogg` |
| `ac3-decode` | `ac3::Decoder`, `ac3::ProgrammeDecoder` | craft-media `bitstream` |
| `ac3-encode`, `eac3-encode` | `ac3::encoder::Encoder`; `encode`, `FileEncoder` for AC-3 and E-AC-3 streams | craft-media `bitstream` |
| `mpa-decode` | `mpa::Decoder` | craft-media `bitstream` |
| `mp3-decode` | `mp3::Decoder`, `mp3::InfoTag` | `mpa-decode` |
| `mp3-encode` | `mp3::Encoder`; `encode`, `FileEncoder` for MP3 | craft-media `bitstream` |
| `peaks` | `peaks::Peaks` | none |
| `rayon` | parallel AAC encoding (with `aac-encode`) | `rayon` |
| `serde` | `Serialize`/`Deserialize` on the shared types | `serde` |
Any one decoder feature (`aac-decode`, `alac-decode`, `opus-decode`, `ac3-decode`, `mpa-decode`,
`mp3-decode`)
also gives `TrackDecoder`, for that codec and PCM.
An app that decodes 32-bit FLAC with `decode` needs a profile override in its workspace; see
[symphonia](#symphonia).
WAV, AIFF and FLAC export only (no decoders, no demuxers, no symphonia):
```toml
craft-audio = { git = "https://github.com/storytold/craft-libs", rev = "<commit>", features = ["lossless-encode"] }
```
Decode, every encoder and waveform overviews:
```toml
craft-audio = { git = "https://github.com/storytold/craft-libs", rev = "<commit>", features = ["decode", "encode", "peaks"] }
```
Packets from an app's own demuxer, AAC both ways:
```toml
craft-audio = { git = "https://github.com/storytold/craft-libs", rev = "<commit>", features = ["aac-decode", "aac-encode"] }
```
craft-audio re-exports the craft-media types its API uses (`ByteSource`, `ReadSeekSource`,
`CodecParams`, …), and craft-media itself as `craft_audio::craft_media`. Use that to reach the
containers directly (for example to pass an `isobmff::Track`'s `codec_params()` to
`TrackDecoder`); `decode-native` turns on all three. A separate craft-media dependency must use
the **same `rev`** as craft-audio: with two revisions Cargo builds two copies, and their types do
not match.
## Usage
Runnable versions are in `examples/`:
```bash
cargo run -p craft-audio --example info --features decode -- take.m4a
```
```bash
cargo run -p craft-audio --example encode --features lossless-encode,aac-encode -- out
```
```bash
cargo run -p craft-audio --example stream --features decode -- long-recording.m4a 60
```
```bash
cargo run -p craft-audio --example packets --features decode -- take.m4a
```
`stream` takes a file and a start time in seconds; `packets` takes an MP4 file. The entry points
(`decode`, `probe`, `tracks`, `Decoder`, `TrackDecoder`, `encode`, `FileEncoder`) and the
functions around them have rustdoc examples.
### Decode a file
```rust
use craft_audio::{decode, probe};
let bytes = std::fs::read("take.m4a")?;
// Container, codec, rate, speaker layout and length. Read from the headers; when they give no
// length (an MP3 without a Xing frame, PCM in Matroska), the file is decoded to count it.
let info = probe(&bytes, Some("m4a"))?;
println!("{} in {}, {} Hz, {}", info.codec.name(), info.container.name(), info.sample_rate, info.layout);
// The first audio track: planar f32 in WAV channel order, trimmed to its presentation length.
let (info, buf) = decode(&bytes, Some("m4a"))?;
let left: &[f32] = &buf.channels[0];
```
`decode` returns `TooLarge` above 2³⁰ samples (4 GiB of `f32`). `info.damaged` counts packets
that were damaged and replaced by silence of their length. A FLAC frame whose checksum fails is
dropped by the demuxer; the jump in the timestamps shows it, and the lost frames are silence too (one
count per run of them), so the audio after them stays in place.
### Choose a track
```rust
use craft_audio::{DecodeOptions, decode_with, tracks};
let list = tracks(&bytes, None)?; // codec, rate and channels of every audio track
if let Some(second) = list.get(1) {
let opts = DecodeOptions::default().with_track(second.index);
let (info, buf) = decode_with(&bytes, None, &opts)?;
}
```
A track index the file does not have is `Unsupported`. `DecodeOptions::with_max_samples` sets
another size limit. The default is `DEFAULT_MAX_SAMPLES`, 2^30 samples (4 GiB of `f32`), which
`decode` and `decode_with` can fill from a small compressed file because they keep the whole
result. An app that opens files it did not write passes a limit it can hold (for example
`DEFAULT_MAX_SAMPLES / 8`, or its longest supported clip), or streams with `Decoder`, which has no
limit because it keeps nothing. `tracks_of` lists the tracks of a file read from a `ByteSource`;
`detect_container` names a file's container from its first bytes. `DECODE_EXTENSIONS` lists the
file extensions of the formats `decode` reads, for a file picker's filter.
### Stream and seek
```rust
use craft_audio::{DecodeOptions, Decoder};
let file = std::fs::File::open("long-recording.m4a")?;
let mut dec = Decoder::open(file, Some("m4a"), &DecodeOptions::default())?;
dec.seek(48_000 * 60)?; // sample-exact (see Limits): the next block starts here
while let Some(block) = dec.next_block()? {
// block.channels: planar f32, WAV channel order
}
```
`Decoder::open` takes any `ByteSource` that is `Send + Sync` (`SharedSource`): a `Vec<u8>` or
`Arc<[u8]>`, a `ReadSeekSource` around any `Read + Seek`, or a `std::fs::File`. Prefer
`ReadSeekSource` for files: it takes the length once and reports a failure when it is made. On
single-threaded WebAssembly the source need not be `Send`, so a reader over a JS `Blob` works.
`Decoder::from_bytes` does the same for a borrowed buffer.
`seek` returns the frame decoding resumes at. A seek to or past the end of a file whose length is
known stops at the end, and the next `next_block` returns `None`. When `length_known()` is false,
`info().frames` is 0: add up the block lengths, or call `Decoder::probe`, which decodes the rest
of the file to count them. `Decoder::probe` is also how to probe a file on disk.
Native formats read their samples from the source packet by packet. The container's packet index
stays in memory (tens of bytes per packet), and opening an Ogg or Matroska file or a raw ADTS
stream reads through the whole file to build it. Formats symphonia decodes are read whole first.
A damaged packet is concealed and counted in `info().damaged`. A source that fails a read (a
network drop) returns `AudioError::Io` from `next_block` instead, and that packet is skipped. To
retry it, keep the position: start from the frame the last `seek` returned (0 without one), add
each block's frames, and `seek` to that position.
### Decode packets from your own demuxer
`TrackDecoder` takes a track's `CodecParams` and the first packets. The parameters come from any
craft-media demuxer's `codec_params()` (see
[craft-media's codec parameters](../media/README.md#containers-codecs-and-codec-parameters)), or
are built with `CodecParams::new` for another container:
```rust
use craft_audio::{CodecId, CodecParams, TrackDecoder};
let params = CodecParams::new(CodecId::Aac).with_extradata(asc).with_sample_rate(48_000);
let lookahead: Vec<&[u8]> = packets.iter().take(craft_audio::LOOKAHEAD_PACKETS).map(Vec::as_slice).collect();
let mut dec = TrackDecoder::new(&params, &lookahead)?;
for p in &packets {
let block = dec.decode(p).or_else(|_| dec.conceal(Some(p)))?;
}
```
It decodes AAC (finding HE-AAC in the lookahead), Opus, AC-3/E-AC-3, MP1/MP2 and PCM, and returns
`AudioBuffer`s in WAV order when `layout()` is ordered. `codec()`, `sample_rate()` and `layout()`
describe the output. Container timing is the caller's.
Streams without codec configuration work where the packets carry it. AAC with empty `extradata`
takes its configuration from the ADTS headers (MPEG-TS, raw `.aac`), which are stripped from each
packet. Opus with empty `extradata` and 1 or 2 channels (RTP, MPEG-TS) needs no `OpusHead`.
To seek: position your demuxer at the packet that starts `preroll()` frames or more before the
target, call `reset()`, decode from there, and drop the output before the target.
The codec modules are also usable on their own. `aac::Decoder` and `opus::Decoder` return the
codec's channel order; `aac::wav_order(channel_config)` and `opus::wav_order(channels)` map it to
WAV order. `ac3::Decoder` and `mpa::Decoder` output WAV order.
### Encode a file
```rust
use craft_audio::{AudioBuffer, BitDepth, ChannelLayout, EncodeFormat, EncodeOptions, FileEncoder, encode};
// One Vec of samples per channel, full scale ±1. `AudioBuffer::new(rate, channels, frames)`
// makes a silent one to fill.
let buf = AudioBuffer { sample_rate: 48_000, channels: vec![left, right] };
let opts = EncodeOptions::new(EncodeFormat::Flac).with_bit_depth(BitDepth::Int24).with_dither(true);
let flac: Vec<u8> = encode(&buf, &opts)?;
// 5.1 with side surrounds: a layout other than the default for 6 channels, recorded in the WAV.
let wav = encode(&surround, &EncodeOptions::default().with_layout(ChannelLayout::SURROUND_5_1_SIDE))?;
// Block by block into any Write + Seek with nothing after its position; the same bytes as `encode`.
let mut enc = FileEncoder::new(std::fs::File::create("take.wav")?, &EncodeOptions::default(), 48_000, 2)?;
enc.write(&buf.channels, buf.frames())?; // one slice (or Vec) per channel
enc.finish()?;
// The coded formats go the same way: AAC in M4A at 192 kbit/s, 5.1 as E-AC-3, 16-bit ALAC.
let m4a = encode(&buf, &EncodeOptions::new(EncodeFormat::Aac).with_bitrate(192_000))?;
let eac3 = encode(&surround, &EncodeOptions::new(EncodeFormat::Eac3).with_layout(ChannelLayout::SURROUND_5_1_SIDE))?;
let alac = encode(&buf, &EncodeOptions::new(EncodeFormat::Alac).with_bit_depth(BitDepth::Int16))?;
```
`EncodeOptions::default()` is 24-bit WAV. `with_bwf` adds a BWF `bext` chunk and
`with_force_rf64` writes RF64 below 4 GiB; both apply to WAV only. `encode_format_for("aiff")`
maps an extension to an `EncodeFormat` (`"m4a"` to AAC; `"alac"` names ALAC), and `ENCODE_EXTENSIONS` lists the extensions the enabled
features can write. `EncodeFormat::ALL` lists the formats and `is_built()` says whether this build
writes one; `extension()` is the extension a new file gets and `mime_type()` its media type.
`write` refuses a block without one slice per channel, or with a slice shorter than `frames`, and
writes nothing. After a write fails for another reason, every later
`write` and `finish` returns an error.
| `EncodeFormat` | File | Audio | Options used |
|---|---|---|---|
| `Wav`, `Aiff`, `Flac` | WAV / BWF / RF64, AIFF / AIFF-C, FLAC | any rate; FLAC up to 8 channels | `bit_depth`, `dither`, `layout` (WAV, FLAC), `bwf`, `force_rf64` (WAV) |
| `Alac` | M4A | 1–8 channels, any rate | `bit_depth` (16, 24, 32), `dither`, `layout` |
| `Aac` | M4A | AAC-LC, 1–8 channels, the 13 AAC rates (7350–96000 Hz) | `rate_control`, `layout` |
| `Mp3` | `.mp3` stream | mono or stereo; 32, 44.1, 48 kHz or 16, 22.05, 24 kHz | `rate_control` (bit rate), `layout` |
| `Ac3`, `Eac3` | `.ac3` / `.eac3` stream | up to 5.1 (E-AC-3: 7.1); 32, 44.1, 48 kHz | `rate_control` (bit rate), `layout` |
`with_bitrate(bits_per_second)` sets a constant bit rate for all channels together. A rate the
stream cannot carry is moved to the nearest one it can: MP3 and AC-3 use the highest rate of their
tables not above it, AAC and E-AC-3 keep it inside their range (AAC from 6 kbit/s or a quarter of
the sample rate per channel, whichever is more: from about half of that down the encoder codes
silence). `with_quality(0.0..=1.0)` is AAC's
constant quality (VBR); the other lossy formats return `Unsupported` for it. Without either, AAC
is written at 64 kbit/s per channel, MP3 at 96 kbit/s per channel, and AC-3 and E-AC-3 at
96 kbit/s per full-bandwidth channel (the LFE not counted).
The audio is in WAV channel order for every format; `layout` (the usual layout for the channel
count when unset) names the speakers, and the channels are reordered into the codec's own order.
Each coded format has a fixed set of layouts, and audio with other speakers is `Unsupported`
rather than written to the wrong ones:
- AAC: C; L R; L R C; L R C Cb; L R C Ls Rs; 5.1; 6.1; and for 8 channels L R C LFE Lb Rb Lc Rc
(a front pair left and right of centre, mask `0xFF`). ALAC: the same, with 6.1's back centre last.
WAV 7.1 (backs and sides) is not that 7.1, and quad (the usual 4-channel layout) has no centre:
both need another format.
- AC-3 and E-AC-3: the layout picks the coding mode (1/0 to 3/2, with or without LFE; E-AC-3 also
7.1 with backs and sides).
- A surround pair is a surround pair: side and back surrounds are interchangeable where the format
has one pair.
Before a file is created, the options and the format say what will happen:
```rust
let opts = EncodeOptions::new(EncodeFormat::Ac3).with_layout(info.layout).with_bitrate(200_000);
opts.check(info.sample_rate, info.channels)?; // the error FileEncoder::new would return, nothing written
let bps = opts.bitrate(info.sample_rate, info.channels)?; // Some(192_000): the rate actually used; None when lossless or by quality
EncodeFormat::Ac3.sample_rates(); // Some(&[32_000, 44_100, 48_000]); None when any rate will do
EncodeFormat::Ac3.max_channels(); // 6
EncodeFormat::Ac3.fixed_layouts(3); // L R C, L R Cb, L R LFE; None for WAV, AIFF and FLAC (any layout)
EncodeFormat::Ac3.supports_layout(&info.layout); // one of those, sides and backs standing for each other
EncodeFormat::Ac3.supports_quality(); // false: AAC only
```
`FileEncoder::bitrate()` gives the rate of a file being written. The `EncodeFormat` queries answer
for a format whose feature is off too; `check` and `EncodeOptions::bitrate` (there with any
encoder feature) return `Unsupported` for it.
The layout `decode` reports (`AudioInfo::layout`) can be passed to `with_layout` as it is. When a
coded format refuses it (2.1 or quad into AAC, a single channel tagged as left, channels with no
speaker assignment), the choices are another format, or audio rearranged into one of the layouts
above with that layout set; leaving `layout` unset declares the usual layout for the count. This
crate's decoder returns 7- and 8-channel AAC without a speaker assignment, in AAC order, so such a
file needs that step before it is written again.
An M4A's edit list skips the AAC encoder's priming (1024 frames) and ends at the last frame
written, so the file decodes to the length that went in. An MP3, AC-3 or E-AC-3 stream has no
place for that (see [Limits](#limits)). For a container of your own, use the codec modules below.
### Encode AAC packets
For an `.m4a` file, use `EncodeFormat::Aac` above. `aac::Encoder` is the packet encoder behind it,
for muxing into a container of your own:
```rust
use craft_audio::AudioError;
use craft_audio::aac::{Encoder, EncoderConfig, aac_order};
let mut enc = Encoder::new(EncoderConfig::cbr(48_000, 6, 384_000))?;
let order = aac_order(6).ok_or_else(|| AudioError::Unsupported("no AAC order for 6 channels".into()))?;
let input: Vec<&[f32]> = order.iter().map(|&c| wav_5_1[c].as_slice()).collect();
let mut units = enc.encode(&input); // zero or more access units
units.extend(enc.flush());
let asc = enc.audio_specific_config(); // for the MP4 `esds` box
let priming = enc.priming_samples(); // for the edit list (1024)
```
The sample rate must be one of the 13 AAC rates (7350–96000 Hz). `aac_order` returns `None` for
mono and stereo, which are already in order, and for 8 channels. Eight channels are written as AAC
channel configuration 7 and taken in its element order: C, Lc Rc, L R, Ls Rs, LFE (front centre,
front left and right of centre, front left and right, surrounds). A WAV 7.1 buffer (L R C LFE Lb Rb
Ls Rs) has no equivalent in that layout; passed unchanged, its channels go to the wrong speakers.
`EncoderConfig::cbr(..).with_adts(true)` makes every access unit an ADTS frame; concatenated, they
are a playable `.aac` file. To write MP4 or Matroska, pass the access units to craft-media's
muxers ([MP4](../media/README.md#muxing), [Matroska](../media/README.md#muxing-1)).
### Encode Opus
```rust
use craft_audio::opus::Encoder;
let mut enc = Encoder::new(2, 128_000)?; // channels, bits per second
let frame_len = Encoder::FRAME_SIZE * 2; // 20 ms, interleaved stereo
let mut samples = buf.interleaved(); // 48 kHz audio
// Silence after the audio flushes the encoder's delay (the pre-skip) and fills the last frame.
let frames = samples.len() / 2 + enc.pre_skip() as usize;
samples.resize(frames.div_ceil(Encoder::FRAME_SIZE) * frame_len, 0.0);
let mut packets = Vec::new();
for frame in samples.chunks_exact(frame_len) {
packets.push(enc.encode_float(frame)?);
}
let head = enc.opus_head(); // Matroska's CodecPrivate
let pre_skip = enc.pre_skip(); // samples the player drops at the start
```
The encoder takes 48 kHz only, and craft-audio has no resampler.
Opus goes into Ogg, Matroska/WebM or MP4:
- **Ogg (`.opus`):** `craft_media::ogg::PageWriter` with `head` and `opus_tags` as the two header
packets, each packet's granule position the samples decoded so far (pre-skip included, as
the input above starts with it), and `finish(Some(pre_skip + length))` to trim the end
(RFC 7845 §4).
- **Matroska/WebM:** `head` is the track's `CodecPrivate`, and the pre-skip goes in
`TrackSpec::codec_delay_ns` (in nanoseconds at 48 kHz). The Matroska muxer cannot write
`DiscardPadding`, so the padding at the end stays in the file.
- **MP4:** the sample entry takes an `isobmff::OpusConfig` (`dOps`) with the same fields as the
`OpusHead`: channels, pre-skip, input rate, gain and mapping family. `TrackConfig::media_start`
set to the pre-skip skips it. To drop the padding as well, give `TrackConfig::edits` one
`Edit` instead, which replaces the edit `media_start` makes: `media_time` the pre-skip (track
timescale), `segment_duration` the audio's length (movie timescale), `media_rate`
`0x0001_0000`.
### Encode Ogg Vorbis
```rust
use craft_audio::{OggVorbisOptions, encode_ogg_vorbis};
// 1–8 channels in Vorbis order (5.1: L C R Ls Rs LFE), any sample rate.
let opts = OggVorbisOptions::new(6.0).with_tag("TITLE", "Take 3").with_tag("ARTIST", "Me");
let ogg: Vec<u8> = encode_ogg_vorbis(&buf, &opts)?;
```
The encoder is pure Rust (`vorbis::encoder`, from FilmCraft #4481) and builds for wasm32. Quality
runs from -1 to 10 at a variable bit rate: about 18 kbit/s per channel at -1, 100 at 6 and 140
at 10 on music. `encode` with `EncodeFormat::Ogg` takes a WAV-order layout and writes it in
Vorbis order; its `RateControl::Bitrate` (64–500 kbit/s) picks the quality whose nominal rate
that is (`quality_for_bitrate`), and `RateControl::Quality` 0.0–1.0 is quality -1 to 10. For
streaming, feed `vorbis::encoder::Encoder` and write its packets with `craft_media::ogg::PageWriter`
(identification, `vorbis_comment`, setup, then the audio with each packet's granule position).
Not yet: short blocks (transients may pre-echo), channel coupling (stereo costs
about twice mono) and bit-rate management.
### Waveform overviews
```rust
use craft_audio::peaks::Peaks;
let peaks = Peaks::build(&left); // once per channel
// Start sample, samples per column, overlap, columns; pass the same samples each time. One
// (min, max) per column, `None` past the end of the data.
let columns = peaks.spans(&left, 0.0, 512.0, 0.0, 800);
```
`Peaks` is a min/max/sum-of-squares pyramid (32-sample blocks, fan-out 4). Range queries are
exact, O(log n). `rms_spans` returns one RMS value per column.
### Errors
Functions return `craft_audio::Result<T>`. The codec modules have their own `Error` types, which
convert into `AudioError` with `?`.
| `AudioError` | Cause |
|---|---|
| `Unsupported` | valid input using an unsupported codec, feature or option, or a format whose feature is off |
| `Malformed` | corrupt or truncated input, or not the claimed format |
| `TooLarge` | over a size limit (`DecodeOptions::max_samples`, an allocation) |
| `Encode` | an encoder rejected the input or its settings (a buffer with no channels or a 0 Hz rate, a block shorter than its frame count, a wrong layout, a rate AAC has no index for) |
| `Io` | the source failed a read, or the `FileEncoder` writer failed |
`AudioError` is `#[non_exhaustive]`, so a `match` needs a `_` arm:
```rust
match craft_audio::decode(&bytes, None) {
Ok((info, buf)) => { /* … */ }
Err(craft_audio::AudioError::Unsupported(what)) => eprintln!("cannot decode: {what}"),
Err(e) => eprintln!("{e}"),
}
```
## Format support
| Format | Decode | Encode |
|---|---|---|
| WAV, BWF, RF64/BW64 | native | native |
| AIFF, AIFF-C | native | native |
| FLAC | symphonia | native |
| AAC-LC | native | native; M4A through `encode` / `FileEncoder`, packets through `aac::Encoder` |
| HE-AAC v1 | native (SBR) | — |
| HE-AAC v2 | native, without parametric stereo (see [Limits](#limits)) | — |
| ALAC | native | native; M4A through `encode` / `FileEncoder`, packets through `alac::Encoder` |
| MP1, MP2 (MPEG audio Layer I/II) | native | — |
| MP3 (Layer III) | native | native; `.mp3` through `encode` / `FileEncoder`, frames through `mp3::Encoder` |
| Opus | native | native, packets (`opus::Encoder`; no file writer) |
| AC-3, E-AC-3 | native | native; `.ac3` / `.eac3` through `encode` / `FileEncoder`, packets through `ac3::encoder::Encoder` |
| Vorbis, ADPCM, A-law, µ-law | symphonia | — |
| Container | Demuxer | Timing |
|---|---|---|
| MP4, M4A, MOV | `craft_media::isobmff` for native codecs; symphonia for the others (FLAC) | edit lists (AAC priming, Opus pre-skip) |
| Matroska, WebM | `craft_media::matroska` for native codecs; symphonia for the others (Vorbis, FLAC) | `CodecDelay`, `DiscardPadding` |
| Ogg | `craft_media::ogg` (Opus); symphonia (Vorbis, FLAC) | pre-skip, end trimming |
| Raw ADTS AAC, AC-3, E-AC-3, MP1/MP2 | native frame sync | — |
| Raw MP3 | native frame sync; symphonia for the free format | Xing / Info / VBRI frame skipped; LAME tag encoder delay and padding |
| FLAC | symphonia | — |
| CAF | symphonia | — |
## Limits
- HE-AAC: `decode`, `Decoder` and `TrackDecoder` decode SBR at twice the core rate.
`aac::Decoder` outputs the core rate unless `set_sbr(true)` is called. Downsampled SBR (an
output rate equal to the core rate) plays the core alone.
- HE-AAC v2: parametric stereo is not reconstructed, so the mono core decodes as mono, with SBR.
- AAC: Main, SSR and LTP profiles, coupling channels and 960-sample frames are unsupported.
- Raw ADTS: frames with several raw data blocks are unsupported: a stream of them is refused, and
one among other frames decodes as silence of its length and counts as damaged, as does a frame
that changes the stream's sample rate, profile or channel configuration.
- A seek into AAC with PNS gives the same samples each time, but its noise differs from a continuous
decode's, at the same band energy.
- MP4 gapless information outside an edit list is not read: a file from Apple's encoders with
`iTunSMPB` and no `elst` decodes with its priming and padding.
- A Matroska track with no block durations (AAC from ffmpeg 6) ends at its `DURATION` tag, when
that ends inside the last packet. Otherwise all its audio is presented, including any padding.
- ffmpeg before 9 ends some codecs' tracks in MP4 and Matroska up to 11 ms early. The audio past
the end a file declares is not presented.
- A Matroska track's end comes from its timestamps, so it is known to one timestamp tick (usually
1 ms) unless the last block has `DiscardPadding`.
- E-AC-3: `ac3::Decoder` and `TrackDecoder` retain independent-substream decoding, so a
7.1 programme is presented as its 5.1 compatibility downmix. Use `ac3::ProgrammeDecoder`
with an explicit expected layout for complete six-block 7.1 access units; see below.
Adaptive hybrid transform and enhanced coupling return `Unsupported`.
- E-AC-3 with syncframes of fewer than six blocks: a seek decodes from the start of the stream,
because such syncframes may reuse exponents from any syncframe before them. A seek in Matroska
E-AC-3 reads the syncframe headers of the packets before its target to find the packets' places.
- AC-3: not bit-exact. Zero-bit mantissas are filled with decoder-specific dither (A/52 §7.3.4),
so white noise matches ffmpeg at only 27 dB (AC-3) and 48 dB (E-AC-3) SNR.
- WebM Opus: `probe` can over-report by up to one block (the last block's `DiscardPadding` is
known only when it is read); `decode` and `Decoder` are exact.
- AAC channel configuration 7 and program-config layouts, Opus mapping families other than 0 and
1, and AIFF with more than four channels decode with an unordered layout, in the codec's order.
- A FLAC layout that decoders would not assume for the channel count depends on its
`WAVEFORMATEXTENSIBLE_CHANNEL_MASK` comment. This includes the usual layouts for 5 and 6 channels:
without the comment, back surrounds are read as side surrounds. It includes the usual 7-channel
layout too: without the comment, its back left, back right and back centre are read as back
centre, side left and side right.
- FLAC at 32 bits codes stereo channels independently, because a side channel would need 33 bits.
- Outside RFC 9639's streamable subset (§7), which some decoders require: FLAC at 32 bits, at a
sample rate the frame header cannot name, or with a layout that needs the mask comment.
- `ChannelLayout::unordered` is written to FLAC as mask `0x0000`, as RFC 9639 §8.6.2 allows, but
ffmpeg and `flac -d` ignore that mask and use their default layout for the channel count.
- Not decoded at all: Speex.
- `TrackDecoder` returns `Unsupported` for FLAC and Vorbis; `decode` and `Decoder` read
those through symphonia. ALAC in CAF still goes through symphonia (craft-media has no CAF
demuxer).
- ALAC: craft-media's MP4 muxer writes no `chan` box, so an M4A of more than two channels (from
`EncodeFormat::Alac` or muxed from `alac::Encoder` packets) carries no explicit layout; decoders
then use the standard ALAC layout for the count, which is the one written.
- `EncodeFormat::Mp3`, `Ac3` and `Eac3` write raw streams, which cannot signal the codec's delay or
the length: the file decodes with 1057 (MP3) or 256 (AC-3, E-AC-3) frames of delay in front and
padded to whole frames at the end. MP3 gets no Xing / Info frame. `EncodeFormat::Aac` and `Alac`
(M4A) decode to the length written.
- An AAC M4A's length is in the edit list and the last packet's duration. This crate, Apple's
decoders and ffmpeg 9 end the audio there; ffmpeg 8 skips the priming but plays the last
packet's padding (under 1024 frames of near silence).
- `EncodeFormat::Aac` and `Alac` write the `moov` box after the audio (no fast start), and no
metadata. Raw ADTS AAC is not a file format of `encode`; `aac::EncoderConfig::with_adts` gives
the frames.
- This crate's file reader plays a raw E-AC-3 7.1 stream as its 5.1 independent substream.
- `EncodeFormat::Aac` with 8 channels is AAC channel configuration 7 (C, Lc Rc, L R, Ls Rs, LFE),
which Apple's decoders read as written. ffmpeg assumes such a stream is a mislabelled 7.1 with
backs and sides and moves the channels accordingly, unless run with `-strict 1`.
- A file with no audio: MP3, AC-3 and E-AC-3 are then zero bytes, which nothing can probe. An
empty AAC M4A (a track with no samples) is read by ffmpeg; this crate's native reader passes it
on, so `decode-native` alone refuses it and symphonia reads only some as zero frames.
- ALAC 32-bit streams: ffmpeg does not decode their uncompressed (escaped) stereo frames, which
Apple's encoder and this one write for audio that does not compress; Apple's decoder and this
one do.
- MP4 edit lists: a single media edit (encoder priming and the end) is applied, alone or after one
empty edit; the empty edit's delay is not added as silence. Other edit lists are not applied, and
the media plays as it is stored.
- AAC in MP4 stored as ADTS frames, when the sample durations count fewer frames than the samples
hold: HE-AAC durations that count only the core frames, or several frames in a sample timed as
one. Such a file is broken: it is outside the MP4 specification in two ways.
- An MP4 AAC sample is one raw access unit, with the stream's configuration in the sample
description (ISO/IEC 14496-14 and 14496-3). ADTS is a transport framing for streams such as
MPEG-TS and raw `.aac`, and its headers do not belong in an MP4 sample.
- A sample's duration in the time-to-sample table is the time it decodes to (ISO/IEC 14496-12).
Durations that count fewer frames than the samples hold do not describe the track.
ffmpeg, Apple's encoders, phones and cameras write raw AAC with matching durations, and a
correct remux from MPEG-TS or raw `.aac` converts the framing, so files within the specification
are not affected. In a file outside it:
- Read from the start, the track decodes in full: durations that fall short of the frames in
the samples read at open do not end it.
- `Decoder::seek` places samples by those durations, so it lands later than asked, and an edit
list measured in them can end the track early.
- These are not corrected because where each sample's audio starts is only known by counting
the ADTS frames in every sample before it: one read per sample, hundreds of thousands on a
two-hour track. Done at open, that would slow every ADTS-framed MP4 to work around files
that are outside the specification.
## Codecs
Each codec module's rustdoc lists the coding tools it implements.
| Codec | Spec | Scope | Verified against |
|---|---|---|---|
| WAV, AIFF | Microsoft RIFF, Apple AIFF/AIFF-C | read: integer 8–32-bit, float 32/64-bit, `WAVE_FORMAT_EXTENSIBLE` masks, RF64/BW64, BWF `bext`, truncated files; write: 16/24/32-bit integer and 32-bit float, RF64 above 4 GiB, any layout, TPDF dither | round trips; hostile-input tests |
| FLAC encoder | RFC 9639 | 16, 24, 32 bits; 1–8 channels, layouts decoders would not assume for the count as a `WAVEFORMATEXTENSIBLE_CHANNEL_MASK` comment; up to 655,350 Hz; LPC, stereo decorrelation, wasted bits, STREAMINFO MD5 | bit-exact through ffmpeg, STREAMINFO MD5 checked against ffmpeg |
| AAC (`aac`) | ISO/IEC 14496-3; SBR tables from ETSI ES 201 980 Annex I | AAC-LC decode and encode (CBR, VBR, ADTS), 1–8 channels; HE-AAC (SBR) decode, see [Limits](#limits) | ffmpeg: ~135 dB SNR; PNS noise differs per sample at equal band energy. HE-AAC from AudioToolbox, 1–6 channels: same 962-sample delay as ffmpeg, ~54 dB SNR, high band level within 0.01 dB |
| Opus (`opus`) | RFC 6716, 8251, 7845 | decoder: SILK, hybrid, CELT, all frame sizes, PLC and FEC, multistream (`Decoder`) and single stream (`StreamDecoder`), 8–48 kHz output; encoder (`Encoder`): SILK, hybrid, CELT, 48 kHz, 20 ms frames, mono or stereo | all 36 RFC 8251 conformance cases; encoder output through ffmpeg's two Opus decoders |
| AC-3/E-AC-3 (`ac3`) | decoder: ATSC A/52:2012; encoder/programme API: ETSI TS 102 366 V1.4.1 | single-syncframe and complete-programme decoding; packet encoding through discrete 7.1 (see below) | decoder comparisons and encoder output through ffmpeg, CRC/channel/timing/bit-budget regressions; synthetic quality limitations below |
| MP1/MP2 (`mpa`) | ISO/IEC 11172-3, 13818-3 | Layer I and II, MPEG-1/2/2.5, 8–48 kHz; also the Layer II rate/mode pairs the spec disallows (ffmpeg's default mono 384 kbit/s); no free format | ffmpeg-encoded streams, 73–84 dB SNR |
| MP3 decoder (`mp3`) | ISO/IEC 11172-3, 13818-3 | Layer III, MPEG-1/2/2.5, 8–48 kHz, every bit rate, CBR and VBR; mono, stereo, dual channel, joint stereo (mid/side and intensity); long, short and mixed blocks; bit reservoir; CRC read, not checked; Xing / Info / VBRI and LAME tags; no free format (read through symphonia) | ffmpeg's float decoder: 127–131 dB SNR on LAME streams of every sampling frequency (CBR, VBR, CRC, no reservoir, transients with short blocks) and on this crate's encoder's; intensity stereo and mixed blocks through LAME frames edited to use them (112–131 dB) |
| MP3 encoder (`mp3`) | ISO/IEC 11172-3, 13818-3 | Layer III, constant bit rate: 32–320 kbit/s at 32/44.1/48 kHz, 8–160 kbit/s at 16/22.05/24 kHz; mono, stereo, joint stereo (mid/side); bit reservoir; long blocks only; no Xing/Info tag, VBR, CRC or free format | ffmpeg decodes every Huffman code as intended; full encodes at every sampling frequency checked with ffprobe and by SNR of ffmpeg's decode |
| ALAC (`alac`) | Apple's reference implementation | decode and encode, 1–8 channels, 16/20/24/32 bits (decode: any depth 1–32), fast mode, magic cookie in MP4/Matroska and CAF form | Apple's reference: same packets from the encoder, same samples from both decoders on 766 configurations; ffmpeg: bit-exact both ways |
### MP3 encoding
```rust
use craft_audio::mp3::{Config, DELAY, Encoder};
let mut enc = Encoder::new(Config::cbr(48_000, 2, 192))?;
let mut mp3 = enc.encode(&[&left, &right]); // whole frames as they complete
mp3.extend(enc.flush()); // pads with silence to the last input sample
// a decoder's output lags the input by DELAY (1057) samples
```
`mp3::bitrates(rate)`, `nearest_bitrate(rate, kbps)` and `nearest_sample_rate(rate)` map arbitrary
settings onto what a stream can carry; `Encoder::new` refuses anything else. Samples that are not
finite count as silence and the rest are clamped to ±4, so no input makes an invalid frame.
- Hybrid filterbank: the Annex C polyphase analysis filter, the normal-window MDCT and alias
reduction; reconstruction is checked against a reference of the normative decoder filterbank.
- Psychoacoustic model: band energies spread across scalefactor bands, floored by the threshold in
quiet (full scale = 96 dB SPL); a low-pass by bit rate.
- Quantization: the inner and outer loops with scalefactors, an exhaustive choice of the region
split and the Huffman table per region, and the bit reservoir (`main_data_begin`) bounded by the
decoder's 7680-bit input buffer.
- Not yet: block switching (short blocks; transients pre-echo), `scfsi` and `preflag`, intensity
stereo, a tonality-aware model, VBR/ABR, the Xing/Info and LAME gapless tags (the delay is not
signalled), CRC and free format.
### AC-3 and E-AC-3 encoding
`ac3::encoder` is implemented from **ETSI TS 102 366 V1.4.1 (September 2017)**,
with the existing first-party decoder's normative allocation tables/math shared internally.
No third-party codec implementation source is used. Decoder executables are interoperability
oracles, not linked dependencies. This is a basic encoder implementation, not a Dolby-certified
product or a claim of perceptual parity with mature commercial encoders.
The public `Config` chooses `Codec`, sample rate, programme bitrate, `CodingMode` and LFE.
`Encoder::new` validates these before taking PCM. Both codecs accept 32, 44.1 and 48 kHz,
all eight AC-3 coding modes (including distinct dual mono), and optional LFE. AC-3 uses
its standardized 32–640 kb/s frame-size table; this implementation requires at least
32 kb/s per full-bandwidth channel. E-AC-3 accepts 32–1024 kb/s programme rates, subject
to that same minimum and the per-substream 2048-word limit. E-AC-3 discrete 7.1 requires
LFE and at least 384 kb/s. Illegal rate/layout combinations return errors rather than
changing the requested codec or silently reducing channel count.
PCM planes have equal lengths, finite values in ±1, and the explicit speaker order returned
by `channel_layout()`. Values outside this input contract are rejected. Ordinary 5.1 uses
**L, R, C, LFE, Ls, Rs**; discrete 7.1 uses WAVE order **L, R, C, LFE, Lrs, Rrs, Ls, Rs**.
Dual mono is an unordered layout of programme 1, programme 2 and optional LFE. Mono surround
and other intermediate modes retain their distinct speaker masks rather than using only a
channel count.
The encoder performs windowed long/short transforms with transient switching, adaptive
D15/D25/D45 exponent grouping and reuse, standardized masking/bit allocation, grouped and
asymmetric mantissa quantization, and CRC generation. Rate control enforces both AC-3
regional bit budgets as well as the total frame size; sparse frames use bounded skip fields
so auxiliary padding cannot violate the final-three-eighths constraint. LFE receives a
stateful six-pole 120 Hz low-pass before analysis. The initial implementation does not use
channel coupling, stereo rematrixing, AHT, spectral extension, enhanced coupling or VBR;
these are optional coding tools whose absence limits efficiency, particularly at low rates.
The emitted dialogue normalization is 31 and no dynamic-range gain processing is requested.
A 7.1 E-AC-3 packet contains an independent 5.1 compatibility downmix followed by a dependent
substream carrying the original side and rear pairs (`chanmap = 0x1a00`). The compatibility
surrounds average side and rear inputs, **−6 dB per input**, so correlated full-scale signals
retain headroom. This differs from the optional Annex H `dmixtyp=1` −3 dB mix; that metadata
is not signalled. Full 7.1 decoding restores the original surrounds. The `dec3` descriptor
reports one dependent substream and the added rear pair, not the replacement side pair.
`push` accepts arbitrary chunk sizes and returns complete 1536-sample access units.
`finish` drains overlap and returns final packets plus **256 priming samples** and exact
trailing padding; an empty stream returns no packets and zero trimming. A muxer should use
these counts once in its presentation timing. Raw elementary streams do not carry the
original arbitrary sample length, so raw-file consumers cannot recover this trimming by
inspecting the bitstream alone. `codec_configuration()` returns the `dac3` or `dec3` payload,
without its box header, for `ac-3`/`ec-3` sample entries. Dependent syncframes are part of the
same timed packet, not separately timestamped samples. Input validation errors consume no
PCM; an internal encoding error terminates that encoder, and its partial stream must be
discarded rather than retrying input with ambiguous consumption.
`ac3::ProgrammeDecoder::new(expected_layout)` provides a separate, strict complete-access-unit
path for the encoder's six-block E-AC-3 topology. It checks CRCs, bounds, substream order,
layout, block counts and dependent channel maps before publishing PCM. Its explicit
full-range policy does not apply metadata DRC independently to component substreams.
Unsupported topology is rejected rather than reported as a successful reduced-channel decode.
The older single-syncframe decoder's contract is preserved.
Validation includes all sample rates/coding modes, channel isolation, CRC and actual decoder
bit-position checks, short/long transition reconstruction, LFE response, chunk invariance,
invalid input and exact trim accounting. Independent executable checks cover original
impulse/tone/noise boundary stimuli and 7.1 channel identities, plus externally
produced 7.1 programme metadata. Synthetic SNR is a diagnostic, not a perceptual quality
certificate: broad dialogue/music listening, platform player behaviour and peak-memory
qualification remain separate checks. Lossy ringing can exceed the source PCM peak.
## symphonia
symphonia 0.6 (MPL-2.0, used unmodified as the Craft licensing rules require) decodes the formats
marked "symphonia" in [Format support](#format-support). Each is to be replaced by a native
decoder, after which the dependency is removed. The native path is tried first, so a new native
decoder takes its formats over without an API change. Build with `decode-native` instead of
`decode` to see what still needs symphonia.
Notes while symphonia is in use:
- symphonia reads from memory: a file it decodes is read whole first. Its decoded audio still
streams through `Decoder`.
- symphonia allocates sizes taken from the file. Container size fields of WAV, FLAC, MP4 and CAF
files are checked against the file length before symphonia reads them.
- AAC in CAF: the priming is not trimmed and `Decoder::seek` is not sample-exact, as CAF goes
through symphonia.
- A panic inside symphonia is caught and returned as `AudioError::Malformed` only where panics
unwind: native builds with the default `panic = "unwind"`. On `wasm32-unknown-unknown`, and in
an app built with `panic = "abort"`, such a panic aborts. The native decoders do not panic.
- `symphonia-bundle-flac` overflows an `i32` add on 32-bit LPC FLAC; the wrapped value is correct.
Release builds decode correctly; debug builds panic (returned as `Malformed`). Apps that decode
32-bit FLAC need this in the workspace `Cargo.toml` (craft-libs has it):
```toml
[profile.dev.package.symphonia-bundle-flac]
overflow-checks = false
```
## Tests
Both integration test binaries need features, so a plain `cargo test -p craft-audio` runs only
the unit tests. Run everything with:
```bash
cargo test -p craft-audio --all-features
```
Tests that need ffmpeg or the Opus vectors are skipped when those are missing. To fail instead,
set `CRAFT_MEDIA_REQUIRE_ORACLES=1`. The helpers and their variables are shared with craft-media
(see [its tests](../media/README.md#tests)). The test files describe what they check;
`tests/codecs/routing_oracle.rs` is the end-to-end check of containers, codecs, timing, seeking
and track choice against ffmpeg.
The Opus conformance test needs the RFC 8251 vectors (75 MB, not committed). Run the script from
the repository root; it fetches them into `target/fixtures/opus/vectors`. With
`CRAFT_MEDIA_FIXTURES_DIR` set, pass the directory:
```bash
scripts/fetch-opus-vectors.sh
```
```bash
scripts/fetch-opus-vectors.sh "$CRAFT_MEDIA_FIXTURES_DIR/opus/vectors"
```
CI (`.github/workflows/audio.yml`) runs clippy for each feature on its own, rustdoc with warnings
as errors, the WASM build, encode-only and native-only test runs, and an MSRV check. It also runs
the full tests with ffmpeg and the vectors required.
## Origin
| Part | Source |
|---|---|
| WAV, AIFF, `decode`/`probe`, peaks | SoundCraft `soundcraft-audio-io` [7dc56a4](https://github.com/storytold/soundcraft/commit/7dc56a4dbeebf57eacece09536726c57844fc59d) |
| FLAC encoder, AAC, Opus decoder, AC-3, MP1/MP2, Ogg | FilmCraft [8fda2f2](https://github.com/storytold/filmcraft/commit/8fda2f232198c4c79ff9cfe5b6a347bb1375fa9e) |
| MP3 decoder | written here, from ISO/IEC 11172-3 and 13818-3; shares the encoder's tables and the MP1/MP2 synthesis filter |
| MP3 encoder | FilmCraft `filmcraft-mp3enc` [4bec22b](https://github.com/storytold/filmcraft/commit/4bec22bd03bd1d995c9cf72e02a284f96d3d72cd) |
| ALAC | Apple's reference implementation [macosforge/alac@c38887c](https://github.com/macosforge/alac/tree/c38887c5c5e64a4b31108733bd79ca9b2496d987/codec), Copyright © 2011 Apple Inc., Apache-2.0; ported to Rust and modified (see the `alac` module docs and [NOTICE](../../NOTICE)) |
| Opus encoder | EffectCraft `effectcraft-opusenc` [c618429](https://github.com/storytold/effectcraft/commit/c618429252587525a2a6d4b5bccbe4ec5261e1b9) |
| Vorbis encoder | FilmCraft `filmcraft-vorbis` by @JordyUSA ([storytold/filmcraft#4481](https://github.com/storytold/filmcraft/pull/4481)), with partitions of whole sample frames so libvorbis reads surround |
Where apps had overlapping implementations, the one that measured better was kept, with the
tests of both:
| Format | Kept | Reason |
|---|---|---|
| FLAC encoding | FilmCraft | 0.1–37% smaller output than SoundCraft's on 12 test signals; STREAMINFO MD5 |
| WAV/AIFF writing | SoundCraft | only one with BWF, dither, arbitrary speaker masks, streaming without known length |
| AAC-LC, MP1/MP2 decoding | FilmCraft (over symphonia) | equal SNR against ffmpeg; also decodes 5.1 AAC and MP2 bit rates symphonia rejects |
## Migration notes for apps
For the apps switching from their own code; to be removed once all three have switched.
The codec modules' public items keep their names, so apps can re-export them
(`pub use craft_audio::aac::*;`). Names kept only for that are `#[doc(hidden)]`:
`ac3::Decoded` (now `ac3::Frame`), `opus::encoder::OpusEncoder` (now `opus::Encoder`),
`aac::Upsample2x`, `aac::ProgramConfig::parse`,
`aac::config_layout` and `aac::sample_rate_index`. What else an app adjusts:
- `AudioInfo` has `container`, `codec`, `layout` and `damaged` instead of SoundCraft's `format`.
`detect_container` replaces `detect_format`. `probe` reports the layout instead of
`wav_channel_mask`.
- SoundCraft's `FileFormat` tables are `DECODE_EXTENSIONS` (was `readable_extensions`),
`ENCODE_EXTENSIONS` and `encode_format_for` (was `from_write_extension`), and
`EncodeFormat::ALL`, `extension()` and `mime_type()` (were `WRITE`, `default_extension` and
`mime_type`). `aifc` is a writable name here.
- `EncodeOptions` is built with `EncodeOptions::new(format)` and `with_*` methods. It carries the
speaker layout and RF64, which replace `encode_with_layout`, `encode_wav_rf64` and
`FileEncoder::new`'s layout argument. `BwfInfo` and `aac::EncoderConfig` are built the same way
(`with_adts`, …). `ENCODE_EXTENSIONS` is a list.
- Arguments go sample rate, then channels, and channel counts are `u16`:
`FileEncoder::new(out, &opts, sample_rate, channels)`, `wav_float_header(sample_rate,
channels, frames)`, `AudioBuffer::new(sample_rate, channels, frames)`,
`AudioBuffer::from_interleaved` and `num_channels`, and the `ChannelLayout` constructors and
`channels()`.
- `AudioInfo`, `AudioError`, `EncodeOptions`, `BwfInfo`, `SampleFormat`, `BitDepth`, the codec
`Error` enums and the codec modules' header, frame and config structs (but for
`aac::ProgramConfig`) are `#[non_exhaustive]`.
`Speaker::ALL` is a slice.
- `TrackInfo::sample_rate` and `channels` are `Option`s.
- Features are per codec. SoundCraft's `encode` (WAV, AIFF, FLAC) is now `lossless-encode`, made
of `pcm-encode` (WAV, AIFF) and `flac-encode`. `encode` turns on every encoder, including AAC,
ALAC, AC-3/E-AC-3 and Opus. Writing a format whose feature is off returns `AudioError::Unsupported`.
- AAC encoder settings it cannot use are `aac::Error::InvalidSettings` (`AudioError::Encode`).
- The Opus encoder's constructors and `encode_float` return `Result` instead of panicking on an
invalid channel count, mode/bandwidth or frame length.
- `TrackDecoder::decode` returns an error for a corrupt Opus packet, as for the other codecs;
call `conceal`.
- `FileEncoder::write` takes any per-channel slices, but refuses a block with missing channels or
short slices instead of filling them with silence.
- `DecodeOptions` is not `Copy`.
- The FLAC encoder's vendor string is `craft-audio <version>`.
- `decode` tries native decoders first. AAC, ALAC, Opus, AC-3 and MP2 no longer go through symphonia, except AAC in
CAF.
MP4 and Matroska files decode to presentation length. A packet that fails is concealed, not
dropped. A failed source read is `AudioError::Io`.
WAV timestamps use `bext` when present, including a zero timestamp. Otherwise a bounded iXML
`BWFXML/BEXT` time reference supplies the timestamp (two unsigned 32-bit words; an omitted high
word is zero). Only the first iXML chunk is considered. Invalid or oversized optional XML is
ignored without rejecting the audio. This works for byte-backed and streaming sources.