tutticode 0.1.0 → 0.1.1

package/README.md

@@ -52,7 +52,7 @@ anywhere else (for example a project's `.claude/skills`).
 tutticode check song.tc                     # diagnostics, no audio
 tutticode render song.tc -o bed.wav --seconds 12 --fade-out 1.5 --lufs -16 --json
 tutticode render song.tc -o loop.flac --loops 4 --stems stems/
-tutticode open song.tc                      # open it in TuttiCode for a human
+tutticode open song.tc                      # open it in TuttiCode for a human (--headless: prints the link)
 cat song.tc | tutticode check -             # read the program from stdin
 ```
 
@@ -60,8 +60,12 @@ cat song.tc | tutticode check -             # read the program from stdin
 `--format wav|flac|mp3` (default from the `-o` extension),
 `--sample-rate 44100|48000`, `--bit-depth 16|24`, `--stems <dir>`,
 `--fade-in s`, `--fade-out s`, `--tail s`, `--lufs N`, `--true-peak N`,
-`--json`, `--timeout s`. `--lufs` applies one static gain; when the true-peak
-ceiling cannot be met the render fails with `clip` instead of being limited.
+`--limit`, `--json`, `--timeout s`. No file is written clipped: a render
+whose true peak would pass the ceiling (`--true-peak`, default -1 dBTP) is
+lowered by one static gain, and the CLI says so ("Lowered 4.6 dB to avoid
+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`.
 
 `--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

package/README.zh-CN.md

@@ -45,16 +45,19 @@ Claude Code、Copilot CLI 和 Codex 分别从 `~/.claude/skills`、`~/.copilot/s
 tutticode check song.tc                     # 只检查,不出声音
 tutticode render song.tc -o bed.wav --seconds 12 --fade-out 1.5 --lufs -16 --json
 tutticode render song.tc -o loop.flac --loops 4 --stems stems/
-tutticode open song.tc                      # 在 TuttiCode 里打开给人看
+tutticode open song.tc                      # 在 TuttiCode 里打开给人看(--headless:只打印链接)
 cat song.tc | tutticode check -             # 从 stdin 读程序
 ```
 
 `render` 参数: `--seconds|--bars|--loops N`、`--bpm N`、
 `--format wav|flac|mp3`(默认按 `-o` 的扩展名)、`--sample-rate 44100|48000`、
 `--bit-depth 16|24`、`--stems <目录>`、`--fade-in 秒`、`--fade-out 秒`、
-`--tail 秒`、`--lufs N`、`--true-peak N`、`--json`、`--timeout 秒`。
+`--tail 秒`、`--lufs N`、`--true-peak N`、`--limit`、`--json`、`--timeout 秒`。
+不会写出削波的文件:true peak 超过上限(`--true-peak`,默认 -1 dBTP)的渲染会
+整体降低一次静态增益,CLI 会说明("Lowered 4.6 dB to avoid clipping")。
 `--lufs` 只做一次静态增益;如果达不到 true peak 上限,会以 `clip` 失败,而不是
-偷偷加限制器。
+偷偷加限制器;需要时加 `--limit`:对混音(不含分轨)加 true peak 限制器,
+报告里的 `limitDb` 是它最多压下的量。
 
 `--json` 输出渲染报告:时长、小节数、速度、响度和 true peak、施加的增益、每个
 声部的电平、小节和拍的时间点(秒,用来对齐剪辑点)、检查报告、分析结果、

package/dist/skills/tutticode/SKILL.md

@@ -125,6 +125,7 @@ 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/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.
@@ -136,5 +137,5 @@ Read only what the task needs:
 - `references/functions.md`: every function, method and signal, with signature, description and example (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.2.0, engine 15.
+Language: PATTERN LANGUAGE 1.2.0, engine 16.
 Human guide: https://tuttidaw.com/code/learn; agents: https://tuttidaw.com/code/learn/for-agents

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

@@ -40,8 +40,9 @@ differences are marked *local* or *web*.
 
 *local* returns `files` (`audio`, `stems`: paths written on disk),
 `editUrl`, `window` (`bars`, `seconds`, `bpm`), `loudness` (`lufs`,
-`truePeak` of the delivered file, `gainDb` applied for a `lufs` target),
-`voices[]` (each voice's solo `lufs` and `truePeak`), `barTimes` /
+`truePeak` of the delivered file, `gainDb` applied for a `lufs` target or
+to avoid clipping, `limitDb` with `limit`), `warnings` (what was done to
+the audio), `voices[]` (each voice's solo `lufs` and `truePeak`), `barTimes` /
 `beatTimes` (seconds of each bar and beat: sync video cuts to them),
 `check` and `analysis`. *web* returns `analysis`, a `listenUrl` (24 h) and
 signed audio links.
@@ -71,11 +72,19 @@ or mute (`_`) the voices you are not listening to.
   (whole loops ring out past their end). `tail` adds seconds after the
   length for reverbs and delays and makes the file exactly length + tail;
   `fadeIn` / `fadeOut` are linear, in seconds.
+- No file is written clipped: without `lufs`, a render whose true peak
+  would pass `truePeak` (default -1 dBTP) is lowered by one static gain
+  (negative `gainDb`, a line in `warnings`); a stem that would clip on
+  its own is lowered further (its `gainDb` in `voices[]`). *web* lowers
+  the audio file the same way and says so in `warnings`; its `analysis`
+  measures the program before that gain.
 - `lufs` applies one static gain to that integrated loudness, the same on
-  the stems. When the true peak would pass `truePeak` (default -1 dBTP)
-  the render fails with code `clip` instead of limiting: ask for a lower
-  `lufs`, or make the program less peaky (lower its loudest voice). Under
-  0.4 s there is no integrated loudness and `lufs` is ignored.
+  the stems. When the true peak would pass `truePeak` the render fails
+  with code `clip`: ask for a lower `lufs`, make the program less peaky
+  (lower its loudest voice), or add `limit: true` (`--limit`), a
+  true-peak limiter on the mix (not the stems) that reports the most it
+  took off in `limitDb`. Under 0.4 s there is no integrated loudness and
+  `lufs` is ignored.
 - Exit codes (CLI): 0 ok, 1 errors in the code or `clip`, 2 bridge or
   browser problem (run `tutticode doctor`), 3 usage.
 

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

@@ -99,7 +99,7 @@ n("0 2 4").scale("C:minor")
 
 ### `note(notes)`
 
-Plays pitches: note names (c4, eb3) or MIDI numbers (60).
+Plays pitches: note names (c4, eb3), solfège (do re mi, sol4, sib) or MIDI numbers (60).
 
 ```js
 note("c3 e3 g3 b3")

package/dist/skills/tutticode/references/melodies-with-do-re-mi.md

@@ -0,0 +1,59 @@
+# 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.
+
+## Solfège is a note name
+
+Wherever a note name goes, you can write its solfège name instead:
+`do re mi fa sol la si`. TuttiCode uses fixed do: `do` is always C, `re` is D,
+`sol` is G, whatever the key. `so` and `ti` work too (the same as `sol` and
+`si`).
+
+```js
+note("do re mi fa sol la si do4")
+```
+
+Only the name differs: `note("do re mi")` plays exactly what `note("c d e")`
+plays.
+
+## Sharps, flats and octaves
+
+Add sharps, flats and octaves as you would to a letter: `do#4`, `mib` (E flat),
+`sib3` (B flat), `fa#`. A name without an octave is in octave 3, like `c`.
+Capitals work too: `Do`, `SOL`.
+
+```js
+note("<do4 mib4 sol4 sib4> [fa#3 la3]").s("piano")
+```
+
+## Scales and chords
+
+Scale roots take solfège: `.scale("re:minor")`. Stack names with commas to
+play a chord.
+
+```js
+n("0 2 4 <7 6>").scale("<re:dorian sol:mixolydian>")
+```
+
+```js
+note("<[do3,mi3,sol3] [la2,do3,mi3] [fa2,la2,do3] [sol2,si2,re3]>").s("piano")
+```
+
+Chord symbols (`chord("C^7")`, `.voicings()`) keep their letters: there `do`
+already means D diminished (`D` and `o`).
+
+## Where a word is not a note
+
+In `s()` and `sound()` words are sound names, so `s("do")` looks for a sound
+called "do". `n()` is also a sample or soundfont index, so `n("do")` is a
+word too: write `note("do")`. Solfège means a pitch only in `note()` /
+`.note()`, `.scale()` roots, `.mode()` and `.anchor()`, and `.add()` /
+`.sub()` / `.transpose()` on notes.
+
+## Opening in strudel.cc
+
+strudel.cc reads letter names only. "Open in strudel.cc" rewrites solfège to
+letters for you (`"do re mi"` becomes `"c d e"`), so the program plays the same
+there.
+
+Source: https://tuttidaw.com/code/learn/melodies-with-do-re-mi

package/dist/skills/tutticode-sound-for-media/SKILL.md

@@ -52,19 +52,26 @@ Recipe index:
 | Broadcast (EBU R128) | -23 |
 | Short sound effects | -18..-26: peaky, see each recipe |
 
-- True peak ceiling -1 dBTP (the default). `lufs` is one static gain, never
-  a limiter: a peaky program fails with `clip`. Then lower the target, or
-  lower the loudest voice's `.gain` and render again. Where loudness
-  matters (music beds at -14..-17), end the program with
-  `master.fx("Limiter", {gainDb: 3, ceiling: -3})`: the program's own bus
-  catches the peaks before the gain, as the music recipes do.
+- True peak ceiling -1 dBTP (the default, `truePeak`). No file is written
+  clipped: without `lufs`, a render that would pass the ceiling is lowered
+  by one static gain (a negative `gainDb` and a line in `warnings`). `lufs`
+  is one static gain: a peaky program (most drum programs at -14..-16)
+  fails with `clip`. Then lower the target, lower the loudest voice's
+  `.gain` and render again, end the program with
+  `master.fx("Limiter", {gainDb: 3, ceiling: -3})` (the program's own bus
+  catches the peaks before the gain, as the music recipes do), or add
+  `limit: true` (`--limit`): the render's true-peak limiter holds the
+  ceiling and reports the most it took off (`limitDb`). More than about
+  6 dB of it flattens the drums: then lower the target instead.
 - Exact durations: `seconds` cuts exactly. A one-shot effect is one bar
   long: `setcpm` sets the bar (`setcpm(60)` = 1 s, `setcpm(15)` = 4 s).
 - Video beds: `fadeIn` 1-3 s, `fadeOut` 2-5 s, `tail` for the reverb.
 - Loops for apps and games: `loops` N with `tail: 0`, no fades, so the file
   is exactly N loops and repeats in time; keep the last step short.
-- Stems: `stems: true` writes one file per voice (named by the labels); a
-  `lufs` gain applies to the stems too, so they still sum to the mix.
+- Stems: `stems: true` writes one file per voice (named by the labels); the
+  mix's static gain applies to the stems too, so they still sum to the mix.
+  A stem that would clip on its own is lowered further (its `gainDb` in
+  `voices`, a line in `warnings`); the limiter never touches stems.
 
 ## Quality bar: never deliver
 

package/dist/tutticode.cjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-/* tutticode v0.1.0 | https://tuttidaw.com */
+/* tutticode v0.1.1 | https://tuttidaw.com */
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -3932,7 +3932,7 @@ function validRender(m) {
     return "lufs must be -40..-5";
   if (!optional(m.truePeak, (v) => finite(v) && v >= -12 && v <= 0))
     return "truePeak must be -12..0";
-  for (const key of ["stems", "analyze"])
+  for (const key of ["stems", "analyze", "limit"])
     if (!optional(m[key], (v) => typeof v === "boolean"))
       return `${key} must be a boolean`;
   return void 0;
@@ -3988,6 +3988,8 @@ function bridgePageUrl(origin, locale, port, token) {
 }
 var MAX_LABEL_CHARS = 64;
 var MAX_VERSION_CHARS = 128;
+var MAX_WARNINGS = 32;
+var MAX_WARNING_CHARS = 1e3;
 var MAX_EDIT_URL_CHARS = 1e6;
 var MAX_GRID_ENTRIES = 2e4;
 var MAX_RENDER_SECONDS = BRIDGE_MAX_SECONDS + 60;
@@ -4023,6 +4025,13 @@ function validateRenderMeta(raw, expect) {
     return no("meta.lufs / meta.truePeak out of range");
   if (!inRange(raw.gainDb, -100, 100))
     return no("meta.gainDb out of range");
+  if (!optional(raw.limitDb, (v) => inRange(v, 0, 100)))
+    return no("meta.limitDb out of range");
+  if (!optional(
+    raw.warnings,
+    (v) => Array.isArray(v) && v.length <= MAX_WARNINGS && v.every((w) => typeof w === "string" && w.length <= MAX_WARNING_CHARS)
+  ))
+    return no("meta.warnings must be at most 32 short strings");
   const barTimes = grid(raw.barTimes);
   const beatTimes = grid(raw.beatTimes);
   if (!barTimes || !beatTimes)
@@ -4046,7 +4055,14 @@ function validateRenderMeta(raw, expect) {
     const voicePeak = level(v.truePeak, -200, 40);
     if (voiceLufs === void 0 || voicePeak === void 0)
       return no("meta.voices levels out of range");
-    voices.push({ label: v.label, lufs: voiceLufs, truePeak: voicePeak });
+    if (!optional(v.gainDb, (g) => inRange(g, -100, 100)))
+      return no("meta.voices gainDb out of range");
+    voices.push({
+      label: v.label,
+      lufs: voiceLufs,
+      truePeak: voicePeak,
+      ...v.gainDb !== void 0 ? { gainDb: v.gainDb } : {}
+    });
   }
   if (!isObject(raw.check))
     return no("meta.check must be a report");
@@ -4067,6 +4083,8 @@ function validateRenderMeta(raw, expect) {
       lufs,
       truePeak,
       gainDb: raw.gainDb,
+      ...raw.limitDb !== void 0 ? { limitDb: raw.limitDb } : {},
+      ...raw.warnings !== void 0 ? { warnings: [...raw.warnings] } : {},
       barTimes,
       beatTimes,
       stems,
@@ -4207,12 +4225,16 @@ function formatCheckSummary(report) {
   )} s)`;
 }
 function formatRenderSummary(meta, files) {
+  const gain = meta.gainDb ? `, gain ${meta.gainDb > 0 ? "+" : ""}${fixed(meta.gainDb)} dB` : "";
+  const limited = meta.limitDb ? `, limited up to ${fixed(meta.limitDb)} dB` : "";
   const lines = [
     `Wrote ${files.mix} (${fixed(meta.seconds)} s, ${meta.bars} bars at ${fixed(
       meta.bpm,
       0
-    )} BPM, ${fixed(meta.lufs)} LUFS, ${fixed(meta.truePeak)} dBTP${meta.gainDb ? `, gain ${meta.gainDb > 0 ? "+" : ""}${fixed(meta.gainDb)} dB` : ""})`
+    )} BPM, ${fixed(meta.lufs)} LUFS, ${fixed(meta.truePeak)} dBTP${gain}${limited})`
   ];
+  for (const warning of meta.warnings ?? [])
+    lines.push(`Note: ${warning}`);
   const stems = Object.values(files.stems);
   if (stems.length)
     lines.push(`Stems: ${stems.length} files in ${(0, import_node_path.dirname)(stems[0])}`);
@@ -4239,7 +4261,7 @@ var wrapper_default = import_websocket.default;
 var import_node_fs2 = require("node:fs");
 var import_node_os = require("node:os");
 var import_node_path2 = require("node:path");
-var VERSION = true ? "0.1.0" : readPackageVersion();
+var VERSION = true ? "0.1.1" : readPackageVersion();
 function envBrowserArgs() {
   const args = process.env.TUTTICODE_BROWSER_ARGS?.split(" ").filter(Boolean);
   return args?.length ? args : void 0;
@@ -4653,6 +4675,7 @@ function parseRender(rest) {
     tail: { type: "string" },
     lufs: { type: "string" },
     "true-peak": { type: "string" },
+    limit: { type: "boolean" },
     "no-analyze": { type: "boolean" },
     json: { type: "boolean" }
   });
@@ -4707,6 +4730,7 @@ function parseRender(rest) {
     ...optional2("tail", number(values, "tail", 0, 60)),
     ...optional2("lufs", number(values, "lufs", -40, -5)),
     ...optional2("truePeak", number(values, "true-peak", -12, 0)),
+    ...values.limit ? { limit: true } : {},
     ...values["no-analyze"] ? { analyze: false } : {}
   };
   return {
@@ -4751,13 +4775,19 @@ program has errors.`,
   --stems <dir>                        also write one file per voice into <dir>
   --fade-in S  --fade-out S  --tail S  seconds
   --lufs N  --true-peak N              static gain to a loudness; fails (clip)
-                                       rather than limiting
+                                       when the true peak would pass the
+                                       ceiling (default -1 dBTP). Without
+                                       --lufs a render over the ceiling is
+                                       lowered (one static gain, reported)
+  --limit                              true-peak limiter instead of failing
+                                       (clip) or lowering; reported
   --no-analyze                         skip the per-voice analysis
   --json                               print the RenderMeta + written files
   --timeout S                          give up after S seconds (default 600)`,
   open: `tutticode open <file|-> [bridge flags]
 
-Opens the program in a visible TuttiCode tab (tuttidaw.com/code).`,
+Opens the program in a visible TuttiCode tab (tuttidaw.com/code). With
+--headless it opens nothing and prints the link.`,
   mcp: `tutticode mcp [bridge flags]
 
 MCP stdio server: code_check, code_render, code_compare, code_open,
@@ -7015,13 +7045,17 @@ var renderProperties2 = {
     type: "number",
     minimum: -40,
     maximum: -5,
-    description: 'Static gain to this integrated loudness (e.g. -14 for streaming, -16 for podcasts / video beds). Fails with code "clip" rather than limiting when truePeak cannot be met.'
+    description: 'Static gain to this integrated loudness (e.g. -14 for streaming, -16 for podcasts / video beds). Fails with code "clip" when truePeak cannot be met, unless limit is true.'
   },
   truePeak: {
     type: "number",
     minimum: -12,
     maximum: 0,
-    description: "dBTP ceiling with lufs (default -1)."
+    description: "dBTP ceiling (default -1). Without lufs, a render that would pass it is lowered by one static gain (loudness.gainDb, warnings): no file is written clipped."
+  },
+  limit: {
+    type: "boolean",
+    description: 'Opt-in true-peak limiter: peaks over truePeak are limited instead of failing with "clip" (with lufs) or lowering the whole render (without). Use it to reach -14 / -16 LUFS on drum-heavy programs; loudness.limitDb reports the most it took off. Stems are not limited.'
   },
   out: {
     type: "string",
@@ -7195,7 +7229,8 @@ function createToolHandler(deps) {
       "fadeOut",
       "tail",
       "lufs",
-      "truePeak"
+      "truePeak",
+      "limit"
     ])
       if (args[key] !== void 0)
         command[key] = args[key];
@@ -7241,8 +7276,10 @@ function createToolHandler(deps) {
         loudness: {
           lufs: meta.lufs,
           truePeak: meta.truePeak,
-          gainDb: meta.gainDb
+          gainDb: meta.gainDb,
+          ...meta.limitDb ? { limitDb: meta.limitDb } : {}
         },
+        ...meta.warnings?.length ? { warnings: meta.warnings } : {},
         voices: meta.voices,
         barTimes: meta.barTimes,
         beatTimes: meta.beatTimes,
@@ -18466,6 +18503,20 @@ async function render(command, io) {
 }
 async function open(command, io) {
   const code = await readProgram(command.file, io);
+  const flags = command.bridge;
+  const url = codeLink(
+    normalizeOrigin(flags.origin ?? "") ?? BRIDGE_ORIGINS[0],
+    flags.locale ?? "en",
+    code
+  );
+  if (flags.show === false) {
+    io.stdout.write(
+      `No browser window was opened (--headless). Open the program in TuttiCode:
+${url}
+`
+    );
+    return EXIT_OK;
+  }
   const outcome = await runJob(
     { type: "open", code },
     command.bridge,
@@ -18480,7 +18531,8 @@ async function open(command, io) {
       command.file,
       io
     );
-  io.stdout.write("Opened in TuttiCode.\n");
+  io.stdout.write(`Opened in TuttiCode: ${url}
+`);
   return EXIT_OK;
 }
 async function mcp(flags, io) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tutticode",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "description": "Turn TuttiCode (tuttidaw.com/code pattern code) into audio files from any agent: a CLI and an MCP server that render in your own browser with the TuttiDAW engine.",
   "license": "MIT",