Struct EncoderConfig 

pub struct EncoderConfig {

    pub width: usize,
    pub height: usize,
    pub profile: Profile,
    pub chroma: ChromaFormat,
    pub level_idc: u8,
    pub qp: u8,
    pub gop_size: u32,
    pub bitrate: u32,
    pub framerate: f32,
    pub num_ref_frames: u32,
    pub preset: Preset,
    pub tune_me_subpel_iter: bool,
    pub tune_greedy_skip: bool,
    pub tune_greedy_skip_min_free: Option<u32>,
    pub tune_rd_skip: bool,
    pub tune_rd_skip_min_free: Option<u32>,
    pub tune_rd_skip_fast_t: Option<f64>,
    pub bframes: u32,
    pub bframe_qp_offset: i32,
    pub aq_strength: f64,
    pub bframes_adaptive: bool,
    pub i_qp_offset: i32,
    pub cabac: bool,
    pub cabac_init_idc: u32,
    pub cabac_lambda_scale: f64,
    pub cabac_dz_div: i64,
    pub cabac_rdoq: f64,
    pub transform_8x8: bool,
    pub sub_8x8: Option<bool>,
    pub me_wide: Option<bool>,
    pub mbtree: bool,
    pub mbtree_strength: f64,
    pub mbtree_lookahead: LookaheadMode,
    /* private fields */
}

Configuration for an crate::Encoder.

Fields

width: usize

Picture width in luma samples. Arbitrary (not restricted to /16).

height: usize

Picture height in luma samples.

profile: Profile

Target profile. Only Profile::ConstrainedBaseline is implemented.

chroma: ChromaFormat

Chroma format. Only ChromaFormat::Yuv420 is implemented.

level_idc: u8

level_idc (e.g. 30 = level 3.0). Caller is responsible for choosing a level that admits the resolution/bitrate; not yet validated.

qp: u8

Quantization parameter (0..=51). With rate control off this is the fixed QP for every frame; with it on, the base/fallback QP and pic_init_qp.

gop_size: u32

Frames between IDR pictures. 1 = all-intra (every frame an IDR).

bitrate: u32

Target bitrate in bits per second. 0 disables rate control (constant QP); any positive value enables average-bitrate control, which varies the per-frame QP around qp to converge on this rate.

framerate: f32

Frame rate (frames per second), used by rate control to turn the bitrate target into a per-frame bit budget.

num_ref_frames: u32

Number of reference frames the encoder may use for P-pictures (1..=16). 1 keeps the single-reference bitstream; higher values let P-macroblocks pick an older reference (ref_idx), helping occlusion/periodic motion.

preset: Preset

Speed/quality trade-off. Defaults to Preset::Balanced.

tune_me_subpel_iter: bool

Walk the sub-pel refinement until it stops improving, instead of a single 8-point pass per step. Independent of Self::tune_me_snap — measured separately, because the two were first built coupled and the attribution was ambiguous.

tune_greedy_skip: bool

tune_greedy_skip_min_free: Option<u32>

Minimum online FREE-skip percentage for Self::tune_greedy_skip to engage, dispatched on exactly the signal that gates RD skip (Self::tune_rd_skip_min_free). The greedy skip wins on temporally redundant content and LOSES on detailed content (BD-SSIM: akiyo -0.59, FourPeople -0.32 vs foreman +1.23) — the same sign-flip, separated by the same signal. None resolves to 85 — the calibrated default, at which the corpus regression on foreman (+1.23% BD-SSIM, previously shipping) becomes 0.00 and nothing else regresses. Some(0) restores the old ungated behaviour; Some(101) disables the greedy skip entirely.

tune_rd_skip: bool

tune_rd_skip_min_free: Option<u32>

Minimum FREE-skip percentage, measured online over the frame so far, for Self::tune_rd_skip to engage on the rest of that frame.

None resolves per preset, because the signal’s SCALE is preset-dependent: sub-pel refinement predicts better, so it lifts the free-skip rate on ALL content and the same absolute bar starts admitting content that loses. Fast (no sub-pel) calibrates to 60; the sub-pel presets need 90. Each is the smallest bar at which no corpus clip regresses on BD-PSNR or BD-SSIM. Some(0) forces RD skip on everywhere (which LOSES badly on detailed content); Some(101) disables it.

