* audio: pure-Rust Vorbis encoder, and an Ogg page writer in craft-media
Replace the libvorbis wrapper (vorbis_rs, C, desktop only) behind
`vorbis-encode` with FilmCraft's clean-room Vorbis I encoder by
@JordyUSA (storytold/filmcraft#4481), and move its Ogg page writer into
craft-media's `ogg` module.
craft-audio:
- `vorbis::encoder::{Encoder, EncoderConfig, Error}`: 1-8 channels in
Vorbis order, any sample rate, quality -1 to 10 (VBR), streaming
packets with granule positions.
- `encode_ogg_vorbis` with `OggVorbisOptions` (quality, vendor, tags,
serial) writes a whole Ogg Vorbis file with a comment header.
- `encode_ogg(buf, kbps)` and `OGG_BITRATES` keep working: the bit rate
picks the quality whose nominal rate it is (`quality_for_bitrate`).
- `encode` with `EncodeFormat::Ogg` takes 1-8 channel WAV-order layouts
and writes them in Vorbis order, and `RateControl::Quality`.
- Ogg is built on wasm32 too.
- Residue partitions hold whole sample frames (48, 40, 48 or 56 values
for 3, 5, 6 and 7 channels): libvorbis decodes each partition from
channel 0, so 32-value partitions came out scrambled for those counts.
- The first audio packet gets a page of its own, so a short file's
first audio page is never also its last (ffmpeg then kept the padding).
craft-media: `ogg::PageWriter`, `opus_tags`, `vorbis_comment`.
Part of storytold/craft-libs#778.
* audio, media: address review on the Vorbis encoder and Ogg writer
- Encoder: read cursor into the pending input, compacted once per call,
so a large encode() call no longer moves the tail on every block.
- Tests: check ffmpeg's libvorbis decoder only when ffmpeg has it.
- PageWriter::finish: the end granule replaces the last page's only when
a packet completes on it (RFC 7845 4.4); documented and tested.
- README: Ogg Opus packet granules are the samples decoded so far.
* audio: pick Ogg by extension on wasm32 too
The Vorbis encoder is pure Rust now, so encode_format_for("ogg") follows
the vorbis-encode feature alone, as EncodeFormat::Ogg.is_built() and
ENCODE_EXTENSIONS already do.
Older ffmpeg releases decode IMA and Flash ADPCM with the
((2 * magnitude + 1) * step) rounding; the tests accept either that or the
recommended-practice one.
Constant bit rate mono and stereo at 16-48 kHz, written from ISO/IEC
11172-3 and 13818-3. Decoded by our decoder and by ffmpeg as an
oracle.
Closes#1545.
Adds flac::decode for whole files and flac::Decoder for single frames:
RFC 9639 subframes (constant, verbatim, fixed, LPC), Rice and escaped
partitions, wasted bits, all stereo modes, fixed and variable block
sizes, 4 to 32 bits, CRC-8 and CRC-16 checked. Not yet wired into
craft_audio::decode, which still uses symphonia for FLAC.
Part of #1546
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
- media: correct round 1's frame placement. The picture's position is
not one value for a file: it starts at the screen's corner and a
frame with data that is as large as the picture and not at the corner
moves it for the frames that follow, as ffmpeg was seen to do.
`picture_rect` now takes the frame's index; `origin()` is gone.
- audio: unknown frame flags are refused for an empty frame too.
- video: count the unpack buffer in the picture budget.
- docs: which sound frames are bounded by what, which cut-short blocks
are errors, and why sound needs both the flag and a rate.
- tests: ffmpeg's placement cases, the size of the LZ stop, multi-block
16-bit stereo frames, and an LZ test that compared half its picture.
- media: place video frames by the first frame as large as the picture,
not by the header's position fields, as ffmpeg was seen to do; a
frame outside the picture has no rectangle.
- media: a file has sound only with the header flag and a sample rate.
- video: stop LZ unpacking at what a picture can use, so a frame's cost
no longer goes by a length the file states.
- audio: a flags 1 sound frame plays every whole block it holds.
- docs: how sound lines up with pictures, what the buffer count is, and
which cut-short blocks are errors.
- tests: the frame-count cap, the 0xFF tag near the end of LZ data,
palette components over 6 bits, the error conversion and the new
identifiers.
Sierra VMD (Video and Music Data) is the video format of Sierra and
Coktel Vision games of the 1990s. Written clean-room from the public
format description at https://wiki.multimedia.cx/index.php/VMD, with
ffmpeg as a black-box oracle.
- craft-media: `vmd` feature, a demuxer for the 816-byte header and the
table of contents; `Container::Vmd`, `CodecId::VmdVideo` and
`CodecId::VmdAudio`.
- craft-video: `vmd` feature, a decoder for 8-bit paletted pictures
(rendering methods 1 to 3, LZ packing, palette changes).
- craft-audio: `vmd-decode` feature, a decoder for 8-bit PCM and 16-bit
DPCM sound, mono and stereo.
- craft-media-testkit: a VMD fixture writer, since ffmpeg reads VMD but
cannot write it.
Tests compare the decoders with ffmpeg on generated files, and on real
files when CRAFT_MEDIA_VMD_SAMPLES names a directory of them. 16-bit,
24-bit and Indeo 3 pictures, IMA ADPCM sound and the later header
revisions are not decoded.
- 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::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