Sample packs

The sample packs are recordings of real instruments and drum machines, mapped so that claudius can play any note at any velocity with them. Every pack in the default set is under a licence that lets you make and publish music with it. Without packs claudius synthesizes every sound; with them, genres reach for a Rhodes, an upright bass or a real 909 where those belong.

Packs live in ~/Library/Application Support/claudius/packs on macOS and ~/.local/share/claudius/packs on Linux, or in $CLAUDIUS_PACKS. Each pack is a folder with an index.json (its licence, attribution, files and how every instrument maps onto them) and a files/ folder.

The packs

claudius-packs list shows every pack with its state and licence. The 14 default packs hold 162 instruments:

The download is about 2.2 GB, larger than the 1.2 GB on disk, because vsco2, vcsl, tr909, doublebass, growlybass and voice arrive as WAV and are converted to lossless FLAC as they install. Where a pack was cut for size (the piano keeps 5 of its 16 velocity layers, VSCO leaves out the tremolo and muted brass), the pack’s description in claudius-packs list says what was left out.

Two more packs install only when you name them:

Three are opt-in: their licences are unclear or carry conditions, and they install only with --accept-licence.

All three install lazily: their samples download the first time a song plays them. 0007 Which samples we ship explains how packs are chosen.

Installing

claudius setup                          # the default packs and the listening models, asking first
claudius-packs install --defaults       # the default packs only
claudius-packs install splendid          # one pack
claudius-packs install mridangam --accept-licence

Curated packs come from their authors’ GitHub repositories at pinned commits, except tr909 (a zip from audiorealism.se) and the FreePats drawbar organ (a .tar.xz from freepats.zenvoid.org), which are unpacked with the system’s tar (or unzip). Each file downloads to a .part file, is checked against its expected size, and is renamed into place, so an interrupted install resumes where it stopped: run the same command again. Installing a pack that is already there downloads only what is missing and deletes files its index no longer uses.

Listing a repository uses GitHub’s API, which allows 60 requests an hour without an account. If an install fails with set GITHUB_TOKEN if the API rate limit was hit, set GITHUB_TOKEN (or GH_TOKEN) to any GitHub token and run it again.

Removing

claudius-packs remove splendid

remove deletes the folder <packs>/<name> and everything in it. It takes a plain pack name, as claudius-packs list shows it, and only for a pack that is installed (its folder has an index.json) or that the registry knows, which covers a half-finished install. Anything else is refused and nothing is deleted:

$ claudius-packs remove ..
Error: '..' is not a pack name
$ claudius-packs remove nonexistentpack
Error: pack nonexistentpack is not installed

Paths are refused the same way as ..: a/b and absolute paths are “not a pack name” too.

Names

A script or a genre asks for an instrument by name, and the installed packs decide what plays:

claudius-packs resolve answers what a name plays on your machine, and claudius-packs aliases lists every friendly name with what it resolves to now (262 of them with the default packs):

$ claudius-packs resolve piano
salamander:piano
$ claudius-packs resolve bd:2 909
tr909:bd:2
$ claudius-packs resolve sd acoustic
muldjord:sd
$ claudius-packs resolve theremin
Error: nothing installed matches theremin

In scripts, drum names and synth presets are looked up before the packs, so s("bd") plays the synthesized kick and .s("epiano") the FM synth. Sounds has the full order and the names to use for the recordings.

Banks and variations

A bank is a drum kit picked by name. s("bd*4, [~ sd]*2, hh*8").bank("tr909") plays all three on the 909. Banks answer to the pack’s name and its aliases:

Drum names have synonyms (kick, kd, bassdrum for bd; snare for sd; rimshot, sidestick for rim; and so on), so s("kick").bank("808") works. A variation picks another recording of the same drum: bd:2 in the pattern, or .n("0 1 2"). The drum machines have many:

• tr808: every knob at five positions, 25 variations of bd, sd and the cymbal (tone by decay, or tone by snappy), 5 of the toms, congas and open hat;
• tr909: variation 0 of every drum plays its 11 accent levels as velocity layers; the others are the knob sweeps (125 for bd and sd, 121 for the toms, the decay of the hats, the tuning of the cymbals);
• tr707: one recording per sound.

claudius-packs instruments shows how many variations each instrument has.

Strudel sample maps

Any Strudel sample map can be added as a pack of your own:

claudius-packs add-map github:tidalcycles/uzu-drumkit       # reads strudel.json on the main branch
claudius-packs add-map github:user/repo/branch/sub/folder   # strudel.json in that folder
claudius-packs add-map https://example.org/samples.json

added tidalcycles-uzu-drumkit (16 sounds, licence Unlicense, lazy)

The pack is named after the GitHub owner and repository (tidalcycles-uzu-drumkit; a curated pack’s name is refused), and installs lazily: each sample downloads the first time a song plays it. Its sounds take the names in the map, so a map with RolandTR909_bd answers to s("bd").bank("RolandTR909"). The licence comes from the map’s _license field or, failing that, from the GitHub repository. When there is none, it is recorded as unknown, add-map prints a warning, and every song that uses the pack says so in its credits.txt. claudius-packs install <name> downloads all of a user pack’s samples at once.

Credits

A song that plays sample-pack instruments gets a credits.txt next to it with the packs it used, and only those:

Sounds:
- E-Pianos (Yamaha CP80, Hohner Pianet T, Wurlitzer EP200) by Greg Sullivan (CC BY 3.0), SFZ mapping by kinwie / sfzinstruments https://creativecommons.org/licenses/by/3.0/
- jRhodes3d by Jeff Learman [jRhodes licence: free for making music (CC0 for musicians); redistributing the samples: CC BY-NC 4.0] https://github.com/sfzinstruments/jlearman.jRhodes3d/blob/master/LICENSE
- Roland TR-808 samples by Michael Fischer (Technopolis, 1994), packaged by TidalCycles [CC0-1.0] https://creativecommons.org/publicdomain/zero/1.0/
- VS Chamber Orchestra 2: Community Edition by Versilian Studios (CC0); recorded by Sam Gossner and Simon Dalzell [CC0-1.0] https://creativecommons.org/publicdomain/zero/1.0/

The packs whose licence requires credit (CC BY) come first, then the others as a courtesy, then a Warning: licence unknown for ... line for any pack without a known licence. When you publish the song, put the lines of the packs that require credit where you credit the music.

claudius-packs credits prints the required credits of every installed pack, and claudius-packs credits piano rhodes bd@tr909 those of the packs behind specific names (name@bank for a drum in a bank).

Auditioning

$ claudius-packs instruments
salamander:piano                     piano                pitched   A0..C8   layers 5  rr 1  zones 150  variants 1
epianos:wurlitzer                    electric piano       pitched   A1..G#6  layers 4  rr 1  zones 48   variants 1
vcsl:marimba                         mallets              pitched   F2..C7   layers 1  rr 1  zones 30   variants 1   one-shot
...

Memory

Decoded samples stay in memory once played, up to 3072 MB by default (CLAUDIUS_PACKS_CACHE_MB changes the budget). When a new sample takes the cache over budget, the samples used longest ago that nothing is playing are dropped until it is back to 80 % of the budget; they are decoded again the next time they play.