13.1 Layering🔗ℹ

This module is the low-level Racket FFI layer. It is normally wrapped by "ffmpeg-ffi.rkt" and then by "ffmpeg-decoder.rkt". The first wrapper adapts this module to the command protocol used by the audio decoder frontend. The second wrapper exposes the callback-oriented decoder interface used by the rest of the playback pipeline.

The distinction matters for buffer lifetime. At this level, fmpg-buffer returns the current buffer owned by the decoder instance. The adapter in "ffmpeg-ffi.rkt" copies that buffer before passing it to "ffmpeg-decoder.rkt". Code that uses this module directly must copy the buffer itself when the bytes must survive the next decoder operation.

13.2 FFmpeg version information🔗ℹ

The version is read from FFmpeg’s packed integer value. For example, a runtime value corresponding to 62.28.100 is returned as '(62 28 100). The function raises an exception for an unknown library symbol.

The runtime versions determine which partial FFmpeg struct layouts are safe to use. If a future FFmpeg major release changes a layout before one of the fields read by this module, the supported range should be extended only after the affected partial definitions have been checked.

13.3 Implementation strategy🔗ℹ

This module talks directly to the FFmpeg shared libraries through Racket’s FFI. There is no C shim that hides FFmpeg’s structs or normalizes their layout. The price of that choice is that the Racket side must know enough of the relevant C struct layouts to read the fields used by the decoder. The benefit is that the binding remains a Racket module with direct access to the platform FFmpeg libraries.

13.4 Decoder instances🔗ℹ

A decoder instance is an opaque value returned by fmpg-init. Its structure type and predicate are not exported. Pass the value back to the functions in this module and do not inspect it directly. The contracts below therefore use any/c for the instance argument. Operationally, that argument must be a value returned by fmpg-init.

The instance owns native FFmpeg resources: a format context, a codec context, an audio frame, a resampler, and the Racket byte string used for the current PCM block. Finalizers are installed as a last line of defence, but callers should still call fmpg-close! explicitly when playback stops or when the file is no longer needed. Explicit close keeps the lifetime of native resources predictable.

Creating the instance does not open a file. Use fmpg-open-file! before querying stream information or decoding audio.

The function returns 1 on success and 0 on failure. On failure, partially initialized native state is closed again. A non-string, non-path filename is treated as an open failure and returns 0.

An instance can only have one file open. Close it with fmpg-close! before opening another file on the same instance.

The stored audio information is reset. Calling this function with #f or with an already closed instance is harmless.

13.5 Audio stream information🔗ℹ

The decoder selects one audio stream for playback using FFmpeg’s best-stream selection. The stream count reports how many audio streams were found in the container, but decoding is performed only for the selected stream.

The term sample in this module means a sample frame: one time step in the audio stream, across all channels. For stereo 32-bit output, one sample frame therefore occupies (* 2 4) bytes in the returned PCM buffer.

13.6 Output format🔗ℹ

The decoder output format is intentionally fixed:

• sample format: signed 32-bit PCM, AV_SAMPLE_FMT_S32

• layout: interleaved

• sample rate: the selected stream’s sample rate

• channels: the selected stream’s channel count

This keeps the playback layer simple. The FFmpeg input format may be planar, floating point, compressed, or otherwise different; libswresample converts the decoded frames to the fixed output format before the bytes are exposed to Racket.

13.7 Decoding🔗ℹ

Decoding is block oriented. Each call to fmpg-decode-next! clears the previous PCM block and attempts to produce the next decoded block for the selected audio stream. When the call returns 1, the block can be read with fmpg-buffer and described with the buffer query functions.

• 1: a new PCM buffer is available through fmpg-buffer.

• 0: decoding is complete and no more PCM is available.

• A negative value: decoding failed or the instance was not ready.

Internally, the decoder first tries to receive frames that FFmpeg may already have buffered. If no frame is ready, it reads packets until it finds a packet for the selected audio stream. Packets from other streams are skipped and immediately unreferenced. Sent packets are unreferenced after avcodec_send_packet, because the codec has then taken what it needs.

At end of input, the function drains both the codec and the resampler. This is necessary because FFmpeg and libswresample may still hold delayed samples even after the demuxer has no more packets.

