rusty_h264-encoder

The encode pipeline of the pure-Rust rusty_h264 codec: raw I420 frames in, a conformant Annex-B H.264 stream out. Every frame it emits decodes bit-exactly under ffmpeg across QP 0–51, intra and inter. #![forbid(unsafe_code)], BSD-2, no C in the dependency tree.

Most users want the facade — rusty_h264, which re-exports Encoder, EncoderConfig and the shared types alongside the decoder. Depend on this crate directly only if you want the encoder alone.

Part of Remade With Rust by Mata Network — the H.264 encoder inside remade_ffmpeg_rs.

Install

cargo add rusty_h264-encoder rusty_h264-common

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

let mut cfg = EncoderConfig::new(1280, 720);
cfg.preset    = Preset::Balanced;  // Fast | Balanced | Quality
cfg.gop_size  = 30;                // an IDR every 30 frames, P-frames between
cfg.bitrate   = 4_000_000;         // 4 Mbps ABR; 0 = constant QP (cfg.qp)
cfg.framerate = 30.0;

let mut enc = Encoder::new(cfg).unwrap();
for frame in &frames {
    let access_unit = enc.encode(frame);   // Annex-B bytes, ready to write
}

How correctness is enforced

The encoder is gated by a dual oracle, and both gates are standing CI tests:

1. Round-trip — the encoder's own output is decoded by rusty_h264-decoder (a dev-dependency; there is no build cycle, the decoder never depends on the encoder) and asserted pixel-exact against the encoder's internal reconstruction. Encoder/decoder drift is caught at the macroblock.
2. Independent reference — every frame is decoded by ffmpeg and asserted pixel-exact, across the whole QP 0–51 range, intra and inter.

Speed work on top of that is gated byte-identical: a performance brick that changes a single output byte is reverted, not shipped.

Coding tools

Default-on

• Intra: I_16x16 (all four modes), I_4x4, I_PCM, chroma 8×8, with λ-based RD/SATD mode decision.
• Inter P-frames: P_Skip, 16×16 / 16×8 / 8×16, quarter-pel motion compensation, rate-aware motion estimation with early termination, a multi-reference DPB.
• CABAC entropy coding (Main profile) — measured −8.8…−9.0% BD-rate for 1.10–1.22× the time on the 4-QP corpus, which is better value than any preset step in either encoder, so it ships on by default. Trellis RDOQ is default-on for all-intra (−0.5…−1.3%). RUSTY_H264_LEGACY_CAVLC=1 restores the exact prior defaults (Constrained Baseline + CAVLC) byte-for-byte, as an escape hatch and bisection anchor.
• Adaptive quantization (aq_strength, default 1.0): per-macroblock QP finer on flat/low-variance regions (where blocking and banding are visible), coarser on busy ones (where the eye masks error). The shift is relative to the frame's mean log-variance, rate-compensated, and its effective strength backs off automatically on pathological synthetic content — so it never regresses. 0.0 = uniform QP, byte-identical to AQ-off.
• Per-GOP I-frame QP cascade (i_qp_offset, default -3) — the calibrated equivalent of x264's ip_ratio, deepened content-adaptively on predictable GOPs.
• In-loop deblocking; average-bitrate rate control (complexity model + leaky-bucket buffer).

Opt-in

Default-on for the Quality preset (None follows the preset; Some(b) forces either way):

Bitstream-changing knobs are validated by 4-QP BD-rate per clip with a worst-clip-≤-0 rule — never a mean, never a single QP.

Presets

EncoderConfig::new() starts at Preset::Fast and all-intra (gop_size = 1); set preset and gop_size for anything else.

Features

The asm SATD kernels are wired into the quality-preset mode decision byte-identically: Σ|H·d| is always even, so openh264's (Σ+1)>>1 result times 2 recovers our value exactly — worth 1.7× on quality inter encode with no bitstream change.

Where this sits

The Remade With Rust ecosystem

Remade With Rust is an initiative by Mata Network to rebuild essential C and C++ tools in Rust — for the memory safety, the predictable performance, and the freedom of a permissive license. Each project is a reimplementation, not a fork: same wire protocols and file formats, new code you can actually depend on. No copyleft. No surprises.

→ All projects: github.com/Remade-With-Rust

License

BSD-2-Clause — see LICENSE.