claudius

claudius makes music the way a producer does in a DAW. It picks sounds, writes drum patterns, bass lines, chords and melodies with music theory, arranges them into a song with an intro, builds and drops, mixes and masters it, listens to the result, and changes what it does not like.

Every sound is real audio. There is no neural audio generation and no General MIDI: drums and synths are synthesized in code, and the rest comes from recordings (a grand piano, a Rhodes, string sections, real TR-808 and TR-909 drum machines, Apple Loops if you have GarageBand, or your own files). Notes exist only as the score that plays those sounds, like a piano roll.

After every change claudius judges the song: is it loud enough and clean at the top, does the drop hit harder than the breakdown, are the bass notes on the chords, does it sound like the genre it claims to be? Each problem comes with what to change.

Four ways to use it

• The studio. An app with an arrangement view, step sequencer, mixer, harmony editor and script editor. It runs as a native window and in the browser. See the studio.
• Scripts. A small language in which a song is a few lines of code: track("drums", s("bd*4, [~ cp]*2")). Any song claudius makes can be printed as a script. See the language reference.
• An assistant. Connect Claude, ChatGPT or Cursor and ask for a song; it composes, listens, and revises while you hear every change in the studio. See working with an assistant.
• The command line. claudius make --genre lofi writes a finished song to a folder. See command line.

Where to start

• You have never made music. Install it, make your first song, then follow how a track is built. The chapters explain every term as it comes up and give you something to listen to on every page.
• You make music already. Read claudius for DAW users and keep the quick reference open. If you know Strudel or TidalCycles, start with coming from Strudel.
• You want to work on claudius. Start with a tour of the repository and the architecture.

Install

The Mac app

Paste this into Terminal:

curl -fsSL https://github.com/devlato/claudius/releases/latest/download/install.sh | sh

It installs Claudius into Applications, and its command-line programs into ~/.local/bin. It runs on Macs with Apple silicon or Intel and macOS 11 or later, and opening it opens the studio.

You can also download the disk image for your Mac from the latest release: claudius-<version>-aarch64-apple-darwin.dmg for Apple silicon, claudius-<version>-x86_64-apple-darwin.dmg for Intel (the Apple menu, About This Mac, says which you have). Open it, and drag Claudius onto Applications. Until the releases are signed with an Apple Developer ID, though, macOS refuses an app downloaded in a browser the first time: ““Claudius” Not Opened. Apple could not verify “Claudius” is free of malware”. Click Done, open System Settings, Privacy & Security, scroll down to the line about Claudius, and click Open Anyway. macOS asks once more, and then remembers. The command above avoids all this, because macOS checks only what a browser downloads, and curl is not one.

The first time the studio starts, it downloads its listening models by itself and offers to download the sample packs (below). To connect Claude, Cursor or Codex, use ?, Connect an assistant in the studio. Move the app into Applications first: an app opened from its disk image, or from Downloads, runs from a copy macOS takes away again, and claudius will not connect an assistant to it. The app holds the command-line programs too. The command above links them into ~/.local/bin; after dragging the app in yourself, link them like this to use them in a terminal:

mkdir -p ~/.local/bin
ln -s /Applications/Claudius.app/Contents/MacOS/Claudius ~/.local/bin/claudius
ln -s /Applications/Claudius.app/Contents/MacOS/claudius-packs ~/.local/bin/claudius-packs

Linux packages

Every release has packages for x86_64 and ARM64 Linux with glibc 2.38 or newer (Ubuntu 24.04, Debian 13, Fedora 39 and later). Each puts the programs in /usr/bin, the web studio in /usr/share/claudius/web, and Claudius in your desktop’s app menu, which opens the studio. Download the one for your system from the latest release:

sudo apt install ./claudius-<version>-x86_64-unknown-linux-gnu.deb    # Debian, Ubuntu
sudo dnf install ./claudius-<version>-x86_64-unknown-linux-gnu.rpm    # Fedora and its relatives

or the AppImage, which needs no installing: make it executable (chmod +x claudius-*.AppImage), then open it to start the studio, or run it with a command, ./claudius-<version>-x86_64-unknown-linux-gnu.AppImage make --genre lofi. It needs FUSE to run, as every AppImage does, and ALSA for the studio’s sound.

The command line: macOS and Linux

curl -fsSL https://github.com/devlato/claudius/releases/latest/download/install.sh | sh

The script comes with every release, next to the archives, and is in the release’s checksums. It downloads the latest release for your computer from GitHub, checks it against the published SHA-256 sums, and installs it. On Linux that is under ~/.local: the programs claudius and claudius-packs in ~/.local/bin, and the web studio in ~/.local/share/claudius/web. On a Mac it is the app, in /Applications (or ~/Applications when you cannot write to /Applications), with ~/.local/bin/claudius and claudius-packs as links into it; --no-app installs the programs and the web studio under ~/.local instead, as on Linux. It tells you if ~/.local/bin is not on your PATH yet.

When you run it in a terminal, it offers to download the sounds and the ears straight away (below). To do that without being asked, pass --yes:

curl -fsSL https://github.com/devlato/claudius/releases/latest/download/install.sh | sh -s -- --yes

Run as root, it installs the programs and leaves the downloads for later: the packs are archives from other sites, so run claudius setup as the user who makes the music.

CLAUDIUS_INSTALL_DIR puts the programs in another folder (the web studio goes next to it, in ../share/claudius/web), CLAUDIUS_APP_DIR puts the Mac app in another folder, and CLAUDIUS_VERSION=0.1.0 installs a specific release.

Windows

Windows is a preview: its build has no ears yet, so verdicts use meters and music theory.

Download claudius-<version>-x86_64-pc-windows-msvc.msi from the latest release and run it. It needs no administrator: it installs claudius for you in %LOCALAPPDATA%\Programs\claudius, adds its programs to your PATH, and puts Claudius in the Start menu, which opens the studio. The installer is not signed yet, so SmartScreen may say Windows protected your PC: click More info, then Run anyway. Settings, Apps, removes it again.

Or install the programs only, in PowerShell:

irm https://github.com/devlato/claudius/releases/latest/download/install.ps1 | iex

The sounds and the ears

The programs are small. The sounds and the listening models are downloaded once, when you agree to it:

claudius setup

The studio offers the same download of the packs when they are missing, and downloads the models by itself the first time it starts. Each model file is checked against a pinned SHA-256 hash. Without the packs, claudius synthesizes every sound; without the models, the verdict uses meters and music theory only. claudius setup --help lists the options, and claudius-packs list shows every pack with its licence.

