# 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.

Pipeline:

LLM → SIDWAVE (YAML) → MCP Compiler → SID Binary (.sid/.prg) → Ultimate64 REST → C64 Playback

---

## File and Schema Conventions

- **Format name:** SIDWAVE
- **File suffix:** `.sidwave.yaml` (or `.sid.yaml` for brevity)
- **Schema field:** `sidwave: 1.0`
- **Schema file:** `sidwave.schema.json`
- **Primary serialization:** YAML 1.2 (JSON also valid)

---

## Example SIDWAVE File

```yaml
# yaml-language-server: $schema=https://example.com/sidwave.schema.json
sidwave: 1.0
title: "Echoes of Tomorrow"
author: "Generated by MCP"
tempo: 92
mode: PAL
global_fx:
  reverb_sim: { depth: 0.3, delay_frames: 3 }
  filter_env: { cutoff_base: 1800, sweep: -800, speed: 12 }

voices:
  - id: 1
    name: LeadPad
    waveform: sawtooth
    adsr: [4, 2, 10, 3]
    patterns:
      A:
        length: 16
        motif: "Cmin9 pad motif"
        transpositions: [0, 5, 7]
        fx:
          vibrato: { depth: 2, rate: 5 }
          filter_mod: { sweep: +500 over 8 steps }

  - id: 2
    name: ArpLayer
    waveform: pulse
    pulse_width: 0.3
    patterns:
      B:
        type: "arpeggio"
        notes: [C3, Eb3, G3, Bb3]
        frame_rate: 2
        fx:
          pwm_sweep: { speed: 6, depth: 8 }

  - id: 3
    name: Bass
    waveform: triangle
    patterns:
      C:
        groove: [C1, C1, C1, G0]
        fx:
          slide: { depth: 2, speed: 3 }

timeline:
  - section: "Intro"
    bars: 16
    layers: { v1: A, v2: -, v3: C }
  - section: "Build"
    bars: 32
    layers: { v1: A↑, v2: B, v3: C }
  - section: "Drift"
    bars: 48
    layers: { v1: A↓, v2: B, v3: C }
  - section: "Fade"
    bars: 32
    layers: { v1: A–, v2: -, v3: - }
```

---

## MCP Responsibilities

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:

```
POST /v1/attachment:sid
Content-Type: application/octet-stream
Body = compiled binary
```

---

## Authoring and Validation

- SIDWAVE files are plain YAML and open cleanly in any standard editor.
- Validation uses JSON Schema:

```json
{
  "yaml.schemas": {
    "https://example.com/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`.
> Avoid direct note repetition; reuse and transpose patterns.
