c64bridge 0.5.0

package/data/audio/sid-programming-best-practices.md

@@ -0,0 +1,198 @@
+# SID Programming Best Practices - Perfect Scale Generation
+
+## Overview
+
+This document captures the successful approach for creating pleasant, musical SID sounds on the Commodore 64, discovered through iterative testing with the MCP server and real hardware feedback.
+
+## Sample Programs
+
+### Play C Major Scale with Basic
+
+```basic
+10 POKE 54296,15:REM VOLUME
+20 POKE 54277,17:POKE 54278,240:REM FAST ATTACK, SLOW RELEASE
+30 REM LOWER C MAJOR SCALE WITH TRIANGLE WAVE
+40 POKE 54273,30:POKE 54274,0:POKE 54276,17:FOR I=1 TO 3000:NEXT I:POKE 54276,16:FOR I=1 TO 500:NEXT I
+50 POKE 54273,34:POKE 54274,0:POKE 54276,17:FOR I=1 TO 3000:NEXT I:POKE 54276,16:FOR I=1 TO 500:NEXT I
+60 POKE 54273,38:POKE 54274,0:POKE 54276,17:FOR I=1 TO 3000:NEXT I:POKE 54276,16:FOR I=1 TO 500:NEXT I
+70 POKE 54273,40:POKE 54274,0:POKE 54276,17:FOR I=1 TO 3000:NEXT I:POKE 54276,16:FOR I=1 TO 500:NEXT I
+80 POKE 54273,45:POKE 54274,0:POKE 54276,17:FOR I=1 TO 3000:NEXT I:POKE 54276,16:FOR I=1 TO 500:NEXT I
+90 POKE 54273,51:POKE 54274,0:POKE 54276,17:FOR I=1 TO 3000:NEXT I:POKE 54276,16:FOR I=1 TO 500:NEXT I
+100 POKE 54273,57:POKE 54274,0:POKE 54276,17:FOR I=1 TO 3000:NEXT I:POKE 54276,16:FOR I=1 TO 500:NEXT I
+110 POKE 54273,60:POKE 54274,0:POKE 54276,17:FOR I=1 TO 3000:NEXT I:POKE 54276,16
+120 POKE 54276,0:PRINT "SMOOTH SCALE DONE"
+```
+
+## Key Success Factors
+
+### 1. Ultra-Low Frequencies
+
+- **Critical Discovery**: The standard frequency tables from documentation are too high for pleasant listening
+- **Working Range**: Use frequencies around 30-60 for the low byte, 0 for high byte
+- **Result**: Produces warm, bass-like tones instead of harsh, screechy sounds
+
+### 2. Triangle Wave Instead of Pulse
+
+- **Register 54276**: Use value `17` (triangle wave + GATE) instead of `33` (pulse wave + GATE)
+- **Benefit**: Triangle waves are much smoother and more musical than pulse waves
+- **Off State**: Use `16` (triangle wave, no GATE) to properly release notes
+
+### 3. Proper ADSR Envelope
+
+- **Attack/Decay (54277)**: `17` = fast attack (1), slow decay (7)
+- **Sustain/Release (54278)**: `240` = high sustain (15), no release (0)
+- **Effect**: Creates natural-sounding note onset and sustain
+
+### 4. Timing is Everything
+
+- **Note Duration**: 3000 cycles provides proper sustain (~1.5 seconds)
+- **Pause Duration**: 500 cycles between notes for clear separation
+- **GATE Control**: Keep GATE on during entire note, then turn off cleanly
+
+### 5. Musical Expression and Phrasing
+
+- **Varied Note Lengths**: Don't make all notes the same duration - create rhythm and emphasis
+- **Phrase Breathing**: Use longer pauses between musical phrases (150-200 cycles)
+- **Dynamic Emphasis**: Emphasize important notes (phrase beginnings/endings) with longer durations
+- **Narrative Flow**: Each phrase should have its own character and emotional arc
+- **Quick Passages**: Use shorter notes (140-180 cycles) for rapid, flowing sections
+- **Sustained Endings**: Use longer notes (400-600 cycles) for phrase climaxes and endings
+
+## Technical Analysis
+
+### Frequency Values Used
+
+```text
+Note | Low Byte | High Byte | Estimated Hz
+-----|----------|-----------|-------------
+C    | 30       | 0         | ~50 Hz
+D    | 34       | 0         | ~57 Hz  
+E    | 38       | 0         | ~63 Hz
+F    | 40       | 0         | ~67 Hz
+G    | 45       | 0         | ~75 Hz
+A    | 51       | 0         | ~85 Hz
+B    | 57       | 0         | ~95 Hz
+C    | 60       | 0         | ~100 Hz
+```
+
+### Register Settings
+
+```text
+54296 (Volume): 15 (maximum)
+54277 (AD): 17 (attack=1, decay=7)
+54278 (SR): 240 (sustain=15, release=0)
+54273 (Freq Lo): Variable per note
+54274 (Freq Hi): 0 (always)
+54276 (Control): 17 (triangle+gate) / 16 (triangle only)
+```
+
+## Common Pitfalls to Avoid
+
+### 1. Using Documentation Frequencies Directly
+
+- Standard frequency tables (C4=261Hz → 0x113E) produce harsh, unpleasant sounds
+- These frequencies are mathematically correct but not musically pleasant for listening
+
+### 2. Pulse Wave Without Proper Setup
+
+- Pulse waves require careful pulse width settings
+- Triangle waves are much more forgiving and musical
+
+### 3. Inadequate ADSR Settings
+
+- Without proper envelope, notes sound like short clicks
+- Fast attack + slow decay + high sustain = musical notes
+
+### 4. Poor GATE Timing
+
+- GATE must stay on during the entire note duration
+- Turning GATE off too early creates click-like sounds
+
+## Testing Methodology
+
+This solution was developed through:
+
+1. **Real Hardware Testing**: Used actual C64 Ultimate with MCP server
+2. **Iterative Refinement**: Multiple attempts with frequency adjustments
+3. **Audio Feedback**: Human verification of pleasant vs. harsh sounds
+4. **Systematic Debugging**: Isolated individual notes before building full scale
+
+## MCP Server Integration
+
+### Upload Command
+
+> [!NOTE]
+> These curl commands require the optional legacy HTTP bridge. Start it manually before using them; the day-to-day workflow runs over MCP stdio.
+
+```bash
+curl -X POST -H 'Content-Type: application/json' \
+  -d '{"program": "... BASIC program ..."}' \
+  http://localhost:8000/tools/upload_and_run_basic
+```
+
+### Future Audio Analysis
+
+The working scale can now be used with the `analyze_audio` tool:
+
+```bash
+curl -X POST -H 'Content-Type: application/json' \
+  -d '{"request": "verify the scale sounds correct"}' \
+  http://localhost:8000/tools/analyze_audio
+```
+
+## Musical Expression Example: "Alle meine Entchen"
+
+The following example demonstrates how to create a musically expressive children's song using varied timing and proper phrasing. This serves as a template for writing engaging melodies.
+
+### Key Musical Programming Principles
+
+1. **Opening Emphasis**: First note gets longer duration (250 cycles) to establish the song
+2. **Flowing Middle**: Quick notes (180 cycles) for melodic flow
+3. **Phrase Endings**: Extended notes (400-600 cycles) at the end of each phrase
+4. **Breathing Space**: Longer pauses (150-200 cycles) between phrases
+5. **Character Variation**: Each verse has its own timing character:
+   - "Swimming" = light, quick notes (160 cycles)
+   - "Diving" = very short, rapid notes (140 cycles)
+   - "Triumphant ending" = building emphasis
+
+### Example Implementation
+
+```basic
+REM ALLE MEINE ENTCHEN - MUSICAL PHRASING
+POKE 54296,15:POKE 54277,17:POKE 54278,240
+
+REM OPENING PHRASE - emphasis on first note
+POKE 54273,30:POKE 54274,0:POKE 54276,17:FOR I=1 TO 250:NEXT I:POKE 54276,16:FOR I=1 TO 40:NEXT I
+POKE 54273,34:POKE 54274,0:POKE 54276,17:FOR I=1 TO 180:NEXT I:POKE 54276,16:FOR I=1 TO 40:NEXT I
+REM ... continued with varied timing for musical expression
+```
+
+**Complete example**: See `data/basic/examples/audio/alle-meine-entchen-expressive.bas`
+
+### Timing Patterns for Different Musical Effects
+
+- **Emphasis/Importance**: 250-400+ cycles
+- **Normal melody notes**: 180-200 cycles  
+- **Quick/flowing passages**: 140-160 cycles
+- **Short pauses**: 25-40 cycles
+- **Phrase breathing**: 120-200 cycles
+- **Dramatic pauses**: 150-250 cycles
+
+## Conclusion
+
+The key insight is that **musical programming requires human feedback**, not just technical accuracy. The "correct" mathematical frequencies from documentation don't necessarily produce the most pleasant musical experience. This approach prioritizes:
+
+1. **Listenability** over technical accuracy
+2. **Smooth waveforms** (triangle) over complex ones (pulse)
+3. **Proper envelopes** for musical note shaping
+4. **Musical expression** through varied timing and phrasing
+5. **Real hardware testing** to validate results
+
+**For Children's Songs and Simple Melodies**: Use the expressive timing patterns demonstrated in "Alle meine Entchen" to create engaging, musical compositions that tell a story rather than just playing notes mechanically.
+
+This methodology can be applied to create more complex musical compositions while maintaining the warm, pleasant character achieved in this scale progression.
+
+---
+
+*Document created: December 2024*  
+*Based on successful MCP server + C64 Ultimate testing session*

