1use 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#[derive(Clone, Copy, Debug, PartialEq, Eq)]
18pub enum BrowserCodec {
19 Gif,
21 Apng,
23 Webm,
25 Mp4,
31 Mp4Hevc,
38}
39
40impl BrowserCodec {
41 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#[derive(Clone, Copy, Debug, PartialEq, Eq)]
54pub enum AnimationExportPhase {
55 Capture,
57 Encode,
59 Done,
61}
62
63#[derive(Clone, Debug)]
65pub struct AnimationExportProgress {
66 pub phase: AnimationExportPhase,
68 pub frame: u32,
70 pub frames: u32,
72 pub ratio: f32,
74 pub codec: BrowserCodec,
76 pub message: String,
78}
79
80pub 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#[derive(Debug)]
118pub enum AnimationEncodeError {
119 Empty,
121 FrameSize {
123 frame: usize,
125 expected: usize,
127 got: usize,
129 },
130 Dimension,
132 Io(String),
134 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
164pub struct AnimationEncodeOptions {
166 pub width: u32,
168 pub height: u32,
170 pub fps: u32,
172 pub codec: BrowserCodec,
174 pub transparent: bool,
176 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
193pub 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
201pub 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 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 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
364fn 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 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 encode_compressed_mp4_from_iter(w, h, opts.fps, 26, None, yuv)
419 } else {
420 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 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}