@typeonce/ritmo-tools 0.17.0 → 0.19.0

package/CHANGELOG.md

@@ -1 +1,51 @@
 # @typeonce/ritmo-tools
+
+## 0.19.0
+
+### Minor Changes
+
+- 6e69a51: `ritmo-tools pixel`: project PNGs. A project PNG is the source picture with its recipe stored inside (one uncompressed `iTXt` chunk, keyword `ritmo-pixel-recipe`; the pixels are untouched), so one file reopens a whole session. The web page exports one (Export → **Project PNG**, for pictures and animation sheets) and restores every setting when it opens one. `pixel fix --project` writes `<name>.project.png`, and `check`, `fix`, `sheet`, and `preview` run the recipe a project PNG holds (a `--recipe` file wins over it; the report says `"storedRecipe": true`). A project PNG is not a game asset: `exiftool -all=` or `oxipng --strip safe` turns it back into the plain picture.
+
+  Grid detection finds cells that a screenshot or resize stretched a few percent on one axis, instead of falling back to a fraction of the cell (a sprite came out 25×68 instead of 28×32).
+
+  The `ritmo-pixel-art` skill says when to hand a person a project PNG, and how to spot and strip one.
+
+- 612c30a: `ritmo-tools pixel`: several animations on one sheet. Each row of frames is one animation by default (`animation-1`, ... in reading order; where two blocks sit side by side, a row across both is split where they meet). The page's **Animations** panel chooses which are exported (**In**/**Out**), plays, renames, and sets each one's speed and loop, and **Split here** (between two frames of the chosen animation) and **Join with** regroup them. Each animation gets its own canvas. The sheet PNG holds every exported animation, each from a new row; its JSON names each one under `animations` and `frameTags`, frames are named `<animation> 0`, ..., and `meta.fps` is a map from animation to frames per second. `pixel sheet` writes a GIF per animation (`<name>.<animation>.gif`) and frames under `.frames/<animation>/`, lists the animations in its report (`animation.animations`), and takes `--animations "walk=1-4;explode=5-14"` and `--only walk,explode`.
+
+  Breaking, for recipes and code reading the sheet: `sheet.fps` and `sheet.loop` moved onto each animation (`sheet.animations[i].fps`, `.loop`). A recipe without `animations` still reads, as one animation of every frame at its `fps` and `loop`. The report's `animation.fps` and `animation.loop` are now per animation in `animation.animations`, and `output` is the size of the sheet written.
+
+  The `ritmo-pixel-art` skill says how to name and pick animations with `--animations` and `--only`.
+
+- 832169a: `ritmo-tools music`: game music as JSON songs (a tempo, a key, bars, and tracks of notes, each track one of sixteen synthesized instruments: piano, electric piano, acoustic and distorted guitar, bass guitar and a reese bass, strings, flute, marimba, bells, a pad, a supersaw lead, two chiptune voices, and a clean and a punchy drum kit; `"compressor": true` squeezes a rock or electronic song louder and punchier). `music listen <song> <audio.wav>` hears a hum, a whistle, a tapped beat, or a recording and writes its tempo, key, and melody into the song as its reference, for the agent to build the song around; a voice that sits off pitch the whole way is heard in tune. `music check` measures the song and lists what usually sounds wrong (clipping, notes outside the key or an instrument's range, a buried track, a melody that wandered from the reference); `music render` writes a seamless looping WAV, a MIDI file, and with `--stems` each track alone. `music review <song>` opens a local page where a person plays the song, records a hum from the microphone, edits notes on a grid, swaps instruments, and comments on bars; `music notes` gives the agent the comments and a list of the person's edits.
+
+  `@typeonce/ritmo` ships a new skill, `skills/ritmo-music`. Link it next to the others:
+
+  ```sh
+  ln -s ../../node_modules/@typeonce/ritmo/skills/ritmo-music .agents/skills/ritmo-music
+  ```
+
+- 818ad0b: `ritmo-tools sound`: game sounds as JSON recipes. Agents write sounds into one bank file, check them (`sound check`: length, loudness, clipping, a late start, a click at the end, much louder or quieter than their kind), make takes nudged one way (`sound vary --toward heavier`), and write WAV files (`sound render`). `sound review <bank>` opens a local page where a person listens, picks among takes, tunes with sliders, and approves or notes each sound; `sound notes` gives the agent the person's answers.
+
+  `@typeonce/ritmo` ships a new skill, `skills/ritmo-sounds`. Link it next to the others:
+
+  ```sh
+  ln -s ../../node_modules/@typeonce/ritmo/skills/ritmo-sounds .agents/skills/ritmo-sounds
+  ```
+
+### Patch Changes
+
+- 793a5f3: The pixel fixer's page opens pixel art that is already at its own size (a small sprite, even with an image generator's noisy colors) one pixel per cell, as `ritmo-tools pixel check` does, instead of applying an unsure grid its own shapes suggest (a 24×24 sprite came out about 8×8).
+
+  Animation sheets: frames are found on sheets made of blocks side by side whose rows do not line up (walking on the left, throwing on the right), instead of boxing frames from two rows together, and a last frame of a few pixels (the end of an explosion) is kept instead of dropped. Such a sheet opens as an animation: most frames alike is enough, so a few faint frames (sparks, smoke) no longer make the page open it as a single picture.
+
+## 0.18.0
+
+### Minor Changes
+
+- 8322cd7: New package `@typeonce/ritmo-tools`: the `ritmo-tools` command, asset tools for agents. `ritmo-tools pixel` is the pixel fixer: it checks, fixes, and makes pixel art, and fixes animation sheets from image generators (`ritmo-tools pixel sheet`) onto one grid and palette, lined up, as a sprite sheet with its JSON (Pixi, Phaser, Aseprite) and a GIF. Run it with `npx @typeonce/ritmo-tools pixel <command>`, or add it as a dev dependency.
+
+  `@typeonce/ritmo` ships a new skill, `skills/ritmo-pixel-art`, telling agents which `ritmo-tools pixel` command to run for each case. Link it next to the others:
+
+  ```sh
+  ln -s ../../node_modules/@typeonce/ritmo/skills/ritmo-pixel-art .agents/skills/ritmo-pixel-art
+  ```

