Skip to main content

rff_codec_h264/
lib.rs

1//! H.264 / AVC video codec, backed by the pure-Rust
2//! [`rusty_h264`](https://crates.io/crates/rusty_h264) encoder + decoder.
3//!
4//! This is the **default** H.264 implementation: `register` is wired into the
5//! `rff` facade unconditionally, so `-c:v h264` decodes and encodes through
6//! `rusty_h264` with no C and no FFI. (The C `openh264` path still exists behind
7//! the opt-in `h264-openh264` feature and overrides this when enabled.)
8//!
9//! Bitstream is **Annex-B**, pixels are **YUV 4:2:0** — the same shape the
10//! openh264 path uses, so the MP4 demuxer's AVCC→Annex-B conversion upstream
11//! feeds this decoder directly. `rusty_h264`'s `default-features` are off here
12//! (no process-wide allocator, the portable scalar kernels); turn on this
13//! crate's `asm` feature for its portable Rust SIMD (SSE2/AVX2/NEON — no
14//! assembler, no C).
15//!
16//! # Encoder options
17//!
18//! `configure` reads the FFmpeg-shaped options the CLI forwards:
19//!
20//! - `-preset fast|medium|slow` — x264's ladder collapses onto `rusty_h264`'s
21//!   three: `ultrafast`..`fast` → `Fast`, `medium` → `Balanced`,
22//!   `slow`..`placebo` → `Quality`.
23//! - `-profile baseline|main|high`. `baseline` is **Constrained Baseline**:
24//!   CAVLC, no 8×8 transform, no B-frames, one reference, no lookahead, no
25//!   scene cut — the configuration a chip runs (`rusty_esp_video`'s
26//!   `chip_config`), so an `rff` encode on the host reproduces a device's
27//!   stream byte for byte at the same preset, GOP, bitrate and QP.
28//! - `-g N` (keyframe interval, also the minimum), `-b:v RATE`, `-qp Q`.
29//!
30//! # Buffering
31//!
32//! `rusty_h264` 0.12 runs a lookahead by default (mb-tree over a GOP): an
33//! `encode` call may return nothing, then a whole GOP of access units at once,
34//! and `flush` returns the tail. The adapter splits those into one packet per
35//! access unit and carries each frame's `pts` through the delay in order (no
36//! B-frames, so coding order is presentation order). Baseline turns the
37//! lookahead off, so it is one packet per frame with no delay.
38
39use std::collections::VecDeque;
40
41use rff_codec::{Codec, CodecParams, CodecRegistry, Decoder, Encoder};
42use rff_core::{Dictionary, Error, Frame, MediaType, Packet, PixelFormat, Result, VideoFrame};
43use rusty_h264::{
44    Decoder as RustyDecoder, Encoder as RustyEncoder, EncoderConfig, Preset, Profile, YuvFrame,
45};
46use std::panic::{catch_unwind, AssertUnwindSafe};
47
48/// Register the pure-Rust H.264 codec into a [`CodecRegistry`].
49pub fn register(registry: &mut CodecRegistry) {
50    registry.register(Codec {
51        id: rff_core::CodecId::H264,
52        name: "h264",
53        long_name: "H.264 / AVC / MPEG-4 AVC (pure-Rust rusty_h264)",
54        media_type: MediaType::Video,
55        decoder: Some(|| Box::new(H264Decoder::new())),
56        encoder: Some(|| Box::new(H264Encoder::new())),
57    });
58}
59
60fn map_err<E: std::fmt::Display>(e: E) -> Error {
61    Error::InvalidData(format!("rusty_h264: {e}"))
62}
63
64/// True if `data` begins with a 3- or 4-byte Annex-B start code.
65fn is_annex_b(data: &[u8]) -> bool {
66    data.starts_with(&[0, 0, 1]) || data.starts_with(&[0, 0, 0, 1])
67}
68
69/// Scan an Annex-B access unit for an IDR slice NAL (`nal_unit_type == 5`).
70fn au_has_idr(data: &[u8]) -> bool {
71    let mut i = 0;
72    while i + 3 < data.len() {
73        if data[i] == 0 && data[i + 1] == 0 && data[i + 2] == 1 {
74            if (data[i + 3] & 0x1f) == 5 {
75                return true;
76            }
77            i += 3;
78        } else {
79            i += 1;
80        }
81    }
82    false
83}
84
85/// Split an Annex-B stream into access units: each ends after a VCL
86/// (coded-slice) NAL, with the parameter-set / SEI NALs before it attached.
87/// `rusty_h264` codes one slice per picture and writes no AUDs, so this is
88/// exact for its output (it mirrors `rusty_h264_decoder::split_access_units`).
89fn split_access_units(stream: &[u8]) -> Vec<&[u8]> {
90    let mut codes: Vec<(usize, bool)> = Vec::new();
91    let mut i = 0;
92    while let Some(w) = stream.get(i..i + 3) {
93        if w[0] == 0 && w[1] == 0 && w[2] == 1 {
94            let nal_type = stream.get(i + 3).copied().unwrap_or(0) & 0x1f;
95            let is_vcl = matches!(nal_type, 1 | 5);
96            let sc = if i > 0 && stream.get(i - 1) == Some(&0) {
97                i - 1
98            } else {
99                i
100            };
101            codes.push((sc, is_vcl));
102            i += 3;
103        } else {
104            i += 1;
105        }
106    }
107    if codes.is_empty() {
108        return vec![stream];
109    }
110    let mut aus: Vec<&[u8]> = Vec::new();
111    let mut start = codes[0].0;
112    for k in 0..codes.len() {
113        if codes[k].1 {
114            let end = codes.get(k + 1).map_or(stream.len(), |c| c.0);
115            aus.push(&stream[start..end]);
116            start = end;
117        }
118    }
119    if start < stream.len() {
120        // Trailing non-VCL NALs (a parameter set with no picture yet): keep
121        // them with the last unit rather than losing them.
122        match aus.pop() {
123            Some(last) => {
124                let begin = last.as_ptr() as usize - stream.as_ptr() as usize;
125                aus.push(&stream[begin..]);
126            }
127            None => aus.push(stream),
128        }
129    }
130    aus
131}
132
133// ---------------------------------------------------------------------------
134// Decoder
135// ---------------------------------------------------------------------------
136
137/// The most pictures an H.264 decoded picture buffer holds (A.3.1, item h).
138const MAX_DPB_FRAMES: usize = 16;
139
140struct H264Decoder {
141    inner: RustyDecoder,
142    /// Out-of-band SPS/PPS (from `extradata`), prepended to the first packet if
143    /// it is itself Annex-B. AVCC `avcC` extradata is handled by the demuxer.
144    extradata: Vec<u8>,
145    started: bool,
146    /// Decoded pictures not yet output, each with its `PicOrderCnt` and the pts
147    /// of the packet that carried it. `rusty_h264` returns pictures in decode
148    /// order; they leave here in display order.
149    reorder: Vec<(i32, Frame)>,
150    /// How many pictures `reorder` holds before the lowest POC goes out: the
151    /// DPB size the active SPS's level allows (MaxDpbFrames). No conforming
152    /// stream reorders a picture past more pictures than that.
153    dpb_frames: usize,
154    queue: VecDeque<Frame>,
155    eof: bool,
156}
157
158impl H264Decoder {
159    fn new() -> H264Decoder {
160        H264Decoder {
161            inner: RustyDecoder::new(),
162            extradata: Vec::new(),
163            started: false,
164            reorder: Vec::new(),
165            dpb_frames: MAX_DPB_FRAMES,
166            queue: VecDeque::new(),
167            eof: false,
168        }
169    }
170
171    /// Output every buffered picture, in POC order: at an IDR (which starts a
172    /// new POC sequence) and at end of stream.
173    fn drain(&mut self) {
174        self.reorder.sort_by_key(|(poc, _)| *poc);
175        self.queue.extend(self.reorder.drain(..).map(|(_, f)| f));
176    }
177
178    /// Output the buffered picture with the lowest POC.
179    fn bump(&mut self) {
180        if let Some(i) = (0..self.reorder.len()).min_by_key(|&i| self.reorder[i].0) {
181            self.queue.push_back(self.reorder.remove(i).1);
182        }
183    }
184}
185
186impl Decoder for H264Decoder {
187    fn configure(&mut self, params: &CodecParams) -> Result<()> {
188        if is_annex_b(&params.extradata) {
189            self.extradata = params.extradata.clone();
190        }
191        Ok(())
192    }
193
194    fn send_packet(&mut self, packet: &Packet) -> Result<()> {
195        // Prepend Annex-B SPS/PPS once, ahead of the first coded packet.
196        let owned_au;
197        let data: &[u8] = if !self.started && !self.extradata.is_empty() {
198            self.started = true;
199            let mut au = std::mem::take(&mut self.extradata);
200            au.extend_from_slice(&packet.data);
201            owned_au = au;
202            &owned_au
203        } else {
204            self.started = true;
205            &packet.data
206        };
207
208        // One unit per coded slice, as `decode_stream` feeds `decode` (the
209        // decoder assembles a multi-slice picture across calls). `decode`
210        // returns pictures in decode order, so they are reordered here by POC
211        // with each packet's pts carried along: `decode_stream` only sorts
212        // within one call, which for one packet per access unit is nothing.
213        for au in split_access_units(data) {
214            if au_has_idr(au) {
215                self.drain();
216            }
217            if let Some(n) = nal_units(au)
218                .filter(|nal| nal.first().is_some_and(|b| b & 0x1f == 7))
219                .find_map(|nal| sps_max_dpb_frames(&unescape(&nal[1..])))
220            {
221                self.dpb_frames = n;
222            }
223
224            // Defense in depth: the decoder eats attacker-controlled bytes. It is fuzzed
225            // to never panic, but a bug here must never take down the host app — so catch
226            // any unwind, reset the decoder, and surface a decode error instead.
227            let inner = &mut self.inner;
228            let decoded = catch_unwind(AssertUnwindSafe(|| {
229                inner
230                    .decode(au)
231                    .map(|picture| picture.map(|yuv| (inner.last_poc(), yuv)))
232            }));
233            let picture = match decoded {
234                Ok(Ok(picture)) => picture,
235                Ok(Err(e)) => return Err(map_err(e)),
236                Err(_) => {
237                    self.inner = RustyDecoder::new();
238                    self.started = false;
239                    self.drain();
240                    return Err(Error::InvalidData(
241                        "rusty_h264: decoder panicked on malformed input (recovered)".into(),
242                    ));
243                }
244            };
245            if let Some((poc, yuv)) = picture {
246                self.reorder.push((poc, yuv_to_frame(yuv, packet.pts)));
247                while self.reorder.len() > self.dpb_frames {
248                    self.bump();
249                }
250            }
251        }
252        Ok(())
253    }
254
255    fn receive_frame(&mut self) -> Result<Frame> {
256        if let Some(frame) = self.queue.pop_front() {
257            return Ok(frame);
258        }
259        if self.eof {
260            Err(Error::Eof)
261        } else {
262            Err(Error::Again)
263        }
264    }
265
266    fn flush(&mut self) {
267        self.drain();
268        self.eof = true;
269    }
270}
271
272/// The NAL units of an Annex-B buffer, each without its start code.
273fn nal_units(data: &[u8]) -> impl Iterator<Item = &[u8]> {
274    let mut starts = Vec::new();
275    let mut i = 0;
276    while let Some(w) = data.get(i..i + 3) {
277        if w == [0, 0, 1] {
278            starts.push(i + 3);
279            i += 3;
280        } else {
281            i += 1;
282        }
283    }
284    let ends: Vec<usize> = starts
285        .iter()
286        .skip(1)
287        .map(|&s| s - 3)
288        .chain([data.len()])
289        .collect();
290    starts
291        .into_iter()
292        .zip(ends)
293        .map(move |(s, e)| &data[s..e.max(s)])
294}
295
296/// Remove emulation-prevention bytes (`00 00 03` -> `00 00`) from a NAL payload.
297fn unescape(nal: &[u8]) -> Vec<u8> {
298    let mut out = Vec::with_capacity(nal.len());
299    let mut zeros = 0;
300    for &b in nal {
301        if zeros >= 2 && b == 3 {
302            zeros = 0;
303            continue;
304        }
305        zeros = if b == 0 { zeros + 1 } else { 0 };
306        out.push(b);
307    }
308    out
309}
310
311/// A big-endian bit reader over an RBSP, with Exp-Golomb codes.
312struct Bits<'a> {
313    data: &'a [u8],
314    pos: usize,
315}
316
317impl Bits<'_> {
318    fn bit(&mut self) -> Option<u32> {
319        let byte = *self.data.get(self.pos / 8)?;
320        self.pos += 1;
321        Some(u32::from(byte >> (7 - (self.pos - 1) % 8)) & 1)
322    }
323
324    fn bits(&mut self, n: u32) -> Option<u32> {
325        (0..n).try_fold(0, |v, _| Some(v << 1 | self.bit()?))
326    }
327
328    fn ue(&mut self) -> Option<u32> {
329        let mut zeros = 0;
330        while self.bit()? == 0 {
331            zeros += 1;
332            if zeros > 31 {
333                return None;
334            }
335        }
336        Some(((1u64 << zeros) - 1 + u64::from(self.bits(zeros)?)) as u32)
337    }
338
339    fn se(&mut self) -> Option<i32> {
340        let k = self.ue()?;
341        Some(if k % 2 == 1 {
342            (k / 2 + 1) as i32
343        } else {
344            -((k / 2) as i32)
345        })
346    }
347}
348
349/// MaxDpbFrames for an SPS RBSP (after the NAL header byte):
350/// `min(MaxDpbMbs / (PicWidthInMbs * FrameHeightInMbs), 16)` with MaxDpbMbs
351/// from the level (Table A-1). A picture larger than its level allows, or an
352/// unknown level, gets the maximum of 16.
353fn sps_max_dpb_frames(rbsp: &[u8]) -> Option<usize> {
354    let mut r = Bits { data: rbsp, pos: 0 };
355    let profile_idc = r.bits(8)?;
356    let constraint_set3 = r.bits(8)? & 0x10 != 0;
357    let level_idc = r.bits(8)?;
358    r.ue()?; // seq_parameter_set_id
359    if matches!(
360        profile_idc,
361        100 | 110 | 122 | 244 | 44 | 83 | 86 | 118 | 128 | 138 | 139 | 134 | 135
362    ) {
363        let chroma_format_idc = r.ue()?;
364        if chroma_format_idc == 3 {
365            r.bit()?; // separate_colour_plane_flag
366        }
367        r.ue()?; // bit_depth_luma_minus8
368        r.ue()?; // bit_depth_chroma_minus8
369        r.bit()?; // qpprime_y_zero_transform_bypass_flag
370        if r.bit()? == 1 {
371            // seq_scaling_matrix_present_flag: skip each list that is present.
372            for i in 0..if chroma_format_idc == 3 { 12 } else { 8 } {
373                if r.bit()? == 1 {
374                    let (mut last, mut next) = (8i32, 8i32);
375                    for _ in 0..if i < 6 { 16 } else { 64 } {
376                        if next != 0 {
377                            next = (i64::from(last) + i64::from(r.se()?)).rem_euclid(256) as i32;
378                        }
379                        if next != 0 {
380                            last = next;
381                        }
382                    }
383                }
384            }
385        }
386    }
387    r.ue()?; // log2_max_frame_num_minus4
388    match r.ue()? {
389        0 => {
390            r.ue()?; // log2_max_pic_order_cnt_lsb_minus4
391        }
392        1 => {
393            r.bit()?; // delta_pic_order_always_zero_flag
394            r.se()?; // offset_for_non_ref_pic
395            r.se()?; // offset_for_top_to_bottom_field
396            for _ in 0..r.ue()?.min(255) {
397                r.se()?; // offset_for_ref_frame
398            }
399        }
400        _ => {}
401    }
402    r.ue()?; // max_num_ref_frames
403    r.bit()?; // gaps_in_frame_num_value_allowed_flag
404    let width_mbs = r.ue()? as usize + 1;
405    let height_map_units = r.ue()? as usize + 1;
406    let frame_mbs_only = r.bit()? == 1;
407    let frame_mbs = width_mbs
408        .saturating_mul(height_map_units)
409        .saturating_mul(if frame_mbs_only { 1 } else { 2 });
410    // Level 1b: level_idc 9, or 11 with constraint_set3 in Baseline/Main/Extended.
411    let level_1b = level_idc == 9
412        || (level_idc == 11 && constraint_set3 && matches!(profile_idc, 66 | 77 | 88));
413    let max_dpb_mbs: usize = match level_idc {
414        _ if level_1b => 396,
415        10 => 396,
416        11 => 900,
417        12 | 13 | 20 => 2376,
418        21 => 4752,
419        22 | 30 => 8100,
420        31 => 18000,
421        32 => 20480,
422        40 | 41 => 32768,
423        42 => 34816,
424        50 => 110400,
425        51 | 52 => 184320,
426        60..=62 => 696320,
427        _ => return Some(MAX_DPB_FRAMES),
428    };
429    Some(match max_dpb_mbs / frame_mbs {
430        0 => MAX_DPB_FRAMES,
431        n => n.min(MAX_DPB_FRAMES),
432    })
433}
434
435/// Map a `rusty_h264` [`YuvFrame`] (tight I420 planes) to an rff [`VideoFrame`].
436fn yuv_to_frame(f: YuvFrame, pts: Option<i64>) -> Frame {
437    let (w, h) = (f.width, f.height);
438    Frame::Video(VideoFrame {
439        width: w as u32,
440        height: h as u32,
441        format: PixelFormat::Yuv420p,
442        planes: vec![f.y, f.u, f.v],
443        strides: vec![w, w / 2, w / 2],
444        pts,
445    })
446}
447
448// ---------------------------------------------------------------------------
449// Encoder
450// ---------------------------------------------------------------------------
451
452/// What `configure` collected; applied when the first frame fixes the geometry.
453#[derive(Debug, Clone, Copy, PartialEq, Default)]
454struct Settings {
455    preset: Option<Preset>,
456    profile: Option<Profile>,
457    /// `-g`: keyframe interval (and minimum).
458    keyint: Option<u32>,
459    /// `-b:v`, bits per second.
460    bitrate: Option<u32>,
461    /// `-qp` / `-crf`.
462    qp: Option<u8>,
463}
464
465impl Settings {
466    /// The chip configuration for Constrained Baseline:
467    /// [`EncoderConfig::baseline`], the one constructor the host and the
468    /// device (`rusty_esp_video::h264::chip_config`) share, so an rff encode
469    /// with `-profile baseline -preset fast` is the byte-for-byte oracle for
470    /// a device stream. The geometry is kept; `-preset`, `-g`, `-b:v` and
471    /// `-qp` are applied on top afterwards.
472    fn baseline(cfg: &mut EncoderConfig) {
473        *cfg = EncoderConfig::baseline(cfg.width, cfg.height);
474    }
475
476    fn apply(&self, cfg: &mut EncoderConfig) {
477        match self.profile {
478            Some(Profile::ConstrainedBaseline | Profile::Baseline) => Self::baseline(cfg),
479            Some(Profile::Main) => {
480                cfg.profile = Profile::Main;
481                cfg.transform_8x8 = false;
482            }
483            Some(other) => cfg.profile = other,
484            None => {}
485        }
486        if let Some(p) = self.preset {
487            cfg.preset = p;
488        }
489        if let Some(g) = self.keyint {
490            cfg.gop_size = g;
491            cfg.min_keyint = g;
492        }
493        if let Some(b) = self.bitrate {
494            cfg.bitrate = b;
495        }
496        if let Some(q) = self.qp {
497            cfg.qp = q;
498        }
499    }
500}
501
502struct H264Encoder {
503    inner: Option<RustyEncoder>,
504    settings: Settings,
505    /// `pts` of every frame sent and not yet emitted, in coding order.
506    pending_pts: VecDeque<Option<i64>>,
507    queue: VecDeque<Packet>,
508    eof: bool,
509}
510
511impl H264Encoder {
512    fn new() -> H264Encoder {
513        H264Encoder {
514            inner: None,
515            settings: Settings::default(),
516            pending_pts: VecDeque::new(),
517            queue: VecDeque::new(),
518            eof: false,
519        }
520    }
521
522    /// Turn a (possibly multi-AU) encoder return into packets.
523    fn emit(&mut self, stream: &[u8]) {
524        if stream.is_empty() {
525            return;
526        }
527        for au in split_access_units(stream) {
528            let mut packet = Packet::from_data(0, au.to_vec());
529            packet.flags.keyframe = au_has_idr(au);
530            packet.pts = self.pending_pts.pop_front().flatten();
531            packet.dts = packet.pts;
532            self.queue.push_back(packet);
533        }
534    }
535}
536
537fn parse_preset(v: &str) -> Result<Preset> {
538    Ok(match v.trim().to_ascii_lowercase().as_str() {
539        "ultrafast" | "superfast" | "veryfast" | "faster" | "fast" => Preset::Fast,
540        "medium" | "balanced" => Preset::Balanced,
541        "slow" | "slower" | "veryslow" | "placebo" | "quality" => Preset::Quality,
542        _ => {
543            return Err(Error::unsupported(format!(
544                "h264 encode: -preset `{v}` (use fast|medium|slow)"
545            )))
546        }
547    })
548}
549
550fn parse_profile(v: &str) -> Result<Profile> {
551    Ok(match v.trim().to_ascii_lowercase().as_str() {
552        "baseline" | "constrained_baseline" | "constrained-baseline" => {
553            Profile::ConstrainedBaseline
554        }
555        "main" => Profile::Main,
556        "high" => Profile::High,
557        _ => {
558            return Err(Error::unsupported(format!(
559                "h264 encode: -profile `{v}` (use baseline|main|high)"
560            )))
561        }
562    })
563}
564
565impl Encoder for H264Encoder {
566    fn configure(&mut self, options: &Dictionary) -> Result<()> {
567        if let Some(v) = options.get("preset") {
568            self.settings.preset = Some(parse_preset(v)?);
569        }
570        if let Some(v) = options.get("profile") {
571            self.settings.profile = Some(parse_profile(v)?);
572        }
573        if let Some(v) = options.get("g") {
574            let g = v
575                .trim()
576                .parse::<u32>()
577                .ok()
578                .filter(|g| *g > 0)
579                .ok_or_else(|| {
580                    Error::unsupported(format!(
581                        "h264 encode: -g wants a positive frame count, got `{v}`"
582                    ))
583                })?;
584            self.settings.keyint = Some(g);
585        }
586        if let Some(b) = options.get_bitrate("b") {
587            self.settings.bitrate = Some(b.clamp(0, i64::from(u32::MAX)) as u32);
588        }
589        for key in ["qp", "crf"] {
590            if let Some(v) = options.get(key) {
591                let q = v
592                    .trim()
593                    .parse::<u8>()
594                    .ok()
595                    .filter(|q| *q <= 51)
596                    .ok_or_else(|| {
597                        Error::unsupported(format!("h264 encode: -{key} wants 0..51, got `{v}`"))
598                    })?;
599                self.settings.qp = Some(q);
600            }
601        }
602        Ok(())
603    }
604
605    fn send_frame(&mut self, frame: &Frame) -> Result<()> {
606        let vf = match frame {
607            Frame::Video(v) => v,
608            Frame::Audio(_) => {
609                return Err(Error::unsupported(
610                    "h264 encode: audio frame on a video codec",
611                ))
612            }
613        };
614        if vf.format != PixelFormat::Yuv420p {
615            return Err(Error::unsupported(format!(
616                "h264 encode: needs yuv420p, got `{}`",
617                vf.format.name()
618            )));
619        }
620        let (w, h) = (vf.width as usize, vf.height as usize);
621        if w == 0 || h == 0 || w % 2 != 0 || h % 2 != 0 {
622            return Err(Error::unsupported(
623                "h264 encode: dimensions must be even and non-zero",
624            ));
625        }
626
627        // rusty_h264 wants tight (stride == width) planes; copy row by row to
628        // strip any padding the upstream frame carries.
629        let yuv = YuvFrame {
630            width: w,
631            height: h,
632            y: tighten(&vf.planes[0], vf.strides[0], w, h),
633            u: tighten(&vf.planes[1], vf.strides[1], w / 2, h / 2),
634            v: tighten(&vf.planes[2], vf.strides[2], w / 2, h / 2),
635        };
636
637        if self.inner.is_none() {
638            let mut cfg = EncoderConfig::new(w, h);
639            self.settings.apply(&mut cfg);
640            self.inner = Some(RustyEncoder::new(cfg).map_err(map_err)?);
641        }
642        let enc = self.inner.as_mut().expect("created above");
643        self.pending_pts.push_back(vf.pts);
644        let out = enc.try_encode(&yuv).map_err(map_err)?;
645        self.emit(&out);
646        Ok(())
647    }
648
649    fn receive_packet(&mut self) -> Result<Packet> {
650        if let Some(packet) = self.queue.pop_front() {
651            return Ok(packet);
652        }
653        if self.eof {
654            Err(Error::Eof)
655        } else {
656            Err(Error::Again)
657        }
658    }
659
660    fn flush(&mut self) {
661        if let Some(enc) = self.inner.as_mut() {
662            let tail = enc.flush();
663            self.emit(&tail);
664        }
665        self.eof = true;
666    }
667}
668
669/// Copy `rows` rows of `width` bytes out of a (possibly padded) plane into a
670/// tight, contiguous `width * rows` buffer.
671fn tighten(plane: &[u8], stride: usize, width: usize, rows: usize) -> Vec<u8> {
672    if stride == width {
673        return plane[..width * rows].to_vec();
674    }
675    let mut out = Vec::with_capacity(width * rows);
676    for r in 0..rows {
677        let s = r * stride;
678        out.extend_from_slice(&plane[s..s + width]);
679    }
680    out
681}
682
683#[cfg(test)]
684mod tests {
685    use super::*;
686
687    fn grey_frame(w: u32, h: u32, luma: u8, pts: i64) -> Frame {
688        let (wi, hi) = (w as usize, h as usize);
689        Frame::Video(VideoFrame {
690            width: w,
691            height: h,
692            format: PixelFormat::Yuv420p,
693            planes: vec![
694                vec![luma; wi * hi],
695                vec![128u8; (wi / 2) * (hi / 2)],
696                vec![128u8; (wi / 2) * (hi / 2)],
697            ],
698            strides: vec![wi, wi / 2, wi / 2],
699            pts: Some(pts),
700        })
701    }
702
703    fn drain(enc: &mut H264Encoder) -> Vec<Packet> {
704        let mut v = Vec::new();
705        while let Ok(p) = enc.receive_packet() {
706            v.push(p);
707        }
708        v
709    }
710
711    /// `(profile_idc, constraint_set flags)` from the SPS in an access unit.
712    fn sps_profile(au: &[u8]) -> (u8, u8) {
713        let mut i = 0;
714        while i + 5 < au.len() {
715            if au[i] == 0 && au[i + 1] == 0 && au[i + 2] == 1 && au[i + 3] & 0x1f == 7 {
716                return (au[i + 4], au[i + 5]);
717            }
718            i += 1;
719        }
720        panic!("no SPS in the access unit");
721    }
722
723    #[test]
724    fn encode_decode_roundtrip() {
725        let (w, h) = (64u32, 48u32);
726        let mut enc = H264Encoder::new();
727        enc.send_frame(&grey_frame(w, h, 128, 0)).unwrap();
728        enc.flush();
729        let packets = drain(&mut enc);
730        assert_eq!(packets.len(), 1);
731        let packet = &packets[0];
732        assert!(!packet.data.is_empty());
733        assert!(packet.flags.keyframe, "first frame must be an IDR");
734        assert_eq!(packet.pts, Some(0));
735
736        let mut dec = H264Decoder::new();
737        dec.send_packet(packet).unwrap();
738        dec.flush();
739        match dec.receive_frame().unwrap() {
740            Frame::Video(v) => {
741                assert_eq!((v.width, v.height), (w, h));
742                assert_eq!(v.format, PixelFormat::Yuv420p);
743            }
744            Frame::Audio(_) => panic!("expected a video frame"),
745        }
746    }
747
748    /// The default configuration runs a lookahead: frames buffer, then come
749    /// out together. Every frame must still become exactly one packet, in
750    /// order, with its own `pts`.
751    #[test]
752    fn lookahead_buffering_yields_one_packet_per_frame_with_its_pts() {
753        let (w, h) = (64u32, 48u32);
754        let mut enc = H264Encoder::new();
755        let n = 12;
756        for i in 0..n {
757            enc.send_frame(&grey_frame(w, h, 100 + i as u8 * 5, i as i64 * 40))
758                .unwrap();
759        }
760        enc.flush();
761        let packets = drain(&mut enc);
762        assert_eq!(packets.len(), n, "one packet per frame after flush");
763        for (i, p) in packets.iter().enumerate() {
764            assert_eq!(
765                p.pts,
766                Some(i as i64 * 40),
767                "packet {i} keeps its frame's pts"
768            );
769            assert!(!p.data.is_empty());
770        }
771        assert!(packets[0].flags.keyframe);
772        // The decoder agrees on the count.
773        let mut dec = H264Decoder::new();
774        for p in &packets {
775            dec.send_packet(p).unwrap();
776        }
777        dec.flush();
778        let mut frames = 0;
779        while dec.receive_frame().is_ok() {
780            frames += 1;
781        }
782        assert_eq!(frames, n);
783    }
784
785    /// `-profile baseline -preset fast -g 30`: the chip configuration. The
786    /// stream must say Constrained Baseline (profile_idc 66 with
787    /// constraint_set1) and come out one packet per frame with no delay.
788    #[test]
789    fn baseline_profile_is_constrained_baseline_and_unbuffered() {
790        let mut opts = Dictionary::new();
791        opts.set("profile", "baseline");
792        opts.set("preset", "fast");
793        opts.set("g", "30");
794        opts.set("b", "500k");
795        opts.set("qp", "28");
796        let mut enc = H264Encoder::new();
797        enc.configure(&opts).unwrap();
798        for i in 0..3 {
799            enc.send_frame(&grey_frame(64, 48, 90, i)).unwrap();
800            let got = drain(&mut enc);
801            assert_eq!(got.len(), 1, "frame {i}: no lookahead delay");
802            if i == 0 {
803                let (profile_idc, flags) = sps_profile(&got[0].data);
804                assert_eq!(profile_idc, 66, "Baseline profile_idc");
805                assert_ne!(flags & 0x40, 0, "constraint_set1_flag: Constrained");
806            }
807        }
808        enc.flush();
809        assert!(drain(&mut enc).is_empty());
810        let cfg = enc.inner.as_ref().unwrap().config();
811        assert_eq!(cfg.profile, Profile::ConstrainedBaseline);
812        assert!(!cfg.cabac && !cfg.transform_8x8 && cfg.bframes == 0);
813        assert_eq!((cfg.num_ref_frames, cfg.lookahead, cfg.scenecut), (1, 0, 0));
814        assert_eq!((cfg.gop_size, cfg.min_keyint), (30, 30));
815        assert_eq!(
816            (cfg.bitrate, cfg.qp, cfg.preset),
817            (500_000, 28, Preset::Fast)
818        );
819    }
820
821    /// A frame with enough texture that every macroblock codes something.
822    fn textured_frame(w: u32, h: u32, t: i64) -> Frame {
823        let (wi, hi) = (w as usize, h as usize);
824        let mut y = vec![0u8; wi * hi];
825        for r in 0..hi {
826            for c in 0..wi {
827                y[r * wi + c] = ((c * 3 + r * 5 + (t as usize) * 11) ^ ((r & 7) * 9)) as u8;
828            }
829        }
830        let (cw, ch) = (wi / 2, hi / 2);
831        let u: Vec<u8> = (0..cw * ch)
832            .map(|i| (96 + (i * 7 + t as usize * 3) % 64) as u8)
833            .collect();
834        let v: Vec<u8> = (0..cw * ch)
835            .map(|i| (160 - (i * 5 + t as usize * 2) % 48) as u8)
836            .collect();
837        Frame::Video(VideoFrame {
838            width: w,
839            height: h,
840            format: PixelFormat::Yuv420p,
841            planes: vec![y, u, v],
842            strides: vec![wi, cw, cw],
843            pts: Some(t),
844        })
845    }
846
847    /// `-profile baseline -preset fast`: an rff encode is the chip
848    /// configuration byte for byte — the same bytes `rusty_h264` produces
849    /// from `EncoderConfig::baseline` directly. This is the host oracle a
850    /// device stream is compared against.
851    #[test]
852    fn baseline_encode_is_byte_identical_to_encoder_config_baseline() {
853        let (w, h) = (64u32, 48u32);
854        let frames: Vec<Frame> = (0..6).map(|t| textured_frame(w, h, t)).collect();
855
856        let mut opts = Dictionary::new();
857        opts.set("profile", "baseline");
858        opts.set("preset", "fast");
859        opts.set("g", "4");
860        opts.set("qp", "26");
861        let mut enc = H264Encoder::new();
862        enc.configure(&opts).unwrap();
863        let mut via_rff = Vec::new();
864        for f in &frames {
865            enc.send_frame(f).unwrap();
866            for p in drain(&mut enc) {
867                via_rff.extend_from_slice(&p.data);
868            }
869        }
870        enc.flush();
871        for p in drain(&mut enc) {
872            via_rff.extend_from_slice(&p.data);
873        }
874
875        let mut cfg = EncoderConfig::baseline(w as usize, h as usize);
876        cfg.gop_size = 4;
877        cfg.min_keyint = 4;
878        cfg.qp = 26;
879        let mut direct = RustyEncoder::new(cfg).unwrap();
880        let mut via_lib = Vec::new();
881        for f in &frames {
882            let Frame::Video(vf) = f else { unreachable!() };
883            let yuv = YuvFrame {
884                width: w as usize,
885                height: h as usize,
886                y: vf.planes[0].clone(),
887                u: vf.planes[1].clone(),
888                v: vf.planes[2].clone(),
889            };
890            via_lib.extend_from_slice(&direct.encode_planes(&yuv.as_planes()).unwrap());
891        }
892        via_lib.extend_from_slice(&direct.flush());
893
894        assert!(via_rff.len() > 6 * 8, "the stream has bytes");
895        assert_eq!(via_rff, via_lib, "rff baseline != EncoderConfig::baseline");
896    }
897
898    #[test]
899    fn bad_options_are_refused_up_front() {
900        let mut enc = H264Encoder::new();
901        let mut opts = Dictionary::new();
902        opts.set("preset", "warp");
903        assert!(enc.configure(&opts).is_err());
904        let mut opts = Dictionary::new();
905        opts.set("profile", "extended");
906        assert!(enc.configure(&opts).is_err());
907        let mut opts = Dictionary::new();
908        opts.set("qp", "99");
909        assert!(enc.configure(&opts).is_err());
910        let mut opts = Dictionary::new();
911        opts.set("preset", "veryslow");
912        opts.set("profile", "high");
913        assert!(enc.configure(&opts).is_ok());
914        assert_eq!(enc.settings.preset, Some(Preset::Quality));
915    }
916
917    #[test]
918    fn access_unit_splitter_keeps_parameter_sets_with_their_picture() {
919        let mut s = Vec::new();
920        for nal in [
921            &[0x67u8, 1][..],
922            &[0x68, 2],
923            &[0x65, 3, 4],
924            &[0x41, 5],
925            &[0x67, 6],
926        ] {
927            s.extend_from_slice(&[0, 0, 0, 1]);
928            s.extend_from_slice(nal);
929        }
930        let aus = split_access_units(&s);
931        assert_eq!(aus.len(), 2);
932        assert_eq!(aus[0], &s[..19], "SPS + PPS + IDR");
933        assert_eq!(
934            aus[1],
935            &s[19..],
936            "P slice, then the trailing SPS stays attached"
937        );
938        assert_eq!(split_access_units(b"junk"), vec![&b"junk"[..]]);
939    }
940
941    /// x264 `-bf 3 -b-pyramid normal -g 12`, 176x144, 24 frames (two IDR GOPs),
942    /// level 1.1, so MaxDpbFrames is 900 / 99 = 9: fewer than a GOP holds.
943    /// Made with `ffmpeg -f lavfi -i testsrc2=size=176x144:rate=24 -frames:v 24
944    /// -c:v libx264 -preset medium -crf 38 -bf 3 -b-pyramid normal -g 12
945    /// -keyint_min 12 -sc_threshold 0 -pix_fmt yuv420p -f h264`.
946    const BFRAMES: &[u8] = include_bytes!("../tests/data/bframes_176x144.h264");
947
948    /// FNV-1a of each picture ffmpeg decodes from [`BFRAMES`], in display order
949    /// (`ffmpeg -i bframes_176x144.h264 -f rawvideo -pix_fmt yuv420p -`).
950    const BFRAMES_DISPLAY: [u64; 24] = [
951        0x15e29badd4eb8e08,
952        0x72640f215a155445,
953        0x7f580929a7eef9d1,
954        0x0a8262f42b2f6b70,
955        0xf1e465e9834c894c,
956        0x91357b6fd4332930,
957        0x7f6628047705acdc,
958        0xfaa17a10be9a607f,
959        0x08ac87e85c1a5cec,
960        0x9f033116b8255cdf,
961        0x0cf43d259bb28793,
962        0xa5c9eecb4f7ee06d,
963        0x65d656843a43c28c,
964        0x463d32b3ca767158,
965        0x456a585faf00718b,
966        0xacc19d4449f32e2e,
967        0xe44da1e1fa26c7d8,
968        0x257e7d4cf472e14a,
969        0xbde9630f2e843b5f,
970        0x313ace733a793c54,
971        0x244f359922302dab,
972        0xa5842b6a0ad889f9,
973        0x735a9b902015b3dd,
974        0xdaf2b558bf05b79f,
975    ];
976
977    /// 64-bit FNV-1a over a picture's tightly packed Y, U and V planes.
978    fn fingerprint(frame: &Frame) -> u64 {
979        let Frame::Video(v) = frame else {
980            panic!("not a video frame")
981        };
982        v.planes
983            .iter()
984            .flatten()
985            .fold(0xcbf2_9ce4_8422_2325, |h, &b| {
986                (h ^ u64::from(b)).wrapping_mul(0x100_0000_01b3)
987            })
988    }
989
990    #[test]
991    fn pictures_come_out_in_display_order_with_their_packets_pts() {
992        let aus = split_access_units(BFRAMES);
993        assert_eq!(aus.len(), 24);
994        // The picture each access unit decodes to, in decode order.
995        let mut core = RustyDecoder::new();
996        let decode_order: Vec<u64> = aus
997            .iter()
998            .map(|au| fingerprint(&yuv_to_frame(core.decode(au).unwrap().unwrap(), None)))
999            .collect();
1000        assert_ne!(decode_order, BFRAMES_DISPLAY, "the stream reorders");
1001
1002        // One access unit per packet, as a demuxer hands them over, stamped with
1003        // its decode index.
1004        let mut dec = H264Decoder::new();
1005        let mut out = Vec::new();
1006        for (k, au) in aus.iter().enumerate() {
1007            if k == 12 {
1008                // Before the second IDR: 12 pictures decoded, the level's 9 held.
1009                assert_eq!(dec.dpb_frames, 9);
1010                assert_eq!(out.len(), 3);
1011            }
1012            let mut packet = Packet::from_data(0, au.to_vec());
1013            packet.pts = Some(k as i64);
1014            dec.send_packet(&packet).unwrap();
1015            while let Ok(frame) = dec.receive_frame() {
1016                out.push(frame);
1017            }
1018        }
1019        dec.flush();
1020        while let Ok(frame) = dec.receive_frame() {
1021            out.push(frame);
1022        }
1023
1024        let got: Vec<u64> = out.iter().map(fingerprint).collect();
1025        assert_eq!(got, BFRAMES_DISPLAY, "ffmpeg's display order");
1026        // Every picture keeps the pts of the packet that carried it.
1027        let pts: Vec<Option<i64>> = out
1028            .iter()
1029            .map(|f| match f {
1030                Frame::Video(v) => v.pts,
1031                _ => None,
1032            })
1033            .collect();
1034        let carried: Vec<Option<i64>> = got
1035            .iter()
1036            .map(|h| decode_order.iter().position(|d| d == h).map(|k| k as i64))
1037            .collect();
1038        assert_eq!(pts, carried);
1039    }
1040
1041    #[test]
1042    fn malformed_packets_never_crash() {
1043        // A decoder eats attacker-controlled bytes; send_packet must return Ok/Err for
1044        // ANY input, never unwind out of the codec. The catch_unwind boundary makes even
1045        // a hypothetical decoder panic a recoverable error (and resets the decoder).
1046        let mut rng = 0x1234_5678_9abc_def0u64;
1047        let mut next = || {
1048            rng ^= rng << 13;
1049            rng ^= rng >> 7;
1050            rng ^= rng << 17;
1051            rng
1052        };
1053        let mut dec = H264Decoder::new();
1054        for _ in 0..4000 {
1055            let len = (next() % 256) as usize;
1056            let data: Vec<u8> = (0..len).map(|_| next() as u8).collect();
1057            // A panic here would unwind and fail the test; a graceful Ok/Err passes.
1058            let _ = dec.send_packet(&Packet::from_data(0, data));
1059            let _ = dec.receive_frame();
1060        }
1061    }
1062}