Adds the qoa module behind the qoa, qoa-decode and qoa-encode features:
whole .qoa files, 16-bit, 1 to 8 channels. Streaming files are
unsupported. An ffmpeg oracle test checks that ffmpeg decodes our files
to exactly the samples our decoder returns.
Closes#1541
- EncodeFormat::max_channels gave 65535 for WAV and AIFF, whose headers
hold 32767 (a WAV fewer at wider samples, which the doc now says).
- Tests pin the AAC and MP3 layouts, each format's channel limit with the
count above it, and every listed sample rate with its neighbours: the
agreement test alone compared the tables with a writer that reads them.
- Docs: FileEncoder::bitrate points at the rule RateControl::Bitrate
states; the README says when check exists.
Refs #1230
- EncodeOptions::check says whether a file can be begun, with the error
FileEncoder::new would return and nothing written.
- EncodeOptions::bitrate and FileEncoder::bitrate give the constant bit
rate actually used, after it is moved to one the stream can carry.
- EncodeFormat::sample_rates, max_channels, fixed_layouts, supports_layout
and supports_quality say what a format takes, also when its feature is
off. The writer reads its layouts from the same table, and tests hold
the tables to the encoders and to what the writer accepts.
Refs #1230
- ffmpeg 8 skips an AAC M4A's priming but plays the last packet's padding
(ffmpeg 9 cuts it): the ffmpeg oracle test takes either length, and the
README says which readers end the audio where.
- With alac-encode and no aac-encode, `m4a` names ALAC: the extension test
compared it with AAC.
Refs #1230
- craft-media: Mp4Writer counts written bytes with a checked sum, so a
writer that takes bytes past the last position gets an error, not an
overflow (correction to round 3, which checked only the header).
- Docs: the AAC bit-rate floor keeps a margin above where the encoder
codes silence, about half of it.
Refs #1230
- craft-media: Mp4Writer::new refuses a writer positioned where the header
would end past u64::MAX instead of overflowing the sum (correction to
round 2, which let the M4A writer reach that addition).
- AAC is written at 6 kbit/s or a quarter of the sample rate per channel at
least: the encoder accepts lower rates but codes only silence at them, so
with_bitrate(128) gave a silent file.
- README: what to do with a layout a coded format refuses, and the names
encode_format_for takes for M4A.
Refs #1230
- craft-media: Mp4Writer counts chunk offsets from the first byte of the
file, not from position 0 of the writer, so a file begun mid-writer is
valid. This replaces the seek adapter the M4A writer wrapped its sink in.
- Tests pin the bytes of the roll sample group and each format's feature.
- Docs: ALAC's length comes from the sample durations, not an edit list;
which readers take an empty AAC file; speaker names as the errors print
them; craft-media's README lists roll_distance.
- Error messages for a layout a format has not no longer suggest setting
a layout that was set.
Refs #1230
- craft-media: TrackConfig::roll_distance writes a `roll` sample group
(sgpd + sbgp) over every sample. The AAC M4A track sets -1: Apple's
decoders took 2112 frames of priming and dropped the start of the audio
without it (afinfo now reports the frames written and 1024 priming).
- EncodeFormat::is_built and feature: which formats this build writes.
- Clippy: the writer enum's variants differ in size with flac-encode and
a codec feature but no pcm-encode.
- Tests for the finished sample entry (AAC bit rate, ALAC cookie), ALAC
dither and afinfo's reading of the priming.
- README: ffmpeg's reading of 8-channel AAC, and files with no audio.
Refs #1230
EncodeFormat gains Aac and Alac (M4A through craft-media's MP4 muxer) and
Mp3, Ac3 and Eac3 (raw streams), so one call writes any of them from
WAV-order f32 audio and EncodeOptions.
- EncodeOptions::rate_control (with_bitrate, with_quality): a bit rate is
moved to the nearest one the stream can carry; quality is AAC's VBR.
- Channels are mapped onto the codec's order by speaker, from
EncodeOptions::layout. A layout the format has not is Unsupported
instead of reaching the wrong speakers.
- M4A: the edit list skips the AAC priming, and the last sample's duration
is cut so the track ends at the last frame written.
- encode_format_for, ENCODE_EXTENSIONS and EncodeFormat::ALL list the new
formats; aac-encode and alac-encode now turn on craft-media's isobmff.
Refs #1230
- `Encoder::with_application` checks the channel count before clamping
the bitrate, so 86 channels or more return `Error::Channels` instead
of panicking in `clamp`. Tested with 86 and 255.
- The ffmpeg oracle test skips a missing `opus`/`libopus` decoder
through the testkit's `skip`, so `CRAFT_MEDIA_REQUIRE_ORACLES=1` fails
it.
- README: the encode example pads at least the pre-skip after the audio
before rounding up to a frame, so the encoder delay is flushed; the
MP4 note says an explicit edit replaces the `media_start` edit and
gives its fields.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
EffectCraft's `effectcraft-opusenc` as `opus::encoder` (and
`opus::Encoder`) behind `opus-encode`: SILK, hybrid and CELT, 48 kHz,
20 ms frames, mono or stereo. The constructors and `encode_float`
return `Result` instead of panicking. `Bandwidth` is one type for the
decoder and the encoder, and the two `Mode` enums convert into each
other. `encode` now turns on `opus-encode`.
The encoder tests (modes, ffmpeg's two Opus decoders as oracles) and
`TrackDecoder` on Opus without an `OpusHead` come with it.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A header whose sixth patch is short (96 kHz, start 3, stop 9) was
rejected, though that patch is dropped and five remain.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The SBR decoders now record the layout they were built for and are rebuilt when the
decoder's layout differs, instead of being cleared in set_layout. An access unit whose new
program config fails puts the layout back, and with it the SBR decoders still match.
Refs #1121
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- A VARFIX pointer of 1 marks no transient envelope, like 0.
- A start at QMF channel 32 is valid; kx is checked once the crossover is known.
- The noise and harmonic gains take q / (1 + q) first, so two clamped levels no longer
overflow to infinity and NaN.
- A header that runs past its fill element is refused before it replaces the one in use.
- A new program config layout drops the SBR decoders, whose history was the old order's.
- The ffmpeg oracle requires a high band to compare on every channel but the 5.1 LFE.
Refs #1121
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
aac::Decoder::set_sbr(true) decodes HE-AAC at twice the core rate with the
SBR tool of ISO/IEC 14496-3 §4.6.18: QMF analysis and synthesis, frequency
band tables, patching with LPC inverse filtering, envelope adjustment with
limiter, boost, noise and sinusoids. TrackDecoder uses it in place of the
2x upsampler. Tables are transcribed from ETSI ES 201 980 Annex I.
Matches ffmpeg's decoder on AudioToolbox HE-AAC streams of 1-6 channels:
the same 962-sample delay, ~54 dB SNR, high band level within 0.01 dB.
Parametric stereo is still not decoded.
Refs #1121
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* craft-audio: native MP3 (Layer III) decoder (feature `mp3-decode`)
A clean-room Layer III decoder written from ISO/IEC 11172-3 and 13818-3:
MPEG-1, MPEG-2 and MPEG-2.5 (8-48 kHz), CBR and VBR, mono, stereo, dual
channel and joint stereo (mid/side and intensity), long, short and mixed
blocks, and the bit reservoir. It shares the encoder's Huffman and
scalefactor band tables and the MP1/MP2 synthesis filter.
`decode`, `Decoder` and `TrackDecoder` now read raw .mp3 files and MP3 in
MP4 and Matroska natively instead of through symphonia. A Xing / Info / VBRI
frame is not a packet, and the LAME tag's encoder delay and padding are
applied, so a file decodes to its exact presented length. The seek
pre-roll covers how far back the bit reservoir can reach, so a seek is
bit-exact. symphonia stays the fallback for free-format MP3.
The encoder moves to mp3/encoder.rs so that each half builds without the
other.
* craft-audio: MP3 review and CI fixes
- Huffman: big values stop at the granule's part2_3_length. A damaged
granule no longer reads the next granule's bits, as ffmpeg does.
- Joint stereo runs on the lines in coded order, before short blocks are
reordered, as ffmpeg and libmad do. Where the two channels' block layouts
differ, against the specification, each channel is then reordered by its
own layout.
- Seek pre-roll: sized from the smallest frame the stream can hold (the
lowest bit rate for its version, rate, mode and CRC), not the last frame,
so a seek into a VBR stream's small frames still has the reservoir. The
decoder learns the stream's format from its first frame.
- Mixed-block oracle test: edit only granules whose scalefactors take no
bits, so the edited streams stay valid, and not before a pure short
block. ffmpeg's short-block IMDCT drops overlap that a mixed block's long
subbands carry, where the specification adds it. Use 16 kHz instead of
12 kHz.
- Routing oracle: ffmpeg before 9 decodes the 1105 samples of the MP3
Matroska CodecDelay.
* craft-audio: MPEG audio packets of several frames keep their length
An MP4 or Matroska packet may hold several MP1/MP2/MP3 frames.
TrackDecoder now counts the frames each packet holds from their headers:
- frames_per_packet is None once a packet in the lookahead or a decoded
packet has held several frames, so an MP4 track's length is no longer
capped at one frame per sample and the container's timing decides.
- Concealment is the length of the frames a damaged packet holds. For MP3
a packet lost whole is as long as the last packet, and one frame before
any is decoded.
Also corrects the Huffman doc comment: a big-value pair that starts
before the granule's end is kept whole, as ffmpeg does.
* craft-audio: MPEG audio concealment after partial packets and before the first
- A packet whose later frame fails decodes only in part: like AC-3, it no
longer replaces the length of the last whole packet that concealment
uses.
- MP1/MP2: a packet lost before any has decoded, or right after a seek, is
one frame (384 or 1152 samples) of silence rather than none, as MP3's
already is.
---------
Co-authored-by: alehel <git@ornumhelgaker.no>
* craft-audio: LOAS / LATM framing in the aac module
latm_config and latm_split give a LOAS frame's AudioSpecificConfig and the
payload of its sub-frame: one program, one layer, AAC-LC, frameLengthType 0,
audioMuxVersion 0 or 1. LATM is an AAC transport, so it belongs with the AAC
decoder (feature aac-decode).
Moved from FilmCraft's filmcraft-codecs (crates/codecs/src/audio.rs at
storytold/filmcraft@db60ee4), with its payload-length test; new tests for a
round trip, the refused cases and mutated frames.
* craft-audio: LATM takes its channel count from the configuration's layout
The channel configuration is an index into ISO/IEC 14496-3 Table 1.19: 7 and
12 are eight channels and 11 is seven, and 8-10 and 13-15 are reserved.
latm_config reported the index as the count, and a reserved configuration as
that many channels; it now sums the layout and refuses a reserved one.
Ported from storytold/filmcraft#4297.
* craft-audio: LATM reads a program config element in its StreamMuxConfig
With channel configuration 0 the layout is in a program config element.
latm_config ignored it and reported two channels, so 5.1 in LATM played as
silent stereo. It now reads the element (lining the bits up first, since the
AudioSpecificConfig starts at any bit of the frame and the element aligns to
its bytes), puts it in the AudioSpecificConfig the decoder gets, and refuses
the stream when the element does not parse. With audioMuxVersion 1, what
ascLen counts past the configuration is skipped as fill.
Ported from storytold/filmcraft#4280 (the LATM part).
* craft-audio: README names the LATM functions
* craft-audio: rustfmt the LATM module
---------
Co-authored-by: mpratsaki <110930793+mpratsaki@users.noreply.github.com>
* craft-audio: a program config element in the shape of a channel configuration gets its speakers
An AAC stream with channel configuration 0 whose program config element lists
a centre, a front pair and then exactly the elements of configuration 3 to 6
decoded as C L R Ls Rs LFE and was reported as an unordered layout, so a
caller reading it in WAV order sent the centre to the left speaker. Such a
stream now has the configuration's layout and WAV order. Any other element
list keeps the decoded order, as before.
Ported from storytold/filmcraft#4280 (aac_stream_order in filmcraft-codecs).
* craft-audio: the ADTS program config oracle expects 5.1 in WAV order
ffmpeg 9 writes its 5.1 program config element centre first, so the stream
now has 5.1's speakers: each decoded channel must match ffmpeg's channel of
the same index. An element list in another order keeps the old check.
---------
Co-authored-by: mpratsaki <110930793+mpratsaki@users.noreply.github.com>
wav_pcm and aiff_pcm (feature decode-native) return a file's integer PCM as stored
(RawPcm: little-endian interleaved bytes, 8-bit unsigned, with channels, rate and
bits), built on the existing WAV and AIFF chunk parsers. pcm_wav_file,
pcm_wav_header, pcm_aiff_file and pcm_aiff_header (feature pcm-encode) write the
44-byte canonical WAVE header and the plain AIFF header around such bytes.
For essence embedded in AAF and OMF files, which is moved bit for bit and whose
descriptors hold a bare header as a summary. The writers are FilmCraft's
(filmcraft-interchange wav.rs); the readers replace its second WAV/AIFF parser
with this crate's.
Moves filmcraft-mp3enc (storytold/filmcraft@4bec22b) into craft_audio::mp3,
on craft-media's BitWriter. `encode` turns the feature on, mp3::Error converts
into AudioError::Encode, and a test covers every sample rate and bit rate with
extreme signals.
The existing test sets the decoder's state by hand, so it also passes
with a mid-only flag kept from one frame to the next (the behaviour the
per-frame flag replaced). This one decodes a stereo frame that codes
the flag, then loses a frame: with a kept flag the side channel does
not restart and the test fails.
* craft-audio: AAC Huffman lookahead uses BitReader::peek
`BitReader::peek` reads from one 8-byte load since the bit reader was made
faster, which is what the AAC decoder's private `peek32` did. The private copy
goes; the lookahead is the same zero-padded 32 bits.
Ported from storytold/filmcraft#4232.
* craft-audio: a damaged FLAC keeps its length and timing
symphonia's FLAC demuxer drops a frame whose checksum fails and resyncs on the
next one, so the decoder never saw an error: the file decoded shorter and all
later audio came out one block early, with `damaged` at 0.
The jump in the packet timestamps is the audio that was lost. It is returned
as silence, in blocks of at most 65 536 frames, and counted once in
`AudioInfo::damaged`. It never passes the length the file declares; with no
declared length a jump of more than 2^20 frames is not believed. A seek into
the lost frames lands on silence at the right position.
Ported from storytold/soundcraft#556, onto the streaming decoder.
---------
Co-authored-by: vangel76 <vangel1976@googlemail.com>
Co-authored-by: Gert Pellin <gert@pellin.be>