code-to-music

What this skill does

This skill provides **tools and patterns** for music composition, not pre-baked solutions. The intelligence and music21 library should be used to compose dynamically based on user requests.

**Core Principle**: Write custom code that composes music algorithmically rather than calling functions with hardcoded melodies.

## Installation & Setup

### Quick Installation

Run the automated installer for complete setup: `install.sh`. This installs all system dependencies, Python packages, and verifies the installation.

**Note:** The install script may display "error: externally-managed-environment" messages at the end. These are expected and can be safely ignored - the dependencies are already installed. If such messages appear, the installation was successful.

### Available SoundFonts

**Traditional Pipeline (Orchestral/Acoustic):**
- **`/usr/share/sounds/sf2/FluidR3_GM.sf2`** (141MB, General MIDI soundfont - use for high-quality orchestral/acoustic samples)
- `/usr/share/sounds/sf2/default.sf2` (symlink to best available)
- ⚠️ **DO NOT use TimGM6mb.sf2** - inferior quality, guitars sound electronic/piano-like

**Electronic Pipeline:**
- Uses the same FluidR3_GM.sf2 soundfont as traditional music
- The difference is which GM programs you choose (synth programs 38-39, 80-95 instead of orchestral)

### Key Concepts

- **Always create downloadable MP3 files** (not HTML players)
- **music21.instrument classes can be used** for convenience: `instrument.Violin()`, `instrument.Violoncello()`, `instrument.Piano()`, `instrument.Trumpet()`, etc.
- **CRITICAL: ALWAYS use mido to set MIDI program numbers after export** - music21's instrument classes do NOT reliably export program_change messages. See the mido workflow below.
- **Generate notes programmatically** - avoid hardcoded sequences

## Choosing Your Music Generation Pipeline

This skill supports TWO rendering pipelines optimized for different musical styles. Read the user's request carefully and choose the correct pipeline by reading the correct next file.

### Decision Process

Identify from the user's request:
- Genre keywords (house, techno, classical, orchestral, reggae)
- Instrument references (synthesizers vs acoustic instruments)
- Musical style descriptions (electronic/DJ vs traditional/acoustic)
- Artist mentions (DJs vs classical composers)

### Electronic Pipeline

**Use `electronic-music-pipeline.md` when request includes:**

- **Genres**: House, techno, trance, EDM, electronic dance music, ambient electronic, acid house, deep house, club music, DJ sets
- **Instruments**: Synthesizers, synth bass/pads/leads, 808 drums, electronic drums, supersaw leads, sub-bass
- **Context**: References to DJs (Keinemusik, Black Coffee, Avicii, Swedish House Mafia), BPM 120-140, "for a club", "for dancing"
- **Sound descriptions**: "Fat synth sound", "buzzy leads", "electronic", "synth-heavy"

**How it works:**
- Uses real-time synthesis (no soundfonts)
- Synthesizes drums, bass, pads, leads on-the-fly with DSP
- Genre presets optimize synthesis parameters (deep_house, techno, trance, ambient, acid_house)
- Frequency-aware mixing automatically balances low/mid/high frequencies
- Best for: Authentic electronic sounds, modern EDM production

**→ See `electronic-music-pipeline.md` for detailed instructions**

---

### Traditional Pipeline

**Use `traditional-music-pipeline.md` when request includes:**

- **Genres**: Classical, orchestral, jazz, blues, rock, country, folk, reggae, ska, symphonic, chamber music
- **Instruments**: Violin, cello, trumpet, flute, piano, acoustic guitar, acoustic bass, brass ensembles, string quartets, organ (reggae/gospel)
- **Context**: References to composers (Mozart, Beethoven, Bach), classical periods (Baroque, Romantic), "unplugged", "acoustic version"
- **Sound descriptions**: "Traditional", "acoustic", "orchestral"

**How it works:**
- Uses pre-recorded orchestral samples (soundfonts)
- FluidR3_GM.sf2 soundfont with 128 General MIDI instruments
- Good for realistic orchestral/acoustic instruments
- Best for: Classical, jazz, reggae, rock, traditional music

**→ See `traditional-music-pipeline.md` for detailed instructions**

---

### If Unclear

- **Default to TRADITIONAL** for mixed requests or ambiguous genres
- **Ask user for clarification** if request could go either way

### Why This Matters

- **Using wrong pipeline** = poor audio quality (technically works, sounds bad)
- Electronic pipeline: Real-time synthesis for authentic electronic sounds
- Traditional pipeline: Pre-recorded samples for realistic orchestral/acoustic

