tutticode 0.2.1 → 0.3.0

package/README.md

@@ -12,8 +12,7 @@ tuttidaw.com/code, so a file sounds exactly like the editor. Nothing is
 rendered on a server and it costs nothing. Every result carries an `editUrl`
 that opens the program in TuttiDAW to keep editing.
 
-Once TuttiDAW switches its limits on (they are being rolled out; until then
-no render is cut or tagged), renders without an account are limited to 60 s,
+Renders without an account are limited to 60 s,
 and renders over 30 s carry a spoken "register at TuttiDAW" tag. A free
 account lifts both:
 `tutticode login` (renders up to 5 minutes, no tag). See
@@ -74,6 +73,17 @@ clipping"). `--lufs` applies one static gain; when the true-peak ceiling
 cannot be met the render fails with `clip`, unless you add `--limit`: a
 true-peak limiter on the mix (not the stems), reported as `limitDb`.
 
+A program can be a whole song (up to 128 bars): each track's sound once, each
+section's content in one block, the order in a form. `render` renders one
+pass of the form by default.
+
+```js
+track("bass").inst("Drift:Deep Bass").mix({vol: -3})
+section("verse", 8, { drums: s("bd ~ sd ~, hh*8"), bass: note("<c2 eb2>*4") })
+section("chorus", 8, { drums: s("bd sd bd sd, hh*16"), bass: note("<c2 ab1>*8") })
+form("verse chorus verse chorus")
+```
+
 `--json` prints the render report: length, bars, tempo, loudness and true
 peak, the gain applied, per-voice levels, the bar and beat grid (seconds, for
 syncing cuts), the check report, the analysis, the `editUrl` and the written
@@ -107,9 +117,8 @@ The reference documents are also MCP resources (`tutticode://skills/...`).
 
 ## Sign-in and limits
 
-The limits below apply once TuttiDAW switches them on (they are being rolled
-out; until then every render runs in full and untagged). The sign-in works
-today.
+TuttiDAW enforces the limits below. A CLI older than 0.2.1 is refused with
+error `upgrade` (exit 6): update it with `npm i -g tutticode`.
 
 | | Without sign-in | Free account |
 | --- | --- | --- |

package/README.zh-CN.md

@@ -10,7 +10,7 @@ MCP server,适用于 Claude Code、Copilot CLI、Codex、Cursor、Claude Desktop
 文件和编辑器里听到的一模一样。不经过服务器渲染,也不收费。每个结果都带一个
 `editUrl`,可以在 TuttiDAW 里打开这段程序继续编辑。
 
