Subsystem Search

Subsample MIDI map: the map

The file that tells Subsample which sounds each MIDI note plays, how they are processed, and how they play. It holds assignments, and may add templates, programs, other maps to play at the same time, and definitions files that name notes, controllers, MIDI channels and programs. Numbers are read as written, so a leading zero is just a leading zero: 036 is 36, and note numbers can be lined up in a column without changing which sound plays. A key written twice where it belongs once, such as a second assignments: or a second notes: in one assignment, is refused, naming both lines.

The map's own keys

Form
a block of keys

The file that tells Subsample which sounds each MIDI note plays, how they are processed, and how they play. It holds assignments, and may add templates, programs, other maps to play at the same time, and definitions files that name notes, controllers, MIDI channels and programs. Numbers are read as written, so a leading zero is just a leading zero: 036 is 36, and note numbers can be lined up in a column without changing which sound plays. A key written twice where it belongs once, such as a second assignments: or a second notes: in one assignment, is refused, naming both lines.

definitions in the-map

Form
names to string
Example
{my: project.yaml}

Definitions files to take names from, each under a prefix the map chooses: {my: project.yaml} lets the map write my.kick for a note the file names. A path is relative to the map. The drum prefix is reserved for the built-in General MIDI drum names.

channel in the-map

Form
channel
Example
10

The MIDI channel an assignment answers on when it names none of its own, so a map can be played on whatever MIDI channel a project gives it without editing it. A map with no channel needs one on every assignment.

programs in the-map

Form
list of program
Example
[{name: "Acoustic kit", directory: kits/acoustic}, {name: "Electronic kit", directory: kits/electronic}]

Instrument sets that a MIDI Program Change switches between, all loaded at startup so that a switch is instant. Without it, Subsample plays the library its configuration names. Each program is selected by its Program Change number alone, so a map holds up to 128, and Bank Select messages are not read. A switch changes the kit on every MIDI channel at once: a directory: program's samples serve all of this map's assignments, and a map: preset's assignments replace all of them, so a MIDI channel the preset does not play falls silent until the next switch. Each keeps its own samples in memory. A sample this map's assignments name by path or directory is loaded for every directory: program, and held in memory once. One whose samples do not all fit within library.max_memory_mb leaves out those it loaded first, which it then cannot play, and startup names it. A switch to a program whose assignments fail to apply keeps the previous program playing, and the log says why. A change to this block, to program_channel or default_program, or to a preset's own file takes a restart.

program_channel in the-map

Form
integer or defined_name or written_number
Default
10
Limits
at least 0, at most 16
Example
0

The MIDI channel that Program Change messages are read on, where 0 reads every MIDI channel. A switch still changes the kit on every MIDI channel, not only this one.

default_program in the-map

Form
program_number
Examples
1, my.brushes

The program active at startup, which must be one the list declares. Left out, the first program in the list.

templates in the-map

Form
names to template
Example
{kit: {channel: 10, process: [{compress: {threshold: -20, ratio: 8}}]}}

Named sets of assignment fields that assignments may start from, so that a kit writes its shared MIDI channel, processing or selection once.

assignments in the-map

Form
list of assignment
Example
[{name: Kick, channel: 10, notes: drum.kick_1, select: {where: {reference: GM36_BassDrum1}}}]

Each instrument the map plays: the notes it answers to, the sound it chooses for them, and how that sound plays. A map whose programs are all map: presets, or that plays other maps through maps, may leave it out.

maps in the-map

Form
list of included_map
Example
[drums.yaml, {map: bass.yaml, channel: 2}]

Other maps to play at the same time, each on its own MIDI channel, which makes this map an ensemble. A map included here may not include maps or declare programs of its own; this file may declare programs:. Two maps may not claim the same note on the same MIDI channel. With player.watch_midi_map on, an edit to this file or to a map it includes reloads them together, and a map added here is watched from the reload that reads it.

assignment

Form
a block of keys

One instrument: the notes it answers to, the sound it chooses for them, how that sound is processed, and how it plays.

name in assignment

Form
string
Default
"<unnamed>"
Example
Kick

A name for the assignment, which log lines and error messages use.

template in assignment

Form
string or list of string
Examples
kit, [kit, room]

The template, or the templates in order, that the assignment starts from. A later template overrides an earlier one, and the assignment's own fields override them all. A template the map does not define is refused, with the list of those it does.

channel in assignment

Form
channel
Examples
10, my.kit

The MIDI channel the assignment answers on. Left out, the map's channel, or the MIDI channel an ensemble plays the map on.

notes in assignment

Form
notes
Required
yes

velocity in assignment

Form
velocity

select in assignment

Form
select
Required
yes

process in assignment

Form
list of process_step
Example
[reverse, {filter_low: {freq: 800, resonance: 6}}, {saturate: {drive: 4}}]

The processors the sound passes through, in order, rendered ahead of time. A processor is named alone for its defaults, or given its parameters. At most one of them may align the sound to the beat.

mode in assignment

Form
one of those listed below
Default
one_shot

How the sound answers the key: played to its end, played while the key is held, or looped while the key is held. Writing loop: sets the mode to loop.

