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

{serum_render-0.2.0 → serum_render-0.3.0}/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.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: serum-render
-Version: 0.2.0
+Version: 0.3.0
 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
@@ -92,9 +92,38 @@ A directory containing both `.fxp` and `.SerumPreset` files renders as one mixed
 | `--skip-existing` | off | Skip presets whose output already exists. |
 | `--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":"..."}
+{"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.
+
+**The output shape is unstable until 1.0.**
+
 ## Library API
 
 ```python

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

@@ -64,9 +64,38 @@ A directory containing both `.fxp` and `.SerumPreset` files renders as one mixed
 | `--skip-existing` | off | Skip presets whose output already exists. |
 | `--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":"..."}
+{"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.
+
+**The output shape is unstable until 1.0.**
+
 ## Library API
 
 ```python

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

@@ -75,3 +75,17 @@ 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.

{serum_render-0.2.0 → serum_render-0.3.0}/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.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "serum-render"
-version = "0.2.0"
+version = "0.3.0"
 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.0/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.0}/serum_render/cli.py

@@ -4,7 +4,9 @@ flags beat platform defaults), builds typed Jobs, and drives the pool.
 """
 from __future__ import annotations
 
+import json
 import logging
+import time
 from pathlib import Path
 from typing import Optional
 
@@ -41,6 +43,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,7 +88,7 @@ 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."),
@@ -89,6 +102,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 +157,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,7 +186,8 @@ 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)
@@ -191,8 +223,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 = [
@@ -214,9 +246,17 @@ def render(
     ]
 
     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": len(jobs),
+                "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 +273,7 @@ def render(
     )
 
     results: list[dict] = []
+    t0 = time.monotonic()
     if deterministic:
         from .pool import iter_jobs_isolated
 
@@ -242,10 +283,25 @@ def render(
     else:
         result_iter = iter_jobs(jobs, n_workers, serum1_str, serum2_str, sample_rate)
 
+    # --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": len(jobs),
+            "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(
@@ -268,7 +324,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.2.0 → serum_render-0.3.0}/serum_render/config.py

@@ -1,11 +1,12 @@
 """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
+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
@@ -29,6 +30,98 @@ _DEFAULT_PLUGIN_PATHS: dict[str, dict[PresetFormat, str]] = {
 }
 
 
+# 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.
 

{serum_render-0.2.0 → serum_render-0.3.0}/serum_render/discover.py

@@ -75,6 +75,7 @@ def compose_filename(
     presets_root: Path | None,
     note: int,
     velocity: int,
+    fmt: PresetFormat | None = None,
 ) -> str:
     """
     Compose a filename stem by substituting template variables against a
@@ -85,6 +86,11 @@ def compose_filename(
     None in single-file mode; {subpath} resolves to "" and any adjacent
     separator is collapsed.
 
+    {format} is the preset's format ("serum1" / "serum2"), for splitting a
+    mixed batch into per-synth output folders. It renders empty when `fmt`
+    is not supplied, and an empty path component is dropped, so
+    "{format}/{preset}" degrades to "{preset}".
+
     {subdir} is {subpath}'s nested twin: the same path components, but
     sanitized individually and joined with "/" so the output directory
     mirrors the preset tree instead of flattening it. Components are
@@ -114,6 +120,7 @@ def compose_filename(
     result = result.replace("{folder}", folder)
     result = result.replace("{subpath}", subpath)
     result = result.replace("{subdir}", subdir)
+    result = result.replace("{format}", fmt.value if fmt is not None else "")
 
     # Collapse separators that an empty {subpath} would leave behind
     # (e.g. "{subpath}_{preset}" -> "_{preset}" -> "preset").

{serum_render-0.2.0 → serum_render-0.3.0}/serum_render/engine.py

@@ -205,6 +205,14 @@ def run_job(job: Job) -> dict:
             return {"status": "skipped", "path": job.preset_path}
 
         audio = _HOST.render(job)
+
+        import numpy as np
+
+        # Carried for consumers, not acted on here. The silence warning in
+        # EngineHost.render only fires below SILENCE_EPS, which is three
+        # orders of magnitude under the wrong-level renders documented in
+        # KNOWN_ISSUES.md — those are invisible without the raw number.
+        peak = float(np.max(np.abs(audio)))
         if job.output_path is not None:
             write_audio(
                 audio,
@@ -213,8 +221,13 @@ def run_job(job: Job) -> dict:
                 job.bit_depth,
                 job.output_format,
             )
-            return {"status": "ok", "path": job.preset_path}
-        return {"status": "ok", "path": job.preset_path, "audio": audio}
+            return {"status": "ok", "path": job.preset_path, "peak": peak}
+        return {
+            "status": "ok",
+            "path": job.preset_path,
+            "peak": peak,
+            "audio": audio,
+        }
     except Exception as exc:
         logger.warning("Failed to render %s: %s", job.preset_path, exc)
         return {"status": "error", "path": job.preset_path, "error": str(exc)}

{serum_render-0.2.0 → serum_render-0.3.0}/serum_render/formats.py

@@ -28,6 +28,18 @@ _FOLDED_SUFFIX_TO_FORMAT: dict[str, PresetFormat] = {
 }
 
 
+# Format -> canonical suffix. Derived from the one table above so the two
+# directions cannot drift apart.
+_FORMAT_TO_SUFFIX: dict[PresetFormat, str] = {
+    fmt: suffix for suffix, fmt in _SUFFIX_TO_FORMAT.items()
+}
+
+
+def suffix_for(fmt: PresetFormat) -> str:
+    """Canonical file suffix for a format (`.fxp` / `.SerumPreset`)."""
+    return _FORMAT_TO_SUFFIX[fmt]
+
+
 def format_or_none(path: Path) -> PresetFormat | None:
     """Resolve a path to its PresetFormat, or None if the suffix is not a
     supported one. The single place suffix matching happens, so directory

