Source code for audioinstruments.panel

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""An instrument as a control panel sees it.

``PanelAdapter(inst)`` wraps an instrument from ``audioinstruments.create()``
in the adapter a control panel edits through: sixteen macro values on the
MIDI scale, the patch names, bypass, reload, and a callback for changes that
come from somewhere else, such as a MIDI controller. It imports no panel, so
anything with the same attributes can use it.

    import audioinstruments.panel as panel

    adapter = panel.create("poly106", 48000)
    audio_out.play(adapter.instrument.output)
    adapter.note_on(60)          # dropped while bypassed
    adapter.note_cc(0, 96)       # a controller moved macro 0: listeners hear it
    adapter.set_patch(1)         # what a pad press does

``request_reload()`` builds the instrument again and swaps it in, so play
``adapter.instrument.output`` again after a reload, or register
``on_reload(callback)`` to hear about it.
"""

MACRO_COUNT = 16
PATCH_COUNT = 128


[docs] def create(name, sample_rate, channel_count=2, transport=None, **options): """Create instrument ``name`` and wrap it. A reload builds it with the same options.""" import audioinstruments def rebuild(): return audioinstruments.create(name, sample_rate, channel_count, transport, **options) return PanelAdapter(rebuild(), rebuild=rebuild)
[docs] class PanelAdapter: """What a control panel needs from ``instrument``, and nothing else. ``rebuild`` is a callable that returns a new instrument, used by ``request_reload()``. Without one, a reload creates the same instrument by name at the same sample rate and channel count, with default options. ``name`` replaces the instrument's display name on the faceplate. """ def __init__(self, instrument, rebuild=None, name=None): self.instrument = instrument self._rebuild = rebuild self._listeners = [] self._reload_listeners = [] self.macro_values = [64] * MACRO_COUNT self.patch_index = 0 self.bypass = False self.engine_ready = True self.engine_error = 0 self.engine_message = "" patch = getattr(instrument, "patch", None) self.script_name = name or getattr(patch, "DISPLAY_NAME", None) or _name(instrument) self._read_declarations() index = getattr(instrument, "patch_index", None) if index is not None: self.patch_index = index self._refresh() # ---- what the instrument declares --------------------------------- def _read_declarations(self): instrument = self.instrument labels = [] for text in getattr(instrument, "macro_labels", ()): if len(labels) >= MACRO_COUNT: break labels.append(str(text)) self.macro_labels = labels self.macro_count = len(labels) declared = getattr(instrument, "patches", None) names = [] if declared: count = min(max(declared) + 1, PATCH_COUNT) for index in range(count): entry = declared.get(index) names.append(str(entry[0]) if entry else "Patch %03d" % (index + 1)) self.patches = names def _refresh(self): """Read every macro back from the instrument, in place.""" values = self.macro_values get = self.instrument.get_macro for index in range(self.macro_count): values[index] = _midi(get(index)) # ---- what the panel tells the instrument -------------------------- def set_macro(self, index, value): if not 0 <= index < self.macro_count: return value = _midi(value) self.macro_values[index] = value self.instrument.set_macro(index, value) def set_patch(self, index): self.patch_index = index self.instrument.program_change(index) self._refresh()
[docs] def set_bypass(self, enabled): """Bypassed, the instrument is silenced and ``note_on`` is dropped.""" self.bypass = bool(enabled) if self.bypass: self.instrument.all_notes_off()
[docs] def request_reload(self): """Build the instrument again and swap it in, keeping the patch and macros. Returns True when the new instrument is in place. On a failure the old one keeps playing, ``engine_error`` is 1 and ``engine_message`` says why. """ self.engine_ready = False old = self.instrument new = None try: rebuild = self._rebuild if rebuild is None: rebuild = _default_rebuild(old) new = rebuild() self._restore(new) except Exception as error: # noqa: BLE001 - any failure is reported, not raised self.engine_error = 1 self.engine_message = "%s: %s" % (type(error).__name__, error) self.engine_ready = True if new is not None: try: new.deinit() except Exception: # noqa: BLE001,S110 - it never played pass return False try: old.all_notes_off() except Exception: # noqa: BLE001,S110 - the old one may already be gone pass self.instrument = new self._read_declarations() self._refresh() self.engine_error = 0 self.engine_message = "" self.engine_ready = True for callback in self._reload_listeners: callback(new, old) return True
def _restore(self, new): """Give a rebuilt instrument the patch and macros the old one had.""" if self.patch_index in (getattr(new, "patches", None) or {}): new.program_change(self.patch_index) count = min(self.macro_count, len(getattr(new, "macro_labels", ()))) for index in range(count): value = self.macro_values[index] if _midi(new.get_macro(index)) != value: new.set_macro(index, value) # ---- what the panel listens to ------------------------------------
[docs] def on_external_change(self, callback): """Register ``callback(kind, index, value)``: ``("macro", i, v)`` or ``("patch", i, i)``.""" self._listeners.append(callback)
[docs] def on_reload(self, callback): """Register ``callback(new, old)``, called after a reload swaps instruments. Play ``new.output`` in place of ``old.output``. The old instrument is silenced but not deinitialised: deinit it once nothing pulls from it. """ self._reload_listeners.append(callback)
def _notify(self, kind, index, value): for callback in self._listeners: callback(kind, index, value) # ---- the MIDI side ------------------------------------------------
[docs] def note_cc(self, index, value): """A controller moved macro ``index`` to ``value`` (0-127): play it, tell the listeners.""" if not 0 <= index < self.macro_count: return value = _midi(value) self.instrument.set_macro(index, value) if self.macro_values[index] != value: self.macro_values[index] = value self._notify("macro", index, value)
[docs] def note_program(self, index): """A program change from outside: play it, tell the listeners the patch and every macro it moved.""" if not 0 <= index < PATCH_COUNT: return self.instrument.program_change(index) if self.patch_index != index: self.patch_index = index self._notify("patch", index, index) values = self.macro_values get = self.instrument.get_macro for macro in range(self.macro_count): value = _midi(get(macro)) if values[macro] != value: values[macro] = value self._notify("macro", macro, value)
[docs] def note_on(self, pitch, velocity=127, channel=0): """``instrument.note_on``, dropped while bypassed.""" if self.bypass: return self.instrument.note_on(pitch, velocity, 0.0, channel)
def note_off(self, pitch, channel=0): self.instrument.note_off(pitch, channel)
def _midi(value): value = int(value + 0.5) return 0 if value < 0 else (127 if value > 127 else value) def _name(instrument): patch = getattr(instrument, "patch", None) return getattr(patch, "NAME", None) or type(instrument).__name__ def _default_rebuild(old): name = getattr(getattr(old, "patch", None), "NAME", None) if not name: raise ValueError("no rebuild given, and the instrument has no NAME to build it by") import audioinstruments def rebuild(): return audioinstruments.create(name, old.sample_rate, old.channel_count) return rebuild