c64bridge 1.0.5 → 1.0.7

package/AGENTS.md

@@ -90,7 +90,7 @@ If a workflow description starts listing tool calls outside `.github/skills`, tr
 
 ## Capabilities
 
-- Program runners: `c64_program` (`upload_run_basic`, `upload_run_asm`, `run_prg`, `run_crt`, `bundle_run`, `batch_run`)
+- Program runners: `c64_program` (`upload_run_basic`, `upload_run_asm`, `load_prg`, `run_prg`, `run_crt`, `bundle_run`, `batch_run`)
 - Fast demo workflow: `c64_program` (`cross_platform_greeting`) for one-call greetings on VICE and/or C64U with screenshot capture and verification
 - Screen & memory: `c64_memory` (`read`, `write`, `read_screen`, `wait_for_text`)
 - System control: `c64_system` (`pause`, `resume`, `reset`, `reboot`, `poweroff`, `power_cycle`, `menu`, tasks)

package/README.md

@@ -717,7 +717,7 @@ Grouped entry point for configuration reads/writes, diagnostics, and snapshots.
 | --- | --- | --- | --- | --- | --- | --- |
 | `batch_update` | Apply multiple configuration updates in a single request. | — | — | ✅ | ✅ | ✅ |
 | `diff` | Compare the current configuration with a snapshot. | `path` | — | ✅ | ✅ | ✅ |
-| `get` | Read a configuration category or specific item. | `category` | `item` | ✅ | ✅ | ✅ |
+| `get` | Read a configuration category or specific item. | `category` | `item`, `includeSecretValues=false` | ✅ | ✅ | ✅ |
 | `info` | Retrieve Ultimate hardware information and status. | — | — | ✅ | ✅ | ✅ |
 | `list` | List configuration categories reported by the firmware. | — | — | ✅ | ✅ | ✅ |
 | `load_flash` | Load configuration from flash storage. | — | — | ✅ | ✅ |  |
@@ -764,7 +764,7 @@ Grouped entry point for disk mounts, listings, image creation, and program disco
 | `find_and_run` | Search for a PRG/CRT by name substring and run the first match. | `nameContains` | `root="/"`, `extensions`, `caseInsensitive=true`, `sort="discovered"`, `waitMs=0`, `captureCandidates=10` | ✅ | ✅ |  |
 | `list_drives` | List Ultimate drive slots and their mounted images. | — | — | ✅ | ✅ | ✅ |
 | `mount` | Mount a disk image with optional verification and retries. Supports verification. | `drive`, `image` | `type`, `attachmentMode`, `driveMode`, `verify=false`, `powerOnIfNeeded=true`, `resetAfterMount=true`, `maxRetries=2`, `retryDelayMs=500` | ✅ | ✅ | ✅ |
-| `unmount` | Remove the mounted image from an Ultimate drive slot. | `drive` | — | ✅ | ✅ | ✅ |
+| `unmount` | Remove the mounted image from an Ultimate drive slot. | `drive` | — | ✅ | ✅ |  |
 
 #### c64_drive
 
@@ -809,7 +809,7 @@ Cross-platform PETSCII typing plus native Ultimate keyboard and joystick events.
 
 | Operation | Description | Required Inputs | Optional Inputs | C64U | U2 | VICE |
 | --- | --- | --- | --- | --- | --- | --- |
-| `joystick` | Simulate joystick input. On C64U/U64 this uses machine:input; VICE uses Binary Monitor Joyport Set. | `port`, `controls`, `action` | `durationMs=80` | ✅ |  | ✅ |
+| `joystick` | Simulate joystick input. On C64U/U64 this uses machine:input. On VICE it attaches VICE's I/O simulation joyport device while pressed; that device also pulls CIA lines 5-7 low, so port 1 produces phantom keys (e.g. SHIFT+C=) and port 2 reads $1E for up instead of $7E. Prefer port 2 on VICE and test bits 0-4. | `port`, `controls`, `action` | `durationMs=80` | ✅ |  | ✅ |
 | `key` | Tap a single key or hold it for a duration. | `key` | `durationMs=0`, `count=1` | ✅ | ✅ | ✅ |
 | `keyboard` | Send physical C64 keyboard matrix events through machine:input (a C64U firmware version that provides it, or U64 3.15+). | `inputs`, `transition` | — | ✅ |  |  |
 | `release_all` | Release every key and joystick control injected through machine:input (a C64U firmware version that provides it, or U64 3.15+). | — | — | ✅ |  |  |

