Files
craft-libs/crates/video/src/av1/decode
Dylan M. Taylor faa36fc2ea Merge pull request #1140 from vangel76/perf/av1-wavefront-3106
AV1 decoding about 1.7x as fast with many threads
2026-11-15 18:28:38 -05:00
..

AV1 decoder (craft_video::av1::decode, feature av1-decode)

Clean-room, pure-Rust (no unsafe) AV1 decoder, implemented from the public AV1 Bitstream & Decoding Process Specification, version 1.0.0 with Errata 1 (AOMediaCodec/av1-spec, git commit 5e04f3f, 2023-06-12). It depends only on thiserror and (optional, feature threads) rayon, and builds for wasm32-unknown-unknown.

All constant tables (default CDFs, scan orders, quantiser lookups, filter taps, …) and the named constants are extracted from the specification's Markdown source by tools/av1_extract_tables.py into spec_tables.rs (every table's shape is checked against its declared dimensions; one missing comma in the spec's Split_Tx_Size initialiser is reported and repaired). No code was taken from libaom, dav1d, SVT-AV1 or any other implementation; ffmpeg (libsvtav1 to encode fixtures, libdav1d to decode the reference) is used only as an external test oracle.

Conformance status

Stage Spec Status
OBU parsing (low-overhead format), temporal delimiters, operating-point dropping 5.3, 7.5 done
Sequence header, color config, timing / decoder model info 5.5 done
Uncompressed frame header (all fields, frame size / superres / render size, tile info, quantiser, segmentation, delta q/lf, loop filter, CDEF, LR, tx mode, skip mode, global motion, film grain params) 5.9 done
Reference frame state: set_frame_refs, setup_past_independence, load_previous, reference update, show_existing_frame 7.8, 7.20, 7.21 done
Symbol decoder, CDF adaptation, init / load / save / frame-end CDF update 8.2, 8.3 done
Tiles and tile groups (uniform and explicit spacing, tile size bytes) 5.11 done (tiles decoded in parallel)
Intra frame mode info: partitions, skip, segment id, CDEF index, delta q / lf, y / uv modes, angle deltas, CfL alphas, palette (colors, cache, color index map), filter intra, tx size (incl. var-tx syntax) 5.11 done, bit-exact
Coefficients (all_zero, eob, base / br levels, Golomb, dc sign, tx type sets, scans) 5.11.39 done, bit-exact
Dequantisation incl. quantiser matrices 7.12 done
Inverse transforms: DCT 4–64, ADST 4/8/16, flip ADST, identity 4–32, WHT (lossless), rectangular 7.13 done, bit-exact
Intra prediction: DC, V/H + directional with edge filter and upsampling, smooth (3), Paeth, recursive filter intra, CfL, palette 7.11.2, 7.11.4, 7.11.5 done, bit-exact
Inter mode info: segment id prediction, skip mode, reference frames (single / compound, uni / bi), modes, DRL, MV coding, inter-intra, motion mode, compound type, interpolation filters 5.11.18–5.11.32 done, bit-exact
MV prediction: spatial / temporal candidate stacks, global MV, extra search, clamping, warp samples 7.10 done, bit-exact
Motion field estimation (projection) and motion vector storage 7.9, 7.19 done, bit-exact
Inter prediction: MV scaling (scaled references), 8-tap sub-pixel filters, global and local warp (warp estimation, shear), OBMC, wedge / difference-weighted / inter-intra masks, distance weights, averaging 7.11.3 done, bit-exact
Intra block copy 7.11.3 done, bit-exact
Output policy with scalability (highest spatial layer per temporal unit) 7.18.1 done, bit-exact
Loop filter (all filter sizes, deltas, segment / ref / mode adjustments) 7.14 done, bit-exact
CDEF 7.15 done, bit-exact
Super-resolution upscaling 7.16 done, bit-exact
Loop restoration (Wiener, self-guided, switchable; stripes) 7.17 done, bit-exact
Film grain synthesis (output pictures only; Decoder::apply_film_grain turns it off) 7.18.3 done, bit-exact
Large-scale tile / tile list OBUs 7.3 not planned

Accuracy

