Skip to main content

threers_codec/
hw.rs

1//! Hardware acceleration with a software fallback, behind one interface each
2//! way.
3//!
4//! | Direction | Type | Hardware | Fallback |
5//! |-----------|------|----------|----------|
6//! | encode | [`Mp4Encoder`] | VideoToolbox HEVC (macOS, `videotoolbox`); NVENC HEVC (Linux/Windows, `nvidia`); VAAPI HEVC (Linux, `vaapi`) | [`hevc::CompressedEncoder`](crate::hevc::CompressedEncoder), frame-parallel with `parallel` |
7//! | decode | [`Decoder`] (feature `decode`) | VideoToolbox H.264/HEVC (macOS, `videotoolbox`); NVDEC H.264/HEVC/VP9/AV1 (Linux/Windows, `nvidia`); VAAPI H.264/HEVC/VP9/AV1 (Linux, `vaapi`) | [`NativeDecoder`](crate::decode::NativeDecoder): H.264, HEVC, VP9, AV1 |
8//!
9//! Code written against these runs on every target, `wasm32` included, and
10//! picks up the hardware block where the build and the machine have one. When
11//! the hardware refuses a stream — a profile it does not do, a session it will
12//! not open — the constructor falls back to the software codec rather than
13//! failing; [`Mp4Encoder::backend`] and [`Decoder::backend`] say which one
14//! you got. Pin one with `with_backend` to measure or test it on its own.
15//!
16//! ```no_run
17//! use threers_codec::hw::{EncodeOptions, Mp4Encoder};
18//!
19//! let (w, h) = (1280, 720);
20//! let mut enc = Mp4Encoder::new(w, h, EncodeOptions::default()).unwrap();
21//! println!("encoding with {:?}", enc.backend());
22//! for i in 0..60u32 {
23//!     let rgba = vec![(i * 4) as u8; (w * h * 4) as usize];
24//!     enc.push_rgba(&rgba).unwrap();
25//! }
26//! let mp4: Vec<u8> = enc.finish().unwrap();
27//! std::fs::write("clip.mp4", mp4).unwrap();
28//! ```
29
30#[cfg(feature = "decode")]
31pub use crate::decode::{Backend, Decoder};
32
33use crate::hevc::{CompressedEncoder, HvccArray, HvccProfile, Yuv420Frame};
34use crate::mp4::{mux_hevc, Mp4Params};
35use crate::rate::{RateControl, PROBE_QP};
36
37#[cfg(all(
38    feature = "nvidia",
39    any(target_os = "linux", target_os = "windows"),
40    target_pointer_width = "64"
41))]
42use crate::nvidia::{NvencEncoder, NvencRate};
43#[cfg(all(feature = "vaapi", target_os = "linux"))]
44use crate::vaapi::{VaapiEncoder, VaapiRate};
45#[cfg(all(feature = "videotoolbox", target_os = "macos"))]
46use crate::videotoolbox::{VideoToolboxEncoder, VtTuning};
47
48/// Which encoder an [`Mp4Encoder`] is using.
49#[derive(Debug, Clone, Copy, PartialEq, Eq)]
50#[non_exhaustive]
51pub enum EncodeBackend {
52    /// Apple's hardware HEVC encoder. macOS with the `videotoolbox` feature.
53    VideoToolbox,
54    /// An NVIDIA GPU's NVENC engine. Linux and Windows with the `nvidia`
55    /// feature, on a machine with the driver.
56    Nvenc,
57    /// A VA driver's HEVC encoder (AMD, Intel). Linux with the `vaapi`
58    /// feature, on a machine with libva and a driver that encodes.
59    Vaapi,
60    /// threers' own all-intra HEVC encoder: pure Rust, every platform, and
61    /// spread across cores with the `parallel` feature.
62    Native,
63}
64
65impl EncodeBackend {
66    /// Whether this build can encode with `self`.
67    pub fn available(self) -> bool {
68        match self {
69            EncodeBackend::VideoToolbox => {
70                cfg!(all(feature = "videotoolbox", target_os = "macos"))
71            }
72            #[cfg(all(
73                feature = "nvidia",
74                any(target_os = "linux", target_os = "windows"),
75                target_pointer_width = "64"
76            ))]
77            EncodeBackend::Nvenc => crate::nvidia::available(),
78            #[cfg(not(all(
79                feature = "nvidia",
80                any(target_os = "linux", target_os = "windows"),
81                target_pointer_width = "64"
82            )))]
83            EncodeBackend::Nvenc => false,
84            #[cfg(all(feature = "vaapi", target_os = "linux"))]
85            EncodeBackend::Vaapi => crate::vaapi::encode_available(),
86            #[cfg(not(all(feature = "vaapi", target_os = "linux")))]
87            EncodeBackend::Vaapi => false,
88            EncodeBackend::Native => true,
89        }
90    }
91
92    /// The hardware backends, in the order [`Mp4Encoder::new`] tries them.
93    pub const HARDWARE: [EncodeBackend; 3] = [
94        EncodeBackend::VideoToolbox,
95        EncodeBackend::Nvenc,
96        EncodeBackend::Vaapi,
97    ];
98
99    /// The backend [`Mp4Encoder::new`] tries first.
100    pub fn preferred() -> EncodeBackend {
101        Self::HARDWARE
102            .into_iter()
103            .find(|b| b.available())
104            .unwrap_or(EncodeBackend::Native)
105    }
106}
107
108/// What an [`Mp4Encoder`] is asked for. Each backend reads it in its own
109/// terms; the fields say how.
110#[derive(Debug, Clone, Copy, PartialEq)]
111pub struct EncodeOptions {
112    /// Frames per second.
113    pub fps: u32,
114    /// 0 (smallest) to 1 (best). VideoToolbox takes it as its own quality
115    /// property; the native encoder, NVENC and VAAPI map it linearly onto
116    /// quantizers 40 to 18, the range where the native encoder's output is
117    /// usable, so 0.5 is QP 29.
118    pub quality: f32,
119    /// A target average bitrate in bits per second, which overrides `quality`
120    /// on the native encoder, NVENC and VAAPI (variable bitrate) and caps it on
121    /// VideoToolbox.
122    pub bitrate: Option<u32>,
123    /// Hint that encoding must keep pace with capture: VideoToolbox's realtime
124    /// mode, NVENC's low-latency tuning and a faster preset. The native
125    /// encoder ignores it.
126    pub realtime: bool,
127}
128
129impl Default for EncodeOptions {
130    fn default() -> Self {
131        Self {
132            fps: 30,
133            quality: 0.7,
134            bitrate: None,
135            realtime: false,
136        }
137    }
138}
139
140impl EncodeOptions {
141    /// The quantizer the native encoder uses for [`quality`](Self::quality).
142    pub fn native_qp(&self) -> i32 {
143        (40.0 - self.quality.clamp(0.0, 1.0) * 22.0).round() as i32
144    }
145}
146
147enum Inner {
148    #[cfg(all(feature = "videotoolbox", target_os = "macos"))]
149    VideoToolbox(VideoToolboxEncoder),
150    #[cfg(all(
151        feature = "nvidia",
152        any(target_os = "linux", target_os = "windows"),
153        target_pointer_width = "64"
154    ))]
155    Nvenc(Box<NvencEncoder>),
156    #[cfg(all(feature = "vaapi", target_os = "linux"))]
157    Vaapi(Box<VaapiEncoder>),
158    Native(Box<NativeMp4>),
159}
160
161/// An HEVC-in-MP4 encoder on whichever [`EncodeBackend`] suits the platform.
162///
163/// Push RGBA frames, then [`finish`](Self::finish) for the file's bytes. The
164/// output is a standard `hvc1` MP4 either way; what differs is speed and that
165/// the native encoder is all-intra, so its files are larger at the same
166/// quality.
167pub struct Mp4Encoder {
168    inner: Inner,
169}
170
171impl Mp4Encoder {
172    /// The first [hardware backend](EncodeBackend::HARDWARE) available that
173    /// opens a session, or the native encoder when none does.
174    pub fn new(width: u32, height: u32, options: EncodeOptions) -> Result<Self, String> {
175        for b in EncodeBackend::HARDWARE
176            .into_iter()
177            .filter(|b| b.available())
178        {
179            if let Ok(e) = Self::with_backend(width, height, options, b) {
180                return Ok(e);
181            }
182        }
183        Self::with_backend(width, height, options, EncodeBackend::Native)
184    }
185
186    /// Exactly `backend`, failing if this build or this machine cannot.
187    pub fn with_backend(
188        width: u32,
189        height: u32,
190        options: EncodeOptions,
191        backend: EncodeBackend,
192    ) -> Result<Self, String> {
193        if width == 0 || height == 0 {
194            return Err(format!("cannot encode a {width}x{height} picture"));
195        }
196        match backend {
197            #[cfg(all(feature = "videotoolbox", target_os = "macos"))]
198            EncodeBackend::VideoToolbox => {
199                let mut tuning = if options.realtime {
200                    VtTuning::realtime()
201                } else {
202                    VtTuning::default()
203                };
204                tuning.average_bitrate = options.bitrate;
205                let enc = VideoToolboxEncoder::new_for_mp4_tuned(
206                    width,
207                    height,
208                    options.fps.max(1) as i32,
209                    options.quality,
210                    tuning,
211                )?;
212                Ok(Self {
213                    inner: Inner::VideoToolbox(enc),
214                })
215            }
216            #[cfg(not(all(feature = "videotoolbox", target_os = "macos")))]
217            EncodeBackend::VideoToolbox => {
218                Err("VideoToolbox needs macOS and the `videotoolbox` feature".into())
219            }
220            #[cfg(all(
221                feature = "nvidia",
222                any(target_os = "linux", target_os = "windows"),
223                target_pointer_width = "64"
224            ))]
225            EncodeBackend::Nvenc => {
226                let rate = match options.bitrate {
227                    Some(bps) => NvencRate::Bitrate(bps),
228                    None => NvencRate::ConstQp(options.native_qp() as u32),
229                };
230                let keyframe_secs = if options.realtime { 2 } else { 5 };
231                let enc = NvencEncoder::new(
232                    width,
233                    height,
234                    options.fps,
235                    rate,
236                    keyframe_secs,
237                    options.realtime,
238                )?;
239                Ok(Self {
240                    inner: Inner::Nvenc(Box::new(enc)),
241                })
242            }
243            #[cfg(not(all(
244                feature = "nvidia",
245                any(target_os = "linux", target_os = "windows"),
246                target_pointer_width = "64"
247            )))]
248            EncodeBackend::Nvenc => {
249                Err("NVENC needs Linux or Windows and the `nvidia` feature".into())
250            }
251            #[cfg(all(feature = "vaapi", target_os = "linux"))]
252            EncodeBackend::Vaapi => {
253                let rate = match options.bitrate {
254                    Some(bps) => VaapiRate::Bitrate(bps),
255                    None => VaapiRate::ConstQp(options.native_qp() as u32),
256                };
257                let keyframe_secs = if options.realtime { 2 } else { 5 };
258                let enc = VaapiEncoder::new(width, height, options.fps, rate, keyframe_secs)?;
259                Ok(Self {
260                    inner: Inner::Vaapi(Box::new(enc)),
261                })
262            }
263            #[cfg(not(all(feature = "vaapi", target_os = "linux")))]
264            EncodeBackend::Vaapi => Err("VAAPI needs Linux and the `vaapi` feature".into()),
265            EncodeBackend::Native => Ok(Self {
266                inner: Inner::Native(Box::new(NativeMp4::new(width, height, options))),
267            }),
268        }
269    }
270
271    /// The backend in use.
272    pub fn backend(&self) -> EncodeBackend {
273        match &self.inner {
274            #[cfg(all(feature = "videotoolbox", target_os = "macos"))]
275            Inner::VideoToolbox(_) => EncodeBackend::VideoToolbox,
276            #[cfg(all(
277                feature = "nvidia",
278                any(target_os = "linux", target_os = "windows"),
279                target_pointer_width = "64"
280            ))]
281            Inner::Nvenc(_) => EncodeBackend::Nvenc,
282            #[cfg(all(feature = "vaapi", target_os = "linux"))]
283            Inner::Vaapi(_) => EncodeBackend::Vaapi,
284            Inner::Native(_) => EncodeBackend::Native,
285        }
286    }
287
288    /// Encode one frame of tightly packed RGBA8, `width * height * 4` bytes.
289    pub fn push_rgba(&mut self, rgba: &[u8]) -> Result<(), String> {
290        match &mut self.inner {
291            #[cfg(all(feature = "videotoolbox", target_os = "macos"))]
292            Inner::VideoToolbox(e) => e.push_rgba(rgba),
293            #[cfg(all(
294                feature = "nvidia",
295                any(target_os = "linux", target_os = "windows"),
296                target_pointer_width = "64"
297            ))]
298            Inner::Nvenc(e) => e.push_rgba(rgba),
299            #[cfg(all(feature = "vaapi", target_os = "linux"))]
300            Inner::Vaapi(e) => e.push_rgba(rgba),
301            Inner::Native(e) => e.push_rgba(rgba),
302        }
303    }
304
305    /// Flush the encoder and return the MP4 file.
306    pub fn finish(self) -> Result<Vec<u8>, String> {
307        match self.inner {
308            #[cfg(all(feature = "videotoolbox", target_os = "macos"))]
309            Inner::VideoToolbox(e) => e.finish_mp4_bytes().map(|(_, mp4)| mp4),
310            #[cfg(all(
311                feature = "nvidia",
312                any(target_os = "linux", target_os = "windows"),
313                target_pointer_width = "64"
314            ))]
315            Inner::Nvenc(e) => e.finish(),
316            #[cfg(all(feature = "vaapi", target_os = "linux"))]
317            Inner::Vaapi(e) => e.finish(),
318            Inner::Native(e) => e.finish(),
319        }
320    }
321}
322
323/// The native side of [`Mp4Encoder`]: frames are buffered just long enough to
324/// encode a batch of them at once, which is free because every frame is an
325/// IDR and nothing carries from one to the next.
326struct NativeMp4 {
327    enc: CompressedEncoder,
328    width: u32,
329    height: u32,
330    fps: u32,
331    qp: i32,
332    rc: Option<RateControl>,
333    batch: usize,
334    pending: Vec<Yuv420Frame>,
335    samples: Vec<Vec<u8>>,
336}
337
338impl NativeMp4 {
339    fn new(width: u32, height: u32, options: EncodeOptions) -> Self {
340        let fps = options.fps.max(1);
341        let rc = options
342            .bitrate
343            .map(|bps| RateControl::new(bps as u64, fps, None));
344        let batch = match &rc {
345            Some(r) => r.group_size(crate::frames_by_memory(width, height)),
346            None => crate::frames_in_flight(width, height),
347        };
348        Self {
349            enc: CompressedEncoder::new(width, height, PROBE_QP),
350            width,
351            height,
352            fps,
353            qp: options.native_qp(),
354            rc,
355            batch: batch.max(1),
356            pending: Vec::new(),
357            samples: Vec::new(),
358        }
359    }
360
361    fn push_rgba(&mut self, rgba: &[u8]) -> Result<(), String> {
362        let need = self.width as usize * self.height as usize * 4;
363        if rgba.len() < need {
364            return Err(format!("frame is {} bytes, want {need}", rgba.len()));
365        }
366        let frame = Yuv420Frame::from_rgba(self.width, self.height, &rgba[..need]);
367        // The first frame tells a bitrate target what this content costs.
368        if let Some(r) = self.rc.as_mut()
369            && self.samples.is_empty()
370            && self.pending.is_empty()
371        {
372            r.seed(
373                PROBE_QP,
374                self.enc.encode_slice_au_at(&frame, PROBE_QP).len(),
375            );
376            if let Some(q2) = r.probe_again() {
377                r.seed_pair(q2, self.enc.encode_slice_au_at(&frame, q2).len());
378            }
379        }
380        self.pending.push(frame);
381        if self.pending.len() >= self.batch {
382            self.flush();
383        }
384        Ok(())
385    }
386
387    fn flush(&mut self) {
388        if self.pending.is_empty() {
389            return;
390        }
391        let qp = self.rc.as_ref().map_or(self.qp, |r| r.next_qp());
392        let enc = &self.enc;
393        let aus = crate::map_frames(&self.pending, |f| enc.encode_slice_au_at(f, qp));
394        self.pending.clear();
395        for au in aus {
396            if let Some(r) = self.rc.as_mut() {
397                r.observe(qp, au.len());
398            }
399            let mut sample = Vec::with_capacity(au.len());
400            for nal in crate::h264::nal::split_annexb(&au) {
401                sample.extend_from_slice(&(nal.len() as u32).to_be_bytes());
402                sample.extend_from_slice(&nal);
403            }
404            self.samples.push(sample);
405        }
406    }
407
408    fn finish(mut self) -> Result<Vec<u8>, String> {
409        self.flush();
410        if self.samples.is_empty() {
411            return Err("no frames were pushed".into());
412        }
413        let (vps, sps, pps) = self.enc.parameter_sets();
414        let (vps, sps, pps) = ([vps], [sps], [pps]);
415        let hvcc = crate::hevc::build_hvcc(
416            &HvccProfile::main_420(self.enc.config().level_idc),
417            &[
418                HvccArray {
419                    nal_type: 32,
420                    complete: true,
421                    nals: &vps,
422                },
423                HvccArray {
424                    nal_type: 33,
425                    complete: true,
426                    nals: &sps,
427                },
428                HvccArray {
429                    nal_type: 34,
430                    complete: true,
431                    nals: &pps,
432                },
433            ],
434        );
435        let timescale = 600u32;
436        Ok(mux_hevc(&Mp4Params {
437            width: self.width,
438            height: self.height,
439            timescale,
440            frame_duration: timescale / self.fps,
441            hvcc_payload: &hvcc,
442            almo_payload: None,
443            samples: &self.samples,
444        }))
445    }
446}
447
448#[cfg(test)]
449mod tests {
450    use super::*;
451
452    #[test]
453    fn quality_maps_onto_the_usable_quantizers() {
454        let at = |quality| {
455            EncodeOptions {
456                quality,
457                ..Default::default()
458            }
459            .native_qp()
460        };
461        assert_eq!(at(0.0), 40);
462        assert_eq!(at(0.5), 29);
463        assert_eq!(at(1.0), 18);
464        assert_eq!(at(7.0), 18);
465    }
466
467    #[test]
468    fn native_backend_writes_an_mp4() {
469        let (w, h) = (64, 48);
470        let opts = EncodeOptions::default();
471        let mut enc = Mp4Encoder::with_backend(w, h, opts, EncodeBackend::Native).unwrap();
472        assert_eq!(enc.backend(), EncodeBackend::Native);
473        for i in 0..5u8 {
474            let rgba: Vec<u8> = (0..w * h * 4).map(|p| (p as u8).wrapping_mul(i)).collect();
475            enc.push_rgba(&rgba).unwrap();
476        }
477        let mp4 = enc.finish().unwrap();
478        assert_eq!(&mp4[4..8], b"ftyp");
479        let track = crate::mp4_demux::demux_video(&mp4).unwrap();
480        assert_eq!(track.samples.len(), 5);
481        assert_eq!((track.width, track.height), (w, h));
482    }
483
484    #[test]
485    fn a_short_frame_is_refused() {
486        let mut enc =
487            Mp4Encoder::with_backend(16, 16, EncodeOptions::default(), EncodeBackend::Native)
488                .unwrap();
489        assert!(enc.push_rgba(&[0; 16]).is_err());
490    }
491
492    #[test]
493    fn unavailable_backends_say_so() {
494        if !EncodeBackend::VideoToolbox.available() {
495            let r =
496                Mp4Encoder::with_backend(16, 16, Default::default(), EncodeBackend::VideoToolbox);
497            assert!(r.is_err());
498        }
499        assert!(EncodeBackend::Native.available());
500    }
501}