claudius uses Apple Loops automatically when GarageBand or Logic content is installed. ffmpeg is optional: with it, songs are also saved as MP3.

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`
  ..  statistics      off (`claudius telemetry` explains them)

Everything claudius needs is here.

From source

You need Rust (the version in rust-toolchain.toml; rustup picks it up) and, for the web studio, trunk.

git clone https://github.com/devlato/claudius
cd claudius
cargo install --locked --path crates/claudius-cli
cargo install --locked --path crates/claudius-packs
cargo xtask web          # builds the web studio into crates/claudius-ui/dist
claudius setup

A claudius built from a checkout finds the web studio in that checkout. The development setup covers everything else.

Uninstall

The Mac app: drag Claudius from Applications to the Bin, and delete the links in ~/.local/bin (rm ~/.local/bin/claudius ~/.local/bin/claudius-packs). The command-line install:

rm ~/.local/bin/claudius ~/.local/bin/claudius-packs
rm -r ~/.local/share/claudius/web

The sample packs, the models and the caches are kept, so that reinstalling does not download them again. To remove them too, delete the packs folder claudius doctor shows (~/Library/Application Support/claudius/packs on macOS, ~/.local/share/claudius/packs on Linux), ~/.cache/earshot-rs, and ~/Library/Caches/claudius (~/.cache/claudius on Linux). Songs you saved stay in ~/Music/claudius.

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.

The studio

claudius studio

opens the studio in its own window. claudius serve runs the same studio in your browser at http://127.0.0.1:7878. Both are views of one session: you can have the window, a browser tab and an assistant working on the same song at once, and each sees the others’ changes as they happen.

Every change is rendered and judged in the background. The arrangement shows when the render you hear is older than the song, and the score badge in the toolbar updates when the new verdict arrives, a few seconds later.

The first time

The first time it opens, a short tour points at the parts of the studio in five cards: making a song, listening, the verdict, the editors, and connecting an assistant, with the Connect buttons right in the last card. The app then asks once whether to send anonymous usage statistics, which stay off unless you say yes (what they are). The tour never blocks the studio. Skip the tour or Esc ends it for good, and ? in the bottom right corner, Take the tour, starts it again.

The first time it starts, claudius downloads its listening models (about 0.8 GB) in the background; the verdict judges with meters and music theory until they are ready, and the log says when they are. If the default sample packs are not installed, the studio says so and offers Download the packs (a 2.2 GB download): until then, the sampled instruments are synthesized. The Sounds tab lists every pack, with a button for each one that is not installed.

Starting a song

New song asks for a genre and, if you like, a seed, tempo and key. The same genre and seed always give the same song, so a seed is a way to come back to one you liked. Open loads a song folder you saved or a .rhai script.

The panels

• Arrangement. The sections of the song from left to right (intro, build, drop and so on), and below them one row per track. Click a cell, or drag across cells, to switch a track on or off in those sections. Drag a section to move it; right-click it to duplicate, insert or remove one. The waveform of the latest render is underneath; click it to jump.
• Section. The selected section’s length, energy, drum variant, which chord progression it plays, and the switches for a build, a gap before the next section, an impact, drum fills, and a filter that opens over the section.
• Steps. A step sequencer for every drum track. Click a step to toggle it, drag to paint, shift-drag to set how hard a hit is.
• Parts. The bass, chords, pad, lead and arpeggio parts: their writing style, their sound (a synth or a sampled instrument), their range and how busy they are. Reseed rewrites a part.
• Mixer. Level, pan, reverb, delay and how much each track ducks under the kick; mute and solo; meters from the last render; the master’s loudness and true peak.
• Harmony. The chord progressions, as chords in the song’s key and as numerals, and which sections play which.
• Script. The whole song as a script. Edit it and press Cmd+Enter (Ctrl+Enter on Windows and Linux) to run it. The sound browser lists every drum, synth and instrument name.
• Verdict. The score and its parts, the issues with what to change, and what earshot hears.
• Log. What happened, and the song’s history.

Mutate tries a few variations and keeps the best one if it beats the current song; Evolve runs several generations of that. Both run in the background and can be stopped. Save writes the song folder.

Help and assistants

? in the bottom right corner opens the help menu: Take the tour, Connect an assistant, Check for updates and Update automatically and the switch for anonymous usage statistics (in the app), the documentation, and a form to report a problem. When a new release has been downloaded, a bar under the toolbar offers Restart to update (Updates). Connect an assistant lists Claude Desktop, Claude Code, Cursor and Codex, says which are connected, and connects one with a click, the way claudius connect does (Working with an assistant). The assistant then makes and edits the song open here, and you hear every change.

Keys

When something does not work

claudius doctor checks the installation. If the studio window opens but stays empty, the engine may not have started: claudius serve prints why. Troubleshooting has more.

Working with an assistant

claudius speaks MCP, the protocol assistants use for tools. Once it is connected, you can ask Claude, ChatGPT or Cursor for a song in plain words. The assistant writes a script or starts from a genre, listens through claudius’ critic, reads the issues, and revises, while you listen in the studio and steer.

From the studio

The studio connects them with a click: ? in the bottom right corner, then Connect an assistant (it is also under New song while no song is open). It lists Claude Desktop, Claude Code, Cursor and Codex, says which are connected, and Connect does what claudius connect below does, skills included. An assistant set up for another claudius (an older install, say) offers Use this app. Then restart the assistant, as it says. This is the way for the Mac app, the Windows installer and the Linux packages, whose claudius may not be on your PATH.

The web studio, a page in a browser, cannot change the settings of the apps on a computer, so it lists the commands to run instead.

Claude Desktop

claudius connect claude-desktop

Quit and reopen Claude Desktop. claudius now appears in the tools menu of a new chat. The command adds one entry to Claude’s configuration file and keeps a backup of the old one next to it; --remove takes it out again.

It also writes claudius’ skills as zips into ~/Music/claudius/skills/. Upload them in Claude’s settings, under Capabilities, and Claude uses them in Claude Desktop and on claude.ai.

Claude Code, Cursor and Codex

claudius connect claude-code
claudius connect cursor
claudius connect codex

Each adds the MCP server and installs the skills where that assistant reads them (~/.claude/skills/, ~/.cursor/skills/, ~/.codex/skills/). --no-skills leaves the skills out, and --remove takes both out again.

For any other client, claudius connect print shows the configuration to paste. Clients that can reach a URL can also connect over HTTP to a running studio: http://127.0.0.1:7878/mcp.

With the assistant’s own command

claudius is an ordinary MCP server: the assistant starts claudius mcp. So each assistant’s own way of adding a server works as well:

claude mcp add --scope user claudius -- claudius mcp    # Claude Code, in every project
codex mcp add claudius -- claudius mcp                  # Codex

Cursor adds it from a link: Add claudius to Cursor opens Cursor, which asks before it adds the server. Or put it in ~/.cursor/mcp.json yourself:

{ "mcpServers": { "claudius": { "command": "claudius", "args": ["mcp"] } } }

Claude Desktop has no command for it: in its Settings, choose Developer, then Edit Config, and add the same entry with the full path of claudius (which claudius prints it), since Claude Desktop does not see your shell’s PATH.

These find claudius on your PATH, where the installers put it. The Mac app dragged from its disk image leaves none there: use /Applications/Claudius.app/Contents/MacOS/Claudius in its place. claudius connect print prints every one of these with the full path of the claudius you run it with.

They add the MCP server only. The skills come with claudius connect; claudius skills --out <folder> writes them anywhere else, a folder each, to copy into ~/.claude/skills, ~/.codex/skills or ~/.cursor/skills.

Skills

The MCP tools give an assistant the controls; claudius’ skills give it the craft. They are short guides, in the Agent Skills format, that an assistant reads when the conversation turns to music:

• claudius-songs: how to make and edit a song: listen, read the verdict, change one thing, and say what changed in musical terms; the script language with recipes; a starting point for each genre.
• claudius-remix: analysing a recording, remaking its skeleton in another genre, chopping and flipping it.
• claudius-setup: installing claudius, connecting assistants, and fixing what goes wrong.

claudius connect installs them for Claude Code, Cursor and Codex, and writes zips for the Claude apps. claudius skills --out <folder> writes them anywhere else, for a project’s own .claude/skills/ folder, say. They are built into claudius, so they always match the version you have. For an assistant without skills, such as a ChatGPT project, claudius-songs/SKILL.md works as its instructions.

You and the assistant on the same song

Open the studio first (claudius studio). When the assistant starts claudius, it finds the studio already running and works on the song you have open, so every change it makes shows up in front of you, and you can change things yourself in between. Without a studio running, it starts a session of its own; open http://127.0.0.1:7878 to follow it.

What to ask

Be specific about what you want to hear, the way you would brief a producer:

• “Make a deep house track at 122 BPM in F minor. Keep the intro sparse and make the drop hit hard.”
• “The lead is too busy. Simplify it, and put a Rhodes on the chords instead of the synth.”
• “Listen to it and fix the critic’s two most serious issues. Tell me what you changed.”
• “Try five variations of the drums and keep the best one.”
• “Remake ~/Music/reference.mp3 as lofi.”

The assistant can undo anything it does, and so can you (Cmd+Z in the studio).

ChatGPT and other assistants in the cloud

These run on someone else’s computer, so they need a public address. Run claudius with a token behind a tunnel:

TOKEN=$(openssl rand -hex 16); echo "$TOKEN"
claudius serve --public --token "$TOKEN"
cloudflared tunnel --url http://127.0.0.1:7878

Then add a custom connector (in ChatGPT’s developer mode) with the URL https://<your tunnel>/mcp?token=<token>. A shared claudius only reads and writes files in ~/Music/claudius, its caches and the sound libraries; see the security model.

What the assistant can do

The MCP tools page lists every tool. In short: start, open and save songs; read the song and its script; run scripts; render and judge; mutate and evolve; analyze and remake audio files; undo and redo.

How a track is built

This course takes you from no music knowledge to a finished song you understand, one page at a time. Each page adds one layer to the same song, explains the musical idea behind it in plain words, and gives you something to listen to. You need claudius installed (see Install) and a text editor.

Listen first

Before writing anything, listen to a track claudius makes on its own:

claudius make --genre house --seed 9

It takes under a minute. When it finishes, it prints where it wrote the song; open the song.mp3 in that folder and listen with headphones if you have them. Then listen again and try to follow one sound at a time:

• the kick, the deep thump that comes four times in every count of four;
• the clap answering it on every second thump;
• the hi-hats, the short ticking sounds between the thumps;
• the bass, the low, round notes that move underneath;
• the chords, several notes played together, which give the music its mood;
• the melody, a single line of notes on top that you could hum;
• the pad, a soft, long sound that fills the background in the quieter parts.

Notice also that the song changes over time. It starts thin, fills up, drops to almost nothing in the middle, builds up with a rising sound, and comes back full. Those changes are sections.

Layers and sections

Almost every track in electronic music, and most pop, is built this way:

Notes and keys (Notes, scales and keys) come between drums and bass, because bass, chords and melody all need them. The last page, Listening, judging, finishing, is about hearing what is wrong and fixing it.

In claudius, a song is a set of tracks (one per layer, or more) and a list of sections, each saying which tracks play in it. You describe both in a script, a short text file, and claudius turns it into audio.

Your first script

Make a file called song.rhai with these two lines:

blank("house");
track("kick", s("bd*4"));

blank("house") starts an empty song. “House” is the style; it decides things you will meet later, like how the finished song is mixed. track("kick", s("bd*4")) adds a track called kick that plays the sound bd (bass drum) four times in every bar. You will learn what a bar is on the next page.

Render it:

claudius script song.rhai

claudius prints a summary and writes the song into a folder such as out/house-untitled-1/. Open song.mp3 there: eight bars of a steady kick drum, about fifteen seconds. That is the start of the song you will build. The studio does the same with no files at all: paste the script into its script tab (see The studio).

On every page, the code is the whole song so far, or a part of it you can add to your file. When a page shows something to try, change one thing, render, and listen to what changed.

Beats: tempo, bars and steps

Play the kick from the last page and tap along with it. Each tap is a beat: the steady pulse you would nod your head to. Everything in this page is about where sounds fall in relation to that pulse.

Tempo

How fast the beats come is the tempo, counted in beats per minute (BPM). Set it at the top of the script:

blank("house");
tempo(120);
track("kick", s("bd*4"));

At 120 BPM there are two beats every second. House music lives around 120 to 126 BPM, hip-hop around 85 to 95, drum and bass around 174. Try tempo(90) and tempo(160) and hear how much the same kick changes character.

Bars

Now count along with the kick: one, two, three, four, one, two, three, four. Each group of four beats is a bar. Musicians count in bars because almost everything in a song repeats in groups of four beats, and bigger ideas come in groups of 4, 8 or 16 bars.

In claudius, one pattern string is one bar. s("bd*4") means “fit four kicks into the bar”, one on each beat. s("bd bd bd bd") is the same thing written out: the words share the bar equally. A kick on every beat is called four on the floor, and it is the heartbeat of house and techno.

The backbeat

Add a clap. Listen for where it lands before reading the explanation:

blank("house");
tempo(120);
track("kick", s("bd*4"));
track("clap", s("~ cp ~ cp"));

The clap falls on beats two and four. ~ is a rest, a beat of silence, so "~ cp ~ cp" reads as rest, clap, rest, clap. Hits on two and four are called the backbeat, and you have heard it in nearly every pop, rock and dance song.

Between the beats

Each beat can be divided into smaller steps. Square brackets squeeze several sounds into one step:

blank("house");
tempo(120);
track("kick", s("bd*4"));
track("clap", s("~ cp ~ cp"));
track("hats", s("[~ hh]*4"));

[~ hh] is a rest and a hi-hat sharing one beat, so the hat lands exactly halfway between two kicks; *4 repeats that in all four beats. Count one AND two AND three AND four AND: the hats are on every AND, the offbeats. This “tss” between the thumps is what makes house sound like house.

The usual ways of dividing a beat:

Sixteen steps per bar are a common grid. Producers call each one a step, and talk about “a hit on step 5” (the second beat) or “a ghost note on step 8”.

A fuller groove

Add a shaker playing sixteen soft steps, so you can hear the grid filled in:

blank("house");
tempo(120);
track("kick",   s("bd*4"));
track("clap",   s("~ cp ~ cp"));
track("hats",   s("[~ hh]*4"));
track("shaker", s("sh*16").gain(0.4));

.gain(0.4) plays the shaker softly: gain is how hard each sound is hit, from 0 to 1. Soft, busy parts like this make a groove feel alive without getting in the way.

Swing

Straight sixteenth steps sound mechanical. Swing delays every second sixteenth a little, so the steps go long-short, long-short, the way a drummer’s hands do:

blank("house");
tempo(120);
swing(0.58);
track("kick",   s("bd*4"));
track("clap",   s("~ cp ~ cp"));
track("hats",   s("[~ hh]*4"));
track("shaker", s("sh*16").gain(0.4));

0.5 is straight; 0.66 is a full triplet swing. Listen to the shaker: at 0.58 it bounces. House usually swings a little (0.52 to 0.56), lofi hip-hop a lot (0.58 to 0.62).

Try this

• Make the kick play only on beats one and three: s("bd ~ bd ~"). The groove relaxes into half the energy.
• Add a kick on the very last sixteenth of the bar, a little push into the next bar: s("bd bd bd [bd ~ ~ bd]"). The last beat is split into four sixteenths, and the extra kick sits on the fourth.
• Replace the hats with eight-per-bar hats, s("hh*8"), and hear how the feel gets busier.
• Play the drums on a real drum machine, the Roland TR-909 used on countless house records (this needs the sample packs, which claudius setup installs):

blank("house");
tempo(120);
track("kick", s("bd*4").bank("tr909"));
track("clap", s("~ cp ~ cp").bank("tr909"));
track("hats", s("[~ hh]*4").bank("tr909"));

The song so far

Keep this in your song.rhai; the next pages add to it.

blank("house");
title("First Light");
tempo(120);
track("kick",   s("bd*4"));
track("clap",   s("~ cp ~ cp"));
track("hats",   s("[~ hh]*4"));
track("shaker", s("sh*16").gain(0.4));

Mini-notation has every symbol you can use in a pattern string.

Notes, scales and keys

Drums mostly don’t have a pitch: a kick is a thump, not a note. Bass, chords and melody do. Before writing them, you need three ideas: notes, scales and keys.

Notes

Play this and listen to the sound climbing:

blank("house");
tempo(120);
track("up", note("c4 d4 e4 f4 g4 a4 b4 c5").s("epiano"));

Each sound is a note, and how high or low it sounds is its pitch. Notes are named with the letters a to g. After g the names start again at a, and the number says which round you are in, the octave: c4 to c5 is one octave up. Listen to the first and last note: they sound like the same note, one higher. That sameness is why they share a name.

c4 is middle C, the C in the middle of a piano. Low notes for bass sit around octave 1 and 2 (a1, e2), chords around 3 and 4, melodies around 4 and 5.

Semitones, sharps and flats

The eight notes above are the white keys of a piano. Between most of them there is a black key, a note halfway between. The smallest step between two neighbouring notes, white or black, is a semitone. The in-between notes are written with # (sharp, a semitone up) or b (flat, a semitone down): c#4 is the black key directly above c4, and it is the same note as db4. There are twelve semitones in an octave.

blank("house");
tempo(120);
track("all twelve", note("c4 c#4 d4 d#4 e4 f4 f#4 g4 g#4 a4 a#4 b4").s("epiano"));

Every note in that bar is a semitone higher than the one before. It sounds like stepping up a staircase, with no sense of where it is going. Music usually picks fewer notes than that.

Scales

A scale is a selection of seven (sometimes five) of the twelve notes that sound good together. Listen to two:

blank("house");
tempo(120);
track("major", n("0 1 2 3 4 5 6 7 6 5 4 3 2 1 0 ~").scale("C:major").octave(4).s("epiano"));

blank("house");
tempo(120);
track("minor", n("0 1 2 3 4 5 6 7 6 5 4 3 2 1 0 ~").scale("A:minor").octave(3).s("epiano"));

The first is C major: bright, settled, the “do re mi” you know. The second is A minor: darker, a little sad. They use exactly the same seven notes, the white keys, but A minor starts and ends on A. The note a scale is built on and comes home to is its tonic, and it changes the whole mood.

n() plays a scale by numbers instead of note names: 0 is the tonic, 1 the next note of the scale, and so on; 7 is the tonic an octave up. That is why the same numbers gave two different tunes: they were counted in two scales.

Keys

A song’s key is the scale it uses: “A minor” means the A minor scale, with A as home. Set it for the whole song:

blank("house");
tempo(120);
key("A minor");
track("tune", n("0 2 4 2 0 ~ ~ ~").octave(4).s("epiano"));

n() without .scale() uses the song’s key. The numbers 0, 2 and 4 skip every other note of the scale (A, C, E), which is a pattern you will meet again on the chords page.

Writing notes as numbers in the key has two advantages. Every number is in the scale, so nothing sounds wrong by accident. And if you change the key, everything written this way moves with it: change key("A minor") to key("D minor") and render again. The tune is the same, only lower.

Try this

• Play the five-note pentatonic scale, which sounds good in almost any order: n("0 1 2 3 4 3 2 1").scale("A:minor:pentatonic").octave(4). Shuffle the numbers; it still works.
• Try key("A major") with the tune above and hear the same numbers turn bright.
• Write a short tune of your own with numbers from 0 to 7 and ~ for rests. Start and end on 0 and it will sound finished.

The song so far

The drums from the last page, now in A minor. You won’t hear a difference yet: the key matters from the next page on.

blank("house");
title("First Light");
tempo(120);
key("A minor");
track("kick",   s("bd*4"));
track("clap",   s("~ cp ~ cp"));
track("hats",   s("[~ hh]*4"));
track("shaker", s("sh*16").gain(0.4));

Pitch has every scale name and the exact rules for notes.

Bass lines

The bass is the lowest part of a song. It does two jobs at once: it gives the beat weight (you feel it as much as hear it), and it tells your ear which chord the music is on, by playing that chord’s lowest note. A good bass line locks to the kick drum and moves with the chords.

Low notes

Bass notes live in octaves 1 and 2. Compare:

blank("house");
tempo(120);
track("high", note("a3 ~ ~ ~").s("sub_bass"));

blank("house");
tempo(120);
track("low", note("a1 ~ ~ ~").s("sub_bass"));

Both are the note A. The second is two octaves lower, and on good headphones or speakers you feel it more than you hear it. sub_bass is a pure, round synthesizer bass, which is why it nearly disappears on laptop speakers.

One note per bar

Our song will move through four chords, one per bar: A minor, F, C and G. You will build those chords on the next page. The bass plays the note each chord is named after, its root: A, F, C, G.

blank("house");
tempo(120);
key("A minor");
track("kick", s("bd*4"));
track("bass", note("<a1 f1 c2 g1>").s("sub_bass"));

The angle brackets < > mean “one per bar, in turn”: A in bar 1, F in bar 2, C in bar 3, G in bar 4, then A again. Each note lasts its whole bar. Listen to how the music seems to change mood every bar, even without chords: that is the bass doing its second job.

c2 is higher than a1 and g1, so the line moves down, up, down without big jumps: A, then F a little below it, C above, G below again. Keeping a bass line in a small range makes it smooth.

Rhythm

A bass that holds one note per bar is a drone. Give it a rhythm with .struct(), which takes the notes from one pattern and the timing from another:

blank("house");
tempo(120);
key("A minor");
track("kick", s("bd*4"));
track("bass", note("<a1 f1 c2 g1>").struct("x ~ ~ x ~ x ~ ~").s("sub_bass"));

"x ~ ~ x ~ x ~ ~" divides the bar into eight steps, two per beat, and plays on three of them. Count one and two and three and four and: the notes fall on one, on the and after two, and on the and after three. Each x plays whatever note the bar has. The first note lands with the kick on beat one, so you hear the chord change exactly when the bar starts; the other two fall between kicks, which is what makes the line groove.

Note length

Each note lasts until the next step unless you shorten it. .legato(0.5) makes every note half as long, so the bass bounces instead of sliding from note to note:

blank("house");
tempo(120);
key("A minor");
track("kick", s("bd*4"));
track("bass", note("<a1 f1 c2 g1>").struct("x ~ ~ x ~ x ~ ~").s("sub_bass").legato(0.5));

Bass sounds

Swap sub_bass for each and listen. On laptop speakers, organ_bass and saw_bass come through much more clearly, because they have higher overtones on top of the low note.

Try this

• The house offbeat bass: .struct("~ x ~ x ~ x ~ x"). The bass plays on every and, between the kicks, and the kick and bass take turns.
• Octave jumps: note("<[a1 a2]*4 [f1 f2]*4 [c2 c3]*4 [g1 g2]*4>").s("saw_bass").legato(0.5) jumps between the root and the same note an octave up, four times a bar: an eighties sound.
• Start the bass a sixteenth late with .late(0.0625) and hear the groove lean back.

The song so far

blank("house");
title("First Light");
tempo(120);
key("A minor");
track("kick",   s("bd*4"));
track("clap",   s("~ cp ~ cp"));
track("hats",   s("[~ hh]*4"));
track("shaker", s("sh*16").gain(0.4));
track("bass",   note("<a1 f1 c2 g1>").struct("x ~ ~ x ~ x ~ ~").s("sub_bass"));

Chords and progressions

A chord is several notes played at the same time. Chords carry the mood of a song more than anything else: the same beat sounds hopeful over one chord sequence and sad over another.

Three notes at once

On the last page, n("0 2 4") played A, C and E one after another. Play them together and you have a chord:

blank("house");
tempo(120);
key("A minor");
track("arpeggio", n("0 2 4 ~").octave(3).s("epiano"));
track("chord",    n("[0, 2, 4] ~ ~ ~").octave(3).s("epiano"));

The comma inside the brackets stacks the notes instead of playing them in turn. A chord built from every other note of the scale (1st, 3rd and 5th) is a triad, the basic chord of almost all Western music.

Major and minor

Triads come in two main colours. Listen to these two chords, one bar each:

blank("house");
tempo(120);
track("chords", chord("<C Cm>").s("epiano"));

C is C major: bright and stable. Cm is C minor: darker. The only difference is the middle note, one semitone lower in the minor chord. In chord names, a capital letter alone is major (F, G), and m after the letter means minor (Am, Dm).

A progression

A sequence of chords that repeats is a progression. The bass from the last page already played the roots of ours: A, F, C, G. Here are the chords themselves:

blank("house");
tempo(120);
key("A minor");
track("chords", chord("<Am F C G>").s("epiano"));
track("bass",   note("<a1 f1 c2 g1>").struct("x ~ ~ x ~ x ~ ~").s("sub_bass"));

A minor, F major, C major, G major, one bar each. This is one of the most used progressions in pop and dance music: it starts sad, lifts, and the G at the end pulls back to the beginning. The bass plays each chord’s root at the start of its bar, so the two agree.

Telling the song its chords

Writing the chords inside a pattern works, but claudius can do more when the song itself knows its progression. Set it once with prog(), and play it with chord("prog"):

blank("house");
tempo(120);
key("A minor");
prog("A", "Am F C G");
bars_per_chord(1);
track("chords", chord("prog").s("epiano"));

prog("A", ...) names the song’s main progression A. bars_per_chord(1) makes each chord last one bar (a blank song starts that way; a 2 would hold each chord for two bars). chord("prog") plays whatever chord the progression has at each moment. Now the song’s harmony is in one place: other parts can follow it, claudius checks your melody against it, and a second progression for another section is one more line.

A bass that follows

The bass can follow the progression too. .root() makes a chord pattern play only each chord’s root, the note the chord is named after (A for A minor), down in the bass register:

blank("house");
tempo(120);
key("A minor");
prog("A", "Am F C G");
bars_per_chord(1);
track("chords", chord("prog").s("epiano"));
track("bass",   chord("prog").root().struct("x ~ ~ x ~ x ~ ~").s("sub_bass"));

The bass plays A, F, C and G, the same rhythm as before, now taken from the progression. Change the chords in prog() and the bass changes with them.

Rhythm for chords

A held chord is calm. Chords played in a rhythm, called stabs, drive the groove:

blank("house");
tempo(120);
key("A minor");
prog("A", "Am F C G");
bars_per_chord(1);
track("kick",   s("bd*4"));
track("chords", chord("prog").struct("x ~ ~ x ~ ~ x ~").s("epiano").legato(0.5));

The rhythm x ~ ~ x ~ ~ x ~ puts three chords in each bar, unevenly spaced (3 + 3 + 2 eighth notes). It is one of the oldest rhythms in dance music, and it rubs nicely against the steady kick.

You did not choose which A, C and E to play, or in which order. claudius picks the notes of each chord so they move as little as possible from the chord before. Musicians call that voice leading, and it is why the chords sound connected rather than jumping around.

A pad underneath

A pad is a soft, long sound holding the chords in the background. It fills the space and makes quiet sections feel full:

blank("house");
tempo(120);
key("A minor");
prog("A", "Am F C G");
bars_per_chord(1);
track("pad", chord("prog").s("pad").role("pad"));

.role("pad") tells the mixer what this track is, so it sits quietly behind everything else. You will see roles again on the mixing page.

The numbers in the progression

If you print your song as a script (you will on the last page), the progression shows up as prog("A", "i VI III VII"). These are Roman numerals: they name each chord by its place in the key. i is the chord on the first note of the scale (A in A minor), VI the chord on the sixth (F), and so on; lower case means a minor chord, capitals a major one. Written this way, the progression works in any key: in D minor, i VI III VII is Dm, B♭, F, C.

Try this

• Seventh chords add one more note on top and sound richer, jazzier: prog("A", "Am7 Fmaj7 Cmaj7 G7").
• A brighter progression in the same key: prog("A", "F G Am Am").
• Hold each chord for two bars with bars_per_chord(2). The chords, the pad and the bass all follow.
• Arpeggiate the chords, playing their notes one after another: chord("prog").struct("x*4").arp("up").s("pluck").

The song so far

blank("house");
title("First Light");
tempo(120);
key("A minor");
prog("A", "Am F C G");
bars_per_chord(1);

track("kick",   s("bd*4"));
track("clap",   s("~ cp ~ cp"));
track("hats",   s("[~ hh]*4"));
track("shaker", s("sh*16").gain(0.4));
track("bass",   chord("prog").root().struct("x ~ ~ x ~ x ~ ~").s("sub_bass"));
track("chords", chord("prog").struct("x ~ ~ x ~ ~ x ~").s("epiano").legato(0.5));
track("pad",    chord("prog").s("pad").role("pad"));

Pitch lists every chord name claudius understands.

Melody

The melody is the part of a song you could sing back: one note at a time, on top of everything else. In electronic music it is often called the lead, or the hook when it is the catchiest bit.

Notes from the key

Write melodies with n(): every number is a note of the key, so you cannot hit a wrong note. In A minor:

A first idea, with eight steps in the bar:

blank("house");
tempo(120);
key("A minor");
track("melody", n("4 ~ 2 ~ 0 ~ 2 4").octave(4).s("pluck"));

E, C, A, C, E: it falls and climbs back. .octave(4) puts the melody above the chords; pluck is a short, bright synth sound that cuts through.

Fitting the chords

Play that same bar over all four chords and something sounds off, most of all over the G in bar 4. The reason: each chord is made of three notes, and a melody note that is part of the chord underneath sounds settled, while one that isn’t sounds tense. A little tension is good; too much on the strongest beats sounds like a mistake.

The strong beats are beat 1 and beat 3 of each bar, steps 1 and 5 when the bar has eight steps. Here are the chord notes of our progression as numbers:

So write each bar for its chord, with a chord note on steps 1 and 5:

blank("house");
tempo(120);
key("A minor");
prog("A", "Am F C G");
bars_per_chord(1);
track("chords", chord("prog").s("epiano"));
track("melody", n("<[4 ~ 2 ~ 0 ~ 2 4] [5 ~ 4 ~ 2 ~ ~ ~] [4 ~ 2 ~ 4 ~ 6 4] [6 ~ 4 ~ 3 ~ ~ ~]>")
                  .octave(4).s("pluck"));

Each pair of square brackets is one bar, and the angle brackets play them in turn. Check bar 2 against the table: F on beat 1 (5) and C on beat 3 (2), both notes of the F chord. The notes in between (the 4 in bar 2 is E) pass through, which is what makes a line move.

Repetition

Listen to the four bars again: bars 1 and 3 start the same way (4, then 2), and bars 2 and 4 both end with a held note. Repeating a short idea, a motif, with small changes is how melodies become memorable. Four bars that are all different are hard to remember; four identical bars are boring. Aim between.

Rests matter as much as notes: the held note at the end of bars 2 and 4 is a breath, and it splits the four bars into a question and an answer.

Echo

A delay repeats a sound a moment later, quieter, like an echo in a canyon. It makes a short melody sound wider and fills the gaps:

blank("house");
tempo(120);
key("A minor");
prog("A", "Am F C G");
bars_per_chord(1);
track("melody", n("<[4 ~ 2 ~ 0 ~ 2 4] [5 ~ 4 ~ 2 ~ ~ ~] [4 ~ 2 ~ 4 ~ 6 4] [6 ~ 4 ~ 3 ~ ~ ~]>")
                  .octave(4).s("pluck").delay(0.2));

.delay(0.2) sends a fifth of the sound to the song’s echo. The echoes come in time with the beat.

Try this

• Play the melody an octave higher every fourth bar: .every(4, |x| x.add(7)). Adding 7 moves every note up seven steps of the scale, which is one octave, so it still fits the chords.
• Swap the sound: bell, square_lead, or with the sample packs installed piano, vibes, flute.
• Add a quieter copy an eighth note behind, an octave up: .off(0.125, |x| x.add(7).gain(0.5)).
• Write your own four bars using the table. Put chord notes on steps 1 and 5, and anything from the key in between.

The song so far

blank("house");
title("First Light");
tempo(120);
key("A minor");
prog("A", "Am F C G");
bars_per_chord(1);

track("kick",   s("bd*4"));
track("clap",   s("~ cp ~ cp"));
track("hats",   s("[~ hh]*4"));
track("shaker", s("sh*16").gain(0.4));
track("bass",   chord("prog").root().struct("x ~ ~ x ~ x ~ ~").s("sub_bass"));
track("chords", chord("prog").struct("x ~ ~ x ~ ~ x ~").s("epiano").legato(0.5));
track("pad",    chord("prog").s("pad").role("pad"));
track("melody", n("<[4 ~ 2 ~ 0 ~ 2 4] [5 ~ 4 ~ 2 ~ ~ ~] [4 ~ 2 ~ 4 ~ 6 4] [6 ~ 4 ~ 3 ~ ~ ~]>")
                  .octave(4).s("pluck").delay(0.2));

Render it. Every layer plays all the time, for eight bars: it sounds like the loudest moment of a song, with nothing leading up to it. The next page fixes that.

Song structure

Your song so far plays every layer at once from the first bar to the last. Real songs change: they start small, build, release, breathe, and end. Each stretch of a song with its own set of layers is a section, and the plan of sections is the song’s structure (or form).

Sections in dance music

Listen to the song you made on the first page again (claudius make --genre house --seed 9) and follow its sections:

Sections are usually 4, 8 or 16 bars long. Ears expect change at those points: a section of 7 bars feels like someone tripped.

Writing the form

form() lists the sections in order. Each sec() gives the kind of section, its length in bars, and the tracks that play in it:

blank("house");
tempo(120);
key("A minor");
prog("A", "Am F C G");
bars_per_chord(1);
track("kick",   s("bd*4"));
track("hats",   s("[~ hh]*4"));
track("bass",   chord("prog").root().struct("x ~ ~ x ~ x ~ ~").s("sub_bass"));
track("chords", chord("prog").struct("x ~ ~ x ~ ~ x ~").s("epiano").legato(0.5));
track("pad",    chord("prog").s("pad").role("pad"));
form([
  sec("intro", 8, "kick hats"),
  sec("groove", 8, "kick hats bass chords"),
  sec("break", 8, "pad chords"),
  sec("drop", 8, "kick hats bass chords pad"),
]);

Thirty-two bars, about a minute. Listen to how much bigger the drop feels after the break, though it adds only the pad to the groove. Taking things away does as much as adding them.

Energy

Every section has an energy, from 0 (silent) to 1 (as intense as the song gets). claudius gives each kind a default (an intro 0.4, a break 0.35, a drop 0.95) and the critic checks that the song really gets louder where the energy rises. You can set it with .energy(0.3) when a section is quieter than its kind suggests.

Making the drop land

Four small touches turn a list of sections into a song that flows. Add them as methods on a section:

• .filter_in() on the intro: the music starts muffled and opens up across the section, like walking into the room where the party is. (The drums stay clear.)
• .build() on the section before the drop: a rising noise (a riser) and a sweep that thins out the low end, both growing until the drop.
• .gap() on that same section: one beat of silence at its very end. The drop hits harder after a breath.
• .impact() on the drop: a crash cymbal and a boom on its first beat.

A drummer would also play a snare roll into the drop: hits getting faster and louder. Make one as its own track, one bar of each speed, and play it only in the build:

blank("house");
tempo(120);
track("roll", s("<sd*2 sd*4 sd*8 sd*16>").gain("<0.5 0.65 0.8 1>"));
form([sec("build", 4, "roll").build()]);

Two hits in bar 1, four in bar 2, eight, then sixteen, getting louder each bar. Since the angle brackets start over in every section, the roll always begins with the build.

A second progression

The break is a good place for different chords. Sections play progression A unless they say otherwise, and breaks play progression B when the song has one (until now, yours did not, so the break played A). Give the song a B:

blank("house");
tempo(120);
key("A minor");
prog("A", "Am F C G");
prog("B", "F G Am Am");
bars_per_chord(1);
track("pad", chord("prog").s("pad").role("pad"));
form([sec("groove", 8, "pad"), sec("break", 8, "pad")]);

The same pad track plays A in the groove and B in the break, because chord("prog") follows whatever progression the section plays, and so does a bass written with .root(). The melody, though, was written note by note for progression A, so keep it out of the break, or tell a section to play A with .prog("A").

The song so far

The whole song: 60 bars, two minutes at 120 BPM.

blank("house");
title("First Light");
tempo(120);
key("A minor");
prog("A", "Am F C G");
prog("B", "F G Am Am");
bars_per_chord(1);

track("kick",   s("bd*4"));
track("clap",   s("~ cp ~ cp"));
track("hats",   s("[~ hh]*4"));
track("shaker", s("sh*16").gain(0.4));
track("roll",   s("<sd*2 sd*4 sd*8 sd*16>").gain("<0.5 0.65 0.8 1>"));
track("bass",   chord("prog").root().struct("x ~ ~ x ~ x ~ ~").s("sub_bass"));
track("chords", chord("prog").struct("x ~ ~ x ~ ~ x ~").s("epiano").legato(0.5));
track("pad",    chord("prog").s("pad").role("pad"));
track("melody", n("<[4 ~ 2 ~ 0 ~ 2 4] [5 ~ 4 ~ 2 ~ ~ ~] [4 ~ 2 ~ 4 ~ 6 4] [6 ~ 4 ~ 3 ~ ~ ~]>")
                  .octave(4).s("pluck").delay(0.2));

form([
  sec("intro", 8, "kick hats pad").filter_in(),
  sec("groove", 16, "kick clap hats shaker bass chords"),
  sec("break", 8, "pad chords"),
  sec("build", 4, "clap hats pad roll melody").gap(),
  sec("drop", 16, "kick clap hats shaker bass chords pad melody").impact(),
  sec("outro", 8, "kick hats bass"),
]);

The pad plays in the intro so the opening filter has something to open: the drums are never filtered. The build has no kick: taking the kick away for four bars makes its return in the drop the biggest moment of the song. A section of kind build gets the riser and the sweep without being asked; .gap() adds the breath.

Try this

• Make the break longer (16 bars) and put the melody in it with .prog("A").
• Add a short break and a second drop before the outro: sec("break", 4, "pad") and a copy of the drop line. A second section with the same name is renamed drop2 automatically. ("*" instead of a list means every track, which here would include the roll.)
• Remove .gap() and listen to the drop again. Then put it back.

Form and sections explains every section setting exactly.

Mixing

Mixing is making every part of a song audible and placing it: how loud each track is, how far left or right, how close or far away. A good mix lets you follow any part you choose to listen to.

claudius does a first mix for you. This page shows what it does and how to adjust it.

Roles: the automatic balance

Every track has a role that says what it is: kick, snare, hat, bass, chords, pad, lead and so on. Each role has a loudness it is usually mixed at, and claudius brings every track to that loudness. Kick and bass are loud, hats and shakers quieter, pads quieter still, behind everything.

Most tracks get the right role on their own: a track playing bd is a kick, one playing sub_bass is a bass, a chord() pattern is chords. A melodic track with nothing else to go on is treated as the lead. That is why the pad had .role("pad") on the chords page: without it, the pad would be mixed as loud as a melody.

Level

To change how loud a track is, give it a level in decibels (dB), relative to where its role puts it:

blank("house");
tempo(120);
key("A minor");
prog("A", "Am F C G");
bars_per_chord(1);
track("kick", s("bd*4"));
track("pad",  chord("prog").s("pad").role("pad"));
mix("pad", #{ level: -3 });

level: -3 is three decibels quieter than usual for a pad. Decibels are how loudness is measured: 1 dB is about the smallest change you can notice, 3 dB is a clear step, and 10 dB sounds roughly half as loud. Use small numbers; anything beyond ±6 usually means the track has the wrong role or the wrong sound.

Left and right

Pan places a track between the left speaker (−1) and the right (1). Kick, bass, snare or clap and the lead stay in the middle; hats, percussion and other small parts spread out to the sides, which makes room in the centre:

blank("house");
tempo(120);
track("kick",   s("bd*4"));
track("hats",   s("[~ hh]*4"));
track("shaker", s("sh*16").gain(0.4));
mix("hats",   #{ pan: 0.2 });
mix("shaker", #{ pan: -0.3 });

Listen on headphones: the hats tick slightly to the right, the shaker to the left.

Space: reverb and delay

Reverb is the sound of a room: the reflections that make a sound seem far away. Delay is a distinct echo. Each track sends some of itself to the song’s reverb and delay, from 0 (none) to 1 (a lot):

blank("house");
tempo(120);
key("A minor");
prog("A", "Am F C G");
bars_per_chord(1);
track("chords", chord("prog").struct("x ~ ~ x ~ ~ x ~").s("epiano").legato(0.5));
mix("chords", #{ reverb: 0.3 });

Short, plucky sounds (stabs, melodies) and pads like reverb; kick and bass sound best dry, close and solid. Too much reverb on everything makes a mix sound washed out and far away.

Ducking under the kick

In dance music, the bass and chords get quieter for a split second every time the kick hits, then swell back. This is called sidechain ducking, and it gives the kick room and the whole track a pumping, breathing feel. Each track has a duck amount from 0 (none) to 1 (the track nearly vanishes on every kick):

blank("house");
tempo(120);
key("A minor");
prog("A", "Am F C G");
bars_per_chord(1);
track("kick", s("bd*4"));
track("pad",  chord("prog").s("pad").role("pad"));
mix("pad", #{ duck: 0.7 });

Listen for the pad pulsing with the kick. Pattern tracks start at 0.3, which you hear as a gentle movement; 0.5 is clearly pumping, 0.8 is the exaggerated pump of future bass.

Listening to one thing

While mixing, it helps to hear one track alone. solo() plays only the soloed tracks, mute() silences one:

blank("house");
tempo(120);
key("A minor");
track("kick", s("bd*4"));
track("bass", note("<a1 f1 c2 g1>").struct("x ~ ~ x ~ x ~ ~").s("sub_bass"));
solo("kick");
solo("bass");

This renders only the kick and the bass, so you can hear whether they fit together. Remove the solo() lines before your final render; the critic judges only what plays.

Try this

• Turn the melody up 2 dB and down 2 dB, rendering each time. Which one lets you hear the chords?
• Give the bass duck: 0 and then duck: 0.6, and listen to the low end with the kick.
• Put a lot of reverb on the clap (reverb: 0.5) and hear it move back into a big room.

The song so far

The mix lines go at the end of the script, after form():

blank("house");
title("First Light");
tempo(120);
key("A minor");
prog("A", "Am F C G");
prog("B", "F G Am Am");
bars_per_chord(1);

track("kick",   s("bd*4"));
track("clap",   s("~ cp ~ cp"));
track("hats",   s("[~ hh]*4"));
track("shaker", s("sh*16").gain(0.4));
track("roll",   s("<sd*2 sd*4 sd*8 sd*16>").gain("<0.5 0.65 0.8 1>"));
track("bass",   chord("prog").root().struct("x ~ ~ x ~ x ~ ~").s("sub_bass"));
track("chords", chord("prog").struct("x ~ ~ x ~ ~ x ~").s("epiano").legato(0.5));
track("pad",    chord("prog").s("pad").role("pad"));
track("melody", n("<[4 ~ 2 ~ 0 ~ 2 4] [5 ~ 4 ~ 2 ~ ~ ~] [4 ~ 2 ~ 4 ~ 6 4] [6 ~ 4 ~ 3 ~ ~ ~]>")
                  .octave(4).s("pluck").delay(0.2));

form([
  sec("intro", 8, "kick hats pad").filter_in(),
  sec("groove", 16, "kick clap hats shaker bass chords"),
  sec("break", 8, "pad chords"),
  sec("build", 4, "clap hats pad roll melody").gap(),
  sec("drop", 16, "kick clap hats shaker bass chords pad melody").impact(),
  sec("outro", 8, "kick hats bass"),
]);

mix("hats",   #{ pan: 0.2 });
mix("shaker", #{ pan: -0.3 });
mix("bass",   #{ duck: 0.5 });
mix("chords", #{ reverb: 0.25, duck: 0.4 });
mix("pad",    #{ level: -3, reverb: 0.4 });
mix("melody", #{ reverb: 0.3 });

Mixing functions has every setting and the loudness of every role.

Listening, judging, finishing

Your song has every layer, a structure and a mix. This page is about the part producers spend most of their time on: listening critically, finding what is wrong, and fixing it until the song is done.

Render the whole song

Save the song from the mixing page as song.rhai and render it:

claudius script song.rhai

This is what claudius printed for it:

track kick: bd
track clap: cp
track hats: hh
track shaker: sh
track roll: sd
track bass: sub_bass
track chords: epiano
track pad: pad
track melody: pluck
ears loaded in 3.6 s
First Light — house at 120 BPM in A minor, 60 bars (2:00)
  progression A: i VI III VII
  progression B: VI VII i i
  form: intro 8 | groove 16 | break 8 | build 4 | drop 16 | outro 8
  tracks: kick (synth kick), clap (synth clap), hats (synth closed_hat), shaker (synth shaker), roll (synth snare), bass (synth patch 'sub_bass'), chords (synth patch 'epiano'), pad (synth patch 'pad'), melody (synth patch 'pluck'), 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 -10.2 LUFS); done in 12.8 s
  ears: 'house music' z +3.4 (closest confusion 'techno music' +3.1); production z +1.2 vs 'a low quality recording with hiss' +0.7; p_real 0.47
        sounds like: house music, tech house music, techno music, drum and bass music
  verdict: 87/100 (arc 0.80, genre 0.80, mix 0.99, production 0.63, theory 1.00). Fix first: dull 4-8 kHz: hats, claps and snare lack bite (presence -26.4 dB, healthy from -26)
  wrote out/house-first-light-1/song.mp3

Line by line:

• track …: each track and the sounds it found.
• ears loaded: claudius loaded its listening models (the first run downloads them; later runs take a few seconds on an idle machine, longer on a busy one).
• First Light: title, style, tempo, key, length.
• progression: your chords, written as Roman numerals.
• form: your sections and their lengths.
• tracks: every track and what plays it. The last five are the transition sounds your section flags asked for: the riser in the build, a reversed cymbal swelling into the drop, and a crash, an impact and a falling “downlifter” on the drop’s first beat.
• master: how loud the finished song is. claudius makes it as loud as songs in the style usually are.
• ears and sounds like: what the listening model hears. More below.
• verdict: the critic’s score, and what to fix first.

Listen before you read

The score is useful, but your ears come first. Listen to the whole song once without stopping, on the best speakers or headphones you have, then on something small (a phone or a laptop). Note anything that bothers you: a part you can’t hear, a part that is too loud, a moment that drags. Then read the verdict and see whether it agrees.

The verdict

The critic listens in three ways and gives each a score from 0 to 1:

• mix: measurements of the finished audio. Is it as loud as it should be, without distortion? Is the sound balanced from deep bass to bright treble? Is it wide enough, and is the bass centred?
• arc: does the song get louder where it should? It compares the loudness of each section with its energy, and checks that the drop is clearly louder than the break.
• theory: the notes. Is the melody in the key? Are its strongest notes part of the chords? Does the bass play the chords’ roots when they change?

When the listening models are loaded (they are by default), two more:

• genre: does it sound like the style you chose, more than the styles it is usually confused with?
• production: does it sound like a professionally produced record, more than like a cheap or broken recording?

With --no-ears, or on a computer the listening models cannot run on (claudius then says earshot is unavailable), the critic judges with the first three only, and the score is out of those.

The total out of 100 combines them. The Fix first list names the problems that cost the most, with numbers and a hint. Ours has one:

• dull 4-8 kHz: hats, claps and snare lack bite (presence -26.4 dB, healthy from -26). The bright, crisp range where hats and claps live is a little quiet compared with the rest. The fix is in the hint: turn the hats and clap up.

The ears line says the song reads as house (z +3.4) a little more than as its closest confusion, techno (z +3.1). The genre model’s readings are hints, not rules: two styles that share a tempo or a drum sound often sit close together for it.

Fix and render again

One change for the one problem: the hats and the clap 2 dB louder.

blank("house");
title("First Light");
tempo(120);
key("A minor");
prog("A", "Am F C G");
prog("B", "F G Am Am");
bars_per_chord(1);

track("kick",   s("bd*4"));
track("clap",   s("~ cp ~ cp"));
track("hats",   s("[~ hh]*4"));
track("shaker", s("sh*16").gain(0.4));
track("roll",   s("<sd*2 sd*4 sd*8 sd*16>").gain("<0.5 0.65 0.8 1>"));
track("bass",   chord("prog").root().struct("x ~ ~ x ~ x ~ ~").s("sub_bass"));
track("chords", chord("prog").struct("x ~ ~ x ~ ~ x ~").s("epiano").legato(0.5));
track("pad",    chord("prog").s("pad").role("pad"));
track("melody", n("<[4 ~ 2 ~ 0 ~ 2 4] [5 ~ 4 ~ 2 ~ ~ ~] [4 ~ 2 ~ 4 ~ 6 4] [6 ~ 4 ~ 3 ~ ~ ~]>")
                  .octave(4).s("pluck").delay(0.2));

form([
  sec("intro", 8, "kick hats pad").filter_in(),
  sec("groove", 16, "kick clap hats shaker bass chords"),
  sec("break", 8, "pad chords"),
  sec("build", 4, "clap hats pad roll melody").gap(),
  sec("drop", 16, "kick clap hats shaker bass chords pad melody").impact(),
  sec("outro", 8, "kick hats bass"),
]);

mix("hats",   #{ pan: 0.2, level: 2 });
mix("clap",   #{ level: 2 });
mix("shaker", #{ pan: -0.3 });
mix("bass",   #{ duck: 0.5 });
mix("chords", #{ reverb: 0.25, duck: 0.4 });
mix("pad",    #{ level: -3, reverb: 0.4 });
mix("melody", #{ reverb: 0.3 });

The new verdict:

  ears: 'house music' z +3.4 (closest confusion 'techno music' +3.1); production z +1.2 vs 'a low quality recording with hiss' +0.7; p_real 0.47
        sounds like: house music, tech house music, techno music, drum and bass music
  verdict: 87/100 (arc 0.80, genre 0.79, mix 1.00, production 0.64, theory 1.00)

The mix score went from 0.99 to 1.00, and the critic has nothing left to fix first. The total stays at 87: it weighs all five scores, and the mix is only one of them. That is a typical round: a small change, a point or less, and a problem gone.

Knowing when to stop

A score in the high 80s means the critic found no big measurable problem. It does not mean the song is good; it has no taste, only measurements. Some things it cannot tell you: whether the melody is catchy, whether the drop is exciting, whether the song is too long. So:

• Fix what the critic finds when you can hear the problem too.
• Ignore a suggestion that makes the song worse to your ears. The genre model, in particular, is a hint.
• Stop when the song does what you wanted and nothing bothers you on three different speakers.

As an example of the critic’s limits: the same song played on a real 909 drum machine with a sampled piano and strings (.bank("tr909"), .s("piano"), .s("string_ensemble")) scores four points lower than the version with synthesizers, because the genre model hears it as closer to drum and bass. Whether it sounds better is your call.

Keep and share it

• The audio: song.mp3 and song.wav in the song’s folder are the finished, mastered song.
• The script: song.rhai in that folder is the song as claudius prints it, which you can read and edit. Your own song.rhai stays the clearest description of what you made.
• The rest: blueprint.json is the song in full detail, verdict.json the critic’s whole report.

To see your song as claudius describes it, print it instead of rendering: claudius script song.rhai --print. You will find your progressions as Roman numerals and your tracks exactly as you wrote them.

Where to go next

• The studio: the same song in a window, with a step sequencer, a mixer and the verdict updating as you edit.
• Working with an assistant: ask Claude or another assistant to make and fix songs with you.
• The cookbook: complete songs in eight styles, with every choice explained.
• For producers: the same ideas in more depth, once you are comfortable with these.

claudius for DAW users

If you work in Ableton, Logic, FL Studio or Bitwig, most of claudius will be familiar: tracks, an arrangement in sections, a mixer with sends and a sidechain, a master chain with a limiter. What differs is how you edit them. There is no free timeline of clips: the arrangement is a grid of sections and tracks (the studio lets you drag sections and paint which tracks play in each), and the notes come from patterns and parts. You describe the song (in a script, in the studio’s panels, or through an assistant), claudius arranges, renders and judges it, and you listen and revise. A render of a three-minute song takes 10 to 40 seconds.

Where things are

There is one tempo, one key and one time signature (4/4) per song. There is no MIDI input, MIDI export or live recording.

The same groove, two ways

A house groove programmed in a step sequencer:

blank("house");
tempo(124);
drum("kick", "X...X...X...X...");
drum("clap", "....X.......X...");
drum("hat",  "..x...x...x...x.");
drum("hat", "sparse", "......x.......x.");

And in pattern form:

blank("house");
tempo(124);
track("drums", s("bd*4, [~ cp]*2, [~ hh]*4"));

They sound alike but behave differently. Drum lanes are what the generator writes: they have named variants that sections switch between (main, sparse, alt), and the arranger rewrites them for builds (a snare roll, the kick dropping out) and phrase-end fills. Pattern tracks are never rewritten; they give you the whole pattern language (alternation, euclidean rhythms, randomness, sampled kits such as tr909:bd), and you write the variation yourself. To put a drum lane on a recorded kit, drum_sound("kick", "tr909:bd") swaps its sound and keeps its pattern. Most of the cookbook uses patterns.

Levels are relative

A DAW fader is an absolute gain. In claudius every track has a role (kick, bass, pad, lead …), every role has a target loudness, and each track is gained to its target while it plays. level is an offset from that target. A pad at level: -3 sits 3 dB below where a pad normally sits, whatever its patch or velocity, and adding a track does not change the balance of the others.

The consequence: gain staging is done for you, and the first mix decision is the role. A track’s role comes from its sound: drums and percussion find theirs, a bass preset or a low line is bass, a chord pattern is chords, and anything else melodic is treated as a lead. Set .role("pad") or .role("arp") on pattern tracks that are not leads.

Sections replace clips

A DAW lets every clip differ. In claudius a track plays the same material in every section it is in, starting from the section’s first bar: an alternation starts again from its first item, every(4, ...) counts from the section, the progression starts on its first chord. To vary a part in one section, make a second track and put it only there:

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("keys",   chord("prog").struct("x ~ ~ x ~ ~ x ~").s("epiano"));
track("keys16", chord("prog").struct("x*16").legato(0.4).s("epiano"));   // the busy version, drop only
form([sec("groove", 16, "drums keys"), sec("drop", 16, "drums keys16")]);

Harmony is written once

A DAW has no idea what key you are in. claudius does: the song has a key and named progressions in Roman numerals (prog("A", "i7 VImaj7 iv7 v7")), sections choose a progression, and chord patterns, generated parts and the critic all read it. Write chord("prog") and the chords follow whatever progression the section plays; change the key and everything written in numerals or scale degrees moves with it. See Harmony.

The loop you work in

1. Write or change the song: a script, an edit in the studio, or a request to an assistant.
2. claudius arranges and renders it (10 to 40 seconds for a full song), then judges it.
3. Listen. Read the verdict: scores for mix, energy arc, theory, genre and production, with each issue naming what to change.
4. Revise, or let evolution try variations for you.

Every song prints as a script (Songs as scripts), so whatever produced it (the generator, the studio, an assistant), you can read it and edit it as text.

Harmony

claudius knows the song’s key and its chord progressions, and everything harmonic reads them: chord patterns, the parts the theory engine writes, arpeggios, the bass check of the critic. This page covers how to write harmony so that all of those agree, and exactly how claudius interprets it. The full rules for symbols and numerals are in Pitch.

Key and mode

A song has one key, in one of seven modes: major, minor (aeolian), dorian, phrygian, lydian, mixolydian, harmonic minor. Roman numerals are counted in the key’s own mode, so the same numeral changes quality with the mode:

Upper and lower case only choose major or minor; they never move the root. IV in A minor is a D major chord (borrowed from dorian) on the fourth degree, iv the diatonic D minor. Accidentals move the root: bVII in C major is B♭, bVI is A♭.

Writing a progression

blank("deep_house");
key("F minor");
prog("A", "Fm9 Bbm9 Dbmaj7 Cm7");     // stored as i9 iv9 VImaj7 v7
prog("B", "Dbmaj7 Eb Fm9 Fm9");
bars_per_chord(1);
track("keys", chord("prog").struct("x ~ ~ x ~ ~ ~ ~").voicing(53, 72).s("epiano"));
form([sec("groove", 8, "keys"), sec("break", 8, "keys")]);

Chord names are converted to numerals in the key that is current when prog() runs, then stored as numerals. Set the key first; a later key() transposes the progression (and changes chord qualities if the mode changes, see below).

Progressions have names. Sections play A by default and breaks B (or A, when the song has no B); any other name works with sec(...).prog("verse"), and a section that asks for a progression the song does not have is an error. Every progression uses the same bars_per_chord(), the number of bars each chord lasts. A progression starts on its first chord at the start of every section and loops.

What numerals can express:

• diatonic triads and sevenths by degree and case: i7 ii° III iv7 v7 VImaj7 VII;
• extensions: 9, add9, 6, maj7, maj9, 11 (always minor 11), sus2, sus4;
• borrowed chords with accidentals: bVI bVII in major, IV (dorian) or V7 (harmonic) in minor;
• applied chords: V/V, V7/ii, viio7/V, read in the key of the target chord;
• a bass note: I/E, VI/A, or as a name, F/A (stored as VI/A in A minor). .root(), the generated basslines and the critic use it, and key() moves it with the chord.

All of these work in pattern strings too: chord("<I V7/V V7 I>"), chord("<Am F/A C G>").

Chord patterns

chord("prog") plays the section’s progression; chord("prog:B") always plays B; chord("<Am7 Fmaj7>") plays the named chords regardless of the song’s progressions. Prefer prog: the arranger’s chord track, the generated parts and the critic all use the song’s progressions, so a pattern with its own chord names can disagree with all of them.

Every chord event is voiced with voice leading (see Voicing):

• three voices for triads, four for sevenths and anything larger; the fifth goes first when there are too many notes, then the root;
• close voicings (within about an octave and a half), placed in the range given by .voicing(lo, hi) (default 52..74, E3 to D5);
• each chord chosen to move the voices as little as possible from the previous one, the first chord of a section near the middle of the range.

There is no drop-2 or spread voicing for patterns, and no control over inversions beyond the range. A narrow range forces inversions: .voicing(60, 72) keeps every chord inside one octave above middle C.

Rhythm comes from the events: .struct("x ~ ~ x ~ ~ x ~") for a tresillo stab, "x*16" with a short legato for a pumping sixteenth chord, .arp("updown") for an arpeggio. Layering two tracks on chord("prog") with different ranges and rhythms (a pad low and long, stabs higher and short) keeps them in the same harmony automatically.

Bass lines

Generated bass parts follow the progression and the kick (see the bass styles of part()). A pattern bass follows the progression with .root(), which plays each chord’s root (or its slash bass) in octave 2:

blank("techno");
key("F phrygian");
prog("A", "i i II i");
bars_per_chord(2);
track("bass", chord("prog").root().octave(1).struct("[~ x x x]*4").s("sub_bass").legato(0.6));

.octave(1) puts the roots an octave lower: F1 for four bars, G♭1 for two, F1 for two. Change the progression and the bass follows. When the line should move by step or leap to a different octave, write the notes out instead: note("<f1!4 gb1!2 f1!2>") plays the same roots, one per bar.

On a blank song, part() adds the genre’s bass part over your progression: part("bass", #{ style: "rolling" }).

The critic checks that the bass plays the chord’s root (or its slash bass) on at least 70 % of the chord changes it plays on; a bass that plays offbeats only is not checked.

Changing key

key() moves everything written relatively: numerals, n() degrees, generated parts. Note names in note() patterns are absolute and stay. When the mode changes, every diatonic chord keeps its degree and takes the new mode’s quality: Imaj7 vi7 ii7 V7 in E major becomes i7 VImaj7 iiø7 v7 in F minor. Borrowed (bVII) and applied (V/V) chords are kept as written.

The generator’s harmony

song(genre, seed) picks a harmonic style from the genre’s profile, or writes a progression with a functional-harmony Markov chain (tonic, subdominant and dominant degrees, no chord repeated twice in a row, ending on a chord that leads back to the start). The styles:

Progression B is another progression of the same style or a substitution of A. Evolution changes harmony with these substitutions, each recorded in the song’s lineage: a chord a third away, an extended or plain version, a secondary dominant before a chord, a chord borrowed from the parallel mode, a suspension, two chords swapped, the progression rotated.

What the critic checks

The theory score reads the arranged song, not the audio:

“The lead” is the first track whose role is lead, and “the bass” the first whose role is bass; the chords are the song’s progressions, as the arranger lays them out. That is why chord("prog") and .role() matter: a melody checked against the wrong chords, or a pad checked as a melody, costs points for no musical reason.

Rhythm and groove

Rhythm in claudius has three layers: where notes sit (patterns and step strings), how hard they are played (velocity), and how the grid is bent when the song renders (swing and humanize). This page gives the exact behaviour of each and the idioms that come out of them.

The grid

Pattern time is continuous: a cycle is one bar, and mini-notation divides it however you like. Common subdivisions:

Drum lanes (drum()) are a step grid with 16 steps per bar by default, or any resolution from 1 to 96. When a lane prints as a script, it uses 16 steps if every hit sits on a sixteenth, then 32, then 48.

Velocity

Velocity drives level and tone the way the instrument does. Synthesized drums and audio files scale level by velocity to the power 1.6 (0.5 is about 10 dB below 1.0); the sampled kits switch velocity layers (the 909 has eleven) as well; synth presets open their filters. The track as a whole is then levelled to its role’s target, so velocity shapes the groove, not the track’s loudness.

A sixteenth hat with accents on the off-beat eighths and soft ghosts between:

blank("house");
tempo(124);
track("hats", s("hh*16").bank("tr909").gain("[0.35 0.2 0.8 0.2]*4"));

Swing

swing(amount) is sixteenth-note swing for the whole song:

• each off-beat sixteenth (the second of each pair inside an eighth note) moves to amount of the way through the eighth; 0.5 is straight, 0.66 is a triplet feel; the range is 0 to 0.8, and up to 0.501 is straight;
• only notes within 0.01 beats of a sixteenth grid position move, so eighth notes, triplets and notes nudged with .late() are untouched;
• it applies at render to every track: drum lanes, parts and pattern tracks alike.

The genres’ generated swing ranges are a good guide: house 0.50–0.56, deep house 0.53–0.58, lofi 0.56–0.63, trap 0.50–0.54, techno 0.50–0.52, drum and bass 0.50–0.51, future bass 0.50–0.53, synthwave straight.

Since swing is global, a part that should sit straight in a swung song has to avoid off-beat sixteenths (use eighths or triplets), and a part that should lag can use .late(0.01) to .late(0.03), which also takes it off the grid that swing moves.

Humanize

humanize(amount) adds random timing and velocity at render:

• timing: a normal distribution with a standard deviation of 4 ms × amount on drum roles, 2.4 ms × amount on others (synth tracks: 3 ms and 1.8 ms);
• velocity: ±5 % × amount (one standard deviation);
• seeded by the song and the track name, so every render is the same.

Generated songs use 0.25 in house, 0.35 in deep house, 0.6 in lofi, 0.15 in trap and 0.1 elsewhere. blank() keeps the genre’s value.

Idioms

Ghost notes are low-velocity hits between the main ones. In a step string, o; in a pattern, a quiet layer in a stack(), since a gain pattern applies by time and would turn down the backbeat too:

blank("lofi");
tempo(86); swing(0.6);
track("snare", stack([s("~ sd ~ sd").gain(0.9), s("~ ~ ~ [~ sd] ~ ~ [~ sd] ~").gain(0.3)]).bank("acoustic"));

Rolls are fast repeats inside one beat. Write the bar beat by beat, with the roll in the beat that has it:

blank("trap");
tempo(140);
track("hats", s("<[hh*2 hh*2 hh*2 hh*2] [hh*2 hh*2 hh*2 hh*6] [hh*2 hh*2 hh*2 hh*2] [hh*2 hh*4 hh*2 hh*8]>")
                .bank("tr808").gain("[0.9 0.6]*4"));

Bar 2 ends with a sixteenth-triplet roll (six in a beat), bar 4 with thirty-seconds. Generated trap hats get rolls from the drum grammar instead: random beats replaced by bursts of thirty-seconds or triplets with a rising or falling velocity ramp, most often on the last beat of a bar and rarely on the first.

Euclidean rhythms spread k hits over n steps as evenly as possible, which gives most of the world’s clave-like patterns: (3,8) is the tresillo (x..x..x.), (5,8) the cinquillo (x.xx.xx.), (5,16) and (7,16) are good percussion lines over a four-on-the-floor kick. A third number rotates the rhythm left by that many steps (see Euclidean rhythms).

blank("techno");
tempo(130);
track("kick", s("bd*4").bank("tr909"));
track("rim",  s("rim(5,16,2)").bank("tr909").gain(0.6).pan(0.3));
track("perc", s("cb(3,8,1)").gain(0.4).pan(-0.3));

Polymeter. There is no { } polymeter, but a fractional fast() runs a short figure across bar lines. A three-step figure on a sixteenth grid is three sixteenths long, so it repeats 16/3 times per bar:

blank("techno");
track("perc", s("rim ~ ~").fast(16.0 / 3.0).gain(0.5));   // lands one sixteenth earlier each bar

It restarts with every section, like every pattern.

Kick and bass together. A bass that plays exactly with the kick uses the kick’s rhythm as its structure. Keep the rhythm in a variable so the two cannot drift apart:

blank("trap");
tempo(140); key("C minor");
let kick = "x ~ ~ ~ ~ ~ ~ x ~ ~ x ~ ~ ~ ~ ~";
track("kick", s("bd").struct(kick).bank("tr808"));
track("808",  note("<c2!2 ab1!2 f1!2 g1!2>").struct(kick).s("808").legato(1.0));

Generated parts do the same with the kick_follow bass style, which plays on every kick of the main kick pattern.

Drum lanes in the arrangement

Drum lanes change with the sections they play in:

• each section plays the lane’s variant it asks for (main, sparse, alt, half …), or main when the lane does not have it; intros and outros ask for sparse;
• fills() replaces the last one or two beats of every 8-bar phrase on the snare (or clap) lane with a fill, and sometimes drops the kick for the last half beat;
• build() turns the snare (or clap) lane into a snare roll for the second half of the build and drops the kick for its last bar.

Form and sections has the exact rules. Pattern tracks are never rewritten; make fills with lastOf() and builds with a track that only plays in the build:

blank("house");
tempo(124);
track("drums", s("bd*4, [~ cp]*2, [~ hh]*4").bank("tr909").lastOf(8, |x| x.ply(2)));
track("roll",  s("<sd*2 sd*2 sd*4 sd*4 sd*8 sd*8 sd*16 sd*16>").bank("tr909")
                 .gain("<0.4 0.45 0.5 0.55 0.65 0.75 0.85 1>"));
form([sec("groove", 16, "drums"), sec("build", 8, "roll").gap(), sec("drop", 16, "drums").impact()]);

The generator’s grooves

Generated drum lanes come from each genre’s drum grammar: for every lane, a probability of a hit on each sixteenth step (1.0 always hits), a velocity range scaled by the metrical weight of the step, a chance of ghost notes, a chance of rolls, and a chance that the last bar of the 4-bar pattern varies. Some lanes use a euclidean rhythm instead (house percussion is a rotated (5,16)). The same seed gives the same grooves; mutation edits single hits, nudges them by a sixteenth, re-accents them or regenerates a lane.

Sounds, samples and sound design

claudius plays two kinds of audio: sounds synthesized in code and sounds that were recorded. There is no General MIDI and no neural audio generation; a note is only ever the score that plays one of these sounds. This page covers where each comes from, how genres choose them, and how much of them you can shape. The names you can use are in the Sounds reference.

Synthesized

Drum voices. Thirteen drum circuits rendered in code: kick, snare, clap, closed and open hats, ride, crash, tom, rim, shaker, cowbell, snap and a tuned percussion voice. Each has nine parameters: tune, decay, tone, punch, snap, drive, pitch-envelope depth and time, and room. The generator draws them from the genre’s ranges (a house kick decays in 0.32–0.55 s with 3–8 dB of drive) and, in genres that ask for it, tunes the kick’s fundamental to the tonic or fifth of the key. A variation (bd:3) moves the voice a few steps through its parameters.

The synth engine. Oscillators with polyBLEP anti-aliasing (saw, square, pulse, triangle, sine), unison with per-voice analog drift, a sub oscillator and noise, FM with a tine component for electric pianos, state-variable and ladder filters with an envelope, key tracking and velocity, an LFO for vibrato, filter and amplitude (free or tempo-synced), glide, mono and legato modes, and drive. Twenty factory presets cover basses (sub_bass, 808, reese, acid, wobble …), keys (epiano, keys, organ), pads, plucks, leads and bells. A generated part takes a copy of a preset with its cutoff and detune varied a little; evolution tweaks cutoff, resonance, release, drive and detune further.

Transitions. Risers, downlifters, impacts, reverse crashes and filter sweeps are rendered at the length the arrangement asks for, with the riser pitched to the key. The crash is a drum voice or a recorded one-shot.

claudius sounds renders every drum voice, preset and transition into out/sounds/ for auditioning.

Recorded

Sample packs. Multi-sampled instruments and drum machines under licences that allow making and publishing music with them. claudius-packs install --defaults installs fourteen packs (a 2.2 GB download, 1.2 GB on disk):

The instruments have velocity layers and round robins (the Salamander piano has five layers; the 909 kick eleven layers and 126 variations). A song that plays a pack whose licence asks for attribution gets a credits.txt in its folder. claudius-packs list shows what is installed, claudius-packs audition renders every instrument, and claudius-packs add-map github:user/repo adds any Strudel sample map, recording its licence (or warning when it has none).

Apple Loops. When GarageBand or Logic content is installed, claudius finds it where Apple put it and uses it three ways: as one-shots cut from drum loops for the drum lanes of generated songs (each lane uses a recorded hit with a 75 % chance in claudius make), as texture loops (house’s top percussion loop), and, with --loops or song(genre, #{ loops: true }), as the backbone of a song built around one loop family: its chords, bass and beat, warped to the tempo and transposed to the key. Apple licenses the loops for use in your own music; claudius reads them in place and only caches the one-shots it cuts (in ~/Library/Caches/claudius). In patterns, s("bd sd").bank("apple") plays one-shots cut from them.

Your recordings. .s("/path/file.wav") plays a file as a sampler (pitch by playback speed, c4 as recorded). claudius chop song.mp3 cuts bar loops and drum one-shots from any recording into your library, and --find "a vocal chop" uses the ears to pull out moments that match a description. claudius make --sample file flips a recording into a new song: warped to the tempo, transposed to the key, re-sliced in half-beat pieces (or played straight) and placed in the high-energy sections. See Remaking a song from audio.

How genres choose sounds

Every genre profile lists, per part, the presets and instruments it may use, most preferred first where it matters: "rhodes|epiano" plays the sampled Rhodes when its pack is installed and the FM electric piano when not. Lofi reaches for Rhodes, upright bass, vibes and kalimba; house for 909s, organ basses, stabs and piano; trap for an 808, bells and pizzicato. Drum lanes are played on a recorded machine with a genre-specific chance (909 in 45 % of house songs and 50 % of techno songs, 808 in 60 % of trap songs, the acoustic kit in 30 % of lofi and drum and bass songs) and stay synthesized otherwise. With the packs or Apple Loops missing, those sounds fall back to synthesis and the rest of the song is unchanged: the same seed writes the same notes and drum patterns either way.

Shaping a sound

From a script you choose sounds; you do not edit them. What you can do:

• pick a preset, an instrument, a kit or a file, per track;
• play it differently: velocity, note length, register, glide (overlapping notes on mono presets);
• process a pattern track with .hpf(), .lpf(), .crush() and .distort() (see Inserts), and place it with level, pan and the two sends;
• swap a generated part’s preset with part("chords", #{ preset: "piano" }), which keeps its notes, and a drum lane’s sound with drum_sound("kick", "tr909:bd"), which keeps its pattern.

Synth patch parameters, drum voice parameters, bus chains and the master chain are set by the generator and the genre, and changed by mutation (patch tweaks, drum voice edits, moving a song’s drums to another kit). A filtered, crushed piano:

blank("lofi");
key("D minor"); prog("A", "Dm9 Gm9 Bbmaj7 A7"); bars_per_chord(1);
track("keys", chord("prog").voicing(50, 72).s("piano").lpf(2500).crush(10).room(0.3));

Sounds and the critic

The ears hear recordings and synthesis differently. Songs built only from synthesis read as less “professionally mixed” to earshot than songs with sampled instruments, and as more “computer-generated”. When the production score is low, swapping a synth part for a recorded instrument (piano, Rhodes, strings, a real drum machine) is usually the most effective change. The genre score responds to the genre’s signature sounds: a 909 for house and techno, an 808 for trap, a dusty kit and a Rhodes for lofi.

Arrangement and energy

The arrangement is the form: a list of sections, each with a kind, a length, an energy and the tracks that play in it. In the studio it is the grid of tracks against sections; in a script it is form(). The arranger then does what a producer does by hand: tiles the parts across their sections, switches drum variants, adds fills at phrase ends, rolls and risers into drops, crashes on downbeats, filter sweeps in intros and outros.

Forms by genre

The generator picks one of the genre’s forms. They are a useful starting point for your own:

song(genre, #{ short: true }) halves every section (to at least 4 bars), which is handy for sketching.

The tools for energy

Energy in a track comes from what plays, how dense it is, and the transitions between sections. claudius gives you:

• layers: which tracks play in each section, the strongest tool;
• drum variants: a lane’s sparse, main, alt or half pattern per section;
• progressions: a break on progression B changes colour without changing key (a song without a B plays A there);
• flags: filter_in (a lowpass opening across the section), build (riser, highpass sweep, snare roll, kick out for the last bar), gap (a beat of silence), impact (crash, impact, downlifter on the downbeat), fills (drum fills every 8 bars);
• automatic touches: a crash every 8 bars in drops and hooks, and a lowpass closing over a final outro.

The exact rules (how long the roll is, which tracks a gap silences, where fills fall) are in What the flags do.

Energy values and the critic

Each section’s energy (0 to 1) is a statement of intent, and the critic holds you to it. It measures the master’s short-term loudness (3-second windows, every half second), takes the median of each section (skipping its first 1.5 seconds and last second), and checks:

• that loudness rises and falls with energy: the correlation between the two across sections, which sets most of the arc score;
• that the loudest drop or hook is at least 3 LU louder than the quietest break (aim for 3 to 7).

A low arc score means the energies and the layers disagree. The usual causes:

• an intro with the full kick: drums are never filtered by filter_in, so an intro at energy 0.4 can be as loud as a groove at 0.65; give the intro fewer drum layers or a higher energy;
• a build without a kick that is quieter than the break before it: either keep the kick until the build’s last bar (drum lanes do that by themselves), or give the build a lower energy;
• a break that keeps the bass or the drums: the drop cannot be 3 LU louder than a break that is almost as full.

Building an arrangement

On a generated song, form() rewrites the arrangement with the song’s own tracks:

form([
  sec("intro", 16, "kick hat perc pad").filter_in(),
  sec("groove", 16, "kick clap hat ohat perc bass chords"),
  sec("break", 16, "pad chords lead").energy(0.3),
  sec("build", 8, "clap hat pad lead chords").gap(),
  sec("drop", 32, "*").impact(),
  sec("break", 8, "pad arp").build(),
  sec("drop", 16, "*").energy(1.0).impact(),
  sec("outro", 16, "kick hat perc bass"),
]);

The second break plays progression B (breaks do by default) and builds back into drop2 with a riser, a highpass sweep and a roll on the clap lane (this song has no snare lane). The two drops are named drop and drop2.

Smaller edits leave the rest alone:

section("drop", #{ bars: 32 });                  // a longer drop
section("break", #{ layers: "pad lead" });        // a sparser break
layer("groove", "shaker", true);                  // the shaker in the groove too
section("intro", #{ variant: "main" });           // the full drum patterns in the intro

Patterns in the arrangement

A pattern track plays its pattern from the first bar of each section it is in. It is not rewritten by builds or fills, so a song made of patterns arranges its own builds:

blank("house");
tempo(124); key("A minor"); prog("A", "Am7 Fmaj7 Dm7 Em7"); bars_per_chord(1);
track("kick",  s("bd*4").bank("tr909"));
track("hats",  s("[~ hh]*4").bank("tr909"));
track("clap",  s("~ cp ~ cp").bank("tr909"));
track("roll",  s("<sd*2 sd*2 sd*4 sd*4 sd*8 sd*8 sd*16 sd*16>").bank("tr909")
                 .gain("<0.4 0.45 0.5 0.55 0.65 0.75 0.85 1>"));
track("keys",  chord("prog").struct("x ~ ~ x ~ ~ x ~").s("epiano"));
track("pad",   chord("prog").s("pad").role("pad"));
form([
  sec("intro", 8, "kick hats keys").filter_in(),
  sec("groove", 16, "kick hats clap keys"),
  sec("break", 8, "pad keys").energy(0.3),
  sec("build", 8, "hats clap roll pad").gap(),
  sec("drop", 16, "kick hats clap keys pad").impact(),
]);

The roll track only plays in the build, rising from half notes to sixteenths over its eight bars, and the build flag adds the riser and the highpass sweep. The break plays progression A, since this song has no B. Because the roll’s alternation starts from its first item in every section, it lines up with the build however long the sections before it are.

Length and phrasing

The critic expects a song of 90 to 330 seconds, and every section a whole number of 4-bar phrases; anything else costs form points. Fills fall every 8 bars from the start of a section, and drops and hooks crash every 8 bars, so sections of 8, 16 or 32 bars keep phrases, fills and crashes aligned.

Mixing and mastering

A claudius mix starts where an engineer’s first pass ends: every track at a sensible level for what it is, the kick ducking what should breathe, everything on a bus with glue, and a master landing on a loudness target under a true-peak ceiling. Your work is the second pass. This page explains the signal flow, the genre chains, and how to act on the critic’s mix report. The functions are in Mixing functions.

Signal flow

For every track, in this order:

1. the sound plays its notes, with swing and humanize;
2. its inserts run: the genre’s (a chorus on some pads, tape on lofi keys) or the pattern’s (.hpf() .lpf() .crush() .distort());
3. it is measured while it plays and gained to role target + genre offset + level (limited to −40..+30 dB);
4. it is ducked by the kick by duck;
5. it is panned;
6. it feeds its bus, and the reverb and delay returns by its sends.

Then each bus runs its chain, the buses and the returns (ducked 30 % by the kick) are summed, the master chain runs, and the loudness stage brings the result to the target.

Starting values

Roles first: a track’s role sets its level, and the critic’s theory checks read roles too (see Roles). Then these are reasonable starting points; the genre profiles use similar values for generated parts:

Bus chains by genre

Besides what every song gets (a tanh saturator on the drums bus unless the genre already saturates there, the bass bus mono below 140 Hz, the music bus at width 1.25 and mono below 160 Hz), each genre has its own chains:

The music bus highpass is why pads and chords never fight the bass: anything on the music bus below 90–140 Hz is gone. Give a part the bass role (and so the bass bus) only if it is the bass.

The master

After the chain, the loudness stage searches for the input gain that lands the song on the target (within 0.15 LU), through a soft clipper 0.1 dB under the ceiling and a limiter 0.5 dB under it, then trims if the true peak is still over. master() changes the target (−24 to −5 LUFS) and the ceiling (−3 to −0.1 dBTP, default −1).

Reading the mix report

The critic measures the master and reports each problem as an issue with its numbers. The mix score starts at 1 and loses a little for each:

The band values are each band’s share of the master’s total energy, in dB, so they move together: cutting the sub raises everything else’s share. What usually fixes each:

• too much sub, thin low end: the bass sits too low or is too pure. Lower its level, move it up an octave, or use a bass with harmonics (saw_bass, organ_bass, reese instead of sub_bass); a long 808 kick adds sub too.
• muddy low mids: pads and chords voiced low. Raise their .voicing() range or lower their level.
• recessed mids: the lead and chords are buried; raise them, or choose brighter sounds (piano over a warm pad).
• dull presence, no air: hats, claps, shakers and rides too quiet or too dark. Raise their levels, add an open hat or a ride. Lofi’s master darkens the top end on purpose, so it needs louder hats than other genres.
• fizzy top end: hats and bright synths (supersaws) too loud; lower the hats or .lpf() the synth.
• nearly mono: everything important sits in the middle. Pan the hats and percussion, raise the reverb and delay sends of chords and pads (the returns are wide), prefer sampled stereo instruments for pads.
• low end not mono: a stereo recording below 150 Hz on the drums bus, usually the acoustic kit’s kick (the drums bus is not made mono). Use a 909 or 808 kick.

The ears add a production score: how strongly the master reads as “a professionally mixed and mastered music track” against six named flaws (a cheap synthesized beep, a low quality recording with hiss, a distorted clipped recording, a computer-generated electronic tone, a low bitrate mp3 with artifacts, a recording made on a phone). It moves with sound choice more than with mix settings: sampled instruments and real drum machines help most, and heavy distortion or a buzzy synth lead pull it towards the flaws.

Stems

claudius make --stems and claudius render blueprint.json --stems write every track as its own WAV into stems/, after its level, sidechain and pan and before the buses, so the stems sum to the mix without the bus chains, the returns and the master.

Coming from Strudel or TidalCycles

claudius borrows Strudel’s mini-notation and many of its pattern methods, so most of your patterns carry over. The model around them is different: a Strudel program is a live loop, and a claudius script describes a song (sections, an arrangement, a mix) that is rendered and judged. This page lists every difference that changes what you write.

The same groove in both

Strudel:

setcpm(124/4)
stack(
  s("bd*4, [~ cp]*2, [~ hh]*4").bank("RolandTR909"),
  note("<a1 f1 d2 e2>").struct("~ x ~ x ~ x ~ [x x]").s("sawtooth").lpf(800),
  n("<0 2 4 6>").scale("A:minor").s("piano").room(0.5)
)

claudius:

blank("house");
tempo(124); key("A minor");
track("drums", s("bd*4, [~ cp]*2, [~ hh]*4").bank("RolandTR909"));
track("bass",  note("<a1 f1 d2 e2>").struct("~ x ~ x ~ x ~ [x x]").s("saw_bass").lpf(800));
track("keys",  n("<0 2 4 6>").scale("A:minor").octave(4).s("piano").room(0.5));

Each pattern becomes a named track, the tempo is in BPM, and the sounds are claudius’s: saw_bass is a synth preset, piano a sampled grand, and the Strudel bank name RolandTR909 is an alias of the tr909 pack.

Time

• One cycle is one bar, always. There is no setcps or setcpm; tempo(bpm) sets the song’s tempo, and a cycle lasts four beats of it.
• Patterns play inside sections. A track plays in the sections that list it, and every section starts the pattern from cycle 0: alternations, every() and random choices start over. There is no global clock running through the song.
• Queries return whole events whose onset falls in the span, never fragments. An event longer than a bar exists only in the bar where it starts, though it still sounds for its full length, and .struct(), .mask() and the controls still find it in the bars after (see Patterns and time).

Syntax

Mini-notation

Most of it is identical. The differences (full list):

• { } is a plain group: no polymeter, no %. A fractional .fast() runs a figure across bar lines instead (see Polymeter).
• . is not a separator; it is an error.
• Weights inside < > are ignored: write <a!3 b> to hold a for three cycles.
• * and / take numbers, not patterns, above 0 and up to 256 (so do fast(), slow() and ply()).
• a ! 3 is three as.
• | and , at the same level group differently; bracket the choice: [a | b], c.

Euclidean rhythms are Strudel’s: bd(3,8), bd(5,8,2) and .euclid(7, 16) give the same steps in both. So do slash chords and applied chords, which stay one word: chord("<Am F/A C G>"), chord("<I V7/V>").

Values and controls

• n() is always scale degrees. In Strudel, n() without .scale() is a sample index (or a note number). In claudius, n("0 2 4") without a scale uses the song’s key, and the sample index is bd:3 or the method .n("0 3") on an s() pattern.
• .transpose() is always semitones; .add() adds to the value. On note() both move semitones; on n(), .add(2) moves two scale degrees and .transpose(12) moves an octave. On chord(), .add() moves the voicing range and .transpose() the voiced notes (see add() and transpose()).
• .gain() is velocity. It is how hard a note is played (0 to 1), not an amplitude multiplier: claudius levels every track to its mixing role, so the track’s loudness is set with .level(dB) or mix(). .velocity() is the same control and wins when both are set.
• Note names default to octave 3, as in Strudel: note("c") is C3, MIDI 48.

Effects are per track

Strudel effects are controls on each event; claudius effects belong to the track:

A patterned effect argument is an error: .lpf("<400 2000>") raises lpf needs a number. Filter movement comes from the arrangement instead (an intro’s filter_in, a build’s highpass sweep).

Sounds

• .s() on a note pattern sets the track’s instrument; it takes one name, not a pattern, so a note pattern cannot switch instruments from event to event. Use two tracks.
• sawtooth, square, triangle and sine are not sounds; use a synth preset (saw_bass, pluck, square_lead, sub_bass …).
• Drum names are the usual bd sd cp hh oh rd cr lt mt ht rim cb sh. Without .bank() they play claudius’s synthesized drum voices; with .bank("tr909") (or RolandTR909, 808, acoustic …) the recorded machines. A bank can also go in the word, s("tr909:bd*4, tr808:cp*2"), to mix machines in one pattern; a number after the last colon is the sample index (tr808:sd:3).
• A sound pattern with several names is split into one track per name when arranged (drums.bd, drums.hh), so each is mixed by its own role.

Methods

Available, with the same meaning: fast slow late early rev ply every lastOf sometimes often rarely almostNever almostAlways sometimesBy off superimpose degrade degradeBy struct mask euclid euclidRot gain velocity legato add transpose n s sound bank scale voicing arp. Differences in detail:

• ply() and every() take integers; .every(4, f) is the first bar of every four, like Strudel’s firstOf.
• .arp() takes a mode ("up", "down", "updown"), not an index pattern.
• .voicing() takes a MIDI range; voice leading is always on.
• Randomness is seeded by the code, not by the cycle alone: two tracks with the same pattern make the same choices.

Not available: continuous signals (sine, saw, rand, perlin, range, segment), jux, sample slicing (chop, striate, slice, splice, begin, end, speed, loopAt, fit), chunk, iter, palindrome, echo/stut, when, ADSR and filter-envelope controls, vowel, and the live-coding commands (hush, setcps).

What claudius adds

• A song: sections with energies, builds, gaps, impacts and fills.
• Harmony the song knows about: prog(), Roman numerals, chord("prog"), and chord("prog").root() for a bass line that follows it.
• Parts written by music theory, drum grammars and genre profiles (song()).
• A mix: roles, target levels, sidechain, buses, a mastered result at a LUFS target.
• A critic that tells you what to fix, and evolution that tries fixes for you.

Genres, mutation and evolution

A genre in claudius is a data file: the production knowledge of a style written down as tempo ranges, harmonic styles, forms, drum grammars, part writers, sounds, transitions and mix targets. The generator composes from it, the critic judges against it, and evolution mutates songs within it. This page covers all three.

The genres

claudius genres lists them:

The “against” list matters: the genre score is high only when a song reads as its genre more than as the styles it is usually confused with.

What a profile contains

Each profile (crates/claudius/data/genres/*.json) has:

To add a genre or change one, drop a JSON file with the same fields into the claudius/genres folder of your configuration directory (~/Library/Application Support/claudius/genres/ on macOS, ~/.config/claudius/genres/ on Linux). A file whose name matches a built-in genre replaces it. A good start is a copy of the built-in file closest to what you want.

Making songs

claudius make --genre techno                          # a new song, seeded from the clock
claudius make --genre trap --key "F# minor" --bpm 142 --seed 7 --stems
claudius make --genre deep_house --loops              # built around an Apple Loops family
claudius make --genre lofi --synth-only               # no recordings at all
claudius make --genre house --sample chop.wav         # flip a recording into the song

In a script, song("trap", #{ seed: 7, bpm: 142, key: "F# minor" }) makes the same song, and the edits after it apply on top. --bpm and --key change only the tempo and the key: the title, the form, progression A and the drum patterns are the ones --seed 7 gives without them, except that a key in another mode moves the chords into it, as key() does. The same genre, seed and options make the same song on any machine, in the studio’s New as on the command line; the sample packs and Apple Loops installed change only which recordings it plays.

Mutation

A mutation is one edit a producer might try, chosen from 25 operators:

Operators are not equally likely. The critic’s top four issues raise the weight of the operators that address them, by 1 + 4 × the issue’s severity: band and width problems favour level, sound, kit, patch, space and pan edits; form problems favour the form operators; a part:lead issue favours rewriting the lead; a weak genre reading favours presets, styles, drum grooves and kits, tempo and harmony. Every mutation records what it did, and the song keeps the list as its lineage.

Mutation edits what the generator writes: drum lanes, parts, loops and their mix. Pattern tracks are moved between sections and follow tempo, key and swing, but their code is never changed.

claudius mutate out/house-crimson-tide-9/blueprint.json -n 4 writes four mutated variants into mutations/ next to it, each rendered and judged, with what changed. The MCP tool mutate tries a few variations of the open song and keeps the best if it beats the current one.

Evolution

claudius evolve runs a (μ + λ) evolution: it starts from fresh songs (or --from a blueprint), and in each generation the best songs so far are parents of new children, each made by one or two mutations or by a crossover of two parents (drums and form from one, harmony and parts from the other) followed by mutations. A child identical to one already heard is skipped. Each candidate is judged on a preview, the build-up into the first drop and the drop (--preview-bars, 32 by default), and at the end the best are rendered in full.

A short run, two generations of four children from two deep house songs:

claudius evolve --genre deep_house --seed 4 --start 2 --generations 2 --children 4 --keep 1

ears loaded in 3.7 s
evolving deep_house (2 start, 2 generations x 4 children, 32-bar previews, with ears)
  g0-0  78.4  Velvet Orbit
  g0-1  86.5  Hollow Harbor
  g1-0  86.1  from g0-1: key Bb dorian -> Eb dorian
  g1-1  86.4  from g0-1: form: clap out of build
  g1-2  84.9  from g0-1: hat: sampled hh (tr909:hh) -> hat cut from 'Times of Plenty Open Hi-Hat' (Apple Loops); key Bb dorian -> F# dorian
  g1-3  85.9  from g0-1: harmony A: i7 IV7 -> i7 iv7 v7 i7 (minor_soul); mix: shaker +2.0 dB (now +2.0)
generation 1: best 86.5
  g2-0  85.1  from g0-1: crossover: drums and form of one parent, harmony and parts of the other; drums (sparse): re-accented a hat hit; key Bb dorian -> G dorian
  g2-1  86.1  from g0-1: form: drop loses fills
  g2-2  84.8  from g1-3: form: build now 4 bars; form: groove loses fills
  g2-3  85.8  from g1-0: crossover: drums and form of one parent, harmony and parts of the other; mix: chords sidechain depth 0.28; mix: kick -1.8 dB (now -1.8)
generation 2: best 86.5
searched 10 candidates in 17 s; rendering the best 1 in full
#1 g0-1 (Hollow Harbor): preview 86.5, full song 86.1

A + marks a child that beats the best parent. In this short run none did, so the winner is a starting song, g0-1, and its full render scores a little under its preview (the preview hears only the build and the first drop). Small differences in score are within the critic’s noise, so treat a gain of half a point as a draw and listen. Evolution is most useful from a weak start (a score in the 70s, like g0-0) or aimed at one problem, and less so for polishing a song that already scores well.

The MCP tool evolve does the same on the open song; a generation takes 10 to 40 seconds.

Judging against references

--refs <files or folders> on make, script, evolve, render and judge adds a typicality score: how close the song’s ears embedding is to a set of reference tracks you choose (at least two). It counts as a sixth score with the same weight as genre and production, and an issue appears when the song is unlike the references.

What the score is

The total is a weighted mean: mix 0.3, arc 0.2, theory 0.2, and with the ears genre 0.15 and production 0.15 (plus references 0.15 when given). A high score means no measurable problems and a confident genre reading, not a hit. Optimising against the ears can please the models without the music getting better, which is earshot’s own warning; judge finished songs by ear.

House, deep house and techno

Three styles built on the same foundation, a kick on every beat, and different in nearly everything else: house is warm and swung with piano and vocals, deep house is slower and jazzier, techno is hypnotic, dark and dry. Each recipe below is a complete song from a blank start, with the reasons for its choices and the critic’s verdict when we rendered it. They use sampled instruments and drum machines, so they need the default sample packs (claudius setup).

Save a recipe as a .rhai file and render it with claudius script house.rhai.

House: “Glass Avenue”

blank("house");
title("Glass Avenue");
tempo(122); key("A minor"); swing(0.58);
prog("A", "Am7 Fmaj7 Dm7 Em7");
prog("B", "Fmaj7 G Em7 Am7");
bars_per_chord(1);

track("kick",  s("bd*4").bank("tr909"));
track("clap",  s("~ cp ~ cp").bank("tr909").room(0.2));
track("hat",   s("[~ hh]*4").bank("tr808").gain(0.7).pan(0.15));
track("ohat",  s("[~ oh]*4").bank("tr909").gain(0.5).pan(-0.15));
track("shaker", s("shaker*8").gain("[0.3 0.6]*4").pan(-0.3).level(-3));
track("roll",  s("<sd*2 sd*2 sd*4 sd*4 sd*8 sd*8 sd*8 sd*8>").bank("tr909")
                 .gain("<0.4 0.45 0.5 0.55 0.65 0.75 0.85 1>"));

track("bass",   note("<a1 f1 d2 e2>").struct("~ x ~ x ~ x ~ [x x]").s("organ_bass").legato(0.7));
track("chords", chord("prog").struct("x ~ ~ x ~ ~ x ~").voicing(55, 74).s("piano").legato(0.5).room(0.2).level(2));
track("pad",    chord("prog").voicing(52, 72).s("string_ensemble").role("pad").level(-2).room(0.35));
track("vox",    note("<[~ ~ e3 ~ ~ ~ c3 ~] [~ ~ a2 ~ ~ ~ c3 ~] [~ ~ a2 ~ ~ ~ f2 ~] [~ ~ b2 ~ ~ ~ ~ ~]>").s("voice").role("vocal").legato(0.9).room(0.3).delay(0.15).level(-4));
track("lead",   n("<[4 ~ 4 2 4 ~ 6 4] [5 ~ 5 4 2 ~ 0 ~] [3 ~ 3 2 0 ~ 2 3] [4 ~ ~ 6 4 ~ ~ ~]>")
                  .octave(4).s("rhodes").room(0.25).delay(0.2));

form([
  sec("intro", 8, "kick hat shaker chords").filter_in(),
  sec("groove", 16, "kick clap hat shaker bass chords"),
  sec("break", 8, "pad chords"),
  sec("build", 8, "kick clap hat pad lead roll").gap(),
  sec("drop", 16, "kick clap hat ohat shaker bass chords pad lead vox").impact(),
  sec("outro", 8, "kick hat shaker bass"),
]);

Why it is built this way:

• Tempo and swing. 122 BPM sits in the middle of house’s range. Swing 0.58 is on the heavy side for house; it makes the shaker and the bass pickups lean, which reads as warmth rather than as techno’s grid.
• Harmony. Am7 Fmaj7 Dm7 Em7 is the minor-soul progression (i7 VImaj7 iv7 v7): sevenths everywhere, no dominant pull, so it loops forever. The break moves to B, which lifts to G before falling back.
• Drums. A 909 kick and clap, the instruments of house. The closed hat comes from the 808 because it is softer than the 909’s, and the open hat on the same offbeats gives the classic “tss” lift in the drop only. The roll doubles every two bars across the 8-bar build, and stops at eighths: house builds less violently than trance.
• Bass. An organ bass on the offbeats, with a sixteenth pickup at the end of each bar ([x x]), plays between the kicks instead of on them, which is the house bounce. It sits on the roots of the progression.
• Chords. A sampled grand piano on the tresillo rhythm (x ~ ~ x ~ ~ x ~), the sound of 90s house.
• Vocal. The voice pack’s sung vowel plays a two-note answer in each bar of the drop. Pitched low, inside the recording’s range, it sounds like a vocal chop rather than a synth.
• Lead. A Rhodes motif with chord tones on beats 1 and 3, enters in the build so the drop is a return, not a surprise.
• Form. The intro’s filter_in() opens a lowpass on the piano over eight bars; the drums are never filtered, so the intro needs a music part for the sweep to be heard. The build keeps the kick (pattern tracks get no automatic kick drop-out), so its energy rises into the drop rather than dipping; the gap() gives the drop its breath.

The critic’s verdict:

  ears: 'house music' z +3.6 (closest confusion 'techno music' +3.4); production z +1.6 vs 'a low quality recording with hiss' +1.0; p_real 0.65
        sounds like: house music, techno music, tech house music, drum and bass music
  verdict: 87/100 (arc 0.85, genre 0.79, mix 0.93, production 0.66, theory 1.00). Fix first: dull 4-8 kHz: hats, claps and snare lack bite (presence -28.7 dB, healthy from -26); fizzy top end (air -16.1 dB, healthy up to -17)

House and techno sit close together for the ears, and a 909 groove pulls towards techno. An earlier version of this recipe had only drums in the intro and read as techno (sounds more like 'techno music' than 'house music', by z +3.5 to +3.4); putting the filtered piano in the intro tipped it to house. The mix notes point at the hats: there is too much above 8 kHz and not enough at 4 to 8 kHz, which a brighter clap and a darker hat would balance.

Try:

• Swap the piano for a Rhodes (.s("rhodes")) and the lead for a piano for a deeper, softer track.
• Replace the offbeat bass with the root on every beat, struct("x*4"), for a harder, more driving groove.
• Put the vocal in the build too, so its hook is introduced before the drop.

Deep house: “Velvet Hours”

blank("deep_house");
title("Velvet Hours");
tempo(121); key("F minor"); swing(0.57);
prog("A", "Fm9 Bbm9 Dbmaj7 Cm7");
prog("B", "Dbmaj7 Cm7 Bbm9 Bbm9");
bars_per_chord(1);

track("kick",   s("bd*4").bank("tr909").gain(0.9));
track("rim",    s("~ ~ rim ~ ~ ~ rim ~ ~ ~ rim ~ ~ rim ~ ~").bank("tr909").gain(0.6).pan(0.3).delay(0.1));
track("hat",    s("[~ hh]*4").bank("tr808").gain(0.6).pan(0.2));
track("shaker", s("shaker*8").gain("[0.3 0.55]*4").pan(-0.3).level(-2));
track("clap",   s("~ cp ~ cp").bank("tr808").room(0.3).level(-2));

track("bass",   note("<f1 bb1 db2 c2>").struct("x ~ ~ x ~ ~ x ~ ~ ~ x ~ ~ ~ ~ ~").s("sub_bass").legato(0.8));
track("chords", chord("prog").struct("x ~ ~ x ~ ~ ~ ~").voicing(53, 72).s("rhodes").room(0.3).delay(0.12));
track("pad",    chord("prog").voicing(50, 74).s("warm_pad").role("pad").level(-3).room(0.4));
track("lead",   n("<[4 ~ ~ 6 4 ~ 2 ~] [2 ~ ~ 4 3 ~ ~ ~] [4 ~ 5 4 2 ~ ~ ~] [~ ~ 1 2 4 ~ ~ ~]>")
                  .octave(4).s("vibes").room(0.35).delay(0.25));

form([
  sec("intro", 8, "kick hat shaker rim chords").filter_in(),
  sec("groove", 16, "kick hat shaker rim clap bass chords"),
  sec("break", 8, "pad chords"),
  sec("build", 8, "kick hat shaker pad chords lead"),
  sec("drop", 16, "kick hat shaker rim clap bass chords pad lead"),
  sec("outro", 8, "kick hat shaker rim bass"),
]);

Why:

• Slower and swung. 121 BPM and swing 0.57: deep house walks where house runs.
• Ninth chords. C is a note of all four chords in Fm9 Bbm9 Dbmaj7 Cm7, so the voice-led Rhodes voicings barely move and the harmony shimmers rather than steps. The lead does the same: its strong beats land on C and A♭, notes most of the chords share.
• The Rhodes plays only twice a bar, on the charleston rhythm (x ~ ~ x), leaving air. Space is the style.
• Softer drums. The 808’s clap and hat are rounder than the 909’s; the rim shot on a syncopated pattern with a touch of delay is the deep house percussion signature.
• Sub bass on a syncopated pattern (x ~ ~ x ~ ~ x ~ ~ ~ x): felt more than heard, under warm sounds.
• No impact. Deep house prefers a riser and a downlifter to a crash and a boom; the genre’s transitions leave the impact out, and the drop has no impact().

  ears: 'house music' z +3.8 (closest confusion 'minimal electronic music' +3.1); production z +1.9 vs 'a low quality recording with hiss' +1.3; p_real 0.52
        sounds like: house music, tech house music, minimal electronic music, drum and bass music
  verdict: 86/100 (arc 0.81, genre 0.91, mix 0.90, production 0.63, theory 1.00). Fix first: dull 4-8 kHz: hats, claps and snare lack bite (presence -31.2 dB, healthy from -26)

The deep house genre score is strong: the ears hear house clearly over its confusions. The one issue, a dull presence range, is the style’s own softness (808 hats, a warm pad, a lowpassed master); raising the clap and the hat by 2 to 3 dB fixes it if you want it brighter.

Try:

• prog("A", "Gm9 C9 Gm9 C9") with key("G dorian"): the dorian vamp, two chords for the whole track.
• A walking bass through each chord’s notes, one per beat: note("<[f1 ab1 c2 eb2] [bb1 db2 f2 ab1] [db2 f2 ab2 c2] [c2 eb2 g2 bb1]>") without the struct().

Techno: “Hollow Engine”

blank("techno");
title("Hollow Engine");
tempo(130); key("F phrygian"); swing(0.5);
prog("A", "i i II i");
prog("B", "i");
bars_per_chord(2);

track("kick",  s("bd*4").bank("tr909"));
track("hat",   s("hh*16").bank("tr909").gain("[0.35 0.25 0.7 0.25]*4").pan(0.35));
track("ohat",  s("[~ oh]*4").bank("tr909").gain(0.6).pan(-0.3).room(0.2));
track("clap",  s("~ cp ~ cp").bank("tr909").room(0.25).level(-2));
track("rim",   s("rim(5,16,2)").bank("tr909").gain(0.7).pan(0.35).delay(0.2));
track("ride",  s("[~ rd]*4").bank("tr909").gain(0.5).pan(0.25));
track("roll",  s("<cp*2 cp*4 cp*8 [cp*16]>").bank("tr909").gain("<0.5 0.65 0.8 1>"));

track("bass",  note("<f1!4 gb1!2 f1!2>").struct("[~ x x x]*4").s("saw_bass").legato(0.6).level(-3));
track("acid",  note("f2 f2 f3 f2 ab2 f2 gb2 f2 f2 c3 f2 eb3 f2 f2 db3 f2")
                 .velocity("1 0.6 0.9 0.6 0.7 0.6 1 0.6 0.6 0.9 0.6 1 0.6 0.6 0.9 0.7")
                 .legato(0.7).s("acid").role("synth").delay(0.3).pan(0.2).level(-4));
track("stab",  chord("prog").struct("~ x ~ ~ ~ ~ x ~").voicing(52, 70).s("stab").room(0.5).delay(0.4).pan(-0.2).level(-1));
track("pad",   chord("prog").voicing(45, 70).s("warm_pad").role("pad").room(0.45).level(-2));

form([
  sec("intro", 8, "kick hat rim stab").filter_in(),
  sec("groove", 16, "kick hat ohat clap rim bass"),
  sec("break", 8, "pad stab acid").prog("A"),
  sec("build", 8, "kick hat clap acid roll").gap(),
  sec("drop", 16, "kick hat ohat clap rim ride bass stab pad").impact(),
  sec("outro", 8, "kick hat rim"),
]);

Why:

• Phrygian. F phrygian has a G♭ a semitone above the tonic, and the progression only moves between F minor and G♭ (i i II i, two bars a chord). That half step is the darkness of techno; there is almost no harmony beyond it.
• A rolling bass. Three sixteenths after every kick ([~ x x x]*4), never on the beat, so kick and bass interlock into one continuous low-end engine. saw_bass keeps it audible without piling on sub.
• An acid line, sixteen steps with accents written as velocities: the acid preset’s resonant filter opens on the loud steps, which is the 303 sound. It plays in the break and the build, then leaves the drop to the drums and stabs.
• Euclidean percussion. rim(5,16,2) spreads five rim shots over the bar against the four kicks, and the ride joins in the drop. Panned hats, rim and ride keep the dry, mono-heavy low end from making the whole track mono.
• Stabs with long delay and reverb fill the space between hits, two per bar, and turn into echoes.
• A clap roll instead of a snare: techno builds on the clap.

  ears: 'techno music' z +4.5 (closest confusion 'drum and bass music' +3.5); production z +1.3 vs 'a distorted clipped recording' +1.5; p_real 0.63
        sounds like: techno music, drum and bass music, tech house music, house music
  verdict: 86/100 (arc 0.82, genre 1.00, mix 0.92, production 0.45, theory 1.00). Fix first: nearly mono (correlation 0.97): widen pads, chords and effects; sounds about as much like a clipped recording as a professional mix: less drive and saturation, or a quieter master

A perfect genre score: nothing about this reads as anything but techno. The production score is the weak point; the ears hear the saturated 909, the drive of the acid and the techno master’s saturation as close to “distorted”. That is partly the style. Lowering the acid further, or keeping it out of the build too, raises production at some cost to character; the call is yours.

Try:

• A 32-bar intro and groove, as techno DJs expect: change the bar counts and nothing else.
• prog("B", "i") is there for a reason: put .prog("B") on the break for eight bars of pure F minor.
• Replace the acid with stabs on every offbeat, struct("[~ x]*4"), for a 90s Detroit feel.

Trap and lofi

Two descendants of hip-hop at opposite ends: trap is fast hi-hats, a booming 808 and dark minor melodies at 140 BPM in half time; lofi is a dusty, swung loop of jazz chords at 84 BPM that sounds like a worn record. Both recipes need the default sample packs (claudius setup).

Trap: “Paper Satellite”

blank("trap");
title("Paper Satellite");
tempo(140); key("C harmonic minor"); swing(0.5);
prog("A", "Cm Ab Fm G");
prog("B", "Ab G Cm Cm");
bars_per_chord(2);

track("kick",  s("bd ~ ~ ~ ~ ~ ~ bd ~ ~ bd ~ ~ ~ ~ ~").bank("tr808"));
track("clap",  s("~ ~ [cp, sd] ~").bank("tr808").room(0.2));
track("hat",   s("<[hh*2 hh*2 hh*2 hh*2] [hh*2 hh*2 hh*2 hh*6] [hh*2 hh*2 hh*2 hh*2] [hh*2 hh*4 hh*2 hh*8]>")
                 .bank("tr808").gain("[0.9 0.6]*4").pan(0.12));
track("ohat",  s("~ ~ ~ oh ~ ~ ~ ~").bank("tr808").gain(0.5).pan(-0.2));
track("808",   note("<c2!2 ab1!2 f1!2 g1!2>").struct("x ~ ~ ~ ~ ~ ~ x ~ ~ x ~ ~ ~ ~ ~").s("808").legato(1.0).duck(0));

track("keys",  chord("prog").voicing(55, 72).s("piano").room(0.3).level(-1));
track("pad",   chord("prog").voicing(48, 70).s("choir").role("pad").room(0.4).level(-4));
track("lead",  n("<[7 ~ 6 7 4 ~ ~ ~] [~ ~ 2 3 4 ~ 2 ~] [7 ~ 6 7 5 ~ ~ ~] [~ ~ 4 5 7 ~ 5 ~] [5 ~ 4 5 3 ~ ~ ~] [~ ~ 2 3 5 ~ 3 ~] [6 ~ 4 6 8 ~ ~ ~] [4 ~ ~ ~ 6 ~ ~ ~]>")
                 .octave(4).s("bell").room(0.3).delay(0.25));

form([
  sec("intro", 8, "keys pad lead").filter_in(),
  sec("hook", 16, "kick clap hat ohat 808 keys pad lead").impact(),
  sec("verse", 16, "kick clap hat 808 keys"),
  sec("hook", 16, "kick clap hat ohat 808 keys pad lead").impact(),
  sec("outro", 8, "keys pad lead"),
]);

Why:

• Half time. At 140 BPM the clap lands on beat 3 only (~ ~ [cp, sd] ~), so the groove feels like 70 BPM while the hats run at full speed. The clap is layered with the snare in one step ([cp, sd]), a standard trap trick for a thicker backbeat.
• Hi-hat rolls. The hats are written beat by beat, with a sixteenth-triplet roll (hh*6) on the last beat of bar 2, and sixteenths on beat 2 and thirty-seconds on beat 4 of bar 4. The <...> cycles four bars, so the rolls come back at the same place in every phrase, and the accents ([0.9 0.6]*4) keep the eighths from sounding like a machine gun.
• The 808 is the bass. It shares the kick’s rhythm exactly (x ~ ~ ~ ~ ~ ~ x ~ ~ x), holds each note until the next (legato(1.0)), and follows the chord roots two bars at a time (<c2!2 ab1!2 f1!2 g1!2>). duck(0) turns off the sidechain that pattern tracks get by default: ducking an 808 under a kick on the same beat would cut off its attack.
• Harmonic minor. C harmonic minor gives G major as the fifth chord (Cm Ab Fm G), with a B that pulls hard back to C: the dark, classical tension of a lot of trap. The bell melody uses that B on the G chord.
• Choir and piano. A sustained piano and a low choir pad are the cinematic bed under the drums; the verse drops the choir, the open hat and the lead so the hook has somewhere to return to.

  ears: 'trap beat' z +3.4 (closest confusion 'hip hop beat with heavy bass' +3.2); production z +1.0 vs 'a recording made on a phone' +0.8; p_real 0.30
        sounds like: trap beat, hip hop beat with heavy bass, lo-fi hip hop beat, a success chime
  verdict: 88/100 (arc 0.97, genre 0.79, mix 0.94, production 0.56, theory 1.00). Fix first: too much sub (boomy): lower the bass / kick, or highpass the music bus (sub -1.8 dB, healthy up to -4); a thin low end: bass or kick too quiet (low -7.7 dB, healthy from -7); sounds about as much like a phone recording as a professional mix: a thin or narrow mix is the usual cause

The low end is the 808’s: a lot of sub, not much above it. That is trap’s sound and the critic’s taste disagreeing. Drive on the 808 (.distort(6)) adds harmonics in the 60–250 Hz band, where small speakers can hear it, without changing its notes; .level(-2) on it trims the sub.

Try:

• Glide: overlap the 808 notes (legato(1.2)) and they slide into each other, since the 808 preset has glide.
• A sparser verse: section("verse", #{ layers: "kick clap 808 keys" }) takes the hats out too.
• Swap the bell for pizzicato or flute (sampled), two other trap lead sounds.

Lofi: “Rain on the Avenue”

blank("lofi");
title("Rain on the Avenue");
tempo(84); key("F major"); swing(0.6);
prog("A", "Gm9 C9 Fmaj9 Dm9");
prog("B", "Bbmaj7 C9 Am7 Dm9");
bars_per_chord(1);

track("kick",  s("bd ~ ~ ~ ~ ~ ~ bd ~ ~ bd ~ ~ ~ ~ ~").bank("tr808").gain(0.9));
track("snare", s("~ sd ~ sd").bank("acoustic").gain(0.8).room(0.15));
track("hat",   s("hh*8?0.1").bank("tr808").gain("[0.6 0.35]*4").pan(0.2).level(4));
track("ohat",  s("~ ~ ~ ~ ~ ~ ~ oh").bank("tr808").gain(0.5).pan(-0.2).level(2));

track("bass",  note("<g1 c2 f1 d2>").struct("x ~ ~ x ~ x ~ ~").s("upright_bass").legato(0.9));
track("keys",  chord("prog").struct("x ~ ~ ~ ~ x ~ ~").voicing(50, 72).s("rhodes").room(0.3).late(0.02));
track("lead",  n("<[2 ~ ~ 1 2 ~ 4 ~] [~ ~ 4 3 1 ~ ~ ~] [2 ~ ~ 4 6 ~ 4 ~] [5 ~ 4 2 0 ~ ~ ~]>")
                 .octave(4).s("kalimba").room(0.35).delay(0.2).level(-1));

form([
  sec("intro", 4, "keys").filter_in(),
  sec("verse", 16, "kick snare hat bass keys"),
  sec("hook", 16, "kick snare hat ohat bass keys lead"),
  sec("verse", 16, "kick snare hat ohat bass keys lead"),
  sec("outro", 8, "keys lead"),
]);

Why:

• The ii–V–I. Gm9 C9 Fmaj9 Dm9 is the jazz cadence in F major with ninths on every chord, then the relative minor to loop back. Lofi borrows its harmony from jazz; the ninths are what make it sound wistful rather than plain.
• Heavy swing and lazy keys. Swing 0.6 drags every off-beat sixteenth, and .late(0.02) puts the Rhodes a hair behind the beat, like a player leaning back. The keys play on beat 1 and the and of 3 only.
• Mixed kits. An 808 kick (mono, deep) with the acoustic kit’s snare (a real drum in a room), and 808 hats with ?0.1 dropping one hit in ten so the pattern never repeats exactly. The kick plays on beat 1, on the last sixteenth of beat 2 and on the and of 3: a boom-bap pattern that pushes into the second half of the bar.
• Upright bass on the chord roots with long notes, and a kalimba melody: acoustic, plucked, warm.
• The genre does the rest. blank("lofi") brings lofi’s mix: a bitcrusher and a lowpass on the drums bus, tape wow and flutter, vinyl crackle and hiss on the master, and a quiet −12.5 LUFS target. That darkening is why the hats are 4 dB up: without it the critic finds no air above 8 kHz.

  ears: 'lo-fi hip hop beat' z +4.0 (closest confusion 'hip hop beat with heavy bass' +3.3); production z +2.0 vs 'a distorted clipped recording' +1.5; p_real 0.32
        sounds like: lo-fi hip hop beat, hip hop beat with heavy bass, jazz music, minimal electronic music
  verdict: 90/100 (arc 0.90, genre 0.92, mix 0.97, production 0.64, theory 1.00). Fix first: recessed mids: the lead and chords are buried (mid -19.0 dB, healthy from -18); too much sub (boomy): lower the bass / kick, or highpass the music bus (sub -3.2 dB, healthy up to -4)

The ears hear hiss, because there is hiss: the vinyl on the master is the style. So lofi’s production reading leaves hiss out, and the thin sound of a phone recording that a lowpassed drum bus has, and compares the master with the next flaw instead, here clipping. The first version of this recipe used the acoustic kit’s kick and a vibraphone lead, and the critic read it as jazz (sounds more like 'jazz music' than 'lo-fi hip hop beat') and found the low end not mono (the acoustic kick is a stereo room recording). The 808 kick and the kalimba fixed both.

Try:

• .s("piano") on the keys and .lpf(3000) for a muffled, sampled-from-a-record piano.
• swing(0.66) for a full triplet shuffle.
• A B section: sec("hook", 16, ...).prog("B") plays the Bbmaj7 C9 Am7 Dm9 progression, but write a second lead for it, since this one fits A.

Drum and bass, synthwave, future bass

Three styles that lean on synthesizers: liquid drum and bass with a rolling breakbeat under pads, synthwave’s eighties arpeggios and gated drums, and future bass’s pumping supersaw chords. All three use sampled drums, so they need the default sample packs (claudius setup).

Drum and bass: “Liquid Orbit”

blank("dnb");
title("Liquid Orbit");
tempo(174); key("F minor"); swing(0.5);
prog("A", "Fm Db Ab Eb");
prog("B", "Db Eb Fm Fm");
bars_per_chord(2);

track("kick",  s("bd ~ ~ ~ ~ ~ ~ ~ ~ ~ bd ~ ~ ~ ~ ~").bank("acoustic"));
track("snare", stack([s("~ sd ~ sd"), s("~ ~ ~ ~ ~ ~ ~ sd:1 ~ ~ sd:1 ~ ~ ~ ~ ~").gain(0.35)]).bank("acoustic").room(0.15));
track("hat",   s("hh*8").bank("acoustic").gain("[0.7 0.45]*4").pan(0.15));
track("ride",  s("[~ rd]*4").bank("acoustic").gain(0.45).pan(-0.2));

track("bass",  note("<f1!2 db1!2 ab1!2 eb1!2>").s("reese").legato(1.0));
track("pad",   chord("prog").voicing(48, 72).s("pad").role("pad").room(0.4).level(-2));
track("arp",   chord("prog").struct("x x").arp("updown").voicing(60, 76).s("pluck").role("arp").delay(0.3).room(0.3));
track("keys",  chord("prog").struct("x ~ ~ x ~ ~ x ~").voicing(55, 72).s("rhodes").room(0.3).level(-2));

form([
  sec("intro", 16, "pad arp").filter_in(),
  sec("build", 8, "hat ride pad arp keys").gap(),
  sec("drop", 32, "kick snare hat ride bass pad arp keys").impact(),
  sec("break", 16, "pad arp keys"),
  sec("drop", 16, "kick snare hat ride bass pad arp keys").impact(),
  sec("outro", 8, "pad arp"),
]);

Why:

• The two-step. At 174 BPM, a kick on beat 1 and on the and of 3 (bd ~ ~ ~ ~ ~ ~ ~ ~ ~ bd), with the snare on 2 and 4: the basic drum and bass rhythm. Two ghost snares (variation sd:1, at a third of the level) in a separate layer of the stack() give it the shuffle of a chopped breakbeat; a gain pattern on the whole snare would have turned down the backbeat with them.
• A recorded kit. The acoustic kit sounds like a sampled break, which is where the style comes from. The ride on the offbeats keeps the top end moving at half the hats’ rate.
• Reese bass. Two detuned saws a bar at a time, on the chord roots two bars each, so the bass is one slow, growling movement under fast drums.
• Three harmonic layers at three speeds: a pad holding the chords, a Rhodes on a slow syncopated rhythm, and a pluck arpeggio (updown over two events a bar) running eighths with a long delay.
• Long sections. Drum and bass phrases are long; the first drop is 32 bars, and the song is 96 bars, 2:12 at 174 BPM. Anything under 90 seconds would cost form points.

  ears: 'drum and bass music' z +3.4 (closest confusion 'techno music' +2.7); production z +1.1 vs 'a low quality recording with hiss' +0.3; p_real 0.76
        sounds like: drum and bass music, energetic and driving music, synthwave music, inspirational corporate background music
  verdict: 93/100 (arc 0.96, genre 0.88, mix 0.99, production 0.72, theory 1.00). Fix first: dull 4-8 kHz: hats, claps and snare lack bite (presence -26.5 dB, healthy from -26)

The best score in the cookbook. The energy arc is nearly perfect because the sections are clearly layered: the intro and break have no drums at all, the drops have everything.

Try:

• .s("wobble") on the bass for a heavier, neurofunk movement (its filter LFO is tempo-synced).
• Busier hats: hh*16 with .gain("[0.7 0.3 0.5 0.3]*4") for a rolling sixteenth feel.
• Replace the arp with a lead melody in F minor, with chord tones on beats 1 and 3 of each bar.

Synthwave: “Neon Harbor”

blank("synthwave");
title("Neon Harbor");
tempo(100); key("A minor"); swing(0.5);
prog("A", "Am F C G");
prog("B", "F G Am Am");
bars_per_chord(1);

track("kick",  s("bd ~ bd ~").bank("tr707"));
track("snare", s("~ sd ~ sd").bank("tr707").room(0.45));
track("hat",   s("hh*16").bank("tr707").gain("[0.6 0.3 0.45 0.3]*4").pan(0.2));

track("bass",  note("<[a1 a2]*4 [f1 f2]*4 [c2 c3]*4 [g1 g2]*4>").s("saw_bass").legato(0.8));
track("arp",   chord("prog").struct("x*4").arp("updown").voicing(57, 76).s("pluck").role("arp").delay(0.25).pan(0.15));
track("pad",   chord("prog").voicing(52, 76).s("strings").role("pad").room(0.45).level(-2));
track("lead",  n("<[4 ~ ~ 4 2 ~ 0 ~] [0 ~ ~ 2 5 ~ 4 ~] [4 ~ ~ 4 6 ~ 4 ~] [6 ~ ~ 4 3 ~ ~ ~]>")
                 .octave(4).s("square_lead").room(0.3).delay(0.2));

form([
  sec("intro", 8, "pad arp").filter_in(),
  sec("verse", 16, "kick snare hat bass arp pad"),
  sec("chorus", 16, "kick snare hat bass arp pad lead").impact(),
  sec("break", 8, "pad lead").prog("A"),
  sec("chorus", 16, "kick snare hat bass arp pad lead").impact(),
  sec("outro", 8, "pad arp"),
]);

Why:

• The 707. Roland’s TR-707 is the drum machine of eighties pop. A kick on 1 and 3, a snare on 2 and 4 with a lot of reverb: the big, simple backbeat of the decade.
• Octave bass. Each bar alternates the root and its octave in eighths ([a1 a2]*4), the driving bass of synth pop, on a buzzy saw_bass.
• Arpeggios in sixteenths. chord("prog").struct("x*4").arp("updown") gives four notes per beat from a triad (up and down without repeating the ends is four steps), so the arpeggio is straight sixteenths and always on the right chord.
• String machine and square lead. strings is the synth preset, slow attack and vibrato, more Juno than orchestra; square_lead is a mono square wave with delayed vibrato. Both are synthesized on purpose: this is the one style where “computer-generated” is the aesthetic.
• A pop form. Verse, chorus, a short break with only pad and lead, and the chorus again: synthwave is song-shaped rather than DJ-shaped.

  ears: 'synthwave music' z +3.5 (closest confusion 'upbeat corporate pop music' +3.0); production z +0.5 vs 'a cheap synthesized beep' +0.3; p_real 0.61
        sounds like: synthwave music, inspirational corporate background music, uplifting and hopeful music, upbeat corporate pop music
  verdict: 90/100 (arc 0.95, genre 0.87, mix 1.00, production 0.55, theory 1.00). Fix first: sounds about as much like a cheap synth as a professional mix: sampled instruments in place of synth patches usually read better

The ears’ worst flaw is “a cheap synthesized beep”, which for synthwave is half the point. A sampled string_ensemble pad instead of the strings synth would raise production and make it less eighties.

Try:

• tempo(86) makes it outrun-slow; tempo(118) makes it italo disco.
• A tom fill in the last beat of every fourth bar, with a big reverb: track("toms", s("<~ ~ ~ [~ ~ ~ [lt mt ht ht]]>").bank("tr707").room(0.5)), added to the choruses’ layers.
• key("F# minor") and render again: the chords, the arpeggio and the lead follow, because they are written with prog and n(). The bass is written in note names and stays in A; move it with .transpose(-3).

Future bass: “Golden Bloom”

blank("future_bass");
title("Golden Bloom");
tempo(150); key("D major"); swing(0.5);
prog("A", "Dmaj9 A Bm9 Gmaj9");
prog("B", "Gmaj9 A Bm9 Bm9");
bars_per_chord(1);

track("kick",  s("bd ~ ~ ~ ~ ~ ~ ~ ~ ~ bd ~ ~ ~ ~ ~").bank("tr909"));
track("clap",  s("~ ~ [cp, sd] ~").bank("tr808").room(0.25));
track("hat",   s("[~ hh]*4, ~ ~ ~ [~ hh hh hh]").bank("tr808").gain(0.6).pan(0.2).level(-3));

track("bass",   note("<d2 a1 b1 g1>").struct("x ~ ~ ~ ~ ~ ~ ~ ~ ~ x ~ ~ ~ ~ ~").s("saw_bass").legato(1.0).level(-3));
track("chords", chord("prog").struct("x ~ ~ x ~ ~ x ~ ~ ~ x ~ x ~ ~ ~").voicing(55, 79).s("supersaw").legato(0.9).duck(0.85).room(0.25).level(2));
track("pad",    chord("prog").voicing(50, 74).s("pad").role("pad").room(0.4).level(-3));
track("lead",   n("<[4 ~ 2 ~ 4 ~ 5 4] [6 ~ 4 ~ 6 ~ 7 6] [5 ~ 4 ~ 2 ~ 4 ~] [3 ~ 2 ~ 4 ~ ~ ~]>")
                  .octave(4).s("pluck").room(0.3).delay(0.25));

form([
  sec("intro", 8, "pad lead").filter_in(),
  sec("verse", 16, "kick clap hat bass pad lead"),
  sec("build", 8, "clap hat chords pad").gap(),
  sec("drop", 16, "kick clap hat bass chords lead").impact(),
  sec("break", 8, "pad lead"),
  sec("build", 8, "clap hat chords pad").gap(),
  sec("drop", 16, "kick clap hat bass chords lead pad").impact(),
  sec("outro", 8, "pad lead"),
]);

Why:

• The pump. The supersaw chords duck under the kick at depth 0.85: they nearly vanish on every kick and swell back, which is the future-bass sound. The kick only plays twice a bar (beat 1 and the and of 3), so the swells are long.
• Syncopated chords. x ~ ~ x ~ ~ x ~ ~ ~ x ~ x ~ ~ ~ is a sixteenth-note rhythm built from threes and twos, the chopped chord rhythm of the style. The chords only enter in the builds and drops; the verse keeps them back.
• Major ninths. Dmaj9 A Bm9 Gmaj9 is the pop I V vi IV with ninths, bright and bittersweet.
• Half-time drums at 150 BPM, with the layered clap and snare on beat 3, as in trap, and a hat skip at the end of each bar ([~ hh hh hh]).
• A saw bass on the kick, not a sub: the first version used sub_bass and the critic found too much sub and a thin low end at once.

  ears: 'future bass music' z +2.4 (closest confusion 'dubstep music' +2.8); production z +1.1 vs 'a low quality recording with hiss' +0.3; p_real 0.53
        sounds like: synthwave music, hip hop beat with heavy bass, drum and bass music, techno music
  verdict: 85/100 (arc 0.96, genre 0.41, mix 0.96, production 0.70, theory 1.00). Fix first: fizzy top end (air -14.8 dB, healthy up to -17); sounds more like 'dubstep music' than 'future bass music'

Future bass is the style the ears are least sure of: it reads close to dubstep and synthwave, which share its sounds. The air band is high because a supersaw at the front of the mix is bright; .lpf(9000) on the chords tames it. An earlier version with a chip arpeggio read as “chiptune video game music”, and taking it out helped.

Try:

• duck(0.6) on the chords for a subtler pump, or 0.95 for an extreme one.
• Vocal chops in the drops: track("vox", note("<[~ d3 ~ a2] [~ c#3 ~ a2]>").s("voice").role("vocal").legato(0.5)), sung vowels on chord notes.
• bars_per_chord(2) and a slower lead for a more anthemic, half-speed drop.

Remaking a song from audio

claudius remake listens to a recording, works out its skeleton (tempo, key, chords, sections, drum habits, the style of its bass) and writes a new song on that skeleton in any genre, with its own parts and sounds. No audio from the original is used. This recipe remakes a song whose answers we know, so you can see what the analysis gets right and what it gets wrong, then edits and evolves the result.

A song to remake

Any audio file ffmpeg can read works. To follow along without one, render the house recipe from House, deep house and techno first: claudius script house.rhai writes out/house-glass-avenue-1/song.mp3. We know exactly what is in it: 122 BPM, A minor, swing 0.58, the progression Am7 Fmaj7 Dm7 Em7 (i7 VImaj7 iv7 v7), and six sections (intro 8, groove 16, break 8, build 8, drop 16, outro 8).

What the analysis hears

claudius analyze out/house-glass-avenue-1/song.mp3

122.0 BPM (pulse clarity 0.58), A minor (confidence 0.75), swing 0.50, 64 bars from 0.00 s
  progression A: III VImaj7 iv7 v7  |  B: i VII v7 i7  (1 bar(s) per chord)
  bar   0 +24  drop    energy 0.97  kick bass hats
  bar  24 + 8  break   energy 0.30  
  bar  32 +32  drop    energy 1.00  kick bass hats
  kick  x...X...X...X...
  snare .-x-X-x-.-x-X-x-
  hats  .-X-x-X-.-X-x-X-
  bass style: syncopated

Against what we know:

• Tempo, key, length, bar grid: right. The tempo comes from onset autocorrelation and a grid fitted to the kicks; the key from the chroma of the whole song.
• Swing: missed (0.50 for 0.58). Swing is measured from the hi-hats on the off-beat sixteenths, and this song’s hats play eighths.
• Progression: three chords out of four right. The first chord, Am7 (A C E G), was heard as C (III): it contains all of C major’s notes, and chords are read from chroma, the energy of each note name per bar.
• Sections: the analysis cuts the song where the energy changes, in 4-bar steps, and labels the parts by energy. It found the break, but merged the intro and groove into one 24-bar “drop”, and the build, drop and outro into another. It reports which sections have kick, bass and hats.
• Drum habits: per sixteenth step, X very likely, x likely, . occasional, - never. The kick is exactly right. The snare line shows the claps on steps 5 and 13 (beats 2 and 4) plus hat energy leaking into the snare’s band on the eighths.
• Bass style: syncopated, a fair name for an offbeat line with pickups.

The analysis is approximate by nature (it reads a finished mix, not stems) and works best on steady electronic music.

Remake it in another genre

claudius remake out/house-glass-avenue-1/song.mp3 --genre deep_house --seed 3

It prints the analysis again, then the new song:

Faded Engine — deep_house at 122 BPM in A minor, 64 bars (2:06)
  progression A: III VImaj7 iv7 v7
  progression B: i VII v7 i7
  form: drop1 24 | break2 8 | drop3 32
  tracks: kick (sampled bd (tr909:bd)), clap (sampled cp (tr909:cp)), hat (sampled hh (tr909:hh)), shaker (shaker cut from 'Loose Leaf Beat Shaker' (Apple Loops)), perc (sampled rim (tr909:rim)), bass (synth patch 'sub_bass'), chords (synth patch 'keys'), pad (synth patch 'warm_pad'), lead (sampled rhodes (jrhodes:rhodes)), top (loop 'Deep Blue Void Hi-Hat' (House, Apple Loops) (126 BPM)), crash (synth crash), riser (synth riser), downlifter (synth downlifter), reverse_crash (synth reverse_crash)
  master: -11.0 LUFS, true peak -1.0 dBTP (pre-master -8.8 LUFS); done in 13.3 s
  ears: 'house music' z +3.3 (closest confusion 'techno music' +3.1); production z +1.3 vs 'a low quality recording with hiss' +1.2; p_real 0.80
        sounds like: house music, drum and bass music, techno music, tech house music
  verdict: 89/100 (arc 1.00, genre 0.79, mix 0.98, production 0.53, 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; dull 4-8 kHz: hats, claps and snare lack bite (presence -26.9 dB, healthy from -26)
  wrote out/remake-deep_house-faded-engine-3/song.mp3

What the remake keeps from the analysis, and what it takes from the genre:

The sections get builds and gaps before drops and impacts on them, an intro (if there is one) filters in, and breaks, intros and outros play progression B. On this machine the shaker was cut from Apple Loops and the top percussion is an Apple Loop; without Apple Loops, the shaker is synthesized and the loop is left out.

The score is high because the skeleton is simple and the sections are clearly layered: the arc check is perfect.

Edit the remake

The remake is an ordinary song. A script can fix what the analysis got wrong and replace any part with your own. This one corrects the first chord and puts a written motif in place of the generated Rhodes lead:

prog("A", "i7 VImaj7 iv7 v7");
track("lead", n("<[4 ~ 4 2 4 ~ 6 4] [5 ~ 5 4 2 ~ 0 ~] [3 ~ 3 2 0 ~ 2 3] [4 ~ ~ 6 4 ~ ~ ~]>")
                .octave(4).s("rhodes").room(0.3).delay(0.2));

claudius script fix.rhai --on out/remake-deep_house-faded-engine-3

  verdict: 87/100 (arc 1.00, genre 0.68, mix 0.98, production 0.46, 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; dull 4-8 kHz: hats, claps and snare lack bite (presence -26.8 dB, healthy from -26)
  wrote out/deep_house-faded-engine-3/song.mp3

The generated parts follow the corrected progression on their own, since they are written from it. The new lead takes the generated lead’s place in every section: both drops and the break. The critic liked it slightly less (the genre reading moved towards techno), which is a matter of taste you settle by listening. The edited song is written to out/deep_house-faded-engine-3/, next to the remake rather than over it, because a script names its folder after the genre, title and seed.

Evolve it

claudius evolve --genre deep_house --from out/deep_house-faded-engine-3/blueprint.json

starts evolution from the edited remake instead of fresh songs. The lead, a pattern track, keeps its notes; the drums, parts, mix, form and global feel are mutated.

Using the audio itself

A remake uses none of the recording’s sound. Two commands do:

• claudius chop song.mp3 cuts the recording into bar loops (2 bars by default, --bars) and drum one-shots, writes them into out/chops/, and adds them to your user library, where generated songs can pick them up as drum sounds. --find "a vocal chop" also uses the ears to cut out the moments that best match a description, three per description (--top).
• claudius make --genre house --sample out/chops/<loop>.wav flips a recording into a new song: warped to the song’s tempo, transposed to its key, re-sliced in half-beat pieces (or played straight) and placed in the high-energy sections, as a track named sample1.

Only use recordings you have the right to use this way. analyze and remake take nothing but measurements from a recording; chop and make --sample put its audio in your song.

From an assistant, the MCP tools analyze and remake take a file path and do the same as the commands; a remake becomes the song open in the studio.

Overview

A claudius script is a Rhai program with two kinds of functions on top:

• Song edits change the song that is open: tempo(124), key("A minor"), prog("A", "i7 VImaj7 iv7 v7"), mix("pad", #{ level: -4 }), form([...]).
• Patterns describe music in Strudel-style mini-notation, and track(name, pattern) turns a pattern into a track of the song: track("hats", s("[~ hh]*4")).

Here is a complete song in eight lines. It builds everything itself, so it runs anywhere:

blank("house");
tempo(122); 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));
track("lead",  n("<[4 ~ 4 2] [5 ~ 2 0] [3 ~ 0 2] [4 ~ ~ ~]>").octave(4).s("pluck").delay(0.2));
form([sec("intro", 8, "drums keys").filter_in(), sec("drop", 16, "*").impact(),
      sec("break", 8, "keys lead"), sec("drop", 16, "*")]);

You hear a four-on-the-floor house groove in A minor at 122 BPM: kick, claps on 2 and 4, offbeat hats, an organ bass on the offbeats playing the root of each chord, electric piano stabs and a plucked melody. The intro opens a lowpass filter over eight bars, the first drop lands with a crash.

How a script runs

A script runs top to bottom against the current song and changes only what it names. There is always a current song:

• song("house", 7) replaces it with a song the generator writes (genre, seed); see song().
• blank("house") replaces it with an empty song: one 8-bar section, no tracks, and the tonic chord as its only progression; see blank().
• Without either, edits apply to the song that is open: the one in the studio, the folder you pass with claudius script --on, or, when there is none, a blank house song.

Edits apply in order, so a later line sees what an earlier line did. key("D minor") after prog() transposes the progression; prog() after key() reads chord names in the new key. Where order matters, the reference says so.

When the script ends, the song is arranged, rendered and judged. That happens outside the script: a script only describes the song.

Where scripts run

claudius reference prints the compact reference that assistants get.

The examples in this reference

Every example in these pages is run by the test suite. An example that starts with song(...) or blank(...) stands alone. One that does not edits a generated song, the same one every time: song("house", 9), “Crimson Tide”, 124 BPM in G dorian, with the tracks kick clap hat ohat shaker perc bass chords pad lead arp, the sections intro groove break drop outro and the progressions A and B. To try such an example yourself, put song("house", 9); on the line before it.

// on the open song: faster, and the hats out of the intro
tempo(126);
layer("intro", "hat", false);

Reading the reference

Signatures use plain names for parameters and say what each one accepts:

tempo(bpm)                 // bpm: number, 40..240
drum(lane, variant, steps, per_bar)

number means an integer or a decimal (124 or 124.5). integer means a whole number: Rhai keeps the two apart, so bars_per_chord(1.5) is an error, not a rounding. A pattern string is mini-notation in quotes. Where a number is clamped into a range rather than rejected, the reference says so.

The pages

• Rhai in five minutes: the language underneath.
• Mini-notation: the grammar inside the strings.
• Patterns and time: cycles, bars, sections and randomness.
• Pattern functions: every pattern constructor and method.
• Pitch: notes, scales, chords, Roman numerals, voicing and arpeggios.
• Sounds: drum names, synth presets, sampled instruments, kits and files.
• Song functions: tempo, key, progressions, drums, parts and tracks.
• Form and sections: the arrangement and what each section flag does.
• Mixing functions: roles, levels, sends, sidechain, buses and the master.
• Songs as scripts: how a song prints, and the round-trip guarantee.
• Errors and limits: error messages and the limits a script runs under.
• Quick reference: everything on one page.

Rhai in five minutes

Scripts are written in Rhai, a small scripting language that reads like JavaScript or Rust. You need very little of it: most scripts are a list of function calls. This page covers the parts that come up in music scripts. The Rhai book has the rest.

Statements and comments

Statements end with ;. Line breaks inside a call are fine, which is how long patterns stay readable:

blank("house");   // a comment runs to the end of the line
/* a block comment
   spans lines */
track("lead", n("0 2 4 7")
                .scale("A:minor")
                .s("pluck"));

Values

Integers and decimals are different types. Functions that take a count (ply(2), every(4, ...), octave(4), bars_per_chord(2), the bars of sec()) need an integer, and a decimal there is an error:

blank("house");
track("lead", n("0 2 4").octave(4.5));

Error: Function not found: octave (Pattern, f64) (line 2, position 26)

“Function not found” with a list of argument types almost always means one argument has the wrong type. Functions that take an amount (tempo(), gain(), level(), swing()) accept both.

Variables

let makes a variable, const a constant. Variables hold anything, patterns included:

blank("house");
let groove = "x ~ ~ x ~ ~ x ~";
const ROOTS = "<a1 f1 c2 g1>";
track("bass", note(ROOTS).struct(groove).s("sub_bass"));
track("keys", chord("<Am F C G>").struct(groove).s("epiano"));

Both tracks share one rhythm, so the bass and the chords hit together.

Calling methods

A pattern method is called with a dot and returns a new pattern, so calls chain left to right. Each method applies to everything before it:

blank("house");
track("hats", s("hh*8").gain(0.6).pan(0.2).every(4, |x| x.fast(2)));

Closures

Higher-order methods take a closure: |x| ... is a function of one pattern, x, that returns a pattern. A closure can use variables from around it:

blank("house");
let up = 7;
track("lead", n("0 2 4 2").scale("A:minor").every(2, |x| x.add(up)).s("pluck"));

When the song prints as a script, the closure prints with the value it used: .every(2, |x| x.add(7)).

Functions, loops and conditions

Rhai has fn, for, while, if and switch. They are useful for building strings and for repeated edits:

song("house", 9);

// the same reverb send on several tracks
for t in ["chords", "pad", "lead"] {
    mix(t, #{ reverb: 0.3 });
}

// a function that writes a pattern string
fn every_beat(sound) { sound + " " + sound + " " + sound + " " + sound }
track("rim", s(every_beat("rim")).gain(0.5));

let late_night = true;
if late_night { tempo(120); swing(0.56); } else { tempo(126); }

A function defined with fn cannot see variables from outside it; pass what it needs as arguments. Ranges are written 0..4 (0 to 3) and 0..=4 (0 to 4).

Strings

Strings join with +. Backtick strings fill in ${...}:

blank("house");
let n = 4;
track("kick", s(`bd*${n}`));
track("hats", s("[~ hh]" + "*4"));

Printing

print(x) and debug(x) write to the script’s log: the terminal for claudius script, the log panel in the studio. Lines printed by the script come after the lines claudius writes for each track().

blank("house");
track("kick", s("bd*4"));
print("kick written");

track kick: bd
kick written

What a script cannot do

A script cannot read or write files (except audio files named in .s(), see Sounds), import modules, call eval, or run forever. It stops with an error after 10 seconds or 5,000,000 operations. The full list is in Errors and limits.

Mini-notation

Mini-notation is the little language inside pattern strings: s("bd*4, [~ cp]*2"). It comes from TidalCycles and Strudel, and claudius implements most of it. This page is the exact grammar, taken from the tokenizer and parser in crates/claudius/src/pattern/mini.rs, followed by what each construct means and where claudius differs from Strudel.

A string is parsed when the pattern is built, so a syntax error stops the script at the line that wrote it.

Grammar

Two levels: the tokenizer cuts the string into tokens, the parser builds a pattern from them. Whitespace separates tokens and is otherwise ignored, so a ! and a! are the same.

Tokens

token       = symbol | rest | hold | number | word ;
symbol      = "[" | "]" | "<" | ">" | "{" | "}" | "(" | ")"
            | "," | "|" | "*" | "/" | "@" | "!" | "?" ;
rest        = "~"
            | "-" ;                (* only when the next character is not a digit or "." *)
hold        = "_" ;                (* only when the next character is not a word character *)
number      = num-start { digit | "." } ;
                                   (* not followed by a word character other than ".";
                                      the text must read as a decimal number, else "bad number" *)
word        = word-start { word-char | "/" ascii-letter }
                                   (* a slash followed by a letter stays in the word: "F/A", "V7/V" *)
            | num-start { digit | "." } word-char-not-dot { word-char } ;
                                   (* "808bd", "3am", "1-2": a number run that continues into letters *)
word-start  = letter | "#" | ":" | "_" | "'" | "^" ;
num-start   = digit | "-" | "." ;
word-char   = letter | digit | "#" | ":" | "." | "_" | "'" | "-" | "^" ;
word-char-not-dot = word-char - "." ;
letter      = (* any Unicode alphabetic character *) ;
ascii-letter = "a" .. "z" | "A" .. "Z" ;
digit       = (* any Unicode digit *) ;

A / followed by a letter belongs to the word it is in, so slash chords (F/A) and applied chords (V7/V) are single words. Anywhere else / is the “slower” modifier: [a b]/2, a/2.

Any other character is an error: unexpected '%' in "bd%4". That includes %, $, =, +, ", °, ♭ and ♯, so write bb rather than B♭, and o or dim rather than °.

Patterns

pattern     = stack ;                                (* the whole string *)
stack       = sequence { ( "," | "|" ) sequence } ;
sequence    = { step | "_" | "!" } ;                 (* may be empty: silence *)
step        = atom { modifier } ;
atom        = "[" stack "]"
            | "{" stack "}"
            | "<" alternation
            | "~" | "-"
            | word
            | number ;
alternation = alt-sequence { "," alt-sequence } ">" ;
alt-sequence = { step | "!" } ;
modifier    = "*" number
            | "/" number
            | "@" number
            | "!" [ number ]
            | "?" [ number ]
            | "(" number "," number [ "," number ] ")" ;

Rules the grammar alone does not show:

• In a sequence, _ adds one step of length to the step before it, and a bare ! repeats the step before it. Either one with no step before it is an error.
• Inside < >, _ and | are errors, and @ weights are read but ignored.
• * and / take a number above 0 and up to 256.
• A stack mixes , and | badly: write [a | b], c, not a | b, c (see Differences).
• Size limits: a string is at most 4096 characters, brackets nest at most 64 deep, a sequence has at most 1024 steps, !n repeats a step at most 256 times, and a euclidean rhythm has at most 256 slots.

What each construct means

A pattern string describes one cycle, and in claudius one cycle is one bar. The constructs below divide the cycle, layer things in it, or change from one cycle to the next. Patterns and time explains cycles in full.

Modifiers apply to the step they follow and chain left to right: hh*2? drops some of the doubled hits, [bd sd](3,8) plays the pair inside each euclidean hit.

Sequences and weights

A sequence divides the cycle by weight. Every step weighs 1 unless @ says otherwise, and each _ after a step adds 1:

blank("house");
track("lead", note("e4@3 d4 c4@2 d4 e4").s("pluck"));   // 3/8, 1/8, 2/8, 1/8, 1/8 of the bar

!n writes the step n times; each copy is a full step. a! with no number means one more copy, and ! after whitespace is the same token, so a ! b is a a b. A number after a bare ! is read as the count: a ! 3 is a a a, not a a 3.

Groups, stacks and alternation

[ ] makes a sub-sequence that takes one step. A comma at the top level, inside [ ] or inside < > stacks layers that all take the full span:

blank("house");
track("drums", s("bd*4, [~ cp]*2, [~ hh]*4, hh*16?0.6"));

< > plays one item per cycle: <a1 f1 c2 g1> is A in bar 1, F in bar 2, C in bar 3, G in bar 4, then again. Items can be groups, and alternations nest: <a <b c>> plays a, b, a, c. Inside < >, ! repeats an item: <c2!2 ab1!2> plays C in bars 1 and 2, then A♭ in bars 3 and 4, a new event in every bar. <c2 ab1>/2 covers the same four bars with two events, each two bars long.

Speed

*n plays the step’s content n times within its slot; /n stretches it over n slots, so it continues in the next cycle. In x [a b c d]/2, the second half of bar 1 plays a b and the second half of bar 2 plays c d. The number can be a decimal above 0 and up to 256; it cannot be a pattern (bd*<2 3> is an error).

Euclidean rhythms

x(k,n,r) puts k hits on n equal slots as evenly as possible, with Bjorklund’s algorithm as Tidal and Strudel run it, and rotates the result left by r slots. A k larger than n fills every slot; an n of 0 is silence.

Randomness

? and | are random, but not from run to run: their random numbers are seeded from the text of the string. The same string gives the same choices on every render, a different bar gets a different choice, and any edit to the string (even a space) gives new choices. hh*16?0.3 thins a 16th-note hat differently in each bar of a section, and identically every time you render.

Values

What a word or number means depends on the pattern it is in:

In a sound name, only a number after the last colon is a variation: bd:3 and tr808:sd:2 carry one, tr808:sd is a single name. Pitch has the note, scale and chord rules. In .struct() and .mask(), a value is “on” when it is a non-zero number or any word except 0, false and f.

Errors

Errors name the token the parser did not expect. These are the messages, as claudius script prints them:

blank("house");
track("x", s("[bd sd"));

Error: Runtime error: expected ']', found the end (line 2, position 12)

A word that parses but means nothing is not an error at this stage; it is one when the track is made, and the message says what was expected: s("bdd") is an unknown sound, note("h3") cannot be read as a note, chord("Xyz") cannot be read as a chord, and n("0 e") is not a scale degree. See Errors and limits.

Differences from Strudel

Patterns and time

A pattern is a description of events in time that claudius can ask questions of: “what happens in bar 3?” This page says exactly how those questions are asked and answered, because everything else (alternation, every, prog, randomness) follows from it.

One cycle is one bar

Pattern time is counted in cycles, and a cycle is always one bar of four beats at the song’s tempo. At 120 BPM a cycle lasts 2 seconds; at 174 BPM, 1.38 seconds. There is no separate cycles-per-second setting: change the tempo with tempo() and the patterns follow.

Every duration in the pattern language is a fraction of a bar:

So .late(0.25) moves a pattern one beat later, and .off(0.125, f) adds a copy an eighth note behind.

Events

A pattern produces events. Each event has a whole, the span it occupies (start and end, in cycles), a value ("bd", "c3", 4, "Am7"), and controls set by methods such as .gain() or .legato(). In s("bd sd"), bar 1 has two events: bd from 0 to 0.5 and sd from 0.5 to 1.

Queries

When claudius needs a pattern’s events, it asks for a span of cycles, from b up to (not including) e, and gets the events whose start falls inside the span. An event that started earlier and is still sounding is not returned, and events are never cut into fragments.

This differs from Strudel, which returns fragments of events that overlap the span. You notice it in one place: an event longer than a bar exists only in the bar where it starts. note("<c3 g3>/2") has an event in bars 1 and 3, none in bars 2 and 4; each note still lasts its full two bars, so you hear it. Methods that read another pattern at each event look further back, so they still find it (see Reading one pattern from another).

Sections restart their patterns

A pattern track plays in the sections that list it (see Form). For a section of N bars, claudius asks the pattern for cycles 0 to N and places the result at the start of the section. Every section therefore starts the pattern from its first cycle:

• an alternation <a b c> starts again from a;
• .every(4, f) applies f on the first bar of each section, then every fourth bar;
• chord("prog") follows the section’s progression from its first chord;
• random choices repeat: bar 1 of every section makes the same choices.

blank("house");
tempo(120);
track("lead", n("<0 2 4 6>").scale("A:minor").octave(4).s("pluck"));
form([sec("groove", 6, "lead"), sec("break", 4, "lead")]);

The groove plays A, C, E, G, A, C; the break starts again on A. A section whose length is not a multiple of the pattern’s length cuts the pattern off, so a 4-bar idea in a 6-bar section plays once and a half.

Drum lanes written with drum() work the same way: their step pattern is tiled from the start of each section.

From events to notes

When a section is arranged, each event becomes a note:

• start: the event’s start, in beats from the section’s first beat (cycle × 4);
• length: the event’s whole length × legato (1 when not set), never shorter than 0.02 beats;
• velocity: velocity, else gain, else 0.9 for sound patterns and 0.8 for the others; anything above 1 plays as 1;
• pitch: from the value, as described in Pitch.

Events shifted by .late() or .early() follow the same rule: .late(0.25) pulls the last beat of cycle −1 into the first beat of every section, and drops the last beat of the section’s final bar.

Swing and humanize are not part of the pattern. They are applied when the song is rendered, to every track: see swing() and humanize().

What a pattern’s values mean

The constructor decides the pattern’s kind, and the kind travels with it through every method:

stack() and cat() take the kind (and the track settings such as .s() and .scale()) of their first pattern. Stack patterns of one kind: stack([note("c3"), s("bd")]) reads bd as a note name and fails with cannot read 'bd' as a note.

Reading one pattern from another

.struct(p), .mask(p) and the per-event controls (.gain(p), .velocity(p), .legato(p), .add(p), .transpose(p), .n(p)) read a second pattern at the start of each event: they take the event of p that is sounding at that moment, including one that started in an earlier bar (up to 64 bars back).

blank("house");
// each bar's root, played on the struct's hits
track("bass", note("<a1 f1 c2 g1>").struct("x ~ x x ~ x x ~").s("sub_bass"));
// a different gain on each beat
track("hats", s("hh*16").gain("0.9 0.4 0.7 0.4"));

A value that lasts longer than a bar holds for all of it. Both of these play A for two bars, then F for two:

blank("house");
track("bass", note("<a1 f1>/2").struct("x ~ x ~").s("sub_bass"));
track("bass2", note("<a1!2 f1!2>").struct("x ~ x ~").s("sub_bass"));

Randomness

Random methods (? and | in mini-notation, .degrade(), .degradeBy(), .sometimes() and its relatives) are deterministic. Each decision comes from a hash of a seed and the start time of the event it is about, and the seed comes from code:

What follows from that:

• The same script renders the same song every time, on every machine.
• Different bars get different choices, and every section repeats the choices of its own first bars.
• Two tracks with the same code make the same choices. s("hh*8?") on two tracks drops the same hits.
• Editing the code before a random method changes its choices; editing after it does not. In s("hh*8").degrade().gain(0.6), changing the gain keeps the same hits, changing "hh*8" to "hh*8 " does not.

To hear a different variation of the same idea, change the code before the random method without changing the music: a space added inside the pattern string ("hh*8 ") is enough. .degrade() and .degradeBy(0.5) make identical choices, since they share a seed.

Pattern functions

Every function that makes or changes a pattern, with its parameters, what it accepts, the errors it raises and an example. Methods are called on a pattern (s("bd*4").fast(2)) and return a new pattern; the original is unchanged.

Many parameters accept a number, pattern string or pattern: gain(0.8), gain("1 0.6") and gain(seq("1 0.6")) are the same kind of argument. Anything else raises expected a number, a pattern string or a pattern. How a second pattern is read is explained in Reading one pattern from another.

Constructors

s() and sound()

s(pattern)        // number, pattern string or pattern
sound(pattern)    // the same

A pattern of sound names: drums, synth presets, sampled instruments, kit sounds such as tr808:sd (see Sounds). Each word is one hit; a number after the last colon picks a variation (bd:3, tr808:sd:2). A track whose sound pattern uses several names is split into one track per name (drums.bd, drums.hh …) so each gets its own mixing role.

blank("house");
track("drums", s("bd*4, [~ cp]*2, [~ hh]*4"));

note()

note(pattern)     // note names or MIDI numbers

A pattern of pitches: c3, eb2, f#4, or MIDI numbers (60 is middle C). A name without an octave is in octave 3. The instrument comes from .s(); without it, the pluck synth plays. See Pitch.

Errors: a word that is not a note name, when the track is made: cannot read 'h3' as a note (names with an octave like c3, f#4, bb2, or MIDI numbers).

blank("house");
track("bass", note("<a1 f1 c2 g1>").struct("x ~ ~ x ~ x ~ ~").s("sub_bass"));

n()

n(pattern)        // scale degrees, from 0

A pattern of scale degrees in the scale set by .scale(), or the song’s key when there is none. Degree 0 is the tonic in octave 3 (.octave() changes it); 7 in a seven-note scale is the tonic an octave up; negative degrees go down. Without .s(), the pluck synth plays. See Pitch.

Errors: a word instead of a number, when the track is made: n() takes scale degrees (0 1 2 -1 ...), not 'e'.

blank("house");
key("A minor");
track("lead", n("0 2 4 7 4 2").octave(4).s("pluck"));

chord()

chord(pattern)    // chord symbols, Roman numerals, prog, prog:NAME

A pattern of chords: names (Am7), slash chords (F/A), Roman numerals (ii7, V7/V). Each event plays every note of its chord, voiced with voice leading (see Voicing), or only its root with .root(). prog plays the song’s progression for the section; prog:B always plays progression B (or A when the song has no B). Without .s(), the epiano synth plays.

Errors: a word that is neither, when the track is made: cannot read 'Xyz' as a chord (names like Am7, Fmaj7, Bb, numerals like ii7, bVII, V7/V, or prog).

blank("house");
key("A minor"); prog("A", "Am7 Fmaj7 Dm7 Em7"); bars_per_chord(1);
track("keys", chord("prog").struct("x ~ ~ x ~ ~ x ~").s("epiano"));

seq()

seq(pattern)      // plain values

A pattern of plain numbers and words, for arguments: .gain(seq("1 0.6")), .struct(seq("x ~ x x")). A string argument does the same job, so seq() is mostly useful for building an argument once and reusing it.

stack()

stack([pattern, pattern, ...])

Plays patterns together. The result has the kind and track settings of the first pattern, so stack patterns of one kind.

Errors: stack() takes patterns when an item is not a pattern; stack() needs at least one pattern for [].

blank("house");
track("drums", stack([s("bd*4"), s("[~ cp]*2"), s("hh*8").gain(0.5)]));

cat()

cat([pattern, pattern, ...])

One pattern per bar, in turn: bar 1 plays the first, bar 2 the second, and so on, then again. Like stack(), it takes the kind and track settings of the first pattern. Errors as for stack(), with cat() in the message.

blank("house");
track("drums", cat([s("bd*4, hh*8"), s("bd*4, hh*8"), s("bd*4, hh*8"), s("bd*2 [bd*4], hh*16")]));

silence()

silence()

A pattern with no events.

Time

fast() and slow()

pattern.fast(factor)     // number above 0, up to 256
pattern.slow(factor)     // number above 0, up to 256

fast(2) plays the pattern twice per bar; slow(2) spreads one cycle over two bars. Factors can be decimals.

Errors: fast needs a number; fast takes a number above 0 and up to 256, not 1000; the same for slow.

blank("house");
track("hats", s("hh hh hh oh").fast(2));          // eighth notes, an open hat on the "and" of 2 and 4
track("pad", chord("<Am F>").slow(2).s("pad"));     // each chord for two bars

late() and early()

pattern.late(cycles)     // number; negative moves earlier
pattern.early(cycles)    // number; negative moves later

Shifts the pattern in time. late(0.25) is one beat; small values such as late(0.02) make a part sit lazily behind the beat. At a section’s start, a shifted pattern brings in the end of the bar before it.

Errors: late needs a number, early needs a number.

blank("lofi");
track("keys", chord("<Dm9 G9>").s("epiano").late(0.02));

rev()

pattern.rev()

Reverses each bar: the last event comes first.

blank("house");
track("lead", n("0 1 2 4").scale("A:minor").octave(4).every(2, |x| x.rev()).s("pluck"));

ply()

pattern.ply(count)       // integer, 1 to 256

Repeats each event count times inside its own slot: s("bd sd").ply(2) is s("[bd bd] [sd sd]").

Errors: ply takes a number above 0 and up to 256, not 300; ply takes a whole number from 1 to 256, not 1.5.

blank("trap");
track("hats", s("hh*8").lastOf(4, |x| x.ply(2)));

Higher-order functions

These take a closure |x| ... that receives the pattern and returns a changed one. Track settings written inside a closure (|x| x.s("piano")) have no effect: only the events it returns are used.

every() and lastOf()

pattern.every(n, f)      // n: integer (below 1 acts as 1), f: closure
pattern.lastOf(n, f)

every(n, f) uses f’s version in the first bar of every n, counted from the start of the section (bars 1, 5, 9 … for n = 4). lastOf(n, f) uses it in the last bar of every n (bars 4, 8, 12 …), which is where a fill belongs.

blank("house");
track("drums", s("bd*4, [~ cp]*2").lastOf(4, |x| x.fast(2)));   // a doubled bar before each phrase

sometimes() and its relatives

pattern.sometimes(f)       // probability 0.5
pattern.often(f)           // 0.75
pattern.rarely(f)          // 0.25
pattern.almostNever(f)     // 0.1
pattern.almostAlways(f)    // 0.9
pattern.sometimesBy(p, f)  // p: number; 0 never, 1 always

Decides once for each event of the pattern, with the given probability, whether f applies to it, the way Strudel does. The chosen events go through f and the others play as they are, so each event is either itself or f’s version of it, never both: s("hh*16").sometimes(|x| x.late(0.01)) plays sixteen hats, some nudged late, and .sometimes(|x| x.ply(2)) doubles some events and leaves the others single. A transform that changes speed (fast, slow) is the exception: it picks events in its own time, so its copies can land on top of originals. The choice is random but repeatable (see Randomness).

Errors: sometimesBy needs a number.

blank("house");
track("hats", s("hh*16").gain(0.6).sometimes(|x| x.gain(0.3)));         // accents vary hit by hit
track("ride", s("rd*8").sometimes(|x| x.ply(2)).gain(0.5));              // some eighths become two sixteenths
track("lead", n("0 2 4 2").scale("A:minor").octave(4).rarely(|x| x.add(7)).s("pluck"));

off()

pattern.off(cycles, f)   // cycles: number; f: closure

Plays the pattern and, on top of it, f’s version shifted later by cycles. A classic is an echo an eighth note behind, an octave up.

Errors: off needs a number.

blank("house");
track("arp", n("0 2 4 6").scale("A:minor").octave(4).off(0.125, |x| x.add(7)).s("pluck"));

superimpose()

pattern.superimpose(f)

Plays the pattern and f’s version together, unshifted. Use it for doublings: a third or an octave above.

blank("house");
track("lead", n("0 1 2 4").scale("A:minor").octave(4).superimpose(|x| x.add(2)).s("pluck"));

degrade() and degradeBy()

pattern.degrade()        // drops each event with probability 0.5
pattern.degradeBy(p)     // p: number; 0 keeps all, 1 drops all

Drops events at random, repeatably. degradeBy(0.3) keeps about 70 % of the events. The mini-notation ? does the same per step.

Errors: degradeBy needs a number.

blank("house");
track("shaker", s("shaker*16").degradeBy(0.3).gain(0.5));

Structure

struct()

pattern.struct(rhythm)   // number, pattern string or pattern

Takes the timing from rhythm and the values from the pattern. Every “on” event of the rhythm (any non-zero number, any word but 0, false, f) becomes an event with the value the pattern has at that moment. Rests in the rhythm are silent. Use it to give a melody or a chord progression a rhythm without rewriting it.

blank("house");
track("stabs", chord("<Am7 Dm7>").struct("~ x ~ x ~ x ~ [x x]").s("stab"));

mask()

pattern.mask(onoff)      // number, pattern string or pattern

Keeps the events of the pattern that start where onoff is on, and removes the others. Unlike struct(), it never adds events or changes timing.

blank("house");
track("hats", s("hh*16").mask("<1 [1 0] 1 [1 0 0 1]>"));   // the hats drop out in places, bar by bar

euclid() and euclidRot()

pattern.euclid(k, n)         // integers: k hits over n slots
pattern.euclidRot(k, n, r)   // and rotated left by r slots

The pattern played on a euclidean rhythm. s("rim").euclid(5, 16) is s("rim(5,16)"). n is 1 to 256, as in mini-notation (otherwise a euclidean rhythm has 1 to 256 steps, not 1000); k is held between 0 and n; r wraps around, so a negative r rotates right.

blank("techno");
track("rim", s("rim").euclidRot(5, 16, 2).gain(0.6));

Per-event controls

Each control is read from its argument at the start of every event, so a pattern string gives different values in different places.

gain() and velocity()

pattern.gain(amount)       // number, pattern string or pattern; 0..1
pattern.velocity(amount)

How hard each note is played. Both set the same thing; when both are present, velocity wins. Without either, sound patterns play at 0.9 and the others at 0.8. Values above 1 play as 1. On synthesized drums and audio files, the level follows velocity to the power 1.6, so 0.5 sounds about 10 dB below 1; synth presets and sampled instruments respond the way the instrument does, with tone as well as level (a sampled piano switches to softer recordings).

blank("house");
track("hats", s("hh*16").gain("[0.4 0.25 0.8 0.25]*4"));   // accent on the off-beat eighth

legato()

pattern.legato(fraction)   // number, pattern string or pattern; 1 = the full slot

How long each note lasts, as a fraction of its slot. 0.5 is staccato, 1 (the default) is the whole slot, and values above 1 overlap the next note. On the mono synths with glide (808, acid, reese, square_lead) an overlap makes the pitch slide into the next note; sub_bass and wobble tie the notes without starting the envelope again. Arpeggiated notes default to 0.9.

blank("house");
track("bass", note("a1*8").s("organ_bass").legato("0.4 0.9"));

add() and transpose()

pattern.add(amount)        // number, pattern string or pattern; rounded to a whole number
pattern.transpose(amount)  // the same, in semitones always

Both move pitches. transpose() always counts semitones. add() adds to the pattern’s values, so what one step means depends on the pattern:

n("0 2 4").transpose(12) is the same line an octave up in any scale; n("0 2 4").add(7) is too, in a seven-note scale. Several calls add up.

blank("house");
key("A minor");
track("lead",  n("0 2 4 2").octave(4).add("<0 0 -2 -1>").s("pluck"));       // the motif moves by scale steps
track("lead2", n("0 2 4 2").octave(4).transpose(12).s("bell").level(-6));   // the same line an octave up
track("perc",  s("rim*8").transpose("0 7 12 7").gain(0.5));

n() on a sound pattern

pattern.n(index)           // number, pattern string or pattern

On an s() pattern, picks the variation of each sound, like bd:3. It replaces an index written in the word.

blank("house");
track("kick", s("bd*4").bank("tr909").n("0 0 3 0"));

Track settings

These describe the track rather than single events, so they apply to the whole track wherever they appear in the chain, and a later call replaces an earlier one. Only the pattern given to track() counts: settings inside a closure are ignored.

.scale() and .arp() check their argument: unknown scale 'Q:minor' (try "A:minor", "C:major", "D:dorian", "E:minor:pentatonic"), unknown arp 'sideways' ("up", "down" or "updown"). The numeric settings raise <name> needs a number for anything else, and are not clamped by the pattern; Mixing functions says what the mixer does with them. .s() on an s() pattern does nothing, since the words already name the sounds.

blank("deep_house");
track("keys", chord("<Fm9 Bbm9>").voicing(53, 72).s("epiano")
                .level(-2).pan(-0.2).room(0.3).delay(0.1).lpf(4000));

.root() turns a chord pattern into a bass line that follows it. On the song’s progression, the bass changes when the progression does:

blank("house");
key("A minor"); prog("A", "Am F/A C G"); bars_per_chord(1);
track("keys", chord("prog").struct("x ~ ~ x ~ ~ x ~").s("epiano"));
track("bass", chord("prog").root().struct("x ~ ~ x ~ x ~ ~").s("sub_bass"));   // A2 A2 C2 G2

Pitch: notes, scales and chords

Three pattern kinds carry pitch: note() (absolute notes), n() (scale degrees) and chord() (chords). This page gives the exact rules for each, then voicing and arpeggios. Pitches are MIDI numbers: 60 is middle C (C4), 69 is the A at 440 Hz, and each step is a semitone.

Note names

note() reads each word as a note name:

• a letter a to g, upper or lower case;
• any number of accidentals: # or s for sharp, b or f for flat (c#, cs, eb, ef, cbb);
• an optional octave number. Without one, the octave is 3, or the track’s .octave(n).

So c is C3 (48), c4 is 60, a1 is 33, f#2 is 42, bb1 is 34. A number instead of a name is a MIDI note: note("60 64 67") is a C major triad from middle C. Decimals are rounded.

blank("house");
track("bass", note("a1 a1 [a2 a1] g1").s("sub_bass"));
track("keys", note("[a3, c4, e4] ~ [f3, a3, c4] ~").s("epiano"));   // chords written note by note

A word that is not a note name is an error when the track is made: cannot read 'h3' as a note (names with an octave like c3, f#4, bb2, or MIDI numbers).

Scale degrees

n() reads numbers as degrees of a scale, counted from 0:

• degree 0 is the tonic in octave 3 (or .octave(n)): in A minor, A3 (57);
• degree 7 in a seven-note scale is the tonic an octave up; degree 5 in a pentatonic scale;
• negative degrees go down: −1 in A minor is G3;
• decimals are rounded; a word that is not a number is an error (n() takes scale degrees (0 1 2 -1 ...), not 'e').

The scale is the track’s .scale(name), or the song’s key when the track has none. Writing melodies in degrees keeps them in key, and key() moves them with the song.

blank("house");
key("A minor");
track("lead", n("0 2 4 7 6 4 2 1").octave(4).s("pluck"));   // A C E A G E C B, from A4

Scale names

A scale is written as a tonic and a name, separated by : or spaces, in any case: "A:minor", "a minor", "E:minor:pentatonic", "F# dorian".

Words after the tonic are joined with _, so "minor pentatonic" and "minor:pentatonic" both name minor_pentatonic. Locrian, melodic minor and other scales are not available; .scale() rejects them with unknown scale.

Keys

key() takes a tonic and a mode: "A minor", "Am", "F#m", "Eb" (major), "D dorian", "C# phrygian", "Bb mixolydian", "E harmonic minor". The tonic accepts #, b, ♯ and ♭. The seven modes in the first seven rows of the table above are the keys a song can be in; the pentatonic, blues and chromatic scales exist only for n().

Chord symbols

chord() reads a word as a chord symbol when it starts with a note letter: a root, then a quality suffix.

Roots are case-insensitive (am7 is A minor 7). A slash chord names its bass note after a slash: F/A is F major over A, C/E is C major over E. Inside a pattern string, °, + and ♭ are not allowed by the tokenizer: write dim or o, aug, and b; a slash followed by a letter stays in the word, so chord("<Am F/A C G>") works. An unknown symbol (Cmaj13, Xyz) is an error when the track is made: cannot read 'Xyz' as a chord (names like Am7, Fmaj7, Bb, numerals like ii7, bVII, V7/V, or prog).

The slash bass does not change the voicing (the chord’s own notes are voiced as usual). It is what .root() plays, what generated basslines play on that chord, and what the critic expects the bass to play.

Roman numerals

A Roman numeral names a chord by its place in the key, so a progression in numerals follows every key change. chord() reads any word that is not a chord symbol as a numeral, and prog() stores progressions as numerals.

• Degree: I II III IV V VI VII, counted in the key’s own mode. VI in A minor is F; IV in A dorian is D; II in E phrygian is F.
• Case picks major or minor when there is no suffix: IV is major, iv is minor. Case never moves the root.
• Accidentals before the numeral move the root a semitone: bVII, bVI, bIII, #iv. These are the borrowed chords.
• Suffixes: 7 is a dominant 7th on an upper-case numeral and a minor 7th on a lower-case one; 9 and 6 work the same way; add9 gives add9 or madd9 by case. °, o, dim make a diminished triad; ø, ø7, m7b5 a half-diminished 7th; °7, o7, dim7 a diminished 7th; +, aug augmented; 11 always a minor 11th. Any other chord-symbol suffix (maj7, maj9, sus4, m7) sets the quality outright, whatever the case.
• Applied chords: V/V, V7/ii, viio7/V read the part before the slash in the key of the chord after it (major or minor, by that chord’s quality). In C major, V/V is D major. They work in prog() and in pattern strings.
• A note after the slash (I/E, VI/A) is a slash chord: the chord, with that note in the bass.

blank("house");
key("A minor");
track("keys", chord("<i VImaj7 iv7 V7>").s("epiano"));   // Am, Fmaj7, Dm7, E7: a harmonic-minor turn

A chord pattern with .scale() reads its numerals in that scale instead of the song’s key: chord("<i VI III VII>").scale("C:minor") plays Cm, A♭, E♭, B♭ in any song.

The song’s progression: prog and prog:NAME

In a chord pattern, the word prog means “the chord the song’s progression has here”. The progression is the one the section plays (A unless the section says otherwise; breaks play B, or A when there is none), with bars_per_chord() bars per chord, starting from its first chord at the start of each section and looping. prog:B always reads progression B, whatever the section.

blank("house");
key("A minor");
prog("A", "Am7 Fmaj7 Dm7 Em7");
prog("B", "Fmaj7 G Em7 Am7");
bars_per_chord(1);
track("keys", chord("prog").struct("x ~ ~ x ~ ~ x ~").s("epiano"));
track("pad",  chord("prog").s("pad").role("pad"));
form([sec("groove", 8, "*"), sec("break", 8, "pad")]);

The keys and the pad play A in the groove and switch to B in the break, without being told. A name with no progression behind it (prog:C when there is no C) plays progression A, as the generated parts do. A section cannot ask for a progression the song does not have: form() and section() refuse it, except that a break with no B plays A.

Writing harmony this way has a second benefit: the arranger’s chord track, the generated parts and the critic’s harmony checks all read the song’s progressions. A chord pattern with explicit names plays what it says, but the critic still checks the melody and bass against prog("A") (on a blank() song, the tonic chord alone), so set it to the same chords.

Roots: bass lines from the chords

.root() makes a chord pattern play only each chord’s root, or its slash bass when it has one, as a single note in octave 2 (.octave(n) moves it). On chord("prog"), that is a bass line that follows the song’s progression, and changes when you change the progression:

blank("house");
key("A minor");
prog("A", "Am F/A C G");
bars_per_chord(1);
track("keys", chord("prog").struct("x ~ ~ x ~ ~ x ~").s("epiano"));
track("bass", chord("prog").root().struct("x ~ ~ x ~ x ~ ~").s("organ_bass"));

The bass plays A2, A2 (the slash bass of F/A), C2 and G2, a bar each. Because every chord’s root lands in the same octave, the line jumps where a bassist would step (G2 up to A2 is fine, A2 down to C2 is a sixth); write the notes out with note() when the shape of the line matters.

Voicing

Every chord event is voiced, whether or not you call .voicing():

1. How many voices: the number of different notes in the chord, but at least 3 and at most 4. A triad gets three voices, a 7th chord four, a 9th or 11th chord four.
2. Which notes go when there are more notes than voices: the fifth first, then the root (the bass covers it). A 9th chord keeps the third, seventh and ninth plus the root.
3. Doubling when there are fewer notes than voices (a power chord): the root first, then the fifth.
4. Where: every arrangement of those notes inside the range is scored. Close voicings (3 to 14 semitones from bottom to top) are preferred; intervals under a fourth below E3 and semitone clusters below E4 are penalised; and the distance each voice moves from the previous chord counts most. The first chord of a section is placed near the middle of the range.

The range is .voicing(lo, hi) in MIDI numbers, by default 52 to 74 (E3 to D5). .voicing() without arguments uses the default. .add(n) shifts the range by n semitones.

blank("house");
key("A minor"); prog("A", "Am7 Fmaj7 Dm7 Em7"); bars_per_chord(1);
track("keys", chord("prog").voicing(55, 74).s("epiano"));    // Am7 as C4 E4 G4 A4
track("pad",  chord("prog").voicing(45, 64).s("pad").role("pad"));

The keys hold common tones and move the other voices by step: from Am7 (C4 E4 G4 A4) to Fmaj7 only the G moves, down to F; to Dm7 the E moves down to D (C4 D4 F4 A4); to Em7 the C, F and A each step down (B3 D4 E4 G4). A range narrower than an octave can leave no valid voicing, in which case the chord tones are stacked upwards from lo.

Arpeggios

chord(...).arp(mode)    // "up", "down", "updown"

.arp() plays each chord event’s voiced notes one after another, evenly across the event:

Each note lasts its share × legato (0.9 by default). Any other mode plays up. The speed comes from the events: one chord per bar arpeggiated over a triad gives three notes per bar; give the pattern more events with .struct() or * for faster arpeggios.

blank("synthwave");
key("A minor"); prog("A", "Am F C G"); bars_per_chord(1);
track("arp", chord("prog").struct("x*4").arp("updown").voicing(57, 76).s("pluck"));   // triads: 16th notes

A triad in updown has four steps (1 2 3 2), so four events per bar give straight sixteenths; up would give triplets.

Velocity and length

Pitch patterns use the same controls as every pattern: gain()/velocity() for how hard, legato() for how long. A note lasts its whole slot unless legato says otherwise, so note("a1 ~ ~ ~") is a quarter note and note("a1 _ _ _") a whole bar.

Sounds

Every sound in claudius is real audio: synthesized in code (drum voices, the synth engine) or recorded (sampled instruments and drum machines from the sample packs, Apple Loops, your own files). There is no General MIDI and no neural audio. A sound name appears in two places:

• the words of an s() pattern: s("bd*4, [~ cp]*2");
• .s(name) on a note(), n(), chord() or seq() pattern: note("a1 c2").s("upright_bass").

claudius sounds renders every drum voice, synth preset and transition effect into out/sounds/ so you can hear them; claudius-packs aliases lists every sampled-instrument name your installed packs answer to.

How a name is resolved

A number after the last colon is a variation (bd:3, tr808:sd:2); the rest is the name, colons included (tr808:sd, vsco2:violins). When a track is made, each name is looked up in this order, and the first match wins:

1. With .bank() set, the name is looked up in that bank only.
2. Drum names play the synthesized drum voices.
3. Synth presets play the synth engine.
4. The sample packs: sampled instruments (rhodes, vsco2:violins) and kit sounds (tr808:sd).
5. Files: a name containing / or ending in .wav, .mp3, .aif, .aiff, .flac, .caf or .m4a.

Anything else is an error that lists what exists:

blank("house");
track("x", s("bdd*4"));

Error: Runtime error: track 'x': unknown sound 'bdd' (drums: bd kick sd snare cp clap hh ch hat oh ohat rd ride cr crash lt mt ht tom rim rs sh shaker cb cowbell snap perc; synths: sub_bass 808 reese acid saw_bass pluck_bass organ_bass wobble pluck supersaw pad warm_pad stab epiano keys bell organ strings square_lead chip; sampled: piano upright rhodes wurlitzer hammond string_ensemble violins cellos pizzicato brass trumpet flute harp marimba vibes kalimba upright_bass guitar choir sax ... (claudius-packs aliases)) (line 2, position 1)

Because drum names and synth presets come first, a few names play synthesis even when a recording by that name exists. Ask for the recording by another name, or exactly as pack:instrument (claudius-packs instruments lists them):

lead is not a synth preset: it plays the sampled FreePats square lead. The synth leads are square_lead, supersaw and the other synth presets.

Drum names

These names play the synthesized drum voices. Each one also decides the mixing role of its track, wherever it appears in the name: bd:3 and tr909:bd are kicks, tr808:sd is a snare, vcsl:shaker a shaker.

Synth presets

The synth engine has polyBLEP oscillators with unison and analog drift, state-variable and ladder filters, FM, glide and drive. These are its factory presets; the role is what role_of assumes for a pattern track.

“By pitch” means a pattern track gets the role chords when it is a chord() pattern, bass when its median note is below E3, and lead otherwise. Mono presets play one note at a time; with glide, overlapping notes slide (see legato()).

Sampled instruments

With the default packs installed (claudius-packs install --defaults), these names play multi-sampled recordings with velocity layers and round robins. Most have several aliases; claudius-packs aliases prints them all.

pack:instrument names one exactly, in .s() or in an s() pattern: note("c4 e4").s("vsco2:violins"), s("vcsl:shaker*8").

Every recorded instrument has a playable range; notes outside it are pitched from the nearest sample, which sounds stretched far from home. Songs that play instruments from packs whose licences ask for credit get a credits.txt in their folder.

A sampled instrument name used without its pack installed is an unknown sound, and the error ends with sampled instruments need packs: claudius-packs install --defaults. A session started with --synth-only (make, evolve, serve, studio and mcp take it) plays no recordings at all: a sampled name ends its error with sampled instruments are off in this session (--synth-only), and .bank("tr909") raises bank 'tr909' plays sample packs, which are off in this session (--synth-only).

blank("lofi");
key("D minor");
track("keys", chord("<Dm9 Gm9>").voicing(50, 72).s("rhodes"));
track("bass", note("<d2 g1>").struct("x ~ ~ x ~ x ~ ~").s("upright_bass"));
track("bongos", s("~ bongo [~ bongo] bongo:2").gain(0.6));

Sampled percussion from the packs gets the perc role by itself.

Drum machines and kits

.bank(name) plays the drum names of an s() pattern on a recorded drum machine or kit from the sample packs:

Each kit has a subset of bd sd cp hh oh rd cr lt mt ht rim cb sh (the 909 has no shaker, the acoustic kit no clap); names like kick and snare map to them. A name the bank does not have is an error:

blank("house");
track("drums", s("bd*4, bongo*2").bank("tr909"));

Error: Runtime error: track 'drums': no 'bongo' in bank 'tr909' (installed packs: salamander epianos jrhodes vsco2 vcsl tr808 tr909 tr707 uzu muldjord freepats doublebass growlybass voice; kits: tr909 tr808 tr707 acoustic uzu) (line 2, position 1)

The bank applies to every word of the pattern. To mix kits, or a kit and a sampled instrument, in one pattern, name each kit sound with its bank instead: s("tr909:bd*4, tr808:cp*2, bongo*2"). Strudel bank names (RolandTR909) work as aliases, and Strudel sample maps added with claudius-packs add-map become banks too.

.bank("apple") cuts drum one-shots from installed Apple Loops (GarageBand or Logic content) instead. On a machine without Apple Loops it falls back to the synthesized voices, without an error.

blank("house");
track("drums", s("bd*4, [~ cp]*2, [~ hh]*4").bank("tr909"));

Variations

A number after the last colon (bd:3, tr808:sd:2) or .n(n) picks variation n of a sound (0 is the default):

• on a kit, the recording numbered n: the 909 has 126 kicks, the 808 has 25;
• on a synthesized drum, the same voice moved a few steps through its parameters (tuning, decay, tone …), the same way every time;
• a variation a recording does not have is an error (no 'bd:200' in bank 'tr909').

blank("techno");
track("kick", s("bd*4").bank("tr909").n("<0 0 0 7>"));

Your own files

.s(path) plays an audio file as a sampler, on any note(), n() or chord() pattern:

track("vox", note("c4 ~ c4 [c4 c4]").s("/Users/me/Samples/vox.wav"));

• c4 plays the file as recorded; other notes play it faster or slower, like a sampler without time-stretch.
• On a track whose role is not a drum role, each note is cut at its length plus 50 ms, so legato() shapes it.
• Paths cannot go inside a pattern string, so a file is set with .s(), or with drum_sound() for a drum lane of a generated song.
• A missing file is an error: track 'vox': /Users/me/Samples/vox.wav does not exist.
• When claudius is shared beyond your computer (a server reached by others), it reads files only from its own folders (saved songs, its caches, the sample packs, Apple Loops) and refuses others with ... is outside the folders this claudius may read.

To use a song or a loop as material, claudius chop cuts bar loops and drum one-shots from it into the user library, and claudius make --sample <file> flips a recording into a new song. See Remaking a song from audio.

Sounds you cannot set from a script

A script names sounds; it does not edit them. The synth presets’ parameters and the tuning and decay of a generated song’s drum voices are set by the generator and changed by evolution. A script can swap them for other sounds: drum_sound() for a drum lane, part() for a generated part’s preset. Pattern tracks can add filters, a bitcrusher and saturation (see Track settings).

Song functions

Song functions edit the current song. Each one changes only what it names, in the order the script calls them. Sections and arrangement are on Form and sections; mix(), master() and the other mixer edits are on Mixing functions.

Starting a song

song()

song(genre)               // a new song, seeded from the clock
song(genre, seed)         // seed: integer
song(genre, options)      // options: map

Replaces the current song with one the generator writes: tempo, key, swing, two progressions, a form, drum lanes, theory-written parts, sounds and a mix, all from the genre’s profile. The same genre and seed give the same song on any machine. The recordings installed (sample packs, Apple Loops) change only which recordings it plays.

The genre is one of house deep_house techno trap lofi dnb future_bass synthwave, or one of your own (see Genres); case, spaces and hyphens do not matter ("deep house"). A negative seed acts as 0. bpm and key change only the tempo and the key: the title, the form, progression A and the drum patterns are the ones the seed gives without them. A key in another mode than the seed’s moves the chords into that mode, as key() does. The options are checked like tempo() and key() check their arguments, and an option the map should not have is an error rather than ignored (so is a misspelt one).

Errors: unknown genre 'polka' (try: deep_house, dnb, future_bass, house, lofi, synthwave, techno, trap); tempo between 40 and 240 BPM; cannot read key 'H minor' (try "A minor", "F#m", "Eb", "D dorian"); song() has no option 'tempo' (options: seed bpm key loops short samples).

song("techno", #{ seed: 3, bpm: 130, key: "F minor", short: true });

blank()

blank(genre)

Replaces the current song with an empty one: a single 8-bar section called loop (kind groove, energy 0.8), no tracks, and one progression, A, which is the key’s tonic chord alone (i in a minor key, I in a major one) at bars_per_chord(1). The rest comes from the genre: the mix (bus effects, master chain, loudness target, reverb and delay), the critic’s genre, and a tempo, key, swing and humanize from the generator. Set the ones you care about; in particular, set prog("A", ...) to the chords you play, since the critic checks the bass and melody against it.

blank("lofi");
tempo(84); key("D minor"); swing(0.58);
track("drums", s("bd ~ ~ bd, ~ sd, hh*8?0.15"));

A script that calls neither song() nor blank() edits the song that is open (the studio’s, or the one passed with claudius script --on), and with no song open it starts from blank("house"). So a script for another genre that should run on its own starts with blank().

Errors: as for song().

Global settings

title()

title(name)    // string

The song’s title, used in the song folder’s name (out/house-night-drive-1/).

tempo()

tempo(bpm)     // number, 40..240
bpm(bpm)       // the same function

Errors: tempo between 40 and 240 BPM; tempo needs a number (also from bpm()).

key()

key(name)      // "A minor", "Am", "F#m", "Eb", "D dorian", "C# phrygian" ...

Sets the key. Roman-numeral progressions and n() patterns follow it; note names in note() patterns do not, since they name absolute pitches. When the mode changes (minor to dorian, major to minor), every diatonic chord in every progression moves to the same degree in the new mode: Imaj7 in a major key becomes i7 in minor, IV7 in dorian becomes iv7 in minor. A borrowed chord keeps its sound and is spelled in the new mode: bIII in F major (A flat) becomes III in F minor, where it is diatonic. Applied chords (V/V) stay as written. Because a borrowed chord can become diatonic, going to minor and back does not always restore the original: bVII becomes VII in minor, and VII becomes vii° back in major. Tonal Apple Loops in the song are repitched the shortest way (at most six semitones).

Errors: cannot read key 'H minor' (try "A minor", "F#m", "Eb", "D dorian").

// G dorian to A minor: "i7 ii7 i7 IV7" becomes "i7 iiø7 i7 iv7"
key("A minor");

The accepted names and modes are in Pitch.

swing()

swing(amount)  // number, clamped to 0..0.8

Sixteenth-note swing for the whole song. Each off-beat sixteenth (the second of each pair) is moved to amount of the way through its eighth note: 0.5 is straight, 0.58 is a lazy hip-hop feel, 0.66 is close to triplets. Values up to 0.501 play straight. Only notes exactly on the sixteenth grid move; eighth notes and triplets stay where they are. Swing applies when the song renders, to drums, parts and pattern tracks alike.

humanize()

humanize(amount)   // number, clamped to 0..1

Random timing and velocity, applied at render. The timing offset has a standard deviation of 4 ms × amount on drum roles and 60 % of that on other tracks (synth tracks use 3 ms instead of 4); velocity varies by 5 % × amount. The offsets are seeded by the song and the track name, so they are the same on every render.

Harmony

prog()

prog(name, chords)   // name: string; chords: string, separated by spaces

Sets a progression. Chords are Roman numerals ("i7 VImaj7 iv7 v7") or chord names ("Am7 Fmaj7 Dm7 Em7"); names are converted to numerals in the current key when prog() runs, so call key() first. Each chord lasts bars_per_chord() bars, and the progression loops.

Sections play A unless they say otherwise (sec().prog()), and breaks play B, or A when the song has no B. Any name works: prog("verse", ...) is used by sections that ask for "verse". The progressions drive chord("prog"), the generated parts, the chord track the critic checks melodies and basslines against, and the harmony tab of the studio. Pitch has the numeral rules.

A chord name outside the key gets an accidental (Bb in A minor is bII). A slash chord keeps its bass note, as a name or as a numeral: F/A in A minor is stored as VI/A, and key() moves the bass note with the chord.

Errors: cannot read chord 'Q7' (Roman numerals like i7 VImaj7 bVII, or names like Am7).

blank("house");
key("A minor");
prog("A", "Am7 Fmaj7 Dm7 Em7");     // stored as i7 VImaj7 iv7 v7
prog("B", "Fmaj7/A G Em7 Am7");     // stored as VImaj7/A VII v7 i7
bars_per_chord(1);
track("keys", chord("prog").s("epiano"));

bars_per_chord()

bars_per_chord(bars)   // integer, clamped to 1..8

How many bars each chord lasts: bars_per_chord(2) holds each chord for two bars. It applies to every progression. blank() starts at 1; a generated song has the generator’s value, often 2.

Drums

drum()

drum(lane, steps)                     // the "main" variant, 16 steps per bar
drum(lane, variant, steps)
drum(lane, variant, steps, per_bar)   // per_bar: integer, clamped to 1..96

Writes a drum lane’s pattern as a step string, the way a step sequencer shows it:

There are 16 steps per bar unless per_bar says otherwise: 32 for thirty-second notes, 12 or 48 for triplet grids. The length of the string decides the length of the pattern, rounded up to whole bars (at most 16): 16 steps are one bar, 20 steps are two bars with the last 12 steps empty. All the variants of a lane have the same length; a shorter one is repeated to fit.

On an existing lane, drum() replaces that variant. On a song without the lane, it creates one, if the name is a drum name (or hats): the lane uses the synthesized voice at its default settings, and joins every section with energy 0.6 or more. drum_sound() changes what it plays.

Sections choose a variant by name with .variant(); intros and outros use sparse, the others main, and a lane without the requested variant plays main.

A lane’s mixing role comes from its name when the name is a drum name (bd and kick are kicks, sd and snare snares), else from the sound it plays. The arranger finds lanes by role: snare rolls and fills go on the snare lane, else the clap; the kick drops out at the end of a build, and the other tracks duck against it.

Errors: no drum lane 'bongo', and drum() makes lanes only for drum names (bd kick sd ...); the song's lanes: kick clap hat ohat shaker perc. For other sounds, track("bongo", s("...")).

drum("kick", "X...x...X...x..x");                     // a pickup into the next bar
drum("hat", "sparse", "..x...x...x...x.");
drum("hat", "main", "x.x.x.x.x.x.x.x.x.x.x.x.x.x.xxxx", 32);

drum_sound()

drum_sound(lane, sound)         // sound: string
drum_sound(lane, sound, bank)   // bank: string, a drum machine or kit

Sets what a drum lane plays, keeping its patterns:

• a drum name, for the synthesized voice: drum_sound("snare", "cp");
• a kit sound from the sample packs: drum_sound("kick", "tr909:bd"), or the same as drum_sound("kick", "bd", "tr909"), with any bank; a variation number picks another recording ("tr909:bd:12");
• another recording from the packs, such as "conga";
• an audio file: drum_sound("perc", "/Users/me/Samples/rim.wav").

Naming the sound the lane already plays keeps it as it is, including the tuning evolution gave a synthesized voice. The lane keeps its name, so a lane named with a drum name keeps its role; a lane named otherwise takes the role of its new sound.

Errors: no drum lane 'bongo' (lanes: kick clap hat ohat shaker perc); drum() makes one, or (lanes: none yet) on a song without drum lanes; 'pad' is not a drum sound (a drum name, a kit sound, or a sample) for a synth preset; the sound errors for a name that does not resolve.

song("house", 9);
drum_sound("kick", "tr909:bd");
drum_sound("clap", "cp", "tr808");

Parts

part()

part(name, options)   // options: map with any of the fields below

Edits a part the theory engine writes: the bass, chords, pad, lead, arp or keys of a generated song. On a song without that part (a blank() song has none), part() first adds the genre’s part, written by the theory engine over the song’s progressions and joining the sections the way a new track does; the options then edit it. part("bass", #{}) adds the genre’s bass as it comes.

A style the part’s role does not have is an error. A decimal seed is ignored.

Errors: no part 'keys' (the song has: bass chords pad lead arp; house parts: bass chords pad lead arp); track() writes your own; a bass part has no style 'wobbly' (styles: sustain pulse root8 ...); unknown preset 'nope' (synths: ...; or an installed instrument such as piano, rhodes, string_ensemble); part() has no option 'styles' (options: style preset register density seed rate).

part("bass", #{ style: "rolling", preset: "reese" });
part("lead", #{ seed: 42, density: 0.4 });
part("chords", #{ style: "stabs", register: [55, 72] });

On a blank song, part() gives you the generator’s parts over your own progression:

blank("house");
key("A minor"); prog("A", "Am F C G");
track("drums", s("bd*4, [~ cp]*2, [~ hh]*4"));
part("bass", #{ style: "offbeat" });
part("chords", #{ style: "stabs", preset: "stab" });

Tracks

track()

track(name, pattern)

Makes a pattern track, or replaces the track of that name: a drum lane, a generated part, a loop or another pattern track (track("bass", ...) on a generated song replaces its bass part). The pattern’s sounds and words are read here, so an unknown sound, a word the pattern cannot read (note("h3")) or a pattern that is too dense fails at this line.

Where it plays:

• A replaced track keeps the replaced track’s place in every section.
• A new track joins every section with energy 0.6 or more, or every section when no section has any track yet (the first track of a blank() song).
• form() and layer() decide it exactly.

Its mix comes from the pattern’s own settings (.level(), .pan(), .room() …); a mix() on the old track does not carry over. Its role comes from .role(), else from its sound (see Roles). A sound pattern with several sounds becomes one track per sound when arranged: drums.bd, drums.cp, drums.hh.

Each track() writes a log line with the sounds it found:

blank("house");
track("drums", s("bd*4, [~ cp]*2, [~ hh]*4"));

track drums: bd, cp, hh

Errors: track 'x': unknown sound 'bdd' (...); track 'x': cannot read 'h3' as a note (...); track 'x': this pattern is too dense to play: it makes more than 262144 events (or it needs more than 4000000 steps of work); track 'x' plays 2048 notes per bar; the limit is 1024. See Errors and limits.

mute(), unmute(), solo(), unsolo(), remove()

mute(track)    unmute(track)
solo(track)    unsolo(track)
remove(track)

mute() silences a track; while any track is soloed, only soloed tracks play, and only they are judged. remove() deletes the track and takes it out of every section. They work on drum lanes, parts, loops and pattern tracks.

Errors: no track 'nope'.

mute("hat");
remove("arp");

Form and sections

The form is the song’s list of sections: an intro, a groove, a break, a build, a drop. Each section has a kind, a length in bars, an energy, a progression, a drum variant, the tracks (layers) that play in it, and flags that ask the arranger for builds, gaps, impacts, fills and filter sweeps. This page says exactly what each one does.

form()

form([sec(...), sec(...), ...])

Replaces the whole form. Sections play in the order given. Two sections with the same name are renamed in order: the second drop becomes drop2, the third drop3.

Every layer must be a track of the song, or one of the genre’s optional parts and loops (which may be absent from a song, and are silent then). "*" and a missing layer list mean every track that exists when form() runs; tracks added later join by the track() rule. Every section’s progression must exist, except B: a section that plays B on a song without one plays A.

Errors: form() takes sec(...) items; section 'drop' uses 'snare', which is not a track (tracks: kick clap hat ohat shaker perc bass chords pad lead arp); section 'drop' plays progression 'C', which the song does not have (progressions: A B; prog() adds one).

form([
  sec("intro", 8, "kick hat perc pad").filter_in(),
  sec("groove", 16, "kick clap hat ohat perc bass chords"),
  sec("break", 8, "pad chords lead"),
  sec("build", 8, "clap hat pad lead").gap(),
  sec("drop", 16, "*").impact(),
  sec("outro", 8, "kick hat perc bass"),
]);

sec()

sec(kind, bars)            // every track
sec(kind, bars, layers)    // layers: "kick hat", ["kick", "hat"] or "*"

bars is an integer, clamped to 1..256. The kind is one of the words below; breakdown, chorus and loop are accepted for break, hook and groove, and the section keeps the word you wrote as its name.

Each kind comes with defaults:

The kind also matters to the arranger (drops and hooks get crashes every 8 bars, a final outro closes a filter) and to the critic, which compares the loudness of drops and hooks with breaks.

Errors: unknown section kind 'party' (intro verse build drop break hook groove outro); layers are a string ("kick hats") or an array of names.

Section methods

Each method returns a new section, so they chain: sec("drop", 16, "*").energy(1.0).impact().

.energy() raises energy needs a number for anything else. A variant that does not exist plays main. A progression that does not exist is an error when form() gets the section, unless it is B (see above).

What the flags do

These are the exact rules of the arranger (compose::arrange). Several act on drum lanes only (the lanes written by the generator or by drum()); pattern tracks are never rewritten, so a song made only of patterns gets the risers, sweeps and crashes but no automatic rolls or fills.

The arranger finds lanes by their role. The fill lane is the first lane whose role is snare (a lane named snare or sd, or one that plays a snare sound), or clap when there is none; the kick lane is the first lane whose role is kick.

build

• The fill lane stops its pattern for the last part of the section and plays a snare roll instead: quarter notes, then eighths, sixteenths and thirty-seconds, with velocity rising from 0.4 to 1.0. The roll lasts half of the section’s first 8 bars, between 1 and 4 bars: 4 bars in an 8-bar build, 2 in a 4-bar one. It is added even when the fill lane is not a layer of the section.
• The kick lane stops for the last bar.
• A riser plays over the last bars of the section: the genre’s riser length (8 bars in house, techno, dnb and future bass; 4 in deep house and synthwave), or the whole section if it is shorter. Trap and lofi have no riser.
• A highpass filter on the music and bass buses sweeps from 10 Hz to 900 Hz across the section and snaps back at the next one.

gap

In the section’s last beat, every track except the riser and the reverse crash is silent: notes that start there are removed and notes that ring into it are cut. Audio loops keep playing. A gap before a drop makes the downbeat land harder.

impact

• A crash on the first beat, at full velocity.
• An impact hit and a downlifter, in genres that use them: house, techno, dnb and future bass have both; deep house has only the downlifter, trap only the impact, synthwave and lofi neither.
• A reverse crash over the last 2 beats of the section before, in genres that use it (all but techno and lofi).

fills

At the end of every 8-bar phrase, counted from the section’s start, the fill lane’s last 1 or 2 beats are replaced by a fill: a sixteenth-note roll, triplets, or a broken groove, at 85 % velocity. At about a third of those phrase ends, the kick drops out for the last half beat. A section shorter than 8 bars gets no fills, and a 12-bar section gets one, at bar 8.

filter_in

A lowpass filter on the music and bass buses opens from 350 Hz to 20 kHz across the section: the classic intro that comes into focus. The drums are not filtered.

Without a flag

• Drops and hooks get a crash every 8 bars after their first bar, at velocity 0.7.
• A final outro (the last section, of kind outro) closes a lowpass on the music and bass buses from 20 kHz, starting 40 % of the way in, down to 500 Hz at the end.
• Every section starts its patterns from their first cycle and its progression from its first chord (see Patterns and time).

Energy

Energy is a number from 0 to 1 that says how intense a section is meant to be. It does not change the sound by itself; what plays decides that. It is used in three places:

• the critic checks that sections get louder where energy rises (the correlation between energy and measured loudness) and that the loudest drop or hook is at least 3 LU louder than the quietest break;
• new tracks made by track() or drum() join the sections with energy 0.6 or more;
• the generator, when it builds a song around Apple Loops, layers the loops into sections by energy.

So set energies that match the layers: a break with three quiet tracks at 0.35, a full drop at 0.95.

section()

section(which, options)   // which: a section name or a 0-based index

Edits one section. A name picks the first section with that name.

The section is checked as form() checks it: its layers must be tracks (or the genre’s optional parts and loops) and its progression must exist. The map takes only the fields above.

Errors: no section 'nope'; no section 12; section() takes a name or an index; section 'drop' uses 'leed', which is not a track (tracks: ...); section 'break' plays progression 'Z', which the song does not have (progressions: A B; prog() adds one); section() has no option 'bar' (options: bars energy prog variant name layers build gap impact fills filter_in).

section("drop", #{ energy: 1.0, layers: "kick clap hat bass chords lead" });
section(0, #{ bars: 16, filter_in: true });

layer()

layer(section, track, on)   // section: name or 0-based index; on: bool

Switches one track on or off in one section, without touching the others. The track must exist, or be one of the genre’s optional parts or loops.

Errors: no section 'nope'; layer() takes a section name or index; no track 'leed' (tracks: ...).

layer("break", "lead", false);
layer("intro", "shaker", true);

Mixing functions

claudius mixes the way an engineer starts a mix: every track has a role, every role has a target loudness, and each track is brought to its target while it plays. Your settings are offsets from that starting point. This page covers roles, levels, panning, sends, sidechain, buses, inserts and the master, and the functions that set them. Mixing and mastering explains how to use them.

Roles

A role says what a track is in the mix. Each role has a target loudness, measured in LUFS while the track plays (silence does not count), before the master stage:

Any other role name gets −19. The transition effects have their own: riser −19, impact −16, downlifter −22, reverse −21. The drum roles (kick snare clap hat ohat shaker perc ride tom crash) also get the full amount of humanize, and an audio file on a drum role rings out instead of stopping at its note length.

How a track gets its role:

• a drum lane: the role of its name when the name is a drum name (kick and bd are kicks), otherwise the role of the sound it plays;
• a generated part: its role (bass, chords, pad, lead, arp, keys);
• a pattern track: .role(name) when the pattern sets it; otherwise, for each sound in it, in this order: the role of a drum name anywhere in the sound’s name (tr808:sd is a snare), perc for percussion from the sample packs (conga, bongo), bass for the bass synth presets (808 is a preset first, so it stays bass), chords for a chord() pattern, bass when the track’s median note is below E3 (MIDI 52), and lead for everything else.

The last rule is the one to watch. A pad written with note() or chord(), an arpeggio, a sampled string section: all become lead or chords unless you say otherwise, and a lead is mixed 3.5 dB louder than a pad and checked by the critic as the melody. Set the role:

blank("house");
track("pad",   chord("<Am F>").s("pad").role("pad"));
track("arp",   n("0 2 4 7").scale("A:minor").octave(4).fast(2).s("pluck").role("arp"));
track("conga", s("~ conga ~ [conga conga]"));   // perc without being told

Genres shift some targets: techno’s kick +1 dB; trap’s bass +1.5, kick −1, hat −1; lofi’s kick −1.5, snare −0.5, keys +2.

Level

The gain a track receives is target of its role + genre offset + its level, minus its own measured loudness, limited to −40..+30 dB. level is therefore relative: level: -4 on a pad puts it 4 dB under where a pad normally sits, whatever its sound or velocity. Two tracks with the same role and level play equally loud.

Pan

pan runs from −1 (left) through 0 to 1 (right) and works as a balance control: the far side is turned down and the near side stays at full level. At ±0.5 the far side is about 5 dB down; at ±1 it is silent.

Sends

Every track has two sends, reverb and delay, from 0 to 1. They feed two returns shared by the whole song, whose settings come from the genre:

The sends are taken after the track’s level, sidechain and pan. The returns are ducked by the kick too, by 30 % of the full depth, so tails breathe with the groove.

Sidechain

duck (0..1) is the depth of sidechain ducking from the kick. At each kick, the track’s gain falls to 1 − duck 3 ms before the hit and recovers over the genre’s release time (0.25 beats in trap and dnb, 0.45 in future bass, 0.3 to 0.35 elsewhere), along a curve that comes back quickly at first. At duck: 0.85 a chord nearly vanishes on each kick and swells back: the future-bass pump.

The kick is the first track whose role is kick; a song without one ducks nothing. Pattern tracks start with duck 0.3, except drum sounds and the kick itself, which start at 0. Generated parts take the genre’s values (in house: bass 0.55, chords 0.45, pad 0.5, lead 0.2).

Buses

Each track plays into a bus, and the buses are summed with the reverb and delay returns into the master:

On top, each genre has its own chain per bus (house: a glue compressor on the drums and a 110 Hz highpass on the music bus; lofi: a bitcrusher, a lowpass and a compressor on the drums). The arranger adds filter automation to the music and bass buses: the lowpass of filter_in(), the highpass sweep of a build, the lowpass closing in a final outro. The drums bus is never filtered. A script cannot move a track to another bus or edit the bus chains.

Inserts on pattern tracks

A pattern track can carry its own effects, set with track settings. They run in this order, before the level stage:

1. .hpf(hz): a highpass filter (resonance 0.1);
2. .lpf(hz) / .cutoff(hz): a lowpass filter (resonance 0.15);
3. .crush(bits): a bitcrusher, 1 to 24 bits;
4. .distort(db): tanh saturation with that much drive.

Because the level stage comes after, saturation and filtering change the tone, not the loudness.

Functions

mix()

mix(track, options)   // options: map with any of the fields below

mix() works on drum lanes, parts, loops and pattern tracks. On a pattern track it overrides what the pattern set (.level(), .pan() …), until the next track() for that name resets the mix to the pattern’s settings. The names fx and transitions address the transition effects (crashes, risers, impacts).

Errors: no track 'nope'; mix() has no option 'volume' (options: level pan reverb room delay duck mute solo).

mix("pad", #{ level: -4, reverb: 0.45 });
mix("lead", #{ pan: 0.2, delay: 0.25, duck: 0.2 });
mix("fx", #{ level: -3 });

master()

master(options)   // options: map

The master stage runs the genre’s master chain (EQ, a glue compressor, saturation; tape and vinyl in lofi), then searches for the input gain that lands the song within 0.15 LU of lufs, through a soft clipper 0.1 dB under the ceiling and a limiter 0.5 dB below it, and trims the result if the true peak still pokes over. The genre targets are house −10, deep_house −11, techno −9, trap −9, lofi −12.5, dnb −8.5, future_bass −9, synthwave −10.5 LUFS.

Every printed song has a master() line with these two values (see Printing a song).

Errors: master() has no option 'loudness' (options: lufs ceiling).

master(#{ lufs: -9, ceiling: -1 });

mute(), solo() and the others

mute(), unmute(), solo(), unsolo() and remove() are on the song functions page. When any track is soloed, everything else is left out of the arrangement, including the transition effects (unless fx is soloed), and the critic judges only what is left.

Songs as scripts

Every song can be printed as a script, whether it was generated, written by hand, edited in the studio, mutated or remade from audio. The printed script is the readable form of the song: its tempo and key, its progressions, every drum lane as step strings, every generated part with its settings, every pattern track’s code, the form and the mix settings that differ from the defaults.

The guarantee

Running a song’s printed script on that same song changes nothing. The test suite checks this for generated songs in several genres and for songs built from patterns. It is what makes the printed script useful: copy it, change one line, run it, and only that line changes.

The guarantee is about running the script on the song it came from. Run anywhere else, a printed script is a recipe for the song only as far as the header and What is not printed allow.

Where to get it

What a printed script looks like

This script:

blank("house");
title("Night Drive"); tempo(122); key("A minor"); swing(0.54);
prog("A", "Am7 Fmaj7 Dm7 Em7");
bars_per_chord(1);
track("drums", s("bd*4, [~ cp]*2, [~ hh]*4"));
track("keys", chord("prog").struct("x ~ ~ x ~ ~ x ~").s("epiano").room(0.25));
drum("snare", "....x.......x...");
form([sec("intro", 8, "drums").filter_in(), sec("drop", 16, "*").impact()]);
mix("keys", #{ level: -2 });

prints as:

// Night Drive — house (seed 1)
// blank("house");   // uncomment to build this song from nothing (as it is, the script edits the song open)
title("Night Drive"); tempo(122); key("A minor"); swing(0.54);
humanize(0.25);
prog("A", "i7 VImaj7 iv7 v7");
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("snare", "main", "....x.......x...");

// pattern tracks (mini-notation, Strudel style)
track("drums", s("bd*4, [~ cp]*2, [~ hh]*4"));
track("keys", chord("prog").struct("x ~ ~ x ~ ~ x ~").s("epiano").room(0.25));

form([
  sec("intro", 8, "drums").filter_in(),
  sec("drop", 16, "*").impact(),
]);

mix("keys", #{ level: -2 });
mix("fx", #{ reverb: 0.25 });

Things to notice:

• Chord names are printed as the Roman numerals they were stored as.
• bars_per_chord() and master() always print. Other settings print only when they differ from what the song would have without them: humanize() when it is not 0, a section method when it differs from the kind’s default, a mix() field when it differs from the track’s starting mix.
• A pattern track’s mix line compares against the pattern’s own settings, so .room(0.25) stays in the code and is not repeated in mix().
• The drum lane prints every variant, with the variant name, so a step string from the studio’s sequencer reads back exactly. A lane that plays something other than what its name gives (a kit sound, a sample, another drum voice, a variation such as bd:3) also prints a drum_sound() line. A one-shot cut from Apple Loops or your library prints as a comment with its label, such as // shaker: shaker cut from 'Cosmic Harmony Shaker' (Apple Loops): the cut file lives in claudius’s cache, so a path would mean nothing on another computer.
• A generated part prints its style, preset, register, density and seed, and an arp part its rate.
• mix("fx", ...) is the transition effects’ mix (crashes and risers), which comes from the genre.

How values print

• Numbers print as the shortest text that reads back as the same value: swing(0.54), density: 0.42195085. Nothing is rounded.
• Drum steps print at 16 steps per bar when every hit sits on a sixteenth, else 32, else 48 (with the number after the string). A hit prints as X at velocity 0.85 or more, x from 0.5, o below. Reading the string back keeps the exact velocities as long as the string is unchanged, so drum("hat", "main", "x...") on a lane whose hits print that way leaves them alone. A lane whose bars are all the same prints one bar.
• Seeds print as signed 64-bit integers, so a large seed can print negative (seed: -8861390911444144378); it reads back as the same seed.
• Closures print with the values they used: .every(2, |x| x.add(7)), even if the script wrote x.add(up).

What is not printed

These are part of the song but not of its script. Running the printed script on the same song keeps them; running it anywhere else does not recreate them.

• the settings the generator or evolution gave a synthesized drum voice (its tuning, decay and the rest): no drum word plays them, so there is nothing to print. A voice that a drum word plays exactly, such as the variation bd:3, prints as that word;
• one-shots cut from Apple Loops or your library, which print as a comment naming them;
• the patch of a generated part beyond its preset name (the generator’s variation and evolution’s tweaks), its voice count and voicing style;
• Apple Loops layered into the song as loops, and flipped samples;
• the effects on tracks and buses, the reverb and delay settings, and the master chain (all from the genre);
• the transition sounds and settings;
• the song’s history (the lineage shown in the studio’s log).

The header

The first two lines say what the song is and how it began: // song("house", 9); for a generated song, // blank("house"); for one that began empty. The second line is a comment, so the script edits whatever song is open: running it on its own song changes nothing. With no song open (claudius script without --on), a script starts from a blank house song, so a printed script run on its own needs that line. Uncomment it to start over:

• A song that began with blank() and was made by scripts is rebuilt exactly, unless it has something from the list above.
• A generated song is generated again from its seed, and the lines after the header re-apply the edits. song() picks the Apple Loops one-shots again from your library. What was changed after generation and is in the list above (evolution’s tweaks, a flipped sample) is not recreated.

Errors and limits

When a script fails, nothing it did is kept: the song stays as it was before the script ran. This page shows what errors look like, lists the mistakes that do not raise an error, and gives the limits a script runs under.

What an error looks like

claudius script prints the error and exits with status 1:

song("house", 9);
tempo(300);

Error: Runtime error: tempo between 40 and 240 BPM (line 2, position 1)

The line and position point at the call that failed. In a chain, that is the innermost call that raised the error, so a bad pattern string points at s( rather than at track(. The studio and the MCP tools report the same message.

Errors come in four kinds:

“Function not found” covers typos (trak, gian), a decimal where an integer is needed (octave(4.5), bars_per_chord(1.5)), a missing or extra argument, and a method called on the wrong thing. The last one is common: track("x", s("bd")).gain(0.5) calls .gain() on what track() returns, which is nothing, and fails with Function not found: gain ((), f64). Put the method inside the parentheses.

Errors by function

The messages, as printed after Runtime error:.

Errors about the words of a pattern (cannot read ... as a note) are raised by track(), when the pattern is first played, so they point at the track( line.

Silent mistakes

These run without an error and do something you may not expect.

Limits

A script runs under these limits, so a mistake cannot hang claudius or fill its memory:

A script reads no files except the audio files named in .s(), and writes none. When claudius is shared beyond your computer, .s() reads only inside claudius’s own folders (see Your own files).

What the language does not do

• Time: every bar has four beats; there are no other time signatures, no tempo changes within a song, and no key changes within a song.
• Automation: there is no general automation lane. Filter sweeps come from section flags (build, filter_in, the final outro), and level changes come from layers and energy.
• Sound design: scripts choose presets and instruments and add simple inserts; they do not edit synth patches or drum voices (see Sounds).
• Arrangement edits per bar: a track plays the same pattern in every section it is in, from the section’s start. For a variation in one section, make a second track and put it in that section only.

Quick reference

Everything on one page. Each name links to its full entry.

Starting