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 [(WebmCodec::Vp8, "V_VP8"), (WebmCodec::Vp9, "V_VP9"), (WebmCodec::Av1, "V_AV1")] {
557 let frame = WebmFrame { data: &[0x12, 0x00], alpha: None, timecode: 0, keyframe: true };
558 let bytes = mux_webm(&WebmParams {
559 width: 16,
560 height: 16,
561 codec,
562 timecode_scale_ns: 1_000_000,
563 frames: &[frame],
564 });
565 let mkv = crate::mkv_demux::Mkv::parse(&bytes).unwrap();
566 assert_eq!(mkv.tracks[0].codec_id, id);
567 }
568 }
569
570 #[test]
571 fn vint_lengths_and_values() {
572 assert_eq!(vint(0), vec![0x80]);
573 assert_eq!(vint(1), vec![0x81]);
574 assert_eq!(vint(126), vec![0xFE]); assert_eq!(vint(127), vec![0x40, 0x7F]); assert_eq!(vint(0x3FFE), vec![0x7F, 0xFE]); }
578
579 #[test]
580 fn id_and_uint_encoding() {
581 assert_eq!(id_bytes(ID_SIMPLE_BLOCK), vec![0xA3]);
582 assert_eq!(id_bytes(ID_TIMECODE_SCALE), vec![0x2A, 0xD7, 0xB1]);
583 assert_eq!(id_bytes(ID_EBML), vec![0x1A, 0x45, 0xDF, 0xA3]);
584 assert_eq!(uint(0), vec![0x00]);
585 assert_eq!(uint(640), vec![0x02, 0x80]);
586 assert_eq!(uint(0x1_0000), vec![0x01, 0x00, 0x00]);
587 }
588
589 fn check_tree(buf: &[u8]) {
592 fn read_vint(b: &[u8], pos: &mut usize) -> u64 {
593 let first = b[*pos];
594 let len = first.leading_zeros() as usize + 1;
595 let mut v = (first & (0xff >> len)) as u64;
596 for k in 1..len {
597 v = (v << 8) | b[*pos + k] as u64;
598 }
599 *pos += len;
600 v
601 }
602 fn walk(b: &[u8], mut pos: usize, end: usize, masters: &[u32]) {
603 while pos < end {
604 let id_len = b[pos].leading_zeros() as usize + 1;
606 let mut id = 0u32;
607 for k in 0..id_len {
608 id = (id << 8) | b[pos + k] as u32;
609 }
610 pos += id_len;
611 let size = read_vint(b, &mut pos) as usize;
612 assert!(pos + size <= end, "element {id:X} overflows parent");
613 if masters.contains(&id) {
614 walk(b, pos, pos + size, masters);
615 }
616 pos += size;
617 }
618 assert_eq!(pos, end, "children tile the parent exactly");
619 }
620 let masters = [
621 ID_EBML,
622 ID_SEGMENT,
623 ID_INFO,
624 ID_TRACKS,
625 ID_TRACK_ENTRY,
626 ID_VIDEO,
627 ID_CLUSTER,
628 ID_BLOCK_GROUP,
629 ID_BLOCK_ADDITIONS,
630 ID_BLOCK_MORE,
631 ];
632 walk(buf, 0, buf.len(), &masters);
633 }
634
635 #[test]
636 fn structure_is_well_formed() {
637 let f0 = WebmFrame {
638 data: &[1, 2, 3, 4],
639 alpha: None,
640 timecode: 0,
641 keyframe: true,
642 };
643 let f1 = WebmFrame {
644 data: &[5, 6, 7],
645 alpha: None,
646 timecode: 33,
647 keyframe: false,
648 };
649 let out = mux_webm(&WebmParams {
650 width: 320,
651 height: 240,
652 codec: WebmCodec::Vp9,
653 timecode_scale_ns: 1_000_000,
654 frames: &[f0, f1],
655 });
656 assert_eq!(&out[..4], &[0x1A, 0x45, 0xDF, 0xA3]);
658 check_tree(&out);
659 }
660
661 #[test]
662 fn frames_split_across_clusters_on_timecode_overflow() {
663 let f0 = WebmFrame {
665 data: &[0],
666 alpha: None,
667 timecode: 0,
668 keyframe: true,
669 };
670 let f1 = WebmFrame {
671 data: &[0],
672 alpha: None,
673 timecode: 100_000,
674 keyframe: true,
675 };
676 let out = mux_webm(&WebmParams {
677 width: 16,
678 height: 16,
679 codec: WebmCodec::Vp9,
680 timecode_scale_ns: 1_000_000,
681 frames: &[f0, f1],
682 });
683 check_tree(&out);
684 let clusters = out
685 .windows(4)
686 .filter(|w| *w == ID_CLUSTER.to_be_bytes())
687 .count();
688 assert_eq!(clusters, 2, "each far-apart frame gets its own cluster");
689 }
690
691 #[test]
692 fn encode_gray_webm_is_well_formed() {
693 let out = encode_gray_webm(64, 64, 2, 30);
694 assert_eq!(&out[..4], &[0x1A, 0x45, 0xDF, 0xA3]);
695 check_tree(&out);
696 assert!(out.windows(4).any(|w| w == b"webm"));
698 assert!(out.windows(5).any(|w| w == b"V_VP9"));
699 }
700
701 #[test]
702 fn alpha_frame_uses_block_group() {
703 let color = [1u8, 2, 3, 4];
704 let alpha = [9u8, 8, 7, 6, 5];
705 let f = WebmFrame {
706 data: &color,
707 alpha: Some(&alpha),
708 timecode: 0,
709 keyframe: true,
710 };
711 let out = mux_webm(&WebmParams {
712 width: 8,
713 height: 8,
714 codec: WebmCodec::Vp9,
715 timecode_scale_ns: 1_000_000,
716 frames: &[f],
717 });
718 check_tree(&out);
719 assert!(
720 out.windows(2).any(|w| w == [0x53, 0xC0]),
721 "AlphaMode present"
722 );
723 assert!(
724 out.windows(2).any(|w| w == [0x75, 0xA1]),
725 "BlockAdditions present"
726 );
727 assert!(out.windows(1).any(|w| w == [0xA0]), "BlockGroup present");
728 }
729}