@hraness/dawg 0.4.1 → 0.5.0

package/src/commands/help.ts

@@ -4,6 +4,7 @@
  * app commands take a slash (bare aliases keep working but are listed once,
  * in their canonical form).
  */
+import { EXPRESSION_USAGE } from "./expression.ts";
 
 export type HelpGroup = "music" | "session" | "window" | "keys";
 
@@ -60,6 +61,38 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
         command: "synth <param> <value> | preset <name>",
         summary: "synth voice · synth lpf 1200 · synth lists every param",
       },
+      {
+        command: "art <articulation>|off [target]",
+        summary:
+          "staccato legato accent tenuto marcato ghost · art staccato bars 1-2",
+      },
+      {
+        command: "glide <ms>|0 [legato|mono|poly] | glide <ms> <target>",
+        summary:
+          "portamento in ms · glide 60 mono · glide 0 off · SDK 0.06 (s)",
+      },
+      {
+        command: "bend <cents>|scoop|fall|doit|<at:cents>... [target]",
+        summary: "pitch curve over each note · bend +200 bar 3",
+      },
+      {
+        command: "vibrato <rate> <depth> [<delay>] [target]",
+        summary: "per-note vibrato · vibrato 5.5 30 0.2",
+      },
+      {
+        command: "pedal <beat>-<beat>... | bars | down|half|up <beat> | off",
+        summary: "sustain pedal · pedal 0-3.5 4-7.5 · pedal bars",
+      },
+      {
+        command: "velcurve linear|soft|hard|fixed [<v>]",
+        summary: "how velocity maps to level · velcurve fixed 0.6 (0..1)",
+      },
+      {
+        command: "humanize <ms> [<vel%> [<len%>]] [seed <n>|<target>] | off",
+        summary:
+          "seeded feel at render · humanize 10 8 5 · humanize 20 bars 2-3",
+      },
+      { command: "expression", summary: "this track's performance settings" },
       { command: "filter <hz> [res]", summary: "low-pass · filter off" },
       { command: "delay <beats> [fb] [mix]", summary: "ping-pong · delay off" },
       { command: "reverb <mix> [size]", summary: "room · reverb off" },
@@ -76,12 +109,82 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
         summary: "drop one point",
       },
       { command: "clear [<lane>] automation", summary: "drop a lane's points" },
+      {
+        command: "master <unit> on|off | preset <name> | <param> <value>",
+        summary:
+          "song master · eq glue tape width limiter · master glue ratio 4",
+      },
+      {
+        command: "master <target> | target <lufs> | measure | off",
+        summary:
+          "loudness · master streaming · master target -9 · master measure",
+      },
       { command: "track name <text>", summary: "rename this track" },
       { command: "meter <1..16>", summary: "beats per bar" },
+      {
+        command: "tempo <bpm> at <beat>|bar <n> [ramp|exp]",
+        summary: "tempo change · tempo 90 at bar 9 ramp · tempo clear",
+      },
+      {
+        command: "rit|accel [<n> bars] [to <bpm>] [at bar <n>]",
+        summary: "gradual · rit 4 bars to 80 · a tempo · tempo primo",
+      },
+      {
+        command: "fermata [at <beat>|at bar <n>|at end] [<extra beats>]",
+        summary: "hold a beat · fermata at 31 2 · fermata clear",
+      },
+      {
+        command: "meter <n>/<d> [at bar <n>]",
+        summary: "meter change · meter 7/8 at bar 5 · meter clear",
+      },
+      {
+        command: "track rate|phase|cycle <n> | off",
+        summary: "polytempo · track rate 3/2 · track cycle 3",
+      },
+      {
+        command: "track phasing <beats> [over <beats>|hold <n>]",
+        summary: "Reich phasing · track phasing 3 hold 8 · track time off",
+      },
       {
         command: "key <tonic> <mode> | none",
         summary: "song key · key A minor · key F# dorian",
       },
