serum-render 0.2.0__tar.gz → 0.3.1__tar.gz

{serum_render-0.2.0 → serum_render-0.3.1}/KNOWN_ISSUES.md

@@ -137,3 +137,15 @@ problem.
 is bimodal and obvious, not subtle. Affected presets are the sample-based ones
 (pianos, guitars, drum kits, orchestral); pure-synthesis presets and all of
 Serum 1 are unaffected.
+
+---
+
+## A killed render can leave a stray `.tmp` file
+
+`write_audio` renders to `<output>.wav.tmp` / `<output>.npy.tmp` and renames it into place, so a `SIGKILL` mid-write can never leave a truncated file at the real output path — which `--skip-existing` would otherwise skip forever on the re-run. The trade is that a killed batch leaves up to `--workers` stray `.tmp` files. The suffix goes *after* the real extension deliberately, so strays stay out of `*.wav` globs. Delete them with `find <output> -name '*.tmp' -delete`.
+
+---
+
+## Worker stdout is shared with the `--json` event stream
+
+loky workers inherit the parent's stdout, so a plugin printing from C code could in principle interleave with `--json` output and split an event line in two. This has never been observed — the only noise Serum's loader is known to produce goes to stderr (see the JUCE entry above) — and nothing in serum-render writes to stdout from a worker. Consumers should skip any line that fails to parse and trust the counts in the `done` event over their own tally of `result` events, which is where a lost line becomes visible.

