Workflows

1. Generate From a Prompt

ableton-composer generate "dusty trip-hop with smoky keys and slow drums" \
  --tracks "Bass,Drums,Pad,Lead,Chords,FX" \
  --provider openai

Use this when you want a fast prompt-to-set workflow without prior analysis.

2. Analyze an Album

Use this workflow with your own material, licensed material, or synthetic/example sets. The reference bundle is meant to capture structural signals for your workflow, not to recreate a protected recording.

ableton-composer analyze sets/reference-collection \
  --scope album \
  --artist "Example Artist" \
  --album "Midnight Signals"

This writes a hierarchical album bundle with:

  • core.json
  • harmony.json
  • rhythm.json
  • arrangement.json
  • prompt.json
  • bundle.json

3. Generate From an Album Bundle

ableton-composer generate "moody electronic sketch with restrained hooks" \
  --style profiles/albums/example-artist/midnight-signals/bundle.json \
  --tracks "Bass,Drums,Pad,Lead,Chords,FX" \
  --provider openai \
  --sections 4 \
  --chunk-size 2

Use chunking for larger prompts or album-scale style bundles.

4. Transcribe an Audio Sketch to MIDI

ableton-composer transcribe audio/idea.wav --engine basic-pitch --out midis/idea.mid
ableton-composer transcribe audio/idea.wav --to-set sets/idea/
ableton-composer transcribe audio/song.wav --separate-first --stem vocals --to-set sets/song-vocal-line/
ableton-composer transcribe audio/song.wav --separate-first --stems bass,vocals --to-set sets/song-stems/
ableton-composer transcribe audio/song.wav --separate-first --stems bass,vocals --push --push-setup
ableton-composer transcribe audio/piano.wav --engine klangio --out midis/piano.mid --xml-out exports/piano.musicxml --to-set sets/piano/

Use this when you want to start from a hummed melody, instrument sketch, or rough audio idea and bring it into the existing MIDI/AbletonSong workflow. This path is optional and can use either the external Basic Pitch CLI or the hosted Klangio API.

The transcribed set path is useful when you want to:

  • inspect the notes before pushing to Ableton
  • critique or compare the result
  • continue composing from the transcription rather than only exporting raw MIDI
  • improve results by transcribing a simpler separated stem such as vocals or bass instead of the full mix
  • merge multiple separated stems into one AbletonSong before pushing to Live
  • switch to Klangio when you want an optional hosted engine that can return both MIDI and MusicXML with local caching

For one-shot WAV-to-Ableton workflows, transcribe can now separate a mix first, transcribe multiple stems with --stems or --all-stems, merge those symbolic tracks into one set, and optionally push the merged result straight into the open Ableton Live set with --push.

5. Separate a Mix Into Stems

ableton-composer separate audio/song.wav --engine demucs
ableton-composer separate audio/song.wav --out stems/separated/song/
ableton-composer separate audio/song.wav --manifest

Use this when you start from a stereo file and want to unlock the existing stems workflow. The current MVP:

  • depends on the optional Demucs CLI
  • writes a normalized output directory instead of exposing Demucs-internal folder layout
  • preserves a separation.json file with source audio hash, engine, model, and output stems
  • can immediately write a standard stem manifest with --manifest

This is the right precursor for both stem-manifest workflows and better per-stem transcription.

6. Generate With a Research Dossier

ableton-composer research genre "early 80s synth-pop" \
  --out research/synth-pop-80s.json

ableton-composer palette generate research/synth-pop-80s.json \
  --tracks "Drums,Bass,Pad,Lead,Keys,Vocals,FX" \
  --historical-strictness loose

ableton-composer generate "melancholic pop pulse with restrained hooks" \
  --dossier research/synth-pop-80s.json \
  --palette palettes/early-80s-synth-pop-palette.json \
  --historical-strictness loose \
  --tracks "Drums,Bass,Pad,Lead,Keys,Vocals,FX" \
  --provider openai

Use this when you want historically informed arrangement and production guardrails without depending only on vague prompt wording. Dossiers are additive: they work alongside style profiles instead of replacing them. The optional operational palette turns dossier guidance into concrete per-track constraints before note generation.

Research dossiers can now carry explicit historical guardrails too, for example period bounds, caution instruments, avoid-by-default lists, and historically plausible substitutes. Those guardrails are passed into generation as advisory constraints so the model can avoid obvious anachronisms by default.

If you want the model to stay much closer to the target era, switch to --historical-strictness strict. Use hybrid or modern when the goal is reinterpretation rather than reconstruction.

7. Build a Local Plugin Inventory

