tutticode 0.0.0-stage → 0.1.0

package/dist/skills/tutticode/references/getting-started.md

@@ -0,0 +1,79 @@
+# Getting started
+
+What TuttiCode is, how a program loops, and how to play your first line.
+
+TuttiCode is a small language for writing music as text. You describe a
+**pattern** (which notes or drum hits happen, and when), and TuttiDAW plays it
+with its own instruments and effects. The pattern repeats, so a single line is
+already a loop you can listen to while you change it.
+
+The language is a superset of [Strudel](https://strudel.cc): most Strudel code
+plays here as written, and TuttiDAW adds a few methods of its own for real
+instruments and effects (see [TuttiDAW extensions](tuttidaw-extensions.md)).
+
+## Your first line
+
+Every example in this guide plays: press **Play** under it on the web page,
+or paste it into TuttiCode at tuttidaw.com/code. Change a letter while it
+plays and evaluate again (Ctrl/Cmd+Enter): the change starts on the next bar.
+
+```js
+note("c3 e3 g3 c4")
+```
+
+`note(...)` turns the text between the quotes into notes. Four names share
+one bar equally, so you hear four quarter notes.
+
+## Cycles
+
+The unit of time is the **cycle**. In TuttiDAW one cycle is one bar. Every
+pattern is squeezed into its cycle: more steps means shorter steps.
+
+```js
+note("c3 e3 g3 c4 e4 g4 c5 g4")
+```
+
+Eight names in one cycle play as eighth notes; the bar stays the same length.
+
+## Tempo
+
+`setcpm(n)` asks for `n` cycles per minute. Because a cycle is a 4/4 bar,
+`setcpm(30)` is 120 BPM and `setcpm(25)` is 100 BPM.
+
+```js
+setcpm(25)
+note("c3 e3 g3 c4")
+```
+
+## Several voices
+
+A program can play several **voices** at once. Give each one a label followed
+by a colon. A label that starts with `_` is muted, which is handy while you
+work on another part.
+
+```js
+setcpm(30)
+drums: s("bd sd bd sd")
+bass: note("c2 c2 g1 bb1")
+_lead: note("c4 e4 g4 e4")
+```
+
+`$:` also starts a voice without naming it. Named voices are better when you
+take a program into the studio, because each label becomes a track name.
+
+## Where code runs
+
+- **TuttiCode** plays a whole program in your browser, without an
+  account. Its **Open in TuttiDAW** button saves it as a studio project.
+- **Pattern Clips** in the studio hold code in a MIDI clip; the notes are
+  rendered from the code.
+- **Muse**, TuttiDAW's AI assistant, can write, explain and fix code for you
+  (see [Muse on /TuttiCode](muse.md)).
+
+## Same code, same notes
+
+Randomness in a program is seeded: the same code always gives the same notes,
+on every computer and every time you open it. That is what lets a project
+with code be shared and played back exactly.
+
+Source: https://tuttidaw.com/code/learn/getting-started

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

@@ -0,0 +1,105 @@
+# Harmony and scales
+
+Note names and octaves, scale degrees, transposition, chord symbols, voicings and arpeggios.
+
+## Note names and octaves
+
+A note name is a letter, an optional accidental (`#` sharp, `b` flat) and an
+octave number. `c4` is MIDI 60, middle C; `a4` is 69 (440 Hz). Each octave
+starts at C, so `b3` is just below `c4`.
+
+A name without an octave is in octave 3: `note("c e g")` is the same as
+`note("c3 e3 g3")`.
+
+```js
+note("c e g b")
+```
+
+TuttiDAW's piano roll uses Live's names, where MIDI 60 is **C3**. Code and the
+clip disagree by one octave in the label only: the pitch is the same.
+
+## Scale degrees: n and scale
+
+`n("0 2 4")` writes numbers; `.scale("C:minor")` turns them into notes of a
+scale. Degree 0 is the root, 1 the next note of the scale, and so on.
+Numbers past the end of the scale continue in the next octave, and negative
+numbers go down.
+
+```js
+n("0 1 2 3 4 5 6 7").scale("C:minor")
+```
+
+The root is in octave 3 unless you give one (`C4:minor`). Scale names
+include `major`, `minor`, `dorian`, `mixolydian`, `lydian`, `phrygian`,
+`blues` and `chromatic`. Join the root and every word of the name with
+colons: `A:minor:pentatonic`, `C:harmonic:minor`. Inside double quotes a
+space starts a new step, so `"C:harmonic minor"` is not one scale name.
+
+```js
+n("0 2 4 <7 6>").scale("<D:dorian G:mixolydian>")
+```
+
+Because the scale is a pattern too, a melody written in degrees follows the
+chord changes on its own.
+
+## Moving notes: add and transpose
+
+`.transpose(n)` moves notes by semitones. `.add(...)` adds to the values: on
+degrees it moves along the scale, on `note` patterns use `note(...)` inside.
+
+```js
+note("c3 e3 g3 e3").transpose("<0 5 7 0>")
+```
+
+```js
+n("0 2 4 2".add("<0 3>")).scale("A:minor")
+```
+
+## Chord symbols: chord and voicing
+
+`chord("...")` takes chord symbols such as `C`, `Am7`, `F^7`, `G7` or
+`Bbm9`. `.voicing()` turns each symbol into notes, laid out so that the top
+of the chord sits at or just below c5.
+
+```js
+chord("<C Am F G>").voicing()
+```
+
+Move the whole voicing with `.anchor(...)`: the chord is laid out below that
+note instead.
+
+```js
+chord("<Dm7 G7 C^7 A7>").anchor("g4").voicing()
+```
+
+## Picking chord notes: n with chords
+
+With a chord set, `n` picks notes of the voicing by index, from the bottom
+up - an arpeggio that follows the changes.
+
+```js
+n("0 1 2 3 2 1").chord("<Cm7 Fm7 Bb7 Eb^7>").voicing()
+```
+
+## Bass lines: rootNotes
+
+`.rootNotes(octave)` plays each chord's root, in the octave you give.
+
+```js
+stack(
+  chord("<Am F C G>").voicing(),
+  chord("<Am F C G>").rootNotes(2)
+)
+```
+
+## Exact notes when you need them
+
+Voicings follow their anchor note, not fixed shapes. When you need
+exact pitches - a specific inversion, a doubled root - write the chord as a
+stack of note names.
+
+```js
+note("<[a2,e3,a3,c4] [f2,c3,a3,c4] [c3,g3,c4,e4] [g2,d3,b3,d4]>")
+```
+
+Source: https://tuttidaw.com/code/learn/harmony-and-scales

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

@@ -0,0 +1,90 @@
+# JavaScript in code
+
+Variables, functions, loops and register - and the sandbox, determinism and limits that keep shared code safe.
+
+A program is JavaScript. Most programs only chain pattern methods, but you
+can use variables, functions, arrays, loops and conditions to build them.
+
+## Variables and functions
+
+`const` names a pattern so you can reuse it. A function can build a pattern
+from arguments.
+
+```js
+const groove = s("bd [~ bd] sd ~, hh*8")
+const riff = (root) => n("0 2 4 2").scale(`${root}:minor`)
+drums: groove.bank("tr909")
+lead: cat(riff("C"), riff("F"), riff("G"), riff("C"))
+```
+
+## Double and single quotes
+
+Double quotes (and backticks) are mini-notation: `"c3 e3"` is a pattern of
+two notes. Single quotes are a plain string that is not read as
+mini-notation - useful for names that contain spaces.
+
+```js
+n("0 1 2 3").scale('C minor')
+```
+
+## Loops and arrays
+
+Ordinary JavaScript can generate patterns. Here an array of degrees is built
+with a loop and joined into mini-notation:
+
+```js
+const steps = []
+for (let i = 0; i < 8; i++) steps.push(i % 3 === 0 ? i : "~")
+n(steps.join(" ")).scale("A:minor").s("triangle")
+```
+
+## Your own methods: register
+
+`register(name, fn)` adds a method you can chain like the built-in ones. The
+pattern comes last in the function's arguments.
+
+```js
+register('dub', (amount, pat) => pat.delay(amount).delayfeedback(0.6).room(0.3))
+note("c3 ~ ~ eb3 ~ ~ g3 ~").s("square").dub(0.5)
+```
+
+## The sandbox
+
+Code arrives in shared projects and links, so TuttiDAW never runs it as
+ordinary page script. Simple programs are read by TuttiDAW's own interpreter;
+anything else runs in a sealed JavaScript sandbox (QuickJS in WebAssembly)
+whose only ability is building patterns:
+
+- there is no network, no page, no storage, no timers and no `eval`;
+- `import(...)` and `fetch` are not available; external audio is declared with
+  `samples(...)` and only loaded by the player when you press Play;
+- every program has a work budget and a time limit, so an endless loop stops
+  with an error instead of freezing the page.
+
+## Determinism
+
+The same code always plays the same notes - on your computer, a
+collaborator's, in an export:
+
+- `Math.random()` and the pattern functions `rand`, `?`, `|`,
+  `sometimes` and friends are seeded;
+- the clock is stopped: `Date.now()` always returns the same moment;
+- every render starts fresh, so state kept in variables does not carry over
+  from one play to the next.
+
+```js
+const pick = Math.floor(Math.random() * 4)
+n(`<${pick} 2 4 6>`).scale("E:minor")
+```
+
+This program picks the same "random" note every time it is run.
+
+## Limits
+
+- a program can be up to 100,000 characters (a TuttiCode link up to 20,000);
+- a cycle can hold up to 2,048 events in one voice.
+
+A program over a limit reports an error at the code that caused it; the other
+voices keep playing.
+
+Source: https://tuttidaw.com/code/learn/javascript

package/dist/skills/tutticode/references/mini-notation.md

@@ -0,0 +1,120 @@
+# Mini-notation
+
+The rhythm language inside the quotes - sequences, rests, groups, alternation, polymeter, Euclidean rhythms and chance.
+
+Everything between double quotes is **mini-notation**: a compact way to write
+rhythm. The same rules work for drum names, note names and numbers.
+
+## Sequences and rests
+
+Steps separated by spaces share the cycle equally. `~` (or `-`) is a rest.
+
+```js
+s("bd ~ ~ bd ~ ~ sd ~")
+```
+
+## Groups: [ ]
+
+Square brackets squeeze several steps into the space of one.
+
+```js
+s("bd [sd sd] bd [~ sd]")
+```
+
+Groups can be nested as deep as you like: `[hh [hh hh]]` is an eighth note
+followed by two sixteenths.
+
+```js
+s("hh [hh hh] hh [hh [hh hh]]")
+```
+
+## Faster and slower: * and /
+
+`*n` plays a step `n` times in its own space; `/n` stretches it over `n`
+cycles, so it only sounds every `n` bars.
+
+```js
+s("bd*2 sd, hh*8, cp/2")
+```
+
+## Alternation: < >
+
+Angle brackets play **one** of their steps per cycle, in turn. They are the
+easiest way to make a pattern change from bar to bar.
+
+```js
+note("<c3 a2 f2 g2>").s("sawtooth")
+```
+
+Combine them with `*` to step through the list faster:
+
+```js
+note("<c3 e3 g3 b3>*4")
+```
+
+## Chords and layers: ,
+
+A comma plays its parts at the same time. Inside a group it makes a chord.
+
+```js
+note("[c3,e3,g3] [a2,c3,e3] [f2,a2,c3] [g2,b2,d3]")
+```
+
+## Longer and repeated steps: @ ! _
+
+`@n` makes a step `n` times as long as the others. `!n` repeats a step `n`
+times, each copy a full step. `_` extends the previous step by one step.
+
+```js
+note("c3@3 eb3 g3!2 bb3 _")
+```
+
+## Polymeter: { }
+
+Curly brackets play layers of different lengths with the **same** step size,
+so they drift against each other and meet again later. `%n` sets how many
+steps fit in a cycle.
+
+```js
+note("{c3 eb3 g3, c4 d4 eb4 f4 g4}%4")
+```
+
+## Euclidean rhythms: (k,n)
+
+`x(k,n)` spreads `k` hits as evenly as possible over `n` steps. Many
+traditional rhythms are Euclidean: `(3,8)` is the tresillo, `(5,8)` the
+cinquillo. A third number rotates the pattern.
+
+```js
+s("bd(3,8), hh(5,8,2), sd(2,8,4)")
+```
+
+## Chance: ? and |
+
+`?` drops a step half of the time (`?0.2` drops it 20% of the time). `|`
+chooses one of its options at random. Chance is seeded: the program plays
+the same "random" notes every time you run it, until you change the code.
+
+```js
+s("hh*16?, bd [sd|cp]")
+```
+
+## Sample variants and number ranges: : and ..
+
+`name:n` chooses variant `n` of a sound (`bd:3`). `a .. b` counts from `a` to
+`b`.
+
+```js
+n("0 .. 7").scale("C:major")
+```
+
+## Mini-notation is a pattern everywhere
+
+Any argument that takes a number also accepts a quoted pattern, so the same
+syntax can drive speed, volume or a filter:
+
+```js
+s("hh*8").gain("0.9 0.4 0.6 0.4").fast("<1 2>")
+```
+
+Source: https://tuttidaw.com/code/learn/mini-notation

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

@@ -0,0 +1,101 @@
+# 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.
+
+A program can mix itself the way a studio project is mixed: **buses** for
+shared effects, **sends** from the voices into them, a **fader and pan** per
+voice, and a **master** that everything goes through. "Open in TuttiDAW"
+makes exactly these tracks.
+
+| Code | What it is | In the studio |
+|---|---|---|
+| `bus(name)` | a shared effect track | a return track inside the program's group |
+| `.send(bus, dB)` | how much of a voice goes to a bus | the voice track's send knob |
+| `.mix({vol, pan, mute})` | a voice's (or a bus's) mixer | the track's fader, pan and mute |
+| `master` | the program's own bus | the program group's devices and fader |
+
+These are TuttiDAW-only, like `.fx`: a program that uses them does not play
+on strudel.cc.
+
+## Buses and sends
+
+Declare a bus with `bus("name")` on its own line and give it effects with
+`.fx`. A bus usually holds a "wet only" effect (Dry/Wet at 100%): the voices
+keep their dry sound and send some of it to the bus.
+
+```js
+bus("verb").fx("Reverb:Large Hall", {dryWetBalance: 1})
+
+drums: s("bd*2 [~ bd] sd ~, hh*8").bank("tr909")
+keys: chord("<Cm7 Fm7>").voicing().inst("Electric").send("verb", -10)
+lead: n("0 2 4 7").scale("C4:minor").s("triangle").send("verb", -18)
+```
+
+`.send(bus, dB)` takes a level in dB: `0` is the most, `-70` is off. Send
+from as many voices as you like, and from one voice to several buses:
+
+```js
+bus("verb").fx("Reverb", {dryWetBalance: 1, decayTime: "3s"})
+bus("echo").fx("Delay", {feedback: 0.4}).mix({vol: -6})
+
+keys: note("<c3 e3 g3>").inst("Drift").send("verb", -10).send("echo", -20)
+```
+
+A pattern moves the level - here the reverb opens up every other bar:
+
+```js
+bus("verb").fx("Reverb", {dryWetBalance: 1})
+keys: note("c3 e3 g3 e3").s("sine").send("verb", "<-24 -6>")
+```
+
+A send to a bus the program does not declare is a warning, and the editor
+offers to add `bus("...")` for you.
+
+Why buses? Two voices that share one reverb sound like they are in one
+room, and you change the room in one place. Strudel's `.room()` still works
+too: it gives that voice its own reverb.
+
+## A voice's fader, pan and mute
+
+`.mix()` sets the voice's mixer: `vol` in dB (`0` leaves it as it is, `-6`
+is half as loud, `-70` is silent), `pan` from `-1` (left) to `1` (right),
+`mute` on or off.
+
+```js
+bass: note("c2 ~ c2 g1").s("sawtooth").lpf(500).mix({vol: -3})
+hats: s("hh*8").mix({vol: -12, pan: 0.4})
+perc: s("~ rim").mix({pan: -0.4, mute: true})
+```
+
+`vol` and `pan` can be patterns too. When a voice has both `.pan()` (Strudel)
+and `.mix({pan})`, the `.mix` value wins.
+
+## The master
+
+`master` is the program's own bus: every voice and bus goes through it.
+Give it effects and a fader like any bus - a gentle compressor to glue the
+mix and a limiter at the end are a common start:
+
+```js
+master.fx("Glue Compressor", {threshold: -12}).fx("Limiter")
+master.mix({vol: -1})
+
+drums: s("bd*4, ~ cp, hh*8").bank("tr909")
+bass: note("<c2 g1 a1 f1>").ply(4).s("sawtooth").lpf(600)
+```
+
+On this page the master is what you hear. In a project, a program lives in
+its own group track, so `master` is that group's chain; it feeds the
+project's master like any other track.
+
+## In the studio
+
+Open the program in TuttiDAW and you get its group with one track per
+voice, the buses as return tracks inside the group, and the master chain on
+the group. The values the code sets belong to the code: change one by hand
+(a device param, a fader, pan or mute, or a device added, removed or moved
+on a bus or the master) and that voice, bus or master is detached from the
+code (Re-attach brings it back). Remove
+a bus from the code and its return track stays, marked "not in code".
+
+Source: https://tuttidaw.com/code/learn/mixing

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

