hyperframes-vst-host 0.1.0__py3-none-any.whl

hyperframes_vst/__main__.py

@@ -0,0 +1,78 @@
+import argparse
+import sys
+
+from .chain import PluginMissingError
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="hyperframes-vst")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_bounce = sub.add_parser("bounce", help="Offline render a WAV through a chain")
+    p_bounce.add_argument("--input", required=True)
+    p_bounce.add_argument("--chain", required=True)
+    p_bounce.add_argument("--output", required=True)
+
+    p_probe = sub.add_parser("probe", help="Probe one bundle (may crash; run in subprocess)")
+    p_probe.add_argument("path")
+
+    p_scan = sub.add_parser("scan", help="Scan plugin dirs, print registry JSON")
+    p_scan.add_argument("--dirs", nargs="*", default=None)
+    p_scan.add_argument("--json", action="store_true")
+
+    p_carve = sub.add_parser("carve", help="Analyze a voiceover WAV, print carve bands JSON")
+    p_carve.add_argument("--voice", required=True)
+    p_carve.add_argument("--max-cut-db", type=float, default=4.0)
+    p_carve.add_argument("--json", action="store_true")
+
+    p_serve = sub.add_parser("serve", help="Run the WebSocket sidecar")
+    p_serve.add_argument("--port", type=int, default=0)
+
+    args = parser.parse_args()
+
+    if args.command == "bounce":
+        from .bounce import bounce_file
+
+        try:
+            bounce_file(args.input, args.chain, args.output)
+        except PluginMissingError as exc:
+            print(f"PLUGIN_MISSING {exc.plugin_name}", file=sys.stderr)
+            return 3
+        return 0
+
+    if args.command == "probe":
+        import json as _json
+
+        from .scan import probe_bundle
+
+        print(_json.dumps(probe_bundle(args.path)))
+        return 0
+
+    if args.command == "scan":
+        import json as _json
+
+        from .scan import default_plugin_dirs, scan_paths
+
+        print(_json.dumps(scan_paths(args.dirs or default_plugin_dirs())))
+        return 0
+
+    if args.command == "carve":
+        import json as _json
+
+        from .carve import carve_file
+
+        bands = carve_file(args.voice, max_cut_db=args.max_cut_db)
+        print(_json.dumps({"bands": bands}))
+        return 0
+
+    if args.command == "serve":
+        from .server import serve
+
+        serve(args.port)
+        return 0
+
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hyperframes_vst/bounce.py

@@ -0,0 +1,19 @@
+"""Offline WAV -> WAV render through a chain. Block-by-block, no realtime clock."""
+from __future__ import annotations
+
+from pedalboard import Pedalboard
+from pedalboard.io import AudioFile
+
+from .chain import build_chain, enabled_plugins, load_chain_spec
+
+
+def bounce_file(input_wav: str, chain_json_path: str, output_wav: str, block_size: int = 8192) -> None:
+    with open(chain_json_path, "r", encoding="utf-8") as f:
+        spec = load_chain_spec(f.read())
+    # Disabled plugins are bypassed at render exactly as in preview.
+    board = Pedalboard(enabled_plugins(spec, build_chain(spec)))
+    with AudioFile(input_wav) as src:
+        with AudioFile(output_wav, "w", src.samplerate, src.num_channels) as dst:
+            while src.tell() < src.frames:
+                chunk = src.read(min(block_size, src.frames - src.tell()))
+                dst.write(board(chunk, src.samplerate, reset=False))

hyperframes_vst/carve.py