ableton-composer plugins scan
ableton-composer plugins enrich
ableton-composer plugins match research/synth-pop-80s.json
ableton-composer plugins scan --formats au,vst3,clap
ableton-composer plugins list

Use this before any plugin-aware preset or research workflow. The inventory is local, scans common macOS plugin folders for AU/VST/VST3/CLAP packages, and stores a structured JSON file that later commands can consume without scraping the filesystem directly.

The default list view is prompt-safe:

  • it prints plugin name, format, inferred type, install scope, and a path hash
  • it does not print raw filesystem paths unless you explicitly ask for --no-prompt-safe
  • missing plugin directories are treated as normal and do not fail the scan

Use plugins enrich when you want the inventory to carry historical/emulation metadata, and plugins match <dossier> when you want dossier-aware buckets such as:

  • recommended installed substitutes
  • caution choices that are usable but slightly off-period
  • avoid-by-default choices that conflict with dossier guardrails

8. Plan Presets From a Dossier

ableton-composer preset plan research/synth-pop-80s.json \
  --palette palettes/early-80s-synth-pop-palette.json \
  --installed-only

Use this when you want dossier and palette guidance to drive actual preset work. The preset plan:

  • maps each role to candidate preset profiles under profiles/presets/
  • prefers installed devices confirmed by the local plugin inventory when possible
  • generates a ready-to-use prompt per role
  • warns when the best available candidate is weak, off-period, or not confirmed as installed

The intended next step is to pick one recommended profile and pass its prompt into preset generate.

9. Generate a Preset

ableton-composer preset generate \
  profiles/presets/generic-analog-poly/bass.json \
  "deep analog bass" \
  --provider openai

This uses a preset profile plus preset-generate.md to create a structured parameter map.

10. Expand an Existing Set

ableton-composer expand sets/my-song \
  --add "Strings,FX" \
  --provider openai

Useful when you already have a harmonic structure and only want new supporting parts.

11. Import MusicXML With Chord Symbols

ableton-composer import-xml score.mxl \
  --chord-track \
  --out sets/imported-score/

When the MusicXML/MXL file contains harmony symbols, the importer stores them as section-level harmony metadata. With --chord-track, it also creates a MIDI Chords track and names the chord clip from the imported progression.

When the source file contains lyrics, the importer preserves them as section/clip metadata. Unpitched percussion parts are imported through MusicXML midi-unpitched mappings when available.

Use a custom track name when your Ableton set already has a dedicated harmony track:

ableton-composer import-xml score.mxl \
  --chord-track "Harmony" \
  --out sets/imported-score/

12. Export a Set Back to MusicXML / MXL

ableton-composer export-xml sets/imported-score \
  --out exports/imported-score.musicxml

ableton-composer export-xml sets/imported-score \
  --out exports/imported-score.mxl

This is the inverse interoperability path for MuseScore, Logic, and other notation-aware tools. The exporter:

  • concatenates sections into one score timeline
  • writes one part per track
  • includes harmony symbols and lyrics when present
  • packages compressed .mxl output when requested

13. Export a Set as MIDI for DAW Interoperability

ableton-composer export-midi sets/imported-score \
  --out exports/imported-score.mid

Use MIDI export when the target is a DAW rather than notation software. The exporter:

  • writes one MIDI track per AbletonSong track
  • preserves track names
  • preserves tempo and time signature
  • concatenates section-relative notes into one absolute song timeline

14. Validate a Round-Trip

ableton-composer validate-roundtrip examples/ableton-song/chord-progression.song.json --via midi
ableton-composer validate-roundtrip examples/ableton-song/chord-progression.song.json --via musicxml

Use this when you want to measure what is preserved across interchange formats. The report highlights:

  • note match percentage
  • track-name overlap
  • BPM and time-signature preservation
  • section-count drift
  • pitch/timing/duration mismatches

15. Critique a Generated Set

ableton-composer critique sets/my-song \
  --rubric general \
  --provider openai \
  --out reports/my-song-critique.json

Use this when you want structured feedback before revising a piece. The critique is advisory rather than objective and can help identify:

  • structural weaknesses
  • role-balance problems
  • idiomatic issues for a target instrumentation
  • weak contrast or continuity between sections

Rubrics are file-based under prompts/critique/, so extending the system is mostly a prompt-authoring task rather than a code change.

If you want critique automatically after generation:

ableton-composer generate "moody electronic sketch with restrained hooks" \
  --style profiles/albums/example-artist/midnight-signals/bundle.json \
  --tracks "Bass,Drums,Pad,Lead,Chords,FX" \
  --provider openai \
  --sections 4 \
  --chunk-size 2 \
  --evaluate \
  --rubric auto

16. Compare Drift

