Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Your first song

This page takes you from a fresh install to a song you made and changed yourself, in about ten minutes. It assumes you have followed Install and have the claudius command.

Check the installation

claudius doctor

claudius 0.1.0 (macos aarch64)
  ok  web studio      ~/.local/share/claudius/web
  ok  sample packs    14 default packs (1.2 GB) in ~/Library/Application Support/claudius/packs
  ok  ears            models in ~/.cache/earshot-rs
  ok  Apple Loops     14096 loops and samples
  ok  ffmpeg          9.0.2 (writes song.mp3)
  ok  port 7878       free
  ..  Claude Desktop  not connected: `claudius connect claude-desktop`
  ..  Cursor          not connected: `claudius connect cursor`
  ..  statistics      off (`claudius telemetry` explains them)

Everything claudius needs is here.

Two things matter for this page: the sample packs (recorded instruments and drum machines) and the ears (the listening models the critic uses). If either is missing, claudius setup downloads them: about 2.2 GB of packs (1.2 GB once unpacked) and 0.8 GB of models, once. Apple Loops are optional (claudius uses them when GarageBand or Logic content is installed), and without ffmpeg you get song.wav but no song.mp3.

Make a song

claudius make --genre house --seed 9

claudius composes a song in the style, arranges it, renders it with real sounds, mixes and masters it, and judges the result. On this machine it printed:

ears loaded in 3.5 s
Crimson Tide — house at 124 BPM in G dorian, 64 bars (2:04)
  progression A: i7 ii7 i7 IV7
  progression B: i7 VIImaj7 i7 IV7
  form: intro 8 | groove 16 | break 8 | drop 24 | outro 8
  tracks: kick (sampled bd (tr909:bd)), clap (sampled cp (tr909:cp)), hat (sampled hh (tr909:hh)), ohat (sampled oh (tr909:oh)), shaker (shaker cut from 'Cosmic Harmony Shaker' (Apple Loops)), perc (sampled rim (tr909:rim)), bass (synth patch 'saw_bass'), chords (synth patch 'stab'), pad (synth patch 'warm_pad'), lead (synth patch 'pluck'), arp (synth patch 'bell'), crash (synth crash), riser (synth riser), impact (synth impact), downlifter (synth downlifter), reverse_crash (synth reverse_crash)
  master: -10.0 LUFS, true peak -1.0 dBTP (pre-master -9.3 LUFS); done in 24.2 s
  ears: 'house music' z +3.2 (closest confusion 'techno music' +3.7); production z +1.6 vs 'a low quality recording with hiss' +1.7; p_real 0.74
        sounds like: techno music, drum and bass music, tech house music, house music
  verdict: 84/100 (arc 0.92, genre 0.58, mix 1.00, production 0.47, theory 1.00). Fix first: sounds about as much like a hissy recording as a professional mix: noise-built sounds (hats, shakers, risers) and long reverbs are the usual cause; sounds more like 'techno music' than 'house music'
  wrote out/house-crimson-tide-9/song.mp3

The same genre and seed give the same song on any machine. What is installed changes only which recordings play: without Apple Loops, the shaker cut from them is synthesized, and without the sample packs so are the 909 drums, but the notes and drum patterns stay the same. Leave out --seed and you get a new song each time.

Open out/house-crimson-tide-9/song.mp3 and listen. Reading the summary while it plays:

  • Crimson Tide: the title the generator chose, the style, tempo, key and length.
  • progression: the chord sequences, as Roman numerals (what those are).
  • form: the sections and their lengths in bars. The drop is the loud part in the middle.
  • tracks: every part and the sound playing it: a real Roland TR-909 for most of the drums, synthesizers for bass, chords, pad, lead and arpeggio, and the transition effects at the end.
  • master: how loud the finished song is, in LUFS (the loudness measure streaming services use), and its highest peak. claudius masters a song to the loudness its style usually has.
  • ears and sounds like: what the listening models hear. The first reading is how clearly the song sounds like house next to the style it is most often taken for, here techno (2.5 is a plausible reading, 3 a strong one); the second compares “professionally mixed” with the closest of six typical flaws. p_real is the models’ guess that this is a real recording, reported and not scored. These are a machine’s impressions: hints, not rules.
  • verdict: the critic’s score out of 100, and the issues that cost the most, each with where it usually comes from. This song sounds about as much like a hissy recording as a professional mix, and a little more like techno than house. Listening, judging, finishing explains every part of it.

The folder holds the song (song.mp3, and song.wav in 24-bit), the song’s full description (blueprint.json) and the same song as a script (song.rhai), the arranged timeline (project.json), the critic’s report (verdict.json), a summary of the render with every track’s loudness (report.json) and credits for the recorded instruments whose licences ask for them (credits.txt).

Change it

A script can edit a saved song. Make a file called edit.rhai:

