@hraness/dawg 0.5.0 → 0.6.0

package/guides/effects.md

@@ -11,6 +11,7 @@ chorus, delay, reverb, and more (phaser, bitcrush, vowel, leslie).
 ## Ask
 
 - "add a dub delay to the snare" · "more room on the keys"
+- "give the guitar a crunchy amp"
 
 ## Type it yourself
 
@@ -19,9 +20,10 @@ chorus, delay, reverb, and more (phaser, bitcrush, vowel, leslie).
 - `fx distort drive 4 tone 5000` · `fx reverb ir hall`
 - `fx chorus on` · `fx chorus off` · `fx chorus reset`
 - `fx compressor preset <name>` load a preset
+- `rig crunch` guitar rig · `head lead` · `cab 4x12` · `stomp fuzz`
 - `filter 1200 0.6` · `delay 0.375 0.3` · `reverb 0.4 0.8` · `filter off`
 
 ## Menu
 
-- Ctrl-K › Effects: core effects first, then more effects, advanced
+- Ctrl-K › Effects: core effects, Guitar rig, more effects, advanced
 - `fx filter` alone opens the filter's faders, stacked

package/guides/sounds.md

@@ -16,10 +16,14 @@ order: 1
 - `synth preset pluck` · pad lead bass acid keys bell organ strings
 - `synth lpf 800 lpenv 3` any parameter · `synth adsr 0.01 0.2 0.5 0.3`
 - `synth lpf off` · `synth reset` · `synth` lists what is set
+- `piano felt` · grand ballad upright lofi · `keys hardness 0.3` · `keys`
 - `wt list` tables · `wt pwm` load one · `wt 0.5` position
+- `string sitar` · nylon koto harp … · `string buzz 0.8` · `string presets`
 - `/pack list` · `/pack use <pack>/<sound> as kick` · `/pack info vcsl`
 - `/sample samples/kick.wav as kick` add a sampler voice
+- `/bpm 174` the sample's tempo (a bare `bpm 174` is the song's) · `fitmode beats` (drums) or `tones` (pads) · `len 8`
 
 ## Menu
 
 - Ctrl-K › Sound: instrument, preset, envelope, filter, browse sounds
+- Ctrl-K › Sound › browse sounds › Strings: the plucked string presets

package/guides/tempo.md

@@ -20,6 +20,7 @@ Positions are beats from 0 or `bar <n>`.
 - `fermata at 31 2` hold beat 31 for 2 extra beats
 - `meter 7/8 at bar 5` · `tempo map` show it · `tempo clear`
 - `track rate 3/2` · `track cycle 3` · `track phasing 3` · `track time off`
+- `/bpm 174` on a sampler voice follows the map · `fitmode beats|tones` keeps pitch
 
 ## Menu
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hraness/dawg",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/agent/agent.ts

