kimusic

name

kimusic

description

AI music composition toolkit — generate original music as MP3 files using MIDI synthesis. Covers Western classical, Chinese traditional, jazz, film score, and other genres. Guides the model through a structured workflow: narrative concept → music theory blueprint → Python MIDI code → FluidSynth rendering → MP3 output. Includes music theory references, GM instrument mappings, genre-specific patterns, and environment auto-setup. Use when the user asks to: create/compose/make music, generate a song/piece/track, write a melody/symphony/sonata, make an MP3, compose classical/Chinese/jazz music, learn music theory and create something, or any task involving MIDI composition and audio synthesis. Do NOT use for: playing existing music files, music analysis without creation, or karaoke/lyrics-only tasks.

Kimusic — AI Music Composition Toolkit

Create original music from concept to MP3. No sub-agents — one model, five steps.

Workflow

Step 1: Environment  →  Check/install tools (run scripts/check_env.sh)
Step 2: Concept      →  Narrative + genre + instrumentation choices
Step 3: Blueprint    →  Detailed musical blueprint with MIDI note data
Step 4: Code         →  Python script using midiutil (use scripts/compose_template.py as skeleton)
Step 5: Render       →  MIDI → WAV → MP3 (run scripts/render.sh)

Step 1: Environment Check

Run the environment check script first. It verifies and installs all dependencies:

bash {SKILL_DIR}/scripts/check_env.sh

This checks for: fluidsynth, GM SoundFont (FluidR3_GM.sf2), Python midiutil, ffmpeg, lame. If anything is missing, it installs automatically (requires apt + pip3).

Step 2: Concept — The Narrative Seed

Every good piece starts with a story, not a scale. Before any music theory, establish:

1. Title — A poetic or evocative name (e.g., "月下听泉", "Dawn Over the Steppe")
2. Narrative arc — What emotional journey does the listener take? (e.g., "calm dawn → rising energy → triumphant peak → serene sunset")
3. Genre — See references/genre-patterns.md for supported genres and their characteristics
4. Duration — Target length in minutes (default: ~3 minutes / 180 seconds)
5. Instrumentation — Choose 4-6 instruments from references/gm-instruments.md
6. Mood palette — 3-5 adjectives (e.g., "ethereal, melancholic, luminous")

Present the concept to the user for confirmation before proceeding.

Step 3: Blueprint — The Musical Architecture

This is the most critical step. Read references/blueprint-guide.md for the full template and examples.

The blueprint is a structured document containing ALL musical decisions before any code is written. It must include:

Required Blueprint Sections

1. Theory Foundation — Scale/mode, key signature, harmonic language

   • Read references/music-theory.md for the relevant theory (Western or Chinese or other)

2. Structure Table — Sections with bar count, time signature, BPM, beat count, duration, mood

   Section	Bars	Time Sig	BPM	Beats	Duration	Character
   Intro	4	4/4	72	16	~13s	Serene
   ...

3. Beat Offset Table — Cumulative beat positions for each section boundary

4. Tempo Map — (beat, bpm) tuples for all tempo changes

5. Instrument Assignment — Track number, MIDI channel, GM program, role per section

6. Harmony Progression — Chord symbols per bar (Roman numerals + actual chords)

7. Note Sequences — For EVERY track in EVERY section, provide complete (pitch, beat, duration) Python tuples

   • Pitches as MIDI numbers (C4=60)
   • Beats relative to section start (add offset in code)
   • Duration in beats

8. Velocity Map — Per-section dynamics with MIDI velocity values

Blueprint Quality Gate

Before proceeding to code, verify:

• Total duration is within ±15s of target
• Beat offsets are mathematically consistent
• Every section has every track defined (or explicitly marked tacet)
• Note sequences use only scale-appropriate pitches (+ marked ornamental exceptions)
• Melody has clear phrase structure (antecedent-consequent, call-response, etc.)

Step 4: Code — Translate Blueprint to Python

