Skip to main content

threers_codec/h264/
encoder.rs

1//! Frame-level H.264 encoder: pixels in, Annex-B byte stream or MP4 out.
2//!
3//! [`H264Encoder`] emits SPS/PPS once, then an IDR slice per frame. Baseline
4//! profile with CAVLC `I_PCM` macroblocks (lossless in the YUV domain) — the
5//! same proving strategy as the HEVC encoder.
6
7use crate::captions::CaptionTrack;
8use crate::h264::avcc::build_avcc;
9use crate::h264::nal::{nal_unit_base, push_annexb, split_annexb, NalUnitType};
10use crate::h264::params::{write_sps, H264Config, MB_SIZE};
11use crate::h264::pps::write_pps;
12use crate::h264::slice::{idr_slice_rbsp, PaddedYuv};
13use crate::hevc::encoder::{pad_plane, Yuv420Frame};
14use crate::mp4::{mux_h264, mux_h264_with_captions, H264Mp4Params};
15
16/// A from-scratch H.264 encoder (IDR-only, `I_PCM`).
17pub struct H264Encoder {
18    cfg: H264Config,
19    headers_emitted: bool,
20    sps: Vec<u8>,
21    pps: Vec<u8>,
22}
23
24impl H264Encoder {
25    /// An I_PCM encoder for `width × height` frames.
26    pub fn new(width: u32, height: u32) -> Self {
27        let cfg = H264Config::new(width, height);
28        let sps = nal_unit_base(NalUnitType::Sps, &write_sps(&cfg));
29        let pps = nal_unit_base(NalUnitType::Pps, &write_pps());
30        Self {
31            cfg,
32            headers_emitted: false,
33            sps,
34            pps,
35        }
36    }
37
38    /// The configuration the parameter sets describe.
39    pub fn config(&self) -> &H264Config {
40        &self.cfg
41    }
42
43    /// SPS NAL (1-byte header + EBSP) for muxing.
44    pub fn sps(&self) -> &[u8] {
45        &self.sps
46    }
47
48    /// PPS NAL for muxing.
49    pub fn pps(&self) -> &[u8] {
50        &self.pps
51    }
52
53    /// `avcC` payload built from this encoder's parameter sets.
54    pub fn avcc(&self) -> Vec<u8> {
55        build_avcc(&self.sps, &self.pps)
56    }
57
58    /// Encode one 4:2:0 frame, returning its Annex-B access unit.
59    pub fn encode_frame(&mut self, frame: &Yuv420Frame) -> Vec<u8> {
60        assert_eq!(
61            (frame.width, frame.height),
62            (self.cfg.width, self.cfg.height),
63            "frame size differs from encoder size"
64        );
65        let (cw, ch) = (self.cfg.coded_width, self.cfg.coded_height);
66        let y = pad_plane(&frame.y, frame.width, frame.height, cw, ch);
67        let u = pad_plane(&frame.u, frame.width / 2, frame.height / 2, cw / 2, ch / 2);
68        let v = pad_plane(&frame.v, frame.width / 2, frame.height / 2, cw / 2, ch / 2);
69        let padded = PaddedYuv {
70            y: &y,
71            u: &u,
72            v: &v,
73            coded_width: cw,
74            coded_height: ch,
75        };
76        self.assemble_au(&padded)
77    }
78
79    fn assemble_au(&mut self, padded: &PaddedYuv) -> Vec<u8> {
80        let slice = idr_slice_rbsp(&self.cfg, padded);
81        let mut au = Vec::new();
82        if !self.headers_emitted {
83            push_annexb(&mut au, &self.sps);
84            push_annexb(&mut au, &self.pps);
85            self.headers_emitted = true;
86        }
87        push_annexb(&mut au, &nal_unit_base(NalUnitType::Idr, &slice));
88        au
89    }
90
91    /// Turn one Annex-B access unit into an MP4 sample (length-prefixed NALs).
92    pub fn sample_from_au(au: &[u8]) -> Vec<u8> {
93        let mut sample = Vec::new();
94        for nal in split_annexb(au) {
95            let t = nal[0] & 0x1F;
96            if t == NalUnitType::Sps.code() || t == NalUnitType::Pps.code() {
97                continue;
98            }
99            sample.extend_from_slice(&(nal.len() as u32).to_be_bytes());
100            sample.extend_from_slice(&nal);
101        }
102        sample
103    }
104}
105
106/// Encode `frames` of YUV420 pictures into an MP4 byte stream.
107pub fn encode_mp4(width: u32, height: u32, fps: u32, frames: &[Yuv420Frame]) -> Vec<u8> {
108    encode_mp4_with_captions(width, height, fps, frames, None)
109}
110
111/// Like [`encode_mp4`], optionally muxing a soft `tx3g` caption track.
112pub fn encode_mp4_with_captions(
113    width: u32,
114    height: u32,
115    fps: u32,
116    frames: &[Yuv420Frame],
117    captions: Option<&CaptionTrack>,
118) -> Vec<u8> {
119    encode_mp4_from_iter(width, height, fps, captions, frames.iter().cloned())
120}
121
122/// [`encode_mp4`] over an iterator of frames, so the caller can generate them
123/// lazily and never hold more than one.
124pub fn encode_mp4_from_iter<I>(
125    width: u32,
126    height: u32,
127    fps: u32,
128    captions: Option<&CaptionTrack>,
129    frames: I,
130) -> Vec<u8>
131where
132    I: IntoIterator<Item = Yuv420Frame>,
133{
134    encode_mp4_inner(width, height, fps, captions, &mut frames.into_iter())
135}
136
137/// [`encode_mp4`] pulling one frame at a time instead of taking them all up
138/// front.
139///
140/// A 4:2:0 frame is `width * height * 1.5` bytes, so at 4K or 8K the source
141/// frames dwarf everything else the encoder touches — ten seconds of 8K at 24fps
142/// is roughly 12 GB of them. Nothing needs them to coexist: the muxer wants the
143/// *encoded* samples, and those are orders of magnitude smaller. `next` is
144/// called once per frame index, in order.
145pub fn encode_mp4_streaming<F>(
146    width: u32,
147    height: u32,
148    fps: u32,
149    frame_count: usize,
150    captions: Option<&CaptionTrack>,
151    next: F,
152) -> Vec<u8>
153where
154    F: FnMut(usize) -> Yuv420Frame,
155{
156    encode_mp4_inner(
157        width,
158        height,
159        fps,
160        captions,
161        &mut (0..frame_count).map(next),
162    )
163}
164
165/// [`encode_mp4_from_iter`] written straight to a sink.
166///
167/// Combined with a lazy `frames`, nothing ever holds the whole clip *or* the
168/// whole file: peak memory is one frame plus the encoded samples.
169pub fn write_mp4_from_iter<W, I>(
170    out: &mut W,
171    width: u32,
172    height: u32,
173    fps: u32,
174    captions: Option<&CaptionTrack>,
175    frames: I,
176) -> std::io::Result<()>
177where
178    W: std::io::Write,
179    I: IntoIterator<Item = Yuv420Frame>,
180{
181    let fps = fps.max(1);
182    let timescale = 600u32;
183    let mut enc = H264Encoder::new(width, height);
184    let avcc = enc.avcc();
185    let mut samples = Vec::new();
186    for f in frames {
187        samples.push(H264Encoder::sample_from_au(&enc.encode_frame(&f)));
188    }
189    let params = H264Mp4Params {
190        width,
191        height,
192        timescale,
193        frame_duration: timescale / fps,
194        avcc_payload: &avcc,
195        samples: &samples,
196    };
197    crate::mp4::write_h264(out, &params, captions.filter(|t| !t.is_empty()))
198}
199
200fn encode_mp4_inner(
201    width: u32,
202    height: u32,
203    fps: u32,
204    captions: Option<&CaptionTrack>,
205    frames: &mut dyn Iterator<Item = Yuv420Frame>,
206) -> Vec<u8> {
207    let fps = fps.max(1);
208    let timescale = 600u32;
209    let frame_duration = timescale / fps;
210    let mut enc = H264Encoder::new(width, height);
211    let avcc = enc.avcc();
212    let mut samples = Vec::new();
213    for f in frames {
214        samples.push(H264Encoder::sample_from_au(&enc.encode_frame(&f)));
215    }
216    let params = H264Mp4Params {
217        width,
218        height,
219        timescale,
220        frame_duration,
221        avcc_payload: &avcc,
222        samples: &samples,
223    };
224    match captions {
225        Some(track) if !track.is_empty() => mux_h264_with_captions(&params, track),
226        _ => mux_h264(&params),
227    }
228}
229
230pub use crate::h264::params::MB_SIZE as MACROBLOCK_SIZE;
231const _: () = assert!(MB_SIZE == 16);
232
233#[cfg(test)]
234mod tests {
235    use super::*;
236    use crate::h264::nal::{split_annexb, START_CODE};
237
238    fn gradient(width: u32, height: u32) -> Yuv420Frame {
239        let mut f = Yuv420Frame::new(width, height);
240        for j in 0..height {
241            for i in 0..width {
242                f.y[(j * width + i) as usize] = ((i * 3 + j * 5) & 0xFF) as u8;
243            }
244        }
245        let (cw, ch) = (width / 2, height / 2);
246        for j in 0..ch {
247            for i in 0..cw {
248                f.u[(j * cw + i) as usize] = ((i * 7 + 30) & 0xFF) as u8;
249                f.v[(j * cw + i) as usize] = ((j * 11 + 60) & 0xFF) as u8;
250            }
251        }
252        f
253    }
254
255    fn nal_starts_with(au: &[u8], header: u8) -> bool {
256        split_annexb(au)
257            .iter()
258            .any(|nal| !nal.is_empty() && nal[0] == header)
259    }
260
261    #[test]
262    fn access_unit_has_expected_nals() {
263        let mut enc = H264Encoder::new(64, 64);
264        let au = enc.encode_frame(&gradient(64, 64));
265        assert!(au.starts_with(&START_CODE));
266        assert!(nal_starts_with(&au, 0x67), "SPS NAL header");
267        assert!(nal_starts_with(&au, 0x68), "PPS NAL header");
268        assert!(nal_starts_with(&au, 0x65), "IDR slice NAL header");
269
270        let au2 = enc.encode_frame(&gradient(64, 64));
271        assert!(!nal_starts_with(&au2, 0x67), "SPS must not repeat");
272        assert!(nal_starts_with(&au2, 0x65), "IDR slice present");
273    }
274
275    #[test]
276    fn mp4_mux_produces_ftyp() {
277        let frames = [gradient(64, 64)];
278        let mp4 = encode_mp4(64, 64, 30, &frames);
279        assert_eq!(&mp4[4..8], b"ftyp");
280    }
281}