premature flac decode deletion solved

scrbl/audio-player.scrbl

@@ -85,7 +85,11 @@ The @racket[state-hash] contains the detailed playback state reported by the
 worker.  It includes values such as the current playback position, stream
 duration, buffer status, music id, and libao handle validity.  Code that only
 needs the logical playback state should use @racket[current-player-state]
-instead of extracting it from the hash.
+instead of extracting it from the hash. The @racket['error] entry is
+@racket[#f] during normal playback or an error message when decoding fails.
+A failed read reports @racket['stopped]; starting another track cleans up the
+failed playback before opening a new decoder. Each new track also resets the
+interruption flag, so an earlier failed Stop cannot suppress its EOF event.
 
 The @racket[cb-eof-stream] callback is called as:
 

scrbl/flac-decoder.scrbl

@@ -66,17 +66,17 @@ handler.
 }
 
 @defproc[(flac-read [handle flac-handle?])
-         (or/c 'stopped-reading
-               'end-of-stream)]{
+         void?]{
 
 Reads the stream by repeatedly calling the native decoder with
 @racket['process-single].
 
 Before reading starts, the handle fields @racket[stop-reading]
 and @racket[reading] are set to @racket[#f] and @racket[#t]. If a
-stop has been requested with @racket[flac-stop], reading ends
-with @racket['stopped-reading] and @racket[reading] is reset to
-@racket[#f].
+stop has been requested with @racket[flac-stop], the read loop ends.
+Native decoder cleanup runs on normal completion, exceptions and breaks; only
+after cleanup does @racket[reading] become @racket[#f]. Decoder failures and
+errors raised by the audio consumer propagate to the caller.
 
 Whenever pending metadata is available, it is processed with
 @racket[process-meta]. For metadata of type
@@ -121,8 +121,10 @@ The procedure then waits until the handle field
 @racket[reading] becomes @racket[#f], sleeping for 10 ms between
 checks.
 
-The procedure prints timing information before and after the
-wait.
+If reading has already finished or never started, the native decoder is
+released directly. Calling @racket[flac-stop] repeatedly, including after EOF
+or a failed read, is safe. The procedure logs timing information before and
+after the wait.
 }
 
 @defproc[(flac-duration [handle flac-handle?])