Command line

The choruspop tool makes songs and versions, exports them and follows jobs, from any shell. It ships inside the direct download of ChorusPop.

Install

In ChorusPop, choose ChorusPop ▸ Install Command-Line Tool. It links the tool into /usr/local/bin if you can write there, otherwise ~/.local/bin. If that one isn't on your PATH yet:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && exec zsh
choruspop version

The tool itself lives at /Applications/ChorusPop.app/Contents/Helpers/choruspop and updates with the app. You don't need ChorusPop open: the tool opens it in the background, without taking focus, and waits for it.

Examples

# Make a song: waits, shows progress, writes the file here
choruspop make "[verse]
Neon on the river
Lights across the bay
[chorus]
Turn it up" --genre synthwave --mood dreamy --voice female --length 0:30

# Lyrics from a file (or - for stdin), a style line, into an album, as FLAC
choruspop make --lyrics-file song.txt --style "indie chill acoustic guitar male vocal" \
  --title "Harbor Lights" --album "Summer" --length 2:30 --format flac --out ~/Desktop/

# The same song again: same seed, same inputs
choruspop make --lyrics-file song.txt --genre folk --seed 1234

# In an exact key (a key in --style isn't followed)
choruspop make --lyrics-file song.txt --genre pop --key "D minor"

# From a plan: an ABC plan, or a MIDI file with the tracks you pick
choruspop make --lyrics-file song.txt --plan song.abc
choruspop tracks song.mid
choruspop make --lyrics-file song.txt --midi song.mid --roles voice=1,lead=5,harmony=2+3

# No singing (experimental: some seeds still sing)
choruspop make --instrumental --genre lofi --mood chill --length 1:00

# Versions of the newest song
choruspop strip latest --remove-vocals
choruspop strip latest --stems --format flac --out ~/Desktop/

# Export what's already made
choruspop export "Harbor Lights" --version instrumental --format alac --out ~/Desktop/
choruspop export latest --music --lrc          # to ~/Music/ChorusPop, with synced lyrics

# Find songs
choruspop list neon --limit 5
choruspop show latest                          # with the key, tempo and metre of its plan

# Queue now, follow later
job=$(choruspop make --lyrics-file song.txt --no-wait)
choruspop status "$job" --wait --timeout 900
choruspop status                               # everything being made
choruspop cancel "$job"

A SONG is its id, the first 6 or more characters of the id, its exact title, or latest. Job ids for songs become the song's id once it's done; version jobs are <song id>#instrumental, #vocals or #stems.

Keys

The model doesn't follow a key named in the style. With --key it writes its plan (tempo, key, chords, melody) first, the plan is moved to that key the nearest way (up to 6 semitones, every part by the same interval), and the song is sung from it, so the key is exact. A key can be written "D minor", Dm, "F# major", "B flat minor" or Ebm. Moving can't change a mode: a plan in a major key asked for a minor one (or the reverse) goes to the key with the same signature, so asking for D minor can give F major. choruspop show SONG says which key it is in.

From a plan

--plan FILE sings an ABC plan instead of one the model writes; --midi FILE turns a MIDI file into a plan as ChorusPop's Import MIDI does. Lyrics are optional with either: given, they're sung to the plan's Vocal line, one syllable per note. The song is made at least as long as the plan.

• A plan is ABC in the model's dialect: the header X, T, M, L, Q, the voices V: Vocal then V: Ins, then K; under each % section, one phrase per voice with full bars. A song's own plan (the plan_path of show --json) is a good place to start. Write the Vocal line an octave above the pitch you want: the model sings it an octave lower.
• choruspop tracks FILE.mid lists a MIDI file's tracks and the role each gets. Change them with --roles voice=N,lead=N,harmony=N+N: the voice is sung, the lead is the instrument line, the harmony tracks give the chords.
• A plan that isn't valid is refused with the line that's wrong (exit 1, invalid).

Instrumentals

--instrumental makes a song with no singing: the model's plan (or yours) with its Vocal line silenced and the tune moved to the band. Leave the lyrics out. It's experimental: on some seeds the song still sings, which is why ChorusPop itself doesn't offer it yet.

Waiting and progress