package/README.md

@@ -7,6 +7,8 @@ tool per kind of asset:
 | Tool | For |
 | --- | --- |
 | `ritmo-tools pixel` | Pixel art: fixes AI-made or blurry pictures and animation sheets onto a true pixel grid and a palette, renders sprites drawn as text, and checks a project's art against its rules. |
+| `ritmo-tools sound` | Sound effects: keeps them as JSON recipes, measures and varies them, writes WAV files, and opens a local page where a person listens, picks, tunes, and notes. |
+| `ritmo-tools music` | Game music: hears a person's hum for its tune, tempo, and key, keeps songs as JSON tracks of notes, checks them, writes WAV and MIDI files, and opens a local page where a person plays, edits notes, records, and comments. |
 
 ```sh
 npx @typeonce/ritmo-tools pixel check art.png
@@ -15,7 +17,9 @@ pnpm add -D @typeonce/ritmo-tools   # pins it to the game's Ritmo version
 
 Every command prints JSON on stdout and exits with a code that says what
 to do next. A game's agent learns them from the skills that ship with
-`@typeonce/ritmo` (`skills/ritmo-pixel-art`), linked by its `SETUP.md`.
+`@typeonce/ritmo` (`skills/ritmo-pixel-art`, `skills/ritmo-sounds`,
+`skills/ritmo-music`), linked by
+its `SETUP.md`.
 The tools are built on Effect; nothing a game imports depends on this
 package.
 
@@ -53,7 +57,8 @@ pnpm --dir website build          # the site, with the page at dist/tools/pixel/
 ```
 
 Open a picture (PNG or JPEG: **Open** in the top bar, drag and drop, or paste), or press
-**Try the demo** for a fake AI picture of a mushroom. The same button opens a sprite source
+**Try the demo** for a fake AI picture of a mushroom. The same button opens a project PNG
+(the picture with every setting it was saved with), a sprite source
 (`.txt`) or a JSON map as pixel art at its own size, a recipe (applied to the
 picture open), and a `pixel.config.json` (its rules, palette, and settings).
 
@@ -157,7 +162,8 @@ node packages/tools/bin/ritmo-tools.mjs pixel check art.png   # from its source,
    units with crisp edges (it stays sharp at any size; same-colored areas are
    merged into rectangles); a JSON map (size, palette, one row of palette
    indices per pixel row, -1 for transparent); the palette as `.hex` or `.gpl`;
-   **Sprite text** (the sprite source format below); and the **Recipe**.
+   **Sprite text** (the sprite source format below); the **Recipe**; and the
+   **Project PNG** (below).
 
 **Undo** and **Redo** (in the top bar, or Ctrl/Cmd+Z and Ctrl/Cmd+Shift+Z
 or Ctrl+Y) cover every setting: the grid, the palette, the background,
@@ -167,25 +173,41 @@ step. Opening another picture starts the history over.
 ### Animations
 
 An image generator asked for an animation draws a sheet: the frames side by
-side (or in rows), each in a box, over a dark background with a painted grid,
+side (or in rows, often one animation per row: walking each way, throwing,
+exploding), each in a box, over a dark background with a painted grid,
 often with a label under each frame. Open it like any picture: when the
