Subsystem Search

Subsample configuration: recorder

The 16 settings under recorder, each with the type, default and limits its schema declares.

Live capture from an audio input. Subsample tracks the room's background level, starts a recording when a sound rises above it, and writes each sound to its own file.

enabled in recorder

Type
boolean
Default
true

Turns live capture on. Set false to process only the files named on the command line, or to run the player alone.

directory in recorder

Type
string
Default
samples/captures

Directory that recordings are written to, absolute or relative to the directory Subsample runs in. Subsample creates it when it is missing. The default is also the default library.directory, so every recording joins the playable library.

filename_format in recorder

Type
string
Default
"%Y-%m-%d_%H-%M-%S-%3f"
Example
"%Y%m%d_%H%M%S"

Name of each recording, as a strftime format without an extension. %3f adds zero-padded milliseconds. The time is the moment the recording ended, so a format without %3f gives two recordings that end in the same second the same name, and the later one replaces the earlier. A / makes folders inside recorder.directory: %Y-%m-%d/%H-%M-%S-%3f gives a folder a day.

previews in recorder

Type
boolean
Default
true

Writes a visual preview of every captured or imported sample: a .preview.png thumbnail beside the audio, and the data it is drawn from inside the .analysis.json sidecar, from which a missing thumbnail is redrawn at the next start-up without analysing the audio again. A file manager shows the thumbnail as a file of its own, not as the audio file's icon, since Subsample never writes into an audio file. The thumbnail, 1024 by 256 pixels, draws the waveform over the sound's four spectral bands, each as tall as its share of the energy, so a kick sits low and a cymbal high; a tick marks each onset, dashed lines mark the beats of a rhythmic sound, and a badge in the corner gives its pitch, tempo and length. Set false to write neither.

audio in recorder

Type
section

The input device, and the format Subsample captures in.

device in recorder.audio

Type
string or null
Default
null
Examples
"Samson Go Mic", "SC-U: USB Audio (hw:*,0)"

Input device to capture from, matched against device names without regard to case. The value may use wildcards: * matches any run of characters and ? matches one, and it may match anywhere in the name. A name can carry a number the system assigns at each start, such as the card index in hw:2,0: write * for that number and keep the one after it, which does not move, as in hw:*,0. Prefer * to ?, which stops matching once the number has two digits. On Linux with PipeWire, the names beginning alsa_input.usb- are built from the device's own identity and hold no number that moves. A device's full name selects that device, even where a longer name contains it. When the value matches several devices, Subsample asks which to use, offering only those; when it matches none, it warns and asks from every input device. With no terminal to ask in, it lists the devices and stops rather than waiting. null selects the only input device when there is one, and otherwise asks. subsample --list-devices prints the names.

sample_rate in recorder.audio

Type
integer
Default
44100
Limits
above 0

Capture sample rate, in Hz. The input device must support it.

bit_depth in recorder.audio

Type
integer
Default
16
Limits
one of 16, 24, 32

Bits per sample, for live capture and the samples cut from it. A recording read from a file keeps its own bit depth and sample rate, as an imported file does.

channels in recorder.audio

Type
integer or null
Default
null
Limits
above 0

Number of input audio channels to capture. null uses as many as the selected device reports. Must be 4 when ambisonic_format is set.

input in recorder.audio

Type
list of integer or null
Default
null
Example
[3, 4]

Physical inputs to record from, numbered from 1 as the interface labels them. null records from the first inputs, as many as channels. The list's length must match channels, and sets it when channels is null.

buffer_frames in recorder.audio

Type
integer
Default
512
Limits
above 0

Frames the input device delivers at a time. Smaller values lower input latency, and larger ones use less CPU.

audio_format in recorder.audio

Type
string
Default
wav
Limits
one of wav, flac

File format for captured and imported samples. wav is uncompressed and supports 16, 24, and 32-bit. flac is lossless and smaller, and supports 16 and 24-bit: under flac, a 32-bit imported file is still written as .wav, and live capture with bit_depth: 32 is refused at start-up, so under flac a folder fed from mixed sources holds both kinds. Samples already in the library load whatever this is set to.

ambisonic_format in recorder.audio

Type
string or null
Default
null
Limits
one of a_generic, a_nt_sf1, b_ambix, b_fuma

Treats the four input audio channels as ambisonic, and stores each recording as first-order AmbiX B-format. a_generic is tetrahedral A-format with the capsules in the order front-left-up, front-right-down, back-left-down, and back-right-up. a_nt_sf1 is the Rode NT-SF1's A-format, with capsule-matching correction. b_fuma is B-format in FuMA order, which Subsample reorders and renormalises. b_ambix is B-format already in AmbiX order, stored as it is. null turns ambisonic capture off. Requires channels: 4. Files cut into samples are treated the same way when they have four audio channels, and are cut as they are otherwise.

float_import_ceiling_dbfs in recorder.audio

Type
number or null
Default
-1
Limits
at most 0

Highest peak level, in dBFS, for 32-bit float and 64-bit audio that Subsample reads from the command line, a MIDI map's directory: or path:, an OSC import, or the library watcher. A file whose peaks go above it is scaled down as a whole, which keeps its dynamics, instead of clipping. Integer audio is never changed. null clips such peaks instead.

buffer in recorder

Type
section

The rolling buffer that holds incoming audio while a recording is open.

max_seconds in recorder.buffer

Type
integer
Default
60
Limits
above 0

Length of the rolling capture buffer, in seconds. A recording can be no longer than this, so set it above the longest sound you expect to capture. One that reaches it is cut there, and Subsample then measures the room's background level again, as it does at the start, in case the room itself has got louder.