serum_render-0.3.0/serum_render/output.py

@@ -0,0 +1,54 @@
+"""Audio file writing. Part of the worker import graph — module level is
+stdlib-only; numpy/soundfile load inside the function, after dawdreamer
+has already been imported by EngineHost."""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+_SUBTYPE_MAP = {"16": "PCM_16", "24": "PCM_24", "32f": "FLOAT"}
+
+
+def write_audio(
+    audio, output_path: str, sample_rate: int, bit_depth: str, output_format: str
+) -> None:
+    """Write a (channels, samples) float32 array as wav (given bit depth)
+    or npy (raw float32, bit depth ignored).
+
+    Writes to a sibling temp file and renames it into place, so a killed
+    render can never leave a truncated file at `output_path` —
+    skip_existing would otherwise skip that garbage forever on the
+    re-run. A SIGKILL does leave a stray `.tmp` behind; that is the
+    intended trade.
+
+    The temp suffix goes *after* the real extension (`a.wav.tmp`, not
+    `a.tmp.wav`) so strays stay out of `*.wav` globs. Both writers are
+    told their format explicitly, because each otherwise infers it from
+    the trailing extension: np.save would write `a.npy.tmp.npy`, and
+    sf.write raises on an unrecognised one.
+    """
+    import numpy as np
+
+    if output_format not in ("wav", "npy"):
+        raise ValueError(f"Unknown output format: {output_format!r}")
+    subtype = None
+    if output_format == "wav":
+        subtype = _SUBTYPE_MAP.get(bit_depth)
+        if subtype is None:
+            raise ValueError(f"Unknown bit depth: {bit_depth!r}")
+
+    Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+    tmp = f"{output_path}.tmp"
+    try:
+        if output_format == "npy":
+            with open(tmp, "wb") as f:
+                np.save(f, audio)
+        else:
+            import soundfile as sf
+
+            # soundfile expects (samples, channels) — transpose before writing.
+            sf.write(tmp, audio.T, sample_rate, subtype=subtype, format="WAV")
+        os.replace(tmp, output_path)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise

{serum_render-0.2.0 → serum_render-0.3.0}/tests/test_cli.py

@@ -4,7 +4,9 @@ worker pool — they assert argument parsing, validation, error messaging,
 exit codes, default-plugin-path resolution, and the --dry-run path.
 
 Output is read via `result.output` (the merged stream) so the suite is
-portable across Click versions.
+portable across Click versions. The --json cases at the bottom are the
+exception: stdout hygiene is only observable in a real subprocess, so
+those shell out rather than using CliRunner.
 
 Default-path resolution is stubbed in most tests: this machine may have
 real Serum installs, and the CLI would otherwise silently pick them up
