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!(f, "this build has no {feature} encoder (enable the `{feature}` feature)")
154 }
155 }
156 }
157}
158
159impl std::error::Error for AnimationEncodeError {}
160
161pub struct AnimationEncodeOptions {
163 pub width: u32,
165 pub height: u32,
167 pub fps: u32,
169 pub codec: BrowserCodec,
171 pub transparent: bool,
173 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
190pub 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
198pub 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 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 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
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.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 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}