c64bridge 0.7.4 → 0.8.0

package/mcp/schemas/c64_sound.schema.json

@@ -0,0 +1,644 @@
+{
+  "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"
+      ],
+      "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"
+      ],
+      "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"
+      ]
+    },
+    {
+      "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"
+      ]
+    },
+    {
+      "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"
+      ],
+      "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"
+      ]
+    },
+    {
+      "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"
+      ],
+      "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"
+      ],
+      "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"
+      ]
+    },
+    {
+      "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"
+      ]
+    },
+    {
+      "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"
+      ]
+    },
+    {
+      "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"
+      ]
+    },
+    {
+      "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"
+      ],
+      "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"
+      ],
+      "additionalProperties": false
+    }
+  ],
+  "discriminator": {
+    "propertyName": "op"
+  }
+}

package/mcp/schemas/c64_stream.schema.json

@@ -0,0 +1,61 @@
+{
+  "type": "object",
+  "description": "Streaming operations available via the c64_stream tool.",
+  "oneOf": [
+    {
+      "type": "object",
+      "description": "Start an Ultimate streaming session toward a host:port target.",
+      "properties": {
+        "stream": {
+          "type": "string",
+          "description": "Stream type to control (video/audio/debug).",
+          "enum": [
+            "video",
+            "audio",
+            "debug"
+          ]
+        },
+        "target": {
+          "type": "string",
+          "description": "Destination host:port or UDP target understood by the firmware.",
+          "minLength": 3
+        },
+        "op": {
+          "const": "start"
+        }
+      },
+      "required": [
+        "stream",
+        "target",
+        "op"
+      ],
+      "additionalProperties": false
+    },
+    {
+      "type": "object",
+      "description": "Stop an active Ultimate streaming session.",
+      "properties": {
+        "stream": {
+          "type": "string",
+          "description": "Stream type to control (video/audio/debug).",
+          "enum": [
+            "video",
+            "audio",
+            "debug"
+          ]
+        },
+        "op": {
+          "const": "stop"
+        }
+      },
+      "required": [
+        "stream",
+        "op"
+      ],
+      "additionalProperties": false
+    }
+  ],
+  "discriminator": {
+    "propertyName": "op"
+  }
+}