@@ -0,0 +1,67 @@
+# 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.
+
+**Muse** is TuttiDAW's AI assistant. On TuttiCode, the **Muse AI**
+button opens it in a sidebar next to the editor. Muse needs you to be signed
+in; playing code does not.
+
+## What to ask
+
+Muse reads the program in the editor before it changes anything, so you can
+talk about the code that is there:
+
+- "Write a slow lo-fi beat in F minor with electric piano chords."
+- "Make the bass follow the kick and add a fill every fourth bar."
+- "Why is the lead silent?" - Muse reads the diagnostics with the code.
+- "Explain what `.off(1/8, ...)` does in my program."
+- "Turn this into a TuttiDAW version with real instruments" - Muse can
+  replace waveform sounds with `.inst(...)` and `.fx(...)` devices.
+
+A request like the first one might come back as:
+
+```js
+setcpm(18)
+drums: s("bd ~ [~ bd] ~, ~ sd, hh*8").bank("linn").swingBy(1/6, 4).gain(0.8)
+keys: chord("<Fm9 Bbm9 Eb^9 Db^7>").voicing().inst("Electric").fx("Chorus")
+bass: n("<0 -2 -4 -5>").scale("F2:minor").s("gm_acoustic_bass")
+```
+
+## How Muse edits
+
+- Every change is checked first: Muse compiles and renders the program before
+  it touches the editor, and repairs its own mistake once if the check fails.
+- A change arrives as **one undoable edit**: Ctrl/Cmd+Z takes it back.
+- If you changed the code while Muse was working, it asks before overwriting
+  your edit (unless Autopilot is on).
+- Muse's edits are evaluated like your typing, so they never start a sample
+  download; press Play to load new samples.
+
+## Attachments
+
+Use **+** in the message box (or paste, or drop a file on the sidebar):
+
+- **a text or code file** - for example a Strudel tune to adapt;
+- **an image** - a screenshot of code, or of a DAW arrangement to recreate;
+- **audio** - a reference track. Muse measures its tempo, key, loudness,
+  brightness and rhythm, and can look at a spectrogram.
+
+Files stay in your browser's memory: Muse receives the text, the picture or
+the measurements, and nothing is saved to a project.
+
+## Conversations
+
+Conversations are kept in your browser for your account, with the same
+models and points as Muse in the studio. In the studio itself, Muse writes
+code into Pattern Clips; other AI apps can do the same through TuttiDAW's MCP
+server (see the agent skill below).
+
+## For AI agents
+
+The same guide is published as an agent skill at
+`/skills/tuttidaw-code/SKILL.md` (with a downloadable zip), and listed in
+`/llms.txt`. Its references are generated from these pages, the engine's
+function table and the device catalogue, so they always match what TuttiDAW
+plays. Muse on TuttiCode reads the same pages when it needs a detail.
+
+Source: https://tuttidaw.com/code/learn/muse