package/data/sound/sidwave.md

@@ -1,18 +1,11 @@
 # SIDWAVE Format Specification
 
-This document defines **SIDWAVE**, a declarative format for describing structured, modern C64 SID compositions.
-SIDWAVE files are authored in YAML (optionally JSON) and compiled by an MCP server into `.SID` or `.PRG` binaries for playback on the Commodore 64 via the Ultimate64 REST API.
-
----
-
-## Purpose
-
-SIDWAVE provides a human- and machine-readable way to describe complex, atmospheric, and modern electronic music for the MOS 6581/8580 SID chip.
-It captures instruments, modulation, and structure symbolically, allowing large language models to generate music that the MCP expands into precise SID register sequences.
+This document defines **SIDWAVE**, a declarative format for describing structured C64 SID compositions.
+SIDWAVE files are authored in YAML (or JSON) and compiled by the MCP server (`music_compile_and_play`) into a `.PRG` or `.SID` (PSID v2) binary with a built-in frame-based player.
 
 Pipeline:
 
-LLM → SIDWAVE (YAML) → MCP Compiler → SID Binary (.sid/.prg) → Ultimate64 REST → C64 Playback
+LLM → SIDWAVE (YAML) → MCP compiler → PRG or PSID → C64 / Ultimate / VICE playback
 
 ---
 
@@ -20,16 +13,20 @@ LLM → SIDWAVE (YAML) → MCP Compiler → SID Binary (.sid/.prg) → Ultimate6
 
 - **Format name:** SIDWAVE
 - **File suffix:** `.sidwave.yaml` (or `.sid.yaml` for brevity)
-- **Schema field:** `sidwave: 1.0`
+- **Version field:** `sidwave: 1.0`
 - **Schema file:** `sidwave.schema.json`
-- **Primary serialization:** YAML 1.2 (JSON also valid)
+- **Serialization:** YAML 1.2 or JSON
+
+Unknown fields, unknown pattern names, invalid notes and out-of-range values are rejected with an error that names the path, for example `Invalid SIDWAVE at $.timeline[1].layers.v2: pattern "X" is not defined for voice 2 (known: B)`.
+
+> YAML pitfall: inside a flow map, a bare `-` starts a list. Write silent layers as `v2: "-"`, not `v2: -`.
 
 ---
 
-## Example SIDWAVE File
+## Example
 
 ```yaml
-# yaml-language-server: $schema=https://example.com/sidwave.schema.json
+# yaml-language-server: $schema=https://raw.githubusercontent.com/chrisgleissner/c64bridge/refs/heads/main/data/sound/sidwave.schema.json
 sidwave: 1.0
 title: "Echoes of Tomorrow"
 author: "Generated by MCP"
@@ -50,8 +47,8 @@ voices:
         motif: "Cmin9 pad motif"
         transpositions: [0, 5, 7]
         fx:
-          vibrato: { depth: 2, rate: 5 }
-          filter_mod: { sweep: +500 over 8 steps }
+          vibrato: { depth: 0.25, rate: 5, delay: 10 }
+          filter_mod: { sweep: "+500 over 8 beats" }
 
   - id: 2
     name: ArpLayer
@@ -59,11 +56,11 @@ voices:
     pulse_width: 0.3
     patterns:
       B:
-        type: "arpeggio"
+        type: arpeggio
         notes: [C3, Eb3, G3, Bb3]
         frame_rate: 2
         fx:
-          pwm_sweep: { speed: 6, depth: 8 }
+          pwm_sweep: { speed: 1, depth: 0.2 }
 
   - id: 3
     name: Bass
@@ -77,7 +74,7 @@ voices:
 timeline:
   - section: "Intro"
     bars: 16
-    layers: { v1: A, v2: -, v3: C }
+    layers: { v1: A, v2: "-", v3: C }
   - section: "Build"
     bars: 32
     layers: { v1: A↑, v2: B, v3: C }
@@ -86,46 +83,126 @@ timeline:
     layers: { v1: A↓, v2: B, v3: C }
   - section: "Fade"
     bars: 32
-    layers: { v1: A–, v2: -, v3: - }
+    layers: { v1: A–, v2: "-", v3: "-" }
 ```
 
 ---
 
