daniel-c-harvey
33d6f34d8a
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.
94 lines
4.7 KiB
C#
94 lines
4.7 KiB
C#
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);
|
||
}
|
||
}
|