@@ -12,6 +14,9 @@ and proceed past the validation being tested.
 """
 from __future__ import annotations
 
+import json
+import subprocess
+import sys
 from pathlib import Path
 
 import mido
@@ -20,6 +25,8 @@ from typer.testing import CliRunner
 
 import serum_render.cli as cli
 from serum_render.cli import app
+from serum_render.config import default_plugin_path
+from serum_render.formats import PresetFormat
 
 runner = CliRunner()
 
@@ -426,3 +433,83 @@ def test_dry_run_with_relative_presets_dir_resolves_subpath(
     )
     assert result.exit_code == 0, result.output
     assert "Leads_lead.wav" in result.output
+
+
+# ---- --json event stream --------------------------------------------------
+#
+# Stdout hygiene is asserted in a real subprocess, not through CliRunner:
+# CliRunner patches sys.stdout in-process, so it cannot see writes that
+# reach the real fd 1 (loky workers, and rich's final Progress renderable).
+# The content assertions below use CliRunner and are stream-agnostic, so
+# they stay portable across Click/Typer versions the way the rest of this
+# module is.
+
+
+def _json_lines(text: str) -> list[dict]:
+    return [json.loads(line) for line in text.splitlines() if line.strip()]
+
+
+def test_json_dry_run_emits_one_start_event(fake_env, no_defaults):
+    plugin, presets, output = fake_env
+    result = runner.invoke(
+        app,
+        [str(presets), str(output), "--serum1", str(plugin), "--dry-run", "--json"],
+    )
+    assert result.exit_code == 0, result.output
+    events = _json_lines(result.stdout)
+    assert len(events) == 1
+    assert events[0]["event"] == "start"
+    assert events[0]["schema"] == 1
+    assert events[0]["total"] == 2  # fake_env plants two .fxp files
+
+
+def test_json_no_presets_still_emits_start_and_done(tmp_path, no_defaults):
+    """Exit 0 with an empty stream is indistinguishable from success, and a
+    mistyped preset directory is the likeliest way to reach this branch."""
+    plugin = tmp_path / "Serum.vst"
+    _touch(plugin)
+    empty = tmp_path / "empty"
+    empty.mkdir()
+    result = runner.invoke(
+        app, [str(empty), str(tmp_path / "out"), "--serum1", str(plugin), "--json"]
+    )
+    assert result.exit_code == 0
+    events = _json_lines(result.stdout)
+    assert [e["event"] for e in events] == ["start", "done"]
+    assert events[0]["total"] == 0
+    assert events[1] == {
+        "event": "done", "ok": 0, "skipped": 0, "failed": 0, "elapsed": 0.0,
+    }
+
+
+def _run_cli(args: list[str]) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [sys.executable, "-m", "serum_render", *args],
+        capture_output=True,
+        text=True,
+    )
+
+
+def test_json_stdout_is_pure_ndjson_in_a_real_process(fake_env):
+    """The assertion CliRunner cannot make: nothing else reaches fd 1."""
+    plugin, presets, output = fake_env
+    proc = _run_cli(
+        [str(presets), str(output), "--serum1", str(plugin), "--dry-run", "--json"]
+    )
+    assert proc.returncode == 0, proc.stderr
+    events = _json_lines(proc.stdout)
+    assert len(events) == 1 and events[0]["total"] == 2
+
+
+@pytest.mark.skipif(
+    default_plugin_path(PresetFormat.SERUM1) is None,
+    reason="No default Serum 1 install to trigger the fallback notice.",
+)
+def test_json_default_plugin_notice_goes_to_stderr(fake_env):
+    """The notice is diagnostic, so it must not land in the event stream."""
+    _plugin, presets, output = fake_env
+    proc = _run_cli([str(presets), str(output), "--dry-run", "--json"])
+    assert proc.returncode == 0, proc.stderr
+    assert "Using default" in proc.stderr
+    assert "Using default" not in proc.stdout
+    assert _json_lines(proc.stdout)  # still parses cleanly

{serum_render-0.2.0 → serum_render-0.3.0}/tests/test_config.py

@@ -1,10 +1,12 @@
 import dataclasses
+import json
 from pathlib import Path
 
 import pytest
 
+import serum_render.config as config
 from serum_render.config import RenderConfig, default_plugin_path
-from serum_render.formats import PresetFormat
+from serum_render.formats import PresetFormat, format_for_path, suffix_for
 
 
 def test_defaults_resolve():
@@ -163,3 +165,82 @@ def test_default_serum2_paths(monkeypatch):
 
 def test_default_path_none_on_unknown_platform():
     assert default_plugin_path(PresetFormat.SERUM1, platform="linux") is None
+
+
+# ---- preset directory detection -------------------------------------------
+
+
+def _preset_tree(root: Path, suffix: str, name: str = "Bass") -> Path:
+    """A directory that actually holds a preset of that format."""
+    root.mkdir(parents=True, exist_ok=True)
+    (root / "Sub").mkdir(exist_ok=True)
+    (root / "Sub" / f"{name}{suffix}").write_bytes(b"")
+    return root
+
+
+@pytest.fixture
+def preset_env(tmp_path, monkeypatch):
+    """Point both lookup tables at tmp_path for a fake 'testos' platform."""
+    prefs = tmp_path / "SerumPrefs.json"
+    fallback = tmp_path / "fallback"
+    monkeypatch.setattr(config, "_PREFS_PATHS", {"testos": {PresetFormat.SERUM1: str(prefs)}})
+    monkeypatch.setattr(config, "_DEFAULT_PRESET_DIRS", {"testos": {PresetFormat.SERUM1: str(fallback)}})
+    return prefs, fallback
+
+
+def test_preset_dir_prefers_the_folder_serum_records(preset_env, tmp_path):
+    """Serum's folder is relocatable from inside the plugin, so its own
+    prefs entry beats the standard install location."""
+    prefs, fallback = preset_env
+    _preset_tree(fallback, ".fxp")
+    moved = _preset_tree(tmp_path / "moved", ".fxp")
+    prefs.write_text(json.dumps({"Serum Presets Path": f"{moved} "}))
+    assert config.default_preset_dir(PresetFormat.SERUM1, "testos") == moved
+
+
+def test_blank_prefs_value_falls_back(preset_env):
+    """Serum 1 writes a single space when the folder was never moved."""
+    prefs, fallback = preset_env
+    _preset_tree(fallback, ".fxp")
+    prefs.write_text(json.dumps({"Serum Presets Path": " "}))
+    assert config.default_preset_dir(PresetFormat.SERUM1, "testos") == fallback
+
+
+def test_directory_without_matching_presets_is_not_a_hit(preset_env):
+    """A folder holding only the *other* format is a miss, not an empty batch."""
+    _prefs, fallback = preset_env
+    _preset_tree(fallback, ".SerumPreset")
+    assert config.default_preset_dir(PresetFormat.SERUM1, "testos") is None
+
+
+def test_uppercase_suffix_still_counts(preset_env):
+    _prefs, fallback = preset_env
+    _preset_tree(fallback, ".FXP")
+    assert config.default_preset_dir(PresetFormat.SERUM1, "testos") == fallback
+
+
+def test_malformed_prefs_falls_back_instead_of_raising(preset_env):
+    prefs, fallback = preset_env
+    _preset_tree(fallback, ".fxp")
+    prefs.write_text("{not json")
+    assert config.default_preset_dir(PresetFormat.SERUM1, "testos") == fallback
+
+
+def test_stale_prefs_path_falls_back(preset_env, tmp_path):
+    prefs, fallback = preset_env
+    _preset_tree(fallback, ".fxp")
+    prefs.write_text(json.dumps({"Serum Presets Path": str(tmp_path / "deleted")}))
+    assert config.default_preset_dir(PresetFormat.SERUM1, "testos") == fallback
+
+
+def test_nothing_found_returns_none(preset_env):
+    assert config.default_preset_dir(PresetFormat.SERUM1, "testos") is None
+
+
+def test_unknown_platform_returns_none(preset_env):
+    assert config.default_preset_dir(PresetFormat.SERUM1, "plan9") is None
+
+
+def test_suffix_for_round_trips_every_format():
+    for fmt in PresetFormat:
+        assert format_for_path(Path(f"x{suffix_for(fmt)}")) is fmt

{serum_render-0.2.0 → serum_render-0.3.0}/tests/test_engine.py

@@ -265,7 +265,12 @@ def test_run_job_writes_to_disk_and_returns_status_only(monkeypatch, tmp_path):
         output_path=str(out),
     )
     result = run_job(job)
-    assert result == {"status": "ok", "path": "/p.fxp"}
+    assert result["status"] == "ok"
+    assert result["path"] == "/p.fxp"
+    # The point of the disk path: no audio array crosses the process
+    # boundary. `peak` is the only extra, and it is a scalar.
+    assert "audio" not in result
+    assert result["peak"] == 0.0
     assert out.exists()
 
 

{serum_render-0.2.0 → serum_render-0.3.0}/tests/test_filename.py

@@ -1,6 +1,7 @@
 from pathlib import Path
 
 from serum_render.discover import compose_filename, resolve_output_paths
+from serum_render.formats import PresetFormat
 
 
 def test_compose_simple_preset(tmp_path: Path):
@@ -217,3 +218,30 @@ def test_compose_subpath_still_flattens(tmp_path: Path):
     assert compose_filename("{subpath}_{preset}", preset, tmp_path, 48, 127) == (
         "Bass_Hard_p"
     )
+
+
+# ---- {format}: splitting a mixed batch by synth ---------------------------
+
+
+def test_compose_format_token(tmp_path: Path):
+    preset = tmp_path / "Bass" / "Growl.fxp"
+    assert compose_filename(
+        "{format}/{preset}", preset, tmp_path, 48, 127, PresetFormat.SERUM1
+    ) == "serum1/Growl"
+    preset2 = tmp_path / "Pads" / "Air.SerumPreset"
+    assert compose_filename(
+        "{format}/{preset}", preset2, tmp_path, 48, 127, PresetFormat.SERUM2
+    ) == "serum2/Air"
+
+
+def test_compose_format_omitted_collapses(tmp_path: Path):
+    """Callers that don't pass a format still get a usable stem."""
+    preset = tmp_path / "Growl.fxp"
+    assert compose_filename("{format}/{preset}", preset, tmp_path, 48, 127) == "Growl"
+
+
+def test_compose_format_combines_with_subdir(tmp_path: Path):
+    preset = tmp_path / "Bass" / "Hard" / "Growl.fxp"
+    assert compose_filename(
+        "{format}/{subdir}/{preset}", preset, tmp_path, 48, 127, PresetFormat.SERUM2
+    ) == "serum2/Bass/Hard/Growl"