-## MCP Responsibilities
+## Song Fields
 
-1. Parse SIDWAVE YAML or JSON input.
-2. Expand patterns, transpositions, and modulation into frame-accurate SID register writes.
-3. Compile to valid `.SID` or `.PRG` binaries with proper init and play routines.
-4. Send the binary to Ultimate64 via:
+| Field | Meaning |
+| --- | --- |
+| `sidwave` | Format version, `1.0`. |
+| `title`, `author` | Written to the PSID header (Latin-1, 32 characters). |
+| `tempo` | Beats (quarter notes) per minute, 30–220. Default 100. |
+| `mode` | `PAL` (985248 Hz clock, 50.12 frames/s) or `NTSC` (1022727 Hz clock, 59.83 frames/s). Default `PAL`. |
+| `length_bars` | Optional song length. Shorter than the timeline truncates it; longer repeats the timeline from the start. Default: the sum of the timeline's bars. |
+| `global_fx` | `reverb_sim` and `filter_env`, described below. |
+| `voices` | One to three voices with ids 1–3. Voices that are not declared stay silent. |
+| `timeline` | Sections played in order. The song loops forever after the last section. |
 
-```
-POST /v1/attachment:sid
-Content-Type: application/octet-stream
-Body = compiled binary
-```
+The legacy shape with a `song: { title, author, tempo, mode, length_bars, global_fx }` block next to `voices` and `timeline` is also accepted.
+
+Time is 4/4: a bar has four beats. The player runs once per video frame of a real C64 (50.1245 Hz on PAL, 59.8262 Hz on NTSC). Every onset is placed on the nearest frame of its exact time (`beat × 60 / tempo × frame rate`), so long songs do not drift; individual notes may be one frame longer or shorter than the average.
+
+## Voices
+
+| Field | Meaning |
+| --- | --- |
+| `id` | SID voice 1, 2 or 3. |
+| `name` | Label only. |
+| `waveform` | `pulse`, `sawtooth` (`saw`), `triangle` (`tri`) or `noise`. Default `pulse`. |
+| `pulse_width` | Pulse duty cycle: a fraction (0 < x ≤ 1, e.g. `0.3`) or a 12-bit value 1–4094. Default 2048 (50 %). |
+| `adsr` | `[attack, decay, sustain, release]`, each 0–15 (SID register nibbles). Default `[2, 2, 10, 3]`. |
+| `patterns` | Named patterns used by the timeline. |
+
+## Patterns
+
+Every pattern is a list of **entries**. Each entry lasts `length` beats (default 1; fractions allowed, e.g. `0.25` for sixteenth notes). The pattern repeats until its section ends; a note that would run past the section end is cut there.
+
+- **groove** — `groove: [C2, "-", C2, "~", G1]`: one note per entry. `-` (or `.`) is a rest, `~` ties the entry to the previous note (no retrigger). A tie holds whatever note is sounding right before it, also across a section boundary (a section that starts with `~` continues the last note of the previous section). After a rest, or at the very start of the song, a tie is a rest.
+- **arpeggio** — `type: arpeggio`, `notes: [...]`. Without `frame_rate`, the notes are played one per entry (a broken chord). With `frame_rate: N`, all notes form one entry that sounds as a fast chord arpeggio, switching to the next chord tone every N frames (`frame_rate: 1` = one tone per frame, about 50 per second on PAL); each entry retriggers the chord.
+- **motif** — `motif: "..."` with tokens separated by spaces or commas:
+  - note names (`C4`, `Eb3`, `F#2`),
+  - integers: semitones above `root` (default `C3`), e.g. `"0 4 7 12"`,
+  - chord symbols, expanded to their chord tones in the octave of `root`: `C`, `Cm`/`Cmin`, `Cdim`, `Caug`, `Csus2`, `Csus4`, `C6`, `Cm6`, `C7`, `Cmaj7`, `Cm7`, `Cdim7`, `Cm7b5`, `C9`, `Cmaj9`, `Cm9`/`Cmin9`, `Cadd9`,
+  - `-` rests and `~` ties.
+  Words that are not notes or chord symbols (such as `pad` or `motif`) are ignored. `"Cmin9 pad motif"` therefore plays C3, Eb3, G3, Bb3, D4, one per entry.
+
+`transpositions: [0, 5, 7]` transposes successive repetitions of the pattern within a section by the given semitones, cycling; the cycle restarts at each section.
+
+Notes range from C0 to B7. At the PAL clock B7 exceeds the SID's 16-bit frequency register, so the highest PAL note is A#7. Notes that leave the range after transposition are rejected.
+
+### Pattern effects (`fx`)
+
+| Effect | Fields | Behaviour |
+| --- | --- | --- |
+| `vibrato` | `depth` (semitones, 0.03–6), `rate` (Hz, 0.2–12), `delay` (frames, optional) | Triangle pitch modulation of ±`depth` semitones around the note (the upward and downward swings are computed separately, so both reach `depth` to within the SID's frequency resolution, about 3 cents in the lowest octave), starting `delay` frames after the note. The upward swing must stay within the SID's highest frequency: on PAL a vibrato on A#7 can be at most 0.54 semitones deep, on NTSC B7 at most 0.19; deeper vibratos on such notes (including the highest note of a chord arpeggio) are rejected. The player samples the vibrato once per frame, so rates are limited to 12 Hz (about a quarter of the frame rate); faster rates would alias or cancel out. |
+| `pwm_sweep` | `depth` (fraction ≤ 1 or 12-bit units), `speed` (cycles per second) | Pulse width moves linearly between `pulse_width − depth` and `pulse_width + depth`, restarting at the base on each note. Pulse waveform only. |
+| `slide` | `depth` (semitones, ±24, non-zero), `speed` (frames, 1–255) | Each note starts `depth` semitones below the target (above when negative) and glides to it linearly in frequency, arriving after `speed` frames. The start note must itself be playable (C0..A#7 on PAL, C0..B7 on NTSC); otherwise the document is rejected. |
+| `filter_mod` | `sweep: "+500 over 8 steps"` (units: `steps`, `beats`, `bars`, `frames`; a step is one entry), or `{ sweep: 500, beats: 8 }` | Routes the voice through the filter while the pattern plays. At each repetition of the pattern the cutoff offset restarts at 0 and ramps to `sweep` (cutoff units, −2047..2047) over the given time, then holds. The resulting cutoff is clamped to 0..2047. The offset is removed when the section ends. |
+
+## Timeline
+
+Each section has `bars` (whole number ≥ 1), an optional `section` name, and `layers` mapping `v1`/`v2`/`v3` to a pattern reference:
+
+- `"-"`, `.`, `rest` or an omitted layer: the voice is silent.
+- `A`: play pattern `A` of that voice.
+- Modifiers after the name: `↑` (or `^`) one octave up, `↓` one octave down, `+N` / `-N` N semitones (e.g. `A+5`), and a trailing `–`, `—` or `-` fades the voice out over the section.
+
+Fading lowers the voice's sustain level linearly to 0 across the section. When every sounding voice of a section fades, the master volume also fades to 0 and returns to full volume when the section ends.
+
+## Global effects (`global_fx`)
+
+| Effect | Fields | Behaviour |
+| --- | --- | --- |
+| `filter_env` | `cutoff_base` (0–2047), `sweep` (±2047), `speed` (beats per one-way sweep), `resonance` (0–15, default 8), `type` (`lowpass` default, `bandpass`, `highpass`), `voices` (default all) | Enables the SID filter for the listed voices. The cutoff moves back and forth between `cutoff_base` and `cutoff_base + sweep`, each direction taking `speed` beats. Without `sweep`/`speed` the cutoff stays at `cutoff_base`. The sweep restarts from `cutoff_base` each time the song loops, so every pass sounds the same. `filter_mod` offsets are added on top. |
+| `reverb_sim` | `depth` (0 < x ≤ 1), `delay_frames` (1–50) | In sections that leave a voice free, the lowest free voice echoes the lowest sounding voice `delay_frames` later, with its sustain level scaled by `depth`. The SID has no per-voice volume, so the echo's attack peak is as loud as the original; only the sustained part is quieter. Sections that use all three voices have no echo. |
+
+Without `filter_env`, a `filter_mod` uses a low-pass filter with cutoff 1024 and resonance 8 as its base. The SID has a single filter, so all routed voices share it; when several patterns with `filter_mod` start at once, the most recent start sets the ramp.
+
+---
+
+## Player
+
+The compiler arranges the timeline into per-voice note events and encodes them as compact command streams (note, instrument, wait, gate-off, hard restart, sustain, volume, filter ramp, loop). A 6502 player reads these streams once per video frame and computes per-frame effects itself.
+
+- **Hard restart:** two frames before every new note the voice's gate is released and its ADSR is set to zero, so each note starts a fresh envelope (this avoids the SID's ADSR delay bug). A note therefore sounds with the gate on until two frames before the next note, so every note needs at least 3 frames (one sounding frame plus the hard restart). Entries shorter than 3 frames are rejected, which limits very short entries at fast tempos (for example 1/16 notes are fine at 220 BPM, 1/32 notes are not). A note that is cut to fewer than 3 frames by the end of a section is dropped.
+- **Gate:** a rest releases the gate at its start, so the note decays with its release rate.
+- **Instruments:** each voice/pattern/effect combination becomes an instrument with its own ADSR, waveform, pulse settings, vibrato, arpeggio table, slide and filter routing (up to 63).
+- **Memory:** the program loads at $0801 and must end below $D000 (about 50 KB). Very long, dense songs are rejected with a validation error rather than truncated. The player uses zero-page bytes $FB/$FC and restores them after every call.
+- **CPU time:** typical songs take 20–65 raster lines per frame (about 1,400–4,100 cycles). The worst case, all three voices starting notes with vibrato, slide, arpeggio, pulse sweep and filter ramp in the same frame, takes about 9,800 cycles (155 raster lines, half a PAL frame), mostly for the arithmetic that scales vibrato and slide to each note's pitch (an 8×8 multiply from a 1 KB table of squares).
+
+### Output formats
+
+- **PSID (`output: sid`):** PSID v2 with init at $0810, play at $0813, vertical-blank timing, and the PAL or NTSC clock flag from `mode`. The SID model is left unspecified.
+- **PRG (`output: prg`):** `10 SYS2061`. The program detects whether the machine is PAL or NTSC, programs CIA 1 timer A for the song's frame rate on that clock, installs an IRQ handler, and returns to BASIC while the music plays. Pitch and tempo are therefore correct on either machine type.
+  - Before returning, it moves the start of BASIC and the variable area behind the player (like `NEW` with a raised start of BASIC), so direct-mode commands, variables and new program lines work without touching the player. The compile result reports `basicFreeBytes`. A song whose PRG ends at or above $A000 leaves no BASIC memory: BASIC commands that need memory then fail with `?OUT OF MEMORY` while the music keeps playing, and the compile result carries a warning.
+  - Because the KERNAL's IRQ (keyboard scan, cursor blink, jiffy clock) now runs at the song's frame rate instead of 60 Hz, `TI`/`TI$` runs about 16.5 % slow for a PAL song (0.3 % for NTSC), and key repeat and cursor blink slow down accordingly while the music plays.
+
+### Not supported
+
+Time signatures other than 4/4, per-note velocity, portamento between consecutive notes (the `slide` effect is a slide into each note), multiple subtunes, multispeed (more than one player call per frame), and combined waveforms.
 
 ---
 
 ## Authoring and Validation
 
-- SIDWAVE files are plain YAML and open cleanly in any standard editor.
-- Validation uses JSON Schema:
+- Validation uses JSON Schema (`sidwave.schema.json`); the compiler applies the same rules and additionally checks note ranges after transposition and minimum note durations.
 
 ```json
 {
   "yaml.schemas": {
-    "https://example.com/sidwave.schema.json": "*.sidwave.yaml"
+    "https://raw.githubusercontent.com/chrisgleissner/c64bridge/refs/heads/main/data/sound/sidwave.schema.json": "*.sidwave.yaml"
   }
 }
 ```
 
-This enables autocomplete, hover info, and validation in VS Code or similar IDEs.
-
 ---
 
 ## LLM Prompt Template
 
 > Compose a 3–5 minute atmospheric, modern electronic SID composition using the **SIDWAVE** format.
 > Use three voices with expressive modulation (PWM, filter sweeps, arpeggios, evolving pads).
-> Output valid YAML conforming to `sidwave.schema.json`.
+> Output valid YAML conforming to `sidwave.schema.json`; quote silent layers as `"-"`.
 > Avoid direct note repetition; reuse and transpose patterns.

package/data/sound/sidwave.schema.json

@@ -2,63 +2,173 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://raw.githubusercontent.com/chrisgleissner/c64bridge/refs/heads/main/data/sound/sidwave.schema.json",
   "title": "SIDWAVE Composition Schema",
+  "description": "See sidwave.md for the meaning of every field. The compiler also checks note ranges after transposition and minimum note durations.",
   "type": "object",
   "required": ["sidwave", "title", "tempo", "mode", "voices", "timeline"],
   "properties": {
     "sidwave": { "type": ["number", "string"], "enum": [1, "1.0", "1"] },
     "title": { "type": "string" },
     "author": { "type": "string" },
-    "tempo": { "type": "number", "minimum": 30, "maximum": 220 },
+    "tempo": { "type": "number", "minimum": 30, "maximum": 220, "description": "Beats (quarter notes) per minute." },
     "mode": { "type": "string", "enum": ["PAL", "NTSC"] },
-    "global_fx": { "type": "object", "additionalProperties": true },
+    "length_bars": { "type": "integer", "minimum": 1, "description": "Truncates or repeats the timeline to this many 4/4 bars." },
+    "global_fx": {
+      "type": "object",
+      "properties": {
+        "reverb_sim": {
+          "type": "object",
+          "required": ["depth", "delay_frames"],
+          "properties": {
+            "depth": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 },
+            "delay_frames": { "type": "integer", "minimum": 1, "maximum": 50 }
+          },
+          "additionalProperties": false
+        },
+        "filter_env": {
+          "type": "object",
+          "required": ["cutoff_base"],
+          "properties": {
+            "cutoff_base": { "type": "number", "minimum": 0, "maximum": 2047 },
+            "sweep": { "type": "number", "minimum": -2047, "maximum": 2047 },
+            "speed": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024, "description": "Beats per one-way sweep." },
+            "resonance": { "type": "integer", "minimum": 0, "maximum": 15 },
+            "type": { "type": "string", "enum": ["lowpass", "bandpass", "highpass"] },
+            "voices": { "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 3 } }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
     "voices": {
       "type": "array",
       "minItems": 1,
+      "maxItems": 3,
       "items": {
         "type": "object",
         "required": ["id"],
         "properties": {
-          "id": { "type": "number", "minimum": 1, "maximum": 3 },
+          "id": { "type": "integer", "minimum": 1, "maximum": 3 },
           "name": { "type": "string" },
           "waveform": { "type": "string", "enum": ["pulse", "sawtooth", "triangle", "noise", "saw", "tri"] },
-          "pulse_width": { "type": "number", "minimum": 0 },
-          "adsr": { "type": "array", "items": { "type": "number", "minimum": 0, "maximum": 15 }, "minItems": 4, "maxItems": 4 },
+          "pulse_width": { "type": "number", "exclusiveMinimum": 0, "exclusiveMaximum": 4095, "description": "Fraction (0 < x <= 1) or 12-bit value." },
+          "adsr": { "type": "array", "items": { "type": "integer", "minimum": 0, "maximum": 15 }, "minItems": 4, "maxItems": 4 },
           "patterns": {
             "type": "object",
             "additionalProperties": {
               "oneOf": [
-                { "type": "object", "required": ["type", "notes"], "properties": {
-                  "type": { "const": "arpeggio" },
-                  "notes": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
-                  "frame_rate": { "type": "number", "minimum": 1 },
-                  "fx": { "type": "object", "additionalProperties": true }
-                }, "additionalProperties": false },
-                { "type": "object", "properties": {
-                  "length": { "type": "number", "minimum": 1 },
-                  "motif": { "type": "string" },
-                  "transpositions": { "type": "array", "items": { "type": "number" } },
-                  "fx": { "type": "object", "additionalProperties": true }
-                }, "additionalProperties": false },
-                { "type": "object", "required": ["groove"], "properties": {
-                  "groove": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
-                  "fx": { "type": "object", "additionalProperties": true }
-                }, "additionalProperties": false }
+                {
+                  "type": "object",
+                  "required": ["notes"],
+                  "properties": {
+                    "type": { "const": "arpeggio" },
+                    "notes": { "type": "array", "items": { "$ref": "#/$defs/note" }, "minItems": 1 },
+                    "frame_rate": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Frames per chord tone; makes the notes a fast chord arpeggio." },
+                    "length": { "$ref": "#/$defs/length" },
+                    "transpositions": { "$ref": "#/$defs/transpositions" },
+                    "fx": { "$ref": "#/$defs/fx" }
+                  },
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "required": ["motif"],
+                  "properties": {
+                    "motif": { "type": "string", "description": "Notes, semitone offsets from root, chord symbols, '-' rests and '~' ties." },
+                    "root": { "$ref": "#/$defs/note" },
+                    "length": { "$ref": "#/$defs/length" },
+                    "transpositions": { "$ref": "#/$defs/transpositions" },
+                    "fx": { "$ref": "#/$defs/fx" }
+                  },
+                  "additionalProperties": false
+                },
+                {
+                  "type": "object",
+                  "required": ["groove"],
+                  "properties": {
+                    "groove": { "type": "array", "items": { "anyOf": [{ "$ref": "#/$defs/note" }, { "enum": ["-", ".", "~", "_", "r", "rest"] }] }, "minItems": 1 },
+                    "length": { "$ref": "#/$defs/length" },
+                    "transpositions": { "$ref": "#/$defs/transpositions" },
+                    "fx": { "$ref": "#/$defs/fx" }
+                  },
+                  "additionalProperties": false
+                }
               ]
             }
           }
         },
-        "additionalProperties": true
+        "additionalProperties": false
       }
     },
     "timeline": {
       "type": "array",
       "minItems": 1,
-      "items": { "type": "object", "required": ["bars", "layers"], "properties": {
-        "section": { "type": "string" },
-        "bars": { "type": "number", "minimum": 1 },
-        "layers": { "type": "object", "additionalProperties": { "type": "string" } }
-      }, "additionalProperties": false }
+      "items": {
+        "type": "object",
+        "required": ["bars", "layers"],
+        "properties": {
+          "section": { "type": "string" },
+          "bars": { "type": "integer", "minimum": 1 },
+          "layers": {
+            "type": "object",
+            "propertyNames": { "pattern": "^(v|voice)?[1-3]$" },
+            "additionalProperties": { "type": ["string", "null"], "description": "Pattern name with optional ↑ ↓ +N -N modifiers and a trailing – for fade; \"-\" is silence." }
+          }
+        },
+        "additionalProperties": false
+      }
     }
   },
-  "additionalProperties": false
+  "additionalProperties": false,
+  "$defs": {
+    "note": { "type": "string", "pattern": "^[A-Ga-g][#b]?[0-7]$" },
+    "length": { "type": "number", "exclusiveMinimum": 0, "maximum": 64, "description": "Beats per entry (default 1)." },
+    "transpositions": { "type": "array", "items": { "type": "integer", "minimum": -48, "maximum": 48 }, "minItems": 1 },
+    "fx": {
+      "type": "object",
+      "properties": {
+        "vibrato": {
+          "type": "object",
+          "required": ["depth", "rate"],
+          "properties": {
+            "depth": { "type": "number", "minimum": 0.03, "maximum": 6, "description": "Semitones." },
+            "rate": { "type": "number", "minimum": 0.2, "maximum": 12, "description": "Hz; at most about a quarter of the frame rate." },
+            "delay": { "type": "integer", "minimum": 0, "maximum": 255, "description": "Frames." }
+          },
+          "additionalProperties": false
+        },
+        "pwm_sweep": {
+          "type": "object",
+          "required": ["depth", "speed"],
+          "properties": {
+            "depth": { "type": "number", "exclusiveMinimum": 0, "maximum": 2047 },
+            "speed": { "type": "number", "exclusiveMinimum": 0, "maximum": 25, "description": "Cycles per second." }
+          },
+          "additionalProperties": false
+        },
+        "slide": {
+          "type": "object",
+          "required": ["depth", "speed"],
+          "properties": {
+            "depth": { "type": "integer", "minimum": -24, "maximum": 24, "not": { "const": 0 } },
+            "speed": { "type": "integer", "minimum": 1, "maximum": 255, "description": "Frames until the slide reaches the note." }
+          },
+          "additionalProperties": false
+        },
+        "filter_mod": {
+          "type": "object",
+          "required": ["sweep"],
+          "properties": {
+            "sweep": { "type": ["string", "number"], "description": "e.g. \"+500 over 8 steps\" (steps, beats, bars or frames)." },
+            "steps": { "type": "number", "exclusiveMinimum": 0 },
+            "beats": { "type": "number", "exclusiveMinimum": 0 },
+            "bars": { "type": "number", "exclusiveMinimum": 0 },
+            "frames": { "type": "number", "exclusiveMinimum": 0 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  }
 }