From 5ab7a6035c0ff409cc743978b17d73f414b58524 Mon Sep 17 00:00:00 2001 From: el-j Date: Sun, 15 Nov 2026 13:06:49 +0100 Subject: [PATCH] craft-video: FFV1 lossless video, version 3 range-coder decoder and encoder Adds the ffv1 feature (RFC 9043): YCbCr (any 2^n subsampling, gray, optional transparency) and RGB through the JPEG 2000 reversible colour transform, 8 to 16 bits, any slice raster, slice and configuration record CRCs. Not covered yet: the Golomb-Rice coder, versions 0 and 1, inter frames. Part of #1509 --- crates/video/Cargo.toml | 6 + crates/video/src/ffv1/README.md | 52 ++ crates/video/src/ffv1/mod.rs | 929 ++++++++++++++++++++++++++++++++ crates/video/src/ffv1/rc.rs | 229 ++++++++ crates/video/src/lib.rs | 4 + crates/video/tests/ffv1.rs | 304 +++++++++++ 6 files changed, 1524 insertions(+) create mode 100644 crates/video/src/ffv1/README.md create mode 100644 crates/video/src/ffv1/mod.rs create mode 100644 crates/video/src/ffv1/rc.rs create mode 100644 crates/video/tests/ffv1.rs diff --git a/crates/video/Cargo.toml b/crates/video/Cargo.toml index c3ebfd722..dae21e5b1 100644 --- a/crates/video/Cargo.toml +++ b/crates/video/Cargo.toml @@ -34,6 +34,8 @@ mpeg2-encode = ["mpeg2-decode"] # MPEG-4 Part 2 video (ISO/IEC 14496-2, the Xvid/DivX format): Simple profile encoder. mpeg4 = ["mpeg4-encode"] mpeg4-encode = ["craft-media/bitstream"] +# FFV1 lossless video (RFC 9043): version 3, range coder, decoder and encoder. +ffv1 = [] # Apple ProRes (SMPTE RDD 36): decoder and encoder. prores = ["craft-media/bitstream"] # H.264 / AVC: decoder and encoder; `h264-decode` or `h264-encode` for one of them. @@ -143,6 +145,10 @@ required-features = ["mpeg4-encode"] name = "mpeg2" required-features = ["mpeg2-decode"] +[[test]] +name = "ffv1" +required-features = ["ffv1"] + [[test]] name = "prores" required-features = ["prores"] diff --git a/crates/video/src/ffv1/README.md b/crates/video/src/ffv1/README.md new file mode 100644 index 000000000..90312dbe5 --- /dev/null +++ b/crates/video/src/ffv1/README.md @@ -0,0 +1,52 @@ +# FFV1 + +Clean-room FFV1 lossless video codec, written from RFC 9043. Feature `ffv1`. + +## What is supported + +| | Decoder | Encoder | +|---|---|---| +| Version | 3 (the one with a configuration record) | 3 | +| Coder | range coder, default or custom state transition table | range coder, default table | +| Colour | YCbCr (any 2^n chroma subsampling, gray, optional transparency), RGB through the JPEG 2000 reversible colour transform (optional transparency) | the same, RGB up to 15 bits | +| Depth | 8 to 16 bits per sample | 8 to 16 bits (RGB 8 to 15) | +| Slices | any raster whose boundaries are multiples of the chroma subsampling | the same | +| Frames | keyframes | keyframes only (`intra` 1) | +| Error detection | slice and configuration record CRCs, checked | written | + +Not supported, and reported as `Error::Unsupported`: the Golomb-Rice coder (`coder_type` 0), +versions 0 and 1 (parameters inside each keyframe, no configuration record), inter frames +(`keyframe` 0), and slice rasters whose boundaries fall inside a chroma sample. + +## Using it + +The configuration record goes in the container (Matroska `CodecPrivate`, the AVI `strf` +extension, an MP4 `glbl` box); each frame is one packet. + +```text +let enc = Encoder::new(&template_frame, EncoderConfig::default())?; +let config = enc.config_record(); +let packet = enc.encode(&frame)?; + +let dec = Decoder::new(&config, width, height)?; +let frame = dec.decode(&packet)?; +``` + +## Notes on the format + +- The Parameters in the configuration record are range coded with the *default* state transition + table. A custom table (`coder_type` 2) applies to the slices only. +- Each Quantization Table starts from fresh states; a Quantization Table Set is five of them. +- A slice is one range-coded stream: for the first slice the `keyframe` bit, then the slice header, + then the samples. Cb and Cr share one set of context states; transparency has its own. +- The context is the sum of five quantised differences. With the default tables this encoder + writes 15125 contexts; FFmpeg refuses tables that multiply to more than 32768, so the encoder + stays below that although the RFC's limit (on half the product) is looser. +- The encoder ends a stream with the top of its final range, so bytes after it (a CRC in the + configuration record) cannot change what decodes. + +## Verification + +`tests/ffv1.rs`: round trips over every shape, hostile input (every truncation and bit flip), +and ffmpeg as the oracle in both directions (skipped without ffmpeg, a failure with +`CRAFT_MEDIA_REQUIRE_ORACLES=1`). diff --git a/crates/video/src/ffv1/mod.rs b/crates/video/src/ffv1/mod.rs new file mode 100644 index 000000000..4df60f9a1 --- /dev/null +++ b/crates/video/src/ffv1/mod.rs @@ -0,0 +1,929 @@ +//! FFV1 lossless video codec (RFC 9043): version 3, range coder, intra-only, YCbCr and RGB (JPEG 2000 +//! RCT), 8 to 16 bits per sample, any number of slices. +//! +//! - [`Decoder`]: built from the *configuration record* a container stores (Matroska `CodecPrivate`, +//! AVI `strf` extension, MP4 `glbl`) and the frame size; [`Decoder::decode`] turns one packet into a +//! [`Frame`]. Slice CRCs are checked. +//! - [`Encoder`]: [`Encoder::config_record`] gives the bytes for the container, [`Encoder::encode`] +//! one packet per frame; every frame is a keyframe. +//! +//! Not supported (reported as [`Error::Unsupported`]): the Golomb-Rice coder (`coder_type` 0), +//! versions 0 and 1 (no configuration record, parameters in every keyframe), inter frames +//! (`intra` 0 with `keyframe` 0), and slice rasters whose boundaries are not multiples of the +//! chroma subsampling. See `src/ffv1/README.md`. +//! +//! Implemented from RFC 9043. Frames are planar `u16`: for YCbCr, `[Y, Cb, Cr]` (plus an optional +//! transparency plane); for RGB, `[R, G, B]` (plus transparency), all at full size. + +mod rc; + +use crate::budget::{DECODE_MEMORY_BUDGET, PictureShape}; +use rc::{Decoder as Rac, Encoder as RacEnc, Transitions}; + +const CONTEXT_SIZE: usize = 32; +const MAX_CONTEXT_INPUTS: usize = 5; +const MAX_CONTEXTS: u64 = 32768; + +/// Codec errors. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum Error { + /// The data ends early or its sizes do not add up. + #[error("truncated FFV1 data")] + Truncated, + /// The data is not valid FFV1. + #[error("invalid FFV1 data: {0}")] + Invalid(&'static str), + /// Valid FFV1 that this module does not decode. + #[error("unsupported FFV1 feature: {0}")] + Unsupported(&'static str), + /// A slice or the configuration record failed its CRC. + #[error("FFV1 CRC mismatch in {0}")] + Crc(&'static str), + /// The encoder was given a frame or settings it cannot encode. + #[error("invalid encoder input: {0}")] + Input(String), +} + +/// `Result` of this module. +pub type Result = std::result::Result; + +/// The colour space coded (RFC 9043 table 8). +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum Colorspace { + /// YCbCr, coded plane by plane without a pixel transform. + YCbCr, + /// RGB through the JPEG 2000 reversible colour transform, coded line by line. + Rgb, +} + +/// One frame of planar samples. +#[derive(Debug, Clone, PartialEq, Eq)] +pub struct Frame { + /// Width in pixels. + pub width: u32, + /// Height in pixels. + pub height: u32, + /// Colour space of the planes. + pub colorspace: Colorspace, + /// Bits per sample, 8 to 16. + pub bit_depth: u8, + /// log2 of the horizontal and vertical chroma subsampling (YCbCr only; 0, 0 is 4:4:4). + pub chroma_shift: (u8, u8), + /// The planes, in the order the module doc gives. + pub planes: Vec>, +} + +impl Frame { + /// Whether the planes are Y, Cb, Cr (or R, G, B) rather than Y (gray) alone, or with transparency. + fn plane_count_ok(&self) -> bool { + matches!(self.planes.len(), 1..=4) + } + + fn dims(&self, plane: usize, chroma_planes: bool) -> (usize, usize) { + plane_dims(self.width as usize, self.height as usize, self.colorspace, self.chroma_shift, plane, chroma_planes) + } +} + +/// `(width, height)` of plane `p` for a full frame (or a slice) of `w` x `h`. +fn plane_dims(w: usize, h: usize, cs: Colorspace, shift: (u8, u8), p: usize, chroma_planes: bool) -> (usize, usize) { + if cs == Colorspace::YCbCr && chroma_planes && (p == 1 || p == 2) { (w.div_ceil(1 << shift.0), h.div_ceil(1 << shift.1)) } else { (w, h) } +} + +/// One Quantization Table Set (section 4.1). +#[derive(Clone)] +struct QuantSet { + tables: Vec<[i32; 256]>, + context_count: usize, +} + +/// The parsed "Parameters" of a stream. +#[derive(Clone)] +struct Params { + coder_type: u32, + transitions: Transitions, + colorspace: Colorspace, + bits: u32, + chroma_planes: bool, + shift: (u8, u8), + extra_plane: bool, + num_h: u32, + num_v: u32, + sets: Vec, + initial_states: Vec>>, + ec: bool, + intra: bool, +} + +impl Params { + fn plane_count(&self) -> usize { + 1 + if self.chroma_planes { 2 } else { 0 } + usize::from(self.extra_plane) + } + + /// Quantization Table Set index slot of plane `p` (section 3.6). + fn qset_slot(&self, p: usize) -> usize { + match p { + 0 => 0, + 1 | 2 if self.chroma_planes => 1, + _ => 2, + } + } +} + +fn crc32(data: &[u8]) -> u32 { + // The IEEE polynomial 0x04C11DB7, initial value 0, no reflection, no final inversion. + let mut crc = 0u32; + for &b in data { + crc ^= u32::from(b) << 24; + for _ in 0..8 { + crc = if crc & 0x8000_0000 != 0 { crc << 1 ^ 0x04C1_1DB7 } else { crc << 1 }; + } + } + crc +} + +// ---- Parameters ---- + +fn read_quant_set(rac: &mut Rac, t: &Transitions) -> Result { + let mut scale: u64 = 1; + let mut tables = Vec::with_capacity(MAX_CONTEXT_INPUTS); + for _ in 0..MAX_CONTEXT_INPUTS { + let mut table = [0i32; 256]; + // Each quantization table starts from fresh states. + let mut state = [128u8; CONTEXT_SIZE]; + let mut v: i64 = 0; + let mut k = 0usize; + while k < 128 { + let len = rac.symbol(&mut state, false, t) as usize + 1; + if k + len > 128 { + return Err(Error::Invalid("quantization table run passes its half")); + } + for _ in 0..len { + table[k] = i32::try_from(scale as i64 * v).map_err(|_| Error::Invalid("quantization table overflows"))?; + k += 1; + } + v += 1; + } + for k in 1..128 { + table[256 - k] = -table[k]; + } + table[128] = -table[127]; + tables.push(table); + scale = scale.checked_mul(2 * v as u64 - 1).filter(|&s| s <= 2 * MAX_CONTEXTS).ok_or(Error::Invalid("too many contexts"))?; + } + let context_count = scale.div_ceil(2); + if context_count > MAX_CONTEXTS { + return Err(Error::Invalid("too many contexts")); + } + Ok(QuantSet { tables, context_count: context_count as usize }) +} + +fn parse_params(rac: &mut Rac) -> Result { + let mut state = [128u8; CONTEXT_SIZE]; + // Until the custom table is known, the default table decodes the fields before it. + let t0 = Transitions::default_table(); + let version = rac.symbol(&mut state, false, &t0); + if version != 3 { + return Err(Error::Unsupported("only FFV1 version 3 has a configuration record; versions 0 and 1 are not supported")); + } + let _micro = rac.symbol(&mut state, false, &t0); + let coder_type = rac.symbol(&mut state, false, &t0) as u32; + let mut delta = [0i32; 256]; + if coder_type > 1 { + for d in delta.iter_mut().skip(1) { + *d = rac.symbol(&mut state, true, &t0); + } + } + let transitions = Transitions::new(&delta); + if coder_type == 0 { + return Err(Error::Unsupported("the Golomb-Rice coder (coder_type 0)")); + } + if coder_type > 2 { + return Err(Error::Invalid("unknown coder_type")); + } + let colorspace = match rac.symbol(&mut state, false, &t0) { + 0 => Colorspace::YCbCr, + 1 => Colorspace::Rgb, + _ => return Err(Error::Unsupported("colorspace_type")), + }; + let bits = rac.symbol(&mut state, false, &t0) as u32; + let bits = if bits == 0 { 8 } else { bits }; + let chroma_planes = rac.bit(&mut state[0], &t0); + let (h, v) = (rac.symbol(&mut state, false, &t0), rac.symbol(&mut state, false, &t0)); + let extra_plane = rac.bit(&mut state[0], &t0); + let num_h = rac.symbol(&mut state, false, &t0) as u32 + 1; + let num_v = rac.symbol(&mut state, false, &t0) as u32 + 1; + let set_count = rac.symbol(&mut state, false, &t0); + if !(8..=16).contains(&bits) || h > 3 || v > 3 || h < 0 || v < 0 || num_h > 1024 || num_v > 1024 || !(1..=8).contains(&set_count) { + return Err(Error::Invalid("parameter out of range")); + } + if colorspace == Colorspace::Rgb && (!chroma_planes || h != 0 || v != 0) { + return Err(Error::Unsupported("RGB with chroma_planes 0 or subsampling")); + } + let mut sets = Vec::new(); + for _ in 0..set_count { + // The Parameters are range coded with the default table; the custom one is for the slices. + sets.push(read_quant_set(rac, &t0)?); + } + let mut initial_states = Vec::new(); + for set in &sets { + if rac.bit(&mut state[0], &t0) { + let mut all = Vec::with_capacity(set.context_count); + let mut prev = [128u8; CONTEXT_SIZE]; + for _ in 0..set.context_count { + let mut cur = [0u8; CONTEXT_SIZE]; + for k in 0..CONTEXT_SIZE { + let d = rac.symbol(&mut state, true, &t0); + cur[k] = (i32::from(prev[k]) + d) as u8; + } + prev = cur; + all.push(cur); + } + initial_states.push(Some(all)); + } else { + initial_states.push(None); + } + } + let ec = rac.symbol(&mut state, false, &t0) != 0; + let intra = rac.symbol(&mut state, false, &t0) != 0; + Ok(Params { + coder_type, + transitions, + colorspace, + bits, + chroma_planes, + shift: (h as u8, v as u8), + extra_plane, + num_h, + num_v, + sets, + initial_states, + ec, + intra, + }) +} + +/// The default quantisation tables of this encoder: 11 levels for the two gradients next to the +/// sample and 5 for the other three, which makes 15125 contexts (FFmpeg refuses more than 32768). +fn default_quant_set() -> QuantSet { + // |difference| thresholds: the first |d| of each level above 0 (levels 0..=5 and 0..=2). + let first_of_level: [&[usize]; MAX_CONTEXT_INPUTS] = [&[1, 2, 4, 8, 16], &[1, 2, 4, 8, 16], &[1, 3], &[1, 3], &[1, 3]]; + let mut scale: i32 = 1; + let mut tables = Vec::new(); + let mut counts = [0usize; MAX_CONTEXT_INPUTS]; + for (j, firsts) in first_of_level.iter().enumerate() { + let mut table = [0i32; 256]; + for (k, slot) in table.iter_mut().take(128).enumerate() { + let level = firsts.iter().filter(|&&f| k >= f).count() as i32; + *slot = scale * level; + } + for k in 1..128 { + table[256 - k] = -table[k]; + } + table[128] = -table[127]; + counts[j] = firsts.len() + 1; + scale *= 2 * counts[j] as i32 - 1; + tables.push(table); + } + QuantSet { tables, context_count: (scale as usize).div_ceil(2) } +} + +/// Run lengths (`len - 1` per step) that describe the first half of a table, as written to the stream. +fn quant_runs(table: &[i32; 256]) -> Vec { + let mut runs = Vec::new(); + let mut k = 0usize; + while k < 128 { + let start = k; + while k < 128 && table[k] == table[start] { + k += 1; + } + runs.push((k - start) as i32 - 1); + } + runs +} + +fn write_params(enc: &mut RacEnc, p: &Params) { + let t = Transitions::default_table(); + let mut state = [128u8; CONTEXT_SIZE]; + enc.symbol(&mut state, 3, false, &t); // version + enc.symbol(&mut state, 4, false, &t); // micro_version: first stable variant + enc.symbol(&mut state, p.coder_type as i32, false, &t); + enc.symbol(&mut state, if p.colorspace == Colorspace::YCbCr { 0 } else { 1 }, false, &t); + enc.symbol(&mut state, p.bits as i32, false, &t); + enc.bit(p.chroma_planes, &mut state[0], &t); + enc.symbol(&mut state, i32::from(p.shift.0), false, &t); + enc.symbol(&mut state, i32::from(p.shift.1), false, &t); + enc.bit(p.extra_plane, &mut state[0], &t); + enc.symbol(&mut state, p.num_h as i32 - 1, false, &t); + enc.symbol(&mut state, p.num_v as i32 - 1, false, &t); + enc.symbol(&mut state, p.sets.len() as i32, false, &t); + for set in &p.sets { + for table in &set.tables { + let mut qstate = [128u8; CONTEXT_SIZE]; + for run in quant_runs(table) { + enc.symbol(&mut qstate, run, false, &t); + } + } + } + for _ in &p.sets { + enc.bit(false, &mut state[0], &t); // states_coded + } + enc.symbol(&mut state, i32::from(p.ec), false, &t); + enc.symbol(&mut state, i32::from(p.intra), false, &t); +} + +// ---- slices ---- + +/// A slice's place in the frame, in pixels. +#[derive(Clone, Copy)] +struct SliceRect { + x: usize, + y: usize, + w: usize, + h: usize, +} + +fn slice_rect(p: &Params, width: usize, height: usize, sx: usize, sy: usize, sw: usize, sh: usize) -> Result { + let (nh, nv) = (p.num_h as usize, p.num_v as usize); + if sx + sw > nh || sy + sh > nv || sw == 0 || sh == 0 { + return Err(Error::Invalid("slice outside the slice raster")); + } + let x0 = sx * width / nh; + let x1 = (sx + sw) * width / nh; + let y0 = sy * height / nv; + let y1 = (sy + sh) * height / nv; + if x1 <= x0 || y1 <= y0 { + return Err(Error::Invalid("empty slice")); + } + Ok(SliceRect { x: x0, y: y0, w: x1 - x0, h: y1 - y0 }) +} + +/// The samples of one plane of a slice with the border of RFC 9043 section 3.1 around them: two +/// columns to the left, one to the right, two rows above. +struct Border { + buf: Vec, + stride: usize, + w: usize, +} + +impl Border { + fn new(w: usize, h: usize) -> Border { + let stride = w + 3; + Border { buf: vec![0; stride * (h + 2)], stride, w } + } + + fn at(&self, x: usize, y: usize) -> usize { + (y + 2) * self.stride + x + 2 + } + + /// Set up the left border of row `y` (the column left of it repeats the row above's first sample). + fn start_row(&mut self, y: usize) { + let row = (y + 2) * self.stride; + self.buf[row] = 0; + self.buf[row + 1] = if y > 0 { self.buf[(y + 1) * self.stride + 2] } else { 0 }; + } + + /// The right border of row `y` repeats its last sample. + fn end_row(&mut self, y: usize) { + let row = (y + 2) * self.stride; + self.buf[row + self.w + 2] = self.buf[row + self.w + 1]; + } + + /// `(context, predictor)` for sample `(x, y)`; `context` is signed (section 3.5). + fn context(&self, x: usize, y: usize, tables: &[[i32; 256]], sixteen_bit_ycbcr: bool) -> (i32, i32) { + let i = self.at(x, y); + let (b, s) = (&self.buf, self.stride); + let (l, ll, t, tl, tr, tt) = (b[i - 1], b[i - 2], b[i - s], b[i - s - 1], b[i - s + 1], b[i - 2 * s]); + let ctx = tables[0][((l - tl) & 255) as usize] + + tables[1][((tl - t) & 255) as usize] + + tables[2][((t - tr) & 255) as usize] + + tables[3][((ll - l) & 255) as usize] + + tables[4][((tt - t) & 255) as usize]; + let (pl, pt, ptl) = if sixteen_bit_ycbcr { + let s16 = |v: i32| if v >= 32768 { v - 65536 } else { v }; + (s16(l), s16(t), s16(tl)) + } else { + (l, t, tl) + }; + (ctx, median(pl, pt, pl + pt - ptl)) + } +} + +fn median(a: i32, b: i32, c: i32) -> i32 { + a.max(b).min(a.min(b).max(c)) +} + +/// The reversible colour transform bits: a plane's samples have `bits + 1` bits. +fn rct_swapped(p: &Params) -> bool { + p.colorspace == Colorspace::Rgb && (9..=15).contains(&p.bits) && !p.extra_plane +} + +fn coded_bits(p: &Params) -> u32 { + if p.colorspace == Colorspace::Rgb { p.bits + 1 } else { p.bits } +} + +/// One plane's samples inside a slice, and which class of states codes them. +struct PlaneCoder { + border: Border, + slot: usize, +} + +/// The adaptive states of one plane class: Y, Cb and Cr together, then transparency (section 3.6). +struct ClassStates { + set: usize, + states: Vec<[u8; CONTEXT_SIZE]>, +} + +fn make_coders(p: &Params, rect: SliceRect, set_idx: &[usize]) -> Result<(Vec, Vec)> { + let mut planes = Vec::new(); + for pl in 0..p.plane_count() { + let (w, h) = plane_dims(rect.w, rect.h, p.colorspace, p.shift, pl, p.chroma_planes); + planes.push(PlaneCoder { border: Border::new(w, h), slot: p.qset_slot(pl) }); + } + let mut classes = Vec::new(); + for slot in 0..=planes.iter().map(|c| c.slot).max().unwrap_or(0) { + let set = *set_idx.get(slot).ok_or(Error::Invalid("missing quant table set index"))?; + let q = p.sets.get(set).ok_or(Error::Invalid("quant table set index out of range"))?; + let states = match p.initial_states.get(set) { + Some(Some(init)) => init.clone(), + _ => vec![[128u8; CONTEXT_SIZE]; q.context_count], + }; + classes.push(ClassStates { set, states }); + } + Ok((planes, classes)) +} + +/// The number of Quantization Table Set indexes in a slice header (section 4.6.5, version 3). +fn set_index_count(p: &Params) -> usize { + 2 + usize::from(p.extra_plane) +} + +fn check_frame_size(p: &Params, w: u32, h: u32) -> Result<()> { + if w == 0 || h == 0 { + return Err(Error::Invalid("empty frame")); + } + let shape = PictureShape { + width: u64::from(w), + height: u64::from(h), + shift_x: u32::from(p.shift.0.min(1)), + shift_y: u32::from(p.shift.1.min(1)), + chroma_planes: if p.chroma_planes { 2 } else { 0 }, + bytes_per_sample: 2, + }; + // The decoded planes and, while a slice decodes, its bordered `i32` copy (2 x the samples at most). + if !shape.fits(5, DECODE_MEMORY_BUDGET) { + return Err(Error::Unsupported("frame size above the memory budget")); + } + if p.shift.0 > 1 || p.shift.1 > 1 { + // Subsampling beyond 2:1 is legal FFV1 (e.g. 4:1:1) but the budget model above is for 2:1. + let extra = (w as u64).checked_mul(h as u64).ok_or(Error::Invalid("frame too large"))?; + if extra > 1 << 28 { + return Err(Error::Unsupported("frame size above the memory budget")); + } + } + Ok(()) +} + +/// A decoder for one stream. +pub struct Decoder { + params: Params, + width: u32, + height: u32, +} + +impl Decoder { + /// Build a decoder from the container's configuration record and the frame size. + pub fn new(config_record: &[u8], width: u32, height: u32) -> Result { + if config_record.len() < 5 { + return Err(Error::Truncated); + } + let (body, _crc) = config_record.split_at(config_record.len() - 4); + if crc32(config_record) != 0 { + return Err(Error::Crc("the configuration record")); + } + let mut rac = Rac::new(body); + let params = parse_params(&mut rac)?; + if rac.consumed() > body.len() + 2 { + return Err(Error::Truncated); + } + check_frame_size(¶ms, width, height)?; + Ok(Decoder { params, width, height }) + } + + /// Decode one frame (a packet from the container). + pub fn decode(&self, packet: &[u8]) -> Result { + let p = &self.params; + let (w, h) = (self.width as usize, self.height as usize); + let planes = p.plane_count(); + let mut frame = Frame { + width: self.width, + height: self.height, + colorspace: p.colorspace, + bit_depth: p.bits as u8, + chroma_shift: if p.chroma_planes { p.shift } else { (0, 0) }, + planes: Vec::with_capacity(planes), + }; + for pl in 0..planes { + let (pw, ph) = plane_dims(w, h, p.colorspace, p.shift, pl, p.chroma_planes); + let mut v = Vec::new(); + v.try_reserve_exact(pw * ph).map_err(|_| Error::Unsupported("frame size above the memory budget"))?; + v.resize(pw * ph, 0u16); + frame.planes.push(v); + } + // Slices are found from the end of the packet through their footers (section 4.9). + let trailer = if p.ec { 8 } else { 3 }; + let slice_count = p.num_h as usize * p.num_v as usize; + let mut end = packet.len(); + let mut spans = Vec::with_capacity(slice_count); + for _ in 0..slice_count { + if end < trailer { + return Err(Error::Truncated); + } + let f = end - trailer; + let size = usize::from(packet[f]) << 16 | usize::from(packet[f + 1]) << 8 | usize::from(packet[f + 2]); + let start = f.checked_sub(size).ok_or(Error::Truncated)?; + spans.push((start, end)); + end = start; + } + spans.reverse(); + for (n, &(start, stop)) in spans.iter().enumerate() { + let slice = &packet[start..stop]; + if p.ec && crc32(slice) != 0 { + return Err(Error::Crc("a slice")); + } + self.decode_slice(slice, n == 0, &mut frame)?; + } + Ok(frame) + } + + fn decode_slice(&self, slice: &[u8], first: bool, frame: &mut Frame) -> Result<()> { + let p = &self.params; + let t = &p.transitions; + let data = &slice[..slice.len() - if p.ec { 8 } else { 3 }]; + let mut rac = Rac::new(data); + // The keyframe flag is the first symbol of the first slice. + // The whole slice, header included, is coded with the stream's state transition table. + let t0 = t; + if first { + let mut ks = 128u8; + if !rac.bit(&mut ks, t0) { + return Err(Error::Unsupported("inter frames (keyframe 0)")); + } + } + let mut hs = [128u8; CONTEXT_SIZE]; + let sx = rac.symbol(&mut hs, false, t0) as usize; + let sy = rac.symbol(&mut hs, false, t0) as usize; + let sw = rac.symbol(&mut hs, false, t0) as usize + 1; + let sh = rac.symbol(&mut hs, false, t0) as usize + 1; + let set_idx: Vec = (0..set_index_count(p)).map(|_| rac.symbol(&mut hs, false, t0).max(0) as usize).collect(); + let _picture_structure = rac.symbol(&mut hs, false, t0); + let _sar = (rac.symbol(&mut hs, false, t0), rac.symbol(&mut hs, false, t0)); + let rect = slice_rect(p, self.width as usize, self.height as usize, sx, sy, sw, sh)?; + let (sx_mask, sy_mask) = ((1usize << p.shift.0) - 1, (1usize << p.shift.1) - 1); + if p.colorspace == Colorspace::YCbCr && p.chroma_planes && (rect.x & sx_mask != 0 || rect.y & sy_mask != 0) { + return Err(Error::Unsupported("slice boundaries that are not multiples of the chroma subsampling")); + } + let (mut coders, mut classes) = make_coders(p, rect, &set_idx)?; + let bits = coded_bits(p); + let mask = (1i32 << bits) - 1; + let sixteen = p.colorspace == Colorspace::YCbCr && p.bits == 16; + let read = |rac: &mut Rac, c: &mut PlaneCoder, cls: &mut ClassStates, x: usize, y: usize| -> i32 { + let q = &p.sets[cls.set]; + let (ctx, pred) = c.border.context(x, y, &q.tables, sixteen); + let (idx, neg) = if ctx < 0 { ((-ctx) as usize, true) } else { (ctx as usize, false) }; + let mut d = rac.symbol(&mut cls.states[idx.min(q.context_count - 1)], true, t); + if neg { + d = -d; + } + let v = (pred + d) & mask; + let at = c.border.at(x, y); + c.border.buf[at] = v; + v + }; + match p.colorspace { + Colorspace::YCbCr => { + for (pl, c) in coders.iter_mut().enumerate() { + let (pw, ph) = plane_dims(rect.w, rect.h, p.colorspace, p.shift, pl, p.chroma_planes); + for y in 0..ph { + c.border.start_row(y); + for x in 0..pw { + read(&mut rac, c, &mut classes[c.slot], x, y); + } + c.border.end_row(y); + } + } + } + Colorspace::Rgb => { + for y in 0..rect.h { + for c in coders.iter_mut() { + c.border.start_row(y); + for x in 0..rect.w { + read(&mut rac, c, &mut classes[c.slot], x, y); + } + c.border.end_row(y); + } + } + } + } + self.store(&coders, rect, frame); + Ok(()) + } + + /// Copy a decoded slice into the frame, undoing the colour transform for RGB. + fn store(&self, coders: &[PlaneCoder], rect: SliceRect, frame: &mut Frame) { + let p = &self.params; + if p.colorspace == Colorspace::YCbCr { + for (pl, c) in coders.iter().enumerate() { + let (pw, ph) = plane_dims(rect.w, rect.h, p.colorspace, p.shift, pl, p.chroma_planes); + let (fw, _) = plane_dims(self.width as usize, self.height as usize, p.colorspace, p.shift, pl, p.chroma_planes); + let (ox, oy) = if p.chroma_planes && (pl == 1 || pl == 2) { (rect.x >> p.shift.0, rect.y >> p.shift.1) } else { (rect.x, rect.y) }; + for y in 0..ph { + for x in 0..pw { + frame.planes[pl][(oy + y) * fw + ox + x] = c.border.buf[c.border.at(x, y)] as u16; + } + } + } + return; + } + let swapped = rct_swapped(p); + let off = 1i32 << p.bits; + let fw = self.width as usize; + for y in 0..rect.h { + for x in 0..rect.w { + let get = |i: usize| coders[i].border.buf[coders[i].border.at(x, y)]; + let (yy, cb, cr) = (get(0), get(1) - off, get(2) - off); + let (r, g, b); + if swapped { + let bb = yy - ((cb + cr) >> 2); + r = cr + bb; + g = cb + bb; + b = bb; + } else { + let gg = yy - ((cb + cr) >> 2); + r = cr + gg; + g = gg; + b = cb + gg; + } + let at = (rect.y + y) * fw + rect.x + x; + frame.planes[0][at] = r as u16; + frame.planes[1][at] = g as u16; + frame.planes[2][at] = b as u16; + if coders.len() > 3 { + frame.planes[3][at] = get(3) as u16; + } + } + } + } +} + +/// Encoder settings. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct EncoderConfig { + /// Slices across the frame. + pub slices_h: u32, + /// Slices down the frame. + pub slices_v: u32, + /// Write a CRC in every slice (error detection). + pub slice_crc: bool, +} + +impl Default for EncoderConfig { + fn default() -> Self { + EncoderConfig { slices_h: 1, slices_v: 1, slice_crc: true } + } +} + +/// An encoder for frames of one fixed format. +pub struct Encoder { + params: Params, + width: u32, + height: u32, +} + +impl Encoder { + /// An encoder for frames shaped like `template` (its samples are not used). + pub fn new(template: &Frame, cfg: EncoderConfig) -> Result { + if !template.plane_count_ok() || template.width == 0 || template.height == 0 { + return Err(Error::Input("a frame has 1 to 4 planes and a nonzero size".into())); + } + if !(8..=16).contains(&template.bit_depth) { + return Err(Error::Input("bit depth must be 8 to 16".into())); + } + if cfg.slices_h == 0 + || cfg.slices_v == 0 + || cfg.slices_h > 1024 + || cfg.slices_v > 1024 + || cfg.slices_h > template.width + || cfg.slices_v > template.height + { + return Err(Error::Input("invalid slice raster".into())); + } + let n = template.planes.len(); + let (chroma_planes, extra_plane) = match (template.colorspace, n) { + (Colorspace::YCbCr, 1) => (false, false), + (Colorspace::YCbCr, 2) => (false, true), + (Colorspace::YCbCr, 3) => (true, false), + (Colorspace::YCbCr, _) => (true, true), + (Colorspace::Rgb, 3) => (true, false), + (Colorspace::Rgb, 4) => (true, true), + (Colorspace::Rgb, _) => return Err(Error::Input("RGB frames have 3 or 4 planes".into())), + }; + let shift = if template.colorspace == Colorspace::YCbCr && chroma_planes { template.chroma_shift } else { (0, 0) }; + if shift.0 > 3 || shift.1 > 3 { + return Err(Error::Input("chroma subsampling above 8:1".into())); + } + if template.colorspace == Colorspace::Rgb && template.bit_depth > 15 { + return Err(Error::Input("RGB above 15 bits needs 17-bit coded samples".into())); + } + let params = Params { + coder_type: 1, + transitions: Transitions::default_table(), + colorspace: template.colorspace, + bits: u32::from(template.bit_depth), + chroma_planes, + shift, + extra_plane, + num_h: cfg.slices_h, + num_v: cfg.slices_v, + sets: vec![default_quant_set()], + initial_states: vec![None], + ec: cfg.slice_crc, + intra: true, + }; + // Every slice boundary must be a multiple of the chroma subsampling, so the decoder accepts it. + for i in 0..=cfg.slices_h as usize { + if params.chroma_planes && (i * template.width as usize / cfg.slices_h as usize) & ((1 << shift.0) - 1) != 0 && i != cfg.slices_h as usize + { + return Err(Error::Input("slice boundaries must be multiples of the chroma subsampling".into())); + } + } + for i in 0..cfg.slices_v as usize { + if params.chroma_planes && (i * template.height as usize / cfg.slices_v as usize) & ((1 << shift.1) - 1) != 0 { + return Err(Error::Input("slice boundaries must be multiples of the chroma subsampling".into())); + } + } + Ok(Encoder { params, width: template.width, height: template.height }) + } + + /// The configuration record for the container (`CodecPrivate` and the like). + pub fn config_record(&self) -> Vec { + let mut enc = RacEnc::new(); + write_params(&mut enc, &self.params); + let mut out = enc.finish(); + let crc = crc32(&out); + out.extend_from_slice(&crc.to_be_bytes()); + out + } + + /// Encode one frame as a keyframe packet. + pub fn encode(&self, frame: &Frame) -> Result> { + let p = &self.params; + if frame.width != self.width || frame.height != self.height || frame.colorspace != p.colorspace || u32::from(frame.bit_depth) != p.bits { + return Err(Error::Input("the frame does not match the encoder's format".into())); + } + if frame.planes.len() != p.plane_count() { + return Err(Error::Input("the frame has the wrong number of planes".into())); + } + let shift = if p.chroma_planes { p.shift } else { (0, 0) }; + if p.colorspace == Colorspace::YCbCr && p.chroma_planes && frame.chroma_shift != shift { + return Err(Error::Input("the chroma subsampling does not match".into())); + } + for (pl, plane) in frame.planes.iter().enumerate() { + let (w, h) = frame.dims(pl, p.chroma_planes); + if plane.len() != w * h { + return Err(Error::Input(format!("plane {pl} has {} samples, expected {}", plane.len(), w * h))); + } + if plane.iter().any(|&v| u32::from(v) >> p.bits != 0) { + return Err(Error::Input(format!("plane {pl} has a sample above {} bits", p.bits))); + } + } + let mut out = Vec::new(); + for sy in 0..p.num_v as usize { + for sx in 0..p.num_h as usize { + let rect = slice_rect(p, self.width as usize, self.height as usize, sx, sy, 1, 1)?; + let mut slice = self.encode_slice(frame, rect, sx, sy, out.is_empty())?; + let size = slice.len(); + slice.extend_from_slice(&(size as u32).to_be_bytes()[1..]); + if p.ec { + slice.push(0); // error_status + let crc = crc32(&slice); + slice.extend_from_slice(&crc.to_be_bytes()); + } + out.extend_from_slice(&slice); + } + } + Ok(out) + } + + fn encode_slice(&self, frame: &Frame, rect: SliceRect, sx: usize, sy: usize, first: bool) -> Result> { + let p = &self.params; + let t = &p.transitions; + let t0 = t; + let mut rac = RacEnc::new(); + if first { + let mut ks = 128u8; + rac.bit(true, &mut ks, t0); + } + let mut hs = [128u8; CONTEXT_SIZE]; + for v in [sx as i32, sy as i32, 0, 0] { + rac.symbol(&mut hs, v, false, t0); + } + let set_idx = vec![0usize; set_index_count(p)]; + for &s in &set_idx { + rac.symbol(&mut hs, s as i32, false, t0); + } + for v in [0, 0, 0] { + rac.symbol(&mut hs, v, false, t0); // picture_structure, sar_num, sar_den + } + let (mut coders, mut classes) = make_coders(p, rect, &set_idx)?; + let bits = coded_bits(p); + let half = 1i32 << (bits - 1); + let mask = (1i32 << bits) - 1; + let sixteen = p.colorspace == Colorspace::YCbCr && p.bits == 16; + // The samples to code, one bordered plane's worth per coder. + let values = self.slice_values(frame, rect); + let write = |rac: &mut RacEnc, c: &mut PlaneCoder, cls: &mut ClassStates, x: usize, y: usize, sample: i32| { + let q = &p.sets[cls.set]; + let (ctx, pred) = c.border.context(x, y, &q.tables, sixteen); + let mut d = ((sample - pred + half) & mask) - half; + let (idx, neg) = if ctx < 0 { ((-ctx) as usize, true) } else { (ctx as usize, false) }; + if neg { + d = -d; + } + rac.symbol(&mut cls.states[idx.min(q.context_count - 1)], d, true, t); + let at = c.border.at(x, y); + c.border.buf[at] = sample; + }; + match p.colorspace { + Colorspace::YCbCr => { + for (pl, c) in coders.iter_mut().enumerate() { + let (pw, ph) = plane_dims(rect.w, rect.h, p.colorspace, p.shift, pl, p.chroma_planes); + for y in 0..ph { + c.border.start_row(y); + for x in 0..pw { + write(&mut rac, c, &mut classes[c.slot], x, y, values[pl][y * pw + x]); + } + c.border.end_row(y); + } + } + } + Colorspace::Rgb => { + for y in 0..rect.h { + for (pl, c) in coders.iter_mut().enumerate() { + c.border.start_row(y); + for x in 0..rect.w { + write(&mut rac, c, &mut classes[c.slot], x, y, values[pl][y * rect.w + x]); + } + c.border.end_row(y); + } + } + } + } + Ok(rac.finish()) + } + + /// The slice's samples per coded plane (after the colour transform for RGB). + fn slice_values(&self, frame: &Frame, rect: SliceRect) -> Vec> { + let p = &self.params; + let fw = self.width as usize; + if p.colorspace == Colorspace::YCbCr { + return (0..p.plane_count()) + .map(|pl| { + let (pw, ph) = plane_dims(rect.w, rect.h, p.colorspace, p.shift, pl, p.chroma_planes); + let (full_w, _) = plane_dims(fw, self.height as usize, p.colorspace, p.shift, pl, p.chroma_planes); + let (ox, oy) = + if p.chroma_planes && (pl == 1 || pl == 2) { (rect.x >> p.shift.0, rect.y >> p.shift.1) } else { (rect.x, rect.y) }; + let mut v = Vec::with_capacity(pw * ph); + for y in 0..ph { + for x in 0..pw { + v.push(i32::from(frame.planes[pl][(oy + y) * full_w + ox + x])); + } + } + v + }) + .collect(); + } + let swapped = rct_swapped(p); + let off = 1i32 << p.bits; + let mut planes = vec![Vec::with_capacity(rect.w * rect.h); p.plane_count()]; + for y in 0..rect.h { + for x in 0..rect.w { + let at = (rect.y + y) * fw + rect.x + x; + let (r, g, b) = (i32::from(frame.planes[0][at]), i32::from(frame.planes[1][at]), i32::from(frame.planes[2][at])); + let (yy, cb, cr) = if swapped { + let (cb, cr) = (g - b, r - b); + (b + ((cb + cr) >> 2), cb, cr) + } else { + let (cb, cr) = (b - g, r - g); + (g + ((cb + cr) >> 2), cb, cr) + }; + planes[0].push(yy); + planes[1].push(cb + off); + planes[2].push(cr + off); + if p.extra_plane { + planes[3].push(i32::from(frame.planes[3][at])); + } + } + } + planes + } +} diff --git a/crates/video/src/ffv1/rc.rs b/crates/video/src/ffv1/rc.rs new file mode 100644 index 000000000..fa2a16ee4 --- /dev/null +++ b/crates/video/src/ffv1/rc.rs @@ -0,0 +1,229 @@ +//! The FFV1 range coder (RFC 9043 section 3.8.1): binary decisions with adaptive 8-bit states, +//! and the signed/unsigned integer coding built on them. + +/// RFC 9043 Figure 24: the default state transition table for a coded 1. +const DEFAULT_ONE_STATE: [u8; 256] = [ + 0, 0, 0, 0, 0, 0, 0, 0, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, + 49, 50, 51, 52, 53, 54, 55, 56, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 75, 76, 77, 78, 79, 80, 81, 82, + 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, + 114, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 133, 134, 135, 136, 137, 138, 139, 140, + 141, 142, 143, 144, 145, 146, 147, 148, 149, 150, 151, 152, 152, 153, 154, 155, 156, 157, 158, 159, 160, 161, 162, 163, 164, 165, 166, 167, 168, + 169, 170, 171, 171, 172, 173, 174, 175, 176, 177, 178, 179, 180, 181, 182, 183, 184, 185, 186, 187, 188, 189, 190, 190, 191, 192, 194, 194, 195, + 196, 197, 198, 199, 200, 201, 202, 202, 204, 205, 206, 207, 208, 209, 209, 210, 211, 212, 213, 215, 215, 216, 217, 218, 219, 220, 220, 222, 223, + 224, 225, 226, 227, 227, 229, 229, 230, 231, 232, 234, 234, 235, 236, 237, 238, 239, 240, 241, 242, 243, 244, 245, 246, 247, 248, 248, 0, 0, 0, + 0, 0, 0, 0, +]; + +/// The state machine: the next state after a coded 0 or 1. +#[derive(Clone)] +pub(crate) struct Transitions { + one: [u8; 256], + zero: [u8; 256], +} + +impl Transitions { + /// The default table plus `delta` (`state_transition_delta`, indexed 1 to 255). + pub(crate) fn new(delta: &[i32; 256]) -> Transitions { + let mut one = [0u8; 256]; + for (i, o) in one.iter_mut().enumerate() { + *o = (i32::from(DEFAULT_ONE_STATE[i]) + delta[i]) as u8; + } + let mut zero = [0u8; 256]; + for i in 1..256 { + zero[i] = (256 - i32::from(one[256 - i])) as u8; + } + Transitions { one, zero } + } + + pub(crate) fn default_table() -> Transitions { + Transitions::new(&[0; 256]) + } +} + +/// Reads binary decisions from `data`; bytes past its end read as 0 (the "Closed" mode of 3.8.1.1.1). +pub(crate) struct Decoder<'a> { + data: &'a [u8], + pos: usize, + low: u32, + range: u32, +} + +impl<'a> Decoder<'a> { + pub(crate) fn new(data: &'a [u8]) -> Decoder<'a> { + let b0 = u32::from(data.first().copied().unwrap_or(0)); + let b1 = u32::from(data.get(1).copied().unwrap_or(0)); + let mut low = b0 << 8 | b1; + let range = 0xFF00; + if low >= range { + low = range; + } + Decoder { data, pos: 2, low, range } + } + + /// Bytes the coder has read so far. + pub(crate) fn consumed(&self) -> usize { + self.pos + } + + fn refill(&mut self) { + if self.range < 256 { + self.range <<= 8; + self.low <<= 8; + self.low += u32::from(self.data.get(self.pos).copied().unwrap_or(0)); + self.pos += 1; + } + } + + pub(crate) fn bit(&mut self, state: &mut u8, t: &Transitions) -> bool { + let off = (self.range * u32::from(*state)) >> 8; + self.range -= off; + if self.low < self.range { + *state = t.zero[usize::from(*state)]; + self.refill(); + false + } else { + self.low -= self.range; + *state = t.one[usize::from(*state)]; + self.range = off; + self.refill(); + true + } + } + + /// RFC 9043 Figure 21: `get_symbol`. + pub(crate) fn symbol(&mut self, state: &mut [u8; 32], signed: bool, t: &Transitions) -> i32 { + if self.bit(&mut state[0], t) { + return 0; + } + let mut e = 0usize; + while self.bit(&mut state[1 + e.min(9)], t) { + e += 1; + if e > 24 { + // No valid stream codes a magnitude this large; stop instead of spinning on garbage. + return 0; + } + } + let mut a = 1i32; + for i in (0..e).rev() { + a = a * 2 + i32::from(self.bit(&mut state[22 + i.min(9)], t)); + } + if signed && self.bit(&mut state[11 + e.min(10)], t) { -a } else { a } + } +} + +/// Writes binary decisions; the inverse of [`Decoder`]. +pub(crate) struct Encoder { + out: Vec, + low: u32, + range: u32, +} + +impl Encoder { + pub(crate) fn new() -> Encoder { + Encoder { out: Vec::new(), low: 0, range: 0xFF00 } + } + + fn shift(&mut self) { + while self.range < 256 { + // Bits 15..8 of `low` are final once a carry (bit 16) is added to the bytes before them. + let carry = self.low >> 16; + let byte = ((self.low >> 8) & 0xFF) as u8; + if carry != 0 { + for b in self.out.iter_mut().rev() { + let (v, over) = b.overflowing_add(1); + *b = v; + if !over { + break; + } + } + } + self.out.push(byte); + self.low = (self.low & 0xFF) << 8; + self.range <<= 8; + } + } + + pub(crate) fn bit(&mut self, bit: bool, state: &mut u8, t: &Transitions) { + let off = (self.range * u32::from(*state)) >> 8; + if bit { + self.low += self.range - off; + self.range = off; + *state = t.one[usize::from(*state)]; + } else { + self.range -= off; + *state = t.zero[usize::from(*state)]; + } + self.shift(); + } + + pub(crate) fn symbol(&mut self, state: &mut [u8; 32], v: i32, signed: bool, t: &Transitions) { + if v == 0 { + self.bit(true, &mut state[0], t); + return; + } + self.bit(false, &mut state[0], t); + let a = v.unsigned_abs(); + let e = (31 - a.leading_zeros()) as usize; + for i in 0..e { + self.bit(true, &mut state[1 + i.min(9)], t); + } + self.bit(false, &mut state[1 + e.min(9)], t); + for i in (0..e).rev() { + self.bit((a >> i) & 1 == 1, &mut state[22 + i.min(9)], t); + } + if signed { + self.bit(v < 0, &mut state[11 + e.min(10)], t); + } + } + + /// Finish the stream with the two bytes of the *top* of the final range: whatever bytes follow + /// (zeros, or a CRC in a container's configuration record) still decode inside the range. + pub(crate) fn finish(mut self) -> Vec { + self.low += self.range - 1; + let carry = self.low >> 16; + if carry != 0 { + for b in self.out.iter_mut().rev() { + let (v, over) = b.overflowing_add(1); + *b = v; + if !over { + break; + } + } + } + self.out.push(((self.low >> 8) & 0xFF) as u8); + self.out.push((self.low & 0xFF) as u8); + self.out + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn symbols_round_trip_through_the_range_coder() { + let t = Transitions::default_table(); + let values: Vec = (0..4000).map(|i| ((i * 7919) % 2001) - 1000).chain([0, 0, 0, 65535, -65535, 1, -1]).collect(); + let mut enc = Encoder::new(); + let mut st = [128u8; 32]; + for &v in &values { + enc.symbol(&mut st, v, true, &t); + } + let bytes = enc.finish(); + let mut dec = Decoder::new(&bytes); + let mut st = [128u8; 32]; + for &v in &values { + assert_eq!(dec.symbol(&mut st, true, &t), v); + } + } + + #[test] + fn transition_tables_follow_the_rfc() { + let t = Transitions::default_table(); + assert_eq!(t.one[8], 20); + assert_eq!(t.one[247], 248); + // zero_state_i = 256 - one_state_(256 - i) + assert_eq!(t.zero[128], (256 - i32::from(t.one[128])) as u8); + assert_eq!(t.zero[1], (256 - i32::from(t.one[255])) as u8); + } +} diff --git a/crates/video/src/lib.rs b/crates/video/src/lib.rs index 0d8625bbd..8202a93f8 100644 --- a/crates/video/src/lib.rs +++ b/crates/video/src/lib.rs @@ -10,6 +10,7 @@ //! | `vp8` | [`vp8`] | VP8 (RFC 6386): decoder (`vp8-decode`) and key-frame encoder (`vp8-encode`) | //! | `mpeg2` | [`mpeg2`] | MPEG-2 video (ITU-T H.262) and MPEG-1 video: decoder (`mpeg2-decode`) and MPEG-2 I/P/B encoder (`mpeg2-encode`) | //! | `mpeg4` | [`mpeg4`] | MPEG-4 Part 2 video (ISO/IEC 14496-2, Xvid/DivX): Simple profile encoder (`mpeg4-encode`) | +//! | `ffv1` | [`ffv1`] | FFV1 lossless video (RFC 9043): version 3, range coder, decoder and encoder | //! | `prores` | [`prores`] | Apple ProRes (SMPTE RDD 36): decoder and encoder | //! | `h264` | [`h264`] | ITU-T H.264 / AVC: decoder (`h264-decode`) and encoder (`h264-encode`) | //! | `hevc` | [`hevc`] | ITU-T H.265 / HEVC: decoder (`hevc-decode`) and encoder (`hevc-encode`) | @@ -41,6 +42,9 @@ pub mod mpeg2; #[cfg(feature = "mpeg4-encode")] pub mod mpeg4; +#[cfg(feature = "ffv1")] +pub mod ffv1; + #[cfg(feature = "prores")] pub mod prores; diff --git a/crates/video/tests/ffv1.rs b/crates/video/tests/ffv1.rs new file mode 100644 index 000000000..1d5c73c0b --- /dev/null +++ b/crates/video/tests/ffv1.rs @@ -0,0 +1,304 @@ +//! FFV1 tests: round trips, hostile input, and ffmpeg as the reference (oracle; skipped when ffmpeg +//! is absent, a failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`). +//! +//! - Our packets, in an AVI with our configuration record, decode in ffmpeg to our source pixels. +//! - ffmpeg's FFV1 files (version 3, range coder, several pixel formats and slice counts) decode +//! with our decoder to ffmpeg's pixels. + +use craft_media::avi::{AviWriter, MuxOptions, StreamSpec, VideoSpec}; +use craft_video::ffv1::{Colorspace, Decoder, Encoder, EncoderConfig, Error, Frame}; +use std::path::Path; +use std::process::Command; + +fn noise(seed: &mut u32, mask: u32) -> u16 { + *seed ^= *seed << 13; + *seed ^= *seed >> 17; + *seed ^= *seed << 5; + (*seed & mask) as u16 +} + +/// A frame of smooth gradients, noise bursts and flat areas. +fn frame(w: u32, h: u32, cs: Colorspace, bits: u8, shift: (u8, u8), planes: usize) -> Frame { + let max = (1u32 << bits) - 1; + let mut seed = 0x9E37_79B9u32; + let mut ps = Vec::new(); + for p in 0..planes { + let (pw, ph) = if cs == Colorspace::YCbCr && (p == 1 || p == 2) && planes >= 3 { + ((w as usize).div_ceil(1 << shift.0), (h as usize).div_ceil(1 << shift.1)) + } else { + (w as usize, h as usize) + }; + let mut v = Vec::with_capacity(pw * ph); + for y in 0..ph { + for x in 0..pw { + let s = match (y / 11 + p) % 3 { + 0 => ((x * 5 + y * 3 + p * 40) as u32 * max / 600) % (max + 1), + 1 => noise(&mut seed, max) as u32, + _ => max / 3, + }; + v.push(s as u16); + } + } + ps.push(v); + } + Frame { width: w, height: h, colorspace: cs, bit_depth: bits, chroma_shift: shift, planes: ps } +} + +fn round_trip(f: &Frame, cfg: EncoderConfig) -> Frame { + let enc = Encoder::new(f, cfg).expect("encoder"); + let config = enc.config_record(); + let packet = enc.encode(f).expect("encode"); + let dec = Decoder::new(&config, f.width, f.height).expect("decoder"); + dec.decode(&packet).expect("decode") +} + +#[test] +fn round_trips_every_shape() { + for (cs, bits, shift, planes) in [ + (Colorspace::YCbCr, 8u8, (0u8, 0u8), 1usize), + (Colorspace::YCbCr, 8, (1, 1), 3), + (Colorspace::YCbCr, 8, (1, 0), 3), + (Colorspace::YCbCr, 8, (0, 0), 4), + (Colorspace::YCbCr, 10, (1, 1), 3), + (Colorspace::YCbCr, 12, (0, 0), 3), + (Colorspace::YCbCr, 16, (1, 0), 3), + (Colorspace::YCbCr, 16, (0, 0), 1), + (Colorspace::Rgb, 8, (0, 0), 3), + (Colorspace::Rgb, 8, (0, 0), 4), + (Colorspace::Rgb, 10, (0, 0), 3), + (Colorspace::Rgb, 12, (0, 0), 4), + (Colorspace::Rgb, 15, (0, 0), 3), + ] { + for (w, h) in [(1, 1), (3, 5), (64, 48), (67, 41)] { + let f = frame(w, h, cs, bits, shift, planes); + for crc in [true, false] { + let back = round_trip(&f, EncoderConfig { slice_crc: crc, ..EncoderConfig::default() }); + assert_eq!(back.planes, f.planes, "{cs:?} {bits}-bit {shift:?} {planes} planes {w}x{h} crc={crc}"); + } + } + } +} + +#[test] +fn round_trips_with_several_slices() { + let f = frame(96, 64, Colorspace::YCbCr, 8, (1, 1), 3); + for (sh, sv) in [(2, 1), (1, 2), (3, 2), (4, 4)] { + let back = round_trip(&f, EncoderConfig { slices_h: sh, slices_v: sv, slice_crc: true }); + assert_eq!(back.planes, f.planes, "{sh}x{sv} slices"); + } + let rgb = frame(50, 30, Colorspace::Rgb, 8, (0, 0), 3); + assert_eq!(round_trip(&rgb, EncoderConfig { slices_h: 3, slices_v: 2, slice_crc: true }).planes, rgb.planes); +} + +#[test] +fn encoder_refuses_what_it_cannot_write() { + let f = frame(8, 8, Colorspace::YCbCr, 8, (1, 1), 3); + assert!(Encoder::new(&f, EncoderConfig { slices_h: 0, ..EncoderConfig::default() }).is_err()); + assert!(Encoder::new(&f, EncoderConfig { slices_h: 9, ..EncoderConfig::default() }).is_err()); + let mut bad = f.clone(); + bad.bit_depth = 7; + assert!(Encoder::new(&bad, EncoderConfig::default()).is_err()); + let mut rgb16 = frame(8, 8, Colorspace::Rgb, 8, (0, 0), 3); + rgb16.bit_depth = 16; + assert!(Encoder::new(&rgb16, EncoderConfig::default()).is_err()); + let enc = Encoder::new(&f, EncoderConfig::default()).expect("encoder"); + let mut wrong = f.clone(); + wrong.planes[1].pop(); + assert!(enc.encode(&wrong).is_err()); + let mut over = f; + over.planes[0][0] = 300; + assert!(enc.encode(&over).is_err()); +} + +#[test] +fn hostile_input_is_an_error_not_a_panic() { + let f = frame(24, 18, Colorspace::YCbCr, 8, (1, 1), 3); + let enc = Encoder::new(&f, EncoderConfig { slices_h: 2, slices_v: 1, slice_crc: true }).expect("encoder"); + let config = enc.config_record(); + let packet = enc.encode(&f).expect("encode"); + // Every truncation of the configuration record and of the packet. + for n in 0..config.len() { + let _ = Decoder::new(&config[..n], 24, 18); + } + let dec = Decoder::new(&config, 24, 18).expect("decoder"); + for n in 0..packet.len() { + let _ = dec.decode(&packet[..n]); + } + // Every single-bit flip: the CRCs catch them in a packet, and none panics. + for i in 0..packet.len() { + for bit in 0..8 { + let mut c = packet.clone(); + c[i] ^= 1 << bit; + assert!(dec.decode(&c).is_err(), "bit {bit} of byte {i} went unnoticed"); + } + } + for i in 0..config.len() { + for bit in 0..8 { + let mut c = config.clone(); + c[i] ^= 1 << bit; + assert!(matches!(Decoder::new(&c, 24, 18), Err(Error::Crc(_))), "config bit {bit} of byte {i}"); + } + } + // Without slice CRCs, flips may decode to wrong pixels but must not panic. + let enc = Encoder::new(&f, EncoderConfig { slice_crc: false, ..EncoderConfig::default() }).expect("encoder"); + let (config, packet) = (enc.config_record(), enc.encode(&f).expect("encode")); + let dec = Decoder::new(&config, 24, 18).expect("decoder"); + for i in 0..packet.len() { + for bit in 0..8 { + let mut c = packet.clone(); + c[i] ^= 1 << bit; + let _ = dec.decode(&c); + } + } + // A huge frame size is refused before any allocation. + assert!(Decoder::new(&config, u32::MAX, u32::MAX).is_err()); +} + +// ---- ffmpeg ---- + +fn ffmpeg_run(ff: &Path, args: &[&str]) -> Vec { + let out = Command::new(ff).args(["-v", "error", "-nostdin", "-y"]).args(args).output().expect("run ffmpeg"); + assert!(out.status.success(), "ffmpeg {args:?}: {}", String::from_utf8_lossy(&out.stderr)); + out.stdout +} + +fn raw_bytes(f: &Frame) -> Vec { + let mut out = Vec::new(); + for p in &f.planes { + for &v in p { + if f.bit_depth == 8 { + out.push(v as u8); + } else { + out.extend_from_slice(&v.to_le_bytes()); + } + } + } + out +} + +/// `(ffmpeg pix_fmt, colourspace, bits, chroma shift, planes)`; RGB planes are G, B, R in ffmpeg's gbrp. +type Format = (&'static str, Colorspace, u8, (u8, u8), usize); + +const FORMATS: &[Format] = &[ + ("gray", Colorspace::YCbCr, 8, (0, 0), 1), + ("yuv420p", Colorspace::YCbCr, 8, (1, 1), 3), + ("yuv422p", Colorspace::YCbCr, 8, (1, 0), 3), + ("yuv444p", Colorspace::YCbCr, 8, (0, 0), 3), + ("yuv420p10le", Colorspace::YCbCr, 10, (1, 1), 3), + ("yuv444p12le", Colorspace::YCbCr, 12, (0, 0), 3), + ("gray16le", Colorspace::YCbCr, 16, (0, 0), 1), + ("yuv444p16le", Colorspace::YCbCr, 16, (0, 0), 3), + ("gbrp", Colorspace::Rgb, 8, (0, 0), 3), + ("gbrp10le", Colorspace::Rgb, 10, (0, 0), 3), + ("gbrp12le", Colorspace::Rgb, 12, (0, 0), 3), + ("yuva444p", Colorspace::YCbCr, 8, (0, 0), 4), + ("gbrap", Colorspace::Rgb, 8, (0, 0), 4), + ("gbrap12le", Colorspace::Rgb, 12, (0, 0), 4), +]; + +/// Formats only ffmpeg writes: our encoder stops at 15-bit RGB (the transform needs 17 bits). +const DECODE_ONLY: &[Format] = &[("gbrp16le", Colorspace::Rgb, 16, (0, 0), 3), ("yuv411p", Colorspace::YCbCr, 8, (2, 0), 3)]; + +/// ffmpeg's planar RGB is G, B, R (then alpha); ours is R, G, B (then alpha). +fn gbr_order(planes: &[Vec]) -> Vec> { + let mut v = vec![planes[1].clone(), planes[2].clone(), planes[0].clone()]; + v.extend(planes[3..].iter().cloned()); + v +} + +fn avi_with(frame: &Frame, config: &[u8], packet: &[u8]) -> Vec { + let mut spec = VideoSpec::new(*b"FFV1", frame.width, frame.height, 25, 1); + spec.format.extra = config.to_vec(); + let mut w = AviWriter::new(std::io::Cursor::new(Vec::new()), vec![StreamSpec::Video(spec)], MuxOptions::default()).expect("writer"); + w.write_chunk(0, packet, true).expect("chunk"); + w.finish().expect("finish").into_inner() +} + +#[test] +fn ffmpeg_decodes_our_packets_to_our_pixels() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("ffv1"); + for &(pix_fmt, cs, bits, shift, planes) in FORMATS { + for (slices_h, slices_v) in [(1, 1), (2, 2), (3, 2)] { + let f = frame(96, 48, cs, bits, shift, planes); + let enc = Encoder::new(&f, EncoderConfig { slices_h, slices_v, slice_crc: true }).expect("encoder"); + let avi = avi_with(&f, &enc.config_record(), &enc.encode(&f).expect("encode")); + let path = dir.join(format!("ours_{pix_fmt}_{slices_h}x{slices_v}.avi")); + std::fs::write(&path, avi).expect("write"); + let theirs = ffmpeg_run(&ff, &["-i", path.to_str().expect("path"), "-f", "rawvideo", "-pix_fmt", pix_fmt, "-"]); + // gbrp is planar G, B, R; our RGB planes are R, G, B. + let mut want = f.clone(); + if cs == Colorspace::Rgb { + want.planes = gbr_order(&f.planes); + } + assert!(theirs == raw_bytes(&want), "{pix_fmt} {slices_h}x{slices_v}: ffmpeg's pixels differ from ours"); + } + } +} + +#[test] +fn our_decoder_reads_ffmpegs_files() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("ffv1"); + for &(pix_fmt, cs, bits, shift, planes) in FORMATS.iter().chain(DECODE_ONLY) { + for slices in ["1", "4", "6"] { + for (ctx, extra) in [("0", false), ("1", true)] { + let path = dir.join(format!("ffmpeg_{pix_fmt}_s{slices}_c{ctx}.avi")); + let lavfi = "testsrc2=size=96x48:rate=1"; + ffmpeg_run( + &ff, + &[ + "-f", + "lavfi", + "-i", + lavfi, + "-frames:v", + "1", + "-vf", + &format!("format={pix_fmt}"), + "-c:v", + "ffv1", + "-level", + "3", + "-coder", + "1", + "-context", + ctx, + "-slices", + slices, + "-slicecrc", + "1", + "-g", + "1", + path.to_str().expect("path"), + ], + ); + let _ = extra; + let file = std::fs::read(&path).expect("read"); + let avi = craft_media::avi::open(&file[..]).expect("open avi"); + let stream = &avi.streams[0]; + let config = stream.video.as_ref().expect("video").extra.clone(); + let chunk = stream.chunks[0]; + let packet = file[chunk.offset as usize..chunk.offset as usize + chunk.size as usize].to_vec(); + let dec = Decoder::new(&config, 96, 48).unwrap_or_else(|e| panic!("{pix_fmt} s{slices} c{ctx}: config: {e}")); + let got = dec.decode(&packet).unwrap_or_else(|e| panic!("{pix_fmt} s{slices} c{ctx}: decode: {e}")); + let theirs = ffmpeg_run(&ff, &["-i", path.to_str().expect("path"), "-f", "rawvideo", "-pix_fmt", pix_fmt, "-"]); + let mut want = got.clone(); + if cs == Colorspace::Rgb { + want.planes = gbr_order(&got.planes); + } + assert_eq!((got.colorspace, got.bit_depth, got.chroma_shift, got.planes.len()), (cs, bits, shift, planes), "{pix_fmt}"); + if theirs != raw_bytes(&want) { + let mut off = 0; + for (i, p) in want.planes.iter().enumerate() { + let n = p.len() * if bits == 8 { 1 } else { 2 }; + let same = theirs[off..off + n] == raw_bytes(&Frame { planes: vec![p.clone()], ..want.clone() })[..]; + eprintln!("{pix_fmt} s{slices} c{ctx}: plane {i} {}", if same { "equal" } else { "DIFFERENT" }); + off += n; + } + panic!("{pix_fmt} s{slices} c{ctx}: our pixels differ from ffmpeg's"); + } + } + } + } +}