OBU and tile length regressions (decoder::tests::hostile_lengths_*, #2801) use synthetic inputs, including truncations and bit flips, without ffmpeg. Oversized LEB128 OBU lengths and four-byte tile lengths return Error::Truncated instead of wrapping or truncating on 32-bit targets. Valid partial tile groups retain their payloads. See 32-bit parser tests.

tests/it/oracle_intra.rs encodes all-intra streams with ffmpeg's libsvtav1 (with and without the in-loop filters; 64×64 and 128×128 superblocks; intra edge filter on and off) and compares every decoded frame with libdav1d: bit-exact on all 13 fixtures (8- and 10-bit 4:2:0; 128×128 to 1280×720 including odd sizes; testsrc2, mandelbrot, gradients and noise; presets 1–8).

tests/it/conformance.rs downloads libaom's conformance test vectors on first use (storage.googleapis.com/aom-test-data) and compares with libdav1d: av1-1-b8-02-allintra (39 frames, deblocking + CDEF + self-guided restoration), 05-mv, 06-mfmv, 24-monochrome and b10-23-film_grain-50 are bit-exact in the default run. The ignored conformance_vectors_extended test covers the wider set; bit-exact today: 01-size-16x16, -66x66, -196x196, -226x226, 00-quantizer-00/31/63 (8-bit) and -00/40 (10-bit), 04-cdfupdate, 05-mv, 06-mfmv, 22-svc-L1T2, 22-svc-L2T1, 22-svc-L2T2 (spatial layers with scaled inter-layer prediction), 24-monochrome (8 and 10-bit) and 16-intra_only-intrabc-extreme-dv (1080p intra block copy), 23-film_grain-50 (8 and 10-bit).

tests/it/oracle_inter.rs also checks draft mode: every unflagged frame stays bit-exact with libdav1d and only flagged frames differ, with 1 and 4 threads. tests/it/oracle_inter.rs encodes SVT-AV1 GOPs (hierarchical references, compound prediction, OBMC / warped motion, motion-field projection, all loop filters; presets 3–8, 8- and 10-bit, odd sizes), plus super-resolution (denominator 12) and film-grain streams, and compares every frame with libdav1d: bit-exact on all 6 fixtures.

Threading and performance

Decoder::new() uses all cores (Decoder::with_threads(1) decodes on the calling thread; on wasm32, or without the default threads feature, everything runs on the calling thread). Headers are parsed in order; each frame is then decoded by a frame worker. With worker threads it first reads the symbols of all its tiles, which needs only the parse results of its references (CDFs, segment ids, saved motion vectors), publishes its own, and then reconstructs from the recorded blocks. Frames with several tiles read the symbols of their tiles in parallel (one after another with intra block copy). A frame reconstructs superblock row by superblock row (that row of every tile), each row waiting only for the reference rows its motion vectors reach (row wavefront), and the in-loop filters (deblocking, CDEF, loop restoration) follow a few 64-row bands behind and publish each final band for the frames predicting from it (decoder.rs and postfilter.rs give the dependency rules). Super-resolution frames wait for their whole references and filter the whole frame. There is one frame worker per thread (at most 16), and the frames in flight are bounded by their size. Independent frames (hierarchical GOP layers) decode concurrently. Results never depend on scheduling (the oracle tests compare 1 thread, many threads and libdav1d). With frame threads, pictures may be returned by a later decode_pts call or by flush; each carries the pts of the temporal unit that showed it.

tests/it/perf.rs (ignored) prints single-threaded fps (thread CPU time), per-stage ms/frame (Decoder::stats()) and all-core fps with its per-stage ms/frame for 1080p fixtures (key frames, GOPs, tiles, low delay) and a single-tile 2160p GOP; AV1_PERF_ONLY=a,b picks fixtures. The hot loops (sub-pixel filters, CDEF, inverse transforms, deblocking, entropy decoding) are written for auto-vectorisation.

Measured 2026-10-01 on a 14-core Apple Silicon Mac (release build, SVT-AV1 preset 8 1080p fixtures from tests/it/perf.rs), before (31f8b3d: hot loops only, no threading) and after tile / frame / post-filter threading. The machine was heavily loaded by other builds during both runs (load average 200–400), so the all-core wall figures understate what an idle machine reaches and are noisy; single-threaded figures use thread CPU time and are comparable.

Fixture 1 thread before 1 thread after 14 threads before 14 threads after
perf_1080p_intra (10 key frames) 43.3 fps 43.0 fps 6.5 fps 20.8 fps
perf_1080p_gop (60 frames, crf 30) 45.5 fps 40.7 fps 7.7 fps 11.0 fps
perf_1080p_gop_10bit 41.3 fps 35.9 fps 8.0 fps 6.6 fps
perf_1080p_gop_hq (crf 18) 19.5 fps 19.4 fps 2.4 fps 3.6 fps
perf_1080p_gop_tiles (4x2 tiles) 44.4 fps 44.7 fps 2.7 fps 16.3 fps

M4.10 (2026-10-03)

CPU cycles per frame counted by the kernel (/usr/bin/time -l, all threads summed; mean of two interleaved base / after rounds at load average 190-320) with AV1_THREADS=n cargo run --release -p craft-video --features av1-decode,threads --example av1_av1dec -- in.ivf on the FilmCraft's cargo xtask bench decode clips (SVT-AV1 preset 10, CRF 35, keyint 48, testsrc2 + grain), bit-exact with libdav1d:

stream threads Mcycles / frame before after after, draft mode
1080p (120 frames) 1 60.5 48.3 (−20 %) 46.2
1080p 14 63.6 51.9 (−18 %) 50.3
2160p (72 frames) 1 212.5 172.4 (−19 %) 167.9
2160p 14 220.0 177.1 (−20 %) 171.1

What changed: the sub-pixel filter passes run over fixed block widths (taps outer, columns inner); frame and tile-region planes come from a bounded pool of recycled buffers (zeroed on reuse) instead of a fresh calloc and munmap per frame (allocation, page faults and zeroing were ~10 % of the time); the palette mode-info arrays (40 bytes per 4x4 unit) are only allocated when screen content tools are allowed; CDF adaptation is branch-free (a branch-free symbol search was tried and was slower: most symbols have 2-4 values). Single-threaded 4K now splits into coefficient parsing ~20 %, inter prediction ~18 %, other block-level parsing ~12 %, deblocking ~11 % (still one edge at a time), inverse transforms ~12 %, CDEF ~5 %.

Draft mode (Decoder::set_draft(true), AV1_DRAFT=1; reduced-resolution playback only): shown frames whose refresh_frame_flags is 0 — no reference slot keeps them, so neither their samples, motion vectors nor CDFs reach another frame — skip deblocking, CDEF and loop restoration (super-resolution still runs, it sets the output size) and are flagged Picture::draft. In SVT-AV1's hierarchical GOPs that is the top layer, half of the frames.

Frame threading on a Ryzen 7800X3D (8 cores / 16 threads, release examples/av1_av1dec, median of 7 alternating runs against Filmcraft 6909e461, 2026-11-08), wall time for the whole file:

Fixture Threads Before After Speed-up
perf_1080p_gop (60 frames) 1 69.2 fps 69.1 fps 1.00x
perf_1080p_gop 16 159.6 fps 227.3 fps 1.42x
perf_2160p_gop (30 frames) 1 17.9 fps 17.8 fps 1.00x
perf_2160p_gop 16 40.2 fps 57.7 fps 1.43x

Peak RSS at 16 threads goes from 278 to 365 MB (1080p) and from 1031 to 1217 MB (2160p, +18%): every frame in flight holds its parse record and its final samples are kept in 64-row bands.

With one frame worker per thread, the row wavefront for frames with several tiles and parse waits limited to what parsing reads (same machine, median of 5 alternating runs, 2026-11-08):

Fixture Threads Before (6909e461) After Speed-up Peak RSS before / after
perf_1080p_gop 4 95.7 fps 185.2 fps 1.94x 148 / 236 MB
perf_1080p_gop 16 155.0 fps 259.7 fps 1.68x 274 / 560 MB
perf_2160p_gop 4 23.6 fps 47.1 fps 2.00x 512 / 798 MB
perf_2160p_gop 16 39.9 fps 65.8 fps 1.65x 994 / 1353 MB
perf_1080p_gop_tiles (4x2 tiles) 16 186.3 fps 237.2 fps 1.27x 328 / 617 MB
SVT-AV1 2160p, 4x2 tiles (30 frames) 16 57.1 fps 70.8 fps 1.24x 1197 / 1502 MB

Known limitations of the frame threading (the output is the same in every case, only the overlap is smaller):

  • A frame whose parse record would pass 32 bytes per luma sample of a tile (pathological streams: tiny blocks, large palettes, every coefficient coded), or that cannot reserve its record from the decoder-wide budget of 1 GiB shared by the frames in flight, is decoded again in one pass.
  • A superblock row using local warped motion, global motion beyond translation or a scaled reference waits for the whole reference instead of the rows its motion vectors reach.
  • Super-resolution frames do not use the row wavefront: they wait for their whole references and filter the whole frame.
  • The tile columns of a superblock row are reconstructed one after another on the frame's worker (their symbols are still read in parallel).

Limits

Frames beyond the AV1 level 6.x limits (Annex A: at most 16384 wide, 8704 high and 35 651 584 luma samples in total, so 16384 x 2176 or 8192 x 4352 at most) are refused with Error::Invalid("frame size"). The sequence header can code up to 65536 x 65536, which would ask for gigabytes of buffers from a few bytes of hostile input; no real stream comes close to level 6.3, the highest defined level.

A frame is also refused when the pictures the decoder would hold at its size (the eight reference slots, the new frame and those in flight, padded as the frame buffers are, two bytes a sample) do not fit Decoder::set_memory_budget (craft_video::budget::DECODE_MEMORY_BUDGET by default: 4 GiB, 1 GiB on 32-bit targets). Non-uniform tile spacing may not code more than 64 tile columns or rows.

API

let mut dec = craft_video::av1::decode::Decoder::new();
for sample in samples {                  // one temporal unit (MP4 / Matroska sample) each
    for pic in dec.decode_pts(&sample, pts)? {   // shown frames ready so far, planar u16
        // pic.width, pic.height, pic.bit_depth, pic.planes[0..3], pic.pts
    }
}
let rest = dec.flush();                  // pictures still in flight at the end