tutticode 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,145 @@
+# Effect controls
+
+Filters, reverb, delay, distortion, panning, envelopes and synth controls - and moving them with signals.
+
+Controls are methods that shape the sound of every event: `.lpf(800)`,
+`.room(0.4)`. In TuttiDAW each control is played by a real device on the
+voice's track - a filter control adds an Auto Filter, `room` a Reverb - so
+what you hear is what you get when you open the program in the studio.
+
+## Filters
+
+`.lpf(hz)` is a low-pass filter (it removes highs), `.hpf(hz)` a high-pass
+(it removes lows), `.bpf(hz)` a band-pass. `.lpq(...)` / `.hpq(...)` add
+resonance.
+
+```js
+note("c2*8").s("sawtooth").lpf("<300 600 1200 2400>").lpq(6)
+```
+
+```js
+s("hh*16").hpf(6000).gain(0.6)
+```
+
+`.vowel("a e i o u")` is a formant filter that makes a sound talk.
+
+```js
+note("c2*4").s("sawtooth").vowel("<a e i o>")
+```
+
+## Space: room and delay
+
+`.room(amount)` sends the voice into a reverb; `.size(...)` makes the room
+bigger. `.delay(amount)` adds an echo, with `.delaytime(cycles)` and
+`.delayfeedback(0..1)`.
+
+```js
+s("~ cp ~ cp").room(0.6).size(4)
+```
+
+```js
+note("<c4 eb4> ~ ~ ~").s("triangle").delay(0.5).delaytime(3/16).delayfeedback(0.55)
+```
+
+## Drive and lo-fi
+
+`.shape(0..1)` and `.distort(...)` add drive; `.crush(bits)` reduces the bit
+depth (lower is crunchier) and `.coarse(n)` the sample rate.
+
+```js
+s("bd*4, ~ sd").shape(0.5)
+```
+
+```js
+note("c3 eb3 g3 bb3").s("square").crush(5)
+```
+
+## Level and stereo
+
+`.gain(...)` is the level into the effects, `.postgain(...)` after them.
+`.pan(0..1)` places the voice from left (0) to right (1).
+
+```js
+s("hh*8").pan("0 1 0.25 0.75").gain(0.7)
+```
+
+## Modulation effects
+
+`.phaser(rate)` and `.chorus(amount)` add movement; `.compressor(...)`
+evens out the level.
+
+```js
+note("[c3,g3,bb3]*2").s("sawtooth").phaser(1).lpf(1800)
+```
+
+## Envelopes
+
+`.attack`, `.decay`, `.sustain` and `.release` shape each note's volume, in
+seconds (sustain is a level, 0 to 1). A slow attack and long release make a
+pad; a short decay with no sustain makes a pluck.
+
+```js
+note("<[c3,eb3,g3] [bb2,d3,f3]>").s("sawtooth").attack(0.4).release(1).lpf(1500)
+```
+
+```js
+note("c4 g4 eb4 g4").s("square").decay(0.12).sustain(0)
+```
+
+## Synth controls
+
+These play on the TuttiDAW synth that stands in for the waveform:
+
+- `.lpenv(depth)` with `.lpattack` / `.lpdecay` / `.lpsustain` / `.lprelease`:
+  an envelope on the filter cutoff;
+- `.fm(index)` with `.fmh(ratio)` and `.fmdecay(...)`: FM brightness (the
+  voice moves onto Operator);
+- `.penv(semitones)` with `.pdecay(...)`: a pitch sweep, good for kicks and
+  zaps;
+- `.vib(rate)` with `.vibmod(semitones)`: vibrato;
+- `.detune(...)` and `.unison(voices)` on `supersaw`.
+
+```js
+note("c2 ~ c2 [~ c3]").s("sawtooth").lpf(250).lpenv(4).lpdecay(0.15).lpsustain(0)
+```
+
+```js
+note("c3 e3 g3 c4").s("sine").fm(3).fmh(2).fmdecay(0.3)
+```
+
+```js
+note("c2*4").s("sine").penv(24).pdecay(0.08)
+```
+
+Each of these is an approximation of Strudel's synth on a TuttiDAW
+instrument; the diagnostics list say which device plays it.
+
+## Moving values: signals
+
+A **signal** is a value that moves continuously through the cycle. `sine`,
+`cosine`, `saw`, `tri` and `square` go from 0 to 1; `perlin` and `rand`
+move smoothly or randomly. `.range(min, max)` scales a signal, `.slow(n)`
+stretches it over `n` cycles.
+
+```js
+note("c2*16").s("sawtooth").lpf(sine.range(300, 3000).slow(4))
+```
+
+```js
+s("hh*16").gain(perlin.range(0.3, 0.9))
+```
+
+`.segment(n)` samples a signal `n` times per cycle, which turns it into
+notes:
+
+```js
+n(saw.range(0, 8).segment(8)).scale("C:minor")
+```
+
+## In the studio: automation
+
+When you **Open in TuttiDAW**, a control that changes over time - a pattern
+like `"<300 600>"` or a signal - becomes a clip envelope on the device
+parameter, so you can see and edit the movement like any other automation.
+
+Source: https://tuttidaw.com/code/learn/effect-controls

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