@@ -1,3 +1,4 @@
+import { GRANULAR_PARAMS } from "../../core/granular.ts";
 import {
   applyScoreOperation,
   type ScoreOperation,
@@ -201,10 +202,16 @@ export const AGENT_SYSTEM_PROMPT = [
   "Song structure: list_sections shows named sections (bars count from 1); edit_section marks, adds, duplicates, moves, renames, deletes, mutes, varies (transpose/gain) and loops them; set_form sets the play order with repeats (intro verse chorus*2 outro); add_transition generates builds (riser, snare roll, filter sweep, uplifter), drops (cut plus impact) and drum fills at section boundaries.",
   CHORD_PROCESS,
   "Synth voices: set_synth shapes a synth track with Strudel params (ADSR, lpf/lpenv filter envelopes, fm/fmh, supersaw unison/detune, vib, penv, noise; z_* ZzFX sounds take slide/pitchJump/lfo/zcrush…) or a preset (pad lead pluck bass keys bell…).",
+  "Plucked strings: set_string makes a track a physical-model string (nylon steel electric jangle ebass slap upright motown sitar tanpura harpsichord lute oud setar tar santur dulcimer koto harp banjo tres requinto) and overrides params (ring bright damp pos mute buzz body sym). The bare words sitar, ebass, pluck keep their older voices; use set_string for the modelled ones.",
+  "Pianos: set_instrument piano (or grand upright felt honkytonk prepared, ballad, lofi) loads a modelled piano with real hammers, stretched inharmonic strings, dampers and the sustain pedal; set_keys tweaks it (hardness touch decay release felt stretch body…, automate as keys-<param> lanes). A track already stored as instrument piano keeps the legacy tone until you set it again.",
+  "Mallets and bells: set_instrument vibes (or marimba via modal, xylophone glock celesta chimes kalimba mbira steelpan bowl gong timpani) plays the modal engine; set_modal changes mallet (yarn…brass), hardness, position, ring, damp, motor/motordepth (vibes tremolo), buzz, click. Plain instrument marimba stays the legacy tone.",
   "Sampler voices: set_sample sets Strudel sample controls per voice (begin end speed unit loop loopBegin loopEnd clip/legato fit loopAt accelerate squiz cut); splice = slices with fit.",
+  "Fitting samples (0.6): fit_sample sets a voice's own bpm (or len in beats) so it follows the song's tempo map; fitmode beats for drums and speech (hits stay sharp), tones for pads and vocals (pitch kept), repitch (default) like tape.",
   "Effects (set_fx; set_effects and set_automation): the brief's effects list is the fixed chain order with each effect's simple params. set_fx turns an effect on with good defaults, loads a preset or sets params by dawg or Strudel name. Lanes: volume, pan, filter, resonance, delay-feedback, delay-mix, wt and <effect>-<param> (e.g. autofilter-cutoff). Sidechain: put pads/bass on `orbit` 2 and give the kick `duck` (orbit 2, preset pump); a ducker never ducks itself.",
+  "Guitar rig (set_rig): rig loads a whole rig (clean crunch punk ragged lead metal fuzz octave funk wah bachata spring bassdrive reese jangle alt) on a guitar or bass track; stomp, head and cab tweak the pedal, amp (level-matched, gate in dB) and cabinet. Tracks named jangle punk funk ragged gtr-lead gtr-metal bachata start with a guitar voice and that rig. `amp` is Strudel gain; the guitar amp is head.",
   "Previewing: preview_sound renders a track, or candidate sound tool calls (changes: [{tool, args}]), without committing, returns loudness, brightness and a comparison, and plays it once in the user's window. Use it when choosing between sounds (tables, presets, effect amounts), say how it sounds, then commit with the normal tools.",
   "Wavetable synth: set_wavetable picks a table (built-ins offline, Strudel wt_ sets fetched once) and scans it by position wt.",
+  `Granular: set_granular makes a track a grain cloud (presets cloud hold sparkle swarm stutter microloop backwards dust) of a synth source (src synth:pad, the default; synth:<name>@<note>) or one of its own sampler voices, and overrides params (${Object.keys(GRANULAR_PARAMS).join(" ")}; repeat and hold latch the head for beat repeats, begin and end pick a region, root takes a MIDI number or note name); off returns to the previous voice; the same seed gives the same grains.`,
   "Mastering: set_master sets the song master and loudness target; measure_mix reports LUFS, true peak, balance and correlation. Master only when asked for loudness or a finished sound, and measure before and after.",
   "If a call is rejected, read the diagnostic and either fix the arguments or stop.",
   WORKSPACE_PROMPT,

package/src/agent/granular-tools.ts

@@ -0,0 +1,138 @@
+/**
+ * Agent tool for the granular instrument: `set_granular` edits a track's
+ * `Track.granular` through the same path as the `grain` prompt command, so
+ * the command, the ctrl-k menu, the tool and the SDK store the same object.
+ */
+import {
+  GRANULAR_PARAMS,
+  GRANULAR_PRESET_NAMES,
+  isGranularPreset,
+  synthSourceNames,
+} from "../../core/granular.ts";
+import { SCORE_LIMITS } from "../../core/score.ts";
+import {
+  applyGranularCommand,
+  type GranularCommand,
+} from "../commands/granular.ts";
+import type { AgentTool, ToolContext } from "./tools.ts";
+
+class GranularToolError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ToolArgumentError";
+  }
+}
+
+function targetTrack(args: Record<string, unknown>, context: ToolContext) {
+  const trackId = args.trackId ?? context.focusedTrackId;
+  if (typeof trackId !== "string" || trackId.length > SCORE_LIMITS.maxIdLength)
+    throw new GranularToolError("trackId must be a short string");
+  if (!context.score.tracks.some((track) => track.id === trackId))
+    throw new GranularToolError(
+      `unknown track ${trackId}; create it with create_track first`,
+    );
+  return trackId;
+}
+
+/** One tool call becomes the `grain` commands it stands for, in order. */
+export function granularToolCommands(
+  args: Record<string, unknown>,
+): GranularCommand[] {
+  const commands: GranularCommand[] = [];
+  if (args.off === true) return [{ type: "grain-off" }];
+  const voice =
+    typeof args.voice === "string" && args.voice.length > 0
+      ? args.voice.toLowerCase()
+      : undefined;
+  if (args.preset !== undefined) {
+    if (typeof args.preset !== "string" || !isGranularPreset(args.preset))
+      throw new GranularToolError(
+        `granular presets: ${GRANULAR_PRESET_NAMES.join(", ")}`,
+      );
+    commands.push({ type: "grain-preset", preset: args.preset, voice });
+  } else if (args.reset === true) commands.push({ type: "grain-reset" });
+  else commands.push({ type: "grain-on", voice });
+  if (args.src !== undefined) {
+    if (typeof args.src !== "string")
+      throw new GranularToolError("src must be synth:<name>[@note]");
+    const text = args.src.startsWith("synth:") ? args.src : `synth:${args.src}`;
+    commands.push({ type: "grain-src", synth: text.toLowerCase() });
+  }
+  if (args.params !== undefined) {
+    if (
+      typeof args.params !== "object" ||
+      args.params === null ||
+      Array.isArray(args.params)
+    )
+      throw new GranularToolError("params must be an object");
+    const values: Record<string, number | string | boolean | null> = {};
+    for (const [name, value] of Object.entries(args.params)) {
+      if (!Object.prototype.hasOwnProperty.call(GRANULAR_PARAMS, name))
+        throw new GranularToolError(
+          `granular has no parameter ${name}; it takes ${Object.keys(GRANULAR_PARAMS).join(", ")}`,
+        );
+      if (
+        value !== null &&
+        typeof value !== "number" &&
+        typeof value !== "string" &&
+        typeof value !== "boolean"
+      )
+        throw new GranularToolError(`granular ${name} must be a value`);
+      values[name] = value;
+    }
+    commands.push({ type: "grain-set", values });
+  }
+  return commands;
+}
+
+export const GRANULAR_TOOLS: readonly AgentTool[] = Object.freeze([
+  {
+    name: "set_granular",
+    description: `Make a track a granular instrument (offline, nothing to download) or shape it. preset: ${GRANULAR_PRESET_NAMES.join(" ")}. src: a built-in synth source synth:<${synthSourceNames().slice(0, 8).join("|")}|…>[@note]; on a sampler track the first (or named voice) sample is the source. params (null unsets): grain s, overlap, scan (head speed, 0 held), pos, begin, end, spray, jitter, pitch st, detune, shimmer, shimint, spread, window (hann tukey gauss tri perc rperc), reverse 0..1, freeze, repeat, hold, drift, drate, attack, release, veltone, gain, seed, root. reset keeps preset and source; off returns to the previous voice.`,
+    parameters: {
+      type: "object",
+      properties: {
+        trackId: { type: "string" },
+        preset: { type: "string", enum: [...GRANULAR_PRESET_NAMES] },
+        src: { type: "string" },
+        voice: { type: "string" },
+        reset: { type: "boolean" },
+        off: { type: "boolean" },
+        params: {
+          type: "object",
+          additionalProperties: {
+            type: ["number", "string", "boolean", "null"],
+          },
+        },
+      },
+      additionalProperties: false,
+    },
+    plan(args, context) {
+      const trackId = targetTrack(args, context);
+      let score = context.score;
+      let message = "";
+      for (const command of granularToolCommands(args)) {
+        const result = applyGranularCommand(score, trackId, command);
+        if (!result.ok) throw new GranularToolError(result.message);
+        if (result.next) score = result.next;
+        message = result.message;
+      }
+      const next = score.tracks.find((t) => t.id === trackId)!;
+      return {
+        kind: "score",
+        operations: [
+          {
+            type: "updateTrack",
+            trackId,
+            patch: {
+              instrument: next.instrument,
+              granular: next.granular ?? null,
+            },
+          },
+        ],
+        trackId,
+        summary: `${trackId} ${message}`,
+      };
+    },
+  },
+]);

