@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/anidoodle/references/music/compose.md

@@ -1,388 +0,0 @@
-# Compose: from a brief to an original score
-
-A style is a **vocabulary**. It gives you:
-- sound: voices, levels and fx;
-- groove families;
-- a harmony language;
-- melody rules;
-- an arrangement grammar.
-
-It never gives you notes. **You write every note**:
-- the chords and their voicings;
-- the bass lines;
-- the motifs and lines;
-- the form.
-
-The engine refuses to fill gaps. Missing harmony, melody, grooves or form is an error that tells you
-what to compose. The engine then performs, mixes and masters, deterministically, in code, and it
-plays recordings of real instruments where you ask for one.
-
-> **Never reuse shipped material.** The demos (`node tools/music.mjs list`) and our own film scores
-> are listening references and the novelty corpus. They are never a film's score or a template. Don't
-> copy them, transpose them or re-rhythm them. `node tools/music.mjs novelty` fails a score that
-> sounds like any shipped piece, or that quotes one: a 6-note fragment (transposed or not), or an
-> 8-note melody shape in any key, meter or rhythm.
->
-> **Idioms are fine.** A ii-V-I, a plagal amen, a two-chord vamp, a I-bVII-IV are vocabulary. The
-> style pages name them so you can use them. What is not fine is reusing the same music: a
-> multi-bar progression together with its rhythm, groove, contour and form, or a quoted melody.
->
-> Why this rule exists: a "new" example once changed the key, chords and pitches of the launch
-> score but kept its rhythms, contour, drums and form. It was heard at once as the same song. The
-> novelty fingerprint weighs exactly those things.
-
-## The workflow
-
-1. **Read the brief as numbers.** Write down:
-   - the use case (launch film, explainer, loop for a site, game, ad);
-   - the length in seconds, and whether it must loop;
-   - 3-5 picture beats with their times (the reveal, the claim, the cut to the end card);
-   - the words the person used for the feeling.
-2. **Pick one style and one mood.** Styles:
-   ```
-   node tools/music.mjs vocab
-   node tools/music.mjs vocab <style>
-   ```
-   For the details, see [styles/vocabularies.md](styles/vocabularies.md). The mood is a row in
-   `tables.ts` (see the README's mood list). Then set the five **mood controls**, each 0..1, where
-   0.5 = the calibrated palette:
-
-   | Control | What it moves |
-   |---|---|
-   | `energy` | groove density, drum level, sidechain depth, dynamics |
-   | `warmth` | filters darker, tape drive and wow, a little more bass |
-   | `brightness` | filters and pluck brightness open, hats up |
-   | `tension` | pad detune wider, string attacks shorter, lead decays shorter |
-   | `space` | reverb sends, delay mix, pad release |
-
-   Controls change the sound only. Harmonic tension is yours to write (step 4). To choose the tempo,
-   mode, register and density that make a feeling read, see [theory/mood.md](theory/mood.md): tempo
-   and mode are the strongest cues, and several cues pointing the same way make the mood unmistakable.
-3. **Sketch the arc and the motif before any chord.** Write three things down:
-   - **The tension curve.** One number 0..1 per section: it rises, dips just before the peak (a breath
-     or breakdown), peaks on the picture's key frame, then releases. This becomes each section's
-     `energy`, its layers and its harmony (leaning chords before home).
-   - **The climax.** The bar, the highest note of the piece, and the chord under it (home, full layers).
-   - **The motif.** Its rhythm (which beats it avoids, where the long note sits), its contour (one leap,
-     then steps back), and how it will develop across the form: stated, sequenced, fragmented in the
-     build, augmented at the climax, last word at the end ([theory/melody.md](theory/melody.md)).
-4. **Compose the harmony.** Work inside the style's harmony language: its modes, chord qualities,
-   tendencies and voicing rule. Decide the key and mode from the mood, not from habit.
-   - Write a progression **for this brief**. Choose its length (2, 3, 4, 5, 6 or 8 bars) and its
-     harmonic rhythm (one chord per bar, two per bar, or one per two bars) on purpose.
-   - Voice each chord yourself. Move the voices by step and hold common tones. The bass owns the
-     root.
-   - Write each chord's bass line (one bar) in the style's bass idiom: held root, root and fifth,
-     walking, offbeat 8ths, a syncopated 808 figure. Make the rhythm YOURS.
-   - **Tension and release as a curve.** Stable (tonic), moving away (subdominant, relative,
-     borrowed), leaning (dominant, suspension, pedal), home. Put home on the picture's key beat. End
-     inner sections on half or deceptive cadences, and save the full close for the end
-     ([theory/harmony.md](theory/harmony.md)).
-   - **Spread low, close high.** No close intervals below about C3 ([theory/sound.md](theory/sound.md)).
-5. **Compose the motif(s).** A motif is 2-5 notes with its own rhythm. Invent the rhythm first:
-   - Which beats does it avoid?
-   - Does it start on an upbeat?
-   - Where is the long note?
-
-   Then the pitches: the contour, one leap, then steps back.
-
-   Develop the motif. Don't photocopy it:
-   - **repeat**, then **vary**: change the last interval, displace it by an eighth, extend it;
-   - **sequence**: the same shape a step or a third higher;
-   - **call and response**: the question ends off the tonic, the answer lands on it, or another
-     instrument answers;
-   - **fragment** it in a build, **augment** it (slower, longer notes) at the climax;
-   - put it in the bass for menace, or high and quiet at the close.
-
-   The phrase's high point goes in its second half. A phrase is 2 or 4 bars; a period is two phrases
-   (question, answer). The line must respect the style's range and density. Put chord tones on strong
-   beats, and put the feeling in appoggiaturas and suspensions that resolve by step.
-6. **Choose or write the groove.** Pick a family from the style's list (`bounce`, `trap`,
-   `brushes`, `hand`, ...). Set `density` 0..1, `variation` 0..1 and `fill` (a fill on a section's
-   last bar). The seed varies every bar, so no two pieces share a loop. You can also write the drum
-   bars 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 on
-   top of them ([theory/rhythm.md](theory/rhythm.md)).
-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.
-   - Lines sound only where you write them.
-   - Land each section change on a picture beat. At `bpm`, a bar lasts `beatsPerBar x 60 / bpm`
-     seconds, 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 and
-     still 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:
-   ```
-   node tools/music.mjs craft <file>.ts#<export>
-   ```
-   - It prints scores (0..1) for melody, harmony, rhythm, tension and mood, the tension curve per
-     section and per bar, and each section's cadence.
-   - Each `CRAFT` line names what it saw, where (bar and beat), and a fix.
-   - Loop: read the findings, revise the notes, run `craft` again. Stop when every remaining
-     finding is one you chose on purpose (an open ending for suspense, parallel fifths in rock). Say
-     which 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. 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 |
-   |---|---|
-   | leaps keep going the same way | turn back by step after a leap |
-   | nothing comes back / exact copies | develop one motif: sequence, vary the last interval, fragment |
-   | phrases don't end on chord tones | land answers on 1, 3 or 5; keep one open question |
-   | the melody peaks early | move the highest note to the second half, on the key frame |
-   | parallel 5ths (common-practice idiom) | contrary motion; hold the common tone |
-   | 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, 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:**
-   ```
-   node tools/music.mjs check <file>.ts#<export> [--fit --seconds 62]   # EVERYTHING, must PASS (below)
-   node tools/music.mjs render <file>.ts#<export> out.mp3 --stems       # the file, plus the same report
-   node tools/music.mjs novelty <a>.ts#x <b>.ts#y                       # several scores: vs shipped AND pairwise
-   node tools/music.mjs score <file>.ts#<export>                        # the text score, bar by bar
-   ```
-   `check` runs everything:
-   - key/mode problems and composer warnings (for example, a line shorter than its section);
-   - the master: loudness vs target, true peak, and a note when the -1 dBTP ceiling stopped the
-     gain short;
-   - the **ghost, reverb and masking guards**;
-   - the stems;
-   - craft (the step-8 report, with brightness measured from the render; only an unplayable range fails);
-   - novelty.
-
-   It exits non-zero on any failure. `render` prints the same report (stems with `--stems`), except
-   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** per
-     slot (+2 = two dB louder), added on top of the calibrated gain, the trims and the mood controls'
-     shifts, on the same scale as your own voice's `gainDb`. LUFS alone once hid a sub 7-10 dB too hot.
-   - **When the guards and the stems disagree, the guards win.** If masking fails (the melody isn't
-     heard), raise the lead. The stem meter lets the lead sit up to +3 dB above its tolerance for
-     this. You can also lower or thin what sits in the melody's register. Mood controls shift the
-     stem targets with the sound (for example, brightness lifts the hats and their target); the
-     printed 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, 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. Changing the key fixes nothing.
-     Each feature is a bag of n-grams compared by cosine (0 = nothing shared, 1 = the same); the
-     score is their weighted mean, and it fails above 0.5:
-
-     | Feature | Weight | What it counts |
-     |---|---|---|
-     | `melodyRhythm` | 0.20 | the lead's onset positions in each bar, and its inter-onset-interval trigrams |
-     | `melodyContour` | 0.15 | the lead's up / down / same 4-grams |
-     | `melodyIntervals` | 0.10 | the lead's interval trigrams, in semitones (transposition-free) |
-     | `lineRhythm` | 0.15 | the counter line's rhythm plus the bass's rhythm (bar positions and inter-onset trigrams of each) |
-     | `drums` | 0.15 | each drum part's hit positions per bar |
-     | `chords` | 0.10 | chord-function trigrams: each root against the key, with its quality |
-     | `qualities` | 0.07 | chord-quality trigrams (maj7, min, dom, sus ...) |
-     | `form` | 0.08 | the order of section kinds, in pairs |
-
-     The lead is the top note of each onset of the melody part. Bar positions depend on the meter;
-     the inter-onset trigrams, the contour, the intervals and both quote gates do not. Two gates fail
-     outright whatever the score: a **6-note fragment** of a shipped melody (its intervals and
-     durations, in any key), and an **8-note melody shape** (its intervals alone, in any key, meter
-     or rhythm: a quote re-barred into 5/4 or stretched is still the tune). Only distinctive shapes
-     count (three or more different intervals, a leap of a third or more, at most three repeated
-     notes), so a scale run is never a quote.
-   - **Listen:** the person hears it before it is used. Meters prove you aren't obviously wrong.
-     Only an ear says right. For a **loop**, deliver a `.wav`: mp3 adds encoder padding, so it clicks
-     or gaps at the loop point.
-
-## Recorded instruments
-
-Eight acoustic parts play recordings of the real thing when the sound pack is installed: `piano`
-(and `piano` with `variant: "upright"`), `harp`, `marimba`, `vibes`, `glockenspiel`, `bell` with
-`variant: "tubular"`, and `timpani`. Strings, guitar, bass, brass, woodwinds, choir, celesta, music
-box, the electric pianos and the acoustic drum kit stay modeled either way, and every score plays
-without the pack.
-
-Four things decide what you write:
-
-- **Stay inside the range, or the render throws.** The grand reaches A0; the timpani stops at B3;
-  the vibraphone starts at F3 and the glockenspiel at G5. The full table is in
-  [README.md](README.md#recorded-instruments-the-optional-sound-pack).
-- **A recorded note decays the way that instrument decays.** A low grand note rings for tens of
-  seconds. Do not write a dense texture under it and expect the tail to get out of the way.
-- **The piano has a real pedal.** `sus` zones sound while the dampers are lifted, so the pedal
-  changes `perform.ts` already writes just after each harmony change are audible, and a chord left
-  ringing under the next one is what a real player does. `opts: { pedal: false }` holds the pedal.
-- **A real marimba's low notes are rich.** D2 to C4 carries as much as its top. Keep a bass line out
-  of the melody's register instead of reaching down for a note that will not sit under a tune.
-
-Two options go in a part's `opts`:
-
-| Option | What it does |
-|---|---|
-| `variant: "upright"` / `variant: "tubular"` | picks the second recording of that instrument |
-| `sampled: false` | keeps the modeled voice for that part, whatever is installed |
-
-`node tools/music.mjs check` prints the split, so read it before you believe the instrument table:
-
-```
-voices   recordings: lead (piano), accomp (piano.upright); modeled: bass (bass), drums (kick)
-```
-
-A part you expected to be recorded and find modeled is either out of range or opted out. Both are
-yours to fix; neither is a silent fallback.
-
-## The material format
-
-Write the score in the film's own file, next to the film module: `src/canvas-core/<film>Score.ts`
-in a scaffolded project (`engine/src/canvas-core/<film>Score.ts` inside the skill), and export it:
-
-```ts
-import type { Material } from "./music";
-export const score = (): Material => ({
-  style: "<style id>", title: "<this film's score>", seed: <any integer>, mood: "<mood id>",
-  bpm: <tempo in the style's range>, key: "<tonic>", mode: "<mode id>", meter: "<meter>",
-  moodControls: { energy: <0..1>, warmth: <0..1>, brightness: <0..1>, tension: <0..1>, space: <0..1> },
-  swing: <0.5 straight .. 0.67 hard>, dyn: [<start 0..1>, <end 0..1>], tail: <seconds of ring-out>,
-  chords: { "<name>": { voicing: "[<note> <note> <note>]", bass: "<one bar of notation>" }, /* ... */ },
-  motifs: { "<motif>": "<one or more bars of notation>", /* your variations are motifs too */ },
-  grooves: { main: { family: "<family>", density: <0..1>, variation: <0..1> }, half: { family: "<family>" } },
-  sections: [
-    { 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>"] },
-  ],
-});
-```
-
-A film plays it with `filmScore(score(), fps, frames)` from `canvas-core/score.ts`. That fits your
-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's
-  alternates. Or give your own `{ inst, role, opts }` (instruments: README table), with the slot's
-  role: `chords` and `arp` are `"accomp"`, `lead` is `"melody"`, `counter` is `"color"`, `bass` is
-  `"bass"`, drum lanes are `"drum"`. **Levels are one scale.** The palette voice, an alternate and
-  your own voice all sit at the slot's stem target (the column in
-  [styles/vocabularies.md](styles/vocabularies.md), fix included): alternates carry a measured trim,
-  and your own voice is placed from its instrument's measured level in the register your notes
-  play in. So leave your voice's `gainDb` out (0 = at the target) and set it, like `levels`, only
-  as an offset: `gainDb: 2` is two dB over. Then read `check`'s stems and adjust by the dB it
-  prints. Options (`attack`, `bright`, `drive`) move the level a little; a piano far up its range
-  is quiet by nature. `variant` and `sampled` are the two options that change which sound you get,
-  and they are in [Recorded instruments](#recorded-instruments) above.
-- **Loops:** `loop: true`, and the form length is the loop. `render` makes it seamless.
-- **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:DUR@0.7` 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
-  section, lines included.
-- **Section `energy`** (0..1, 0.5 = as written) sets the section's dynamics for every part,
-  hand-written lines included. It scales velocity from 0.55x to 1.45x, roughly -5 to +3 dB. It
-  also sets the density of generated grooves.
-- **`dyn`** is the whole piece's dynamic level `[start, end]`, ramped (default `[0.62, 0.66]`).
-  `swing` and `tail` default to the style's lower swing bound and 3.2 s.
-- **Modulation:** give a section its own `key` and `mode`. The key check then reads each key region
-  on its own. A lift of a step for the last chorus is fine when that section declares the new key.
-- **The key check weighs the tonic.** It accepts your declared tonic and mode when the mode's scale
-  explains the notes as well as any other reading, and the tonic is heard (at least 8 % of note
-  time). A lydian or dorian passage whose notes lean on another degree gets read as that degree's
-  major. Put the bass on the tonic at section starts and cadences, and state the mode's colour note.
-- **Written drums:**
-  - A `LiteralGroove` gives notation bars per lane (`kick`, `snare`, `ghost`, `hat`, `perc`).
-  - The bars cycle from each section's first bar; `cycle: "piece"` cycles on the piece's bar count
-    instead.
-  - Unpitched drums ignore the written pitch: write `C4`.
-  - A timpani in a drum lane (orchestral, choral, suspense, world) is tuned to the tonic of `key`,
-    generated grooves included (`epic`).
-
-**Notation** (bar-checked; a bar that doesn't add up throws, the last bar too: a line that ends
-mid-bar writes its rest, `C2:3 r:1`, never a silent gap):
-- A token is `NOTE:DUR[@VEL]` (a pitch name with an octave, e.g. `F#4`), `[NOTE NOTE ...]:DUR` (a
-  chord) or `r:DUR` (a rest).
-- Bars are separated by `|`, or given as array items.
-- Durations are in beats. In 6/8, 9/8 and 12/8 a beat is a dotted quarter, so an eighth is `1/3`.
-  In 7/8 a beat is a quarter, so an eighth is `.5` and a bar is 3.5.
-- `@VEL` scales the line's velocity (0..1).
-- In a hand-written piece, a one-bar sting on any beat says so: `line(t, "G6:1", { ..., hit: true })`.
-
-## What makes it beautiful (check before you call it done)
-
-- [ ] **One idea, developed.** One motif, heard 6-12 times, never the same way twice. A second idea
-  answers or contrasts it.
-- [ ] **A line you could sing.** Mostly steps, leaps that turn back, arches, and one high point per
-  phrase group in its second half.
-- [ ] **Questions and answers.** Phrases in 2s and 4s. Questions end open, answers end home.
-- [ ] **Feeling in the dissonance.** Chord tones on the beats. An appoggiatura or suspension where
-  the picture needs an ache, resolved down by step.
-- [ ] **Harmony that moves smoothly.** Common tones held, voices by step, the bass contrary to the
-  tune, the low end spread.
-- [ ] **A groove that breathes.** An anchored kick and backbeat, syncopation on top, rests in the
-  melody, a fill only at section ends.
-- [ ] **An arc.** Contrast by section in density, register, harmonic rhythm and groove. A dip
-  before the peak, the peak on the key frame, then release.
-- [ ] **Cadences on picture beats.** The claim, the reveal and the logo each get a structural
-  downbeat.
-- [ ] **An ending on a phrase:** a held home chord with the motif's last word, a button, or (suspense
-  only) an unresolved hold.
-- [ ] **Mood cues aligned.** Tempo, mode, register, density, articulation and brightness all point
-  at the words. If a listener names a different emotion, the choice was wrong, not the listener.
-- [ ] **Breadth.** Across projects, vary the meter, harmonic rhythm, groove family and form length.
-  Two scores for two products should not be siblings.
-
-## What checks what
-
-| Check | Runs in | Fails when |
-|---|---|---|
-| key/mode (`planProblems`) | `check`, `render` | a key region's notes don't support its declared tonic and mode |
-| composer warnings | `check`, `render` | (warns only) a line is shorter than its section, ... |
-| master | `check`, `render` | (notes only) the peak ceiling stopped the gain short of the target |
-| ghost guard | `check`, `render` | 4-bar windows are formless (few onsets, sustained, wet, no cadence) |
-| reverb guard | `check`, `render` | the late tail sits within 10 dB of the dry sound |
-| masking guard | `check`, `render` | the melody doesn't clear the other parts in 500 Hz-4 kHz |
-| stems | `check`, `render --stems`, `stems` | a part is more than 3 dB off target (lead: up to +6 dB allowed); advisory for uncalibrated styles |
-| craft | `craft`, `check` | (advisory scores and fixes) melody, harmony, rhythm, tension, mood fit; fails only on a note an acoustic instrument cannot play |
-| novelty | `check`, `novelty` | similarity above 0.5 to a shipped piece (or to each other), a reused 6-note melody fragment, or an 8-note melody shape in any key, meter or rhythm |
-
-`tools/music-unit.mjs` keeps the engine honest: determinism, no defaults, every vocabulary renders.