tempo(122);
part("chords", #{ preset: "piano" });
mix("lead", #{ level: -2, reverb: 0.35 });
section("drop", #{ bars: 32 });

It slows the song down a little, plays the chords on a sampled grand piano instead of a synth stab, pulls the lead back and into more reverb, and makes the drop 32 bars long. Run it on the song:

claudius script edit.rhai --on out/house-crimson-tide-9

ears loaded in 6.2 s
Crimson Tide — house at 122 BPM in G dorian, 72 bars (2:22)
  progression A: i7 ii7 i7 IV7
  progression B: i7 VIImaj7 i7 IV7
  form: intro 8 | groove 16 | break 8 | drop 32 | outro 8
  tracks: kick (sampled bd (tr909:bd)), clap (sampled cp (tr909:cp)), hat (sampled hh (tr909:hh)), ohat (sampled oh (tr909:oh)), shaker (shaker cut from 'Cosmic Harmony Shaker' (Apple Loops)), perc (sampled rim (tr909:rim)), bass (synth patch 'saw_bass'), chords (sampled piano (salamander:piano)), pad (synth patch 'warm_pad'), lead (synth patch 'pluck'), arp (synth patch 'bell'), crash (synth crash), riser (synth riser), impact (synth impact), downlifter (synth downlifter), reverse_crash (synth reverse_crash)
  master: -10.1 LUFS, true peak -1.0 dBTP (pre-master -9.3 LUFS); done in 22.4 s
  ears: 'house music' z +3.4 (closest confusion 'techno music' +3.7); production z +1.6 vs 'a low quality recording with hiss' +1.6; p_real 0.75
        sounds like: techno music, tech house music, house music, drum and bass music
  verdict: 85/100 (arc 0.92, genre 0.63, mix 1.00, production 0.49, theory 1.00). Fix first: sounds about as much like a hissy recording as a professional mix: noise-built sounds (hats, shakers, risers) and long reverbs are the usual cause; sounds more like 'techno music' than 'house music'
  wrote out/house-crimson-tide-9/song.mp3

Everything you did not name stayed as it was. The chords are now sampled piano, the song is 72 bars, and the score moved a point: the critic is a guide, and your ears decide whether the piano is better.

The edited song is written back into the same folder, because its genre, title and seed are the same, so the original files are replaced. To keep both, add title("Crimson Tide (piano)") to the script, or pass --out another-folder.

Read the song as a script

Every song can be written as a script that describes it completely enough to edit, and the folder already has one: song.rhai. An empty script changes nothing, so this prints the same script for any song:

echo "" | claudius script - --on out/house-crimson-tide-9 --print

out/house-crimson-tide-9/song.rhai starts like this:

// Crimson Tide — house (seed 9)
// song("house", 9);   // uncomment to start over from the generator
title("Crimson Tide"); tempo(122); key("G dorian"); swing(0.5257842);
humanize(0.25);
prog("A", "i7 ii7 i7 IV7");
prog("B", "i7 VIImaj7 i7 IV7");
bars_per_chord(1);
master(#{ lufs: -10, ceiling: -1 });

// drums: X accent, x hit, o ghost, . rest, | bar line; 16 steps per bar unless a number follows
drum("kick", "main", "X...X...X...X...");
drum("kick", "sparse", "X...X...X...X...");
drum_sound("kick", "tr909:bd");

and goes on with every drum lane and the sound it plays, every part, the form and the mix. Copy any line into your edit.rhai, change it, and run the script again. Songs as scripts explains the format.

Make a beat from nothing

blank() starts an empty song instead of a generated one. Save this as beat.rhai:

blank("house");
tempo(124); key("A minor");
prog("A", "Am7 Fmaj7 Dm7 Em7"); bars_per_chord(1);
track("drums", s("bd*4, [~ cp]*2, [~ hh]*4"));
track("bass",  chord("prog").root().struct("~ x ~ x ~ x ~ [x x]").s("organ_bass").legato(0.7));
track("keys",  chord("prog").struct("x ~ ~ x ~ ~ x ~").s("epiano").room(0.25));
form([sec("intro", 8, "drums keys").filter_in(), sec("drop", 16, "*").impact()]);

and render it with claudius script beat.rhai. You hear eight bars of drums with electric piano chords coming into focus as a filter opens on them, then a crash and sixteen bars with an organ bass bouncing between the kicks on the root of each chord. Each line is one idea: the style, the tempo and key, the chords, three tracks, and two sections.

Where to go from here

  • Never made music before? How a track is built starts a short course that ends with a song you understand, line by line.
  • Already make music? claudius for DAW users maps what you know onto claudius.
  • The studio is the same engine in a window: an arrangement view, a step sequencer, a mixer and the verdict updating as you edit.
  • Working with an assistant: claudius connect claude-desktop (or claude-code, cursor) lets an assistant make and edit songs while you listen.
  • The cookbook has complete songs in eight styles.