Racket

flac-decoder🔗ℹ

(require "racket-sound/flac-decoder")
	package: racket-sound

This module provides a small decoder interface on top of the FLAC FFI layer. It opens a decoder for a file, reads stream metadata, reads audio frames, exposes the current decoder state, and allows an active read loop to be stopped. It also re-exports the bindings from "flac-definitions.rkt".

A decoder handle stores the native decoder handler together with optional callbacks for stream metadata and decoded audio.

1 Procedures🔗ℹ

procedure
(flac-open flac-file*
cb-stream-info
cb-audio) → (or/c flac-handle? #f)
  flac-file* : (or/c path? string?)
  cb-stream-info : (or/c procedure? #f)
  cb-audio : (or/c procedure? #f)

Opens a FLAC decoder for flac-file*. If a path is given, it is converted with path->string. If the file does not exist, the result is #f.

Otherwise a native decoder handler is created with flac-ffi-decoder-handler, initialized with the file, and wrapped in a flac-handle. The given callbacks are stored in the handle.

When metadata of type 'streaminfo is processed and cb-stream-info is a procedure, it is called with a flac-stream-info value.

When decoded audio data is processed and cb-audio is a procedure, it is called as (cb-audio header buffers), where header is a mutable hash containing the frame header fields plus 'duration, and buffers is the decoded channel data returned by the FFI layer.

procedure
(flac-stream-state handle) →
(or/c 'search-for-metadata
      'read-metadata
      'search-for-frame-sync
      'read-frames
      'end-of-stream
      'ogg-error
      'seek-error
      'aborted
      'memory-allocation-error
      'uninitialized
      'end-of-link)
  handle : flac-handle?

Returns the current decoder state reported by the native decoder handler.

procedure
(flac-read handle) →
(or/c 'stopped-reading
'end-of-stream)
handle : flac-handle?

Reads the stream by repeatedly calling the native decoder with 'process-single.

Before reading starts, the handle fields stop-reading and reading are set to #f and #t. If a stop has been requested with flac-stop, reading ends with 'stopped-reading and reading is reset to #f.

Whenever pending metadata is available, it is processed with process-meta. For metadata of type 'streaminfo, a flac-stream-info value is constructed, stored in the handle, and passed to the stream-info callback.

Whenever pending frame data is available, it is processed with process-frame. The frame header is converted to a mutable hash, extended with a 'duration entry taken from flac-duration, and passed together with the decoded buffers to the audio callback.

For each processed frame, the module also updates last-buffer, last-buf-len, and kinds.

The procedure prints diagnostic messages for state changes, metadata, stream errors, and stop handling.

procedure
(flac-read-meta handle) → (or/c flac-stream-info? #f)
handle : flac-handle?

Advances the decoder until the state becomes one of 'read-metadata, 'end-of-stream, 'aborted, 'memory-allocation-error, or 'uninitialized.

If the resulting state is 'read-metadata, pending metadata is processed and the stored stream info is returned. Otherwise the result is #f.

Only metadata of type 'streaminfo is converted into a flac-stream-info value by this module.

procedure
(flac-stop handle) → void?
handle : flac-handle?

Requests termination of an active flac-read loop by setting the handle field stop-reading to #t. The procedure then waits until the handle field reading becomes #f, sleeping for 10 ms between checks.

The procedure prints timing information before and after the wait.

2 Diagnostic bindings🔗ℹ

value
kinds : hash?

A mutable hash used to record the frame number kinds encountered during decoding. The keys are the values found in the frame-header field 'number-type.

value
last-buffer : (or/c #f list?)

The most recently decoded buffer set produced by frame processing.

value
last-buf-len : (or/c #f exact-integer?)

The block size of the most recently processed frame.

3 Notes🔗ℹ

The frame-header hash passed to the audio callback is produced by flac-ffi-frame-header. In this module it is extended with a 'duration field before the callback is called.

All bindings from "flac-definitions.rkt" are re-exported.