Crate rusty_h264_encoder

Expand description

Pure-Rust H.264 encoder — raw I420 frames in, a conformant Annex-B stream out.

Every frame it emits decodes bit-exactly under ffmpeg across QP 0–51, intra and inter. The crate is #![forbid(unsafe_code)]; the optional SIMD kernels behind the asm feature keep their unsafe quarantined in rusty_h264-accel, so that guarantee holds either way.

Coding tools, default-on: I_16x16/I_4x4/I_PCM intra with λ-based RD/SATD mode decision; P-frames (P_Skip, 16×16/16×8/8×16) with quarter-pel motion compensation, rate-aware ME and a multi-reference DPB; CABAC entropy coding (Main profile — set RUSTY_H264_LEGACY_CAVLC=1 to restore the Constrained Baseline + CAVLC bitstream byte-for-byte); adaptive quantization; the per-GOP I-frame QP cascade; in-loop deblocking; and average-bitrate rate control. Opt-in via EncoderConfig: B-frames (fixed or content-adaptive), the 8×8 transform, mb-tree temporal AQ, sub-8×8 partitions and RD P_Skip.

Preset picks the speed/quality trade-off — Fast (SAD, integer-pel), Balanced (adds sub-pel refinement; the default) or Quality (full RD trial-encode). The bitstream is valid either way; only the effort differs.

use rusty_h264_encoder::{Encoder, EncoderConfig};
use rusty_h264_common::YuvFrame;

let cfg = EncoderConfig::new(16, 16);
let mut enc = Encoder::new(cfg).unwrap();
let frame = YuvFrame::black(16, 16);
// The default config carries a lookahead (mb-tree), so `encode()` may
// buffer — `flush()` at end of stream is part of the streaming contract.
let mut bitstream = enc.encode(&frame);
bitstream.extend_from_slice(&enc.flush());
assert!(!bitstream.is_empty());

Re-exports§

pub use crate::mb16::EXT_MV;
pub use crate::mb16::ME_PROBE;
pub use crate::mb16::MVCMP;
pub use crate::mb16::MVCMP_FRAME;

Modules§

bitacct: The BIT ACCOUNTANT — codec-analyzer instrument #6, the rate-domain twin of the stage profiler.
gopstats: Gate fire-rate census (Tier 1 of the gate-regression harness): (fired, seen) per tracked gate, in gate_census_names order. Deterministic — one run is the verdict. See signals::census. Per-GOP mb-tree gate telemetry (Front-B harvest seam). 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.
mb16: I_16x16 macroblock encoding (DC prediction) — the compressing intra path.

Structs§

Encoder: A Constrained Baseline H.264 encoder.
EncoderConfig: Configuration for an crate::Encoder.
Pps: Picture parameter set for a CAVLC, single-slice-group CBP encoder.
RateControl: Frame-level average-bitrate controller.
Sps: Sequence parameter set, carrying only the fields a CBP encoder emits.

Enums§

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×).
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.

Constants§

DIA_DEFAULT_MASK: Default diamond rung mask ([16,8,4]).

Functions§

bframes_gate_signals: B-frame gate signal probe (harness surface for the bframes-v2 dispatch fit): per-GOP (bi_residual_1gap, gmc_residual, mgain, dcfrac, is_screen, grain_signature) — the same estimators the shipping gates consult, on the GOP’s leading frames. Frame dimensions must be MB multiples (probe use).
diastats_reset
diastats_snapshot
gate_census
gate_census_by_t8: 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: 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: Names for gate_census, same order.
gate_census_reset: Zeroes the gate census.
gate_work: Deterministic WORK counts (best_part, mb_plan, mb_coded) — the speed instrument that needs no pinning. See signals::census.
gate_work_names: Names for gate_work, same order.
mbtree_satd_calls: Lookahead candidate evaluations so far (mb-tree cost instrument, H-36) — a deterministic stand-in for wall time, which this box cannot measure at the precision the content effect needs. reset before an encode, read after.
mbtree_satd_reset: Zeroes mbtree_satd_calls.
satdpath_reset
satdpath_snapshot
scene_cut_ratios: Scene-cut pair ratios for a frame sequence (calibration probe surface — the same detector segment_gops consults; index i is the pair (frames[i], frames[i+1])).
set_defer_subpel
set_dia_mask: Descent A: select which rungs of the [64,32,16,8,4] diamond ladder to walk.
set_me_fc: Fixed-centre batched diamond passes (both cost domains). Off = cascade.
set_me_sadfp: Track-B B2: SAD-domain full-pel search phase (SATD from sub-pel on) — x264’s cost split. Bitstream-changing; BD-gated; off = byte-identical to pre-B2.
set_me_sadfp_mode: B2 mode: 0 off, 1 dispatched per frame by the b2_mgain probe, 2 force-on.
set_mv_smooth: H-23: smooth (x264-shape) mvd cost model in ME. Off = Exp-Golomb step fn.
set_mv_smooth_mode: H-24 mv-cost mode: 0 off, 1 dispatched per frame by mgain, 2 force-on.
set_sp_fc: Fixed-centre batched HALF-PEL sub-pel ring (satd_x4p). Off = cascade.
set_sp_maxit: Track-B B3: sub-pel iteration budget (0 = unlimited = byte-identical) — the bounded walk x264’s subme levels have; pairs with B2. BD-gated.
set_split_mg: H-13 split-dispatch threshold in milli-units of the mgain probe (0 = always search splits, byte-identical to pre-gate). Default 30 (= 0.03).
set_split_t
set_subme: The x264-style SUB-PEL EFFORT LADDER (H-10): one level selects a priced (ring pattern × iteration budget) rung — closing the ~24-vs-9 eval-count gap vs x264 as a BUDGET choice instead of a blanket cut.
set_subpel_dispatch
set_subpel_pattern
set_turbo: 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.
spstats_redundant
spstats_reset
spstats_snapshot
temporal_decay_ratio: 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.