mp3-decoder🔗ℹ

1 Validation🔗ℹ

The current implementation does not inspect mp3-file. This procedure exists to satisfy the reader interface used by racket-sound/audio-decoder.

Basic validation such as file existence and extension matching is performed in the higher-level module. This procedure therefore acts as an additional hook and currently accepts all inputs.

2 Opening🔗ℹ

If mp3-file* is a path, it is converted with path->string. If the file does not exist, the result is #f.

Otherwise a decoder handle is created and initialized. During initialization, stream information is collected and stored in a mutable hash in the handle.

The stream-info callback is invoked once, immediately after initialization:

(cb-stream-info info)

where info is a mutable hash containing at least:

• ’duration

• ’sample-rate

• ’channels

• ’bits-per-sample

• ’bytes-per-sample

• ’total-samples

3 Reading🔗ℹ

The loop repeatedly decodes audio chunks and invokes the audio callback:

(cb-audio info buffer size)

Before each callback, the info hash is updated in place with:

• ’sample

• ’current-time

The loop also checks for a pending seek request. If a seek has been requested, the stored target sample position is forwarded to the decoder backend and the request is cleared.

The loop terminates when either:

• the backend reports end-of-stream

• a stop has been requested via mp3-stop

If a stop is detected, the procedure returns ’stopped-reading.

After termination, the underlying decoder is closed and released.

The return value is otherwise unspecified.

4 Seeking🔗ℹ

The percentage argument represents a position relative to the full audio stream, where 0 is the start and 100 is the end. The value may be fractional.

If the total number of samples is available in the handle, the procedure computes an absolute target sample and stores it in the handle as a pending seek request.

The actual seek operation is performed later by mp3-read in its decode loop.

If the total number of samples is unavailable or equal to -1, this procedure has no effect.

5 Stopping🔗ℹ

The procedure sets an internal stop flag and waits until the read loop has terminated, sleeping briefly between checks.

6 Notes🔗ℹ

The stream-info hash is shared between initialization and decoding and is updated in place during playback.

The audio buffer passed to the callback is managed by the decoder and should be treated as transient data.

Seeking is implemented as a request stored in the handle and executed by the decode loop, not directly by mp3-seek.