+      {
+        command: "scale [<tonic>] <name> | list",
+        summary: "song scale · scale D hijaz · scale yaman · scale list",
+      },
+      {
+        command: "tuning <name> | edo <n> | scl <file> | off",
+        summary: "song tuning · tuning 19-edo · tuning just · tuning list",
+      },
+      {
+        command: "tuning ref <hz> | root <note> | map linear|nearest",
+        summary: "A4 reference · degree-0 key · keys per step",
+      },
+      {
+        command: "tuning track <…> | track off",
+        summary: "this track's tuning · off follows the song",
+      },
+      {
+        command: "cents <id> <±c>",
+        summary: "detune one note · cents n3 -14 · add E4-14c at 0",
+      },
+      {
+        command: "section <name> <a>-<b> | add | dup | move | rename | delete",
+        summary: "song sections · section chorus 9-16 · section lists them",
+      },
+      {
+        command: "section loop | jump | mute | vary <name>",
+        summary: "section loop chorus · section mute verse drums",
+      },
+      {
+        command: "form <section…> | off | bake",
+        summary: "song form · form intro verse chorus*2 outro",
+      },
+      {
+        command: "build | drop | fill [<section> | <a>-<b>]",
+        summary: "riser, roll, sweep · pre-drop cut and impact · drum fill",
+      },
       {
         command: "hit <voice> at <beat>",
         summary: "kit tracks · hit kick at 0",
@@ -112,7 +215,10 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
       { command: "/rename <name>|--auto", summary: "name this session" },
       { command: "/fork [<name>]", summary: "copy into a new session" },
       { command: "/status", summary: "name · revision · digest · storage" },
-      { command: "/export <file>", summary: "write track.loop/v1 JSON" },
+      {
+        command: "/export <file>",
+        summary: "write track.loop/v1 JSON, or MIDI for .mid",
+      },
       { command: "/import <file>", summary: "replace the score from a file" },
       {
         command: "/sample [<path> [as <voice>]]",
@@ -143,6 +249,10 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
       },
       { command: "/auth [--check]", summary: "provider and audio status" },
       { command: "/play [on|off]", summary: "keyboard play mode · Ctrl-P" },
+      {
+        command: "/play degrees|chromatic",
+        summary: "home row plays the key's scale degrees (any tuning) · i",
+      },
       {
         command: "/pattern [name]",
         summary: "drum groove picker · moving previews",
@@ -179,6 +289,10 @@ export const HELP_SECTIONS: readonly HelpSection[] = [
         command: "/help [topic]",
         summary: "start here · /help all for everything",
       },
+      {
+        command: "/guide [topic]",
+        summary: "short how-to guides · F1",
+      },
     ],
   },
   {
@@ -219,13 +333,9 @@ export const HELP_GUIDE: readonly HelpSection[] = [
       { command: "ctrl-p", summary: "play notes on the computer keyboard" },
       {
         command: "ctrl-k",
-        summary: "menu: every sound, effect, rhythm, chord",
-      },
-      { command: "?", summary: "keys for the screen you are on" },
-      {
-        command: "ctrl-z · ctrl-y",
-        summary: "undo · redo (every change is one)",
+        summary: "menu: sound, effects, performance, mix, master, arrange …",
       },
+      { command: "? · ctrl-z · ctrl-y", summary: "keys here · undo · redo" },
     ],
   },
   {
@@ -244,8 +354,10 @@ export const HELP_GUIDE: readonly HelpSection[] = [
   {
     group: "make drums" as HelpGroup,
     entries: [
-      { command: "/pattern", summary: "pick a groove · moving previews it" },
-      { command: "/kit", summary: "pick a drum kit" },
+      {
+        command: "/pattern · /kit",
+        summary: "pick a groove · pick a drum kit",
+      },
       { command: "/euclid", summary: "rhythm editor: pulses, steps, rotation" },
     ],
   },
@@ -257,35 +369,68 @@ export const HELP_GUIDE: readonly HelpSection[] = [
         summary: "instrument, envelope, filter, wavetable",
       },
       { command: "ctrl-k › Effects", summary: "delay, reverb, distortion …" },
-      { command: "fx delay mix 0.3", summary: "the same from the prompt" },
+      {
+        command: "master streaming",
+        summary: "finish: -14 LUFS, limiter · master measure",
+      },
       { command: "/try fx reverb mix 0.6", summary: "hear it before keeping" },
     ],
   },
+  {
+    group: "shape the performance" as HelpGroup,
+    entries: [
+      {
+        command: "art staccato bar 2",
+        summary: "humanize 8 5 · ctrl-k › Sound › performance",
+      },
+    ],
+  },
   {
     group: "chords" as HelpGroup,
     entries: [
       { command: "key A minor", summary: "set the song key" },
       {
         command: "ctrl-p, then q",
-        summary: "chord mode: one key plays a chord",
+        summary: "chord mode · 1–4 type · 5–8 extension · n next",
       },
+    ],
+  },
+  {
+    group: "song structure" as HelpGroup,
+    entries: [
       {
-        command: "1–4 · 5–8 · n",
-        summary: "chord type · extension · next chord",
+        command: "section verse 1-8",
+        summary: "name bars · form verse chorus*2 orders them",
+      },
+      {
+        command: "build · drop · fill",
+        summary: "transitions · ctrl-k › Arrange · /help arrange",
       },
     ],
   },
   {
     group: "more" as HelpGroup,
     entries: [
-      { command: "/help all", summary: "every command and key" },
-      { command: "/help music", summary: "or session, window, keys" },
+      {
+        command: "rit 4 bars to 80",
+        summary: "tempo, fermatas, meter · tuning pelog · scale yaman",
+      },
+      {
+        command: "/help all",
+        summary: "every command and key · /guide feature guides · F1",
+      },
     ],
   },
 ];
 
 /** Topics `/help <topic>` takes, besides `all`. */