-fixer finds several boxes holding about as much art each, it opens the sheet
-as an **Animation** and says so. **Picture** and **Animation** in the top bar
+fixer finds several boxes, most of them holding about as much art each (a
+few faint ones, like the last smoke of an explosion, do not count against
+it), it opens the sheet as an **Animation** and says so. **Picture** and **Animation** in the top bar
 switch between the two at any time; everything about pictures above stays as
 it is.
 
 - **Frames.** The sheet's background is cleared from its border (the painted
   grid and the boxes with it), and each run of art is a frame: rows of art
   are split where the columns empty out, and short rows (the labels) are
-  dropped. A grid painted behind the frames is painted out first, where it
+  dropped. A box that still holds frames one over another (blocks side by
+  side whose rows do not line up) is cut into rows again, and a frame of a
+  few pixels set apart like the others (the last wisp of smoke) stays a
+  frame. A grid painted behind the frames is painted out first, where it
   runs over the background, so lines as dark as the art's outline never
   flood into the art; how close a color must be to the background follows
   how noisy the background is. The **Sheet** view shows the source with every frame's box,
   numbered. Choose **Boxes** (F) to drag a box, resize it by its handles, or
   draw a new one on empty space when something was cut out; Delete removes the
-  selected box. **Frames** on the right lists every frame: **In**/**Out**
-  leaves one out of the animation without losing its box, and **Find again**
-  starts over (boxes changed by hand are dropped).
+  selected box. Each box is tinted with its animation's color.
+- **Animations.** Each row of frames is one animation, named
+  `animation-1`, `animation-2`, ... in reading order; where two blocks sit
+  side by side (walking on the left, throwing on the right), a row across
+  both is split where they meet, when its two parts hold as many frames as
+  the blocks' rows. **Animations** on the right lists them: **In**/**Out**
+  chooses which are exported (the others keep their frames and settings);
+  choose one to play it, rename it (the name a game plays it by), and set its
+  speed and loop. Its frames are listed under it: **In**/**Out** leaves one
+  out without losing its box. **Split here**, on the line between two of
+  its frames, cuts the animation in two there (the frames after it become a
+  new animation), and **Join with** puts it together with the next one, for
+  a sheet whose rows are not its animations. **Find again** starts over
+  (boxes and animations changed by hand are dropped).
 - **Grid and palette.** Every frame is read on one cell size (found from all
   the frames together, or typed), each at its own offset, and fixed with one
   recipe: the palette, matching, and cleanup are the picture's settings, and
@@ -196,23 +218,51 @@ it is.
   height it was drawn, so a hop or a bob stays; **Feet** pins the body's
   lowest row to one spot (hops are flattened); **Center** pins the body's
   middle, for things that float; **Box** places frames as cut. Arrow keys nudge the selected frame by a pixel
-  (Shift: 4). **Margin** sets the empty pixels around the frames.
-- **Playing.** The **Play** view shows the animation running, with the grid
+  (Shift: 4). Each animation gets its own canvas, the smallest that holds
+  its frames; **Margin** sets the empty pixels around them.
+- **Playing.** The **Play** view shows the chosen animation running, with the grid
   if you want it; Space plays and pauses, `,` and `.` step a frame, and the
   bar under it sets the frame rate, **Loop** or **Ping-pong**, and **Onion**
   (the previous frame, faint, under the current one). **Frames** shows them
   all side by side; click one to select it.
-- **Export.** A **Sheet PNG** with every frame in one row or in rows of
-  **Per row** frames, with **Spacing** between them, at any whole scale; its
+- **Export.** A **Sheet PNG** with every exported animation, each from a
+  new row, its frames in one row or in rows of **Per row** frames, with
+  **Spacing** between frames and animations, at any whole scale; its
   **JSON** in the hash format Pixi (`Spritesheet`), Phaser (`atlas`), and
-  Aseprite share, with each frame's rectangle, duration, and anchor, the
-  animation's frame list, and Aseprite's `frameTags`; a **GIF**; **Frames
-  .zip** (one PNG per frame); the **Recipe** (frames, anchor, frame rate, and
-  loop included); and the palette.
+  Aseprite share, with each frame's rectangle, duration, and anchor (frames
+  are named `<animation> 0`, `<animation> 1`, ...), each animation's frame
+  list under `animations`, and Aseprite's `frameTags`; a **GIF** of the
+  chosen animation; **Frames .zip** (one PNG per frame, a folder per
+  animation); the **Recipe** (frames, animations, and anchor included); and
+  the palette.
 
 Hand edits (**Erase**, **Paint**) and **Size** are for single pictures and
 are not offered for animations.
 
+### Project PNGs
+
+A **Project PNG** (in Export) is the source picture with the recipe stored
+inside it, so one file holds the whole session: open it on the page and every
+setting comes back, hand edits included. It is how to share work in progress
+or pick it up later; nothing leaves the device unless you send the file. It is
+not a game asset: export the fixed art for that.
+
+The picture's pixels are untouched (a PNG opened keeps its own bytes; another
+format is stored as PNG). The recipe is one uncompressed `iTXt` text chunk
+with the keyword `ritmo-pixel-recipe`, right after the header, holding the
+recipe JSON: about 0.5 to 2 KB, more with many hand strokes. Viewers ignore
+it. Some apps re-encode pictures and drop it (chat apps sending a photo as a
+photo): send it as a file. A project PNG without its chunk opens as the plain
+picture.
+
+To see the recipe: `exiftool art.png`, `pngcheck -t art.png`, or
+`grep -a ritmo-pixel-recipe art.png`. To remove it: `exiftool -all= art.png`,
+`oxipng --strip safe art.png`, or `pngcrush -rem text in.png out.png`; what is
+left is the plain picture. `ritmo-tools pixel fix --project` writes one from the CLI, and
+`check`, `fix`, `sheet`, and `preview` run the recipe a project PNG holds (a
+`--recipe` file wins over it; the report says `"storedRecipe": true` when it
+ran).
+
 ### The CLI
 
 `ritmo-tools pixel` runs the page's pipeline from the command line, for agents. It is
@@ -225,8 +275,8 @@ the source), 4 needs a person (the grid is unsure: look at the preview).
 | Command | What it does |
 | --- | --- |
 | `check <file>` | Clean pixel art, fixable with confidence, or needs a person? Writes nothing. |
-| `fix <png>` | Fixes it, writing `.png` (1x), `@Nx.png` (`--scale N`), `.svg`, `.json` map, `.sprite.txt`, `.recipe.json`, and `.preview.png`. |
-| `sheet <png>` | Fixes an animation sheet: `.png` (the frames in a strip, or `--columns N` per row), its `.json`, a `.gif`, `.frames/` (one PNG each), `.recipe.json`, and `.preview.png` (the boxes found over the source, and the fixed frames). |
+| `fix <png>` | Fixes it, writing `.png` (1x), `@Nx.png` (`--scale N`), `.svg`, `.json` map, `.sprite.txt`, `.recipe.json`, and `.preview.png`; `--project` also writes `<name>.project.png`. |
+| `sheet <png>` | Fixes an animation sheet: `.png` (each animation's frames in a strip from a new row, or `--columns N` per row), its `.json`, a `.<animation>.gif` each, `.frames/<animation>/` (one PNG per frame), `.recipe.json`, and `.preview.png` (the boxes found over the source, and each animation's fixed frames). The report lists the animations with their frame numbers. |
 | `pixelate <png> -w N` | Cuts a picture that is not pixel art into N pixels across, on the palette (or `--colors N` proposed from it). |
 | `render <sprite>` | Renders a sprite source or JSON map to PNG and SVG, and lints it. |
 | `lint <file>` | The project's rules on the pixels as they are. |
@@ -238,9 +288,11 @@ the source), 4 needs a person (the grid is unsure: look at the preview).
 `fix`, `check`, `pixelate`, and `preview` take the page's settings as flags
 (`--palette`, `--cell 8x8 --offset 2,3`, `--follow`, `--cleanup`,
 `--remove-background`, `--crop`, `--dither`, `--metric`, `--shrink-to`), over a
-`--recipe` file, over the config. `ritmo-tools pixel <command> --help` lists them. `sheet` takes them too, plus
-`--boxes`, `--skip`, `--anchor`, `--fps`, `--pingpong`, `--columns`, and
-`--spacing`. Every command reads PNG and JPEG.
+`--recipe` file (or the recipe a project PNG holds), over the config. `ritmo-tools pixel <command> --help` lists them. `sheet` takes them too, plus
+`--boxes`, `--skip`, `--animations` (which frames make which animation:
+`"walk=1-4;throw=5-8;explode=9-18"`, every frame in one), `--only` (the
+animations to write, by name: `"walk,explode"`), `--anchor`, `--fps`,
+`--pingpong`, `--columns`, and `--spacing`. Every command reads PNG and JPEG.
 
 **`pixel.config.json`**, found from the working directory up (or
 `--config`), holds a project's rules: `palette` (a preset's name, a list of
@@ -311,7 +363,8 @@ of the true size, which are as clean but have half their lines mid-cell.
   (colors the palette lost), `export.ts` (PNG pixels,
   SVG, JSON), `demo.ts` (the fake AI picture generator),
   `pipeline.ts` (the whole fix, from a picture and a recipe: what the page and
-  the CLI both run), `recipe.ts` (recipes as JSON), `sprite.ts` (sprite
+  the CLI both run), `recipe.ts` (recipes as JSON), `project.ts` (project
+  PNGs: the recipe in a PNG text chunk), `sprite.ts` (sprite
   sources), `lint.ts` (the rules), `report.ts` (the check and its verdict),
   `preview.ts` (pictures to look at), `sheet.ts` (clearing a sheet, finding
   its frames, anchors, and laying frames on one canvas), `animation.ts` (the
@@ -325,3 +378,230 @@ of the true size, which are as clean but have half their lines mid-cell.
   JPEG through `jpeg-js`;
   `src/cli.ts` is `ritmo-tools` itself, and `bin/ritmo-tools.mjs` runs it from
   its TypeScript source inside the repository.
+
+## Sound lab (`ritmo-tools sound`)
+
+Game sounds as JSON recipes, for agents and the people they make games with.
+An agent writes and checks sounds from the command line; a person listens,
+compares, tunes, and notes them on a local page in the pixel fixer's look.
+Both use one renderer, so what the person hears, what the agent measures,
+and what the game plays are the same samples.
+
+Its page is built from the pixel fixer's kit, so the two tools look and
+work alike.
+
+### Recipes and banks
+
+A recipe is a few layers built from small instruments, mixed into a room:
+
+```json
+{
+  "about": "A blow lands: a short thud and a crack.",
+  "reverb": 0.12,
+  "layers": [
+    { "type": "click", "gain": 0.45 },
+    { "type": "tone", "wave": "sine", "from": 160, "to": 55, "duration": 0.12, "attack": 0.002, "gain": 0.65 },
+    { "type": "crunch", "from": 1500, "to": 500, "duration": 0.07, "gain": 0.3 }
+  ]
+}
+```
+
+| Layer | What it is |
+| --- | --- |
+| `tone` | A wave (`sine`, `triangle`, `square`, `sawtooth`) gliding `from` → `to` Hz: thuds, notes, hums. |
+| `noise` | Noise through a filter (`lowpass`, `highpass`, `bandpass`) gliding `from` → `to` Hz, with `q`: air, hiss, rumble. |
+| `swish` | A band of noise rising from `low` to `peak` Hz, loudest at `peakAt`: a swing. |
+| `crunch` | Distorted band-passed noise: the crack of a blow. |
+| `metal` | Inharmonic partials of `pitch` Hz, the higher dying first: a ring. |
+| `click` | A short tick at the very start, for punch. |
+
+Every layer has `gain` and an optional `delay` in seconds. A recipe may
+carry `heavy` (it ducks the others in the game's mixer), `interval` (the
+least time between two plays), and a `tune` the person set with sliders
+(`pitch`, `length`, `brightness`, `echo`, `volume`), kept apart from the
+layers so it reads at a glance.
+
+A bank is one file of named recipes and the game's master volume:
+`{"version": 1, "master": 0.6, "sounds": {...}}`. Its review lives next to
+it (`game.sounds.json` → `game.sounds.review.json`): each sound's status
+(`new`, `approved`, `changes`), the person's note, and the takes offered.
+`examples/spirit-call.sounds.json` in the repository is Spirit call's 46 sounds.
+
+### The command line
+
+`npx @typeonce/ritmo-tools sound <command>` (inside the Ritmo repository, `node packages/tools/bin/ritmo-tools.mjs sound <command>`).
+Every command prints JSON and exits 0 (clean), 2 (usage error, missing
+file, broken bank), or 3 (a sound has errors).
+
+| Command | Does |
+| --- | --- |
+| `ritmo-tools sound init [bank]` | Writes a starting bank of three sounds. |
+| `ritmo-tools sound check <bank> [names...]` | Measures each sound (length, peak, loudness, attack, brightness, ending) and lists what breaks the rules: clipping, silence, a late start, a click at the end, much louder or quieter than its kind. |
+| `ritmo-tools sound render <bank> [names...] [-o dir] [--sequence 0.25]` | Writes WAV files, and with `--sequence` the sounds in a row. |
+| `ritmo-tools sound vary <bank> <name> --toward heavier [--count 4] [--seed 1]` | Makes takes nudged one way (`heavier`, `lighter`, `brighter`, `darker`, `punchier`, `softer`, `shorter`, `longer`, or `wider` for anything) and offers them in the review. |
+| `ritmo-tools sound review <bank> [--port 5190] [--host]` | Serves the review page and prints its address; runs until stopped. |
+| `ritmo-tools sound notes <bank>` | What the person said: status and note for each sound, changes asked first. |
+
+### The review page
+
+`ritmo-tools sound review` opens the bank on a local page: the sounds on the left with
+their status, the selected sound's wave and layers on the stage with the
+takes beside each other, and on the right its review, its check, the takes
+maker, tune sliders, and the layers' numbers (takes and layers start closed).
+Space plays, the arrows move through the list, 1 to 9 play the takes, and
+Ctrl/Cmd+Z undoes. Every change is written to the bank and its review as it
+happens, and changes the agent writes while the page is open show up in it.
+`--host` serves it on the network too, to listen on a phone.
+
+### Code
+
+- `src/sound/core/`: recipes (`recipe.ts`), the renderer (`render.ts`, plain
+  TypeScript that plays the same in Node and the browser), the measures and
+  checks (`measure.ts`), takes (`takes.ts`), reviews (`review.ts`), and WAV
+  files (`wav.ts`).
+- `src/sound/cli/`: the `sound` command (Effect), and the review page's
+  server (`serve.ts`).
+- `src/sound/ui/`: the review page, built from the pixel fixer's kit. The
+  published package carries it built (`dist/sound/page`, made by `prepack`);
+  inside the repository Vite serves it from source.
+
+## Music lab (`ritmo-tools music`)
+
+Game music as JSON songs, for agents and the people they make games with,
+most of whom are not musicians. The person hums the tune they have in mind
+(or gives a recording); the tool listens and writes down its tempo, key, and
+melody; the agent builds a song around it; the person plays it, edits notes
+on a grid, swaps instruments, and comments on bars, on a local page in the
+pixel fixer's look. One renderer serves the page, the checks, and the WAV,
+so what the person hears is what the agent measured.
+
+### Songs
+
+```json
+{
+  "version": 1,
+  "about": "Village at dusk: the hum's tune on a flute over picked guitar.",
+  "tempo": 93,
+  "key": "D minor",
+  "bars": 8,
+  "master": 0.65,
+  "tracks": [
+    { "name": "Melody", "instrument": "flute", "volume": 0.6, "reverb": 0.35, "notes": [
+      { "at": 0, "length": 1, "pitch": "D5" },
+      { "at": 1, "length": 0.5, "pitch": "F5", "velocity": 0.7 }
+    ] },
+    { "name": "Drums", "instrument": "drums", "volume": 0.9, "reverb": 0.15, "notes": [
+      { "at": 0, "length": 0.5, "pitch": "kick" }
+    ] }
+  ]
+}
+```
+
+Time is in beats from the start (`at: 4` is bar 2 in 4/4); `length` is in
+beats; `pitch` is a note name (`"C4"` is middle C, `"F#3"`, `"Bb2"`) or, on a
+drum track, a drum (`kick`, `snare`, `hat`, `openHat`, `clap`, `tomLow`,
+`tomHigh`, `crash`, `rim`, `shaker`); `velocity` (0 to 1, default 0.8) is how
+hard a note is played. A song has `beatsPerBar` (default 4), `loop` (default
+true: the WAV is one pass long and its tail wraps into its start, so it
+repeats without a seam), `master`, and `compressor` (default false: true
+squeezes the whole mix louder and punchier, its peaks held under -1 dBFS,
+for rock, drum & bass, and electronic songs; stems stay uncompressed, for
+the game to mix); a track has `volume`, `pan` (-1 to
+1), `reverb` (0 to 1), and `mute`. The key is a note and a scale: `major`,
+`minor`, `harmonic minor`, `dorian`, `phrygian`, `lydian`, `mixolydian`,
+`major pentatonic`, `minor pentatonic`, `blues`.
+
+The instruments are synthesized from small models of the real ones (a
+plucked string, struck strings, a breath through a tube), so they need no
+sample files and play the same bits everywhere:
+
+| Instrument | For |
+| --- | --- |
+| `piano`, `epiano` | Chords, melodies; the electric piano for mellow, lo-fi tunes. |
+| `guitar`, `bass` | Picked or strummed chords; the low line under them. |
+| `rockGuitar` | An overdriven electric guitar: riffs and power chords (a note and the one seven semitones up). |
+| `reese` | The drum & bass bass: detuned saws, a sub, and grit; long notes. |
+| `strings`, `pad` | Long held chords that swell in. |
+| `flute`, `marimba`, `bells` | Melodies; short bright patterns; sparkle. |
+| `synthLead` | A supersaw: modern electronic leads and riffs. |
+| `chipLead`, `chipBass` | Chiptune: a retro console's square and triangle waves. |
+| `drums`, `breaks` | A clean drum kit; a punchy, driven one for rock and drum & bass (the same drums). |
+
+A song's `reference` is what `music listen` heard: its `tempo`, `key`, the
+melody as `notes` rounded to the grid, the raw pitch line (`contour`), and the
+audio file it came from. The review lives next to the song
+(`theme.song.json` → `theme.song.review.json`): the status (`new`,
+`approved`, `changes`), a note, comments pinned to bars (and a track), and
+the person's edits since the agent last wrote the song, a line each.
+`examples/village.song.json` in the repository is a song built around a
+hum (`examples/village.song.reference.wav`, a synthesized test hum).
+
+### Listening
+
+`music listen` follows the strongest pitch moment to moment (YIN, the
+standard pitch tracker for one voice), cuts it into notes where the pitch
+jumps or the voice restarts, finds the tempo whose beats line up best with
+where the notes start, and the key whose notes match how long each pitch
+sounds (Krumhansl's key profiles, over the whole spectrum). A voice that
+sits off pitch the whole way, as most people's do, is heard in tune: the
+offset (`tuning`, in cents, in the report) is measured over all its notes
+and taken out before they are named. It hears one voice (a hum, a
+whistle, a lead line): on a full song or in a noisy room it finds a tempo
+and a key but few notes, and says so (hum the part alone instead). A tapped
+beat with no tune gives a tempo and no notes. When the song already has a
+tempo and the hum was sung along to it, `--tempo` puts the notes on the
+song's grid.
+
+### The command line
+
+`npx @typeonce/ritmo-tools music <command>` (inside the Ritmo repository,
+`node packages/tools/bin/ritmo-tools.mjs music <command>`). Every command
+prints JSON and exits 0 (clean), 2 (usage error, missing file, broken song),
+or 3 (the song clips or is silent).
+
+| Command | Does |
+| --- | --- |
+| `ritmo-tools music listen <song> <audio.wav> [--tempo 96]` | Hears a hum, a whistle, or a tapped beat and writes its tempo, key, and melody into the song as its reference; makes the song if it does not exist. |
+| `ritmo-tools music instruments` | Lists the instruments (what each is for, its range), the drums, and the scales. |
+| `ritmo-tools music init [song]` | Writes a starting song: four bars of piano chords, a bass line, and a beat. |
+| `ritmo-tools music check <song>` | Measures the song (length, peak, loudness, each track's loudness and range) and lists what usually sounds wrong: clipping, silence, notes outside the key or an instrument's range, a buried track, a doubled note, and with a reference, how closely the melody follows it. |
+| `ritmo-tools music render <song> [-o file.wav] [--stems]` | Writes the song as a stereo WAV and a MIDI file, and with `--stems` each track alone. |
+| `ritmo-tools music review <song> [--port 5191] [--host]` | Serves the review page and prints its address; runs until stopped. |
+| `ritmo-tools music notes <song>` | What the person said: the status, the note, comments in song order with their bars, and their edits. |
+
+### The review page
+
+`ritmo-tools music review` opens the song on a local page: the reference and
+the tracks on the left (mute and solo each), the arrangement (every track
+as a lane under the bar numbers, with the hum's pitch line above them) and
+the chosen track's note grid on the stage, and on the right the review, the
+comments, the track (instrument, volume, pan, room), the song (tempo, key,
+bars, loop, compressor, master), the reference, and the check. On the grid, a click
+places a note (and plays it), a drag moves it, dragging its end stretches
+it, and a double-click or right-click removes it; the key's notes are a
+shade lighter, and the hum's notes show as dashed outlines with its pitch
+line through them. A click on the bar numbers, or on a lane of the
+arrangement, puts the start marker there (while playing, the bar numbers
+jump the music there); dragging across the bar numbers picks bars to
+comment on, and Play starts from them. Record a hum records from the microphone (the page must be on
+localhost or HTTPS); Audio file, or dropping a file on the stage, takes any
+audio the browser plays. Space plays and pauses (Play goes on from where
+it paused), Stop goes back to the start, the microphone
+button plays the hum along with the song, Delete removes the chosen note,
+and Ctrl/Cmd+Z undoes. MIDI and WAV download the song. Every change is
+written to the song and its review as it happens, and a song the agent
+rewrites while the page is open shows up in it.
+
+### Code
+
+- `src/music/core/`: songs (`song.ts`), the instruments (`instruments.ts`),
+  the renderer (`render.ts`), listening (`listen.ts`), checks (`check.ts`),
+  reviews and edits in words (`review.ts`), WAV (`audio.ts`) and MIDI
+  (`midi.ts`) files. Plain TypeScript that runs the same in Node and the
+  browser.
+- `src/music/cli/`: the `music` command (Effect), and the review page's
+  server (`serve.ts`).
+- `src/music/ui/`: the review page: the canvases (`grid.ts`), playing
+  (`player.ts`), recording (`record.ts`). The published package carries it
+  built (`dist/music/page`, made by `prepack`); inside the repository Vite
+  serves it from source.

package/dist/cli.js

@@ -3,6 +3,8 @@
  * `ritmo-tools`: the asset tools for games made with Ritmo, run by agents.
  *
  *   ritmo-tools pixel <command>   checks, fixes, and makes pixel art and animations
+ *   ritmo-tools sound <command>   checks, renders, and varies game sounds, and opens the review page
+ *   ritmo-tools music <command>   listens to a hum, checks and renders songs, and opens the review page
  *
  * Every command prints JSON on stdout and exits with what to do next (see
  * each tool's `--help`). Built on Effect; nothing a game imports depends on it.
@@ -13,7 +15,9 @@ import { CliError, Command } from "effect/cli";
 import { toolsVersion } from "./internal/version.js";
 import { Exit, pixel } from "./pixel/cli/commands.js";
 import { printJson } from "./pixel/cli/io.js";
-const tools = Command.make("ritmo-tools").pipe(Command.withDescription("Ritmo's asset tools for agents: `pixel` for pixel art and animations. Each prints JSON and exits with what to do next."), Command.withSubcommands([pixel]));
+import { music } from "./music/cli/commands.js";
+import { sound } from "./sound/cli/commands.js";
+const tools = Command.make("ritmo-tools").pipe(Command.withDescription("Ritmo's asset tools for agents: `pixel` for pixel art and animations, `sound` for sound effects, `music` for game music. Each prints JSON and exits with what to do next."), Command.withSubcommands([pixel, sound, music]));
 const program = Command.run(tools, { version: toolsVersion }).pipe(Effect.catchTag("CliFailure", (failure) => Effect.gen(function* () {
     yield* Console.error(`ritmo-tools: ${failure.message}`);
     if (failure.details !== undefined)

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACpD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAA;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAE7C,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,CAC5C,OAAO,CAAC,eAAe,CAAC,wHAAwH,CAAC,EACjJ,OAAO,CAAC,eAAe,CAAC,CAAC,KAAK,CAAC,CAAC,CACjC,CAAA;AAED,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC,IAAI,CAChE,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,EAAE,CACxC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,gBAAgB,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;IACvD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;QAAE,KAAK,CAAC,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;IACnG,OAAO,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAA;AACrC,CAAC,CAAC,CACH;AACD,6EAA6E;AAC7E,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAC9E,CAAA;AAED,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;GASG;AACH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACjE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACpD,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAA;AACrD,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAC7C,OAAO,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAA;AAC/C,OAAO,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAA;AAE/C,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,IAAI,CAC5C,OAAO,CAAC,eAAe,CAAC,2KAA2K,CAAC,EACpM,OAAO,CAAC,eAAe,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAC/C,CAAA;AAED,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC,IAAI,CAChE,MAAM,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,EAAE,CACxC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,KAAK,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,gBAAgB,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;IACvD,IAAI,OAAO,CAAC,OAAO,KAAK,SAAS;QAAE,KAAK,CAAC,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;IACnG,OAAO,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAA;AACrC,CAAC,CAAC,CACH;AACD,6EAA6E;AAC7E,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAC9E,CAAA;AAED,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA"}

package/dist/internal/version.d.ts

@@ -3,5 +3,5 @@
  * `package.json` by `scripts/sync-version.ts` (run by `pnpm version-packages`)
  * and checked by a test.
  */
