From c009f708e631700fb1d65ccba2c8229c10054528 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 06:13:50 -0300 Subject: examples/live: the README, the language on one page examples/live/README.md: what the sketch is, how to run it (keys, the console's replay verbs, capture, crossfade, the test and probe steps), the language (its grammar and every builtin a line, from Lang.builtins), the capacities, what it cannot say (no state between samples or frames: no filters, feedback or reverb; the price of computing each sample alone on the GPU and of exact replays) and how it works, with the probe's numbers. Its example program parses (out 22 instructions, color 38). The sketchbook README lists the example. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T --- examples/live/README.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 examples/live/README.md (limited to 'examples/live/README.md') diff --git a/examples/live/README.md b/examples/live/README.md new file mode 100644 index 0000000..3c0c885 --- /dev/null +++ b/examples/live/README.md @@ -0,0 +1,89 @@ +# live + +A program typed over its own picture, and heard. Each line names an +expression; the `out` line is what you hear (-1..1), the `color` line what +you see. At every keystroke that leaves a program that parses, the +program is compiled into two tapes of at most 128 instructions, and one +interpreter on the GPU runs them per sample and per pixel. While a line +is broken, the last good program keeps playing and the problem is marked +under its byte. + +``` +bpm = 120 +beat = t * bpm / 60 +kick = exp(-7 * fract(beat)) +thump = sin(tau * 48 * t * (1 + 2 * kick)) * kick * 0.5 +out = thump +r = sqrt((x - 0.5) * (x - 0.5) + (y - 0.5) * (y - 0.5)) +color = hsv(fract(beat / 16 + r), 0.6, smoothstep(0.03, 0, abs(r - 0.2 - 0.1 * kick))) +``` + +The picture pulses with the kick because both lines say `kick`. + +## Running it + +`zig build run` (with `zig build lib --watch` beside it for hot reload). +Type; Backspace deletes the last character, Return starts a line. The +console (backtick) records, plays and seeks as for any sketch: `play +session 0`, `pause`, `seek 5000`, `step -60`, `stop`; a seek brings back +the text, the tapes and the picture of that moment, and the sound with +them. `capture` appends what is heard to `capture.f32` beside the save +(mono f32 at the device's rate) until `capture` again; `set crossfade +false` lets an edit click. `zig build test` runs the language's tests and +test/live.script headless; `zig build probe` times the interpreter on the +GPU (`--profile-gpu`). + +## The language + +A line is `name = expression`, a name defined once and before it is used, +so a program has no loops or recursion and always ends. Expressions: +numbers (`0.5`, `120`, `1e-3`), names, `+ - * /`, unary `-`, parentheses, +calls; `#` starts a comment. The builtins (src/Lang.zig's one table): + +| | | +| --- | --- | +| `t` | seconds | +| `x`, `y` | 0..1, left to right and bottom to top; 0 in sound | +| `tau`, `pi` | a turn and half a turn, in radians | +| `sin(a)`, `cos(a)` | of radians | +| `exp(a)`, `log(a)`, `pow(a, b)`, `sqrt(a)` | e to the a, its inverse, a to the b (a not negative), square root | +| `abs(a)`, `floor(a)`, `fract(a)` | without its sign, the whole number at or below, a - floor(a) | +| `min(a, b)`, `max(a, b)`, `clamp(v, lo, hi)` | the smaller, the larger, v kept between | +| `mix(a, b, w)` | a + (b - a) * w | +| `step(edge, v)` | 0 below edge, 1 from it on | +| `smoothstep(lo, hi, v)` | 0 to 1 smoothly as v goes from lo to hi, either way round | +| `atan2(y, x)` | the angle of the point (x, y) | +| `noise(x, y, z)` | smooth noise, -1..1, a new value about every 1; y and z 0 when left out | +| `saw(p)`, `sqr(p)`, `tri(p)` | waves of period 1 (cycles, not radians), -1..1; saw and tri rise through 0 at 0, sqr is 1 then -1 | +| `seq(i, v0, v1, ...)` | the value at floor(i), round the list: a step pattern, 16 values at most | +| `hsv(h, s, v)`, `rgb(r, g, b)` | a colour (hue 0..1 round the wheel); only as the whole `color` line | + +Capacities: 128 instructions a tape (a line reaches only what it uses), +512 terms and 128 names in the text, nesting 32 deep, 4 KiB of text. Past +any of them is a problem like a syntax error, in words, at its byte. + +## What it cannot say + +No state between samples or between frames: every sample is a function of +its time alone, every pixel of x, y and t. So no filters, feedback, delay +lines or reverb, and no picture that remembers the last frame. That is the +price of computing every sample alone on the GPU, and what makes a replayed +moment sound and look as it did. An echo can be said by evaluating again +at an earlier time (`t - 0.25` in a copy of the line). No user functions, +no vectors but the final colour, and `t` is a 32-bit float: past ten +minutes or so a high pitch begins to roughen. + +## How it works + +src/Lang.zig compiles the text in `update` (no allocation: fixed arrays on +the stack) into tapes of `{op, a, b, c}`, instruction i writing register +i; State keeps the text, both tapes, the problem and the time. The tapes +go to the GPU as data: the color tape as picture.frag's uniforms, the out +tape (with the one it replaces, for the crossfade) in a storage buffer for +synth.comp, both including shaders/vm.glsl, a loop over the tape with a +switch per op. No shader is compiled after the first frame, so typing +never stalls one. A color tape over 64 instructions is drawn at half +resolution: on an RTX 3050, 128 instructions took 2.7 ms at 1280x720 and +0.85 at half; 60 took 1.4 at full. The sound is `pub const audio_pull = +256` and a block a frame, as much as keeps the host's lead queued: a +change is heard a pull or so after the frame that made it. -- cgit v1.3 From fb237529724ae1c01b15f99e3b25bdce7c77cf82 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 07:59:59 -0300 Subject: examples/live: square units, x and y from the centre in half the height picture.frag gives the tape x and y in half the target's height, 0 at its centre and y up (`y` -1 to 1, `x` -1.78 to 1.78 on 16:9), so a circle is round on any window, half resolution included. Lang.builtins and the README's table say so; the README's program draws its ring about the centre (`r = sqrt(x * x + y * y)`, the ring's radius and width doubled into the new unit). Test: test/live.script replaces the text (`%`, `c`) with a disc of radius 0.5, `step(x * x + y * y, 0.25)`, and reads its edge 180 pixels from the centre across and up: white at 170, black at 190, each way. zig build test: 85 of 85 steps. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T --- examples/live/README.md | 6 +++--- examples/live/shaders/picture.frag | 5 +++-- examples/live/src/Lang.zig | 4 ++-- examples/live/test/live.script | 15 +++++++++++++++ 4 files changed, 23 insertions(+), 7 deletions(-) (limited to 'examples/live/README.md') diff --git a/examples/live/README.md b/examples/live/README.md index 3c0c885..e69b583 100644 --- a/examples/live/README.md +++ b/examples/live/README.md @@ -14,8 +14,8 @@ beat = t * bpm / 60 kick = exp(-7 * fract(beat)) thump = sin(tau * 48 * t * (1 + 2 * kick)) * kick * 0.5 out = thump -r = sqrt((x - 0.5) * (x - 0.5) + (y - 0.5) * (y - 0.5)) -color = hsv(fract(beat / 16 + r), 0.6, smoothstep(0.03, 0, abs(r - 0.2 - 0.1 * kick))) +r = sqrt(x * x + y * y) +color = hsv(fract(beat / 16 + r), 0.6, smoothstep(0.06, 0, abs(r - 0.4 - 0.2 * kick))) ``` The picture pulses with the kick because both lines say `kick`. @@ -43,7 +43,7 @@ calls; `#` starts a comment. The builtins (src/Lang.zig's one table): | | | | --- | --- | | `t` | seconds | -| `x`, `y` | 0..1, left to right and bottom to top; 0 in sound | +| `x`, `y` | across and up from the centre, in half the window's height (`y` -1 to 1, `x` -1.78 to 1.78 on 16:9: a circle is round); 0 in sound | | `tau`, `pi` | a turn and half a turn, in radians | | `sin(a)`, `cos(a)` | of radians | | `exp(a)`, `log(a)`, `pow(a, b)`, `sqrt(a)` | e to the a, its inverse, a to the b (a not negative), square root | diff --git a/examples/live/shaders/picture.frag b/examples/live/shaders/picture.frag index ec1293e..4621b31 100644 --- a/examples/live/shaders/picture.frag +++ b/examples/live/shaders/picture.frag @@ -1,6 +1,7 @@ #version 450 #extension GL_GOOGLE_include_directive : require -// The color tape at every pixel; x and y run 0..1, y up. +// The color tape at every pixel; x and y in half the target's height, 0 at +// its centre, y up: a circle is round on any window. #include "Picture.glsl" #define TAPE(i) u.tape[i] #include "vm.glsl" @@ -8,6 +9,6 @@ layout(location = 0) out vec4 out_color; void main() { - vec2 p = vec2(gl_FragCoord.x, u.size.y - gl_FragCoord.y) / u.size; + vec2 p = vec2(gl_FragCoord.x - 0.5 * u.size.x, 0.5 * u.size.y - gl_FragCoord.y) / (0.5 * u.size.y); out_color = vec4(clamp(vm(0u, u.len, u.time, p.x, p.y), 0.0, 1.0), 1.0); } diff --git a/examples/live/src/Lang.zig b/examples/live/src/Lang.zig index 6ad1f40..4ce504e 100644 --- a/examples/live/src/Lang.zig +++ b/examples/live/src/Lang.zig @@ -92,8 +92,8 @@ pub const Builtin = struct { /// switch, and only for a program that needs it. pub const builtins = [_]Builtin{ .{ .call = "t", .op = .t, .doc = "seconds" }, - .{ .call = "x", .op = .x, .doc = "0 at the left to 1 at the right; 0 in sound" }, - .{ .call = "y", .op = .y, .doc = "0 at the bottom to 1 at the top; 0 in sound" }, + .{ .call = "x", .op = .x, .doc = "across, in half the window's height: 0 at the centre, -1.78 to 1.78 on 16:9; 0 in sound" }, + .{ .call = "y", .op = .y, .doc = "up, in half the window's height: -1 at the bottom, 0 at the centre, 1 at the top; 0 in sound" }, .{ .call = "tau", .op = .constant, .value = std.math.tau, .doc = "a turn in radians, 6.283..." }, .{ .call = "pi", .op = .constant, .value = std.math.pi, .doc = "half a turn, 3.141..." }, .{ .call = "sin(a)", .op = .sin, .min = 1, .max = 1, .doc = "sine, of radians" }, diff --git a/examples/live/test/live.script b/examples/live/test/live.script index bedcf83..1ddcec2 100644 --- a/examples/live/test/live.script +++ b/examples/live/test/live.script @@ -94,3 +94,18 @@ expect out.code[1].a 1129906176 up 169 27 type u expect out.code[1].a 1130102784 +# Square units: a disc of radius 0.5 (half the window's height is 1) is +# 180 pixels across each way from the centre, round on 16:9. +type % +type c +type color = step(x * x + y * y, 0.25) +key escape +expect color.len 7 +frames 2 +screenshot .zig-cache/live/disc.png +expect-pixel .zig-cache/live/disc.png 810 360 255 255 255 255 2 +expect-pixel .zig-cache/live/disc.png 640 190 255 255 255 255 2 +expect-pixel .zig-cache/live/disc.png 470 360 255 255 255 255 2 +expect-pixel .zig-cache/live/disc.png 830 360 0 0 0 255 2 +expect-pixel .zig-cache/live/disc.png 640 170 0 0 0 255 2 +expect-pixel .zig-cache/live/disc.png 640 550 0 0 0 255 2 -- cgit v1.3 From abe2962264d590a6f54d64434222cd4b10b62160 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 17 Nov 2026 08:07:27 -0300 Subject: examples/live: the README, the editor's keys, hear this, the drag, scrubbing The README says the text is pardes's editor and what it needs (pardes beside sketchbook); the keys that matter, helix's in two lines (`i`, Escape, the motions, `x`, `d`, `c`, `r`, `u`/`U`, `%`) and the pointer; hear this (Alt-o, Alt-i, Alt-n, Alt-p: that expression alone, heard and seen grey until the next key; an example in thump); the drag (a step every 4 pixels, by the number's own precision, one step to undo); how to scrub in the console's words (`sessions`, `play session N [at S]`, `pause`, `seek MS`, `step -N`, `stop`); what the tests play, the storyboard among them; and in How it works, the editor's value in State and the grammar, its colours, node walks and indent. The reload is 0.07 to 0.09 s under `zig build lib --watch -fincremental`. zig build test: 86 of 86 steps. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_016Y9MNBECMWcJD5pdS4SR6T --- examples/live/README.md | 58 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 46 insertions(+), 12 deletions(-) (limited to 'examples/live/README.md') diff --git a/examples/live/README.md b/examples/live/README.md index e69b583..ea62cec 100644 --- a/examples/live/README.md +++ b/examples/live/README.md @@ -1,6 +1,7 @@ # live -A program typed over its own picture, and heard. Each line names an +A program typed over its own picture, and heard, in pardes's editor +(helix's keys, the language's grammar colouring it). Each line names an expression; the `out` line is what you hear (-1..1), the `color` line what you see. At every keystroke that leaves a program that parses, the program is compiled into two tapes of at most 128 instructions, and one @@ -22,16 +23,44 @@ The picture pulses with the kick because both lines say `kick`. ## Running it -`zig build run` (with `zig build lib --watch` beside it for hot reload). -Type; Backspace deletes the last character, Return starts a line. The -console (backtick) records, plays and seeks as for any sketch: `play -session 0`, `pause`, `seek 5000`, `step -60`, `stop`; a seek brings back -the text, the tapes and the picture of that moment, and the sound with -them. `capture` appends what is heard to `capture.f32` beside the save -(mono f32 at the device's rate) until `capture` again; `set crossfade -false` lets an edit click. `zig build test` runs the language's tests and -test/live.script headless; `zig build probe` times the interpreter on the -GPU (`--profile-gpu`). +`zig build run` (with `zig build lib --watch -fincremental` beside it for +hot reload: an edit of main.zig is back in 0.07-0.09 s). It needs pardes +beside sketchbook (`../02-pardes-code` of sketchbook's directory), whose +editor it takes as a library. + +**Keys** are helix's: `i` (or `a`, `o`, `O`) to type, Escape back to +normal mode, where `h j k l w b` move, `x` takes a line, `d` deletes, `c` +changes, `r` replaces a character, `u` and `U` undo and redo, `%` takes +it all. The mode is in the corner (NOR, INS, SEL). The pointer drags. + +**Hear this.** Alt-o grows the selection to the expression around it, +Alt-i shrinks it back, Alt-n and Alt-p go to the next and previous: after +any of them, that expression alone is heard (as `out`) and seen (grey, +unless it is a colour) until the next key. Escape, or any edit, goes back +to the program. `f*` then `;` then `mi(` then Alt-o, in +`thump = sin(tau * 48 * t ...)`, hears the sine alone. + +**Drag a number.** Press on a number and drag sideways: it moves a step +every 4 pixels, its step from how it is written (`220` by ones, `0.25` +by hundredths), and the program follows as you drag. The whole drag is +one step to undo. + +**Scrub** through the console (backtick): `sessions` lists the sessions +recorded, `play session N` plays one back (`play session N at 12` paused +at 12 s in), +`pause`, `seek 5000` (to 5 s in), `step -60` (60 frames back), `stop` +(live again from that moment, the session kept as it was). A seek brings back the text, the tapes and +the picture of that moment, and the sound with them. `capture` appends +what is heard to `capture.f32` beside the save (mono f32 at the +device's rate) until `capture` again; `set crossfade false` lets an edit +click. + +`zig build test` runs the language's tests, the grammar against the +language (test/grammar.zig), and test/live.script and test/story.script +(the storyboard: a tone, a drag, a gradient, a kick, a `)` broken and +mended, a probe, a bass and a ring, the session played back and sought) +headless; `zig build probe` times the interpreter on the GPU +(`--profile-gpu`). ## The language @@ -77,7 +106,12 @@ minutes or so a high pitch begins to roughen. src/Lang.zig compiles the text in `update` (no allocation: fixed arrays on the stack) into tapes of `{op, a, b, c}`, instruction i writing register -i; State keeps the text, both tapes, the problem and the time. The tapes +i; State keeps the editor's value (pardes-editor: 39 KiB of plain data, +4 KiB of text), both tapes, the probe's, the problem, the drag and the +time. grammar/grammar.js, generated into the committed grammar/src/parser.c, +is the same language for tree-sitter: its parse colours the text +(queries/highlights.scm, in pardes's orchard theme), gives Alt-o its +nodes and a new line its indent (queries/indents.scm). The tapes go to the GPU as data: the color tape as picture.frag's uniforms, the out tape (with the one it replaces, for the crossfade) in a storage buffer for synth.comp, both including shaders/vm.glsl, a loop over the tape with a -- cgit v1.3