package/data/audio/sid-spec.md

@@ -0,0 +1,166 @@
+# Commodore 64 SID (MOS 6581 / 8580) — Concise Technical Overview
+
+## Overview
+
+- **Voices:** 3 independent oscillators  
+  Each has: 16-bit frequency, waveform select (triangle / saw / pulse / noise), pulse-width, ADSR envelope, optional SYNC and RING-MOD.  
+- **Global:** Analog multimode filter (LP / BP / HP), resonance, master volume, and read-back registers for OSC3 and ENV3.  
+- **Models:** 6581 (original, “warmer”, nonlinear filter) and 8580 (revised, linear filter, lower noise).
+
+---
+
+## Register Map (base = $D400 / 54272)
+
+**Per Voice (1 – 3):**
+
+| Function | Voice 1 | Voice 2 | Voice 3 | Bits / Notes |
+|-----------|----------|----------|----------|--------------|
+| Frequency LO | $D400 | $D407 | $D40E | Low byte of 16-bit pitch increment |
+| Frequency HI | $D401 | $D408 | $D40F | High byte |
+| Pulse Width LO | $D402 | $D409 | $D410 | 12-bit value (0-4095) |
+| Pulse Width HI | $D403 | $D40A | $D411 | Upper 4 bits used |
+| Control | $D404 | $D40B | $D412 | **7..0 = NOISE PULSE SAW TRI TEST RING SYNC GATE** |
+| AD | $D405 | $D40C | $D413 | Attack/Decay nibbles |
+| SR | $D406 | $D40D | $D414 | Sustain/Release nibbles |
+
+**Global:**
+
+| Function | Address | Description |
+|-----------|----------|-------------|
+| Cutoff LO | $D415 | Lower 8 bits of filter cutoff |
+| Cutoff HI | $D416 | Upper 3 bits of cutoff |
+| Res/Routing | $D417 | 7..4 = resonance (0–15); 3..0 = route Ext,V3,V2,V1 into filter |
+| Mode/Volume | $D418 | 0..3 = master vol (0–15); 4..6 = LP/BP/HP; 7 = CH3 off |
+| Read-backs | $D419–$D41C | POTX, POTY, OSC3, ENV3 |
+
+---
+
+## Note → SID Frequency
+
+```
+FREQ = round( note_hz * 2^24 / φ2 ) >> 8   ; 16-bit register value
+```
+
+- φ₂ = system clock  
+  - PAL = 985 248 Hz  
+  - NTSC = 1 022 727 Hz  
+- Store FREQ (low/high) into FREQLO/HI.  
+- Typical usage: lookup table per note/octave.
+
+**Example (PAL):**
+
+```
+FREQ16 = round( (note_hz * 16777216) / 985248 ) >> 8
+```
+
+---
+
+## Basic Play / Stop Sequence
+
+1. Set FREQ, PW, AD/SR.  
+2. Write CTRL = waveform bits | GATE (=1) → start note.  
+3. Clear GATE bit to release note.
+
+---
+
+## Waveforms & Pulse Width
+
+- **Waveform bits:** Triangle = bit 4, Saw = 5, Pulse = 6, Noise = 7.  
+- **Pulse Width:** 12-bit ($000–$FFF); $0800 ≈ 50 % duty.  
+- Combining waveform bits produces nonlinear mixed timbres.  
+- PWM = vary pulse-width in real time.
+
+---
+
+## Filter Block
+
+- **Cutoff:** $D415 + $D416 (11 bits).  
+- **Resonance / Routing:** $D417.  
+- **Mode / Volume:** $D418 → LP/BP/HP bits + master volume.  
+- **Differences:** 6581 = nonlinear; 8580 = more accurate.
+
+---
+
+## Famous Effects
+
+**Arpeggio** – Cycle chord intervals (e.g. 0,+4,+7) each tick by rewriting FREQ.  
+**Vibrato** – Small sinusoidal offset of FREQ each tick (software LFO).  
+**PWM** – Periodic variation of pulse-width for animated tone.  
+**Filter Sweep** – Ramp cutoff ($D415/$D416) and/or resonance ($D417).  
+**Hard Restart** – Clear GATE early, optionally TEST=1 to reset osc; next tick set ADSR + GATE=1 for tight attack.  
+**Sync / Ring-Mod** – Enable SYNC or RING bits in CTRL to tie oscillators.  
+**Digi Playback** – Rapid writes to $D418 volume simulate 4-bit PCM DAC (~4–8 kHz).
+
+---
+
+## Reset Tips
+
+Write $FF then $00 to all SID registers on init to clear stale state before loading new instrument settings.
+
+---
+
+## Alternative Exact Frequency Formulas
+
+```
+PAL:  x = f * (18 * 2^24) / 17734475
+NTSC: x = f * (14 * 2^24) / 14318182
+```
+
+Equivalent to `FREQ = f * 2^24 / φ2`, then take the upper 16 bits.
+
+---
+
+## Frequency Table (C-Major, A4 = 440 Hz)
+
+| Note | Freq (Hz) | FREQ PAL (hex) | FREQ NTSC (hex) |
+|------|------------|----------------|-----------------|
+| C4 (Do) | 261.63 | 0x113E (4414) | 0x1069 (4201) |
+| D4 (Re) | 293.66 | 0x1325 (4901) | 0x123C (4668) |
+| E4 (Mi) | 329.63 | 0x154E (5454) | 0x1459 (5209) |
+| F4 (Fa) | 349.23 | 0x1667 (5735) | 0x156E (5486) |
+| G4 (Sol)| 392.00 | 0x18EE (6382) | 0x1753 (5971) |
+| A4 (La) | 440.00 | 0x1B9B (7067) | 0x19B5 (6581) |
+| B4 (Ti) | 493.88 | 0x1F04 (7940) | 0x1BFD (7165) |
+| C5 (Do) | 523.25 | 0x2102 (8450) | 0x1E08 (7688) |
+
+*Multiply FREQ by 2ⁿ to move up n octaves.*
+
+---
+
+## Primary References (for RAG)
+
+- Oxyron SID Register Reference — bit map, frequency formulas, play sequence.  
+- Commodore 64 Programmer’s Reference (sound chapter, PDF).  
+- C64-Wiki — SID overview and filter behavior.  
+- Codebase64 — SID programming patterns (arpeggio, vibrato, PWM, players).  
+- $D418 Digi Playback articles — technique and bias requirements.
+
+---
+
+## Typical Usage Snippet (ASM)
+
+```asm
+; Initialize SID
+lda #$0f        ; volume = 15
+sta $d418
+
+; Play note (Voice 1 example)
+lda freq_lo
+sta $d400
+lda freq_hi
+sta $d401
+lda #$00
+sta $d402
+lda #$08
+sta $d403
+lda #$11
+sta $d405
+lda #$f3
+sta $d406
+lda #%01000001  ; pulse + gate
+sta $d404
+
+; ... release ...
+and #%11111110
+sta $d404
+```

package/data/audio/sidwave.md

@@ -0,0 +1,131 @@
+# 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.

package/data/audio/sidwave.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/schemas/sidwave.schema.json",
+  "title": "SIDWAVE Composition Schema",
+  "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 },
+    "mode": { "type": "string", "enum": ["PAL", "NTSC"] },
+    "global_fx": { "type": "object", "additionalProperties": true },
+    "voices": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id"],
+        "properties": {
+          "id": { "type": "number", "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 },
+          "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 }
+              ]
+            }
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "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 }
+    }
+  },
+  "additionalProperties": false
+}