Audio component metadata manifest
Every component declares what it is as plain data on its class or module, so a host can build a panel, offer patches or map drum pads without constructing an audio graph. This page is what those declarations mean. The live calls are in the runtime API.
What a component declares
NAME = "tr808" # the stable lookup name
DISPLAY_NAME = "TR-808" # optional, for menus and panels
MACRO_LABELS = ("Level", "Accent") # up to 16 knobs
MACRO_MODES = {0: "UNIPOLAR", 1: "UNIPOLAR"}
PATCHES = {
0: ("Default", (102, 64)), # name, one value per macro
}
NAME is what you pass to create(). It is an instrument’s module name or an
effect’s class name, and it doesn’t change between releases.
MACRO_LABELS names the knobs in index order, the index set_macro() takes. A
component with no knobs declares ().
MACRO_MODES says how each knob rests and moves:
Mode |
Meaning |
|---|---|
|
rests at 0 and moves upward |
|
rests at 64 and moves either way |
|
0 is off and 127 is on; at run time 0 to 63 is off and 64 to 127 on |
PATCHES numbers its patches from 0 with no gaps, up to 128. Each is a name and
one integer from 0 to 127 per macro. Patch 0 is what a new component plays.
Patch values are whole numbers so that a patch saved anywhere plays the same on
a MIDI rig; live macro values can still be fractional.
CATEGORIES (a tuple of descriptive strings), VERSION and VENDOR are
optional. Knob spans in hertz, seconds or decibels are not metadata; they are
listed in Effect controls.
Drum kits
A percussion instrument also declares NOTE_MAP, its voices on General MIDI’s
percussion keys, so one MIDI track plays on any kit:
NOTE_MAP = (
(36, "Bass Drum"),
(38, "Snare"),
)
Having a NOTE_MAP is what makes an instrument a drum machine;
audioinstruments.DRUM_MACHINES lists those and MELODIC the rest.
Every kit also answers keys 36 to 51, the first bank of an 8- or 16-pad
controller. A key the kit has a voice for plays that voice; the rest play the
nearest voice it does have (an electric snare plays the snare, a pedal hat the
closed hat, a ride the cymbal). The kit’s PAD_MAP lists that choice as
(key, voice) pairs:
PAD_MAP = (
(36, 36),
(38, 38),
(39, 38), # Clap -> Snare
...
)
Two create() options change it. strict_pads=True plays only the notes in
NOTE_MAP, and the instrument’s strict_pads property reports it. pad_map=
takes (key, voice) pairs or a dict in place of PAD_MAP. You can’t pass both.
Any other note is ignored without a sound, an error or a warning, so a melodic
part sent to a drum track plays nothing. Some patches of a kit with several
machines, such as drumkits, leave a few pads silent too. Which kit answers
which hit is a table in the
audioinstruments documentation.
Reading metadata as a host
Use NAME as the identity. Everything else is there when you want it, and a
host must not assume the optional fields exist. A host can still offer a
generic panel for a component with no macros or patches.
The catalog
Every wheel carries audioeffects/catalog.json: each effect’s name, display
name, categories, macros (label and mode) and patches (index, name and values).
A DAW or MIDI host can read it to show those names without loading the audio
stack:
import json, os, audioeffects
with open(os.path.join(os.path.dirname(audioeffects.__file__), "catalog.json")) as f:
catalog = json.load(f)
for effect in catalog["effects"]:
print(effect["display_name"], [p["name"] for p in effect["patches"]])
The file is {"format": 1, "package": "audioeffects", "effects": [...]}, in
the order of audioeffects.ALL.