BeatFlow Skill

Compose complete, editable multi-track MIDI with Codex.

BeatFlow turns a musical brief into an explicit Python composition, validates hard structural contracts, realizes exact notes, and exports deterministic Standard MIDI. Musical decisions remain inspectable: timing, roles, phrases, arrangement, voices, and themes are data rather than hidden model state.

BeatFlow 3.0 requires Python 3.10 or newer. Its runtime has two dependencies: Pydantic and Mido. It does not require music21.

Examples

These are MIDI output snapshots, not templates used by the engine.

Composition	MIDI	Focus
After the Last Tram	Download	Neo-soul with extended voicings, independent bass, and foreground space
A Letter in Four Seasons	Download	A theme developed through transposition, augmentation, inversion, and return

Design

musical brief
  -> Codex-authored build() script
  -> Composition 1.2
  -> hard validation
  -> RealizedScore (exact notes + source identity)
  -> advisory checks for declared intent
  -> Standard MIDI

There is no public Project/Clip/Link layer. The renderer and analyzers consume the same realized score. Diagnostics test only explicit contracts—duration, phrases, arrivals, silence, role interaction, counterpoint, and thematic relationships—and never assign a universal quality score.

Install

With the Skills CLI:

npx skills add the0cp/beatflow-skill --skill beatflow-skill --global --agent codex --yes

Or from Codex:

$skill-installer install https://github.com/the0cp/beatflow-skill/tree/master/skills/beatflow-skill

Run the smoke test from the installed skill directory:

python scripts/run.py self-check

The launcher creates an isolated cached environment. When pinned dependencies change, it rebuilds that environment so removed packages do not linger. Set BEATFLOW_CACHE_DIR to move the cache.

Ask Codex to compose

Use $beatflow-skill to compose a 2-3 minute neo-soul piece in 4/4 at about
88 BPM. Use Rhodes voicings with a designed top-note line, an independent
electric bass, restrained drums, and deliberate melodic space. Validate the
composition, revise structural problems, and export MIDI plus Composition and
diagnostic JSON.

BeatFlow writes source and outputs in your workspace, not inside the installed skill. A trusted composition script must expose build():

from beatflow_core.composer import SongBuilder, beat, chord

def build():
    song = SongBuilder(
        "Small Example", intent="A spacious two-bar idea.",
        bpm=88, tonic="D", mode="minor",
    )
    song.track(
        "trk_keys", "Rhodes", program=4,
        low=48, center=62, high=79,
    )
    section = song.section("sec_a", "A", bars=2, energy=0.5)
    section.chord_bar(1, "Dm9")
    section.chord_bar(2, "Gm9")
    keys = section.segment(
        "seg_keys", "Rhodes", track="trk_keys",
        functions=["harmony"], start=beat(0), duration=beat(8),
    )
    keys.chord(beat(0), beat(3), notes=4, top_target=chord(3))
    keys.chord(beat(4), beat(3), notes=4, top_target=chord(5))
    keys.end()
    section.end()
    song.play("occ_a", "sec_a")
    return song.build()

Render it:

python skills/beatflow-skill/scripts/run.py compose song.py \
  --midi song.mid \
  --composition song.composition.json \
  --report song.report.json

The source file is the durable checkpoint. Composition, MIDI, and reports use atomic writes. If a run is interrupted, rerun the same command; realization is deterministic and inexpensive.

Commands

python skills/beatflow-skill/scripts/run.py compose song.py --midi song.mid --composition song.composition.json --report song.report.json
python skills/beatflow-skill/scripts/run.py analyze song.composition.json --output analysis.json
python skills/beatflow-skill/scripts/run.py compare first.json second.json --output comparison.json
python skills/beatflow-skill/scripts/run.py compare before.json after.json --revision --output revision.json
python skills/beatflow-skill/scripts/run.py inspect song.mid
python skills/beatflow-skill/scripts/run.py inspect --schema --output composition.schema.json
python skills/beatflow-skill/scripts/run.py self-check

Supported musical model

• exact rational timing, tuplets, literal durations, and meter-aware helpers;
• functional, relative, and absolute pitch targets;
• common lead-sheet chords through altered 13ths, omissions, and slash bass;
• deterministic voicing with designed chord top notes;
• reusable sections and occurrence-level treatments;
• optional phrase, arrival, silence, interaction, voice, counterpoint, and thematic contracts;
• source-located counterpoint and thematic findings;
• type-1 Standard MIDI with conductor markers and stable channel assignment.

Unsupported chord spellings fail clearly instead of being guessed. General MIDI playback is a preview; final timbre belongs in a DAW or destination instrument.

Develop

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
$env:PYTHONPATH=(Resolve-Path 'skills\beatflow-skill\scripts').Path
.\.venv\Scripts\python.exe -m unittest discover -s tests -v
python skills\beatflow-skill\scripts\run.py self-check

Repository layout:

• skills/beatflow-skill/SKILL.md: Codex workflow
• skills/beatflow-skill/scripts/beatflow_core: compact runtime
• skills/beatflow-skill/references: conditional format/diagnostic/architecture detail
• examples: listening snapshots
• tests: core, counterpoint, and thematic regression tests

License

GPL-3.0-only. See LICENSE.