summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-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