A project folder

By the end of this chapter you have a folder for your project, and you know what each file in it is for and where Subsample looks for its settings.

Subsample works in a folder, and the folder is the project: its settings, its MIDI maps and every sample it records live there. Each chapter from here on adds to the one you make now.

Make one

Make a folder, move into it, and ask Subsample to fill it:

$ mkdir kitchen-kit
$ cd kitchen-kit
$ subsample --init
Created a Subsample project in /home/keanu/kitchen-kit:
  config.yaml              every setting documented; the GM kit map is pre-wired
  midi-map-gm-drums.yaml   instant GM drum kit - plays your closest-matching samples
  midi-map.yaml            a commented template for building your own map
  samples/captures/        recordings land here, and the library loads from here

The 47 GM reference fingerprints the kit matches against are built in - the
map names them, so nothing was copied and the map stays portable.  Set
library.reference_directory to match against your own references instead.

Next: connect a microphone and run `subsample` to start capturing sounds.
To play the kit, set player.enabled: true in config.yaml (plus your MIDI
and audio devices), then play MIDI channel 10.

--init refuses to write over a file that is already there, so run it in an empty folder.

What each file is for

• config.yaml holds Subsample's settings. Every setting is in it, each with a comment saying what it does, and one line differs from Subsample's defaults: the line naming the drum kit's map.
• midi-map-gm-drums.yaml is a drum kit ready to play. Each drum note of General MIDI plays whichever of your samples sounds most like that drum.
• midi-map.yaml is the start of a map of your own: a drum kit and a keyboard that play as they are, below examples written as comments.
• samples/captures/ is where Subsample saves what it records, and where it loads your samples from when it starts.

It also writes a .gitignore, for a project you keep in Git, which leaves out the processed sounds Subsample keeps and can always make again.

What a configuration holds

Subsample carries its own defaults, and reads your config.yaml over them, so a configuration only has to say what differs from them. The file --init wrote lists every setting, which makes it a good place to read about them, but as far as Subsample is concerned it says no more than this:

player:
  midi_map: midi-map-gm-drums.yaml

The file is YAML. Each line is a name, a colon and a value, and a name indented under another belongs to it, so this sets midi_map in the player section. Indent with spaces, never tabs. A name has to be spelled exactly: Subsample ignores a setting it does not know, and says so in one line among everything else it prints as it starts.

Each setting has its own entry in the configuration reference, which is made from the code that reads your file: its type, its default, the values it takes and an example. player.midi_map is the one above.

Where Subsample looks

Subsample reads config.yaml from the folder you run it in. That folder is the project, and the files a configuration names, such as its MIDI map, are found from it, so start Subsample from inside the project folder. If there is no config.yaml there, Subsample runs on its defaults alone, and says so as it starts.

A configuration kept somewhere else is named with --config:

Example not checked: it is not run when this site is built.

$ subsample --config ../shared/config.yaml

The folder you run it from is still the project, so its map and its samples are still the ones there.

With the project made, the next chapter records ten sounds in one room and turns them into a drum kit.