{serum_render-0.2.0 → serum_render-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: serum-render
-Version: 0.2.0
+Version: 0.3.1
 Summary: Batch-render Serum 1 (.fxp) and Serum 2 (.SerumPreset) presets to audio files via DawDreamer.
 Project-URL: Homepage, https://github.com/wiillownet/serum-render
 Project-URL: Repository, https://github.com/wiillownet/serum-render
@@ -90,11 +90,48 @@ A directory containing both `.fxp` and `.SerumPreset` files renders as one mixed
 | `--midi` | — | Render a `.mid` file instead of a single note. |
 | `--workers` | `-1` | Parallel workers; `-1` = `cpu_count - 1`. |
 | `--skip-existing` | off | Skip presets whose output already exists. |
+| `--skip-missing-format` | off | Render what the installed plugins cover instead of refusing the whole batch. |
 | `--no-recurse` | off | Don't descend into subdirectories. |
 | `--dry-run` | off | Print the render plan and exit. |
+| `--json` | off | Emit machine-readable events on stdout (see below). |
 
 Run `serum-render --help` for the full list.
 
+### Machine-readable output
+
+`--json` writes one JSON object per line to stdout and moves every
+human-readable line to stderr, for driving serum-render from another
+program:
+
+```
+{"event":"start","schema":1,"total":4271,"workers":7}
+{"event":"result","status":"ok","path":".../Bass 1.fxp","peak":0.3325}
+{"event":"result","status":"skipped","path":"...","reason":"exists"}
+{"event":"result","status":"error","path":"...","error":"..."}
+{"event":"done","ok":4268,"skipped":0,"failed":3,"elapsed":612.4}
+```
+
+`--dry-run --json` emits the `start` event alone and exits. Exit codes
+are unchanged: `0` clean, `1` some renders failed, `2` usage or
+validation error. Validation errors write to stderr and produce no
+events, so **exit 0 always means at least one `done` event** — a run that
+found no presets still emits `start` with `total: 0` and a zeroed `done`.
+
+Two rules for consumers. Reject an unrecognised `schema` rather than
+guessing at the shape. And skip any stdout line that fails to parse:
+loky workers inherit the parent's stdout, so a plugin printing from C
+could in principle interleave with the stream — trust the counts in
+`done` over a local tally of `result` events.
+
+A `skipped` result carries a `reason`: `exists` when `--skip-existing`
+found the output already written, or `no_plugin` when
+`--skip-missing-format` dropped a preset whose plugin is not installed.
+Both are counted in `done`'s `skipped`, and both are inside `start`'s
+`total` — `total` covers every preset the run reports on, not just the
+ones it renders.
+
+**The output shape is unstable until 1.0.**
+
 ## Library API
 
 ```python

{serum_render-0.2.0 → serum_render-0.3.1}/README.md

@@ -62,11 +62,48 @@ A directory containing both `.fxp` and `.SerumPreset` files renders as one mixed
 | `--midi` | — | Render a `.mid` file instead of a single note. |
 | `--workers` | `-1` | Parallel workers; `-1` = `cpu_count - 1`. |
 | `--skip-existing` | off | Skip presets whose output already exists. |
+| `--skip-missing-format` | off | Render what the installed plugins cover instead of refusing the whole batch. |
 | `--no-recurse` | off | Don't descend into subdirectories. |
 | `--dry-run` | off | Print the render plan and exit. |
+| `--json` | off | Emit machine-readable events on stdout (see below). |
 
 Run `serum-render --help` for the full list.
 
+### Machine-readable output
+
+`--json` writes one JSON object per line to stdout and moves every
+human-readable line to stderr, for driving serum-render from another
+program:
+
+```
+{"event":"start","schema":1,"total":4271,"workers":7}
+{"event":"result","status":"ok","path":".../Bass 1.fxp","peak":0.3325}
+{"event":"result","status":"skipped","path":"...","reason":"exists"}
+{"event":"result","status":"error","path":"...","error":"..."}
+{"event":"done","ok":4268,"skipped":0,"failed":3,"elapsed":612.4}
+```
+
+`--dry-run --json` emits the `start` event alone and exits. Exit codes
+are unchanged: `0` clean, `1` some renders failed, `2` usage or
+validation error. Validation errors write to stderr and produce no
+events, so **exit 0 always means at least one `done` event** — a run that
+found no presets still emits `start` with `total: 0` and a zeroed `done`.
+
+Two rules for consumers. Reject an unrecognised `schema` rather than
+guessing at the shape. And skip any stdout line that fails to parse:
+loky workers inherit the parent's stdout, so a plugin printing from C
+could in principle interleave with the stream — trust the counts in
+`done` over a local tally of `result` events.
+
+A `skipped` result carries a `reason`: `exists` when `--skip-existing`
+found the output already written, or `no_plugin` when
+`--skip-missing-format` dropped a preset whose plugin is not installed.
+Both are counted in `done`'s `skipped`, and both are inside `start`'s
+`total` — `total` covers every preset the run reports on, not just the
+ones it renders.
+
+**The output shape is unstable until 1.0.**
+
 ## Library API
 
 ```python

{serum_render-0.2.0 → serum_render-0.3.1}/docs/decisions.md

@@ -75,3 +75,35 @@ Two effects are mixed together here, which is why one knob cannot address them:
 Also measured: with no settle, most presets are stable across loads 2..N and only load 1 differs. That is the order-dependence already documented, not a third effect.
 
 **Alternatives considered:** a longer warmup at `EngineHost` construction — rejected, it happens before any preset is loaded, so it cannot affect a per-preset sample load. A per-preset settle tuned by sample count or blob size — not attempted: worth doing only if a structural trait is first shown to predict which presets drift, and that has not been established. Waiting on a load-complete signal from the plugin — no such signal is known to be exposed via DawDreamer.
+
+## [2026-09-01] A GUI drives serum-render as a subprocess over `--json`, not as a library
+
+**Decision:** the forthcoming GUI (separate repo, PySide6) spawns `python -m serum_render ... --json` and parses an NDJSON event stream from stdout. serum-render gains `--json`, `__main__.py`, an atomic `write_audio`, and a `peak` field on the result dict. It does **not** gain a public batch API for the GUI to call.
+
+**Reason:** the GUI must not host the render, because DawDreamer hangs off the main thread (`engine.py`) — that is settled. What was not obvious is which *kind* of process boundary. The deciding factor is packaging: the GUI is intended to ship as a bundled app, and a frozen PySide6 app must never host loky's workers, because `spawn` re-executes `sys.executable`, which inside a bundle is the app itself. Spawning a separate interpreter sidesteps that entirely. Secondarily, `--json` is useful for scripting independent of any GUI, and the subprocess reuses the ~110 lines of validation, discovery, filename composition and collision resolution in `cli.py` rather than duplicating them.
+
+Two reasons that were considered and are explicitly **not** why, recorded so they are not repeated as justification: *crash isolation* (the parent process is identical either way — dawdreamer only loads inside `EngineHost.__init__`, in a worker — so a segfault kills a worker in both designs, and no worker death has ever been observed here), and *cleaner cancellation* (loky's `shutdown(wait=True, kill_workers=True)` is one line, against the ~40 lines of process-group code the subprocess boundary requires).
+
+**Alternatives considered:** extract `cli.py`'s job-building into a public `plan_jobs() -> list[Job]` and drive `pool.iter_jobs` from a GUI background thread — genuinely works (the pool parent never imports dawdreamer, and `iter_jobs_isolated` already threads the parent), and is roughly 200 lines cheaper overall, but forecloses the bundled-app path above. A GUI-owned driver subprocess emitting its own protocol — pays the protocol cost *and* duplicates `cli.py`. Rejected: putting the event stream on stderr, which would delete the stdout-hygiene work but move events onto the one stream with observed C-level writes (JUCE, see `KNOWN_ISSUES.md`). Rejected: an `os.dup2(2, 1)` worker initializer to pre-empt stdout pollution — the hazard is structural but has never been observed, and placing it in `init_worker` breaks every `--deterministic` render, since `isolated.py` calls that same function and then prints its result line to stdout.
+
+**Contract the GUI depends on, recorded because it lives nowhere else:** exit `0` clean, `1` some renders failed, `2` usage or validation error. Validation errors produce no events, so exit 0 always implies at least one `done` event — including the no-presets case, which emits `start` with `total: 0`. Shape is unstable until 1.0; the `schema` key exists so a consumer fails loudly instead of mis-parsing.
+
+**Reversal criterion:** revisit if the GUI ever needs per-job *start* events (the parent submits all futures at once and cannot know when a job begins, so that needs a worker-side change) or the audio array itself.
+
+## [2026-09-05] Render what the installed plugins cover, behind a flag
+
+**Decision:** Add `--skip-missing-format`, default off. With it, a batch whose library holds a format with no installed plugin renders the presets it can and reports the rest as ordinary `skipped` results carrying `"reason": "no_plugin"`; without it, `cli.py`'s existing refusal of the whole batch with exit 2 is unchanged. Skips from `--skip-existing` gained the matching `"reason": "exists"`. `start`'s `total` counts dropped presets, matching how skip-existing skips were already counted inside it. If *nothing* is renderable, the flag still exits 2.
+
+**Reason:** A library holding both `.fxp` and `.SerumPreset` on a machine with one synth installed was entirely unrenderable — and that is the common install, not an edge case. The GUI's design makes filtering a hard requirement: it states the split ("770 will render · 765 need Serum 2, skipped") in the footer and puts the renderable count on the Render button, so it cannot call a code path that aborts instead. Default-off keeps the failure loud where it should be: a typo'd `--serum2` path must not quietly render half a library, and the flag is opt-in precisely so that mistake still costs an exit 2. `reason` rather than a new status value means `done`'s `skipped` count already includes these and an existing consumer needs no new branch — while the GUI, which must word the two skips differently ("never renderable" vs "already rendered"), can tell them apart.
+
+**Alternatives considered:** `--only-format serum1|serum2`, with the caller running one batch per installed synth — two plugin cold starts at ~10–15s each and two event streams to merge, to express what one flag says. Passing an explicit preset list instead of a directory — the CLI's whole input contract is one path, so this is a larger change than the problem. Making the filtering behaviour the default — rejected because it silently converts a misconfiguration into a half-finished batch. A distinct `"status": "unrenderable"` — rejected because every existing consumer would need a new branch to keep its counts reconciling.
+
+**Note:** the GUI plan (revision 3) explicitly said "do not add a `--skip-missing-format` flag on speculation." That was correct on the information then available; the speculation resolved when the design made batch filtering a requirement rather than a guess.
+
+## [2026-09-05] Expected plugin suffix lives beside the default plugin paths
+
+**Decision:** Add `_PLUGIN_SUFFIXES` to `config.py` alongside `_DEFAULT_PLUGIN_PATHS`, with `plugin_suffix_for(fmt, platform)` and `plugin_path_looks_valid(path, fmt, platform)`. Serum 1 (VST2) expects `.vst` on macOS, `.dll` on Windows, `.so` on Linux; Serum 2 (VST3) expects `.vst3` everywhere. Validity is `exists()` plus a case-folded suffix match; an unknown platform enforces existence only.
+
+**Reason:** A user browsing for a plugin by hand can pick the folder above the bundle, or hand the Serum 2 row a Serum 1 `.vst` — and the Serum 1 VST3 in particular *silently mis-loads* `.fxp` presets rather than failing, which is the exact failure this check exists to catch before a 1500-preset batch runs. Putting the table next to `_DEFAULT_PLUGIN_PATHS` means the check and the default read the same platform knowledge and cannot drift apart, which is why this lives in serum-render rather than in the GUI that needs it.
+
+**Alternatives considered:** Implementing the check GUI-side — rejected because the two tables would then encode the same platform facts in two repos. Using `is_file()` — actively wrong: both plugin formats are *bundles* (directories) on macOS, so `is_file()` rejects every valid macOS plugin.

{serum_render-0.2.0 → serum_render-0.3.1}/docs/implementation.md

@@ -98,6 +98,20 @@ process (`discover.get_midi_duration`); workers never parse MIDI.
 4. `EngineHost.render` — one backstop RuntimeError for a format with no
    engine.
 
+## Machine-readable output
+
+`--json` (`cli.py`) turns stdout into an NDJSON event stream: `start`
+(with `schema`, `total`, `workers`), one `result` per job carrying the
+worker's result dict verbatim, then `done` with the totals and elapsed
+seconds. Every human-readable line moves to stderr, and the rich
+progress bar is suppressed outright — rich writes it to stdout and
+still prints one final renderable when stdout is not a tty.
+
+`--json` is tested before `--verbose` in the results loop: they are
+independent flags and the other order drops the stream when both are
+set. The per-result `peak` comes from `engine.run_job` and is carried,
+not acted on; nothing in the render path branches on it.
+
 ## Default plugin paths
 
 `config.default_plugin_path(fmt, platform=None)` returns the standard

{serum_render-0.2.0 → serum_render-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "serum-render"
-version = "0.2.0"
+version = "0.3.1"
 description = "Batch-render Serum 1 (.fxp) and Serum 2 (.SerumPreset) presets to audio files via DawDreamer."
 readme = "README.md"
 requires-python = ">=3.11,<3.13"

serum_render-0.3.1/serum_render/__main__.py

@@ -0,0 +1,11 @@
+"""`python -m serum_render` — same entry point as the `serum-render` script.
+
+Exists because the console script is not reliably locatable from a GUI:
+there is no useful PATH when an app is launched from Finder, and Windows
+venvs place it in `Scripts/` with a `.exe` suffix. On Windows that stub
+also spawns a child interpreter which can survive a kill
+(pypa/distlib#175); going through `-m` removes that process level.
+"""
+from .cli import app
+
+app()

{serum_render-0.2.0 → serum_render-0.3.1}/serum_render/cli.py

@@ -4,7 +4,10 @@ flags beat platform defaults), builds typed Jobs, and drives the pool.
 """
 from __future__ import annotations
 
+import itertools
+import json
 import logging
+import time
 from pathlib import Path
 from typing import Optional
 
@@ -41,6 +44,17 @@ _EXT_FOR = {PresetFormat.SERUM1: ".fxp", PresetFormat.SERUM2: ".SerumPreset"}
 _PLUGIN_NAME_FOR = {PresetFormat.SERUM1: "Serum 1", PresetFormat.SERUM2: "Serum 2"}
 
 
+# --json stream version. Bumped only on an incompatible shape change;
+# consumers should reject an unknown value rather than guess at it.
+_JSON_SCHEMA = 1
+
+
+def _emit(event: dict) -> None:
+    """Write one NDJSON event to stdout. Under --json, stdout carries
+    these and nothing else — every human-readable line goes to stderr."""
+    typer.echo(json.dumps(event))
+
+
 def _setup_logging(verbose: bool) -> None:
     """Only the CLI configures logging — library code uses a named logger."""
     logging.basicConfig(
@@ -75,11 +89,18 @@ def render(
     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} {subdir}. {subdir} nests output to mirror the preset tree.",
+        help="Filename template. Vars: {preset} {note} {velocity} {folder} {subpath} {subdir} {format}. {subdir} nests output to mirror the preset tree; {format} splits a mixed batch into serum1/ and serum2/ folders.",
     ),
     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."),
+    skip_missing_format: bool = typer.Option(
+        False, "--skip-missing-format",
+        help="Render the presets whose plugin is installed instead of refusing "
+             "the whole batch. Presets needing a missing plugin are reported "
+             "as skipped with reason 'no_plugin'. Still exits 2 if nothing is "
+             "renderable.",
+    ),
     deterministic: bool = typer.Option(
         False, "--deterministic",
         help="Render every preset in a fresh single-use process so batch "
@@ -89,6 +110,12 @@ def render(
     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."),
+    json_out: bool = typer.Option(
+        False, "--json",
+        help="Emit one JSON event per line on stdout (start, result per "
+             "preset, done) and move all human-readable output to stderr. "
+             "Output shape is unstable until 1.0.",
+    ),
 ) -> None:
     _setup_logging(verbose)
 
@@ -138,6 +165,18 @@ def render(
             f"No supported preset files (.fxp, .SerumPreset) found under {presets}",
             err=True,
         )
+        # Emit the full pair anyway. Exiting 0 with an empty stream is
+        # indistinguishable from a successful run to a consumer, and a
+        # mistyped preset directory is the likeliest way to land here.
+        if json_out:
+            _emit({
+                "event": "start", "schema": _JSON_SCHEMA, "total": 0,
+                "workers": resolve_worker_count(workers),
+            })
+            _emit({
+                "event": "done", "ok": 0, "skipped": 0, "failed": 0,
+                "elapsed": 0.0,
+            })
         raise typer.Exit(code=0)
 
     # Resolve plugin paths: an explicit flag always wins; otherwise fall
@@ -155,10 +194,15 @@ def render(
             if fallback is not None:
                 plugin_paths[preset_fmt] = fallback
                 typer.echo(
-                    f"Using default {_PLUGIN_NAME_FOR[preset_fmt]} plugin: {fallback}"
+                    f"Using default {_PLUGIN_NAME_FOR[preset_fmt]} plugin: {fallback}",
+                    err=True,
                 )
 
     missing = discovered_formats - set(plugin_paths)
+    # Presets dropped for want of a plugin. Reported as ordinary skipped
+    # results so `done`'s counts stay reconcilable, distinguished from
+    # skip-existing skips by `reason`.
+    skipped_results: list[dict] = []
     if missing:
         msgs = sorted(
             f"found {_EXT_FOR[m]} files but {_FLAG_FOR[m]} was not provided "
@@ -167,7 +211,27 @@ def render(
         )
         for m in msgs:
             typer.echo(m, err=True)
-        raise typer.Exit(code=2)
+        # Refusing the whole batch is the default on purpose: a typo'd plugin
+        # flag must fail loudly rather than quietly render half a library.
+        if not skip_missing_format:
+            raise typer.Exit(code=2)
+        renderable = [(p, f) for p, f in preset_files if f in plugin_paths]
+        if not renderable:
+            typer.echo(
+                "No discovered preset has an installed plugin; nothing to render.",
+                err=True,
+            )
+            raise typer.Exit(code=2)
+        skipped_results = [
+            {
+                "status": "skipped",
+                "path": str(p.resolve()),
+                "reason": "no_plugin",
+            }
+            for p, f in preset_files
+            if f not in plugin_paths
+        ]
+        preset_files = renderable
 
     # Single-file mode: presets_root=None so {subpath} collapses out.
     # Resolve when a directory so `relative_to` works against the absolute
@@ -191,8 +255,8 @@ def render(
 
     extension = ".npy" if fmt == "npy" else ".wav"
     stems = [
-        compose_filename(filename_template, p, presets_root, note, velocity)
-        for p, _ in preset_files
+        compose_filename(filename_template, p, presets_root, note, velocity, pfmt)
+        for p, pfmt in preset_files
     ]
     output_paths = resolve_output_paths(stems, output, extension)
     jobs = [
@@ -213,10 +277,20 @@ def render(
         for (p, preset_fmt), out in zip(preset_files, output_paths)
     ]
 
+    total = len(jobs) + len(skipped_results)
+
     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}")
+        if json_out:
+            # No separate "plan" event — a start with the total is the
+            # same information, and one fewer branch for a consumer.
+            _emit({
+                "event": "start", "schema": _JSON_SCHEMA, "total": total,
+                "workers": resolve_worker_count(workers),
+            })
+        else:
+            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)
@@ -233,6 +307,7 @@ def render(
     )
 
     results: list[dict] = []
+    t0 = time.monotonic()
     if deterministic:
         from .pool import iter_jobs_isolated
 
@@ -242,10 +317,29 @@ def render(
     else:
         result_iter = iter_jobs(jobs, n_workers, serum1_str, serum2_str, sample_rate)
 
+    # The dropped presets are already decided, so they lead the stream and a
+    # consumer sees one result per preset counted in `total`.
+    result_iter = itertools.chain(skipped_results, result_iter)
+
+    # --json is tested before --verbose: they are independent flags, and
+    # the other order would silently drop the stream when both are set.
     # 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…")
+    # the two don't fight for the terminal. Under --json the bar is
+    # suppressed outright: rich writes it to stdout, and when stdout is
+    # not a tty it still prints one final renderable that would corrupt
+    # the stream.
+    if json_out:
+        _emit({
+            "event": "start", "schema": _JSON_SCHEMA, "total": total,
+            "workers": n_workers,
+        })
+        for result in result_iter:
+            results.append(result)
+            _emit({"event": "result", **result})
+    elif verbose:
+        typer.echo(
+            f"Rendering {len(jobs)} preset(s) with {n_workers} workers…", err=True
+        )
         results = list(result_iter)
     else:
         with Progress(
@@ -258,7 +352,7 @@ def render(
             TimeRemainingColumn(),
         ) as progress:
             task_id = progress.add_task(
-                f"Rendering ({n_workers} workers)", total=len(jobs)
+                f"Rendering ({n_workers} workers)", total=total
             )
             for result in result_iter:
                 results.append(result)
@@ -268,7 +362,13 @@ def render(
     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.")
+    if json_out:
+        _emit({
+            "event": "done", "ok": ok, "skipped": skipped,
+            "failed": len(errors), "elapsed": round(time.monotonic() - t0, 3),
+        })
+    else:
+        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-0.3.1/serum_render/config.py

@@ -0,0 +1,227 @@
+"""Frozen render configuration. Stdlib-only at module level."""
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from .formats import PresetFormat, suffix_for
+
+# 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",
+    },
+}
+
+
+# Expected binary suffix per platform per format, derived from the same
+# knowledge as _DEFAULT_PLUGIN_PATHS above so a check and a default can never
+# disagree. Serum 1 is VST2 (a different extension on every platform); Serum 2
+# is VST3 everywhere. INVARIANT: never `.vst3` for SERUM1 — the Serum 1 VST3
+# silently mis-loads .fxp presets, which is the failure this table exists to
+# catch when a user browses by hand.
+_PLUGIN_SUFFIXES: dict[str, dict[PresetFormat, str]] = {
+    "darwin": {PresetFormat.SERUM1: ".vst", PresetFormat.SERUM2: ".vst3"},
+    "win32": {PresetFormat.SERUM1: ".dll", PresetFormat.SERUM2: ".vst3"},
+    "linux": {PresetFormat.SERUM1: ".so", PresetFormat.SERUM2: ".vst3"},
+}
+
+
+def plugin_suffix_for(fmt: PresetFormat, platform: str | None = None) -> str | None:
+    """Expected binary suffix for a format on a platform, or None if the
+    platform is unknown (in which case callers should not enforce a check)."""
+    platform = platform if platform is not None else sys.platform
+    table = _PLUGIN_SUFFIXES.get(platform)
+    return None if table is None else table[fmt]
+
+
+def plugin_path_looks_valid(
+    path: str | Path, fmt: PresetFormat, platform: str | None = None
+) -> bool:
+    """True when `path` exists and carries the suffix this format expects.
+
+    Existence is `exists()`, not `is_file()`: on macOS both plugin formats are
+    bundles — directories — so an is_file() check rejects every valid macOS
+    plugin. An unknown platform has no expectation to violate, so only
+    existence is checked there.
+    """
+    path = Path(path)
+    if not path.exists():
+        return False
+    suffix = plugin_suffix_for(fmt, platform)
+    return suffix is None or path.suffix.lower() == suffix
+
+
+# Where Serum keeps its factory presets when they have not been moved.
+# The macOS entries are verified against a real install (2026-09-01). The
+# Windows entries are NOT verified on a Windows machine — that is safe
+# here, because `default_preset_dir` only ever returns a directory that
+# exists and actually holds presets of that format, so a wrong guess
+# degrades to "not found" instead of to a wrong answer.
+_DEFAULT_PRESET_DIRS: dict[str, dict[PresetFormat, str]] = {
+    "darwin": {
+        PresetFormat.SERUM1: "/Library/Audio/Presets/Xfer Records/Serum Presets",
+        PresetFormat.SERUM2: "/Library/Audio/Presets/Xfer Records/Serum 2 Presets",
+    },
+    "win32": {
+        PresetFormat.SERUM1: "C:/ProgramData/Xfer/Serum Presets",
+        PresetFormat.SERUM2: "C:/ProgramData/Xfer/Serum 2 Presets",
+    },
+}
+
+# Serum records its own preset folder in these prefs files. Reading it
+# beats assuming the default, because the folder is relocatable from
+# inside the plugin. A blank or whitespace-only value means "unset" —
+# that is what Serum 1 writes when the folder has never been moved.
+# Windows paths unverified, same reasoning as above.
+_PREFS_PATHS: dict[str, dict[PresetFormat, str]] = {
+    "darwin": {
+        PresetFormat.SERUM1: "~/Library/Preferences/SerumPrefs.json",
+        PresetFormat.SERUM2: "~/Library/Preferences/Serum2Prefs.json",
+    },
+    "win32": {
+        PresetFormat.SERUM1: "~/AppData/Roaming/Xfer/Serum/SerumPrefs.json",
+        PresetFormat.SERUM2: "~/AppData/Roaming/Xfer/Serum2/Serum2Prefs.json",
+    },
+}
+_PREFS_PRESET_KEY = "Serum Presets Path"
+
+
+def _configured_preset_dir(fmt: PresetFormat, platform: str) -> Path | None:
+    """The preset folder Serum itself records, or None if it says nothing.
+
+    Never raises: an absent, unreadable or malformed prefs file is just
+    "no opinion", and the caller falls through to the standard location.
+    """
+    table = _PREFS_PATHS.get(platform)
+    if table is None:
+        return None
+    try:
+        data = json.loads(Path(table[fmt]).expanduser().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    value = data.get(_PREFS_PRESET_KEY) if isinstance(data, dict) else None
+    if not isinstance(value, str) or not value.strip():
+        return None
+    return Path(value.strip())
+
+
+def _holds_preset(directory: Path, suffix: str) -> bool:
+    """True as soon as one preset of that suffix turns up. Stops at the
+    first hit — the factory tree runs to thousands of files."""
+    try:
+        for path in directory.rglob("*"):
+            if path.suffix.lower() == suffix:
+                return True
+    except OSError:
+        return False
+    return False
+
+
+def default_preset_dir(
+    fmt: PresetFormat, platform: str | None = None
+) -> Path | None:
+    """Best guess at where this format's presets live, or None.
+
+    Prefers the folder Serum records in its own prefs over the standard
+    install location. Only returns a directory that exists AND contains
+    at least one preset of that format, so a stale prefs entry or a
+    wrong default reads as "not found" rather than as an empty batch.
+    """
+    platform = platform if platform is not None else sys.platform
+    candidates: list[Path] = []
+    configured = _configured_preset_dir(fmt, platform)
+    if configured is not None:
+        candidates.append(configured)
+    table = _DEFAULT_PRESET_DIRS.get(platform)
+    if table is not None:
+        candidates.append(Path(table[fmt]))
+
+    suffix = suffix_for(fmt).lower()
+    for candidate in candidates:
+        if candidate.is_dir() and _holds_preset(candidate, suffix):
+            return candidate
+    return None
+
+
+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]