-TuttiDAW 启用限制后(正在逐步上线;在此之前渲染既不截断也不加标签),不登录时每次渲染最长 60 秒,超过 30 秒的渲染会混入一段语音标签
+不登录时每次渲染最长 60 秒,超过 30 秒的渲染会混入一段语音标签
 "register at TuttiDAW"。用免费账号登录(`tutticode login`)就没有这些限制:
 每次最长 5 分钟,没有语音标签。见[登录与限制](#登录与限制)。
 
@@ -63,6 +63,16 @@ cat song.tc | tutticode check -             # 从 stdin 读程序
 偷偷加限制器;需要时加 `--limit`:对混音(不含分轨)加 true peak 限制器,
 报告里的 `limitDb` 是它最多压下的量。
 
+程序可以是一整首歌(最长 128 小节):每条轨道的音色写一次,每个段落的内容写在一个块里,
+顺序写在 form 里。`render` 默认渲染整个曲式一遍。
+
+```js
+track("bass").inst("Drift:Deep Bass").mix({vol: -3})
+section("verse", 8, { drums: s("bd ~ sd ~, hh*8"), bass: note("<c2 eb2>*4") })
+section("chorus", 8, { drums: s("bd sd bd sd, hh*16"), bass: note("<c2 ab1>*8") })
+form("verse chorus verse chorus")
+```
+
 `--json` 输出渲染报告:时长、小节数、速度、响度和 true peak、施加的增益、每个
 声部的电平、小节和拍的时间点(秒,用来对齐剪辑点)、检查报告、分析结果、
 `editUrl` 和写出的文件路径。永远不会把音频打印到终端。
@@ -93,8 +103,8 @@ TuttiCode" 元数据;仅登录后有效。
 
 ## 登录与限制
 
-下面的限制在 TuttiDAW 启用后生效(正在逐步上线;在此之前每次渲染都完整、不加标签)。
-登录现在就能用。
+TuttiDAW 已经启用下面的限制。低于 0.2.1 的 CLI 会被拒绝,报错 `upgrade`(退出码 6):
+用 `npm i -g tutticode` 升级。
 
 | | 不登录 | 免费账号 |
 | --- | --- | --- |

package/dist/skills/tutticode/SKILL.md

@@ -39,10 +39,10 @@ _lead: n("0 2 4 7").scale("C:minor")         // a leading _ mutes a voice
   `.range(a, b)` `.slow(n)` `.segment(n)`.
 - TuttiDAW only: `.inst("Device:Preset", {key: value})` instrument,
   `.midifx(...)` before it, `.fx(...)` after it, in call order. Params use the
-  device's keys and units (`"4s"`, `"-6dB"`, `"1/16"`); constants only for now.
-  Mixing: `bus("verb").fx("Reverb")` + `.send("verb", -12)`, `.mix({vol, pan,
-  mute})`, `master.fx("Limiter")`, `group("drums")` + `.group("drums")`.
-  `toggle(1)` is an inline switch; `note("do re mi")` = `note("c d e")`.
+  device's keys and units (`"4s"`, `"-6dB"`, `"1/16"`); a pattern automates.
+  Mixing: voices sharing a reverb/delay get one `bus("verb").fx("Reverb", {dryWetBalance: 1})` and a `.send("verb", -12)` each,
+  not an `.fx`/`.room` per voice; `.mix({vol, pan, mute})`; finish a piece with `master.fx("Limiter")`; `group("drums")` + `.group("drums")`.
+  `toggle(1)` is an inline switch; `note("do re mi")` = `note("c d e")`; `ensembleSet({reverb: {revSize: 100}})` sets the Ensemble Sets' buses/master.
 
 ## Top mistakes
 
@@ -55,8 +55,8 @@ _lead: n("0 2 4 7").scale("C:minor")         // a leading _ mutes a voice
    `"A:minor:pentatonic"`. `"C:harmonic minor"` is two steps.
 4. **Device calls inside callbacks** fail: `every(2, x => x.fx(...))` is an
    error; a voice has one chain. Put `.inst/.fx/.midifx` on the voice.
-5. **Patterned device params** (`{cutoff: "<300 900>"}`) are not applied
-   yet; use Strudel controls (`.lpf("<300 900>")`) for movement.
+5. **Automation**: `.mix({vol: ramp(-60, 0, 4)})` fades over 4 bars (`.once()`: no loop); `env("0:200 2:4000~.5 _4:0")`
+   is points pos:value (`~k` curve, `_` step); patterns `"<300 900>"` step. On a bus/group/master: Arrangement lanes.
 6. **One `.inst` per voice**; a second is an error. Use another voice.
 7. **Single vs double quotes**: double quotes are mini-notation; single
    quotes are plain strings (`register('name', ...)`, `.scale('C minor')`).
@@ -75,7 +75,7 @@ The same tools and report shapes run on two backends; prefer the local one.
 - **Local `tutticode`** (default; free): the `tutticode` CLI
   and MCP server (`npm i -g tutticode`, `tutticode mcp`) render in the
   user's own browser with the tuttidaw.com/code engine and write files to
-  disk, up to 300 s (60 s without sign-in once the limits are on, below). Its tool descriptions
+  disk, up to 300 s (60 s without sign-in, below). Its tool descriptions
   say "Runs locally". Without MCP,
   call the CLI: `tutticode check prog.tc`, `tutticode render prog.tc -o
   out.wav --seconds 12 --lufs -16 --json`, `tutticode open prog.tc`.
@@ -95,8 +95,7 @@ The same tools and report shapes run on two backends; prefer the local one.
 | `code_reference` | (local) search these references |
 | `code_account` | (local) signed in or not, the length limits, today's usage |
 
-**Without sign-in**, once the limits are on (until then nothing is cut or
-tagged), local renders stop at 60 s (error `limit`) and over 30 s carry a
+**Without sign-in**, local renders stop at 60 s (error `limit`) and over 30 s carry a
 spoken "register at TuttiDAW" tag (`watermark`; never edit code to remove it).
 Tell the user once; `tutticode login` (free) lifts both. Agents: run
 `tutticode login --device --no-wait --json` and give the user its link.
@@ -132,18 +131,19 @@ Read only what the task needs:
 - `references/mini-notation.md`: Mini-notation. The rhythm language inside the quotes - sequences, rests, groups, alternation, polymeter, Euclidean rhythms and chance.
 - `references/time-and-structure.md`: Time and structure. Functions that speed up, shift, reverse, repeat and combine patterns, and arrange them into sections.
 - `references/harmony-and-scales.md`: Harmony and scales. Note names and octaves, scale degrees, transposition, chord symbols, voicings and arpeggios.
-- `references/melodies-with-do-re-mi.md`: Melodies with do re mi. Write notes in solfège (do re mi fa sol la si) wherever a note name goes; strudel.cc gets letters.
+- `references/melodies-with-do-re-mi.md`: Melodies with do re mi. Write notes in solfège (do re mi fa sol la si) wherever a note name goes; Export to Strudel gives letters.
 - `references/sounds.md`: Sounds. Drum kits and banks, synth waveforms, General MIDI instrument names, Ensemble sounds and your own samples.
 - `references/effect-controls.md`: Effect controls. Filters, reverb, delay, distortion, panning, envelopes and synth controls - and moving them with signals.
 - `references/sample-operations.md`: Sample operations. Play part of a sample, change its speed, cut it into slices, fit it to the tempo and choke it.
 - `references/tuttidaw-extensions.md`: TuttiDAW extensions. Load any TuttiDAW instrument, MIDI effect or audio effect with presets and parameters; voices, groups and Open in TuttiDAW.
-- `references/mixing.md`: Mixing: buses and master. Shared reverbs and delays on buses, sends from the voices, each voice's fader and pan, and the program's master chain - the same tracks Open in TuttiDAW makes.
+- `references/automation.md`: Automation. Fades with ramp(), points and curves with env(), patterns and signals - device parameters, faders and sends that move over time, as the same automation Open in TuttiDAW shows.
+- `references/mixing.md`: Mixing: buses and master. Shared reverbs and delays on buses, sends from the voices, each voice's fader and pan, sidechain ducking, and the program's master chain - the same tracks Open in TuttiDAW makes.
 - `references/mixing-groups.md`: Mixing: groups. Put voices in a group with its own effects, fader and sends - a drum bus inside the program, the same group track Open in TuttiDAW makes.
 - `references/javascript.md`: JavaScript in code. Variables, functions, loops and register - and the sandbox, determinism and limits that keep shared code safe.
 - `references/muse.md`: Muse on /TuttiCode. Ask TuttiDAW's AI assistant to write, explain, fix or restyle your program, from text, a Strudel tune, a screenshot or a reference track.
 - `references/for-agents.md`: TuttiCode for agents. Let Claude Code, Copilot, Codex or any MCP client write TuttiCode and render it to audio files in your own browser, with the tutticode CLI, MCP server and skills.
-- `references/functions.md`: every function, method and signal, with signature, description and example (generated from the engine).
+- `references/functions.md`: every function, method and signal, with signature, description and example; `references/language-reference.md`: the full EBNF grammar, typed signatures, control aliases (both generated from the engine).
 - `references/devices.md`: every instrument and effect for `.inst/.fx/.midifx`, with `references/devices/<id>.md` per device: param keys, ranges, units, presets (generated from the device catalogue).
 
-Language: PATTERN LANGUAGE 1.3.0, engine 17.
+Language: PATTERN LANGUAGE 1.9.0, engine 23.
 Human guide: https://tuttidaw.com/code/learn; agents: https://tuttidaw.com/code/learn/for-agents

package/dist/skills/tutticode/references/agent-loop.md

@@ -91,10 +91,8 @@ or mute (`_`) the voices you are not listening to.
 
 ## Sign-in, limits and the voice tag (*local*)
 
-- **Limits.** Once TuttiDAW switches them on (they are being rolled out;
-  until then no render is cut or tagged), a render without sign-in is at
-  most 60 s, and a render over 30 s carries a spoken "register at
-  TuttiDAW" tag throughout. A free account (`tutticode login`) lifts both. `code_account` (or `tutticode
+- **Limits.** A render without sign-in is at most 60 s, and a render
+  over 30 s carries a spoken "register at TuttiDAW" tag throughout. A free account (`tutticode login`) lifts both. `code_account` (or `tutticode
   whoami --json`) says which applies (`limits.maxSeconds`,
   `limits.watermarkAfterSeconds`, null = never tagged): plan within it,
   for example keep an anonymous draft at 30 s or less.
@@ -130,6 +128,21 @@ or mute (`_`) the voices you are not listening to.
 `jazz-swing` and others); a render without a master chain sits a few LU
 under a style's mastered loudness, so match its spectrum first.
 