{serum_render-0.2.0 → serum_render-0.3.0}/tests/test_output.py

@@ -49,3 +49,35 @@ def test_unknown_bit_depth_raises(tmp_path: Path):
 def test_unknown_format_raises(tmp_path: Path):
     with pytest.raises(ValueError, match="format"):
         write_audio(_audio(), str(tmp_path / "a.flac"), 44100, "16", "flac")
+
+
+# ---- atomic write ---------------------------------------------------------
+#
+# write_audio renames a temp file into place so a killed render can never
+# leave a truncated file at the target — skip_existing would otherwise skip
+# that garbage forever on the re-run.
+
+
+@pytest.mark.parametrize("name,fmt", [("a.wav", "wav"), ("a.npy", "npy")])
+def test_no_temp_file_survives_a_successful_write(tmp_path: Path, name, fmt):
+    write_audio(_audio(), str(tmp_path / name), 44100, "16", fmt)
+    assert sorted(p.name for p in tmp_path.iterdir()) == [name]
+
+
+def test_temp_suffix_stays_out_of_extension_globs(tmp_path: Path):
+    """`a.wav.tmp`, never `a.tmp.wav` — a stray from a SIGKILL must not be
+    picked up by the `*.wav` globs callers use over the output directory."""
+    write_audio(_audio(), str(tmp_path / "a.wav"), 44100, "16", "wav")
+    assert [p.name for p in tmp_path.glob("*.wav")] == ["a.wav"]
+
+
+def test_failed_write_leaves_nothing_behind(tmp_path: Path, monkeypatch):
+    """The existing unknown-format/bit-depth cases raise *before* any write,
+    so the cleanup path needs a failure during one."""
+    def boom(*args, **kwargs):
+        raise RuntimeError("disk full")
+
+    monkeypatch.setattr(sf, "write", boom)
+    with pytest.raises(RuntimeError, match="disk full"):
+        write_audio(_audio(), str(tmp_path / "a.wav"), 44100, "16", "wav")
+    assert list(tmp_path.iterdir()) == []

