pyaudiohost 0.1.0__py3-none-any.whl

pyaudiohost/__init__.py

@@ -0,0 +1,55 @@
+"""Host audio effects and instruments with NumPy arrays and native editors.
+
+Use Plugin or load_plugin() for one effect, or PluginChain for ordered
+effects, streaming processing, and offline rendering. AudioHost and Host
+are aliases of PluginChain. Discovery functions inspect installed plugins
+in isolated workers; AAX is available only through probe_aax().
+Pass MidiNote events to Plugin.process() to play an instrument into an array.
+
+Audio uses channel-first arrays with 1 through 64 channels. Plugin supports
+independent native buses; chains route main buses. File I/O, audio devices,
+and playback are handled by the calling application. Close plugin
+handles and chains explicitly or use their context managers. Protect code
+that creates workers with an ``if __name__ == "__main__":`` guard because
+workers use multiprocessing spawn.
+
+Public classes and functions are re-exported here. Their docstrings describe
+arguments, return values, ownership, and operation-specific failures.
+"""
+
+from .discovery import (
+    PluginDescription,
+    ScanResult,
+    capabilities,
+    default_search_paths,
+    find_plugin_paths,
+    inspect_plugin,
+    probe_aax,
+    scan_plugins,
+)
+from .errors import AudioHostError, HostCrashedError, HostTimeoutError, UnsupportedFormatError
+from .host import AudioHost, Host, PluginChain
+from .midi import MidiNote
+from .plugin import Plugin, load_plugin
+
+__version__ = "0.1.0"
+__all__ = [
+    "AudioHost",
+    "AudioHostError",
+    "Host",
+    "HostCrashedError",
+    "HostTimeoutError",
+    "MidiNote",
+    "Plugin",
+    "PluginChain",
+    "PluginDescription",
+    "ScanResult",
+    "UnsupportedFormatError",
+    "capabilities",
+    "default_search_paths",
+    "find_plugin_paths",
+    "inspect_plugin",
+    "load_plugin",
+    "probe_aax",
+    "scan_plugins",
+]

pyaudiohost/_channels.py