Accepts one of:

loop in assignment

Form
loop

release in assignment

Form
release

extract in assignment

Form
extract

gain in assignment

Form
number
Default
0
Example
-3

Gain applied to the sound as it plays.

pan in assignment

Form
pan

output in assignment

Form
output

stack in assignment

Form
boolean
Default
false

Lets the assignment sound together with another on the same note and velocity. Every assignment that overlaps must set it, or the map is refused.

silenced_by in assignment

Form
silenced_by

align in assignment

Form
one of those listed below
Default
hit

What lands on the time an OSC note in a bundle names: the sound's hit, or its start. A MIDI note, or an OSC note sent on its own, starts its sound as it arrives, whatever this says.

Accepts one of:

channel

Form
integer or defined_name or written_number
Limits
at least 1, at most 16

A MIDI channel, counted from 1, or a name a definitions file gives one.

program_number

Form
integer or defined_name or written_number
Limits
at least 0, at most 127

A MIDI program number, or a name a definitions file gives one.

template

Form
a block of keys

A named set of assignment fields. An assignment that names the template starts from its fields, and its own fields win: a field it sets replaces the template's whole, with nothing merged inside it. A template may not name a template of its own.

name in template

Form
string
Default
"<unnamed>"
Example
Kick

A name for the assignment, which log lines and error messages use.

channel in template

Form
channel
Examples
10, my.kit

The MIDI channel the assignment answers on. Left out, the map's channel, or the MIDI channel an ensemble plays the map on.

notes in template

Form
notes

velocity in template

Form
velocity

select in template

Form
select

process in template

Form
list of process_step
Example
[reverse, {filter_low: {freq: 800, resonance: 6}}, {saturate: {drive: 4}}]

The processors the sound passes through, in order, rendered ahead of time. A processor is named alone for its defaults, or given its parameters. At most one of them may align the sound to the beat.

mode in template

Form
one of those listed below
Default
one_shot

How the sound answers the key: played to its end, played while the key is held, or looped while the key is held. Writing loop: sets the mode to loop.

Accepts one of:

loop in template

Form
loop

release in template

Form
release

extract in template

Form
extract

gain in template

Form
number
Default
0
Example
-3

Gain applied to the sound as it plays.

pan in template

Form
pan

output in template

Form
output

stack in template

Form
boolean
Default
false

Lets the assignment sound together with another on the same note and velocity. Every assignment that overlaps must set it, or the map is refused.

silenced_by in template

Form
silenced_by

align in template

Form
one of those listed below
Default
hit

What lands on the time an OSC note in a bundle names: the sound's hit, or its start. A MIDI note, or an OSC note sent on its own, starts its sound as it arrives, whatever this says.

Accepts one of:

program

Form
any value

One program: the instrument set a Program Change message switches to. It names either a directory of samples for this map's assignments, or a whole map of its own.

name in program

Form
string
Required
yes
Limits
at least 1 character
Example
"Acoustic kit"

A name for the program, which log lines use.

program in program

Form
program_number
Example
1

The Program Change number that selects the program. Left out, its place in the list, counted from 0.

directory in program

Form
string
Limits
at least 1 character
Example
kits/acoustic

A directory of samples for the map's own assignments to choose from while the program is active, relative to where Subsample runs. A select by name plays nothing in a program whose directory lacks that sound, while a select by rules takes the closest there.

map in program

Form
string
Limits
at least 1 character
Example
kits/808-kit.yaml

A whole map, with its own assignments and samples, relative to this map. Its own paths resolve from its own folder, so a kit's folder works as one unit, and a switch to the program changes the assignments and the samples together. It may not declare programs or maps of its own.

included_map

Form
string or a block of keys
Limits
at least 1 character

One map an ensemble plays: its path alone, which keeps the MIDI channel the map declares, or its path with a MIDI channel to play it on.

map in included_map

Form
string
Limits
at least 1 character
Example
drums.yaml

The map to play, by its path relative to this map.

channel in included_map

Form
channel
Example
2

The MIDI channel to play the map on, in place of the one it declares. An assignment that names its own MIDI channel keeps it, with a warning.

notes

Form
note or list of note or a block of keys or one of those listed below
Examples
36, C2..C4, [drum.kick_1, drum.kick_2], {mode: zone-tuned, range: [C2, C4]}

The notes the assignment answers to: one note, a range written as C2..C4 or 36..60, a list of notes, or zone-tuned, which shares a range of the keyboard out among pitched samples. Without a pick, each note of a list plays the next rank, starting with the best match, unless the assignment repitches.

Accepts one of:

note

Form
integer or string
Limits
at least 0, at most 127, at least 1 character

One note: its MIDI number, its name, where C4 is note 60, or a name from a definitions file or from the built-in General MIDI drum names, such as drum.kick_1.

defined_name

Form
string
Limits
matching ^[A-Za-z][A-Za-z0-9_]*\.[A-Za-z][A-Za-z0-9_]*$

A name from a mounted definitions file, written as its prefix and its name, such as my.kick.

written_number

Form
string
Limits
matching ^\s*[+-]?[0-9]+\s*$

A whole number written as text, which the map reads as that number.