+A program mixes itself: shared effects on a bus the voices send to, levels
+with `.mix`, and the program's own master chain, which every render goes
+through. A limiter there lets a `lufs` target fit under the ceiling
+without `limit: true`:
+
+```js
+bus("verb").fx("Reverb", {dryWetBalance: 1})
+master.fx("Limiter", {gainDb: 3, ceiling: -3})
+drums: s("bd*4, ~ cp, hh*8").bank("tr909").mix({vol: -3})
+keys: chord("<Cm7 Fm7>").voicing().inst("Electric").send("verb", -10)
+```
+
+`group("drums")` + `.group("drums")` gives several voices one fader and
+chain. `note("do re mi")` is `note("c d e")` (fixed do).
+
 ## Comparing
 
 `code_compare` returns `deltas[]` (`metric`, `current`, `target`,

package/dist/skills/tutticode/references/automation.md

@@ -0,0 +1,168 @@
+# Automation
+
+Fades with ramp(), points and curves with env(), patterns and signals - device parameters, faders and sends that move over time, as the same automation Open in TuttiDAW shows.
+
+A device parameter does not have to stay put. Give it a **pattern** and it
+changes from cycle to cycle; give it a **signal** and it sweeps. This is
+automation, written in code: "Open in TuttiDAW" shows it as an envelope on
+the voice's clip, and the voice plays it the same way on /code.
+
+| Value | What the device gets |
+|---|---|
+| `0.4`, `"4s"`, `slider(0.4)` | a setting that stays |
+| `ramp(-60, 0, 4)` | a straight line from -60 to 0 over 4 bars, then again |
+| `env("0:200 2:4000~.5 4:200")` | points joined by lines and curves |
+| `"<0.1 0.6>"`, `"0 0.5 1 0.5"` | a step at each event: the value holds until the next one |
+| `sine.range(300, 3000)` | a smooth sweep, sampled 16 times per cycle |
+
+Like `.inst`, `.fx` and `.midifx` themselves, this is TuttiDAW-only.
+
+## Fades: ramp
+
+`ramp(from, to, bars)` is a straight line from one value to another over
+a number of bars. A fade-in on the kick's fader, over four bars:
+
+```js
+kick: s("bd*4").mix({vol: ramp(-60, 0, 4)})
+```
+
+The ramp then starts again, like a pattern loops. Add `.once()` and it
+plays once from the start of the program, then holds its last value:
+
+```js
+pad: note("<c3 eb3 g3 bb3>").s("sawtooth").release(0.3)
+  .mix({vol: ramp(-60, -6, 8).once()})
+```
+
+The program's loop grows to cover a ramp or an envelope (here 8 bars), so
+on /code you hear all of it.
+
+## Points, lines and curves: env
+
+`env("...")` draws any shape as points `position:value`, joined by
+straight lines. Positions are in bars (`1.5`, `3/4`); values are in the
+parameter's unit, units allowed (`"-6dB"`, `"2kHz"`):
+
+```js
+pad: note("c3").s("sawtooth")
+  .fx("Auto Filter", {frequency: env("0:200 2:4000~.5 4:200")})
+```
+
+| Written | Means |
+|---|---|
+| `2:4000` | at bar 2 the value is 4000; a straight line leads there |
+| `2:4000~.5` | the segment ending there bends (`-1..1`; positive stays near the start longer, like the studio's curve) |
+| `_2:4000` | hold the value before until bar 2, then jump |
+| `2:0 2:1` | two points at one position: a jump |
+
+The envelope loops over its last position. A second argument makes the loop
+longer: `env("0:0 2:1", 4)` rises for two bars and holds for two. Before
+its first point it holds the first value.
+
+## The exact form
+
+The studio can also store a curve drawn as a Bezier (Live's curve handles).
+Code writes it as a list of points, each `[position, value]` with an
+optional segment: `{curve: k}`, `{curve: [x1, y1, x2, y2]}` or `"hold"`:
+
+```js
+lead: note("c4 eb4 g4").s("sawtooth")
+  .mix({pan: env([[0, -1], [2, 1, {curve: [0.2, 0, 0.8, 1]}], [4, -1, "hold"]])})
+```
+
+You rarely write this by hand: "Copy as TuttiCode code" in the studio
+writes the shortest form that keeps the automation exactly - a `ramp`,
+an `env` string, or this list.
+
+## A wetter reverb every other bar
+
+`"<0.1 0.6>"` is 0.1 in the first cycle and 0.6 in the second:
+
+```js
+pad: note("<c3 eb3 g3 bb3>").s("sawtooth").release(0.3)
+  .fx("Reverb", {dryWetBalance: "<0.1 0.6>", decayTime: "3s"})
+```
+
+`decayTime` is a constant, so it stays at 3 seconds. Several parameters
+of one device can move at once, each with its own pattern.
+
+## A filter sweep
+
+A signal moves continuously. `sine.range(300, 3000)` goes from 300 Hz up to
+3000 Hz and back once a cycle; `.slow(4)` stretches that over four:
+
+```js
+bass: note("c2*8").s("sawtooth")
+  .fx("Auto Filter", {frequency: sine.range(300, 3000).slow(4)})
+```
+
+The program then loops after four cycles, like any pattern that changes
+over four.
+
+## Units, instruments and MIDI effects
+
+Patterns take the same values as constants, in the parameter's unit:
+strings with a unit convert (`"<-6dB 0dB>"`, `"<1s 4s>"`). Instrument
+parameters automate too:
+
+```js
+lead: note("c4 eb4 g4 bb4").inst("Drift", {cutoff: "<400 1200 2400 800>"})
+  .fx("Utility", {gainDb: "<-6dB 0dB>"})
+```
+
+A choice parameter steps between its names. Arpeggiator's rate names
+(`1/16`, `1/8`) read as names inside a pattern, not as a division:
+
+```js
+arp: note("[c3,e3,g3]").midifx("Arpeggiator", {style: "<Up Down>", rate: "<1/16 1/8>"})
+```
+
+Names with spaces (`"Up & Down"`) cannot be steps of a pattern: use their
+index. A percentage (`"30%"`) works as a constant only, because `%` means
+something else in mini-notation - write `0.3` in a pattern.
+
+## Buses, groups and the master
+
+A bus, a group and the master move the same way: their `.mix({vol, pan})`,
+a group's `.send(bus, level)` and their devices' parameters take patterns
+and signals too.
+
+```js
+bus("verb").fx("Reverb", {dryWetBalance: 1, decayTime: "<2s 6s>"})
+  .mix({vol: sine.range(-18, -6).slow(4)})
+group("drums").fx("Drum Buss", {drive: "<0 20>"}).send("verb", "<-30 -12>")
+master.mix({vol: "<0 -3>"})
+
+kick: s("bd*4").group("drums")
+pad:  note("<c3 eb3>").s("sawtooth").release(0.3).send("verb", -6)
+```
+
+These tracks have no clip of their own, so "Open in TuttiDAW" writes their
+automation into the **Arrangement**: on the return track, the drums group
+and the program's group (the master), one copy per loop across the span
+the voice clips cover. Lengthen the clips and evaluate again: the
+automation follows. The points the code wrote are the code's - edit one
+and that bus, group or master is detached (Re-attach brings the code back).
+Points you draw before or after that span are yours: the code never
+touches them.
+
+## What cannot move
+
+- **Static settings** take a constant: an Ensemble part's `voice` or filter
+  type. A pattern there is an error that lists the parameters that can move.
+- A pattern of names for the device itself (`.fx("<Reverb Delay>")`) is an
+  error: a voice has one chain.
+
+## In the studio
+
+The envelope belongs to the code, like the voice's other values: an
+evaluate rewrites it, and the device shows the pattern's first value.
+`ramp` and `env` arrive as real points with their curves, editable like
+any envelope. One as long as the voice's clip loops with the clip; a
+longer or shorter one is an unlinked clip envelope with its own loop, and
+a `.once()` one an unlinked envelope with its loop switched off. Edit
+the envelope by hand and the voice is detached from the code (Re-attach
+brings the code back). An envelope holds at most 1024 points; a pattern
+that changes more often is held on a coarser grid, with a warning.
+
+Source: https://tuttidaw.com/code/learn/automation

package/dist/skills/tutticode/references/devices/compressor.md

@@ -35,6 +35,8 @@ Accepted names: `compressor`.
 | `sideListen` | S/C Listen | `true` / `false` |
 | `lookahead` | Lookahead | `0 ms` `1 ms` `10 ms` |
 
+Sidechain: `sidechain: "kick"` keys it by the voice labelled `kick:`, `"bus:verb"` by the bus `verb` and `"group:drums"` by the group `drums` of the program. `sidechainGain` (dB) sets how loud the source is to it; `sidechainFilter` (a frequency, e.g. `"150Hz"`, or `false`) lets only the source's lows key it.
+
 ## Factory presets
 
 Acoustic · Acoustic Kick · Gentle Glue · Vocal Leveler

package/dist/skills/tutticode/references/devices/filter.md

@@ -50,6 +50,8 @@ Accepted names: `autofilter`, `filter`.
 | `envSahRate` | Env S&H Rate | -6 .. 0 |
 | `djControl` | Control | -1 .. 1 |
 
+Sidechain: `sidechain: "kick"` keys it by the voice labelled `kick:`, `"bus:verb"` by the bus `verb` and `"group:drums"` by the group `drums` of the program. `sidechainGain` (dB) sets how loud the source is to it; `sidechainFilter` (a frequency, e.g. `"150Hz"`, or `false`) lets only the source's lows key it.
+
 ## Factory presets
 
 Auto Filter Sweep · Auto Wah · Low Cut

package/dist/skills/tutticode/references/devices/gate.md

@@ -31,6 +31,8 @@ Accepted names: `gate`.
 | `lookahead` | Lookahead | `0 ms` `1 ms` `10 ms` |
 | `scFilterMode` | SC EQ Mode | `Low Shelf` `Bell` `High Shelf` `Low Pass` `Band Pass` `High Pass` |
 
+Sidechain: `sidechain: "kick"` keys it by the voice labelled `kick:`, `"bus:verb"` by the bus `verb` and `"group:drums"` by the group `drums` of the program. `sidechainGain` (dB) sets how loud the source is to it; `sidechainFilter` (a frequency, e.g. `"150Hz"`, or `false`) lets only the source's lows key it.
+
 ## Factory presets
 
 Drum Gate · Flipside · Soft Cleanup

package/dist/skills/tutticode/references/devices/glue.md

@@ -31,6 +31,8 @@ Accepted names: `gluecompressor`, `glue`.
 | `scFilterOn` | S/C EQ On | `true` / `false` |
 | `scOn` | S/C On | `true` / `false` |
 
+Sidechain: `sidechain: "kick"` keys it by the voice labelled `kick:`, `"bus:verb"` by the bus `verb` and `"group:drums"` by the group `drums` of the program. `sidechainGain` (dB) sets how loud the source is to it; `sidechainFilter` (a frequency, e.g. `"150Hz"`, or `false`) lets only the source's lows key it.
+
 ## Factory presets
 
 Drum Buss Glue · Gentle Mix Bus · Parallel Crush

package/dist/skills/tutticode/references/devices/multibanddynamics.md

@@ -57,6 +57,8 @@ Accepted names: `multibanddynamics`.
 | `bands.2.attackMs` | High Attack | 0.1 .. 5000 ms (log) |
 | `bands.2.releaseMs` | High Release | 0.1 .. 5000 ms (log) |
 
+Sidechain: `sidechain: "kick"` keys it by the voice labelled `kick:`, `"bus:verb"` by the bus `verb` and `"group:drums"` by the group `drums` of the program. `sidechainGain` (dB) sets how loud the source is to it; `sidechainFilter` (a frequency, e.g. `"150Hz"`, or `false`) lets only the source's lows key it.
+
 ## Factory presets
 
 De-Mud Upward Low · Gentle Multiband Glue · Multiband Expander

package/dist/skills/tutticode/references/devices.md

@@ -77,8 +77,8 @@ ranges and units.
 | [Drum Buss](devices/drumbuss.md) | available | 3 | 11 |
 | [Dynamic Tube](devices/dynamic-tube.md) | available | 2 | 8 |
 | [Echo](devices/echo.md) | tested end to end | 5 | 38 |
-| Ensemble Bus | not available in code yet: an Ensemble Set's buses come in a later version | 0 | 7 |
-| Ensemble Master | not available in code yet: an Ensemble Set's master comes in a later version | 0 | 25 |
+| Ensemble Bus | not available in code: an Ensemble Set's buses are set with ensembleSet({...}) | 0 | 9 |
+| Ensemble Master | not available in code: an Ensemble Set's master is set with ensembleSet({...}) | 0 | 26 |
 | Envelope Follower | not available in code yet: modulators need mapping targets, which come in a later version | 5 | 8 |
 | [EQ Eight](devices/eqeight.md) | tested end to end | 3 | 51 |
 | [EQ Three](devices/eqthree.md) | available | 2 | 9 |

package/dist/skills/tutticode/references/effect-controls.md

@@ -41,6 +41,10 @@ s("~ cp ~ cp").room(0.6).size(4)
 note("<c4 eb4> ~ ~ ~").s("triangle").delay(0.5).delaytime(3/16).delayfeedback(0.55)
 ```
 
+`.room` and `.delay` give each voice its own reverb or echo. For one reverb
+shared by several voices, so they sound like one room, use a bus and send to
+it: see [Mixing](mixing.md).
+
 ## Drive and lo-fi
 
 `.shape(0..1)` and `.distort(...)` add drive; `.crush(bits)` reduces the bit
@@ -63,6 +67,10 @@ note("c3 eb3 g3 bb3").s("square").crush(5)
 s("hh*8").pan("0 1 0.25 0.75").gain(0.7)
 ```
 
+To set a voice's level and pan on its track's fader instead, the way you
+balance a mix, use `.mix({vol: -6, pan: -0.3})` (vol in dB): see
+[Mixing](mixing.md).
+
 ## Modulation effects
 
 `.phaser(rate)` and `.chorus(amount)` add movement; `.compressor(...)`

package/dist/skills/tutticode/references/first-sounds.md

@@ -45,6 +45,8 @@ s("bd*2 [~ bd] sd ~, hh*8").bank("tr909")
 
 `note` plays pitches. Write note names (`c`, `d`, `eb`, `f#`) with an octave
 number, or MIDI numbers.
+Solfège works too: `note("do re mi")` plays `c d e` (see
+[Melodies with do re mi](melodies-with-do-re-mi.md)).
 
 ```js
 note("c3 eb3 g3 bb3")

package/dist/skills/tutticode/references/for-agents.md

@@ -41,8 +41,8 @@ a target or an earlier render). Only where the audio is made differs:
 
 - **tutticode on your computer** (the default): renders in your own browser
   and writes the files to your disk. Free, up to 5 minutes of audio per
-  render with a free account (`tutticode login`); without sign-in, once the
-  limits are switched on (being rolled out), up to 60 seconds, and renders
+  render with a free account (`tutticode login`); without sign-in, up to
+  60 seconds, and renders
   over 30 seconds carry a spoken "register at TuttiDAW" tag. It also offers `code_open` (open a program here for you to hear),
   `code_reference` (search the language reference) and `code_account`
   (signed in or not, and the limits).
@@ -75,6 +75,32 @@ You get `riser.wav`, its loudness and true peak, and an `editUrl` that
 opens the program here, so you can listen, change it and render it again
 yourself. Press play above to hear what the agent made.
 
+## Example: a bed that mixes itself
+
+For music with several voices the agent mixes in the code, as in the
+[Mixing](mixing.md) lesson: one shared reverb on a bus that the voices send
+to, each voice's level with `.mix`, and a limiter on the `master` so the
+loudness target fits under the peak ceiling:
+
+```js
+setcpm(15) // 60 BPM
+bus("verb").fx("Reverb", {dryWetBalance: 1, decayTime: "4s"})
+master.fx("Limiter", {gainDb: 3, ceiling: -3})
+drone: note("c2").s("sawtooth").lpf(300).attack(1).release(1).mix({vol: -6}).send("verb", -18)
+strings: chord("<Cm Ab>").voicing().s("supersaw").attack(2).release(2).lpf(1200).mix({vol: -10}).send("verb", -4)
+pulse: note("c6*8").s("sine").decay(0.1).sustain(0).mix({vol: -8}).send("verb", -14)
+```
+
+```sh
+tutticode render tension.tc -o tension.wav --loops 3 --tail 3 --fade-out 4 --lufs -18 --json
+```
+
+Each voice's `lufs` in the report (`voices`) says whether the balance is
+what the agent meant; it changes a `.mix` or a `.send` and renders again.
+Drums can share one fader with `group("drums")` and `.group("drums")`
+([Mixing: groups](mixing-groups.md)), and melodies can be written as
+`note("do re mi")` ([Melodies with do re mi](melodies-with-do-re-mi.md)).
+
 ## Privacy
 
 tutticode renders on your computer: the program goes from the agent to the

package/dist/skills/tutticode/references/functions.md

@@ -64,9 +64,36 @@ Sets chord symbols; also available as .chord(symbols) or .chord().
 chord("<Bbm9 Fm9>/4").dict("ireal").voicing()
 ```
 
+### `ensembleSet(sections)` *(TuttiDAW only)*
+
+TuttiDAW extension, not in Strudel: sets the shared effects of the program's Ensemble Sets (the Sets its .inst("Ensemble:...") voices play in): the Chorus, Delay and Reverb buses and the Set's master, in the devices' own values; once per program, constants only.
+
+```js
+ensembleSet({reverb: {revType: "HALL", revSize: 100}, delay: {dlyTime: "1/8D", dlyFdbk: 40}})
+flute: note("g4 a4 c5 d5").inst("Ensemble:Sample FLUTE", {rev: 60})
+```
+
+### `env(points, bars?)` *(TuttiDAW only)*
+
+TuttiDAW extension, not in Strudel: automation as points "position:value" (positions in bars), joined by straight lines and looped over the last position (or bars); ~k (-1..1) bends the segment ending at a point, _ before a position holds until it, two points at one position jump. A list [[position, value, segment]] is the exact form.
+
+```js
+pad: note("c3").fx("Auto Filter", {frequency: env("0:200 4:4000~.5 8:200")})
+```
+
+### `form(order)` *(TuttiDAW only)*
+
+TuttiDAW extension, not in Strudel: the order the section(...) blocks play in, once per program: section names in order, [..] to group, !n to repeat, name@n for the bars of that one occurrence. The whole form is the program loop (up to 128 bars on TuttiCode).
+
+```js
+section("verse", 8, {drums: s("bd ~ sd ~")})
+section("chorus", 8, {drums: s("bd sd bd sd")})
+form("[verse chorus]!2 verse@4")
+```
+
 ### `group(name)` *(TuttiDAW only)*
 
-TuttiDAW extension, not in Strudel: declares a group, a group track inside the program; give it .fx(...), .mix(...) and .send(bus, dB), and put voices in it with .group(name).
+TuttiDAW extension, not in Strudel: declares a group, a group track inside the program; give it .fx(...), .mix(...) and .send(bus, dB). On a voice, .group(name) puts its track in that group (a name the program does not declare is a warning).
 
 ```js
 group("drums").fx("Drum Buss").mix({vol: -3})
@@ -123,6 +150,14 @@ One event per cycle with the value.
 note(pure(60))
 ```
 
+### `ramp(from, to, bars)` *(TuttiDAW only)*
+
+TuttiDAW extension, not in Strudel: a straight line from one value to another over a number of bars, then again (a loop); as a mixer level, a send or a device param it is automation with real points. Add .once() to play it once and hold the end.
+
+```js
+kick: s("bd*4").mix({vol: ramp(-60, 0, 4)})
+```
+
 ### `register(name, fn)`
 
 Defines a new method (and a function) from your own code; the pattern comes last.
@@ -156,6 +191,16 @@ Declares external sample references; browser consumers load audio explicitly.
 samples('github:user/repo')
 ```
 
+### `section(name, bars, tracks?)` *(TuttiDAW only)*
+
+TuttiDAW extension, not in Strudel: a section of a song - everything each track plays in it, in one block. Each pattern starts at the section's first bar and loops in it; a track it does not list is silent there. "verse#2" changes only the second verse (the tracks it lists). Sections play in form(...) order, else in the order they are written.
+
+```js
+section("verse", 16, {drums: s("bd ~ sd ~, hh*8"), bass: note("<c2 eb2 g1 bb1>*4")})
+section("chorus", 16, {drums: s("bd sd bd sd, hh*16"), bass: note("<c2 ab1>*8")})
+form("verse chorus verse chorus")
+```
+
 ### `seq(...patterns)`
 
 Squeezes all patterns into one cycle, one after another.
@@ -263,6 +308,15 @@ A value pattern with an inline on/off control (Tutti extension, not in Strudel).
 note("60 64").mask(toggle(1))
 ```
 
+### `track(name)` *(TuttiDAW only)*
+
+TuttiDAW extension, not in Strudel: declares a track of a song with sections and its sound, once - give it .inst(...), .fx(...), .midifx(...), .mix(...), .send(bus, dB) and .group(name). What it plays goes in the section(...) blocks; a track no section lists plays nothing.
+
+```js
+track("bass").inst("Drift:Deep Bass").mix({vol: -3})
+section("verse", 8, {bass: note("<c2 eb2>*4")})
+```
+
 ## Methods
 
 ### `.accelerate(amount?)`
@@ -795,10 +849,10 @@ note("c2 eb2 g2").s("sawtooth").lpf(500).lpenv(4).ftype("<0 1 2>")
 
 ### `.fx(name, params?)` *(TuttiDAW only)*
 
-TuttiDAW extension, not in Strudel: adds an audio effect after the instrument of the voice, in call order.
+TuttiDAW extension, not in Strudel: adds an audio effect after the instrument of the voice, in call order; patterns automate params.
 
 ```js
-note("c4 e4").fx("Reverb:Large Hall", {decayTime: "4s"})
+note("c4 e4").fx("Auto Filter", {frequency: sine.range(300, 3000).slow(4)})
 ```
 
 ### `.gain(level?)`
@@ -883,7 +937,7 @@ note("c d e f").inside(2, rev)
 
 ### `.inst(name, params?)` *(TuttiDAW only)*
 
-TuttiDAW extension, not in Strudel: plays the voice on a TuttiDAW instrument ("Device" or "Device:Preset"), params in the device units.
+TuttiDAW extension, not in Strudel: plays the voice on a TuttiDAW instrument ("Device" or "Device:Preset"), params in the device units; patterns automate params.
 
 ```js
 note("c2 eb2").inst("Drift:Deep Bass", {cutoff: 600})
@@ -1059,7 +1113,7 @@ note("[c3,e3,g3]").midifx("Arpeggiator", {style: "UpDown", rate: "1/16"})
 
 ### `.mix(mixer)` *(TuttiDAW only)*
 
-TuttiDAW extension, not in Strudel: the voice's mixer: vol in dB (-70..6), pan -1..1, mute true / false; a bus's, a group's and the master's too.
+TuttiDAW extension, not in Strudel: the voice's mixer: vol in dB (-70..6), pan -1..1, mute true / false; a bus's, a group's and the master's too. Patterns automate vol and pan.
 
 ```js
 note("c3 e3").mix({vol: -6, pan: -0.3})
@@ -1121,6 +1175,14 @@ Applies f to about 75% of the events.
 s("hh*8").often(x => x.gain(0.4))
 ```
 
+### `.once()` *(TuttiDAW only)*
+
+TuttiDAW extension, not in Strudel: an env() or ramp() plays once from the start, then holds its last value.
+
+```js
+kick: s("bd*4").mix({vol: ramp(-60, 0, 8).once()})
+```
+
 ### `.orbit(orbit?)`
 
 Voices on one orbit share its delay and reverb settings.

package/dist/skills/tutticode/references/harmony-and-scales.md

@@ -102,4 +102,7 @@ stack of note names.
 note("<[a2,e3,a3,c4] [f2,c3,a3,c4] [c3,g3,c4,e4] [g2,d3,b3,d4]>")
 ```
 
+Next: [Melodies with do re mi](melodies-with-do-re-mi.md) writes the same note
+names, and scale roots, in solfège.
+
 Source: https://tuttidaw.com/code/learn/harmony-and-scales