@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.
- package/README.md +178 -29
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,10 +1,16 @@
|
|
|
1
1
|
# RIFF — Rhythm In Functional Form
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
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
|
-
|
|
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 {
|
|
17
|
-
|
|
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
|
-
##
|
|
77
|
+
## How it came to be
|
|
21
78
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
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
|
|
36
|
-
|
|
37
|
-
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
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.
|
|
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",
|