ableton-composer compare \
  profiles/albums/example-artist/midnight-signals/bundle.json \
  sets/my-generated-song

This reports:

  • component scores for key, BPM, structure, role presence, and rhythm
  • key agreement
  • BPM drift
  • rhythm by role
  • role presence drift

When the source is an album, artist, or collection bundle, compare weights role presence, structure, and role-level rhythm more heavily than exact track-name matches.

17. Scan a Stem Folder

ableton-composer stems scan /path/to/song-stems \
  --out stems/manifests/song-stems.stems.json

This creates a versioned stem manifest with:

  • source root
  • relative audio file paths
  • default track names derived from filenames
  • deterministic role, group, and color classification for common stem names
  • default display_name and order fields for stable organization
  • preserved manual overrides when rescanning into the same manifest

Use this as the first step before building audio-track setup and Ableton stem loading workflows.

18. Prepare Ableton Audio Tracks From a Stem Manifest

ableton-composer stems setup stems/manifests/song-stems.stems.json

Use this after scanning/classifying stems and before actual audio clip loading. The setup step:

  • creates missing audio tracks
  • reuses tracks when the manifest name already exists
  • applies track colors from the manifest when possible

Preview only:

ableton-composer stems setup stems/manifests/song-stems.stems.json --dry-run
ableton-composer stems setup stems/manifests/song-stems.stems.json --prefix-groups

You can also edit display_name and order in the manifest directly when you want to override the default grouping/order rules without changing the source filenames.

Current limitation: the Ableton remote API exposed through ableton-js can create and reuse tracks and inspect existing clips, but it does not currently expose a supported way to import arbitrary external audio files into Session View clip slots. So this step prepares the Live set structure; loading the actual stem audio into clips still needs manual drag-and-drop in Ableton or the REAPER import workflow below.

19. Prepare a REAPER Import Script From a Stem Manifest

ableton-composer stems reaper stems/manifests/song-stems.stems.json \
  --bpm 120 \
  --time-signature 4/4

Use this when the next step is comping, editing, or mixing in REAPER rather than Ableton. The generated Lua script:

  • creates one track per stem and imports the audio file at timeline start
  • optionally groups tracks into REAPER folder tracks by stem group
  • applies track colors derived from the stem manifest
  • sets the target project tempo and time signature before import

Run the generated .lua file from REAPER’s action list or script editor.

20. Generate a Portable Audio Render Plan

ableton-composer render-plan sets/my-song \
  --stems stems/manifests/my-song.stems.json \
  --out renders/plans/my-song.render-chain.json

Use this before implementing or invoking any offline audio engine. The render plan:

  • maps song tracks to source types such as MIDI or external stems
  • separates instrument placeholders from effect chains and mix settings
  • defines per-track stem outputs plus a master chain and final mixdown target
  • stays portable across future engines such as ffmpeg fallback or Pedalboard

21. Mix Existing Audio With ffmpeg Fallback

ableton-composer render-audio renders/plans/my-song.render-chain.json --dry-run
ableton-composer render-audio renders/plans/my-song.render-chain.json --normalize
ableton-composer convert-audio renders/my-song/mixdown.wav --out renders/my-song/mixdown.mp3

Use this when audio already exists as stems and you only need format conversion, simple summing, gain/pan application, or normalization. ffmpeg here is not a plugin host and does not render instruments from MIDI.

22. Process Existing Stems With Pedalboard

ableton-composer render-stems renders/plans/my-song.render-chain.json --dry-run
ableton-composer render-stems renders/plans/my-song.render-chain.json --out renders/my-song/pedalboard/

Use this when a render plan already points at external audio stems and you want an optional offline Python worker to process them. The current Pedalboard integration is intentionally narrow:

  • it requires Python plus the pedalboard package installed separately
  • it currently handles external audio stems only
  • it does not synthesize MIDI tracks or emulate a DAW mixer/project renderer
  • it writes per-track outputs using the same render-plan contract as the ffmpeg fallback

23. Typical Album-Style Loop

# analyze
ableton-composer analyze sets/source-album --scope album --artist "Artist" --album "Album"

# generate
ableton-composer generate "prompt" \
  --style profiles/albums/artist/album/bundle.json \
  --tracks "Bass,Drums,Pad,Lead,Chords,FX" \
  --provider openai \
  --sections 4 \
  --chunk-size 2

# compare
ableton-composer compare \
  profiles/albums/artist/album/bundle.json \
  sets/generated-output

24. Export for Logic Pro

ableton-composer export-midi sets/my-song --target logic
ableton-composer export-xml sets/my-song --target logic

