# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Synthesizers, organs and electric pianos, each one a patch on a virtual rack.
Each instrument is a module, ``audioinstruments.<name>``, exposing::
MACRO_LABELS tuple of names, one per macro parameter
MACRO_MODES {index: "UNIPOLAR" | "BIPOLAR" | "TOGGLE"}
PATCHES {index: (name, (macro values, 0-127))}; patch 0 is the sound
a freshly created instrument makes
NOTE_MAP drum machines only: ((midi_note, label), ...)
PAD_MAP drum machines only: ((key, voice), ...) for pad keys 36-51
create(sample_rate, channel_count=2, transport=None, **options)
import audioinstruments
inst = audioinstruments.create("poly106", 48000)
inst.note_on(60)
inst.set_macro(0, 96) # vcf_freq, MIDI scale
audio_out.play(inst.output)
On MicroPython call ``inst.fill()`` every 10 to 20 ms while it plays: that is
when notes and knobs reach the sound. Where the patch compiles to an
``audiograph`` graph, ``inst.output`` is the graph and renders as it is
pulled; otherwise it is a ring that ``fill()`` keeps topped up. The options
are those of ``audioinstruments._rack.adapter.Instrument`` (``voices``, ``block_size``,
``output``, ``engine`` and the rest), or of ``audioinstruments._rack.soundfont.create`` for the
SAMPLERS.
"""
import sys
from ._names import ALL, DRUM_MACHINES, MELODIC, SAMPLERS
__all__ = ("ALL", "DRUM_MACHINES", "MELODIC", "SAMPLERS", "create", "load")
[docs]
def load(name):
"""Import and return the instrument module ``name``."""
full = __name__ + "." + name
__import__(full)
return sys.modules[full]
[docs]
def create(name, sample_rate, channel_count=2, transport=None, **options):
"""Load instrument ``name`` and return a live instance of it."""
return load(name).create(
sample_rate, channel_count=channel_count, transport=transport, **options
)
def _build(name, sample_rate, channel_count, transport, options):
if name in SAMPLERS:
# A SoundFont plays on audiosampler alone, so it skips the adapter and
# the rack's array code: a board without ulab can still play a bank.
options.pop("engine", None)
module = __import__("audioinstruments._rack." + name, None, None, ("create",))
return module.create(
sample_rate, channel_count=channel_count, transport=transport, **options
)
import audioinstruments._rack.adapter as adapter
options["voice"] = name
if name not in adapter.SAMPLERS and "output" not in options and adapter._pull_is_native_only():
# The graph renders as it is pulled, so a host that pulls and calls
# fill() now and then keeps time. A patch that does not compile, or
# an audiograph older than the change queue (before audiodsp 0.6.11),
# takes the ring.
try:
return adapter.create(
sample_rate,
channel_count=channel_count,
transport=transport,
output="graph",
**options,
)
except (ImportError, ValueError, RuntimeError):
pass
return adapter.create(sample_rate, channel_count=channel_count, transport=transport, **options)