-export declare const toolsVersion = "0.17.0";
+export declare const toolsVersion = "0.19.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/internal/version.js

@@ -3,5 +3,5 @@
  * `package.json` by `scripts/sync-version.ts` (run by `pnpm version-packages`)
  * and checked by a test.
  */
-export const toolsVersion = "0.17.0";
+export const toolsVersion = "0.19.0";
 //# sourceMappingURL=version.js.map

package/dist/music/cli/commands.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The `music` commands: the music lab for agents. The same core as the
+ * review page (one renderer, one song format), driven from the command
+ * line, printing JSON and exiting with a code that says what to do next:
+ *
+ * - 0: clean (warnings are listed, and are the agent's call)
+ * - 2: a usage problem, a missing file, a broken song
+ * - 3: errors: the song clips or is silent; fix it
+ */
+import { Path } from "effect";
+import { Command } from "effect/cli";
+import { Exit } from "../../sound/cli/commands.ts";
+import { CliFailure } from "../../sound/cli/io.ts";
+export declare const music: Command.Command<"music", {}, {}, CliFailure | Exit, import("effect/FileSystem").FileSystem | Path.Path>;
+//# sourceMappingURL=commands.d.ts.map

package/dist/music/cli/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../../src/music/cli/commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAkB,IAAI,EAAE,MAAM,QAAQ,CAAA;AAC7C,OAAO,EAAY,OAAO,EAAQ,MAAM,YAAY,CAAA;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAA;AAClD,OAAO,EAAE,UAAU,EAA8C,MAAM,uBAAuB,CAAA;AA4N9F,eAAO,MAAM,KAAK,yGAKjB,CAAA"}