Crate rusty_h264 

rusty_h264

A ground-up, pure-Rust H.264 codec — a Remade With Rust rebuild of Cisco’s openh264. Unlike the FFI bindings in openh264-rs, there is no C in the dependency tree: the codec core is #![forbid(unsafe_code)], BSD-2 licensed, and embeddable anywhere.

The encoder produces compressed Constrained Baseline streams (intra I_16x16/I_4x4/I_PCM, inter P-frames with quarter-pel motion compensation, in-loop deblocking, and rate control) that decode bit-exactly under reference decoders. The decoder handles the full Constrained Baseline subset and is validated bit-exact against Cisco’s h264dec.

This facade re-exports the encoder, decoder, and shared types so downstream users depend on a single crate.

Decoding a whole stream

Decoder::decode_stream is the one-call entry point — it splits access units, assembles multi-slice pictures, and returns frames in display order:

use rusty_h264::{Encoder, EncoderConfig, Decoder, YuvFrame};

// Encode three frames. The default config carries a lookahead (mb-tree),
// so `encode()` may buffer — always `flush()` at end of stream.
let mut enc = Encoder::new(EncoderConfig::new(32, 32)).unwrap();
let mut stream = Vec::new();
for _ in 0..3 {
    stream.extend_from_slice(&enc.encode(&YuvFrame::black(32, 32)));
}
stream.extend_from_slice(&enc.flush());

let frames = Decoder::new().decode_stream(&stream).unwrap();
assert_eq!(frames.len(), 3);
assert_eq!((frames[0].width, frames[0].height), (32, 32));

For streaming use, the lower-level Decoder::decode returns one picture per access unit in decode order (pair it with Decoder::last_poc to reorder).

Modules

bitacct

The BIT ACCOUNTANT — codec-analyzer instrument #6, the rate-domain twin of the stage profiler.

gopstats

Gate-regression instruments (Great Gate P4 — see bench/examples/gatecheck.rs): the fire-rate census and the deterministic work counts every gate verdict must report alongside its quality number (the dual-verdict law). mb-tree per-frame per-MB QP offsets for a GOP of SOURCE frames (display order, the IDR first). strength <= 0 returns all-zero (no-op / byte-identical). The offsets are centered per GOP so the mean QP — hence the rate — is preserved. Per-GOP gate telemetry — the Front-B harvest seam.

Structs

Decoder

A Constrained Baseline H.264 decoder. Holds the most recent parameter sets and the previous decoded picture (the inter reference) across calls.

Encoder

A Constrained Baseline H.264 encoder.

EncoderConfig

Configuration for an crate::Encoder.

NalUnit

A NAL unit: a header (type + nal_ref_idc) plus its raw RBSP payload.

YuvFrame

A raw planar YUV 4:2:0 frame (8-bit). Plane strides equal their widths; chroma planes are half-resolution in each dimension.

Enums

ChromaFormat

Chroma subsampling. The encoder supports 4:2:0 only for now.

DecodeError

Decode errors.

EncodeError

Errors that can arise constructing or driving the encoder.

LookaheadMode

Resolution the mb-tree lookahead motion search runs at (speed/quality lever). Measured on CIF (mb-tree BD-rate vs off / encode wall vs FullRes): FullRes mand −0.19% tsrc −1.80% (1.0×) · Hybrid −0.19% / −1.47% (~1.7×) · HalfRes +0.12% / −1.28% (~4×).

NalUnitType

NAL unit type (nal_unit_type, 5 bits). Only the subset relevant to a Constrained Baseline encoder/decoder is named; others are Other.

Preset

Speed/quality trade-off, in the spirit of x264’s -preset. The bitstream is valid (and decodes bit-exactly) either way; only the encoder’s effort differs.

Profile

H.264 profile. The encoder targets Constrained Baseline; the rest are named for parsing/identification only.

Constants

VERSION

The crate version string.

Functions

bstats_dump

B-slice mode census (RFF_BSTATS=1). Re-exported so the CLI can print it on the same flags a comparison is being judged on.

diastats_reset

Gate-regression instruments (Great Gate P4 — see bench/examples/gatecheck.rs): the fire-rate census and the deterministic work counts every gate verdict must report alongside its quality number (the dual-verdict law).

diastats_snapshot

