1use crate::captions::CaptionTrack;
24
25const ID_EBML: u32 = 0x1A45_DFA3;
27const ID_EBML_VERSION: u32 = 0x4286;
28const ID_EBML_READ_VERSION: u32 = 0x42F7;
29const ID_EBML_MAX_ID_LENGTH: u32 = 0x42F2;
30const ID_EBML_MAX_SIZE_LENGTH: u32 = 0x42F3;
31const ID_DOC_TYPE: u32 = 0x4282;
32const ID_DOC_TYPE_VERSION: u32 = 0x4287;
33const ID_DOC_TYPE_READ_VERSION: u32 = 0x4285;
34
35const ID_SEGMENT: u32 = 0x1853_8067;
36const ID_INFO: u32 = 0x1549_A966;
37const ID_TIMECODE_SCALE: u32 = 0x002A_D7B1;
38const ID_DURATION: u32 = 0x4489;
39const ID_MUXING_APP: u32 = 0x4D80;
40const ID_WRITING_APP: u32 = 0x5741;
41
42const ID_TRACKS: u32 = 0x1654_AE6B;
43const ID_TRACK_ENTRY: u32 = 0xAE;
44const ID_TRACK_NUMBER: u32 = 0xD7;
45const ID_TRACK_UID: u32 = 0x73C5;
46const ID_TRACK_TYPE: u32 = 0x83;
47const ID_FLAG_LACING: u32 = 0x9C;
48const ID_CODEC_ID: u32 = 0x86;
49const ID_VIDEO: u32 = 0xE0;
50const ID_PIXEL_WIDTH: u32 = 0xB0;
51const ID_PIXEL_HEIGHT: u32 = 0xBA;
52const ID_ALPHA_MODE: u32 = 0x53C0;
53
54const ID_CODEC_PRIVATE: u32 = 0x63A2;
55const ID_LANGUAGE: u32 = 0x22B59C;
56const ID_NAME: u32 = 0x536E;
57const ID_FLAG_DEFAULT: u32 = 0x88;
58
59const ID_CLUSTER: u32 = 0x1F43_B675;
60const ID_TIMECODE: u32 = 0xE7;
61const ID_SIMPLE_BLOCK: u32 = 0xA3;
62const ID_BLOCK_GROUP: u32 = 0xA0;
63const ID_BLOCK: u32 = 0xA1;
64const ID_BLOCK_DURATION: u32 = 0x9B;
65const ID_BLOCK_ADDITIONS: u32 = 0x75A1;
66const ID_BLOCK_MORE: u32 = 0xA6;
67const ID_BLOCK_ADD_ID: u32 = 0xEE;
68const ID_BLOCK_ADDITIONAL: u32 = 0xA5;
69
70const SUBTITLE_TRACK: u64 = 2;
72
73#[derive(Clone, Copy, Debug, PartialEq, Eq)]
75pub enum WebmCodec {
76 Vp8,
78 Vp9,
80 Av1,
82}
83
84impl WebmCodec {
85 fn codec_id(self) -> &'static [u8] {
86 match self {
87 WebmCodec::Vp8 => b"V_VP8",
88 WebmCodec::Vp9 => b"V_VP9",
89 WebmCodec::Av1 => b"V_AV1",
90 }
91 }
92}
93
94pub struct WebmFrame<'a> {
96 pub data: &'a [u8],
98 pub alpha: Option<&'a [u8]>,
100 pub timecode: u64,
102 pub keyframe: bool,
104}
105
106pub struct WebmParams<'a> {
108 pub width: u32,
110 pub height: u32,
112 pub codec: WebmCodec,
114 pub timecode_scale_ns: u32,
117 pub frames: &'a [WebmFrame<'a>],
119}
120
121fn vint(value: u64) -> Vec<u8> {
125 let mut len = 1usize;
126 while len < 8 && value >= (1u64 << (7 * len)) - 1 {
127 len += 1;
128 }
129 let mut bytes = vec![0u8; len];
130 let mut v = value;
131 for i in (0..len).rev() {
132 bytes[i] = (v & 0xff) as u8;
133 v >>= 8;
134 }
135 bytes[0] |= 1 << (8 - len); bytes
137}
138
139fn id_bytes(id: u32) -> Vec<u8> {
141 let b = id.to_be_bytes();
142 let start = b.iter().position(|&x| x != 0).unwrap_or(3);
143 b[start..].to_vec()
144}
145
146fn uint(mut value: u64) -> Vec<u8> {
148 if value == 0 {
149 return vec![0];
150 }
151 let mut bytes = Vec::new();
152 while value != 0 {
153 bytes.push((value & 0xff) as u8);
154 value >>= 8;
155 }
156 bytes.reverse();
157 bytes
158}
159
160fn elem(id: u32, payload: &[u8]) -> Vec<u8> {
162 let mut v = id_bytes(id);
163 v.extend_from_slice(&vint(payload.len() as u64));
164 v.extend_from_slice(payload);
165 v
166}
167
168fn concat(parts: &[Vec<u8>]) -> Vec<u8> {
169 let mut v = Vec::new();
170 for p in parts {
171 v.extend_from_slice(p);
172 }
173 v
174}
175
176pub fn encode_gray_webm(width: u32, height: u32, frame_count: u32, fps: u32) -> Vec<u8> {
183 assert!(frame_count >= 1, "need at least one frame");
184 assert!(fps >= 1, "fps must be >= 1");
185
186 let bitstream = crate::vp9::encode_intra_gray(width, height);
187 let tick_ms = (1000u64 / fps as u64).max(1);
188 let frames: Vec<WebmFrame> = (0..frame_count)
189 .map(|i| WebmFrame {
190 data: &bitstream,
191 alpha: None,
192 timecode: i as u64 * tick_ms,
193 keyframe: true,
194 })
195 .collect();
196
197 mux_webm(&WebmParams {
198 width,
199 height,
200 codec: WebmCodec::Vp9,
201 timecode_scale_ns: 1_000_000,
202 frames: &frames,
203 })
204}
205
206pub fn encode_webm(frames_yuv: &[&crate::hevc::Yuv420Frame], fps: u32) -> Vec<u8> {
213 assert!(!frames_yuv.is_empty(), "need at least one frame");
214 assert!(fps >= 1, "fps must be >= 1");
215 let (w, h) = (frames_yuv[0].width, frames_yuv[0].height);
216 for f in frames_yuv {
217 assert_eq!((f.width, f.height), (w, h), "all frames must share a size");
218 }
219
220 let color: Vec<Vec<u8>> = frames_yuv
221 .iter()
222 .map(|f| crate::vp9::encode_intra_frame(f).0)
223 .collect();
224
225 let alpha: Vec<Option<Vec<u8>>> = frames_yuv
226 .iter()
227 .map(|f| {
228 f.alpha.as_ref().map(|a| {
229 assert_eq!(a.len(), (w * h) as usize, "alpha plane size");
230 let mut plane = crate::hevc::Yuv420Frame::new(w, h);
231 plane.y.copy_from_slice(a);
232 plane.u.fill(128);
233 plane.v.fill(128);
234 crate::vp9::encode_intra_frame(&plane).0
235 })
236 })
237 .collect();
238
239 let tick_ms = (1000u64 / fps as u64).max(1);
240 let frames: Vec<WebmFrame> = color
241 .iter()
242 .zip(alpha.iter())
243 .enumerate()
244 .map(|(i, (b, a))| WebmFrame {
245 data: b,
246 alpha: a.as_deref(),
247 timecode: i as u64 * tick_ms,
248 keyframe: true,
249 })
250 .collect();
251
252 mux_webm(&WebmParams {
253 width: w,
254 height: h,
255 codec: WebmCodec::Vp9,
256 timecode_scale_ns: 1_000_000,
257 frames: &frames,
258 })
259}
260
261pub fn mux_webm(p: &WebmParams) -> Vec<u8> {
263 mux(p, None)
264}
265
266pub fn mux_webm_with_captions(p: &WebmParams, captions: &CaptionTrack) -> Vec<u8> {
288 mux(p, Some(captions))
289}
290
291fn mux(p: &WebmParams, captions: Option<&CaptionTrack>) -> Vec<u8> {
292 let scale = if p.timecode_scale_ns == 0 {
293 1_000_000
294 } else {
295 p.timecode_scale_ns
296 };
297 let alpha_mode = p.frames.iter().any(|f| f.alpha.is_some());
298 let caption_blocks = captions
299 .map(|t| caption_blocks(t, scale))
300 .unwrap_or_default();
301
302 let ebml = elem(
304 ID_EBML,
305 &concat(&[
306 elem(ID_EBML_VERSION, &uint(1)),
307 elem(ID_EBML_READ_VERSION, &uint(1)),
308 elem(ID_EBML_MAX_ID_LENGTH, &uint(4)),
309 elem(ID_EBML_MAX_SIZE_LENGTH, &uint(8)),
310 elem(ID_DOC_TYPE, b"webm"),
311 elem(ID_DOC_TYPE_VERSION, &uint(2)),
312 elem(ID_DOC_TYPE_READ_VERSION, &uint(2)),
313 ]),
314 );
315
316 let last = p.frames.last();
318 let video_end = last.map(|f| f.timecode + 1).unwrap_or(0);
319 let caption_end = caption_blocks
320 .last()
321 .map(|c| c.timecode + c.duration)
322 .unwrap_or(0);
323 let duration = video_end.max(caption_end) as f64;
324 let info = elem(
325 ID_INFO,
326 &concat(&[
327 elem(ID_TIMECODE_SCALE, &uint(scale as u64)),
328 elem(ID_DURATION, &duration.to_bits().to_be_bytes()),
329 elem(ID_MUXING_APP, b"threers"),
330 elem(ID_WRITING_APP, b"threers"),
331 ]),
332 );
333
334 let mut video_parts = vec![
336 elem(ID_PIXEL_WIDTH, &uint(p.width as u64)),
337 elem(ID_PIXEL_HEIGHT, &uint(p.height as u64)),
338 ];
339 if alpha_mode {
340 video_parts.push(elem(ID_ALPHA_MODE, &uint(1)));
341 }
342 let video = elem(ID_VIDEO, &concat(&video_parts));
343 let track_entry = elem(
344 ID_TRACK_ENTRY,
345 &concat(&[
346 elem(ID_TRACK_NUMBER, &uint(1)),
347 elem(ID_TRACK_UID, &uint(1)),
348 elem(ID_TRACK_TYPE, &uint(1)), elem(ID_FLAG_LACING, &uint(0)),
350 elem(ID_CODEC_ID, p.codec.codec_id()),
351 video,
352 ]),
353 );
354 let mut track_entries = vec![track_entry];
355 if !caption_blocks.is_empty() {
356 let track = captions.expect("caption blocks imply a caption track");
357 let mut parts = vec![
358 elem(ID_TRACK_NUMBER, &uint(SUBTITLE_TRACK)),
359 elem(ID_TRACK_UID, &uint(SUBTITLE_TRACK)),
360 elem(ID_TRACK_TYPE, &uint(17)), elem(ID_FLAG_LACING, &uint(0)),
362 elem(ID_FLAG_DEFAULT, &uint(1)),
363 elem(ID_LANGUAGE, &crate::captions::iso639_2(&track.language)),
364 elem(ID_CODEC_ID, b"D_WEBVTT/SUBTITLES"),
365 elem(ID_CODEC_PRIVATE, b""),
367 ];
368 if !track.label.is_empty() {
369 parts.push(elem(ID_NAME, track.label.as_bytes()));
370 }
371 track_entries.push(elem(ID_TRACK_ENTRY, &concat(&parts)));
372 }
373 let tracks = elem(ID_TRACKS, &concat(&track_entries));
374
375 let mut items: Vec<Item> = p.frames.iter().map(Item::Frame).collect();
379 items.extend(caption_blocks.iter().map(Item::Caption));
380 items.sort_by_key(|it| (it.timecode(), it.order()));
381
382 let mut clusters: Vec<Vec<u8>> = Vec::new();
385 let mut i = 0;
386 while i < items.len() {
387 let base = items[i].timecode();
388 let mut blocks = vec![elem(ID_TIMECODE, &uint(base))];
389 while i < items.len() {
390 let rel = items[i].timecode() as i64 - base as i64;
391 if rel > i16::MAX as i64 {
392 break;
393 }
394 blocks.push(match &items[i] {
395 Item::Frame(f) => cluster_frame(f, rel as i16),
396 Item::Caption(c) => caption_block_group(c, rel as i16),
397 });
398 i += 1;
399 }
400 clusters.push(elem(ID_CLUSTER, &concat(&blocks)));
401 }
402
403 let mut segment_children = vec![info, tracks];
404 segment_children.extend(clusters);
405 let segment = elem(ID_SEGMENT, &concat(&segment_children));
406
407 concat(&[ebml, segment])
408}
409
410struct CaptionBlock {
412 timecode: u64,
413 duration: u64,
414 payload: Vec<u8>,
416}
417
418enum Item<'a> {
420 Frame(&'a WebmFrame<'a>),
421 Caption(&'a CaptionBlock),
422}
423
424impl Item<'_> {
425 fn timecode(&self) -> u64 {
426 match self {
427 Item::Frame(f) => f.timecode,
428 Item::Caption(c) => c.timecode,
429 }
430 }
431
432 fn order(&self) -> u8 {
434 match self {
435 Item::Frame(_) => 0,
436 Item::Caption(_) => 1,
437 }
438 }
439}
440
441fn caption_blocks(track: &crate::captions::CaptionTrack, scale_ns: u32) -> Vec<CaptionBlock> {
443 let ticks = |seconds: f64| -> u64 {
444 (seconds.max(0.0) * 1_000_000_000.0 / scale_ns.max(1) as f64).round() as u64
445 };
446 let mut blocks: Vec<CaptionBlock> = track
447 .cues
448 .iter()
449 .filter_map(|cue| {
450 let text = cue.text.trim_end();
451 if text.is_empty() {
452 return None;
453 }
454 let start = ticks(cue.start);
455 let end = ticks(cue.end).max(start);
456 let mut payload = Vec::new();
457 payload.extend_from_slice(cue.id.as_deref().unwrap_or("").as_bytes());
458 payload.push(b'\n');
459 payload.extend_from_slice(cue_settings(cue).as_bytes());
460 payload.push(b'\n');
461 payload.extend_from_slice(text.as_bytes());
462 Some(CaptionBlock {
463 timecode: start,
464 duration: (end - start).max(1),
466 payload,
467 })
468 })
469 .collect();
470 blocks.sort_by_key(|b| b.timecode);
471 blocks
472}
473
474fn cue_settings(cue: &crate::captions::Cue) -> String {
476 use crate::captions::CaptionAlign;
477 let mut parts: Vec<String> = Vec::new();
478 if let Some(align) = cue.align {
479 parts.push(
480 match align {
481 CaptionAlign::Left => "align:left",
482 CaptionAlign::Center => "align:center",
483 CaptionAlign::Right => "align:right",
484 }
485 .to_string(),
486 );
487 }
488 if let Some(line) = cue.line {
489 parts.push(format!("line:{:.0}%", line * 100.0));
490 }
491 if let Some(position) = cue.position {
492 parts.push(format!("position:{:.0}%", position * 100.0));
493 }
494 parts.join(" ")
495}
496
497fn caption_block_group(caption: &CaptionBlock, rel_timecode: i16) -> Vec<u8> {
500 let mut payload = vint(SUBTITLE_TRACK);
501 payload.extend_from_slice(&rel_timecode.to_be_bytes());
502 payload.push(0x00); payload.extend_from_slice(&caption.payload);
504 elem(
505 ID_BLOCK_GROUP,
506 &concat(&[
507 elem(ID_BLOCK, &payload),
508 elem(ID_BLOCK_DURATION, &uint(caption.duration)),
509 ]),
510 )
511}
512
513fn cluster_frame(frame: &WebmFrame, rel_timecode: i16) -> Vec<u8> {
515 match frame.alpha {
516 None => simple_block(frame, rel_timecode),
517 Some(alpha) => block_group_with_alpha(frame, alpha, rel_timecode),
518 }
519}
520
521fn block_payload(frame: &WebmFrame, rel_timecode: i16) -> Vec<u8> {
523 let mut payload = vint(1); payload.extend_from_slice(&rel_timecode.to_be_bytes());
525 payload.push(if frame.keyframe { 0x80 } else { 0x00 });
526 payload.extend_from_slice(frame.data);
527 payload
528}
529
530fn simple_block(frame: &WebmFrame, rel_timecode: i16) -> Vec<u8> {
532 elem(ID_SIMPLE_BLOCK, &block_payload(frame, rel_timecode))
533}
534
535fn block_group_with_alpha(frame: &WebmFrame, alpha: &[u8], rel_timecode: i16) -> Vec<u8> {
537 let block = elem(ID_BLOCK, &block_payload(frame, rel_timecode));
538 let more = elem(
539 ID_BLOCK_MORE,
540 &concat(&[
541 elem(ID_BLOCK_ADD_ID, &uint(1)),
542 elem(ID_BLOCK_ADDITIONAL, alpha),
543 ]),
544 );
545 let additions = elem(ID_BLOCK_ADDITIONS, &more);
546 elem(ID_BLOCK_GROUP, &concat(&[block, additions]))
547}
548
549#[cfg(test)]
550mod tests {
551 use super::*;
552
553 #[test]
555 fn codec_ids_read_back() {
556 for (codec, id) in [
557 (WebmCodec::Vp8, "V_VP8"),
558 (WebmCodec::Vp9, "V_VP9"),
559 (WebmCodec::Av1, "V_AV1"),
560 ] {
561 let frame = WebmFrame {
562 data: &[0x12, 0x00],
563 alpha: None,
564 timecode: 0,
565 keyframe: true,
566 };
567 let bytes = mux_webm(&WebmParams {
568 width: 16,
569 height: 16,
570 codec,
571 timecode_scale_ns: 1_000_000,
572 frames: &[frame],
573 });
574 let mkv = crate::mkv_demux::Mkv::parse(&bytes).unwrap();
575 assert_eq!(mkv.tracks[0].codec_id, id);
576 }
577 }
578
579 #[test]
580 fn vint_lengths_and_values() {
581 assert_eq!(vint(0), vec![0x80]);
582 assert_eq!(vint(1), vec![0x81]);
583 assert_eq!(vint(126), vec![0xFE]); assert_eq!(vint(127), vec![0x40, 0x7F]); assert_eq!(vint(0x3FFE), vec![0x7F, 0xFE]); }
587
588 #[test]
589 fn id_and_uint_encoding() {
590 assert_eq!(id_bytes(ID_SIMPLE_BLOCK), vec![0xA3]);
591 assert_eq!(id_bytes(ID_TIMECODE_SCALE), vec![0x2A, 0xD7, 0xB1]);
592 assert_eq!(id_bytes(ID_EBML), vec![0x1A, 0x45, 0xDF, 0xA3]);
593 assert_eq!(uint(0), vec![0x00]);
594 assert_eq!(uint(640), vec![0x02, 0x80]);
595 assert_eq!(uint(0x1_0000), vec![0x01, 0x00, 0x00]);
596 }
597
598 fn check_tree(buf: &[u8]) {
601 fn read_vint(b: &[u8], pos: &mut usize) -> u64 {
602 let first = b[*pos];
603 let len = first.leading_zeros() as usize + 1;
604 let mut v = (first & (0xff >> len)) as u64;
605 for k in 1..len {
606 v = (v << 8) | b[*pos + k] as u64;
607 }
608 *pos += len;
609 v
610 }
611 fn walk(b: &[u8], mut pos: usize, end: usize, masters: &[u32]) {
612 while pos < end {
613 let id_len = b[pos].leading_zeros() as usize + 1;
615 let mut id = 0u32;
616 for k in 0..id_len {
617 id = (id << 8) | b[pos + k] as u32;
618 }
619 pos += id_len;
620 let size = read_vint(b, &mut pos) as usize;
621 assert!(pos + size <= end, "element {id:X} overflows parent");
622 if masters.contains(&id) {
623 walk(b, pos, pos + size, masters);
624 }
625 pos += size;
626 }
627 assert_eq!(pos, end, "children tile the parent exactly");
628 }
629 let masters = [
630 ID_EBML,
631 ID_SEGMENT,
632 ID_INFO,
633 ID_TRACKS,
634 ID_TRACK_ENTRY,
635 ID_VIDEO,
636 ID_CLUSTER,
637 ID_BLOCK_GROUP,
638 ID_BLOCK_ADDITIONS,
639 ID_BLOCK_MORE,
640 ];
641 walk(buf, 0, buf.len(), &masters);
642 }
643
644 #[test]
645 fn structure_is_well_formed() {
646 let f0 = WebmFrame {
647 data: &[1, 2, 3, 4],
648 alpha: None,
649 timecode: 0,
650 keyframe: true,
651 };
652 let f1 = WebmFrame {
653 data: &[5, 6, 7],
654 alpha: None,
655 timecode: 33,
656 keyframe: false,
657 };
658 let out = mux_webm(&WebmParams {
659 width: 320,
660 height: 240,
661 codec: WebmCodec::Vp9,
662 timecode_scale_ns: 1_000_000,
663 frames: &[f0, f1],
664 });
665 assert_eq!(&out[..4], &[0x1A, 0x45, 0xDF, 0xA3]);
667 check_tree(&out);
668 }
669
670 #[test]
671 fn frames_split_across_clusters_on_timecode_overflow() {
672 let f0 = WebmFrame {
674 data: &[0],
675 alpha: None,
676 timecode: 0,
677 keyframe: true,
678 };
679 let f1 = WebmFrame {
680 data: &[0],
681 alpha: None,
682 timecode: 100_000,
683 keyframe: true,
684 };
685 let out = mux_webm(&WebmParams {
686 width: 16,
687 height: 16,
688 codec: WebmCodec::Vp9,
689 timecode_scale_ns: 1_000_000,
690 frames: &[f0, f1],
691 });
692 check_tree(&out);
693 let clusters = out
694 .windows(4)
695 .filter(|w| *w == ID_CLUSTER.to_be_bytes())
696 .count();
697 assert_eq!(clusters, 2, "each far-apart frame gets its own cluster");
698 }
699
700 #[test]
701 fn encode_gray_webm_is_well_formed() {
702 let out = encode_gray_webm(64, 64, 2, 30);
703 assert_eq!(&out[..4], &[0x1A, 0x45, 0xDF, 0xA3]);
704 check_tree(&out);
705 assert!(out.windows(4).any(|w| w == b"webm"));
707 assert!(out.windows(5).any(|w| w == b"V_VP9"));
708 }
709
710 #[test]
711 fn alpha_frame_uses_block_group() {
712 let color = [1u8, 2, 3, 4];
713 let alpha = [9u8, 8, 7, 6, 5];
714 let f = WebmFrame {
715 data: &color,
716 alpha: Some(&alpha),
717 timecode: 0,
718 keyframe: true,
719 };
720 let out = mux_webm(&WebmParams {
721 width: 8,
722 height: 8,
723 codec: WebmCodec::Vp9,
724 timecode_scale_ns: 1_000_000,
725 frames: &[f],
726 });
727 check_tree(&out);
728 assert!(
729 out.windows(2).any(|w| w == [0x53, 0xC0]),
730 "AlphaMode present"
731 );
732 assert!(
733 out.windows(2).any(|w| w == [0x75, 0xA1]),
734 "BlockAdditions present"
735 );
736 assert!(out.windows(1).any(|w| w == [0xA0]), "BlockGroup present");
737 }
738}