tune_rd_skip_fast_t: Option<f64>

Skip-gate on the null arm’s cost, in units of lambda: when SSD(skip) <= lambda * T the skip is taken WITHOUT trial-encoding the coded arm at all.

The RD skip decision has to encode the coded arm to price it, and 55-80% of the time it then throws that encode away — the null arm wins. This is the standard search-skip gate over that: it trades a small number of decisions (the RD comparison would occasionally have coded) for not encoding at all. None/<= 0.0 disables it (every candidate is priced exactly). Unlike the rest of the decision this is NOT byte-identical, so it is BD-rate gated.

bframes: u32

Number of B-frames between reference (I/P) anchors. 0 = no B-frames (Constrained Baseline, byte-identical). >0 requires Main profile (B is illegal in Baseline) and activates the reorder pipeline: anchors are coded ahead of the B-frames that reference them (L0 past + L1 future), and B- frames are non-reference. WORK IN PROGRESS — see the B-frame build plan.

bframe_qp_offset: i32

QP offset applied to B-frames (added to qp). B-frames are non-reference, so their coding error never propagates — quantizing them harder (a positive offset) spends the saved bits on the reference anchors. Only used when bframes > 0. Default 2.

aq_strength: f64

Adaptive Quantization strength. Modulates the QP per macroblock by content: flat/low-variance MBs (where blocking & banding are visible) get a FINER QP, busy/high-variance MBs (where the eye masks error) a COARSER one — moving bits to where they’re seen, a perceptual (SSIM) win at ~neutral PSNR. The QP shift is relative to the FRAME’s mean log-variance (content-invariant), rate- compensated, and its EFFECTIVE strength backs off automatically where the log-variance spread is extreme (pathological synthetic content), so it never regresses. Default 1.0 (on); 0.0 = off (uniform QP, byte-identical).

bframes_adaptive: bool

Content-adaptive B-frame ENABLE. When set (with bframes > 0), the encoder measures the clip’s temporal predictability (a cheap global-motion bi- prediction residual) and codes B-frames ONLY when they’ll help — smooth / predictable motion, where bi-pred + spatial-direct are cheap. On busy content it falls back to P-only, so B-frames never regress. Default false.

i_qp_offset: i32

Per-GOP I-frame QP cascade — the BASE offset for the classic ip_ratio (added to qp on each GOP’s I-frame; it’s the root reference for its whole GOP, so coding it finer propagates quality GOP-wide). Default -3. In the B-capable batch path this is CONTENT-ADAPTIVE per GOP: predictable GOPs — where the I-frame dominates the GOP’s bits — deepen it up to 2 further QP steps (calibrated: busy ≈ base, compressible ≈ base−2). 0 disables the cascade entirely (byte-identical escape hatch). Constant-QP only.

cabac: bool

CABAC entropy coding (PPS entropy_coding_mode_flag = 1, Main profile). Codes ~5–17% smaller than CAVLC at matched quality (I- and P-slices; B-slice CABAC pending). Default false (CAVLC — Constrained Baseline, unchanged).

cabac_init_idc: u32

cabac_init_idc (0..2) — selects one of 3 context-initialization tables for P/B slices (I-slices always use the I preset). The best table is content-dependent; 0 is the default. Signalled in the P/B slice header.

cabac_lambda_scale: f64

Multiplier on the mode-decision Lagrangian (√λ) in the CABAC P/B path only. CABAC codes ~9% fewer bits than the CAVLC-flavoured rate estimate the mode decision uses, so the rate term is slightly over-weighted; this retunes it. Default 1.0 (unchanged). CAVLC path is never affected.

cabac_dz_div: i64

Quantizer dead-zone divisor override for the CABAC path (F = 2^qbits/dz). A smaller divisor (bigger F) keeps more near-threshold coefficients — cheaper under CABAC’s context-coded residual than under CAVLC. 0 = use the standard content-derived dead-zone (default, unchanged).

cabac_rdoq: f64

CABAC trellis-quantization (RDOQ) strength. Each 4×4 residual coefficient is RD-optimized (level vs level−1 minimizing SSD + λ·R_cabac, λ scaled by this; ~8 calibrated). 0.0 = off. DEFAULT-ON for CABAC I-slices (frame-type adaptive — P/B off, sparse residual gains ~0); CAVLC path always off.