@@ -0,0 +1,90 @@
+"""Spectral carve: find a voiceover's dominant presence bands so a music
+track can be EQ-dipped there (the "vocal pocket"). Pure numpy analysis; the
+returned bands are plain pedalboard PeakFilter configs."""
+from __future__ import annotations
+
+import numpy as np
+
+SPEECH_LO_HZ = 150.0
+SPEECH_HI_HZ = 6000.0
+CARVE_Q = 1.5
+MIN_BANDS = 2
+MAX_BANDS = 4
+# Roughly third-octave centers spanning the speech-relevant range.
+CANDIDATE_CENTERS_HZ = [160.0, 250.0, 400.0, 630.0, 1000.0, 1600.0, 2500.0, 4000.0, 6000.0]
+
+_FRAME = 4096
+_HOP = 2048
+
+
+def _to_mono(samples: np.ndarray) -> np.ndarray:
+    arr = np.asarray(samples, dtype=np.float64)
+    if arr.ndim == 2:
+        # pedalboard yields (channels, frames); average channels to mono.
+        arr = arr.mean(axis=0)
+    return arr.reshape(-1)
+
+
+def _power_spectrum(mono: np.ndarray, sample_rate: float) -> tuple[np.ndarray, np.ndarray]:
+    """Welch-style averaged power spectrum. Returns (freqs, power)."""
+    n = mono.shape[0]
+    if n < _FRAME:
+        mono = np.pad(mono, (0, _FRAME - n))
+        n = _FRAME
+    window = np.hanning(_FRAME)
+    acc = np.zeros(_FRAME // 2 + 1)
+    frames = 0
+    for start in range(0, n - _FRAME + 1, _HOP):
+        seg = mono[start : start + _FRAME] * window
+        spec = np.abs(np.fft.rfft(seg)) ** 2
+        acc += spec
+        frames += 1
+    if frames == 0:
+        acc = np.abs(np.fft.rfft(mono[:_FRAME] * window)) ** 2
+        frames = 1
+    freqs = np.fft.rfftfreq(_FRAME, d=1.0 / sample_rate)
+    return freqs, acc / frames
+
+
+def _band_power(freqs: np.ndarray, power: np.ndarray, center: float) -> float:
+    lo = center / (2.0 ** (1.0 / 6.0))
+    hi = center * (2.0 ** (1.0 / 6.0))
+    mask = (freqs >= lo) & (freqs < hi)
+    if not np.any(mask):
+        return 0.0
+    return float(power[mask].mean())
+
+
+def carve(samples: np.ndarray, sample_rate: float, max_cut_db: float = 4.0) -> list[dict]:
+    mono = _to_mono(samples)
+    freqs, power = _power_spectrum(mono, sample_rate)
+
+    centers = [c for c in CANDIDATE_CENTERS_HZ if SPEECH_LO_HZ <= c <= SPEECH_HI_HZ]
+    band_powers = [(c, _band_power(freqs, power, c)) for c in centers]
+    mean_power = np.mean([p for _, p in band_powers]) or 1.0
+
+    # Rank by how far each band exceeds the average; keep those above average
+    # (up to MAX_BANDS), but always return at least MIN_BANDS (the strongest).
+    ranked = sorted(band_powers, key=lambda cp: cp[1], reverse=True)
+    above = [cp for cp in ranked if cp[1] > mean_power]
+    selected = above[:MAX_BANDS] if len(above) >= MIN_BANDS else ranked[:MIN_BANDS]
+
+    top = max(p for _, p in selected) or 1.0
+    bands: list[dict] = []
+    for center, p in selected:
+        # Deepest cut on the strongest band; shallower elsewhere, floored at
+        # half depth so weak-but-selected bands still get meaningful room.
+        depth = max_cut_db * (p / top)
+        depth = min(max_cut_db, max(max_cut_db / 2.0, depth))
+        bands.append({"freq": float(center), "gainDb": float(-depth), "q": CARVE_Q})
+    bands.sort(key=lambda b: b["freq"])
+    return bands
+
+
+def carve_file(voice_wav: str, max_cut_db: float = 4.0) -> list[dict]:
+    from pedalboard.io import AudioFile
+
+    with AudioFile(voice_wav) as f:
+        samples = f.read(f.frames)  # (channels, frames)
+        sr = f.samplerate
+    return carve(samples, sr, max_cut_db=max_cut_db)

hyperframes_vst/chain.py

@@ -0,0 +1,120 @@
+"""Chain spec: the persisted .vstchain.json contents and live plugin construction."""
+from __future__ import annotations
+
+import base64
+import json
+import os
+from dataclasses import dataclass
+
+import pedalboard
+
+VALID_FORMATS = {"vst3", "au", "builtin"}
+
+
+class ChainError(ValueError):
+    pass
+
+
+class PluginMissingError(ChainError):
+    def __init__(self, name: str):
+        super().__init__(f"Plugin not available on this machine: {name}")
+        self.plugin_name = name
+
+
+@dataclass
+class PluginSpec:
+    format: str
+    path: str
+    plugin_name: str | None
+    name: str
+    state_b64: str | None
+    # Bypass toggle — absent in the JSON means enabled (backward compatible
+    # with chain files written before the field existed). A disabled plugin
+    # is still CONSTRUCTED (so set-param/get-state indices stay aligned with
+    # the chain file) but excluded from the processing board — see
+    # `enabled_plugins`.
+    enabled: bool = True
+
+
+@dataclass
+class ChainSpec:
+    version: int
+    plugins: list[PluginSpec]
+
+
+def load_chain_spec(json_text: str) -> ChainSpec:
+    raw = json.loads(json_text)
+    if raw.get("version") != 1:
+        raise ChainError(f"Unsupported chain version: {raw.get('version')}")
+    plugins = []
+    for p in raw.get("plugins", []):
+        fmt = p.get("format")
+        if fmt not in VALID_FORMATS:
+            raise ChainError(f"Unknown plugin format: {fmt}")
+        plugins.append(
+            PluginSpec(
+                format=fmt,
+                path=p["path"],
+                plugin_name=p.get("pluginName"),
+                name=p.get("name", p["path"]),
+                state_b64=p.get("stateB64"),
+                enabled=p.get("enabled", True) is not False,
+            )
+        )
+    return ChainSpec(version=1, plugins=plugins)
+
+
+def _build_builtin(spec: PluginSpec):
+    cls = getattr(pedalboard, spec.path, None)
+    if cls is None:
+        raise PluginMissingError(spec.name)
+    plugin = cls()
+    if spec.state_b64:
+        params = json.loads(base64.b64decode(spec.state_b64))
+        for key, value in params.items():
+            setattr(plugin, key, value)
+    return plugin
+
+
+def _build_external(spec: PluginSpec):
+    if not os.path.exists(spec.path):
+        raise PluginMissingError(spec.name)
+    try:
+        plugin = pedalboard.load_plugin(spec.path, plugin_name=spec.plugin_name)
+    except Exception as exc:
+        raise PluginMissingError(spec.name) from exc
+    if spec.state_b64:
+        plugin.raw_state = base64.b64decode(spec.state_b64)
+    return plugin
+
+
+def build_chain(spec: ChainSpec) -> list:
+    return [_build_builtin(p) if p.format == "builtin" else _build_external(p) for p in spec.plugins]
+
+
+def enabled_plugins(spec: ChainSpec, built: list) -> list:
+    """The subset of `built` (from `build_chain(spec)`, same order) that should
+    actually process audio. Disabled plugins are constructed but bypassed —
+    keeping the full list's indices aligned with the chain file for
+    set-param/get-state while the processing board skips them. An all-disabled
+    chain yields an empty board, which pedalboard treats as a passthrough."""
+    return [plugin for plugin, p in zip(built, spec.plugins) if p.enabled]
+
+
+def _is_builtin(plugin) -> bool:
+    return not hasattr(plugin, "raw_state")
+
+
+def serialize_states(plugins: list) -> list[str]:
+    states = []
+    for plugin in plugins:
+        if _is_builtin(plugin):
+            params = {
+                key: float(getattr(plugin, key))
+                for key in dir(plugin)
+                if not key.startswith("_") and isinstance(getattr(plugin, key), float)
+            }
+            states.append(base64.b64encode(json.dumps(params).encode()).decode())
+        else:
+            states.append(base64.b64encode(plugin.raw_state).decode())
+    return states

hyperframes_vst/scan.py

@@ -0,0 +1,88 @@
+"""Plugin discovery. Every bundle probe runs in a throwaway subprocess:
+a malformed bundle can SIGBUS the probing process (observed with macOS
+CoreAudio.component), so the sidecar process itself never loads candidates."""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+
+BUNDLE_EXTENSIONS = {".vst3": "vst3", ".component": "au"}
+PROBE_TIMEOUT_SEC = 10
+
+# pedalboard's built-in effects that host cleanly with no constructor args and
+# no external plugin file — the reliable, always-available options (unlike
+# third-party VST3/AU, which pedalboard's headless host can't run for a real
+# subset; see the stability guard). Each maps to a `pedalboard.<name>` class in
+# chain.py's `_build_builtin` (format "builtin", path = the class name).
+# Ordered most-useful-first for the FX picker. Convolution and IIRFilter are
+# excluded: they require constructor arguments (an impulse response / filter
+# coefficients) this add flow can't supply.
+BUILTIN_EFFECTS = [
+    "Reverb", "Delay", "Chorus", "Phaser", "Distortion", "Compressor",
+    "Limiter", "NoiseGate", "Gain", "PitchShift", "Bitcrush", "Clipping",
+    "LadderFilter", "LowpassFilter", "HighpassFilter", "PeakFilter",
+    "LowShelfFilter", "HighShelfFilter", "MP3Compressor", "Invert",
+]
+
+
+def builtin_registry() -> list[dict]:
+    """The built-in effects, in FX-picker registry form. `pluginName` is None
+    (builtins take no sub-name), `path` is the pedalboard class name."""
+    return [{"path": name, "name": name, "format": "builtin"} for name in BUILTIN_EFFECTS]
+
+
+def default_plugin_dirs() -> list[str]:
+    home = os.path.expanduser("~")
+    if sys.platform == "darwin":
+        return [
+            "/Library/Audio/Plug-Ins/VST3",
+            f"{home}/Library/Audio/Plug-Ins/VST3",
+            "/Library/Audio/Plug-Ins/Components",
+            f"{home}/Library/Audio/Plug-Ins/Components",
+        ]
+    if sys.platform == "win32":
+        return [r"C:\Program Files\Common Files\VST3"]
+    return []
+
+
+def _probe(bundle: str, probe_cmd: list[str]) -> list[dict]:
+    try:
+        proc = subprocess.run(
+            probe_cmd + [bundle], capture_output=True, text=True, timeout=PROBE_TIMEOUT_SEC
+        )
+    except subprocess.TimeoutExpired:
+        return []
+    if proc.returncode != 0:
+        return []
+    try:
+        return json.loads(proc.stdout)
+    except json.JSONDecodeError:
+        return []
+
+
+def scan_paths(dirs: list[str], probe_cmd: list[str] | None = None) -> list[dict]:
+    cmd = probe_cmd or [sys.executable, "-m", "hyperframes_vst", "probe"]
+    registry: list[dict] = []
+    for d in dirs:
+        if not os.path.isdir(d):
+            continue
+        for entry in sorted(os.listdir(d)):
+            _, ext = os.path.splitext(entry)
+            fmt = BUNDLE_EXTENSIONS.get(ext.lower())
+            if fmt is None:
+                continue
+            bundle = os.path.join(d, entry)
+            for item in _probe(bundle, cmd):
+                registry.append({"path": bundle, "name": item["name"], "format": fmt})
+    return registry
+
+
+def probe_bundle(path: str) -> list[dict]:
+    """Runs IN the throwaway subprocess. May crash; caller tolerates."""
+    from pedalboard._pedalboard import AudioUnitPlugin, VST3Plugin
+
+    cls = AudioUnitPlugin if path.lower().endswith(".component") else VST3Plugin
+    names = cls.get_plugin_names_for_file(path)
+    return [{"name": n} for n in names]