package/skills/anidoodle/references/music/sound-design.md

@@ -1,245 +0,0 @@
-# Sound design: the effects kit, placed by frame, heard over the score
-
-Every anidoodle sound effect is **built in code, from nothing**: no samples, no recordings, ever.
-(The music's acoustic instruments can play recordings from the optional sound pack; effects never
-do.) Every effect is deterministic: the same cue and seed give identical samples.
-
-Code: `engine/src/canvas-core/music/sfxKit.ts` (the kit), `sfxMix.ts` (placement), `sfxCore.ts`
-(building blocks). Tool: `engine/tools/sfx.mjs`.
-
-## What makes an effect sound designed, not generated
-
-- **Layers.** Every sound has a transient (the contact: a 1-4 ms filtered noise burst), a body
-  (modes of the struck object, a pitch-dropping sine, a friction band) and a tail (a small room from
-  `dsp.room`). A single noise burst is not an effect. It is a click.
-- **Physics, cheaply.** Plastic, bricks and bells are *modal*: a few damped sines at inharmonic
-  ratios. Drops and bubbles ring with a *rising* pitch. A whoosh is a *pass-by*: distance sets
-  level and air, radial speed sets the doppler glide (bright coming, darker going), angle sets pan.
-  A pen's friction band brightens with stroke speed.
-- **Stereo that moves.** Moving sounds travel across the field (`dir: 1` = left to right).
-  Hits sit a little off-centre with a Haas offset. Tails are decorrelated.
-- **No two hits alike.** Pitch, decay, pan, mode tuning and level (±1 dB) vary per seed. Twenty
-  key ticks are twenty different ticks. `mixSfx` gives each cue its own seed from (kind, frame), so
-  inserting a cue never changes the others.
-- **Tuned where it is tonal.** chime, riser, `press:confirm` and `impact:bloom` follow the film's
-  key. A sparkle in the wrong key sounds like a mistake, so there is **no default key or tempo**.
-  Pass `plan.score: { piece, tempo? }` (key, bpm and bar come from the film's piece) or set
-  `plan.key` / `plan.bpm`. A tuned kind with no key, or a riser with no bpm, throws.
-
-## The kit
-
-`node tools/sfx.mjs list` prints this live. The level is the target loudness over the sound's own
-speaking window (K-weighted, see below). Duck is how far the score dips under it.
-
-| kind | variants (first = default) | use it for | level | duck |
-|---|---|---|---|---|
-| tick | key, soft, ui, space | typing, one per character; a UI tick | -20.5 | 0 |
-| press | thock, soft, confirm | the Generate button; `confirm` adds a tuned answer | -13 | 2 |
-| pop | pop, cork, tiny | something appears; a card lands; a badge | -16 | 1 |
-| ink | plip, double, bloom | an ink drop; `bloom` opens an ink-bloom frame | -15 | 2 |
-| scratch | nib, pencil, marker | lettering being written (`lengthS` = writing time) | -18.5 | 1.5 |
-| paper | slide, flip, rustle | a sheet lands (hit = landing), a page turn (hit = snap) | -18 | 1.5 |
-| whoosh | soft, air, fast, deep | something passes the camera (hit = the pass-by) | -16 | 2 |
-| swish | in, out, soft | a UI panel or card slides | -17 | 1 |
-| riser | soft, air, tonal | THE build into the reveal (hit = its end) | -15 | 2 |
-| impact | boom, soft, bloom | THE reveal; `bloom` breathes in first and shimmers in key | -9 | 6 |
-| chime | sparkle, bell, glint | magic / success, tuned to the key | -17 | 1.5 |
-| bubble | bubbles, splash, gloop | water life, the koi | -16.5 | 1.5 |
-| brick | clack, snap, tumble | toy bricks: tap, press onto studs, drop on a pile | -15 | 1.5 |
-| thread | pull, pierce, stitch | embroidery: thread through cloth (hit = the tug), the needle | -17.5 | 1.5 |
-
-## Placing effects in a film
-
-Cues are addressed by **film frame**, a whole number (a fractional frame throws; to land a hit
-between frames, `snap` it to the beat). The frame is where the sound's sync point lands: the hit;
-the pass-by of a whoosh; the landing of a paper slide; the END of a riser. Pre-roll (a whoosh's
-approach, a riser's build) is rendered before the frame. If it would start before frame 0,
-the plan throws and names the earliest legal frame.
-
-```ts
-import { filmSfx, filmAudio, composePiece, type SfxPlan } from "./music";
-import { myScore } from "./myScore";                  // the Material YOU composed for this film (compose.md)
-const score = composePiece(myScore);
-const plan: SfxPlan = {
-  fps: 30, frames: 450, score: { piece: score }, beatZeroS: 0, seed: 7,  // key, bpm, bar from the score
-  cues: [
-    { frame: 12, kind: "tick" },                                          // ...one per typed character
-    { frame: 157, kind: "press", variant: "thock", snap: "beat", label: "Generate" },
-    { frame: 182, kind: "scratch", variant: "nib", lengthS: 1.4 },
-    { frame: 232, kind: "whoosh", variant: "soft", dir: 1 },
-    { frame: 400, kind: "riser", beats: 4 },                              // ends ON bar 5
-    { frame: 400, kind: "impact", variant: "bloom", snap: "bar" },
-  ],
-};
-export const audio = filmSfx(filmAudio(score, 15), plan);   // Film.audio: score + effects
-```
-
-- `snap: "bar" | "beat" | "8th" | "16th"` moves the sync point to the tempo grid (`bpm`,
-  `beatZeroS`, `beatsPerBar`). Snap musical moments: the reveal on the bar, a sparkle on the beat.
-  Keep UI sounds (typing, clicks) on the picture.
-- `beats` sizes a riser in tempo. Its chord pulses in 8ths, then 16ths, then 32nds, and it stops
-  on the downbeat.
-- Per cue: `variant`, `seed`, `pitch` (semitones), `gainDb`, `dir`, `lengthS`, `duckDb`, `minDb`,
-  `label`.
-- `mixSfx(music, plan)` returns the mix, the stems (`sfx`, ducked `music`), the duck curve, every
-  placed cue and the audibility table. `filmSfx` wraps it for `Film.audio` and **throws on a
-  buried cue**.
-- One master at the very end: a look-ahead true-peak ceiling at -1 dBTP (`ceilingDb`). The score
-  arrives already mastered, so nothing is renormalised.
-
-## Sound across a cut (J-cut and L-cut)
-
-The cheapest smooth seam works on the ear: the sound crosses the cut ahead of the picture or
-behind it. In a **J-cut** the next scene is heard before it is seen, 0.3 to 0.8 s early (the
-pond's bubbles under the last shot of the room, the nib scratching before the page appears). In an
-**L-cut** the last scene is still heard 0.5 to 1.5 s into the next (a page still rustling, a pen
-still scratching). The ear makes the join first, so the picture cut lands as an answer. It uses
-the same cue table: cue the incoming scene's sound at `CUT - lead` (`{ frame: CUT - 15, kind:
-"bubble" }`). To carry the outgoing sound past the cut, give it a longer `lengthS` where the kind
-takes one (scratch, paper, whoosh, swish, riser, thread); for the others, place a few quieter cues
-of that scene's sound after the cut. The score can do it too, entering its next section a beat
-before the cut (a pre-lap), or letting the old chord ring over the first beat of the new scene.
-This never moves a hit: a contact's sound stays on its own frame (Land on the frame, below). What
-crosses the cut is a scene's ongoing sound, never a hit's. Deck card `seam-sound-leads`.
-
-## Levels and the audibility rule
-
-A cue nobody hears is a bug, not a subtle choice. A test that only checks a cue exists proves
-nothing: test that it is heard over the music at its own moment.
-
-- Every cue is measured against the ducked score **at its own moment**. The yardstick is
-  K-weighted (BS.1770) loudness over the cue's *speaking window*: the 10 ms frames within 10 dB of
-  its loudest, 15-500 ms long. The score is measured over the same window, at least 100 ms.
-- **margin = cue - score.** The mix fails if any cue is more than `minDb` under (default **-6
-  dB**). Short transients cut through at -3 to -6. Sustained textures (scratch, thread) want -3
-  or better.
-- To fix a failing cue, raise its `gainDb` first. Raise its `duckDb` only for the moments that
-  matter.
-- Ducking: the score dips before the cue's window (40 ms raised-cosine attack), holds, and comes
-  back over 280 ms (1.2 s after an impact). Typing does not duck. The reveal ducks 6 dB.
-- Measured on our own launch film's score (`launchLofi3`: a demo, never a score for your film;
-  first 15 s, 33 cues): -15.5 LUFS, -1.9 dBTP, every cue audible. Margins: typing +3 to +8 dB over the intro pad; groove cues -3.5 to +5 dB; the reveal +10.7 dB.
-
-## Taste: when to use effects
-
-- **Effects only on real direction changes.** A press, an appearance, a scene move, a landing.
-  Never under every motion, and never a constant bed of whooshes. Silence around a cue is what
-  makes it land.
-- **One signature riser, one impact per film.** They mark the big reveal. A second riser halves
-  both.
-- Transitions are gentle moves by default, so their sound is gentle: `whoosh:soft` and
-  `swish:soft`. A matched hard cut takes a short hit on the beat or nothing. Never a sharp swoosh.
-- Typing is one `tick` per character at the typing cadence, with `space` on spaces. Its level sits
-  above the intro and under the groove.
-- Put at most two cues in any 100 ms. A thock on the kick merges into the kick, which is lovely
-  when it starts the groove and mud anywhere else.
-- Hear it in context before it ships. Render the kit page (`node tools/sfx.mjs kit <dir>`) and a
-  demo over the real score, and check the audibility table.
-- **Restraint is the design.** A cue earns its place by marking something the viewer should feel: a
-  press, an arrival, a landing, the reveal. Picture changes that are only edits stay silent. Count
-  your cues against the film's length; if you cannot say what each one marks, cut it.
-- **Land on the frame.** A hit belongs on the frame where the thing happens; within a frame either
-  side reads as one event. A soft lead into the hit reads as anticipation. A hit's sound after its
-  picture reads as lag, which is the one error a viewer always notices. (A place's sound may run
-  past a cut: Sound across a cut, above.)
-- **One voice per job.** Every press of every button is the same click, at the same level, so the UI
-  feels like one object. Variety goes to the story moments, not to repeats of the same action.
-- **The ending breathes.** The music settles on the tonic or lets its last chord ring, a beat of
-  near silence before the final mark if the film has one, and the tail rings out to the last frame.
-  Never a cut-off, never dead air after it.
-
-## The finished mix
-
-What the whole film's sound must be before it ships, score and effects together:
-
-- **On its loudness target.** The delivery master (`music/delivery.ts`, the last stage of `mixSfx` and
-  `mixLaunch`) sets one static gain to -16 LUFS (gentle) or -14 (dense, launch films), then a smooth
-  true-peak limiter with its work capped (4 dB gentle, 6 dense): past the cap the gain gives way
-  instead of the hits being squashed, and the shortfall is reported. `master: "none"` keeps the old
-  peak-only ceiling. A score-only film keeps its own master (music/README.md, Master).
-- **Never digital silence.** An effects-only film sits on room tone 22 dB under its cues (`bed`), nearly
-  mono so a phone keeps it, from the first frame to the last.
-- **A finished shape.** Sound from the first frame (within 0.5 s), no hole over 0.25 s, the last sound
-  within 0.5 s of the last frame. A silence the film means (a held breath, a pause on a beat) is declared in
-  `meta.quiet` as `[fromFrame, toFrame, reason]`. `verify-export --delivery` fails the shape, a true
-  peak over -1 dBTP after the encode, and loudness under -19 LUFS; it warns from -17.
-
-
-## Checking the finished film's sound
-
-Before the film goes to anyone, put numbers on the mix that was actually delivered. Two tools take
-the rendered file and do it (give a film name for `out/<name>.mp4`, or point at a `.wav` or `.m4a`):
-
-```
-node tools/soundcheck.mjs <film|file>                 # the scorecard; exit 1 on any FAIL
-node tools/soundcheck.mjs <film> --json --out x.json  # the same, as data
-node tools/soundcheck.mjs <film> --allow 3.1:3.6      # the silence there is a declared held breath
-node tools/soundsheet.mjs <film> -o out/<film>-sound.png   # one picture of it all
-```
-
-Each metric in `soundcheck` gets a status line: PASS, WARN or FAIL when it has a range, INFO when
-it is only reported. Under them comes **START HERE**, the changes to make ranked by importance, and
-every one is specific about where and what: "3.4 s hole at 0:03.4", "crowded body, strongest near
-630 Hz: notch it a couple of dB", "mids decorrelated: narrow the stereo width below 2 kHz". The
-numbers fall into five groups:
-
-- level: integrated LUFS, true peak, loudness range, loudest 3 s, intro and end level, an
-  11-point arc, the loudest moment;
-- shape: when the first sound arrives, any holes mid-film, dead air after the last sound, the fade,
-  the closing moment, an ending that cuts off, how many onsets and accents (sudden jumps in level)
-  there are per second, and held breaths (short dips that come straight back);
-- spectrum: how the energy splits across five bands (rumble, warmth, body, bite and sparkle,
-  20 Hz to 16 kHz), plus the centroid;
-- stereo: side vs mid, L/R correlation overall and per band (150 Hz-2 kHz is where phones comb
-  the body away), and how much more than the expected 3 dB the mix loses folded to mono;
-- picture (any file with video): frame-difference events, the share with an onset within 100 ms
-  against a chance baseline, the events with no sound, and the median onset offset. INFO only:
-  not every picture change is meant to be a cue.
-
-The built-in ranges are for drawing films: -16 to -13 LUFS (web target -14, gentle films -16),
-true peak at or under -1 dBTP, LRA at most 9 LU, sound by 0.5 s, no hole over 0.25 s, at most
-0.5 s of silence at the end, 150 Hz-2 kHz correlation at least 0.3, at most 1.5 dB of extra mono
-loss, and the rumble (under 80 Hz) at or under -5 dB of the energy.
-
-When the user has films whose sound they love, score against those instead:
-`node tools/soundcheck.mjs profile <films...> -o references/music/sound-profile.json`, then pass
-`--profile references/music/sound-profile.json`. The profile shifts the ranges that are a matter
-of taste (loudness, bands, width). The ranges a delivery must meet (true peak, first sound, holes,
-end silence, mono loss) do not move.
-
-`soundsheet` lays the whole soundtrack out on one timeline, top to bottom: a strip of frames, the
-spectrogram, the waveform, momentary and short-term loudness with the integrated level and -14
-marked, then rows of onsets, accents and picture events (a picture event turns red when no sound
-lands on it). Holes and dead air at the end are shaded. Look at it before handing the film over;
-a gap, a silent ending or a late accent is obvious on the page.
-
-The metrics live in `engine/src/canvas-core/music/soundcheck.ts`, tested on synthetic faults in
-`engine/test/soundcheck.test.ts`.
-
-## Tools and checks
-
-```
-node tools/sfx.mjs list                              # kinds, variants, levels, uses
-node tools/sfx.mjs one whoosh soft 3 out.mp3         # one sound
-node tools/sfx.mjs kit <dir>                          # every variant x3 + demo + page + meters.json + spectra/
-node tools/sfx.mjs test                               # the gate
-node tools/soundcheck.mjs <film>                      # the finished film's sound (see above)
-```
-
-The test checks every kind and variant for:
-
-- determinism (md5 of two renders) and seed variation;
-- no NaN, no DC, a peak of -1 dBFS or lower, an end at zero, and no fizz above 20 kHz (a
-  16.5 kHz air roll-off is built in);
-- a non-silent sound whose level stays stable across seeds.
-
-It also checks:
-
-- the whoosh's doppler and pan travel;
-- a chime tuned to its key;
-- a riser synced to tempo, and snap-to-beat;
-- the demo: deterministic, at film length, true peak within ceiling, every cue audible, the score
-  ducked under the impact;
-- that a buried cue fails;
-- that validation throws clearly on an unknown kind or variant, a pre-roll before frame 0, a bad
-  seed, a frame outside the film, a snap without bpm, a bad key, or a pitch out of range.