summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorGabriel Schneider <[email protected]>2026-11-17 00:21:06 -0300
committerGabriel Schneider <[email protected]>2026-11-17 12:15:01 -0300
commit20bfc56562068ff963281d562cba17a65880ec2d (patch)
tree71a17fdf19436a03d38918695571d2fa14600205
parentc37f1b3b1374df2a2a434d16cd772a4bb00c567e (diff)
downloadsketchbook-20bfc56562068ff963281d562cba17a65880ec2d.tar.gz
sketchbook-20bfc56562068ff963281d562cba17a65880ec2d.zip
README: what the sound code does now, and the truth about sound on the web
The sound section says what each part does: voices with their rate and group and f.gain, when the host mixes them (once a frame, topping its queue up to 2048 samples, about 43 ms, ahead of the device), streams and the microphone, the mixer's curve, newSound and sfxr (from the changes before this one), and that --export writes no sound. Known limits said synthesised voices were silent on the web. Every voice is: web.zig drops each .voice command (and now .gain), whatever its sound; decodeSound gives .none; loadSound knows only files the page decoded. It now says so, and what does sound there: streams and the microphone. Co-Authored-By: Claude Opus 5.5 <[email protected]> Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T
-rw-r--r--README.md40
1 files changed, 23 insertions, 17 deletions
diff --git a/README.md b/README.md
index 0fdc93a..75a6fbe 100644
--- a/README.md
+++ b/README.md
@@ -435,22 +435,26 @@ readback. Each dispatch is its own compute pass, so it sees everything the
commands before it wrote.
Sound is declarative. `f.voice(.{ .key, .audio, .serial, .loop, .volume,
-.fade, .rate, .group })` declares a voice that should be sounding. A new key
-or serial starts it, and an undeclared key stops it. A finished one-shot
-stays finished while it is still declared, so replays and seeks never
-re-fire sounds. `.rate` is its speed and so its pitch (2 is an octave up
-and half as long; resampled by linear interpolation, cheap and a little
-dull far from 1); changing it does not restart the voice. `.group` (0-7)
-puts it under a gain the sketch declares each frame, `f.gain(group,
-value)`, 1 when not declared: music ducks under speech by the sketch
-lowering one number, and the host glides to a new gain over 10 ms so a
-step does not click. `f.audio(key,
-samples, .{})` streams PCM, and `input.stream(key)` reports what the host has
-queued and played. `f.microphone()` keeps the default recording device open
+.fade, .rate, .group })` declares a voice that should be sounding. A new
+key or serial starts it, and an undeclared key stops it. A finished
+one-shot stays finished while it is still declared, so replays and seeks
+never re-fire sounds. `.rate` is its speed and so its pitch (2 is an
+octave up and half as long; resampled by linear interpolation, cheap and
+a little dull far from 1); changing it does not restart the voice.
+`.group` (0-7) puts it under a gain the sketch declares each frame,
+`f.gain(group, value)`, 1 when not declared: music ducks under speech by
+the sketch lowering one number, and the host glides to a new gain over
+10 ms so a step does not click. The host mixes the voices once a frame,
+topping its queue up to 2048 samples (about 43 ms) ahead of the device,
+so what `draw` declares is heard up to that much later.
+
+`f.audio(key, samples, .{})` streams PCM, and `input.stream(key)` reports
+what the host has queued and played: the sketch chooses how far ahead it
+keeps a stream. `f.microphone()` keeps the default recording device open
while declared, and the next frame's `input.microphone` holds what it heard
(to `draw` only: it is a device, not an event, so it does not replay).
`host.samples(audio)` gives a loaded sound's samples, mono at
-`input.sample_rate`.
+`input.sample_rate`. `--export` writes frames only, no sound.
The host sums the voices and limits the sum, sample by sample: below
0.75 (-2.5 dBFS) it plays at true volume, to the bit; above, it bends
@@ -1090,10 +1094,12 @@ Add `.sketchbook = .{ .path = "..." }` to your `build.zig.zon`.
native draws aliased. A stroke that overlaps itself blends twice
natively where it overlaps, once on the web.
- On the web: nothing persists (Store lasts as long as the page) and no
- sessions are recorded,
- synthesised voices are silent, `loadSound` knows only sounds the page
- decoded, multisampling is 4× at most, and mixing runs on the main thread
- (a ScriptProcessor), so a busy page can crackle.
+ sessions are recorded, and multisampling is 4× at most. Every voice is
+ silent there, whatever its sound (loaded, decoded or made with
+ `newSound`), and so are groups' gains; `decodeSound` gives `.none`, and
+ `loadSound` knows only sounds the page decoded (opened or dropped
+ files). What does sound: streams (`f.audio`) and the microphone, mixed
+ on the main thread (a ScriptProcessor), so a busy page can crackle.
The reusable GPU executor and the pardes integration are described in
[docs/pardes-rendering.md](docs/pardes-rendering.md), including the remaining