transform_8x8: bool

High-profile 8×8 transform (transform_8x8_mode_flag). When set, an intra macroblock may use one 8×8 integer DCT per 8×8 block (I_8x8) instead of four 4×4s — a per-MB RD choice that wins on smooth / large-structure content. Requires High profile (profile_idc 100). CAVLC only (our decoder has no CABAC 8×8). Default false.

sub_8x8: Option<bool>

P_8x8 sub-partition motion: allow a P macroblock to split into four 8×8 partitions, each with its own motion vector (finer motion granularity on complex / boundary motion). A per-MB RD choice vs 16×16/16×8/8×16, gated on the heavy-16×16 motion-boundary signal. A NET WIN on real content (12-clip Derf corpus: −0.23% mean BD, big wins on bus/mobile/flower; a rigorous 6-channel discovery harvest proved no cheap gate beats default-on, oracle headroom only 0.18%), so it is DEFAULT-ON for the Quality preset. Quality-only. None = follow the preset (ON for Quality); Some(b) forces it either way. (8×4/4×8/4×4 sub-shapes within an 8×8 are a further split, not yet built.)

me_wide: Option<bool>

Adaptive WIDE motion search: on flat source blocks (where the gradient-descent diamond stalls at a plateau and misses the true MV) cover the ±16 neighbourhood with a grid search instead; busy blocks keep the fast diamond. A big win on smooth/low-motion content (the diamond’s flat-surface failure), free on busy content — content-adaptive (a per-frame coherence gate keeps it from regressing even on pure pans), so it is DEFAULT-ON for the Quality preset. Quality-only. None = follow the preset (ON for Quality); Some(b) forces it either way.

mbtree: bool

Macroblock-tree lookahead adaptive QP (TEMPORAL AQ). A cheap forward pass over each GOP’s source frames propagates future-reference importance backward along motion vectors and lowers the QP of heavily-referenced macroblocks — investing bits where they pay off across many later frames. The complement to the spatial aq_strength. Per-GOP-centered (rate-preserving). Applies only in the batch (encode_all) constant-QP path, where the GOP’s future frames are available (a bframes > 0 encode uses the reorder pipeline and ignores it).

Default true since 0.5.0 (H-37) — the gate cleared and the architectural blocker is gone: the streaming path now carries a one-GOP lookahead queue, so encode() + flush is byte-identical to encode_all(). Set false for zero added latency (one AU per encode call) or for the pre-0.5.0 bytes. Evidence:

• BD: the 4-QP per-clip gate CLEARS with room to spare (akiyo −4.82%, foreman −3.13%, football −0.53%, bus −0.29%, mobile −0.24%, city_4cif +0.01% neutral) — the monotone non-regression bar, not a mean.
• Cost: content-INDEPENDENT at 16-21 candidate evaluations per macroblock per frame across that corpus (1.3× spread) ≈ 1-2% of a busy-clip encode. The per-clip “blowups” (+251%, +34%) were wall-clock artifacts of a drifting box.

COST OF THE DEFAULT: encode() now returns a whole GOP’s access units at once (empty while the GOP fills), so end-to-end latency is up to gop_size frames and flush() is required at end of stream. Batch callers (encode_all) are unaffected — they already had the whole GOP.

mbtree_strength: f64

mb-tree QP-offset strength: qp_offset = -strength · log2((intra+propagate)/intra). Larger = more aggressive bit redistribution toward referenced MBs. Default 0.9.

mbtree_lookahead: LookaheadMode

Resolution the mb-tree lookahead motion search runs at (see LookaheadMode). Default HalfRes — fastest (~4× the lookahead), a small BD-rate cost on fine detail; use Hybrid to recover full-res quality at ~1.7×. Only relevant when mbtree is on.

Implementations

impl EncoderConfig

pub fn new(width: usize, height: usize) -> Self

A minimal all-intra Constrained Baseline configuration at the given size.

Examples found in repository

examples/rd_skip_speed.rs (line 58)

fn encode(frames: &[YuvFrame], w: usize, h: usize, rd_skip: bool) -> (f64, usize) {
    let mut cfg = EncoderConfig::new(w, h);
    cfg.qp = std::env::var("RS_QP").ok().and_then(|v| v.parse().ok()).unwrap_or(27);
    cfg.gop_size = 30;
    cfg.tune_rd_skip = rd_skip;
    cfg.tune_rd_skip_fast_t = std::env::var("RS_GATE").ok().and_then(|v| v.parse().ok());
    let mut enc = Encoder::new(cfg).expect("encoder");
    let t = std::time::Instant::now();
    let mut bytes = 0usize;
    for fr in frames {
        bytes += enc.encode(fr).len();
    }
    (t.elapsed().as_secs_f64(), bytes)
}

examples/bit_accountant.rs (line 51)

fn main() {
    let path = std::env::args().nth(1).unwrap_or_else(|| "video-tests/clips/foreman_cif.y4m".into());
    let n: usize = std::env::var("BA_FRAMES").ok().and_then(|v| v.parse().ok()).unwrap_or(24);
    let qp: u8 = std::env::var("BA_QP").ok().and_then(|v| v.parse().ok()).unwrap_or(27);
    let (w, h, frames) = read_y4m(&path, n);
    let name = std::path::Path::new(&path).file_stem().unwrap().to_string_lossy().to_string();
    for (pname, preset) in [("quality", Preset::Quality)] {
        let mut cfg = EncoderConfig::new(w, h);
        cfg.qp = qp;
        cfg.gop_size = 60;
        cfg.preset = preset;
        rusty_h264_encoder::bitacct::reset();
        rusty_h264_encoder::bitacct::set_enabled(true);
        let mut enc = Encoder::new(cfg).unwrap();
        let mut total = 0usize;
        for f in &frames {
            total += enc.encode(f).len();
        }
        rusty_h264_encoder::bitacct::add_actual_bytes(total);
        rusty_h264_encoder::bitacct::set_enabled(false);
        let mbs = (w.div_ceil(16) * h.div_ceil(16) * frames.len()) as u64;
        rusty_h264_encoder::bitacct::dump(
            &format!("{name} {pname} qp{qp} x{} ({} bytes)", frames.len(), total),
            mbs,
        );
        if std::env::var_os("BA_MVDTAB").is_some() {
            rusty_h264_encoder::bitacct::dump_mvd_table();
        }
    }
}

examples/thread_bench.rs (line 37)

fn main() {
    let path = std::env::args().nth(1).unwrap();
    let n: usize = std::env::var("TB_FRAMES").ok().and_then(|v| v.parse().ok()).unwrap_or(240);
    let gop: u32 = std::env::var("TB_GOP").ok().and_then(|v| v.parse().ok()).unwrap_or(30);
    let (w, h, frames) = read_y4m(&path, n);
    for (pn, preset) in [("balanced", Preset::Balanced), ("quality", Preset::Quality)] {
        let mut cfg = EncoderConfig::new(w, h);
        cfg.qp = 27; cfg.gop_size = gop; cfg.preset = preset;
        // best-of-3 each arm
        let mut seq_ms = f64::MAX; let mut seq_out = Vec::new();
        for _ in 0..3 {
            let mut enc = Encoder::new(cfg.clone()).unwrap();
            let t = std::time::Instant::now();
            let mut o = Vec::new();
            for f in &frames { o.extend_from_slice(&enc.encode(f)); }
            seq_ms = seq_ms.min(t.elapsed().as_secs_f64() * 1e3);
            seq_out = o;
        }
        let mut par_ms = f64::MAX; let mut par_out = Vec::new();
        for _ in 0..3 {
            let enc = Encoder::new(cfg.clone()).unwrap();
            let t = std::time::Instant::now();
            let o: Vec<u8> = enc.encode_all(&frames).unwrap().concat();
            par_ms = par_ms.min(t.elapsed().as_secs_f64() * 1e3);
            par_out = o;
        }
        assert_eq!(seq_out, par_out, "seq != parallel — compression WOULD be compromised");
        println!("{pn:<9} x{} gop{gop}: seq {seq_ms:.0} ms  parallel {par_ms:.0} ms  speedup {:.2}x  (byte-identical ✓)", frames.len(), seq_ms / par_ms);
    }
}

