Metadata-Version: 2.4
Name: pyaudiohost
Version: 0.1.0
Summary: Python audio effect and instrument hosting with VST2/VST3/AU plugin editors
Author-email: Sucial <1584846096@qq.com>
License-Expression: Apache-2.0
Project-URL: Source Code, https://github.com/SUC-DriverOld/pyaudiohost
Project-URL: Bug Tracker, https://github.com/SUC-DriverOld/pyaudiohost/issues
Project-URL: Documentation, https://github.com/SUC-DriverOld/pyaudiohost/blob/main/docs/README.md
Keywords: audio,audio-plugins,plugin-host,vst,vst2,vst3,audio-unit
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Sound/Audio :: MIDI
Classifier: Topic :: Multimedia :: Sound/Audio :: Sound Synthesis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Requires-Dist: numpy>=1.24
Requires-Dist: pywin32>=308; sys_platform == "win32"
Requires-Dist: python-xlib>=0.33; sys_platform == "linux"
Requires-Dist: pyobjc-framework-Cocoa>=10; sys_platform == "darwin"
Requires-Dist: rubicon-objc>=0.5; sys_platform == "darwin"
Dynamic: license-file

# pyaudiohost

A pure Python audio effect and instrument host with NumPy input/output and native plugin
editors. Plugin interfaces use `ctypes`; each plugin runs in an isolated Python
process, with audio processing independent of the editor event loop.

- VST2 and VST3 effects on Windows, macOS, and Linux.
- Audio Unit v2/v3 effects on macOS.
- VST2/VST3 and macOS AU instruments with MIDI note-on/off input.
- Multichannel audio and independent plugin buses, with layout negotiation.
- Native editors for live adjustment, normalized parameters, and state snapshots.
- Streaming processing and offline rendering with latency compensation,
  progress callbacks, and cancellation.
- AAX module probing is reserved; AAX audio processing and editors are unavailable.

The library handles plugins and arrays. Your application handles audio files,
playback devices, and saving. Runtime dependencies are NumPy plus native platform
bridges: pywin32 on Windows, python-xlib on Linux, and PyObjC/Rubicon ObjC on macOS.
The library installs without compiling a project extension. Playback and file I/O
dependencies belong to the application.

## Install from source

Python 3.10 or newer is required. In this checkout:

```sh
uv sync --dev
```

To use the checkout from another uv project:

```sh
uv add /path/to/pyaudiohost
```

See [installation](docs/installation.md) for platform requirements and packaging.

## Process an array

```python
import numpy as np
from pyaudiohost import PluginChain

if __name__ == "__main__":
    # Replace this path with a compatible effect installed on your machine.
    plugin_path = "/path/to/effect.vst3"
    audio = np.zeros((2, 48000), dtype=np.float32)  # channels, frames
    audio[:, 0] = 0.1

    with PluginChain([plugin_path], sample_rate=48000) as chain:
        processed = chain.render(
            audio,
            progress=lambda value: print(f"Rendering: {value:.0%}"),
        )
        assert processed.shape == audio.shape
```

For a plugin bundle, pass the outer bundle directory (such as `Effect.vst3`),
not a binary inside its `Contents/` directory. Single-file plugins accept the file
path directly.

Use the `__main__` guard because plugin workers use multiprocessing spawn.
[Array processing](docs/array-processing.md) covers continuous audio blocks;
[rendering](docs/rendering.md) covers progress, tails, cancellation, and background
GUI integration.

## Try the standalone player

```sh
uv run --script examples/player.py
```

Open an audio file, add effects, open their native editors, adjust settings during
playback, and render to WAV. The example declares its own playback/file dependencies
and is not included in the installed library. See the [player guide](docs/examples.md).

For a single instrument with an on-screen piano keyboard:

```sh
uv run --script examples/instrument.py
```

Load an instrument, open its native editor to select a sound, and hold or drag the
piano keys to play through the default output device. See [instruments](docs/instruments.md)
for the array/MIDI API and tested scope.

## Documentation

Start with the [documentation index](docs/README.md) for the API reference, plugin
discovery, editors, parameters/state, platform support, and troubleshooting.
See [multichannel audio](docs/multichannel.md) for surround layouts, sidechains,
and instruments with multiple output buses.

See [platform support](docs/platform-support.md) for native plugin verification
and the remaining platform/format coverage.

License: Apache-2.0. See [LICENSE](LICENSE) and
[third-party notices](THIRD_PARTY_NOTICES.md).