Use the compose template as a starting skeleton:

cp {SKILL_DIR}/scripts/compose_template.py ./compose.py

Then fill in the data from the blueprint. Key architecture:

# Constants: paths, beat offsets, GM programs, tempo map
# add() helper: (track, notes, offset, velocity) → midi.addNote()
# Per-section functions: intro(), section_a(), section_b(), ...
# create_midi() → write .mid file
# render_audio() → fluidsynth + ffmpeg → .mp3

Code Quality Rules:

• Every note tuple from the blueprint → one addNote() call
• Tempo changes via addTempo() on track 0
• Instrument setup via addProgramChange() per track
• Use ticks_per_quarternote=480 for fine timing resolution
• Clean up intermediate WAV after MP3 encoding

Step 5: Render and Deliver

bash {SKILL_DIR}/scripts/render.sh <input.mid> <output.mp3>

Or let the Python script handle rendering directly (preferred — compose_template.py includes render functions).

After rendering, verify:

• MP3 file exists and is >500KB (sanity check)
• Duration roughly matches blueprint target
• Send MP3 to user

Narrative Design Statement (mandatory output)

After delivering the MP3, always present a Narrative Design Statement explaining the creative intent. This bridges the gap between raw audio and the artistic vision. Include:

1. Narrative Arc — The emotional journey in plain language

   "The piece traces a path from predawn stillness through the awakening of a mountain spring, building to a torrent of energy before dissolving back into silence."

2. Why This Genre / Mode / Key — Connect the technical choice to the story

   "A minor pentatonic (羽調式) was chosen for its inherent melancholy and connection to Chinese landscape painting aesthetics."

3. Instrumentation Rationale — Why each instrument was cast in its role

   "The shakuhachi carries the main voice — its breathy tone evokes wind through bamboo. The koto provides water imagery through arpeggiated figures."

4. Structural Motivation — Why this form, not another

   "The 散-慢-中-快-散 structure mirrors the natural rhythm of a mountain spring: trickling at dawn, swelling by noon, calming at dusk."

5. Key Moments — 2-3 specific musical moments and their dramatic purpose

   "At bar 42, the erhu enters in unison with the xiao — two voices becoming one, symbolizing the merging of moonlight and water."

6. Limitations & Honesty — What GM SoundFont cannot capture

   "The shakuhachi lacks the breath noise and pitch bends that define the real instrument. The emotional shape is there; the timbral soul awaits a dedicated sample library."

Format this as a readable block after the MP3 delivery message. Keep it concise (150-300 words) but evocative — it should make the listener hear the piece differently.

If the user wants a Feishu/document record, write a full doc covering: concept, theory, blueprint summary, narrative design statement, technical implementation, and result stats.

Reference Files

File	When to Read	Content
references/music-theory.md	Step 3 — after choosing genre	Western harmony, Chinese pentatonic, scales, modes, cadences
references/gm-instruments.md	Step 2 — choosing instruments	Full GM instrument table + Chinese/ethnic instrument mappings
references/blueprint-guide.md	Step 3 — writing blueprint	Complete blueprint template + annotated examples
references/genre-patterns.md	Step 2 — choosing genre	Genre-specific patterns: structure, harmony, rhythm, instrumentation

Common Pitfalls

1. Skipping the blueprint → Results in incoherent music. Always blueprint first.
2. Non-pentatonic notes in Chinese music → Only A C D E G (+ rare F/B ornaments). Check every pitch.
3. Beat offset math errors → Section N offset = sum of all previous sections' total beats. Double-check.
4. B section time signature changes → If switching to 3/4, each bar = 3 beats, not 4. Affects offset calculation.
5. Velocity monotony → Vary dynamics between sections AND within phrases. Music without dynamics is dead.
6. FluidSynth channel 9 → Reserved for percussion in GM. Never assign melodic instruments to channel 9.
7. Duration overshoot → Calculate total duration from tempo map BEFORE writing notes. Adjust bar counts to hit target.