package/src/agent/models.ts

@@ -486,17 +486,17 @@ export async function loadLiveCatalog(
  * and `chatTools()` serialized, plus `compositionBrief` of a 3-track, 48-note
  * loop; see models.test.ts, which keeps these in step with the code):
  *
- * - system prompt ≈ 4.3 KB, tool schemas ≈ 38 KB, brief ≈ 1.6 KB typical
- *   (capped at 12 KiB), user request ≈ 0.1 KB → ≈ 44 KB ≈ 11,000 tokens
+ * - system prompt ≈ 7 KB, tool schemas ≈ 51 KB, brief ≈ 1.6 KB typical
+ *   (capped at 12 KiB), user request ≈ 0.1 KB → ≈ 59 KB ≈ 14,800 tokens
  *   per request at ~4 bytes per token;
  * - about 2 requests per prompt (tool calls, then a short reply), the second
  *   also carrying the first step's tool calls and results (≈ 0.6 KB);
  * - output ≈ 450 tokens of tool-call arguments and ≈ 150 of reply.
  *
- * So ≈ 22,100 input and ≈ 600 output tokens per prompt.
+ * So ≈ 29,800 input and ≈ 600 output tokens per prompt.
  */
 export const TYPICAL_PROMPT = Object.freeze({
-  inputTokens: 22_100,
+  inputTokens: 29_800,
   outputTokens: 600,
 });
 

