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!(
154                    f,
155                    "this build has no {feature} encoder (enable the `{feature}` feature)"
156                )
157            }
158        }
159    }
160}
161
162impl std::error::Error for AnimationEncodeError {}
163
164/// Options for [`encode_animation_rgba`].
165pub struct AnimationEncodeOptions {
166    /// Frame width in pixels.
167    pub width: u32,
168    /// Frame height in pixels.
169    pub height: u32,
170    /// Frames per second.
171    pub fps: u32,
172    /// Container and codec to write.
173    pub codec: BrowserCodec,
174    /// Keep the alpha channel where the codec can carry it.
175    pub transparent: bool,
176    /// GIF palette size (`2..=256`; normally `256`).
177    pub gif_colors: u16,
178}
179
180impl Default for AnimationEncodeOptions {
181    fn default() -> Self {
182        Self {
183            width: 0,
184            height: 0,
185            fps: 30,
186            codec: BrowserCodec::Gif,
187            transparent: false,
188            gif_colors: 256,
189        }
190    }
191}
192
193/// Encode tightly-packed RGBA8 frames into a browser-friendly animation.
194pub fn encode_animation_rgba(
195    opts: &AnimationEncodeOptions,
196    frames: impl IntoIterator<Item = Vec<u8>>,
197) -> Result<Vec<u8>, AnimationEncodeError> {
198    encode_animation_rgba_with_progress(opts, frames, |_| {})
199}
200
201/// Like [`encode_animation_rgba`], with encode-phase progress callbacks.
202pub fn encode_animation_rgba_with_progress<I, P>(
203    opts: &AnimationEncodeOptions,
204    frames: I,
205    mut on_progress: P,
206) -> Result<Vec<u8>, AnimationEncodeError>
207where
208    I: IntoIterator<Item = Vec<u8>>,
209    P: FnMut(AnimationExportProgress),
210{
211    let pixels = opts
212        .width
213        .checked_mul(opts.height)
214        .and_then(|n| n.checked_mul(4))
215        .ok_or(AnimationEncodeError::Dimension)?;
216    if opts.width == 0
217        || opts.height == 0
218        || opts.fps == 0
219        || opts.fps > u16::MAX as u32
220        || (matches!(opts.codec, BrowserCodec::Gif) && !(2..=256).contains(&opts.gif_colors))
221    {
222        return Err(AnimationEncodeError::Dimension);
223    }
224    if matches!(opts.codec, BrowserCodec::Gif)
225        && (opts.width > u16::MAX as u32 || opts.height > u16::MAX as u32)
226    {
227        return Err(AnimationEncodeError::Dimension);
228    }
229    if matches!(opts.codec, BrowserCodec::Webm)
230        && (!opts.width.is_multiple_of(8) || !opts.height.is_multiple_of(8))
231    {
232        return Err(AnimationEncodeError::Dimension);
233    }
234    if matches!(opts.codec, BrowserCodec::Mp4 | BrowserCodec::Mp4Hevc)
235        && (!opts.width.is_multiple_of(2) || !opts.height.is_multiple_of(2))
236    {
237        return Err(AnimationEncodeError::Dimension);
238    }
239
240    let expected = pixels as usize;
241
242    // The MP4 codecs can consume frames as they arrive. Everything else needs
243    // them all at once (GIF quantizes a palette across the set, WebM and APNG
244    // take slices), so only these two avoid the collect — which matters most
245    // here, since an RGBA frame is 4 bytes per pixel: 133 MB each at 8K.
246    if matches!(opts.codec, BrowserCodec::Mp4 | BrowserCodec::Mp4Hevc) && !opts.transparent {
247        return encode_mp4_streaming(opts, frames, expected, on_progress);
248    }
249
250    let mut frames: Vec<Vec<u8>> = frames.into_iter().collect();
251    if frames.is_empty() {
252        return Err(AnimationEncodeError::Empty);
253    }
254    for (frame, rgba) in frames.iter().enumerate() {
255        if rgba.len() != expected {
256            return Err(AnimationEncodeError::FrameSize {
257                frame,
258                expected,
259                got: rgba.len(),
260            });
261        }
262    }
263
264    let total = frames.len() as u32;
265    on_progress(make_anim_progress(
266        AnimationExportPhase::Encode,
267        0,
268        total,
269        0.0,
270        opts.codec,
271    ));
272
273    let delay_den = opts.fps as u16;
274    let bytes = match opts.codec {
275        #[cfg(not(feature = "gif"))]
276        BrowserCodec::Gif => return Err(AnimationEncodeError::FeatureDisabled("gif")),
277        #[cfg(feature = "gif")]
278        BrowserCodec::Gif => {
279            let gif_opts = GifOptions::default()
280                .colors(opts.gif_colors)
281                .transparency(opts.transparent)
282                .dither(true)
283                .diff_rects(true)
284                .palette_mode(PaletteMode::Local);
285            encode_gif(
286                opts.width,
287                opts.height,
288                0,
289                &gif_opts,
290                frames.into_iter().map(|rgba| (rgba, 1, delay_den)),
291            )
292        }
293        BrowserCodec::Apng => {
294            let mut encoder = ApngEncoder::new(opts.width, opts.height, 0);
295            let n = frames.len();
296            for (i, mut rgba) in frames.into_iter().enumerate() {
297                if !opts.transparent {
298                    for pixel in rgba.as_chunks_mut::<4>().0 {
299                        pixel[3] = 255;
300                    }
301                }
302                encoder.add_frame(&rgba, 1, delay_den);
303                let done = (i + 1) as u32;
304                on_progress(make_anim_progress(
305                    AnimationExportPhase::Encode,
306                    done,
307                    n as u32,
308                    done as f32 / n as f32,
309                    opts.codec,
310                ));
311            }
312            encoder.finish()
313        }
314        BrowserCodec::Webm => {
315            let yuv: Vec<Yuv420Frame> = frames
316                .drain(..)
317                .map(|rgba| {
318                    let mut frame = Yuv420Frame::from_rgba(opts.width, opts.height, &rgba);
319                    if !opts.transparent {
320                        frame.alpha = None;
321                    }
322                    frame
323                })
324                .collect();
325            let refs: Vec<&Yuv420Frame> = yuv.iter().collect();
326            encode_webm(&refs, opts.fps)
327        }
328        BrowserCodec::Mp4 | BrowserCodec::Mp4Hevc => {
329            if opts.transparent {
330                return Err(AnimationEncodeError::Dimension);
331            }
332            let n = frames.len();
333            let mut yuv = Vec::with_capacity(n);
334            for rgba in frames.drain(..) {
335                yuv.push(Yuv420Frame::from_rgba(opts.width, opts.height, &rgba));
336                let done = yuv.len() as u32;
337                on_progress(make_anim_progress(
338                    AnimationExportPhase::Encode,
339                    done,
340                    n as u32,
341                    done as f32 / n as f32,
342                    opts.codec,
343                ));
344            }
345            if matches!(opts.codec, BrowserCodec::Mp4Hevc) {
346                // QP 26 is the middle of the usable range; see `encode_mp4`.
347                encode_compressed_mp4(opts.width, opts.height, opts.fps, 26, &yuv)
348            } else {
349                encode_mp4_with_captions(opts.width, opts.height, opts.fps, &yuv, None)
350            }
351        }
352    };
353
354    on_progress(make_anim_progress(
355        AnimationExportPhase::Done,
356        total,
357        total,
358        1.0,
359        opts.codec,
360    ));
361    Ok(bytes)
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.as_chunks_mut::<4>().0 {
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!(
471                    result,
472                    Err(AnimationEncodeError::FeatureDisabled("gif"))
473                ));
474                continue;
475            }
476            let bytes = result.unwrap();
477            assert!(bytes.len() > header.len());
478            if matches!(codec, BrowserCodec::Mp4) {
479                assert_eq!(&bytes[4..8], header);
480            } else {
481                assert_eq!(&bytes[..header.len()], header);
482            }
483        }
484    }
485}