Files and settings

claudius keeps songs, sounds, models and caches in separate places, so that each can be backed up, moved or deleted on its own. The paths below are for macOS and Linux; where an environment variable moves a folder, it is named.

Where everything is

On Linux, $XDG_MUSIC_DIR comes from ~/.config/user-dirs.dirs; without it, the studio saves under out in the folder it was started from. The web studio keeps its preferences in the browser’s local storage.

Song folders

A song folder holds a song in every form claudius has for it. One function, song::write_folder, writes every folder, whether the CLI (make, script, render, remake, evolve, mutate) or a save in the studio or over MCP made it, so they hold the same files:

Stems are floating point because a track can peak above full scale before the master’s limiter brings the mix down. claudius judge runs its arrangement and theory checks when project.json sits next to the audio, so any song folder gets the full verdict.

blueprint.json is the song: claudius render, claudius script --on, claudius evolve --from, claudius mutate, and open in the studio and the MCP tools all start from it. The song model describes its fields. Every later claudius opens it; a newer claudius’s song, in a format this one does not read yet, says so and asks for an update. A blueprint that plays audio files (Apple Loops, chops, files from scripts) stores their paths, so it plays on another computer only where those files exist.

Caches

Everything in the cache folder can be deleted while claudius is not running; it is rebuilt on demand.

A session keeps its last ten renders and deletes older ones as it goes. When a session starts, it deletes the render folders of sessions that last wrote more than 12 hours ago, so a session that crashed leaves its renders behind for at most that long. decoded/ and stretched/ are never trimmed: on a machine that renders and analyses a lot, they reach gigabytes, and deleting them costs only the time to decode again.

The pack installer’s scratch space holds downloaded archives and their unpacked files only while a pack installs, and is removed afterwards.

Sample packs and models

A pack is a folder under the packs folder with an index.json and a files/ folder; Sample packs covers installing and removing them. claudius-packs list prints the folder in use.

The models live under models/<repository>/<revision>/ in the models folder, one revision folder per pinned model, with CLAP’s text embeddings of earshot’s vocabulary cached in text/clap-d78c3994912c.bin. Deleting the folder makes the next verdict download 785 MB again (1.13 GB with the AudioSet tagger).

Your genres

A genre is a JSON file. claudius loads its eight built-in genres, then every .json file in your genres folder; a file whose name matches a built-in genre replaces it. The fields are those of crates/claudius/data/genres/house.json; copy it, rename the name, change what you like, and claudius genres lists it. A file that does not parse makes every genre lookup fail, the built-in genres included, so make and song() fail with Error: genre file <path> and the JSON error under Caused by:, and the studio’s list of genres comes up empty. Fix or move the file and try again.

The web studio

claudius studio, serve and mcp serve the web studio at / from the first of these folders that has an index.html:

1. --web <dir>, or CLAUDIUS_WEB;
2. share/claudius/web next to the program’s folder (~/.local/share/claudius/web for ~/.local/bin/claudius);
3. web inside the program’s folder;
4. crates/claudius-ui/dist of the checkout the program was built from (cargo xtask web builds it there).

Without one, / shows a page that says how to build it, and the API and MCP work as usual.

Assistant configuration

claudius connect edits these files, keeping a copy of the previous version as <file>.bak:

Environment variables

The install script reads CLAUDIUS_VERSION, CLAUDIUS_INSTALL_DIR and CLAUDIUS_DOWNLOAD_URL; see Install.