Art and animation, written as code. Illustrations, loops, interactive web art, launch-videos and scored films in dozens of styles, identical on every render.
TypeScript agent-skillsanimationcanvasclaude-codeclaude-pluginclaude-skillscodex-plugincreative-codecreative-codingcreative-toolsdeterministicgenerative-arthand-drawnillustrationlaunch-videomotion-designmotion-graphicspluginprocedural-generationskill
compose: held chords ("~"), comped chord rhythms, split bars on the meter's beats; docs for fit, peak and speed
Alex Greenshpun4ad2abaabfd2
diff --git a/skills/anidoodle/engine/src/canvas-core/music/compose.ts b/skills/anidoodle/engine/src/canvas-core/music/compose.tsindex 086a8bb..fb693d5 100644--- a/skills/anidoodle/engine/src/canvas-core/music/compose.ts+++ b/skills/anidoodle/engine/src/canvas-core/music/compose.ts@@ -13,19 +13,36 @@ import { VOCAB_TRIM, VOCAB_TARGET_FIX } from "./vocabTrim";import { VOCAB, KINDS, BASE_SLOTS, resolveVoice, moodVoice, moodFx, fullMood, type Slot, type Voice, type SectionKind, type MoodControls } from "./vocab";import type { MixProfile } from "./mixProfiles";-/** One chord of YOUR harmony: its voicing (a notation chord) and a one-bar bass line you wrote for it. */+/**+ * One chord of YOUR harmony: its voicing and a one-bar bass line you wrote for it. The voicing is a+ * notation chord ("[C3 G3 E4]"), one note ("E4"), or "r": the chord part rests while the chord is+ * still the harmony (named for the key check, craft, novelty and the bass), for a bar the bass or an+ * arp states alone.+ */export type ComposedChord = { voicing: string; bass?: string };/** A line = notation bars, or names of your motifs, joined in order from the section's first bar. */export type LineSpec = string | string[];export type ComposedSection = {id?: string; kind: SectionKind; bars: number;- /** chord names per bar (keys of `chords`), cycled to fill the section; a bar may hold two: "Dm9 G13" splits it */+ /**+ * chord names per bar (keys of `chords`), cycled to fill the section. A bar may hold several: "Dm9 G13"+ * splits it where the meter splits (splitBar: 4/4 2+2, 3/4 2+1, 5/4 3+2, 6/8 3+3 eighths, 7/8 4+3+ * eighths, or your `grouping`), or give each chord its beats: "Dm9:1 G13:2". "~" holds the chord before+ * it: tied over the bar line, no restrike ("Cmaj9", "~" = one chord for two bars; "~ G13" holds into+ * the bar, then changes).+ */harmony: string[];+ /**+ * the chord part's rhythm, one bar per item (or bars joined with "|"), cycled over the section:+ * "x:DUR[@VEL]" strikes the chord sounding at that point, "r:DUR" rests, "~:DUR" (a bar's first token)+ * holds the last strike over the bar line. Without it, each chord is held for its whole span.+ */+ comp?: string | string[];/** lines play ONCE from the section's first bar (harmony cycles, lines do not); a shorter line leaves rests, unless `loopLines` */lead?: LineSpec; counter?: LineSpec; arp?: LineSpec;/** repeat each line to fill the section (a 2-bar motif in an 8-bar section plays 4 times) */ loopLines?: boolean;/** modulate: this section's key and mode (default the piece's); the key check reads each key region separately */ key?: string; mode?: ModeId;- /** override the chords' bass lines for this section (one bar of notation, or one per bar) */ bass?: string | string[];+ /** override the chords' bass lines for this section (one bar of notation, or one per bar; "~" ties the bass over that bar line) */ bass?: string | string[];/** a key of `grooves`, or null for no drums; default by kind (main / half / build / none) */ groove?: string | null;/** chord velocity scale (0..1.2), e.g. 0.8 for a softer intro */ chordVel?: number;/** 0..1 (0.5 = as written): the section's dynamics for EVERY part (velocity x 0.55..1.45, about -5..+3 dB) and the density of generated grooves */ energy?: number;@@ -41,6 +58,7 @@ export type Material = {/** 0.5 straight .. 0.67 hard swing (default the style's lower bound) */ swing?: number;/** the piece's dynamic level [start, end] 0..1, ramped over the whole piece (default [0.62, 0.66]); section `energy` shapes it locally */ dyn?: [number, number];/** seconds of ring-out after the last onset (default 3.2) */ tail?: number; loop?: boolean;+ /** how a bar divides into beat groups (in beats, summing to the bar), e.g. [2, 3] for a 5/4 felt 2+3 or [1.5, 1, 1] for a 7/8 felt 3+2+2: where a split bar ("A B", "A B C") changes chord (default: splitBar's table) */ grouping?: number[];/** a shipped score frozen on the old sound (the launch film): never set this for a new piece */ legacy?: boolean;/** override the style's mix/space/feel profile (mixProfiles.ts), e.g. { space: {...}, feel: "tight" } */ mix?: Partial<MixProfile>;};@@ -51,6 +69,25 @@ const need = (ok: unknown, msg: string) => { if (!ok) throw new Error(`compose:const fmt = (x: number) => String(+x.toFixed(4));const lanes: Lane[] = ["kick", "snare", "ghost", "hat", "perc"];+/**+ * Where a bar of `k` chords changes, in beats per chord. Two chords split on the meter's strong+ * division, not the arithmetic middle: 2/4 1+1, 3/4 2+1 (a waltz changes on beat 3, never on 2.5),+ * 4/4 2+2, 5/4 3+2, 6/8 1+1 (3+3 eighths), 7/8 2+1.5 (4+3 eighths), 9/8 2+1, 12/8 2+2. Three chords:+ * 3/4 1+1+1, 4/4 2+1+1, 5/4 2+1+2... see the table. A `grouping` with k groups wins; otherwise a+ * count the table does not name divides the bar evenly. Explicit beats ("A:1 B:2") override all of it.+ */+const SPLITS: Partial<Record<Meter, Record<number, number[]>>> = {+ "2/4": { 2: [1, 1] }, "3/4": { 2: [2, 1], 3: [1, 1, 1] }, "4/4": { 2: [2, 2], 3: [2, 1, 1], 4: [1, 1, 1, 1] },+ "5/4": { 2: [3, 2], 3: [2, 1, 2], 5: [1, 1, 1, 1, 1] }, "6/8": { 2: [1, 1] }, "7/8": { 2: [2, 1.5], 3: [1, 1, 1.5] },+ "9/8": { 2: [2, 1], 3: [1, 1, 1] }, "12/8": { 2: [2, 2], 3: [2, 1, 1], 4: [1, 1, 1, 1] },+};+export const splitBar = (meter: Meter, k: number, grouping?: number[]): number[] => {+ const bpb = beatsPerBar(meter);+ if (k <= 1) return [bpb];+ if (grouping && grouping.length === k) return grouping;+ return SPLITS[meter]?.[k] ?? Array.from({ length: k }, () => bpb / k);+};+/** Expand repeats: the sections as played, with their first bar. */export const layout = (sections: ComposedSection[]) => {const out: { s: ComposedSection; id: string; from: number; to: number; pass: number }[] = []; let b = 0;@@ -70,13 +107,27 @@ export const composePiece = (m: Material): Piece => {const motif = (x: string) => { const v = m.motifs?.[x]; if (v !== undefined) return v; need(/[:|]/.test(x), `no motif named "${x}": add motifs["${x}"] = "<bars of notation>", or write the notes inline (NOTE:DUR ...).`); return x; };const lineOf = (spec: LineSpec) => (Array.isArray(spec) ? spec : [spec]).map(motif).join(" | ");- // ---- harmony per bar (a bar may split into chords: "A B" = two halves)- const chordAt: string[][] = [];+ // ---- harmony per bar: chords with their beats; "~" holds the chord before it (tied, no restrike)+ need(!m.grouping || Math.abs(m.grouping.reduce((a, x) => a + x, 0) - bpb) < 1e-6, `grouping [${m.grouping?.join(", ")}] must add up to the bar (${bpb} beats in ${meter}).`);+ type Seg = { name: string; at: number; d: number; tie: boolean };+ const bars: Seg[][] = []; let prev: string | undefined;for (const x of lay) {need(x.s.harmony?.length, `section "${x.id}" has no harmony: write the chord names for its bars.`);- for (let i = 0; i < x.s.bars; i++) { const names = x.s.harmony[i % x.s.harmony.length].trim().split(/\s+/); for (const n of names) need(m.chords[n], `chord "${n}" (section "${x.id}") has no voicing: add chords["${n}"] = { voicing: "[...]", bass: "..." }.`); chordAt.push(names); }+ for (let i = 0; i < x.s.bars; i++) {+ const src = x.s.harmony[i % x.s.harmony.length].trim(), toks = src.split(/\s+/).map((t) => { const [name, beats] = t.split(":"); return { name, beats: beats === undefined ? undefined : Number(beats) }; });+ const given = toks.filter((t) => t.beats !== undefined).length;+ need(given === 0 || given === toks.length, `harmony bar "${src}" (section "${x.id}"): give every chord its beats ("A:2 B:1") or none ("A B" splits where the meter does).`);+ const ds = given ? toks.map((t) => t.beats!) : splitBar(meter, toks.length, m.grouping);+ need(ds.every((d) => Number.isFinite(d) && d > 0) && Math.abs(ds.reduce((a, d) => a + d, 0) - bpb) < 1e-6, `harmony bar "${src}" (section "${x.id}") adds up to ${+ds.reduce((a, d) => a + d, 0).toFixed(4)} beats; a ${meter} bar is ${bpb}.`);+ let at = 0; const segs: Seg[] = [];+ toks.forEach((t, j) => { const tie = t.name === "~"; need(!tie || prev, `section "${x.id}": "~" holds the chord before it, but nothing comes before it.`);+ const name = tie ? prev! : t.name; need(m.chords[name], `chord "${name}" (section "${x.id}") has no voicing: add chords["${name}"] = { voicing: "[...]", bass: "..." }.`);+ segs.push({ name, at, d: ds[j], tie }); at += ds[j]; prev = name; });+ bars.push(segs);+ }}- const harmony = chordAt.flatMap((names, b) => names.map((name, j) => ({ t: b * bpb + (j * bpb) / names.length, name })));+ const chordAt = bars.map((segs) => [...new Set(segs.map((g) => g.name))]);+ const harmony = bars.flatMap((segs, b) => segs.filter((g) => !g.tie).map((g) => ({ t: b * bpb + g.at, name: g.name })));const at = (b: number) => lay.find((x) => b >= x.from && b < x.to)!;// ---- notes@@ -84,14 +135,36 @@ export const composePiece = (m: Material): Piece => {const push = (slot: Slot, ns: Note[]) => { (notes[slot] ??= []).push(...ns); };const vel: Record<Slot, number> = { chords: 0.62, lead: 0.72, counter: 0.5, bass: 0.85, arp: 0.55, kick: 0.85, snare: 0.7, ghost: 0.5, hat: 0.5, perc: 0.45 };const role = (slot: Slot): Role => (slot === "chords" || slot === "arp" ? "accomp" : slot === "lead" ? "melody" : slot === "counter" ? "color" : slot === "bass" ? "bass" : "drum");+ /** extend the chord-part notes that end exactly at beat t by d beats: a tie, no restrike */+ const holdIn = (slot: Slot) => (t: number, d: number) => { for (const n of notes[slot] ?? []) if (Math.abs(n.t + n.d - t) < 1e-9) n.d += d; };+ /** a tie: the chord part's (hold) or the bass's (hold2) notes that end exactly at beat t sound d beats longer, no restrike */+ const hold = holdIn("chords"), hold2 = holdIn("bass");+ const comps = new Map<ComposedSection, string[]>();+ for (const x of lay) if (x.s.comp !== undefined) comps.set(x.s, (Array.isArray(x.s.comp) ? x.s.comp : [x.s.comp]).join(" | ").split("|").map((z) => z.trim()).filter(Boolean));for (let b = 0; b < B; b++) {- const x = at(b), cv = x.s.chordVel, names = chordAt[b], d = bpb / names.length;- const src = names.map((n) => `${m.chords[n].voicing}:${fmt(d)}${cv !== undefined ? `@${fmt(cv)}` : ""}`).join(" ");- push("chords", lineIn(`section "${x.id}" chords (bar ${b})`, b * bpb, src, { role: "accomp", v: vel.chords, bpb, roll: 0.03 }));+ const x = at(b), cv = x.s.chordVel, names = chordAt[b], segs = bars[b], vtok = (name: string, d: number, v?: number) => { const k = v === undefined ? cv : (cv ?? 1) * v; return `${m.chords[name].voicing}:${fmt(d)}${k !== undefined ? `@${fmt(k)}` : ""}`; };+ const comp = comps.get(x.s);+ if (comp) { // the chord part's rhythm: x strikes the chord sounding at that point, r rests, ~ holds the last strike over the bar line+ const cb = comp[(b - x.from) % comp.length], toks: string[] = []; let o = 0;+ cb.split(/\s+/).forEach((tk, i) => { const q = /^(x|r|~):([0-9./]+)(?:@([0-9.]+))?$/.exec(tk); need(q, `section "${x.id}" comp bar "${cb}": "${tk}" is not x:DUR[@VEL], r:DUR or ~:DUR.`);+ const d = q![2].includes("/") ? Number(q![2].split("/")[0]) / Number(q![2].split("/")[1]) : Number(q![2]);+ if (q![1] === "~") { need(i === 0, `section "${x.id}" comp bar "${cb}": "~" holds the last strike over the bar line, so it comes first.`); hold(b * bpb, d); toks.push(`r:${fmt(d)}`); }+ else if (q![1] === "r") toks.push(`r:${fmt(d)}`);+ else toks.push(vtok(segs.filter((g) => g.at <= o + 1e-9).pop()!.name, d, q![3] ? Number(q![3]) : undefined));+ o += d; });+ need(Math.abs(o - bpb) < 1e-6, `section "${x.id}" comp bar "${cb}" sums to ${+o.toFixed(4)} beats; a ${meter} bar is ${bpb}${o < bpb ? ` (end it with its rest: "${cb} r:${+(bpb - o).toFixed(4)}")` : ""}.`);+ push("chords", lineIn(`section "${x.id}" comp (bar ${b})`, b * bpb, toks.join(" "), { role: "accomp", v: vel.chords, bpb, roll: 0.03 }));+ } else {+ segs.forEach((g) => { if (g.tie) hold(b * bpb + g.at, g.d); });+ const src = segs.map((g) => (g.tie ? `r:${fmt(g.d)}` : vtok(g.name, g.d))).join(" ");+ if (segs.some((g) => !g.tie)) push("chords", lineIn(`section "${x.id}" chords (bar ${b})`, b * bpb, src, { role: "accomp", v: vel.chords, bpb, roll: 0.03 }));+ }if (KINDS[x.s.kind].bass) {+ // the bass keeps its own rhythm under a held chord (the chord's bass line plays again); a bass bar "~" ties the bass over the bar line insteadconst ov = x.s.bass, bl = ov !== undefined ? (Array.isArray(ov) ? ov[(b - x.from) % ov.length] : ov) : names.length === 1 ? m.chords[names[0]].bass : undefined;need(bl !== undefined, names.length > 1 ? `bar ${b} splits into ${names.join(" + ")}: give section "${x.id}" a bass override for it.` : `chord "${names[0]}" (section "${x.id}") has no bass line: add chords["${names[0]}"].bass (one bar), or a section bass override.`);- if (bl) push("bass", lineIn(`section "${x.id}" bass (bar ${b}${names.length === 1 && ov === undefined ? `, chords["${names[0]}"].bass` : ""})`, b * bpb, bl, { role: "bass", v: vel.bass, bpb }));+ if (bl?.trim() === "~") hold2(b * bpb, bpb);+ else if (bl) push("bass", lineIn(`section "${x.id}" bass (bar ${b}${names.length === 1 && ov === undefined ? `, chords["${names[0]}"].bass` : ""})`, b * bpb, bl, { role: "bass", v: vel.bass, bpb }));}// drumsconst def = KINDS[x.s.kind].drums, gname = x.s.groove === undefined ? def : x.s.groove;diff --git a/skills/anidoodle/engine/tools/music-unit.mjs b/skills/anidoodle/engine/tools/music-unit.mjsindex bc31ee0..bb7e779 100644--- a/skills/anidoodle/engine/tools/music-unit.mjs+++ b/skills/anidoodle/engine/tools/music-unit.mjs@@ -137,6 +137,34 @@ for (const secs of [70, 90, 110]) {const w = M.composePiece(M.testMaterial(M.VOCAB.world, { bars: 4 })), wr = M.renderPiece(w, SR), g = M.guardReport(wr, SR, wr.L.length / SR);assert(Number.isFinite(g.lufs) && g.ghost.windows > 0); pass(`guards run on a 7/8 score (${g.ghost.windows} windows)`); }+// 9b. Chords and bars (from the blind composer's report).+{+ // chords: a tie holds over the bar line (no restrike), comping gives the chord part a rhythm with rests, "r" voices a silent chord+ const mat = (meter, sec, extra = {}) => ({ style: "cinematic", title: "t", seed: 3, mood: "tender", bpm: 80, key: "C", mode: "major", meter, grooves: {}, ...extra,+ chords: { C: { voicing: "[C4 E4 G4]", bass: meter === "3/4" ? "C2:3" : meter === "5/4" ? "C2:5" : meter === "6/8" ? "C2:2" : meter === "7/8" ? "C2:3.5" : "C2:4" }, F: { voicing: "[C4 F4 A4]", bass: "F2:4" }, N: { voicing: "r", bass: "G2:4" } },+ sections: [{ kind: "verse", groove: null, lead: "r:" + M.beatsPerBar(meter), ...sec }] });+ const chordsOf = (p) => p.parts.find((x) => x.id === "chords").notes, bassOf = (p) => p.parts.find((x) => x.id === "bass").notes;+ { const held = M.composePiece(mat("4/4", { bars: 2, harmony: ["C", "~"], lead: "E5:4 | D5:4" })), struck = M.composePiece(mat("4/4", { bars: 2, harmony: ["C", "C"], lead: "E5:4 | D5:4" }));+ assert.equal(chordsOf(held).length, 3); assert(chordsOf(held).every((n) => n.d === 8)); assert.equal(chordsOf(struck).length, 6); assert.deepEqual(held.harmony.map((h) => h.t), [0]);+ assert.equal(bassOf(held).length, 2, "the bass keeps its line under a held chord");+ const tiedBass = M.composePiece(mat("4/4", { bars: 2, harmony: ["C", "~"], bass: ["C2:4", "~"], lead: "E5:4 | D5:4" })); assert.equal(bassOf(tiedBass).length, 1); assert.equal(bassOf(tiedBass)[0].d, 8);+ const into = M.composePiece(mat("4/4", { bars: 2, harmony: ["C", "~ F"], bass: ["C2:4", "C2:2 F2:2"], lead: "E5:4 | D5:4" })); assert.deepEqual(chordsOf(into).map((n) => [n.t, n.d]).filter(([t]) => t === 0), [[0, 6], [0, 6], [0, 6]]); assert.deepEqual(into.harmony.map((h) => [h.t, h.name]), [[0, "C"], [6, "F"]]);+ pass("harmony \"~\": the chord holds over the bar line (3 notes of 8 beats, not 6 restrikes), the bass keeps its line unless its bar is \"~\"; \"~ F\" holds into the bar, then changes");+ const comp = M.composePiece(mat("4/4", { bars: 2, harmony: ["C F"], comp: ["x:1 r:.5 x:[email protected] r:1 x:1", "~:1 r:1 x:2"], bass: "C2:2 F2:2", lead: "E5:4 | D5:4" }));+ const on = (t) => chordsOf(comp).filter((n) => Math.abs(n.t - t) < 1e-9);+ assert.deepEqual([...new Set(chordsOf(comp).map((n) => n.t))], [0, 1.5, 3, 6]); assert(on(3).some((n) => n.p === 65), "x on beat 4 strikes the chord sounding there (F)");+ assert(Math.abs(on(1.5)[0].v - on(0)[0].v * 0.6) < 1e-9, "@VEL scales the strike"); assert.equal(on(3)[0].d, 2, "~:1 holds beat 4's strike over the bar line");+ assert.throws(() => M.composePiece(mat("4/4", { bars: 1, harmony: ["C"], comp: "x:1 r:1", lead: "E5:4" })), /comp bar .* sums to 2/);+ pass("comp: x strikes the chord sounding at that point, r rests, @VEL accents, ~ ties a push over the bar line; a comp bar that does not add up throws");+ const rest = M.composePiece(mat("4/4", { bars: 2, harmony: ["C", "N"], lead: "E5:4 | D5:4" }));+ assert(chordsOf(rest).every((n) => n.t < 4)); assert.deepEqual(rest.harmony.map((h) => h.name), ["C", "N"]); assert(bassOf(rest).some((n) => n.t === 4 && n.p === 43));+ pass("voicing \"r\": the chord part rests for that chord, the harmony still names it and its bass plays"); }+ { const one = (meter, bar, extra) => { const b = M.beatsPerBar(meter); return M.composePiece(mat(meter, { bars: 1, harmony: [bar], bass: `r:${b}`, lead: `r:${b}` }, extra)).harmony.map((h) => h.t); };+ assert.deepEqual(one("3/4", "C F"), [0, 2], "3/4: 2+1, never beat 2.5"); assert.deepEqual(one("6/8", "C F"), [0, 1]); assert.deepEqual(one("5/4", "C F"), [0, 3]);+ assert.deepEqual(one("5/4", "C F", { grouping: [2, 3] }), [0, 2]); assert.deepEqual(one("7/8", "C F"), [0, 2]); assert.deepEqual(one("4/4", "C F"), [0, 2]);+ assert.deepEqual(one("3/4", "C:1 F:2"), [0, 1]); assert.throws(() => one("3/4", "C:1 F:1"), /adds up to 2/);+ pass("split bars: 3/4 changes on beat 3 (2+1), 6/8 3+3 eighths, 5/4 3+2 or its grouping (2+3), 7/8 4+3 eighths, explicit beats \"C:1 F:2\"; a wrong sum throws"); }+}// 10. Novelty: the copy Alex heard scores as a copy; the shipped demos stay apart; a reused fragment fails.{ const d = M.novelty(M.daylightCopy(), M.DEMOS);assert(!d.pass && d.worst.name.startsWith("launchLofi") && d.worst.score > 0.6, `daylight copy scored ${d.worst.score} vs ${d.worst.name}`);diff --git a/skills/anidoodle/references/music/README.md b/skills/anidoodle/references/music/README.mdindex 0445045..fac91ff 100644--- a/skills/anidoodle/references/music/README.md+++ b/skills/anidoodle/references/music/README.md@@ -127,6 +127,14 @@ upbeat leads into it.A hand-written piece with a short form, repeatable sections and optional sections can fit anythingfrom a quarter of its length to many times it, and it still ends on its cadence.+A form that already fits keeps its tempo: when the last note plus the tail lands within max(0.5 s,+one beat) of the length, `fitScore` changes nothing and the tail takes up the difference (the final+ritard alone would otherwise nudge the tempo). **Music that must hit exact picture moments** (a drop+on a cut, a sting on a reveal) is composed to the length and rendered without `--fit`, or uses the+beat-grid mode the launch films use (`gridScore` in `launchTemplate.ts`), where the score plays at+the film's bpm exactly and every cut sits on a downbeat. A fit that changes the tempo moves every+hit with it.+## Styles (21) and moods (21)Both are rows of numbers in `tables.ts`. The vocabularies are in `vocab.ts` and `vocabMore.ts`, anddiff --git a/skills/anidoodle/references/music/compose.md b/skills/anidoodle/references/music/compose.mdindex c3c4656..150b2ab 100644--- a/skills/anidoodle/references/music/compose.md+++ b/skills/anidoodle/references/music/compose.md@@ -101,7 +101,7 @@ what to compose. The engine then performs, synthesizes, mixes and masters, deterbars yourself as notation, one or more bars per lane: `kick`, `snare`, `ghost`, `hat`, `perc`.Use a second groove for contrast (`half`, `build`). Keep the kick and backbeat stable, and syncopate ontop of them ([theory/rhythm.md](theory/rhythm.md)).-7. **Write the form.** Sections are `{ kind, bars, harmony, lead, counter, arp, groove, bass,+7. **Write the form.** Sections are `{ kind, bars, harmony, lead, counter, arp, comp, groove, bass,chordVel, energy, repeat, stretch }`.- The **kind** sets which layers may sound: intro, verse, groove, hook, build, half, breakdown,drop, bridge, swell, breath, outro. See the arrangement grammar in vocabularies.md.@@ -110,6 +110,12 @@ what to compose. The engine then performs, synthesizes, mixes and masters, deterseconds, and at 30 fps a beat is `1800 / bpm` frames.- Mark one section `stretch: true`: a film fit repeats or drops it to reach the exact length andstill end on your outro.+ - **Music that must hit exact picture moments** (a drop on the reveal at 16.0 s): compose it to+ the length (bars x beats x 60 / bpm) and render without `--fit`, or use the beat-grid mode the+ launch films use (`gridScore` in `launchTemplate.ts`: the score plays at the film's bpm exactly+ and the cuts sit on its downbeats). `--fit` keeps your tempo when the form already ends within+ max(0.5 s, one beat) of the length, and the tail takes up the difference. Past that it changes+ the tempo, and every hit moves with it.- Song and cue forms, builds, and orchestration slots: [theory/form.md](theory/form.md).8. **Revise with craft, before you render.** `craft` reads the notes in milliseconds:```@@ -122,7 +128,9 @@ what to compose. The engine then performs, synthesizes, mixes and masters, deterfinding is one you chose on purpose (an open ending for suspense, parallel fifths in rock). Saywhich ones in your note to the person.- Compare the printed tension curve with your sketch from step 3. If the peak is not where you- planned it, the arrangement is wrong, not the sketch.+ planned it, the arrangement is wrong, not the sketch. The line under the curve says what drives+ each section (loudness, density, register, harmony): loudness and density weigh most, so a+ home-chord tutti or a drop is the peak ([theory/harmony.md](theory/harmony.md), section 8).| `craft` says | Usual fix ||---|---|@@ -134,7 +142,7 @@ what to compose. The engine then performs, synthesizes, mixes and masters, deter| close intervals below their low limit | spread the voicing: 1-5-3', or lift the upper note an octave || melody under the chords | voice the chords lower, or the melody higher || no syncopation (groove idiom) | anticipate a bass or melody note by an eighth |- | flat tension curve / no release | change layers, register and harmony by section; release after the peak |+ | flat tension curve / no release | change layers, loudness (`energy`), register and harmony by section; release after the peak (a loop, ambient or calm piece may stay level: a note, not a warning) || mood cues (tempo, mode, register, density) | move the cue toward the mood, or declare the mood you wrote |9. **Check, render, listen:**```@@ -153,7 +161,9 @@ what to compose. The engine then performs, synthesizes, mixes and masters, deter- novelty.It exits non-zero on any failure. `render` prints the same report (stems with `--stems`), except- novelty.+ novelty. Both synthesize each voice once, on all but one of your cores, and render the guards and+ the stems in parallel with the mix: the audio is bit-identical to a serial render (`render+ --verify` renders again serially and compares; `ANIDOODLE_THREADS=1` turns the pool off).- **Stems:** fix any part flagged more than 3 dB off with `levels`. `levels` is a **dB offset** perslot (+2 = two dB louder), added on top of the calibrated gain, the trims and the mood controls'shifts. LUFS alone once hid a sub 7-10 dB too hot.@@ -163,8 +173,10 @@ what to compose. The engine then performs, synthesizes, mixes and masters, deterstem targets with the sound (for example, brightness lifts the hats and their target); theprinted targets already include that.- **Master short of target:** a gentle master (-16 LUFS) never compresses. If one peak blocks the- gain, the whole piece stays quieter, and `check` says by how much. Fix it in the notes: stagger- the bass under the loudest downbeat, roll the big chord, don't double the climax note.+ gain, the whole piece stays quieter, and `check` says by how much, where the peak is (bar, beat+ and seconds) and which parts pile up there, loudest first, with the notes they are playing.+ Fix it in the notes at that spot: stagger the bass under that downbeat, roll the big chord, don't+ double the climax note.- **Novelty:** if it fails, change what the numbers point at. The per-feature scores name it:the lead's rhythm, the contour, the groove, the chord colours, the form. Changing the key fixesnothing.@@ -191,6 +203,7 @@ export const score = (): Material => ({{ kind: "intro", bars: <n>, harmony: ["<chord>", /* per bar, cycled */], chordVel: <0..1> },{ kind: "hook", bars: <n>, harmony: [/* ... */], lead: ["<motif>", "<motif variant>", "r:<beats>"], stretch: true, energy: <0..1> },{ kind: "groove", bars: <n>, harmony: [/* ... */], lead: ["<2-bar motif>"], loopLines: true },+ { kind: "verse", bars: <n>, harmony: ["<chord>", "~"], comp: ["x:1 r:.5 x:.5 r:2"] }, // held over the bar line; a comped rhythm{ kind: "bridge", bars: <n>, key: "<new tonic>", mode: "<mode>", harmony: [/* in the new key */], lead: [/* ... */] },/* ... */{ kind: "outro", bars: <n>, harmony: ["<home chord>"], lead: ["<the motif's last word>"] },@@ -204,8 +217,35 @@ form to the exact length. `score.ts` is an empty skeleton to copy.- **Voices:** `voices: { lead: "<alternate name>" }` swaps a slot for one of the style'salternates. Or give your own `{ inst, role, gainDb, opts }` (instruments: README table).- **Loops:** `loop: true`, and the form length is the loop. `render` makes it seamless.-- **Split bars:** `harmony: ["<chord> <chord>"]` splits a bar in two. Give that section a `bass`- override for it.+- **Split bars:** `harmony: ["<chord> <chord>"]` splits a bar where the meter divides, not at its+ arithmetic middle. Give that section a `bass` override for it.++ | Meter | 2 chords | 3 chords |+ |---|---|---|+ | 2/4 | 1 + 1 | even |+ | 3/4 | 2 + 1 (the change on beat 3) | 1 + 1 + 1 |+ | 4/4 | 2 + 2 | 2 + 1 + 1 |+ | 5/4 | 3 + 2 | 2 + 1 + 2 |+ | 6/8 | 1 + 1 (3 + 3 eighths) | even |+ | 7/8 | 2 + 1.5 (4 + 3 eighths) | 1 + 1 + 1.5 (2 + 2 + 3) |+ | 9/8 | 2 + 1 | 1 + 1 + 1 |+ | 12/8 | 2 + 2 | 2 + 1 + 1 |++ Beats are the meter's beats (in 6/8, 9/8 and 12/8 a dotted quarter). To feel the bar another+ way, set the piece's `grouping` (for example `grouping: [2, 3]` for a 5/4 felt 2 + 3): a split+ into as many chords as it has groups follows it. Or give each chord its beats: `"Dm9:1 G13:2"`.+- **Held chords:** `"~"` holds the chord before it over the bar line, with no restrike, so a pad+ never dips at the bar line: `harmony: ["Cmaj9", "~", "Am9", "~"]` is two chords of two bars each.+ `"~ G13"` holds into the bar, then changes. The bass keeps its own line under a held chord (the+ chord's bass line plays again). To tie the bass too, write that bar of the section's `bass` as `"~"`.+- **Comping:** a section's `comp` gives the chord part a rhythm, one bar per item, cycled over the+ section. `x:DUR` strikes the chord sounding at that point, `r:DUR` rests, `x:[email protected]` accents, and+ a bar may start with `~:DUR` to hold the last strike over the bar line (a pushed chord):+ `comp: ["x:1 r:.5 x:.5 r:1 x:1", "r:3.5 x:.5", "~:1 r:1 x:2"]`. A comp bar must add up to the bar.+ Without `comp`, each chord sounds for its whole span.+- **A silent chord:** `voicing: "r"` makes the chord part rest while the chord still names the+ harmony: the key check, `craft`, novelty and the bass all read it. Use it for a bar that the bass+ or an arp states alone, or a stop-time break.- **Lines play once.** `lead`, `counter` and `arp` start at the section's first bar and play ONCE,even though `harmony` cycles. A shorter line leaves rests, and `check` warns. Set`loopLines: true` to repeat the line until the section is full. `repeat: n` replays the whole