Integrate shared main after USD LZ4 prerequisite merge

This commit is contained in:
Dylan M. Taylor
2026-11-15 17:05:33 -05:00
57 changed files with 5237 additions and 1247 deletions
Generated
-34
View File
@@ -222,16 +222,6 @@ version = "1.0.104"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
[[package]]
name = "aotuv_lancer_vorbis_sys"
version = "0.1.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5bc4fd1a61860d2f1198b60bedd30910eaffa978f1ee6214dfb24ac70d589225"
dependencies = [
"cc",
"ogg_next_sys",
]
[[package]]
name = "arbitrary"
version = "1.5.0"
@@ -1414,7 +1404,6 @@ dependencies = [
"serde_json",
"symphonia",
"thiserror 2.0.21",
"vorbis_rs",
]
[[package]]
@@ -6826,15 +6815,6 @@ dependencies = [
"phf 0.11.3",
]
[[package]]
name = "ogg_next_sys"
version = "0.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ed2d7a48e247c2bb07e633aefb65a38648ea58c7eedd4e4408a5861721ab049b"
dependencies = [
"cc",
]
[[package]]
name = "oid-registry"
version = "0.8.1"
@@ -10653,20 +10633,6 @@ version = "0.9.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
[[package]]
name = "vorbis_rs"
version = "0.5.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "49c5da94d280f7a27e8c937e9b73df2da3e23a2583f48471fd8fb4c72f9c1933"
dependencies = [
"aotuv_lancer_vorbis_sys",
"errno",
"getrandom 0.4.3",
"ogg_next_sys",
"thiserror 2.0.21",
"tinyvec",
]
[[package]]
name = "wait-timeout"
version = "0.2.1"
+4 -6
View File
@@ -1,6 +1,6 @@
[package]
name = "craft-audio"
description = "Audio file I/O and codecs: WAV/AIFF read and write, FLAC encoder, AAC and ALAC decoders and encoders, AC-3/E-AC-3 decoder and encoder, MP3 decoder and encoder, Opus decoder and encoder, MP1/MP2 decoders."
description = "Audio file I/O and codecs: WAV/AIFF read and write, FLAC encoder, AAC and ALAC decoders and encoders, AC-3/E-AC-3 decoder and encoder, MP3 decoder and encoder, Opus decoder and encoder, Vorbis encoder, MP1/MP2 decoders."
version.workspace = true
edition.workspace = true
license.workspace = true
@@ -31,8 +31,9 @@ lossless-encode = ["pcm-encode", "flac-encode"]
pcm-encode = []
# Encode FLAC files.
flac-encode = ["craft-media/bitstream"]
# Encode Ogg Vorbis files (desktop only: builds the reference libvorbis from its C sources).
vorbis-encode = ["dep:vorbis_rs"]
# The pure-Rust Vorbis encoder (`vorbis::encoder`) and Ogg Vorbis files through `encode` and
# `encode_ogg_vorbis`.
vorbis-encode = ["craft-media/ogg"]
# Codec modules on their own, for packet-level use.
aac-decode = ["craft-media/bitstream"]
# The AAC encoder (`aac::Encoder`), and AAC in M4A through `encode` and `FileEncoder`.
@@ -72,9 +73,6 @@ rayon = { workspace = true, optional = true }
# symphonia keeps its AAC decoder for AAC in CAF, a container craft-media does not read.
symphonia = { version = "0.6.1", optional = true, default-features = false, features = ["mp3", "flac", "vorbis", "ogg", "wav", "pcm", "aiff", "isomp4", "aac", "alac", "adpcm", "caf", "mkv"] }
[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
vorbis_rs = { version = "0.5", optional = true }
[dev-dependencies]
craft-media-testkit = { workspace = true }
proptest = { workspace = true }
+30 -3
View File
@@ -29,7 +29,7 @@ No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayou
| `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` |
| `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-encode` | `encode`, `FileEncoder` for FLAC; `flac::Encoder`, the packet encoder for callers that mux FLAC themselves | craft-media `bitstream` |
@@ -37,6 +37,7 @@ No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayou
| `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` |
@@ -355,8 +356,12 @@ 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.
craft-media has no Ogg muxer, so `.opus` files cannot be written yet; Opus goes into
Matroska/WebM or MP4:
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
@@ -368,6 +373,27 @@ Matroska/WebM or MP4:
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
@@ -704,6 +730,7 @@ the full tests with ffmpeg and the vectors required.
| 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:
+24 -12
View File
@@ -13,6 +13,8 @@
//! demuxers and [`TrackDecoder`]; everything else (FLAC, Vorbis, CAF, ADPCM, A-law, µ-law) through
//! `symphonia`, which is to be replaced by native decoders. Feature `decode-native` is the
//! same without symphonia.
//! - [`encode_ogg_vorbis`] and [`vorbis::encoder`] (feature `vorbis-encode`): Ogg Vorbis files
//! and Vorbis packets from a pure-Rust encoder, 1 to 8 channels, quality -1 to 10, with tags.
//! - [`TrackDecoder`] (any decoder feature): one track's packets from any demuxer to planar
//! `f32` in WAV channel order.
//! - [`encode`], [`FileEncoder`]: WAV/BWF/RF64 and AIFF/AIFF-C (feature `pcm-encode`, which also
@@ -56,8 +58,12 @@ pub mod qoa;
mod read;
#[cfg(any(feature = "aac-decode", feature = "alac-decode", feature = "opus-decode", feature = "ac3-decode", feature = "mpa-decode"))]
mod track;
#[cfg(feature = "vorbis-encode")]
pub mod vorbis;
#[cfg(any(feature = "decode-native", feature = "pcm-encode"))]
mod wav;
/// Bounded WAV/RF64 cue, adtl and XMP marker metadata, without audio decoding.
pub mod wav_markers;
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
@@ -73,7 +79,7 @@ mod write;
/// Range-backed PCM WAVE access and a 16-bit PCM writer.
pub mod wav_range;
#[cfg(feature = "vorbis-encode")]
pub use write::{OGG_BITRATES, encode_ogg};
pub use write::{OGG_BITRATES, OggVorbisOptions, encode_ogg, encode_ogg_vorbis, quality_for_bitrate};
/// The FLAC packet encoder (RFC 9639), for a caller that muxes FLAC itself (into MP4, Matroska or
/// its own `.flac` writer): planar integer samples in, frames out, and the STREAMINFO to patch in
@@ -276,7 +282,9 @@ pub enum EncodeFormat {
Ac3,
/// An E-AC-3 stream: up to 7.1 at 32, 44.1 or 48 kHz.
Eac3,
/// Ogg Vorbis, whole-buffer encoding only.
/// Ogg Vorbis, 1–8 channels at any sample rate, whole-buffer encoding only. Variable bit
/// rate: a [`RateControl::Bitrate`] picks the quality whose nominal rate it is
/// ([`quality_for_bitrate`]), [`RateControl::Quality`] sets it directly.
Ogg,
}
@@ -377,7 +385,7 @@ impl EncodeFormat {
EncodeFormat::Mp3 => cfg!(feature = "mp3-encode"),
EncodeFormat::Ac3 => cfg!(feature = "ac3-encode"),
EncodeFormat::Eac3 => cfg!(feature = "eac3-encode"),
EncodeFormat::Ogg => cfg!(all(feature = "vorbis-encode", not(target_arch = "wasm32"))),
EncodeFormat::Ogg => cfg!(feature = "vorbis-encode"),
}
}
@@ -398,9 +406,9 @@ impl EncodeFormat {
pub fn max_channels(self) -> u16 {
match self {
EncodeFormat::Wav | EncodeFormat::Aiff => 32_767,
EncodeFormat::Flac | EncodeFormat::Aac | EncodeFormat::Alac | EncodeFormat::Eac3 => 8,
EncodeFormat::Flac | EncodeFormat::Aac | EncodeFormat::Alac | EncodeFormat::Eac3 | EncodeFormat::Ogg => 8,
EncodeFormat::Ac3 => 6,
EncodeFormat::Mp3 | EncodeFormat::Ogg => 2,
EncodeFormat::Mp3 => 2,
}
}
@@ -414,7 +422,10 @@ impl EncodeFormat {
EncodeFormat::Aac => &[&[0x4], &[0x3], &[0x7], &[0x107], &[0x607], &[0x60F], &[0x70F], &[0xFF]],
// Apple's layout tags for 1–8 channels, surrounds as back speakers.
EncodeFormat::Alac => &[&[0x4], &[0x3], &[0x7], &[0x107], &[0x37], &[0x3F], &[0x13F], &[0xFF]],
EncodeFormat::Mp3 | EncodeFormat::Ogg => &[&[0x4], &[0x3]],
EncodeFormat::Mp3 => &[&[0x4], &[0x3]],
// The Vorbis I §4.3.9 layouts for 1–8 channels (6.1 with a back centre and sides, 7.1
// with sides and backs), written in Vorbis order.
EncodeFormat::Ogg => &[&[0x4], &[0x3], &[0x7], &[0x33], &[0x37], &[0x3F], &[0x70F], &[0x63F]],
// The coding modes 1/0 to 3/2 with and without an LFE, by channel count.
EncodeFormat::Ac3 => &[&[0x4], &[0x3, 0xC], &[0x7, 0x103, 0xB], &[0x107, 0x603, 0xF, 0x10B], &[0x607, 0x10F, 0x60B], &[0x60F]],
// The same, and 7.1 with backs and sides.
@@ -456,10 +467,10 @@ impl EncodeFormat {
}
}
/// Whether the format takes [`RateControl::Quality`]: AAC. The other lossy formats are
/// written at a constant bit rate only.
/// Whether the format takes [`RateControl::Quality`]: AAC and Ogg Vorbis. The other lossy
/// formats are written at a constant bit rate only.
pub fn supports_quality(self) -> bool {
self == EncodeFormat::Aac
matches!(self, EncodeFormat::Aac | EncodeFormat::Ogg)
}
/// Whether the format loses audio: AAC, MP3, AC-3 and E-AC-3. These take
@@ -478,11 +489,12 @@ pub enum RateControl {
/// set of rates (MP3, AC-3) uses the highest one not above it; a rate outside what the
/// stream can carry is moved to the nearest one inside. AAC is written at 6 kbit/s or a
/// quarter of the sample rate per channel at least: from about half of that down its encoder
/// codes silence. Vorbis treats this as a VBR target (64–500 kbit/s), falling back to
/// a quality preset when that target is unsupported; it does not promise a constant bitrate.
/// codes silence. Vorbis takes 64–500 kbit/s and writes the quality whose nominal rate that is
/// ([`quality_for_bitrate`]); its rate varies with the audio.
Bitrate(u32),
/// A constant quality from 0.0 (smallest) to 1.0 (best), at whatever bit rate each frame
/// needs. AAC only; values outside the range are clamped, and NaN is an error.
/// needs. AAC and Vorbis (0.0 is Vorbis quality -1, 1.0 quality 10); values outside the range
/// are clamped, and NaN is an error.
Quality(f32),
}
+1 -135
View File
@@ -4,141 +4,7 @@
//! producing the N/2 "folded" time samples; the window overlap region is then unfolded against the
//! folded tail of the previous block, which the caller keeps in place in the output buffer.
#[derive(Clone, Copy, Default, Debug)]
pub struct Cpx {
pub re: f32,
pub im: f32,
}
impl Cpx {
#[inline]
fn mul(self, o: Cpx) -> Cpx {
Cpx { re: self.re * o.re - self.im * o.im, im: self.re * o.im + self.im * o.re }
}
#[inline]
fn add(self, o: Cpx) -> Cpx {
Cpx { re: self.re + o.re, im: self.im + o.im }
}
#[inline]
fn sub(self, o: Cpx) -> Cpx {
Cpx { re: self.re - o.re, im: self.im - o.im }
}
}
/// Mixed-radix (2, 3, 4, 5) forward complex FFT, unscaled. Radix 2, 3 and 4 use dedicated
/// butterflies; radix 5 uses a generic one.
pub struct Fft {
n: usize,
factors: Vec<usize>,
twiddle: Vec<Cpx>,
}
impl Fft {
pub fn new(n: usize) -> Fft {
let mut factors = Vec::new();
let mut m = n;
for p in [4usize, 2, 3, 5] {
while m.is_multiple_of(p) {
factors.push(p);
m /= p;
}
}
assert_eq!(m, 1, "unsupported FFT size {n}");
let twiddle = (0..n)
.map(|k| {
let ph = -2.0 * std::f64::consts::PI * k as f64 / n as f64;
Cpx { re: ph.cos() as f32, im: ph.sin() as f32 }
})
.collect();
Fft { n, factors, twiddle }
}
pub fn process(&self, data: &mut [Cpx], scratch: &mut Vec<Cpx>) {
scratch.clear();
scratch.extend_from_slice(&data[..self.n]);
self.rec(&mut data[..self.n], scratch, 1, self.n, 0, 1);
}
fn rec(&self, out: &mut [Cpx], inp: &[Cpx], in_stride: usize, n: usize, fi: usize, tw_stride: usize) {
let p = self.factors[fi];
let m = n / p;
if m == 1 {
for (i, o) in out.iter_mut().enumerate().take(p) {
*o = inp[i * in_stride];
}
} else {
for q in 0..p {
self.rec(&mut out[q * m..(q + 1) * m], &inp[q * in_stride..], in_stride * p, m, fi + 1, tw_stride * p);
}
}
let tw = &self.twiddle;
match p {
2 => {
for k in 0..m {
let a0 = out[k];
let a1 = out[m + k].mul(tw[k * tw_stride]);
out[k] = a0.add(a1);
out[m + k] = a0.sub(a1);
}
}
4 => {
for k in 0..m {
let t0 = out[k];
let t1 = out[m + k].mul(tw[k * tw_stride]);
let t2 = out[2 * m + k].mul(tw[2 * k * tw_stride]);
let t3 = out[3 * m + k].mul(tw[3 * k * tw_stride]);
let s0 = t0.add(t2);
let d0 = t0.sub(t2);
let s1 = t1.add(t3);
let d1 = t1.sub(t3);
out[k] = s0.add(s1);
out[2 * m + k] = s0.sub(s1);
// -j * d1 = (d1.im, -d1.re)
out[m + k] = Cpx { re: d0.re + d1.im, im: d0.im - d1.re };
out[3 * m + k] = Cpx { re: d0.re - d1.im, im: d0.im + d1.re };
}
}
3 => {
// sin(-2*pi/3) = -sqrt(3)/2
let h = tw[self.n / 3].im;
for k in 0..m {
let t0 = out[k];
let t1 = out[m + k].mul(tw[k * tw_stride]);
let t2 = out[2 * m + k].mul(tw[2 * k * tw_stride]);
let s = t1.add(t2);
let d = t1.sub(t2);
let a = Cpx { re: t0.re - 0.5 * s.re, im: t0.im - 0.5 * s.im };
out[k] = t0.add(s);
// j * h * d = (-h * d.im, h * d.re)
out[m + k] = Cpx { re: a.re - h * d.im, im: a.im + h * d.re };
out[2 * m + k] = Cpx { re: a.re + h * d.im, im: a.im - h * d.re };
}
}
_ => {
// Radix 5 (at most once per transform): generic butterfly with the five roots of
// unity looked up once.
let mut w5 = [Cpx::default(); 5];
for (q, w) in w5.iter_mut().enumerate() {
*w = tw[q * (self.n / p)];
}
let mut t = [Cpx::default(); 5];
for k in 0..m {
t[0] = out[k];
for q in 1..p {
t[q] = out[q * m + k].mul(tw[q * k * tw_stride]);
}
for q2 in 0..p {
let mut acc = t[0];
for q in 1..p {
acc = acc.add(t[q].mul(w5[(q * q2) % p]));
}
out[q2 * m + k] = acc;
}
}
}
}
}
}
use crate::opus::fft::{Cpx, Fft};
pub struct Imdct {
/// Full MDCT length (2x the number of coefficients).
+19 -327
View File
@@ -1,272 +1,45 @@
//! Pulse cache and bit allocation (RFC 6716 §4.3.3, §4.3.4.1).
use super::tables::{ALLOC, EBANDS, LOG2_FRAC_TABLE, MAX_LM, NB_EBANDS, OVERLAP};
use super::tables::{EBANDS, LOG2_FRAC_TABLE, MAX_LM, NB_EBANDS, OVERLAP};
use crate::opus::decode::range::{BITRES, RangeDecoder};
const MAX_PSEUDO: i32 = 40;
const LOG_MAX_PSEUDO: i32 = 6;
pub use crate::opus::rate_common::get_pulses;
#[cfg(test)]
use crate::opus::rate_common::log2_frac;
#[cfg(test)]
pub use crate::opus::rate_common::pvq_v;
pub const MAX_FINE_BITS: i32 = 8;
const FINE_OFFSET: i32 = 21;
pub const QTHETA_OFFSET: i32 = 4;
pub const QTHETA_OFFSET_TWOPHASE: i32 = 16;
const ALLOC_STEPS: i32 = 6;
/// Number of pulses represented by pseudo-pulse index `i`.
pub fn get_pulses(i: i32) -> i32 {
if i < 8 { i } else { (8 + (i & 7)) << ((i >> 3) - 1) }
}
/// Conservative (rounded up) log2 of `val` with `frac` fractional bits.
pub fn log2_frac(mut val: u32, mut frac: u32) -> i32 {
let mut l = crate::opus::decode::range::ilog(val);
if val & val.wrapping_sub(1) != 0 {
if l > 16 {
val = ((val - 1) >> (l - 16)) + 1;
} else {
val <<= 16 - l;
}
let mut l = (l - 1) << frac;
loop {
let b = (val >> 16) as i32;
l += b << frac;
val = (val + b as u32) >> b;
val = (val * val + 0x7FFF) >> 15;
if frac == 0 {
break;
}
frac -= 1;
}
l + (val > 0x8000) as i32
} else {
l -= 1;
l << frac
}
}
/// PVQ codebook size V(N, K) as u128 (saturating far above 2^32).
pub fn pvq_v(n: usize, k: usize) -> u128 {
// V(N,K) = V(N-1,K) + V(N,K-1) + V(N-1,K-1); computed row by row.
if k == 0 {
return 1;
}
if n == 0 {
return 0;
}
let mut row = vec![0u128; k + 1]; // V(0, k)
row[0] = 1;
for _ in 0..n {
let mut prev_diag = row[0]; // V(n-1, 0)
// V(n, 0) = 1
for kk in 1..=k {
let up = row[kk]; // V(n-1, kk)
let v = up.saturating_add(row[kk - 1]).saturating_add(prev_diag);
prev_diag = up;
row[kk] = v.min(u128::MAX >> 8);
}
row[0] = 1;
}
row[k]
}
fn fits_in32(n: usize, k: i32) -> bool {
pvq_v(n, k as usize) <= u32::MAX as u128
}
/// Precomputed per-mode data shared by all CELT decoders.
/// Decoder mode: shared allocation tables and decoder-specific inverse transforms.
pub struct Mode {
/// log2 of band width in 1/8 bits.
pub log_n: [i32; NB_EBANDS],
/// Index into `cache_bits` for `(LM+1)*NB_EBANDS + band` (-1 when unused).
pub cache_index: Vec<i16>,
/// `cache[0]` = max pseudo-pulses; `cache[k]` = bits(k) - 1 in 1/8 bits.
pub cache_bits: Vec<u8>,
/// Per-band maximum allocation: `[(2*LM + C-1)*NB_EBANDS + band]`.
pub caps: Vec<u8>,
core: crate::opus::rate_common::Mode,
pub window: [f32; OVERLAP],
pub mdct: [super::mdct::Imdct; MAX_LM + 1],
}
impl Mode {
pub fn new() -> Mode {
let mut log_n = [0i32; NB_EBANDS];
for (i, l) in log_n.iter_mut().enumerate() {
*l = log2_frac((EBANDS[i + 1] - EBANDS[i]) as u32, BITRES);
}
let (cache_index, cache_bits) = compute_pulse_cache(MAX_LM as i32);
let mut m = Mode {
log_n,
cache_index,
cache_bits,
caps: Vec::new(),
pub fn new() -> Self {
let mut mode = Self {
core: crate::opus::rate_common::Mode::new(),
window: [0.0; OVERLAP],
mdct: [super::mdct::Imdct::new(1920), super::mdct::Imdct::new(960), super::mdct::Imdct::new(480), super::mdct::Imdct::new(240)],
};
m.caps = compute_caps(&m);
for i in 0..OVERLAP {
let x = std::f64::consts::FRAC_PI_2 * (i as f64 + 0.5) / OVERLAP as f64;
let s = x.sin();
m.window[i] = (std::f64::consts::FRAC_PI_2 * s * s).sin() as f32;
mode.window[i] = (std::f64::consts::FRAC_PI_2 * s * s).sin() as f32;
}
m
}
#[inline]
pub fn cache(&self, lm: i32, band: usize) -> &[u8] {
let idx = self.cache_index[((lm + 1) as usize) * NB_EBANDS + band];
&self.cache_bits[idx.max(0) as usize..]
}
pub fn bits2pulses(&self, band: usize, lm: i32, bits: i32) -> i32 {
let cache = self.cache(lm, band);
let mut lo = 0i32;
let mut hi = cache[0] as i32;
let bits = bits - 1;
for _ in 0..LOG_MAX_PSEUDO {
let mid = (lo + hi + 1) >> 1;
if cache[mid as usize] as i32 >= bits {
hi = mid;
} else {
lo = mid;
}
}
let lo_bits = if lo == 0 { -1 } else { cache[lo as usize] as i32 };
if bits - lo_bits <= cache[hi as usize] as i32 - bits { lo } else { hi }
}
pub fn pulses2bits(&self, band: usize, lm: i32, pulses: i32) -> i32 {
if pulses == 0 { 0 } else { self.cache(lm, band)[pulses as usize] as i32 + 1 }
}
/// Per-band allocation caps for this frame (`init_caps`).
pub fn init_caps(&self, lm: usize, c: usize) -> [i32; NB_EBANDS] {
let mut cap = [0i32; NB_EBANDS];
for (i, cp) in cap.iter_mut().enumerate() {
let n = (EBANDS[i + 1] - EBANDS[i]) << lm;
*cp = ((self.caps[NB_EBANDS * (2 * lm + c - 1) + i] as i32 + 64) * c as i32 * n) >> 2;
}
cap
mode
}
}
fn compute_pulse_cache(lm_max: i32) -> (Vec<i16>, Vec<u8>) {
let nb = NB_EBANDS;
let rows = (lm_max + 2) as usize;
let mut index = vec![-1i16; nb * rows];
let mut entries: Vec<(usize, i32, usize)> = Vec::new(); // (N, K, offset)
let mut curr = 0usize;
for i in 0..rows {
for j in 0..nb {
let n = (((EBANDS[j + 1] - EBANDS[j]) << i) >> 1) as usize;
index[i * nb + j] = -1;
// Reuse the entry of an earlier band with the same size.
'search: for k in 0..=i {
for nn in 0..nb {
if k == i && nn >= j {
break;
}
if n == (((EBANDS[nn + 1] - EBANDS[nn]) << k) >> 1) as usize {
index[i * nb + j] = index[k * nb + nn];
break 'search;
}
}
}
if index[i * nb + j] == -1 && n != 0 {
let mut k = 0;
while k < MAX_PSEUDO && fits_in32(n, get_pulses(k + 1)) {
k += 1;
}
index[i * nb + j] = curr as i16;
entries.push((n, k, curr));
curr += (k + 1) as usize;
}
}
impl std::ops::Deref for Mode {
type Target = crate::opus::rate_common::Mode;
fn deref(&self) -> &Self::Target {
&self.core
}
let mut bits = vec![0u8; curr];
for &(n, k, off) in &entries {
let maxk = get_pulses(k) as usize;
let tmp = required_bits(n, maxk, BITRES);
for j in 1..=k {
bits[off + j as usize] = (tmp[get_pulses(j) as usize] - 1) as u8;
}
bits[off] = k as u8;
}
(index, bits)
}
/// Bits (1/2^frac units, rounded up) needed for each K in `0..=maxk` for dimension `n`.
fn required_bits(n: usize, maxk: usize, frac: u32) -> Vec<i32> {
let mut out = vec![0i32; maxk + 1];
if n == 1 {
for o in out.iter_mut().skip(1) {
*o = 1 << frac;
}
} else {
for (k, o) in out.iter_mut().enumerate().skip(1) {
let v = pvq_v(n, k);
*o = log2_frac(v as u32, frac);
}
}
out
}
fn compute_caps(m: &Mode) -> Vec<u8> {
let nb = NB_EBANDS;
let mut caps = vec![0u8; (MAX_LM + 1) * 2 * nb];
for i in 0..=MAX_LM as i32 {
for c in 1..=2i32 {
for j in 0..nb {
let mut n0 = EBANDS[j + 1] - EBANDS[j];
let max_bits = if n0 << i == 1 {
(c * (1 + MAX_FINE_BITS)) << BITRES
} else {
let mut lm0 = 0;
if n0 > 2 {
n0 >>= 1;
lm0 -= 1;
} else if n0 <= 1 {
lm0 = i.min(1);
n0 <<= lm0;
}
let pcache = m.cache(lm0, j);
let mut mb = pcache[pcache[0] as usize] as i32 + 1;
let mut n = n0;
for k in 0..(i - lm0) {
mb <<= 1;
let offset = ((m.log_n[j] + ((lm0 + k) << BITRES)) >> 1) - QTHETA_OFFSET;
let num = 459 * ((2 * n - 1) * offset + mb);
let den = ((2 * n - 1) << 9) - 459;
let qb = ((num + (den >> 1)) / den).min(57);
mb += qb;
n <<= 1;
}
if c == 2 {
mb <<= 1;
let offset = ((m.log_n[j] + (i << BITRES)) >> 1) - if n == 2 { QTHETA_OFFSET_TWOPHASE } else { QTHETA_OFFSET };
let ndof = 2 * n - 1 - (n == 2) as i32;
let p = if n == 2 { 512 } else { 487 };
let num = p * (mb + ndof * offset);
let den = (ndof << 9) - p;
let qb = ((num + (den >> 1)) / den).min(if n == 2 { 64 } else { 61 });
mb += qb;
}
let ndof = c * n + if c == 2 && n > 2 { 1 } else { 0 };
let mut offset = ((m.log_n[j] + (i << BITRES)) >> 1) - FINE_OFFSET;
if n == 2 {
offset += (1 << BITRES) >> 2;
}
let num = mb + ndof * offset;
let den = (ndof - 1) << BITRES;
let qb = ((num + (den >> 1)) / den).min(MAX_FINE_BITS);
mb += (c * qb) << BITRES;
mb
};
let w = c * ((EBANDS[j + 1] - EBANDS[j]) << i);
let v = (4 * max_bits / w) - 64;
caps[((i * 2 + c - 1) as usize) * nb + j] = v.clamp(0, 255) as u8;
}
}
}
caps
}
/// Result of the allocation process.
@@ -296,89 +69,8 @@ pub struct AllocationInput<'a, 'd> {
pub fn compute_allocation(input: AllocationInput<'_, '_>) -> Allocation {
let AllocationInput { mode: m, start, end, offsets, cap, trim: alloc_trim, total, channels: c, lm, decoder: dec } = input;
let ci = c as i32;
let lmi = lm as i32;
let mut total = total.max(0);
let mut skip_start = start;
let skip_rsv = if total >= 1 << BITRES { 1 << BITRES } else { 0 };
total -= skip_rsv;
let mut intensity_rsv = 0;
let mut dual_stereo_rsv = 0;
if c == 2 {
intensity_rsv = LOG2_FRAC_TABLE[end - start];
if intensity_rsv > total {
intensity_rsv = 0;
} else {
total -= intensity_rsv;
dual_stereo_rsv = if total >= 1 << BITRES { 1 << BITRES } else { 0 };
total -= dual_stereo_rsv;
}
}
let mut bits1 = [0i32; NB_EBANDS];
let mut bits2 = [0i32; NB_EBANDS];
let mut thresh = [0i32; NB_EBANDS];
let mut trim_offset = [0i32; NB_EBANDS];
for j in start..end {
let w = EBANDS[j + 1] - EBANDS[j];
thresh[j] = (ci << BITRES).max(((3 * w) << lmi << BITRES) >> 4);
trim_offset[j] = (ci * w * (alloc_trim - 5 - lmi) * (end as i32 - j as i32 - 1) * (1 << (lmi + BITRES as i32))) >> 6;
if w << lmi == 1 {
trim_offset[j] -= ci << BITRES;
}
}
let nb_alloc = ALLOC.len() as i32;
let mut lo = 1;
let mut hi = nb_alloc - 1;
loop {
let mut done = false;
let mut psum = 0;
let mid = (lo + hi) >> 1;
for j in (start..end).rev() {
let n = EBANDS[j + 1] - EBANDS[j];
let mut bitsj = (ci * n * (ALLOC[mid as usize][j] as i32)) << lmi >> 2;
if bitsj > 0 {
bitsj = (bitsj + trim_offset[j]).max(0);
}
bitsj += offsets[j];
if bitsj >= thresh[j] || done {
done = true;
psum += bitsj.min(cap[j]);
} else if bitsj >= ci << BITRES {
psum += ci << BITRES;
}
}
if psum > total {
hi = mid - 1;
} else {
lo = mid + 1;
}
if lo > hi {
break;
}
}
hi = lo;
lo -= 1;
for j in start..end {
let n = EBANDS[j + 1] - EBANDS[j];
let mut bits1j = (ci * n * (ALLOC[lo as usize][j] as i32)) << lmi >> 2;
let mut bits2j = if hi >= nb_alloc { cap[j] } else { (ci * n * (ALLOC[hi as usize][j] as i32)) << lmi >> 2 };
if bits1j > 0 {
bits1j = (bits1j + trim_offset[j]).max(0);
}
if bits2j > 0 {
bits2j = (bits2j + trim_offset[j]).max(0);
}
if lo > 0 {
bits1j += offsets[j];
}
bits2j += offsets[j];
if offsets[j] > 0 {
skip_start = j;
}
bits2j = (bits2j - bits1j).max(0);
bits1[j] = bits1j;
bits2[j] = bits2j;
}
let crate::opus::rate_common::Bracket { skip_start, bits1, bits2, thresh, total, skip_rsv, intensity_rsv, dual_stereo_rsv } =
crate::opus::rate_common::bracket(start, end, offsets, cap, alloc_trim, total, c, lm);
interp_bits2pulses(InterpPulsesInput {
mode: m,
start,
@@ -14,6 +14,7 @@ pub const MAX_LM: usize = 3;
pub const PREEMPH: f32 = 0.850_006_1;
/// Static allocation table (Table 57), indexed `[quality][band]`, in 1/32 bit per MDCT bin.
#[cfg(not(feature = "opus-encode"))]
pub const ALLOC: [[u8; NB_EBANDS]; 11] = transpose([
[0, 90, 110, 118, 126, 134, 144, 152, 162, 172, 200],
[0, 80, 100, 110, 119, 127, 137, 145, 155, 165, 200],
@@ -38,6 +39,7 @@ pub const ALLOC: [[u8; NB_EBANDS]; 11] = transpose([
[0, 0, 0, 0, 0, 1, 1, 1, 1, 20, 104],
]);
#[cfg(not(feature = "opus-encode"))]
const fn transpose(t: [[u8; 11]; NB_EBANDS]) -> [[u8; NB_EBANDS]; 11] {
let mut out = [[0u8; NB_EBANDS]; 11];
let mut b = 0;
+1 -19
View File
@@ -4,25 +4,7 @@
//! RFC 6716 Table 54 (and the integer delays used when no rate conversion is needed), so that the
//! SILK output lines up with the CELT layer in Hybrid mode.
/// Dot product with eight independent partial sums, so the additions pipeline and the loop
/// vectorises instead of waiting on one 4-cycle add chain. Rounds differently from a
/// sequential sum (the resampler is not normative).
#[inline]
fn dot8(a: &[f32], b: &[f32]) -> f32 {
let mut s = [0f32; 8];
let (ca, ra) = a.as_chunks::<8>();
let (cb, rb) = b.as_chunks::<8>();
for (x, y) in ca.iter().zip(cb) {
for l in 0..8 {
s[l] += x[l] * y[l];
}
}
let mut acc = ((s[0] + s[4]) + (s[1] + s[5])) + ((s[2] + s[6]) + (s[3] + s[7]));
for (x, y) in ra.iter().zip(rb) {
acc += x * y;
}
acc
}
use crate::opus::dot::dot8;
#[derive(Clone)]
pub struct Resampler {
+20
View File
@@ -0,0 +1,20 @@
//! Shared fixed-order FIR dot product.
/// Dot product with eight independent partial sums, which the compiler can vectorise (a single
/// running sum is bound by the latency of the float addition). The sums are combined pairwise.
#[inline]
pub(super) fn dot8(a: &[f32], b: &[f32]) -> f32 {
let mut s = [0f32; 8];
let (ca, ra) = a.as_chunks::<8>();
let (cb, rb) = b.as_chunks::<8>();
for (x, y) in ca.iter().zip(cb) {
for l in 0..8 {
s[l] += x[l] * y[l];
}
}
let mut acc = ((s[0] + s[4]) + (s[1] + s[5])) + ((s[2] + s[6]) + (s[3] + s[7]));
for (x, y) in ra.iter().zip(rb) {
acc += x * y;
}
acc
}
+282 -59
View File
@@ -8,7 +8,8 @@
use crate::opus::encoder::range::{BITRES, RangeEncoder, ilog};
use crate::opus::encoder::rate::{Mode, QTHETA_OFFSET, get_pulses};
use crate::opus::encoder::tables::{EBANDS, NB_EBANDS};
use crate::opus::encoder::tables::EBANDS;
use crate::opus::encoder::{CeltFrame, rate::Allocation};
pub const SPREAD_NORMAL: usize = 2;
@@ -55,7 +56,7 @@ fn exp_rotation1_inv(x: &mut [f32], len: usize, stride: usize, c: f32, s: f32) {
if len <= stride {
return;
}
if len >= 2 * stride + 1 {
if len > 2 * stride {
for i in 0..=len - 2 * stride - 1 {
let x1 = x[i];
let x2 = x[i + stride];
@@ -96,12 +97,24 @@ pub fn exp_rotation_inv(x: &mut [f32], len: usize, k: usize, spread: usize) {
}
}
/// Relative slack for the pulse-candidate filter in [`pvq_search`]: far above the f32 rounding of
/// the filter score (a few 1e-7), far below the spread of real scores.
const PVQ_SCORE_SLACK: f32 = 1e-5;
/// Greedy PVQ search: the integer vector `y` with `sum |y| = k` closest in direction to `x`.
pub fn pvq_search(x: &[f32], k: usize, y: &mut [i32]) {
let n = x.len();
y[..n].fill(0);
let abs: Vec<f32> = x.iter().map(|v| v.abs()).collect();
let sum: f32 = abs.iter().sum();
// `abs`, `dy` (2 y + 1, infinite in the padding) and the per-pass scores `score`, each padded to
// whole 8-lane chunks.
let np = n.next_multiple_of(8);
let mut buf = vec![0f32; 3 * np];
let (abs, rest) = buf.split_at_mut(np);
let (dy, score) = rest.split_at_mut(np);
for (a, v) in abs.iter_mut().zip(x) {
*a = v.abs();
}
let sum: f32 = abs[..n].iter().sum();
if !sum.is_finite() || sum <= 1e-15 {
y[0] = k as i32;
return;
@@ -113,30 +126,69 @@ pub fn pvq_search(x: &[f32], k: usize, y: &mut [i32]) {
// Pre-project onto the pyramid (rounding down) and place the rest greedily.
let r = (k as f32 - 1.0) / sum;
for j in 0..n {
let p = (abs[j] * r).floor() as i32;
// Non-negative and at most k, so the truncating cast is the floor.
let p = (abs[j] * r) as i32;
y[j] = p;
placed += p as usize;
xy += abs[j] * p as f32;
yy += (p * p) as f32;
}
}
for j in 0..np {
dy[j] = if j < n { 2.0 * y[j] as f32 + 1.0 } else { f32::INFINITY };
}
while placed < k {
// Vectorisable scores (xy + |x_j|)^2 / (yy + 2 y_j + 1) and their maximum.
for ((sc, &a), &d) in score.iter_mut().zip(abs.iter()).zip(dy.iter()) {
let t = xy + a;
*sc = t * t / (yy + d);
}
let mut lane_max = [0f32; 8];
for c in score.as_chunks::<8>().0 {
for i in 0..8 {
lane_max[i] = if c[i] > lane_max[i] { c[i] } else { lane_max[i] };
}
}
let top = lane_max.iter().fold(0f32, |m, &v| if v > m { v } else { m });
// The exact cross-multiplied test below, in index order with the first maximum winning, only
// matters for entries within rounding distance of the top score: every other entry is beaten
// by the top one whenever it is reached and never beats it afterwards. Running the test on
// those alone therefore picks the same pulse as running it on all of them.
let filter = top > 1e-30 && top.is_finite();
let lo = top * (1.0 - PVQ_SCORE_SLACK);
// Usually exactly one entry qualifies; its index falls out of a lane-wise count.
let mut count = [0u32; 8];
let mut index = [0u32; 8];
for (ci, c) in score.as_chunks::<8>().0.iter().enumerate() {
for i in 0..8 {
let hit = u32::from(c[i] >= lo);
count[i] += hit;
index[i] += hit * (ci * 8 + i) as u32;
}
}
let mut best = 0usize;
let mut best_num = -1f32;
let mut best_den = 1f32;
for j in 0..n {
let num = xy + abs[j];
let num = num * num;
let den = yy + 2.0 * y[j] as f32 + 1.0;
if num * best_den > best_num * den {
best_num = num;
best_den = den;
best = j;
if filter && count.iter().sum::<u32>() == 1 {
best = index.iter().sum::<u32>() as usize;
} else {
let mut best_num = -1f32;
let mut best_den = 1f32;
for j in 0..n {
if !filter || score[j] >= lo {
let num = xy + abs[j];
let num = num * num;
let den = yy + 2.0 * y[j] as f32 + 1.0;
if num * best_den > best_num * den {
best_num = num;
best_den = den;
best = j;
}
}
}
}
xy += abs[best];
yy += 2.0 * y[best] as f32 + 1.0;
y[best] += 1;
dy[best] = 2.0 * y[best] as f32 + 1.0;
placed += 1;
}
for j in 0..n {
@@ -146,25 +198,45 @@ pub fn pvq_search(x: &[f32], k: usize, y: &mut [i32]) {
}
}
/// Encodes the PVQ codeword `y` (`sum |y| = k`) as the index the RFC 6716 §4.3.4.2 decoder maps
/// back to `y`.
pub fn encode_pulses(y: &[i32], k: usize, enc: &mut RangeEncoder, v: &mut Vec<u64>) {
let n = y.len();
let w = k + 1;
v.clear();
v.resize((n + 1) * w, 0);
/// Largest band width and pulse count the encoder codes (176 coefficients, `get_pulses(40)` = 128).
const PVQ_MAX_N: usize = 176;
const PVQ_MAX_K: usize = 128;
/// Row-major `V(n, k)` for `n <= max_n`, `k <= max_k` with row stride `max_k + 1`, saturated at
/// `u32::MAX` (a codebook that large is never coded, see `rate::fits_in32`).
fn build_pvq_table(max_n: usize, max_k: usize) -> Vec<u32> {
let w = max_k + 1;
let mut v = vec![0u32; (max_n + 1) * w];
v[0] = 1;
for nn in 1..=n {
for nn in 1..=max_n {
v[nn * w] = 1;
for kk in 1..=k {
let a = v[(nn - 1) * w + kk];
let b = v[nn * w + kk - 1];
let c = v[(nn - 1) * w + kk - 1];
v[nn * w + kk] = a.saturating_add(b).saturating_add(c);
for kk in 1..=max_k {
let sum = v[(nn - 1) * w + kk] as u64 + v[nn * w + kk - 1] as u64 + v[(nn - 1) * w + kk - 1] as u64;
v[nn * w + kk] = sum.min(u32::MAX as u64) as u32;
}
}
let total = v[n * w + k];
let vv = |nn: usize, kx: usize| v[nn * w + kx];
v
}
fn pvq_table() -> &'static [u32] {
static TABLE: std::sync::OnceLock<Vec<u32>> = std::sync::OnceLock::new();
TABLE.get_or_init(|| build_pvq_table(PVQ_MAX_N, PVQ_MAX_K))
}
/// Encodes the PVQ codeword `y` (`sum |y| = k`) as the index the RFC 6716 §4.3.4.2 decoder maps
/// back to `y`.
pub fn encode_pulses(y: &[i32], k: usize, enc: &mut RangeEncoder) {
let n = y.len();
// Shapes outside the coded range (never produced by the band layout) get a local table.
let local;
let (v, w) = if n <= PVQ_MAX_N && k <= PVQ_MAX_K {
(pvq_table(), PVQ_MAX_K + 1)
} else {
local = build_pvq_table(n, k);
(&local[..], k + 1)
};
let row = |nn: usize| &v[nn * w..(nn + 1) * w];
let total = row(n)[k] as u64;
let mut index = 0u64;
let mut kk = k;
for j in 0..n {
@@ -173,10 +245,11 @@ pub fn encode_pulses(y: &[i32], k: usize, enc: &mut RangeEncoder, v: &mut Vec<u6
}
let rem = n - j;
let t = y[j].unsigned_abs() as usize;
let below = row(rem - 1);
// Codewords with |y_j| = t start at sum_{m < kk - t} V(rem-1, m) within their sign half.
let mut base: u64 = (0..kk - t).map(|m| vv(rem - 1, m)).sum();
let mut base: u64 = below[..kk - t].iter().map(|&x| x as u64).sum();
if y[j] < 0 {
base += (vv(rem - 1, kk) + vv(rem, kk)) / 2;
base += (below[kk] as u64 + row(rem)[kk] as u64) / 2;
}
index += base;
kk -= t;
@@ -193,7 +266,6 @@ pub struct BandEnc<'m, 'e> {
pub i: usize,
pub spread: usize,
pub remaining_bits: i32,
pvq_v: Vec<u64>,
iy: Vec<i32>,
tmp: Vec<f32>,
}
@@ -217,7 +289,7 @@ impl BandEnc<'_, '_> {
let q = qn as u32;
let half = q >> 1;
let ft = (half + 1) * (half + 1);
let (fl, fs) = if it <= half { (it * (it + 1) >> 1, it + 1) } else { (ft - ((q + 1 - it) * (q + 2 - it) >> 1), q + 1 - it) };
let (fl, fs) = if it <= half { ((it * (it + 1)) >> 1, it + 1) } else { (ft - (((q + 1 - it) * (q + 2 - it)) >> 1), q + 1 - it) };
self.enc.encode(fl, fl + fs, ft);
itheta = ((it * 16384) / q) as i32;
}
@@ -287,36 +359,29 @@ impl BandEnc<'_, '_> {
iy.clear();
iy.resize(n, 0);
pvq_search(&tmp, k, &mut iy);
encode_pulses(&iy, k, self.enc, &mut self.pvq_v);
encode_pulses(&iy, k, self.enc);
self.iy = iy;
self.tmp = tmp;
}
}
}
/// Codes all band shapes (`quant_all_bands`, encoder side, long blocks). `x` holds `c` channels
/// of `n` normalised MDCT coefficients each.
#[allow(clippy::too_many_arguments)]
pub fn quant_all_bands(
m: &Mode,
start: usize,
end: usize,
x: &[f32],
n_total: usize,
c: usize,
pulses: &[i32; NB_EBANDS],
spread: usize,
dual_stereo: bool,
intensity: usize,
total_bits: i32,
mut balance: i32,
enc: &mut RangeEncoder,
lm: usize,
coded_bands: usize,
) {
/// Shape-coding controls, independent of the selected band allocation.
pub struct BandCoding {
pub spread: usize,
pub total_bits: i32,
}
/// Codes all band shapes (`quant_all_bands`, encoder side, long blocks). `x` holds
/// `frame.channels` channels of `n_total` normalised MDCT coefficients each.
pub fn quant_all_bands(m: &Mode, frame: CeltFrame, x: &[f32], n_total: usize, allocation: &Allocation, coding: BandCoding, enc: &mut RangeEncoder) {
let CeltFrame { start, end, channels: c, lm } = frame;
let Allocation { pulses, dual_stereo, intensity, coded_bands, balance, .. } = allocation;
let (dual_stereo, intensity, coded_bands, mut balance) = (*dual_stereo, *intensity, *coded_bands, *balance);
let BandCoding { spread, total_bits } = coding;
let mm = 1usize << lm;
debug_assert!(c == 1 || dual_stereo || intensity <= start, "stereo frames are coded as dual stereo");
let mut ctx = BandEnc { m, enc, i: 0, spread, remaining_bits: 0, pvq_v: Vec::new(), iy: Vec::new(), tmp: Vec::new() };
let mut ctx = BandEnc { m, enc, i: 0, spread, remaining_bits: 0, iy: Vec::new(), tmp: Vec::new() };
for i in start..end {
ctx.i = i;
let xo = mm * EBANDS[i] as usize;
@@ -362,7 +427,7 @@ mod tests {
x[i + stride] = c * x2 + s * x1;
x[i] = c * x1 + ms * x2;
}
if len >= 2 * stride + 1 {
if len > 2 * stride {
for i in (0..=len - 2 * stride - 1).rev() {
let x1 = x[i];
let x2 = x[i + stride];
@@ -466,12 +531,11 @@ mod tests {
#[test]
fn pvq_index_roundtrip_exhaustive() {
let mut v = Vec::new();
for n in 1..6usize {
for k in 1..6usize {
for y in all_codewords(n, k) {
let mut e = RangeEncoder::new();
encode_pulses(&y, k, &mut e, &mut v);
encode_pulses(&y, k, &mut e);
let buf = e.done(16);
let mut d = RangeDecoder::new(&buf);
assert_eq!(decode_pulses(n, k, &mut d), y, "n={n} k={k}");
@@ -480,6 +544,165 @@ mod tests {
}
}
/// The per-call table encoder this module used before the shared table.
fn encode_pulses_reference(y: &[i32], k: usize, enc: &mut RangeEncoder) {
let n = y.len();
let w = k + 1;
let mut v = vec![0u64; (n + 1) * w];
v[0] = 1;
for nn in 1..=n {
v[nn * w] = 1;
for kk in 1..=k {
let a = v[(nn - 1) * w + kk];
let b = v[nn * w + kk - 1];
let c = v[(nn - 1) * w + kk - 1];
v[nn * w + kk] = a.saturating_add(b).saturating_add(c);
}
}
let total = v[n * w + k];
let vv = |nn: usize, kx: usize| v[nn * w + kx];
let mut index = 0u64;
let mut kk = k;
for j in 0..n {
if kk == 0 {
break;
}
let rem = n - j;
let t = y[j].unsigned_abs() as usize;
let mut base: u64 = (0..kk - t).map(|m| vv(rem - 1, m)).sum();
if y[j] < 0 {
base += (vv(rem - 1, kk) + vv(rem, kk)) / 2;
}
index += base;
kk -= t;
}
if total >= 2 {
enc.uint(index as u32, total as u32);
}
}
#[test]
fn pvq_table_encode_matches_per_call_table() {
let mut seed = 0x9E37_79B9_7F4A_7C15u64;
let mut next = move |m: u64| {
seed ^= seed << 13;
seed ^= seed >> 7;
seed ^= seed << 17;
seed % m
};
let mut checked = 0;
for n in (1..=PVQ_MAX_N).step_by(5).chain([PVQ_MAX_N]) {
for k in (1..=PVQ_MAX_K).step_by(3).chain([PVQ_MAX_K]) {
if crate::opus::encoder::rate::pvq_v(n, k) > u32::MAX as u128 {
continue;
}
for _ in 0..4 {
let mut y = vec![0i32; n];
for _ in 0..k {
let at = next(n as u64) as usize;
y[at] += if next(2) == 0 { 1 } else { -1 };
}
// Opposite pulses cancel; top up so that sum |y| = k again.
let mut have: usize = y.iter().map(|v| v.unsigned_abs() as usize).sum();
while have < k {
let at = next(n as u64) as usize;
y[at] += if y[at] < 0 { -1 } else { 1 };
have += 1;
}
let (mut a, mut b) = (RangeEncoder::new(), RangeEncoder::new());
encode_pulses(&y, k, &mut a);
encode_pulses_reference(&y, k, &mut b);
assert_eq!(a.done(16), b.done(16), "n={n} k={k}");
checked += 1;
}
}
}
assert!(checked > 100, "{checked}");
}
/// The scalar greedy search the vectorised one replaced.
fn pvq_search_ref(x: &[f32], k: usize, y: &mut [i32]) {
let n = x.len();
y[..n].fill(0);
let abs: Vec<f32> = x.iter().map(|v| v.abs()).collect();
let sum: f32 = abs.iter().sum();
if !sum.is_finite() || sum <= 1e-15 {
y[0] = k as i32;
return;
}
let mut placed = 0usize;
let mut xy = 0f32;
let mut yy = 0f32;
if k > n / 2 {
let r = (k as f32 - 1.0) / sum;
for j in 0..n {
let p = (abs[j] * r).floor() as i32;
y[j] = p;
placed += p as usize;
xy += abs[j] * p as f32;
yy += (p * p) as f32;
}
}
while placed < k {
let mut best = 0usize;
let mut best_num = -1f32;
let mut best_den = 1f32;
for j in 0..n {
let num = xy + abs[j];
let num = num * num;
let den = yy + 2.0 * y[j] as f32 + 1.0;
if num * best_den > best_num * den {
best_num = num;
best_den = den;
best = j;
}
}
xy += abs[best];
yy += 2.0 * y[best] as f32 + 1.0;
y[best] += 1;
placed += 1;
}
for j in 0..n {
if x[j] < 0.0 {
y[j] = -y[j];
}
}
}
#[test]
fn pvq_search_matches_scalar_reference() {
let mut state = 0x9e3779b97f4a7c15u64;
let mut rnd = move || {
state ^= state << 13;
state ^= state >> 7;
state ^= state << 17;
(state >> 40) as f32 / (1u64 << 24) as f32 * 2.0 - 1.0
};
let mut a = vec![0i32; 200];
let mut b = vec![0i32; 200];
let mut cases = 0;
for round in 0..6000 {
let n = 1 + (round * 37 + (rnd().abs() * 176.0) as usize) % 176;
let k = 1 + (rnd().abs() * 127.0) as usize;
let scale = [1.0f32, 1e-9, 1e6, 3e-3][round % 4];
let x: Vec<f32> = (0..n)
.map(|_| match round % 6 {
0 => rnd(),
1 => if rnd() > 0.8 { rnd() } else { 0.0 },
2 => (rnd() * 4.0).round() / 4.0,
3 => if rnd() > 0.0 { 1.0 } else { -1.0 },
4 => rnd().powi(5),
_ => if rnd() > 0.95 { 3.0 * rnd() } else { 1e-4 * rnd() },
} * scale)
.collect();
pvq_search(&x, k, &mut a);
pvq_search_ref(&x, k, &mut b);
assert_eq!(a[..n], b[..n], "n={n} k={k} round={round}");
cases += 1;
}
assert_eq!(cases, 6000);
}
#[test]
fn pvq_search_finds_good_direction() {
let x: Vec<f32> = (0..32).map(|i| ((i as f32) * 0.7).sin()).collect();
+10 -15
View File
@@ -4,8 +4,9 @@
//! The quantised energies are updated with exactly the decoder's arithmetic so the prediction
//! state never drifts between encoder and decoder.
use crate::opus::encoder::CeltFrame;
use crate::opus::encoder::range::RangeEncoder;
use crate::opus::encoder::rate::MAX_FINE_BITS;
use crate::opus::encoder::rate::{Allocation, MAX_FINE_BITS};
use crate::opus::encoder::tables::{BETA_COEF, BETA_INTRA, E_PROB_MODEL, NB_EBANDS, PRED_COEF, SMALL_ENERGY_ICDF};
const LAPLACE_MINP: u32 = 1;
@@ -56,18 +57,15 @@ pub fn laplace_encode(enc: &mut RangeEncoder, value: i32, mut fs: u32, decay: u3
/// `quant_coarse_energy` for one prediction mode. `e` holds the target log2 energies (relative
/// to `E_MEANS`), `old_e` the quantised energies, updated in place. `budget` is the frame size in
/// bits.
#[allow(clippy::too_many_arguments)]
pub fn quant_coarse_energy(
start: usize,
end: usize,
frame: CeltFrame,
e: &[f32; 2 * NB_EBANDS],
old_e: &mut [f32; 2 * NB_EBANDS],
intra: bool,
enc: &mut RangeEncoder,
c: usize,
lm: usize,
budget: i32,
) {
let CeltFrame { start, end, channels: c, lm } = frame;
let prob = &E_PROB_MODEL[lm][intra as usize];
let (coef, beta) = if intra { (0.0, BETA_INTRA) } else { (PRED_COEF[lm], BETA_COEF[lm]) };
let mut prev = [0f32; 2];
@@ -112,14 +110,13 @@ pub fn quant_coarse_energy(
/// `quant_fine_energy`: raw bits refining each band's quantised energy.
pub fn quant_fine_energy(
start: usize,
end: usize,
frame: CeltFrame,
e: &[f32; 2 * NB_EBANDS],
old_e: &mut [f32; 2 * NB_EBANDS],
fine_quant: &[i32; NB_EBANDS],
enc: &mut RangeEncoder,
c: usize,
) {
let CeltFrame { start, end, channels: c, .. } = frame;
for i in start..end {
let fq = fine_quant[i];
if fq <= 0 {
@@ -139,18 +136,16 @@ pub fn quant_fine_energy(
/// `quant_energy_finalise`: spends the bits left at the end of the frame on one more bit of
/// energy resolution per band, in priority order.
#[allow(clippy::too_many_arguments)]
pub fn quant_energy_finalise(
start: usize,
end: usize,
frame: CeltFrame,
e: &[f32; 2 * NB_EBANDS],
old_e: &mut [f32; 2 * NB_EBANDS],
fine_quant: &[i32; NB_EBANDS],
fine_priority: &[i32; NB_EBANDS],
allocation: &Allocation,
mut bits_left: i32,
enc: &mut RangeEncoder,
c: usize,
) {
let CeltFrame { start, end, channels: c, .. } = frame;
let Allocation { fine_quant, fine_priority, .. } = allocation;
for prio in 0..2 {
let mut i = start;
while i < end && bits_left >= c as i32 {
+26 -78
View File
@@ -9,84 +9,7 @@
use crate::opus::encoder::tables::OVERLAP;
#[derive(Clone, Copy, Default, Debug)]
pub struct Cpx {
pub re: f32,
pub im: f32,
}
impl Cpx {
#[inline]
fn mul(self, o: Cpx) -> Cpx {
Cpx { re: self.re * o.re - self.im * o.im, im: self.re * o.im + self.im * o.re }
}
#[inline]
fn add(self, o: Cpx) -> Cpx {
Cpx { re: self.re + o.re, im: self.im + o.im }
}
}
/// Mixed-radix (2, 3, 4, 5) forward complex FFT, unscaled (decimation in time, recursive).
pub struct Fft {
n: usize,
factors: Vec<usize>,
twiddle: Vec<Cpx>,
}
impl Fft {
pub fn new(n: usize) -> Fft {
let mut factors = Vec::new();
let mut m = n;
for p in [4usize, 2, 3, 5] {
while m.is_multiple_of(p) {
factors.push(p);
m /= p;
}
}
assert_eq!(m, 1, "unsupported FFT size {n}");
let twiddle = (0..n)
.map(|k| {
let ph = -2.0 * std::f64::consts::PI * k as f64 / n as f64;
Cpx { re: ph.cos() as f32, im: ph.sin() as f32 }
})
.collect();
Fft { n, factors, twiddle }
}
pub fn process(&self, data: &mut [Cpx], scratch: &mut Vec<Cpx>) {
scratch.clear();
scratch.extend_from_slice(&data[..self.n]);
self.rec(&mut data[..self.n], scratch, 1, self.n, 0, 1);
}
fn rec(&self, out: &mut [Cpx], inp: &[Cpx], in_stride: usize, n: usize, fi: usize, tw_stride: usize) {
let p = self.factors[fi];
let m = n / p;
if m == 1 {
for (i, o) in out.iter_mut().enumerate().take(p) {
*o = inp[i * in_stride];
}
} else {
for q in 0..p {
self.rec(&mut out[q * m..(q + 1) * m], &inp[q * in_stride..], in_stride * p, m, fi + 1, tw_stride * p);
}
}
let big = self.n;
let mut t = [Cpx::default(); 5];
for k in 0..m {
for (q, tq) in t.iter_mut().enumerate().take(p) {
*tq = out[q * m + k].mul(self.twiddle[(q * k * tw_stride) % big]);
}
for q2 in 0..p {
let mut acc = Cpx::default();
for (q, tq) in t.iter().enumerate().take(p) {
acc = acc.add(tq.mul(self.twiddle[((q * q2) % p) * (big / p)]));
}
out[q2 * m + k] = acc;
}
}
}
}
use crate::opus::fft::{Cpx, Fft};
/// Forward MDCT producing `n` coefficients from a block of `n + OVERLAP` samples.
pub struct Mdct {
@@ -199,6 +122,31 @@ mod tests {
.collect()
}
#[test]
fn fft_matches_dft() {
// Every radix combination, including the 480-point size of the 20 ms frame.
for &n in &[2usize, 3, 4, 5, 6, 8, 12, 15, 16, 20, 24, 30, 48, 60, 120, 240, 480] {
let fft = Fft::new(n);
let x: Vec<Cpx> = (0..n).map(|i| Cpx { re: ((i * 37 % 101) as f32 - 50.0) / 7.0, im: ((i * 53 % 89) as f32 - 44.0) / 9.0 }).collect();
let mut y = x.clone();
fft.process(&mut y, &mut Vec::new());
for k in 0..n {
let (mut re, mut im) = (0f64, 0f64);
for (j, v) in x.iter().enumerate() {
let ph = -2.0 * std::f64::consts::PI * ((j * k) % n) as f64 / n as f64;
re += v.re as f64 * ph.cos() - v.im as f64 * ph.sin();
im += v.re as f64 * ph.sin() + v.im as f64 * ph.cos();
}
assert!(
(y[k].re as f64 - re).abs() < 2e-3 && (y[k].im as f64 - im).abs() < 2e-3,
"n={n} k={k}: ({}, {}) vs ({re}, {im})",
y[k].re,
y[k].im
);
}
}
}
#[test]
fn matches_direct_formula() {
for &n in &[240usize, 960] {
+36 -33
View File
@@ -10,8 +10,9 @@
//! above in the same range-coded frame; constant packet size.
//! - **CELT** (fullband): MDCT transform coding; constant packet size.
//!
//! From EffectCraft's `effectcraft-opusenc` (storytold/effectcraft@c618429). Public items keep their
//! names, so EffectCraft can re-export this module.
//! From EffectCraft's `effectcraft-opusenc` (storytold/effectcraft@c618429), with its later speed-ups
//! and CELT stage refactor up to storytold/effectcraft@d6c9ad66. Public items keep their names, so
//! EffectCraft can re-export this module.
//!
//! ```
//! # #[cfg(feature = "opus-encode")] {
@@ -26,6 +27,7 @@
//! # }
//! ```
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
// The bit-allocation code mirrors the normative integer arithmetic; keep C-like shift expressions.
#![allow(clippy::precedence, clippy::int_plus_one)]
@@ -36,19 +38,28 @@ mod range;
mod rate;
mod resample;
mod silk;
mod tables;
pub(super) mod tables;
use std::sync::OnceLock;
use bands::{SPREAD_NORMAL, quant_all_bands};
use bands::{BandCoding, SPREAD_NORMAL, quant_all_bands};
use energy::{quant_coarse_energy, quant_energy_finalise, quant_fine_energy};
use mdct::Mdct;
use range::{BITRES, RangeEncoder};
use rate::{Mode as CeltMode, compute_allocation};
use rate::{AllocationInput, Mode as CeltMode, compute_allocation};
use resample::Downsampler;
use silk::SilkEncoder;
use tables::{E_MEANS, EBANDS, NB_EBANDS, OVERLAP, PREEMPH, SPREAD_ICDF, TF_SELECT_TABLE, TRIM_ICDF};
/// Band range, channel count and transform size shared by CELT coding stages.
#[derive(Clone, Copy)]
struct CeltFrame {
start: usize,
end: usize,
channels: usize,
lm: usize,
}
/// Samples per channel in one 20 ms frame at 48 kHz.
const N: usize = 960;
/// LM of a 20 ms frame (8 short blocks).
@@ -338,7 +349,7 @@ impl Encoder {
Mode::Celt => {
let (log_e, silence) = self.celt_analysis(pcm);
let len = self.frame_bytes;
packet.extend_from_slice(&self.encode_celt(RangeEncoder::new(), len, 0, NB_EBANDS, &log_e, silence));
packet.extend_from_slice(&self.encode_celt(RangeEncoder::new(), len, 0..NB_EBANDS, &log_e, silence));
}
Mode::Silk => {
let x = self.silk_input(pcm);
@@ -368,7 +379,7 @@ impl Encoder {
}
let (log_e, _) = self.celt_analysis(pcm);
let end = if self.bandwidth == Bandwidth::SuperWideband { 19 } else { NB_EBANDS };
packet.extend_from_slice(&self.encode_celt(enc, len, HYBRID_START_BAND, end, &log_e, false));
packet.extend_from_slice(&self.encode_celt(enc, len, HYBRID_START_BAND..end, &log_e, false));
}
}
Ok(packet)
@@ -430,10 +441,18 @@ impl Encoder {
/// Codes one CELT frame (RFC 6716 §4.3, in bitstream order) of `len` bytes into `enc`
/// (which already holds the SILK frame in hybrid mode), coding bands `start..end`, and
/// finalises the frame.
#[allow(clippy::too_many_arguments)]
fn encode_celt(&mut self, mut enc: RangeEncoder, len: usize, start: usize, end: usize, log_e: &[f32; 2 * NB_EBANDS], silence: bool) -> Vec<u8> {
fn encode_celt(
&mut self,
mut enc: RangeEncoder,
len: usize,
bands: std::ops::Range<usize>,
log_e: &[f32; 2 * NB_EBANDS],
silence: bool,
) -> Vec<u8> {
let m = celt_mode();
let c = self.channels;
let frame = CeltFrame { start: bands.start, end: bands.end, channels: c, lm: LM };
let CeltFrame { start, end, .. } = frame;
if c == 1 {
for i in 0..NB_EBANDS {
self.old_band_e[i] = self.old_band_e[i].max(self.old_band_e[NB_EBANDS + i]);
@@ -462,10 +481,10 @@ impl Encoder {
let mut enc_intra = enc.clone();
let mut old_intra = self.old_band_e;
enc_intra.bit_logp(true, 3);
quant_coarse_energy(start, end, log_e, &mut old_intra, true, &mut enc_intra, c, LM, total_bits_raw);
quant_coarse_energy(frame, log_e, &mut old_intra, true, &mut enc_intra, total_bits_raw);
enc.bit_logp(false, 3);
let mut old_inter = self.old_band_e;
quant_coarse_energy(start, end, log_e, &mut old_inter, false, &mut enc, c, LM, total_bits_raw);
quant_coarse_energy(frame, log_e, &mut old_inter, false, &mut enc, total_bits_raw);
if enc_intra.tell_frac() < enc.tell_frac() {
enc = enc_intra;
self.old_band_e = old_intra;
@@ -473,14 +492,14 @@ impl Encoder {
self.old_band_e = old_inter;
}
} else {
quant_coarse_energy(start, end, log_e, &mut self.old_band_e, false, &mut enc, c, LM, total_bits_raw);
quant_coarse_energy(frame, log_e, &mut self.old_band_e, false, &mut enc, total_bits_raw);
}
// TF resolution: no changes.
{
let mut budget = total_bits_raw;
let mut tell = enc.tell();
let mut logp = 4;
let tf_select_rsv = LM > 0 && tell + logp + 1 <= budget;
let tf_select_rsv = LM > 0 && tell + logp < budget;
budget -= tf_select_rsv as i32;
for _ in start..end {
if tell + logp <= budget {
@@ -512,27 +531,11 @@ impl Encoder {
enc.icdf(alloc_trim as usize, &TRIM_ICDF, 7);
}
let bits = (total_bits_raw << BITRES) - enc.tell_frac() - 1;
let alloc = compute_allocation(m, start, end, &offsets, &cap, alloc_trim, bits, c, LM, &mut enc);
quant_fine_energy(start, end, log_e, &mut self.old_band_e, &alloc.fine_quant, &mut enc, c);
quant_all_bands(
m,
start,
end,
&self.freq,
N,
c,
&alloc.pulses,
SPREAD_NORMAL,
alloc.dual_stereo,
alloc.intensity,
total_bits_raw << BITRES,
alloc.balance,
&mut enc,
LM,
alloc.coded_bands,
);
let alloc = compute_allocation(m, frame, AllocationInput { offsets: &offsets, cap: &cap, trim: alloc_trim, bits }, &mut enc);
quant_fine_energy(frame, log_e, &mut self.old_band_e, &alloc.fine_quant, &mut enc);
quant_all_bands(m, frame, &self.freq, N, &alloc, BandCoding { spread: SPREAD_NORMAL, total_bits: total_bits_raw << BITRES }, &mut enc);
let bits_left = total_bits_raw - enc.tell();
quant_energy_finalise(start, end, log_e, &mut self.old_band_e, &alloc.fine_quant, &alloc.fine_priority, bits_left, &mut enc, c);
quant_energy_finalise(frame, log_e, &mut self.old_band_e, &alloc, bits_left, &mut enc);
debug_assert!(enc.tell() <= total_bits_raw, "frame overflow: {} > {}", enc.tell(), total_bits_raw);
if c == 1 {
let (a, b) = self.old_band_e.split_at_mut(NB_EBANDS);
+45 -363
View File
@@ -4,254 +4,18 @@
//! spec-derived `filmcraft-opus` decoder (first-party, MIT OR Apache-2.0) step by step; the only
//! difference is that the encoder *writes* the band-skip, intensity and dual-stereo symbols.
use crate::opus::encoder::range::{BITRES, RangeEncoder, ilog};
use crate::opus::encoder::tables::{ALLOC, EBANDS, LOG2_FRAC_TABLE, MAX_LM, NB_EBANDS};
use crate::opus::encoder::CeltFrame;
use crate::opus::encoder::range::{BITRES, RangeEncoder};
use crate::opus::encoder::tables::{EBANDS, LOG2_FRAC_TABLE, NB_EBANDS};
const MAX_PSEUDO: i32 = 40;
const LOG_MAX_PSEUDO: i32 = 6;
#[cfg(test)]
pub use crate::opus::rate_common::pvq_v;
pub use crate::opus::rate_common::{Mode, get_pulses};
pub const MAX_FINE_BITS: i32 = 8;
const FINE_OFFSET: i32 = 21;
pub const QTHETA_OFFSET: i32 = 4;
pub const QTHETA_OFFSET_TWOPHASE: i32 = 16;
const ALLOC_STEPS: i32 = 6;
/// Number of pulses represented by pseudo-pulse index `i`.
pub fn get_pulses(i: i32) -> i32 {
if i < 8 { i } else { (8 + (i & 7)) << ((i >> 3) - 1) }
}
/// Conservative (rounded up) log2 of `val` with `frac` fractional bits.
pub fn log2_frac(mut val: u32, mut frac: u32) -> i32 {
let mut l = ilog(val);
if val & val.wrapping_sub(1) != 0 {
if l > 16 {
val = ((val - 1) >> (l - 16)) + 1;
} else {
val <<= 16 - l;
}
let mut l = (l - 1) << frac;
loop {
let b = (val >> 16) as i32;
l += b << frac;
val = (val + b as u32) >> b;
val = (val * val + 0x7FFF) >> 15;
if frac == 0 {
break;
}
frac -= 1;
}
l + (val > 0x8000) as i32
} else {
l -= 1;
l << frac
}
}
/// PVQ codebook size V(N, K) (saturating far above 2^32).
pub fn pvq_v(n: usize, k: usize) -> u128 {
if k == 0 {
return 1;
}
if n == 0 {
return 0;
}
let mut row = vec![0u128; k + 1];
row[0] = 1;
for _ in 0..n {
let mut prev_diag = row[0];
for kk in 1..=k {
let up = row[kk];
let v = up.saturating_add(row[kk - 1]).saturating_add(prev_diag);
prev_diag = up;
row[kk] = v.min(u128::MAX >> 8);
}
row[0] = 1;
}
row[k]
}
fn fits_in32(n: usize, k: i32) -> bool {
pvq_v(n, k as usize) <= u32::MAX as u128
}
/// Precomputed per-mode data.
pub struct Mode {
/// log2 of band width in 1/8 bits.
pub log_n: [i32; NB_EBANDS],
cache_index: Vec<i16>,
cache_bits: Vec<u8>,
caps: Vec<u8>,
}
impl Mode {
pub fn new() -> Mode {
let mut log_n = [0i32; NB_EBANDS];
for (i, l) in log_n.iter_mut().enumerate() {
*l = log2_frac((EBANDS[i + 1] - EBANDS[i]) as u32, BITRES);
}
let (cache_index, cache_bits) = compute_pulse_cache(MAX_LM as i32);
let mut m = Mode { log_n, cache_index, cache_bits, caps: Vec::new() };
m.caps = compute_caps(&m);
m
}
#[inline]
pub fn cache(&self, lm: i32, band: usize) -> &[u8] {
let idx = self.cache_index[((lm + 1) as usize) * NB_EBANDS + band];
&self.cache_bits[idx.max(0) as usize..]
}
pub fn bits2pulses(&self, band: usize, lm: i32, bits: i32) -> i32 {
let cache = self.cache(lm, band);
let mut lo = 0i32;
let mut hi = cache[0] as i32;
let bits = bits - 1;
for _ in 0..LOG_MAX_PSEUDO {
let mid = (lo + hi + 1) >> 1;
if cache[mid as usize] as i32 >= bits {
hi = mid;
} else {
lo = mid;
}
}
let lo_bits = if lo == 0 { -1 } else { cache[lo as usize] as i32 };
if bits - lo_bits <= cache[hi as usize] as i32 - bits { lo } else { hi }
}
pub fn pulses2bits(&self, band: usize, lm: i32, pulses: i32) -> i32 {
if pulses == 0 { 0 } else { self.cache(lm, band)[pulses as usize] as i32 + 1 }
}
/// Per-band allocation caps for this frame (`init_caps`).
pub fn init_caps(&self, lm: usize, c: usize) -> [i32; NB_EBANDS] {
let mut cap = [0i32; NB_EBANDS];
for (i, cp) in cap.iter_mut().enumerate() {
let n = (EBANDS[i + 1] - EBANDS[i]) << lm;
*cp = (self.caps[NB_EBANDS * (2 * lm + c - 1) + i] as i32 + 64) * c as i32 * n >> 2;
}
cap
}
}
fn compute_pulse_cache(lm_max: i32) -> (Vec<i16>, Vec<u8>) {
let nb = NB_EBANDS;
let rows = (lm_max + 2) as usize;
let mut index = vec![-1i16; nb * rows];
let mut entries: Vec<(usize, i32, usize)> = Vec::new();
let mut curr = 0usize;
for i in 0..rows {
for j in 0..nb {
let n = (((EBANDS[j + 1] - EBANDS[j]) << i) >> 1) as usize;
index[i * nb + j] = -1;
'search: for k in 0..=i {
for nn in 0..nb {
if k == i && nn >= j {
break;
}
if n == (((EBANDS[nn + 1] - EBANDS[nn]) << k) >> 1) as usize {
index[i * nb + j] = index[k * nb + nn];
break 'search;
}
}
}
if index[i * nb + j] == -1 && n != 0 {
let mut k = 0;
while k < MAX_PSEUDO && fits_in32(n, get_pulses(k + 1)) {
k += 1;
}
index[i * nb + j] = curr as i16;
entries.push((n, k, curr));
curr += (k + 1) as usize;
}
}
}
let mut bits = vec![0u8; curr];
for &(n, k, off) in &entries {
let maxk = get_pulses(k) as usize;
let tmp = required_bits(n, maxk, BITRES);
for j in 1..=k {
bits[off + j as usize] = (tmp[get_pulses(j) as usize] - 1) as u8;
}
bits[off] = k as u8;
}
(index, bits)
}
fn required_bits(n: usize, maxk: usize, frac: u32) -> Vec<i32> {
let mut out = vec![0i32; maxk + 1];
if n == 1 {
for o in out.iter_mut().skip(1) {
*o = 1 << frac;
}
} else {
for (k, o) in out.iter_mut().enumerate().skip(1) {
*o = log2_frac(pvq_v(n, k) as u32, frac);
}
}
out
}
fn compute_caps(m: &Mode) -> Vec<u8> {
let nb = NB_EBANDS;
let mut caps = vec![0u8; (MAX_LM + 1) * 2 * nb];
for i in 0..=MAX_LM as i32 {
for c in 1..=2i32 {
for j in 0..nb {
let mut n0 = EBANDS[j + 1] - EBANDS[j];
let max_bits = if n0 << i == 1 {
c * (1 + MAX_FINE_BITS) << BITRES
} else {
let mut lm0 = 0;
if n0 > 2 {
n0 >>= 1;
lm0 -= 1;
} else if n0 <= 1 {
lm0 = i.min(1);
n0 <<= lm0;
}
let pcache = m.cache(lm0, j);
let mut mb = pcache[pcache[0] as usize] as i32 + 1;
let mut n = n0;
for k in 0..(i - lm0) {
mb <<= 1;
let offset = ((m.log_n[j] + ((lm0 + k) << BITRES)) >> 1) - QTHETA_OFFSET;
let num = 459 * ((2 * n - 1) * offset + mb);
let den = ((2 * n - 1) << 9) - 459;
let qb = ((num + (den >> 1)) / den).min(57);
mb += qb;
n <<= 1;
}
if c == 2 {
mb <<= 1;
let offset = ((m.log_n[j] + (i << BITRES)) >> 1) - if n == 2 { QTHETA_OFFSET_TWOPHASE } else { QTHETA_OFFSET };
let ndof = 2 * n - 1 - (n == 2) as i32;
let p = if n == 2 { 512 } else { 487 };
let num = p * (mb + ndof * offset);
let den = (ndof << 9) - p;
let qb = ((num + (den >> 1)) / den).min(if n == 2 { 64 } else { 61 });
mb += qb;
}
let ndof = c * n + if c == 2 && n > 2 { 1 } else { 0 };
let mut offset = ((m.log_n[j] + (i << BITRES)) >> 1) - FINE_OFFSET;
if n == 2 {
offset += (1 << BITRES) >> 2;
}
let num = mb + ndof * offset;
let den = (ndof - 1) << BITRES;
let qb = ((num + (den >> 1)) / den).min(MAX_FINE_BITS);
mb += c * qb << BITRES;
mb
};
let w = c * ((EBANDS[j + 1] - EBANDS[j]) << i);
let v = (4 * max_bits / w) - 64;
caps[((i * 2 + c - 1) as usize) * nb + j] = v.clamp(0, 255) as u8;
}
}
}
caps
}
/// Result of the allocation process.
pub struct Allocation {
pub coded_bands: usize,
@@ -263,125 +27,43 @@ pub struct Allocation {
pub fine_priority: [i32; NB_EBANDS],
}
/// `clt_compute_allocation`, encoder side. Stereo frames are always coded as dual (L/R) stereo
/// with no intensity bands, and no band is skipped voluntarily.
#[allow(clippy::too_many_arguments)]
pub fn compute_allocation(
m: &Mode,
start: usize,
end: usize,
offsets: &[i32; NB_EBANDS],
cap: &[i32; NB_EBANDS],
alloc_trim: i32,
total: i32,
c: usize,
lm: usize,
enc: &mut RangeEncoder,
) -> Allocation {
let ci = c as i32;
let lmi = lm as i32;
let mut total = total.max(0);
let mut skip_start = start;
let skip_rsv = if total >= 1 << BITRES { 1 << BITRES } else { 0 };
total -= skip_rsv;
let mut intensity_rsv = 0;
let mut dual_stereo_rsv = 0;
if c == 2 {
intensity_rsv = LOG2_FRAC_TABLE[end - start];
if intensity_rsv > total {
intensity_rsv = 0;
} else {
total -= intensity_rsv;
dual_stereo_rsv = if total >= 1 << BITRES { 1 << BITRES } else { 0 };
total -= dual_stereo_rsv;
}
}
let mut bits1 = [0i32; NB_EBANDS];
let mut bits2 = [0i32; NB_EBANDS];
let mut thresh = [0i32; NB_EBANDS];
let mut trim_offset = [0i32; NB_EBANDS];
for j in start..end {
let w = EBANDS[j + 1] - EBANDS[j];
thresh[j] = (ci << BITRES).max((3 * w << lmi << BITRES) >> 4);
trim_offset[j] = ci * w * (alloc_trim - 5 - lmi) * (end as i32 - j as i32 - 1) * (1 << (lmi + BITRES as i32)) >> 6;
if w << lmi == 1 {
trim_offset[j] -= ci << BITRES;
}
}
let nb_alloc = ALLOC.len() as i32;
let mut lo = 1;
let mut hi = nb_alloc - 1;
loop {
let mut done = false;
let mut psum = 0;
let mid = (lo + hi) >> 1;
for j in (start..end).rev() {
let n = EBANDS[j + 1] - EBANDS[j];
let mut bitsj = ci * n * (ALLOC[mid as usize][j] as i32) << lmi >> 2;
if bitsj > 0 {
bitsj = (bitsj + trim_offset[j]).max(0);
}
bitsj += offsets[j];
if bitsj >= thresh[j] || done {
done = true;
psum += bitsj.min(cap[j]);
} else if bitsj >= ci << BITRES {
psum += ci << BITRES;
}
}
if psum > total {
hi = mid - 1;
} else {
lo = mid + 1;
}
if lo > hi {
break;
}
}
hi = lo;
lo -= 1;
for j in start..end {
let n = EBANDS[j + 1] - EBANDS[j];
let mut bits1j = ci * n * (ALLOC[lo as usize][j] as i32) << lmi >> 2;
let mut bits2j = if hi >= nb_alloc { cap[j] } else { ci * n * (ALLOC[hi as usize][j] as i32) << lmi >> 2 };
if bits1j > 0 {
bits1j = (bits1j + trim_offset[j]).max(0);
}
if bits2j > 0 {
bits2j = (bits2j + trim_offset[j]).max(0);
}
if lo > 0 {
bits1j += offsets[j];
}
bits2j += offsets[j];
if offsets[j] > 0 {
skip_start = j;
}
bits2j = (bits2j - bits1j).max(0);
bits1[j] = bits1j;
bits2[j] = bits2j;
}
interp_bits2pulses(m, start, end, skip_start, &bits1, &bits2, &thresh, cap, total, skip_rsv, intensity_rsv, dual_stereo_rsv, c, lm, enc)
/// Per-band limits, boosts and available budget for the allocation search.
pub struct AllocationInput<'a> {
pub offsets: &'a [i32; NB_EBANDS],
pub cap: &'a [i32; NB_EBANDS],
pub trim: i32,
pub bits: i32,
}
#[allow(clippy::too_many_arguments)]
fn interp_bits2pulses(
m: &Mode,
start: usize,
end: usize,
/// `clt_compute_allocation`, encoder side. Stereo frames are always coded as dual (L/R) stereo
/// with no intensity bands, and no band is skipped voluntarily.
pub fn compute_allocation(m: &Mode, frame: CeltFrame, input: AllocationInput<'_>, enc: &mut RangeEncoder) -> Allocation {
let CeltFrame { start, end, channels: c, lm } = frame;
let AllocationInput { offsets, cap, trim: alloc_trim, bits: total } = input;
let crate::opus::rate_common::Bracket { skip_start, bits1, bits2, thresh, total, skip_rsv, intensity_rsv, dual_stereo_rsv } =
crate::opus::rate_common::bracket(start, end, offsets, cap, alloc_trim, total, c, lm);
let interpolation =
AllocationInterpolation { skip_start, bits1: &bits1, bits2: &bits2, thresh: &thresh, cap, total, skip_rsv, intensity_rsv, dual_stereo_rsv };
interp_bits2pulses(m, frame, interpolation, enc)
}
/// Bracketing allocation vectors and signalling reserves for the interpolation stage.
struct AllocationInterpolation<'a> {
skip_start: usize,
bits1: &[i32; NB_EBANDS],
bits2: &[i32; NB_EBANDS],
thresh: &[i32; NB_EBANDS],
cap: &[i32; NB_EBANDS],
mut total: i32,
bits1: &'a [i32; NB_EBANDS],
bits2: &'a [i32; NB_EBANDS],
thresh: &'a [i32; NB_EBANDS],
cap: &'a [i32; NB_EBANDS],
total: i32,
skip_rsv: i32,
mut intensity_rsv: i32,
mut dual_stereo_rsv: i32,
c: usize,
lm: usize,
enc: &mut RangeEncoder,
) -> Allocation {
intensity_rsv: i32,
dual_stereo_rsv: i32,
}
fn interp_bits2pulses(m: &Mode, frame: CeltFrame, interpolation: AllocationInterpolation<'_>, enc: &mut RangeEncoder) -> Allocation {
let CeltFrame { start, end, channels: c, lm } = frame;
let AllocationInterpolation { skip_start, bits1, bits2, thresh, cap, mut total, skip_rsv, mut intensity_rsv, mut dual_stereo_rsv } =
interpolation;
let ci = c as i32;
let alloc_floor = ci << BITRES;
let stereo = (c > 1) as i32;
@@ -393,7 +75,7 @@ fn interp_bits2pulses(
let mut psum = 0;
let mut done = false;
for j in (start..end).rev() {
let tmp = bits1[j] + (mid * bits2[j] >> ALLOC_STEPS);
let tmp = bits1[j] + ((mid * bits2[j]) >> ALLOC_STEPS);
if tmp >= thresh[j] || done {
done = true;
psum += tmp.min(cap[j]);
@@ -411,7 +93,7 @@ fn interp_bits2pulses(
let mut psum = 0;
let mut done = false;
for j in (start..end).rev() {
let mut tmp = bits1[j] + (lo * bits2[j] >> ALLOC_STEPS);
let mut tmp = bits1[j] + ((lo * bits2[j]) >> ALLOC_STEPS);
if tmp < thresh[j] && !done {
tmp = if tmp >= alloc_floor { alloc_floor } else { 0 };
} else {
@@ -500,9 +182,9 @@ fn interp_bits2pulses(
if n == 2 {
offset += (den << BITRES) >> 2;
}
if bits[j] + offset < den * 2 << BITRES {
if bits[j] + offset < (den * 2) << BITRES {
offset += nclogn >> 2;
} else if bits[j] + offset < den * 3 << BITRES {
} else if bits[j] + offset < (den * 3) << BITRES {
offset += nclogn >> 3;
}
let mut eb = (bits[j] + offset + (den << (BITRES - 1))).max(0);
@@ -513,7 +195,7 @@ fn interp_bits2pulses(
eb = eb.min(MAX_FINE_BITS);
ebits[j] = eb;
fine_priority[j] = (eb * (den << BITRES) >= bits[j] + offset) as i32;
bits[j] -= ci * eb << BITRES;
bits[j] -= (ci * eb) << BITRES;
} else {
excess = (bit - (ci << BITRES)).max(0);
bits[j] = bit - excess;
@@ -523,7 +205,7 @@ fn interp_bits2pulses(
if excess > 0 {
let extra_fine = (excess >> (stereo + BITRES as i32)).min(MAX_FINE_BITS - ebits[j]);
ebits[j] += extra_fine;
let extra_bits = extra_fine * ci << BITRES;
let extra_bits = (extra_fine * ci) << BITRES;
fine_priority[j] = (extra_bits >= excess - balance) as i32;
excess -= extra_bits;
}
+13 -1
View File
@@ -45,6 +45,8 @@ fn design(fc: f64, beta: f64, delay: usize) -> Vec<f32> {
h.iter().map(|&v| v as f32).collect()
}
use crate::opus::dot::dot8;
/// Decimates one channel of 48 kHz audio by 3, 4 or 6.
#[derive(Clone)]
pub struct Downsampler {
@@ -77,7 +79,7 @@ impl Downsampler {
let t = taps - 1 + self.factor * j;
let win = &self.buf[t + 1 - taps..=t];
// h is symmetric, so the window can be taken in forward order.
out.push(win.iter().zip(&self.h).map(|(a, b)| a * b).sum());
out.push(dot8(win, &self.h));
}
let n = self.buf.len();
self.buf.copy_within(n - (taps - 1).., 0);
@@ -97,6 +99,16 @@ mod tests {
(x.iter().map(|&v| (v as f64).powi(2)).sum::<f64>() / x.len() as f64).sqrt()
}
#[test]
fn dot8_matches_sequential_sum() {
for len in [0usize, 1, 7, 8, 9, 63, 167, 251] {
let a: Vec<f32> = (0..len).map(|i| ((i * 37 % 101) as f32 - 50.0) / 50.0).collect();
let b: Vec<f32> = (0..len).map(|i| ((i * 53 % 89) as f32 - 44.0) / 44.0).collect();
let exact: f64 = a.iter().zip(&b).map(|(&x, &y)| x as f64 * y as f64).sum();
assert!((dot8(&a, &b) as f64 - exact).abs() < 1e-4, "len {len}");
}
}
#[test]
fn passes_band_and_rejects_aliases() {
for &(fs, pass, stop) in &[(16_000u32, 6_000.0, 8_600.0), (12_000, 4_500.0, 6_500.0), (8_000, 3_000.0, 4_500.0)] {
+104 -8
View File
@@ -69,28 +69,55 @@ pub fn levinson(r: &[f64], order: usize) -> Vec<f64> {
}
/// Evaluates the symmetric polynomial `p` (length `d + 1`, `d` even) as the cosine series
/// `e^{jωd/2} P(e^{jω})`.
fn cos_series(p: &[f64], w: f64) -> f64 {
/// `e^{jωd/2} P(e^{jω})`, with `cos_m(m)` giving `cos(m ω)`.
#[inline]
fn cos_series_with(p: &[f64], cos_m: impl Fn(usize) -> f64) -> f64 {
let h = (p.len() - 1) / 2;
let mut s = p[h];
for k in 0..h {
s += 2.0 * p[k] * ((h - k) as f64 * w).cos();
s += 2.0 * p[k] * cos_m(h - k);
}
s
}
fn cos_series(p: &[f64], w: f64) -> f64 {
cos_series_with(p, |m| (m as f64 * w).cos())
}
/// Number of grid intervals the root search scans over `[0, π]`.
const GRID: usize = 1024;
/// Largest multiple of ω in the series (half the LPC order, at most 16 / 2).
const MAX_H: usize = 8;
/// Bisection steps per root: the bracket shrinks to 3e-9 rad, far below one Q15 NLSF step (9.6e-5 rad).
const BISECT_STEPS: usize = 20;
/// `cos(m · π g / GRID)` for every grid point `g` and `m` in `0..=MAX_H`, computed with the same
/// expression as [`cos_series`], so the table values are bit-identical to calling `cos` there.
fn grid_cos() -> &'static [[f64; MAX_H + 1]] {
static TABLE: std::sync::OnceLock<Vec<[f64; MAX_H + 1]>> = std::sync::OnceLock::new();
TABLE.get_or_init(|| {
(0..=GRID)
.map(|g| {
let w = std::f64::consts::PI * g as f64 / GRID as f64;
std::array::from_fn(|m| (m as f64 * w).cos())
})
.collect()
})
}
fn roots(p: &[f64], out: &mut Vec<f64>) {
const GRID: usize = 1024;
let grid = grid_cos();
let at_grid = |g: usize| cos_series_with(p, |m| grid[g][m]);
let mut w0 = 0.0;
let mut f0 = cos_series(p, w0);
let mut f0 = at_grid(0);
for g in 1..=GRID {
let w1 = std::f64::consts::PI * g as f64 / GRID as f64;
let f1 = cos_series(p, w1);
let f1 = at_grid(g);
if f0 == 0.0 {
out.push(w0);
} else if f0 * f1 < 0.0 {
let (mut lo, mut hi, mut flo) = (w0, w1, f0);
for _ in 0..40 {
for _ in 0..BISECT_STEPS {
let mid = 0.5 * (lo + hi);
let fm = cos_series(p, mid);
if fm * flo <= 0.0 {
@@ -111,6 +138,9 @@ fn roots(p: &[f64], out: &mut Vec<f64>) {
/// when the root search fails (unstable or degenerate filter).
pub fn a2nlsf(a: &[f64]) -> Option<Vec<f64>> {
let d = a.len();
if d > 2 * MAX_H {
return None;
}
let mut c = vec![0f64; d + 2];
c[0] = 1.0;
for k in 0..d {
@@ -199,9 +229,20 @@ pub fn pitch_search(x: &[f32], start: usize, len: usize, fs_khz: usize) -> Pitch
let score = full[(lag - min_lag) as usize];
// Contour: per-subframe lag offsets around the chosen lag.
let cb: &[[i32; 4]] = if fs_khz == 8 { &CB_NB_20 } else { &CB_WB_20 };
// The contour search revisits the same (subframe, lag) pairs for neighbouring base lags and
// codebook entries, so each correlation is computed once.
let span = (18 * fs - min_lag + 1) as usize;
let memo = std::cell::RefCell::new(vec![f64::NAN; 4 * span]);
let sub_score = |k: usize, l: i32| -> f64 {
let l = l.clamp(min_lag, 18 * fs);
ncorr(x, start + k * sub..start + (k + 1) * sub, l as usize)
let slot = k * span + (l - min_lag) as usize;
let cached = memo.borrow()[slot];
if !cached.is_nan() {
return cached;
}
let v = ncorr(x, start + k * sub..start + (k + 1) * sub, l as usize);
memo.borrow_mut()[slot] = v;
v
};
let mut best = (f64::MIN, lag, 0usize);
for l0 in (lag - 2).max(min_lag)..=(lag + 2).min(max_lag) {
@@ -319,4 +360,59 @@ mod tests {
}
}
}
/// The root search as it was before the grid table: `cos` called for every evaluation.
fn roots_reference(p: &[f64], out: &mut Vec<f64>) {
let mut w0 = 0.0;
let mut f0 = cos_series(p, w0);
for g in 1..=GRID {
let w1 = std::f64::consts::PI * g as f64 / GRID as f64;
let f1 = cos_series(p, w1);
if f0 == 0.0 {
out.push(w0);
} else if f0 * f1 < 0.0 {
let (mut lo, mut hi, mut flo) = (w0, w1, f0);
for _ in 0..BISECT_STEPS {
let mid = 0.5 * (lo + hi);
let fm = cos_series(p, mid);
if fm * flo <= 0.0 {
hi = mid;
} else {
lo = mid;
flo = fm;
}
}
out.push(0.5 * (lo + hi));
}
w0 = w1;
f0 = f1;
}
}
#[test]
fn grid_table_roots_are_bit_identical_to_direct_cos() {
let mut seed = 7u64;
let mut rnd = move || {
seed ^= seed << 13;
seed ^= seed >> 7;
seed ^= seed << 17;
(seed >> 11) as f64 / (1u64 << 53) as f64 * 2.0 - 1.0
};
let mut found = 0;
for len in [11usize, 17] {
for _ in 0..300 {
let mut p = vec![0f64; len];
for k in 0..len / 2 + 1 {
p[k] = rnd();
p[len - 1 - k] = p[k];
}
let (mut a, mut b) = (Vec::new(), Vec::new());
roots(&p, &mut a);
roots_reference(&p, &mut b);
assert_eq!(a.iter().map(|v| v.to_bits()).collect::<Vec<_>>(), b.iter().map(|v| v.to_bits()).collect::<Vec<_>>());
found += a.len();
}
}
assert!(found > 1000, "{found}");
}
}
+158 -10
View File
@@ -129,6 +129,48 @@ struct Coded {
pulses: Vec<i32>,
}
/// Noise-feedback history (decoded − input), most recent first, as a double-length ring: each
/// sample is stored at `pos` and `pos + MAX_LPC_ORDER`, so `buf[pos..pos + MAX_LPC_ORDER]` is
/// always the contiguous window and a push costs two stores instead of a shift.
struct NfRing {
buf: [f64; 2 * MAX_LPC_ORDER],
/// Index of the most recent sample, always below `MAX_LPC_ORDER`.
pos: usize,
}
impl NfRing {
fn new(hist: &[f64; MAX_LPC_ORDER]) -> Self {
let mut buf = [0.0; 2 * MAX_LPC_ORDER];
buf[..MAX_LPC_ORDER].copy_from_slice(hist);
buf[MAX_LPC_ORDER..].copy_from_slice(hist);
NfRing { buf, pos: 0 }
}
/// The history, most recent first.
fn window(&self) -> &[f64] {
self.buf.get(self.pos..self.pos + MAX_LPC_ORDER).unwrap_or(&[])
}
/// Makes `v` the most recent sample and drops the oldest.
fn push(&mut self, v: f64) {
self.pos = self.pos.checked_sub(1).unwrap_or(MAX_LPC_ORDER - 1);
for i in [self.pos, self.pos + MAX_LPC_ORDER] {
if let Some(slot) = self.buf.get_mut(i) {
*slot = v;
}
}
}
/// The history as a plain array, most recent first.
fn to_array(&self) -> [f64; MAX_LPC_ORDER] {
let mut out = [0.0; MAX_LPC_ORDER];
for (o, v) in out.iter_mut().zip(self.window()) {
*o = *v;
}
out
}
}
#[derive(Clone)]
struct Channel {
fs_khz: usize,
@@ -237,7 +279,7 @@ impl Channel {
let sub = self.sub;
let order = self.order;
let st = &mut self.dec;
let nf = &mut self.nf;
let mut ring = NfRing::new(&self.nf);
let off = if p.signal_type == 0 { offset + INACTIVE_OFFSET } else { offset };
let gamma = nf_gamma(off);
let mut nf_c = [0f64; MAX_LPC_ORDER];
@@ -355,7 +397,7 @@ impl Channel {
}
let lpc_q14 = lpc_pred.saturating_mul(16);
// Target excitation (Q14) for this sample.
let fb: f64 = (0..order).map(|j| nf_c[j] * nf[j]).sum();
let fb: f64 = nf_c.iter().zip(ring.window()).take(order).map(|(c, e)| c * e).sum();
let tgt = (x[n] as f64 + fb).clamp(-32768.0, 32767.0) * inv_g - lpc_q14 as f64 - ltp_q14 as f64;
let sgn = if seed_v < 0 { -1.0 } else { 1.0 };
let u = sgn * tgt;
@@ -394,11 +436,11 @@ impl Channel {
let v = res.saturating_add(lpc_q14);
s_lpc[MAX_LPC_ORDER + i] = v;
xq[n] = sat16(rshift_round(smulww(v, gain_q10), 8)) as i16;
nf.copy_within(0..MAX_LPC_ORDER - 1, 1);
nf[0] = xq[n] as f64 - x[n] as f64;
ring.push(xq[n] as f64 - x[n] as f64);
}
s_lpc.copy_within(sub..sub + MAX_LPC_ORDER, 0);
}
self.nf = ring.to_array();
st.s_lpc_q14.copy_from_slice(&s_lpc[..MAX_LPC_ORDER]);
st.out_buf[..l].copy_from_slice(&xq);
(Coded { gain_ix, gains_q16, seed, pulses }, xq)
@@ -485,6 +527,14 @@ struct Prep {
pred_q13: [i32; 2],
}
/// One rate-loop trial: the frame coded at gain offset `offset`.
struct Trial {
offset: f64,
bits: i32,
state: SilkEncoder,
coder: RangeEncoder,
}
/// SILK encoder for one mono or stereo (mid/side) stream.
#[derive(Clone)]
pub struct SilkEncoder {
@@ -635,11 +685,20 @@ impl SilkEncoder {
pub fn encode(&mut self, input: &[Vec<f32>], target_bits: f64, max_bits: i32, enc: &mut RangeEncoder) {
let prep = self.prepare(input);
let start_bits = enc.tell();
let trial = |s: &Self, o: f64| -> i32 {
let mut t = s.clone();
let mut e = enc.clone();
t.code(&prep, o, &mut e);
e.tell() - start_bits
// Every trial codes the frame into a clone of the encoder and the range coder. The result
// is kept per offset: the hard-limit check below hits the memo for the chosen offset, and
// the final step adopts that trial instead of coding the frame once more.
let mut trials: Vec<Trial> = Vec::new();
let mut trial = |s: &Self, o: f64| -> i32 {
if let Some(t) = trials.iter().find(|t| t.offset == o) {
return t.bits;
}
let mut state = s.clone();
let mut coder = enc.clone();
state.code(&prep, o, &mut coder);
let bits = coder.tell() - start_bits;
trials.push(Trial { offset: o, bits, state, coder });
bits
};
// Bisection on the gain offset: the smallest offset (finest quantisation) within budget.
let target = target_bits.min(max_bits as f64);
@@ -701,8 +760,20 @@ impl SilkEncoder {
while trial(self, o) > max_bits && o < 12.0 {
o += 1.0;
}
match trials.iter().position(|t| t.offset == o) {
Some(i) => {
let t = trials.swap_remove(i);
*self = t.state;
*enc = t.coder;
}
None => self.code(&prep, o, enc),
}
self.end_frame(&prep, o);
}
/// Advances the input history and the frame counter after frame `prep` was coded at `o`.
fn end_frame(&mut self, prep: &Prep, o: f64) {
self.last_offset = o;
self.code(&prep, o, enc);
for ch in 0..self.channels {
self.ch[ch].push_history(&prep.x[ch]);
}
@@ -712,3 +783,80 @@ impl SilkEncoder {
self.frame += 1;
}
}
#[cfg(test)]
mod tests {
use super::*;
/// Deterministic speech-like test input: two harmonics with a moving pitch, a syllable
/// envelope, noise and short silences, at the internal rate and 16-bit scale.
fn signal(len: usize, fs_khz: usize, seed: u32) -> Vec<f32> {
let mut s = seed;
let fs = (fs_khz * 1000) as f64;
(0..len)
.map(|i| {
s = s.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
let noise = (s >> 8) as f64 / (1u32 << 24) as f64 - 0.5;
let t = i as f64 / fs;
let f0 = 140.0 + 40.0 * (t * 1.3).sin();
let env = ((t * 4.0).sin().max(0.0)).powf(0.7);
let voiced = (std::f64::consts::TAU * f0 * t).sin() + 0.5 * (std::f64::consts::TAU * 2.0 * f0 * t).sin();
(8000.0 * env * voiced + 600.0 * noise) as f32
})
.collect()
}
#[test]
fn nf_ring_matches_a_shifted_history() {
let mut hist = [0f64; MAX_LPC_ORDER];
for (i, h) in hist.iter_mut().enumerate() {
*h = i as f64 * 0.5 - 3.0;
}
let mut ring = NfRing::new(&hist);
assert_eq!(ring.window(), &hist[..]);
for n in 0..100 {
let v = (n as f64 * 0.37).sin() * 100.0;
hist.copy_within(0..MAX_LPC_ORDER - 1, 1);
hist[0] = v;
ring.push(v);
assert_eq!(ring.window(), &hist[..], "after push {n}");
}
assert_eq!(ring.to_array(), hist);
}
/// The rate loop adopts the memoised trial for the chosen offset. A second encoder that codes
/// every frame afresh at that offset (what the loop did before the memo) must produce the
/// same bytes, frame after frame, so the adopted encoder and range-coder states are exact.
#[test]
fn adopting_the_memoised_trial_equals_coding_the_frame_again() {
for (fs_khz, channels, target_bits, max_bits) in
[(8, 1, 200.0, 1000), (12, 1, 320.0, 1000), (16, 1, 480.0, 1000), (16, 2, 640.0, 1000), (16, 1, 900.0, 400), (8, 2, 120.0, 160)]
{
let mut memo = SilkEncoder::new(fs_khz, channels);
let mut fresh = memo.clone();
let l = memo.frame_len();
let frames = 40;
let left = signal(l * frames, fs_khz, 7);
let right: Vec<f32> = signal(l * frames + 37, fs_khz, 11)[37..].iter().map(|v| v * 0.6).collect();
for f in 0..frames {
let mut input = vec![left[f * l..(f + 1) * l].to_vec()];
if channels == 2 {
input.push(right[f * l..(f + 1) * l].to_vec());
}
let mut enc = RangeEncoder::new();
memo.encode(&input, target_bits, max_bits, &mut enc);
let o = memo.last_offset;
let prep = fresh.prepare(&input);
let mut enc_fresh = RangeEncoder::new();
fresh.code(&prep, o, &mut enc_fresh);
fresh.end_frame(&prep, o);
assert_eq!(enc.tell(), enc_fresh.tell(), "{fs_khz} kHz {channels} ch frame {f}");
assert_eq!(enc.done(1275), enc_fresh.done(1275), "{fs_khz} kHz {channels} ch frame {f}");
for c in 0..channels {
assert_eq!(memo.ch[c].nf, fresh.ch[c].nf, "noise feedback, channel {c}, frame {f}");
assert_eq!(memo.ch[c].dec.s_lpc_q14, fresh.ch[c].dec.s_lpc_q14, "LPC state, channel {c}, frame {f}");
}
}
}
}
}
+130
View File
@@ -0,0 +1,130 @@
//! Shared CELT forward complex FFT.
#[derive(Clone, Copy, Default, Debug)]
pub struct Cpx {
pub re: f32,
pub im: f32,
}
impl Cpx {
#[inline]
pub(crate) fn mul(self, o: Cpx) -> Cpx {
Cpx { re: self.re * o.re - self.im * o.im, im: self.re * o.im + self.im * o.re }
}
#[inline]
pub(crate) fn add(self, o: Cpx) -> Cpx {
Cpx { re: self.re + o.re, im: self.im + o.im }
}
#[inline]
pub(crate) fn sub(self, o: Cpx) -> Cpx {
Cpx { re: self.re - o.re, im: self.im - o.im }
}
}
/// Mixed-radix (2, 3, 4, 5) forward complex FFT, unscaled (decimation in time, recursive).
pub struct Fft {
pub(crate) n: usize,
pub(crate) factors: Vec<usize>,
pub(crate) twiddle: Vec<Cpx>,
}
impl Fft {
pub fn new(n: usize) -> Fft {
let mut factors = Vec::new();
let mut m = n;
for p in [4usize, 2, 3, 5] {
while m.is_multiple_of(p) {
factors.push(p);
m /= p;
}
}
assert_eq!(m, 1, "unsupported FFT size {n}");
let twiddle = (0..n)
.map(|k| {
let ph = -2.0 * std::f64::consts::PI * k as f64 / n as f64;
Cpx { re: ph.cos() as f32, im: ph.sin() as f32 }
})
.collect();
Fft { n, factors, twiddle }
}
pub fn process(&self, data: &mut [Cpx], scratch: &mut Vec<Cpx>) {
scratch.clear();
scratch.extend_from_slice(&data[..self.n]);
self.rec(&mut data[..self.n], scratch, 1, self.n, 0, 1);
}
fn rec(&self, out: &mut [Cpx], inp: &[Cpx], in_stride: usize, n: usize, fi: usize, tw_stride: usize) {
let p = self.factors[fi];
let m = n / p;
if m == 1 {
for (i, o) in out.iter_mut().enumerate().take(p) {
*o = inp[i * in_stride];
}
} else {
for q in 0..p {
self.rec(&mut out[q * m..(q + 1) * m], &inp[q * in_stride..], in_stride * p, m, fi + 1, tw_stride * p);
}
}
// The twiddle index q * k * tw_stride is always below n, so no modulo is needed.
let tw = &self.twiddle;
match p {
2 => {
for k in 0..m {
let a0 = out[k];
let a1 = out[m + k].mul(tw[k * tw_stride]);
out[k] = a0.add(a1);
out[m + k] = a0.sub(a1);
}
}
4 => {
for k in 0..m {
let t0 = out[k];
let t1 = out[m + k].mul(tw[k * tw_stride]);
let t2 = out[2 * m + k].mul(tw[2 * k * tw_stride]);
let t3 = out[3 * m + k].mul(tw[3 * k * tw_stride]);
let (s0, d0) = (t0.add(t2), t0.sub(t2));
let (s1, d1) = (t1.add(t3), t1.sub(t3));
out[k] = s0.add(s1);
out[2 * m + k] = s0.sub(s1);
// The odd outputs combine d0 with -j * d1 = (d1.im, -d1.re) and its negative.
out[m + k] = Cpx { re: d0.re + d1.im, im: d0.im - d1.re };
out[3 * m + k] = Cpx { re: d0.re - d1.im, im: d0.im + d1.re };
}
}
3 => {
// Imaginary part of exp(-2 pi i / 3) = -sqrt(3) / 2.
let h = tw[self.n / 3].im;
for k in 0..m {
let t0 = out[k];
let t1 = out[m + k].mul(tw[k * tw_stride]);
let t2 = out[2 * m + k].mul(tw[2 * k * tw_stride]);
let (s, d) = (t1.add(t2), t1.sub(t2));
let a = Cpx { re: t0.re - 0.5 * s.re, im: t0.im - 0.5 * s.im };
out[k] = t0.add(s);
// j * h * d = (-h * d.im, h * d.re)
out[m + k] = Cpx { re: a.re - h * d.im, im: a.im + h * d.re };
out[2 * m + k] = Cpx { re: a.re + h * d.im, im: a.im - h * d.re };
}
}
_ => {
// Generic DFT butterfly (radix 5, once per transform).
let roots: [Cpx; 5] = std::array::from_fn(|q| if q < p { tw[q * (self.n / p)] } else { Cpx::default() });
let mut t = [Cpx::default(); 5];
for k in 0..m {
t[0] = out[k];
for q in 1..p {
t[q] = out[q * m + k].mul(tw[q * k * tw_stride]);
}
for q2 in 0..p {
let mut acc = t[0];
for q in 1..p {
acc = acc.add(t[q].mul(roots[(q * q2) % p]));
}
out[q2 * m + k] = acc;
}
}
}
}
}
}
+6 -2
View File
@@ -7,14 +7,18 @@
//! 20 ms, mono or stereo). From EffectCraft's `effectcraft-opusenc` (storytold/effectcraft@c618429).
//!
//! Public items keep their names, so FilmCraft and EffectCraft can re-export this module. The two
//! halves come from separate crates and do not share code yet (each has its own range coder, MDCT
//! and band tables). [`Bandwidth`] is one type for both (`encoder::Bandwidth` is the same type);
//! halves share the FFT, resampling dot product and CELT allocation preparation; range coders and
//! mode-specific MDCT processing remain separate. [`Bandwidth`] is one type for both (`encoder::Bandwidth` is the same type);
//! the two `Mode` enums keep their apps' variant names and convert into each other.
// Index loops and long argument lists follow the specification's pseudo-code (FilmCraft and
// EffectCraft allow these lints workspace-wide).
#![allow(clippy::needless_range_loop, clippy::too_many_arguments)]
mod dot;
mod fft;
mod rate_common;
#[cfg(feature = "opus-decode")]
mod decode;
#[cfg(feature = "opus-encode")]
+362
View File
@@ -0,0 +1,362 @@
//! CELT pulse cache and allocation caps shared by encoder and decoder.
#[cfg(not(feature = "opus-encode"))]
use super::decode::celt::tables::{ALLOC, EBANDS, LOG2_FRAC_TABLE, MAX_LM, NB_EBANDS};
#[cfg(feature = "opus-encode")]
use super::encoder::tables::{ALLOC, EBANDS, LOG2_FRAC_TABLE, MAX_LM, NB_EBANDS};
const BITRES: u32 = 3;
const MAX_PSEUDO: i32 = 40;
const LOG_MAX_PSEUDO: i32 = 6;
const MAX_FINE_BITS: i32 = 8;
const FINE_OFFSET: i32 = 21;
const QTHETA_OFFSET: i32 = 4;
const QTHETA_OFFSET_TWOPHASE: i32 = 16;
fn ilog(x: u32) -> i32 {
(32 - x.leading_zeros()) as i32
}
/// Number of pulses represented by pseudo-pulse index `i`.
pub fn get_pulses(i: i32) -> i32 {
if i < 8 { i } else { (8 + (i & 7)) << ((i >> 3) - 1) }
}
/// Conservative (rounded up) log2 of `val` with `frac` fractional bits.
pub fn log2_frac(mut val: u32, mut frac: u32) -> i32 {
let mut l = ilog(val);
if val & val.wrapping_sub(1) != 0 {
if l > 16 {
val = ((val - 1) >> (l - 16)) + 1;
} else {
val <<= 16 - l;
}
let mut l = (l - 1) << frac;
loop {
let b = (val >> 16) as i32;
l += b << frac;
val = (val + b as u32) >> b;
val = (val * val + 0x7FFF) >> 15;
if frac == 0 {
break;
}
frac -= 1;
}
l + (val > 0x8000) as i32
} else {
l -= 1;
l << frac
}
}
/// PVQ codebook size V(N, K) (saturating far above 2^32).
pub fn pvq_v(n: usize, k: usize) -> u128 {
if k == 0 {
return 1;
}
if n == 0 {
return 0;
}
let mut row = vec![0u128; k + 1];
row[0] = 1;
for _ in 0..n {
let mut prev_diag = row[0];
for kk in 1..=k {
let up = row[kk];
let v = up.saturating_add(row[kk - 1]).saturating_add(prev_diag);
prev_diag = up;
row[kk] = v.min(u128::MAX >> 8);
}
row[0] = 1;
}
row[k]
}
fn fits_in32(n: usize, k: i32) -> bool {
pvq_v(n, k as usize) <= u32::MAX as u128
}
/// Precomputed per-mode data.
pub struct Mode {
/// log2 of band width in 1/8 bits.
pub log_n: [i32; NB_EBANDS],
pub(crate) cache_index: Vec<i16>,
pub(crate) cache_bits: Vec<u8>,
pub(crate) caps: Vec<u8>,
}
impl Mode {
pub fn new() -> Mode {
let mut log_n = [0i32; NB_EBANDS];
for (i, l) in log_n.iter_mut().enumerate() {
*l = log2_frac((EBANDS[i + 1] - EBANDS[i]) as u32, BITRES);
}
let (cache_index, cache_bits) = compute_pulse_cache(MAX_LM as i32);
let mut m = Mode { log_n, cache_index, cache_bits, caps: Vec::new() };
m.caps = compute_caps(&m);
m
}
#[inline]
pub fn cache(&self, lm: i32, band: usize) -> &[u8] {
let idx = self.cache_index[((lm + 1) as usize) * NB_EBANDS + band];
&self.cache_bits[idx.max(0) as usize..]
}
pub fn bits2pulses(&self, band: usize, lm: i32, bits: i32) -> i32 {
let cache = self.cache(lm, band);
let mut lo = 0i32;
let mut hi = cache[0] as i32;
let bits = bits - 1;
for _ in 0..LOG_MAX_PSEUDO {
let mid = (lo + hi + 1) >> 1;
if cache[mid as usize] as i32 >= bits {
hi = mid;
} else {
lo = mid;
}
}
let lo_bits = if lo == 0 { -1 } else { cache[lo as usize] as i32 };
if bits - lo_bits <= cache[hi as usize] as i32 - bits { lo } else { hi }
}
pub fn pulses2bits(&self, band: usize, lm: i32, pulses: i32) -> i32 {
if pulses == 0 { 0 } else { self.cache(lm, band)[pulses as usize] as i32 + 1 }
}
/// Per-band allocation caps for this frame (`init_caps`).
pub fn init_caps(&self, lm: usize, c: usize) -> [i32; NB_EBANDS] {
let mut cap = [0i32; NB_EBANDS];
for (i, cp) in cap.iter_mut().enumerate() {
let n = (EBANDS[i + 1] - EBANDS[i]) << lm;
*cp = ((self.caps[NB_EBANDS * (2 * lm + c - 1) + i] as i32 + 64) * c as i32 * n) >> 2;
}
cap
}
}
fn compute_pulse_cache(lm_max: i32) -> (Vec<i16>, Vec<u8>) {
let nb = NB_EBANDS;
let rows = (lm_max + 2) as usize;
let mut index = vec![-1i16; nb * rows];
let mut entries: Vec<(usize, i32, usize)> = Vec::new();
let mut curr = 0usize;
for i in 0..rows {
for j in 0..nb {
let n = (((EBANDS[j + 1] - EBANDS[j]) << i) >> 1) as usize;
index[i * nb + j] = -1;
'search: for k in 0..=i {
for nn in 0..nb {
if k == i && nn >= j {
break;
}
if n == (((EBANDS[nn + 1] - EBANDS[nn]) << k) >> 1) as usize {
index[i * nb + j] = index[k * nb + nn];
break 'search;
}
}
}
if index[i * nb + j] == -1 && n != 0 {
let mut k = 0;
while k < MAX_PSEUDO && fits_in32(n, get_pulses(k + 1)) {
k += 1;
}
index[i * nb + j] = curr as i16;
entries.push((n, k, curr));
curr += (k + 1) as usize;
}
}
}
let mut bits = vec![0u8; curr];
for &(n, k, off) in &entries {
let maxk = get_pulses(k) as usize;
let tmp = required_bits(n, maxk, BITRES);
for j in 1..=k {
bits[off + j as usize] = (tmp[get_pulses(j) as usize] - 1) as u8;
}
bits[off] = k as u8;
}
(index, bits)
}
fn required_bits(n: usize, maxk: usize, frac: u32) -> Vec<i32> {
let mut out = vec![0i32; maxk + 1];
if n == 1 {
for o in out.iter_mut().skip(1) {
*o = 1 << frac;
}
} else {
for (k, o) in out.iter_mut().enumerate().skip(1) {
*o = log2_frac(pvq_v(n, k) as u32, frac);
}
}
out
}
fn compute_caps(m: &Mode) -> Vec<u8> {
let nb = NB_EBANDS;
let mut caps = vec![0u8; (MAX_LM + 1) * 2 * nb];
for i in 0..=MAX_LM as i32 {
for c in 1..=2i32 {
for j in 0..nb {
let mut n0 = EBANDS[j + 1] - EBANDS[j];
let max_bits = if n0 << i == 1 {
(c * (1 + MAX_FINE_BITS)) << BITRES
} else {
let mut lm0 = 0;
if n0 > 2 {
n0 >>= 1;
lm0 -= 1;
} else if n0 <= 1 {
lm0 = i.min(1);
n0 <<= lm0;
}
let pcache = m.cache(lm0, j);
let mut mb = pcache[pcache[0] as usize] as i32 + 1;
let mut n = n0;
for k in 0..(i - lm0) {
mb <<= 1;
let offset = ((m.log_n[j] + ((lm0 + k) << BITRES)) >> 1) - QTHETA_OFFSET;
let num = 459 * ((2 * n - 1) * offset + mb);
let den = ((2 * n - 1) << 9) - 459;
let qb = ((num + (den >> 1)) / den).min(57);
mb += qb;
n <<= 1;
}
if c == 2 {
mb <<= 1;
let offset = ((m.log_n[j] + (i << BITRES)) >> 1) - if n == 2 { QTHETA_OFFSET_TWOPHASE } else { QTHETA_OFFSET };
let ndof = 2 * n - 1 - (n == 2) as i32;
let p = if n == 2 { 512 } else { 487 };
let num = p * (mb + ndof * offset);
let den = (ndof << 9) - p;
let qb = ((num + (den >> 1)) / den).min(if n == 2 { 64 } else { 61 });
mb += qb;
}
let ndof = c * n + if c == 2 && n > 2 { 1 } else { 0 };
let mut offset = ((m.log_n[j] + (i << BITRES)) >> 1) - FINE_OFFSET;
if n == 2 {
offset += (1 << BITRES) >> 2;
}
let num = mb + ndof * offset;
let den = (ndof - 1) << BITRES;
let qb = ((num + (den >> 1)) / den).min(MAX_FINE_BITS);
mb += (c * qb) << BITRES;
mb
};
let w = c * ((EBANDS[j + 1] - EBANDS[j]) << i);
let v = (4 * max_bits / w) - 64;
caps[((i * 2 + c - 1) as usize) * nb + j] = v.clamp(0, 255) as u8;
}
}
}
caps
}
/// Shared allocation search before encoder/decoder signalling diverges.
pub struct Bracket {
pub skip_start: usize,
pub bits1: [i32; NB_EBANDS],
pub bits2: [i32; NB_EBANDS],
pub thresh: [i32; NB_EBANDS],
pub total: i32,
pub skip_rsv: i32,
pub intensity_rsv: i32,
pub dual_stereo_rsv: i32,
}
pub fn bracket(
start: usize,
end: usize,
offsets: &[i32; NB_EBANDS],
cap: &[i32; NB_EBANDS],
alloc_trim: i32,
total: i32,
c: usize,
lm: usize,
) -> Bracket {
let ci = c as i32;
let lmi = lm as i32;
let mut total = total.max(0);
let mut skip_start = start;
let skip_rsv = if total >= 1 << BITRES { 1 << BITRES } else { 0 };
total -= skip_rsv;
let mut intensity_rsv = 0;
let mut dual_stereo_rsv = 0;
if c == 2 {
intensity_rsv = LOG2_FRAC_TABLE[end - start];
if intensity_rsv > total {
intensity_rsv = 0;
} else {
total -= intensity_rsv;
dual_stereo_rsv = if total >= 1 << BITRES { 1 << BITRES } else { 0 };
total -= dual_stereo_rsv;
}
}
let mut bits1 = [0i32; NB_EBANDS];
let mut bits2 = [0i32; NB_EBANDS];
let mut thresh = [0i32; NB_EBANDS];
let mut trim_offset = [0i32; NB_EBANDS];
for j in start..end {
let w = EBANDS[j + 1] - EBANDS[j];
thresh[j] = (ci << BITRES).max(((3 * w) << lmi << BITRES) >> 4);
trim_offset[j] = (ci * w * (alloc_trim - 5 - lmi) * (end as i32 - j as i32 - 1) * (1 << (lmi + BITRES as i32))) >> 6;
if w << lmi == 1 {
trim_offset[j] -= ci << BITRES;
}
}
let nb_alloc = ALLOC.len() as i32;
let mut lo = 1;
let mut hi = nb_alloc - 1;
loop {
let mut done = false;
let mut psum = 0;
let mid = (lo + hi) >> 1;
for j in (start..end).rev() {
let n = EBANDS[j + 1] - EBANDS[j];
let mut bitsj = (ci * n * (ALLOC[mid as usize][j] as i32)) << lmi >> 2;
if bitsj > 0 {
bitsj = (bitsj + trim_offset[j]).max(0);
}
bitsj += offsets[j];
if bitsj >= thresh[j] || done {
done = true;
psum += bitsj.min(cap[j]);
} else if bitsj >= ci << BITRES {
psum += ci << BITRES;
}
}
if psum > total {
hi = mid - 1;
} else {
lo = mid + 1;
}
if lo > hi {
break;
}
}
hi = lo;
lo -= 1;
for j in start..end {
let n = EBANDS[j + 1] - EBANDS[j];
let mut bits1j = (ci * n * (ALLOC[lo as usize][j] as i32)) << lmi >> 2;
let mut bits2j = if hi >= nb_alloc { cap[j] } else { (ci * n * (ALLOC[hi as usize][j] as i32)) << lmi >> 2 };
if bits1j > 0 {
bits1j = (bits1j + trim_offset[j]).max(0);
}
if bits2j > 0 {
bits2j = (bits2j + trim_offset[j]).max(0);
}
if lo > 0 {
bits1j += offsets[j];
}
bits2j += offsets[j];
if offsets[j] > 0 {
skip_start = j;
}
bits2j = (bits2j - bits1j).max(0);
bits1[j] = bits1j;
bits2[j] = bits2j;
}
Bracket { skip_start, bits1, bits2, thresh, total, skip_rsv, intensity_rsv, dual_stereo_rsv }
}
+287
View File
@@ -0,0 +1,287 @@
//! Bit packing (Vorbis I §2) and codebooks (§3): Huffman lengths, the codeword assignment the
//! decoder derives from them, VQ lattices (lookup type 1) and the header encoding.
use super::{Error, Result};
/// LSB-first bit packer (Vorbis I §2.1.4): bits fill each byte from its least significant end.
#[derive(Clone, Debug, Default)]
pub struct BitWriter {
buf: Vec<u8>,
bits: u64,
}
impl BitWriter {
pub fn new() -> BitWriter {
BitWriter::default()
}
/// Writes the low `n` bits of `v` (`n` ≤ 32).
pub fn write(&mut self, v: u32, n: u32) {
let n = n.min(32);
for i in 0..n {
let bit = (v >> i) & 1;
let at = (self.bits / 8) as usize;
if at == self.buf.len() {
self.buf.push(0);
}
if bit != 0
&& let Some(b) = self.buf.get_mut(at)
{
*b |= 1 << (self.bits % 8);
}
self.bits += 1;
}
}
pub fn flag(&mut self, b: bool) {
self.write(b as u32, 1);
}
/// Writes a codeword MSB first: the decoder walks the tree from its first bit.
fn codeword(&mut self, word: u32, len: u32) {
for i in (0..len).rev() {
self.write((word >> i) & 1, 1);
}
}
pub fn bytes(&mut self, data: &[u8]) {
for &b in data {
self.write(u32::from(b), 8);
}
}
pub fn finish(self) -> Vec<u8> {
self.buf
}
}
/// `ilog` of the specification (§9.2.1): the position of the highest set bit, 0 for 0.
pub fn ilog(v: u32) -> u32 {
32 - v.leading_zeros()
}
/// The 32-bit float format of codebook headers (§9.2.2), for values it represents exactly.
pub fn float32_pack(v: f64) -> u32 {
if v == 0.0 || !v.is_finite() {
return 0;
}
let sign = if v < 0.0 { 0x8000_0000u32 } else { 0 };
let mut m = v.abs();
let mut exp: i32 = 0;
// a 21-bit mantissa: scale into [2^20, 2^21)
while m >= (1 << 21) as f64 {
m /= 2.0;
exp += 1;
}
while m < (1 << 20) as f64 {
m *= 2.0;
exp -= 1;
}
let mant = (m.round() as u32).min((1 << 21) - 1);
let biased = (exp + 788).clamp(0, 1023) as u32;
sign | (biased << 21) | mant
}
/// Huffman code lengths (1..=`max_len`) for `weights`, every entry coded.
pub fn huffman_lengths(weights: &[f64], max_len: u32) -> Vec<u32> {
let n = weights.len();
if n <= 1 {
return vec![1; n];
}
let total: f64 = weights.iter().map(|w| if w.is_finite() { w.max(0.0) } else { 0.0 }).sum::<f64>().max(1e-300);
let mut floor = 1e-9;
loop {
let w: Vec<f64> = weights.iter().map(|&x| (if x.is_finite() { x.max(0.0) } else { 0.0 }) / total + floor).collect();
let lens = huffman(&w);
if lens.iter().all(|&l| l <= max_len) || floor > 1.0 {
return lens.into_iter().map(|l| l.clamp(1, max_len)).collect();
}
floor *= 4.0;
}
}
fn huffman(w: &[f64]) -> Vec<u32> {
// nodes: (weight, children) with leaves first
let n = w.len();
let mut parent = vec![usize::MAX; 2 * n];
let mut weight: Vec<f64> = w.to_vec();
let mut alive: Vec<usize> = (0..n).collect();
while alive.len() > 1 {
alive.sort_by(|&a, &b| weight[b].partial_cmp(&weight[a]).unwrap_or(std::cmp::Ordering::Equal).then(b.cmp(&a)));
let (Some(a), Some(b)) = (alive.pop(), alive.pop()) else { break };
let id = weight.len();
weight.push(weight[a] + weight[b]);
if parent.len() <= id {
parent.resize(id + 1, usize::MAX);
}
parent[a] = id;
parent[b] = id;
alive.push(id);
}
(0..n)
.map(|i| {
let mut d = 0;
let mut x = i;
while let Some(&p) = parent.get(x) {
if p == usize::MAX {
break;
}
d += 1;
x = p;
}
d
})
.collect()
}
/// The codewords the decoder assigns to `lengths` (§3.2.1): in entry order, each entry gets the
/// lowest available codeword of its length (no prefix of an assigned codeword, and no assigned
/// codeword a prefix of it). An error when the lengths do not fit a prefix code.
pub fn assign_codewords(lengths: &[u32]) -> Result<Vec<u32>> {
// A trie of the assigned codewords: `children[node]` (0 = none), `leaf[node]`.
let mut children: Vec<[usize; 2]> = vec![[0, 0]];
let mut leaf = vec![false];
let mut words = Vec::with_capacity(lengths.len());
for &len in lengths {
if len == 0 || len > 32 {
return Err(Error::Internal("codeword length"));
}
let bits = lowest_free(&children, &leaf, 0, len).ok_or(Error::Internal("over-subscribed codebook"))?;
let mut node = 0usize;
let mut word = 0u32;
for &bit in &bits {
word = (word << 1) | bit as u32;
node = match children[node][bit] {
0 => {
children.push([0, 0]);
leaf.push(false);
let id = children.len() - 1;
children[node][bit] = id;
id
}
c => c,
};
}
leaf[node] = true;
words.push(word);
}
Ok(words)
}
/// The leftmost free path of `depth` bits below `node` (depth-first, 0 before 1).
fn lowest_free(children: &[[usize; 2]], leaf: &[bool], node: usize, depth: u32) -> Option<Vec<usize>> {
if leaf[node] || depth == 0 {
return None;
}
for bit in 0..2 {
let c = children[node][bit];
if c == 0 {
let mut p = vec![bit];
p.resize(depth as usize, 0);
return Some(p);
}
if let Some(mut rest) = lowest_free(children, leaf, c, depth - 1) {
rest.insert(0, bit);
return Some(rest);
}
}
None
}
/// A codebook: entry lengths and codewords, and for VQ books a lattice (lookup type 1).
#[derive(Clone, Debug)]
pub struct Codebook {
pub dimensions: u32,
pub lengths: Vec<u32>,
pub words: Vec<u32>,
/// Lattice values per dimension (lookup type 1: `values^dimensions == entries`).
pub lattice: Option<Lattice>,
}
#[derive(Clone, Copy, Debug)]
pub struct Lattice {
pub minimum: f64,
pub delta: f64,
/// Values per dimension.
pub values: u32,
}
impl Codebook {
/// A scalar book (no lookup) of `weights.len()` entries.
pub fn scalar(dimensions: u32, weights: &[f64]) -> Result<Codebook> {
let lengths = huffman_lengths(weights, 20);
let words = assign_codewords(&lengths)?;
Ok(Codebook { dimensions, lengths, words, lattice: None })
}
/// A lattice VQ book: `values` integers per dimension from `minimum` in steps of `delta`;
/// `weight(v)` is the relative probability of one component `v`.
pub fn lattice(dimensions: u32, values: u32, minimum: i32, delta: i32, weight: impl Fn(i32) -> f64) -> Result<Codebook> {
let entries = values.checked_pow(dimensions).ok_or(Error::Internal("codebook size"))?;
let w: Vec<f64> = (0..entries)
.map(|e| {
let mut p = 1.0;
let mut rest = e;
for _ in 0..dimensions {
let t = (rest % values) as i32;
rest /= values;
p *= weight(minimum + t * delta);
}
p
})
.collect();
let lengths = huffman_lengths(&w, 20);
let words = assign_codewords(&lengths)?;
Ok(Codebook { dimensions, lengths, words, lattice: Some(Lattice { minimum: f64::from(minimum), delta: f64::from(delta), values }) })
}
pub fn entries(&self) -> usize {
self.lengths.len()
}
/// Writes entry `e`.
pub fn put(&self, w: &mut BitWriter, e: usize) {
if let (Some(&word), Some(&len)) = (self.words.get(e), self.lengths.get(e)) {
w.codeword(word, len);
}
}
/// The entry of the lattice vector `v` (component 0 is the least significant digit, §3.2.1).
pub fn entry_of(&self, v: &[i32]) -> usize {
let Some(l) = self.lattice else { return 0 };
let mut e = 0usize;
let mut scale = 1usize;
for &x in v.iter().take(self.dimensions as usize) {
let t = ((f64::from(x) - l.minimum) / l.delta).round().clamp(0.0, f64::from(l.values - 1)) as usize;
e += t * scale;
scale *= l.values as usize;
}
e
}
/// The header encoding (§3.2.1).
pub fn write_header(&self, w: &mut BitWriter) {
w.write(0x56_4342, 24);
w.write(self.dimensions, 16);
w.write(self.entries() as u32, 24);
w.flag(false); // not ordered
w.flag(false); // not sparse
for &l in &self.lengths {
w.write(l - 1, 5);
}
match self.lattice {
None => w.write(0, 4),
Some(l) => {
w.write(1, 4);
w.write(float32_pack(l.minimum), 32);
w.write(float32_pack(l.delta), 32);
let bits = ilog(l.values - 1).max(1);
w.write(bits - 1, 4);
w.flag(false); // sequence_p
for m in 0..l.values {
w.write(m, bits);
}
}
}
}
}
+207
View File
@@ -0,0 +1,207 @@
//! Floor type 1 (Vorbis I §7): a piecewise-linear spectral envelope in the decoder's dB scale.
//!
//! The encoder picks a target value at each of the floor's X positions, codes it against the
//! decoder's prediction from its neighbours (step 2 of §7.2.4, inverted), and renders the curve
//! exactly as the decoder will (`render_line`, integer arithmetic), so the residue is computed
//! against the very floor the decoder multiplies it by.
use super::book::{BitWriter, Codebook, ilog};
/// `floor1_multiplier`: 2, so values run 0..128 and step two entries of the dB table.
pub const MULTIPLIER: u32 = 2;
/// The value range for [`MULTIPLIER`] 2.
pub const RANGE: i32 = 128;
const RANGE_BITS: u32 = 10;
/// Points per partition, and partitions.
pub const CLASS_DIM: usize = 4;
pub const PARTITIONS: usize = 8;
/// Step (in dB) between entries of `floor1_inverse_dB_table`: it runs from 1.0649863e-07 to 1
/// over 256 entries.
fn db_step() -> f64 {
(1.0f64 / 1.064_986_3e-7).ln() / 255.0
}
/// `floor1_inverse_dB_table[i]`.
pub fn inverse_db(i: i32) -> f32 {
(f64::from(i.clamp(0, 255) - 255) * db_step()).exp() as f32
}
/// The table index whose amplitude is nearest (in dB) to `a`.
pub fn db_index(a: f32) -> i32 {
if !a.is_finite() || a <= 0.0 {
return 0;
}
((f64::from(a)).ln() / db_step() + 255.0).round().clamp(0.0, 255.0) as i32
}
/// A floor 1 configuration for blocks of `n/2 = 2^RANGE_BITS` bins.
#[derive(Clone, Debug)]
pub struct Floor1 {
/// X positions: 0, 1024, then the partitions' points.
pub xs: Vec<i32>,
/// Index of the book coding the point values.
pub book: usize,
/// For each point (in coding order) its low and high neighbours.
neighbours: Vec<(usize, usize)>,
/// Point indices sorted by X.
sorted: Vec<usize>,
}
impl Floor1 {
/// Points spaced about evenly in log frequency over 1..1024.
pub fn new(book: usize) -> Floor1 {
let count = CLASS_DIM * PARTITIONS;
let mut xs = vec![0, 1 << RANGE_BITS];
let mut last = 0;
for i in 1..=count {
// geometric from 2 to ~1000 bins, at least one bin apart
let x = (2.0f64 * (500.0f64).powf((i - 1) as f64 / (count - 1) as f64)).round() as i32;
let x = x.max(last + 1).min((1 << RANGE_BITS) - 1);
xs.push(x);
last = x;
}
let neighbours = (0..xs.len())
.map(|i| {
if i < 2 {
return (0, 0);
}
let (mut lo, mut hi) = (0usize, 1usize);
for j in 0..i {
if xs[j] < xs[i] && xs[j] > xs[lo] {
lo = j;
}
if xs[j] > xs[i] && xs[j] < xs[hi] {
hi = j;
}
}
(lo, hi)
})
.collect();
let mut sorted: Vec<usize> = (0..xs.len()).collect();
sorted.sort_by_key(|&i| xs[i]);
Floor1 { xs, book, neighbours, sorted }
}
/// The setup-header encoding (§7.2.2): one class of `CLASS_DIM` points, no subclasses.
pub fn write_header(&self, w: &mut BitWriter) {
w.write(PARTITIONS as u32, 5);
for _ in 0..PARTITIONS {
w.write(0, 4);
}
w.write(CLASS_DIM as u32 - 1, 3);
w.write(0, 2); // no subclasses
w.write(self.book as u32 + 1, 8);
w.write(MULTIPLIER - 1, 2);
w.write(RANGE_BITS, 4);
for &x in &self.xs[2..] {
w.write(x as u32, RANGE_BITS);
}
}
/// Codes the target values `want` (one per point, 0..RANGE) into `w`; returns the floor curve
/// the decoder renders (`n2` amplitudes).
pub fn encode(&self, w: &mut BitWriter, book: &Codebook, want: &[i32], n2: usize) -> Vec<f32> {
let n = self.xs.len();
let want = |i: usize| want.get(i).copied().unwrap_or(0).clamp(0, RANGE - 1);
let mut fin = vec![0i32; n];
let mut used = vec![false; n];
let mut coded = vec![0u32; n];
fin[0] = want(0);
fin[1] = want(1);
used[0] = true;
used[1] = true;
for i in 2..n {
let (lo, hi) = self.neighbours[i];
let pred = render_point(self.xs[lo], fin[lo], self.xs[hi], fin[hi], self.xs[i]);
let f = want(i);
let (highroom, lowroom) = (RANGE - pred, pred);
let room = 2 * highroom.min(lowroom);
let val = if f == pred {
0
} else {
let d = f - pred;
let inside = if d > 0 { 2 * d } else { -2 * d - 1 };
if inside < room {
inside
} else if highroom > lowroom {
f - pred + lowroom
} else {
pred - f + highroom - 1
}
};
coded[i] = val.clamp(0, RANGE - 1) as u32;
if val != 0 {
used[lo] = true;
used[hi] = true;
used[i] = true;
fin[i] = f;
} else {
fin[i] = pred;
}
}
let bits = ilog(RANGE as u32 - 1);
w.write(fin[0] as u32, bits);
w.write(fin[1] as u32, bits);
for &c in &coded[2..] {
book.put(w, c as usize);
}
self.render(&fin, &used, n2)
}
/// The decoder's curve (§7.2.4 step 2, `render_line`) as amplitudes.
fn render(&self, fin: &[i32], used: &[bool], n2: usize) -> Vec<f32> {
let mut v = vec![0i32; n2];
let m = MULTIPLIER as i32;
let (mut lx, mut ly) = (0i32, fin[self.sorted[0]] * m);
let (mut hx, mut hy) = (0i32, ly);
for &i in &self.sorted[1..] {
if used[i] {
hy = fin[i] * m;
hx = self.xs[i];
render_line(lx, ly, hx, hy, &mut v);
lx = hx;
ly = hy;
}
}
if (hx as usize) < n2 {
render_line(hx, hy, n2 as i32, hy, &mut v);
}
v.iter().map(|&i| inverse_db(i)).collect()
}
}
fn render_point(x0: i32, y0: i32, x1: i32, y1: i32, x: i32) -> i32 {
let dy = y1 - y0;
let adx = (x1 - x0).max(1);
let err = dy.abs() * (x - x0);
let off = err / adx;
if dy < 0 { y0 - off } else { y0 + off }
}
fn render_line(x0: i32, y0: i32, x1: i32, y1: i32, v: &mut [i32]) {
let dy = y1 - y0;
let adx = x1 - x0;
if adx <= 0 {
return;
}
let base = dy / adx;
let sy = if dy < 0 { base - 1 } else { base + 1 };
let ady = dy.abs() - base.abs() * adx;
let (mut y, mut err) = (y0, 0);
if let Some(s) = v.get_mut(x0 as usize) {
*s = y;
}
for x in x0 + 1..x1 {
err += ady;
if err >= adx {
err -= adx;
y += sy;
} else {
y += base;
}
if let Some(s) = v.get_mut(x as usize) {
*s = y;
}
}
}
+134
View File
@@ -0,0 +1,134 @@
//! Forward MDCT of a windowed block of `n` samples to `n/2` coefficients:
//! `X[k] = Σ x[j] cos(2π/n · (j + 1/2 + n/4)(k + 1/2))`, the transform the Vorbis decoder inverts
//! (Vorbis I §1.3.2, §4.3.9). Computed as a DCT-IV of the folded block through an `n/8`-point
//! complex FFT.
use std::f64::consts::PI;
#[derive(Clone, Copy, Default, Debug)]
struct Cpx {
re: f64,
im: f64,
}
impl Cpx {
fn mul(self, o: Cpx) -> Cpx {
Cpx { re: self.re * o.re - self.im * o.im, im: self.re * o.im + self.im * o.re }
}
}
/// A forward MDCT for one block size (a power of two, at least 16).
#[derive(Clone, Debug)]
pub struct Mdct {
n: usize,
twiddle: Vec<Cpx>,
post: Vec<Cpx>,
fft_tw: Vec<Cpx>,
rev: Vec<usize>,
}
impl Mdct {
pub fn new(n: usize) -> Mdct {
let m = n / 2; // DCT-IV length
let h = m / 2; // FFT length
let twiddle = (0..h).map(|j| cis(-PI * (4.0 * j as f64 + 1.0) / (4.0 * m as f64))).collect();
let post = (0..h).map(|k| cis(-PI * k as f64 / m as f64)).collect();
let fft_tw = (0..h / 2).map(|j| cis(-2.0 * PI * j as f64 / h as f64)).collect();
let bits = h.trailing_zeros();
let rev = (0..h).map(|i| if bits == 0 { 0 } else { i.reverse_bits() >> (usize::BITS - bits) }).collect();
Mdct { n, twiddle, post, fft_tw, rev }
}
/// `x`: `n` windowed samples; `out`: `n/2` coefficients (scaled by `scale`).
pub fn forward(&self, x: &[f32], out: &mut [f32], scale: f64) {
let n = self.n;
let m = n / 2;
let q = n / 4;
let at = |i: usize| f64::from(x.get(i).copied().unwrap_or(0.0));
// fold (a, b, c, d) to the DCT-IV input (-c_r - d, a - b_r)
let mut v = vec![0f64; m];
for (i, s) in v.iter_mut().enumerate() {
*s = if i < q { -at(3 * q - 1 - i) - at(3 * q + i) } else { at(i - q) - at(3 * q - 1 - i) };
}
// DCT-IV through a half-length complex FFT
let h = m / 2;
let mut z: Vec<Cpx> = (0..h).map(|j| Cpx { re: v[2 * j], im: v[m - 1 - 2 * j] }.mul(self.twiddle[j])).collect();
self.fft(&mut z);
for (k, c) in z.iter().enumerate() {
let d = c.mul(self.post[k]);
if let Some(o) = out.get_mut(2 * k) {
*o = (d.re * scale) as f32;
}
if let Some(o) = out.get_mut(m - 1 - 2 * k) {
*o = (-d.im * scale) as f32;
}
}
}
/// In-place radix-2 FFT (`e^{-2πi jk/h}`).
fn fft(&self, a: &mut [Cpx]) {
let h = a.len();
for i in 0..h {
let j = self.rev[i];
if i < j {
a.swap(i, j);
}
}
let mut len = 2;
while len <= h {
let step = h / len;
for start in (0..h).step_by(len) {
for k in 0..len / 2 {
let w = self.fft_tw[k * step];
let u = a[start + k];
let t = a[start + k + len / 2].mul(w);
a[start + k] = Cpx { re: u.re + t.re, im: u.im + t.im };
a[start + k + len / 2] = Cpx { re: u.re - t.re, im: u.im - t.im };
}
}
len *= 2;
}
}
}
fn cis(t: f64) -> Cpx {
Cpx { re: t.cos(), im: t.sin() }
}
/// The Vorbis window (§4.3.1) for a block of `n` between blocks of the same size.
pub fn window(n: usize) -> Vec<f32> {
(0..n)
.map(|i| {
let s = (PI * (i as f64 + 0.5) / n as f64).sin();
(PI / 2.0 * s * s).sin() as f32
})
.collect()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn matches_the_direct_formula() {
for n in [16usize, 64, 256, 2048] {
let x: Vec<f32> = (0..n).map(|i| ((i * 7919 % 211) as f32 - 105.0) / 50.0).collect();
let mut fast = vec![0f32; n / 2];
Mdct::new(n).forward(&x, &mut fast, 1.0);
for k in [0usize, 1, 2, n / 4, n / 2 - 1] {
let direct: f64 =
(0..n).map(|j| f64::from(x[j]) * (2.0 * PI / n as f64 * (j as f64 + 0.5 + n as f64 / 4.0) * (k as f64 + 0.5)).cos()).sum();
assert!((direct - f64::from(fast[k])).abs() < 1e-3 * (1.0 + direct.abs()), "n={n} k={k}: {direct} vs {}", fast[k]);
}
}
}
#[test]
fn the_window_is_power_complementary() {
let w = window(2048);
for i in 0..1024 {
let s = w[i] * w[i] + w[i + 1024] * w[i + 1024];
assert!((s - 1.0).abs() < 1e-5, "{i}: {s}");
}
}
}
+494
View File
@@ -0,0 +1,494 @@
//! Pure-Rust Vorbis I encoder, written from the Vorbis I specification (Xiph.Org, 2020-07-04).
//!
//! No `unsafe` and no C code; builds for `wasm32-unknown-unknown`. ffmpeg is used only as an
//! external test oracle.
//!
//! The stream: one mode of 2048-sample blocks; per channel a floor 1 envelope of 34 points; one
//! residue type 2 over the interleaved channels, partitions of 32 values (a multiple of the
//! channel count for 3, 5, 6 and 7 channels) in seven classes (silent,
//! three single-pass lattice books, and two- and three-pass cascades for large values); no channel
//! coupling. Quality (-1 to 10) sets how far the floor sits from the spectral envelope (below it
//! for tonal regions, above it for noise-like ones, from the spectral flatness), and with it the
//! residue's precision: variable bit rate, like other Vorbis encoders.
//!
//! From FilmCraft's `filmcraft-vorbis` by @JordyUSA (storytold/filmcraft#4481).
//!
//! The packets go into Ogg with [`craft_media::ogg::PageWriter`] and a comment header from
//! [`craft_media::ogg::vorbis_comment`]; [`crate::encode_ogg_vorbis`] does all of it for a
//! whole buffer.
//!
//! ```
//! use craft_audio::vorbis::encoder::{Encoder, EncoderConfig};
//!
//! let mut enc = Encoder::new(EncoderConfig::new(48_000, 2, 5.0))?;
//! let tone: Vec<f32> = (0..4_800).map(|i| (i as f32 * 0.05).sin() * 0.5).collect();
//! let mut packets = enc.encode(&[&tone, &tone])?;
//! packets.extend(enc.finish()?);
//! // the last granule position is the input's length, so a decoder trims the padding
//! assert_eq!(packets.last().map(|p| p.1), Some(4_800));
//! assert_eq!(&enc.identification()[1..7], b"vorbis");
//! # Ok::<(), craft_audio::vorbis::encoder::Error>(())
//! ```
// Index loops follow the specification, as in FilmCraft (which allows this lint workspace-wide).
#![allow(clippy::needless_range_loop)]
mod book;
mod floor;
mod mdct;
use book::{BitWriter, Codebook};
use floor::Floor1;
use mdct::Mdct;
/// Why an encoder could not be created or input could not be encoded.
#[non_exhaustive]
#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
pub enum Error {
/// A setting or the input is outside what the encoder takes.
#[error("invalid argument: {0}")]
InvalidArgument(&'static str),
/// An encoder invariant failed (a bug, reported instead of panicking).
#[error("internal error: {0}")]
Internal(&'static str),
}
/// The encoder's result type.
pub type Result<T> = std::result::Result<T, Error>;
/// Block size (samples); the short block size of the header is never used.
pub const BLOCK: usize = 2048;
const HOP: usize = BLOCK / 2;
/// Residue values per partition for `channels` channels: 32, or for 3, 5, 6 and 7 channels a
/// multiple of the channel count (48, 40, 48, 56). libvorbis decodes each partition of an
/// interleaved (type 2) residue as if it started on channel 0, so a partition must hold whole
/// sample frames; the size also divides `channels × 1024` and is a multiple of every book's
/// dimension (4).
fn partition_size(channels: usize) -> usize {
match channels {
3 | 6 => 48,
5 => 40,
7 => 56,
_ => 32,
}
}
const CLASSES: usize = 8;
/// Largest residue magnitude the cascade codes: 7·225 + 7·15 + 7.
const MAX_RESIDUE: i32 = 1687;
/// The quality a NaN or infinite setting reads as.
pub const DEFAULT_QUALITY: f32 = 6.0;
/// Encoder settings.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct EncoderConfig {
/// Samples per second, 1 to 768 000.
pub sample_rate: u32,
/// 1 to 8, in Vorbis channel order (§4.3.9).
pub channels: usize,
/// -1 (smallest) to 10 (best); clamped.
pub quality: f32,
}
impl EncoderConfig {
/// Settings for `channels` channels (in Vorbis order) at `sample_rate` and `quality`.
pub fn new(sample_rate: u32, channels: usize, quality: f32) -> EncoderConfig {
EncoderConfig { sample_rate, channels, quality }
}
}
/// Book indices in the setup header.
const BOOK_CLASS: usize = 0;
const BOOK_FLOOR: usize = 1;
const BOOK_A1_SPARSE: usize = 2;
const BOOK_A1: usize = 3;
const BOOK_A2: usize = 4;
const BOOK_A4: usize = 5;
const BOOK_F: usize = 6;
const BOOK_M: usize = 7;
const BOOK_C: usize = 8;
/// Books per class and pass (`None`: nothing coded in that pass).
const CASCADE: [[Option<usize>; 3]; CLASSES] = [
[None, None, None],
[Some(BOOK_A1_SPARSE), None, None],
[Some(BOOK_A1), None, None],
[Some(BOOK_A2), None, None],
[Some(BOOK_A4), None, None],
[Some(BOOK_F), None, None],
[Some(BOOK_M), Some(BOOK_F), None],
[Some(BOOK_C), Some(BOOK_M), Some(BOOK_F)],
];
/// A Vorbis encoder for one stream: planar `f32` in, Vorbis packets with their granule
/// positions out.
pub struct Encoder {
cfg: EncoderConfig,
books: Vec<Codebook>,
floor: Floor1,
mdct: Mdct,
window: Vec<f32>,
/// Input not yet past a block, per channel; the next block starts at `start`.
pending: Vec<Vec<f32>>,
/// Read cursor into `pending`: consumed hops are dropped once per call, not per block.
start: usize,
samples_in: u64,
blocks: u64,
finished: bool,
/// Floor offset below the envelope (dB) for tonal and for noise-like regions.
tonal_db: f32,
noise_db: f32,
/// Residue magnitudes below this quantise to 0.
dead_zone: f32,
}
impl Encoder {
/// An encoder for `cfg`: 1 to 8 channels, a sample rate of 1 to 768 000; the quality is
/// clamped to -1..=10, and NaN or infinite reads as [`DEFAULT_QUALITY`].
pub fn new(cfg: EncoderConfig) -> Result<Encoder> {
if !(1..=8).contains(&cfg.channels) {
return Err(Error::InvalidArgument("Vorbis encoder: 1 to 8 channels"));
}
if !(1..=768_000).contains(&cfg.sample_rate) {
return Err(Error::InvalidArgument("Vorbis encoder: sample rate"));
}
let quality = if cfg.quality.is_finite() { cfg.quality.clamp(-1.0, 10.0) } else { DEFAULT_QUALITY };
let cfg = EncoderConfig { quality, ..cfg };
let books = vec![
Codebook::scalar(2, &(0..CLASSES * CLASSES).map(|e| class_weight(e / CLASSES) * class_weight(e % CLASSES)).collect::<Vec<_>>())?,
Codebook::scalar(1, &(0..floor::RANGE).map(|v| 1.0 / (1.0 + f64::from(v)).powf(1.6)).collect::<Vec<_>>())?,
Codebook::lattice(4, 3, -1, 1, |v| if v == 0 { 0.92 } else { 0.04 })?,
Codebook::lattice(4, 3, -1, 1, |v| if v == 0 { 0.5 } else { 0.25 })?,
Codebook::lattice(2, 5, -2, 1, |v| 0.6f64.powi(v.abs()))?,
Codebook::lattice(2, 9, -4, 1, |v| 0.7f64.powi(v.abs()))?,
Codebook::lattice(2, 15, -7, 1, |v| 0.8f64.powi(v.abs()))?,
Codebook::lattice(2, 15, -105, 15, |v| 0.55f64.powi((v / 15).abs()))?,
Codebook::lattice(2, 15, -1575, 225, |v| 0.4f64.powi((v / 225).abs()))?,
];
Ok(Encoder {
cfg,
books,
floor: Floor1::new(BOOK_FLOOR),
mdct: Mdct::new(BLOCK),
window: mdct::window(BLOCK),
// the first block is centred on sample 0: the decoder's first output is input sample 0
pending: vec![vec![0.0; HOP]; cfg.channels],
start: 0,
samples_in: 0,
blocks: 0,
finished: false,
// tones 4 dB (-1) to 30.4 dB (10) under their envelope; noise 14 dB above it (-1)
// to 4.1 dB (10)
tonal_db: 4.0 + 2.4 * (quality + 1.0),
noise_db: -14.0 + 0.9 * (quality + 1.0),
dead_zone: 0.8 - 0.025 * (quality + 1.0),
})
}
/// Channels per sample frame.
pub fn channels(&self) -> usize {
self.cfg.channels
}
/// The quality in use, after clamping.
pub fn quality(&self) -> f32 {
self.cfg.quality
}
/// Input samples per channel taken so far.
pub fn samples_in(&self) -> u64 {
self.samples_in
}
/// The identification header packet (§4.2.2): the first packet of the stream.
pub fn identification(&self) -> Vec<u8> {
let mut w = BitWriter::new();
w.write(1, 8);
w.bytes(b"vorbis");
w.write(0, 32);
w.write(self.cfg.channels as u32, 8);
w.write(self.cfg.sample_rate, 32);
w.write(0, 32); // bit rates: unset (variable)
w.write(0, 32);
w.write(0, 32);
w.write(8, 4); // 256-sample short blocks (unused)
w.write(11, 4); // 2048-sample long blocks
w.flag(true);
w.finish()
}
/// The setup header packet (§4.2.4): codebooks, floor, residue, mapping and mode. It follows
/// the comment header.
pub fn setup(&self) -> Vec<u8> {
let mut w = BitWriter::new();
w.write(5, 8);
w.bytes(b"vorbis");
w.write(self.books.len() as u32 - 1, 8);
for b in &self.books {
b.write_header(&mut w);
}
w.write(0, 6); // one time-domain transform placeholder
w.write(0, 16);
w.write(0, 6); // one floor
w.write(1, 16);
self.floor.write_header(&mut w);
w.write(0, 6); // one residue, type 2
w.write(2, 16);
let end = (self.cfg.channels * HOP) as u32;
w.write(0, 24);
w.write(end, 24);
w.write(partition_size(self.cfg.channels) as u32 - 1, 24);
w.write(CLASSES as u32 - 1, 6);
w.write(BOOK_CLASS as u32, 8);
for c in &CASCADE {
let bits: u32 = c.iter().enumerate().map(|(j, b)| u32::from(b.is_some()) << j).sum();
w.write(bits & 7, 3);
w.flag(bits > 7);
if bits > 7 {
w.write(bits >> 3, 5);
}
}
for c in &CASCADE {
for b in c.iter().flatten() {
w.write(*b as u32, 8);
}
}
w.write(0, 6); // one mapping, type 0
w.write(0, 16);
w.flag(false); // one submap
w.flag(false); // no coupling
w.write(0, 2);
w.write(0, 8); // submap 0: time, floor 0, residue 0
w.write(0, 8);
w.write(0, 8);
w.write(0, 6); // one mode: long blocks, mapping 0
w.flag(true);
w.write(0, 16);
w.write(0, 16);
w.write(0, 8);
w.flag(true);
w.finish()
}
/// Encodes planar samples (one slice per channel, all the same length, nominal range ±1);
/// returns the packets completed with their granule positions. NaN or infinite samples, or a
/// channel count or length mismatch, are an error.
pub fn encode(&mut self, planar: &[&[f32]]) -> Result<Vec<(Vec<u8>, i64)>> {
if self.finished {
return Err(Error::InvalidArgument("Vorbis encoder: encode after finish"));
}
if planar.len() != self.cfg.channels {
return Err(Error::InvalidArgument("Vorbis encoder: one slice per channel"));
}
let len = planar.first().map_or(0, |p| p.len());
if planar.iter().any(|p| p.len() != len) {
return Err(Error::InvalidArgument("Vorbis encoder: channels of different lengths"));
}
if planar.iter().any(|p| p.iter().any(|v| !v.is_finite())) {
return Err(Error::InvalidArgument("Vorbis encoder: NaN or infinite sample"));
}
for (b, p) in self.pending.iter_mut().zip(planar) {
b.extend_from_slice(p);
}
self.samples_in += len as u64;
self.drain()
}
/// Encodes what remains, padded with silence; the last packet's granule position is the
/// input's length, so the decoder trims the padding (§A.2).
pub fn finish(&mut self) -> Result<Vec<(Vec<u8>, i64)>> {
if self.finished {
return Ok(Vec::new());
}
self.finished = true;
// block k ends output at k·HOP: blocks 0..=ceil(len / HOP)
let blocks = self.samples_in.div_ceil(HOP as u64) + 1;
let missing = blocks.saturating_sub(self.blocks) as usize;
self.compact();
let need = (missing + 1) * HOP;
for b in self.pending.iter_mut() {
if b.len() < need {
b.resize(need, 0.0);
}
}
let mut out = Vec::new();
for _ in 0..missing {
out.push(self.block()?);
}
Ok(out)
}
fn drain(&mut self) -> Result<Vec<(Vec<u8>, i64)>> {
let mut out = Vec::new();
while self.pending.first().is_some_and(|b| b.len().saturating_sub(self.start) >= BLOCK) {
out.push(self.block()?);
}
self.compact();
Ok(out)
}
/// Drops the hops already encoded from the front of every channel buffer.
fn compact(&mut self) {
for b in self.pending.iter_mut() {
b.drain(..self.start.min(b.len()));
}
self.start = 0;
}
/// Encodes the block at `start` in `pending` and advances by a hop.
fn block(&mut self) -> Result<(Vec<u8>, i64)> {
let ch = self.cfg.channels;
let mut w = BitWriter::new();
w.write(0, 1); // audio packet; one mode, so no mode number
w.flag(true); // previous and next windows long
w.flag(true);
let mut residue = vec![0i32; ch * HOP];
let mut any = false;
let mut x = vec![0f32; BLOCK];
let mut coeffs = vec![0f32; HOP];
for c in 0..ch {
let src = self.pending.get(c).and_then(|b| b.get(self.start..)).ok_or(Error::Internal("channel buffer"))?;
for (i, v) in x.iter_mut().enumerate() {
*v = src.get(i).copied().unwrap_or(0.0).clamp(-8.0, 8.0) * self.window[i];
}
self.mdct.forward(&x, &mut coeffs, 2.0 / HOP as f64);
let peak = coeffs.iter().fold(0f32, |m, v| m.max(v.abs()));
// (a NaN peak cannot happen: samples are finite and clamped)
if peak <= 1e-7 {
w.flag(false); // floor unused: the channel is silent
continue;
}
any = true;
w.flag(true);
let want = self.floor_targets(&coeffs);
let curve = self.floor.encode(&mut w, &self.books[BOOK_FLOOR], &want, HOP);
for (k, (&v, &f)) in coeffs.iter().zip(&curve).enumerate() {
let r = if f > 0.0 { v / f } else { 0.0 };
// a dead zone: values just past half a step are noise peaks, not worth a ±1
let q = if r.abs() < self.dead_zone { 0.0 } else { r.round() };
residue[k * ch + c] = if q.is_finite() { (q as i32).clamp(-MAX_RESIDUE, MAX_RESIDUE) } else { 0 };
}
}
if any {
self.write_residue(&mut w, &residue);
}
let granule = if self.blocks == 0 {
0
} else {
let natural = self.blocks.saturating_mul(HOP as u64);
if self.finished { natural.min(self.samples_in) } else { natural }
};
self.start += HOP;
self.blocks += 1;
Ok((w.finish(), i64::try_from(granule).unwrap_or(i64::MAX)))
}
/// Floor values at the floor's points: the spectral envelope (power smoothed over a quarter of
/// the frequency, at least 8 bins, on each side) less an offset that grows with the region's tonality, from its
/// spectral flatness: noise needs a few dB of precision, tones much more.
fn floor_targets(&self, coeffs: &[f32]) -> Vec<i32> {
let n = coeffs.len();
let mut cum = vec![0f64; n + 1];
let mut cum_ln = vec![0f64; n + 1];
for (i, &v) in coeffs.iter().enumerate() {
let p = f64::from(v) * f64::from(v);
cum[i + 1] = cum[i] + p;
cum_ln[i + 1] = cum_ln[i] + (p + 1e-30).ln();
}
self.floor
.xs
.iter()
.map(|&x| {
let k = (x as usize).min(n - 1);
let half = (k / 4).max(8);
let (lo, hi) = (k.saturating_sub(half), (k + half + 1).min(n));
let len = (hi - lo) as f64;
let am = (cum[hi] - cum[lo]) / len;
let gm = ((cum_ln[hi] - cum_ln[lo]) / len).exp();
// spectral flatness: about -2.5 dB for noise, far below for a tone
let sfm_db = 10.0 * (gm / am.max(1e-30)).max(1e-30).log10();
let tonality = ((-sfm_db - 2.5) / 20.0).clamp(0.0, 1.0);
let offset = tonality * f64::from(self.tonal_db) + (1.0 - tonality) * f64::from(self.noise_db);
let amp = (am.sqrt() * 10f64.powf(-offset / 20.0)).max(1e-7) as f32;
(floor::db_index(amp) + 1) / floor::MULTIPLIER as i32
})
.collect()
}
/// Residue type 2 (§8.6.2 with the interleaved vector): classes per partition, then the
/// cascade's passes in the decoder's order.
fn write_residue(&self, w: &mut BitWriter, r: &[i32]) {
let partition = partition_size(self.cfg.channels);
let parts = r.len() / partition;
let classes: Vec<usize> = r.chunks(partition).map(class_of).collect();
let per_word = self.books[BOOK_CLASS].dimensions as usize;
for pass in 0..3 {
let mut pc = 0;
while pc < parts {
if pass == 0 {
let mut e = 0usize;
for i in 0..per_word {
e = e * CLASSES + classes.get(pc + i).copied().unwrap_or(0);
}
self.books[BOOK_CLASS].put(w, e);
}
for _ in 0..per_word {
if pc >= parts {
break;
}
let class = classes[pc];
if let Some(b) = CASCADE[class][pass] {
let book = &self.books[b];
let dims = book.dimensions as usize;
let part = &r[pc * partition..(pc + 1) * partition];
for chunk in part.chunks(dims) {
let v: Vec<i32> = chunk.iter().map(|&x| pass_value(x, class, pass)).collect();
book.put(w, book.entry_of(&v));
}
}
pc += 1;
}
}
}
}
}
/// Relative frequency of each residue class (for the class book's code lengths).
fn class_weight(c: usize) -> f64 {
[0.3, 0.2, 0.12, 0.12, 0.1, 0.08, 0.06, 0.02].get(c).copied().unwrap_or(0.01)
}
/// The part of residue value `v` coded in `pass` for `class`: the passes add up to `v`.
fn pass_value(v: i32, class: usize, pass: usize) -> i32 {
let split = |v: i32, step: i32| -> (i32, i32) {
let a = ((f64::from(v) / f64::from(step)).round() as i32).clamp(-7, 7);
(a * step, v - a * step)
};
match (class, pass) {
(6, 0) => split(v, 15).0,
(6, _) => split(v, 15).1,
(7, 0) => split(v, 225).0,
(7, 1) => split(split(v, 225).1, 15).0,
(7, _) => split(split(v, 225).1, 15).1,
_ => v,
}
}
/// The residue class of a partition: silent; ±1 with at most four nonzero values, or more; then
/// by the largest magnitude.
fn class_of(p: &[i32]) -> usize {
let m = p.iter().map(|v| v.abs()).max().unwrap_or(0);
match m {
0 => 0,
1 if p.iter().filter(|&&v| v != 0).count() <= 4 => 1,
1 => 2,
2 => 3,
3..=4 => 4,
5..=7 => 5,
8..=112 => 6,
_ => 7,
}
}
#[cfg(test)]
mod tests;
+285
View File
@@ -0,0 +1,285 @@
//! Unit tests, and ffmpeg (as an external oracle only) decoding the encoder's streams.
#![allow(clippy::unwrap_used)]
use std::path::Path;
use std::process::Command;
use super::book::{BitWriter, assign_codewords, float32_pack};
use super::{BLOCK, Encoder, EncoderConfig, HOP, partition_size};
#[test]
fn codewords_follow_the_specification_example() {
// Vorbis I §3.2.1: lengths 2 4 4 4 4 2 3 3
let words = assign_codewords(&[2, 4, 4, 4, 4, 2, 3, 3]).unwrap();
assert_eq!(words, [0b00, 0b0100, 0b0101, 0b0110, 0b0111, 0b10, 0b110, 0b111]);
assert!(assign_codewords(&[1, 1, 1]).is_err(), "over-subscribed");
}
#[test]
fn every_book_is_a_complete_prefix_code() {
let e = Encoder::new(EncoderConfig::new(48_000, 2, 5.0)).unwrap();
for (i, b) in e.books.iter().enumerate() {
let kraft: f64 = b.lengths.iter().map(|&l| 0.5f64.powi(l as i32)).sum();
assert!((kraft - 1.0).abs() < 1e-9, "book {i}: Kraft sum {kraft}");
assert!(b.lengths.iter().all(|&l| (1..=20).contains(&l)));
for (a, (&wa, &la)) in b.words.iter().zip(&b.lengths).enumerate() {
for (c, (&wc, &lc)) in b.words.iter().zip(&b.lengths).enumerate() {
if a != c && la <= lc {
assert_ne!(wc >> (lc - la), wa, "book {i}: codeword {a} is a prefix of {c}");
}
}
}
}
}
#[test]
fn float32_pack_is_exact_for_lattice_values() {
let unpack = |x: u32| {
let mant = f64::from(x & 0x1F_FFFF);
let exp = ((x >> 21) & 0x3FF) as i32 - 788;
let v = mant * 2f64.powi(exp);
if x & 0x8000_0000 != 0 { -v } else { v }
};
for v in [1.0, -1.0, -2.0, -4.0, -7.0, -105.0, 15.0, -1575.0, 225.0, 0.5, 3.0] {
assert_eq!(unpack(float32_pack(v)), v);
}
assert_eq!(float32_pack(0.0), 0);
}
#[test]
fn bits_are_packed_lsb_first() {
let mut w = BitWriter::new();
w.write(0b1, 1);
w.write(0b10, 2);
w.write(0x1F, 5);
w.write(0xABC, 12);
assert_eq!(w.finish(), [0b1111_1101, 0xBC, 0x0A]);
}
#[test]
fn hostile_input_is_an_error_not_a_panic() {
assert!(Encoder::new(EncoderConfig::new(48_000, 0, 3.0)).is_err());
assert!(Encoder::new(EncoderConfig::new(48_000, 9, 3.0)).is_err());
assert!(Encoder::new(EncoderConfig::new(0, 2, 3.0)).is_err());
assert_eq!(Encoder::new(EncoderConfig::new(48_000, 1, f32::NAN)).unwrap().cfg.quality, 6.0, "NaN quality uses the default, as the export does");
let mut e = Encoder::new(EncoderConfig::new(44_100, 2, 3.0)).unwrap();
assert!(e.encode(&[&[0.0; 4]]).is_err());
assert!(e.encode(&[&[0.0; 4], &[0.0; 3]]).is_err());
assert!(e.encode(&[&[f32::NAN; 4], &[0.0; 4]]).is_err());
let loud = vec![1e30f32; 5000];
assert!(!e.encode(&[&loud, &loud]).unwrap().is_empty());
assert!(!e.finish().unwrap().is_empty());
assert!(e.finish().unwrap().is_empty());
assert!(e.encode(&[&[0.0; 4], &[0.0; 4]]).is_err());
}
#[test]
fn granules_count_the_samples_and_trim_the_end() {
for len in [0usize, 1, 1023, 1024, 1025, 48_000] {
let mut e = Encoder::new(EncoderConfig::new(48_000, 1, 3.0)).unwrap();
let x = vec![0.1f32; len];
let mut packets = e.encode(&[&x]).unwrap();
packets.extend(e.finish().unwrap());
assert_eq!(packets.len(), len.div_ceil(HOP) + 1, "len {len}");
// packet k ends output at k·1024 samples; the last one at the input's length
let want: Vec<i64> = (0..packets.len()).map(|k| ((k * HOP) as i64).min(len as i64)).collect();
let got: Vec<i64> = packets.iter().map(|p| p.1).collect();
assert_eq!(got, want, "len {len}");
}
}
// --- ffmpeg oracle ---
/// An Ogg Vorbis file of the three headers and the audio packets, through craft-media's writer.
fn ogg(packets: &[(Vec<u8>, i64)]) -> Vec<u8> {
let mut w = craft_media::ogg::PageWriter::new(7);
let mut out = Vec::new();
for (i, (p, g)) in packets.iter().enumerate() {
out.extend(if i < 3 { w.header(p) } else { w.packet(p, *g) });
}
out.extend(w.finish(None));
out
}
fn comment() -> Vec<u8> {
craft_media::ogg::vorbis_comment("test", &[])
}
/// Encodes `input` (planar) and decodes it with ffmpeg's `decoder`; returns the planar output.
/// ffmpeg's decoders to check: its own `vorbis` always, and `libvorbis` when ffmpeg has it.
fn decoders(ff: &Path) -> Vec<&'static str> {
let list =
Command::new(ff).args(["-hide_banner", "-decoders"]).output().map(|o| String::from_utf8_lossy(&o.stdout).into_owned()).unwrap_or_default();
if list.lines().any(|l| l.split_whitespace().nth(1) == Some("libvorbis")) {
vec!["vorbis", "libvorbis"]
} else {
eprintln!("SKIPPED (libvorbis decoder): this ffmpeg has no libvorbis; checking its own decoder only");
vec!["vorbis"]
}
}
fn round_trip(input: &[Vec<f32>], rate: u32, quality: f32, decoder: &str, name: &str) -> Option<(Vec<Vec<f32>>, usize)> {
let ff = craft_media_testkit::ffmpeg_or_skip("vorbis oracle")?;
let mut e = Encoder::new(EncoderConfig::new(rate, input.len(), quality)).unwrap();
let mut packets = vec![(e.identification(), 0), (comment(), 0), (e.setup(), 0)];
let n = input[0].len();
let mut at = 0;
while at < n {
let end = (at + 4410).min(n);
let s: Vec<&[f32]> = input.iter().map(|c| &c[at..end]).collect();
packets.extend(e.encode(&s).unwrap());
at = end;
}
packets.extend(e.finish().unwrap());
let bytes: usize = packets[3..].iter().map(|p| p.0.len()).sum();
let dir = craft_media_testkit::fixtures_dir("audio/vorbis-encoder");
let path = dir.join(format!("{name}.ogg"));
std::fs::write(&path, ogg(&packets)).unwrap();
let out = Command::new(ff)
.args(["-v", "error", "-xerror", "-c:a", decoder, "-i"])
.arg(&path)
.args(["-f", "f32le", "-c:a", "pcm_f32le", "-"])
.output()
.unwrap();
assert!(out.status.success() && out.stderr.is_empty(), "{name} {decoder}: {}", String::from_utf8_lossy(&out.stderr));
let pcm: Vec<f32> = out.stdout.as_chunks::<4>().0.iter().map(|&b| f32::from_le_bytes(b)).collect();
let ch = input.len();
Some(((0..ch).map(|c| pcm.iter().skip(c).step_by(ch).copied().collect()).collect(), bytes))
}
fn snr_db(a: &[f32], b: &[f32]) -> f64 {
let (mut s, mut e) = (0f64, 0f64);
for (&x, &y) in a.iter().zip(b) {
s += f64::from(x) * f64::from(x);
e += (f64::from(x) - f64::from(y)).powi(2);
}
10.0 * (s.max(1e-20) / e.max(1e-20)).log10()
}
fn music(n: usize, seed: u32) -> Vec<f32> {
let mut r = seed;
(0..n)
.map(|i| {
let t = i as f32 / 48_000.0;
r = r.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
let noise = (r >> 8) as f32 / 8_388_608.0 - 1.0;
let chord: f32 = [220.0f32, 277.18, 329.63, 440.0]
.iter()
.enumerate()
.map(|(k, f)| (0.2 / (k + 1) as f32) * (2.0 * std::f32::consts::PI * f * t).sin())
.sum();
chord + 0.01 * noise
})
.collect()
}
/// Harmonic chords changing every half second, with decaying noise bursts (music-like).
fn chords(n: usize, seed: u32) -> Vec<f32> {
let mut r = seed;
let notes = [220.0f32, 277.2, 329.6, 440.0, 349.2, 523.3, 392.0, 659.3];
(0..n)
.map(|i| {
let t = i as f32 / 48_000.0;
let chord = (t * 2.0) as usize;
let mut s = 0.0;
for k in 0..3 {
let f = notes[(chord * 3 + k * 2) % notes.len()];
for h in 1..6 {
s += (2.0 * std::f32::consts::PI * f * h as f32 * t).sin() * 0.08 / h as f32;
}
}
r = r.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
let env = (-(t * 2.0).fract() * 3.0).exp();
s * (0.5 + 0.5 * env) + 0.02 * ((r >> 8) as f32 / 8_388_608.0 - 1.0) * env
})
.collect()
}
/// ffmpeg's own Vorbis decoder and libvorbis read every stream exactly as long as the input,
/// with SNR floors about 6 dB (chords 4 dB) under what the encoder measured when written, and bit
/// rates near libvorbis's for the same quality.
/// A signal, and per quality the SNR floor and the bit-rate range (kbit/s).
type Case = (&'static str, Vec<Vec<f32>>, [(f32, f64, std::ops::Range<usize>); 5]);
#[test]
fn ffmpeg_decodes_every_quality() {
let Some(ff) = craft_media_testkit::ffmpeg_or_skip("vorbis oracle") else { return };
let n = 48_000 * 3;
let cases: [Case; 2] = [
(
"music",
vec![music(n, 1), music(n, 2).iter().map(|v| v * 0.7).collect()],
[(-1.0, 3.0, 15..90), (0.0, 6.5, 20..110), (3.0, 12.0, 60..180), (6.0, 18.5, 120..280), (10.0, 25.5, 180..400)],
),
(
"chords",
vec![chords(n, 1), chords(n, 2).iter().map(|v| v * 0.8).collect()],
[(-1.0, 4.5, 20..90), (0.0, 6.0, 25..110), (3.0, 10.0, 70..200), (6.0, 14.0, 130..300), (10.0, 19.0, 180..420)],
),
];
for (name, input, levels) in &cases {
for (q, floor, kbps) in levels {
for decoder in decoders(&ff) {
let Some((out, bytes)) = round_trip(input, 48_000, *q, decoder, &format!("{name}{q}")) else { return };
assert!(out.iter().all(|c| c.len() == n), "{name} q{q} {decoder}: length {}", out[0].len());
let snr = snr_db(&input[0][4096..], &out[0][4096..]);
assert!(snr >= *floor, "{name} q{q} {decoder}: {snr:.2} dB < {floor}");
let rate = bytes * 8 / 3 / 1000;
assert!(kbps.contains(&rate), "{name} q{q}: {rate} kbit/s outside {kbps:?}");
}
}
}
}
/// Mono, 44.1 kHz, 3.0, 5.1 and 6.1 streams decode too, with libvorbis as well (which reads each
/// residue partition from channel 0); a silent channel costs one bit per block.
#[test]
fn channel_counts_and_rates() {
let Some(ff) = craft_media_testkit::ffmpeg_or_skip("vorbis oracle") else { return };
let n = 44_100;
for (rate, ch) in [(44_100u32, 1usize), (22_050, 2), (48_000, 3), (48_000, 6), (48_000, 7)] {
let mut input: Vec<Vec<f32>> = (0..ch).map(|c| chords(n, c as u32 + 1).iter().map(|v| v * (1.0 - 0.1 * c as f32)).collect()).collect();
if ch == 6 {
input[3] = vec![0.0; n];
}
for decoder in decoders(&ff) {
let Some((mut out, _)) = round_trip(&input, rate, 5.0, decoder, &format!("ch{ch}_{rate}_{decoder}")) else { return };
if decoder == "vorbis" {
// ffmpeg's decoder gives WAV order (5.1: FL FR FC LFE BL BR); the stream is in Vorbis
// order (L C R Ls Rs LFE), which libvorbis passes through
let wav_to_vorbis: &[usize] = match ch {
3 => &[0, 2, 1],
6 => &[0, 2, 1, 4, 5, 3],
7 => &[0, 2, 1, 5, 6, 4, 3],
_ => &[0, 1],
};
if ch > 2 {
out = wav_to_vorbis.iter().map(|&i| out[i].clone()).collect();
}
}
assert_eq!(out.len(), ch);
for (c, (a, b)) in input.iter().zip(&out).enumerate() {
assert_eq!(b.len(), n, "{ch} ch {rate} Hz {decoder}: channel {c} length");
if a.iter().all(|&v| v == 0.0) {
assert!(b.iter().all(|v| v.abs() < 1e-6), "silent channel {c}");
} else {
let snr = snr_db(&a[4096..], &b[4096..]);
assert!(snr > 8.0, "{ch} ch {rate} Hz {decoder} channel {c}: {snr:.1} dB");
}
}
}
}
}
/// Every partition holds whole sample frames (libvorbis decodes each one from channel 0), splits
/// the interleaved residue evenly and fits every book's dimension.
#[test]
fn partitions_hold_whole_frames() {
for ch in 1..=8 {
let p = partition_size(ch);
assert_eq!(p % ch, 0, "{ch} channels");
assert_eq!((ch * BLOCK / 2) % p, 0, "{ch} channels");
assert_eq!(p % 4, 0, "{ch} channels");
}
}
+4
View File
@@ -0,0 +1,4 @@
//! Vorbis I (feature `vorbis-encode`): the pure-Rust [`encoder`]. Decoding Vorbis goes through
//! [`crate::decode`].
pub mod encoder;
+721
View File
@@ -0,0 +1,721 @@
//! Markers a WAV file carries, read from its RIFF chunks.
//!
//! Two encodings are read into separate lists for the caller to map and merge:
//! - **Cue points** (the standard): a `cue ` chunk with one point per marker, named by `labl` (or
//! `note`) sub-chunks of a `LIST` `adtl` chunk, and given a length by `ltxt`.
//! - **XMP** (Adobe's tools): an `_PMX` chunk holding an XMP packet whose `xmpDM:markers` list has
//! one entry per marker (`xmpDM:startTime`, `xmpDM:duration`, `xmpDM:name`), counted in frames
//! of `xmpDM:frameRate` (`f44100` for samples at 44.1 kHz), or with an explicit
//! FrameCount rate suffix (`15f24`, `15f30000s1001`). Durations with a distinct rate
//! are converted to the marker start rate without app-specific time quantization.
//!
//! RF64 files (WAVs over 4 GB) carry a `0xFFFFFFFF` size for a chunk too big for 32 bits and give its real size in a
//! `ds64` chunk; those sizes are resolved so the chunks after the audio are still found.
//!
//! The file is untrusted input: every read is bounds-checked, sizes use checked arithmetic, and
//! the number of markers, of `adtl` sub-chunks looked at and the size of the XMP packet are capped.
use std::collections::{HashMap, HashSet};
/// Marker coordinates before app-specific time quantization. Explicit XMP duration
/// rates are normalized to the start coordinate rate; bare counts retain the legacy
/// track/file-rate interpretation.
#[derive(Clone, Debug, PartialEq)]
pub struct Marker {
/// Start in frames at `rate`.
pub start: f64,
/// Duration in frames at `rate`.
pub duration: f64,
/// Frames per second; consumers decide how invalid or absent rates map to their timeline.
pub rate: f64,
/// Label text.
pub name: String,
}
/// Separate source lists: rounding, deduplication, ordering and labels belong to the caller.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct Markers {
/// RIFF cue/adtl markers in file order.
pub cue: Vec<Marker>,
/// XMP markers in packet order.
pub xmp: Vec<Marker>,
/// A chunk-inventory or cue-label retention limit omitted metadata. Marker coordinates
/// remain available when only their label was omitted. Existing marker/XMP prefix limits
/// are separate and do not set this flag.
pub limited: bool,
}
/// Most markers read from one file.
pub const MAX_MARKERS: usize = 10_000;
/// Largest XMP packet read (bytes).
const MAX_XMP: usize = 4 << 20;
/// Most `adtl` sub-chunks (`labl`, `note`, `ltxt`) looked at in one file: a few per cue point is plenty.
const MAX_ADTL_RECORDS: usize = 4 * MAX_MARKERS;
/// Most entries read from an RF64 file's `ds64` size table.
const MAX_DS64_TABLE: usize = 1_024;
/// Maximum retained RIFF chunk descriptors (including empty chunks).
pub const MAX_CHUNKS: usize = 100_000;
/// Maximum UTF-8 bytes in one retained cue label.
pub const MAX_LABEL_BYTES: usize = 64 * 1024;
/// Aggregate cue label bytes, enforced separately for the name map and emitted markers.
pub const MAX_LABEL_TOTAL_BYTES: usize = 4 * 1024 * 1024;
fn u32_at(b: &[u8], at: usize) -> Option<u32> {
let s = b.get(at..at.checked_add(4)?)?;
Some(u32::from_le_bytes(s.try_into().ok()?))
}
fn u64_at(b: &[u8], at: usize) -> Option<u64> {
let s = b.get(at..at.checked_add(8)?)?;
Some(u64::from_le_bytes(s.try_into().ok()?))
}
/// The text of a NUL-terminated label (the rest of the chunk), lossily decoded.
fn label(b: &[u8]) -> Option<String> {
// Look only as far as one label can be retained; never copy an arbitrary chunk body.
let end = b.iter().take(MAX_LABEL_BYTES + 1).position(|&c| c == 0).unwrap_or(b.len());
if end > MAX_LABEL_BYTES {
return None;
}
let text = String::from_utf8_lossy(b.get(..end)?);
let text = text.trim();
(text.len() <= MAX_LABEL_BYTES).then(|| text.to_string())
}
/// Whether `bytes` start a RIFF/WAVE file.
pub fn is_wav(bytes: &[u8]) -> bool {
matches!(bytes.get(0..4), Some(b"RIFF" | b"RF64")) && bytes.get(8..12) == Some(b"WAVE")
}
/// The sizes an RF64 file's `ds64` chunk gives for chunks too big for the 32-bit size field.
struct Ds64 {
/// The `data` chunk's size.
data: u64,
/// Other chunks: `(id, size)`.
table: Vec<([u8; 4], u64)>,
}
impl Ds64 {
/// The real size of chunk `id`, when the file says.
fn size_of(&self, id: &[u8; 4]) -> Option<u64> {
if id == b"data" { Some(self.data) } else { self.table.iter().find(|(t, _)| t == id).map(|(_, size)| *size) }
}
}
/// The `ds64` chunk of an RF64 file (`RF64`, size, `WAVE`, then `ds64`); `None` for any other file or one whose
/// `ds64` doesn't fit.
fn ds64(bytes: &[u8]) -> Option<Ds64> {
if bytes.get(0..4) != Some(b"RF64") || bytes.get(12..16) != Some(b"ds64") {
return None;
}
let size = usize::try_from(u32_at(bytes, 16)?).ok()?;
let body = bytes.get(20..20usize.checked_add(size)?)?;
// riff size (8), data size (8), sample count (8), table length (4), then `(id, size)` entries of 12 bytes
let data = u64_at(body, 8)?;
let entries = usize::try_from(u32_at(body, 24)?).ok()?;
let mut table = Vec::new();
for i in 0..entries.min(MAX_DS64_TABLE) {
let at = 28usize.checked_add(i.checked_mul(12)?)?;
let id = <[u8; 4]>::try_from(body.get(at..at.checked_add(4)?)?).ok()?;
table.push((id, u64_at(body, at + 4)?));
}
Some(Ds64 { data, table })
}
/// The chunks of a WAVE file as `(id, body)`, stopping at the first one that doesn't fit.
fn chunks<'a>(bytes: &'a [u8], limited: &mut bool) -> Vec<([u8; 4], &'a [u8])> {
let big = ds64(bytes);
let mut out = Vec::new();
let mut at = 12usize;
while let Some(head) = bytes.get(at..at.saturating_add(8)) {
if out.len() == MAX_CHUNKS {
*limited = true;
break;
}
let (Ok(id), Some(field)) = (<[u8; 4]>::try_from(&head[..4]), u32_at(head, 4)) else { break };
// In an RF64 file a size field of 0xFFFFFFFF stands for the size `ds64` gives.
let size = match &big {
Some(d) if field == u32::MAX => d.size_of(&id).unwrap_or(u64::from(field)),
_ => u64::from(field),
};
let start = at.saturating_add(8);
let Some(end) = usize::try_from(size).ok().and_then(|n| start.checked_add(n)) else { break };
let Some(body) = bytes.get(start..end) else { break };
out.push((id, body));
// Chunks are padded to an even size.
at = end.saturating_add(end & 1);
}
out
}
/// Read bounded cue/adtl and XMP metadata without interpreting application timeline policy.
pub fn read(bytes: &[u8]) -> Markers {
if !is_wav(bytes) {
return Markers::default();
}
let mut limited = false;
let chunks = chunks(bytes, &mut limited);
let rate = chunks.iter().find(|(id, _)| id == b"fmt ").and_then(|(_, b)| u32_at(b, 4)).map_or(0.0, f64::from);
let cue = cue_markers(&chunks, rate, &mut limited);
let xmp = chunks.iter().find(|(id, _)| id == b"_PMX").map_or_else(Vec::new, |(_, xmp)| xmp_markers(xmp, rate));
Markers { cue, xmp, limited }
}
/// Cue points named and sized by the `adtl` list.
fn cue_markers(chunks: &[([u8; 4], &[u8])], rate: f64, limited: &mut bool) -> Vec<Marker> {
let Some((_, cue)) = chunks.iter().find(|(id, _)| id == b"cue ") else { return Vec::new() };
let count = (u32_at(cue, 0).unwrap_or(0) as usize).min(MAX_MARKERS);
// The cue points first: `(id, offset in samples)`.
let mut points = Vec::new();
for i in 0..count {
let Some(point) = cue.get(4usize.saturating_add(i.saturating_mul(24))..) else { break };
let (Some(id), Some(offset)) = (u32_at(point, 0), u32_at(point, 20)) else { break };
points.push((id, offset));
}
// Only the names and lengths of those ids are kept, so a hostile `adtl` list cannot grow them past the cue count,
// and each record is a lookup, not a scan.
let wanted: HashSet<u32> = points.iter().map(|(id, _)| *id).collect();
let mut names: HashMap<u32, String> = HashMap::new();
let mut lengths: HashMap<u32, u32> = HashMap::new();
let mut name_bytes = 0usize;
let mut records = 0usize;
'lists: for (_, list) in chunks.iter().filter(|(id, b)| id == b"LIST" && b.get(0..4) == Some(b"adtl")) {
let mut at = 4usize;
while let Some(head) = list.get(at..at.saturating_add(8)) {
let (Ok(id), Some(size)) = (<[u8; 4]>::try_from(&head[..4]), u32_at(head, 4)) else { break };
let start = at.saturating_add(8);
let Some(end) = start.checked_add(size as usize) else { break };
let Some(body) = list.get(start..end) else { break };
records += 1;
if records > MAX_ADTL_RECORDS {
break 'lists;
}
if let Some(cue_id) = u32_at(body, 0).filter(|c| wanted.contains(c)) {
match &id {
// A `labl` is the name; a `note` only when there is none.
b"labl" | b"note" if id == *b"labl" || !names.contains_key(&cue_id) => {
let without_old = name_bytes.saturating_sub(names.get(&cue_id).map_or(0, String::len));
let text = label(body.get(4..).unwrap_or_default())
.filter(|text| text.len() <= MAX_LABEL_TOTAL_BYTES.saturating_sub(without_old))
.unwrap_or_else(|| {
*limited = true;
String::new()
});
name_bytes = without_old + text.len();
names.insert(cue_id, text);
}
// The first `ltxt` of a cue point gives its length.
b"ltxt" => {
lengths.entry(cue_id).or_insert_with(|| u32_at(body, 4).unwrap_or(0));
}
_ => {}
}
}
at = end.saturating_add(end & 1);
}
}
let mut emitted_bytes = 0usize;
points
.into_iter()
.map(|(id, offset)| {
let comment = match names.get(&id) {
Some(text) if text.len() <= MAX_LABEL_TOTAL_BYTES.saturating_sub(emitted_bytes) => {
emitted_bytes += text.len();
text.clone()
}
Some(_) => {
*limited = true;
String::new()
}
None => String::new(),
};
let length = lengths.get(&id).copied().unwrap_or(0);
Marker { start: f64::from(offset), duration: f64::from(length), rate, name: comment }
})
.collect()
}
/// The text of `name` in an XMP entry, as an attribute (`name="v"`) or an element
/// (`<name>v</name>`).
fn xmp_value(entry: &str, name: &str) -> Option<String> {
// Each entry starts just after `<rdf:li`. Scan only tag attributes, skipping
// quoted values so a label containing an attribute-like string cannot spoof it.
let bytes = entry.as_bytes();
let mut at = 0;
let mut in_tag = true;
while at < bytes.len() {
match bytes[at] {
b'<' => in_tag = true,
b'>' => in_tag = false,
b'\'' | b'"' if in_tag => {
let quote = bytes[at];
at += 1;
while at < bytes.len() && bytes[at] != quote {
at += 1;
}
}
_ if in_tag && (at == 0 || xml_space(bytes[at - 1])) && bytes[at..].starts_with(name.as_bytes()) => {
let mut value = at + name.len();
while value < bytes.len() && xml_space(bytes[value]) {
value += 1;
}
if bytes.get(value) == Some(&b'=') {
value += 1;
while value < bytes.len() && xml_space(bytes[value]) {
value += 1;
}
if let Some(&quote @ (b'\'' | b'"')) = bytes.get(value) {
let start = value + 1;
let end = bytes.get(start..)?.iter().position(|&b| b == quote)? + start;
return Some(unescape(entry.get(start..end)?));
}
}
}
_ => {}
}
at += 1;
}
let open = format!("<{name}>");
let i = entry.find(&open)?;
let rest = entry.get(i + open.len()..)?;
Some(unescape(rest.get(..rest.find('<')?)?))
}
fn xml_space(b: u8) -> bool {
matches!(b, b' ' | b'\t' | b'\r' | b'\n')
}
fn unescape(s: &str) -> String {
let mut out = String::with_capacity(s.len());
let mut rest = s;
while let Some(i) = rest.find('&') {
out.push_str(rest.get(..i).unwrap_or_default());
let tail = rest.get(i..).unwrap_or_default();
let Some(semi) = tail.as_bytes().iter().take(11).position(|b| *b == b';') else {
out.push('&');
rest = tail.get(1..).unwrap_or_default();
continue;
};
let ent = tail.get(1..semi).unwrap_or_default();
match ent {
"amp" => out.push('&'),
"lt" => out.push('<'),
"gt" => out.push('>'),
"quot" => out.push('"'),
"apos" => out.push('\''),
_ => {
let code = ent
.strip_prefix("#x")
.and_then(|h| u32::from_str_radix(h, 16).ok())
.or_else(|| ent.strip_prefix('#').and_then(|d| d.parse().ok()));
match code.and_then(char::from_u32) {
Some(c) => out.push(c),
None => out.push_str(tail.get(..=semi).unwrap_or_default()),
}
}
}
rest = tail.get(semi + 1..).unwrap_or_default();
}
out.push_str(rest);
out.trim().to_string()
}
/// A frame rate as XMP writes it: `f44100`, or `f30000s1001` (rate over scale).
fn xmp_rate(text: &str) -> Option<f64> {
let t = text.trim().strip_prefix('f')?;
let (num, den) = t.split_once('s').unwrap_or((t, "1"));
let (n, d): (f64, f64) = (num.parse().ok()?, den.parse().ok()?);
(n.is_finite() && d.is_finite() && n > 0.0 && d > 0.0 && (n / d).is_finite() && n / d > 0.0).then_some(n / d)
}
/// Adobe XMP FrameCount: a count optionally followed by `fRATE[sSCALE]`.
/// Bare counts retain the caller's legacy track/file-rate interpretation.
fn xmp_count(text: &str, default_rate: f64) -> Option<(f64, f64)> {
let text = text.trim();
let (count, rate) = match text.find('f') {
Some(at) => (text.get(..at)?, xmp_rate(text.get(at..)?)?),
None => (text, default_rate),
};
let count: f64 = count.parse().ok()?;
(count.is_finite() && rate.is_finite() && rate > 0.0).then_some((count, rate))
}
/// The markers of an XMP packet's `xmpDM:markers` entries.
fn xmp_markers(packet: &[u8], file_rate: f64) -> Vec<Marker> {
let text = String::from_utf8_lossy(packet.get(..packet.len().min(MAX_XMP)).unwrap_or_default());
let mut out = Vec::new();
// The frame rate belongs to the track an entry follows.
let mut rate = file_rate;
for entry in text.split("<rdf:li").skip(1) {
if let Some(r) = xmp_value(entry, "xmpDM:frameRate").as_deref().and_then(xmp_rate) {
rate = r;
}
let Some((start, marker_rate)) = xmp_value(entry, "xmpDM:startTime").and_then(|v| xmp_count(&v, rate)) else { continue };
let length = xmp_value(entry, "xmpDM:duration")
.and_then(|v| xmp_count(&v, rate))
.map(|(count, duration_rate)| if duration_rate == marker_rate { count } else { count / duration_rate * marker_rate })
.unwrap_or(0.0);
if !length.is_finite() {
continue;
}
let comment = xmp_value(entry, "xmpDM:name").unwrap_or_default();
out.push(Marker { start, duration: length, rate: marker_rate, name: comment });
if out.len() >= MAX_MARKERS {
break;
}
}
out
}
#[cfg(test)]
mod tests {
use super::*;
struct TimedMarker {
time: f64,
duration: f64,
comment: String,
}
fn read(bytes: &[u8]) -> Vec<TimedMarker> {
let metadata = super::read(bytes);
let time = |frames: f64, rate: f64| if rate > 0.0 && frames.is_finite() { (frames / rate).max(0.0) } else { 0.0 };
let map = |m: Marker| TimedMarker { time: time(m.start, m.rate), duration: time(m.duration, m.rate), comment: m.name };
let mut out: Vec<_> = metadata.cue.into_iter().map(map).collect();
let mut seen: HashSet<_> = out.iter().map(|m| (m.comment.clone(), m.time.to_bits())).collect();
for m in metadata.xmp.into_iter().map(map) {
if seen.insert((m.comment.clone(), m.time.to_bits())) {
out.push(m);
}
}
out.truncate(MAX_MARKERS);
out.sort_by(|a, b| a.time.total_cmp(&b.time));
out
}
fn chunk(id: &[u8; 4], body: &[u8]) -> Vec<u8> {
let mut v = id.to_vec();
v.extend((body.len() as u32).to_le_bytes());
v.extend(body);
if body.len() % 2 == 1 {
v.push(0);
}
v
}
fn fmt(rate: u32) -> Vec<u8> {
let mut b = Vec::new();
b.extend(1u16.to_le_bytes()); // PCM
b.extend(1u16.to_le_bytes()); // mono
b.extend(rate.to_le_bytes());
b.extend((rate * 2).to_le_bytes());
b.extend(2u16.to_le_bytes());
b.extend(16u16.to_le_bytes());
chunk(b"fmt ", &b)
}
fn wav(chunks: &[Vec<u8>]) -> Vec<u8> {
let body: Vec<u8> = chunks.iter().flatten().copied().collect();
let mut v = b"RIFF".to_vec();
v.extend((body.len() as u32 + 4).to_le_bytes());
v.extend(b"WAVE");
v.extend(body);
v
}
fn cue(points: &[(u32, u32)]) -> Vec<u8> {
let mut b = (points.len() as u32).to_le_bytes().to_vec();
for (id, offset) in points {
b.extend(id.to_le_bytes());
b.extend(0u32.to_le_bytes());
b.extend(b"data");
b.extend(0u32.to_le_bytes());
b.extend(0u32.to_le_bytes());
b.extend(offset.to_le_bytes());
}
chunk(b"cue ", &b)
}
fn labl(id: &[u8; 4], cue_id: u32, text: &str) -> Vec<u8> {
let mut b = cue_id.to_le_bytes().to_vec();
b.extend(text.as_bytes());
b.push(0);
chunk(id, &b)
}
fn adtl(subs: &[Vec<u8>]) -> Vec<u8> {
let mut b = b"adtl".to_vec();
b.extend(subs.iter().flatten());
chunk(b"LIST", &b)
}
#[test]
fn cue_points_are_named_by_the_adtl_list_and_timed_in_samples() {
let file = wav(&[
fmt(44100),
chunk(b"data", &[0; 8]),
cue(&[(2, 88200), (1, 22050)]),
adtl(&[labl(b"labl", 1, "SEQ01_Prologue"), labl(b"labl", 2, "SEQ02_Vallee_P1_Agriculture")]),
]);
let m = read(&file);
assert_eq!(m.len(), 2);
assert_eq!((m[0].comment.as_str(), m[0].time), ("SEQ01_Prologue", 0.5));
assert_eq!((m[1].comment.as_str(), m[1].time), ("SEQ02_Vallee_P1_Agriculture", 2.0));
}
#[test]
fn a_note_names_a_cue_only_when_it_has_no_label_and_ltxt_gives_a_length() {
let mut ltxt = 1u32.to_le_bytes().to_vec();
ltxt.extend(44100u32.to_le_bytes());
ltxt.extend([0; 16]);
let file = wav(&[
fmt(44100),
cue(&[(1, 0), (2, 44100)]),
adtl(&[labl(b"note", 1, "from note"), chunk(b"ltxt", &ltxt), labl(b"labl", 2, "named"), labl(b"note", 2, "ignored")]),
]);
let m = read(&file);
assert_eq!((m[0].comment.as_str(), m[0].duration), ("from note", 1.0));
assert_eq!(m[1].comment, "named");
}
const XMP_ELEMENTS: &str = r#"<x:xmpmeta><rdf:RDF><rdf:Description><xmpDM:Tracks><rdf:Bag><rdf:li rdf:parseType="Resource"><xmpDM:trackName>Markers</xmpDM:trackName><xmpDM:trackType>Cue</xmpDM:trackType><xmpDM:frameRate>f44100</xmpDM:frameRate><xmpDM:markers><rdf:Seq><rdf:li rdf:parseType="Resource"><xmpDM:startTime>44100</xmpDM:startTime><xmpDM:duration>0</xmpDM:duration><xmpDM:name>One &amp; Two</xmpDM:name></rdf:li><rdf:li rdf:parseType="Resource"><xmpDM:startTime>132300</xmpDM:startTime><xmpDM:duration>22050</xmpDM:duration><xmpDM:name>Three</xmpDM:name></rdf:li></rdf:Seq></xmpDM:markers></rdf:li></rdf:Bag></xmpDM:Tracks></rdf:Description></rdf:RDF></x:xmpmeta>"#;
#[test]
fn xmp_markers_are_read_as_elements_in_frames_of_the_track_rate() {
let file = wav(&[fmt(48000), chunk(b"_PMX", XMP_ELEMENTS.as_bytes())]);
let m = read(&file);
assert_eq!(m.len(), 2);
// 44100 frames at f44100 is one second, whatever the file's own rate.
assert_eq!((m[0].comment.as_str(), m[0].time), ("One & Two", 1.0));
assert_eq!((m[1].comment.as_str(), m[1].time, m[1].duration), ("Three", 3.0, 0.5));
}
#[test]
fn xmp_markers_are_read_as_attributes_and_use_the_file_rate_without_a_track_rate() {
let xmp = r#"<rdf:Seq><rdf:li xmpDM:startTime="24000" xmpDM:duration="0" xmpDM:name="Attr &#233;"/></rdf:Seq>"#;
let m = read(&wav(&[fmt(48000), chunk(b"_PMX", xmp.as_bytes())]));
assert_eq!((m[0].comment.as_str(), m[0].time), ("Attr é", 0.5));
}
#[test]
fn a_marker_in_both_encodings_is_listed_once() {
let xmp = r#"<rdf:li xmpDM:startTime="44100" xmpDM:name="Same"/><rdf:li xmpDM:startTime="88200" xmpDM:name="Only XMP"/>"#;
let file = wav(&[fmt(44100), cue(&[(1, 44100)]), adtl(&[labl(b"labl", 1, "Same")]), chunk(b"_PMX", xmp.as_bytes())]);
let names: Vec<String> = read(&file).into_iter().map(|m| m.comment).collect();
assert_eq!(names, ["Same", "Only XMP"]);
}
#[test]
fn damaged_or_hostile_files_read_as_far_as_they_go_without_panicking() {
assert!(read(b"").is_empty());
assert!(read(b"RIFF").is_empty());
assert!(read(b"not a wav file at all").is_empty());
let good = wav(&[fmt(44100), cue(&[(1, 44100)]), adtl(&[labl(b"labl", 1, "Kept")])]);
// Every truncation is safe.
for n in 0..good.len() {
let _ = read(&good[..n]);
}
// A cue count far beyond the chunk, and chunk sizes past the end of the file.
let mut huge = 0xFFFF_FFFFu32.to_le_bytes().to_vec();
huge.extend([0; 24]);
let m = read(&wav(&[fmt(44100), chunk(b"cue ", &huge)]));
assert!(m.len() <= 1);
let mut lying = good.clone();
lying.extend(b"LIST\xff\xff\xff\xffadtl");
assert_eq!(read(&lying).len(), 1);
// No sample rate: times are zero, not a division by zero.
let m = read(&wav(&[cue(&[(1, 44100)])]));
assert_eq!(m[0].time, 0.0);
}
/// A chunk whose size field says `field` (an RF64 file's `0xFFFFFFFF`) while its body is `body`.
fn chunk_with_size_field(id: &[u8; 4], field: u32, body: &[u8]) -> Vec<u8> {
let mut v = id.to_vec();
v.extend(field.to_le_bytes());
v.extend(body);
if body.len() % 2 == 1 {
v.push(0);
}
v
}
/// An RF64 `ds64` chunk: the `data` chunk's size and a table of other chunks' sizes.
fn ds64_chunk(data_size: u64, table: &[([u8; 4], u64)]) -> Vec<u8> {
let mut b = 0u64.to_le_bytes().to_vec(); // riff size (not used)
b.extend(data_size.to_le_bytes());
b.extend(0u64.to_le_bytes()); // sample count
b.extend((table.len() as u32).to_le_bytes());
for (id, size) in table {
b.extend(id);
b.extend(size.to_le_bytes());
}
chunk(b"ds64", &b)
}
fn rf64(chunks: &[Vec<u8>]) -> Vec<u8> {
let body: Vec<u8> = chunks.iter().flatten().copied().collect();
let mut v = b"RF64".to_vec();
v.extend(u32::MAX.to_le_bytes());
v.extend(b"WAVE");
v.extend(body);
v
}
#[test]
fn rf64_markers_after_a_data_chunk_of_sentinel_size_are_read() {
let audio = [0u8; 8];
let file = rf64(&[
ds64_chunk(audio.len() as u64, &[]),
fmt(44100),
chunk_with_size_field(b"data", u32::MAX, &audio),
cue(&[(1, 44100)]),
adtl(&[labl(b"labl", 1, "After the audio")]),
]);
let m = read(&file);
assert_eq!(m.len(), 1);
assert_eq!((m[0].comment.as_str(), m[0].time), ("After the audio", 1.0));
}
#[test]
fn rf64_sizes_of_other_chunks_come_from_the_ds64_table() {
let junk = [7u8; 6];
let tail = || [cue(&[(1, 8000)]), adtl(&[labl(b"labl", 1, "Found")])].concat();
let with_entry = rf64(&[ds64_chunk(0, &[(*b"junk", junk.len() as u64)]), fmt(8000), chunk_with_size_field(b"junk", u32::MAX, &junk), tail()]);
assert_eq!(read(&with_entry)[0].comment, "Found");
// Without the table entry the sentinel is all there is, and what follows is not reached.
let without = rf64(&[ds64_chunk(0, &[]), fmt(8000), chunk_with_size_field(b"junk", u32::MAX, &junk), tail()]);
assert!(read(&without).is_empty());
}
#[test]
fn hostile_rf64_size_tables_read_as_far_as_they_go_without_panicking() {
// sizes that overflow when added to an offset
for data in [u64::MAX, u64::MAX - 7, 1 << 63] {
let file =
rf64(&[ds64_chunk(data, &[(*b"junk", u64::MAX)]), fmt(8000), chunk_with_size_field(b"data", u32::MAX, &[0; 4]), cue(&[(1, 0)])]);
assert!(read(&file).is_empty());
}
// a table that claims far more entries than its chunk holds
let mut liar = ds64_chunk(0, &[]);
liar[8 + 24..8 + 28].copy_from_slice(&u32::MAX.to_le_bytes());
let _ = read(&rf64(&[liar, fmt(8000), cue(&[(1, 0)])]));
// every truncation of a good RF64 file is safe
let good = rf64(&[
ds64_chunk(4, &[]),
fmt(44100),
chunk_with_size_field(b"data", u32::MAX, &[0; 4]),
cue(&[(1, 44100)]),
adtl(&[labl(b"labl", 1, "Kept")]),
]);
assert_eq!(read(&good).len(), 1);
for n in 0..good.len() {
let _ = read(&good[..n]);
}
}
#[test]
fn a_huge_adtl_list_is_read_in_linear_time_and_only_for_the_cue_points_that_exist() {
// Records for ids that have no cue point are skipped, not stored, and the number looked at is capped.
let junk = |n: u32| (1000..1000 + n).map(|id| labl(b"labl", id, "n")).collect::<Vec<_>>();
let started = std::time::Instant::now();
// the real label comes first: read
let mut subs = vec![labl(b"labl", 1, "Real")];
subs.extend(junk(100_000));
let m = read(&wav(&[fmt(44100), cue(&[(1, 44100)]), adtl(&subs)]));
assert_eq!(m[0].comment, "Real");
// it comes after more records than are looked at: not read, and the marker is still there
let mut subs = junk(MAX_ADTL_RECORDS as u32 + 10);
subs.push(labl(b"labl", 1, "Too late"));
let m = read(&wav(&[fmt(44100), cue(&[(1, 44100)]), adtl(&subs)]));
assert_eq!((m.len(), m[0].comment.as_str()), (1, ""));
assert!(started.elapsed() < std::time::Duration::from_secs(5), "took {:?}", started.elapsed());
}
#[test]
fn metadata_keeps_original_coordinates_and_separate_sources() {
let xmp = br#"<rdf:li xmpDM:startTime="1" xmpDM:duration="2" xmpDM:name="Same"/>"#;
let file = wav(&[fmt(44100), cue(&[(1, 1)]), adtl(&[labl(b"labl", 1, "Same")]), chunk(b"_PMX", xmp)]);
let data = super::read(&file);
assert_eq!(data.cue[0].start, 1.0);
assert_eq!(data.cue[0].rate, 44100.0);
assert_eq!(data.xmp[0].start, 1.0);
assert_eq!(data.xmp[0].duration, 2.0);
assert_eq!(data.cue.len(), 1);
assert_eq!(data.xmp.len(), 1);
}
#[test]
fn repeated_unterminated_entities_preserve_text_with_bounded_lookahead() {
let text = "&".repeat(100_000);
assert_eq!(unescape(&text), text);
assert_eq!(unescape("&#0000065; &#00000065; &amp; &unknown;"), "A A & &unknown;");
}
#[test]
fn repeated_cue_ids_cannot_multiply_label_storage() {
let text = "x".repeat(MAX_LABEL_BYTES);
let points: Vec<_> = (0..MAX_MARKERS).map(|i| (1, i as u32)).collect();
let file = wav(&[fmt(44100), cue(&points), adtl(&[labl(b"labl", 1, &text)])]);
let metadata = super::read(&file);
assert_eq!(metadata.cue.len(), MAX_MARKERS);
assert_eq!(metadata.cue.iter().map(|m| m.name.len()).sum::<usize>(), MAX_LABEL_TOTAL_BYTES);
assert!(metadata.limited);
assert_eq!(metadata.cue[0].name, text);
assert!(metadata.cue[MAX_MARKERS - 1].name.is_empty());
assert_eq!(metadata.cue[MAX_MARKERS - 1].start, (MAX_MARKERS - 1) as f64);
}
#[test]
fn cue_name_map_and_single_label_are_bounded() {
let count = MAX_LABEL_TOTAL_BYTES / MAX_LABEL_BYTES + 2;
let text = "x".repeat(MAX_LABEL_BYTES);
let points: Vec<_> = (0..count as u32).map(|i| (i, i)).collect();
let labels: Vec<_> = (0..count as u32).map(|i| labl(b"labl", i, &text)).collect();
let metadata = super::read(&wav(&[fmt(44100), cue(&points), adtl(&labels)]));
assert!(metadata.limited);
assert_eq!(metadata.cue.iter().map(|m| m.name.len()).sum::<usize>(), MAX_LABEL_TOTAL_BYTES);
let oversized = "x".repeat(MAX_LABEL_BYTES + 1);
let metadata = super::read(&wav(&[fmt(44100), cue(&[(1, 3)]), adtl(&[labl(b"labl", 1, &oversized)])]));
assert!(metadata.limited);
assert_eq!(metadata.cue[0].start, 3.0);
assert!(metadata.cue[0].name.is_empty());
}
#[test]
fn empty_chunk_inventory_is_bounded() {
let empty = chunk(b"junk", &[]);
let many = empty.repeat(MAX_CHUNKS + 1);
let metadata = super::read(&wav(&[many, fmt(44100), cue(&[(1, 1)])]));
assert!(metadata.limited);
assert!(metadata.cue.is_empty());
}
#[test]
fn entity_lookahead_keeps_previous_semicolon_boundary() {
assert_eq!(unescape("&#00000065;"), "A");
assert_eq!(unescape("&#000000065;"), "&#000000065;");
}
#[test]
fn xmp_quotes_spacing_and_attribute_boundaries() {
let packet = br#"<rdf:li xmpDM:startTime = '24000' xmpDM:duration =
'12000' xmpDM:name='single &amp; quoted'/>"#;
let markers = xmp_markers(packet, 48000.0);
assert_eq!(markers.len(), 1);
assert_eq!((markers[0].start, markers[0].duration, markers[0].rate), (24000.0, 12000.0, 48000.0));
assert_eq!(markers[0].name, "single & quoted");
let spoof = r#" label=" xmpDM:startTime='7'" otherxmpDM:startTime='8' xmpDM:startTime = '9'/>"#;
assert_eq!(xmp_value(spoof, "xmpDM:startTime").as_deref(), Some("9"));
assert!(xmp_value(" xmpDM:startTime='unterminated", "xmpDM:startTime").is_none());
}
#[test]
fn xmp_frame_counts_preserve_explicit_and_mixed_rates() {
let packet = br#"<rdf:li xmpDM:frameRate='f48000'><rdf:li xmpDM:startTime='15f24' xmpDM:duration='15f30000s1001'/><rdf:li xmpDM:startTime='48000' xmpDM:duration='12f24'/><rdf:li xmpDM:startTime='15f24' xmpDM:duration='24000'/></rdf:li>"#;
let markers = xmp_markers(packet, 44100.0);
assert_eq!(markers.len(), 3);
assert_eq!((markers[0].start, markers[0].rate), (15.0, 24.0));
assert!((markers[0].duration / markers[0].rate - 0.5005).abs() < 1e-12);
assert_eq!((markers[1].start, markers[1].duration, markers[1].rate), (48000.0, 24000.0, 48000.0));
assert_eq!((markers[2].start, markers[2].duration, markers[2].rate), (15.0, 12.0, 24.0));
for invalid in ["15f0", "15f24s0", "15fNaN", "15finf", "NaN", "1e999", "15f24junk"] {
assert!(xmp_count(invalid, 48000.0).is_none(), "{invalid}");
}
}
}
+17 -10
View File
@@ -12,7 +12,7 @@ mod pcm;
#[cfg(feature = "vorbis-encode")]
mod vorbis;
#[cfg(feature = "vorbis-encode")]
pub use vorbis::{OGG_BITRATES, encode as encode_ogg};
pub use vorbis::{OGG_BITRATES, OggVorbisOptions, encode as encode_ogg, encode_ogg_vorbis, quality_for_bitrate};
#[cfg(feature = "pcm-encode")]
mod raw;
#[cfg(feature = "pcm-encode")]
@@ -66,15 +66,22 @@ pub fn encode(buf: &AudioBuffer, opts: &EncodeOptions) -> Result<Vec<u8>> {
EncodeFormat::Aac | EncodeFormat::Alac | EncodeFormat::Mp3 | EncodeFormat::Ac3 | EncodeFormat::Eac3 => coded::encode(buf, opts),
#[cfg(feature = "vorbis-encode")]
EncodeFormat::Ogg => {
if opts.layout.is_some_and(|layout| !EncodeFormat::Ogg.supports_layout(&layout)) {
return Err(AudioError::Unsupported("Vorbis requires a mono or stereo speaker layout".into()));
let count = u16::try_from(buf.channels.len()).unwrap_or(u16::MAX);
let layout = opts.layout.unwrap_or_else(|| ChannelLayout::default_for(count));
if layout.channels() != count {
return Err(AudioError::Unsupported(format!("a {}-channel layout for {count} channels", layout.channels())));
}
let kbps = match opts.rate_control {
None => 192,
Some(crate::RateControl::Bitrate(bps)) => bps / 1000,
Some(crate::RateControl::Quality(_)) => return Err(AudioError::Unsupported("Ogg export takes a target bitrate".into())),
let map = vorbis::vorbis_map(&layout)?;
let quality = match opts.rate_control {
None => vorbis::quality_for_bitrate(192, buf.channels.len()),
Some(crate::RateControl::Bitrate(bps)) => {
vorbis::quality_for_bitrate((bps / 1000).clamp(OGG_BITRATES.0, OGG_BITRATES.1), buf.channels.len())
}
Some(crate::RateControl::Quality(q)) if q.is_nan() => return Err(AudioError::Encode("the Vorbis quality is NaN".into())),
Some(crate::RateControl::Quality(q)) => -1.0 + 11.0 * q.clamp(0.0, 1.0),
};
vorbis::encode(buf, kbps)
let planar: Vec<&[f32]> = map.iter().filter_map(|&i| buf.channels.get(i).map(Vec::as_slice)).collect();
vorbis::encode_planar(buf.sample_rate, &planar, &OggVorbisOptions::new(quality))
}
#[allow(unreachable_patterns)]
f => Err(AudioError::Unsupported(format!("writing {f:?}"))),
@@ -106,7 +113,7 @@ const fn extensions() -> ([&'static str; 13], usize) {
add!(cfg!(feature = "mp3-encode"), "mp3");
add!(cfg!(feature = "ac3-encode"), "ac3");
add!(cfg!(feature = "eac3-encode"), "eac3", "ec3");
add!(cfg!(all(feature = "vorbis-encode", not(target_arch = "wasm32"))), "ogg");
add!(cfg!(feature = "vorbis-encode"), "ogg");
(all, n)
}
@@ -148,7 +155,7 @@ pub fn encode_format_for(name: &str) -> Option<EncodeFormat> {
"ac3" => Some(EncodeFormat::Ac3),
#[cfg(feature = "eac3-encode")]
"eac3" | "ec3" => Some(EncodeFormat::Eac3),
#[cfg(all(feature = "vorbis-encode", not(target_arch = "wasm32")))]
#[cfg(feature = "vorbis-encode")]
"ogg" => Some(EncodeFormat::Ogg),
_ => None,
}
+217 -80
View File
@@ -1,83 +1,198 @@
//! Ogg Vorbis encoding (RFC 5334): the reference libvorbis encoder, built from its C sources by
//! `vorbis_rs`. Stereo or mono, variable bitrate at the requested kbit/s (64–500), with a
//! fallback to a quality preset when the bitrate is not supported for the rate and channel count.
//! Ogg Vorbis files (Vorbis I §A, RFC 5334) from the pure-Rust [`crate::vorbis::encoder`] and
//! craft-media's Ogg page writer: 1 to 8 channels in Vorbis channel order, a quality from -1 to
//! 10 (variable bit rate), and the tags in the comment header. Builds for every target.
use crate::{AudioBuffer, AudioError, Result};
use craft_media::ogg::{PageWriter, vorbis_comment};
/// The bitrates an Ogg Vorbis export is asked for, in kbit/s.
use crate::vorbis::encoder::{DEFAULT_QUALITY, Encoder, EncoderConfig, Error as VorbisError};
use crate::{AudioBuffer, AudioError, ChannelLayout, Result};
/// The bit rates [`encode_ogg`](crate::encode_ogg) takes, in kbit/s. Vorbis is variable: the bit rate picks a
/// quality ([`quality_for_bitrate`]), and the file comes out near it for typical music.
pub const OGG_BITRATES: (u32, u32) = (64, 500);
/// The block size the encoder processes at a time: small enough that memory stays bounded
/// regardless of file length.
#[cfg(not(target_arch = "wasm32"))]
const BLOCK: usize = 4096;
/// The serial number of the stream when the options do not set one (`LCRF`): one stream per file,
/// so a constant keeps files byte-for-byte reproducible.
const SERIAL: u32 = 0x4C43_5246;
#[cfg(not(target_arch = "wasm32"))]
fn encode_error(e: vorbis_rs::VorbisError) -> AudioError {
AudioError::Encode(e.to_string())
/// Samples per channel fed to the encoder at a time.
const CHUNK: usize = 4096;
/// What [`encode_ogg_vorbis`] writes besides the audio.
///
/// `#[non_exhaustive]`: build it with `OggVorbisOptions::default()` or
/// [`OggVorbisOptions::new`] and the `with_*` methods.
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq)]
pub struct OggVorbisOptions {
/// -1 (smallest) to 10 (best); clamped, and NaN or infinite reads as
/// [`DEFAULT_QUALITY`] (6).
pub quality: f32,
/// The comment header's vendor string.
pub vendor: String,
/// `NAME=value` comments (Vorbis I §5), in order. A name that is empty, or holds `=` or a byte
/// outside 0x20–0x7D, is left out.
pub tags: Vec<(String, String)>,
/// The logical stream's serial number.
pub serial: u32,
}
/// Encode `buf` as an Ogg Vorbis stream at about `kbps` (variable, as Vorbis is): stereo, or mono
/// for a mono buffer. A bitrate the encoder has no setup for at that rate and channel count falls
/// back to a quality that suits it. `Err` says why there is nothing.
#[cfg(not(target_arch = "wasm32"))]
pub fn encode(buf: &AudioBuffer, kbps: u32) -> Result<Vec<u8>> {
use std::num::{NonZeroU8, NonZeroU32};
let channels = buf.channels.len();
if !(1..=2).contains(&channels) {
return Err(AudioError::Unsupported("Ogg Vorbis export requires mono or stereo audio".into()));
impl Default for OggVorbisOptions {
fn default() -> Self {
OggVorbisOptions { quality: DEFAULT_QUALITY, vendor: "craft-audio".into(), tags: Vec::new(), serial: SERIAL }
}
if buf.channels.iter().any(|c| c.len() != buf.frames() || c.iter().any(|s| !s.is_finite())) {
}
impl OggVorbisOptions {
/// The defaults at `quality`.
pub fn new(quality: f32) -> Self {
OggVorbisOptions { quality, ..Self::default() }
}
/// Sets [`quality`](Self::quality).
pub fn with_quality(mut self, quality: f32) -> Self {
self.quality = quality;
self
}
/// Sets [`vendor`](Self::vendor).
pub fn with_vendor(mut self, vendor: impl Into<String>) -> Self {
self.vendor = vendor.into();
self
}
/// Adds a comment ([`tags`](Self::tags)).
pub fn with_tag(mut self, name: impl Into<String>, value: impl Into<String>) -> Self {
self.tags.push((name.into(), value.into()));
self
}
/// Sets [`serial`](Self::serial).
pub fn with_serial(mut self, serial: u32) -> Self {
self.serial = serial;
self
}
}
fn encode_error(e: VorbisError) -> AudioError {
AudioError::Encode(format!("Vorbis: {e}"))
}
/// Encode `buf` as an Ogg Vorbis file with `opts`. The channels are in Vorbis channel order
/// (Vorbis I §4.3.9: L C R for three, L C R Ls Rs LFE for 5.1, L C R Ls Rs Rl Rr LFE for 7.1).
/// The last granule position is the buffer's length, so a decoder returns exactly its frames.
///
/// ```
/// use craft_audio::{AudioBuffer, OggVorbisOptions, encode_ogg_vorbis};
///
/// let buf = AudioBuffer::new(48_000, 6, 4_800); // 0.1 s of 5.1 silence
/// let opts = OggVorbisOptions::new(4.0).with_tag("TITLE", "Silence");
/// let ogg = encode_ogg_vorbis(&buf, &opts).unwrap();
/// assert!(ogg.starts_with(b"OggS"));
/// ```
pub fn encode_ogg_vorbis(buf: &AudioBuffer, opts: &OggVorbisOptions) -> Result<Vec<u8>> {
let planar: Vec<&[f32]> = buf.channels.iter().map(Vec::as_slice).collect();
encode_planar(buf.sample_rate, &planar, opts)
}
/// [`encode_ogg_vorbis`] over channels already in Vorbis order.
pub(crate) fn encode_planar(sample_rate: u32, planar: &[&[f32]], opts: &OggVorbisOptions) -> Result<Vec<u8>> {
if !(1..=8).contains(&planar.len()) {
return Err(AudioError::Unsupported(format!("Ogg Vorbis holds 1 to 8 channels, not {}", planar.len())));
}
let frames = planar.first().map_or(0, |c| c.len());
if planar.iter().any(|c| c.len() != frames || c.iter().any(|s| !s.is_finite())) {
return Err(AudioError::Encode("Vorbis samples must be finite and channels equally long".into()));
}
let (Some(rate), Some(count)) = (NonZeroU32::new(buf.sample_rate), NonZeroU8::new(channels as u8)) else {
if sample_rate == 0 {
return Err(AudioError::Encode("there is no audio to encode".into()));
};
let target = NonZeroU32::new(kbps.clamp(OGG_BITRATES.0, OGG_BITRATES.1) * 1000).unwrap_or(NonZeroU32::MIN);
let encode = |strategy: vorbis_rs::VorbisBitrateManagementStrategy| -> Result<Vec<u8>> {
let mut encoder = vorbis_rs::VorbisEncoderBuilder::new_with_serial(rate, count, Vec::new(), 0x4C43_5246)
.bitrate_management_strategy(strategy)
.build()
.map_err(encode_error)?;
let frames = buf.frames();
let mut at = 0usize;
while at < frames {
let end = (at + BLOCK).min(frames);
let block: Vec<&[f32]> = buf.channels.iter().take(channels).map(|side| side.get(at..end).unwrap_or_default()).collect();
encoder.encode_audio_block(&block).map_err(encode_error)?;
at = end;
}
let mut enc = Encoder::new(EncoderConfig::new(sample_rate, planar.len(), opts.quality)).map_err(encode_error)?;
let mut pages = PageWriter::new(opts.serial);
let tags: Vec<(&str, &str)> = opts.tags.iter().map(|(k, v)| (k.as_str(), v.as_str())).collect();
let mut out = pages.header(&enc.identification());
out.extend(pages.header(&vorbis_comment(&opts.vendor, &tags)));
out.extend(pages.header(&enc.setup()));
// The first audio packet (which outputs nothing) gets a page of its own: a stream whose first
// audio page is also its last would leave decoders to choose between start and end trimming
// (Vorbis I §A.2), and ffmpeg then plays the padding.
let mut first = true;
let mut add = |packets: Vec<(Vec<u8>, i64)>, out: &mut Vec<u8>| {
for (packet, granule) in packets {
out.extend(pages.packet(&packet, granule));
if std::mem::take(&mut first) {
out.extend(pages.flush());
}
}
encoder.finish().map_err(encode_error)
};
let mut at = 0;
loop {
let end = (at + CHUNK).min(frames);
let chunk: Vec<&[f32]> = planar.iter().map(|c| c.get(at..end).unwrap_or_default()).collect();
add(enc.encode(&chunk).map_err(encode_error)?, &mut out);
at = end;
if at >= frames {
break;
}
}
add(enc.finish().map_err(encode_error)?, &mut out);
out.extend(pages.finish(None));
Ok(out)
}
// Convert Rust unwinds to an error. This does not catch native crashes or aborts.
let attempt = |strategy| {
std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| encode(strategy)))
.unwrap_or_else(|_| Err(AudioError::Encode("the Vorbis encoder failed".into())))
};
match attempt(vorbis_rs::VorbisBitrateManagementStrategy::Vbr { target_bitrate: target }) {
Ok(bytes) => Ok(bytes),
Err(_) => attempt(vorbis_rs::VorbisBitrateManagementStrategy::QualityVbr { target_quality: 0.6 })
.map_err(|e| AudioError::Encode(format!("the Vorbis encoder refused the audio: {e}"))),
/// Nominal kbit/s per channel at each whole quality from -1 to 10: this encoder's rate on
/// music-like test signals at 48 kHz (harmonic chords with noise), averaged.
const KBPS_PER_CHANNEL: [f32; 12] = [18.0, 23.0, 31.0, 43.0, 58.0, 75.0, 89.0, 100.0, 111.0, 121.0, 130.0, 140.0];
/// The quality whose nominal bit rate is `kbps` kbit/s for `channels` channels (clamped to -1..=10).
/// Vorbis is variable: the bit rate of a file depends on the audio.
pub fn quality_for_bitrate(kbps: u32, channels: usize) -> f32 {
let per = kbps as f32 / channels.max(1) as f32;
let mut q = -1.0;
for pair in KBPS_PER_CHANNEL.windows(2) {
if let [lo, hi] = *pair
&& per <= hi
{
return q + ((per - lo) / (hi - lo)).clamp(0.0, 1.0);
}
q += 1.0;
}
10.0
}
/// Encode `buf` as an Ogg Vorbis stream near `kbps` kbit/s ([`OGG_BITRATES`], clamped): the
/// quality [`quality_for_bitrate`] gives, no tags. 1 to 8 channels in Vorbis channel order.
/// `Err` says why there is nothing.
pub fn encode(buf: &AudioBuffer, kbps: u32) -> Result<Vec<u8>> {
let kbps = kbps.clamp(OGG_BITRATES.0, OGG_BITRATES.1);
encode_ogg_vorbis(buf, &OggVorbisOptions::new(quality_for_bitrate(kbps, buf.channels.len())))
}
/// WAV-order speakers ([`crate::EncodeFormat::layout_masks`]) to Vorbis order, per channel count.
const VORBIS_ORDER: [&[usize]; 8] =
[&[0], &[0, 1], &[0, 2, 1], &[0, 1, 2, 3], &[0, 2, 1, 3, 4], &[0, 2, 1, 4, 5, 3], &[0, 2, 1, 5, 6, 4, 3], &[0, 2, 1, 6, 7, 4, 5, 3]];
/// For each Vorbis channel, the channel of audio in `layout` it comes from.
pub(crate) fn vorbis_map(layout: &ChannelLayout) -> Result<Vec<usize>> {
let n = layout.channels();
let mask = crate::EncodeFormat::Ogg.layout_masks(n).first().copied();
let order = usize::from(n).checked_sub(1).and_then(|i| VORBIS_ORDER.get(i)).copied();
match (mask, order) {
(Some(mask), Some(order)) => crate::layout::channel_map(mask, Some(order), layout)
.ok_or_else(|| AudioError::Unsupported(format!("Vorbis has no layout of {n} channels with these speakers"))),
_ => Err(AudioError::Unsupported(format!("Ogg Vorbis holds 1 to 8 channels, not {n}"))),
}
}
/// Ogg Vorbis encoding is unavailable on WASM; returns an unsupported-format error.
#[cfg(target_arch = "wasm32")]
pub fn encode(_buf: &AudioBuffer, _kbps: u32) -> Result<Vec<u8>> {
Err(AudioError::Unsupported("Ogg Vorbis files are exported by the desktop app".into()))
}
#[cfg(all(test, not(target_arch = "wasm32")))]
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used)]
use super::*;
use super::{OGG_BITRATES, OggVorbisOptions, encode, encode_ogg_vorbis, quality_for_bitrate, vorbis_map};
use crate::{AudioBuffer, AudioError, ChannelLayout};
#[test]
fn rejects_unsupported_or_malformed_channels_without_dropping_audio() {
for channels in [0, 3, 6] {
for channels in [0, 9] {
assert!(matches!(encode(&AudioBuffer::new(48_000, channels, 16), 192), Err(AudioError::Unsupported(_))));
}
let ragged = AudioBuffer { sample_rate: 48_000, channels: vec![vec![0.0; 16], vec![0.0; 15]] };
@@ -85,46 +200,68 @@ mod tests {
assert!(encode(&AudioBuffer::new(0, 1, 16), 192).is_err());
let invalid = AudioBuffer { sample_rate: 48_000, channels: vec![vec![f32::NAN]] };
assert!(encode(&invalid, 192).is_err());
let infinite = AudioBuffer { sample_rate: 48_000, channels: vec![vec![f32::INFINITY]] };
assert!(encode(&infinite, 192).is_err());
}
#[test]
fn generic_and_direct_encoders_write_mono_and_stereo_ogg() {
for channels in [1, 2] {
fn generic_and_direct_encoders_write_one_to_eight_channels() {
for channels in 1..=8 {
let audio = AudioBuffer::new(48_000, channels, 512);
let opts = crate::EncodeOptions::new(crate::EncodeFormat::Ogg);
assert!(opts.check(48_000, channels).is_ok());
assert_eq!(opts.bitrate(48_000, channels).unwrap(), None);
let direct = encode(&audio, 192).unwrap();
let generic = crate::encode(&audio, &opts).unwrap();
assert!(direct.starts_with(b"OggS"));
assert_eq!(direct, generic);
// silence: the channel order changes nothing, so the generic path writes the same file
let generic = crate::encode(&audio, &opts.with_bitrate(192_000)).unwrap();
assert_eq!(direct, generic, "{channels} channels");
#[cfg(feature = "decode")]
{
let (info, decoded) = crate::decode(&generic, Some("ogg")).unwrap();
assert_eq!(info.channels, channels);
assert_eq!(decoded.num_channels(), channels);
assert_eq!(decoded.frames(), audio.frames());
}
}
}
#[cfg(feature = "decode")]
#[test]
fn distinct_signals_survive_full_and_partial_blocks() {
for frames in [4096, 4097, 8193] {
let channels: Vec<Vec<f32>> = [440.0f32, 880.0]
.into_iter()
.map(|hz| (0..frames).map(|i| (std::f32::consts::TAU * hz * i as f32 / 48_000.0).sin() * 0.4).collect())
.collect();
let audio = AudioBuffer { sample_rate: 48_000, channels };
let bytes = encode(&audio, 192).unwrap();
let (_, decoded) = crate::decode(&bytes, Some("ogg")).unwrap();
assert_eq!(decoded.frames(), frames);
assert_eq!(decoded.channels.len(), 2);
for (expected, actual) in audio.channels.iter().zip(&decoded.channels) {
let mse = expected.iter().zip(actual).map(|(a, b)| (a - b).powi(2)).sum::<f32>() / frames as f32;
// Vorbis is lossy; this tolerates codec error but rejects silence or swapped channels.
assert!(mse.sqrt() < 0.08, "{frames} frames: RMS error {}", mse.sqrt());
}
fn the_quality_follows_the_bit_rate() {
assert_eq!(quality_for_bitrate(0, 2), -1.0);
assert_eq!(quality_for_bitrate(10_000, 2), 10.0);
assert!((quality_for_bitrate(200, 2) - 6.0).abs() < 1e-6);
assert!((quality_for_bitrate(600, 6) - 6.0).abs() < 1e-6);
let mut last = -2.0;
for kbps in OGG_BITRATES.0..=OGG_BITRATES.1 {
let q = quality_for_bitrate(kbps, 2);
assert!(q >= last && (-1.0..=10.0).contains(&q));
last = q;
}
assert!(quality_for_bitrate(192, 0).is_finite());
}
#[test]
fn layouts_map_to_vorbis_order() {
// 5.1 in WAV order (L R C LFE Ls Rs) is written L C R Ls Rs LFE
assert_eq!(vorbis_map(&ChannelLayout::SURROUND_5_1).unwrap(), [0, 2, 1, 4, 5, 3]);
assert_eq!(vorbis_map(&ChannelLayout::SURROUND_5_1_SIDE).unwrap(), [0, 2, 1, 4, 5, 3]);
assert_eq!(vorbis_map(&ChannelLayout::from_mask(0x63F)).unwrap(), [0, 2, 1, 6, 7, 4, 5, 3]);
assert_eq!(vorbis_map(&ChannelLayout::from_mask(0x7)).unwrap(), [0, 2, 1]);
assert_eq!(vorbis_map(&ChannelLayout::STEREO).unwrap(), [0, 1]);
assert!(vorbis_map(&ChannelLayout::from_mask(0xC)).is_err());
assert!(vorbis_map(&ChannelLayout::unordered(9)).is_err());
assert!(vorbis_map(&ChannelLayout::unordered(0)).is_err());
}
#[test]
fn options_build_and_tags_reach_the_comment_header() {
let opts = OggVorbisOptions::default().with_quality(2.0).with_vendor("v").with_tag("TITLE", "t").with_tag("bad=name", "x").with_serial(9);
assert_eq!((opts.quality, opts.vendor.as_str(), opts.serial, opts.tags.len()), (2.0, "v", 9, 2));
let ogg = encode_ogg_vorbis(&AudioBuffer::new(44_100, 1, 100), &opts).unwrap();
let file = craft_media::ogg::open(&ogg).unwrap();
let s = &file.streams[0];
assert_eq!((s.serial, s.saw_eos, s.headers.len()), (9, true, 3));
assert_eq!(s.headers[1], craft_media::ogg::vorbis_comment("v", &[("TITLE", "t")]));
assert_eq!(s.last_granule, Some(100));
}
}
+2 -2
View File
@@ -20,8 +20,8 @@ fn only_formats_the_encoder_writes_are_named() {
}
#[test]
fn ogg_names_follow_the_native_feature() {
let built = cfg!(all(feature = "vorbis-encode", not(target_arch = "wasm32")));
fn ogg_names_follow_the_feature() {
let built = cfg!(feature = "vorbis-encode");
assert_eq!(EncodeFormat::Ogg.is_built(), built);
assert_eq!(encode_format_for("ogg"), built.then_some(EncodeFormat::Ogg));
assert_eq!(craft_audio::ENCODE_EXTENSIONS.contains(&"ogg"), built);
+1 -1
View File
@@ -527,7 +527,7 @@ fn the_format_queries_agree_with_the_writer() {
// The most channels is the most: one more is refused, by the layouts of a format that has
// a fixed set and by the writer of one that has not.
let most: Vec<u16> = EncodeFormat::ALL.iter().map(|f| f.max_channels()).collect();
assert_eq!(most, [32_767, 32_767, 8, 8, 8, 2, 6, 8, 2]);
assert_eq!(most, [32_767, 32_767, 8, 8, 8, 2, 6, 8, 8]);
for &format in EncodeFormat::ALL {
let most = format.max_channels();
match format.fixed_layouts(most) {
+2
View File
@@ -20,3 +20,5 @@ mod opus;
mod opusenc;
mod routing_oracle;
mod track_decoder;
#[cfg(feature = "vorbis-encode")]
mod vorbis_encoder_oracle;
@@ -0,0 +1,131 @@
//! ffmpeg as an external oracle for the pure-Rust Vorbis encoder: both of its decoders (its own
//! and libvorbis) read every file exactly as long as the input, surround comes out on the right
//! speakers, and the tags reach ffprobe. Skipped when ffmpeg is not installed.
use std::path::Path;
use std::process::Command;
use craft_audio::{AudioBuffer, ChannelLayout, EncodeFormat, EncodeOptions, OggVorbisOptions, encode, encode_ogg_vorbis};
/// A different tone on every channel, so each output channel can be traced to its input.
fn tones(rate: u32, channels: usize, frames: usize) -> AudioBuffer {
let channels = (0..channels)
.map(|c| {
let f = 220.0 * (c + 1) as f32;
(0..frames).map(|i| (std::f32::consts::TAU * f * i as f32 / rate as f32).sin() * 0.3).collect()
})
.collect();
AudioBuffer { sample_rate: rate, channels }
}
/// Decodes `file` with ffmpeg's `decoder`; planar output in ffmpeg's (WAV) channel order.
fn ffmpeg_decode(ff: &Path, decoder: &str, file: &[u8], channels: usize, tag: &str) -> Vec<Vec<f32>> {
let path = crate::testkit::fixtures_dir("vorbis-encoder").join(format!("{tag}.ogg"));
std::fs::write(&path, file).unwrap();
let out = Command::new(ff)
.args(["-v", "error", "-xerror", "-c:a", decoder, "-i"])
.arg(&path)
.args(["-f", "f32le", "-c:a", "pcm_f32le", "-"])
.output()
.unwrap();
assert!(out.status.success() && out.stderr.is_empty(), "{tag} {decoder}: {}", String::from_utf8_lossy(&out.stderr));
let pcm: Vec<f32> = out.stdout.as_chunks::<4>().0.iter().map(|&b| f32::from_le_bytes(b)).collect();
(0..channels).map(|c| pcm.iter().skip(c).step_by(channels).copied().collect()).collect()
}
/// ffmpeg's decoders to check: its own `vorbis` always, and `libvorbis` when ffmpeg has it.
fn decoders(ff: &Path) -> Vec<&'static str> {
let list =
Command::new(ff).args(["-hide_banner", "-decoders"]).output().map(|o| String::from_utf8_lossy(&o.stdout).into_owned()).unwrap_or_default();
if list.lines().any(|l| l.split_whitespace().nth(1) == Some("libvorbis")) {
vec!["vorbis", "libvorbis"]
} else {
eprintln!("SKIPPED (libvorbis decoder): this ffmpeg has no libvorbis; checking its own decoder only");
vec!["vorbis"]
}
}
fn correlation(a: &[f32], b: &[f32]) -> f64 {
let (mut ab, mut aa, mut bb) = (0f64, 0f64, 0f64);
for (&x, &y) in a.iter().zip(b) {
ab += f64::from(x) * f64::from(y);
aa += f64::from(x) * f64::from(x);
bb += f64::from(y) * f64::from(y);
}
ab / (aa * bb).sqrt().max(1e-20)
}
/// Vorbis order (§4.3.9) of the WAV-order layouts the test writes, per channel count.
const VORBIS_ORDER: [&[usize]; 8] =
[&[0], &[0, 1], &[0, 2, 1], &[0, 1, 2, 3], &[0, 2, 1, 3, 4], &[0, 2, 1, 4, 5, 3], &[0, 2, 1, 5, 6, 4, 3], &[0, 2, 1, 6, 7, 4, 5, 3]];
/// 1 to 8 channels through `encode` with a WAV-order layout, at exactly the input's length out of
/// both decoders: ffmpeg's own puts every channel back on its WAV speaker, and libvorbis (through
/// ffmpeg, which passes its order through) gives the file's Vorbis order.
#[test]
fn every_channel_count_decodes_on_the_right_speakers() {
let ff = require_ffmpeg!();
for channels in 1..=8u16 {
let layout = if channels == 7 { ChannelLayout::from_mask(0x70F) } else { ChannelLayout::default_for(channels) };
let buf = tones(48_000, channels.into(), 24_000 + 77);
let opts = EncodeOptions::new(EncodeFormat::Ogg).with_layout(layout).with_quality(0.6);
let file = encode(&buf, &opts).unwrap();
for decoder in decoders(&ff) {
let out = ffmpeg_decode(&ff, decoder, &file, channels.into(), &format!("tones{channels}-{decoder}"));
for (j, got) in out.iter().enumerate() {
let c = if decoder == "libvorbis" { VORBIS_ORDER[usize::from(channels) - 1][j] } else { j };
assert_eq!(got.len(), buf.frames(), "{channels} ch {decoder}: channel {j} length");
let best = (0..buf.channels.len()).max_by(|&a, &b| {
correlation(&buf.channels[a][2048..], &got[2048..]).total_cmp(&correlation(&buf.channels[b][2048..], &got[2048..]))
});
assert_eq!(best, Some(c), "{channels} ch {decoder}: output channel {c} carries input {best:?}");
let r = correlation(&buf.channels[c][2048..], &got[2048..]);
assert!(r > 0.95, "{channels} ch {decoder}: channel {c} correlation {r:.3}");
}
}
}
}
/// The comment header's tags, UTF-8 values included, are what ffprobe reports; a name that is not
/// a valid field name is left out.
#[test]
fn tags_reach_ffprobe() {
let Some(probe) = crate::common::tool("ffprobe").or_else(|| crate::common::skip("ffprobe not found")) else { return };
let opts = OggVorbisOptions::new(3.0)
.with_tag("TITLE", "Smörgåsbord ✓")
.with_tag("ARTIST", "Craft")
.with_tag("bad=name", "dropped")
.with_vendor("craft-audio test");
let file = encode_ogg_vorbis(&tones(44_100, 2, 44_100), &opts).unwrap();
let path = crate::testkit::fixtures_dir("vorbis-encoder").join("tags.ogg");
std::fs::write(&path, &file).unwrap();
let out = Command::new(probe).args(["-v", "error", "-of", "json", "-show_streams", "-show_format"]).arg(&path).output().unwrap();
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
let j: serde_json::Value = serde_json::from_slice(&out.stdout).unwrap();
let s = &j["streams"][0];
assert_eq!((s["codec_name"].as_str(), s["channels"].as_u64(), s["sample_rate"].as_str()), (Some("vorbis"), Some(2), Some("44100")));
let tags = &s["tags"];
assert_eq!((tags["TITLE"].as_str(), tags["ARTIST"].as_str()), (Some("Smörgåsbord ✓"), Some("Craft")));
assert!(tags.as_object().unwrap().keys().all(|k| !k.contains("bad")), "{tags}");
assert_eq!(j["format"]["duration"].as_str().map(|d| d.parse::<f64>().unwrap()), Some(1.0));
}
/// The lowest and highest qualities and the bit-rate path decode at the exact length, mono at
/// 44.1 kHz and stereo at 22.05 kHz.
#[test]
fn quality_extremes_and_rates_decode_exactly() {
let ff = require_ffmpeg!();
for (rate, channels, quality) in [(44_100u32, 1usize, -1.0f32), (44_100, 1, 10.0), (22_050, 2, -1.0), (22_050, 2, 10.0), (96_000, 2, 5.0)] {
let buf = tones(rate, channels, rate as usize / 2 + 13);
let file = encode_ogg_vorbis(&buf, &OggVorbisOptions::new(quality)).unwrap();
for decoder in decoders(&ff) {
let out = ffmpeg_decode(&ff, decoder, &file, channels, &format!("q{quality}-{rate}-{channels}-{decoder}"));
assert!(out.iter().all(|c| c.len() == buf.frames()), "q{quality} {rate} Hz {decoder}: {}", out[0].len());
let r = correlation(&buf.channels[0][2048..], &out[0][2048..]);
assert!(r > 0.9, "q{quality} {rate} Hz {decoder}: correlation {r:.3}");
}
}
let low = craft_audio::encode_ogg(&tones(48_000, 2, 48_000), craft_audio::OGG_BITRATES.0).unwrap();
let high = craft_audio::encode_ogg(&tones(48_000, 2, 48_000), craft_audio::OGG_BITRATES.1).unwrap();
assert!(low.len() < high.len(), "{} vs {} bytes", low.len(), high.len());
}
+1
View File
@@ -34,6 +34,7 @@ pub mod profile;
pub mod synth;
pub mod transform;
mod write;
pub mod write_v2;
pub use builtin::Builtin;
pub use clut::Clut;
+195
View File
@@ -0,0 +1,195 @@
//! Bounded ICC v2.1 matrix/TRC display-profile writer, extracted from TextureCraft.
//! Colour-space selection and transfer-curve sampling remain caller policy.
const D50_XYZ: [f64; 3] = [0.9642, 1.0, 0.8249];
/// One common red/green/blue transfer curve.
#[derive(Clone, Copy)]
pub enum ToneCurve<'a> {
/// ICC gamma 1.0 (`curv` with one u8Fixed8 entry).
Linear,
/// Already quantized samples, inclusive endpoints, between 2 and 4096 entries.
Samples(&'a [u16]),
}
/// Parameters for an ICC v2.1 RGB display profile.
pub struct MatrixProfile<'a> {
/// RGB-to-XYZ matrix already adapted to PCS D50, in row-major order.
pub matrix: [[f64; 3]; 3],
/// Common RGB transfer curve; its storage is shared by all three tags.
pub curve: ToneCurve<'a>,
/// ASCII description, at most 1024 bytes with no embedded NUL.
pub description: &'a str,
/// ASCII copyright text, at most 1024 bytes with no embedded NUL.
pub copyright: &'a str,
/// Raw ICC date fields: year, month, day, hour, minute, second.
pub date: [u16; 6],
}
fn s15f16(v: f64) -> [u8; 4] {
((v * 65536.0).round().clamp(f64::from(i32::MIN), f64::from(i32::MAX)) as i32).to_be_bytes()
}
fn xyz_tag(v: [f64; 3]) -> Vec<u8> {
let mut b = b"XYZ \0\0\0\0".to_vec();
for c in v {
b.extend_from_slice(&s15f16(c));
}
b
}
fn text_tag(text: &str) -> Vec<u8> {
let mut b = b"text\0\0\0\0".to_vec();
b.extend_from_slice(text.as_bytes());
b.push(0);
b
}
/// `textDescriptionType` with the ASCII description only.
fn desc_tag(text: &str) -> Vec<u8> {
let mut b = b"desc\0\0\0\0".to_vec();
b.extend_from_slice(&(text.len() as u32 + 1).to_be_bytes());
b.extend_from_slice(text.as_bytes());
b.push(0);
// No Unicode text and no Macintosh ScriptCode text: empty fields and the 67-byte filler.
b.extend_from_slice(&[0; 4 + 4 + 2 + 1 + 67]);
b
}
fn curve_tag(curve: ToneCurve<'_>) -> Vec<u8> {
let mut b = b"curv\0\0\0\0".to_vec();
match curve {
ToneCurve::Linear => {
b.extend_from_slice(&1u32.to_be_bytes());
b.extend_from_slice(&0x0100u16.to_be_bytes());
}
ToneCurve::Samples(samples) => {
b.extend_from_slice(&(samples.len() as u32).to_be_bytes());
for sample in samples {
b.extend_from_slice(&sample.to_be_bytes());
}
}
}
b
}
/// Write a deterministic ICC v2.1 RGB display profile with one shared RGB TRC.
///
/// Returns `None` for nonfinite matrix values, descriptions longer than 1024 ASCII
/// bytes or containing NUL, or sampled curves outside 2..=4096 entries. These caps
/// bound every allocation independently of caller input. Matrix values outside the
/// signed 15.16 range saturate, matching the legacy exporter. The caller owns colour
/// adaptation, transfer sampling, names and timestamp policy.
pub fn matrix_profile(params: &MatrixProfile<'_>) -> Option<Vec<u8>> {
let valid_text = |s: &str| s.len() <= 1024 && s.is_ascii() && !s.contains('\0');
if !valid_text(params.description)
|| !valid_text(params.copyright)
|| !params.matrix.iter().flatten().all(|v| v.is_finite())
|| matches!(params.curve, ToneCurve::Samples(s) if !(2..=4096).contains(&s.len()))
{
return None;
}
let m = params.matrix;
let column = |c: usize| [m[0][c], m[1][c], m[2][c]];
let curve = curve_tag(params.curve);
// The green and blue curves are the red one's entry.
let tags: [(&[u8; 4], Vec<u8>); 9] = [
(b"desc", desc_tag(params.description)),
(b"cprt", text_tag(params.copyright)),
(b"wtpt", xyz_tag(D50_XYZ)),
(b"rXYZ", xyz_tag(column(0))),
(b"gXYZ", xyz_tag(column(1))),
(b"bXYZ", xyz_tag(column(2))),
(b"rTRC", curve.clone()),
(b"gTRC", curve.clone()),
(b"bTRC", curve),
];
// Header (128) + tag count (4) + 12 per tag, then the tag data, each tag padded to 4 bytes.
let table_end = 128 + 4 + 12 * tags.len();
let mut offsets = Vec::new();
let mut data: Vec<u8> = Vec::new();
for (i, (_, bytes)) in tags.iter().enumerate() {
let shared = i >= 7;
let at = if shared { offsets.get(6).copied().unwrap_or(0) } else { table_end + data.len() };
offsets.push(at);
if !shared {
data.extend_from_slice(bytes);
while !data.len().is_multiple_of(4) {
data.push(0);
}
}
}
let total = table_end + data.len();
let mut out = vec![0u8; 128];
out.get_mut(0..4)?.copy_from_slice(&(total as u32).to_be_bytes());
out.get_mut(8..12)?.copy_from_slice(&[2, 0x10, 0, 0]); // version 2.1.0
out.get_mut(12..16)?.copy_from_slice(b"mntr");
out.get_mut(16..20)?.copy_from_slice(b"RGB ");
out.get_mut(20..24)?.copy_from_slice(b"XYZ ");
// Serialize caller-supplied ICC date fields; no calendar arithmetic.
for (i, value) in params.date.iter().enumerate() {
out.get_mut(24 + i * 2..26 + i * 2)?.copy_from_slice(&value.to_be_bytes());
}
out.get_mut(36..40)?.copy_from_slice(b"acsp");
for (k, v) in D50_XYZ.iter().enumerate() {
out.get_mut(68 + 4 * k..72 + 4 * k)?.copy_from_slice(&s15f16(*v));
}
out.extend_from_slice(&(tags.len() as u32).to_be_bytes());
for ((sig, bytes), at) in tags.iter().zip(&offsets) {
out.extend_from_slice(*sig);
out.extend_from_slice(&(*at as u32).to_be_bytes());
out.extend_from_slice(&(bytes.len() as u32).to_be_bytes());
}
out.extend_from_slice(&data);
Some(out)
}
#[cfg(test)]
mod tests {
#![allow(clippy::unwrap_used)]
use super::*;
fn params() -> MatrixProfile<'static> {
MatrixProfile {
matrix: [[0.4361, 0.3851, 0.1431], [0.2225, 0.7169, 0.0606], [0.0139, 0.0971, 0.7141]],
curve: ToneCurve::Linear,
description: "v2",
copyright: "free",
date: [2026, 1, 1, 0, 0, 0],
}
}
#[test]
fn valid_profile_parses_and_aliases_curves() {
for curve in [ToneCurve::Linear, ToneCurve::Samples(&[0, 32768, 65535])] {
let bytes = matrix_profile(&MatrixProfile { curve, ..params() }).unwrap();
let p = crate::Profile::parse(&bytes).unwrap();
assert_eq!(p.version, (2, 0x10));
assert_eq!(p.description, "v2");
assert_eq!(&bytes[24..28], &[7, 234, 0, 1]);
assert_eq!(&bytes[208..216], &bytes[220..228]);
assert_eq!(&bytes[208..216], &bytes[232..240]);
assert_eq!(bytes, matrix_profile(&MatrixProfile { curve, ..params() }).unwrap());
}
}
#[test]
fn bounded_inputs_reject_before_serializing() {
let long = "x".repeat(1025);
for description in [long.as_str(), "bad\0name", "non-ascii é"] {
assert!(matrix_profile(&MatrixProfile { description, ..params() }).is_none());
}
for samples in [&[][..], &[0][..], &vec![0; 4097][..]] {
assert!(matrix_profile(&MatrixProfile { curve: ToneCurve::Samples(samples), ..params() }).is_none());
}
for value in [f64::NAN, f64::INFINITY, f64::NEG_INFINITY] {
let mut p = params();
p.matrix[0][0] = value;
assert!(matrix_profile(&p).is_none());
}
let samples = vec![0; 4096];
let name = "x".repeat(1024);
let bytes = matrix_profile(&MatrixProfile { description: &name, copyright: &name, curve: ToneCurve::Samples(&samples), ..params() }).unwrap();
assert!(bytes.len() < 12 * 1024);
}
}
+55 -24
View File
@@ -62,6 +62,10 @@ impl Limits {
/// A byte count in megabytes for messages ("9.9 MB", "1024 MB").
#[cfg_attr(no_dwg_bridge, allow(dead_code))]
#[expect(
clippy::cast_precision_loss,
reason = "Megabyte formatting is rounded for display; exact integer precision beyond 2^53 bytes is not meaningful."
)]
fn mb(n: u64) -> String {
let m = n as f64 / f64::from(1u32 << 20);
if m >= 100.0 { format!("{m:.0} MB") } else { format!("{m:.1} MB") }
@@ -79,12 +83,17 @@ mod proxy_transport;
#[cfg(not(no_dwg_bridge))]
mod native {
use std::fmt::Write as _;
use std::io::{Cursor, Write};
use std::panic::AssertUnwindSafe;
use super::{Limits, mb};
/// Read DWG bytes and return an ASCII DXF rendition, within [`Limits::DEFAULT`].
///
/// # Errors
///
/// Returns an error when the DWG cannot be read or post-processed, or its DXF rendition exceeds the default limits.
pub fn dwg_to_dxf(bytes: &[u8]) -> Result<Vec<u8>, String> {
dwg_to_dxf_with(bytes, Limits::DEFAULT)
}
@@ -92,6 +101,10 @@ mod native {
/// [`dwg_to_dxf`] with explicit limits. Both are checked before the expensive step they
/// guard: the input size before the DWG reader runs, the DXF size while it is written, so a
/// runaway conversion stops at the limit instead of filling memory first.
///
/// # Errors
///
/// Returns an error when the input exceeds `limits`, decoding fails, or the DXF output exceeds `limits`.
pub fn dwg_to_dxf_with(bytes: &[u8], limits: Limits) -> Result<Vec<u8>, String> {
dwg_to_dxf_noted(bytes, limits).map(|(dxf, _)| dxf)
}
@@ -100,6 +113,10 @@ mod native {
/// failsafe mode: an object record it can't decode is skipped instead of failing the whole
/// file, and the notes say how many were skipped and of which types, so a partial read never
/// passes for a complete one.
///
/// # Errors
///
/// Returns an error when the input exceeds `limits`, decoding fails, or the DXF output exceeds `limits`.
pub fn dwg_to_dxf_noted(bytes: &[u8], limits: Limits) -> Result<(Vec<u8>, Vec<String>), String> {
if bytes.len() > limits.max_dwg_bytes {
return Err(format!(
@@ -122,13 +139,13 @@ mod native {
let mut notes = read_notes(&outcome.stats);
let mut doc = outcome.document;
notes.extend(
guarded(AssertUnwindSafe(|| application_objects(&mut doc))).map_err(|_| "the DWG application object conversion failed".to_string())?,
guarded(AssertUnwindSafe(|| application_objects(&mut doc))).map_err(|()| "the DWG application object conversion failed".to_string())?,
);
// After application_objects, so the proxy objects it makes are numbered as the DXF's.
notes.extend(
guarded(AssertUnwindSafe(|| super::proxy_transport::prepare(&mut doc))).map_err(|_| "the DWG proxy conversion failed".to_string())?,
guarded(AssertUnwindSafe(|| super::proxy_transport::prepare(&mut doc))).map_err(|()| "the DWG proxy conversion failed".to_string())?,
);
let orphans = guarded(AssertUnwindSafe(|| post_process(&mut doc))).map_err(|_| "the DWG post-processing failed on this file".to_string())?;
let orphans = guarded(AssertUnwindSafe(|| post_process(&mut doc))).map_err(|()| "the DWG post-processing failed on this file".to_string())?;
if orphans > 0 {
let (s, were) = if orphans == 1 { ("", "was") } else { ("s", "were") };
notes.push(format!("DWG: {orphans} DGN line style component{s} that no line style definition uses {were} left out"));
@@ -632,7 +649,7 @@ mod native {
// A real table has at most one merge per cell; more ranges than that come from a
// damaged file and would only make this rows × cols × ranges.
let max_ranges = rows.saturating_mul(cols).min(1 << 16);
for r in t.merged_ranges.iter().take(max_ranges).cloned().collect::<Vec<_>>() {
for r in t.merged_ranges.iter().take(max_ranges).copied().collect::<Vec<_>>() {
// Clamp to the table: the ranges come from the file.
let (bottom, right) = (r.bottom_row.min(rows.saturating_sub(1)), r.right_col.min(cols.saturating_sub(1)));
if r.top_row > bottom || r.left_col > right || rows == 0 || cols == 0 || (r.top_row, r.left_col) == (bottom, right) {
@@ -715,8 +732,8 @@ mod native {
}
/// Leave out DGN line style components (`LS*COMPONENT`) that no line style definition uses
/// (#1482). A drawing that once came from MicroStation can carry hundreds of thousands of
/// them, orphaned copies piled up by earlier DGN imports and copy-pastes (AutoCAD's PURGE
/// (#1482). A drawing that once came from `MicroStation` can carry hundreds of thousands of
/// them, orphaned copies piled up by earlier DGN imports and copy-pastes (`AutoCAD`'s PURGE
/// removes them as orphaned data): in a real 83 MB site plan they were 888,483 of 889,053
/// components and made its DXF rendition 1.2 GB, over [`Limits::DEFAULT`], so the file
/// didn't open at all. No definition that was read refers to them (a definition the reader
@@ -846,7 +863,7 @@ mod native {
for (name, code, value) in unwritten_header_vars(h) {
let written = section.windows(name.len() + 2).any(|w| w.starts_with(name.as_bytes()) && w.ends_with(b"\r\n"));
if !written && value.parse::<f64>().is_ok_and(f64::is_finite) {
add.push_str(&format!(" 9\r\n{name}\r\n{code:>3}\r\n{value}\r\n"));
let _ = write!(add, " 9\r\n{name}\r\n{code:>3}\r\n{value}\r\n");
}
}
dxf.splice(end..end, add.into_bytes());
@@ -878,14 +895,22 @@ mod native {
/// Oldest DWG version written; older DXF input is written as this version.
const MIN_DWG_VERSION: acadrust::DxfVersion = acadrust::DxfVersion::AC1018;
/// Convert DXF bytes into a DWG file of the DXF's version, and at least AutoCAD 2004
/// Convert DXF bytes into a DWG file of the DXF's version, and at least `AutoCAD` 2004
/// (AC1018).
///
/// # Errors
///
/// Returns an error when the DXF cannot be decoded or the DWG cannot be written, including oversized input.
pub fn dxf_to_dwg(dxf: &[u8]) -> Result<Vec<u8>, String> {
convert(dxf, None, None).map(|(dwg, _)| dwg)
}
/// Convert DXF bytes into a DWG file of `version`, a code from [`super::VERSIONS`] ("AC1032"),
/// whatever version the DXF declares.
///
/// # Errors
///
/// Returns an error for an unsupported version, invalid DXF, oversized input, or a DWG write failure.
pub fn dxf_to_dwg_as(dxf: &[u8], version: &str) -> Result<Vec<u8>, String> {
dxf_to_dwg_noted(dxf, version).map(|(dwg, _)| dwg)
}
@@ -1011,7 +1036,7 @@ mod native {
/// The current dimension style (`$DIMSTYLE`) by its name: the DXF gives the name, and the
/// handle read with it needn't be the style's in the document, in which case the DWG writer
/// fell back to Standard and AutoCAD opened the drawing with Standard current (#1051).
/// fell back to Standard and `AutoCAD` opened the drawing with Standard current (#1051).
fn current_dimstyle(doc: &mut acadrust::CadDocument) {
let name = doc.header.current_dimstyle_name.clone();
if let Some(h) = doc.dim_styles.iter().find(|ds| ds.name.eq_ignore_ascii_case(&name)).map(|ds| ds.handle) {
@@ -1021,7 +1046,7 @@ mod native {
/// The current text style (`$TEXTSTYLE`) by its name, the same way as [`current_dimstyle`]:
/// the handle read with the DXF needn't be the style's in the document, in which case the DWG
/// writer fell back to Standard and AutoCAD opened the drawing with Standard current (#1650).
/// writer fell back to Standard and `AutoCAD` opened the drawing with Standard current (#1650).
fn current_text_style(doc: &mut acadrust::CadDocument) {
let name = doc.header.current_text_style_name.clone();
if let Some(h) = doc.text_styles.iter().find(|ts| ts.name.eq_ignore_ascii_case(&name)).map(|ts| ts.handle) {
@@ -1211,7 +1236,7 @@ mod native {
};
let (classes, source) = guarded(AssertUnwindSafe(|| (dxf_class_names(&data), super::proxy_transport::source_classes(&data))))
.map_err(|_| "the DXF proxy class conversion failed".to_string())?;
let mut doc = std::panic::catch_unwind(move || acadrust::DxfReader::from_reader(Cursor::new(data)).and_then(|r| r.read()))
let mut doc = std::panic::catch_unwind(move || acadrust::DxfReader::from_reader(Cursor::new(data)).and_then(acadrust::DxfReader::read))
.map_err(|_| "the DXF→DWG conversion failed".to_string())?
.map_err(|e| format!("DXF: {e}"))?;
match version {
@@ -1250,14 +1275,14 @@ mod native {
current_layer(&mut doc);
unwritten
}))
.map_err(|_| "the DXF to DWG conversion failed on this file".to_string())?;
.map_err(|()| "the DXF to DWG conversion failed on this file".to_string())?;
let dwg = std::panic::catch_unwind(AssertUnwindSafe(|| acadrust::DwgWriter::write_to_vec(&doc)))
.map_err(|_| "the DWG writer failed on this drawing".to_string())?
.map_err(|e| format!("DWG write: {e}"))?;
Ok((dwg, unwritten))
}
/// AutoCAD's entry name for the drawing variables dictionary (the DXF Reference calls it the
/// `AutoCAD`'s entry name for the drawing variables dictionary (the DXF Reference calls it the
/// ACDBVARIABLEDICTIONARY; dictionary keys are case-insensitive).
const VARIABLE_DICTIONARY: &str = "AcDbVariableDictionary";
@@ -1273,11 +1298,11 @@ mod native {
if valid.contains(&value) { value.to_string() } else { default.to_string() }
}
/// Add the drawing variables dictionary AutoCAD always writes into the named object
/// Add the drawing variables dictionary `AutoCAD` always writes into the named object
/// dictionary, with the variables it keeps there, when the drawing has none (#1813).
/// Vectric Aspire 10.5 reads a 2004 (AC1018) DWG without it as empty ("No data was imported
/// from the DXF / DWG file"), though it reads the same drawing as DXF — which has no such
/// dictionary either, as CADCraft's and ezdxf's writers don't make one. AutoCAD's AC1032 DWGs
/// dictionary either, as CADCraft's and ezdxf's writers don't make one. `AutoCAD`'s AC1032 DWGs
/// read there without it, so newer output is left as it was, and a dictionary the drawing
/// does have keeps its own entries and values.
fn add_variable_dictionary(doc: &mut acadrust::CadDocument) {
@@ -1326,7 +1351,7 @@ mod native {
/// Entities of a layout other than the one in `*Paper_Space` are written owned by their block
/// (entity mode 0, with its handle). acadrust writes every paper-space entity with mode 1,
/// "paper space", which AutoCAD reads as the `*Paper_Space` block's: everything drawn on a
/// "paper space", which `AutoCAD` reads as the `*Paper_Space` block's: everything drawn on a
/// second layout landed on the first one, and the second stayed empty (#1057).
fn other_layout_owners(doc: &mut acadrust::CadDocument) {
let others: std::collections::HashSet<acadrust::Handle> = doc
@@ -1549,11 +1574,11 @@ thread_local! {
/// Panics when a test asked for `stage` to fail (see [`PANIC_IN`]); does nothing otherwise.
#[cfg(not(no_dwg_bridge))]
#[allow(clippy::panic)]
fn fail_in_test(_stage: &str) {
fn fail_in_test(stage: &str) {
#[cfg(not(test))]
let _ = stage;
#[cfg(test)]
if PANIC_IN.with(|p| p.get()) == Some(_stage) {
panic!("test-forced panic in {_stage}");
}
assert!(PANIC_IN.with(std::cell::Cell::get) != Some(stage), "test-forced panic in {stage}");
}
/// The error for a DWG version this writer can't create.
@@ -1633,6 +1658,8 @@ pub fn dxf_to_dwg_kept_noted(_dxf: &[u8], _version: &str, _kept: &str) -> Result
#[cfg(test)]
mod tests {
use std::fmt::Write as _;
use super::*;
/// The DXF of an empty drawing, enough for the bridge to make a small DWG.
@@ -1726,9 +1753,9 @@ mod tests {
let mut s = String::from(" 0\nSECTION\n 2\nHEADER\n 9\n$ACADVER\n 1\nAC1032\n 0\nENDSEC\n 0\nSECTION\n 2\nENTITIES\n");
for (text, flags, sub, pts) in dims {
s += " 0\nDIMENSION\n 8\n0\n100\nAcDbEntity\n100\nAcDbDimension\n 10\n0\n 20\n0\n 30\n0\n";
s += &format!(" 11\n50\n 21\n-20\n 31\n0\n 70\n{flags}\n 1\n{text}\n 3\nStandard\n100\n{sub}\n");
for (code, [x, y]) in pts.iter() {
s += &format!("{code:>3}\n{x}\n{:>3}\n{y}\n{:>3}\n0\n", code + 10, code + 20);
let _ = write!(s, " 11\n50\n 21\n-20\n 31\n0\n 70\n{flags}\n 1\n{text}\n 3\nStandard\n100\n{sub}\n");
for (code, [x, y]) in *pts {
let _ = write!(s, "{code:>3}\n{x}\n{:>3}\n{y}\n{:>3}\n0\n", code + 10, code + 20);
}
}
s + " 0\nENDSEC\n 0\nEOF\n"
@@ -1797,13 +1824,17 @@ mod tests {
.collect()
}
/// Issue #1482: a DWG that once came from MicroStation can carry hundreds of thousands of DGN
/// Issue #1482: a DWG that once came from `MicroStation` can carry hundreds of thousands of DGN
/// line style components no definition uses (a real 83 MB site plan: 888,483 of 889,053, a
/// 1.2 GB DXF rendition over the limit, so it didn't open). They're left out with a note, and
/// their dictionary entries with them; the definition and every component it reaches —
/// through compound and point components, around a cycle — are kept.
#[cfg(not(no_dwg_bridge))]
#[test]
#[expect(
clippy::too_many_lines,
reason = "This integration test builds and verifies one complete DGN component graph; splitting the fixture would obscure reachability."
)]
fn orphaned_dgn_line_style_components_are_left_out() {
use acadrust::objects::*;
let mut doc = acadrust::CadDocument::new();
+3 -2
View File
@@ -199,8 +199,9 @@ pub use codepage::decode_code_page;
/// # Errors
///
/// Returns an error for empty input, an invalid group code, an incomplete group-code/value pair,
/// truncated binary data, or more than [`MAX_TAGS`] group codes. For ASCII input, invalid numeric
/// text becomes `0.0` for real values or `0` for integer values, and an EOF tag is not required.
/// truncated binary data, or more group codes than the limit returned by [`max_tags()`], which is
/// [`MAX_TAGS`] by default. For ASCII input, invalid numeric text becomes `0.0` for real values or
/// `0` for integer values, and an EOF tag is not required.
pub fn parse(bytes: &[u8]) -> Result<Vec<Tag>> {
parse_with_limit(bytes, max_tags())
}
+3 -3
View File
@@ -15,7 +15,7 @@
//! `IRMAK` and `ırmak`. Plain `str::to_lowercase` follows no locale and turns `İ` into `i` plus a
//! combining dot, which nothing typed would match.
//!
//! The Turkish i handling and sigma folding come from PdfCraft's `fold_case` (snipeTR,
//! The Turkish i handling and sigma folding come from `PdfCraft`'s `fold_case` (snipeTR,
//! nevicia2010-hub).
use std::ops::Range;
@@ -85,7 +85,7 @@ impl Folder {
}
/// One cluster, already in NFKD.
fn fold_cluster(&self, cluster: &str, out: &mut String) {
fn fold_cluster(self, cluster: &str, out: &mut String) {
let mut chars = cluster.chars().peekable();
while let Some(c) = chars.next() {
match c {
@@ -363,10 +363,10 @@ mod tests {
#[test]
fn matches_map_back_to_the_source() {
let f = Folder::new("en");
fn find<'a>(f: Folder, haystack: &'a str, needle: &str) -> Option<&'a str> {
f.fold(haystack).find(&f.fold(needle)).map(|r| &haystack[r])
}
let f = Folder::new("en");
let find = |haystack, needle| find(f, haystack, needle);
assert_eq!(find("Große Straße", "strasse"), Some("Straße"));
assert_eq!(find("Große Straße", "SS"), Some("ß"));
+5 -4
View File
@@ -4,7 +4,7 @@
use std::fmt;
use fixed_decimal::{Decimal, Sign};
use icu_decimal::{DecimalFormatter, parts};
use icu_decimal::{DecimalFormatter, options::DecimalFormatterOptions, parts};
use icu_locale_core::Locale;
use icu_locale_core::extensions::unicode::{key, value};
use writeable::{Part, PartsWrite, Writeable};
@@ -46,7 +46,8 @@ impl Format {
if digits == Digits::Latin {
locale.extensions.unicode.keywords.set(key!("nu"), value!("latn"));
}
let decimal = data::provider().and_then(|p| DecimalFormatter::try_new_with_buffer_provider(p, (&locale).into(), Default::default()).ok());
let decimal = data::provider()
.and_then(|p| DecimalFormatter::try_new_with_buffer_provider(p, (&locale).into(), DecimalFormatterOptions::default()).ok());
let mut format = Format { decimal, group: None, point: None, percent: ("", "%"), marks: Marks::default() };
// The locale's own separators and digits, read from a number that shows them all.
let probe = format.parts(&Decimal::try_from_str("-1234567.5").unwrap_or_default());
@@ -212,7 +213,7 @@ impl PartsWrite for Sink<'_> {
_ => return result,
};
if slot.is_empty() {
*slot = written.to_owned();
written.clone_into(slot);
}
}
result
@@ -370,7 +371,7 @@ mod tests {
for (tag, want) in
[("en", "50%"), ("de", "50\u{a0}%"), ("fr", "12,5\u{a0}%"), ("tr", "%50"), ("ar-EG", "٥٠٪\u{61c}"), ("fa", "۵۰٪"), ("hi", "50%")]
{
let decimals = if tag == "fr" { 1 } else { 0 };
let decimals = usize::from(tag == "fr");
let ratio = if tag == "fr" { 0.125 } else { 0.5 };
assert_eq!(Format::from_tag(tag).percent(ratio, decimals), want, "{tag}");
}
+6 -5
View File
@@ -113,7 +113,9 @@ impl Locale {
rows.entry(e.context).or_default().insert(e.source, e.translation);
}
}
problems.iter().for_each(|p| log::warn!("translation catalog: {p}; row skipped"));
for p in &problems {
log::warn!("translation catalog: {p}; row skipped");
}
Parsed { rows, problems }
})
}
@@ -483,14 +485,13 @@ fn wrap(initiator: char, value: &str) -> String {
PDF if open.last() == Some(&false) => {
open.pop();
}
PDF => continue,
PDI if isolates > 0 => {
while open.pop() == Some(false) {
out.push(PDF);
}
isolates -= 1;
}
PDI => continue,
PDF | PDI => continue,
_ => {}
}
out.push(c);
@@ -713,11 +714,11 @@ fn plural_rules(code: &str) -> Option<(PluralRules, Vec<PluralCategory>)> {
categories.push(c);
}
}
categories.sort_by_key(rank);
categories.sort_by_key(|c| rank(*c));
Some((rules, categories))
}
fn rank(c: &PluralCategory) -> u8 {
fn rank(c: PluralCategory) -> u8 {
match c {
PluralCategory::Zero => 0,
PluralCategory::One => 1,
+11
View File
@@ -80,6 +80,12 @@ impl Format {
///
/// Percent signs, units and the space before a unit (`50 %`, `12 px`) are not read; strip them
/// first. Anything else is an error rather than a guess.
///
/// # Errors
///
/// Returns `NumberError::Empty` for an empty input or one reduced to spaces and a sign,
/// `Unexpected` for an invalid character, `MixedDigits` for mixed digit sets, `Separator`
/// for misplaced marks, and `TooLarge` when the parsed value is not finite.
pub fn parse(&self, text: &str) -> Result<f64, NumberError> {
let marks = self.marks;
let text: String = text.chars().filter(|c| !is_bidi_mark(*c)).collect();
@@ -129,6 +135,11 @@ impl Format {
/// The number in `text` as `locale` (a language tag, `de-CH`, `ar_EG.UTF-8`) writes it:
/// [`Format::parse`] for [`Format::from_tag`]. Build the [`Format`] once to read many numbers. A
/// locale CLDR doesn't know reads as CLDR's root does (`1,234.5`).
///
/// # Errors
///
/// Returns the same `NumberError` as [`Format::parse`] for invalid digits, characters, or
/// separators, or when the value is not finite.
pub fn parse_number(text: &str, locale: &str) -> Result<f64, NumberError> {
Format::from_tag(locale).parse(text)
}
+1
View File
@@ -298,6 +298,7 @@ fn from_apple(identifier: &str, metric: bool, decimal: &str, grouping: &str, hou
/// A grouping separator the system sets: none at all when empty (Windows' `sThousand` the user
/// cleared), else one character.
#[cfg(any(test, windows, target_vendor = "apple"))]
#[expect(clippy::option_option, reason = "The public setting distinguishes following the locale, no grouping, and a custom separator")]
fn grouping(s: &str) -> Option<Option<char>> {
if s.is_empty() { Some(None) } else { single_char(s).map(Some) }
}
+17 -5
View File
@@ -113,7 +113,10 @@ pub enum Han {
/// Latin.
// ponytail: the languages a Craft app ships or could plausibly ship; add a row with the locale.
pub fn scripts(tag: &str) -> &'static [Script] {
use Script::*;
use Script::{
Arab, Armn, Beng, Cyrl, Deva, Ethi, Geor, Grek, Gujr, Guru, Hang, Hani, Hebr, Hira, Kana, Khmr, Knda, Laoo, Latn, Mlym, Mymr, Orya, Sinh,
Syrc, Taml, Telu, Thaa, Thai, Tibt,
};
let tag = Subtags::parse(tag);
if let Some(s) = tag.script.as_deref().and_then(subtag_scripts) {
return s;
@@ -175,7 +178,7 @@ pub fn base_direction(text: &str) -> Option<Direction> {
/// The forms a language tag's Han characters take: `zh-CN`, `zh-SG`, `zh-Hans` and plain `zh` →
/// Simplified; `zh-TW`, `zh-Hant` and the other regions CLDR writes in Traditional characters
/// (`zh-US`, `zh-AU`) → Traditional; `zh-HK`, `zh-MO`, `zh-Hant-HK` and `yue` → HongKong; `ja` →
/// (`zh-US`, `zh-AU`) → Traditional; `zh-HK`, `zh-MO`, `zh-Hant-HK` and `yue` → `HongKong`; `ja` →
/// Japanese; `ko` → Korean. `None` for a language not written with Han, which leaves the choice
/// to the font stack.
pub fn han(tag: &str) -> Option<Han> {
@@ -202,8 +205,14 @@ pub fn han(tag: &str) -> Option<Han> {
// ponytail: mn-CN → Mong is left out until vertical Mongolian layout is supported.
pub(crate) fn region_script(language: &str, region: &str) -> Option<&'static str> {
Some(match (language, region) {
("az", "iq" | "ir") | ("ha", "cm" | "sd") | ("kk", "af" | "cn" | "ir" | "mn") | ("ku", "iq" | "ir" | "lb") => "arab",
("ky", "cn") | ("ms", "cc") | ("pa", "pk") | ("tg", "pk") | ("uz", "af") => "arab",
("az", "iq" | "ir")
| ("ha", "cm" | "sd")
| ("kk", "af" | "cn" | "ir" | "mn")
| ("ku", "iq" | "ir" | "lb")
| ("ky", "cn")
| ("ms", "cc")
| ("pa" | "tg", "pk")
| ("uz", "af") => "arab",
("az", "ru") | ("ku", "am" | "az" | "ge" | "tm") | ("ug", "kz" | "mn") | ("uz", "cn") => "cyrl",
("ky", "tr") | ("sr", "me" | "ro" | "tr") => "latn",
("sd", "in") => "deva",
@@ -216,7 +225,10 @@ pub(crate) fn region_script(language: &str, region: &str) -> Option<&'static str
/// The scripts a script subtag stands for, including the CLDR unions (`jpan`, `kore`). `None` for
/// one not in [`Script`], so the language's own scripts apply.
fn subtag_scripts(subtag: &str) -> Option<&'static [Script]> {
use Script::*;
use Script::{
Arab, Armn, Beng, Cyrl, Deva, Ethi, Geor, Grek, Gujr, Guru, Hang, Hani, Hebr, Hira, Kana, Khmr, Knda, Laoo, Latn, Mlym, Mong, Mymr, Orya,
Sinh, Syrc, Taml, Telu, Thaa, Thai, Tibt,
};
Some(match subtag {
"hans" | "hant" | "hani" => &[Hani],
"jpan" => &[Hani, Hira, Kana],
+5
View File
@@ -104,6 +104,10 @@ impl FileSize {
}
/// The unit `bytes` is written in, the number in it and its digits after the point.
#[expect(
clippy::cast_precision_loss,
reason = "File sizes are displayed as rounded f64 values; exact u64 arithmetic is not required for presentation"
)]
fn parts(&self, bytes: u64) -> (SizeUnit, f64, usize) {
let (smallest, largest) = (self.smallest.min(self.largest), self.largest);
let mut unit = smallest;
@@ -137,6 +141,7 @@ impl FileSize {
}
}
#[expect(clippy::cast_precision_loss, reason = "Unit scales are displayed as f64 values; exact u64 arithmetic is not required for presentation")]
fn scale(&self, unit: SizeUnit) -> f64 {
(self.step as f64).powi(unit as i32)
}
+7 -1
View File
@@ -447,7 +447,13 @@ page yet. Damage recovery may read bytes again up to twice the file's length plu
is read at most about three times over; the packets kept and the header packets of a stream are
bounded too, with a warning when a bound is reached.
`OpusTiming` gives each Opus packet's start, the pre-skip and the end trimming of the final page.
No muxer.
The muxer side is `PageWriter`, from FilmCraft's `filmcraft-oggmux` by @JordyUSA
(storytold/filmcraft#4481): it laces the packets of one logical stream into pages (continued
packets, granule positions, BOS/EOS, CRC-32), puts each header packet on pages of its own, closes
audio pages at a byte or packet target, and can replace the final granule position for Ogg Opus
end trimming. `opus_tags` and `vorbis_comment` build the comment headers; tag names that are not
valid field names (Vorbis I §5.2.1) are left out.
## `avi`
+9 -1
View File
@@ -1,4 +1,4 @@
//! Clean-room Ogg demuxer, written from RFC 3533 (the Ogg encapsulation format), RFC 7845 (Ogg
//! Clean-room Ogg demuxer and page writer, written from RFC 3533 (the Ogg encapsulation format), RFC 7845 (Ogg
//! Opus) and the Vorbis I specification's Ogg mapping (section A).
//!
//! [`open`] reads every page (capture pattern, header, lacing values, CRC-32 checked; damaged
@@ -12,6 +12,9 @@
//! TOC-derived durations, the pre-skip, and end trimming of the final page, so a player can seek
//! to any 48 kHz sample.
//!
//! [`PageWriter`] writes the pages of a logical bitstream, and [`opus_tags`] and
//! [`vorbis_comment`] build the comment headers of Ogg Opus and Ogg Vorbis.
//!
//! Layer L0: no dependencies beyond `std`, no `unsafe`, builds for `wasm32-unknown-unknown`.
//!
//! From FilmCraft's `filmcraft-ogg` (storytold/filmcraft@8fda2f2). Public items keep their names, so
@@ -25,6 +28,9 @@ use std::fmt;
use std::io;
pub use crate::source::{ByteSource, ReadSeekSource};
pub use write::{PAGE_TARGET_BYTES, PAGE_TARGET_PACKETS, PageWriter, opus_tags, vorbis_comment};
mod write;
/// Errors from reading an Ogg file.
#[non_exhaustive]
@@ -879,3 +885,5 @@ impl VorbisInfo {
#[cfg(test)]
mod tests;
#[cfg(test)]
mod write_tests;
+206
View File
@@ -0,0 +1,206 @@
//! Ogg page writer (RFC 3533) and the comment-header packets of Ogg Opus (RFC 7845 §5.2) and Ogg
//! Vorbis (Vorbis I §5).
//!
//! [`PageWriter`] laces packets into pages of one logical bitstream: lacing values of 255 with a
//! shorter last value per packet, at most 255 per page, continued packets flagged on the next
//! page, the granule position of the last packet completed on each page (-1 on a page where no
//! packet completes), page sequence numbers, the CRC-32, and the beginning- and end-of-stream
//! flags. Header packets are flushed to pages of their own, as both mappings require.
//!
//! From FilmCraft's `filmcraft-oggmux` by @JordyUSA (storytold/filmcraft#4481).
use super::crc32;
/// Default size at which an audio page is closed before the next packet is added.
pub const PAGE_TARGET_BYTES: usize = 4096;
/// Default number of packets after which an audio page is closed (one second of 20 ms Opus).
pub const PAGE_TARGET_PACKETS: usize = 50;
/// Writes the pages of one logical bitstream.
#[derive(Clone, Debug)]
pub struct PageWriter {
serial: u32,
seq: u32,
lacing: Vec<u8>,
body: Vec<u8>,
/// Granule position of the last packet completed on the pending page.
granule: Option<i64>,
/// The pending page starts with the continuation of a packet.
continued: bool,
packets: usize,
bos_written: bool,
finished: bool,
target_bytes: usize,
target_packets: usize,
}
impl PageWriter {
/// A writer for the logical bitstream with serial number `serial`, closing audio pages at
/// [`PAGE_TARGET_BYTES`] or [`PAGE_TARGET_PACKETS`].
pub fn new(serial: u32) -> PageWriter {
PageWriter {
serial,
seq: 0,
lacing: Vec::with_capacity(255),
body: Vec::new(),
granule: None,
continued: false,
packets: 0,
bos_written: false,
finished: false,
target_bytes: PAGE_TARGET_BYTES,
target_packets: PAGE_TARGET_PACKETS,
}
}
/// Closes audio pages at `bytes` of payload or `packets` packets, whichever comes first.
pub fn with_page_target(mut self, bytes: usize, packets: usize) -> PageWriter {
self.target_bytes = bytes.max(1);
self.target_packets = packets.max(1);
self
}
/// Pages written so far.
pub fn pages(&self) -> u32 {
self.seq
}
/// A header packet on pages of its own (granule position 0); the first one opens the stream.
pub fn header(&mut self, data: &[u8]) -> Vec<u8> {
let mut out = self.flush();
out.extend(self.add(data, 0));
out.extend(self.flush());
out
}
/// Adds an audio packet that ends at granule position `granule`; returns the pages it
/// completed. The pending page is closed first once it is full enough, so the last packet
/// always stays pending for [`Self::finish`] to mark the end of the stream.
pub fn packet(&mut self, data: &[u8], granule: i64) -> Vec<u8> {
let mut out = Vec::new();
if self.body.len() >= self.target_bytes || self.packets >= self.target_packets {
out = self.flush();
}
out.extend(self.add(data, granule));
out
}
/// Closes the pending page now, if there is one.
pub fn flush(&mut self) -> Vec<u8> {
let mut out = Vec::new();
if !self.lacing.is_empty() {
self.emit(&mut out, false);
}
out
}
/// Ends the stream: the pending page (or an empty page when nothing is pending) with the
/// end-of-stream flag. `last_granule` replaces the granule position of the final page (Ogg
/// Opus end trimming) when a packet is pending; `None` keeps the last packet's. End trimming
/// applies only to packets completed on the last page (RFC 7845 §4.4), so do not
/// [`Self::flush`] the last packet before finishing.
pub fn finish(&mut self, last_granule: Option<i64>) -> Vec<u8> {
let mut out = Vec::new();
if self.finished {
return out;
}
if let Some(g) = last_granule
&& !self.lacing.is_empty()
{
self.granule = Some(g);
}
self.emit(&mut out, true);
self.finished = true;
out
}
fn add(&mut self, data: &[u8], granule: i64) -> Vec<u8> {
let mut out = Vec::new();
let mut rest = data;
let mut started = false;
loop {
if self.lacing.len() == 255 {
// A full page: the next one continues this packet, unless it has not begun yet.
self.emit(&mut out, false);
self.continued = started;
}
let n = rest.len().min(255);
self.lacing.push(n as u8);
started = true;
self.body.extend_from_slice(&rest[..n]);
rest = &rest[n..];
if n < 255 {
break;
}
}
self.granule = Some(granule);
self.packets += 1;
out
}
fn emit(&mut self, out: &mut Vec<u8>, eos: bool) {
let mut flags = 0u8;
if self.continued {
flags |= 0x01;
}
if !self.bos_written {
flags |= 0x02;
self.bos_written = true;
}
if eos {
flags |= 0x04;
}
let start = out.len();
out.extend_from_slice(b"OggS");
out.push(0);
out.push(flags);
out.extend_from_slice(&self.granule.unwrap_or(-1).to_le_bytes());
out.extend_from_slice(&self.serial.to_le_bytes());
out.extend_from_slice(&self.seq.to_le_bytes());
out.extend_from_slice(&[0; 4]);
out.push(self.lacing.len() as u8);
out.extend_from_slice(&self.lacing);
out.extend_from_slice(&self.body);
let crc = crc32(&out[start..]);
out[start + 22..start + 26].copy_from_slice(&crc.to_le_bytes());
self.seq = self.seq.wrapping_add(1);
self.lacing.clear();
self.body.clear();
self.granule = None;
self.continued = false;
self.packets = 0;
}
}
/// A comment header body: vendor string and `KEY=value` comments, little-endian lengths.
fn comments(magic: &[u8], vendor: &str, tags: &[(&str, &str)]) -> Vec<u8> {
let mut v = magic.to_vec();
let len = |n: usize| u32::try_from(n).unwrap_or(u32::MAX).to_le_bytes();
v.extend(len(vendor.len()));
v.extend_from_slice(vendor.as_bytes());
let tags: Vec<String> = tags.iter().filter(|(k, _)| valid_key(k)).map(|(k, val)| format!("{k}={val}")).collect();
v.extend(len(tags.len()));
for t in &tags {
v.extend(len(t.len()));
v.extend_from_slice(t.as_bytes());
}
v
}
/// A comment field name: printable ASCII 0x20–0x7D other than `=` (Vorbis I §5.2.1), not empty.
fn valid_key(k: &str) -> bool {
!k.is_empty() && k.bytes().all(|b| (0x20..=0x7D).contains(&b) && b != b'=')
}
/// The `OpusTags` packet (RFC 7845 §5.2). Comments whose name is not a valid field name are
/// left out.
pub fn opus_tags(vendor: &str, tags: &[(&str, &str)]) -> Vec<u8> {
comments(b"OpusTags", vendor, tags)
}
/// The Vorbis comment header packet (Vorbis I §5: type 3, `vorbis`, comments, framing bit).
pub fn vorbis_comment(vendor: &str, tags: &[(&str, &str)]) -> Vec<u8> {
let mut v = comments(b"\x03vorbis", vendor, tags);
v.push(1);
v
}
+200
View File
@@ -0,0 +1,200 @@
//! The page writer, read back by [`open`].
#![allow(clippy::unwrap_used)]
use super::{Codec, OpusTiming, PageWriter, crc32, open, opus_tags, vorbis_comment};
/// A TOC-only 20 ms CELT packet of `len` bytes whose bytes encode `i` (so packets differ).
fn opus_packet(i: usize, len: usize) -> Vec<u8> {
let mut p = vec![0xF8u8];
p.extend((0..len.saturating_sub(1)).map(|k| (i * 31 + k) as u8));
p
}
fn opus_head(pre_skip: u16) -> Vec<u8> {
let mut h = b"OpusHead".to_vec();
h.extend([1, 2]);
h.extend(pre_skip.to_le_bytes());
h.extend(48_000u32.to_le_bytes());
h.extend([0, 0, 0]);
h
}
/// An Ogg Opus file of `n` packets of `sizes(i)` bytes, `samples` playable samples after the pre-skip.
fn write_opus(n: usize, sizes: impl Fn(usize) -> usize, pre_skip: u16, samples: i64) -> (Vec<u8>, Vec<Vec<u8>>) {
let mut w = PageWriter::new(0x1234_5678);
let mut f = w.header(&opus_head(pre_skip));
f.extend(w.header(&opus_tags("FilmCraft", &[("TITLE", "Test"), ("bad=key", "dropped"), ("", "dropped")])));
let mut packets = Vec::new();
for i in 0..n {
let p = opus_packet(i, sizes(i));
f.extend(w.packet(&p, (i as i64 + 1) * 960));
packets.push(p);
}
f.extend(w.finish(Some(i64::from(pre_skip) + samples)));
(f, packets)
}
#[test]
fn written_pages_read_back_packet_for_packet() {
let (f, packets) = write_opus(230, |i| 3 + (i * 37) % 400, 120, 230 * 960 - 120 - 500);
let ogg = open(&f).unwrap();
assert!(ogg.warnings.is_empty(), "{:?}", ogg.warnings);
assert_eq!(ogg.streams.len(), 1);
let s = &ogg.streams[0];
assert_eq!((s.serial, s.codec, s.saw_eos), (0x1234_5678, Codec::Opus, true));
assert_eq!(s.headers.len(), 2);
assert_eq!(s.headers[0], opus_head(120));
assert_eq!(s.headers[1], opus_tags("FilmCraft", &[("TITLE", "Test")]));
assert_eq!(s.packets.len(), packets.len());
for (k, p) in packets.iter().enumerate() {
assert_eq!(&ogg.read_packet(&f, 0, k).unwrap(), p, "packet {k}");
}
assert!(s.packets.last().unwrap().eos);
assert_eq!(s.last_granule, Some(120 + 230 * 960 - 120 - 500));
// RFC 7845 §4: the end trimming of the final page.
let t = OpusTiming::of(s, 120);
assert_eq!(t.total, 230 * 960 - 120 - 500);
assert_eq!(t.starts[0], -120);
assert!(t.durations.iter().all(|&d| d == 960));
}
#[test]
fn headers_have_pages_of_their_own_and_only_the_first_page_opens_the_stream() {
let (f, _) = write_opus(3, |_| 10, 0, 3 * 960);
let mut pos = 0;
let mut flags = Vec::new();
let mut seqs = Vec::new();
while pos + 27 <= f.len() {
assert_eq!(&f[pos..pos + 4], b"OggS");
let mut page = f[pos..].to_vec();
let nseg = page[26] as usize;
let len = 27 + nseg + page[27..27 + nseg].iter().map(|&l| l as usize).sum::<usize>();
page.truncate(len);
let stored = u32::from_le_bytes(page[22..26].try_into().unwrap());
page[22..26].fill(0);
assert_eq!(crc32(&page), stored, "page CRC");
flags.push(f[pos + 5]);
seqs.push(u32::from_le_bytes(f[pos + 18..pos + 22].try_into().unwrap()));
pos += len;
}
assert_eq!(pos, f.len());
assert_eq!(flags, [0x02, 0x00, 0x04], "BOS head page, tags page, one audio page with EOS");
assert_eq!(seqs, [0, 1, 2]);
}
#[test]
fn a_packet_longer_than_a_page_continues() {
let big = 2 * 255 * 255 + 7000; // spans three pages: the middle one completes no packet
let (f, packets) = write_opus(4, |i| if i == 1 { big } else { 50 }, 0, 4 * 960);
let ogg = open(&f).unwrap();
assert!(ogg.warnings.is_empty());
for (k, p) in packets.iter().enumerate() {
assert_eq!(&ogg.read_packet(&f, 0, k).unwrap(), p, "packet {k}");
}
// a page on which no packet completes has granule position -1
let mut pos = 0;
let mut saw_none = false;
while pos + 27 <= f.len() {
let nseg = f[pos + 26] as usize;
let lacing = &f[pos + 27..pos + 27 + nseg];
let g = i64::from_le_bytes(f[pos + 6..pos + 14].try_into().unwrap());
if lacing.iter().all(|&l| l == 255) {
assert_eq!(g, -1);
saw_none = true;
}
pos += 27 + nseg + lacing.iter().map(|&l| l as usize).sum::<usize>();
}
assert!(saw_none);
}
#[test]
fn page_targets_bound_page_size_and_finish_marks_the_end_once() {
let mut w = PageWriter::new(7).with_page_target(1000, 10);
let mut f = w.header(&opus_head(0));
f.extend(w.header(&opus_tags("v", &[])));
for i in 0..95 {
f.extend(w.packet(&opus_packet(i, 160), (i as i64 + 1) * 960));
}
f.extend(w.finish(None));
assert!(w.finish(None).is_empty());
let ogg = open(&f).unwrap();
let s = &ogg.streams[0];
assert_eq!(s.packets.len(), 95);
assert_eq!(s.pages, 2 + 95_u32.div_ceil(7), "1000-byte pages hold 7 packets of 160 bytes");
assert_eq!(s.last_granule, Some(95 * 960));
// An empty stream still ends.
let mut w = PageWriter::new(1);
let mut f = w.header(&opus_head(0));
f.extend(w.finish(Some(0)));
assert!(open(&f).unwrap().streams[0].saw_eos);
// A flushed last packet cannot be trimmed: the empty end page keeps its granule.
let mut w = PageWriter::new(1);
let mut f = w.header(&opus_head(312));
f.extend(w.header(&opus_tags("t", &[])));
f.extend(w.packet(&[0xFC; 40], 960));
f.extend(w.flush());
f.extend(w.finish(Some(500)));
let s = &open(&f).unwrap().streams[0];
assert!(s.saw_eos);
assert_eq!(s.last_granule, Some(960));
}
#[test]
fn vorbis_comment_has_the_framing_bit() {
let c = vorbis_comment("FilmCraft", &[("ARTIST", "x")]);
assert_eq!(&c[..7], b"\x03vorbis");
assert_eq!(*c.last().unwrap(), 1);
assert_eq!(u32::from_le_bytes(c[7..11].try_into().unwrap()), 9);
}
/// Packets on and around the lacing boundaries (multiples of 255, where a packet ends with a
/// zero lacing value) and an empty packet read back exactly.
#[test]
fn lacing_boundaries_read_back() {
let sizes = [0usize, 1, 254, 255, 256, 509, 510, 511, 765, 65_024, 65_025, 65_026];
let mut w = PageWriter::new(3);
let mut f = w.header(&opus_head(0));
f.extend(w.header(&opus_tags("v", &[])));
let packets: Vec<Vec<u8>> = sizes.iter().enumerate().map(|(i, &n)| (0..n).map(|k| (i * 7 + k) as u8).collect()).collect();
for (i, p) in packets.iter().enumerate() {
f.extend(w.packet(p, (i as i64 + 1) * 960));
}
f.extend(w.finish(None));
let ogg = open(&f).unwrap();
assert!(ogg.warnings.is_empty(), "{:?}", ogg.warnings);
assert_eq!(ogg.streams[0].packets.len(), packets.len());
for (k, p) in packets.iter().enumerate() {
assert_eq!(ogg.read_packet(&f, 0, k).unwrap(), *p, "packet {k} of {} bytes", p.len());
}
}
/// A page exactly full of lacing values when a packet starts: the packet begins on the next page,
/// which must not be flagged as continuing one (the reader would drop its first packet). Review
/// of #4481; reachable with page targets larger than the defaults.
#[test]
fn a_packet_after_an_exactly_full_page_is_not_a_continuation() {
let mut w = PageWriter::new(5).with_page_target(1 << 20, 1000);
let mut f = w.header(&opus_head(0));
f.extend(w.header(&opus_tags("v", &[])));
let packets: Vec<Vec<u8>> = (0..300).map(|i| opus_packet(i, 1)).collect();
for (i, p) in packets.iter().enumerate() {
f.extend(w.packet(p, (i as i64 + 1) * 960));
}
f.extend(w.finish(None));
let ogg = open(&f).unwrap();
assert!(ogg.warnings.is_empty(), "{:?}", ogg.warnings);
assert_eq!(ogg.streams[0].packets.len(), 300, "every packet is read back");
for (k, p) in packets.iter().enumerate() {
assert_eq!(&ogg.read_packet(&f, 0, k).unwrap(), p, "packet {k}");
}
// the second audio page starts with packet 255 and is not a continuation
let mut pos = 0;
let mut flags = Vec::new();
while pos + 27 <= f.len() {
let nseg = f[pos + 26] as usize;
flags.push(f[pos + 5]);
pos += 27 + nseg + f[pos + 27..pos + 27 + nseg].iter().map(|&l| l as usize).sum::<usize>();
}
assert!(flags.iter().all(|&fl| fl & 0x01 == 0), "no page continues a packet: {flags:?}");
}
+2 -2
View File
@@ -30,7 +30,7 @@ BitReader: bit, bits, character, unsigned_integer, integer, integer_vbn, double_
- `Tessellation::Mesh` is a `TriangleMesh`: positions, triangles, one triangle range per face, the stored normals and
texture coordinates with each triangle's corner indices into them, and per-triangle line-attribute styles.
`Wire` is polylines; `Markup` is read past.
- `Tessellation::Compressed` is read to its end so later entities decode; its triangles are not rebuilt yet.
- `Tessellation::Compressed` is read to its end so later entities decode. Recalculated-normal meshes in the accepted 3T form are rebuilt when their arrays fit; stored-normal meshes and unsupported traversals stay `Compressed`.
- A face may carry at most 8 texture-coordinate sets; more is `Malformed`. Optimised vertex colours are `Unsupported`.
- The product tree: each drawable tessellation placed by its occurrence path's locations and the item's coordinate
systems (a 4x4 `Matrix`), coloured by the style inheritance rules, with occurrences' entity references applied
@@ -39,6 +39,6 @@ BitReader: bit, bits, character, unsigned_integer, integer, integer_vbn, double_
came from, its visibility and the range of placements it drew.
- Occurrence and prototype cycles are `Malformed`; the walk is capped at depth 64, 2^20 visits and `MAX_PLACEMENTS`.
- A tree's markups (PMI), views, scene lights and clipping planes are read past, not modelled; so are textures.
- Not yet in the crate: rebuilding compressed meshes, textures.
- Not yet in the crate: stored-normal or one-status compressed mesh reconstruction, textures.
- The `Double` code table's rows come from [prc-rs](https://github.com/ralovich/prc-rs) (MIT); its notice is in `src/acof/table.rs`.
A few reading choices also follow prc-rs; each is marked `// prc-rs:` in the source.
+2
View File
@@ -349,5 +349,7 @@ impl Walk {
}
}
#[cfg(test)]
mod independent;
#[cfg(test)]
mod tests;
@@ -0,0 +1,451 @@
#![allow(
clippy::cast_possible_truncation,
clippy::cast_precision_loss,
clippy::expect_used,
clippy::float_cmp,
clippy::many_single_char_names,
clippy::panic,
clippy::unwrap_used
)]
use super::*;
const S: f64 = std::f64::consts::SQRT_2;
#[derive(Clone, Copy)]
enum Slot {
Point(V),
#[allow(dead_code)]
Reference(u32),
}
#[derive(Clone, Copy)]
enum Recipe {
Seed { slots: [Slot; 3], status: i32, face: u32 },
Apex { edge: (u32, u32), opposite: u32, slot: Slot, status: i32, face: u32 },
}
impl Recipe {
fn status(self) -> i32 {
match self {
Self::Seed { status, .. } | Self::Apex { status, .. } => status,
}
}
fn face(self) -> u32 {
match self {
Self::Seed { face, .. } | Self::Apex { face, .. } => face,
}
}
}
#[derive(Clone)]
struct Encoded {
tolerance: f64,
origin: V,
points: Vec<i64>,
edge_status: Vec<i32>,
face_of: Vec<u32>,
is_reference: Vec<bool>,
references: Vec<u32>,
positions: Vec<V>,
triangles: Vec<[u32; 3]>,
}
impl Encoded {
fn arrays(&self, limit: usize) -> Arrays<'_> {
Arrays {
tolerance: self.tolerance,
origin: self.origin,
points: &self.points,
edge_status: &self.edge_status,
triangles: self.triangles.len(),
is_reference: &self.is_reference,
references: &self.references,
limit,
}
}
#[allow(dead_code)]
fn faces(&self) -> usize {
self.face_of.iter().max().map_or(0, |&face| face as usize + 1)
}
fn push_reference(&mut self, vertex: u32) -> u32 {
let index = usize::try_from(vertex).unwrap();
assert!(index < self.positions.len(), "a recipe reference must name an earlier vertex");
self.is_reference.push(true);
self.references.push(vertex);
vertex
}
fn push_position(&mut self, position: V, point: [i64; 3]) -> u32 {
self.points.extend(point);
self.is_reference.push(false);
self.positions.push(position);
u32::try_from(self.positions.len() - 1).unwrap()
}
fn push_seed_point(&mut self, index: usize, target: V, triangle: [u32; 3]) -> u32 {
let base = match index {
0 => self.origin,
1 => self.positions[usize::try_from(triangle[0]).unwrap()],
2 => {
let first = self.positions[usize::try_from(triangle[0]).unwrap()];
let second = self.positions[usize::try_from(triangle[1]).unwrap()];
p_scale(p_add(first, second), 0.5)
}
_ => panic!("a seed has exactly three slots"),
};
let point = quantize(p_sub(target, base), self.tolerance);
let position = p_add(base, scaled(point, self.tolerance));
self.push_position(position, point)
}
fn push_apex_point(&mut self, edge: (u32, u32), opposite: u32, target: V) -> u32 {
let (p, q) = edge;
let (lo, hi) = if p < q { (p, q) } else { (q, p) };
let lo = self.positions[usize::try_from(lo).unwrap()];
let hi = self.positions[usize::try_from(hi).unwrap()];
let opposite = self.positions[usize::try_from(opposite).unwrap()];
let (origin, x, y, z) = encoder_frame(lo, hi, opposite);
let offset = p_sub(target, origin);
let point = [
quantize_component(p_dot(offset, x), self.tolerance),
quantize_component(-p_dot(offset, y), self.tolerance),
quantize_component(-p_dot(offset, z), self.tolerance),
];
let delta = scaled(point, self.tolerance);
let position = p_sub(p_sub(p_add(origin, p_scale(x, delta[0])), p_scale(y, delta[1])), p_scale(z, delta[2]));
self.push_position(position, point)
}
}
fn encode(origin: V, tolerance: f64, recipes: &[Recipe]) -> Encoded {
assert!(tolerance.is_finite() && tolerance > 0.0, "a positive finite tolerance");
let mut edge_status: Vec<i32> = recipes.iter().map(|recipe| recipe.status()).collect();
edge_status.resize(recipes.len().saturating_mul(3), 0);
let mut encoded = Encoded {
tolerance,
origin,
points: Vec::new(),
edge_status,
face_of: Vec::new(),
is_reference: Vec::new(),
references: Vec::new(),
positions: Vec::new(),
triangles: Vec::new(),
};
for &recipe in recipes {
encoded.face_of.push(recipe.face());
match recipe {
Recipe::Seed { slots, .. } => {
let mut triangle = [0; 3];
for (index, slot) in slots.into_iter().enumerate() {
triangle[index] = match slot {
Slot::Point(target) => encoded.push_seed_point(index, target, triangle),
Slot::Reference(vertex) => encoded.push_reference(vertex),
};
}
encoded.triangles.push(triangle);
}
Recipe::Apex { edge: (p, q), opposite, slot, .. } => {
let vertex = match slot {
Slot::Point(target) => encoded.push_apex_point((p, q), opposite, target),
Slot::Reference(vertex) => encoded.push_reference(vertex),
};
encoded.triangles.push([p, q, vertex]);
}
}
}
encoded
}
fn p_add(a: V, b: V) -> V {
[a[0] + b[0], a[1] + b[1], a[2] + b[2]]
}
fn p_sub(a: V, b: V) -> V {
[a[0] - b[0], a[1] - b[1], a[2] - b[2]]
}
fn p_scale(a: V, factor: f64) -> V {
a.map(|component| component * factor)
}
fn p_dot(a: V, b: V) -> f64 {
a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
}
fn p_cross(a: V, b: V) -> V {
[a[1] * b[2] - a[2] * b[1], a[2] * b[0] - a[0] * b[2], a[0] * b[1] - a[1] * b[0]]
}
fn quantize_component(value: f64, tolerance: f64) -> i64 {
let quantized = (value / tolerance).round();
assert!(quantized.is_finite() && quantized >= i64::MIN as f64 && quantized <= i64::MAX as f64);
quantized as i64
}
fn quantize(value: V, tolerance: f64) -> [i64; 3] {
value.map(|component| quantize_component(component, tolerance))
}
fn scaled(point: [i64; 3], tolerance: f64) -> V {
point.map(|component| component as f64 * tolerance)
}
fn encoder_length(value: V) -> Option<f64> {
let squared = (value[0] * value[0] + value[1] * value[1] + value[2] * value[2]) as f32;
let bits = squared.to_bits();
let exponent = (bits >> 23) & 0xff;
let seed = if exponent > 127 { f32::from_bits((bits & !(0xff << 23)) | (((exponent - 127) / 2 + 127) << 23)) } else { squared };
let squared = f64::from(squared);
let mut current = f64::from(seed);
for _ in 0..100 {
let next = 0.5 * (current + squared / current);
if next == current {
return Some(next);
}
current = next;
}
None
}
fn encoder_unit(value: V) -> Option<V> {
let length = encoder_length(value).filter(|&length| length >= f64::from(f32::EPSILON))?;
Some([value[0] / length, value[1] / length, value[2] / length])
}
fn encoder_ortho_z(x: V) -> Option<V> {
let x = encoder_unit(x)?;
encoder_unit(p_cross(x, [0.0, 1.0, 0.0])).or_else(|| encoder_unit(p_cross(x, [1.0, 0.0, 0.0])))
}
fn encoder_frame(lo: V, hi: V, opposite: V) -> (V, V, V, V) {
let origin = p_scale(p_add(lo, hi), 0.5);
let difference = p_sub(lo, hi);
let x = encoder_unit(difference).unwrap_or(difference);
let residue = p_cross(p_sub(opposite, origin), x);
let (y, z) = encoder_unit(residue)
.and_then(|z| Some((encoder_unit(p_cross(z, x))?, z)))
.or_else(|| {
let z = encoder_ortho_z(x)?;
let y = encoder_unit(p_cross(z, x))?;
Some(if p_dot(residue, z) < 0.0 { (p_scale(y, -1.0), p_scale(z, -1.0)) } else { (y, z) })
})
.unwrap_or_default();
(origin, x, y, z)
}
fn assert_positions(actual: &[V], expected: &[V]) {
assert_eq!(actual.len(), expected.len(), "vertex counts differ");
for (index, (actual, expected)) in actual.iter().zip(expected).enumerate() {
for component in 0..3 {
assert!(
(actual[component] - expected[component]).abs() < 1e-9,
"vertex {index}, component {component}: actual {actual:?}, expected {expected:?}",
);
}
}
}
#[allow(dead_code)]
fn assert_within_tolerance(actual: &[V], source: &[V], tolerance: f64) {
assert_eq!(actual.len(), source.len(), "vertex counts differ");
let limit = tolerance * 3.0_f64.sqrt() / 2.0;
for (index, (actual, source)) in actual.iter().zip(source).enumerate() {
let difference = p_sub(*actual, *source);
let distance = p_dot(difference, difference).sqrt();
assert!(distance <= limit + 1e-12, "vertex {index}: distance {distance} exceeds {limit}; actual {actual:?}, source {source:?}");
}
}
fn triangle_seed(x: f64, status: i32, face: u32) -> Recipe {
Recipe::Seed { slots: [Slot::Point([x, 0.0, 0.0]), Slot::Point([x + 2.0, 0.0, 0.0]), Slot::Point([x, 2.0, 0.0])], status, face }
}
fn panel(target: V) -> Encoded {
encode(
[0.0; 3],
0.5,
&[
triangle_seed(0.0, 3, 0),
Recipe::Apex { edge: (2, 1), opposite: 0, slot: Slot::Point(target), status: 3, face: 0 },
Recipe::Apex { edge: (2, 3), opposite: 1, slot: Slot::Reference(0), status: 2, face: 0 },
Recipe::Apex { edge: (0, 3), opposite: 2, slot: Slot::Reference(1), status: 0, face: 0 },
],
)
}
#[test]
fn independent_seed_and_apex_match_a_hand_computed_stream() {
let encoded = encode(
[10.0, 0.0, 0.0],
0.5,
&[
Recipe::Seed { slots: [Slot::Point([10.0, 0.0, 0.0]), Slot::Point([12.0, 0.0, 0.0]), Slot::Point([10.0, 2.0, 0.0])], status: 2, face: 0 },
Recipe::Apex { edge: (2, 1), opposite: 0, slot: Slot::Point([11.0 + 2.0 * S, 1.0 + S, -1.0]), status: 0, face: 0 },
],
);
assert_eq!(encoded.points, [0, 0, 0, 4, 0, 0, -2, 4, 0, 2, -6, 2]);
let rebuilt = rebuild(&encoded.arrays(usize::MAX)).unwrap();
assert_eq!(rebuilt.triangles, [[0, 1, 2], [2, 1, 3]]);
let expected = [[10.0, 0.0, 0.0], [12.0, 0.0, 0.0], [10.0, 2.0, 0.0], [11.0 + 2.0 * S, 1.0 + S, -1.0]];
assert_positions(&rebuilt.positions, &expected);
}
#[test]
fn independent_components_and_a_reference_are_rebuilt() {
let encoded = encode(
[0.0; 3],
0.5,
&[
triangle_seed(0.0, 2, 0),
Recipe::Apex { edge: (2, 1), opposite: 0, slot: Slot::Reference(0), status: 0, face: 0 },
triangle_seed(5.0, 0, 1),
],
);
let rebuilt = rebuild(&encoded.arrays(usize::MAX)).unwrap();
assert_eq!(rebuilt.triangles, [[0, 1, 2], [2, 1, 0], [3, 4, 5]]);
assert_eq!(encoded.references, [0]);
assert_eq!(encoded.face_of, [0, 0, 1]);
assert_eq!(rebuilt.positions.len(), 6);
let expected = [[0.0, 0.0, 0.0], [2.0, 0.0, 0.0], [0.0, 2.0, 0.0], [5.0, 0.0, 0.0], [7.0, 0.0, 0.0], [5.0, 2.0, 0.0]];
assert_positions(&rebuilt.positions, &expected);
}
#[test]
fn independent_fold_and_component_retry_rebuild_the_same_panel() {
let folded = [1.0 - 1.0 / S, 1.0 - S, 0.0];
let unfolded = [1.0 + S, 1.0 + 1.0 / S, 0.0];
for target in [folded, unfolded] {
let source = [[0.0, 0.0, 0.0], [2.0, 0.0, 0.0], [0.0, 2.0, 0.0], target];
let encoded = panel(target);
assert_within_tolerance(&encoded.positions, &source, 0.5);
let rebuilt = rebuild(&encoded.arrays(usize::MAX)).unwrap();
assert_eq!(rebuilt.triangles, [[0, 1, 2], [2, 1, 3], [2, 3, 0], [0, 3, 1]]);
assert_eq!(rebuilt.positions.len(), 4);
assert_within_tolerance(&rebuilt.positions, &source, 0.5);
}
}
#[test]
fn independent_closed_continuation_uses_the_open_edge() {
let encoded = encode(
[0.0; 3],
0.5,
&[
triangle_seed(0.0, 2, 0),
Recipe::Apex { edge: (2, 1), opposite: 0, slot: Slot::Point([0.0, 0.0, 2.0]), status: 2, face: 0 },
Recipe::Apex { edge: (3, 1), opposite: 2, slot: Slot::Reference(0), status: 2, face: 0 },
Recipe::Apex { edge: (3, 0), opposite: 1, slot: Slot::Reference(2), status: 0, face: 0 },
],
);
let source = [[0.0, 0.0, 0.0], [2.0, 0.0, 0.0], [0.0, 2.0, 0.0], [0.0, 0.0, 2.0]];
assert_within_tolerance(&encoded.positions, &source, 0.5);
let rebuilt = rebuild(&encoded.arrays(usize::MAX)).unwrap();
assert_eq!(rebuilt.triangles, [[0, 1, 2], [2, 1, 3], [3, 1, 0], [3, 0, 2]]);
assert_within_tolerance(&rebuilt.positions, &source, 0.5);
}
#[test]
fn independent_non_planar_strip_tracks_the_quantized_working_mesh() {
let source: Vec<V> = (0..16).map(|index| [f64::from(index) * 0.05, f64::from(index % 2) * 2.0, (f64::from(index % 5) - 2.0) * 0.03]).collect();
let mut recipes = vec![Recipe::Seed { slots: [Slot::Point(source[0]), Slot::Point(source[1]), Slot::Point(source[2])], status: 2, face: 0 }];
let (mut p, mut q, mut opposite) = (2_u32, 1_u32, 0_u32);
for index in 1..source.len() - 2 {
let vertex = u32::try_from(index + 2).unwrap();
let status = if index % 2 == 1 { 1 } else { 2 };
recipes.push(Recipe::Apex { edge: (p, q), opposite, slot: Slot::Point(source[index + 2]), status, face: 0 });
if status == 1 {
(p, q, opposite) = (p, vertex, q);
} else {
(p, q, opposite) = (vertex, q, p);
}
}
let encoded = encode([0.0; 3], 1e-4, &recipes);
assert_within_tolerance(&encoded.positions, &source, 1e-4);
let rebuilt = rebuild(&encoded.arrays(usize::MAX)).unwrap();
assert_eq!(
rebuilt.triangles,
[
[0, 1, 2],
[2, 1, 3],
[2, 3, 4],
[4, 3, 5],
[4, 5, 6],
[6, 5, 7],
[6, 7, 8],
[8, 7, 9],
[8, 9, 10],
[10, 9, 11],
[10, 11, 12],
[12, 11, 13],
[12, 13, 14],
[14, 13, 15],
]
);
assert_eq!(encoded.points.len(), source.len() * 3);
assert_within_tolerance(&rebuilt.positions, &source, 1e-4);
}
#[test]
fn independent_near_degenerate_parent_uses_an_orthogonal_frame() {
let encoded = encode(
[0.0; 3],
1e-8,
&[
Recipe::Seed {
slots: [Slot::Point([1.0, 1.0 + 1e-8, 0.0]), Slot::Point([2.0, 0.0, 0.0]), Slot::Point([0.0, 2.0, 0.0])],
status: 2,
face: 0,
},
Recipe::Apex { edge: (2, 1), opposite: 0, slot: Slot::Point([0.3, 0.7, 0.2]), status: 0, face: 0 },
],
);
let source = [[1.0, 1.0 + 1e-8, 0.0], [2.0, 0.0, 0.0], [0.0, 2.0, 0.0], [0.3, 0.7, 0.2]];
assert_within_tolerance(&encoded.positions, &source, 1e-8);
let rebuilt = rebuild(&encoded.arrays(usize::MAX)).unwrap();
assert_eq!(rebuilt.triangles, [[0, 1, 2], [2, 1, 3]]);
assert_within_tolerance(&rebuilt.positions, &source, 1e-8);
}
#[test]
fn independent_rebuild_requires_exact_arrays_and_enough_budget() {
let encoded = encode([0.0; 3], 0.5, &[triangle_seed(0.0, 0, 0)]);
assert!(rebuild(&encoded.arrays(usize::MAX)).is_ok());
let mut extra_point = encoded.clone();
extra_point.points.push(0);
assert_eq!(rebuild(&extra_point.arrays(usize::MAX)).unwrap_err(), "the decoded triangles do not use up the stored arrays",);
let mut extra_slot = encoded.clone();
extra_slot.is_reference.push(false);
assert_eq!(rebuild(&extra_slot.arrays(usize::MAX)).unwrap_err(), "the decoded triangles do not use up the stored arrays",);
let mut extra_reference = encoded.clone();
extra_reference.references.push(0);
assert_eq!(rebuild(&extra_reference.arrays(usize::MAX)).unwrap_err(), "the decoded triangles do not use up the stored arrays",);
assert_eq!(rebuild(&encoded.arrays(0)).unwrap_err(), "the rebuild needs more than the decoded-element allowance left",);
}
#[test]
fn independent_faces_group_walk_order_triangles() {
let encoded = encode([0.0; 3], 0.5, &[triangle_seed(0.0, 0, 1), triangle_seed(5.0, 0, 0)]);
let rebuilt = rebuild(&encoded.arrays(usize::MAX)).unwrap();
let mesh = super::super::by_face(rebuilt, &encoded.face_of, encoded.faces(), &[]);
assert_eq!(mesh.faces, [0..1, 1..2]);
assert_eq!(mesh.triangles, [[3, 4, 5], [0, 1, 2]]);
let expected = [[0.0, 0.0, 0.0], [2.0, 0.0, 0.0], [0.0, 2.0, 0.0], [5.0, 0.0, 0.0], [7.0, 0.0, 0.0], [5.0, 2.0, 0.0]];
assert_positions(&mesh.positions, &expected);
}
+111
View File
@@ -0,0 +1,111 @@
//! Raw PSD channel DisplayInfo (1077/1007) and Alternate Spot Colors (1067) records.
//!
//! Ported from PhotoCraft channel_map: Jason D's f7f8fdcd89 DisplayInfo framing and
//! Khawar Zamman Wani's 9a390661b5 alternate-spot reader. Colour interpretation, opacity
//! clamping, channel matching and legacy compatibility decisions belong to the caller.
//! Readers borrow their input and ignore a trailing partial record, preserving the
//! original tolerant import behavior. Version words are framing, not validation here.
/// One 13-byte DisplayInfo record, without document-specific colour interpretation.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct DisplayInfo {
/// PSD colour-space identifier.
pub space: u16,
/// Four raw colour components.
pub components: [u16; 4],
/// Raw opacity (normally 0 through 100).
pub opacity: u16,
/// Raw channel kind (0 selected, 1 masked, 2 spot).
pub kind: u8,
}
impl DisplayInfo {
/// Encode the version-1 resource's 13-byte record, without clamping fields.
pub fn to_bytes(self) -> [u8; 13] {
let mut out = [0; 13];
let values = [self.space, self.components[0], self.components[1], self.components[2], self.components[3], self.opacity];
for (slot, value) in out[..12].as_chunks_mut::<2>().0.iter_mut().zip(values) {
*slot = value.to_be_bytes();
}
out[12] = self.kind;
out
}
}
/// Iterate complete DisplayInfo records without allocating.
///
/// `versioned` selects resource 1077 (skip four version bytes, 13-byte records),
/// otherwise resource 1007 (14-byte records, ignoring each padding byte). A short
/// version header or incomplete final record yields no corresponding record.
pub fn display_info(data: &[u8], versioned: bool) -> impl ExactSizeIterator<Item = DisplayInfo> + '_ {
let (body, size) = if versioned { (data.get(4..).unwrap_or(&[]), 13) } else { (data, 14) };
body.chunks_exact(size).map(|rec| {
let u = |i: usize| u16::from_be_bytes([rec[i], rec[i + 1]]);
DisplayInfo { space: u(0), components: [u(2), u(4), u(6), u(8)], opacity: u(10), kind: rec[12] }
})
}
/// One Alternate Spot Colors record, retaining unknown colour spaces.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct AlternateSpotColor {
/// Channel identifier from resource 1053.
pub id: u32,
/// PSD colour-space identifier.
pub space: u16,
/// Four raw colour components.
pub components: [u16; 4],
}
/// Iterate available complete 14-byte records up to the resource's declared u16 count.
///
/// Short headers, absent declared records and trailing partial bytes are tolerated exactly
/// as in the original importer. No allocation is derived from an untrusted count.
pub fn alternate_spot_colors(data: &[u8]) -> impl ExactSizeIterator<Item = AlternateSpotColor> + '_ {
let count = data.get(2..4).map_or(0, |c| usize::from(u16::from_be_bytes([c[0], c[1]])));
data.get(4..).unwrap_or_default().as_chunks::<14>().0.iter().take(count).map(|rec| {
let u = |i: usize| u16::from_be_bytes([rec[i], rec[i + 1]]);
AlternateSpotColor { id: u32::from_be_bytes([rec[0], rec[1], rec[2], rec[3]]), space: u(4), components: [u(6), u(8), u(10), u(12)] }
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn display_round_trip_and_truncation() {
let record = DisplayInfo { space: 0x2331, components: [0, 1, 255, u16::MAX], opacity: 500, kind: 255 };
let mut modern = 99u32.to_be_bytes().to_vec();
modern.extend(record.to_bytes());
assert_eq!(display_info(&modern, true).collect::<Vec<_>>(), [record]);
for n in 0..modern.len() {
assert_eq!(display_info(&modern[..n], true).len(), 0);
}
modern.extend([1, 2, 3]);
assert_eq!(display_info(&modern, true).len(), 1);
let mut old = record.to_bytes().to_vec();
old.push(42);
old.extend(record.to_bytes());
old.push(99);
assert_eq!(display_info(&old, false).collect::<Vec<_>>(), [record, record]);
assert_eq!(display_info(&old[..27], false).len(), 1);
}
#[test]
fn alternate_count_is_bounded_by_available_records() {
let mut bytes = vec![0, 9, 255, 255];
bytes.extend(123u32.to_be_bytes());
for value in [7u16, 10000, 0xffff, 4, 5] {
bytes.extend(value.to_be_bytes());
}
let want = AlternateSpotColor { id: 123, space: 7, components: [10000, 0xffff, 4, 5] };
assert_eq!(alternate_spot_colors(&bytes).collect::<Vec<_>>(), [want]);
for n in 0..bytes.len() {
assert_eq!(alternate_spot_colors(&bytes[..n]).len(), 0);
}
bytes.extend([1, 2, 3]);
assert_eq!(alternate_spot_colors(&bytes).len(), 1);
bytes[2..4].copy_from_slice(&0u16.to_be_bytes());
assert_eq!(alternate_spot_colors(&bytes).len(), 0);
}
}
+103
View File
@@ -0,0 +1,103 @@
//! PSD Grid and Guides version 2 (resource 1092) record decoding.
//!
//! Extracted from PhotoCraft `guides_map.rs` at f49564d281bf8892db58ed154767717223aff4f6
//! by Bram Heerink. Document colour preference and resource-retention policy belong to callers.
//! Unknown direction values retain PhotoCraft's vertical interpretation. Grid cycles, reserved
//! bytes and trailing data are not interpreted. Resource 1097 remains opaque except its count.
/// Grid and Guides version 2 resource ID.
pub const GUIDES_V2: u16 = 1092;
/// Associated guide identifiers resource ID.
pub const GUIDE_IDS: u16 = 1097;
/// One version 2 guide record.
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
pub struct GuideV2 {
/// Signed position in units of 1/32 pixel.
pub location: i32,
/// True for vertical guides (direction byte other than 1).
pub vertical: bool,
/// Stored RGB colour; interpretation of preference colours is app policy.
pub rgb: [u8; 3],
}
fn be_u32(data: &[u8], at: usize) -> Option<u32> {
let b = data.get(at..at.checked_add(4)?)?;
Some(u32::from_be_bytes([b[0], b[1], b[2], b[3]]))
}
/// Validate the full declared record region before returning an allocation-free iterator.
/// Returns `None` for an unsupported version, short header or truncated records.
/// Record count cannot cause allocation or work beyond the supplied byte slice.
pub fn parse_v2(data: &[u8]) -> Option<impl ExactSizeIterator<Item = GuideV2> + '_> {
if be_u32(data, 0)? != 2 {
return None;
}
let count = usize::try_from(be_u32(data, 12)?).ok()?;
let end = 16usize.checked_add(count.checked_mul(9)?)?;
let records = data.get(16..end)?;
Some(records.as_chunks::<9>().0.iter().map(|g| GuideV2 {
location: i32::from_be_bytes([g[0], g[1], g[2], g[3]]),
vertical: g[4] != 1,
rgb: [g[6], g[7], g[8]],
}))
}
/// Only the declared entry count in resource 1097; this does not validate its GUID payload.
pub fn ids_count(data: &[u8]) -> Option<u32> {
be_u32(data, 0)
}
#[cfg(test)]
mod tests {
use super::*;
fn fixture() -> Vec<u8> {
let mut v = Vec::new();
for n in [2u32, 576, 576, 2] {
v.extend_from_slice(&n.to_be_bytes());
}
for (position, direction, rgb) in [(512i32, 0u8, [74, 255, 255]), (-32, 1, [1, 2, 3])] {
v.extend_from_slice(&position.to_be_bytes());
v.extend_from_slice(&[direction, 0]);
v.extend_from_slice(&rgb);
}
v
}
#[test]
fn decodes_signed_positions_directions_and_colours() {
let data = fixture();
let actual = parse_v2(&data).map(Iterator::collect::<Vec<_>>);
assert_eq!(
actual,
Some(vec![GuideV2 { location: 512, vertical: true, rgb: [74, 255, 255] }, GuideV2 { location: -32, vertical: false, rgb: [1, 2, 3] },])
);
}
#[test]
fn validates_every_truncation_and_hostile_count_before_iteration() {
let mut data = fixture();
for n in 0..data.len() {
assert!(parse_v2(&data[..n]).is_none());
}
data[12..16].copy_from_slice(&u32::MAX.to_be_bytes());
assert!(parse_v2(&data).is_none());
data[12..16].copy_from_slice(&0u32.to_be_bytes());
assert_eq!(parse_v2(&data).map(|v| v.len()), Some(0));
data[3] = 1;
assert!(parse_v2(&data).is_none());
}
#[test]
fn preserves_unknown_direction_reserved_bytes_and_trailing_data_policy() {
let mut data = fixture();
data[20] = 255;
data[21] = 42;
data.extend_from_slice(&[9; 12]);
assert_eq!(parse_v2(&data).and_then(|mut v| v.next()).map(|g| g.vertical), Some(true));
assert_eq!(parse_v2(&data).map(|v| v.len()), Some(2));
assert_eq!(ids_count(&[0, 0, 0, 2, 255]), Some(2));
assert_eq!(ids_count(&[0, 0, 0]), None);
}
}
+3
View File
@@ -60,6 +60,7 @@ pub mod asl;
pub mod atn;
pub mod blend;
pub mod builder;
pub mod channel_resources;
mod codepage;
pub mod compression;
pub mod csh;
@@ -74,6 +75,7 @@ pub mod fixtures;
pub mod flat;
pub mod float;
pub mod grd;
pub mod guides;
pub mod hdr;
pub mod head;
pub mod header;
@@ -101,6 +103,7 @@ pub mod testgen;
pub mod text;
pub mod tiff;
pub mod tree;
pub mod unicode_names;
pub use blend::BlendMode;
pub use builder::{GroupSpec, LayerSpec, MaskSpec, PixelData, PsdBuilder};
+54
View File
@@ -0,0 +1,54 @@
//! Counted UTF-16 name records, as used by PSD Unicode Alpha Names (resource 1045).
//!
//! Adapted from PhotoCraft's channel-name reader. Framing is shared; decoding malformed
//! UTF-16, removing terminators and assigning names to document channels remain caller policy.
/// Iterate complete records as borrowed big-endian UTF-16 byte slices.
///
/// A record starts with a big-endian `u32` code-unit count. Empty records are retained.
/// An incomplete count, truncated record or arithmetic overflow ends the list, preserving
/// preceding complete records. No allocation is driven by the declared count, and bytes
/// after a malformed record are not interpreted as new records.
pub fn records(mut data: &[u8]) -> impl Iterator<Item = &[u8]> {
std::iter::from_fn(move || {
let count = data.get(..4)?;
let count = u32::from_be_bytes([count[0], count[1], count[2], count[3]]);
let input = data;
// On any malformed length the iterator stays exhausted on subsequent calls.
data = &[];
let len = usize::try_from(count).ok()?.checked_mul(2)?;
let end = 4usize.checked_add(len)?;
let record = input.get(4..end)?;
data = input.get(end..)?;
Some(record)
})
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn borrows_empty_and_uninterpreted_code_units() {
let data = [0, 0, 0, 0, 0, 0, 0, 3, 0xd8, 0, 0, 65, 0, 0];
let found: Vec<_> = records(&data).collect();
assert_eq!(found, [&data[4..4], &data[8..14]]);
assert_eq!(found[1].as_ptr(), data[8..].as_ptr());
}
#[test]
fn partial_tail_and_hostile_count_stop_without_losing_prefix() {
let first = [0, 0, 0, 1, 0, 65];
for tail in [&[0][..], &[0, 0, 0], &[0, 0, 0, 2, 0, 66], &[255, 255, 255, 255, 0, 66]] {
let mut bytes = first.to_vec();
bytes.extend(tail);
let mut it = records(&bytes);
assert_eq!(it.next(), Some(&first[4..]));
assert_eq!(it.next(), None);
assert_eq!(it.next(), None);
}
for end in 0..first.len() {
assert_eq!(records(&first[..end]).count(), 0);
}
}
}
+3 -2
View File
@@ -15,8 +15,9 @@ workspace = true
fax = "0.2.7"
# CCITT fax decoding, the decoder the vendored PDF reader uses. MIT OR Apache-2.0.
hayro-ccitt = { version = "0.3", default-features = false }
# JBIG2 decoding, the decoder the vendored PDF reader uses (the workspace patches it to `vendor/hayro-jbig2`).
hayro-jbig2 = { version = "=0.3.0", default-features = false, features = ["std"] }
# The bounded JBIG2 API is a local extension: consumers do not inherit workspace patches.
# Keep the vendored dependency explicit so Git consumers retain its work-budget safeguards.
hayro-jbig2 = { path = "../../vendor/hayro-jbig2", version = "=0.3.0", default-features = false, features = ["std"] }
thiserror = { workspace = true }
[dev-dependencies]
+9
View File
@@ -78,6 +78,15 @@ mod tests {
use super::*;
use crate::{encode_jbig2, encode_jbig2_generic};
/// A registry fallback lacks the budget APIs and breaks consumers outside this workspace.
#[test]
fn bounded_decoder_dependency_is_explicit_for_external_consumers() {
let manifest = include_str!("../../Cargo.toml");
let dependency = manifest.lines().find(|line| line.starts_with("hayro-jbig2 =")).unwrap();
assert!(dependency.contains(r#"path = "../../vendor/hayro-jbig2""#));
assert!(dependency.contains(r#"version = "=0.3.0""#));
}
/// [`decode_jbig2_within`] with no limit on the work.
fn decode_jbig2(data: &[u8], globals: Option<&[u8]>, columns: u32, rows: u32, max: usize) -> Result<Vec<u8>, CodecError> {
let mut unbounded = u64::MAX;