Midi agent skill

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 you need...	Read this file
Scales, chords, intervals, cadences	resources/music-theory.md
Chord progressions by genre	resources/chord-progressions.md
Avoiding dissonance, voice spacing	resources/voice-leading.md
Classical/Baroque counterpoint	resources/counterpoint.md
Modes (Dorian, Phrygian, etc.)	resources/modes-scales.md
Rhythm, time signatures, syncopation	resources/rhythm-patterns.md
Instrument ranges, combinations	resources/orchestration.md

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

Script	Purpose
skills/generate_midi.py	Generate MIDI (auto-assigns channels per track)
skills/normalize_composition.py	Validate and normalize input
skills/refine_composition.py	Adjust length, extend tracks
skills/convert_to_wav.py	MIDI → WAV (requires FluidSynth)

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

Value	Note
1	Whole note (4 beats)
2	Half note (2 beats)
d2	Dotted half (3 beats)
4	Quarter note (1 beat)
d4	Dotted quarter (1.5 beats)
8	Eighth note (0.5 beats)
16	Sixteenth note (0.25 beats)

Instrument Aliases

Alias	GM Instrument
piano	acoustic-grand-piano
guitar	acoustic-guitar-nylon
bass	acoustic-bass
strings	string-ensemble-1
brass	brass-section
sax	alto-sax

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/