serum_render-0.2.0/serum_render/output.py

@@ -1,33 +0,0 @@
-"""Audio file writing. Part of the worker import graph — module level is
-stdlib-only; numpy/soundfile load inside the function, after dawdreamer
-has already been imported by EngineHost."""
-from __future__ import annotations
-
-from pathlib import Path
-
-_SUBTYPE_MAP = {"16": "PCM_16", "24": "PCM_24", "32f": "FLOAT"}
-
-
-def write_audio(
-    audio, output_path: str, sample_rate: int, bit_depth: str, output_format: str
-) -> None:
-    """Write a (channels, samples) float32 array as wav (given bit depth)
-    or npy (raw float32, bit depth ignored)."""
-    import numpy as np
-
-    Path(output_path).parent.mkdir(parents=True, exist_ok=True)
-
-    if output_format == "npy":
-        np.save(output_path, audio)
-        return
-    if output_format != "wav":
-        raise ValueError(f"Unknown output format: {output_format!r}")
-
-    subtype = _SUBTYPE_MAP.get(bit_depth)
-    if subtype is None:
-        raise ValueError(f"Unknown bit depth: {bit_depth!r}")
-
-    import soundfile as sf
-
-    # soundfile expects (samples, channels) — transpose before writing.
-    sf.write(output_path, audio.T, sample_rate, subtype=subtype)