music-skill plugin

---
name: music-production
description: "Composes, arranges, performs and mixes original instrumental music as editable notes. The agent writes every note into a project file; scripts check the score, play it on sampled instruments (pianos, guitars, basses, drums, orchestra, saxophones, erhu, steel drum, mallets, organ) or built-in synthesizers, Surge XT presets and drum machines with player-like timing, dynamics, swing and legato, mix it with buses, sidechain, delays and reverbs, and master it to MIDI, stems, an MP3 and seamless game loops. No audio-generation model: every note can be changed and re-rendered. Use it whenever the user wants an original instrumental track, game, film, video or visual novel music, an RPG scene, horror or anime-opening-style cue, orchestral, baroque, piano, jazz, blues, bossa nova or organ music, pop ballads, rock, metal, EDM, techno, synthwave, chiptune, lo-fi, boom bap or trap beats, an arrangement, a revision of one phrase, editable MIDI, stems or a mix, even if they only ask for 'a song' or 'some music'."
license: "MIT; scripts/surge_host.py is GPL-3.0-or-later (LICENSES/GPL-3.0-or-later.txt)"
compatibility: "Python 3.10+ with NumPy. FluidSynth 2.x and FFmpeg 6 or newer: pinned portable builds on Windows x64, the system packages on Linux and macOS. Sound banks are downloaded once from this project's GitHub release (twenty-five built here, five repacked unchanged from FreePats), each checked against a pinned SHA-256, with each publisher's own download as the fallback. No GPU and no audio model."
metadata:
  author: "owoevan-dev"
  version: "0.6.0"
---

# Music production

The music is written, not generated. You decide every note, chord, velocity and placement; the scripts validate the project, question the score, perform it, render it on sampled instruments, mix and master it, and measure the result. A clean render shows the pipeline worked, not that the music does. Listening decides that.

What it does and does not do (say so when it matters to the request):
- **Does**: complete instrumental pieces up to 30 minutes and 64 parts, one meter per project with a tempo map; sampled instruments, subtractive and FM synthesizers, Surge XT with its 3,008 patches (optional, installed by default), drum machines, an additive synth voice and noise transitions; player-like timing and dynamics, swing, staggered chords, legato and pitch bends; production tools (sidechain ducking, tempo-synced delay, filter sweeps, saturation, gates, tape wobble, vinyl noise); MIDI, processed stems, a mixed and mastered WAV, FLAC and MP3.
- **Does not**: sing or set lyrics, host your own VST plugins (only the bundled Surge XT runs), invent articulations a sample bank does not contain, or judge musical quality from numbers.

## Workflow

Copy this checklist into the project's notes and tick it off. Each step ends on its done-criterion.

