docs: record Opus transcode store-path streaming

This commit is contained in:
daniel-c-harvey
2026-06-26 14:30:24 -04:00
parent a98cef1ba7
commit 1e17ffc380
2 changed files with 6 additions and 0 deletions
+2
View File
@@ -62,6 +62,8 @@ The split between host projects (`DeepDrftPublic`, `DeepDrftManager`, `DeepDrftC
If step 1 succeeds and step 2 fails, audio is orphaned in the vault (no rollback today).
The Opus transcode derived-artifact path (`OpusTranscodeService.TranscodeAndStoreAsync`) also streams its entire pipeline: extension and duration are read from the vault index (no body load); the source bytes are opened via `TrackContentService.OpenAudioMediaStreamAsync` and bounded-copied to a staging file; the encoded Ogg output is walked from a `FileStream` via `OggOpusParser.WalkAsync(Stream)` (bounded one-page-at-a-time buffer; byte-identical to the retained whole-buffer oracle `Walk(ReadOnlySpan<byte>)`); and stored via `RegisterResourceStreamingAsync`. The sidecar (a few KB, inherently bounded) retains the whole-buffer write. Completes the store-path OOM-fix arc.
### Streaming-first audio playback
The player is not fetch-then-play:
+4
View File
@@ -147,6 +147,10 @@ Reads audio from the `tracks` vault via `FileDatabase.LoadResourceAsync<AudioBin
Returns a read-only, seekable `Stream` over a track's vault audio without buffering the whole file. Used by the streaming waveform compute path (`WaveformProfileService`). Caller owns and must dispose the stream. Returns `null` if the entry has no backing file.
### OpenAudioMediaStreamAsync(entryKey)
Returns a `MediaStream?` — a read-only, non-buffering stream over a track's vault audio together with its stored extension, or `null` if the entry has no backing file. Same non-buffering contract as `OpenAudioStreamAsync`, but exposes `.Extension` alongside `.Stream` so the caller can name a staging file by the original format (the Opus transcode stages the source with the correct extension so ffmpeg can detect the format). The caller owns the returned `MediaStream` and must dispose it. Follows the FileDatabase swallow-and-return-null contract.
### GetAudioDurationAsync(entryKey)
Reads the stored audio duration from the vault index metadata only — no audio body load. Used by the streaming waveform compute to derive the duration-based bucket count, and by `UnifiedTrackService.BackfillDurationsAsync`. Returns `null` if the entry is unknown or carries no audio metadata.