From e15bbb997410e0d7b75fd56e0eb881bfd14cce8f Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 09:41:34 +0000 Subject: [PATCH] feat(video): add AVI MJPEG writer with idx1 and OpenDML indexes Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC --- src/Titano.Core/Video/Avi/AviMjpegWriter.cs | 312 ++++++++++++++++++ .../Video/AviMjpegWriterTests.cs | 205 ++++++++++++ 2 files changed, 517 insertions(+) create mode 100644 src/Titano.Core/Video/Avi/AviMjpegWriter.cs create mode 100644 tests/Titano.Core.Tests/Video/AviMjpegWriterTests.cs diff --git a/src/Titano.Core/Video/Avi/AviMjpegWriter.cs b/src/Titano.Core/Video/Avi/AviMjpegWriter.cs new file mode 100644 index 00000000..1e42fb5b --- /dev/null +++ b/src/Titano.Core/Video/Avi/AviMjpegWriter.cs @@ -0,0 +1,312 @@ +using System.Buffers.Binary; + +namespace Titano.Core.Video.Avi; + +/// +/// Streaming RIFF AVI writer for already-encoded JPEG frames ('MJPG', chunks '00dc'). Writes the legacy idx1 index +/// for the first RIFF and OpenDML indexes ('indx' super index, one 'ix00' per RIFF) so files can continue in +/// 'AVIX' RIFF lists past the per-RIFF size limit. AVI is constant frame rate: repeat a frame to hold it longer. +/// The output stream must be seekable and is not disposed. +/// +public sealed class AviMjpegWriter +{ + /// Default size of each RIFF list; 1 GiB keeps the first RIFF readable by AVI 1.0 software. + public const long DefaultRiffSizeLimit = 1L << 30; + + private const int SuperIndexCapacity = 256; + private const uint KeyFrameFlag = 0x10; // AVIIF_KEYFRAME + private static readonly uint ChunkId = FourCc("00dc"); + + private readonly Stream _stream; + private readonly int _width; + private readonly int _height; + private readonly uint _rate; + private readonly uint _scale; + private readonly long _riffLimit; + private readonly long _start; + private readonly List<(long Offset, uint Size, uint Frames)> _superIndex = []; + private readonly List<(long DataOffset, uint Size)> _segmentFrames = []; + private long _avih, _strh, _indx, _dmlh; + private long _riffStart, _moviStart, _position; + private int _framesInFirstRiff; + private int _totalFrames; + private uint _maxFrame; + private bool _completed; + + /// Bytes per RIFF list before an 'AVIX' list starts (tests use small values). + public AviMjpegWriter(Stream output, int width, int height, Rational frameRate, long riffSizeLimit = DefaultRiffSizeLimit) + { + ArgumentNullException.ThrowIfNull(output); + if (!output.CanSeek || !output.CanWrite) throw new ArgumentException("The output stream must be writable and seekable", nameof(output)); + ArgumentOutOfRangeException.ThrowIfNegativeOrZero(width); + ArgumentOutOfRangeException.ThrowIfNegativeOrZero(height); + if (frameRate.Numerator <= 0 || frameRate.Denominator <= 0) throw new ArgumentOutOfRangeException(nameof(frameRate)); + ArgumentOutOfRangeException.ThrowIfLessThan(riffSizeLimit, 16 * 1024); + ArgumentOutOfRangeException.ThrowIfGreaterThan(riffSizeLimit, uint.MaxValue); + _stream = output; + _width = width; + _height = height; + var g = Gcd(frameRate.Numerator, frameRate.Denominator); + _rate = (uint)(frameRate.Numerator / g); + _scale = (uint)(frameRate.Denominator / g); + _riffLimit = riffSizeLimit; + _start = output.Position; + WriteHeaders(); + } + + public int FrameCount => _totalFrames; + + /// Appends one JPEG (SOI-prefixed) frame. + public void WriteFrame(ReadOnlySpan jpeg) + { + if (_completed) throw new InvalidOperationException("The writer is complete"); + if (jpeg.Length < 4 || jpeg[0] != 0xFF || jpeg[1] != 0xD8) throw new ArgumentException("Not a JPEG frame", nameof(jpeg)); + var chunk = 8L + jpeg.Length + (jpeg.Length & 1); + if (_segmentFrames.Count > 0 && _position - _riffStart + chunk + IndexOverhead(_segmentFrames.Count + 1) > _riffLimit) + { + CloseSegment(); + OpenSegment("AVIX"); + } + + Span header = stackalloc byte[8]; + BinaryPrimitives.WriteUInt32LittleEndian(header, ChunkId); + BinaryPrimitives.WriteUInt32LittleEndian(header[4..], (uint)jpeg.Length); + _stream.Write(header); + _stream.Write(jpeg); + if ((jpeg.Length & 1) != 0) _stream.WriteByte(0); + _segmentFrames.Add((_position + 8, (uint)jpeg.Length)); + _position += chunk; + _maxFrame = Math.Max(_maxFrame, (uint)jpeg.Length); + _totalFrames++; + } + + /// Writes the indexes, patches sizes and frame counts, and flushes. + public void Complete() + { + if (_completed) throw new InvalidOperationException("The writer is already complete"); + CloseSegment(); + var buffer = _maxFrame + 8; + var bytesPerSecond = (uint)Math.Min(uint.MaxValue, (double)_maxFrame * _rate / _scale); + Patch(_avih + 4, bytesPerSecond); + Patch(_avih + 16, (uint)_framesInFirstRiff); + Patch(_avih + 28, buffer); + Patch(_strh + 32, (uint)_totalFrames); + Patch(_strh + 36, buffer); + Patch(_dmlh, (uint)_totalFrames); + Patch(_indx + 4, (uint)_superIndex.Count); + Span entry = stackalloc byte[16]; + for (var i = 0; i < _superIndex.Count; i++) + { + BinaryPrimitives.WriteInt64LittleEndian(entry, _superIndex[i].Offset); + BinaryPrimitives.WriteUInt32LittleEndian(entry[8..], _superIndex[i].Size); + BinaryPrimitives.WriteUInt32LittleEndian(entry[12..], _superIndex[i].Frames); + _stream.Position = _indx + 24 + i * 16; + _stream.Write(entry); + } + _stream.Position = _position; + _stream.Flush(); + _completed = true; + } + + /// Bytes the segment's ix00 (and idx1 in the first RIFF) will need for frames. + private long IndexOverhead(int frames) => 32 + 8L * frames + (_superIndex.Count == 0 ? 8 + 16L * frames : 0); + + private void WriteHeaders() + { + var h = new List(4800); + var riff = Begin(h, "RIFF", "AVI "); + var hdrl = Begin(h, "LIST", "hdrl"); + + _avih = ChunkStart(h, "avih", 56); + Add32(h, (uint)Math.Round(1_000_000.0 * _scale / _rate)); // dwMicroSecPerFrame + Add32(h, 0); // dwMaxBytesPerSec (patched) + Add32(h, 0); // dwPaddingGranularity + Add32(h, 0x10 | 0x100); // AVIF_HASINDEX | AVIF_ISINTERLEAVED + Add32(h, 0); // dwTotalFrames of the first RIFF (patched) + Add32(h, 0); // dwInitialFrames + Add32(h, 1); // dwStreams + Add32(h, 0); // dwSuggestedBufferSize (patched) + Add32(h, (uint)_width); + Add32(h, (uint)_height); + AddZeros(h, 16); + + var strl = Begin(h, "LIST", "strl"); + _strh = ChunkStart(h, "strh", 56); + Add32(h, FourCc("vids")); + Add32(h, FourCc("MJPG")); + Add32(h, 0); // dwFlags + Add32(h, 0); // wPriority, wLanguage + Add32(h, 0); // dwInitialFrames + Add32(h, _scale); + Add32(h, _rate); + Add32(h, 0); // dwStart + Add32(h, 0); // dwLength (patched) + Add32(h, 0); // dwSuggestedBufferSize (patched) + Add32(h, uint.MaxValue); // dwQuality: default + Add32(h, 0); // dwSampleSize: variable + Add16(h, 0); + Add16(h, 0); + Add16(h, (ushort)Math.Min(_width, short.MaxValue)); + Add16(h, (ushort)Math.Min(_height, short.MaxValue)); + + ChunkStart(h, "strf", 40); + Add32(h, 40); // BITMAPINFOHEADER.biSize + Add32(h, (uint)_width); + Add32(h, (uint)_height); + Add16(h, 1); // biPlanes + Add16(h, 24); // biBitCount + Add32(h, FourCc("MJPG")); + Add32(h, (uint)Math.Min(uint.MaxValue, (long)_width * _height * 3)); + AddZeros(h, 16); + + _indx = ChunkStart(h, "indx", 24 + 16 * SuperIndexCapacity); + Add16(h, 4); // wLongsPerEntry + h.Add(0); // bIndexSubType + h.Add(0); // bIndexType = AVI_INDEX_OF_INDEXES + Add32(h, 0); // nEntriesInUse (patched) + Add32(h, ChunkId); + AddZeros(h, 12 + 16 * SuperIndexCapacity); + End(h, strl); + + var odml = Begin(h, "LIST", "odml"); + _dmlh = ChunkStart(h, "dmlh", 248); + AddZeros(h, 248); + End(h, odml); + End(h, hdrl); + + // The RIFF size is patched when the first segment closes; the movi list follows directly. + _riffStart = _start + riff; + _stream.Write(h.ToArray()); + _avih += _start; + _strh += _start; + _indx += _start; + _dmlh += _start; + _position = _start + h.Count; + OpenMovi(); + } + + private void OpenSegment(string type) + { + _riffStart = _position; + Span header = stackalloc byte[12]; + BinaryPrimitives.WriteUInt32LittleEndian(header, FourCc("RIFF")); + BinaryPrimitives.WriteUInt32LittleEndian(header[8..], FourCc(type)); + _stream.Write(header); + _position += 12; + OpenMovi(); + } + + private void OpenMovi() + { + Span header = stackalloc byte[12]; + BinaryPrimitives.WriteUInt32LittleEndian(header, FourCc("LIST")); + BinaryPrimitives.WriteUInt32LittleEndian(header[8..], FourCc("movi")); + _stream.Write(header); + _moviStart = _position + 8; // offsets in idx1 and ix00 are relative to the 'movi' four-cc + _position += 12; + } + + private void CloseSegment() + { + if (_superIndex.Count == SuperIndexCapacity) throw new InvalidOperationException("AVI super index is full"); + var frames = _segmentFrames.Count; + + // Standard index (OpenDML ix00) closes the movi list. + var ixOffset = _position; + var ix = new byte[32 + 8 * frames]; + BinaryPrimitives.WriteUInt32LittleEndian(ix, FourCc("ix00")); + BinaryPrimitives.WriteUInt32LittleEndian(ix.AsSpan(4), (uint)(ix.Length - 8)); + BinaryPrimitives.WriteUInt16LittleEndian(ix.AsSpan(8), 2); // wLongsPerEntry + ix[11] = 1; // AVI_INDEX_OF_CHUNKS + BinaryPrimitives.WriteUInt32LittleEndian(ix.AsSpan(12), (uint)frames); + BinaryPrimitives.WriteUInt32LittleEndian(ix.AsSpan(16), ChunkId); + BinaryPrimitives.WriteInt64LittleEndian(ix.AsSpan(20), _moviStart); + for (var i = 0; i < frames; i++) + { + BinaryPrimitives.WriteUInt32LittleEndian(ix.AsSpan(32 + i * 8), (uint)(_segmentFrames[i].DataOffset - _moviStart)); + BinaryPrimitives.WriteUInt32LittleEndian(ix.AsSpan(36 + i * 8), _segmentFrames[i].Size); // bit 31 clear: key frame + } + _stream.Position = ixOffset; + _stream.Write(ix); + _position += ix.Length; + Patch(_moviStart - 4, (uint)(_position - _moviStart)); + + if (_superIndex.Count == 0) + { + var idx1 = new byte[8 + 16 * frames]; + BinaryPrimitives.WriteUInt32LittleEndian(idx1, FourCc("idx1")); + BinaryPrimitives.WriteUInt32LittleEndian(idx1.AsSpan(4), (uint)(idx1.Length - 8)); + for (var i = 0; i < frames; i++) + { + var e = idx1.AsSpan(8 + i * 16); + BinaryPrimitives.WriteUInt32LittleEndian(e, ChunkId); + BinaryPrimitives.WriteUInt32LittleEndian(e[4..], KeyFrameFlag); + BinaryPrimitives.WriteUInt32LittleEndian(e[8..], (uint)(_segmentFrames[i].DataOffset - 8 - _moviStart)); + BinaryPrimitives.WriteUInt32LittleEndian(e[12..], _segmentFrames[i].Size); + } + _stream.Position = _position; + _stream.Write(idx1); + _position += idx1.Length; + _framesInFirstRiff = frames; + } + Patch(_riffStart + 4, (uint)(_position - _riffStart - 8)); + _superIndex.Add((ixOffset, (uint)ix.Length, (uint)frames)); + _segmentFrames.Clear(); + _stream.Position = _position; + } + + private void Patch(long offset, uint value) + { + Span bytes = stackalloc byte[4]; + BinaryPrimitives.WriteUInt32LittleEndian(bytes, value); + _stream.Position = offset; + _stream.Write(bytes); + } + + private static int Begin(List h, string id, string type) + { + var start = h.Count; + Add32(h, FourCc(id)); + Add32(h, 0); + Add32(h, FourCc(type)); + return start; + } + + private static void End(List h, int start) + { + var size = (uint)(h.Count - start - 8); + for (var i = 0; i < 4; i++) h[start + 4 + i] = (byte)(size >> (8 * i)); + } + + /// Writes a chunk header and returns the offset of its data. + private static int ChunkStart(List h, string id, int size) + { + Add32(h, FourCc(id)); + Add32(h, (uint)size); + return h.Count; + } + + private static void Add16(List h, ushort v) + { + h.Add((byte)v); + h.Add((byte)(v >> 8)); + } + + private static void Add32(List h, uint v) + { + for (var i = 0; i < 4; i++) h.Add((byte)(v >> (8 * i))); + } + + private static void AddZeros(List h, int count) + { + for (var i = 0; i < count; i++) h.Add(0); + } + + private static uint FourCc(string s) => (uint)(s[0] | s[1] << 8 | s[2] << 16 | s[3] << 24); + + private static int Gcd(int a, int b) + { + while (b != 0) (a, b) = (b, a % b); + return a; + } +} diff --git a/tests/Titano.Core.Tests/Video/AviMjpegWriterTests.cs b/tests/Titano.Core.Tests/Video/AviMjpegWriterTests.cs new file mode 100644 index 00000000..47ee61f6 --- /dev/null +++ b/tests/Titano.Core.Tests/Video/AviMjpegWriterTests.cs @@ -0,0 +1,205 @@ +using System.Buffers.Binary; +using System.Text; +using Titano.Core.Video; +using Titano.Core.Video.Avi; +using Titano.Testing; + +namespace Titano.Core.Tests.Video; + +public sealed class AviMjpegWriterTests +{ + [Test] + public void SingleRiffHasHeadersIdx1AndStandardIndex() + { + var frames = Frames(10, 1); + var bytes = Write(frames, Rational.Fps2997, AviMjpegWriter.DefaultRiffSizeLimit); + var file = Riff.Parse(bytes); + Assert.Equal(bytes.Length, file.Sum(r => r.Size + 8)); + Assert.Count(1, file); + var riff = file[0]; + Assert.Equal("RIFF", riff.Id); + Assert.Equal("AVI ", riff.Type); + + var hdrl = riff.List("hdrl"); + var avih = hdrl.Chunk("avih").Data; + Assert.Equal(33367u, U32(avih, 0)); + Assert.Equal(10u, U32(avih, 16)); + Assert.Equal(1u, U32(avih, 24)); + Assert.Equal(64u, U32(avih, 32)); + Assert.Equal(48u, U32(avih, 36)); + var strl = hdrl.List("strl"); + var strh = strl.Chunk("strh").Data; + Assert.Equal("vids", Encoding.ASCII.GetString(strh, 0, 4)); + Assert.Equal("MJPG", Encoding.ASCII.GetString(strh, 4, 4)); + Assert.Equal(1001u, U32(strh, 20)); + Assert.Equal(30000u, U32(strh, 24)); + Assert.Equal(10u, U32(strh, 32)); + Assert.Equal("MJPG", Encoding.ASCII.GetString(strl.Chunk("strf").Data, 16, 4)); + Assert.Equal(10u, U32(hdrl.List("odml").Chunk("dmlh").Data, 0)); + + var movi = riff.List("movi"); + var chunks = movi.Children.Where(c => c.Id == "00dc").ToList(); + Assert.Equal(10, chunks.Count); + for (var i = 0; i < 10; i++) + { + Assert.BytesEqual(frames[i], chunks[i].Data); + Assert.Equal(0L, chunks[i].Offset % 2, "chunks stay word aligned after odd frames"); + } + + var idx1 = riff.Chunk("idx1").Data; + Assert.Equal(160, idx1.Length); + for (var i = 0; i < 10; i++) + { + Assert.Equal("00dc", Encoding.ASCII.GetString(idx1, i * 16, 4)); + Assert.Equal(0x10u, U32(idx1, i * 16 + 4)); + Assert.Equal(chunks[i].Offset, movi.TypeOffset + U32(idx1, i * 16 + 8)); + Assert.Equal((uint)frames[i].Length, U32(idx1, i * 16 + 12)); + } + AssertOpenDmlIndex(bytes, file, frames); + } + + [Test] + public void LargeOutputsContinueInAvixLists() + { + var frames = Frames(40, 2); + const long limit = 16 * 1024; + var bytes = Write(frames, new Rational(25, 1), limit); + var file = Riff.Parse(bytes); + Assert.Equal(bytes.Length, file.Sum(r => r.Size + 8)); + Assert.Greater(file.Count, 3); + Assert.Equal("AVI ", file[0].Type); + Assert.True(file.Skip(1).All(r => r.Type == "AVIX" && r.Children.All(c => c.Id != "idx1"))); + Assert.True(file.All(r => r.Size + 8 <= limit), "every RIFF respects the limit"); + + var first = file[0].List("movi").Children.Count(c => c.Id == "00dc"); + Assert.Equal((uint)first, U32(file[0].List("hdrl").Chunk("avih").Data, 16)); + Assert.Equal(first * 16, file[0].Chunk("idx1").Data.Length); + Assert.Equal(40u, U32(file[0].List("hdrl").List("strl").Chunk("strh").Data, 32)); + Assert.Equal(40u, U32(file[0].List("hdrl").List("odml").Chunk("dmlh").Data, 0)); + AssertOpenDmlIndex(bytes, file, frames); + } + + [Theory] + [Case(24, 1, 41667u)] + [Case(25, 1, 40000u)] + [Case(60000, 1001, 16683u)] + [Case(48, 2, 41667u)] + public void FrameRateFieldsAreExact(int numerator, int denominator, uint microseconds) + { + var bytes = Write(Frames(2, 3), new Rational(numerator, denominator), AviMjpegWriter.DefaultRiffSizeLimit); + var hdrl = Riff.Parse(bytes)[0].List("hdrl"); + Assert.Equal(microseconds, U32(hdrl.Chunk("avih").Data, 0)); + var strh = hdrl.List("strl").Chunk("strh").Data; + var g = (uint)System.Numerics.BigInteger.GreatestCommonDivisor(numerator, denominator); + Assert.Equal((uint)denominator / g, U32(strh, 20)); + Assert.Equal((uint)numerator / g, U32(strh, 24)); + } + + [Test] + public void RejectsNonJpegFrames() + { + using var ms = new MemoryStream(); + var writer = new AviMjpegWriter(ms, 64, 48, new Rational(30, 1)); + Assert.Throws(() => writer.WriteFrame([0x89, 0x50, 0x4E, 0x47])); + } + + private static void AssertOpenDmlIndex(byte[] bytes, List file, List frames) + { + var indx = file[0].List("hdrl").List("strl").Chunk("indx").Data; + Assert.Equal(4, BinaryPrimitives.ReadUInt16LittleEndian(indx)); + Assert.Equal((byte)0, indx[3]); // AVI_INDEX_OF_INDEXES + var entries = U32(indx, 4); + Assert.Equal((uint)file.Count, entries); + var frame = 0; + for (var e = 0; e < entries; e++) + { + var offset = BinaryPrimitives.ReadInt64LittleEndian(indx.AsSpan(24 + e * 16)); + var size = U32(indx, 32 + e * 16); + var duration = U32(indx, 36 + e * 16); + Assert.Equal("ix00", Encoding.ASCII.GetString(bytes, (int)offset, 4)); + Assert.Equal(size, U32(bytes, (int)offset + 4) + 8); + var ix = bytes.AsSpan((int)offset + 8); + Assert.Equal((byte)1, ix[3]); // AVI_INDEX_OF_CHUNKS + Assert.Equal(duration, U32(bytes, (int)offset + 12)); + var baseOffset = BinaryPrimitives.ReadInt64LittleEndian(ix[12..]); + for (var i = 0; i < duration; i++, frame++) + { + var dataOffset = baseOffset + U32(bytes, (int)offset + 32 + i * 8); + var length = U32(bytes, (int)offset + 36 + i * 8); + Assert.Equal(0u, length & 0x8000_0000u, "every MJPEG frame is a key frame"); + Assert.BytesEqual(frames[frame], bytes.AsSpan((int)dataOffset, (int)length)); + } + } + Assert.Equal(frames.Count, frame); + } + + private static byte[] Write(List frames, Rational rate, long limit) + { + using var ms = new MemoryStream(); + var writer = new AviMjpegWriter(ms, 64, 48, rate, limit); + foreach (var f in frames) writer.WriteFrame(f); + writer.Complete(); + Assert.Equal(frames.Count, writer.FrameCount); + return ms.ToArray(); + } + + /// JPEG-shaped payloads (SOI … EOI) of odd and even lengths. + private static List Frames(int count, int seed) + { + var rng = new Random(seed); + var list = new List(); + for (var i = 0; i < count; i++) + { + var f = new byte[1500 + rng.Next(2000)]; + rng.NextBytes(f); + f[0] = 0xFF; + f[1] = 0xD8; + f[^2] = 0xFF; + f[^1] = 0xD9; + list.Add(f); + } + return list; + } + + private static uint U32(byte[] data, int offset) => BinaryPrimitives.ReadUInt32LittleEndian(data.AsSpan(offset)); + + /// Minimal RIFF tree reader for verification. + private static class Riff + { + public sealed record Node(string Id, string? Type, long Offset, uint Size, byte[] Data, List Children) + { + /// File offset of the list type four-cc (the base of idx1 offsets). + public long TypeOffset => Offset + 8; + + public Node List(string type) => Children.Single(c => c.Type == type); + + public Node Chunk(string id) => Children.Single(c => c.Id == id); + } + + public static List Parse(byte[] bytes) => ParseRange(bytes, 0, bytes.Length); + + private static List ParseRange(byte[] bytes, long start, long end) + { + var nodes = new List(); + var pos = start; + while (pos + 8 <= end) + { + var id = Encoding.ASCII.GetString(bytes, (int)pos, 4); + var size = U32(bytes, (int)pos + 4); + Assert.True(pos + 8 + size <= end, $"chunk {id} at {pos} overruns its parent"); + if (id is "RIFF" or "LIST") + { + var type = Encoding.ASCII.GetString(bytes, (int)pos + 8, 4); + nodes.Add(new Node(id, type, pos, size, [], ParseRange(bytes, pos + 12, pos + 8 + size))); + } + else + { + nodes.Add(new Node(id, null, pos, size, bytes.AsSpan((int)pos + 8, (int)size).ToArray(), [])); + } + pos += 8 + size + (size & 1); + } + Assert.Equal(end, pos); + return nodes; + } + } +}