c64bridge 0.8.1 → 0.9.0

package/mcp/schemas/c64_sound.schema.json

@@ -1,644 +1,368 @@
 {
   "type": "object",
-  "description": "Sound operations available via the c64_sound tool.",
-  "oneOf": [
-    {
-      "type": "object",
-      "description": "Capture raw stereo PCM samples from the C64 Ultimate audio UDP stream.",
-      "properties": {
-        "op": {
-          "const": "capture_samples"
-        },
-        "count": {
-          "type": [
-            "integer",
-            "null"
-          ],
-          "description": "Number of stereo sample pairs to capture.",
-          "minimum": 1,
-          "maximum": 65536,
-          "default": 256
-        },
-        "encoding": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "Encoding used for the PCM sample payload.",
-          "enum": [
-            "base64",
-            "hex"
-          ],
-          "default": "base64"
-        }
-      },
-      "required": [
-        "op"
+  "properties": {
+    "op": {
+      "type": "string",
+      "enum": [
+        "capture_samples",
+        "set_volume",
+        "reset",
+        "note_on",
+        "note_off",
+        "silence_all",
+        "play_sid_file",
+        "play_mod_file",
+        "generate",
+        "compile_play",
+        "play_preset",
+        "pipeline",
+        "analyze",
+        "record_analyze"
       ],
-      "additionalProperties": false
-    },
-    {
-      "type": "object",
-      "description": "Set the SID master volume register at $D418 (0-15).",
-      "properties": {
-        "volume": {
-          "type": "number",
-          "description": "Desired SID master volume. Values outside 0-15 are clamped.",
-          "minimum": 0,
-          "maximum": 15
-        },
-        "op": {
-          "const": "set_volume"
-        }
-      },
-      "required": [
-        "volume",
-        "op"
+      "description": "Selects the operation."
+    },
+    "count": {
+      "type": [
+        "integer",
+        "null"
       ],
-      "additionalProperties": false
-    },
-    {
-      "type": "object",
-      "description": "Soft or hard reset of SID registers to clear glitches.",
-      "properties": {
-        "hard": {
-          "type": "boolean",
-          "description": "If true, perform a hard register scrub; otherwise silence voices softly.",
-          "default": false
-        },
-        "op": {
-          "const": "reset"
-        }
-      },
-      "additionalProperties": false,
-      "required": [
-        "op"
-      ]
+      "description": "Number of stereo sample pairs to capture.",
+      "minimum": 1,
+      "maximum": 65536,
+      "default": 256
     },
-    {
-      "type": "object",
-      "description": "Trigger a SID voice with configurable waveform, ADSR, and pitch.",
-      "properties": {
-        "voice": {
-          "type": "integer",
-          "description": "SID voice to trigger (1-3).",
-          "minimum": 1,
-          "maximum": 3,
-          "default": 1
-        },
-        "note": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "Musical note like A4, C#5, or Bb3. Overrides frequencyHz if provided.",
-          "pattern": "^([A-Ga-g])([#b]?)(-?\\d+)$"
-        },
-        "frequencyHz": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "Explicit frequency in Hz. Used when note is omitted.",
-          "minimum": 1
-        },
-        "system": {
-          "type": "string",
-          "description": "Video system for frequency calculation.",
-          "enum": [
-            "PAL",
-            "NTSC"
-          ],
-          "default": "PAL"
-        },
-        "waveform": {
-          "type": "string",
-          "description": "SID waveform to enable.",
-          "enum": [
-            "pulse",
-            "saw",
-            "tri",
-            "noise"
-          ],
-          "default": "pulse"
-        },
-        "pulseWidth": {
-          "type": "integer",
-          "description": "Pulse width (0-4095). Used for pulse waveform.",
-          "minimum": 0,
-          "maximum": 4095,
-          "default": 2048
-        },
-        "attack": {
-          "type": "integer",
-          "description": "Attack rate nibble (0-15).",
-          "minimum": 0,
-          "maximum": 15,
-          "default": 1
-        },
-        "decay": {
-          "type": "integer",
-          "description": "Decay rate nibble (0-15).",
-          "minimum": 0,
-          "maximum": 15,
-          "default": 1
-        },
-        "sustain": {
-          "type": "integer",
-          "description": "Sustain level nibble (0-15).",
-          "minimum": 0,
-          "maximum": 15,
-          "default": 15
-        },
-        "release": {
-          "type": "integer",
-          "description": "Release rate nibble (0-15).",
-          "minimum": 0,
-          "maximum": 15,
-          "default": 3
-        },
-        "op": {
-          "const": "note_on"
-        }
-      },
-      "additionalProperties": false,
-      "required": [
-        "op"
-      ]
+    "encoding": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Encoding used for the PCM sample payload.",
+      "enum": [
+        "base64",
+        "hex"
+      ],
+      "default": "base64"
+    },
+    "volume": {
+      "type": "number",
+      "description": "Desired SID master volume. Values outside 0-15 are clamped.",
+      "minimum": 0,
+      "maximum": 15
+    },
+    "hard": {
+      "type": "boolean",
+      "description": "If true, perform a hard register scrub; otherwise silence voices softly.",
+      "default": false
+    },
+    "voice": {
+      "type": "integer",
+      "description": "SID voice to trigger (1-3).",
+      "minimum": 1,
+      "maximum": 3,
+      "default": 1
     },
-    {
-      "type": "object",
-      "description": "Release a SID voice by clearing its gate bit.",
-      "properties": {
-        "voice": {
-          "type": "integer",
-          "description": "SID voice to release (1-3).",
-          "minimum": 1,
-          "maximum": 3
-        },
-        "op": {
-          "const": "note_off"
-        }
-      },
-      "required": [
-        "voice",
-        "op"
+    "note": {
+      "type": [
+        "string",
+        "null"
       ],
-      "additionalProperties": false
-    },
-    {
-      "type": "object",
-      "description": "Silence all SID voices with optional audio verification.",
-      "properties": {
-        "verify": {
-          "type": [
-            "boolean",
-            "null"
-          ],
-          "description": "When true, record audio after silencing to confirm the SID output is quiet.",
-          "default": false
-        },
-        "op": {
-          "const": "silence_all"
-        }
-      },
-      "additionalProperties": false,
-      "required": [
-        "op"
-      ]
+      "description": "Musical note like A4, C#5, or Bb3. Overrides frequencyHz if provided.",
+      "pattern": "^([A-Ga-g])([#b]?)(-?\\d+)$"
     },
-    {
-      "type": "object",
-      "description": "Play a SID file stored on the Ultimate filesystem.",
-      "properties": {
-        "path": {
-          "type": "string",
-          "description": "Absolute or Ultimate filesystem path to the SID, PRG, or audio file.",
-          "minLength": 1
-        },
-        "songnr": {
-          "type": [
-            "integer",
-            "null"
-          ],
-          "description": "Song number within the SID file (0-based index).",
-          "minimum": 0
-        },
-        "op": {
-          "const": "play_sid_file"
-        }
-      },
-      "required": [
-        "path",
-        "op"
+    "frequencyHz": {
+      "type": [
+        "number",
+        "null"
       ],
-      "additionalProperties": false
-    },
-    {
-      "type": "object",
-      "description": "Play a MOD tracker module via the Ultimate SID player.",
-      "properties": {
-        "path": {
-          "type": "string",
-          "description": "Absolute or Ultimate filesystem path to the SID, PRG, or audio file.",
-          "minLength": 1
-        },
-        "op": {
-          "const": "play_mod_file"
-        }
-      },
-      "required": [
-        "path",
-        "op"
+      "description": "Explicit frequency in Hz. Used when note is omitted.",
+      "minimum": 1
+    },
+    "system": {
+      "type": "string",
+      "description": "Video system for frequency calculation.",
+      "enum": [
+        "PAL",
+        "NTSC"
       ],
-      "additionalProperties": false
-    },
-    {
-      "type": "object",
-      "description": "Generate a lightweight SID arpeggio playback sequence.",
-      "properties": {
-        "root": {
-          "type": "string",
-          "description": "Root note for the arpeggio such as C4 or A#3.",
-          "pattern": "^([A-Ga-g])([#b]?)(-?\\d+)$",
-          "default": "C4"
-        },
-        "pattern": {
-          "type": "string",
-          "description": "Comma-separated semitone offsets (e.g. '0,4,7').",
-          "minLength": 1,
-          "default": "0,4,7"
-        },
-        "steps": {
-          "type": "integer",
-          "description": "Number of notes to schedule.",
-          "minimum": 1,
-          "maximum": 128,
-          "default": 16
-        },
-        "tempoMs": {
-          "type": "integer",
-          "description": "Delay in milliseconds between notes.",
-          "minimum": 20,
-          "maximum": 2000,
-          "default": 120
-        },
-        "waveform": {
-          "type": "string",
-          "description": "Waveform for playback.",
-          "enum": [
-            "pulse",
-            "saw",
-            "tri",
-            "noise"
-          ],
-          "default": "tri"
-        },
-        "preset": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "Optional musical preset to influence timing/expression.",
-          "enum": [
-            "classic",
-            "expression"
-          ],
-          "default": "classic"
-        },
-        "op": {
-          "const": "generate"
-        }
-      },
-      "additionalProperties": false,
-      "required": [
-        "op"
-      ]
+      "default": "PAL"
+    },
+    "waveform": {
+      "type": "string",
+      "description": "SID waveform to enable.",
+      "enum": [
+        "pulse",
+        "saw",
+        "tri",
+        "noise"
+      ],
+      "default": "pulse"
+    },
+    "pulseWidth": {
+      "type": "integer",
+      "description": "Pulse width (0-4095). Used for pulse waveform.",
+      "minimum": 0,
+      "maximum": 4095,
+      "default": 2048
+    },
+    "attack": {
+      "type": "integer",
+      "description": "Attack rate nibble (0-15).",
+      "minimum": 0,
+      "maximum": 15,
+      "default": 1
+    },
+    "decay": {
+      "type": "integer",
+      "description": "Decay rate nibble (0-15).",
+      "minimum": 0,
+      "maximum": 15,
+      "default": 1
+    },
+    "sustain": {
+      "type": "integer",
+      "description": "Sustain level nibble (0-15).",
+      "minimum": 0,
+      "maximum": 15,
+      "default": 15
+    },
+    "release": {
+      "type": "integer",
+      "description": "Release rate nibble (0-15).",
+      "minimum": 0,
+      "maximum": 15,
+      "default": 3
+    },
+    "verify": {
+      "type": [
+        "boolean",
+        "null"
+      ],
+      "description": "When true, record audio after silencing to confirm the SID output is quiet.",
+      "default": false
+    },
+    "path": {
+      "type": "string",
+      "description": "Absolute or Ultimate filesystem path to the SID, PRG, or audio file.",
+      "minLength": 1
+    },
+    "songnr": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "description": "Song number within the SID file (0-based index).",
+      "minimum": 0
+    },
+    "root": {
+      "type": "string",
+      "description": "Root note for the arpeggio such as C4 or A#3.",
+      "pattern": "^([A-Ga-g])([#b]?)(-?\\d+)$",
+      "default": "C4"
+    },
+    "pattern": {
+      "type": "string",
+      "description": "Comma-separated semitone offsets (e.g. '0,4,7').",
+      "minLength": 1,
+      "default": "0,4,7"
+    },
+    "steps": {
+      "type": "integer",
+      "description": "Number of notes to schedule.",
+      "minimum": 1,
+      "maximum": 128,
+      "default": 16
+    },
+    "tempoMs": {
+      "type": "integer",
+      "description": "Delay in milliseconds between notes.",
+      "minimum": 20,
+      "maximum": 2000,
+      "default": 120
+    },
+    "preset": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Optional musical preset to influence timing/expression.",
+      "enum": [
+        "classic",
+        "expression"
+      ],
+      "default": "classic"
     },
-    {
-      "type": "object",
-      "description": "Compile SIDWAVE or CPG source and optionally play it immediately.",
-      "properties": {
-        "sidwave": {
-          "description": "SIDWAVE composition represented as YAML/JSON text or an already parsed object.",
-          "type": [
-            "string",
-            "object",
-            "null"
-          ]
-        },
-        "cpg": {
-          "description": "SIDWAVE composition represented as YAML/JSON text or an already parsed object.",
-          "type": [
-            "string",
-            "object",
-            "null"
-          ]
-        },
-        "format": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "Source format hint when providing raw text.",
-          "enum": [
-            "yaml",
-            "json"
-          ]
-        },
-        "output": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "Playback target format.",
-          "enum": [
-            "prg",
-            "sid"
-          ],
-          "default": "prg"
-        },
-        "dryRun": {
-          "type": [
-            "boolean",
-            "null"
-          ],
-          "description": "When true, skip playback and only return compilation metadata.",
-          "default": false
-        },
-        "op": {
-          "const": "compile_play"
-        }
-      },
-      "additionalProperties": false,
-      "required": [
-        "op"
+    "sidwave": {
+      "description": "SIDWAVE composition represented as YAML/JSON text or an already parsed object.",
+      "type": [
+        "string",
+        "object",
+        "null"
       ]
     },
-    {
-      "type": "object",
-      "description": "Compile and play a built-in SID preset such as Für Elise by Beethoven.",
-      "properties": {
-        "preset": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "Named SID preset to compile and play. Canonical public preset: fuer_elise.",
-          "minLength": 1,
-          "default": "fuer_elise"
-        },
-        "platforms": {
-          "type": [
-            "array",
-            "null"
-          ],
-          "items": {
-            "type": "string",
-            "description": "Backends to target in sequence.",
-            "minLength": 1,
-            "enum": [
-              "vice",
-              "c64u"
-            ]
-          }
-        },
-        "verify": {
-          "type": [
-            "boolean",
-            "null"
-          ],
-          "description": "Capture and analyze audio on supported backends after playback starts.",
-          "default": true
-        },
-        "analysisDurationSeconds": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "Length of the verification recording on analyzable backends.",
-          "minimum": 0.5,
-          "maximum": 20,
-          "default": 4
-        },
-        "waitBeforeCaptureMs": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "Delay between starting playback and beginning verification capture.",
-          "minimum": 0,
-          "maximum": 5000,
-          "default": 400
-        },
-        "restoreActiveBackend": {
-          "type": [
-            "boolean",
-            "null"
-          ],
-          "description": "Restore the backend that was active before the workflow started.",
-          "default": true
-        },
-        "op": {
-          "const": "play_preset"
-        }
-      },
-      "additionalProperties": false,
-      "required": [
-        "op"
+    "cpg": {
+      "description": "SIDWAVE composition represented as YAML/JSON text or an already parsed object.",
+      "type": [
+        "string",
+        "object",
+        "null"
       ]
     },
-    {
-      "type": "object",
-      "description": "Compile a SIDWAVE score, play it, and analyze the recording.",
-      "properties": {
-        "sidwave": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "SIDWAVE source in YAML or JSON format.",
-          "minLength": 1
-        },
-        "cpg": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "Legacy CPG input format.",
-          "minLength": 1
-        },
-        "output": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "Playback artifact format.",
-          "enum": [
-            "prg",
-            "sid"
-          ],
-          "default": "prg"
-        },
-        "waitBeforeCaptureMs": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "Delay between starting playback and beginning analysis capture (milliseconds).",
-          "minimum": 0,
-          "maximum": 5000,
-          "default": 500
-        },
-        "analysisDurationSeconds": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "Audio capture length in seconds.",
-          "minimum": 0.5,
-          "maximum": 20,
-          "default": 3
-        },
-        "expectedSidwave": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "description": "Optional expected SIDWAVE used to refine analysis comparisons.",
-          "minLength": 1
-        },
-        "verifySilenceBefore": {
-          "type": [
-            "boolean",
-            "null"
-          ],
-          "description": "Run silence verification before playback to ensure a quiet baseline.",
-          "default": true
-        },
-        "verifySilenceAfter": {
-          "type": [
-            "boolean",
-            "null"
-          ],
-          "description": "Run silence verification after playback to ensure voices are released.",
-          "default": true
-        },
-        "silenceDurationSeconds": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "Audio capture length used for silence verification.",
-          "minimum": 0.5,
-          "maximum": 10,
-          "default": 1.5
-        },
-        "silenceRmsThreshold": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "RMS threshold applied to silence verification captures.",
-          "minimum": 0,
-          "maximum": 1,
-          "default": 0.02
-        },
-        "postSilenceWaitMs": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "Delay between main analysis capture and the post-playback silence check (milliseconds).",
-          "minimum": 0,
-          "maximum": 5000,
-          "default": 200
-        },
-        "silenceWaitMs": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "Delay between silencing the SID and recording during pre/post checks (milliseconds).",
-          "minimum": 0,
-          "maximum": 5000,
-          "default": 150
-        },
-        "op": {
-          "const": "pipeline"
-        }
-      },
-      "additionalProperties": false,
-      "required": [
-        "op"
+    "format": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Source format hint when providing raw text.",
+      "enum": [
+        "yaml",
+        "json"
       ]
     },
-    {
-      "type": "object",
-      "description": "Automatically analyze SID playback when verification is requested.",
-      "properties": {
-        "request": {
-          "type": "string",
-          "description": "Natural language user request describing the verification goal.",
-          "minLength": 1
-        },
-        "durationSeconds": {
-          "type": [
-            "number",
-            "null"
-          ],
-          "description": "Override capture duration in seconds.",
-          "minimum": 0.5,
-          "maximum": 30
-        },
-        "expectedSidwave": {
-          "description": "SIDWAVE composition represented as YAML/JSON text or an already parsed object.",
-          "type": [
-            "string",
-            "object",
-            "null"
-          ]
-        },
-        "op": {
-          "const": "analyze"
-        }
-      },
-      "required": [
-        "request",
-        "op"
+    "output": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Playback target format.",
+      "enum": [
+        "prg",
+        "sid"
+      ],
+      "default": "prg"
+    },
+    "dryRun": {
+      "type": [
+        "boolean",
+        "null"
+      ],
+      "description": "When true, skip playback and only return compilation metadata.",
+      "default": false
+    },
+    "platforms": {
+      "type": [
+        "array",
+        "null"
+      ],
+      "items": {
+        "type": "string",
+        "description": "Backends to target in sequence.",
+        "minLength": 1,
+        "enum": [
+          "vice",
+          "c64u"
+        ]
+      }
+    },
+    "analysisDurationSeconds": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "description": "Length of the verification recording on analyzable backends.",
+      "minimum": 0.5,
+      "maximum": 20,
+      "default": 4
+    },
+    "waitBeforeCaptureMs": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "description": "Delay between starting playback and beginning verification capture.",
+      "minimum": 0,
+      "maximum": 5000,
+      "default": 400
+    },
+    "restoreActiveBackend": {
+      "type": [
+        "boolean",
+        "null"
+      ],
+      "description": "Restore the backend that was active before the workflow started.",
+      "default": true
+    },
+    "expectedSidwave": {
+      "type": [
+        "string",
+        "null"
       ],
-      "additionalProperties": false
-    },
-    {
-      "type": "object",
-      "description": "Record audio for a fixed duration and return SID analysis metrics.",
-      "properties": {
-        "durationSeconds": {
-          "type": "number",
-          "description": "Capture duration in seconds (0.5 - 30).",
-          "minimum": 0.5,
-          "maximum": 30
-        },
-        "expectedSidwave": {
-          "description": "SIDWAVE composition represented as YAML/JSON text or an already parsed object.",
-          "type": [
-            "string",
-            "object",
-            "null"
-          ]
-        },
-        "op": {
-          "const": "record_analyze"
-        }
-      },
-      "required": [
-        "durationSeconds",
-        "op"
+      "description": "Optional expected SIDWAVE used to refine analysis comparisons.",
+      "minLength": 1
+    },
+    "verifySilenceBefore": {
+      "type": [
+        "boolean",
+        "null"
+      ],
+      "description": "Run silence verification before playback to ensure a quiet baseline.",
+      "default": true
+    },
+    "verifySilenceAfter": {
+      "type": [
+        "boolean",
+        "null"
+      ],
+      "description": "Run silence verification after playback to ensure voices are released.",
+      "default": true
+    },
+    "silenceDurationSeconds": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "description": "Audio capture length used for silence verification.",
+      "minimum": 0.5,
+      "maximum": 10,
+      "default": 1.5
+    },
+    "silenceRmsThreshold": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "description": "RMS threshold applied to silence verification captures.",
+      "minimum": 0,
+      "maximum": 1,
+      "default": 0.02
+    },
+    "postSilenceWaitMs": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "description": "Delay between main analysis capture and the post-playback silence check (milliseconds).",
+      "minimum": 0,
+      "maximum": 5000,
+      "default": 200
+    },
+    "silenceWaitMs": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "description": "Delay between silencing the SID and recording during pre/post checks (milliseconds).",
+      "minimum": 0,
+      "maximum": 5000,
+      "default": 150
+    },
+    "request": {
+      "type": "string",
+      "description": "Natural language user request describing the verification goal.",
+      "minLength": 1
+    },
+    "durationSeconds": {
+      "type": [
+        "number",
+        "null"
       ],
-      "additionalProperties": false
+      "description": "Override capture duration in seconds.",
+      "minimum": 0.5,
+      "maximum": 30
     }
+  },
+  "required": [
+    "op"
   ],
-  "discriminator": {
-    "propertyName": "op"
-  }
+  "description": "Sound operations available via the c64_sound tool.\n\nOperations:\n- capture_samples: Capture raw stereo PCM samples from the C64 Ultimate audio UDP stream.\n- set_volume: Set the SID master volume register at $D418 (0-15).\n- reset: Soft or hard reset of SID registers to clear glitches.\n- note_on: Trigger a SID voice with configurable waveform, ADSR, and pitch.\n- note_off: Release a SID voice by clearing its gate bit.\n- silence_all: Silence all SID voices with optional audio verification.\n- play_sid_file: Play a SID file stored on the Ultimate filesystem.\n- play_mod_file: Play a MOD tracker module via the Ultimate SID player.\n- generate: Generate a lightweight SID arpeggio playback sequence.\n- compile_play: Compile SIDWAVE or CPG source and optionally play it immediately.\n- play_preset: Compile and play a built-in SID preset such as Für Elise by Beethoven.\n- pipeline: Compile a SIDWAVE score, play it, and analyze the recording.\n- analyze: Automatically analyze SID playback when verification is requested.\n- record_analyze: Record audio for a fixed duration and return SID analysis metrics.",
+  "additionalProperties": false
 }