feature: Phase 18.1 — derive Opus 320 + seek-index sidecar at ingest

Background-job transcode (ffmpeg/libopus) after source store; pure C# Ogg walker builds the 0.5s-bucketed granule→byte seek index + captures the OpusHead/OpusTags setup header into a per-track sidecar in a new track-opus vault. Best-effort, additive, regenerated on replace-audio.
2026-06-23 06:30:10 -04:00
parent 8752fc0c98
commit 33d6f34d8a
17 changed files with 1111 additions and 0 deletions
@@ -0,0 +1,93 @@
+using System.Buffers.Binary;
+
+namespace DeepDrftContent.Processors.Opus;
+
+/// <summary>
+/// A single seek-index entry: an authoritative 48 kHz <see cref="GranulePosition"/> (Opus granule
+/// positions are always sample counts at 48 kHz, so time = granulepos / 48000) paired with the exact
+/// byte offset of the Ogg page that carries it. Every <see cref="ByteOffset"/> is a real page-start
+/// boundary, so a <c>Range: bytes={ByteOffset}-</c> fetch lands the decoder Ogg-sync-aligned.
+/// </summary>
+/// <param name="GranulePosition">The page's end granule position (48 kHz sample count).</param>
+/// <param name="ByteOffset">The byte offset of the page start in the Opus file.</param>
+public readonly record struct OpusSeekPoint(ulong GranulePosition, ulong ByteOffset)
+{
+    /// <summary>Time in seconds this granule position represents (granulepos / 48 kHz).</summary>
+    public double TimeSeconds => GranulePosition / OggOpusConstants.OpusSampleRate;
+}
+
+/// <summary>
+/// The accurate, precomputed transfer function from seek-time to true file byte offset for one Ogg
+/// Opus stream (§3.4a A). Built once at transcode time by walking the encoded stream; the client reads
+/// it back and binary-searches <see cref="Points"/> instead of doing inaccurate VBR byte-rate math.
+/// One entry per 0.5 s of audio (<see cref="OggOpusConstants.SeekBucketSeconds"/>), each snapped to the
+/// nearest enclosing page start, plus the totals needed to clamp a seek to range.
+/// </summary>
+/// <param name="Points">Ordered (granulepos, byteOffset) entries, ascending. The first is always the
+/// first audio page (offset just past the setup headers).</param>
+/// <param name="TotalDurationSeconds">Total stream duration from the final granule position.</param>
+/// <param name="TotalByteLength">Total Opus file byte length, for clamping a seek past the end.</param>
+public sealed record OggOpusSeekIndex(
+    IReadOnlyList<OpusSeekPoint> Points,
+    double TotalDurationSeconds,
+    ulong TotalByteLength)
+{
+    /// <summary>
+    /// Serializes the index to the compact little-endian binary blob the sidecar stores. Layout:
+    /// <c>[uint64 totalByteLength][double totalDurationSeconds][uint32 pointCount]</c> then
+    /// <c>pointCount × (uint64 granulepos, uint64 byteOffset)</c>. Fixed-width records keep the client
+    /// parse to a single typed-array read.
+    /// </summary>
+    public byte[] ToBytes()
+    {
+        var size = OggOpusConstants.SeekIndexHeaderSize + Points.Count * OggOpusConstants.SeekPointSize;
+        var bytes = new byte[size];
+        var span = bytes.AsSpan();
+
+        BinaryPrimitives.WriteUInt64LittleEndian(span[..8], TotalByteLength);
+        BinaryPrimitives.WriteDoubleLittleEndian(span.Slice(8, 8), TotalDurationSeconds);
+        BinaryPrimitives.WriteUInt32LittleEndian(span.Slice(16, 4), (uint)Points.Count);
+
+        var cursor = OggOpusConstants.SeekIndexHeaderSize;
+        foreach (var point in Points)
+        {
+            BinaryPrimitives.WriteUInt64LittleEndian(span.Slice(cursor, 8), point.GranulePosition);
+            BinaryPrimitives.WriteUInt64LittleEndian(span.Slice(cursor + 8, 8), point.ByteOffset);
+            cursor += OggOpusConstants.SeekPointSize;
+        }
+
+        return bytes;
+    }
+
+    /// <summary>
+    /// Parses a blob produced by <see cref="ToBytes"/>. Returns null if the blob is too short or its
+    /// declared point count does not fit — the storage contract is exact, so a malformed blob is a
+    /// corruption signal, not a recoverable shape. (Provided so tests and any future server-side reader
+    /// share one codec with the writer.)
+    /// </summary>
+    public static OggOpusSeekIndex? FromBytes(ReadOnlySpan<byte> bytes)
+    {
+        if (bytes.Length < OggOpusConstants.SeekIndexHeaderSize)
+            return null;
+
+        var totalByteLength = BinaryPrimitives.ReadUInt64LittleEndian(bytes[..8]);
+        var totalDuration = BinaryPrimitives.ReadDoubleLittleEndian(bytes.Slice(8, 8));
+        var count = BinaryPrimitives.ReadUInt32LittleEndian(bytes.Slice(16, 4));
+
+        var expected = OggOpusConstants.SeekIndexHeaderSize + (long)count * OggOpusConstants.SeekPointSize;
+        if (bytes.Length < expected)
+            return null;
+
+        var points = new OpusSeekPoint[count];
+        var cursor = OggOpusConstants.SeekIndexHeaderSize;
+        for (var i = 0; i < count; i++)
+        {
+            var granule = BinaryPrimitives.ReadUInt64LittleEndian(bytes.Slice(cursor, 8));
+            var offset = BinaryPrimitives.ReadUInt64LittleEndian(bytes.Slice(cursor + 8, 8));
+            points[i] = new OpusSeekPoint(granule, offset);
+            cursor += OggOpusConstants.SeekPointSize;
+        }
+
+        return new OggOpusSeekIndex(points, totalDuration, totalByteLength);
+    }
+}