Skip to main content

threers_codec/
webm.rs

1//! Minimal WebM (Matroska / EBML) muxer for a single video track (pure Rust,
2//! wasm-safe).
3//!
4//! WebM is the subset of Matroska that browsers play: an EBML document whose
5//! `Segment` holds `Info`, `Tracks`, and one or more `Cluster`s of frames. This
6//! muxer emits exactly that for a single VP8 / VP9 / AV1 video track — enough for
7//! ffmpeg and every WebM-capable browser to open the result.
8//!
9//! Optional **alpha** is carried the WebM way: `AlphaMode = 1` on the track and a
10//! second VP9 bitstream in `BlockAdditional` (`BlockAddID = 1`) inside a
11//! `BlockGroup` (see Matroska codec mapping for `V_VP9`).
12//!
13//! Optional **subtitles** follow the WebM "WebVTT in WebM" mapping:
14//! a `D_WEBVTT/SUBTITLES` track whose every cue is a `BlockGroup` of a `Block`
15//! (payload `identifier\nsettings\ncue text`) plus a `BlockDuration`. See
16//! [`mux_webm_with_captions`].
17//!
18//! Everything is built bottom-up into `Vec<u8>` so each element's size is known
19//! before its parent is written (no streaming "unknown size" VINTs needed). The
20//! codec bitstream itself comes from the caller — pair this with a native VP9
21//! encoder (see [`crate::vp9`]) for a fully dependency-free `.webm`.
22
23use crate::captions::CaptionTrack;
24
25// ---- EBML element IDs (canonical, marker bits included) ----
26const 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
70/// Track number of the optional WebVTT subtitle track (video is track 1).
71const SUBTITLE_TRACK: u64 = 2;
72
73/// The video codec carried by the track (selects the Matroska `CodecID`).
74#[derive(Clone, Copy, Debug, PartialEq, Eq)]
75pub enum WebmCodec {
76    /// VP8 (`V_VP8`).
77    Vp8,
78    /// VP9 (`V_VP9`).
79    Vp9,
80    /// AV1 (`V_AV1`).
81    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
94/// One coded frame to place in the stream.
95pub struct WebmFrame<'a> {
96    /// The codec bitstream for this frame (a VP9 super-frame, VP8 frame, …).
97    pub data: &'a [u8],
98    /// Optional alpha-channel VP9 bitstream (`BlockAdditional`, `BlockAddID = 1`).
99    pub alpha: Option<&'a [u8]>,
100    /// Presentation time in `TimecodeScale` ticks from the start of the segment.
101    pub timecode: u64,
102    /// Whether this frame is a keyframe (sets the Block / SimpleBlock keyframe flag).
103    pub keyframe: bool,
104}
105
106/// Parameters for [`mux_webm`].
107pub struct WebmParams<'a> {
108    /// Picture width in pixels.
109    pub width: u32,
110    /// Picture height in pixels.
111    pub height: u32,
112    /// The codec of every frame.
113    pub codec: WebmCodec,
114    /// Nanoseconds per `TimecodeScale` tick — 1_000_000 gives millisecond
115    /// timecodes (the WebM default).
116    pub timecode_scale_ns: u32,
117    /// The frames, in presentation order.
118    pub frames: &'a [WebmFrame<'a>],
119}
120
121/// Encode `value` as an EBML variable-length integer (used for element sizes and
122/// the SimpleBlock track number). The minimal length is chosen; the all-ones
123/// pattern (reserved for "unknown size") is never produced.
124fn 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); // length-marker bit
136    bytes
137}
138
139/// Minimal big-endian bytes of `id` (its own marker bits give the length).
140fn 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
146/// Minimal big-endian encoding of an unsigned integer (at least one byte).
147fn 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
160/// One EBML element: `id`, then its size as a VINT, then `payload`.
161fn 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
176/// Encode `frame_count` solid mid-gray VP9 keyframes and mux them into a
177/// `.webm`. Uses the native [`crate::vp9`] encoder — no ffmpeg, no C
178/// bindings — so it runs on native and `wasm32`.
179///
180/// Currently only `64×64` is supported by the gray keyframe path. `fps` must
181/// be ≥ 1.
182pub 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
206/// Encode VP9 keyframes from planar YUV (optional alpha) and mux into a `.webm`.
207///
208/// Each frame is coded independently (all keyframes). Dimensions must be
209/// multiples of 8. When any frame carries [`crate::hevc::encoder::Yuv420Frame::alpha`], the track is
210/// marked `AlphaMode = 1` and each cluster uses a `BlockGroup` with the alpha
211/// plane coded as a second VP9 bitstream in `BlockAdditional`.
212pub 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
261/// Mux the frames into a single-track `.webm` byte stream.
262pub fn mux_webm(p: &WebmParams) -> Vec<u8> {
263    mux(p, None)
264}
265
266/// Mux the frames plus a WebVTT soft-subtitle track.
267///
268/// Follows the WebM "WebVTT in WebM" mapping: a second track with
269/// `CodecID = D_WEBVTT/SUBTITLES` and `TrackType = 17`, where each cue is a
270/// `BlockGroup` holding a `Block` whose payload is
271/// `identifier\nsettings\ncue text` and a `BlockDuration`. Browsers and ffmpeg
272/// both surface it as a selectable subtitle stream.
273///
274/// ```
275/// use threers_codec::webm::{mux_webm_with_captions, WebmCodec, WebmParams};
276/// use threers_codec::captions::CaptionTrack;
277/// let captions = CaptionTrack::new().language("en").cue(0.0, 2.0, "Hello");
278/// let bytes = mux_webm_with_captions(
279///     &WebmParams {
280///         width: 64, height: 64, codec: WebmCodec::Vp9,
281///         timecode_scale_ns: 1_000_000, frames: &[],
282///     },
283///     &captions,
284/// );
285/// assert!(bytes.windows(18).any(|w| w == b"D_WEBVTT/SUBTITLES"));
286/// ```
287pub 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    // ---- EBML header (DocType = "webm") ----
303    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    // ---- Segment > Info ----
317    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    // ---- Segment > Tracks (one video track) ----
335    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)), // 1 = video
349            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)), // 17 = subtitle
361            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            // The WebVTT file header before the first cue; empty for plain files.
366            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    // ---- Segment > Cluster(s) ----
376    // Video frames and caption cues share one timeline; ties put the frame
377    // first so a Cluster still opens on a video block.
378    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    // A Block timecode is a signed 16-bit offset from its Cluster's Timecode,
383    // so start a fresh Cluster whenever the offset would overflow.
384    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
410/// One WebVTT cue laid out on the segment timeline, in `TimecodeScale` ticks.
411struct CaptionBlock {
412    timecode: u64,
413    duration: u64,
414    /// `identifier\nsettings\ncue text`, the WebM WebVTT block payload.
415    payload: Vec<u8>,
416}
417
418/// Either kind of thing that goes into a Cluster, so both can be merge-sorted.
419enum 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    /// Tie-break rank — video frames sort ahead of captions at equal timecodes.
433    fn order(&self) -> u8 {
434        match self {
435            Item::Frame(_) => 0,
436            Item::Caption(_) => 1,
437        }
438    }
439}
440
441/// Convert cues to timeline-ordered blocks in `TimecodeScale` ticks.
442fn 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                // A zero-duration cue would never display; give it one tick.
465                duration: (end - start).max(1),
466                payload,
467            })
468        })
469        .collect();
470    blocks.sort_by_key(|b| b.timecode);
471    blocks
472}
473
474/// The WebVTT cue settings list for a cue (`"align:left position:20%"`).
475fn 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
497/// A caption cue: `BlockGroup` of a `Block` on the subtitle track plus the
498/// `BlockDuration` it must carry (a `SimpleBlock` has nowhere to put one).
499fn 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); // no flags — Block has no keyframe bit
503    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
513/// Opaque frame → `SimpleBlock`; alpha frame → `BlockGroup` + `BlockAdditional`.
514fn 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
521/// Block / SimpleBlock payload: track VINT, 16-bit relative timecode, flags, data.
522fn block_payload(frame: &WebmFrame, rel_timecode: i16) -> Vec<u8> {
523    let mut payload = vint(1); // track number 1
524    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
530/// A SimpleBlock element (no alpha).
531fn simple_block(frame: &WebmFrame, rel_timecode: i16) -> Vec<u8> {
532    elem(ID_SIMPLE_BLOCK, &block_payload(frame, rel_timecode))
533}
534
535/// `BlockGroup` with colour `Block` and alpha in `BlockAdditional` (`BlockAddID = 1`).
536fn 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    /// Matroska's codec IDs, as the demuxers (ours and everyone's) match them.
554    #[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]); // max 1-byte (127 is reserved)
575        assert_eq!(vint(127), vec![0x40, 0x7F]); // rolls to 2 bytes
576        assert_eq!(vint(0x3FFE), vec![0x7F, 0xFE]); // max 2-byte
577    }
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    /// Walk the EBML tree and confirm every element's declared size fits inside
590    /// its parent and children tile the payload exactly.
591    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                // element ID: length from the marker bit of the first byte
605                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        // Starts with the EBML header ID.
657        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        // Two frames >32767 ticks apart must land in separate clusters.
664        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        // DocType "webm" appears in the EBML header.
697        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}