(sigil audio sink)

Portable streaming audio-sink facade

This is the target-independent audio sink API. It presents ONE surface for pushing interleaved float32 PCM into a device, and selects its backend with cond-expand:

• native (else): the SPSC ring living in (sigil audio), drained by the playback device (miniaudio)
• wasm: the WebAudio bridge in (sigil browser audio-sink), provided by the sigil-wasm-audio package

This mirrors how (sigil websocket) selects a native socket stack vs the (sigil browser websocket) bridge. Application code imports THIS module and the same source compiles for both targets.

Context lifecycle

WebAudio requires an AudioContext that starts suspended and must be resumed from a user gesture (autoplay policy). The context ops model that. On native, the device layer owns a single always-running device, so the context ops are thin shims (open initializes the device; resume is a no-op; the sample rate is a fixed 44100). They exist so the SAME source compiles and runs on both targets behind this facade.

(import (sigil audio sink))
(define ctx (audio-context-open))
(audio-context-resume ctx)                  ; from a user gesture on wasm
(let ((rate (audio-context-sample-rate ctx))
      (s    (open-audio-stream channels: 2 buffer-frames: 8192)))
  (push-audio-samples s pcm n-frames)       ; interleaved f32
  (audio-stream-depth s))                    ; backpressure accounting

Streams below the device's rate

A producer that renders below the device's rate (a synth stepped down by (sigil audio ladder)) passes rate: to open-audio-stream, or calls set-audio-stream-rate! when it steps; the sink upsamples. Frames already queued keep the rate they were pushed at, so a step needs no reopen.

Cues

A cue is a short sound a game triggers: a tap, a hit. Pushed into a stream it would be heard one ring-depth late (a 256 ms ring is a 256 ms delay). Load it once and play it by handle instead; it is mixed at output time:

(define tap (load-audio-cue (render-tap rate) channels: 1))
(play-audio-cue tap volume: 0.8 pan: -0.2)

On the web the cue is mixed in an AudioWorklet in the next render quantum (2.7 ms at 48 kHz); natively it plays through play-sound, mixed in the device callback. Neither waits behind a stream's ring.

Underruns

audio-stream-underruns counts output frames a stream could not fill. audio-stream-underruns-sounding is the part a listener heard as a gap: the stream ran dry within 128 frames of a sample above -80 dB. The rest (audio-stream-underruns-idle) is a quiet or unfed stream running dry.