@zeeuw/riff 0.1.0-beta.0 → 0.1.0-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +178 -29
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,10 +1,16 @@
1
1
  # RIFF — Rhythm In Functional Form
2
2
 
3
- A live-coding music engine for the browser. Patterns are functions of time.
4
- Code written for Strudel runs in RIFF and gives the same events. MIT licensed,
5
- zero dependencies, plain ES modules (no build step).
3
+ RIFF is a live-coding music engine for the browser. A pattern is a function of
4
+ time: ask it for a time span and it returns the events in that span. Code
5
+ written for Strudel runs in RIFF unchanged and gives the same events, at the
6
+ same times, with the same values.
6
7
 
7
- > Status: beta. How RIFF can be MIT while running Strudel code: [`docs/clean-room.md`](docs/clean-room.md).
8
+ - MIT licensed.
9
+ - Zero runtime dependencies. Fractions, the mini-notation parser, the code
10
+ transpiler, the scale and chord tables and the synth are RIFF's own code.
11
+ - Plain ES modules. No build step, no bundler needed.
12
+
13
+ > Status: beta (`0.1.0-beta.0`).
8
14
 
9
15
  ## Install
10
16
 
@@ -12,36 +18,179 @@ zero dependencies, plain ES modules (no build step).
12
18
  npm install @zeeuw/riff@beta
13
19
  ```
14
20
 
21
+ ## Example
22
+
23
+ In the browser. Audio can only start after a user gesture, so create it in a
24
+ click handler:
25
+
26
+ ```js
27
+ import { initStrudel } from '@zeeuw/riff';
28
+
29
+ let riff;
30
+ document.querySelector('#play').onclick = async () => {
31
+ riff ??= await initStrudel(); // audio, scheduler, Strudel names on globalThis
32
+ await riff.evaluate(`
33
+ $: note("c3 [e3 g3] a2 <f2 g2>").s("sawtooth").lpf(900).room(0.3)
34
+ $: note("c5 e5 g5 b5").s("triangle").fast(2).gain(0.4)
35
+ `);
36
+ };
37
+ document.querySelector('#stop').onclick = () => riff?.hush();
38
+ ```
39
+
40
+ Patterns also work without audio, for example in Node or a test:
41
+
42
+ ```js
43
+ import { note } from '@zeeuw/riff';
44
+
45
+ for (const hap of note('c e g').queryArc(0, 1)) {
46
+ console.log(hap.whole.begin.valueOf(), hap.value); // 0 { note: 'c' } ...
47
+ }
48
+ ```
49
+
50
+ `evaluate`, `hush`, `initStrudel`, `samples`, `setcps` and the pattern
51
+ functions have the same names and arguments as in Strudel. The contract is in
52
+ [`spec/integration.md`](spec/integration.md) in the repository.
53
+
54
+ ### Optional extras
55
+
15
56
  ```js