## Available Scripts

All scripts are located in `./scripts`:

**Traditional Rendering:**
- **`midi_inventory.py`** - Extract complete structure from ANY MIDI file to JSON format
- **`midi_render.py`** - Render JSON music structure to MP3 using FluidSynth with dynamic range compression
- **`midi_utils.py`** - MIDI utility functions (extract drums, get BPM, etc.)

**Utilities:**
- **`audio_validate.py`** - Validate audio file quality and format

**Note**: Both electronic and traditional music use the same rendering pipeline (FluidSynth + FluidR3_GM.sf2). The difference is which GM programs you choose.

## Music Theory Reference

### Complete General MIDI Instrument Map (Programs 0-127)

**CRITICAL: music21 does NOT reliably export program_change messages. You MUST ALWAYS use mido to set program numbers after export, even for traditional instruments like saxophone, guitar, or bass. Without this step, tracks will default to piano (program 0).**

**INSTRUMENT CATEGORIZATION FOR SYNTHESIS:**
When composing electronic music, classify instruments by their sonic characteristics for proper synthesis:
- **Guitar (24-31)**: Plucky attack, bright tone, medium sustain - needs distinct synthesis from pads
- **Bass (32-39)**: Low-frequency fundamentals, sub-bass energy, short attack
- **Strings (40-47)**: Sustained bowing, rich harmonics, smooth legato
- **Brass (56-63)**: Bright attack, sustained tone, powerful projection
- **Reed/Woodwinds (64-79)**: Breathy attack, organic timbre, expressive dynamics
- **Synth Lead (80-87)**: Bright, cutting, aggressive - designed for melody
- **Synth Pad (88-95)**: Soft attack, long sustain, atmospheric - designed for background
- **Ethnic/Percussive (104-119)**: Plucky or struck sounds with unique timbres

```python
# Piano (0-7)
0: "Acoustic Grand Piano"
1: "Bright Acoustic Piano"
2: "Electric Grand Piano"
3: "Honky-tonk Piano"
4: "Electric Piano 1"
5: "Electric Piano 2"
6: "Harpsichord"
7: "Clavinet"

# Chromatic Percussion (8-15)
8: "Celesta"
9: "Glockenspiel"
10: "Music Box"
11: "Vibraphone"
12: "Marimba"
13: "Xylophone"
14: "Tubular Bells"
15: "Dulcimer"

# Organ (16-23)
16: "Drawbar Organ"
17: "Percussive Organ"
18: "Rock Organ"
19: "Church Organ"
20: "Reed Organ"
21: "Accordion"
22: "Harmonica"
23: "Tango Accordion"

# Guitar (24-31)
24: "Acoustic Guitar (nylon)"
25: "Acoustic Guitar (steel)"
26: "Electric Guitar (jazz)"
27: "Electric Guitar (clean)"
28: "Electric Guitar (muted)"
29: "Overdriven Guitar"
30: "Distortion Guitar"
31: "Guitar Harmonics"

# Bass (32-39)
32: "Acoustic Bass"
33: "Electric Bass (finger)"
34: "Electric Bass (pick)"
35: "Fretless Bass"
36: "Slap Bass 1"
37: "Slap Bass 2"
38: "Synth Bass 1"
39: "Synth Bass 2"

# Strings (40-47)
40: "Violin"
41: "Viola"
42: "Cello"
43: "Contrabass"
44: "Tremolo Strings"
45: "Pizzicato Strings"
46: "Orchestral Harp"
47: "Timpani"

# Ensemble (48-55)
48: "String Ensemble 1"
49: "String Ensemble 2"
50: "Synth Strings 1"
51: "Synth Strings 2"
52: "Choir Aahs"
53: "Voice Oohs"
54: "Synth Voice"
55: "Orchestra Hit"

# Brass (56-63)
56: "Trumpet"
57: "Trombone"
58: "Tuba"
59: "Muted Trumpet"
60: "French Horn"
61: "Brass Section"
62: "Synth Brass 1"
63: "Synth Brass 2"

# Reed (64-71)
64: "Soprano Sax"
65: "Alto Sax"
66: "Tenor Sax"
67: "Baritone Sax"
68: "Oboe"
69: "English Horn"
70: "Bassoon"
71: "Clarinet"

# Pipe (72-79)
72: "Piccolo"
73: "Flute"
74: "Recorder"
75: "Pan F