package/dist/skills/tutticode/references/sample-operations.md

@@ -0,0 +1,102 @@
+# Sample operations
+
+Play part of a sample, change its speed, cut it into slices, fit it to the tempo and choke it.
+
+Drum sounds and your own samples are recordings, so you can play a window of
+them, faster or slower, forwards or backwards. In TuttiDAW every variation
+becomes its own pad in a Drum Rack, so the result opens in the studio exactly
+as it sounds.
+
+## Window: begin and end
+
+`.begin(...)` and `.end(...)` set where a sample starts and stops, as a
+fraction of its length (0 to 1).
+
+```js
+s("oh*4").end("<0.1 0.3 0.6 1>")
+```
+
+## Speed
+
+`.speed(n)` plays a sample `n` times as fast: 2 is an octave up, 0.5 an
+octave down, and a negative speed plays it backwards.
+
+```js
+s("cp*4").speed("1 2 0.5 -1")
+```
+
+## Gating and choke groups: clip and cut
+
+A sample normally plays to its end. `.clip(1)` stops it at the end of its
+step (`.clip(0.5)` halfway). `.cut(n)` puts sounds in a choke group: a new
+hit stops the one still ringing, like an open hi-hat closed by a closed one.
+
+```js
+s("[oh hh]*4").cut(1)
+```
+
+```js
+s("oh*8").clip("<1 0.25>")
+```
+
+## Cutting into parts: chop and striate
+
+`.chop(n)` cuts every event, and its sample, into `n` parts played one after
+another. `.striate(n)` plays the whole pattern `n` times, a later part of each
+sample each time.
+
+```js
+s("cr").chop(8).speed("<1 -1>")
+```
+
+```js
+s("bd sd").striate(4)
+```
+
+## Slices: slice and splice
+
+`.slice(n, indices)` cuts a sample into `n` equal slices and plays the slices
+the index pattern names - the classic way to rearrange a break. `.splice` does
+the same and changes each slice's speed so it fills its step exactly.
+
+```js
+s("cr").slice(8, "0 7 2 5 4 3 6 1")
+```
+
+```js
+s("oh").splice(4, "0 2 1 [3 3]")
+```
+
+## Fitting to the tempo: loopAt and fit
+
+`.loopAt(n)` changes a sample's speed so it lasts exactly `n` cycles - ideal
+for loops and breaks. `.fit()` makes each sample fill its own step. Both follow
+the tempo, so the loop stays in time when you change `setcpm`.
+
+```js
+s("cr").loopAt(1).chop(4)
+```
+
+## Scrubbing
+
+`.scrub("position:speed")` starts the sample at a position, like moving a
+tape head.
+
+```js
+s("cr*4").scrub("0 0.5:2 0.25 0.75:0.5")
+```
+
+## With your own loops
+
+These operations are at their best on your own recordings. Declare them with
+`samples(...)` (see [Sounds](sounds.md#your-own-samples)) and slice away:
+
+```js
+samples({ break: "https://example.com/loops/break-120.wav" })
+s("break").loopAt(2).slice(8, "0 1 <2 6> 3 [4 4] 5 6 <7 1>")
+```
+
+A pitched instrument - a synth or a General MIDI name - plays its notes as
+written: these operations only change sampled drums and samples.
+
+Source: https://tuttidaw.com/code/learn/sample-operations