16
- import { initStrudel, note, s, stack } from '@zeeuw/riff';
17
- import { check } from '@zeeuw/riff/extras'; // optional: checker, describe, editor helpers
57
+ import { check, describe, createEditorExtensions } from '@zeeuw/riff/extras';
58
+
59
+ const diagnostics = await check(code); // errors with line and column, before playing
60
+ ```
61
+
62
+ `@zeeuw/riff/extras` holds the code checker, `describe()` and CodeMirror
63
+ helpers. The engine never imports it, so a page that does not need these tools
64
+ does not load them.
65
+
66
+ ### CDN or vendored copy
67
+
68
+ `src/` is browser-ready ES modules. Copy `src/` and `data/` into your site, or
69
+ load the package from any npm CDN that serves files as published:
70
+
71
+ ```html
72
+ <script type="module">
73
+ import { initStrudel } from 'https://cdn.jsdelivr.net/npm/@zeeuw/riff@beta/src/index.js';
74
+ </script>
18
75
  ```
19
76
 
20
- ## Package
77
+ ## How it came to be
21
78
 
22
- - Published to npm as `@zeeuw/riff` (scoped, public). The package holds `src/`
23
- (engine plus the optional `src/extras/`), the generated `data/`,
24
- `docs/clean-room.md`, `LICENSE` and this README; specs, fixtures and tools stay
25
- in the repository.
26
- - How RIFF was built clean-room so it can be MIT, and the evidence:
27
- [`docs/clean-room.md`](docs/clean-room.md) (ships in the package).
28
- - Works from a CDN or a vendored copy as-is: `src/` is browser ES modules.
29
- - Release: bump `version`, run `npm test` and `npm pack --dry-run`, then
30
- `npm publish --tag beta` (the operator's step, needs the npm login).
79
+ RIFF started as the engine for SAAI, an app where a language model writes
80
+ music as Strudel code. Strudel is licensed AGPL-3.0, and was never MIT: its
81
+ first commit was GPL-3.0-or-later and it moved to AGPL-3.0 in April 2022.
82
+ Shipping it inside SAAI would have made SAAI's own source AGPL as well. There
83
+ was no permissive version to fork.
84
+
85
+ Copyright protects code and text, not a language, an interface or behaviour.
86
+ So RIFF reimplements Strudel's interface and behaviour (names, signatures, the
87
+ mini-notation, the event output) and nothing else. It was built as a clean
88
+ room:
89
+
90
+ - **Two roles.** Spec writers ran Strudel as a black box and wrote plain
91
+ specs and recorded test fixtures. Implementers wrote RIFF from those specs
92
+ only and never looked at Strudel's source.
93
+ - **Black-box oracle.** A test tool runs the published Strudel packages and
94
+ records which events a program produces. Its output (fixtures) is data, not
95
+ code. The tool is never imported, bundled or served by RIFF.
96
+ - **Similarity gate.** A token-level scan compares RIFF's source with
97
+ Strudel's. The recorded run found no shared run of 40 tokens or more and
98
+ 0.28 % of RIFF tokens inside shared 20-token runs (limit 2 %).
99
+ - **The lab.** A static page that runs every public name and compares the
100
+ result with its fixture, so anyone can check the behaviour by hand.
101
+
102
+ The full account, with the evidence and its limits, is in
103
+ [`docs/clean-room.md`](docs/clean-room.md) (ships in the package). The gate's
104
+ recorded runs are in [`docs/similarity-report.md`](docs/similarity-report.md).
105
+ As that document says, this is not legal advice.
106
+
107
+ ## RIFF vs Strudel
108
+
109
+ | | RIFF 0.1.0-beta.0 | Strudel 1.2.5 / 1.2.6 |
110
+ |---|---|---|
111
+ | Licence | MIT | AGPL-3.0 |
112
+ | Runtime dependencies | 0 | 91 npm packages installed for the 8 packages SAAI's bundle used (M) |
113
+ | Build step | none, plain ES modules | bundler (SAAI shipped a prebuilt bundle) |
114
+ | Engine code, raw | 359,494 B, 39 files in `src/` excl. extras (M) | 2,326,731 B, `strudel.mjs` bundle as SAAI shipped it (M) |
115
+ | Engine code, gzip -9 | 110,292 B (M) | 648,951 B (M) |
116
+ | Extras (`src/extras/`), raw / gzip | 69,832 B / 22,286 B (M) | n/a |
117
+ | Data (`data/`, loaded on demand), raw / gzip | 320,466 B / 32,001 B (M) | included in the bundle |
118
+ | npm package | 181.7 kB packed, 782.5 kB unpacked, 49 files (M) | not compared |
119
+ | Public names | 961: 695 of Strudel's 838, plus 123 RIFF-only (D) | 838 names (1059 name/kind rows) in the inventory (D) |
120
+ | Event fixtures | 1326 recorded, 0 broken; 1175 run, 105 of them compared statistically (random), 46 expected errors (M) | the reference |
121
+ | Exact events (L2), 102 programs | 101 / 102; the miss is one hat 13 µs off (D) | the reference |
122
+ | Sound (L3, ±1 dB etc.), 102 programs | 94 / 102 (D) | the reference |
123
+ | Query speed | 250.7 ms for 1290 corpus programs × 64 cycles, median of 3 (M) | not measured |
124
+
125
+ (M) measured on 18 Nov 2026 on main 254e9a0, Node 24.12. (D) taken from the
126
+ repository docs of the same date: names from `registry.json` and
127
+ `spec/inventory.md`, L2 and L3 from [`docs/parity-report.md`](docs/parity-report.md).
128
+
129
+ How the numbers were taken:
130
+
131
+ - RIFF sizes: the `src/` files (excl. `src/extras/`) concatenated and run
132
+ through Node's `zlib.gzipSync` at level 9; this is unminified source.
133
+ Package size from `npm pack --dry-run`.
134
+ - Strudel size: byte count and the same gzip of the `strudel.mjs` bundle SAAI
135
+ vendored before it switched to RIFF (minified). Bundle and source are not
136
+ the same thing, so read the size rows as orders of magnitude.
137
+ - Strudel dependencies: packages in the npm lockfile that installs
138
+ `@strudel/core`, `mini`, `tonal`, `transpiler`, `draw`, `codemirror`,
139
+ `web` and `superdough` (`tools/similarity/package-lock.json`).
140
+ - Fixtures: `npm test`. Query speed: `npm run bench`. No Strudel benchmark
141
+ was run.
142
+
143
+ ### What RIFF adds
144
+
145
+ - `check(code)` in the extras: finds unknown names (with a "did you mean"),
146
+ mini-notation errors and wrong argument types before playing, as
147
+ diagnostics with line, column, hint and, where safe, a fix
148
+ ([`spec/diagnostics.md`](spec/diagnostics.md)).
149
+ - Errors while playing name the layer and the call site in your code.
150
+ - A layer that throws keeps playing its last good version; the other layers
151
+ are not affected.
152
+ - Late notes: an event at most `lateLimit` late (default 0.1 s) plays with
153
+ its normal attack instead of clicking; later ones are dropped and counted.
154
+ - Phone defaults: on phones a playback latency hint, 48 voices and a 64 MB
155
+ sample budget; desktop keeps 128 voices and 192 MB.
156
+ - `describeFunction` and `listFunctions`: a machine-readable registry of every
157
+ name, used for editor help and LLM prompts.
158
+
159
+ ### Out of scope
160
+
161
+ - MIDI, OSC, serial and CSound output, and Hydra.
162
+ - 144 Strudel names marked "won't" in `spec/inventory.csv`, mostly internal
163
+ helpers not meant for users.
164
+ - Strudel's REPL website, documentation, tutorials and sample packs.
165
+ - Bit-identical audio: sound is compared within tolerances (L3).
166
+
167
+ ## Licence
168
+
169
+ MIT. Copyright (c) 2026 Danny de Zeeuw. See [`LICENSE`](LICENSE).
170
+
171
+ Strudel's function names and syntax are reproduced as an interface only. No
172
+ Strudel code ships in this package.
173
+
174
+ Contributing: implementers must not read Strudel's source code, in any form.
175
+ The rules are in `CONTRIBUTING.md` and `docs/clean-room.md`.
31
176
 
32
177
  ## Test lab
33
178
 
34
179
  `lab/` is a static page for testing RIFF by hand, one item per public name,
35
- grouped by feature area. It is not part of the npm package.
36
-
37
- - **Run:** `npm run lab`, then open <http://localhost:8080/> (`PORT`, `HOST`
38
- override). Health: `/healthz/`, `/readyz/`.
39
- - **Deploy:** the `Dockerfile` builds the lab image (port 8080, user 65532,
40
- read-only root with `--tmpfs /tmp`).
41
- - **How items light up:** an item is `not implemented` until `src/index.js`
42
- exports the name (pattern methods: `Pattern.prototype.<name>`). Then the lab
43
- runs its example and compares cycles with the oracle fixture: `matches`,
44
- `mismatch`, `random (statistical)` or `no fixture`. Play/Stop enable when
45
- RIFF exports `hush` plus `initStrudel`+`evaluate`, `play` or `Pattern.prototype.play`.
46
- - **After a merge** that adds `spec/functions/` or `corpus/functions/`:
47
- `npm run lab:catalog` and commit `lab/catalog.json`. Areas live in `lab/areas.json`.
180
+ grouped by area. It is not in the npm package.
181
+
182
+ - `npm run lab`, then open <http://localhost:8080/> (`PORT`, `HOST` override).
183
+ - Each item runs its example and compares cycles with the oracle fixture:
184
+ `matches`, `mismatch`, `random (statistical)` or `no fixture`.
185
+ - After a merge that adds `spec/functions/` or `corpus/functions/`, run
186
+ `npm run lab:catalog` and commit `lab/catalog.json`.
187
+ - The `Dockerfile` builds the lab image (port 8080, user 65532, read-only root).
188
+
189
+ ## Package contents
190
+
191
+ The npm package holds `src/` (engine plus the optional `src/extras/`),
192
+ `data/`, `docs/clean-room.md`, `LICENSE` and this README. Specs, fixtures,
193
+ tools and the lab stay in the repository.
194
+
195
+ Release: bump `version`, run `npm test` and `npm pack --dry-run`, then
196
+ `npm publish --tag beta`.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zeeuw/riff",
3
- "version": "0.1.0-beta.0",
3
+ "version": "0.1.0-beta.2",
4
4
  "description": "RIFF (Rhythm In Functional Form): a zero-dependency live-coding music engine for the browser, compatible with Strudel code",
5
5
  "license": "MIT",
6
6
  "author": "Danny de Zeeuw",