package/src/agent/ops.ts

@@ -1,4 +1,9 @@
+import { resolveInstrumentWord } from "../../core/instruments.ts";
 import { pitchToMidi } from "../../core/pitch.ts";
+import {
+  instrumentPatchForWord,
+  type TrackModal,
+} from "../../core/resonators.ts";
 import { SCORE_LIMITS } from "../../core/score.ts";
 
 export { pitchToMidi };
@@ -34,11 +39,16 @@ export type AgentOperation =
       type: "track";
       patch: {
         instrument?: string;
+        string?: { preset: string };
+        /** 0.6: a modal preset word (`instrument vibes`) sets this too. */
+        modal?: TrackModal;
         muted?: boolean;
         volume?: number;
         pan?: number;
         name?: string;
       };
+      /** The instrument word as typed (a guitar alias also loads its rig). */
+      word?: string;
     }
   | {
       type: "automation";
@@ -74,8 +84,14 @@ export function parsePrompt(prompt: string): AgentOperation | undefined {
   const instrument = text.match(
     /^(?:instrument|sound|voice)\s+([a-z0-9._ -]{1,64})$/,
   );
-  if (instrument)
-    return { type: "track", patch: { instrument: instrument[1]!.trim() } };
+  if (instrument) {
+    const word = instrument[1]!.trim();
+    return {
+      type: "track",
+      patch: instrumentPatch(word),
+      ...(resolveInstrumentWord(word)?.fx ? { word } : {}),
+    };
+  }
   if (/^(?:mute|silence)\b/.test(text))
     return { type: "track", patch: { muted: true } };
   if (/^(?:unmute|unsilence)\b/.test(text))
@@ -180,3 +196,24 @@ export function parsePrompt(prompt: string): AgentOperation | undefined {
     ...(offset !== 0 ? { cents: offset } : {}),
   };
 }
+
+/**
+ * The track patch an instrument word means: a 0.6 resolver word for the
+ * string engine also writes its preset (`instrument nylon` plays the nylon
+ * string); every other word stores the instrument as before.
+ */
+export function instrumentPatch(word: string): {
+  instrument: string;
+  string?: { preset: string };
+  modal?: TrackModal;
+} {
+  const meaning = resolveInstrumentWord(word);
+  if (!meaning) return { instrument: word };
+  if (meaning.field === "modal") return instrumentPatchForWord(word);
+  if (meaning.field === "string" && meaning.preset)
+    return {
+      instrument: meaning.instrument,
+      string: { preset: meaning.preset },
+    };
+  return { instrument: meaning.instrument };
+}

package/src/agent/preview-tool.ts

@@ -36,10 +36,15 @@ export const PREVIEWABLE_TOOLS: readonly string[] = Object.freeze([
   "set_mix",
   "set_automation",
   "set_fx",
+  "set_rig",
   "set_synth",
+  "set_string",
+  "set_modal",
   "set_sample",
+  "fit_sample",
   "set_effects",
   "set_wavetable",
+  "set_granular",
   "set_drum_kit",
   "use_sound",
 ]);
@@ -154,7 +159,7 @@ export function previewSoundTool(
   return {
     name: "preview_sound",
     description:
-      "Hear a track, or a candidate sound change, without committing it. changes: sound tool calls to try ({tool, args} for set_fx, set_synth, set_wavetable, set_instrument, set_sample, set_effects, set_mix, set_automation, set_drum_kit, use_sound), applied to a copy. Renders the track's notes over up to 4 bars (or a short phrase by role when it has none), solo or in context, and returns RMS/peak dBFS, spectral centroid and a one-line description for the current and the candidate sound. When the user's window is open it plays the snippet once. Then commit with the normal tools if it sounds right.",
+      "Hear a track, or a candidate sound change, without committing it. changes: sound tool calls to try ({tool, args} for set_fx, set_rig, set_synth, set_string, set_modal, set_wavetable, set_instrument, set_sample, fit_sample, set_effects, set_mix, set_automation, set_drum_kit, use_sound), applied to a copy. Renders the track's notes over up to 4 bars (or a short phrase by role when it has none), solo or in context, and returns RMS/peak dBFS, spectral centroid and a one-line description for the current and the candidate sound. When the user's window is open it plays the snippet once. Then commit with the normal tools if it sounds right.",
     parameters: {
       type: "object",
       properties: {