Skip to main content

threers_codec/
animation.rs

1//! High-level encoders for browser-friendly animated image/video containers.
2
3use std::fmt;
4
5#[cfg(feature = "gif")]
6use crate::gif::{encode_gif, GifOptions, PaletteMode};
7use crate::{
8    apng::ApngEncoder,
9    h264::{
10        encode_compressed_mp4_from_iter as encode_h264_mp4_from_iter, encode_mp4_with_captions,
11    },
12    hevc::{encode_compressed_mp4, encode_compressed_mp4_from_iter, Yuv420Frame},
13    webm::encode_webm,
14};
15
16/// Browser-friendly animation containers (no ffmpeg).
17#[derive(Clone, Copy, Debug, PartialEq, Eq)]
18pub enum BrowserCodec {
19    /// Animated GIF (feature `gif`): plays everywhere, 256 colours a frame.
20    Gif,
21    /// Animated PNG: full colour and alpha, larger files.
22    Apng,
23    /// VP9 in WebM, with alpha when the frames have any.
24    Webm,
25    /// H.264 in an MP4 container (`avc1` + `avcC`). Universally playable.
26    ///
27    /// Transform-coded intra, roughly a hundredth the size of the `I_PCM` path
28    /// this used to take. [`Mp4Hevc`](Self::Mp4Hevc) is smaller again where its
29    /// narrower playback reach is acceptable.
30    Mp4,
31    /// HEVC in an MP4 container (`hvc1` + `hvcC`), transform-coded.
32    ///
33    /// Two orders of magnitude smaller than [`Mp4`](Self::Mp4) — 0.16 MB against
34    /// 47 MB on the 17-frame clip in `docs/codec-benchmark.md`. The cost is
35    /// reach: HEVC in MP4 plays in Safari everywhere and in Chrome/Edge on
36    /// hardware that supports it, but not universally the way H.264 does.
37    Mp4Hevc,
38}
39
40impl BrowserCodec {
41    /// The file extension for this codec's container.
42    pub fn label(self) -> &'static str {
43        match self {
44            Self::Gif => "gif",
45            Self::Apng => "apng",
46            Self::Webm => "webm",
47            Self::Mp4 | Self::Mp4Hevc => "mp4",
48        }
49    }
50}
51
52/// Progress phase for [`encode_animation_rgba_with_progress`].
53#[derive(Clone, Copy, Debug, PartialEq, Eq)]
54pub enum AnimationExportPhase {
55    /// Frames are being rendered or collected.
56    Capture,
57    /// Frames are being encoded.
58    Encode,
59    /// The file is complete.
60    Done,
61}
62
63/// Progress tick for browser animation encoding.
64#[derive(Clone, Debug)]
65pub struct AnimationExportProgress {
66    /// What is happening now.
67    pub phase: AnimationExportPhase,
68    /// Frames done in this phase.
69    pub frame: u32,
70    /// Frames in the whole animation.
71    pub frames: u32,
72    /// Overall progress from 0 to 1.
73    pub ratio: f32,
74    /// The codec being written.
75    pub codec: BrowserCodec,
76    /// A ready-to-display line, as [`format_animation_progress`] writes it.
77    pub message: String,
78}
79
80/// Ready-to-display animation progress line.
81pub fn format_animation_progress(info: &AnimationExportProgress) -> String {
82    let pct = (info.ratio.clamp(0.0, 1.0) * 100.0).round() as i32;
83    match info.phase {
84        AnimationExportPhase::Capture => {
85            format!("Rendering {}/{} ({pct}%)", info.frame, info.frames)
86        }
87        AnimationExportPhase::Encode => {
88            format!(
89                "Encoding {}… ({pct}%)",
90                info.codec.label().to_ascii_uppercase()
91            )
92        }
93        AnimationExportPhase::Done => format!("Done ({} frames)", info.frames),
94    }
95}
96
97fn make_anim_progress(
98    phase: AnimationExportPhase,
99    frame: u32,
100    frames: u32,
101    ratio: f32,
102    codec: BrowserCodec,
103) -> AnimationExportProgress {
104    let mut info = AnimationExportProgress {
105        phase,
106        frame,
107        frames,
108        ratio: ratio.clamp(0.0, 1.0),
109        codec,
110        message: String::new(),
111    };
112    info.message = format_animation_progress(&info);
113    info
114}
115
116/// Errors produced while encoding a browser animation.
117#[derive(Debug)]
118pub enum AnimationEncodeError {
119    /// No frames were given.
120    Empty,
121    /// A frame is not `width * height * 4` bytes.
122    FrameSize {
123        /// Index of the offending frame.
124        frame: usize,
125        /// The size every frame should be.
126        expected: usize,
127        /// The size this one is.
128        got: usize,
129    },
130    /// A zero dimension or frame rate, or options the codec cannot represent.
131    Dimension,
132    /// Writing the output failed.
133    Io(String),
134    /// The codec asked for was not compiled in: its feature (named here) is off.
135    FeatureDisabled(&'static str),
136}
137
138impl fmt::Display for AnimationEncodeError {
139    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
140        match self {
141            Self::Empty => write!(f, "animation needs at least one frame"),
142            Self::FrameSize {
143                frame,
144                expected,
145                got,
146            } => write!(
147                f,
148                "frame {frame} has {got} bytes, expected {expected} (width*height*4)"
149            ),
150            Self::Dimension => write!(f, "invalid dimensions, frame rate, or codec options"),
151            Self::Io(message) => write!(f, "animation encoding I/O failed: {message}"),
152            Self::FeatureDisabled(feature) => {
153                write!(f, "this build has no {feature} encoder (enable the `{feature}` feature)")
154            }
155        }
156    }
157}
158
159impl std::error::Error for AnimationEncodeError {}
160
161/// Options for [`encode_animation_rgba`].
162pub struct AnimationEncodeOptions {
163    /// Frame width in pixels.
164    pub width: u32,
165    /// Frame height in pixels.
166    pub height: u32,
167    /// Frames per second.
168    pub fps: u32,
169    /// Container and codec to write.
170    pub codec: BrowserCodec,
171    /// Keep the alpha channel where the codec can carry it.
172    pub transparent: bool,
173    /// GIF palette size (`2..=256`; normally `256`).
174    pub gif_colors: u16,
175}
176
177impl Default for AnimationEncodeOptions {
178    fn default() -> Self {
179        Self {
180            width: 0,
181            height: 0,
182            fps: 30,
183            codec: BrowserCodec::Gif,
184            transparent: false,
185            gif_colors: 256,
186        }
187    }
188}
189
190/// Encode tightly-packed RGBA8 frames into a browser-friendly animation.
191pub fn encode_animation_rgba(
192    opts: &AnimationEncodeOptions,
193    frames: impl IntoIterator<Item = Vec<u8>>,
194) -> Result<Vec<u8>, AnimationEncodeError> {
195    encode_animation_rgba_with_progress(opts, frames, |_| {})
196}
197
198/// Like [`encode_animation_rgba`], with encode-phase progress callbacks.
199pub fn encode_animation_rgba_with_progress<I, P>(
200    opts: &AnimationEncodeOptions,
201    frames: I,
202    mut on_progress: P,
203) -> Result<Vec<u8>, AnimationEncodeError>
204where
205    I: IntoIterator<Item = Vec<u8>>,
206    P: FnMut(AnimationExportProgress),
207{
208    let pixels = opts
209        .width
210        .checked_mul(opts.height)
211        .and_then(|n| n.checked_mul(4))
212        .ok_or(AnimationEncodeError::Dimension)?;
213    if opts.width == 0
214        || opts.height == 0
215        || opts.fps == 0
216        || opts.fps > u16::MAX as u32
217        || (matches!(opts.codec, BrowserCodec::Gif) && !(2..=256).contains(&opts.gif_colors))
218    {
219        return Err(AnimationEncodeError::Dimension);
220    }
221    if matches!(opts.codec, BrowserCodec::Gif)
222        && (opts.width > u16::MAX as u32 || opts.height > u16::MAX as u32)
223    {
224        return Err(AnimationEncodeError::Dimension);
225    }
226    if matches!(opts.codec, BrowserCodec::Webm)
227        && (!opts.width.is_multiple_of(8) || !opts.height.is_multiple_of(8))
228    {
229        return Err(AnimationEncodeError::Dimension);
230    }
231    if matches!(opts.codec, BrowserCodec::Mp4 | BrowserCodec::Mp4Hevc)
232        && (!opts.width.is_multiple_of(2) || !opts.height.is_multiple_of(2))
233    {
234        return Err(AnimationEncodeError::Dimension);
235    }
236
237    let expected = pixels as usize;
238
239    // The MP4 codecs can consume frames as they arrive. Everything else needs
240    // them all at once (GIF quantizes a palette across the set, WebM and APNG
241    // take slices), so only these two avoid the collect — which matters most
242    // here, since an RGBA frame is 4 bytes per pixel: 133 MB each at 8K.
243    if matches!(opts.codec, BrowserCodec::Mp4 | BrowserCodec::Mp4Hevc) && !opts.transparent {
244        return encode_mp4_streaming(opts, frames, expected, on_progress);
245    }
246
247    let mut frames: Vec<Vec<u8>> = frames.into_iter().collect();
248    if frames.is_empty() {
249        return Err(AnimationEncodeError::Empty);
250    }
251    for (frame, rgba) in frames.iter().enumerate() {
252        if rgba.len() != expected {
253            return Err(AnimationEncodeError::FrameSize {
254                frame,
255                expected,
256                got: rgba.len(),
257            });
258        }
259    }
260
261    let total = frames.len() as u32;
262    on_progress(make_anim_progress(
263        AnimationExportPhase::Encode,
264        0,
265        total,
266        0.0,
267        opts.codec,
268    ));
269
270    let delay_den = opts.fps as u16;
271    let bytes = match opts.codec {
272        #[cfg(not(feature = "gif"))]
273        BrowserCodec::Gif => return Err(AnimationEncodeError::FeatureDisabled("gif")),
274        #[cfg(feature = "gif")]
275        BrowserCodec::Gif => {
276            let gif_opts = GifOptions::default()
277                .colors(opts.gif_colors)
278                .transparency(opts.transparent)
279                .dither(true)
280                .diff_rects(true)
281                .palette_mode(PaletteMode::Local);
282            encode_gif(
283                opts.width,
284                opts.height,
285                0,
286                &gif_opts,
287                frames.into_iter().map(|rgba| (rgba, 1, delay_den)),
288            )
289        }
290        BrowserCodec::Apng => {
291            let mut encoder = ApngEncoder::new(opts.width, opts.height, 0);
292            let n = frames.len();
293            for (i, mut rgba) in frames.into_iter().enumerate() {
294                if !opts.transparent {
295                    for pixel in rgba.chunks_exact_mut(4) {
296                        pixel[3] = 255;
297                    }
298                }
299                encoder.add_frame(&rgba, 1, delay_den);
300                let done = (i + 1) as u32;
301                on_progress(make_anim_progress(
302                    AnimationExportPhase::Encode,
303                    done,
304                    n as u32,
305                    done as f32 / n as f32,
306                    opts.codec,
307                ));
308            }
309            encoder.finish()
310        }
311        BrowserCodec::Webm => {
312            let yuv: Vec<Yuv420Frame> = frames
313                .drain(..)
314                .map(|rgba| {
315                    let mut frame = Yuv420Frame::from_rgba(opts.width, opts.height, &rgba);
316                    if !opts.transparent {
317                        frame.alpha = None;
318                    }
319                    frame
320                })
321                .collect();
322            let refs: Vec<&Yuv420Frame> = yuv.iter().collect();
323            encode_webm(&refs, opts.fps)
324        }
325        BrowserCodec::Mp4 | BrowserCodec::Mp4Hevc => {
326            if opts.transparent {
327                return Err(AnimationEncodeError::Dimension);
328            }
329            let n = frames.len();
330            let mut yuv = Vec::with_capacity(n);
331            for rgba in frames.drain(..) {
332                yuv.push(Yuv420Frame::from_rgba(opts.width, opts.height, &rgba));
333                let done = yuv.len() as u32;
334                on_progress(make_anim_progress(
335                    AnimationExportPhase::Encode,
336                    done,
337                    n as u32,
338                    done as f32 / n as f32,
339                    opts.codec,
340                ));
341            }
342            if matches!(opts.codec, BrowserCodec::Mp4Hevc) {
343                // QP 26 is the middle of the usable range; see `encode_mp4`.
344                encode_compressed_mp4(opts.width, opts.height, opts.fps, 26, &yuv)
345            } else {
346                encode_mp4_with_captions(opts.width, opts.height, opts.fps, &yuv, None)
347            }
348        }
349    };
350
351    on_progress(make_anim_progress(
352        AnimationExportPhase::Done,
353        total,
354        total,
355        1.0,
356        opts.codec,
357    ));
358    Ok(bytes)
359}
360
361
362
363
364/// Encode the MP4 codecs without holding every source frame.
365///
366/// Frames are pulled from the iterator, converted, encoded and dropped one at a
367/// time, so peak memory is one RGBA frame plus one YUV frame plus the encoded
368/// samples — rather than every RGBA frame at once. Output is byte-identical to
369/// the collecting path.
370fn encode_mp4_streaming<I, P>(
371    opts: &AnimationEncodeOptions,
372    frames: I,
373    expected: usize,
374    mut on_progress: P,
375) -> Result<Vec<u8>, AnimationEncodeError>
376where
377    I: IntoIterator<Item = Vec<u8>>,
378    P: FnMut(AnimationExportProgress),
379{
380    let mut iter = frames.into_iter().peekable();
381    if iter.peek().is_none() {
382        return Err(AnimationEncodeError::Empty);
383    }
384    // Only used to report a ratio; an unsized iterator just reports against the
385    // count so far, which still moves monotonically.
386    let hint = iter.size_hint().1.unwrap_or(0) as u32;
387
388    let mut err = None;
389    let mut done = 0u32;
390    let (w, h) = (opts.width, opts.height);
391    let codec = opts.codec;
392    let yuv = std::iter::from_fn(|| {
393        if err.is_some() {
394            return None;
395        }
396        let rgba = iter.next()?;
397        if rgba.len() != expected {
398            err = Some(AnimationEncodeError::FrameSize {
399                frame: done as usize,
400                expected,
401                got: rgba.len(),
402            });
403            return None;
404        }
405        done += 1;
406        on_progress(make_anim_progress(
407            AnimationExportPhase::Encode,
408            done,
409            hint.max(done),
410            done as f32 / hint.max(done) as f32,
411            codec,
412        ));
413        Some(Yuv420Frame::from_rgba(w, h, &rgba))
414    });
415
416    let bytes = if matches!(codec, BrowserCodec::Mp4Hevc) {
417        // QP 26 is the middle of the usable range; see `encode_mp4`.
418        encode_compressed_mp4_from_iter(w, h, opts.fps, 26, None, yuv)
419    } else {
420        // QP 26 is the middle of the usable range, matching the HEVC path.
421        encode_h264_mp4_from_iter(w, h, opts.fps, 26, None, yuv)
422    };
423    if let Some(e) = err {
424        return Err(e);
425    }
426
427    on_progress(make_anim_progress(
428        AnimationExportPhase::Done,
429        done,
430        done,
431        1.0,
432        codec,
433    ));
434    Ok(bytes)
435}
436
437#[cfg(test)]
438mod tests {
439    use super::*;
440
441    fn solid(r: u8, g: u8, b: u8, a: u8) -> Vec<u8> {
442        let mut frame = vec![0; 8 * 8 * 4];
443        for pixel in frame.chunks_exact_mut(4) {
444            pixel.copy_from_slice(&[r, g, b, a]);
445        }
446        frame
447    }
448
449    #[test]
450    fn encodes_browser_animation_headers() {
451        for (codec, header) in [
452            (BrowserCodec::Gif, b"GIF8".as_slice()),
453            (BrowserCodec::Apng, &[0x89, b'P', b'N', b'G']),
454            (BrowserCodec::Webm, &[0x1a, 0x45, 0xdf, 0xa3]),
455            (BrowserCodec::Mp4, b"ftyp".as_slice()),
456        ] {
457            let transparent = !matches!(codec, BrowserCodec::Mp4);
458            let options = AnimationEncodeOptions {
459                width: 8,
460                height: 8,
461                fps: 10,
462                codec,
463                transparent,
464                gif_colors: 256,
465            };
466            let result =
467                encode_animation_rgba(&options, [solid(255, 0, 0, 255), solid(0, 0, 255, 128)]);
468            // Without the `gif` feature GIF is an error naming it, not a panic.
469            if cfg!(not(feature = "gif")) && matches!(codec, BrowserCodec::Gif) {
470                assert!(matches!(result, Err(AnimationEncodeError::FeatureDisabled("gif"))));
471                continue;
472            }
473            let bytes = result.unwrap();
474            assert!(bytes.len() > header.len());
475            if matches!(codec, BrowserCodec::Mp4) {
476                assert_eq!(&bytes[4..8], header);
477            } else {
478                assert_eq!(&bytes[..header.len()], header);
479            }
480        }
481    }
482}