make and strip wait for the job by default. Progress goes to stderr (one updating line in a terminal, a line per 10% otherwise), and the paths of the files written go to stdout, so file=$(choruspop make …) captures the path.

• --no-wait prints the job id and returns at once.
• --timeout SEC stops waiting after SEC seconds and exits 4; the job keeps going.
• ^C stops waiting too. ChorusPop keeps making the song; choruspop status shows it, choruspop cancel JOB stops it.

When a command stops waiting (--timeout, ^C, or --no-wait with --out or --music), the files still go where it asked once the job is done: to the Music folder, or to --out (the current folder by default), moved there by the tool in the background or by the next choruspop command you run.

Songs are made one at a time. Starting several queues them; they don't run side by side. Versions (strip) wait for every song queued or being made: songs go first.

--json output

Add --json (or -j) to any command for newline-delimited JSON on stdout: zero or more events, then exactly one result or error.

{"type":"progress","job":{"id":"8f3c…","kind":"song","status":"running","progress":0.42,"stage":"performing","title":"Neon River","eta_seconds":48,"length_sec":30}}
{"type":"file","path":"/Users/me/Desktop/Neon River.flac","role":"song"}
{"type":"result","data":{"job":{"id":"8f3c…","kind":"song","status":"done","progress":1,"title":"Neon River","song_id":"8f3c…","length_sec":30},"files":["/Users/me/Desktop/Neon River.flac"]}}

{"type":"error","code":"queue_full","message":"The queue is full (10 songs)."}

Job

Song

App

# The newest song's id and seed
choruspop list --limit 1 --json | jq -r '.data.songs[0] | "\(.id) \(.seed)"'

# Make a song and keep only its path
path=$(choruspop make --lyrics-file song.txt --json | jq -r 'select(.type=="result") | .data.files[0]')

Exit status

Error codes

With --json an error is {"type":"error","code":…,"message":…}; without it, the message goes to stderr.

A batch from a folder of lyrics

# One song per .txt file, queued without waiting, then collected in order.
# The app makes them one at a time.
for f in lyrics/*.txt; do
  choruspop make --lyrics-file "$f" --title "$(basename "$f" .txt)" \
    --genre pop --length 1:00 --album "Demo tape" --no-wait
done > jobs.txt

mkdir -p out
while read -r job; do
  choruspop status "$job" --wait --timeout 1800 && choruspop export "$job" --format flac --out out/
done < jobs.txt

The queue holds 10 songs; a longer batch gets queue_full for the rest. Queue the next one when one finishes, as the Python example does.

Commands

choruspop — make songs with ChorusPop on this Mac.

Usage:
  choruspop make LYRICS [options]        make a song (waits, then writes the file here)
  choruspop make --plan song.abc | --midi song.mid [LYRICS] [options]
  choruspop tracks song.mid              a MIDI file's tracks and the roles make --midi gives them
  choruspop strip SONG --remove-vocals | --vocals-only | --stems
  choruspop export SONG [--format flac] [--version instrumental] [--out PATH | --music]
  choruspop list [SEARCH] [--album NAME] [--limit N]
  choruspop show SONG
  choruspop status [JOB] [--wait] [--timeout SEC]
  choruspop cancel JOB
  choruspop version
  choruspop mcp                           run as an MCP server over stdio

SONG is an id, the start of one, a title, or "latest".
Add --json to any command for newline-delimited JSON on stdout.
Run `choruspop help COMMAND` for its options.

choruspop make LYRICS [options]
choruspop make --lyrics-file song.txt [options]      (- reads stdin)
choruspop make --plan song.abc [LYRICS] [options]
choruspop make --midi song.mid [--roles voice=1,lead=5,harmony=2+3] [LYRICS] [options]
choruspop make --instrumental [options]

choruspop tracks FILE.mid

choruspop strip SONG --remove-vocals | --vocals-only | --stems [options]

choruspop export SONG [options]

choruspop list [SEARCH] [--album NAME] [--limit N]

choruspop show SONG

choruspop status                 everything being made
choruspop status JOB [--wait] [--timeout SEC]

choruspop cancel JOB

choruspop version

choruspop mcp

Environment