@@ -0,0 +1,82 @@
+"""Channel and bus validation shared by public handles and native bridges."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import numpy as np
+
+from .errors import AudioHostError
+
+MAX_CHANNELS = 64
+MAX_BUSES = 32
+
+
+def channel_count(value):
+    if isinstance(value, bool) or not isinstance(value, int) or not 1 <= value <= MAX_CHANNELS:
+        raise ValueError("channels must be an integer between 1 and 64")
+    return value
+
+
+def audio_array(audio):
+    data = np.asarray(audio, dtype=np.float32)
+    if data.ndim == 1:
+        data = data[None, :]
+    if data.ndim != 2 or not 1 <= data.shape[0] <= MAX_CHANNELS:
+        raise ValueError("audio must have shape (channels, frames), with 1 through 64 channels")
+    if not np.isfinite(data).all():
+        raise ValueError("Audio samples must be finite")
+    return np.ascontiguousarray(data)
+
+
+def bus_config(config, *, output=False):
+    if config is None:
+        return None
+    if not isinstance(config, Mapping):
+        raise TypeError(
+            "Bus configuration must map integer bus indices to channel counts or layouts"
+        )
+    if output and not config:
+        raise ValueError("At least one output bus must be enabled")
+    result = {}
+    for index, value in config.items():
+        if isinstance(index, bool) or not isinstance(index, int) or not 0 <= index < MAX_BUSES:
+            raise ValueError("Bus indices must be integers between 0 and 31")
+        layout = dict(value) if isinstance(value, Mapping) else {"channels": value}
+        count = channel_count(layout.get("channels"))
+        arrangement = layout.get("arrangement")
+        if arrangement is not None and (
+            isinstance(arrangement, bool)
+            or not isinstance(arrangement, int)
+            or not 0 < arrangement < 1 << 64
+            or arrangement.bit_count() != count
+        ):
+            raise ValueError("A VST3 arrangement must be a 64-bit mask with one bit per channel")
+        result[index] = {"channels": count, "arrangement": arrangement}
+    if sum(item["channels"] for item in result.values()) > MAX_CHANNELS:
+        raise ValueError("At most 64 channels can be enabled per input/output direction")
+    return dict(sorted(result.items()))
+
+
+def adapt_channels(audio, channels):
+    """Preserve exact layouts; retain legacy mono/stereo conversion only."""
+    if audio.shape[0] == channels:
+        return np.ascontiguousarray(audio, dtype=np.float32)
+    if audio.shape[0] == 1 and channels == 2:
+        return np.repeat(audio, 2, axis=0)
+    if audio.shape[0] == 2 and channels == 1:
+        return audio.mean(axis=0, keepdims=True)
+    raise AudioHostError(
+        f"Cannot convert {audio.shape[0]} channels to {channels}; configure a matching layout or use process_buses()"
+    )
+
+
+def requested_buses(config, counts, channels):
+    result = bus_config(config)
+    if result is None:
+        result = {0: {"channels": channels, "arrangement": None}} if counts else {}
+    if any(index >= len(counts) for index in result):
+        raise AudioHostError(
+            f"Requested audio bus does not exist; plugin exposes {len(counts)} bus(es)"
+        )
+    return result

pyaudiohost/_render.py

@@ -0,0 +1,58 @@
+"""Shared offline block rendering for effects and instruments."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .errors import AudioHostError
+
+
+def check_cancel(cancel):
+    if cancel is not None and cancel.is_set():
+        raise AudioHostError("Render cancelled")
+
+
+def render_blocks(
+    *,
+    channels,
+    block_size,
+    output_frames,
+    latency,
+    process_block,
+    progress=None,
+    cancel=None,
+    trim_tail_at=None,
+    minimum_frames=0,
+):
+    """Flush latency and tails, reporting processed frames in the caller's thread.
+
+    Callers emit initial progress before snapshot/setup. Extra minimum_frames
+    allow a final instrument note-off even when the output ends at that sample.
+    """
+    check_cancel(cancel)
+    output = np.empty((channels, output_frames), np.float32)
+    total = max(output_frames + latency, minimum_frames)
+    skip, written = latency, 0
+    last_audible = trim_tail_at
+    for position in range(0, total, block_size):
+        check_cancel(cancel)
+        count = min(block_size, total - position)
+        data = process_block(position, count)
+        if data.shape != (channels, count):
+            raise AudioHostError("A plugin returned an invalid audio block shape")
+        if not np.isfinite(data).all():
+            raise AudioHostError("A plugin produced non-finite audio samples")
+        ignored = min(skip, count)
+        skip -= ignored
+        data = data[:, ignored:][:, : output_frames - written]
+        output[:, written : written + data.shape[1]] = data
+        if trim_tail_at is not None:
+            audible = np.flatnonzero(np.any(np.abs(data) > 1e-6, axis=0))
+            if audible.size:
+                last_audible = max(last_audible, written + int(audible[-1]) + 1)
+        written += data.shape[1]
+        if progress:
+            progress(min(1.0, (position + count) / total))
+    if progress and total == 0:
+        progress(1.0)
+    return output[:, :last_audible].copy() if trim_tail_at is not None else output

pyaudiohost/_worker.py

