From a50a3ce54d063aebb7d0e4d59c213fa7d8b7a6b3 Mon Sep 17 00:00:00 2001 From: Alb3e3 <74142887+Alb3e3@users.noreply.github.com> Date: Mon, 27 Jul 2026 19:45:01 +0400 Subject: [PATCH] doc: describe when the partial block after a seek is written FLAC__stream_decoder_seek_absolute() decodes the block containing the target sample during the seek and hands the samples from the target onwards to the write callback before it returns. The documentation only said that the next write callback may contain a partial block, which reads as if that callback comes from a later FLAC__stream_decoder_process_single() call. Seeking into the last block of a stream then looks like lost audio: the samples have already been written, and the following process_single() call reports end of stream without a write callback (issue #906). Assisted-by: Claude Code (Claude Opus 5) --- include/FLAC/stream_decoder.h | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/include/FLAC/stream_decoder.h b/include/FLAC/stream_decoder.h index a0e779456b..64e684a3bb 100644 --- a/include/FLAC/stream_decoder.h +++ b/include/FLAC/stream_decoder.h @@ -1755,7 +1755,16 @@ FLAC_API FLAC__bool FLAC__stream_decoder_skip_single_link(FLAC__StreamDecoder *d /** Flush the input and seek to an absolute sample. * Decoding will resume at the given sample. Note that because of - * this, the next write callback may contain a partial block. The + * this, the next write callback may contain a partial block. That + * write callback happens while this function is still running: the + * block containing \a sample is decoded during the seek, and the + * samples from \a sample to the end of that block are handed to the + * write callback before this function returns. Decoding then + * continues with the block after it, so when \a sample lies in the + * last block of the stream there is nothing left to decode and the + * next call to FLAC__stream_decoder_process_single() returns \c true + * without another write callback, with the decoder state set to + * \c FLAC__STREAM_DECODER_END_OF_STREAM. The * client must support seeking the input or this function will fail * and return \c false. Furthermore, if the decoder state is * \c FLAC__STREAM_DECODER_SEEK_ERROR, then the decoder must be flushed