Gate-regression instruments (Great Gate P4 — see bench/examples/gatecheck.rs): the fire-rate census and the deterministic work counts every gate verdict must report alongside its quality number (the dual-verdict law).

gate_census

Gate-regression instruments (Great Gate P4 — see bench/examples/gatecheck.rs): the fire-rate census and the deterministic work counts every gate verdict must report alongside its quality number (the dual-verdict law).

gate_census_by_t8

Gate-regression instruments (Great Gate P4 — see bench/examples/gatecheck.rs): the fire-rate census and the deterministic work counts every gate verdict must report alongside its quality number (the dual-verdict law). Per-gate (fired, seen) split by the macroblock’s TRANSFORM SIZE: [0] = macroblocks coded 4x4, [1] = coded 8x8, each in gate_census_names order. A LABEL on the existing counters, not a new gate — it answers whether a per-transform-size threshold could ever be worth fitting, before one is.

gate_census_dump_csv

Gate-regression instruments (Great Gate P4 — see bench/examples/gatecheck.rs): the fire-rate census and the deterministic work counts every gate verdict must report alongside its quality number (the dual-verdict law). LIVENESS tap: dump gate,fired,seen to $RFF_CENSUS_CSV, once, at the end of an encode. No-op when the env var is unset.

gate_census_names

Gate-regression instruments (Great Gate P4 — see bench/examples/gatecheck.rs): the fire-rate census and the deterministic work counts every gate verdict must report alongside its quality number (the dual-verdict law). Names for gate_census, same order.

gate_census_reset

Gate-regression instruments (Great Gate P4 — see bench/examples/gatecheck.rs): the fire-rate census and the deterministic work counts every gate verdict must report alongside its quality number (the dual-verdict law). Zeroes the gate census.

gate_work

Gate-regression instruments (Great Gate P4 — see bench/examples/gatecheck.rs): the fire-rate census and the deterministic work counts every gate verdict must report alongside its quality number (the dual-verdict law). Deterministic WORK counts (best_part, mb_plan, mb_coded) — the speed instrument that needs no pinning. See signals::census.

gate_work_names

Gate-regression instruments (Great Gate P4 — see bench/examples/gatecheck.rs): the fire-rate census and the deterministic work counts every gate verdict must report alongside its quality number (the dual-verdict law). Names for gate_work, same order.

set_turbo

The SUPERFAST-CLASS shape rung (WHYS-speed-gap H-11/H-12): the current preset at P16×16-only partition shape. Measured 1.81× faster than default quality at −0.9% BD vs x264 superfast. Composable with any Preset. The SUPERFAST-CLASS rung (H-11/H-12): the Quality preset at x264 superfast’s partition SHAPE — P16×16-only (splits gated off), everything else (sub-pel ladder, B2 dispatch) at defaults. Measured fair-run on foreman: 1.81× faster than default quality and STILL −0.9% BD vs x264 superfast itself. The further effort cuts (subme 2 + SAD-fp force) were measured and REJECTED from this rung: no speed on top of shape-only (0.27× vs 0.28×) while costing BD (+1.9% foreman / +8.4% bus) — compose them manually via set_subme / set_me_sadfp_mode if wanted. Split-heavy content (bus-class) pays more at this rung; the per-frame split DISPATCH (H-11 next-brick b) is the eventual no-tax answer. Env twin: RFF_SPLIT_T=10000000.

temporal_decay_ratio

Gate-regression instruments (Great Gate P4 — see bench/examples/gatecheck.rs): the fire-rate census and the deterministic work counts every gate verdict must report alongside its quality number (the dual-verdict law). Adaptive B-COUNT (B-frames per anchor gap) for auto mode. The RATIO of the 2-gap to 1-gap bi-prediction residual measures how fast bi-pred degrades as the anchor spacing widens: LOW ratio (content survives wider gaps) carries MORE cheap non-reference B’s; HIGH ratio (simple translation — degrades fast, so wider anchors cost more than the extra B’s save) wants a single equidistant B. Calibrated on pans/zoom: ratio ≥ 1.8 → 1, ≥ 1.4 → 2, else 3. Capped at max_b (the auto cap). TEMPORAL PREDICTABILITY probe (Great Gate P3 item 4). Returns the 2-gap / 1-gap motion-compensated residual ratio for a frame window – the axis the mb-tree dispatch has been waiting on.