@@ -0,0 +1,305 @@
+"""Isolated plugins: lifecycle/UI on the main thread, audio on a dedicated thread."""
+
+from __future__ import annotations
+
+import multiprocessing as mp
+import queue
+import threading
+import time
+import weakref
+
+from .errors import AudioHostError, HostCrashedError, HostTimeoutError
+
+
+def _platform_init(audio=False):
+    import sys
+
+    if sys.platform == "win32":
+        import pythoncom
+
+        try:
+            pythoncom.CoInitializeEx(
+                pythoncom.COINIT_MULTITHREADED if audio else pythoncom.COINIT_APARTMENTTHREADED
+            )
+        except pythoncom.com_error:
+            return None
+        return pythoncom
+    if sys.platform == "darwin" and not audio:
+        from .backends._window_cocoa import application
+
+        application()
+    return None
+
+
+def _backend(format, path, plugin_id):
+    if format == "vst2":
+        from .backends.vst2 import VST2Backend
+
+        return VST2Backend(path, plugin_id)
+    if format == "vst3":
+        from .backends.vst3 import VST3Backend
+
+        return VST3Backend(path, plugin_id)
+    if format == "au":
+        from .backends.au import AUBackend
+
+        return AUBackend(path, plugin_id)
+    raise AudioHostError(f"Unsupported processing format: {format}")
+
+
+def _scan(format, path):
+    if format == "aax":
+        from .backends.aax import probe
+
+        return probe(path)
+    if format == "vst3":
+        from .backends.vst3 import Module
+
+        module = Module(path)
+        try:
+            return module.scan()
+        finally:
+            module.close()
+    if format == "au":
+        from .backends.au import scan
+
+        return scan(path)
+    instance = _backend(format, path, None)
+    try:
+        return instance.scan()
+    finally:
+        instance.close()
+
+
+def _entry(connection, format, path, plugin_id, inspection):
+    import sys
+
+    _run_worker(connection, format, path, plugin_id, inspection)
+    if sys.platform == "win32":
+        import win32api
+
+        # SDK teardown and pipe closure have completed. Avoid a second round of
+        # DLL/global destructors after Python services have started shutting down.
+        # Ozone's GUI runtime otherwise aborts in ZeroMQ/Winsock during DLL detach.
+        win32api.TerminateProcess(win32api.GetCurrentProcess(), 0)
+
+
+def _run_worker(connection, format, path, plugin_id, inspection):
+    import sys
+
+    instance = None
+    ole = None
+    audio_thread = None
+    stopped = threading.Event()
+    processing = threading.RLock()
+    jobs = queue.Queue()
+    sending = threading.Lock()
+    timing = {"latency": 0, "tail": 0}
+
+    def send(message):
+        with sending:
+            connection.send(message)
+
+    def invoke(operation, args, kwargs):
+        try:
+            with processing:
+                if operation == "editor_status":
+                    window = instance.window
+                    result = bool(window and window.open)
+                elif operation == "timing":
+                    result = dict(timing)
+                else:
+                    result = getattr(instance, operation)(*args, **kwargs)
+                    if operation in (
+                        "prepare",
+                        "reset",
+                        "load_state",
+                        "save_state",
+                        "set_parameter",
+                    ):
+                        timing.update(instance.timing())
+                    if operation == "prepare" and hasattr(instance, "audio_buses"):
+                        result = {**result, "buses": instance.audio_buses()}
+                    if operation in ("process", "process_buses"):
+                        result = {"audio": result, "timing": dict(timing)}
+                return {"ok": True, "result": result}
+        except Exception as error:  # noqa: BLE001 -- serialize native errors across IPC.
+            return {"ok": False, "error": f"{type(error).__name__}: {error}"}
+
+    def serve_audio():
+        # This thread keeps receiving/processing audio even while a window manager
+        # runs a modal move/resize loop inside the main thread's GUI pump.
+        audio_ole = None
+        try:
+            audio_ole = _platform_init(audio=True)
+            while not stopped.is_set():
+                if not connection.poll(0.01):
+                    continue
+                operation, args, kwargs = connection.recv()
+                if operation == "close":
+                    break
+                # Reading editor state must not wait for a native modal dialog.
+                if operation in ("process", "process_buses", "timing", "editor_status"):
+                    response = invoke(operation, args, kwargs)
+                else:
+                    done, response = threading.Event(), []
+                    jobs.put((operation, args, kwargs, done, response))
+                    while not done.wait(0.05):
+                        if stopped.is_set():
+                            return
+                    response = response[0]
+                send(response)
+        except (EOFError, BrokenPipeError, OSError):
+            pass
+        finally:
+            if audio_ole:
+                audio_ole.CoUninitialize()
+            stopped.set()
+
+    try:
+        ole = _platform_init()
+        if inspection:
+            send({"ok": True, "result": _scan(format, path)})
+            return
+        instance = _backend(format, path, plugin_id)
+        timing.update(instance.timing())
+        next_timing = time.monotonic() + 0.05
+        send({"ok": True, "result": instance.description})
+        audio_thread = threading.Thread(target=serve_audio, name="plugin-audio", daemon=True)
+        audio_thread.start()
+        while not stopped.is_set():
+            try:
+                operation, args, kwargs, done, response = jobs.get(timeout=0.002)
+            except queue.Empty:
+                pass
+            else:
+                response.append(invoke(operation, args, kwargs))
+                done.set()
+            # Lifecycle changes share a lock with processing. Never hold that lock
+            # across idle(): GUI dragging can keep idle() inside a modal loop.
+            service = getattr(instance, "service_main", None)
+            with processing:
+                if service:
+                    service()
+                if time.monotonic() >= next_timing:
+                    timing.update(instance.timing())
+                    next_timing = time.monotonic() + 0.05
+            instance.idle()
+            if sys.platform == "darwin" and instance.window is None:
+                from .backends._window_cocoa import pump_events
+
+                pump_events()
+    except (EOFError, BrokenPipeError):
+        pass
+    except BaseException as error:  # noqa: BLE001 -- report worker startup/UI failures.
+        try:
+            send({"ok": False, "error": f"{type(error).__name__}: {error}"})
+        except (EOFError, BrokenPipeError, OSError):
+            pass
+    finally:
+        stopped.set()
+        if audio_thread is not None:
+            audio_thread.join(1)
+        try:
+            with processing:
+                if instance is not None:
+                    instance.close()
+        finally:
+            if ole:
+                ole.CoUninitialize()
+            connection.close()
+
+
+def _terminate(process, connection):
+    if process.is_alive():
+        process.terminate()
+        process.join(2)
+        if process.is_alive():
+            process.kill()
+            process.join(2)
+    else:
+        process.join()
+    connection.close()
+
+
+class Worker:
+    def __init__(self, format, path, plugin_id=None, *, timeout=30.0, inspection=False):
+        self.timeout = timeout
+        self._lock = threading.RLock()
+        self._closed = False
+        context = mp.get_context("spawn")
+        self._connection, child = context.Pipe()
+        self._process = context.Process(
+            target=_entry,
+            args=(child, format, str(path), plugin_id, inspection),
+            name="pyaudiohost-" + format,
+            daemon=True,
+        )
+        try:
+            self._process.start()
+        except RuntimeError as error:
+            self._connection.close()
+            child.close()
+            raise AudioHostError(
+                "Create plugin hosts under `if __name__ == '__main__':` when using spawn."
+            ) from error
+        child.close()
+        self._finalizer = weakref.finalize(self, _terminate, self._process, self._connection)
+        try:
+            self.initial = self._receive(timeout)
+        except BaseException:
+            self.close()
+            raise
+        if inspection:
+            self._process.join(3)
+            self.close()
+
+    @property
+    def closed(self):
+        return self._closed or not self._process.is_alive()
+
+    def _receive(self, timeout):
+        deadline = time.monotonic() + timeout
+        while True:
+            if self._connection.poll(min(0.05, max(0, deadline - time.monotonic()))):
+                try:
+                    message = self._connection.recv()
+                except (EOFError, OSError) as error:
+                    raise HostCrashedError(
+                        f"Plugin worker exited (code {self._process.exitcode})"
+                    ) from error
+                if not message["ok"]:
+                    raise AudioHostError(message.get("error", "Plugin operation failed"))
+                return message.get("result")
+            if not self._process.is_alive():
+                raise HostCrashedError(f"Plugin worker exited (code {self._process.exitcode})")
+            if time.monotonic() >= deadline:
+                self._closed = True
+                self._finalizer()
+                raise HostTimeoutError(
+                    f"Plugin operation timed out after {timeout:g}s; worker closed"
+                )
+
+    def request(self, operation, *args, timeout=None, **kwargs):
+        with self._lock:
+            if self.closed:
+                raise HostCrashedError("Plugin worker is closed")
+            try:
+                self._connection.send((operation, args, kwargs))
+                return self._receive(self.timeout if timeout is None else timeout)
+            except HostTimeoutError:
+                raise
+            except (OSError, EOFError) as error:
+                raise HostCrashedError("Cannot communicate with plugin worker") from error
+
+    def close(self):
+        with self._lock:
+            if not self._closed:
+                if self._process.is_alive():
+                    try:
+                        self._connection.send(("close", (), {}))
+                        self._process.join(3)
+                    except (OSError, EOFError):
+                        pass
+                self._closed = True
+            self._finalizer()

pyaudiohost/backends/__init__.py

@@ -0,0 +1 @@
+"""ctypes plugin ABIs; loaded only inside isolated worker processes."""