name: midi-generation description: Generate MIDI files with GM instruments and music theory. Use when creating music, composing melodies, or generating MIDI files. license: MIT

MIDI Generation Skill

Generate MIDI files with proper music theory. Use the provided Python scripts in skills/. Do NOT write custom code.

Important Rules

1. Use provided scripts in skills/ directory (Python)
2. Never write custom Python/JS for MIDI generation
3. Install dependencies first: pip install midiutil
4. Consult music theory resources when needed (see below)

Quick Dissonance Rules

Always follow these to avoid harsh sounds:

1. Never play notes 1 semitone apart (C+C#, E+F, B+C)
2. Bass plays root or fifth of the chord
3. Spread voices across octaves (don't cluster)
4. Each track uses different MIDI channel (automatic)

Music Theory Resources (Read When Needed)

Only read the resource that matches your current task:

When to Read Each Resource

• Pop/Rock song → chord-progressions.md + voice-leading.md
• Classical piece → counterpoint.md + orchestration.md
• Jazz composition → modes-scales.md + chord-progressions.md
• Film score → orchestration.md + modes-scales.md
• Any composition → Always check voice-leading.md for dissonance

Workflow

1. Install dependencies: pip install midiutil
2. Identify genre/style → Select appropriate resources
3. Read relevant theory → Only the files you need
4. Choose instruments → See midi_types/gm_instruments.py
5. Create composition JSON
6. Use scripts to generate MIDI

Python Scripts

Usage Example

import sys
sys.path.insert(0, '/path/to/midi-skill')

from skills.generate_midi import generate_midi_from_dict

composition = {
    "title": "My Song",
    "bpm": 120,
    "tracks": [
        {
            "instrument": "acoustic-grand-piano",
            "notes": [
                {"pitch": "C4", "duration": "4"},
                {"pitch": "E4", "duration": "4"},
                {"pitch": "G4", "duration": "4"},
                {"pitch": "C5", "duration": "2"}
            ]
        },
        {
            "instrument": "acoustic-bass",
            "notes": [
                {"pitch": "C2", "duration": "2"},
                {"pitch": "G2", "duration": "2"}
            ]
        }
    ]
}

midi_path = generate_midi_from_dict(composition)
print(f"Generated: {midi_path}")

Composition Format

{
  "title": "My Song",
  "bpm": 120,
  "tracks": [
    {
      "instrument": "acoustic-grand-piano",
      "notes": [
        { "pitch": "C4", "duration": "4" },
        { "pitch": "E4", "duration": "4" }
      ]
    },
    {
      "instrument": "acoustic-bass",
      "notes": [
        { "pitch": "C2", "duration": "2" }
      ]
    }
  ]
}

Duration Notation

Instrument Aliases

Full list: midi_types/gm_instruments.py

Notes

• Max 15 melodic tracks (MIDI channels 0-8, 10-15; ch.9 = drums)
• Output: output/ directory
• WAV requires: FluidSynth + A320U.sf2 in soundfonts/