examples/me_snap_ab.rs (line 36)

fn main() {
    let a: Vec<String> = std::env::args().skip(1).collect();
    let (w, h) = a[1].split_once('x').unwrap();
    let (w, h): (usize, usize) = (w.parse().unwrap(), h.parse().unwrap());
    let frames = load(&a[0], w, h, std::env::var("RS_FRAMES").ok().and_then(|v| v.parse().ok()).unwrap_or(60));
    let preset = match std::env::var("RS_PRESET").unwrap_or_default().as_str() {
        "fast" => Preset::Fast, "quality" => Preset::Quality, _ => Preset::Balanced,
    };
    let arm_off: u32 = std::env::var("RS_ARM_OFF").ok().and_then(|v| v.parse().ok()).unwrap_or(0);
    let arm_on: u32 = std::env::var("RS_ARM_ON").ok().and_then(|v| v.parse().ok()).unwrap_or(3);
    let run = |on: bool| {
        let m = if on { arm_on } else { arm_off };
        let mut cfg = EncoderConfig::new(w, h);
        cfg.qp = std::env::var("RS_QP").ok().and_then(|v| v.parse().ok()).unwrap_or(27);
        cfg.gop_size = 30;
        cfg.preset = preset;
        cfg.tune_me_snap = m & 1 != 0;
        cfg.tune_me_subpel_iter = m & 2 != 0;
        let mut enc = Encoder::new(cfg).expect("enc");
        let t = std::time::Instant::now();
        let mut b = 0usize;
        for f in &frames { b += enc.encode(f).len(); }
        (t.elapsed().as_secs_f64(), b)
    };
    let mut best = [f64::MAX; 2];
    let mut bytes = [0usize; 2];
    for pass in 0..10 {
        let arm = pass % 2;
        let (t, b) = run(arm == 1);
        if t < best[arm] { best[arm] = t; }
        bytes[arm] = b;
    }
    let px = (w * h * frames.len()) as f64;
    println!("arm {arm_off} -> {arm_on} — {} {w}x{h} {} frames {preset:?}", a[0], frames.len());
    println!("  off : {:>7.1} ms  {:>6.2} Mpx/s  {:>9} bytes", best[0]*1e3, px/best[0]/1e6, bytes[0]);
    println!("  on  : {:>7.1} ms  {:>6.2} Mpx/s  {:>9} bytes", best[1]*1e3, px/best[1]/1e6, bytes[1]);
    println!("  speed {:>6.3}x   size {:>+6.2}%", best[0]/best[1],
             100.0*(bytes[1] as f64/bytes[0] as f64 - 1.0));
}

examples/mbtree_bench.rs (line 76)

fn main() {
    let path = std::env::args().nth(1).expect("usage: mbtree_bench <clip.y4m>");
    let env = |k: &str, d: usize| -> usize {
        std::env::var(k).ok().and_then(|v| v.parse().ok()).unwrap_or(d)
    };
    let (n, qp, gop, reps) = (env("MB_FRAMES", 48), env("MB_QP", 27), env("MB_GOP", 30), env("MB_REPS", 3));
    if let Ok(la) = std::env::var("MB_LA") {
        std::env::set_var("RFF_MBTREE_LA", la);
    }
    let (w, h, frames) = read_y4m(&path, n);
    println!("mbtree_bench {}x{} x{} qp{qp} gop{gop} (best-of-{reps})", w, h, frames.len());

    let mut off_ms = f64::MAX;
    let mut on_ms = f64::MAX;
    let (mut off_h, mut on_h, mut off_b, mut on_b) = (0u64, 0u64, 0usize, 0usize);
    let mut calls = 0u64;
    // Alternate the arms so thermal drift hits both equally.
    for _ in 0..reps {
        for on in [false, true] {
            let mut cfg = EncoderConfig::new(w, h);
            cfg.qp = qp as u8;
            cfg.gop_size = gop as u32;
            cfg.preset = Preset::Quality;
            cfg.mbtree = on;
            let enc = Encoder::new(cfg).expect("cfg");
            rusty_h264_encoder::mbtree_satd_reset();
            let t = std::time::Instant::now();
            let out: Vec<u8> = enc.encode_all(&frames).expect("encode").concat();
            let ms = t.elapsed().as_secs_f64() * 1e3;
            if on {
                on_ms = on_ms.min(ms);
                on_h = fnv1a(&out);
                on_b = out.len();
                calls = rusty_h264_encoder::mbtree_satd_calls();
            } else {
                off_ms = off_ms.min(ms);
                off_h = fnv1a(&out);
                off_b = out.len();
            }
        }
    }
    println!("  mbtree OFF: {off_ms:8.1} ms  {off_b:>8} bytes  hash {off_h:016x}");
    println!("  mbtree ON : {on_ms:8.1} ms  {on_b:>8} bytes  hash {on_h:016x}");
    println!(
        "  lookahead work: {calls} candidate evals ({:.0}/MB/frame, DETERMINISTIC)",
        calls as f64 / ((w / 16 * (h / 16)) as f64 * frames.len() as f64)
    );
    println!(
        "  lookahead overhead: {:+.1}%   size {:+.2}%",
        100.0 * (on_ms / off_ms - 1.0),
        100.0 * (on_b as f64 / off_b as f64 - 1.0)
    );
}

