Subsystem Search

subsample commands

The 5 commands subsample runs directly, each with its arguments and options.

subsample import

subsample import [-h] [--to DIR] [--force] [--config PATH] [FILE ...]

Import pre-trimmed audio files into the Subsample capture library. It reads WAV, BWF, FLAC, AIFF, OGG and anything else libsndfile can read.

output: A line for each file imported: its name, its length in seconds, and its peak and loudness (rms) in dBFS. A file not imported says why.

Arguments

Options

subsample catalog

subsample catalog [-h] [-o FILE] [--full] [--pitched] [--quantizable] [--loopable] [--group] [--similarity-threshold T] [--order {name,similarity}] [--config PATH] [directory]

Write a CSV of every sample's detected properties, or list samples matching a capability filter

columns:
  pitched        passes the stable-pitch test, so `pitched: true` selects it
                 and it can be re-pitched across a keyboard
  quantizable    has at least two hits, so `stretch_quantize` and
                 `pad_quantize` can align them to a beat grid
  loopable       holds a steady sound worth looping while a key is held, so
                 `loopable: true` selects it; loop_ms is the loop found,
                 blank when no clean loop point was found
  impact_ms      how far into the file the loudest event begins: 0 for a
                 struck drum, later for a hi-hat pedal or a shaker drawn
                 back before the beat; a note sent ahead over OSC starts
                 the sound that much early, so the hit lands on its time,
                 if impact_pre_db is -10 or lower; it varies from take to
                 take
  impact_pre_db  the level before that event, against the sample's peak;
                 near 0 dB, the file holds several events of similar
                 loudness
  pitch_hz, pitch_confidence, pitch_stability_st, voiced_fraction,
  voiced_frame_count, harmonic_ratio, duration_s
                 the seven measures the stable-pitch test reads, to see why
                 a sample passes or fails it
  snr_db         how far the loudest moment rises above the quiet ones; low
                 means room tone with no real event in it
  near_silent    nothing in it is loud enough to be an event
  clipping_risk  it peaks at digital full scale, and may be distorted
  noisiness      from 0, a clean hit or tone, to 1, noise from end to end;
                 a sustained unpitched sound scores high too
  band_sub_bass, band_low_mid, band_high_mid, band_presence
                 each spectral band's share of the sound's energy
  group, group_size, group_keeper
                 with --group: the pile of near-identical takes a sample is
                 in, how many takes it holds, and yes for the suggested take
                 to keep, the loudest, whose clipping_risk is worth a look

The capability columns run the tests the player runs, so they show the pool a MIDI map would draw from.

It reads the directory and every directory within it. The first run over files without sidecars analyses each, as a start-up does, and keeps the results as sidecars, so later runs are quick; progress goes to stderr and the data to stdout.

--pitched, --quantizable and --loopable combine: a path is listed when it passes every one given.

Arguments

Options

subsample analyze

subsample analyze [-h] [--config PATH] FILE [FILE ...]

Analyse audio files and print their detected metrics (rhythm, spectral, pitch, level, loop).

output:
  rhythm     the tempo in BPM, and the beats, pulses and onsets found
  attacks    each hit's start in seconds, and its level in dB against the
             loudest hit, which reads 0.0dB, measured from its attack to the
             next hit; hits evenly spaced and within a few dB of one another
             quantise well, and one 20 dB below the rest is a ghost note
  spectral   the length in seconds, then measures from 0 to 1:
               flatness    0 tonal, 1 noisy
               attack      0 instant, 1 a gradual build
               release     0 a sudden stop, 1 a long decay
               centroid    0 bassy, 1 bright
               bandwidth   0 a pure tone, 1 spectrally complex
               zcr         how often the wave crosses zero: 0 smooth, 0.5 white
                           noise, 1 at every sample
               harmonic    0 percussive, 1 harmonic
               contrast    0 a flat spectrum, 1 strong spectral peaks
               voiced      the share of the sound with a detected pitch
               log_attack  0 an instant onset, 1 a very slow one
               flux        0 a steady spectrum, 1 a fast-changing one
               rolloff     0 energy low down, 1 energy reaching the top
               slope       0 bass-heavy, 0.5 about flat, 1 treble-heavy
  pitch      the pitch in Hz and its pitch class (chroma), or none;
             pitch_conf, from 0 to 1, is how sure the pitch is, stability is
             how far it wanders in semitones, and voiced_frames how many
             frames hold a pitch
  level      the peak, the loudness (rms) and, when it can be measured, the
             room's floor, in dBFS, and the crest factor, peak over loudness,
             in dB; rms sets the playback gain
  noisiness  from 0, a clean hit or tone, to 1, noise from end to end such as
             static; a sustained unpitched sound scores high too
  loop       the loop found, its length and crossfade, and junction_flux,
             about 1 or below for a seamless join and higher as the join
             grows audible; none when there is no clean loop

Arguments

Options

subsample similar

subsample similar [-h] [--top N] [--config PATH] [--reference-dir DIR] [SOUND]

Show the instrument samples most similar to each reference, or to one sound

output: For each reference, or for the sound given, the library samples most like it, best first: the rank, the sample's number in this run, how alike the two sound, where 1 is the same, the sample's name and its file. A sound from the library is not listed among its own matches.

Arguments

Options

subsample loops

subsample loops [-h] [--render DIR] [--force] [--all] [--config PATH] paths [paths ...]

Find and audition loop points for loop-candidate samples

output: A line for each sample tried: where its loop starts and ends in seconds, the loop's length, the crossfade across its join, junction_flux, about 1 or below for a seamless join and higher as the join grows audible, and the tail left after the loop for the note's release. A sample with no clean loop plays without looping.

Arguments

Options