Skip to main content

threers_codec/
mp4_stream.rs

1//! Incremental MP4 writing for **live** capture, as opposed to the batch muxers
2//! in [`crate::mp4`].
3//!
4//! [`mux_h264`](crate::mp4::mux_h264) is built for an export: it takes
5//! every sample up front, gives them all one fixed duration, and marks them all
6//! as sync samples, which is exactly right for a render that produced a constant
7//! frame rate of all-intra frames. A camera or a screen feed breaks all three
8//! assumptions:
9//!
10//! * **Variable frame rate.** A screen feed emits frames when the screen
11//!   changes. Forcing a constant duration makes playback drift from wall clock.
12//! * **Mostly inter frames.** Marking every frame as a sync sample tells the
13//!   player it can seek anywhere, and seeking then lands on a P-frame and shows
14//!   garbage until the next real keyframe.
15//! * **Unbounded length.** An hour of 1080p is gigabytes; it cannot sit in a
16//!   `Vec` waiting for the mux.
17//!
18//! So this module keeps per-sample durations, records which samples really are
19//! keyframes, and streams sample data to the sink as it arrives — only the
20//! sample *tables* stay in memory, about 16 bytes per frame (an hour at 60 fps
21//! is a few megabytes). It also carries an optional uncompressed audio track, so
22//! a capture with sound lands in one file instead of a video file plus a
23//! sidecar WAV.
24//!
25//! The sink must be seekable: `mdat` is written before its length is known and
26//! patched at the end.
27//!
28//! ```no_run
29//! use std::fs::File;
30//! use threers_codec::mp4_stream::{AudioConfig, Mp4StreamWriter, VideoConfig};
31//!
32//! # let avcc_bytes: Vec<u8> = Vec::new();
33//! # let avcc_frame: Vec<u8> = Vec::new();
34//! # let pcm: Vec<u8> = Vec::new();
35//! let video = VideoConfig {
36//!     width: 1170,
37//!     height: 2532,
38//!     timescale: 1_000_000, // microseconds; fine-grained enough for real PTS
39//!     avcc: avcc_bytes,     // from the stream's SPS/PPS
40//! };
41//! let mut w = Mp4StreamWriter::new(
42//!     File::create("capture.mp4")?,
43//!     video,
44//!     Some(AudioConfig::pcm_s16le(48_000, 2)),
45//! )?;
46//! w.write_video_sample(&avcc_frame, 16_666, true)?;
47//! w.write_audio_sample(&pcm)?;
48//! let stats = w.finish()?;
49//! # Ok::<(), std::io::Error>(())
50//! ```
51
52use std::io::{self, Seek, SeekFrom, Write};
53
54use super::mp4::{bx, concat, fullbox, UNITY_MATRIX};
55
56/// Movie-level timescale. Track timescales are independent of this.
57const MOVIE_TIMESCALE: u32 = 1000;
58
59/// The video track of an [`Mp4StreamWriter`]: H.264 configured by an `avcC`.
60#[derive(Clone)]
61pub struct VideoConfig {
62    /// Picture width in pixels.
63    pub width: u32,
64    /// Picture height in pixels.
65    pub height: u32,
66    /// Ticks per second for this track's durations. Use something fine-grained
67    /// (1_000_000 for microseconds) so real presentation deltas survive.
68    pub timescale: u32,
69    /// `avcC` box payload without its size/type header — see
70    /// [`crate::h264::avcc::build_avcc`].
71    pub avcc: Vec<u8>,
72}
73
74/// How the audio samples are coded.
75///
76/// The two cases are not variations on a theme: PCM frames are all the same
77/// size and arrive as a byte stream to be cut up, while AAC frames are already
78/// packets of their own length and carry a configuration the decoder cannot
79/// work without. They differ in the sample entry, the sample-size table, and
80/// even the file's brand.
81#[derive(Clone, PartialEq, Eq)]
82pub enum AudioCoding {
83    /// Signed 16-bit little-endian interleaved PCM, stored as `sowt`. Makes the
84    /// file a QuickTime movie — see [`Mp4StreamWriter::new`].
85    PcmS16le,
86    /// AAC access units, stored as `mp4a` with an `esds`.
87    ///
88    /// `asc` is the AudioSpecificConfig — two bytes for plain AAC-LC, five with
89    /// explicit SBR signalling. It is not something to synthesise: every
90    /// encoder hands it over, WebCodecs as `decoderConfig.description` on the
91    /// first output and the ISO reference as the `DecoderSpecificInfo`. Without
92    /// it the track says it is AAC and declines to say which kind.
93    Aac {
94        /// The AudioSpecificConfig.
95        asc: Vec<u8>,
96    },
97}
98
99/// The optional audio track of an [`Mp4StreamWriter`].
100#[derive(Clone)]
101pub struct AudioConfig {
102    /// Samples per second.
103    pub sample_rate: u32,
104    /// Channel count.
105    pub channels: u16,
106    /// Bits per sample (16 for PCM; what the encoder reports for AAC).
107    pub bits_per_sample: u16,
108    /// How the samples are coded.
109    pub coding: AudioCoding,
110    /// Samples the encoder emitted before the first real one, to be skipped on
111    /// playback via an edit list.
112    ///
113    /// A transform codec cannot start cold: AAC's first packets carry the
114    /// window it needed to get going, and the content proper begins after them
115    /// — 2048 samples for the usual two-frame priming, which is 43 ms and
116    /// plainly visible against a picture. The samples stay in the file, because
117    /// the decoder needs them; an `elst` is how the format says "begin here".
118    pub encoder_delay: u32,
119}
120
121impl AudioConfig {
122    /// Signed 16-bit little-endian interleaved PCM, stored as `sowt`.
123    pub fn pcm_s16le(sample_rate: u32, channels: u16) -> Self {
124        AudioConfig {
125            sample_rate,
126            channels,
127            bits_per_sample: 16,
128            coding: AudioCoding::PcmS16le,
129            encoder_delay: 0, // PCM starts where it starts
130        }
131    }
132
133    /// AAC, with the AudioSpecificConfig its decoder needs.
134    ///
135    /// `encoder_delay` is in samples; see the field. Zero if the encoder has
136    /// already accounted for it, or you would rather not say.
137    pub fn aac(sample_rate: u32, channels: u16, asc: Vec<u8>, encoder_delay: u32) -> Self {
138        AudioConfig {
139            sample_rate,
140            channels,
141            bits_per_sample: 16,
142            coding: AudioCoding::Aac { asc },
143            encoder_delay,
144        }
145    }
146
147    /// Bytes in one audio frame across all channels. PCM only — an AAC packet
148    /// is its own size.
149    pub fn bytes_per_frame(&self) -> usize {
150        usize::from(self.channels) * usize::from(self.bits_per_sample / 8)
151    }
152
153    fn is_pcm(&self) -> bool {
154        self.coding == AudioCoding::PcmS16le
155    }
156}
157
158/// One MPEG-4 descriptor: a tag, a length in base-128 continuation bytes, and
159/// the payload. `esds` is built out of nothing else.
160fn descriptor(tag: u8, payload: &[u8]) -> Vec<u8> {
161    let mut v = vec![tag];
162    let mut len = payload.len();
163    // Base-128, most significant group first, every byte but the last carrying
164    // the continuation bit.
165    let mut groups = Vec::new();
166    loop {
167        groups.push((len & 0x7f) as u8);
168        len >>= 7;
169        if len == 0 {
170            break;
171        }
172    }
173    for (i, g) in groups.iter().enumerate().rev() {
174        v.push(if i == 0 { *g } else { *g | 0x80 });
175    }
176    v.extend_from_slice(payload);
177    v
178}
179
180/// What an [`Mp4StreamWriter`] has written so far.
181#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
182pub struct Mp4StreamStats {
183    /// Video samples written.
184    pub video_samples: u32,
185    /// Audio frames written.
186    pub audio_frames: u32,
187    /// Video samples marked as sync samples.
188    pub keyframes: u32,
189    /// Bytes of sample data written (the `mdat` payload).
190    pub media_bytes: u64,
191    /// Total video duration, in the video timescale.
192    pub video_duration_ticks: u64,
193    /// Total audio duration, in samples.
194    pub audio_duration_ticks: u64,
195}
196
197#[derive(Clone, Copy, PartialEq, Eq)]
198enum Kind {
199    Video,
200    Audio,
201}
202
203/// Per-track sample tables. Everything here is run-length encoded or index-only,
204/// which is what keeps a long capture's memory flat.
205#[derive(Default)]
206struct Track {
207    /// Per-sample byte sizes. Left empty for constant-size tracks (PCM).
208    sizes: Vec<u32>,
209    /// `stts` as (consecutive sample count, duration) runs.
210    durations: Vec<(u32, u32)>,
211    /// 1-based sample numbers that are sync samples. Only populated once a
212    /// non-sync sample has been seen; see [`Track::sync_sample_table`].
213    sync: Vec<u32>,
214    all_sync: bool,
215    /// `(file offset, samples in chunk)`.
216    chunks: Vec<(u64, u32)>,
217    samples: u32,
218    duration: u64,
219}
220
221impl Track {
222    fn new() -> Self {
223        Track {
224            all_sync: true,
225            ..Default::default()
226        }
227    }
228
229    fn add_duration(&mut self, d: u32) {
230        match self.durations.last_mut() {
231            Some((count, delta)) if *delta == d => *count += 1,
232            _ => self.durations.push((1, d)),
233        }
234        self.duration += u64::from(d);
235    }
236
237    /// Record `n` samples starting at `offset`, extending the current chunk when
238    /// this track also wrote the previous sample.
239    fn add_chunk(&mut self, offset: u64, n: u32, contiguous: bool) {
240        if contiguous && let Some(last) = self.chunks.last_mut() {
241            last.1 += n;
242            return;
243        }
244        self.chunks.push((offset, n));
245    }
246
247    fn mark_sync(&mut self, sample: u32, sync: bool) {
248        if sync {
249            self.sync.push(sample);
250        } else {
251            self.all_sync = false;
252        }
253    }
254
255    /// `None` when every sample is a sync sample: an absent `stss` means exactly
256    /// that, and omitting the box is both smaller and unambiguous.
257    fn sync_sample_table(&self) -> Option<Vec<u8>> {
258        if self.all_sync {
259            return None;
260        }
261        Some(fullbox(b"stss", 0, 0, &{
262            let mut v = Vec::with_capacity(4 + self.sync.len() * 4);
263            v.extend_from_slice(&(self.sync.len() as u32).to_be_bytes());
264            for s in &self.sync {
265                v.extend_from_slice(&s.to_be_bytes());
266            }
267            v
268        }))
269    }
270
271    fn time_to_sample(&self) -> Vec<u8> {
272        fullbox(b"stts", 0, 0, &{
273            let mut v = Vec::with_capacity(4 + self.durations.len() * 8);
274            v.extend_from_slice(&(self.durations.len() as u32).to_be_bytes());
275            for (count, delta) in &self.durations {
276                v.extend_from_slice(&count.to_be_bytes());
277                v.extend_from_slice(&delta.to_be_bytes());
278            }
279            v
280        })
281    }
282
283    /// `stsz`, using the constant-size form when `constant_size` is given.
284    fn sample_size(&self, constant_size: Option<u32>) -> Vec<u8> {
285        fullbox(b"stsz", 0, 0, &{
286            let mut v = Vec::new();
287            match constant_size {
288                Some(size) => {
289                    v.extend_from_slice(&size.to_be_bytes());
290                    v.extend_from_slice(&self.samples.to_be_bytes());
291                }
292                None => {
293                    v.extend_from_slice(&0u32.to_be_bytes());
294                    v.extend_from_slice(&(self.sizes.len() as u32).to_be_bytes());
295                    for s in &self.sizes {
296                        v.extend_from_slice(&s.to_be_bytes());
297                    }
298                }
299            }
300            v
301        })
302    }
303
304    /// `stsc`, collapsing consecutive chunks that hold the same sample count.
305    fn sample_to_chunk(&self) -> Vec<u8> {
306        let mut entries: Vec<(u32, u32)> = Vec::new(); // (first_chunk, samples_per_chunk)
307        for (i, (_, n)) in self.chunks.iter().enumerate() {
308            let first_chunk = (i + 1) as u32;
309            match entries.last() {
310                Some((_, prev)) if prev == n => {}
311                _ => entries.push((first_chunk, *n)),
312            }
313        }
314        fullbox(b"stsc", 0, 0, &{
315            let mut v = Vec::with_capacity(4 + entries.len() * 12);
316            v.extend_from_slice(&(entries.len() as u32).to_be_bytes());
317            for (first, per) in &entries {
318                v.extend_from_slice(&first.to_be_bytes());
319                v.extend_from_slice(&per.to_be_bytes());
320                v.extend_from_slice(&1u32.to_be_bytes()); // sample_description_index
321            }
322            v
323        })
324    }
325
326    /// `stco`, or `co64` when any offset needs more than 32 bits.
327    fn chunk_offsets(&self) -> Vec<u8> {
328        let needs_64 = self
329            .chunks
330            .iter()
331            .any(|(off, _)| *off > u64::from(u32::MAX));
332        if needs_64 {
333            fullbox(b"co64", 0, 0, &{
334                let mut v = Vec::with_capacity(4 + self.chunks.len() * 8);
335                v.extend_from_slice(&(self.chunks.len() as u32).to_be_bytes());
336                for (off, _) in &self.chunks {
337                    v.extend_from_slice(&off.to_be_bytes());
338                }
339                v
340            })
341        } else {
342            fullbox(b"stco", 0, 0, &{
343                let mut v = Vec::with_capacity(4 + self.chunks.len() * 4);
344                v.extend_from_slice(&(self.chunks.len() as u32).to_be_bytes());
345                for (off, _) in &self.chunks {
346                    v.extend_from_slice(&(*off as u32).to_be_bytes());
347                }
348                v
349            })
350        }
351    }
352}
353
354/// Streams an MP4 to a seekable sink as samples arrive.
355pub struct Mp4StreamWriter<W: Write + Seek> {
356    out: W,
357    video_cfg: VideoConfig,
358    audio_cfg: Option<AudioConfig>,
359    video: Track,
360    audio: Track,
361    /// File offset of the `mdat` box header.
362    mdat_header_offset: u64,
363    /// File offset of the first byte of `mdat` payload.
364    payload_start: u64,
365    payload_len: u64,
366    last_kind: Option<Kind>,
367    keyframes: u32,
368    /// Audio bytes that did not fill a whole frame, carried to the next write.
369    pcm_remainder: Vec<u8>,
370    finished: bool,
371}
372
373impl<W: Write + Seek> Mp4StreamWriter<W> {
374    /// Start a file on `out`: the `ftyp` and an open `mdat` are written now, the
375    /// `moov` on [`finish`](Self::finish). `PcmS16le` audio makes the file a
376    /// QuickTime movie (`qt` brand), because that is the brand `sowt` belongs to.
377    pub fn new(mut out: W, video: VideoConfig, audio: Option<AudioConfig>) -> io::Result<Self> {
378        assert!(video.timescale > 0, "video timescale must be non-zero");
379
380        // A file with an uncompressed `sowt` audio track is a QuickTime movie
381        // rather than plain ISO base media, so it is branded accordingly. AAC
382        // is not: `mp4a` is ISO base media's own audio and the file stays an
383        // MP4, which is the difference between something a browser will play
384        // and something only QuickTime and VLC will. Video only keeps the same
385        // brands the batch muxer uses.
386        let ftyp = if audio.as_ref().is_some_and(AudioConfig::is_pcm) {
387            bx(b"ftyp", &{
388                let mut v = Vec::new();
389                v.extend_from_slice(b"qt  ");
390                v.extend_from_slice(&0x0000_0200u32.to_be_bytes()); // minor_version
391                v.extend_from_slice(b"qt  ");
392                v
393            })
394        } else {
395            bx(b"ftyp", &{
396                let mut v = Vec::new();
397                v.extend_from_slice(b"isom");
398                v.extend_from_slice(&0u32.to_be_bytes());
399                for brand in [b"isom", b"iso2", b"avc1", b"mp41"] {
400                    v.extend_from_slice(brand);
401                }
402                v
403            })
404        };
405        out.write_all(&ftyp)?;
406
407        // Always use the 64-bit `mdat` header. The size is unknown until the end,
408        // and reserving the extended form means patching it later never has to
409        // move the payload.
410        let mdat_header_offset = ftyp.len() as u64;
411        out.write_all(&1u32.to_be_bytes())?; // size == 1 → largesize follows
412        out.write_all(b"mdat")?;
413        out.write_all(&0u64.to_be_bytes())?; // largesize placeholder
414        let payload_start = mdat_header_offset + 16;
415
416        Ok(Mp4StreamWriter {
417            out,
418            video_cfg: video,
419            audio_cfg: audio,
420            video: Track::new(),
421            audio: Track::new(),
422            mdat_header_offset,
423            payload_start,
424            payload_len: 0,
425            last_kind: None,
426            keyframes: 0,
427            pcm_remainder: Vec::new(),
428            finished: false,
429        })
430    }
431
432    /// Append one coded video frame.
433    ///
434    /// `sample` holds that frame's NAL units in AVCC framing (each prefixed with
435    /// a 4-byte big-endian length), which is what an `avc1` track stores and what
436    /// hardware encoders and Apple's capture protocol already hand over — no
437    /// conversion needed. `duration` is in the video track's timescale, and
438    /// `sync` must be true only for genuine keyframes.
439    pub fn write_video_sample(
440        &mut self,
441        sample: &[u8],
442        duration: u32,
443        sync: bool,
444    ) -> io::Result<()> {
445        if sample.is_empty() {
446            return Ok(());
447        }
448        let offset = self.payload_start + self.payload_len;
449        self.out.write_all(sample)?;
450        self.payload_len += sample.len() as u64;
451
452        let contiguous = self.last_kind == Some(Kind::Video);
453        self.video.sizes.push(sample.len() as u32);
454        self.video.samples += 1;
455        self.video.add_duration(duration);
456        self.video.add_chunk(offset, 1, contiguous);
457        self.video.mark_sync(self.video.samples, sync);
458        if sync {
459            self.keyframes += 1;
460        }
461        self.last_kind = Some(Kind::Video);
462        Ok(())
463    }
464
465    /// Append interleaved PCM. Any trailing partial frame is held back and
466    /// prepended to the next call, so callers can pass whatever sized buffers
467    /// their source produces.
468    pub fn write_audio_sample(&mut self, pcm: &[u8]) -> io::Result<()> {
469        let Some(cfg) = self.audio_cfg.clone() else {
470            return Ok(()); // no audio track configured; drop silently
471        };
472        if !cfg.is_pcm() {
473            return Err(io::Error::new(
474                io::ErrorKind::InvalidInput,
475                "this track is AAC — use write_audio_packet",
476            ));
477        }
478        let frame = cfg.bytes_per_frame();
479        if frame == 0 || pcm.is_empty() && self.pcm_remainder.is_empty() {
480            return Ok(());
481        }
482
483        // Splice the carried remainder onto the front, only allocating when
484        // there actually is one.
485        let joined: &[u8] = if self.pcm_remainder.is_empty() {
486            pcm
487        } else {
488            self.pcm_remainder.extend_from_slice(pcm);
489            &self.pcm_remainder
490        };
491
492        let frames = joined.len() / frame;
493        let usable = frames * frame;
494        if frames == 0 {
495            if self.pcm_remainder.is_empty() {
496                self.pcm_remainder.extend_from_slice(pcm);
497            }
498            return Ok(());
499        }
500
501        let offset = self.payload_start + self.payload_len;
502        self.out.write_all(&joined[..usable])?;
503        self.payload_len += usable as u64;
504        let leftover = joined[usable..].to_vec();
505
506        let contiguous = self.last_kind == Some(Kind::Audio);
507        self.audio.samples += frames as u32;
508        // Every PCM frame lasts exactly one tick at a sample-rate timescale, so
509        // the whole track collapses to a single `stts` run.
510        match self.audio.durations.last_mut() {
511            Some((count, delta)) if *delta == 1 => *count += frames as u32,
512            _ => self.audio.durations.push((frames as u32, 1)),
513        }
514        self.audio.duration += frames as u64;
515        self.audio.add_chunk(offset, frames as u32, contiguous);
516
517        self.pcm_remainder = leftover;
518        self.last_kind = Some(Kind::Audio);
519        Ok(())
520    }
521
522    /// Append one coded audio packet.
523    ///
524    /// The AAC counterpart of [`write_audio_sample`](Self::write_audio_sample),
525    /// and it is a different shape because the data is: a packet is already its
526    /// own unit and its own length, so nothing is cut up and nothing is carried
527    /// over. `duration` is in the audio track's timescale, which is the sample
528    /// rate — 1024 for AAC-LC, 2048 for HE-AAC's doubled frame.
529    ///
530    /// Every AAC access unit is independently decodable, so the track keeps its
531    /// `all_sync` default and no `stss` is written.
532    pub fn write_audio_packet(&mut self, packet: &[u8], duration: u32) -> io::Result<()> {
533        let Some(cfg) = self.audio_cfg.as_ref() else {
534            return Ok(()); // no audio track configured; drop silently
535        };
536        if cfg.is_pcm() {
537            return Err(io::Error::new(
538                io::ErrorKind::InvalidInput,
539                "this track is PCM — use write_audio_sample",
540            ));
541        }
542        if packet.is_empty() {
543            return Ok(());
544        }
545
546        let offset = self.payload_start + self.payload_len;
547        self.out.write_all(packet)?;
548        self.payload_len += packet.len() as u64;
549
550        let contiguous = self.last_kind == Some(Kind::Audio);
551        self.audio.sizes.push(packet.len() as u32);
552        self.audio.samples += 1;
553        self.audio.add_duration(duration);
554        self.audio.add_chunk(offset, 1, contiguous);
555        self.last_kind = Some(Kind::Audio);
556        Ok(())
557    }
558
559    /// Patch the `mdat` length, append `moov`, and report what was written.
560    pub fn finish(self) -> io::Result<Mp4StreamStats> {
561        self.finish_with_sink().map(|(stats, _)| stats)
562    }
563
564    /// [`finish`](Self::finish), also handing back the sink — for callers that
565    /// need the handle afterwards (to `sync_all`, or to read a test buffer).
566    pub fn finish_with_sink(mut self) -> io::Result<(Mp4StreamStats, W)> {
567        self.finished = true;
568
569        // Patch the mdat largesize now that the payload is complete.
570        let mdat_total = 16 + self.payload_len;
571        self.out
572            .seek(SeekFrom::Start(self.mdat_header_offset + 8))?;
573        self.out.write_all(&mdat_total.to_be_bytes())?;
574        self.out.seek(SeekFrom::End(0))?;
575
576        let moov = self.build_moov();
577        self.out.write_all(&moov)?;
578        self.out.flush()?;
579
580        let stats = Mp4StreamStats {
581            video_samples: self.video.samples,
582            audio_frames: self.audio.samples,
583            keyframes: self.keyframes,
584            media_bytes: self.payload_len,
585            video_duration_ticks: self.video.duration,
586            audio_duration_ticks: self.audio.duration,
587        };
588        Ok((stats, self.out))
589    }
590
591    /// Track duration converted into the movie timescale.
592    fn movie_ticks(duration: u64, timescale: u32) -> u32 {
593        if timescale == 0 {
594            return 0;
595        }
596        (duration.saturating_mul(u64::from(MOVIE_TIMESCALE)) / u64::from(timescale)) as u32
597    }
598
599    fn build_moov(&self) -> Vec<u8> {
600        let video_movie_ticks = Self::movie_ticks(self.video.duration, self.video_cfg.timescale);
601        let audio_movie_ticks = self
602            .audio_cfg
603            .as_ref()
604            .map(|c| Self::movie_ticks(self.audio.duration, c.sample_rate))
605            .unwrap_or(0);
606        let movie_duration = video_movie_ticks.max(audio_movie_ticks);
607
608        let video_trak = self.build_video_trak(video_movie_ticks);
609        let audio_trak = self
610            .audio_cfg
611            .as_ref()
612            .map(|c| self.build_audio_trak(c, audio_movie_ticks));
613        let next_track_id = if audio_trak.is_some() { 3u32 } else { 2 };
614
615        let mvhd = fullbox(b"mvhd", 0, 0, &{
616            let mut v = Vec::new();
617            v.extend_from_slice(&0u32.to_be_bytes()); // creation_time
618            v.extend_from_slice(&0u32.to_be_bytes()); // modification_time
619            v.extend_from_slice(&MOVIE_TIMESCALE.to_be_bytes());
620            v.extend_from_slice(&movie_duration.to_be_bytes());
621            v.extend_from_slice(&0x0001_0000u32.to_be_bytes()); // rate 1.0
622            v.extend_from_slice(&0x0100u16.to_be_bytes()); // volume 1.0
623            v.extend_from_slice(&0u16.to_be_bytes()); // reserved
624            v.extend_from_slice(&[0u8; 8]); // reserved
625            v.extend_from_slice(&UNITY_MATRIX);
626            v.extend_from_slice(&[0u8; 24]); // pre_defined
627            v.extend_from_slice(&next_track_id.to_be_bytes());
628            v
629        });
630
631        let mut children = vec![mvhd, video_trak];
632        children.extend(audio_trak);
633        bx(b"moov", &concat(&children))
634    }
635
636    fn build_video_trak(&self, movie_ticks: u32) -> Vec<u8> {
637        let cfg = &self.video_cfg;
638
639        let avc1 = bx(b"avc1", &{
640            let mut v = Vec::new();
641            v.extend_from_slice(&[0u8; 6]); // reserved
642            v.extend_from_slice(&1u16.to_be_bytes()); // data_reference_index
643            v.extend_from_slice(&[0u8; 16]); // pre_defined + reserved
644            v.extend_from_slice(&(cfg.width as u16).to_be_bytes());
645            v.extend_from_slice(&(cfg.height as u16).to_be_bytes());
646            v.extend_from_slice(&0x0048_0000u32.to_be_bytes()); // horizresolution 72
647            v.extend_from_slice(&0x0048_0000u32.to_be_bytes()); // vertresolution 72
648            v.extend_from_slice(&0u32.to_be_bytes()); // reserved
649            v.extend_from_slice(&1u16.to_be_bytes()); // frame_count
650            v.extend_from_slice(&[0u8; 32]); // compressorname
651            v.extend_from_slice(&0x0018u16.to_be_bytes()); // depth 24
652            v.extend_from_slice(&(-1i16).to_be_bytes()); // pre_defined
653            v.extend_from_slice(&bx(b"avcC", &cfg.avcc));
654            v
655        });
656        let stsd = fullbox(b"stsd", 0, 0, &{
657            let mut v = Vec::new();
658            v.extend_from_slice(&1u32.to_be_bytes()); // entry_count
659            v.extend_from_slice(&avc1);
660            v
661        });
662
663        let mut stbl_children = vec![stsd, self.video.time_to_sample()];
664        stbl_children.extend(self.video.sync_sample_table());
665        stbl_children.push(self.video.sample_to_chunk());
666        stbl_children.push(self.video.sample_size(None));
667        stbl_children.push(self.video.chunk_offsets());
668        let stbl = bx(b"stbl", &concat(&stbl_children));
669
670        let vmhd = fullbox(b"vmhd", 0, 1, &[0u8; 8]);
671        let minf = bx(
672            b"minf",
673            &concat(&[vmhd, handler(b"vide"), data_information(), stbl]),
674        );
675        let mdia = bx(
676            b"mdia",
677            &concat(&[
678                media_header(cfg.timescale, self.video.duration),
679                handler(b"vide"),
680                minf,
681            ]),
682        );
683
684        let tkhd = fullbox(b"tkhd", 0, 7, &{
685            let mut v = Vec::new();
686            v.extend_from_slice(&0u32.to_be_bytes());
687            v.extend_from_slice(&0u32.to_be_bytes());
688            v.extend_from_slice(&1u32.to_be_bytes()); // track_ID
689            v.extend_from_slice(&0u32.to_be_bytes()); // reserved
690            v.extend_from_slice(&movie_ticks.to_be_bytes());
691            v.extend_from_slice(&[0u8; 8]); // reserved
692            v.extend_from_slice(&0u16.to_be_bytes()); // layer
693            v.extend_from_slice(&0u16.to_be_bytes()); // alternate_group
694            v.extend_from_slice(&0u16.to_be_bytes()); // volume
695            v.extend_from_slice(&0u16.to_be_bytes()); // reserved
696            v.extend_from_slice(&UNITY_MATRIX);
697            v.extend_from_slice(&(cfg.width << 16).to_be_bytes());
698            v.extend_from_slice(&(cfg.height << 16).to_be_bytes());
699            v
700        });
701        bx(b"trak", &concat(&[tkhd, mdia]))
702    }
703
704    fn build_audio_trak(&self, cfg: &AudioConfig, movie_ticks: u32) -> Vec<u8> {
705        // Both codings use a version-0 sound sample description — the same
706        // sixteen bytes of channels, depth and rate — and differ only in the
707        // four-character type and what hangs off the end of it.
708        let mut entry = Vec::new();
709        entry.extend_from_slice(&[0u8; 6]); // reserved
710        entry.extend_from_slice(&1u16.to_be_bytes()); // data_reference_index
711        entry.extend_from_slice(&0u16.to_be_bytes()); // version
712        entry.extend_from_slice(&0u16.to_be_bytes()); // revision_level
713        entry.extend_from_slice(&0u32.to_be_bytes()); // vendor
714        entry.extend_from_slice(&cfg.channels.to_be_bytes());
715        entry.extend_from_slice(&cfg.bits_per_sample.to_be_bytes());
716        entry.extend_from_slice(&0u16.to_be_bytes()); // compression_id
717        entry.extend_from_slice(&0u16.to_be_bytes()); // packet_size
718                                                      // sample_rate as 16.16 fixed point
719        entry.extend_from_slice(&(cfg.sample_rate << 16).to_be_bytes());
720
721        let sample_entry = match &cfg.coding {
722            // `sowt` is signed 16-bit little-endian PCM, and a version-0
723            // description is enough for it — what QuickTime, ffmpeg and VLC all
724            // read back.
725            AudioCoding::PcmS16le => bx(b"sowt", &entry),
726            // `mp4a` says only "MPEG-4 audio"; which kind is in the `esds`
727            // underneath it, as a nest of descriptors ending in the encoder's
728            // own AudioSpecificConfig. The two constants are the ones that make
729            // it AAC: object type 0x40 is MPEG-4 Audio, and 0x15 is stream type
730            // 5 (audio) shifted up two with the reserved bit set.
731            AudioCoding::Aac { asc } => {
732                let dec_specific = descriptor(0x05, asc);
733                let dec_config = descriptor(0x04, &{
734                    let mut v = Vec::new();
735                    v.push(0x40); // objectTypeIndication: MPEG-4 Audio
736                    v.push(0x15); // streamType 5 << 2 | upStream 0 << 1 | reserved 1
737                    v.extend_from_slice(&[0, 0, 0]); // bufferSizeDB, unstated
738                    v.extend_from_slice(&0u32.to_be_bytes()); // maxBitrate, unstated
739                    v.extend_from_slice(&0u32.to_be_bytes()); // avgBitrate, unstated
740                    v.extend_from_slice(&dec_specific);
741                    v
742                });
743                // SLConfig 0x02 is "MP4 defaults", which is what a file-backed
744                // track uses: the timing is in the sample tables, not in-band.
745                let sl_config = descriptor(0x06, &[0x02]);
746                let es = descriptor(0x03, &{
747                    let mut v = Vec::new();
748                    v.extend_from_slice(&1u16.to_be_bytes()); // ES_ID
749                    v.push(0x00); // no dependency, no URL, no OCR
750                    v.extend_from_slice(&dec_config);
751                    v.extend_from_slice(&sl_config);
752                    v
753                });
754                entry.extend_from_slice(&fullbox(b"esds", 0, 0, &es));
755                bx(b"mp4a", &entry)
756            }
757        };
758        let stsd = fullbox(b"stsd", 0, 0, &{
759            let mut v = Vec::new();
760            v.extend_from_slice(&1u32.to_be_bytes());
761            v.extend_from_slice(&sample_entry);
762            v
763        });
764
765        // PCM frames are all one size and the table says so once; AAC packets
766        // are each their own and have to be listed.
767        let constant_size = cfg.is_pcm().then(|| cfg.bytes_per_frame() as u32);
768        let stbl = bx(
769            b"stbl",
770            &concat(&[
771                stsd,
772                self.audio.time_to_sample(),
773                self.audio.sample_to_chunk(),
774                self.audio.sample_size(constant_size),
775                self.audio.chunk_offsets(),
776            ]),
777        );
778
779        let smhd = fullbox(b"smhd", 0, 0, &[0u8; 4]); // balance + reserved
780        let minf = bx(
781            b"minf",
782            &concat(&[smhd, handler(b"soun"), data_information(), stbl]),
783        );
784        let mdia = bx(
785            b"mdia",
786            &concat(&[
787                media_header(cfg.sample_rate, self.audio.duration),
788                handler(b"soun"),
789                minf,
790            ]),
791        );
792
793        // Skip the priming: present this track from `encoder_delay` into its
794        // media rather than from the top, which is the only way a file can say
795        // "these samples are here for the decoder, not for the listener".
796        let edts = if cfg.encoder_delay > 0 && self.audio.duration > u64::from(cfg.encoder_delay) {
797            let media = self.audio.duration - u64::from(cfg.encoder_delay);
798            let elst = fullbox(b"elst", 0, 0, &{
799                let mut v = Vec::new();
800                v.extend_from_slice(&1u32.to_be_bytes()); // entry_count
801                v.extend_from_slice(&Self::movie_ticks(media, cfg.sample_rate).to_be_bytes());
802                v.extend_from_slice(&cfg.encoder_delay.to_be_bytes()); // media_time
803                v.extend_from_slice(&0x0001_0000u32.to_be_bytes()); // media_rate 1.0
804                v
805            });
806            Some(bx(b"edts", &elst))
807        } else {
808            None
809        };
810
811        let tkhd = fullbox(b"tkhd", 0, 7, &{
812            let mut v = Vec::new();
813            v.extend_from_slice(&0u32.to_be_bytes());
814            v.extend_from_slice(&0u32.to_be_bytes());
815            v.extend_from_slice(&2u32.to_be_bytes()); // track_ID
816            v.extend_from_slice(&0u32.to_be_bytes());
817            v.extend_from_slice(&movie_ticks.to_be_bytes());
818            v.extend_from_slice(&[0u8; 8]);
819            v.extend_from_slice(&0u16.to_be_bytes()); // layer
820            v.extend_from_slice(&0u16.to_be_bytes()); // alternate_group
821            v.extend_from_slice(&0x0100u16.to_be_bytes()); // volume 1.0
822            v.extend_from_slice(&0u16.to_be_bytes()); // reserved
823            v.extend_from_slice(&UNITY_MATRIX);
824            v.extend_from_slice(&0u32.to_be_bytes()); // width
825            v.extend_from_slice(&0u32.to_be_bytes()); // height
826            v
827        });
828        let mut parts = vec![tkhd];
829        parts.extend(edts);
830        parts.push(mdia);
831        bx(b"trak", &concat(&parts))
832    }
833}
834
835fn media_header(timescale: u32, duration: u64) -> Vec<u8> {
836    fullbox(b"mdhd", 0, 0, &{
837        let mut v = Vec::new();
838        v.extend_from_slice(&0u32.to_be_bytes()); // creation_time
839        v.extend_from_slice(&0u32.to_be_bytes()); // modification_time
840        v.extend_from_slice(&timescale.to_be_bytes());
841        v.extend_from_slice(&(duration.min(u64::from(u32::MAX)) as u32).to_be_bytes());
842        v.extend_from_slice(&0x55c4u16.to_be_bytes()); // language 'und'
843        v.extend_from_slice(&0u16.to_be_bytes()); // pre_defined
844        v
845    })
846}
847
848fn handler(kind: &[u8; 4]) -> Vec<u8> {
849    fullbox(b"hdlr", 0, 0, &{
850        let mut v = Vec::new();
851        v.extend_from_slice(&0u32.to_be_bytes()); // pre_defined
852        v.extend_from_slice(kind);
853        v.extend_from_slice(&[0u8; 12]); // reserved
854        v.extend_from_slice(b"threers\0");
855        v
856    })
857}
858
859fn data_information() -> Vec<u8> {
860    let dref = fullbox(b"dref", 0, 0, &{
861        let mut v = Vec::new();
862        v.extend_from_slice(&1u32.to_be_bytes()); // entry_count
863        v.extend_from_slice(&fullbox(b"url ", 0, 1, &[])); // self-contained
864        v
865    });
866    bx(b"dinf", &dref)
867}
868
869#[cfg(test)]
870mod tests {
871    use super::*;
872    use crate::mp4_demux::demux_video;
873    use std::io::Cursor;
874
875    /// Real H.264 parameter sets, captured from an iPad screen stream.
876    const SPS: &[u8] = &[
877        0x27, 0x64, 0x00, 0x33, 0xac, 0x56, 0x80, 0x47, 0x01, 0x33, 0xe6, 0x9e, 0x6e, 0x04, 0x04,
878        0x04, 0x04,
879    ];
880    const PPS: &[u8] = &[0x28, 0xee, 0x3c, 0xb0];
881
882    fn video_config() -> VideoConfig {
883        VideoConfig {
884            width: 1126,
885            height: 2436,
886            timescale: 1_000_000,
887            avcc: crate::h264::avcc::build_avcc(SPS, PPS),
888        }
889    }
890
891    /// One AVCC-framed NAL of `n` payload bytes, so the total sample is `n + 4`.
892    fn avcc_frame(n: usize, fill: u8) -> Vec<u8> {
893        let mut v = Vec::with_capacity(4 + n);
894        v.extend_from_slice(&(n as u32).to_be_bytes());
895        v.extend(std::iter::repeat_n(fill, n));
896        v
897    }
898
899    fn contains_tag(data: &[u8], tag: &[u8; 4]) -> bool {
900        data.windows(4).any(|w| w == tag)
901    }
902
903    type Frame = (Vec<u8>, u32, bool);
904
905    fn write_video_only(frames: &[Frame]) -> Vec<u8> {
906        let mut w = Mp4StreamWriter::new(Cursor::new(Vec::new()), video_config(), None).unwrap();
907        for (data, dur, sync) in frames {
908            w.write_video_sample(data, *dur, *sync).unwrap();
909        }
910        w.finish_with_sink().unwrap().1.into_inner()
911    }
912
913    #[test]
914    fn roundtrips_through_the_demuxer() {
915        let frames: Vec<Frame> = vec![
916            (avcc_frame(120, 0xa1), 16_666, true),
917            (avcc_frame(40, 0xa2), 16_666, false),
918            (avcc_frame(55, 0xa3), 33_333, false),
919            (avcc_frame(200, 0xa4), 16_666, true),
920            (avcc_frame(30, 0xa5), 16_666, false),
921        ];
922        let bytes = write_video_only(&frames);
923
924        let track = demux_video(&bytes).expect("demux");
925        assert_eq!((track.width, track.height), (1126, 2436));
926        assert_eq!(track.timescale, 1_000_000);
927        assert_eq!(track.config, crate::h264::avcc::build_avcc(SPS, PPS));
928        assert_eq!(track.samples.len(), frames.len());
929
930        for (i, (data, dur, sync)) in frames.iter().enumerate() {
931            let s = &track.samples[i];
932            assert_eq!(s.size as usize, data.len(), "sample {i} size");
933            assert_eq!(s.duration, *dur, "sample {i} duration");
934            assert_eq!(s.sync, *sync, "sample {i} sync flag");
935            let start = s.offset as usize;
936            assert_eq!(
937                &bytes[start..start + s.size as usize],
938                data.as_slice(),
939                "sample {i} bytes at its recorded offset"
940            );
941        }
942    }
943
944    #[test]
945    fn variable_durations_survive_the_round_trip() {
946        // The shape a screen feed actually produces: a burst at frame rate, then
947        // a long gap while nothing on screen changes. A fixed-duration muxer
948        // would silently rewrite this to a constant rate.
949        let durations = [16_666u32, 16_666, 16_666, 500_000, 16_666];
950        let frames: Vec<Frame> = durations
951            .iter()
952            .enumerate()
953            .map(|(i, d)| (avcc_frame(32 + i, 0xb0 + i as u8), *d, i == 0))
954            .collect();
955        let bytes = write_video_only(&frames);
956        let track = demux_video(&bytes).unwrap();
957        let got: Vec<u32> = track.samples.iter().map(|s| s.duration).collect();
958        assert_eq!(got, durations);
959    }
960
961    #[test]
962    fn stss_is_omitted_when_every_sample_is_a_keyframe() {
963        let frames: Vec<Frame> = (0..3u8)
964            .map(|i| (avcc_frame(16, 0xc0 + i), 16_666, true))
965            .collect();
966        let bytes = write_video_only(&frames);
967        assert!(
968            !contains_tag(&bytes, b"stss"),
969            "an all-keyframe track should omit stss; its absence already means \
970             every sample is a sync sample"
971        );
972        let track = demux_video(&bytes).unwrap();
973        assert!(track.samples.iter().all(|s| s.sync));
974    }
975
976    #[test]
977    fn stss_lists_only_real_keyframes() {
978        // Guards the bug this module exists to fix: claiming every frame is a
979        // sync sample makes a player seek onto a P-frame and show garbage.
980        let sync_flags = [true, false, false, false, true, false];
981        let frames: Vec<Frame> = sync_flags
982            .iter()
983            .enumerate()
984            .map(|(i, s)| (avcc_frame(16 + i, 0xd0 + i as u8), 16_666, *s))
985            .collect();
986        let bytes = write_video_only(&frames);
987        assert!(contains_tag(&bytes, b"stss"), "a mixed track needs an stss");
988        let track = demux_video(&bytes).unwrap();
989        let got: Vec<bool> = track.samples.iter().map(|s| s.sync).collect();
990        assert_eq!(got, sync_flags);
991    }
992
993    #[test]
994    fn mdat_length_is_patched_after_the_fact() {
995        let frames: Vec<Frame> = vec![(avcc_frame(100, 0xe1), 16_666, true)];
996        let bytes = write_video_only(&frames);
997
998        let ftyp_len = u32::from_be_bytes(bytes[0..4].try_into().unwrap()) as usize;
999        assert_eq!(&bytes[ftyp_len + 4..ftyp_len + 8], b"mdat");
1000        assert_eq!(
1001            u32::from_be_bytes(bytes[ftyp_len..ftyp_len + 4].try_into().unwrap()),
1002            1,
1003            "mdat should use the 64-bit extended size form so it can be patched \
1004             without moving the payload"
1005        );
1006        let largesize = u64::from_be_bytes(bytes[ftyp_len + 8..ftyp_len + 16].try_into().unwrap());
1007        assert_eq!(largesize, 16 + 104, "mdat size must include its own header");
1008    }
1009
1010    #[test]
1011    fn audio_track_is_written_and_interleaved_with_video() {
1012        let cfg = AudioConfig::pcm_s16le(48_000, 2);
1013        assert_eq!(cfg.bytes_per_frame(), 4);
1014
1015        let mut w =
1016            Mp4StreamWriter::new(Cursor::new(Vec::new()), video_config(), Some(cfg)).unwrap();
1017        for i in 0..4u8 {
1018            w.write_video_sample(&avcc_frame(64, 0xf0 + i), 16_666, i == 0)
1019                .unwrap();
1020            // 480 frames is 10 ms of 48 kHz stereo.
1021            w.write_audio_sample(&vec![i; 480 * 4]).unwrap();
1022        }
1023        let (stats, cursor) = w.finish_with_sink().unwrap();
1024        let bytes = cursor.into_inner();
1025
1026        assert_eq!(stats.video_samples, 4);
1027        assert_eq!(stats.audio_frames, 4 * 480);
1028        assert_eq!(stats.keyframes, 1);
1029
1030        assert!(contains_tag(&bytes, b"sowt"), "missing pcm sample entry");
1031        assert!(contains_tag(&bytes, b"smhd"), "missing sound media header");
1032        assert!(contains_tag(&bytes, b"qt  "), "a pcm file brands as qt");
1033
1034        // Interleaving puts each video sample in its own chunk; the offsets must
1035        // still land exactly on the AVCC length prefix we wrote.
1036        let track = demux_video(&bytes).unwrap();
1037        assert_eq!(track.samples.len(), 4);
1038        for (i, s) in track.samples.iter().enumerate() {
1039            assert_eq!(s.size, 68, "sample {i} size");
1040            let start = s.offset as usize;
1041            assert_eq!(
1042                u32::from_be_bytes(bytes[start..start + 4].try_into().unwrap()),
1043                64,
1044                "sample {i} offset should point at its length prefix"
1045            );
1046        }
1047    }
1048
1049    /// AAC-LC, 48 kHz, stereo — the two bytes every encoder emits for it.
1050    const ASC: &[u8] = &[0x11, 0x90];
1051
1052    #[test]
1053    fn aac_writes_an_mp4a_entry_with_the_config_inside_it() {
1054        let cfg = AudioConfig::aac(48_000, 2, ASC.to_vec(), 0);
1055        let mut w =
1056            Mp4StreamWriter::new(Cursor::new(Vec::new()), video_config(), Some(cfg)).unwrap();
1057        for i in 0..4u8 {
1058            w.write_video_sample(&avcc_frame(64, 0xf0 + i), 16_666, i == 0)
1059                .unwrap();
1060            // AAC-LC codes 1024 samples a packet, whatever the packet weighs.
1061            w.write_audio_packet(&vec![i; 180 + i as usize], 1024)
1062                .unwrap();
1063        }
1064        let (stats, cursor) = w.finish_with_sink().unwrap();
1065        let bytes = cursor.into_inner();
1066
1067        assert_eq!(stats.audio_frames, 4);
1068        assert_eq!(stats.audio_duration_ticks, 4 * 1024);
1069
1070        assert!(
1071            contains_tag(&bytes, b"mp4a"),
1072            "missing the aac sample entry"
1073        );
1074        assert!(contains_tag(&bytes, b"esds"), "missing the decoder config");
1075        assert!(!contains_tag(&bytes, b"sowt"), "this is not a pcm track");
1076        // The whole point of AAC over PCM here: the file stays an MP4 rather
1077        // than becoming a QuickTime movie, which is what a browser will play.
1078        assert!(!contains_tag(&bytes, b"qt  "), "an aac file must stay isom");
1079
1080        // The AudioSpecificConfig has to survive into the file verbatim, inside
1081        // a DecoderSpecificInfo of its own length — a decoder that cannot find
1082        // it will not play the track at all.
1083        let want = [0x05u8, ASC.len() as u8, ASC[0], ASC[1]];
1084        assert!(
1085            bytes.windows(want.len()).any(|w| w == want),
1086            "the DecoderSpecificInfo should carry the ASC as written"
1087        );
1088
1089        // Video must still be readable with an audio track beside it.
1090        let track = demux_video(&bytes).unwrap();
1091        assert_eq!(track.samples.len(), 4);
1092    }
1093
1094    #[test]
1095    fn an_edit_list_hides_the_encoder_priming() {
1096        // 2048 samples of priming is what a two-frame AAC encoder emits before
1097        // the content starts, and 43 ms of silence against a picture is plainly
1098        // visible. The samples stay — the decoder needs them — and the edit
1099        // list says where to begin.
1100        let cfg = AudioConfig::aac(48_000, 2, ASC.to_vec(), 2048);
1101        let mut w =
1102            Mp4StreamWriter::new(Cursor::new(Vec::new()), video_config(), Some(cfg)).unwrap();
1103        w.write_video_sample(&avcc_frame(16, 1), 16_666, true)
1104            .unwrap();
1105        for _ in 0..8 {
1106            w.write_audio_packet(&[7u8; 128], 1024).unwrap();
1107        }
1108        let bytes = w.finish_with_sink().unwrap().1.into_inner();
1109
1110        assert!(contains_tag(&bytes, b"elst"), "no edit list");
1111        // One entry, running from media time 2048 at normal rate. 8192 samples
1112        // of track less 2048 of priming is 6144, which is 128 ms of movie.
1113        let want: Vec<u8> = {
1114            let mut v = Vec::new();
1115            v.extend_from_slice(&1u32.to_be_bytes()); // entry_count
1116            v.extend_from_slice(&128u32.to_be_bytes()); // segment_duration, movie ticks
1117            v.extend_from_slice(&2048u32.to_be_bytes()); // media_time
1118            v.extend_from_slice(&0x0001_0000u32.to_be_bytes()); // rate 1.0
1119            v
1120        };
1121        assert!(
1122            bytes.windows(want.len()).any(|w| w == want),
1123            "the edit list should start the track at the first real sample"
1124        );
1125    }
1126
1127    #[test]
1128    fn no_priming_means_no_edit_list() {
1129        // An `elst` that skips nothing is a box every player has to parse to
1130        // learn it was not needed.
1131        let cfg = AudioConfig::aac(48_000, 2, ASC.to_vec(), 0);
1132        let mut w =
1133            Mp4StreamWriter::new(Cursor::new(Vec::new()), video_config(), Some(cfg)).unwrap();
1134        w.write_video_sample(&avcc_frame(16, 1), 16_666, true)
1135            .unwrap();
1136        w.write_audio_packet(&[7u8; 128], 1024).unwrap();
1137        let bytes = w.finish_with_sink().unwrap().1.into_inner();
1138        assert!(
1139            !contains_tag(&bytes, b"elst"),
1140            "nothing to skip, nothing to say"
1141        );
1142    }
1143
1144    #[test]
1145    fn aac_packets_keep_their_own_sizes() {
1146        // PCM can say "every sample is four bytes" once. AAC cannot: a packet
1147        // is as long as the coder made it, so the sizes have to be listed, and
1148        // a constant-size `stsz` would hand the decoder the wrong bytes.
1149        let cfg = AudioConfig::aac(44_100, 1, ASC.to_vec(), 0);
1150        let mut w =
1151            Mp4StreamWriter::new(Cursor::new(Vec::new()), video_config(), Some(cfg)).unwrap();
1152        w.write_video_sample(&avcc_frame(16, 1), 16_666, true)
1153            .unwrap();
1154        let packets: [&[u8]; 3] = [&[1u8; 97], &[2u8; 211], &[3u8; 64]];
1155        for p in packets {
1156            w.write_audio_packet(p, 1024).unwrap();
1157        }
1158        let (stats, cursor) = w.finish_with_sink().unwrap();
1159        let bytes = cursor.into_inner();
1160        assert_eq!(stats.audio_frames, 3);
1161
1162        // Find the audio `stsz`: the video one lists one sample, this one three.
1163        let want: Vec<u8> = {
1164            let mut v = vec![0, 0, 0, 0]; // sample_size 0 → sizes follow
1165            v.extend_from_slice(&3u32.to_be_bytes());
1166            for p in packets {
1167                v.extend_from_slice(&(p.len() as u32).to_be_bytes());
1168            }
1169            v
1170        };
1171        assert!(
1172            bytes.windows(want.len()).any(|w| w == want),
1173            "each packet's own length must reach the sample size table"
1174        );
1175    }
1176
1177    #[test]
1178    fn the_two_codings_refuse_each_other() {
1179        let mut aac = Mp4StreamWriter::new(
1180            Cursor::new(Vec::new()),
1181            video_config(),
1182            Some(AudioConfig::aac(48_000, 2, ASC.to_vec(), 0)),
1183        )
1184        .unwrap();
1185        assert!(
1186            aac.write_audio_sample(&[0; 16]).is_err(),
1187            "pcm into an aac track"
1188        );
1189
1190        let mut pcm = Mp4StreamWriter::new(
1191            Cursor::new(Vec::new()),
1192            video_config(),
1193            Some(AudioConfig::pcm_s16le(48_000, 2)),
1194        )
1195        .unwrap();
1196        assert!(
1197            pcm.write_audio_packet(&[0; 16], 1024).is_err(),
1198            "a packet into pcm"
1199        );
1200    }
1201
1202    #[test]
1203    fn descriptor_lengths_use_the_base_128_form() {
1204        // Under 128 bytes it is one byte, which is every ordinary ASC. Over it,
1205        // the length continues across bytes with the top bit set — getting this
1206        // wrong truncates the config and the track goes silent.
1207        assert_eq!(
1208            descriptor(0x05, &[0xaa, 0xbb]),
1209            vec![0x05, 0x02, 0xaa, 0xbb]
1210        );
1211        let long = vec![0u8; 200];
1212        let d = descriptor(0x04, &long);
1213        assert_eq!(&d[..3], &[0x04, 0x81, 0x48], "200 is 0x81 0x48 in base 128");
1214        assert_eq!(d.len(), 3 + 200);
1215    }
1216
1217    #[test]
1218    fn partial_pcm_frames_are_carried_rather_than_dropped() {
1219        let cfg = AudioConfig::pcm_s16le(48_000, 2);
1220        let mut w =
1221            Mp4StreamWriter::new(Cursor::new(Vec::new()), video_config(), Some(cfg)).unwrap();
1222        w.write_video_sample(&avcc_frame(16, 1), 16_666, true)
1223            .unwrap();
1224        // Six bytes is one whole 4-byte frame plus half of the next.
1225        w.write_audio_sample(&[1, 2, 3, 4, 5, 6]).unwrap();
1226        // These two complete it, so two frames should be stored in total.
1227        w.write_audio_sample(&[7, 8]).unwrap();
1228        let stats = w.finish().unwrap();
1229        assert_eq!(stats.audio_frames, 2, "the split frame must not be lost");
1230        assert_eq!(stats.audio_duration_ticks, 2);
1231    }
1232
1233    #[test]
1234    fn a_capture_with_no_samples_still_produces_a_parsable_file() {
1235        let w = Mp4StreamWriter::new(Cursor::new(Vec::new()), video_config(), None).unwrap();
1236        let bytes = w.finish_with_sink().unwrap().1.into_inner();
1237        assert!(contains_tag(&bytes, b"moov"));
1238        assert!(contains_tag(&bytes, b"avcC"));
1239    }
1240}