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