serum-render 0.1.0__py3-none-any.whl

serum_render/__init__.py

@@ -0,0 +1,35 @@
+"""
+serum-render — batch Serum 1 (.fxp) and Serum 2 (.SerumPreset) preset
+rendering via DawDreamer.
+
+Public API:
+    from serum_render import (
+        RenderConfig,
+        Renderer,
+        ParallelRenderer,
+        render_preset,
+    )
+
+RenderConfig is eager (pure-Python). The renderer entry points are
+exposed lazily via PEP 562 __getattr__ so that importing worker-side
+modules inside a loky worker process does NOT transitively import
+dawdreamer / numpy at module level — dawdreamer must be the first
+non-stdlib import in a render process, enforced inside EngineHost.
+"""
+from __future__ import annotations
+
+from .config import RenderConfig
+
+__all__ = [
+    "RenderConfig",
+    "Renderer",
+    "ParallelRenderer",
+    "render_preset",
+]
+
+
+def __getattr__(name: str):
+    if name in ("Renderer", "ParallelRenderer", "render_preset"):
+        from . import api
+        return getattr(api, name)
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

serum_render/api.py

@@ -0,0 +1,203 @@
+"""
+Public library API: Renderer, ParallelRenderer, render_preset.
+
+Thin wrappers over the single render core (engine.EngineHost) — no
+render logic lives here. Module level stays stdlib-only so importing
+the package stays cheap and worker-safe.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Iterable, Iterator
+
+from .config import RenderConfig
+from .discover import get_midi_duration
+from .engine import EngineHost
+from .formats import PresetFormat, format_for_path
+from .jobs import Job
+
+if TYPE_CHECKING:
+    import numpy as np
+
+
+def _validate_entry(config: RenderConfig) -> float | None:
+    """First-use validation: any plugin/MIDI path the caller set must
+    exist. Returns the precomputed MIDI duration (workers never parse
+    MIDI) or None."""
+    for path in (config.serum1_plugin_path, config.serum2_plugin_path):
+        if path is not None and not Path(path).exists():
+            raise FileNotFoundError(f"Plugin not found: {path}")
+    if config.midi_path is not None:
+        if not Path(config.midi_path).exists():
+            raise FileNotFoundError(f"MIDI file not found: {config.midi_path}")
+        return get_midi_duration(Path(config.midi_path))
+    return None
+
+
+def _check_format_coverage(
+    config: RenderConfig, formats: Iterable[PresetFormat]
+) -> None:
+    """Every format actually being rendered must have its plugin path on
+    the config. Fails before any engine boots, naming the missing field."""
+    missing = sorted(
+        f"{'.fxp' if fmt is PresetFormat.SERUM1 else '.SerumPreset'} preset(s) "
+        f"supplied but RenderConfig.{fmt.value}_plugin_path is unset"
+        for fmt in set(formats)
+        if config.plugin_path_for(fmt) is None
+    )
+    if missing:
+        raise ValueError("; ".join(missing))
+
+
+def _build_job(
+    config: RenderConfig, preset_path: str | Path, midi_duration: float | None
+) -> Job:
+    path = Path(preset_path)
+    fmt = format_for_path(path)
+    _check_format_coverage(config, [fmt])
+    return Job(
+        preset_path=str(path.resolve()),
+        format=fmt,
+        note=config.note,
+        velocity=config.velocity,
+        duration=config.duration,
+        tail=config.tail,
+        midi_path=(
+            str(Path(config.midi_path).resolve())
+            if config.midi_path is not None
+            else None
+        ),
+        midi_duration=midi_duration,
+    )
+
+
+class Renderer:
+    """
+    Single-process, sequential renderer. Loads the configured plugin(s)
+    once in `__enter__` and hot-swaps presets for every `render()` call.
+    Preset format is auto-detected from the file suffix. Errors raise.
+    """
+
+    def __init__(self, config: RenderConfig):
+        self.config = config
+        self._host: EngineHost | None = None
+        self._midi_duration: float | None = None
+        self._entered = False
+
+    def __enter__(self) -> "Renderer":
+        self._midi_duration = _validate_entry(self.config)
+        if not self.config.deterministic:
+            # Deterministic mode never builds an in-process engine —
+            # every render runs in its own single-use process.
+            self._host = EngineHost(
+                self.config.serum1_plugin_path,
+                self.config.serum2_plugin_path,
+                self.config.sample_rate,
+            )
+        self._entered = True
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        # DawDreamer has no explicit teardown — drop the ref for GC.
+        self._host = None
+        self._entered = False
+
+    def render(self, preset_path: str | Path) -> "np.ndarray":
+        if not getattr(self, "_entered", False):
+            raise RuntimeError("Renderer must be used as a context manager")
+        job = _build_job(self.config, preset_path, self._midi_duration)
+        if self.config.deterministic:
+            from .pool import render_isolated
+
+            cfg = self.config
+            result = render_isolated(
+                job,
+                str(cfg.serum1_plugin_path) if cfg.serum1_plugin_path else None,
+                str(cfg.serum2_plugin_path) if cfg.serum2_plugin_path else None,
+                cfg.sample_rate,
+                keep_audio=True,
+            )
+            if result["status"] != "ok":
+                raise RuntimeError(
+                    f"Deterministic render failed for {preset_path}: "
+                    f"{result.get('error')}"
+                )
+            return result["audio"]
+        return self._host.render(job)
+
+
+class ParallelRenderer:
+    """
+    Multi-process renderer for bulk use. Mixed-format batches are fine —
+    format is auto-detected per path. Audio ships back from workers to
+    the main process (~700 KB per 2s stereo render); for very large
+    libraries iterate and spill to disk instead of holding the dict.
+    """
+
+    def __init__(self, config: RenderConfig, workers: int = -1):
+        self.config = config
+        self.workers = workers
+        self._midi_duration: float | None = None
+        self._entered = False
+
+    def __enter__(self) -> "ParallelRenderer":
+        self._midi_duration = _validate_entry(self.config)
+        self._entered = True
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        # Executor is owned by loky's reusable cache; leave it warm so
+        # the next ParallelRenderer in this process reuses the workers.
+        self._entered = False
+
+    def _build_jobs(self, preset_paths: list[str | Path]) -> list[Job]:
+        if not self._entered:
+            raise RuntimeError(
+                "ParallelRenderer must be used as a context manager"
+            )
+        # Coverage-check the whole batch first so the error names every
+        # missing plugin path in one pass, before any worker boots.
+        _check_format_coverage(
+            self.config, [format_for_path(Path(p)) for p in preset_paths]
+        )
+        return [
+            _build_job(self.config, p, self._midi_duration) for p in preset_paths
+        ]
+
+    def iter_batch(
+        self, preset_paths: list[str | Path]
+    ) -> Iterator[tuple[str, "np.ndarray"]]:
+        """Yield `(preset_path, audio)` as each job completes (unordered).
+        Failed jobs are logged by the worker and skipped here."""
+        from .pool import iter_jobs, iter_jobs_isolated
+
+        jobs = self._build_jobs(preset_paths)
+        cfg = self.config
+        serum1 = str(cfg.serum1_plugin_path) if cfg.serum1_plugin_path else None
+        serum2 = str(cfg.serum2_plugin_path) if cfg.serum2_plugin_path else None
+        if cfg.deterministic:
+            results = iter_jobs_isolated(
+                jobs, self.workers, serum1, serum2, cfg.sample_rate,
+                keep_audio=True,
+            )
+        else:
+            results = iter_jobs(jobs, self.workers, serum1, serum2, cfg.sample_rate)
+        for result in results:
+            if result["status"] == "ok":
+                yield result["path"], result["audio"]
+
+    def render_batch(
+        self, preset_paths: list[str | Path]
+    ) -> dict[str, "np.ndarray"]:
+        """Render all presets and return a dict mapping path -> audio."""
+        return dict(self.iter_batch(preset_paths))
+
+
+def render_preset(preset_path: str | Path, config: RenderConfig) -> "np.ndarray":
+    """
+    One-off render. Spins up a fresh EngineHost, renders, returns audio.
+    Not suitable for batch use — each call pays the ~1-2s plugin
+    cold-start plus a 0.1s warmup render per loaded synth.
+    """
+    with Renderer(config) as renderer:
+        return renderer.render(preset_path)

serum_render/cli.py

@@ -0,0 +1,274 @@
+"""
+Typer CLI entry point. Discovers presets, resolves plugin paths (explicit
+flags beat platform defaults), builds typed Jobs, and drives the pool.
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Optional
+
+import typer
+from rich.progress import (
+    BarColumn,
+    MofNCompleteColumn,
+    Progress,
+    TextColumn,
+    TimeElapsedColumn,
+    TimeRemainingColumn,
+)
+
+from .config import default_plugin_path
+from .discover import (
+    compose_filename,
+    discover_presets,
+    get_midi_duration,
+    resolve_output_paths,
+)
+from .formats import PresetFormat
+from .jobs import Job
+from .pool import iter_jobs, resolve_worker_count
+
+logger = logging.getLogger("serum_render")
+
+app = typer.Typer(
+    add_completion=False,
+    help="Batch-render Serum presets (.fxp, .SerumPreset) to audio.",
+)
+
+_FLAG_FOR = {PresetFormat.SERUM1: "--serum1", PresetFormat.SERUM2: "--serum2"}
+_EXT_FOR = {PresetFormat.SERUM1: ".fxp", PresetFormat.SERUM2: ".SerumPreset"}
+_PLUGIN_NAME_FOR = {PresetFormat.SERUM1: "Serum 1", PresetFormat.SERUM2: "Serum 2"}
+
+
+def _setup_logging(verbose: bool) -> None:
+    """Only the CLI configures logging — library code uses a named logger."""
+    logging.basicConfig(
+        level=logging.DEBUG if verbose else logging.WARNING,
+        format="%(levelname)s %(name)s: %(message)s",
+    )
+
+
+@app.command()
+def render(
+    presets: Path = typer.Argument(..., help="Path to a single preset (.fxp or .SerumPreset) or a directory of them."),
+    output: Path = typer.Argument(..., help="Output directory (created if missing)."),
+    serum1: Optional[Path] = typer.Option(
+        None, "--serum1",
+        help="Path to a Serum 1 plugin that loads .fxp presets — the VST2 "
+             "binary (.dll on Windows, .vst bundle on macOS). Defaults to "
+             "the standard install location if .fxp files are being "
+             "rendered and it exists.",
+    ),
+    serum2: Optional[Path] = typer.Option(
+        None, "--serum2",
+        help="Path to the Serum 2 VST3 plugin. Defaults to the standard "
+             "install location if .SerumPreset files are being rendered "
+             "and it exists.",
+    ),
+    note: Optional[int] = typer.Option(None, min=0, max=127, help="MIDI note (0-127). Default 48 (C3)."),
+    velocity: int = typer.Option(127, min=1, max=127, help="MIDI velocity (1-127)."),
+    duration: float = typer.Option(1.0, help="Note-on duration in seconds (> 0)."),
+    tail: float = typer.Option(1.0, min=0.0, help="Release silence in seconds (>= 0)."),
+    sample_rate: int = typer.Option(44100, "--sample-rate", min=1, help="Output sample rate in Hz."),
+    bit_depth: str = typer.Option("16", "--bit-depth", help="Output bit depth: 16, 24, or 32f."),
+    fmt: str = typer.Option("wav", "--format", help="Output container: wav or npy."),
+    filename_template: str = typer.Option(
+        "{preset}", "--filename-template",
+        help="Filename template. Vars: {preset} {note} {velocity} {folder} {subpath}.",
+    ),
+    midi: Optional[Path] = typer.Option(None, "--midi", help="Path to a .mid file (overrides --note)."),
+    workers: int = typer.Option(-1, "--workers", help="Parallel workers. -1 = cpu_count - 1."),
+    skip_existing: bool = typer.Option(False, "--skip-existing", help="Skip if output file already exists."),
+    deterministic: bool = typer.Option(
+        False, "--deterministic",
+        help="Render every preset in a fresh single-use process so batch "
+             "output is bit-reproducible. Slower: one plugin load per "
+             "preset instead of per worker.",
+    ),
+    no_recurse: bool = typer.Option(False, "--no-recurse", help="Do not recurse into subdirectories."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Print presets that would render and exit."),
+    verbose: bool = typer.Option(False, "--verbose", help="Per-preset status logging."),
+) -> None:
+    _setup_logging(verbose)
+
+    # --note and --midi are mutually exclusive. Typer can't detect a
+    # user-set default, so we use None sentinel + manual check.
+    if midi is not None and note is not None:
+        raise typer.BadParameter(
+            "--note and --midi are mutually exclusive. Use --midi to render a "
+            "MIDI sequence, or --note to render a single note."
+        )
+    if note is None:
+        note = 48
+
+    # Typer's `min=` is inclusive, so "> 0" on duration needs a manual check.
+    if duration <= 0:
+        raise typer.BadParameter(f"--duration must be > 0 (got {duration}).")
+
+    if bit_depth not in ("16", "24", "32f"):
+        raise typer.BadParameter(f"--bit-depth must be 16, 24, or 32f (got {bit_depth!r}).")
+    if fmt not in ("wav", "npy"):
+        raise typer.BadParameter(f"--format must be wav or npy (got {fmt!r}).")
+
+    # Path.exists() returns True for VST3 bundle directories on macOS and
+    # for plain .vst3 / .dll / .vst files on Windows + macOS — both shapes
+    # are valid plugin paths, so no is_file() check.
+    if serum1 is not None and not serum1.exists():
+        typer.echo(f"Plugin not found: {serum1}", err=True)
+        raise typer.Exit(code=2)
+    if serum2 is not None and not serum2.exists():
+        typer.echo(f"Plugin not found: {serum2}", err=True)
+        raise typer.Exit(code=2)
+    if not presets.exists():
+        typer.echo(f"Presets path not found: {presets}", err=True)
+        raise typer.Exit(code=2)
+    if output.exists() and not output.is_dir():
+        typer.echo(f"Output path exists and is not a directory: {output}", err=True)
+        raise typer.Exit(code=2)
+
+    try:
+        preset_files = discover_presets(presets, recurse=not no_recurse)
+    except ValueError as exc:
+        # Single-file mode with an unsupported extension.
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(code=2) from None
+    if not preset_files:
+        typer.echo(
+            f"No supported preset files (.fxp, .SerumPreset) found under {presets}",
+            err=True,
+        )
+        raise typer.Exit(code=0)
+
+    # Resolve plugin paths: an explicit flag always wins; otherwise fall
+    # back to the standard install location — but only for formats that
+    # actually appear in the discovered set, and only if the default
+    # exists on disk (a missing default is "unset", not an error).
+    discovered_formats = {fmt_tag for _, fmt_tag in preset_files}
+    plugin_paths: dict[PresetFormat, Path] = {}
+    explicit = {PresetFormat.SERUM1: serum1, PresetFormat.SERUM2: serum2}
+    for preset_fmt in discovered_formats:
+        if explicit[preset_fmt] is not None:
+            plugin_paths[preset_fmt] = explicit[preset_fmt]
+        else:
+            fallback = default_plugin_path(preset_fmt)
+            if fallback is not None:
+                plugin_paths[preset_fmt] = fallback
+                typer.echo(
+                    f"Using default {_PLUGIN_NAME_FOR[preset_fmt]} plugin: {fallback}"
+                )
+
+    missing = discovered_formats - set(plugin_paths)
+    if missing:
+        msgs = sorted(
+            f"found {_EXT_FOR[m]} files but {_FLAG_FOR[m]} was not provided "
+            f"and no default {_PLUGIN_NAME_FOR[m]} install was found"
+            for m in missing
+        )
+        for m in msgs:
+            typer.echo(m, err=True)
+        raise typer.Exit(code=2)
+
+    # Single-file mode: presets_root=None so {subpath} collapses out.
+    # Resolve when a directory so `relative_to` works against the absolute
+    # preset paths that discover_presets returns — a relative presets arg
+    # would otherwise silently collapse {subpath} to an empty string.
+    presets_root: Path | None = presets.resolve() if presets.is_dir() else None
+
+    # Compute MIDI duration once in the main process — all workers share it.
+    midi_duration: float | None = None
+    midi_str: str | None = None
+    if midi is not None:
+        if not midi.exists():
+            typer.echo(f"MIDI file not found: {midi}", err=True)
+            raise typer.Exit(code=2)
+        try:
+            midi_duration = get_midi_duration(midi)
+        except (TypeError, ValueError) as exc:
+            typer.echo(f"Error reading MIDI file '{midi}': {exc}", err=True)
+            raise typer.Exit(code=2) from None
+        midi_str = str(midi.resolve())
+
+    extension = ".npy" if fmt == "npy" else ".wav"
+    stems = [
+        compose_filename(filename_template, p, presets_root, note, velocity)
+        for p, _ in preset_files
+    ]
+    output_paths = resolve_output_paths(stems, output, extension)
+    jobs = [
+        Job(
+            preset_path=str(p.resolve()),
+            format=preset_fmt,
+            note=note,
+            velocity=velocity,
+            duration=duration,
+            tail=tail,
+            midi_path=midi_str,
+            midi_duration=midi_duration,
+            output_path=out,
+            bit_depth=bit_depth,
+            output_format=fmt,
+            skip_existing=skip_existing,
+        )
+        for (p, preset_fmt), out in zip(preset_files, output_paths)
+    ]
+
+    if dry_run:
+        typer.echo(f"Would render {len(jobs)} preset(s):")
+        for j in jobs:
+            typer.echo(f"  {j.preset_path}  ->  {j.output_path}")
+        raise typer.Exit(code=0)
+
+    output.mkdir(parents=True, exist_ok=True)
+    n_workers = resolve_worker_count(workers)
+    serum1_str = (
+        str(plugin_paths[PresetFormat.SERUM1].resolve())
+        if PresetFormat.SERUM1 in plugin_paths
+        else None
+    )
+    serum2_str = (
+        str(plugin_paths[PresetFormat.SERUM2].resolve())
+        if PresetFormat.SERUM2 in plugin_paths
+        else None
+    )
+
+    results: list[dict] = []
+    if deterministic:
+        from .pool import iter_jobs_isolated
+
+        result_iter = iter_jobs_isolated(
+            jobs, n_workers, serum1_str, serum2_str, sample_rate
+        )
+    else:
+        result_iter = iter_jobs(jobs, n_workers, serum1_str, serum2_str, sample_rate)
+
+    # In verbose mode, per-preset DEBUG logs replace the progress bar so
+    # the two don't fight for the terminal.
+    if verbose:
+        typer.echo(f"Rendering {len(jobs)} preset(s) with {n_workers} workers…")
+        results = list(result_iter)
+    else:
+        with Progress(
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            MofNCompleteColumn(),
+            TextColumn("•"),
+            TimeElapsedColumn(),
+            TextColumn("•"),
+            TimeRemainingColumn(),
+        ) as progress:
+            task_id = progress.add_task(
+                f"Rendering ({n_workers} workers)", total=len(jobs)
+            )
+            for result in result_iter:
+                results.append(result)
+                progress.advance(task_id)
+
+    ok = sum(1 for r in results if r["status"] == "ok")
+    skipped = sum(1 for r in results if r["status"] == "skipped")
+    errors = [r for r in results if r["status"] == "error"]
+
+    typer.echo(f"Done: {ok} rendered, {skipped} skipped, {len(errors)} failed.")
+    for r in errors:
+        typer.echo(f"  FAIL {r.get('path')}: {r.get('error')}", err=True)
+    raise typer.Exit(code=1 if errors else 0)

serum_render/config.py

@@ -0,0 +1,96 @@
+"""Frozen render configuration. Stdlib-only at module level."""
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from .formats import PresetFormat
+
+# Peak below this is treated as silent output by the engine.
+# -90 dBFS ~= 16-bit quantization floor. Advisory only — known to be
+# conservative for 24/32f bit depths.
+SILENCE_EPS = 3.16e-5
+
+
+# Standard Serum install locations, used as fallbacks when no explicit
+# plugin path is given. INVARIANT: the SERUM1 entry must be a VST2 binary —
+# the Serum 1 VST3 silently mis-loads .fxp presets. On Windows the 64-bit
+# VST2 really does live in the VST3 folder (Xfer installer quirk).
+_DEFAULT_PLUGIN_PATHS: dict[str, dict[PresetFormat, str]] = {
+    "darwin": {
+        PresetFormat.SERUM1: "/Library/Audio/Plug-Ins/VST/Serum.vst",
+        PresetFormat.SERUM2: "/Library/Audio/Plug-Ins/VST3/Serum2.vst3",
+    },
+    "win32": {
+        PresetFormat.SERUM1: "C:/Program Files/Common Files/VST3/Serum_x64.dll",
+        PresetFormat.SERUM2: "C:/Program Files/Common Files/VST3/Serum2.vst3",
+    },
+}
+
+
+def default_plugin_path(fmt: PresetFormat, platform: str | None = None) -> Path | None:
+    """Return the standard install path for a format if it exists on disk.
+
+    A missing default is "unset" (returns None), never an error — the
+    caller falls through to its normal missing-plugin message.
+    """
+    platform = platform if platform is not None else sys.platform
+    table = _DEFAULT_PLUGIN_PATHS.get(platform)
+    if table is None:
+        return None
+    candidate = Path(table[fmt])
+    return candidate if candidate.exists() else None
+
+
+@dataclass(frozen=True)
+class RenderConfig:
+    # At least one of these must be set. `serum1_plugin_path` accepts either
+    # the VST2 binary or the VST3 build of Serum 1 for library users who
+    # know what they're doing — but only the VST2 build loads .fxp
+    # correctly, so the CLI default never picks the VST3.
+    # `serum2_plugin_path` is Serum 2's VST3, paired with `load_state`.
+    serum1_plugin_path: str | Path | None = None
+    serum2_plugin_path: str | Path | None = None
+    sample_rate: int = 44100
+    note: int = 48
+    velocity: int = 127
+    duration: float = 1.0
+    tail: float = 1.0
+    midi_path: str | Path | None = None
+    # Render every preset in a fresh single-use process, making batch
+    # output bit-reproducible. Costs a plugin load per preset instead of
+    # per worker. In-process resets don't work for Serum 1 (state
+    # survives even a full engine reload); see docs/decisions.md.
+    deterministic: bool = False
+
+    def __post_init__(self) -> None:
+        # Cheap shape/range checks only — no disk I/O. Path existence is
+        # verified on first use (renderer entry), keeping construction free
+        # of filesystem side effects.
+        if self.serum1_plugin_path is None and self.serum2_plugin_path is None:
+            raise ValueError(
+                "RenderConfig requires at least one of serum1_plugin_path or "
+                "serum2_plugin_path to be set."
+            )
+        for field in ("serum1_plugin_path", "serum2_plugin_path", "midi_path"):
+            value = getattr(self, field)
+            if value is not None:
+                object.__setattr__(self, field, Path(value))
+
+        if self.sample_rate <= 0:
+            raise ValueError(f"sample_rate must be > 0, got {self.sample_rate}")
+        if not (0 <= self.note <= 127):
+            raise ValueError(f"note must be 0-127, got {self.note}")
+        if not (1 <= self.velocity <= 127):
+            raise ValueError(f"velocity must be 1-127, got {self.velocity}")
+        if self.duration <= 0:
+            raise ValueError(f"duration must be > 0, got {self.duration}")
+        if self.tail < 0:
+            raise ValueError(f"tail must be >= 0, got {self.tail}")
+
+    def plugin_path_for(self, fmt: PresetFormat) -> Path | None:
+        return {
+            PresetFormat.SERUM1: self.serum1_plugin_path,
+            PresetFormat.SERUM2: self.serum2_plugin_path,
+        }[fmt]