tutticode 0.2.2 → 0.3.0

package/README.md

@@ -73,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

package/README.zh-CN.md

@@ -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` 和写出的文件路径。永远不会把音频打印到终端。

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')`).
@@ -131,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

@@ -128,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

@@ -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