13.8 Decoded buffers🔗ℹ

The PCM buffer belongs to the decoder instance. It is replaced by the next call to fmpg-decode-next!, fmpg-seek-ms!, or fmpg-close!. Treat the returned byte string as read-only. Copy it if it must outlive the next decoder operation or if another component may mutate it.

The byte string contains interleaved signed 32-bit samples. Its logical frame count is available as the difference between fmpg-buffer-end-sample and fmpg-buffer-start-sample. Its byte size is also available through fmpg-buffer-size.

fmpg-buffer-start-sample returns the first sample frame represented by the current PCM buffer. fmpg-buffer-end-sample returns the half-open end position: the first sample frame after the current buffer. fmpg-sample-position returns the next sample position the decoder expects to produce.

These values count sample frames, not individual channel samples. For stereo audio, one sample frame contains one sample for the left channel and one sample for the right channel.

13.9 Seeking🔗ℹ

Seeking uses FFmpeg’s backward seek flag. FFmpeg may therefore seek to a packet position before the requested target. The decoder stores a discard target in sample frames. During the following decode calls, frames before the target are dropped, and frames that overlap the target are trimmed so the exposed PCM buffer starts at, or as close as FFmpeg can provide to, the requested position.

After a successful seek, the codec buffers are flushed, the resampler is closed and reinitialized, EOF state is cleared, and sample bookkeeping is reset to the target position.

13.10 Resource ownership🔗ℹ

The decoder instance owns the native FFmpeg objects it allocates. The codec pointer returned by FFmpeg is not owned by the instance, but the codec context, frame, resampler and format context are. They are released by fmpg-close!. Finalizers are registered as a safety net, but callers should close decoder instances explicitly.

Temporary native buffers used during resampling are allocated only for the duration of a conversion step and are always freed before control returns to the caller. The public PCM buffer is a Racket byte string, so it can safely be passed to the Racket-side playback backend.

13.11 Use through the decoder frontend🔗ℹ

The direct API above is normally wrapped by "ffmpeg-ffi.rkt" and by "ffmpeg-decoder.rkt". The frontend function ffmpeg-open returns a handle or #f when the file does not exist. Its stream-info callback receives a mutable hash with at least these playback keys:

(list 'sample-rate

'channels

'bits-per-sample

'bytes-per-sample

'total-samples

'duration)

The audio callback receives the same hash extended for the current buffer with these keys:

(list 'sample

'current-time)

The hash is followed by a copied byte string and its valid byte count. The copy is made by "ffmpeg-ffi.rkt", not by the low-level buffer function itself.

The frontend’s seek function accepts a percentage of the stream and translates that percentage to a sample position. The adapter then translates the sample position to milliseconds and calls fmpg-seek-ms!. This is why the low-level module exposes millisecond seeking while the frontend exposes percentage seeking.

13.12 Examples🔗ℹ

The following example opens a file, decodes all PCM blocks, and reports their byte ranges and sample ranges. A real playback loop would pass each buffer to the audio output layer before requesting the next block.

(define dec (fmpg-init))

(when (and dec (= (fmpg-open-file! dec "track.ogg") 1))

(printf "~a Hz, ~a channels, ~a ms\n"

(fmpg-audio-sample-rate dec)

(fmpg-audio-channels dec)

(fmpg-duration-ms dec))

(let loop ()

(case (fmpg-decode-next! dec)

[(1)

(define pcm (fmpg-buffer dec))

(define size (fmpg-buffer-size dec))

(define start (fmpg-buffer-start-sample dec))

(define end (fmpg-buffer-end-sample dec))

(printf "decoded ~a bytes, samples [~a, ~a)\n"

size start end)

(loop)]

[(0)

(printf "done\n")]

[else

(error "decode error")]))

(fmpg-close! dec))

A simple seek flow looks the same after the seek succeeds. The following code moves to 30 seconds and then requests the next decoded buffer.

(when (= (fmpg-seek-ms! dec 30000) 1)

(when (= (fmpg-decode-next! dec) 1)

(define pcm (fmpg-buffer dec))

(define start (fmpg-buffer-start-sample dec))

(printf "first buffer after seek starts at sample ~a\n" start)))