diff --git a/src/Titano.Core/Video/Mp4/BoxWriter.cs b/src/Titano.Core/Video/Mp4/BoxWriter.cs
new file mode 100644
index 00000000..80542462
--- /dev/null
+++ b/src/Titano.Core/Video/Mp4/BoxWriter.cs
@@ -0,0 +1,106 @@
+using System.Buffers.Binary;
+
+namespace Titano.Core.Video.Mp4;
+
+///
+/// Big-endian ISO-BMFF box builder over a growable in-memory buffer. Boxes nest with
+/// /; sizes (32-bit) are patched when a box closes.
+///
+public sealed class BoxWriter
+{
+ private readonly Stack _open = new();
+ private byte[] _buffer;
+ private int _length;
+
+ public BoxWriter(int capacity = 4096) => _buffer = new byte[Math.Max(capacity, 64)];
+
+ public int Length => _length;
+
+ public ReadOnlySpan WrittenSpan => _buffer.AsSpan(0, _length);
+
+ public void BeginBox(string type)
+ {
+ _open.Push(_length);
+ WriteUInt32(0);
+ WriteFourCc(type);
+ }
+
+ public void BeginFullBox(string type, byte version, uint flags)
+ {
+ BeginBox(type);
+ WriteUInt32((uint)version << 24 | (flags & 0xFFFFFF));
+ }
+
+ public void EndBox()
+ {
+ var start = _open.Pop();
+ BinaryPrimitives.WriteUInt32BigEndian(_buffer.AsSpan(start), (uint)(_length - start));
+ }
+
+ public void WriteByte(int value) => Grow(1)[0] = (byte)value;
+
+ public void WriteUInt16(int value) => BinaryPrimitives.WriteUInt16BigEndian(Grow(2), (ushort)value);
+
+ public void WriteInt16(short value) => BinaryPrimitives.WriteInt16BigEndian(Grow(2), value);
+
+ public void WriteUInt24(uint value)
+ {
+ var span = Grow(3);
+ span[0] = (byte)(value >> 16);
+ span[1] = (byte)(value >> 8);
+ span[2] = (byte)value;
+ }
+
+ public void WriteUInt32(uint value) => BinaryPrimitives.WriteUInt32BigEndian(Grow(4), value);
+
+ public void WriteInt32(int value) => BinaryPrimitives.WriteInt32BigEndian(Grow(4), value);
+
+ public void WriteUInt48(ulong value)
+ {
+ WriteUInt16((int)(value >> 32));
+ WriteUInt32((uint)value);
+ }
+
+ public void WriteUInt64(ulong value) => BinaryPrimitives.WriteUInt64BigEndian(Grow(8), value);
+
+ public void WriteInt64(long value) => BinaryPrimitives.WriteInt64BigEndian(Grow(8), value);
+
+ public void WriteFourCc(string fourCc)
+ {
+ if (fourCc.Length != 4) throw new ArgumentException("A four-character code is required", nameof(fourCc));
+ var span = Grow(4);
+ for (var i = 0; i < 4; i++) span[i] = (byte)fourCc[i];
+ }
+
+ public void WriteBytes(ReadOnlySpan bytes) => bytes.CopyTo(Grow(bytes.Length));
+
+ public void WriteZeros(int count) => Grow(count).Clear();
+
+ /// The identity transformation matrix of mvhd/tkhd.
+ public void WriteUnityMatrix()
+ {
+ WriteUInt32(0x00010000);
+ WriteUInt32(0);
+ WriteUInt32(0);
+ WriteUInt32(0);
+ WriteUInt32(0x00010000);
+ WriteUInt32(0);
+ WriteUInt32(0);
+ WriteUInt32(0);
+ WriteUInt32(0x40000000);
+ }
+
+ public byte[] ToArray()
+ {
+ if (_open.Count != 0) throw new InvalidOperationException("Unclosed box");
+ return WrittenSpan.ToArray();
+ }
+
+ private Span Grow(int count)
+ {
+ if (_length + count > _buffer.Length) Array.Resize(ref _buffer, Math.Max(_buffer.Length * 2, _length + count));
+ var span = _buffer.AsSpan(_length, count);
+ _length += count;
+ return span;
+ }
+}
diff --git a/src/Titano.Core/Video/Mp4/DecoderConfiguration.cs b/src/Titano.Core/Video/Mp4/DecoderConfiguration.cs
new file mode 100644
index 00000000..a9df9b77
--- /dev/null
+++ b/src/Titano.Core/Video/Mp4/DecoderConfiguration.cs
@@ -0,0 +1,251 @@
+using System.Buffers.Binary;
+using System.Globalization;
+using Titano.Core.Video.Bitstream;
+
+namespace Titano.Core.Video.Mp4;
+
+///
+/// A decoder configuration record (avcC, hvcC or av1C payload) with the stream properties it declares.
+///
+public sealed record DecoderConfiguration(
+ VideoCodec Codec,
+ string BoxType,
+ byte[] Payload,
+ int Width,
+ int Height,
+ int BitDepth,
+ string CodecString)
+{
+ /// Builds avcC (ISO/IEC 14496-15 5.3.3) from SPS and PPS NAL units; the first SPS describes the stream.
+ public static DecoderConfiguration ForAvc(IReadOnlyList sps, IReadOnlyList pps)
+ {
+ if (sps.Count is 0 or > 31 || pps.Count is 0 or > 255) throw new ArgumentException("avcC needs 1–31 SPS and 1–255 PPS");
+ if (!H264SpsParser.TryParse(sps[0], out var info)) throw new ArgumentException("Unparseable H.264 SPS", nameof(sps));
+ var w = new BoxWriter(256);
+ w.WriteByte(1);
+ w.WriteByte(info.ProfileIdc);
+ w.WriteByte(info.ConstraintFlags);
+ w.WriteByte(info.LevelIdc);
+ w.WriteByte(0xFF); // reserved + lengthSizeMinusOne = 3
+ w.WriteByte(0xE0 | sps.Count);
+ foreach (var s in sps)
+ {
+ w.WriteUInt16(s.Length);
+ w.WriteBytes(s);
+ }
+ w.WriteByte(pps.Count);
+ foreach (var p in pps)
+ {
+ w.WriteUInt16(p.Length);
+ w.WriteBytes(p);
+ }
+ if (info.ProfileIdc is 100 or 110 or 122 or 144)
+ {
+ w.WriteByte(0xFC | info.ChromaFormatIdc);
+ w.WriteByte(0xF8 | (info.BitDepthLuma - 8));
+ w.WriteByte(0xF8 | (info.BitDepthChroma - 8));
+ w.WriteByte(0); // numOfSequenceParameterSetExt
+ }
+ return new DecoderConfiguration(VideoCodec.H264, "avcC", w.ToArray(), info.Width, info.Height, info.BitDepthLuma, AvcCodecString(info));
+ }
+
+ /// Builds hvcC (ISO/IEC 14496-15 8.3.3) with complete VPS/SPS/PPS arrays; the first SPS describes the stream.
+ public static DecoderConfiguration ForHevc(IReadOnlyList vps, IReadOnlyList sps, IReadOnlyList pps)
+ {
+ if (vps.Count == 0 || sps.Count == 0 || pps.Count == 0) throw new ArgumentException("hvcC needs VPS, SPS and PPS");
+ if (!HevcSpsParser.TryParse(sps[0], out var info)) throw new ArgumentException("Unparseable HEVC SPS", nameof(sps));
+ var ptl = info.ProfileTierLevel;
+ var w = new BoxWriter(256);
+ w.WriteByte(1);
+ w.WriteByte(ptl.ProfileSpace << 6 | (ptl.HighTier ? 0x20 : 0) | ptl.ProfileIdc);
+ w.WriteUInt32(ptl.ProfileCompatibilityFlags);
+ w.WriteUInt48(ptl.ConstraintIndicatorFlags);
+ w.WriteByte(ptl.LevelIdc);
+ w.WriteUInt16(0xF000); // min_spatial_segmentation_idc = 0
+ w.WriteByte(0xFC); // parallelismType = 0 (unknown)
+ w.WriteByte(0xFC | info.ChromaFormatIdc);
+ w.WriteByte(0xF8 | (info.BitDepthLuma - 8));
+ w.WriteByte(0xF8 | (info.BitDepthChroma - 8));
+ w.WriteUInt16(0); // avgFrameRate unspecified
+ w.WriteByte((info.MaxSubLayers & 7) << 3 | (info.TemporalIdNesting ? 4 : 0) | 3);
+ w.WriteByte(3);
+ WriteArray(w, HevcNalUnitType.Vps, vps);
+ WriteArray(w, HevcNalUnitType.Sps, sps);
+ WriteArray(w, HevcNalUnitType.Pps, pps);
+ return new DecoderConfiguration(VideoCodec.Hevc, "hvcC", w.ToArray(), info.Width, info.Height, info.BitDepthLuma, HevcCodecString(ptl));
+
+ static void WriteArray(BoxWriter w, HevcNalUnitType type, IReadOnlyList nals)
+ {
+ w.WriteByte(0x80 | (int)type); // array_completeness = 1: no parameter sets in-band (hvc1)
+ w.WriteUInt16(nals.Count);
+ foreach (var nal in nals)
+ {
+ w.WriteUInt16(nal.Length);
+ w.WriteBytes(nal);
+ }
+ }
+ }
+
+ /// Builds av1C (AV1-ISOBMFF 2.3) around a sequence header OBU written with obu_size.
+ public static DecoderConfiguration ForAv1(byte[] sequenceHeaderObu)
+ {
+ if (!Av1ObuParser.TryReadObu(sequenceHeaderObu, 0, out var obu) || obu.Type != Av1ObuType.SequenceHeader || !obu.HasSizeField
+ || !Av1ObuParser.TryParseSequenceHeader(obu.Payload(sequenceHeaderObu), out var seq))
+ throw new ArgumentException("A sized sequence header OBU is required", nameof(sequenceHeaderObu));
+ var w = new BoxWriter(64);
+ w.WriteByte(0x81); // marker + version 1
+ w.WriteByte(seq.SeqProfile << 5 | seq.SeqLevelIdx);
+ w.WriteByte((seq.SeqTier ? 0x80 : 0) | (seq.HighBitDepth ? 0x40 : 0) | (seq.TwelveBit ? 0x20 : 0) | (seq.MonoChrome ? 0x10 : 0)
+ | (seq.ChromaSubsamplingX ? 0x08 : 0) | (seq.ChromaSubsamplingY ? 0x04 : 0) | seq.ChromaSamplePosition);
+ w.WriteByte(seq.InitialDisplayDelay is { } delay ? 0x10 | ((delay - 1) & 0x0F) : 0);
+ w.WriteBytes(sequenceHeaderObu.AsSpan(0, obu.TotalLength));
+ return new DecoderConfiguration(VideoCodec.Av1, "av1C", w.ToArray(), seq.MaxFrameWidth, seq.MaxFrameHeight, seq.BitDepth, Av1CodecString(seq));
+ }
+
+ /// Parses an avcC/hvcC/av1C payload back; explains a failure.
+ public static bool TryParse(string boxType, ReadOnlySpan payload, out DecoderConfiguration? configuration, out string? error)
+ {
+ configuration = null;
+ error = null;
+ try
+ {
+ configuration = boxType switch
+ {
+ "avcC" => ParseAvc(payload, out error),
+ "hvcC" => ParseHevc(payload, out error),
+ "av1C" => ParseAv1(payload, out error),
+ _ => null,
+ };
+ }
+ catch (ArgumentException ex)
+ {
+ error = ex.Message;
+ configuration = null;
+ }
+ error ??= configuration is null ? $"unsupported configuration box '{boxType}'" : null;
+ return configuration is not null;
+ }
+
+ private static DecoderConfiguration? ParseAvc(ReadOnlySpan p, out string? error)
+ {
+ error = null;
+ if (p.Length < 7 || p[0] != 1)
+ {
+ error = "avcC header invalid";
+ return null;
+ }
+ if ((p[4] & 3) != 3) error = "avcC lengthSizeMinusOne is not 3";
+ var pos = 5;
+ var sps = ReadNalList(p, ref pos, p[5] & 0x1F, 1);
+ var pps = pos < p.Length ? ReadNalList(p, ref pos, p[pos], 1) : null;
+ if (sps is null || pps is null || sps.Count == 0 || pps.Count == 0)
+ {
+ error = "avcC parameter set lists truncated or empty";
+ return null;
+ }
+ var config = ForAvc(sps, pps);
+ if (config.Payload[1] != p[1] || config.Payload[3] != p[3]) error = "avcC profile/level differ from its SPS";
+ return config;
+ }
+
+ private static DecoderConfiguration? ParseHevc(ReadOnlySpan p, out string? error)
+ {
+ error = null;
+ if (p.Length < 23 || p[0] != 1)
+ {
+ error = "hvcC header invalid";
+ return null;
+ }
+ if ((p[21] & 3) != 3) error = "hvcC lengthSizeMinusOne is not 3";
+ var arrays = p[22];
+ var pos = 23;
+ List vps = [], sps = [], pps = [];
+ for (var a = 0; a < arrays; a++)
+ {
+ if (pos + 3 > p.Length)
+ {
+ error = "hvcC arrays truncated";
+ return null;
+ }
+ var type = (HevcNalUnitType)(p[pos] & 0x3F);
+ var count = BinaryPrimitives.ReadUInt16BigEndian(p[(pos + 1)..]);
+ pos += 3;
+ var list = ReadNalList(p, ref pos, count, 0);
+ if (list is null)
+ {
+ error = "hvcC NAL units truncated";
+ return null;
+ }
+ (type switch { HevcNalUnitType.Vps => vps, HevcNalUnitType.Sps => sps, HevcNalUnitType.Pps => pps, _ => [] }).AddRange(list);
+ }
+ if (vps.Count == 0 || sps.Count == 0 || pps.Count == 0)
+ {
+ error = "hvcC lacks a VPS, SPS or PPS array";
+ return null;
+ }
+ var config = ForHevc(vps, sps, pps);
+ if (!config.Payload.AsSpan(1, 12).SequenceEqual(p.Slice(1, 12))) error = "hvcC profile/tier/level differ from its SPS";
+ return config;
+ }
+
+ private static DecoderConfiguration? ParseAv1(ReadOnlySpan p, out string? error)
+ {
+ error = null;
+ if (p.Length < 4 || p[0] != 0x81)
+ {
+ error = "av1C marker/version invalid";
+ return null;
+ }
+ var obus = p[4..];
+ foreach (var obu in Av1ObuParser.Split(obus))
+ {
+ if (obu.Type != Av1ObuType.SequenceHeader) continue;
+ var config = ForAv1(obus.Slice(obu.Offset, obu.TotalLength).ToArray());
+ if (config.Payload[1] != p[1] || config.Payload[2] != p[2]) error = "av1C fields differ from its sequence header";
+ return config;
+ }
+ error = "av1C has no sequence header OBU";
+ return null;
+ }
+
+ private static List? ReadNalList(ReadOnlySpan p, ref int pos, int count, int countBytes)
+ {
+ pos += countBytes;
+ var list = new List(count);
+ for (var i = 0; i < count; i++)
+ {
+ if (pos + 2 > p.Length) return null;
+ var length = BinaryPrimitives.ReadUInt16BigEndian(p[pos..]);
+ pos += 2;
+ if (length == 0 || pos + length > p.Length) return null;
+ list.Add(p.Slice(pos, length).ToArray());
+ pos += length;
+ }
+ return list;
+ }
+
+ private static string AvcCodecString(H264Sps sps) =>
+ string.Create(CultureInfo.InvariantCulture, $"avc1.{sps.ProfileIdc:x2}{sps.ConstraintFlags:x2}{sps.LevelIdc:x2}");
+
+ private static string HevcCodecString(HevcProfileTierLevel ptl)
+ {
+ var space = ptl.ProfileSpace == 0 ? string.Empty : ((char)('A' + ptl.ProfileSpace - 1)).ToString();
+ var compatibility = ReverseBits(ptl.ProfileCompatibilityFlags);
+ var s = string.Create(CultureInfo.InvariantCulture,
+ $"hvc1.{space}{ptl.ProfileIdc}.{compatibility:X}.{(ptl.HighTier ? 'H' : 'L')}{ptl.LevelIdc}");
+ var last = 5;
+ while (last >= 0 && ((ptl.ConstraintIndicatorFlags >> (8 * (5 - last))) & 0xFF) == 0) last--;
+ for (var i = 0; i <= last; i++) s += "." + ((ptl.ConstraintIndicatorFlags >> (8 * (5 - i))) & 0xFF).ToString("X", CultureInfo.InvariantCulture);
+ return s;
+ }
+
+ private static string Av1CodecString(Av1SequenceHeader seq) =>
+ string.Create(CultureInfo.InvariantCulture, $"av01.{seq.SeqProfile}.{seq.SeqLevelIdx:D2}{(seq.SeqTier ? 'H' : 'M')}.{seq.BitDepth:D2}");
+
+ private static uint ReverseBits(uint v)
+ {
+ uint r = 0;
+ for (var i = 0; i < 32; i++, v >>= 1) r = (r << 1) | (v & 1);
+ return r;
+ }
+}
diff --git a/src/Titano.Core/Video/Mp4/Mp4Muxer.cs b/src/Titano.Core/Video/Mp4/Mp4Muxer.cs
new file mode 100644
index 00000000..2e1f3e74
--- /dev/null
+++ b/src/Titano.Core/Video/Mp4/Mp4Muxer.cs
@@ -0,0 +1,662 @@
+using System.Buffers.Binary;
+using Titano.Core.Diagnostics;
+using Titano.Core.Video.Bitstream;
+
+namespace Titano.Core.Video.Mp4;
+
+/// Parameters of the single video track written by .
+public sealed record VideoTrackConfig
+{
+ /// , or .
+ public required VideoCodec Codec { get; init; }
+
+ /// Display width (tkhd); the sample entry uses the size declared by the bitstream.
+ public required int Width { get; init; }
+
+ public required int Height { get; init; }
+
+ /// Moves moov in front of mdat when completing (progressive playback); the stream must be readable.
+ public bool FastStart { get; init; }
+
+ /// Signalled in colr; Titano encodes limited (video) range.
+ public bool FullRange { get; init; }
+
+ public DateTime CreationTime { get; init; } = DateTime.UtcNow;
+}
+
+///
+/// Streaming MP4 writer for one video track: ftyp, then samples straight into mdat, then moov at the end
+/// (optionally moved to the front). Timescale 90 kHz; parameter sets are taken from the bitstream.
+/// The output stream is not disposed.
+///
+public sealed class Mp4Muxer
+{
+ /// Media and movie timescale (ticks per second).
+ public const int TimeScale = 90_000;
+
+ private const long ChunkTicks = TimeScale;
+ private const long ChunkBytes = 4 << 20;
+ private const string LogCategory = "Mp4Muxer";
+
+ private readonly Stream _stream;
+ private readonly VideoTrackConfig _config;
+ private readonly long _mdatHeader;
+ private readonly List _sizes = [];
+ private readonly List _durations = [];
+ private readonly List _compositionOffsets = [];
+ private readonly List _syncSamples = [];
+ private readonly List _chunkOffsets = [];
+ private readonly List _chunkSampleCounts = [];
+ private readonly SortedDictionary _vps = [];
+ private readonly SortedDictionary _sps = [];
+ private readonly SortedDictionary _pps = [];
+ private byte[]? _av1SequenceHeader;
+ private long _position;
+ private long _chunkTicks;
+ private long _chunkBytes;
+ private long _totalTicks;
+ private long _totalBytes;
+ private bool _warnedInBandChange;
+ private bool _completed;
+
+ public Mp4Muxer(Stream output, VideoTrackConfig config)
+ {
+ ArgumentNullException.ThrowIfNull(output);
+ ArgumentNullException.ThrowIfNull(config);
+ if (config.Codec is not (VideoCodec.H264 or VideoCodec.Hevc or VideoCodec.Av1))
+ throw new ArgumentException($"MP4 muxing supports H.264, HEVC and AV1, not {config.Codec}", nameof(config));
+ if (config.Width is <= 0 or > ushort.MaxValue || config.Height is <= 0 or > ushort.MaxValue)
+ throw new ArgumentOutOfRangeException(nameof(config), "Frame size out of range");
+ if (!output.CanSeek || !output.CanWrite) throw new ArgumentException("The output stream must be writable and seekable", nameof(output));
+ if (config.FastStart && !output.CanRead) throw new ArgumentException("FastStart needs a readable stream", nameof(output));
+
+ _stream = output;
+ _config = config;
+ var ftyp = new BoxWriter(64);
+ ftyp.BeginBox("ftyp");
+ ftyp.WriteFourCc("isom");
+ ftyp.WriteUInt32(0x200);
+ ftyp.WriteFourCc("isom");
+ ftyp.WriteFourCc("iso6");
+ ftyp.WriteFourCc("mp41");
+ if (config.Codec == VideoCodec.Av1) ftyp.WriteFourCc("av01");
+ ftyp.EndBox();
+ _stream.Write(ftyp.WrittenSpan);
+ _mdatHeader = _stream.Position;
+ // 16 bytes: 'free' + 32-bit 'mdat' header, or one 64-bit 'mdat' header when the payload exceeds 4 GiB.
+ _stream.Write(stackalloc byte[16]);
+ _position = _mdatHeader + 16;
+ }
+
+ public int SampleCount => _sizes.Count;
+
+ /// Sum of the sample durations written so far, in 90 kHz ticks.
+ public long Duration90k => _totalTicks;
+
+ ///
+ /// Records parameter sets (H.264/HEVC NAL units, Annex-B or length-prefixed) or an AV1 sequence header OBU
+ /// delivered outside the samples, e.g. an encoder's MF_MT_MPEG_SEQUENCE_HEADER.
+ ///
+ public void AddParameterSets(ReadOnlySpan data)
+ {
+ if (_config.Codec == VideoCodec.Av1)
+ {
+ foreach (var obu in Av1ObuParser.Split(data))
+ {
+ if (obu.Type == Av1ObuType.SequenceHeader) _av1SequenceHeader ??= SizedObu(data, obu);
+ }
+ return;
+ }
+ foreach (var unit in AnnexBParser.SplitAccessUnit(data, out _)) RecordNal(unit.Slice(data));
+ }
+
+ ///
+ /// Appends one access unit (H.264/HEVC: Annex-B or 4-byte length-prefixed NAL units; AV1: a temporal unit of OBUs)
+ /// in decode order. is presentation minus decode time and may be negative.
+ ///
+ public void WriteSample(ReadOnlySpan data, long duration90k, bool isSync, long compositionOffset90k = 0)
+ {
+ if (_completed) throw new InvalidOperationException("The muxer is complete");
+ if (duration90k <= 0 || duration90k > uint.MaxValue) throw new ArgumentOutOfRangeException(nameof(duration90k));
+ if (Math.Abs(compositionOffset90k) > int.MaxValue / 2) throw new ArgumentOutOfRangeException(nameof(compositionOffset90k));
+
+ var start = _position;
+ if (_stream.Position != start) _stream.Position = start;
+ var size = _config.Codec == VideoCodec.Av1 ? WriteObus(data) : WriteNalUnits(data);
+ if (size == 0) throw new ArgumentException("The sample contains no picture data", nameof(data));
+ if (_sizes.Count == 0 && !isSync) Log.Warning(LogCategory, "First sample is not a sync sample; players may not start decoding");
+
+ if (_chunkSampleCounts.Count == 0 || _chunkTicks >= ChunkTicks || _chunkBytes >= ChunkBytes)
+ {
+ _chunkOffsets.Add(start);
+ _chunkSampleCounts.Add(0);
+ _chunkTicks = 0;
+ _chunkBytes = 0;
+ }
+ _chunkSampleCounts[^1]++;
+ _chunkTicks += duration90k;
+ _chunkBytes += size;
+ _sizes.Add((uint)size);
+ _durations.Add((uint)duration90k);
+ _compositionOffsets.Add(compositionOffset90k);
+ if (isSync) _syncSamples.Add((uint)_sizes.Count);
+ _totalTicks += duration90k;
+ _totalBytes += size;
+ }
+
+ /// Patches mdat, writes moov (and relocates it when is set) and flushes.
+ public void Complete()
+ {
+ if (_completed) throw new InvalidOperationException("The muxer is already complete");
+ if (_sizes.Count == 0) throw new InvalidOperationException("No samples were written");
+ var configuration = BuildDecoderConfiguration();
+ if (configuration.Width != _config.Width || configuration.Height != _config.Height)
+ {
+ Log.Warning(LogCategory, $"Bitstream size {configuration.Width}×{configuration.Height} differs from the track size {_config.Width}×{_config.Height}");
+ }
+
+ WriteMdatHeader();
+ var moov = BuildMoov(configuration, 0);
+ _stream.Position = _position;
+ _stream.Write(moov);
+ if (_config.FastStart) MoveMoovToFront(configuration, moov.Length);
+ else _position += moov.Length;
+ _stream.Flush();
+ _completed = true;
+ }
+
+ private long WriteNalUnits(ReadOnlySpan data)
+ {
+ Span length = stackalloc byte[4];
+ long size = 0;
+ var picture = false;
+ foreach (var unit in AnnexBParser.SplitAccessUnit(data, out _))
+ {
+ var nal = unit.Slice(data);
+ if (!RecordNal(nal)) continue;
+ BinaryPrimitives.WriteInt32BigEndian(length, nal.Length);
+ _stream.Write(length);
+ _stream.Write(nal);
+ size += 4 + nal.Length;
+ picture |= IsPicture(nal[0]);
+ }
+ _position += size;
+ return picture ? size : 0;
+ }
+
+ private long WriteObus(ReadOnlySpan data)
+ {
+ var obus = Av1ObuParser.Split(data);
+ if (obus.Count == 0 || obus[^1].Offset + obus[^1].TotalLength != data.Length)
+ throw new ArgumentException("Malformed AV1 temporal unit", nameof(data));
+ Span header = stackalloc byte[2 + 8];
+ long size = 0;
+ var picture = false;
+ foreach (var obu in obus)
+ {
+ if (obu.Type is Av1ObuType.TemporalDelimiter or Av1ObuType.Padding) continue;
+ if (obu.Type == Av1ObuType.SequenceHeader) _av1SequenceHeader ??= SizedObu(data, obu);
+ picture |= obu.Type is Av1ObuType.Frame or Av1ObuType.FrameHeader or Av1ObuType.TileGroup;
+ if (obu.HasSizeField)
+ {
+ _stream.Write(data.Slice(obu.Offset, obu.TotalLength));
+ size += obu.TotalLength;
+ continue;
+ }
+ // Samples carry every OBU with obu_size (AV1-ISOBMFF 2.4).
+ var n = WriteSizedHeader(header, data, obu);
+ _stream.Write(header[..n]);
+ _stream.Write(obu.Payload(data));
+ size += n + obu.PayloadLength;
+ }
+ _position += size;
+ return picture ? size : 0;
+ }
+
+ private static int WriteSizedHeader(Span header, ReadOnlySpan data, Av1Obu obu)
+ {
+ header[0] = (byte)(data[obu.Offset] | 0x02);
+ var n = 1;
+ if (obu.HasExtension) header[n++] = data[obu.Offset + 1];
+ return n + Av1ObuParser.WriteLeb128(header[n..], (ulong)obu.PayloadLength);
+ }
+
+ private static byte[] SizedObu(ReadOnlySpan data, Av1Obu obu)
+ {
+ Span header = stackalloc byte[2 + 8];
+ var n = WriteSizedHeader(header, data, obu);
+ var result = new byte[n + obu.PayloadLength];
+ header[..n].CopyTo(result);
+ obu.Payload(data).CopyTo(result.AsSpan(n));
+ return result;
+ }
+
+ private bool IsPicture(byte header) => _config.Codec == VideoCodec.H264
+ ? AnnexBParser.H264Type(header) is >= H264NalUnitType.NonIdrSlice and <= H264NalUnitType.IdrSlice
+ : (int)AnnexBParser.HevcType(header) < 32;
+
+ /// Stores parameter sets for the sample entry; returns whether the NAL unit belongs in the sample.
+ private bool RecordNal(ReadOnlySpan nal)
+ {
+ if (nal.Length < 2) return true;
+ SortedDictionary table;
+ int id;
+ if (_config.Codec == VideoCodec.H264)
+ {
+ switch (AnnexBParser.H264Type(nal[0]))
+ {
+ case H264NalUnitType.AccessUnitDelimiter or H264NalUnitType.FillerData:
+ return false;
+ case H264NalUnitType.Sps when H264SpsParser.TryParse(nal, out var sps):
+ (table, id) = (_sps, sps.SpsId);
+ break;
+ case H264NalUnitType.Pps:
+ (table, id) = (_pps, FirstUe(nal[1..]));
+ break;
+ default:
+ return true;
+ }
+ }
+ else
+ {
+ switch (AnnexBParser.HevcType(nal[0]))
+ {
+ case HevcNalUnitType.AccessUnitDelimiter or HevcNalUnitType.FillerData:
+ return false;
+ case HevcNalUnitType.Vps when nal.Length > 2:
+ (table, id) = (_vps, nal[2] >> 4);
+ break;
+ case HevcNalUnitType.Sps when HevcSpsParser.TryParse(nal, out var sps):
+ (table, id) = (_sps, sps.SpsId);
+ break;
+ case HevcNalUnitType.Pps:
+ (table, id) = (_pps, FirstUe(nal[2..]));
+ break;
+ default:
+ return true;
+ }
+ }
+ if (id < 0) return true;
+ if (!table.TryGetValue(id, out var known))
+ {
+ table[id] = nal.ToArray();
+ return false;
+ }
+ if (nal.SequenceEqual(known)) return false;
+ // A redefinition keeps working in-band, but the sample entry describes only the first definition.
+ if (!_warnedInBandChange)
+ {
+ Log.Warning(LogCategory, "A parameter set changed mid-stream; keeping the new one in-band");
+ _warnedInBandChange = true;
+ }
+ return true;
+ }
+
+ private static int FirstUe(ReadOnlySpan payload)
+ {
+ var rbsp = AnnexBParser.RemoveEmulationPrevention(payload[..Math.Min(payload.Length, 8)]);
+ var r = new BitReader(rbsp);
+ var v = r.ReadUe();
+ return r.IsOverrun || v > 255 ? -1 : (int)v;
+ }
+
+ private DecoderConfiguration BuildDecoderConfiguration() => _config.Codec switch
+ {
+ VideoCodec.H264 when _sps.Count > 0 && _pps.Count > 0 => DecoderConfiguration.ForAvc([.. _sps.Values], [.. _pps.Values]),
+ VideoCodec.Hevc when _vps.Count > 0 && _sps.Count > 0 && _pps.Count > 0 =>
+ DecoderConfiguration.ForHevc([.. _vps.Values], [.. _sps.Values], [.. _pps.Values]),
+ VideoCodec.Av1 when _av1SequenceHeader is not null => DecoderConfiguration.ForAv1(_av1SequenceHeader),
+ _ => throw new InvalidOperationException("The bitstream carried no parameter sets / sequence header"),
+ };
+
+ private void WriteMdatHeader()
+ {
+ Span header = stackalloc byte[16];
+ var compact = _position - (_mdatHeader + 8);
+ if (compact <= uint.MaxValue)
+ {
+ BinaryPrimitives.WriteUInt32BigEndian(header, 8);
+ "free"u8.CopyTo(header[4..]);
+ BinaryPrimitives.WriteUInt32BigEndian(header[8..], (uint)compact);
+ "mdat"u8.CopyTo(header[12..]);
+ }
+ else
+ {
+ BinaryPrimitives.WriteUInt32BigEndian(header, 1);
+ "mdat"u8.CopyTo(header[4..]);
+ BinaryPrimitives.WriteUInt64BigEndian(header[8..], (ulong)(_position - _mdatHeader));
+ }
+ _stream.Position = _mdatHeader;
+ _stream.Write(header);
+ }
+
+ private void MoveMoovToFront(DecoderConfiguration configuration, int moovAtEnd)
+ {
+ // Chunk offsets grow by the relocated moov size, which itself grows if they now need co64.
+ var delta = moovAtEnd;
+ byte[] moov;
+ while (true)
+ {
+ moov = BuildMoov(configuration, delta);
+ if (moov.Length == delta) break;
+ delta = moov.Length;
+ }
+
+ var buffer = new byte[1 << 20];
+ var remaining = _position - _mdatHeader;
+ while (remaining > 0)
+ {
+ var n = (int)Math.Min(buffer.Length, remaining);
+ var source = _mdatHeader + remaining - n;
+ _stream.Position = source;
+ _stream.ReadExactly(buffer, 0, n);
+ _stream.Position = source + delta;
+ _stream.Write(buffer, 0, n);
+ remaining -= n;
+ }
+ _stream.Position = _mdatHeader;
+ _stream.Write(moov);
+ _position += delta;
+ }
+
+ private byte[] BuildMoov(DecoderConfiguration configuration, long chunkOffsetDelta)
+ {
+ var count = _sizes.Count;
+ long minOffset = 0;
+ foreach (var o in _compositionOffsets) minOffset = Math.Min(minOffset, o);
+ var shift = -minOffset;
+
+ // Presentation span: earliest composition time to the latest composition end.
+ long decode = 0, minCts = long.MaxValue, maxEnd = 0;
+ var anyOffset = false;
+ for (var i = 0; i < count; i++)
+ {
+ var cts = decode + _compositionOffsets[i] + shift;
+ minCts = Math.Min(minCts, cts);
+ maxEnd = Math.Max(maxEnd, cts + _durations[i]);
+ anyOffset |= _compositionOffsets[i] + shift != 0;
+ decode += _durations[i];
+ }
+ var edit = minCts > 0;
+ var presentation = edit ? Math.Max(1, maxEnd - minCts) : _totalTicks;
+ var wide = presentation > uint.MaxValue || _totalTicks > uint.MaxValue;
+ var created = (ulong)Math.Max(0, (_config.CreationTime.ToUniversalTime() - new DateTime(1904, 1, 1, 0, 0, 0, DateTimeKind.Utc)).TotalSeconds);
+
+ var w = new BoxWriter(4096 + count * 16);
+ w.BeginBox("moov");
+
+ w.BeginFullBox("mvhd", wide ? (byte)1 : (byte)0, 0);
+ WriteTimes(w, wide, created, presentation);
+ w.WriteUInt32(0x00010000); // rate 1.0
+ w.WriteUInt16(0x0100); // volume 1.0
+ w.WriteZeros(10);
+ w.WriteUnityMatrix();
+ w.WriteZeros(24);
+ w.WriteUInt32(2); // next_track_ID
+ w.EndBox();
+
+ w.BeginBox("trak");
+ w.BeginFullBox("tkhd", wide ? (byte)1 : (byte)0, 3); // enabled | in movie
+ if (wide)
+ {
+ w.WriteUInt64(created);
+ w.WriteUInt64(created);
+ w.WriteUInt32(1);
+ w.WriteUInt32(0);
+ w.WriteUInt64((ulong)presentation);
+ }
+ else
+ {
+ w.WriteUInt32((uint)created);
+ w.WriteUInt32((uint)created);
+ w.WriteUInt32(1);
+ w.WriteUInt32(0);
+ w.WriteUInt32((uint)presentation);
+ }
+ w.WriteZeros(8);
+ w.WriteZeros(8); // layer, alternate_group, volume, reserved
+ w.WriteUnityMatrix();
+ w.WriteUInt32((uint)_config.Width << 16);
+ w.WriteUInt32((uint)_config.Height << 16);
+ w.EndBox();
+
+ if (edit)
+ {
+ w.BeginBox("edts");
+ w.BeginFullBox("elst", wide ? (byte)1 : (byte)0, 0);
+ w.WriteUInt32(1);
+ if (wide)
+ {
+ w.WriteUInt64((ulong)presentation);
+ w.WriteInt64(minCts);
+ }
+ else
+ {
+ w.WriteUInt32((uint)presentation);
+ w.WriteInt32((int)minCts);
+ }
+ w.WriteUInt32(0x00010000); // media_rate 1.0
+ w.EndBox();
+ w.EndBox();
+ }
+
+ w.BeginBox("mdia");
+ w.BeginFullBox("mdhd", wide ? (byte)1 : (byte)0, 0);
+ WriteTimes(w, wide, created, _totalTicks);
+ w.WriteUInt16(0x55C4); // 'und'
+ w.WriteUInt16(0);
+ w.EndBox();
+
+ w.BeginFullBox("hdlr", 0, 0);
+ w.WriteUInt32(0);
+ w.WriteFourCc("vide");
+ w.WriteZeros(12);
+ w.WriteBytes("VideoHandler\0"u8);
+ w.EndBox();
+
+ w.BeginBox("minf");
+ w.BeginFullBox("vmhd", 0, 1);
+ w.WriteZeros(8);
+ w.EndBox();
+ w.BeginBox("dinf");
+ w.BeginFullBox("dref", 0, 0);
+ w.WriteUInt32(1);
+ w.BeginFullBox("url ", 0, 1); // media data in this file
+ w.EndBox();
+ w.EndBox();
+ w.EndBox();
+
+ w.BeginBox("stbl");
+ WriteSampleDescription(w, configuration);
+ WriteTimeToSample(w);
+ if (anyOffset) WriteCompositionOffsets(w, shift);
+ if (_syncSamples.Count != count)
+ {
+ w.BeginFullBox("stss", 0, 0);
+ w.WriteUInt32((uint)_syncSamples.Count);
+ foreach (var s in _syncSamples) w.WriteUInt32(s);
+ w.EndBox();
+ }
+ WriteSampleToChunk(w);
+ WriteSampleSizes(w);
+ WriteChunkOffsets(w, chunkOffsetDelta);
+ w.EndBox(); // stbl
+ w.EndBox(); // minf
+ w.EndBox(); // mdia
+ w.EndBox(); // trak
+ w.EndBox(); // moov
+ return w.ToArray();
+ }
+
+ private static void WriteTimes(BoxWriter w, bool wide, ulong created, long duration)
+ {
+ if (wide)
+ {
+ w.WriteUInt64(created);
+ w.WriteUInt64(created);
+ w.WriteUInt32(TimeScale);
+ w.WriteUInt64((ulong)duration);
+ }
+ else
+ {
+ w.WriteUInt32((uint)created);
+ w.WriteUInt32((uint)created);
+ w.WriteUInt32(TimeScale);
+ w.WriteUInt32((uint)duration);
+ }
+ }
+
+ private void WriteSampleDescription(BoxWriter w, DecoderConfiguration configuration)
+ {
+ w.BeginFullBox("stsd", 0, 0);
+ w.WriteUInt32(1);
+ w.BeginBox(_config.Codec switch { VideoCodec.H264 => "avc1", VideoCodec.Hevc => "hvc1", _ => "av01" });
+ w.WriteZeros(6);
+ w.WriteUInt16(1); // data_reference_index
+ w.WriteZeros(16); // pre_defined, reserved
+ w.WriteUInt16(configuration.Width);
+ w.WriteUInt16(configuration.Height);
+ w.WriteUInt32(0x00480000); // 72 dpi
+ w.WriteUInt32(0x00480000);
+ w.WriteUInt32(0);
+ w.WriteUInt16(1); // frame_count
+ Span compressor = stackalloc byte[32];
+ compressor.Clear();
+ compressor[0] = 6;
+ "Titano"u8.CopyTo(compressor[1..]);
+ w.WriteBytes(compressor);
+ w.WriteUInt16(0x0018);
+ w.WriteInt16(-1);
+
+ w.BeginBox(configuration.BoxType);
+ w.WriteBytes(configuration.Payload);
+ w.EndBox();
+
+ w.BeginBox("colr");
+ w.WriteFourCc("nclx");
+ w.WriteUInt16(1); // BT.709 primaries
+ w.WriteUInt16(1); // BT.709 transfer
+ w.WriteUInt16(1); // BT.709 matrix
+ w.WriteByte(_config.FullRange ? 0x80 : 0);
+ w.EndBox();
+
+ w.BeginBox("pasp");
+ w.WriteUInt32(1);
+ w.WriteUInt32(1);
+ w.EndBox();
+
+ w.BeginBox("btrt");
+ uint maxSize = 0;
+ foreach (var s in _sizes) maxSize = Math.Max(maxSize, s);
+ var seconds = _totalTicks / (double)TimeScale;
+ w.WriteUInt32(maxSize);
+ w.WriteUInt32((uint)Math.Min(uint.MaxValue, PeakBitrate()));
+ w.WriteUInt32((uint)Math.Min(uint.MaxValue, _totalBytes * 8 / Math.Max(seconds, 1e-9)));
+ w.EndBox();
+
+ w.EndBox(); // sample entry
+ w.EndBox(); // stsd
+ }
+
+ /// Largest number of bits in any one-second window of decode time.
+ private long PeakBitrate()
+ {
+ long peak = 0, window = 0, startTime = 0, time = 0;
+ var first = 0;
+ for (var i = 0; i < _sizes.Count; i++)
+ {
+ window += _sizes[i];
+ while (time - startTime >= TimeScale)
+ {
+ window -= _sizes[first];
+ startTime += _durations[first];
+ first++;
+ }
+ peak = Math.Max(peak, window * 8);
+ time += _durations[i];
+ }
+ return _totalTicks < TimeScale ? (long)(peak * (TimeScale / (double)_totalTicks)) : peak;
+ }
+
+ private void WriteTimeToSample(BoxWriter w)
+ {
+ var runs = new List<(uint Count, uint Delta)>();
+ foreach (var d in _durations)
+ {
+ if (runs.Count > 0 && runs[^1].Delta == d) runs[^1] = (runs[^1].Count + 1, d);
+ else runs.Add((1, d));
+ }
+ w.BeginFullBox("stts", 0, 0);
+ w.WriteUInt32((uint)runs.Count);
+ foreach (var (count, delta) in runs)
+ {
+ w.WriteUInt32(count);
+ w.WriteUInt32(delta);
+ }
+ w.EndBox();
+ }
+
+ private void WriteCompositionOffsets(BoxWriter w, long shift)
+ {
+ var runs = new List<(uint Count, uint Offset)>();
+ foreach (var o in _compositionOffsets)
+ {
+ var v = (uint)(o + shift);
+ if (runs.Count > 0 && runs[^1].Offset == v) runs[^1] = (runs[^1].Count + 1, v);
+ else runs.Add((1, v));
+ }
+ w.BeginFullBox("ctts", 0, 0);
+ w.WriteUInt32((uint)runs.Count);
+ foreach (var (count, offset) in runs)
+ {
+ w.WriteUInt32(count);
+ w.WriteUInt32(offset);
+ }
+ w.EndBox();
+ }
+
+ private void WriteSampleToChunk(BoxWriter w)
+ {
+ var entries = new List<(uint FirstChunk, uint Samples)>();
+ for (var i = 0; i < _chunkSampleCounts.Count; i++)
+ {
+ if (entries.Count == 0 || entries[^1].Samples != _chunkSampleCounts[i]) entries.Add(((uint)i + 1, _chunkSampleCounts[i]));
+ }
+ w.BeginFullBox("stsc", 0, 0);
+ w.WriteUInt32((uint)entries.Count);
+ foreach (var (firstChunk, samples) in entries)
+ {
+ w.WriteUInt32(firstChunk);
+ w.WriteUInt32(samples);
+ w.WriteUInt32(1);
+ }
+ w.EndBox();
+ }
+
+ private void WriteSampleSizes(BoxWriter w)
+ {
+ var constant = true;
+ foreach (var s in _sizes) constant &= s == _sizes[0];
+ w.BeginFullBox("stsz", 0, 0);
+ w.WriteUInt32(constant ? _sizes[0] : 0);
+ w.WriteUInt32((uint)_sizes.Count);
+ if (!constant)
+ {
+ foreach (var s in _sizes) w.WriteUInt32(s);
+ }
+ w.EndBox();
+ }
+
+ private void WriteChunkOffsets(BoxWriter w, long delta)
+ {
+ var wide = _chunkOffsets.Count > 0 && _chunkOffsets[^1] + delta > uint.MaxValue;
+ w.BeginFullBox(wide ? "co64" : "stco", 0, 0);
+ w.WriteUInt32((uint)_chunkOffsets.Count);
+ foreach (var offset in _chunkOffsets)
+ {
+ if (wide) w.WriteUInt64((ulong)(offset + delta));
+ else w.WriteUInt32((uint)(offset + delta));
+ }
+ w.EndBox();
+ }
+}
diff --git a/src/Titano.Core/Video/Mp4Inspector.cs b/src/Titano.Core/Video/Mp4Inspector.cs
new file mode 100644
index 00000000..1edfa8c7
--- /dev/null
+++ b/src/Titano.Core/Video/Mp4Inspector.cs
@@ -0,0 +1,683 @@
+using System.Buffers.Binary;
+using System.Globalization;
+using System.Text;
+using Titano.Core.Video.Bitstream;
+using Titano.Core.Video.Mp4;
+
+namespace Titano.Core.Video;
+
+/// One ISO-BMFF box of an inspected file.
+public sealed record Mp4Box(string Type, long Offset, long Size, int HeaderSize, IReadOnlyList Children)
+{
+ /// Payload bytes (only kept for boxes inside moov).
+ internal ReadOnlyMemory Payload { get; init; }
+
+ public Mp4Box? Child(string type)
+ {
+ foreach (var c in Children)
+ {
+ if (c.Type == type) return c;
+ }
+ return null;
+ }
+}
+
+/// One sample of the inspected video track, in decode order.
+public readonly record struct Mp4SampleInfo(long Offset, int Size, long DecodeTime, uint Duration, long CompositionOffset, bool IsSync);
+
+/// Result of : structure, stream properties and problems found.
+public sealed class Mp4Report
+{
+ public List Errors { get; } = [];
+ public List Warnings { get; } = [];
+ public bool IsValid => Errors.Count == 0;
+ public IReadOnlyList Boxes { get; internal set; } = [];
+
+ /// Sample entry four-character code ("avc1", "hvc1", "av01"…).
+ public string? SampleEntry { get; internal set; }
+
+ public VideoCodec? Codec { get; internal set; }
+
+ /// RFC 6381 codec string, e.g. "avc1.640029".
+ public string? CodecString { get; internal set; }
+
+ /// Coded picture size from the sample entry.
+ public int Width { get; internal set; }
+
+ public int Height { get; internal set; }
+ public int BitDepth { get; internal set; }
+ public int FrameCount { get; internal set; }
+ public int SyncSampleCount { get; internal set; }
+ public uint TimeScale { get; internal set; }
+
+ /// Presentation duration in ticks (edit list applied).
+ public long DurationTicks { get; internal set; }
+
+ public TimeSpan Duration => TimeScale == 0 ? TimeSpan.Zero : TimeSpan.FromSeconds(DurationTicks / (double)TimeScale);
+ public long MediaBytes { get; internal set; }
+
+ /// Average bit rate in bits per second.
+ public double AverageBitrate { get; internal set; }
+
+ /// moov precedes mdat (progressive download).
+ public bool FastStart { get; internal set; }
+
+ public bool UsesCo64 { get; internal set; }
+ public bool UsesLargeMdat { get; internal set; }
+ public bool HasCompositionOffsets { get; internal set; }
+ public bool HasEditList { get; internal set; }
+ public IReadOnlyList Samples { get; internal set; } = [];
+
+ public override string ToString()
+ {
+ var sb = new StringBuilder();
+ var inv = CultureInfo.InvariantCulture;
+ sb.AppendLine(inv, $"{CodecString ?? SampleEntry ?? "unknown"} {Width}x{Height} {BitDepth}-bit, {FrameCount} frames ({SyncSampleCount} sync), {Duration.TotalSeconds:0.###} s, {AverageBitrate / 1000:0} kbit/s");
+ sb.AppendLine(inv, $"fast start: {FastStart}, co64: {UsesCo64}, 64-bit mdat: {UsesLargeMdat}, composition offsets: {HasCompositionOffsets}, edit list: {HasEditList}");
+ foreach (var e in Errors) sb.AppendLine("error: " + e);
+ foreach (var w in Warnings) sb.AppendLine("warning: " + w);
+ return sb.ToString();
+ }
+}
+
+///
+/// Parses an MP4 into a box tree and validates the first video track: required boxes, sample-table consistency,
+/// chunk offsets inside mdat, sync start, durations, decoder configuration versus sample entry. Never throws on
+/// malformed input.
+///
+public static class Mp4Inspector
+{
+ private const int MaxDepth = 16;
+ private const int MaxBoxes = 100_000;
+ private const long MaxMoovBytes = 256L << 20;
+ private const int CheckedSamples = 4;
+
+ public static Mp4Report Inspect(string path)
+ {
+ using var stream = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read, 1 << 16, FileOptions.RandomAccess);
+ return Inspect(stream);
+ }
+
+ public static Mp4Report Inspect(Stream stream)
+ {
+ var report = new Mp4Report();
+ if (!stream.CanSeek || !stream.CanRead)
+ {
+ report.Errors.Add("stream is not readable and seekable");
+ return report;
+ }
+ try
+ {
+ Run(stream, report);
+ }
+ catch (IOException ex)
+ {
+ report.Errors.Add("read failed: " + ex.Message);
+ }
+ return report;
+ }
+
+ private static void Run(Stream stream, Mp4Report report)
+ {
+ var length = stream.Length;
+ var top = new List();
+ var mdats = new List<(long Start, long End)>();
+ Mp4Box? moov = null;
+ long pos = 0;
+ var budget = MaxBoxes;
+ Span header = stackalloc byte[16];
+ while (pos + 8 <= length && budget-- > 0)
+ {
+ stream.Position = pos;
+ var want = (int)Math.Min(16, length - pos);
+ var read = stream.ReadAtLeast(header[..want], want, throwOnEndOfStream: false);
+ long size = BinaryPrimitives.ReadUInt32BigEndian(header);
+ var type = FourCc(header[4..8]);
+ var headerSize = 8;
+ if (size == 1)
+ {
+ if (read < 16)
+ {
+ report.Errors.Add($"box '{type}' at {pos} is truncated");
+ break;
+ }
+ size = (long)Math.Min(BinaryPrimitives.ReadUInt64BigEndian(header[8..]), long.MaxValue);
+ headerSize = 16;
+ if (type == "mdat") report.UsesLargeMdat = true;
+ }
+ else if (size == 0)
+ {
+ size = length - pos;
+ }
+ if (size < headerSize)
+ {
+ report.Errors.Add($"box '{type}' at {pos} has invalid size {size}");
+ break;
+ }
+ if (size > length - pos)
+ {
+ report.Errors.Add($"box '{type}' at {pos} extends past the end of the file ({size} > {length - pos} bytes)");
+ size = length - pos;
+ }
+
+ var children = (IReadOnlyList)[];
+ if (type == "moov")
+ {
+ if (moov is not null)
+ {
+ report.Errors.Add("more than one moov box");
+ }
+ else if (size - headerSize > MaxMoovBytes)
+ {
+ report.Errors.Add($"moov is implausibly large ({size} bytes)");
+ }
+ else
+ {
+ var data = new byte[size - headerSize];
+ stream.Position = pos + headerSize;
+ stream.ReadExactly(data);
+ children = ParseBoxes(data, 0, data.Length, pos + headerSize, 1, report, ref budget);
+ }
+ }
+ var box = new Mp4Box(type, pos, size, headerSize, children);
+ if (type == "moov" && moov is null && children.Count > 0) moov = box;
+ if (type == "mdat") mdats.Add((pos + headerSize, pos + size));
+ if (type == "moof") report.Warnings.Add("fragmented MP4 (moof) is not inspected");
+ top.Add(box);
+ pos += size;
+ }
+ if (pos < length && budget > 0) report.Warnings.Add($"{length - pos} trailing bytes after the last box");
+ report.Boxes = top;
+
+ if (top.Count == 0 || top[0].Type != "ftyp")
+ {
+ if (top.Exists(b => b.Type == "ftyp")) report.Warnings.Add("ftyp is not the first box");
+ else report.Errors.Add("ftyp box missing");
+ }
+ if (mdats.Count == 0) report.Errors.Add("mdat box missing");
+ if (moov is null)
+ {
+ report.Errors.Add("moov box missing or empty");
+ return;
+ }
+ report.FastStart = mdats.Count > 0 && moov.Offset < mdats[0].Start;
+ InspectMovie(stream, moov, mdats, report);
+ }
+
+ private static List ParseBoxes(byte[] data, int start, int end, long baseOffset, int depth, Mp4Report report, ref int budget)
+ {
+ var list = new List();
+ var pos = start;
+ while (end - pos >= 8 && budget-- > 0)
+ {
+ long size = BinaryPrimitives.ReadUInt32BigEndian(data.AsSpan(pos));
+ var type = FourCc(data.AsSpan(pos + 4, 4));
+ var headerSize = 8;
+ if (size == 1)
+ {
+ if (end - pos < 16) break;
+ size = (long)Math.Min(BinaryPrimitives.ReadUInt64BigEndian(data.AsSpan(pos + 8)), long.MaxValue);
+ headerSize = 16;
+ }
+ else if (size == 0)
+ {
+ size = end - pos;
+ }
+ if (size < headerSize || size > end - pos)
+ {
+ report.Errors.Add($"box '{type}' at {baseOffset + pos} overruns its parent");
+ return list;
+ }
+ var payloadStart = pos + headerSize;
+ var boxEnd = pos + (int)size;
+ var childStart = ChildrenStart(type, payloadStart);
+ var children = childStart >= 0 && childStart <= boxEnd && depth < MaxDepth
+ ? ParseBoxes(data, childStart, boxEnd, baseOffset, depth + 1, report, ref budget)
+ : [];
+ list.Add(new Mp4Box(type, baseOffset + pos, size, headerSize, children)
+ {
+ Payload = data.AsMemory(payloadStart, boxEnd - payloadStart),
+ });
+ pos = boxEnd;
+ }
+ return list;
+ }
+
+ private static int ChildrenStart(string type, int payload) => type switch
+ {
+ "moov" or "trak" or "edts" or "mdia" or "minf" or "dinf" or "stbl" or "mvex" => payload,
+ "stsd" or "dref" => payload + 8,
+ "avc1" or "avc3" or "hvc1" or "hev1" or "av01" => payload + 78,
+ _ => -1,
+ };
+
+ private static void InspectMovie(Stream stream, Mp4Box moov, List<(long Start, long End)> mdats, Mp4Report report)
+ {
+ var mvhd = moov.Child("mvhd");
+ if (mvhd is null) report.Errors.Add("mvhd missing");
+ var movieScale = mvhd is null ? 0u : ReadTimescale(mvhd.Payload.Span, out _);
+
+ Mp4Box? trak = null;
+ foreach (var t in moov.Children)
+ {
+ if (t.Type == "trak" && Handler(t) == "vide")
+ {
+ trak = t;
+ break;
+ }
+ }
+ if (trak is null)
+ {
+ report.Errors.Add("no video track (trak with hdlr 'vide')");
+ return;
+ }
+ if (trak.Child("tkhd") is null) report.Errors.Add("tkhd missing");
+ var mdia = trak.Child("mdia");
+ var mdhd = mdia?.Child("mdhd");
+ var minf = mdia?.Child("minf");
+ var stbl = minf?.Child("stbl");
+ if (mdhd is null) report.Errors.Add("mdhd missing");
+ if (minf?.Child("vmhd") is null) report.Errors.Add("vmhd missing");
+ if (minf?.Child("dinf")?.Child("dref") is null) report.Errors.Add("dinf/dref missing");
+ if (stbl is null)
+ {
+ report.Errors.Add("stbl missing");
+ return;
+ }
+ long mdhdDuration = 0;
+ var mediaScale = mdhd is null ? 0u : ReadTimescale(mdhd.Payload.Span, out mdhdDuration);
+ if (mdhd is not null && mediaScale == 0) report.Errors.Add("mdhd timescale is zero");
+ report.TimeScale = mediaScale;
+
+ var config = InspectSampleDescription(stbl, report);
+ var durations = ReadTimeToSample(stbl, report);
+ var sizes = ReadSampleSizes(stbl, report);
+ var chunkOffsets = ReadChunkOffsets(stbl, report);
+ var samplesPerChunk = ReadSampleToChunk(stbl, chunkOffsets?.Length ?? 0, report);
+ if (durations is null || sizes is null || chunkOffsets is null || samplesPerChunk is null) return;
+
+ long stscTotal = 0;
+ foreach (var n in samplesPerChunk) stscTotal += n;
+ if (durations.Length != sizes.Length) report.Errors.Add($"stts covers {durations.Length} samples, stsz has {sizes.Length}");
+ if (stscTotal != sizes.Length) report.Errors.Add($"stsc/stco map {stscTotal} samples, stsz has {sizes.Length}");
+ var count = sizes.Length;
+ report.FrameCount = count;
+ if (count == 0)
+ {
+ report.Errors.Add("track has no samples");
+ return;
+ }
+
+ var offsets = ReadCompositionOffsets(stbl, count, report);
+ var sync = ReadSyncSamples(stbl, count, report);
+ report.SyncSampleCount = sync?.Count ?? count;
+ if (sync is not null && (sync.Count == 0 || sync[0] != 1)) report.Errors.Add("first sample is not a sync sample");
+
+ var samples = new Mp4SampleInfo[count];
+ var index = 0;
+ long decode = 0, bytes = 0;
+ var syncIndex = 0;
+ for (var c = 0; c < chunkOffsets.Length && index < count; c++)
+ {
+ var offset = chunkOffsets[c];
+ var chunkStart = offset;
+ for (var s = 0; s < samplesPerChunk[c] && index < count; s++, index++)
+ {
+ var isSync = sync is null || (syncIndex < sync.Count && sync[syncIndex] == index + 1);
+ if (isSync && sync is not null) syncIndex++;
+ var duration = index < durations.Length ? durations[index] : 0u;
+ samples[index] = new Mp4SampleInfo(offset, (int)Math.Min(sizes[index], int.MaxValue), decode, duration, offsets?[index] ?? 0, isSync);
+ offset += sizes[index];
+ decode += duration;
+ bytes += sizes[index];
+ }
+ if (!InsideMdat(chunkStart, offset, mdats)) report.Errors.Add($"chunk {c + 1} [{chunkStart}, {offset}) lies outside mdat");
+ }
+ report.Samples = samples;
+ report.MediaBytes = bytes;
+
+ for (var i = 0; i < durations.Length; i++)
+ {
+ if (durations[i] != 0) continue;
+ if (i == durations.Length - 1) report.Warnings.Add("last sample has zero duration");
+ else report.Errors.Add($"sample {i + 1} has zero duration");
+ }
+ if (mdhd is not null && mdhdDuration != decode) report.Warnings.Add($"mdhd duration {mdhdDuration} differs from the sample durations sum {decode}");
+
+ report.DurationTicks = decode;
+ var elst = trak.Child("edts")?.Child("elst");
+ if (elst is not null && ReadEditList(elst.Payload.Span, out var segment, out var mediaTime, report))
+ {
+ report.HasEditList = true;
+ if (mediaTime < 0 || (mediaTime >= decode && decode > 0)) report.Errors.Add($"edit list media_time {mediaTime} outside the media");
+ if (movieScale > 0) report.DurationTicks = (long)Math.Round(segment * (double)mediaScale / movieScale);
+ }
+ var seconds = mediaScale == 0 ? 0 : report.DurationTicks / (double)mediaScale;
+ report.AverageBitrate = seconds > 0 ? bytes * 8 / seconds : 0;
+
+ if (config is not null) CheckSamplePayloads(stream, samples, config.Codec, report);
+ }
+
+ private static DecoderConfiguration? InspectSampleDescription(Mp4Box stbl, Mp4Report report)
+ {
+ var stsd = stbl.Child("stsd");
+ if (stsd is null || stsd.Children.Count == 0)
+ {
+ report.Errors.Add("stsd missing or empty");
+ return null;
+ }
+ var entry = stsd.Children[0];
+ report.SampleEntry = entry.Type;
+ var payload = entry.Payload.Span;
+ if (payload.Length < 78)
+ {
+ report.Errors.Add($"sample entry '{entry.Type}' truncated");
+ return null;
+ }
+ report.Width = BinaryPrimitives.ReadUInt16BigEndian(payload[24..]);
+ report.Height = BinaryPrimitives.ReadUInt16BigEndian(payload[26..]);
+ var configBox = entry.Type switch
+ {
+ "avc1" or "avc3" => "avcC",
+ "hvc1" or "hev1" => "hvcC",
+ "av01" => "av1C",
+ _ => null,
+ };
+ if (configBox is null)
+ {
+ report.Warnings.Add($"sample entry '{entry.Type}' is not validated");
+ return null;
+ }
+ var box = entry.Child(configBox);
+ if (box is null)
+ {
+ report.Errors.Add($"{configBox} missing in '{entry.Type}'");
+ return null;
+ }
+ if (!DecoderConfiguration.TryParse(configBox, box.Payload.Span, out var config, out var error) || config is null)
+ {
+ report.Errors.Add($"{configBox} unparseable: {error}");
+ return null;
+ }
+ if (error is not null) report.Errors.Add(error);
+ report.Codec = config.Codec;
+ report.CodecString = config.CodecString;
+ report.BitDepth = config.BitDepth;
+ if (config.Width != report.Width || config.Height != report.Height)
+ report.Errors.Add($"{configBox} declares {config.Width}x{config.Height}, sample entry {report.Width}x{report.Height}");
+ return config;
+ }
+
+ /// Walks the NAL length prefixes / OBU sizes of the first samples and checks the first picture is a random access point.
+ private static void CheckSamplePayloads(Stream stream, Mp4SampleInfo[] samples, VideoCodec codec, Mp4Report report)
+ {
+ var length = stream.Length;
+ for (var i = 0; i < Math.Min(CheckedSamples, samples.Length); i++)
+ {
+ var s = samples[i];
+ if (s.Size <= 0 || s.Offset + s.Size > length || s.Size > 64 << 20) continue;
+ var data = new byte[s.Size];
+ stream.Position = s.Offset;
+ stream.ReadExactly(data);
+ if (codec == VideoCodec.Av1)
+ {
+ var obus = Av1ObuParser.Split(data);
+ if (obus.Count == 0 || obus[^1].Offset + obus[^1].TotalLength != data.Length)
+ report.Errors.Add($"sample {i + 1}: OBU sizes do not cover the sample");
+ continue;
+ }
+ if (!AnnexBParser.TrySplitLengthPrefixed(data, 4, out var units))
+ {
+ report.Errors.Add($"sample {i + 1}: NAL length prefixes do not cover the sample");
+ continue;
+ }
+ if (i != 0) continue;
+ var randomAccess = false;
+ foreach (var u in units)
+ {
+ var h = data[u.Offset];
+ randomAccess |= codec == VideoCodec.H264
+ ? AnnexBParser.H264Type(h) == H264NalUnitType.IdrSlice
+ : AnnexBParser.HevcType(h) is >= HevcNalUnitType.BlaWLp and <= HevcNalUnitType.Cra;
+ }
+ if (!randomAccess) report.Warnings.Add("first sample contains no IDR/IRAP picture");
+ }
+ }
+
+ private static uint[]? ReadTimeToSample(Mp4Box stbl, Mp4Report report)
+ {
+ var box = stbl.Child("stts");
+ if (box is null)
+ {
+ report.Errors.Add("stts missing");
+ return null;
+ }
+ var p = box.Payload.Span;
+ if (!Entries(p, 8, report, "stts", out var entries)) return null;
+ var list = new List();
+ for (var i = 0; i < entries; i++)
+ {
+ var n = BinaryPrimitives.ReadUInt32BigEndian(p[(8 + i * 8)..]);
+ var delta = BinaryPrimitives.ReadUInt32BigEndian(p[(12 + i * 8)..]);
+ if (list.Count + (long)n > 50_000_000)
+ {
+ report.Errors.Add("stts sample count implausible");
+ return null;
+ }
+ for (var k = 0; k < n; k++) list.Add(delta);
+ }
+ return [.. list];
+ }
+
+ private static long[]? ReadCompositionOffsets(Mp4Box stbl, int count, Mp4Report report)
+ {
+ var box = stbl.Child("ctts");
+ if (box is null) return null;
+ var p = box.Payload.Span;
+ if (!Entries(p, 8, report, "ctts", out var entries)) return null;
+ var signed = p[0] == 1;
+ var result = new long[count];
+ long covered = 0;
+ for (var i = 0; i < entries; i++)
+ {
+ var n = BinaryPrimitives.ReadUInt32BigEndian(p[(8 + i * 8)..]);
+ var raw = BinaryPrimitives.ReadUInt32BigEndian(p[(12 + i * 8)..]);
+ long offset = signed ? (int)raw : raw;
+ for (var k = covered; k < Math.Min(count, covered + n); k++) result[k] = offset;
+ covered += n;
+ }
+ report.HasCompositionOffsets = true;
+ if (covered != count) report.Errors.Add($"ctts covers {covered} of {count} samples");
+ return result;
+ }
+
+ private static List? ReadSyncSamples(Mp4Box stbl, int count, Mp4Report report)
+ {
+ var box = stbl.Child("stss");
+ if (box is null) return null;
+ var p = box.Payload.Span;
+ if (!Entries(p, 4, report, "stss", out var entries)) return [];
+ var list = new List(entries);
+ for (var i = 0; i < entries; i++)
+ {
+ var s = BinaryPrimitives.ReadUInt32BigEndian(p[(8 + i * 4)..]);
+ if (s == 0 || s > count || (list.Count > 0 && s <= list[^1]))
+ {
+ report.Errors.Add($"stss entry {s} out of order or range");
+ break;
+ }
+ list.Add(s);
+ }
+ return list;
+ }
+
+ private static uint[]? ReadSampleSizes(Mp4Box stbl, Mp4Report report)
+ {
+ var box = stbl.Child("stsz") ?? stbl.Child("stz2");
+ if (box is null)
+ {
+ report.Errors.Add("stsz missing");
+ return null;
+ }
+ var p = box.Payload.Span;
+ if (p.Length < 12)
+ {
+ report.Errors.Add($"{box.Type} truncated");
+ return null;
+ }
+ var count = BinaryPrimitives.ReadUInt32BigEndian(p[8..]);
+ if (count > 50_000_000)
+ {
+ report.Errors.Add($"{box.Type} sample count implausible");
+ return null;
+ }
+ var sizes = new uint[count];
+ if (box.Type == "stsz")
+ {
+ var constant = BinaryPrimitives.ReadUInt32BigEndian(p[4..]);
+ if (constant != 0)
+ {
+ Array.Fill(sizes, constant);
+ return sizes;
+ }
+ if (p.Length < 12 + count * 4L)
+ {
+ report.Errors.Add("stsz truncated");
+ return null;
+ }
+ for (var i = 0; i < count; i++) sizes[i] = BinaryPrimitives.ReadUInt32BigEndian(p[(12 + i * 4)..]);
+ return sizes;
+ }
+ var field = p[7];
+ if (field is not (4 or 8 or 16) || p.Length < 12 + (count * field + 7) / 8)
+ {
+ report.Errors.Add("stz2 invalid");
+ return null;
+ }
+ for (var i = 0; i < count; i++)
+ {
+ sizes[i] = field switch
+ {
+ 16 => BinaryPrimitives.ReadUInt16BigEndian(p[(12 + i * 2)..]),
+ 8 => p[12 + i],
+ _ => (uint)((p[12 + i / 2] >> ((i & 1) == 0 ? 4 : 0)) & 0x0F),
+ };
+ }
+ return sizes;
+ }
+
+ private static long[]? ReadChunkOffsets(Mp4Box stbl, Mp4Report report)
+ {
+ var box = stbl.Child("stco") ?? stbl.Child("co64");
+ if (box is null)
+ {
+ report.Errors.Add("stco/co64 missing");
+ return null;
+ }
+ var wide = box.Type == "co64";
+ report.UsesCo64 = wide;
+ var p = box.Payload.Span;
+ if (!Entries(p, wide ? 8 : 4, report, box.Type, out var entries)) return null;
+ var offsets = new long[entries];
+ for (var i = 0; i < entries; i++)
+ {
+ offsets[i] = wide
+ ? (long)Math.Min(BinaryPrimitives.ReadUInt64BigEndian(p[(8 + i * 8)..]), long.MaxValue)
+ : BinaryPrimitives.ReadUInt32BigEndian(p[(8 + i * 4)..]);
+ }
+ return offsets;
+ }
+
+ private static uint[]? ReadSampleToChunk(Mp4Box stbl, int chunks, Mp4Report report)
+ {
+ var box = stbl.Child("stsc");
+ if (box is null)
+ {
+ report.Errors.Add("stsc missing");
+ return null;
+ }
+ var p = box.Payload.Span;
+ if (!Entries(p, 12, report, "stsc", out var entries)) return null;
+ var perChunk = new uint[chunks];
+ for (var i = 0; i < entries; i++)
+ {
+ var first = BinaryPrimitives.ReadUInt32BigEndian(p[(8 + i * 12)..]);
+ var samples = BinaryPrimitives.ReadUInt32BigEndian(p[(12 + i * 12)..]);
+ var next = i + 1 < entries ? BinaryPrimitives.ReadUInt32BigEndian(p[(8 + (i + 1) * 12)..]) : (uint)chunks + 1;
+ if (first == 0 || next <= first || (i == 0 && first != 1))
+ {
+ report.Errors.Add("stsc first_chunk values invalid");
+ return null;
+ }
+ if (BinaryPrimitives.ReadUInt32BigEndian(p[(16 + i * 12)..]) != 1) report.Errors.Add("stsc references a sample description other than 1");
+ for (var c = first; c < next && c <= chunks; c++) perChunk[c - 1] = samples;
+ }
+ return perChunk;
+ }
+
+ private static bool ReadEditList(ReadOnlySpan p, out long segment, out long mediaTime, Mp4Report report)
+ {
+ segment = mediaTime = 0;
+ var wide = p.Length > 0 && p[0] == 1;
+ if (!Entries(p, wide ? 20 : 12, report, "elst", out var entries) || entries == 0) return false;
+ if (entries > 1) report.Warnings.Add($"edit list has {entries} entries; only the first is evaluated");
+ segment = wide ? (long)Math.Min(BinaryPrimitives.ReadUInt64BigEndian(p[8..]), long.MaxValue) : BinaryPrimitives.ReadUInt32BigEndian(p[8..]);
+ mediaTime = wide ? BinaryPrimitives.ReadInt64BigEndian(p[16..]) : BinaryPrimitives.ReadInt32BigEndian(p[12..]);
+ return true;
+ }
+
+ /// Reads entry_count of a full box and checks the table fits its payload.
+ private static bool Entries(ReadOnlySpan p, int entrySize, Mp4Report report, string type, out int entries)
+ {
+ entries = 0;
+ if (p.Length < 8)
+ {
+ report.Errors.Add($"{type} truncated");
+ return false;
+ }
+ var n = BinaryPrimitives.ReadUInt32BigEndian(p[4..]);
+ if (n > (p.Length - 8) / entrySize)
+ {
+ report.Errors.Add($"{type} declares {n} entries but holds {(p.Length - 8) / entrySize}");
+ return false;
+ }
+ entries = (int)n;
+ return true;
+ }
+
+ private static uint ReadTimescale(ReadOnlySpan p, out long duration)
+ {
+ duration = 0;
+ if (p.Length < 20) return 0;
+ if (p[0] == 1)
+ {
+ if (p.Length < 32) return 0;
+ duration = (long)Math.Min(BinaryPrimitives.ReadUInt64BigEndian(p[24..]), long.MaxValue);
+ return BinaryPrimitives.ReadUInt32BigEndian(p[20..]);
+ }
+ duration = BinaryPrimitives.ReadUInt32BigEndian(p[16..]);
+ return BinaryPrimitives.ReadUInt32BigEndian(p[12..]);
+ }
+
+ private static string? Handler(Mp4Box trak)
+ {
+ var hdlr = trak.Child("mdia")?.Child("hdlr");
+ return hdlr is null || hdlr.Payload.Length < 12 ? null : FourCc(hdlr.Payload.Span[8..12]);
+ }
+
+ private static bool InsideMdat(long start, long end, List<(long Start, long End)> mdats)
+ {
+ foreach (var (s, e) in mdats)
+ {
+ if (start >= s && end <= e) return true;
+ }
+ return false;
+ }
+
+ private static string FourCc(ReadOnlySpan bytes)
+ {
+ Span chars = stackalloc char[4];
+ for (var i = 0; i < 4; i++) chars[i] = bytes[i] is >= 0x20 and < 0x7F ? (char)bytes[i] : '?';
+ return new string(chars);
+ }
+}
diff --git a/tests/Titano.Core.Tests/Video/Mp4MuxerTests.cs b/tests/Titano.Core.Tests/Video/Mp4MuxerTests.cs
new file mode 100644
index 00000000..d505885b
--- /dev/null
+++ b/tests/Titano.Core.Tests/Video/Mp4MuxerTests.cs
@@ -0,0 +1,240 @@
+using System.Buffers.Binary;
+using Titano.Core.Video;
+using Titano.Core.Video.Bitstream;
+using Titano.Core.Video.Mp4;
+using Titano.Testing;
+
+namespace Titano.Core.Tests.Video;
+
+public sealed class Mp4MuxerTests(TestContext context)
+{
+ private static long Duration(int i) => 3000 + i % 3 * 1500;
+
+ [Test]
+ public void H264WithVariableDurationsInspectsClean()
+ {
+ using var ms = new MemoryStream();
+ var muxer = new Mp4Muxer(ms, new VideoTrackConfig { Codec = VideoCodec.H264, Width = 1920, Height = 1080 });
+ var expected = new List();
+ long total = 0;
+ for (var i = 0; i < 30; i++)
+ {
+ var idr = i % 10 == 0;
+ var slice = SyntheticStreams.H264Slice(idr, 200 + i * 7, i);
+ List nals = [SyntheticStreams.H264AccessUnitDelimiter()];
+ if (idr) nals.AddRange([SyntheticStreams.H264Sps(), SyntheticStreams.H264Pps()]);
+ nals.Add(slice);
+ var annexB = AnnexBParser.ToAnnexB(nals);
+ // Alternate input formats: the muxer accepts both.
+ muxer.WriteSample(i % 2 == 0 ? annexB : AnnexBParser.ToLengthPrefixed(annexB), Duration(i), idr);
+ expected.Add(AnnexBParser.ToLengthPrefixed(AnnexBParser.ToAnnexB([slice])));
+ total += Duration(i);
+ }
+ muxer.Complete();
+
+ var report = Mp4Inspector.Inspect(ms);
+ AssertClean(report);
+ Assert.Equal("avc1", report.SampleEntry);
+ Assert.Equal("avc1.640029", report.CodecString);
+ Assert.Equal(1920, report.Width);
+ Assert.Equal(1080, report.Height);
+ Assert.Equal(30, report.FrameCount);
+ Assert.Equal(3, report.SyncSampleCount);
+ Assert.Equal(90000u, report.TimeScale);
+ Assert.Equal(total, report.DurationTicks);
+ Assert.False(report.FastStart);
+ Assert.False(report.HasEditList);
+ for (var i = 0; i < 30; i++)
+ {
+ Assert.Equal(Duration(i), (long)report.Samples[i].Duration);
+ Assert.BytesEqual(expected[i], ReadSample(ms, report.Samples[i]));
+ }
+ }
+
+ [Test]
+ public void HevcMain10InspectsClean()
+ {
+ using var ms = new MemoryStream();
+ var muxer = new Mp4Muxer(ms, new VideoTrackConfig { Codec = VideoCodec.Hevc, Width = 3840, Height = 2160 });
+ for (var i = 0; i < 12; i++)
+ {
+ var idr = i % 6 == 0;
+ List nals = idr ? [SyntheticStreams.HevcVps(), SyntheticStreams.HevcSps(3840, 2160), SyntheticStreams.HevcPps()] : [];
+ nals.Add(SyntheticStreams.HevcSlice(idr, 500, i));
+ muxer.WriteSample(AnnexBParser.ToAnnexB(nals), 1500, idr);
+ }
+ muxer.Complete();
+ var report = Mp4Inspector.Inspect(ms);
+ AssertClean(report);
+ Assert.Equal("hvc1", report.SampleEntry);
+ Assert.Equal(VideoCodec.Hevc, report.Codec);
+ Assert.Equal("hvc1.2.4.L153.90", report.CodecString);
+ Assert.Equal(3840, report.Width);
+ Assert.Equal(2160, report.Height);
+ Assert.Equal(10, report.BitDepth);
+ Assert.Equal(12, report.FrameCount);
+ Assert.Equal(18000L, report.DurationTicks);
+ Assert.Approximately(0.2, report.Duration.TotalSeconds, 1e-9);
+ }
+
+ [Test]
+ public void Av1InspectsCleanAndGetsSizeFields()
+ {
+ using var ms = new MemoryStream();
+ var muxer = new Mp4Muxer(ms, new VideoTrackConfig { Codec = VideoCodec.Av1, Width = 1280, Height = 720 });
+ for (var i = 0; i < 10; i++)
+ {
+ var key = i == 0;
+ var frame = SyntheticStreams.Random(300, i);
+ // Last OBU of the temporal unit without obu_size, as encoders may emit it.
+ byte[] lastWithoutSize = [(byte)Av1ObuType.Frame << 3, .. frame];
+ var tu = key
+ ? SyntheticStreams.Concat(SyntheticStreams.Av1TemporalDelimiter(), SyntheticStreams.Av1SequenceHeaderObu(1280, 720, 5), lastWithoutSize)
+ : SyntheticStreams.Concat(SyntheticStreams.Av1TemporalDelimiter(), lastWithoutSize);
+ muxer.WriteSample(tu, 3003, key);
+ }
+ muxer.Complete();
+ var report = Mp4Inspector.Inspect(ms);
+ AssertClean(report);
+ Assert.Equal("av01", report.SampleEntry);
+ Assert.Equal("av01.0.05M.08", report.CodecString);
+ Assert.Equal(1280, report.Width);
+ Assert.Equal(720, report.Height);
+ Assert.Equal(10, report.FrameCount);
+ Assert.Equal(1, report.SyncSampleCount);
+ var second = ReadSample(ms, report.Samples[1]);
+ Assert.True(Av1ObuParser.TryReadObu(second, 0, out var obu));
+ Assert.True(obu.HasSizeField);
+ Assert.Equal(Av1ObuType.Frame, obu.Type);
+ Assert.Equal(second.Length, obu.TotalLength);
+ }
+
+ [Test]
+ public void FastStartMovesMoovAndKeepsOffsetsValid()
+ {
+ var path = Path.Combine(context.CreateTempDirectory(), "fast.mp4");
+ var expected = new List();
+ using (var fs = new FileStream(path, FileMode.CreateNew, FileAccess.ReadWrite))
+ {
+ var muxer = new Mp4Muxer(fs, new VideoTrackConfig { Codec = VideoCodec.H264, Width = 1280, Height = 720, FastStart = true });
+ for (var i = 0; i < 90; i++)
+ {
+ var idr = i % 30 == 0;
+ var slice = SyntheticStreams.H264Slice(idr, 4000 + i, i);
+ List nals = idr ? [SyntheticStreams.H264Sps(1280, 720, 77, 31), SyntheticStreams.H264Pps(), slice] : [slice];
+ muxer.WriteSample(AnnexBParser.ToAnnexB(nals), 3000, idr);
+ expected.Add(AnnexBParser.ToLengthPrefixed(AnnexBParser.ToAnnexB([slice])));
+ }
+ muxer.Complete();
+ }
+ var report = Mp4Inspector.Inspect(path);
+ AssertClean(report);
+ Assert.True(report.FastStart);
+ Assert.SequenceEqual(["ftyp", "moov", "free", "mdat"], report.Boxes.Select(b => b.Type));
+ Assert.Equal(new FileInfo(path).Length, report.Boxes.Sum(b => b.Size));
+ using var read = File.OpenRead(path);
+ for (var i = 0; i < expected.Count; i++) Assert.BytesEqual(expected[i], ReadSample(read, report.Samples[i]));
+ }
+
+ [Test]
+ public void CompositionOffsetsProduceCttsAndEditList()
+ {
+ // Decode order I0 P3 B1 B2 P6 B4 B5 with unit durations of 3000 ticks; encoder gives PTS − DTS.
+ int[] pts = [0, 3, 1, 2, 6, 4, 5];
+ using var ms = new MemoryStream();
+ var muxer = new Mp4Muxer(ms, new VideoTrackConfig { Codec = VideoCodec.H264, Width = 1920, Height = 1080 });
+ for (var i = 0; i < pts.Length; i++)
+ {
+ List nals = i == 0 ? [SyntheticStreams.H264Sps(), SyntheticStreams.H264Pps()] : [];
+ nals.Add(SyntheticStreams.H264Slice(i == 0, 100, i));
+ muxer.WriteSample(AnnexBParser.ToAnnexB(nals), 3000, i == 0, (pts[i] - i) * 3000L);
+ }
+ muxer.Complete();
+ var report = Mp4Inspector.Inspect(ms);
+ AssertClean(report);
+ Assert.True(report.HasCompositionOffsets);
+ Assert.True(report.HasEditList);
+ Assert.Equal(7 * 3000L, report.DurationTicks);
+ // After the shift every composition time is non-negative and I0 presents first.
+ var cts = report.Samples.Select(s => s.DecodeTime + s.CompositionOffset).ToArray();
+ Assert.Equal(cts.Min(), cts[0]);
+ Assert.True(report.Samples.All(s => s.CompositionOffset >= 0));
+ }
+
+ [Test]
+ public void LargeFilesUseCo64AndLargeMdat()
+ {
+ const int sampleSize = 1 << 20;
+ const int samples = 4200; // ≈ 4.4 GB of payload, dropped by the sparse stream
+ var slice = new byte[sampleSize];
+ BinaryPrimitives.WriteInt32BigEndian(slice, sampleSize - 4);
+ slice[4] = 0x41; // non-IDR slice header
+ var first = SyntheticStreams.Concat(
+ AnnexBParser.ToLengthPrefixed(AnnexBParser.ToAnnexB([SyntheticStreams.H264Sps(), SyntheticStreams.H264Pps()])), slice);
+ first[first.Length - sampleSize + 4] = 0x65;
+
+ using var sparse = new SparseStream();
+ var muxer = new Mp4Muxer(sparse, new VideoTrackConfig { Codec = VideoCodec.H264, Width = 1920, Height = 1080 });
+ muxer.WriteSample(first, 3000, true);
+ for (var i = 1; i < samples; i++) muxer.WriteSample(slice, 3000, i % 60 == 0);
+ muxer.Complete();
+
+ var report = Mp4Inspector.Inspect(sparse);
+ AssertClean(report);
+ Assert.True(report.UsesCo64);
+ Assert.True(report.UsesLargeMdat);
+ Assert.Equal(samples, report.FrameCount);
+ Assert.Greater(report.Samples[^1].Offset, uint.MaxValue);
+ Assert.Equal((long)sampleSize * samples, report.MediaBytes);
+ }
+
+ [Test]
+ public void CompleteWithoutParameterSetsThrows()
+ {
+ using var ms = new MemoryStream();
+ var muxer = new Mp4Muxer(ms, new VideoTrackConfig { Codec = VideoCodec.H264, Width = 64, Height = 64 });
+ muxer.WriteSample(AnnexBParser.ToAnnexB([SyntheticStreams.H264Slice(true, 10, 1)]), 3000, true);
+ Assert.Throws(muxer.Complete);
+ Assert.Throws(() => muxer.WriteSample([0, 0, 1, 0x65, 1], 0, true));
+ }
+
+ [Test]
+ public void InspectorSurvivesTruncationAndCorruption()
+ {
+ using var ms = new MemoryStream();
+ var muxer = new Mp4Muxer(ms, new VideoTrackConfig { Codec = VideoCodec.H264, Width = 1920, Height = 1080 });
+ for (var i = 0; i < 5; i++)
+ {
+ List nals = i == 0 ? [SyntheticStreams.H264Sps(), SyntheticStreams.H264Pps()] : [];
+ nals.Add(SyntheticStreams.H264Slice(i == 0, 50, i));
+ muxer.WriteSample(AnnexBParser.ToAnnexB(nals), 3000, i == 0);
+ }
+ muxer.Complete();
+ var valid = ms.ToArray();
+ for (var cut = 0; cut < valid.Length; cut += 7)
+ {
+ var report = Mp4Inspector.Inspect(new MemoryStream(valid, 0, cut));
+ Assert.False(report.IsValid, $"truncated at {cut} should not validate");
+ }
+ var rng = new Random(11);
+ for (var trial = 0; trial < 500; trial++)
+ {
+ var corrupt = (byte[])valid.Clone();
+ for (var k = 0; k < 3; k++) corrupt[rng.Next(corrupt.Length)] = (byte)rng.Next(256);
+ Mp4Inspector.Inspect(new MemoryStream(corrupt)).ToString();
+ }
+ }
+
+ private static void AssertClean(Mp4Report report)
+ {
+ if (!report.IsValid) Assert.Fail("Inspector errors: " + string.Join("; ", report.Errors));
+ }
+
+ private static byte[] ReadSample(Stream stream, Mp4SampleInfo sample)
+ {
+ var data = new byte[sample.Size];
+ stream.Position = sample.Offset;
+ stream.ReadExactly(data);
+ return data;
+ }
+}
diff --git a/tests/Titano.Core.Tests/Video/SparseStream.cs b/tests/Titano.Core.Tests/Video/SparseStream.cs
new file mode 100644
index 00000000..d470d960
--- /dev/null
+++ b/tests/Titano.Core.Tests/Video/SparseStream.cs
@@ -0,0 +1,76 @@
+namespace Titano.Core.Tests.Video;
+
+///
+/// A seekable stream that keeps small writes (headers, length prefixes, moov) and drops large payload writes,
+/// which read back as zeros. Lets tests produce multi-gigabyte container layouts without the bytes.
+///
+internal sealed class SparseStream : Stream
+{
+ private const int PageSize = 1024;
+ private const int LargeWrite = 64 * 1024;
+ private readonly Dictionary _pages = [];
+ private long _length;
+ private long _position;
+
+ public override bool CanRead => true;
+ public override bool CanSeek => true;
+ public override bool CanWrite => true;
+ public override long Length => _length;
+
+ public override long Position
+ {
+ get => _position;
+ set => _position = value;
+ }
+
+ public override void Flush()
+ {
+ }
+
+ public override long Seek(long offset, SeekOrigin origin) => _position = origin switch
+ {
+ SeekOrigin.Begin => offset,
+ SeekOrigin.Current => _position + offset,
+ _ => _length + offset,
+ };
+
+ public override void SetLength(long value) => _length = value;
+
+ public override int Read(byte[] buffer, int offset, int count) => Read(buffer.AsSpan(offset, count));
+
+ public override int Read(Span buffer)
+ {
+ var n = (int)Math.Clamp(_length - _position, 0, buffer.Length);
+ for (var i = 0; i < n;)
+ {
+ var at = _position + i;
+ var inPage = (int)(at % PageSize);
+ var chunk = Math.Min(n - i, PageSize - inPage);
+ if (_pages.TryGetValue(at / PageSize, out var page)) page.AsSpan(inPage, chunk).CopyTo(buffer.Slice(i, chunk));
+ else buffer.Slice(i, chunk).Clear();
+ i += chunk;
+ }
+ _position += n;
+ return n;
+ }
+
+ public override void Write(byte[] buffer, int offset, int count) => Write(buffer.AsSpan(offset, count));
+
+ public override void Write(ReadOnlySpan buffer)
+ {
+ if (buffer.Length < LargeWrite)
+ {
+ for (var i = 0; i < buffer.Length;)
+ {
+ var at = _position + i;
+ var inPage = (int)(at % PageSize);
+ var chunk = Math.Min(buffer.Length - i, PageSize - inPage);
+ if (!_pages.TryGetValue(at / PageSize, out var page)) _pages[at / PageSize] = page = new byte[PageSize];
+ buffer.Slice(i, chunk).CopyTo(page.AsSpan(inPage, chunk));
+ i += chunk;
+ }
+ }
+ _position += buffer.Length;
+ _length = Math.Max(_length, _position);
+ }
+}