-export const HELP_TOPICS = ["music", "session", "window", "keys"] as const;
+export const HELP_TOPICS = [
+  "music",
+  "session",
+  "window",
+  "keys",
+  "arrange",
+] as const;
 
 /**
  * Rows for `/help [topic]`: the guide with no topic, the full reference for
@@ -299,10 +444,47 @@ export function helpTopicLines(
   if (!name) return sectionLines(HELP_GUIDE, width, 20);
   if (name === "all" || name === "commands" || name === "reference")
     return helpLines(width);
+  if (name === "arrange" || name === "arrangement" || name === "sections")
+    return sectionLines([arrangeSection()], width);
   const group = HELP_SECTIONS.find((section) => section.group === name);
   return group ? sectionLines([group], width) : undefined;
 }
 
+/** `/help arrange`: every arranging command with its full usage. */
+function arrangeSection(): HelpSection {
+  const verbs = ["section", "sections", "form", "build", "drop", "fill"];
+  return {
+    group: "arrange" as HelpGroup,
+    entries: [
+      // Usage strings run long: wrapped onto continuation rows.
+      ...verbs.flatMap((verb) =>
+        wrapWords(USAGE[verb] ?? "", 46).map((summary, index) => ({
+          command: index === 0 ? verb : "",
+          summary,
+        })),
+      ),
+      { command: "/menu arrange", summary: "the Arrange menu (ctrl-k)" },
+      {
+        command: "dawg render --section <name>",
+        summary: "export one section",
+      },
+    ],
+  };
+}
+
+function wrapWords(text: string, width: number): string[] {
+  const rows: string[] = [];
+  let row = "";
+  for (const word of text.split(" ")) {
+    if (row && row.length + 1 + word.length > width) {
+      rows.push(row);
+      row = word;
+    } else row = row ? `${row} ${word}` : word;
+  }
+  if (row) rows.push(row);
+  return rows;
+}
+
 function sectionLines(
   sections: readonly HelpSection[],
   width: number,
@@ -365,15 +547,31 @@ export function helpText(): string {
 }
 
 /** Usage for a known verb, shown instead of sending a near-miss to the agent. */
-const USAGE: Readonly<Record<string, string>> = {
+export const USAGE: Readonly<Record<string, string>> = {
   click: "/click on|off|<volume> · /click 50%",
   "count-in": "/count-in 0|1|2",
   chords:
     "/chords auto|manual|off · voicing <n> · spread · bass · perform · rate · octaves · sevenths · preset · style",
   key: "key <tonic> <mode> | none · key A minor",
+  scale: "scale [<tonic>] <name> | list · scale D hijaz",
+  tuning:
+    "tuning <name> | edo <n> | ratios … | cents … | scl <file> [kbm <file>] | ref <hz> | root <note> | map linear|nearest | track … | off · tuning 19-edo",
+  tune: "tuning <name> | edo <n> | scl <file> | off · tuning list",
+  cents: "cents <id> <±cents> · cents n3 -14",
   grid: "/grid 1/4|1/8|1/8T|1/16|1/16T|1/32",
-  tempo: "tempo takes 20…300 · tempo 120",
+  tempo:
+    "tempo takes 20…300 · tempo 120 · tempo 90 at bar 9 [ramp|exp] · tempo remove bar 9 · tempo clear · tempo map",
   bpm: "tempo takes 20…300 · tempo 120",
+  rit: "rit [<n> bars|beats] [to <bpm>] [at bar <n>|<beat>] [exp] · rit 4 bars to 80",
+  ritardando:
+    "rit [<n> bars|beats] [to <bpm>] [at bar <n>|<beat>] [exp] · rit 4 bars to 80",
+  rall: "rit [<n> bars|beats] [to <bpm>] [at bar <n>|<beat>] [exp] · rall 2 bars",
+  accel:
+    "accel [<n> bars|beats] [to <bpm>] [at bar <n>|<beat>] [exp] · accel 8 bars to 174 at bar 9",
+  accelerando:
+    "accel [<n> bars|beats] [to <bpm>] [at bar <n>|<beat>] [exp] · accel 8 bars to 174",
+  fermata:
+    "fermata [at <beat>|at bar <n>|at end] [<extra beats>] · fermata at 31 2 · fermata remove 31 · fermata clear",
   add: "add <note> at <beat> [for <beats>] · add C4 at 0",
   put: "add <note> at <beat> [for <beats>] · add C4 at 0",
   remove: "remove <id> · ids show in the transcript",
@@ -400,7 +598,8 @@ const USAGE: Readonly<Record<string, string>> = {
   hit: "hit <voice> at <beat> · hit kick at 0",
   pattern: "pattern <voice> <beats...> | every <step> · pattern kick every 1",
   clear: "clear · clear <voice> · clear [<lane>] automation",
-  track: "/track <name> · /track drums",
+  track:
+    "/track <name> · /track drums · track rate <0.125..8>|<a>/<b>|off · track phase <beats> · track cycle <beats> · track phasing <beats> [over <beats>]",
   tracks: "/tracks",
   sessions: "/sessions",
   resume: "/resume [<n>|<name>|<id>]",
@@ -422,15 +621,37 @@ const USAGE: Readonly<Record<string, string>> = {
   logout: "/logout [provider]",
   auth: "/auth [--check]",
   help: "/help [topic] · /help all · /help music|session|window|keys",
+  guide: "/guide [topic] · /guide chords · F1",
   fx: "fx <effect> <param> <value> | on | off | preset <name> · fx delay mix 0.3",
   synth: "synth <param> <value> | preset <name> · synth lpf 1200",
   pack: "/pack list | info <name> | use <pack>/<sound> | add <url>",
   kit: "/kit [name] · /kit syn909",
   euclid: "/euclid [voice] · euclid hat 7 16",
-  menu: "/menu [sound|effects|rhythm|chords|mix|project]",
+  menu: "/menu [sound|effects|rhythm|chords|mix|master|project|tuning]",
+  master:
+    "master <unit> on|off|preset <name>|<param> <value> · master streaming|club|loud · master target -14 · master measure · master off",
   try: "/try <sound command> · /try fx reverb mix 0.6",
-  play: "/play [on|off] · Ctrl-P",
-  meter: "meter <1..16> · meter 3",
+  play: "/play [on|off|degrees|chromatic] · Ctrl-P · i toggles degrees",
+  meter:
+    "meter <1..16> · meter 3 · meter 7/8 [at bar <n>] · meter remove bar <n> · meter clear",
+  art: EXPRESSION_USAGE.art,
+  articulation: EXPRESSION_USAGE.art,
+  bend: EXPRESSION_USAGE.bend,
+  vibrato: EXPRESSION_USAGE.vibrato,
+  glide: EXPRESSION_USAGE.glide,
+  portamento: EXPRESSION_USAGE.glide,
+  pedal: EXPRESSION_USAGE.pedal,
+  sustain: EXPRESSION_USAGE.pedal,
+  velcurve: EXPRESSION_USAGE.velcurve,
+  humanize: EXPRESSION_USAGE.humanize,
+  section:
+    "section [mark] <name> <a>-<b> | add [<name>] [<n>] | dup | move <name> to <bar> | rename <name> to <new> | delete | unmark | mute | vary | reset | loop <name>|off | jump <name> · section chorus 9-16",
+  sections: "section · lists sections, the form and the loop",
+  form: "form <section…> | off | bake · form verse verse chorus verse · form verse chorus*2",
+  build:
+    "build [into <section> | <section> | <a>-<b>] [<n> bars] [riser] [roll] [sweep] [uplifter] · build into chorus",
+  drop: "drop [<section> | at <bar>] [cut <beats>] [no impact] · drop chorus",
+  fill: "fill [<section> | at <bar>] [toms|roll|kick] [<n> beats] [no crash] · fill chorus (the beats before it)",
   undo: "undo · Ctrl-Z",
   redo: "redo · Ctrl-Y",
 };
@@ -530,6 +751,42 @@ export function looksLikeProse(command: string): boolean {
  */
 export function usageHint(command: string): string | undefined {
   if (looksLikeProse(command)) return undefined;
-  const verb = command.trim().toLowerCase().replace(/^\//, "").split(/\s+/)[0];
-  return verb ? USAGE[verb] : undefined;
+  const words = command.trim().toLowerCase().replace(/^\//, "").split(/\s+/);
+  const verb = words[0];
+  if (!verb) return undefined;
+  // `build tension`, `drop bass`, `form a hook`: everyday words, so only
+  // arguments that look like the grammar earn a usage hint; the rest is
+  // a request for the agent.
+  if (
+    ARRANGE_VERBS.has(verb) &&
+    !command.trim().startsWith("/") &&
+    !words.slice(1).some((word) => /\d/.test(word) || ARRANGE_WORDS.has(word))
+  )
+    return undefined;
+  return USAGE[verb];
 }
+
+const ARRANGE_VERBS: ReadonlySet<string> = new Set([
+  "build",
+  "drop",
+  "fill",
+  "form",
+]);
+const ARRANGE_WORDS: ReadonlySet<string> = new Set([
+  "at",
+  "into",
+  "cut",
+  "no",
+  "impact",
+  "crash",
+  "riser",
+  "roll",
+  "sweep",
+  "uplifter",
+  "toms",
+  "kick",
+  "beats",
+  "bars",
+  "bake",
+  "off",
+]);