Subsample MIDI map: choosing a sample
select_spec
- Form
- a block of keys
One way of choosing a sound: which samples qualify, how they are ranked, and which of them plays.
where in select_spec
- Form
where
order in select_spec
- Form
order
order_by in select_spec
- Form
order
The older spelling of order.
pick in select_spec
- Form
pick
order_clause
- Form
- one of those listed below or a block of keys
One ranking: what the samples are ranked by, and which way round.
Accepts one of:
newest: The older spelling of{by: age, dir: desc}.oldest: The older spelling of{by: age, dir: asc}.duration_asc: The older spelling of{by: duration, dir: asc}.duration_desc: The older spelling of{by: duration, dir: desc}.pitch_asc: The older spelling of{by: pitch, dir: asc}.pitch_desc: The older spelling of{by: pitch, dir: desc}.onsets_asc: The older spelling of{by: onsets, dir: asc}.onsets_desc: The older spelling of{by: onsets, dir: desc}.tempo_asc: The older spelling of{by: tempo, dir: asc}.tempo_desc: The older spelling of{by: tempo, dir: desc}.loudest: The older spelling of{by: level, dir: desc}.quietest: The older spelling of{by: level, dir: asc}.similarity: The older spelling of{by: similarity, dir: desc}.quantized_beats_asc: The older spelling of{by: quantized_beats, dir: asc}.quantized_beats_desc: The older spelling of{by: quantized_beats, dir: desc}.
by in order_clause
- Form
- one of those listed below
What the samples are ranked by.
Accepts one of:
duration: The sample's length.pitch: The pitch Subsample detected in the sample. A sample with no pitch found comes last, whichever way round.onsets: How many hits Subsample detected in the sample.tempo: The tempo Subsample detected in the sample. A sample with no tempo found comes last, whichever way round.level: How loud the sample is. A velocity pick needs this as the first ranking.age: When Subsample took the sample in, sodescputs the newest first.quantized_beats: The sample's length in beats once quantised. A sample not yet quantised comes last, whichever way round.beat_match: How closely the sample's energy on each beat follows the beat pattern inpattern. It needs a quantise processor, and leaves out any sample not yet quantised.similarity: How closely the sample resembles thereferenceinwhere. It must be the first ranking.
dir in order_clause
- Form
- one of those listed below
Which end of the ranking comes first. Left out, the best match comes first for beat_match and similarity, and the lowest value for everything else.
Accepts one of:
asc: The lowest value comes first.desc: The highest value comes first.
pattern in order_clause
- Form
- list of
number - Example
[1, 0, 0.5, 0]
The beat pattern to match: one number for each beat, of which only the shape counts, not the level.
rank
- Form
integer- Limits
- at least 1
A place in the ranking, counted from 1 for the best match.
select
- Form
select_specor list ofselect_spec- Examples
{where: {reference: GM36_BassDrum1}},[{where: {name: my-favourite-kick}}, {where: {reference: GM36_BassDrum1}}]
How the assignment chooses a sound from the library. A list is a fallback chain: each is tried in turn until one finds a sound, and the first pick in the chain governs the whole chain.
where
- Form
- a block of keys
- Example
{pitched: true, duration: {gte: 1}}
Which samples qualify. Every condition written must hold. Left out, every sample qualifies.
name in where
- Form
stringor list ofstringor a block of keys- Limits
- at least 1 character
- Examples
"909-kick",["909-kick", "808-kick"],{matches: "kick*"}
Samples by file name, without the folder or the extension: one name exactly, any of a list of names, or a name matched by wildcards or a regular expression. Names are not unique, so a name may match several samples. An exact name matches letter case, and a wildcard or a regular expression does not.
matches in name
- Form
string- Limits
- at least 1 character
- Example
"kick*"
Wildcards the whole name must match, where * stands for any run of characters and ? for any one character.
regex in name
- Form
string- Limits
- at least 1 character
- Example
"^(kick|bd)_[0-9]+$"
A regular expression the whole name must match.
path in where
- Form
string- Limits
- at least 1 character
- Example
kicks/909-kick.wav
One audio file, by its path relative to the map. It may not be combined with name. A symbolic link and the file it points to each name the same sample.
directory in where
- Form
string- Limits
- at least 1 character
- Example
kits/acoustic
The samples inside this directory and the directories within it, relative to the map. Subsample loads them at startup. A symbolic link counts as inside both its own directory and that of the file it points to.
reference in where
- Form
string- Limits
- at least 1 character
- Examples
GM36_BassDrum1,references/my-kick.wav
Ranks the samples by how closely they resemble a reference: a built-in reference by name, such as GM36_BassDrum1, or an audio file by its path relative to the map. An assignment whose reference name is unknown is left out, with a warning.
pitched in where
- Form
boolean
true keeps only samples with a stable pitch, and false only samples without one.
loopable in where
- Form
boolean
true keeps only samples with a steady part worth looping, and false only samples without one.
duration in where
- Form
- a block of keys
- Example
{lte: 0.5}
The sample's length, kept within bounds. A length is measured from the audio, so it is written as a range: one value would keep only a sample measured at exactly that, which almost none is.
gte in duration
- Form
number
At least this value.
lte in duration
- Form
number
At most this value.
gt in duration
- Form
number
More than this value.
lt in duration
- Form
number
Less than this value.
duration_beats in where
- Form
- a block of keys
- Example
{gte: 4}
The sample's length in beats at the session tempo, where a beat is a quarter note, kept within bounds. A map that uses it needs a session tempo. It is worked out from a measured length, so it is written as a range rather than as one value.
gte in duration_beats
- Form
number
At least this value.
lte in duration_beats
- Form
number
At most this value.
gt in duration_beats
- Form
number
More than this value.
lt in duration_beats
- Form
number
Less than this value.
onsets in where
- Form
numberor a block of keys- Examples
1,{gte: 4}
How many hits Subsample detected in the sample. A number keeps exactly that count, and bounds keep the counts within them.
gte in onsets
- Form
number
At least this value.
lte in onsets
- Form
number
At most this value.
gt in onsets
- Form
number
More than this value.
lt in onsets
- Form
number
Less than this value.
eq in onsets
- Form
number
Exactly this value.
tempo in where
- Form
- a block of keys
- Example
{gte: 118, lte: 122}
The tempo Subsample detected in the sample, kept within bounds. A detected tempo is measured, so it is written as a range: one value would keep only a sample measured at exactly that, which almost none is. A sample with no tempo found is kept by no range.
gte in tempo
- Form
number
At least this value.
lte in tempo
- Form
number
At most this value.
gt in tempo
- Form
number
More than this value.
lt in tempo
- Form
number
Less than this value.
pitch in where
- Form
- a block of keys
- Examples
{gte: C2, lte: C3},{lte: 200}
The pitch Subsample detected in the sample, as a frequency or as a note name such as C3, kept within bounds. A detected pitch is measured, so it is written as a range rather than as one pitch. A sample with no pitch found is kept by no range.
gte in pitch
- Form
numberorstring- Limits
- at least 1 character
At least this value.
lte in pitch
- Form
numberorstring- Limits
- at least 1 character
At most this value.
gt in pitch
- Form
numberorstring- Limits
- at least 1 character
More than this value.
lt in pitch
- Form
numberorstring- Limits
- at least 1 character
Less than this value.
quantized_beats in where
- Form
numberor a block of keys- Examples
4,{gte: 4}
The sample's length in beats once the assignment's quantise processor has run. A sample not yet quantised does not qualify. A quantised length comes out of the grid whole, so a number keeps exactly that many beats, and bounds keep the lengths within them.
gte in quantized_beats
- Form
number
At least this value.
lte in quantized_beats
- Form
number
At most this value.
gt in quantized_beats
- Form
number
More than this value.
lt in quantized_beats
- Form
number
Less than this value.
eq in quantized_beats
- Form
number
Exactly this value.
min_duration in where
- Form
number
The older spelling of gte under duration.
max_duration in where
- Form
number
The older spelling of lte under duration.
min_onsets in where
- Form
number
The older spelling of gte under onsets.
max_onsets in where
- Form
number
The older spelling of lte under onsets.
min_tempo in where
- Form
number
The older spelling of gte under tempo.
max_tempo in where
- Form
number
The older spelling of lte under tempo.
min_pitch in where
- Form
numberorstring- Limits
- at least 1 character
The older spelling of gte under pitch.
max_pitch in where
- Form
numberorstring- Limits
- at least 1 character
The older spelling of lte under pitch.
min_quantized_beats in where
- Form
number
The older spelling of gte under quantized_beats.
max_quantized_beats in where
- Form
number
The older spelling of lte under quantized_beats.
order
- Form
order_clauseor list oforder_clause- Examples
{by: level, dir: desc},[{by: duration, dir: asc}, {by: level, dir: desc}]
How the qualifying samples are ranked: one ranking, or a list in which each ranking breaks the ties the one before it leaves. Left out, the newest sample comes first, or the closest match where where names a reference.
pick
- Form
- one of those listed below or
rankor list ofrankornullor a block of keys - Examples
2,[1, 4],{gte: 3},{mode: velocity, variation: 10},{mode: round_robin, lte: 4}
Which of the ranked samples plays: a rank, a range of ranks drawn from at random on every note, any for any match at random, round_robin for every match in turn, or velocity to choose by how hard the note is struck. Left out, a single note plays the best match, and each note of a list plays the next rank unless the assignment repitches.
Accepts one of:
any: A match at random on every note, each as likely as the next.velocity: The match that suits how hard the note is struck, from the quiet end of the ranking to the loud end. The ranking must be bylevel.round_robin: Every match in turn, from the best down, starting again after the last. Each note keeps its own place in the turn, and each note of a list starts one rank on from the note before, so they do not all open on the same sound.
gte in pick
- Form
rank
The first rank chosen from.
lte in pick
- Form
rank
The last rank chosen from.
gt in pick
- Form
rank
Chooses from the ranks after this one.
lt in pick
- Form
rank
Chooses from the ranks before this one.
eq in pick
- Form
rank
Always this rank.
mode in pick
- Form
- one of those listed below
How the pick chooses, which decides the keys that may sit beside it.
Accepts one of:
velocity: Chooses by how hard the note is struck, withvariation,curveandspacingbeside it.round_robin: Takes the matches in turn.gte,gt,lteandltbeside it narrow the turn to part of the ranking.
variation in pick
- Form
integer- Default
0- Limits
- at least 0, at most 127
- Example
10
How far the choice may stray from the velocity played, in velocity values across both directions: 10 strays up to 5 either way. The loudness still follows the velocity played.
curve in pick
- Form
- one of those listed below
- Default
linear
How the velocity played maps across the ranking.
Accepts one of:
linear: Velocity spreads evenly across the ranking.logarithmic: Soft notes spread across more of the ranking, for more distinct quiet tones.exponential: Hard notes spread across more of the ranking, for a finer choice among the loud samples.
spacing in pick
- Form
- one of those listed below
- Default
rank
How the ranked samples are laid out across the range of velocities.
Accepts one of:
rank: Each sample takes an equal share of the velocities, by its place in the ranking.loudness: Each sample sits at its own measured level, so the layout follows the real dynamics of the samples.