@@ -0,0 +1,89 @@
+# First sounds
+
+Drums with s(), pitches with note(), and the difference between them.
+
+There are two ways to make a voice sound: name a **sound** with `s(...)`, or
+play **pitches** with `note(...)`.
+
+## Drums with s()
+
+`s` (or its long name `sound`) picks sounds by name. Short names stand for
+the parts of a drum kit:
+
+| Name | Sound | Name | Sound |
+|---|---|---|---|
+| `bd` | bass drum | `oh` | open hi-hat |
+| `sd` | snare | `cr` | crash |
+| `rim` | rimshot | `rd` | ride |
+| `cp` | clap | `ht` `mt` `lt` | high, mid, low tom |
+| `hh` | closed hi-hat | `sh` `cb` | shaker, cowbell |
+
+```js
+s("bd hh sd hh")
+```
+
+A comma inside the quotes plays two rows at the same time:
+
+```js
+s("bd ~ sd ~, hh hh hh hh hh hh hh hh")
+```
+
+`~` is a rest: the step is there, but nothing plays.
+
+## Choosing a drum machine
+
+`.bank(...)` picks the drum machine the names play on. TuttiDAW maps the
+classic machines to its factory kits: `tr808`, `tr909`, `tr707`, `tr606`,
+`tr505`, `linn`, `dmx` and `cr78` (Strudel's long names such as
+`RolandTR909` work too).
+
+```js
+s("bd*2 [~ bd] sd ~, hh*8").bank("tr909")
+```
+
+## Pitches with note()
+
+`note` plays pitches. Write note names (`c`, `d`, `eb`, `f#`) with an octave
+number, or MIDI numbers.
+
+```js
+note("c3 eb3 g3 bb3")
+```
+
+```js
+note("48 51 55 58")
+```
+
+Both lines play the same four notes. In code, `c4` is MIDI 60 (middle C).
+TuttiDAW's piano roll, like Ableton Live, labels MIDI 60 as **C3**, so a
+note written `c4` in code shows as C3 in the clip.
+
+## Giving notes a sound
+
+A `note` voice without a sound plays a simple synth. Add `.s(...)` to pick
+another one: the basic waveforms `sine`, `triangle`, `square`, `sawtooth`, or
+an instrument name such as `piano`.
+
+```js
+note("c3 e3 g3 b3").s("sawtooth")
+```
+
+```js
+note("c4 e4 g4 c5").s("piano")
+```
+
+The [Sounds](sounds.md) chapter lists the instruments you can name, and
+[TuttiDAW extensions](tuttidaw-extensions.md) shows how to load any TuttiDAW
+instrument with its presets.
+
+## Volume and velocity
+
+`.gain(...)` sets the loudness of a voice. `.velocity(...)` (0 to 1) sets how
+hard each note is played, as a MIDI velocity: it is kept when you freeze code
+to MIDI.
+
+```js
+s("hh*8").gain(0.5).velocity("1 0.6 0.8 0.6")
+```
+
+Source: https://tuttidaw.com/code/learn/first-sounds

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

