summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 02:36:42 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commita3085da09e222238071c4948f6893b21542ac695 (patch)
tree77d98cd2c8959699cb9cdba161bf1e48438e4d42 /README.md
parent5553b933f7c243b2706eb2a7989d8e33d2f6042b (diff)
downloadsketchbook-a3085da09e222238071c4948f6893b21542ac695.tar.gz
sketchbook-a3085da09e222238071c4948f6893b21542ac695.zip
host: a sketch may ask for the sound device's pull, audio_pull
Sound a sketch makes leaves for the device about one pull after draw, and SDL opens 1024-sample pulls at 48 kHz (21 ms); 256 leaves in about 6.5 ms, but the audio server then runs every client at that size, and drops out under load. The only way to ask was SDL_AUDIO_DEVICE_SAMPLE_FRAMES in the environment. Now an app declares `pub const audio_pull = 256;` beside its name; abi.Info carries it (0, SDL's own, when it is not declared), and the host sets it as SDL's hint just before it opens the device, at normal priority, so the environment variable still wins. It is read once, at start; the web host has no device to open and ignores it. The sound overlay's header says what the device took: OUTPUT ch1 / ... / pull 256. Test: audio, on SDL's dummy driver: the device opened with nothing asked takes 1024 at once, asked 256 takes 256, and with 512 in SDL's copy of the environment takes 512 though 256 was asked. test-audio: 48/48 steps, 9/9 tests. README: the app table's row, and a paragraph in sound with the trade-off. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
Diffstat (limited to 'README.md')
-rw-r--r--README.md18
1 files changed, 15 insertions, 3 deletions
diff --git a/README.md b/README.md
index 7d8b1a9..9dbd183 100644
--- a/README.md
+++ b/README.md
@@ -45,6 +45,7 @@ An app is an ordinary module. Every declaration is optional:
| Declaration | Meaning |
| --- | --- |
| `name`, `width`, `height` | Window title and initial canvas |
+| `audio_pull` | Samples the sound device takes at once (see sound) |
| `State` | The one thing a sketch keeps: what `update` changes, saved in one file with its history, replayed. No pointers, no host handles, and at most 32 MiB, half of a save (compile errors). |
| `Session` | This process: survives reloads, never saved. Caches, image and buffer handles, playback cursors. |
| `init(state, host)` | Seed brand-new state, after the declared defaults |
@@ -466,9 +467,20 @@ once a frame), plus the device's pull (what it takes from a stream at once,
A sketch that makes its sound as it goes pushes `in.lead -|
in.stream(key).queued` a frame, and a change it makes is heard after what
is queued ahead of it, about a pull: 19 to 27 ms after `draw` on this
-machine at 60 Hz. `SDL_AUDIO_DEVICE_SAMPLE_FRAMES=256` in the environment
-asks SDL for 5 ms pulls instead, and a change leaves in about 6.5 ms (on
-PipeWire every client then runs at that size). `f.audioBuffer(key, buffer, .{ .count
+machine at 60 Hz.
+
+A sketch that must answer faster asks for a smaller pull:
+`pub const audio_pull = 256;` beside its `name` has the host ask SDL for
+256-sample pulls (5.3 ms) when it opens the device, and a change then
+leaves in about 6.5 ms. The price is paid by the whole machine: the audio
+server then runs every program's sound at that size, four times as many
+wake-ups, and under load it misses one now and then, a dropout (a click)
+in everything playing, not only the sketch. Without it SDL picks (1024 at
+48 kHz). `SDL_AUDIO_DEVICE_SAMPLE_FRAMES` in the environment wins over
+both, the web ignores it, it is read once, when the host starts, and the
+sound overlay (`overlay sound`) shows what the device took (`pull 256`).
+
+`f.audioBuffer(key, buffer, .{ .count
= n })` streams `n` samples a compute shader wrote (f32 from `.offset`
bytes): the host reads them back within the frame, waiting for the GPU's
work so far (about 0.2 ms), and queues them. A GPU synth is then: