Indexed integer PCM read-ahead¶
With resampled-playback, IndexedConvertedReadAhead provides a separate
known-duration IntegerSinc pump. It implements ReadAheadPump, so the existing
worker and unique-consumer BufferedPlaybackOutput bridge can render it. Its
IndexedPlaybackReader contract is implemented by WaveReader<Read + Seek> and
AiffReader<Read + Seek>; their logical seeks defer physical repositioning to
the next read. Copy, floating Sinc, unknown-duration and compressed readers have
no indexed adapter here. Existing ConvertedReadAhead retains its stopped replay
behavior and counters.
new prepares frame zero without reads, seeks or factory calls and returns owned
inputs on failure. seek_indexed_stopped requires the matching, exclusively
stopped consumer. It preflights output bounds and generation before calling the
fresh-reader factory, validates identical rate/channel/declared duration before
seeking, and reads at most the taps-sized original source window needed for the
requested output. It supplies explicit zero history before frame zero and after
the declared source end, primes the exact integer phase, and commits one new
generation only after validation succeeds. A failed candidate returns its original
error and optional reader through IndexedSeekFailure::into_parts; its actual
cursor may have advanced. The old reader, queue, retained suffix, phase, origin
and generation remain intact. Factory side effects are not rolled back.
The retained endpoint is a separate operation: seeking to the exact output total
validates the last min(taps, source length) original frames and a zero EOF read,
then installs an empty completed stream. Its receipt has
filter_input_coordinate = None and verified_end_point = true; no unemitted
next output or fictitious padding is primed. The new indexed pump accepts a known
empty PCM source as zero retained output after an EOF check. The existing replay
and complete-file preparation APIs still reject empty clips. Positive streams
keep the existing causal delay and retained-tail policy.
IndexedSeekReceipt reports the validated original window and its actual ending
reader position separately from the u128 filter coordinate and leading/trailing
zero history. IndexedReadAheadCounts reports original cursor movement and
source/padding submitted after priming, absolute generated output, generated
output since priming and queue publication. Cursor movement includes commits
before reader errors and is not labelled validated decoded PCM; it is None
if a contract-violating reader regresses. Skipped prefixes are never reported as
read or submitted source. Generic worker seek_stopped preserves the original
error but releases the failed candidate on control; use the richer direct
method when the candidate reader must be recovered.
A successful candidate reads at most min(taps, source length) original frames, with at most taps positive read calls when a custom reader supplies short reads, plus one bounded EOF probe when the window reaches EOF. The built-in full-read WAV/AIFF implementations use at most ceil(window frames / read batch) payload reads, plus that probe. Instrumented container tests measure payload bytes and physical read/seek calls after the fresh reader's metadata constructor; factory parsing, custom reader internals and filesystem latency remain separate. Temporary history scratch is at most 66 KiB in addition to each candidate's existing 32 MiB array ceiling; old and candidate states coexist until commit. Reader, ring and allocator memory are separate. Existing rate/channel/batch, reader/container and configured duration bounds remain, including retained output no greater than u64::MAX−65536.
The factory must supply the same source version. Window/EOF validation does not authenticate skipped regions or detect every earlier malformed/changed byte. This adds no compressed indexing, RF64, clock/drift control, callback seek/wait, filesystem deadline or physical-device support claim. Stopped renderer reclamation and explicit preparation/reopening remain necessary for device composition.