examples/me_oracle.rs (line 43)

fn main() {
    let a: Vec<String> = std::env::args().skip(1).collect();
    let (w, h) = a[1].split_once('x').unwrap();
    let (w, h): (usize, usize) = (w.parse().unwrap(), h.parse().unwrap());
    let nf: usize = std::env::var("RS_FRAMES").ok().and_then(|v| v.parse().ok()).unwrap_or(20);
    let frames = load(&a[0], w, h, nf);

    let preset = match std::env::var("RS_PRESET").unwrap_or_default().as_str() {
        "fast" => Preset::Fast,
        "quality" => Preset::Quality,
        _ => Preset::Balanced,
    };
    let mut cfg = EncoderConfig::new(w, h);
    cfg.qp = std::env::var("RS_QP").ok().and_then(|v| v.parse().ok()).unwrap_or(27);
    cfg.gop_size = 30;
    cfg.preset = preset;
    let mut enc = Encoder::new(cfg).expect("encoder");
    for f in &frames {
        let _ = enc.encode(f);
    }

    let p: Vec<u64> = rusty_h264_encoder::ME_PROBE
        .iter()
        .map(|c| c.load(std::sync::atomic::Ordering::Relaxed))
        .collect();
    let (n, ours, oracle, worse, evals) = (p[0].max(1), p[1], p[2], p[3], p[4]);
    let (oracle_sp, worse_sp) = (p[5], p[6]);
    println!("ME oracle — {} ({w}x{h}, {} frames, {preset:?})\n", a[0], frames.len());
    println!("  searches                {n}");
    println!("  mean cost   ours        {:>10.1}", ours as f64 / n as f64);
    println!("  mean cost   exhaustive  {:>10.1}", oracle as f64 / n as f64);
    println!("  ---> we are {:>6.2}% above the achievable minimum",
             100.0 * (ours as f64 - oracle as f64) / oracle as f64);
    println!("  searches the oracle beat {:>9} ({:.1}%)", worse, 100.0 * worse as f64 / n as f64);
    // the oracle's own 49x49 grid + 8 sub-pel probes are included in `evals`
    println!("
  + exhaustive SUB-PEL (all quarter-pel in +-3):");
    println!("  mean cost   exhaustive  {:>10.1}", oracle_sp as f64 / n as f64);
    println!("  ---> we are {:>6.2}% above the achievable minimum",
             100.0 * (ours as f64 - oracle_sp as f64) / oracle_sp as f64);
    println!("  searches it beat        {:>9} ({:.1}%)", worse_sp, 100.0 * worse_sp as f64 / n as f64);
    let oracle_evals = 0;
    println!("\n  cost() evals/search     {:>8.1}  (ours, oracle's {oracle_evals} excluded)",
             evals as f64 / n as f64 - oracle_evals as f64);
}

pub fn mb_width(&self) -> usize

Picture width rounded up to whole macroblocks.

pub fn mb_height(&self) -> usize

Picture height rounded up to whole macroblocks.

Trait Implementations

impl Clone for EncoderConfig

fn clone(&self) -> EncoderConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for EncoderConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.