- [ ] **0. Setup**: `studio.py doctor --config <config>` passes. Without a configuration, tell the user what the setup installs, its size and how long it takes, and run it once they agree ([setup.md](references/setup.md)); keep the configuration where the next session will find it (the user's choice, for example `~/.music-skill/`). Install banks for the parts you plan, by group or name (`fetch_soundbanks.py --only`), not all thirty up front ([soundbanks.md](references/soundbanks.md)).
- [ ] **1. Brief**: duration, mood, style, the foreground instrument and the delivery format are settled from the request; ask only for what blocks the composition. Place the piece on the style maps: one entry, or a primary entry with others borrowed for some axes, each borrowing with its reason, written into the project's `style` ([style-maps.md](references/style-maps.md)). For a game, also the use (loop, one-shot or layers), how long a player stays and where the loop starts ([game-music.md](references/game-music.md)). For an anime opening or a J-rock or J-pop band cue, the length (TV size is about 90 s) and the instrument that carries the vocal line ([anime-opening.md](references/anime-opening.md)). For a scene in a visual novel or an RPG, the cue's place in the set, whether the lines are voiced, and the engine ([scene-music.md](references/scene-music.md)). For orchestra or pipe organ, the ensemble, the room and the dynamic range ([orchestration.md](references/orchestration.md), [organ.md](references/organ.md)); for solo piano or a small ensemble, [piano-and-chamber.md](references/piano-and-chamber.md). For EDM, techno, future bass, synthwave or chiptune, the style, tempo and use ([electronic.md](references/electronic.md)); for lo-fi, boom-bap or trap beats, [beats.md](references/beats.md); for jazz, blues, bossa nova, funk or city pop, [jazz-and-funk.md](references/jazz-and-funk.md); for baroque music, [baroque.md](references/baroque.md). For film or video underscore, music timed to picture, or a suspense or horror cue, [film-score.md](references/film-score.md); for instrumental pop or a ballad, [pop-and-ballad.md](references/pop-and-ballad.md); for rock or metal, [rock-and-metal.md](references/rock-and-metal.md). A brief and a revision log exist in the project folder.
- [ ] **2. Form and theme**: sections with a function each, a planned high point and an ending; a motif in real pitches and rhythm, tested against the bass and simple harmony before other parts are written: the hook first, phrases that breathe, sections built by restating it; an energy plan per section and support parts with a rhythm of their own ([arrangement.md](references/arrangement.md); the high point and the melody, [climax-and-melody.md](references/climax-and-melody.md); chords and keys, [harmony.md](references/harmony.md); variation and groove, [development-and-groove.md](references/development-and-groove.md)).
- [ ] **3. Project file**: written to [schema.md](references/schema.md), usually by a composition script of your own in the project folder; `studio.py validate` passes and lists no warnings (an unknown field is a typo that does nothing).
- [ ] **4. Performance**: velocities, gates and timing shaped by phrase; player-like deviation from `musiclib.expression` (`drift='time'`, so a revised note moves nothing else); legato on sustained sampled leads, bends on lead guitar ([performance-and-mix.md](references/performance-and-mix.md)).
- [ ] **5. Revision rounds**: each round is one `studio.py round` into a new folder (`r1`, `r2`, ...), with `--previous` the round before. It validates the project, reviews the score with the configuration (so notes far from their samples are found), renders a draft (the same audio as a full render; `mix.chain` is `"bus"` for a finished mix), analyzes it (`--reference` where a genre reference fits, `--span` for a passage) and compares it with the previous round, printing each step's summary. Every review question has a musical decision (a prepared tension, a loop that now moves, or a fix); review also asks where nothing changes and where parts move as blocks or never push, about notes outside the written chord that are not resolved by step, parallel fifths and octaves between independent parts and close intervals under their low interval limits, and, with Surge XT installed, about built-in synth presets a Surge patch covers. Section levels, spectrum, tonal balance, stereo and lead presence are explained or fixed. The comparison shows that only the intended parts and bars changed; if anything else did, find out why first. One cause at a time, then a full-form pass; `studio.py profile` shows whether density, register, repetition and the melody's phrases follow the plan section by section.
- [ ] **6. Listen**: the user heard the full piece; a round's `--clip <file>.mp3` gives them its change old then new at equal loudness (`studio.py compare --clip` does it for any two renders).
- [ ] **7. Deliver**: a full render (`studio.py render`, without `--draft`) completes with every check passed. Master, FLAC, MP3, MIDI, stems (and `returns/` for a remix) and project, and for a game loop `loop.wav`/`loop.ogg` with the loop points; a credit only where a bank the user added asks for one (the banks the setup installs ask nothing of the music); measured checks; what changed and what is still open. Then `studio.py clean <project> --keep <final render> --keep <last round>` lists the piece's older renders, rounds and audition caches and the cache entries those two do not use; check the list, then run it again with `--remove`. It removes only what the tools made for that piece, by the records they wrote, never follows a link, and leaves alone a folder a render, round or audition is still working in.

## Commands

`scripts/studio.py` is the entry point. Resolve its absolute path from this skill's folder; do not assume the working directory.

```text
python <skill>/scripts/studio.py doctor   --config <config.json>
python <skill>/scripts/studio.py round    <project>/song.json --config <config.json> --output <project>/r2 --previous <project>/r1 --clip <project>/r1_r2.mp3
python <skill>/scripts/studio.py render   <project>/song.json --config <config.json> --output <project>/final
python <skill>/scripts/studio.py clean    <project> --keep <project>/final --keep <project>/r6 --remove   # without --remove: the list only