@@ -0,0 +1,119 @@
+# 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.
+
+AI agents can write TuttiCode as well as you can, but they cannot hear it.
+**tutticode** gives them ears and a mixing desk: a command-line tool and an
+MCP server that check a program, render it to WAV, FLAC or MP3 with the
+same engine as this page, and measure the result (loudness, peaks, balance,
+groove) so the agent can fix what it cannot hear. Two skills teach agents
+the language and how to make sound for videos, apps and games.
+
+## Install
+
+You need Node 20 or newer and Google Chrome or Microsoft Edge.
+
+```sh
+npm i -g tutticode
+tutticode skills install
+tutticode doctor
+```
+
+`skills install` copies the two skills, `tutticode` (the language) and
+`tutticode-sound-for-media` (music beds, loops and sound effects at the
+right length and loudness), into the skill folders of Claude Code
+(`~/.claude/skills`), Copilot CLI (`~/.copilot/skills`) and Codex
+(`~/.codex/skills`): every one that exists on your computer, or the ones
+you name with `--claude`, `--copilot`, `--codex`, or any folder with
+`--dir <path>`.
+
+For MCP clients, add the server, for example in Claude Code:
+
+```sh
+claude mcp add tutticode -- tutticode mcp
+```
+
+## Two backends, one API
+
+The tools have the same names everywhere: `code_check` (compile, no
+audio), `code_render` (render and measure) and `code_compare` (compare with
+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, no account, up to 5 minutes of
+  audio per render. It also offers `code_open` (open a program here for you to hear)
+  and `code_reference` (search the language reference).
+- **TuttiDAW's web MCP** (`https://tuttidaw.com/api/mcp`) and the HTTP API
+  (`/api/code/check`, `/api/code/render`, `/api/code/compare`): for agents
+  that cannot run programs on your computer. Renders on our servers, needs
+  you to be signed in, costs Muse points, at most 60 seconds, and returns a
+  link to listen to instead of files.
+
+## Example: a riser for a video
+
+1. Ask your agent: "Make a 4 second riser for the start of my video,
+   normalised for YouTube, and save it as riser.wav."
+2. The agent picks the riser recipe from the media skill, writes the
+   program and runs `code_check` until it has no errors:
+
+```js
+setcpm(15) // one bar = 4 s
+cymbal: note("c4").s("gm_reverse_cymbal").gain(0.9)
+sweep: note("c3").s("sawtooth").penv(24).pattack(4).attack(3.5).release(0.1).lpf(2000).gain(0.4)
+```
+
+3. It renders the file and reads the numbers before it hands it over:
+
+```sh
+tutticode render riser.tc -o riser.wav --seconds 4 --lufs -18 --json
+```
+
+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.
+
+## Privacy
+
+tutticode renders on your computer: the program goes from the agent to the
+TuttiCode page in your own browser and nowhere else. The bridge sends no
+program code and no audio to our servers, and tutticode sends no telemetry.
+Its logs stay in `~/.tutticode/logs` and never contain your programs or
+audio. The page itself loads from tuttidaw.com like any web page, with its
+instruments and samples. The web MCP is different: there the program is
+sent to TuttiDAW to be rendered.
+
+## The browser permission
+
+The TuttiCode page talks to tutticode over your own computer
+(`127.0.0.1`), which Chrome and Edge treat as your local network:
+
+- By default tutticode starts a hidden browser with its own profile and
+  allows this for tuttidaw.com only; you see nothing.
+- With `--show` (the default when you type a command yourself) it uses a
+  tab in your normal browser. The first time, the page asks whether this
+  agent may render sound with TuttiCode, and the browser asks whether
+  tuttidaw.com may access devices on your local network: allow both.
+- `tutticode setup` (optional) explains, asks, and then sets one browser
+  policy for your user so that the second question does not come back:
+  local network access for `https://tuttidaw.com` only.
+  `tutticode setup --undo` removes exactly that entry.
+
+## Troubleshooting
+
+Run `tutticode doctor` first: it checks Node, the browser, the page, the
+connection and the engine version, and says what to fix.
+
+- **No browser found**: install Chrome or Edge, or point tutticode at one
+  with `--browser <path>` or the `TUTTICODE_BROWSER` variable.
+- **The page never connects** (exit code 2): allow the local network
+  question in the browser (or run `tutticode setup`), and check that no
+  extension or company policy blocks tuttidaw.com.
+- **Errors in the code** (exit code 1): the report lists each one with its
+  line, column and a fix; the agent should run `code_check` until it is
+  clean.
+- **`clip`**: the loudness asked for would push the peaks past -1 dBTP.
+  Ask for a lower `--lufs`, or turn down the loudest voice.
+- **A render that runs too long**: give it more time with `--timeout`, or
+  render fewer loops.
+
+Source: https://tuttidaw.com/code/learn/for-agents