@zeeuw/riff 0.0.0-stage → 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 (49) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +195 -2
  3. package/data/registry-data.js +3 -0
  4. package/data/signatures.js +3 -0
  5. package/docs/clean-room.md +450 -0
  6. package/package.json +69 -4
  7. package/src/audio/clock.js +383 -0
  8. package/src/audio/engine.js +678 -0
  9. package/src/audio/index.js +394 -0
  10. package/src/audio/offline.js +73 -0
  11. package/src/audio/params.js +397 -0
  12. package/src/audio/samples.js +274 -0
  13. package/src/audio/unlock.js +70 -0
  14. package/src/audio/voices.js +44 -0
  15. package/src/combinators.js +150 -0
  16. package/src/compat.js +16 -0
  17. package/src/constructors.js +236 -0
  18. package/src/controls.js +199 -0
  19. package/src/draw.js +252 -0
  20. package/src/euclid.js +57 -0
  21. package/src/evaluate.js +251 -0
  22. package/src/extras/check.js +678 -0
  23. package/src/extras/describe.js +433 -0
  24. package/src/extras/editor.js +369 -0
  25. package/src/extras/index.js +10 -0
  26. package/src/fraction.js +300 -0
  27. package/src/hap.js +64 -0
  28. package/src/helpers.js +68 -0
  29. package/src/index.js +74 -0
  30. package/src/mini/index.js +36 -0
  31. package/src/mini/parser.js +400 -0
  32. package/src/ops.js +293 -0
  33. package/src/outline.js +175 -0
  34. package/src/pattern.js +365 -0
  35. package/src/random.js +344 -0
  36. package/src/register.js +83 -0
  37. package/src/registry.js +52 -0
  38. package/src/samples.js +14 -0
  39. package/src/sampling.js +123 -0
  40. package/src/scope.js +77 -0
  41. package/src/signals.js +76 -0
  42. package/src/stepwise.js +150 -0
  43. package/src/structure.js +636 -0
  44. package/src/time.js +70 -0
  45. package/src/tonal.js +583 -0
  46. package/src/transforms.js +125 -0
  47. package/src/transpile.js +394 -0
  48. package/src/util.js +80 -0
  49. package/src/visuals.js +216 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Danny de Zeeuw
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,196 @@
1
- # Temporary Holding Version
1
+ # RIFF — Rhythm In Functional Form
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.
7
+
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`).
14
+
15
+ ## Install
16
+
17
+ ```sh
18
+ npm install @zeeuw/riff@beta
19
+ ```
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
+
56
+ ```js
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>
75
+ ```
76
+
77
+ ## How it came to be
78
+
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`.
176
+
177
+ ## Test lab
178
+
179
+ `lab/` is a static page for testing RIFF by hand, one item per public name,
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`.