Use this when the next step is arranging or scoring in Logic Pro rather than round-tripping back into Ableton. The Logic target preset:

  • prefixes part and track names with stable import order
  • adds MIDI section markers from set section names
  • writes MIDI key signature metadata when meta.scale is a simple major/minor key
  • reserves channel 10 for drum-like tracks during MIDI export

25. Generate a Static Song Report

ableton-composer report sets/example --out reports/example-report.md
ableton-composer report sets/example --out docs/content/reports/example-report.md

Use this when you want a lightweight inspection page for demos, thesis material, or internal review. The report includes:

  • metadata snapshot for BPM, scale, signature, sections, tracks, and notes
  • section timeline SVG
  • energy curve SVG
  • section, track, and role presence tables
  • density summaries derived from notes per bar

When saved under docs/content/, the generated Markdown becomes part of the Minuto docs build automatically.

26. Export MIDI for REAPER

ableton-composer export-midi sets/my-song --target reaper

Use this when the next step is arranging or editing MIDI directly in REAPER. The REAPER target preset:

  • keeps original track names instead of renaming them for score import order
  • adds MIDI section markers from set section names
  • reserves channel 10 for drum-like tracks during MIDI export
  • writes to exports/<name>-reaper.mid unless you override --out

27. Build an Evaluation Pack for Thesis or User Studies

ableton-composer evaluation-pack \
  sets/generated-a \
  sets/generated-b \
  --reference profiles/albums/example-artist/midnight-signals/bundle.json \
  --roundtrip midi,musicxml \
  --out reports/session-01

Add critique when you want qualitative feedback in the same bundle:

ableton-composer evaluation-pack \
  sets/generated-a \
  --reference profiles/albums/example-artist/midnight-signals/bundle.json \
  --roundtrip midi \
  --critique \
  --rubric auto \
  --provider openai \
  --out reports/session-02

The command writes:

  • evaluation-pack.json with structured per-target results
  • README.md with a quick human-readable summary

This is the intended bridge between generation, compare, critique, and interoperability validation when you need repeatable evaluation artifacts.

29. Revise From Critique

ableton-composer critique sets/my-song --rubric auto --out reports/my-song.critique.json

ableton-composer revise sets/my-song \
  --critique reports/my-song.critique.json \
  --provider openai \
  --out sets/my-song-revised/

Use this when the first symbolic generation is structurally promising but needs a second pass guided by explicit critique. The revision workflow:

  • keeps the process in the symbolic domain instead of re-entering audio transcription
  • reuses strengths from the original set where possible
  • turns critique findings and suggested revisions into a fresh full AbletonSong output
  • is a natural bridge between generate, critique, and later push

Format Versioning

New full AbletonSong JSON outputs include a format marker:

{
  "_format": {
    "name": "AbletonSong",
    "version": "0.3"
  },
  "meta": {},
  "sections": []
}

Set directories store the same marker in meta.json; loaders lift it back to the full-song level. Older unversioned files still load normally and are upgraded to the current marker the next time they are saved by a command.

Notation Metadata Layer

MusicXML-oriented workflows can now persist an optional notation layer without affecting Ableton push. Typical locations are:

  • meta.notation for key/time signature details from MusicXML
  • section.notation for original measure bounds
  • track.notation for part ids, source names, and clef hints
  • note.notation for pitch spelling, note type, voice/staff, ties, and unpitched percussion display data

This keeps the core format MIDI-friendly while allowing better MusicXML export and future notation-aware features.

Provenance Metadata

New generated and imported songs also include optional meta.provenance metadata. This is reproducibility context, not musical content, and Ableton push ignores it.

Typical fields include:

  • source_type, such as generated, imported-musicxml, imported-midi, or pulled-ableton
  • source_path and source_format for imports
  • provider, model, prompt_summary, and prompt_hash for AI generation
  • style_profile when generation used a profile bundle
  • transforms, a lightweight history of operations such as generate, import-xml, expand, split, or compile

Older files without provenance still load normally. Commands that save the song again can add or append provenance history where practical.

Example Corpus

The repository includes a small synthetic corpus under examples/ for repeatable demos and smoke tests:

  • examples/ableton-song/*.song.json for direct analysis and visualization tests
  • examples/musicxml/simple-harmony-lyrics.musicxml for MusicXML harmony/lyrics import tests
  • examples/midi/simple-melody.mid for MIDI import tests

Example commands:

ableton-composer analyze examples/ableton-song/multi-section-song.song.json \
  --scope song \
  --print

ableton-composer import-xml examples/musicxml/simple-harmony-lyrics.musicxml \
  --chord-track \
  --out /tmp/ac-simple-xml/

ableton-composer import-midi examples/midi/simple-melody.mid \
  --out /tmp/ac-simple-midi/
Edit this page