Skip to main content

codec_bench/
codec_bench.rs

1//! Encode a raw `yuv420p` clip with each pure-Rust encoder and report bytes and
2//! wall time as JSON on stdout.
3//!
4//! This is the native arm of the codec benchmark. `scripts/codec_bench.py`
5//! prepares the clip, runs the ffmpeg and VideoToolbox arms, decodes every
6//! result back and computes the quality metrics; this binary only encodes, so
7//! the timings here are the encoder and nothing else.
8//!
9//! Input is planar `yuv420p` — the same bytes the ffmpeg arms are fed — rather
10//! than RGBA, so no arm pays a colour-conversion cost the others avoid and the
11//! comparison is codec-to-codec.
12//!
13//! ```text
14//! codec_bench --input clip.yuv --size 1280x1440 --fps 24 \
15//!             --encoder hevc-intra --qp 26 --out out.mp4
16//! ```
17
18use std::time::Instant;
19
20use threers_codec::h264::{encode_compressed_mp4, encode_mp4, split_annexb};
21use threers_codec::hevc::{
22    build_hvcc, encode_compressed_mp4_streaming, CompressedEncoder, HevcEncoder, HvccArray,
23    HvccProfile, Yuv420Frame,
24};
25use threers_codec::mp4::{mux_hevc, Mp4Params};
26
27fn main() {
28    let args = Args::parse();
29    let frames = if args.encoder == "hevc-stream" {
30        Vec::new()
31    } else {
32        read_yuv(&args)
33    };
34    eprintln!(
35        "codec_bench: {} frames {}x{} via {}",
36        frames.len(),
37        args.width,
38        args.height,
39        args.encoder
40    );
41
42    let t0 = Instant::now();
43    let bytes = match args.encoder.as_str() {
44        "h264-pcm" => encode_mp4(args.width, args.height, args.fps, &frames),
45        "hevc-pcm" => encode_hevc_pcm(&args, &frames),
46        "h264-native" => encode_compressed_mp4(args.width, args.height, args.fps, args.qp, &frames),
47        "hevc-intra" => encode_hevc_intra(&args, &frames, false),
48        "hevc-intra-residual" => encode_hevc_intra(&args, &frames, true),
49        // The library's own export path, which batches frames so they can be
50        // encoded concurrently. `hevc-intra-residual` above drives the encoder
51        // a frame at a time and so never exercises it.
52        "hevc-mp4" => encode_hevc_mp4(&args, &frames),
53        // Same encoder, but pulling frames from disk one at a time — the shape
54        // that matters at 8K, where holding every source frame is gigabytes.
55        "hevc-stream" => {
56            let (w, h) = (args.width as usize, args.height as usize);
57            let frame_len = w * h + 2 * (w / 2) * (h / 2);
58            let n = std::fs::metadata(&args.input).expect("stat input").len() as usize / frame_len;
59            let mut file = std::fs::File::open(&args.input).expect("open input");
60            eprintln!("codec_bench: streaming {n} frames of {w}x{h}");
61            encode_compressed_mp4_streaming(
62                args.width,
63                args.height,
64                args.fps,
65                args.qp,
66                n,
67                None,
68                |_| read_one(&mut file, args.width, args.height),
69            )
70        }
71        other => {
72            eprintln!("unknown encoder `{other}`");
73            std::process::exit(2);
74        }
75    };
76    let ms = t0.elapsed().as_secs_f64() * 1000.0;
77
78    std::fs::write(&args.out, &bytes).expect("write output");
79    println!(
80        "{{\"encoder\":\"{}\",\"qp\":{},\"bytes\":{},\"encode_ms\":{:.1},\"frames\":{}}}",
81        args.encoder,
82        args.qp,
83        bytes.len(),
84        ms,
85        frames.len()
86    );
87}
88
89/// PCM HEVC: every CTB carries raw samples. Lossless in YUV, and the size floor
90/// this benchmark exists to move.
91fn encode_hevc_pcm(args: &Args, frames: &[Yuv420Frame]) -> Vec<u8> {
92    let mut enc = HevcEncoder::new(args.width, args.height);
93    let level = enc.config().level_idc;
94    let stream: Vec<Vec<u8>> = frames.iter().map(|f| enc.encode_frame(f)).collect();
95    mux_annexb(args, &stream, level)
96}
97
98/// Transform-coded intra HEVC. `residual` adds coefficient coding on top of the
99/// prediction-only path.
100///
101/// With `--recon` set, the encoder's own reconstruction is written out too. A
102/// conformant decoder must reproduce it bit-for-bit, so comparing that file to
103/// ffmpeg's decode separates "the bitstream is wrong" from "the encoder's
104/// choices are bad" — two failures that look identical in a PSNR column.
105/// The library export path, optionally tiled.
106fn encode_hevc_mp4(args: &Args, frames: &[Yuv420Frame]) -> Vec<u8> {
107    use threers_codec::hevc::compress::CompressedEncoder;
108    let enc =
109        CompressedEncoder::new(args.width, args.height, args.qp).tiles(args.tiles.0, args.tiles.1);
110    let level = enc.config().level_idc;
111    let (vps, sps, pps) = enc.parameter_sets();
112    let mut stream = vec![[
113        vec![0, 0, 0, 1],
114        vps,
115        vec![0, 0, 0, 1],
116        sps,
117        vec![0, 0, 0, 1],
118        pps,
119    ]
120    .concat()];
121    stream.extend(threers_codec::map_frames_pub(frames, |f| {
122        enc.encode_slice_au(f)
123    }));
124    mux_annexb(args, &stream, level)
125}
126
127fn encode_hevc_intra(args: &Args, frames: &[Yuv420Frame], residual: bool) -> Vec<u8> {
128    let mut enc = CompressedEncoder::new(args.width, args.height, args.qp).residual(residual);
129    let level = enc.config().level_idc;
130    let mut recon_out = Vec::new();
131    let stream: Vec<Vec<u8>> = frames
132        .iter()
133        .map(|f| {
134            let (au, recon) = enc.encode_frame(f);
135            if !args.recon.is_empty() {
136                // Crop the CTB-aligned reconstruction back to display size, the
137                // way the conformance window makes a decoder do.
138                let (cw, cwc) = (recon.coded_width as usize, (recon.coded_width / 2) as usize);
139                let (w, h) = (args.width as usize, args.height as usize);
140                for row in 0..h {
141                    recon_out.extend_from_slice(&recon.y[row * cw..row * cw + w]);
142                }
143                for plane in [&recon.u, &recon.v] {
144                    for row in 0..h / 2 {
145                        recon_out.extend_from_slice(&plane[row * cwc..row * cwc + w / 2]);
146                    }
147                }
148            }
149            au
150        })
151        .collect();
152    if !args.recon.is_empty() {
153        std::fs::write(&args.recon, &recon_out).expect("write reconstruction");
154    }
155    mux_annexb(args, &stream, level)
156}
157
158/// Split each access unit's Annex-B NALs, hoist the parameter sets into `hvcC`,
159/// and length-prefix the slice NALs into MP4 samples.
160fn mux_annexb(args: &Args, access_units: &[Vec<u8>], level_idc: u8) -> Vec<u8> {
161    let (mut vps, mut sps, mut pps) = (Vec::new(), Vec::new(), Vec::new());
162    let mut samples: Vec<Vec<u8>> = Vec::with_capacity(access_units.len());
163
164    for au in access_units {
165        let mut sample = Vec::new();
166        for nal in split_annexb(au) {
167            // HEVC NAL header is 2 bytes; nal_unit_type is bits 1..7 of byte 0.
168            let kind = (nal[0] >> 1) & 0x3F;
169            match kind {
170                32 => vps.push(nal),
171                33 => sps.push(nal),
172                34 => pps.push(nal),
173                _ => {
174                    sample.extend_from_slice(&(nal.len() as u32).to_be_bytes());
175                    sample.extend_from_slice(&nal);
176                }
177            }
178        }
179        samples.push(sample);
180    }
181
182    let hvcc = build_hvcc(
183        &HvccProfile::main_420(level_idc),
184        &[
185            HvccArray {
186                nal_type: 32,
187                complete: true,
188                nals: &vps,
189            },
190            HvccArray {
191                nal_type: 33,
192                complete: true,
193                nals: &sps,
194            },
195            HvccArray {
196                nal_type: 34,
197                complete: true,
198                nals: &pps,
199            },
200        ],
201    );
202
203    let timescale = 600u32;
204    mux_hevc(&Mp4Params {
205        width: args.width,
206        height: args.height,
207        timescale,
208        frame_duration: timescale / args.fps.max(1),
209        hvcc_payload: &hvcc,
210        almo_payload: None,
211        samples: &samples,
212    })
213}
214
215/// Read the next planar `yuv420p` frame from an open file.
216fn read_one(file: &mut std::fs::File, width: u32, height: u32) -> Yuv420Frame {
217    use std::io::Read;
218    let (w, h) = (width as usize, height as usize);
219    let (cw, ch) = (w / 2, h / 2);
220    let mut y = vec![0u8; w * h];
221    let mut u = vec![0u8; cw * ch];
222    let mut v = vec![0u8; cw * ch];
223    file.read_exact(&mut y).expect("read luma");
224    file.read_exact(&mut u).expect("read Cb");
225    file.read_exact(&mut v).expect("read Cr");
226    Yuv420Frame {
227        width,
228        height,
229        y,
230        u,
231        v,
232        alpha: None,
233    }
234}
235
236/// Read the whole planar `yuv420p` file into frames.
237fn read_yuv(args: &Args) -> Vec<Yuv420Frame> {
238    let raw = std::fs::read(&args.input).expect("read input clip");
239    let (w, h) = (args.width as usize, args.height as usize);
240    let (cw, ch) = (w / 2, h / 2);
241    let frame_len = w * h + 2 * cw * ch;
242    assert!(
243        raw.len().is_multiple_of(frame_len),
244        "clip is {} bytes, not a whole number of {w}x{h} yuv420p frames ({frame_len} each)",
245        raw.len()
246    );
247
248    raw.chunks_exact(frame_len)
249        .map(|c| Yuv420Frame {
250            width: args.width,
251            height: args.height,
252            y: c[..w * h].to_vec(),
253            u: c[w * h..w * h + cw * ch].to_vec(),
254            v: c[w * h + cw * ch..].to_vec(),
255            alpha: None,
256        })
257        .collect()
258}
259
260struct Args {
261    input: String,
262    out: String,
263    width: u32,
264    height: u32,
265    fps: u32,
266    qp: i32,
267    encoder: String,
268    recon: String,
269    tiles: (u32, u32),
270}
271
272impl Args {
273    fn parse() -> Self {
274        let mut a = Args {
275            input: String::new(),
276            out: "out.mp4".into(),
277            width: 0,
278            height: 0,
279            fps: 30,
280            qp: 26,
281            encoder: "hevc-intra".into(),
282            recon: String::new(),
283            tiles: (1, 1),
284        };
285        let argv: Vec<String> = std::env::args().skip(1).collect();
286        let mut i = 0;
287        while i < argv.len() {
288            let val = || argv.get(i + 1).cloned().unwrap_or_default();
289            match argv[i].as_str() {
290                "--input" => a.input = val(),
291                "--out" => a.out = val(),
292                "--fps" => a.fps = val().parse().expect("--fps"),
293                "--qp" => a.qp = val().parse().expect("--qp"),
294                "--encoder" => a.encoder = val(),
295                "--recon" => a.recon = val(),
296                "--tiles" => {
297                    let s = val();
298                    let (c, r) = s.split_once('x').expect("--tiles CxR");
299                    a.tiles = (c.parse().expect("cols"), r.parse().expect("rows"));
300                }
301                "--size" => {
302                    let s = val();
303                    let (w, h) = s.split_once('x').expect("--size WxH");
304                    a.width = w.parse().expect("width");
305                    a.height = h.parse().expect("height");
306                }
307                other => {
308                    eprintln!("unknown flag `{other}`");
309                    std::process::exit(2);
310                }
311            }
312            i += 2;
313        }
314        if a.input.is_empty() || a.width == 0 || a.height == 0 {
315            eprintln!("usage: codec_bench --input FRAMES.rgb --size WxH [options]");
316            std::process::exit(2);
317        }
318        a
319    }
320}