discover · compare · collections · requirements · contribute · feed · watching · stats · help with your tokens

the0cp/beatflow-skill · source

Snapshot 0 · 2026-11-04T12:47:28Z · Python · GPL-3.0

GitHub description at capture

AI music composition skill with a Python DSL, musical diagnostics, and deterministic multi-track MIDI rendering.

README at capture

# 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](examples/neo-soul.mid) | Neo-soul with extended voicings, independent bass, and foreground space |
| A Letter in Four Seasons | [Download](examples/theme-and-variation.mid) | A theme developed through transposition, augmentation, inversion, and return |

## Design

```text
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:

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

Or from Codex:

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

Run the smoke test from the installed skill directory:

```bash
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

```text
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()`:

```python
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:

```bash
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

```bash
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

```powershell
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](LICENSE).