Skip to main content

threers_codec/
mp4.rs

1//! Minimal ISOBMFF / MP4 muxer for H.264 and HEVC video tracks, optionally with
2//! a `tx3g` timed-text (subtitle) track. Pure Rust, wasm-safe.
3//!
4//! Enough of the box hierarchy to produce a `.mp4`/`.mov` that AVFoundation and
5//! ffmpeg open: `ftyp` + `mdat` + `moov`, with an `avc1`/`hvc1` sample entry
6//! carrying an `avcC`/`hvcC` config record (and, for transparent HEVC, Apple's
7//! `almo` alpha-mode box). NAL units inside samples are 4-byte length-prefixed
8//! (not Annex-B).
9//!
10//! [`mux_hevc_with_captions`] adds a second track holding 3GPP timed text
11//! (`tx3g`, what ffmpeg calls `mov_text`) — the soft-subtitle format MP4
12//! players understand, so the viewer can toggle captions off.
13//!
14//! Layout is `ftyp, mdat, moov` — `mdat` before `moov` so chunk offsets (`stco` /
15//! `co64`) are fixed before `moov`'s size is known. Boxes larger than 4 GiB use
16//! the ISOBMFF extended-size header.
17
18use crate::captions::CaptionTrack;
19
20/// Wrap `payload` in a box with `type_` (a 4-byte tag).
21///
22/// Uses the 64-bit ISOBMFF extended size (`size == 1` + `largesize`) when the
23/// box would exceed 4 GiB — required for long HEVC exports whose `mdat` is huge.
24pub(crate) fn bx(type_: &[u8; 4], payload: &[u8]) -> Vec<u8> {
25    let total = 8u64 + payload.len() as u64;
26    if total > u32::MAX as u64 {
27        let largesize = 16u64 + payload.len() as u64;
28        let mut v = Vec::with_capacity(largesize as usize);
29        v.extend_from_slice(&1u32.to_be_bytes()); // size == 1 → 64-bit largesize follows
30        v.extend_from_slice(type_);
31        v.extend_from_slice(&largesize.to_be_bytes());
32        v.extend_from_slice(payload);
33        v
34    } else {
35        let mut v = Vec::with_capacity(total as usize);
36        v.extend_from_slice(&(total as u32).to_be_bytes());
37        v.extend_from_slice(type_);
38        v.extend_from_slice(payload);
39        v
40    }
41}
42
43/// Header length of a serialized box: 16 bytes for the 64-bit extended form,
44/// 8 otherwise. Only the tests need this now that `mdat` is written in place.
45#[cfg(test)]
46fn box_header_len(box_bytes: &[u8]) -> usize {
47    if box_bytes.len() >= 8 && u32::from_be_bytes(box_bytes[0..4].try_into().unwrap()) == 1 {
48        16
49    } else {
50        8
51    }
52}
53
54/// A full-box (`version` + 24-bit `flags`) wrapping `payload`.
55pub(crate) fn fullbox(type_: &[u8; 4], version: u8, flags: u32, payload: &[u8]) -> Vec<u8> {
56    let mut p = Vec::with_capacity(4 + payload.len());
57    p.push(version);
58    p.extend_from_slice(&flags.to_be_bytes()[1..]);
59    p.extend_from_slice(payload);
60    bx(type_, &p)
61}
62
63pub(crate) fn concat(parts: &[Vec<u8>]) -> Vec<u8> {
64    let mut v = Vec::new();
65    for p in parts {
66        v.extend_from_slice(p);
67    }
68    v
69}
70
71/// Shared timing/layout fields for both H.264 and HEVC muxers.
72struct CommonMp4Params<'a> {
73    pub width: u32,
74    pub height: u32,
75    pub timescale: u32,
76    pub frame_duration: u32,
77    pub samples: &'a [Vec<u8>],
78}
79
80/// Parameters for [`mux_hevc`].
81pub struct Mp4Params<'a> {
82    /// Picture width in pixels.
83    pub width: u32,
84    /// Picture height in pixels.
85    pub height: u32,
86    /// Media timescale (ticks per second). Apple uses 600.
87    pub timescale: u32,
88    /// Duration of each sample in `timescale` ticks.
89    pub frame_duration: u32,
90    /// The `hvcC` box payload (without its size/type header) — see
91    /// [`crate::hevc::hvcc`].
92    pub hvcc_payload: &'a [u8],
93    /// Optional Apple `almo` alpha-mode box payload (4 bytes) to append to the
94    /// sample entry, signaling a transparent track.
95    pub almo_payload: Option<&'a [u8]>,
96    /// Per-frame sample data: each entry is that frame's NAL units, already
97    /// 4-byte length-prefixed and concatenated.
98    pub samples: &'a [Vec<u8>],
99}
100
101/// Parameters for [`mux_h264`].
102pub struct H264Mp4Params<'a> {
103    /// Picture width in pixels.
104    pub width: u32,
105    /// Picture height in pixels.
106    pub height: u32,
107    /// Media timescale (ticks per second).
108    pub timescale: u32,
109    /// Duration of each sample in `timescale` ticks.
110    pub frame_duration: u32,
111    /// The `avcC` box payload (without its size/type header) — see
112    /// [`crate::h264::avcc`].
113    pub avcc_payload: &'a [u8],
114    /// Per-frame sample data: each entry is that frame's NAL units, already
115    /// 4-byte length-prefixed and concatenated.
116    pub samples: &'a [Vec<u8>],
117}
118
119impl<'a> From<&Mp4Params<'a>> for CommonMp4Params<'a> {
120    fn from(p: &Mp4Params<'a>) -> Self {
121        Self {
122            width: p.width,
123            height: p.height,
124            timescale: p.timescale,
125            frame_duration: p.frame_duration,
126            samples: p.samples,
127        }
128    }
129}
130
131impl<'a> From<&H264Mp4Params<'a>> for CommonMp4Params<'a> {
132    fn from(p: &H264Mp4Params<'a>) -> Self {
133        Self {
134            width: p.width,
135            height: p.height,
136            timescale: p.timescale,
137            frame_duration: p.frame_duration,
138            samples: p.samples,
139        }
140    }
141}
142
143/// Mux one HEVC video track into a `.mp4`/`.mov` byte stream.
144pub fn mux_hevc(p: &Mp4Params) -> Vec<u8> {
145    mux_hevc_internal(p, None)
146}
147
148/// Mux an HEVC video track plus a `tx3g` soft-subtitle track.
149///
150/// The caption track becomes a second, selectable text track — the player can
151/// show or hide it, unlike burned-in captions. `tx3g` shows one sample at a
152/// time, so cues that overlap are serialized: a cue starting before the
153/// previous one ends is pushed back to that end time. Gaps between cues are
154/// filled with empty samples, which is how a `tx3g` track blanks the display.
155///
156/// ```no_run
157/// use threers_codec::mp4::{mux_hevc_with_captions, Mp4Params};
158/// use threers_codec::captions::CaptionTrack;
159/// let track = CaptionTrack::new().language("en").cue(0.0, 2.0, "Hello");
160/// let bytes = mux_hevc_with_captions(
161///     &Mp4Params {
162///         width: 640, height: 360, timescale: 600, frame_duration: 20,
163///         hvcc_payload: &[], almo_payload: None, samples: &[],
164///     },
165///     &track,
166/// );
167/// # let _ = bytes;
168/// ```
169pub fn mux_hevc_with_captions(p: &Mp4Params, captions: &CaptionTrack) -> Vec<u8> {
170    mux_hevc_internal(p, Some(captions))
171}
172
173/// Mux one H.264 video track into a `.mp4`/`.mov` byte stream.
174pub fn mux_h264(p: &H264Mp4Params) -> Vec<u8> {
175    mux_h264_internal(p, None)
176}
177
178/// Mux an H.264 video track plus a `tx3g` soft-subtitle track.
179/// [`mux_h264`] streamed to a sink — see `mux_common_to` for why.
180pub fn write_h264<W: std::io::Write>(
181    out: &mut W,
182    p: &H264Mp4Params,
183    captions: Option<&CaptionTrack>,
184) -> std::io::Result<()> {
185    let common = CommonMp4Params::from(p);
186    let stsd = build_h264_stsd(p);
187    mux_common_to(
188        out,
189        &common,
190        &[b"isom", b"iso2", b"avc1", b"mp41"],
191        stsd,
192        captions,
193    )
194}
195
196/// [`mux_hevc`] streamed to a sink — see `mux_common_to` for why.
197pub fn write_hevc<W: std::io::Write>(
198    out: &mut W,
199    p: &Mp4Params,
200    captions: Option<&CaptionTrack>,
201) -> std::io::Result<()> {
202    let common = CommonMp4Params::from(p);
203    let stsd = build_hevc_stsd(p);
204    mux_common_to(
205        out,
206        &common,
207        &[b"isom", b"iso2", b"mp41", b"hvc1"],
208        stsd,
209        captions,
210    )
211}
212
213/// Mux an H.264 video track plus a `tx3g` soft-subtitle track; see
214/// [`mux_hevc_with_captions`] for how cues become samples.
215pub fn mux_h264_with_captions(p: &H264Mp4Params, captions: &CaptionTrack) -> Vec<u8> {
216    mux_h264_internal(p, Some(captions))
217}
218
219fn mux_hevc_internal(p: &Mp4Params, captions: Option<&CaptionTrack>) -> Vec<u8> {
220    let common = CommonMp4Params::from(p);
221    let stsd = build_hevc_stsd(p);
222    mux_common(
223        &common,
224        &[b"isom", b"iso2", b"mp41", b"hvc1"],
225        stsd,
226        captions,
227    )
228}
229
230fn mux_h264_internal(p: &H264Mp4Params, captions: Option<&CaptionTrack>) -> Vec<u8> {
231    let common = CommonMp4Params::from(p);
232    let stsd = build_h264_stsd(p);
233    mux_common(
234        &common,
235        &[b"isom", b"iso2", b"mp41", b"avc1"],
236        stsd,
237        captions,
238    )
239}
240
241/// `ColourInformationBox` — the stream's colour, for players that read only
242/// the container.
243///
244/// The encoder already states this in the bitstream: it sets `ColorPrimaries`,
245/// `TransferFunction` and `YCbCrMatrix` on the VideoToolbox session, so the
246/// values reach the HEVC VUI. That is the durable place for them and it is not
247/// enough on its own, because not every player reads the VUI. The ones that do
248/// not fall back to guessing from the frame size, and the guess for a tall 4K
249/// frame is not reliably BT.709 — so the same file renders with different
250/// contrast in different players, most visibly on high-contrast edges, which
251/// is where a thin bright rail against black lives.
252///
253/// Both, then. The VUI survives a remux that rebuilds the container; this box
254/// is read by players that never look at the VUI.
255///
256/// The box says what the stream's own SPS says, so the two cannot disagree:
257/// threers' software encoders convert with BT.601 and state that in their
258/// VUI, VideoToolbox states BT.709. A stream whose SPS has no colour
259/// description gets BT.709, limited range — nothing asks VideoToolbox for
260/// full range, and its default for 8-bit is video range.
261fn colr_box(stream: Option<StreamColour>) -> Vec<u8> {
262    let c = stream.unwrap_or(StreamColour {
263        primaries: 1,
264        transfer: 1,
265        matrix: 1,
266        full_range: false,
267    });
268    let mut v = Vec::with_capacity(19);
269    v.extend_from_slice(b"nclx");
270    v.extend_from_slice(&c.primaries.to_be_bytes()); // colour_primaries
271    v.extend_from_slice(&c.transfer.to_be_bytes()); // transfer_characteristics
272    v.extend_from_slice(&c.matrix.to_be_bytes()); // matrix_coefficients
273    v.push((c.full_range as u8) << 7); // full_range_flag (1 bit) + reserved
274    bx(b"colr", &v)
275}
276
277/// A VUI colour description, as `colr` carries it.
278#[derive(Debug, Clone, Copy, PartialEq, Eq)]
279struct StreamColour {
280    primaries: u16,
281    transfer: u16,
282    matrix: u16,
283    full_range: bool,
284}
285
286impl StreamColour {
287    /// From a parsed SPS's VUI; `None` when it describes no matrix.
288    fn from_vui(
289        primaries: Option<u32>,
290        transfer: Option<u32>,
291        matrix: Option<u32>,
292        full_range: bool,
293    ) -> Option<Self> {
294        Some(StreamColour {
295            matrix: matrix? as u16,
296            primaries: primaries.unwrap_or(2) as u16,
297            transfer: transfer.unwrap_or(2) as u16,
298            full_range,
299        })
300    }
301
302    /// The first SPS in an `avcC` payload.
303    fn of_avcc(avcc: &[u8]) -> Option<Self> {
304        let count = *avcc.get(5)? & 31;
305        if count == 0 {
306            return None;
307        }
308        let len = u16::from_be_bytes([*avcc.get(6)?, *avcc.get(7)?]) as usize;
309        let nal = avcc.get(8..8 + len)?;
310        let sps =
311            crate::decode::h264::params::Sps::parse(&crate::decode::bits::unescape(nal.get(1..)?))
312                .ok()?;
313        Self::from_vui(
314            sps.colour_primaries,
315            sps.transfer_characteristics,
316            sps.matrix_coefficients,
317            sps.full_range,
318        )
319    }
320
321    /// The base layer's SPS in an `hvcC` payload.
322    fn of_hvcc(hvcc: &[u8]) -> Option<Self> {
323        let arrays = *hvcc.get(22)? as usize;
324        let mut at = 23;
325        for _ in 0..arrays {
326            let kind = *hvcc.get(at)? & 0x3f;
327            let count = u16::from_be_bytes([*hvcc.get(at + 1)?, *hvcc.get(at + 2)?]) as usize;
328            at += 3;
329            for _ in 0..count {
330                let len = u16::from_be_bytes([*hvcc.get(at)?, *hvcc.get(at + 1)?]) as usize;
331                let nal = hvcc.get(at + 2..at + 2 + len)?;
332                at += 2 + len;
333                let layer = ((nal.first()? & 1) << 5) | (nal.get(1)? >> 3);
334                if kind == 33 && layer == 0 {
335                    let rbsp = crate::decode::bits::unescape(nal.get(2..)?);
336                    let sps = crate::decode::hevc::params::Sps::parse(&rbsp).ok()?;
337                    return Self::from_vui(
338                        sps.colour_primaries,
339                        sps.transfer_characteristics,
340                        sps.matrix_coefficients,
341                        sps.full_range,
342                    );
343                }
344            }
345        }
346        None
347    }
348}
349
350fn build_hevc_stsd(p: &Mp4Params) -> Vec<u8> {
351    let hvcc = bx(b"hvcC", p.hvcc_payload);
352    let mut sample_entry = Vec::new();
353    sample_entry.extend_from_slice(&[0u8; 6]); // reserved
354    sample_entry.extend_from_slice(&1u16.to_be_bytes()); // data_reference_index
355    sample_entry.extend_from_slice(&[0u8; 16]); // pre_defined + reserved (2+2+12)
356    sample_entry.extend_from_slice(&(p.width as u16).to_be_bytes());
357    sample_entry.extend_from_slice(&(p.height as u16).to_be_bytes());
358    sample_entry.extend_from_slice(&0x0048_0000u32.to_be_bytes()); // horizresolution 72dpi
359    sample_entry.extend_from_slice(&0x0048_0000u32.to_be_bytes()); // vertresolution
360    sample_entry.extend_from_slice(&0u32.to_be_bytes()); // reserved
361    sample_entry.extend_from_slice(&1u16.to_be_bytes()); // frame_count
362    sample_entry.extend_from_slice(&[0u8; 32]); // compressorname
363    sample_entry.extend_from_slice(&0x0018u16.to_be_bytes()); // depth
364    sample_entry.extend_from_slice(&0xFFFFu16.to_be_bytes()); // pre_defined -1
365    sample_entry.extend_from_slice(&hvcc);
366    sample_entry.extend_from_slice(&colr_box(StreamColour::of_hvcc(p.hvcc_payload)));
367    if let Some(almo) = p.almo_payload {
368        sample_entry.extend_from_slice(&bx(b"almo", almo));
369    }
370    let hvc1 = bx(b"hvc1", &sample_entry);
371    let mut payload = Vec::new();
372    payload.extend_from_slice(&1u32.to_be_bytes()); // entry_count
373    payload.extend_from_slice(&hvc1);
374    fullbox(b"stsd", 0, 0, &payload)
375}
376
377fn build_h264_stsd(p: &H264Mp4Params) -> Vec<u8> {
378    let avcc = bx(b"avcC", p.avcc_payload);
379    let mut sample_entry = Vec::new();
380    sample_entry.extend_from_slice(&[0u8; 6]); // reserved
381    sample_entry.extend_from_slice(&1u16.to_be_bytes()); // data_reference_index
382    sample_entry.extend_from_slice(&[0u8; 16]); // pre_defined + reserved
383    sample_entry.extend_from_slice(&(p.width as u16).to_be_bytes());
384    sample_entry.extend_from_slice(&(p.height as u16).to_be_bytes());
385    sample_entry.extend_from_slice(&0x0048_0000u32.to_be_bytes()); // horizresolution
386    sample_entry.extend_from_slice(&0x0048_0000u32.to_be_bytes()); // vertresolution
387    sample_entry.extend_from_slice(&0u32.to_be_bytes()); // reserved
388    sample_entry.extend_from_slice(&1u16.to_be_bytes()); // frame_count
389    sample_entry.extend_from_slice(&[0u8; 32]); // compressorname
390    sample_entry.extend_from_slice(&0x0018u16.to_be_bytes()); // depth
391    sample_entry.extend_from_slice(&0xFFFFu16.to_be_bytes()); // pre_defined -1
392    sample_entry.extend_from_slice(&avcc);
393    sample_entry.extend_from_slice(&colr_box(StreamColour::of_avcc(p.avcc_payload)));
394    let avc1 = bx(b"avc1", &sample_entry);
395    let mut payload = Vec::new();
396    payload.extend_from_slice(&1u32.to_be_bytes()); // entry_count
397    payload.extend_from_slice(&avc1);
398    fullbox(b"stsd", 0, 0, &payload)
399}
400
401fn mux_common(
402    p: &CommonMp4Params,
403    brands: &[&[u8; 4]],
404    stsd: Vec<u8>,
405    captions: Option<&CaptionTrack>,
406) -> Vec<u8> {
407    let mut out = Vec::new();
408    // Writing into a Vec cannot fail, so the shared path's errors are unreachable here.
409    mux_common_to(&mut out, p, brands, stsd, captions).expect("writing to a Vec cannot fail");
410    out
411}
412
413/// [`mux_common`], streamed to a sink instead of returned.
414///
415/// The file is emitted as it is assembled, so nothing holds a complete copy of
416/// it. That matters for long exports: the sample data alone is the bulk of the
417/// file, and building the whole thing in memory first doubles it.
418fn mux_common_to<W: std::io::Write>(
419    out: &mut W,
420    p: &CommonMp4Params,
421    brands: &[&[u8; 4]],
422    stsd: Vec<u8>,
423    captions: Option<&CaptionTrack>,
424) -> std::io::Result<()> {
425    let num_samples = p.samples.len().max(1) as u32;
426    let total_duration = p.frame_duration * num_samples;
427
428    // ---- ftyp ----
429    let ftyp = bx(b"ftyp", &{
430        let mut v = Vec::new();
431        v.extend_from_slice(b"isom"); // major_brand
432        v.extend_from_slice(&0u32.to_be_bytes()); // minor_version
433        for brand in brands {
434            v.extend_from_slice(*brand);
435        }
436        v
437    });
438
439    // Timed-text samples share the video's timescale and run the full movie
440    // duration so the text track never ends early.
441    let text_samples = captions
442        .map(|t| build_text_samples(t, p.timescale, total_duration))
443        .unwrap_or_default();
444
445    // ---- mdat sizing ----
446    //
447    // Only the *size* is needed here; the payload is streamed straight into the
448    // output at the end. Materialising it would cost three full copies of the
449    // sample data (concat, then the box, then the final assembly), and at 4K the
450    // samples are already hundreds of megabytes.
451    let video_bytes: u64 = p.samples.iter().map(|s| s.len() as u64).sum();
452    let text_bytes: u64 = text_samples.iter().map(|s| s.data.len() as u64).sum();
453    let mdat_payload_len = video_bytes + text_bytes;
454    // Matches `bx`: the 64-bit extended header kicks in past 4 GiB.
455    let mdat_hdr = if 8 + mdat_payload_len > u32::MAX as u64 {
456        16
457    } else {
458        8
459    };
460    let mdat_data_offset = ftyp.len() as u64 + mdat_hdr as u64;
461    let text_data_offset = mdat_data_offset + video_bytes;
462
463    // ---- sample tables ----
464    let stts = fullbox(b"stts", 0, 0, &{
465        let mut v = Vec::new();
466        v.extend_from_slice(&1u32.to_be_bytes()); // entry_count
467        v.extend_from_slice(&num_samples.to_be_bytes()); // sample_count
468        v.extend_from_slice(&p.frame_duration.to_be_bytes()); // sample_delta
469        v
470    });
471
472    // All samples are IDR → all sync samples: stss lists them all.
473    let stss = fullbox(b"stss", 0, 0, &{
474        let mut v = Vec::new();
475        v.extend_from_slice(&num_samples.to_be_bytes());
476        for i in 1..=num_samples {
477            v.extend_from_slice(&i.to_be_bytes());
478        }
479        v
480    });
481
482    let stsc = fullbox(b"stsc", 0, 0, &{
483        let mut v = Vec::new();
484        v.extend_from_slice(&1u32.to_be_bytes()); // entry_count
485        v.extend_from_slice(&1u32.to_be_bytes()); // first_chunk
486        v.extend_from_slice(&num_samples.to_be_bytes()); // samples_per_chunk
487        v.extend_from_slice(&1u32.to_be_bytes()); // sample_description_index
488        v
489    });
490
491    let stsz = fullbox(b"stsz", 0, 0, &{
492        let mut v = Vec::new();
493        v.extend_from_slice(&0u32.to_be_bytes()); // sample_size 0 = per-sample
494        v.extend_from_slice(&num_samples.to_be_bytes()); // sample_count
495        for s in p.samples {
496            v.extend_from_slice(&(s.len() as u32).to_be_bytes());
497        }
498        v
499    });
500
501    // Single chunk holding all samples, located at the start of mdat's payload.
502    // Use `co64` when the file is large enough that the chunk offset needs 64 bits
503    // (always true once `mdat` uses a 16-byte extended header past 4 GiB payloads,
504    // and also if the offset itself exceeds u32::MAX).
505    let stco = if mdat_data_offset > u32::MAX as u64 {
506        fullbox(b"co64", 0, 0, &{
507            let mut v = Vec::new();
508            v.extend_from_slice(&1u32.to_be_bytes()); // entry_count
509            v.extend_from_slice(&mdat_data_offset.to_be_bytes());
510            v
511        })
512    } else {
513        fullbox(b"stco", 0, 0, &{
514            let mut v = Vec::new();
515            v.extend_from_slice(&1u32.to_be_bytes()); // entry_count
516            v.extend_from_slice(&(mdat_data_offset as u32).to_be_bytes());
517            v
518        })
519    };
520
521    let stbl = bx(b"stbl", &concat(&[stsd, stts, stss, stsc, stsz, stco]));
522
523    // ---- minf ----
524    let vmhd = fullbox(b"vmhd", 0, 1, &[0u8; 8]); // graphicsmode + opcolor
525    let dref = fullbox(b"dref", 0, 0, &{
526        let mut v = Vec::new();
527        v.extend_from_slice(&1u32.to_be_bytes()); // entry_count
528        v.extend_from_slice(&fullbox(b"url ", 0, 1, &[])); // self-contained
529        v
530    });
531    let dinf = bx(b"dinf", &dref);
532    let vid_hdlr = fullbox(b"hdlr", 0, 0, &{
533        let mut v = Vec::new();
534        v.extend_from_slice(&0u32.to_be_bytes()); // pre_defined
535        v.extend_from_slice(b"vide"); // handler_type
536        v.extend_from_slice(&[0u8; 12]); // reserved
537        v.extend_from_slice(b"threers\0"); // name
538        v
539    });
540    let minf = bx(b"minf", &concat(&[vmhd, vid_hdlr, dinf, stbl]));
541
542    // ---- mdia ----
543    let mdhd = fullbox(b"mdhd", 0, 0, &{
544        let mut v = Vec::new();
545        v.extend_from_slice(&0u32.to_be_bytes()); // creation_time
546        v.extend_from_slice(&0u32.to_be_bytes()); // modification_time
547        v.extend_from_slice(&p.timescale.to_be_bytes());
548        v.extend_from_slice(&total_duration.to_be_bytes());
549        v.extend_from_slice(&0x55c4u16.to_be_bytes()); // language 'und'
550        v.extend_from_slice(&0u16.to_be_bytes()); // pre_defined
551        v
552    });
553    let mdia_hdlr = fullbox(b"hdlr", 0, 0, &{
554        let mut v = Vec::new();
555        v.extend_from_slice(&0u32.to_be_bytes());
556        v.extend_from_slice(b"vide");
557        v.extend_from_slice(&[0u8; 12]);
558        v.extend_from_slice(b"threers\0");
559        v
560    });
561    let mdia = bx(b"mdia", &concat(&[mdhd, mdia_hdlr, minf]));
562
563    // ---- trak ----
564    let tkhd = fullbox(b"tkhd", 0, 7 /* enabled|in_movie|in_preview */, &{
565        let mut v = Vec::new();
566        v.extend_from_slice(&0u32.to_be_bytes()); // creation_time
567        v.extend_from_slice(&0u32.to_be_bytes()); // modification_time
568        v.extend_from_slice(&1u32.to_be_bytes()); // track_ID
569        v.extend_from_slice(&0u32.to_be_bytes()); // reserved
570        v.extend_from_slice(&total_duration.to_be_bytes());
571        v.extend_from_slice(&[0u8; 8]); // reserved
572        v.extend_from_slice(&0u16.to_be_bytes()); // layer
573        v.extend_from_slice(&0u16.to_be_bytes()); // alternate_group
574        v.extend_from_slice(&0u16.to_be_bytes()); // volume
575        v.extend_from_slice(&0u16.to_be_bytes()); // reserved
576        v.extend_from_slice(&UNITY_MATRIX);
577        v.extend_from_slice(&(p.width << 16).to_be_bytes()); // width 16.16
578        v.extend_from_slice(&(p.height << 16).to_be_bytes()); // height 16.16
579        v
580    });
581    let trak = bx(b"trak", &concat(&[tkhd, mdia]));
582
583    let text_trak = (!text_samples.is_empty()).then(|| {
584        text_track(
585            p.width,
586            p.height,
587            captions.map(|c| c.language.as_str()).unwrap_or(""),
588            &text_samples,
589            p.timescale,
590            total_duration,
591            text_data_offset,
592        )
593    });
594    let next_track_id = if text_trak.is_some() { 3u32 } else { 2 };
595
596    // ---- mvhd ----
597    let mvhd = fullbox(b"mvhd", 0, 0, &{
598        let mut v = Vec::new();
599        v.extend_from_slice(&0u32.to_be_bytes()); // creation_time
600        v.extend_from_slice(&0u32.to_be_bytes()); // modification_time
601        v.extend_from_slice(&p.timescale.to_be_bytes());
602        v.extend_from_slice(&total_duration.to_be_bytes());
603        v.extend_from_slice(&0x0001_0000u32.to_be_bytes()); // rate 1.0
604        v.extend_from_slice(&0x0100u16.to_be_bytes()); // volume 1.0
605        v.extend_from_slice(&0u16.to_be_bytes()); // reserved
606        v.extend_from_slice(&[0u8; 8]); // reserved
607        v.extend_from_slice(&UNITY_MATRIX);
608        v.extend_from_slice(&[0u8; 24]); // pre_defined
609        v.extend_from_slice(&next_track_id.to_be_bytes());
610        v
611    });
612    let mut moov_children = vec![mvhd, trak];
613    moov_children.extend(text_trak);
614    let moov = bx(b"moov", &concat(&moov_children));
615
616    // Emit in order: ftyp, the mdat header, every sample, then moov.
617    out.write_all(&ftyp)?;
618    if mdat_hdr == 16 {
619        out.write_all(&1u32.to_be_bytes())?; // size == 1 → largesize follows
620        out.write_all(b"mdat")?;
621        out.write_all(&(16 + mdat_payload_len).to_be_bytes())?;
622    } else {
623        out.write_all(&((8 + mdat_payload_len) as u32).to_be_bytes())?;
624        out.write_all(b"mdat")?;
625    }
626    for s in p.samples {
627        out.write_all(s)?;
628    }
629    for s in &text_samples {
630        out.write_all(&s.data)?;
631    }
632    out.write_all(&moov)?;
633    Ok(())
634}
635
636/// One `tx3g` sample: a duration in media ticks and its serialized payload.
637struct TextSample {
638    duration: u32,
639    data: Vec<u8>,
640}
641
642/// Turn cues into the gap-free sample run a `tx3g` track requires.
643///
644/// A `tx3g` track has no notion of "nothing showing" other than a sample whose
645/// text is empty, so every gap — including the one before the first cue and
646/// after the last — becomes a zero-length text sample.
647fn build_text_samples(
648    track: &CaptionTrack,
649    timescale: u32,
650    total_duration: u32,
651) -> Vec<TextSample> {
652    let ticks = |seconds: f64| -> u32 {
653        (seconds.max(0.0) * timescale as f64)
654            .round()
655            .min(u32::MAX as f64) as u32
656    };
657    let mut samples: Vec<TextSample> = Vec::new();
658    let mut cursor = 0u32;
659
660    for cue in &track.cues {
661        let text = cue.plain_text();
662        if text.trim().is_empty() {
663            continue;
664        }
665        // Overlapping cues cannot display at once — serialize them.
666        let start = ticks(cue.start).max(cursor);
667        let end = ticks(cue.end).max(start);
668        if end == start {
669            continue;
670        }
671        if start > cursor {
672            samples.push(TextSample {
673                duration: start - cursor,
674                data: encode_text_sample(""),
675            });
676        }
677        samples.push(TextSample {
678            duration: end - start,
679            data: encode_text_sample(&text),
680        });
681        cursor = end;
682    }
683
684    if samples.is_empty() {
685        return samples;
686    }
687    // Run the track to the end of the movie so players do not stop early.
688    if cursor < total_duration {
689        samples.push(TextSample {
690            duration: total_duration - cursor,
691            data: encode_text_sample(""),
692        });
693    }
694    samples
695}
696
697/// A `tx3g` sample body: 16-bit UTF-8 byte count, then the text itself.
698fn encode_text_sample(text: &str) -> Vec<u8> {
699    // Players expect LF line breaks inside a sample; CR would show as a box.
700    let text = text.replace("\r\n", "\n").replace('\r', "\n");
701    let bytes = text.as_bytes();
702    let len = bytes.len().min(u16::MAX as usize);
703    let mut v = Vec::with_capacity(2 + len);
704    v.extend_from_slice(&(len as u16).to_be_bytes());
705    v.extend_from_slice(&bytes[..len]);
706    v
707}
708
709/// Build the `trak` for the timed-text track.
710fn text_track(
711    width: u32,
712    height: u32,
713    language: &str,
714    samples: &[TextSample],
715    timescale: u32,
716    total_duration: u32,
717    data_offset: u64,
718) -> Vec<u8> {
719    let count = samples.len() as u32;
720
721    // ---- stsd > tx3g ----
722    let stsd = {
723        let mut entry = Vec::new();
724        entry.extend_from_slice(&[0u8; 6]); // reserved
725        entry.extend_from_slice(&1u16.to_be_bytes()); // data_reference_index
726        entry.extend_from_slice(&0u32.to_be_bytes()); // displayFlags
727        entry.push(1); // horizontal-justification: center
728        entry.push(0xFF); // vertical-justification: -1 = bottom
729        entry.extend_from_slice(&[0, 0, 0, 0]); // background-color-rgba (transparent)
730                                                // BoxRecord default-text-box — the full frame.
731        entry.extend_from_slice(&0i16.to_be_bytes()); // top
732        entry.extend_from_slice(&0i16.to_be_bytes()); // left
733        entry.extend_from_slice(&(height.min(i16::MAX as u32) as i16).to_be_bytes()); // bottom
734        entry.extend_from_slice(&(width.min(i16::MAX as u32) as i16).to_be_bytes()); // right
735                                                                                     // StyleRecord default-style — white text in the first font table entry.
736        entry.extend_from_slice(&0u16.to_be_bytes()); // startChar
737        entry.extend_from_slice(&0u16.to_be_bytes()); // endChar
738        entry.extend_from_slice(&1u16.to_be_bytes()); // font-ID
739        entry.push(0); // face-style-flags
740        entry.push(((height / 16).clamp(12, 255)) as u8); // font-size
741        entry.extend_from_slice(&[0xFF, 0xFF, 0xFF, 0xFF]); // text-color-rgba
742                                                            // FontTableBox.
743        let ftab = bx(b"ftab", &{
744            let name = b"Sans-Serif";
745            let mut v = Vec::new();
746            v.extend_from_slice(&1u16.to_be_bytes()); // entry-count
747            v.extend_from_slice(&1u16.to_be_bytes()); // font-ID
748            v.push(name.len() as u8);
749            v.extend_from_slice(name);
750            v
751        });
752        entry.extend_from_slice(&ftab);
753
754        let mut payload = Vec::new();
755        payload.extend_from_slice(&1u32.to_be_bytes()); // entry_count
756        payload.extend_from_slice(&bx(b"tx3g", &entry));
757        fullbox(b"stsd", 0, 0, &payload)
758    };
759
760    // ---- stts: run-length encoded per-sample durations ----
761    let stts = {
762        let mut runs: Vec<(u32, u32)> = Vec::new(); // (count, delta)
763        for s in samples {
764            match runs.last_mut() {
765                Some((n, delta)) if *delta == s.duration => *n += 1,
766                _ => runs.push((1, s.duration)),
767            }
768        }
769        let mut v = Vec::new();
770        v.extend_from_slice(&(runs.len() as u32).to_be_bytes());
771        for (n, delta) in runs {
772            v.extend_from_slice(&n.to_be_bytes());
773            v.extend_from_slice(&delta.to_be_bytes());
774        }
775        fullbox(b"stts", 0, 0, &v)
776    };
777
778    let stsc = fullbox(b"stsc", 0, 0, &{
779        let mut v = Vec::new();
780        v.extend_from_slice(&1u32.to_be_bytes()); // entry_count
781        v.extend_from_slice(&1u32.to_be_bytes()); // first_chunk
782        v.extend_from_slice(&count.to_be_bytes()); // samples_per_chunk
783        v.extend_from_slice(&1u32.to_be_bytes()); // sample_description_index
784        v
785    });
786
787    let stsz = fullbox(b"stsz", 0, 0, &{
788        let mut v = Vec::new();
789        v.extend_from_slice(&0u32.to_be_bytes()); // per-sample sizes follow
790        v.extend_from_slice(&count.to_be_bytes());
791        for s in samples {
792            v.extend_from_slice(&(s.data.len() as u32).to_be_bytes());
793        }
794        v
795    });
796
797    let stco = if data_offset > u32::MAX as u64 {
798        fullbox(b"co64", 0, 0, &{
799            let mut v = Vec::new();
800            v.extend_from_slice(&1u32.to_be_bytes()); // entry_count
801            v.extend_from_slice(&data_offset.to_be_bytes());
802            v
803        })
804    } else {
805        fullbox(b"stco", 0, 0, &{
806            let mut v = Vec::new();
807            v.extend_from_slice(&1u32.to_be_bytes()); // entry_count
808            v.extend_from_slice(&(data_offset as u32).to_be_bytes());
809            v
810        })
811    };
812
813    let stbl = bx(b"stbl", &concat(&[stsd, stts, stsc, stsz, stco]));
814
815    // ---- minf: text media has a null media header ----
816    let nmhd = fullbox(b"nmhd", 0, 0, &[]);
817    let dref = fullbox(b"dref", 0, 0, &{
818        let mut v = Vec::new();
819        v.extend_from_slice(&1u32.to_be_bytes());
820        v.extend_from_slice(&fullbox(b"url ", 0, 1, &[]));
821        v
822    });
823    let dinf = bx(b"dinf", &dref);
824    let minf = bx(b"minf", &concat(&[nmhd, dinf, stbl]));
825
826    // ---- mdia ----
827    let mdhd = fullbox(b"mdhd", 0, 0, &{
828        let mut v = Vec::new();
829        v.extend_from_slice(&0u32.to_be_bytes()); // creation_time
830        v.extend_from_slice(&0u32.to_be_bytes()); // modification_time
831        v.extend_from_slice(&timescale.to_be_bytes());
832        v.extend_from_slice(&total_duration.to_be_bytes());
833        v.extend_from_slice(&pack_language(language).to_be_bytes());
834        v.extend_from_slice(&0u16.to_be_bytes()); // pre_defined
835        v
836    });
837    let hdlr = fullbox(b"hdlr", 0, 0, &{
838        let mut v = Vec::new();
839        v.extend_from_slice(&0u32.to_be_bytes()); // pre_defined
840        v.extend_from_slice(b"sbtl"); // subtitle handler
841        v.extend_from_slice(&[0u8; 12]); // reserved
842        v.extend_from_slice(b"threers captions\0");
843        v
844    });
845    let mdia = bx(b"mdia", &concat(&[mdhd, hdlr, minf]));
846
847    // ---- tkhd: same frame box as the video, drawn in front (layer -1) ----
848    let tkhd = fullbox(b"tkhd", 0, 3 /* enabled | in_movie */, &{
849        let mut v = Vec::new();
850        v.extend_from_slice(&0u32.to_be_bytes()); // creation_time
851        v.extend_from_slice(&0u32.to_be_bytes()); // modification_time
852        v.extend_from_slice(&2u32.to_be_bytes()); // track_ID
853        v.extend_from_slice(&0u32.to_be_bytes()); // reserved
854        v.extend_from_slice(&total_duration.to_be_bytes());
855        v.extend_from_slice(&[0u8; 8]); // reserved
856        v.extend_from_slice(&(-1i16).to_be_bytes()); // layer: in front of video
857        v.extend_from_slice(&0u16.to_be_bytes()); // alternate_group
858        v.extend_from_slice(&0u16.to_be_bytes()); // volume
859        v.extend_from_slice(&0u16.to_be_bytes()); // reserved
860        v.extend_from_slice(&UNITY_MATRIX);
861        v.extend_from_slice(&(width << 16).to_be_bytes());
862        v.extend_from_slice(&(height << 16).to_be_bytes());
863        v
864    });
865
866    bx(b"trak", &concat(&[tkhd, mdia]))
867}
868
869/// Pack a BCP-47 tag into `mdhd`'s 15-bit ISO-639-2 field (5 bits per letter,
870/// each offset by `0x60`).
871fn pack_language(language: &str) -> u16 {
872    let code = crate::captions::iso639_2(language);
873    let bits = |b: u8| ((b - 0x60) & 0x1F) as u16;
874    (bits(code[0]) << 10) | (bits(code[1]) << 5) | bits(code[2])
875}
876
877/// The identity transformation matrix used in `tkhd`/`mvhd` (16.16 / 2.30 fixed).
878pub(crate) const UNITY_MATRIX: [u8; 36] = [
879    0x00, 0x01, 0x00, 0x00, 0, 0, 0, 0, 0, 0, 0, 0, //
880    0, 0, 0, 0, 0x00, 0x01, 0x00, 0x00, 0, 0, 0, 0, //
881    0, 0, 0, 0, 0, 0, 0, 0, 0x40, 0x00, 0x00, 0x00,
882];
883
884#[cfg(test)]
885mod tests {
886    use super::*;
887
888    #[test]
889    fn colr_follows_the_stream_and_survives_garbage() {
890        // threers' encoder tags BT.601 (matrix 6), limited range.
891        let enc = crate::h264::CompressedEncoder::new(32, 16, 30);
892        let c =
893            StreamColour::of_avcc(&enc.avcc()).expect("the encoder writes a colour description");
894        assert_eq!((c.matrix, c.full_range), (6, false));
895        // Parameter sets the parser cannot make sense of fall back, never panic.
896        let mut seed = 0x2545_f491_4f6c_dd1du64;
897        for i in 0..3000usize {
898            let len = i % 400;
899            let bytes: Vec<u8> = (0..len)
900                .map(|_| {
901                    seed ^= seed << 13;
902                    seed ^= seed >> 7;
903                    seed ^= seed << 17;
904                    seed as u8
905                })
906                .collect();
907            for header in [&[1u8, 100, 0, 40, 0xff, 0xe1][..], &[]] {
908                let mut avcc = header.to_vec();
909                if !header.is_empty() {
910                    avcc.extend_from_slice(&(len as u16).to_be_bytes());
911                }
912                avcc.extend_from_slice(&bytes);
913                let _ = StreamColour::of_avcc(&avcc);
914            }
915            let mut hvcc = vec![0u8; 22];
916            hvcc.extend_from_slice(&[1, 33, 0, 1]);
917            hvcc.extend_from_slice(&((len + 2) as u16).to_be_bytes());
918            hvcc.extend_from_slice(&[0x42, 0x01]);
919            hvcc.extend_from_slice(&bytes);
920            let _ = StreamColour::of_hvcc(&hvcc);
921        }
922    }
923
924    fn walk_top_level(out: &[u8]) -> Vec<String> {
925        let mut o = 0usize;
926        let mut tags = Vec::new();
927        while o + 8 <= out.len() {
928            let size32 = u32::from_be_bytes([out[o], out[o + 1], out[o + 2], out[o + 3]]);
929            let (hdr, size) = if size32 == 1 {
930                assert!(o + 16 <= out.len());
931                let large = u64::from_be_bytes(out[o + 8..o + 16].try_into().unwrap());
932                (16usize, large as usize)
933            } else {
934                (8usize, size32 as usize)
935            };
936            tags.push(String::from_utf8_lossy(&out[o + 4..o + 8]).to_string());
937            assert!(size >= hdr && o + size <= out.len(), "box {size} at {o}");
938            o += size;
939        }
940        assert_eq!(o, out.len(), "top-level boxes tile the file");
941        tags
942    }
943
944    #[test]
945    fn boxes_are_well_formed() {
946        let sample = vec![0u8; 40];
947        let out = mux_hevc(&Mp4Params {
948            width: 64,
949            height: 64,
950            timescale: 600,
951            frame_duration: 20,
952            hvcc_payload: &[0u8; 30],
953            almo_payload: Some(&[0, 0, 1, 2]),
954            samples: &[sample],
955        });
956        assert_eq!(&out[4..8], b"ftyp");
957        assert_eq!(walk_top_level(&out), vec!["ftyp", "mdat", "moov"]);
958    }
959
960    #[test]
961    fn h264_boxes_are_well_formed() {
962        let sample = vec![0u8; 40];
963        let out = mux_h264(&H264Mp4Params {
964            width: 64,
965            height: 64,
966            timescale: 600,
967            frame_duration: 20,
968            avcc_payload: &[0u8; 20],
969            samples: &[sample],
970        });
971        assert_eq!(&out[4..8], b"ftyp");
972        assert_eq!(walk_top_level(&out), vec!["ftyp", "mdat", "moov"]);
973        assert!(out.windows(4).any(|w| w == b"avc1"));
974    }
975
976    #[test]
977    fn extended_size_header_layout() {
978        // `bx` switches to largesize when 8+payload > u32::MAX. We don't allocate
979        // a 4 GiB buffer in tests — just assert the header math the muxer uses.
980        let payload_len = (u32::MAX as u64) - 6; // 8 + len > u32::MAX
981        let largesize = 16 + payload_len;
982        assert!(largesize > u32::MAX as u64);
983        let mut hdr = Vec::new();
984        hdr.extend_from_slice(&1u32.to_be_bytes());
985        hdr.extend_from_slice(b"mdat");
986        hdr.extend_from_slice(&largesize.to_be_bytes());
987        assert_eq!(box_header_len(&hdr), 16);
988        assert_eq!(box_header_len(&bx(b"mdat", &[0u8; 64])), 8);
989    }
990}