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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. {serum_render-0.3.0 → serum_render-0.4.0}/PKG-INFO +19 -5
  2. {serum_render-0.3.0 → serum_render-0.4.0}/README.md +16 -3
  3. {serum_render-0.3.0 → serum_render-0.4.0}/docs/decisions.md +54 -0
  4. {serum_render-0.3.0 → serum_render-0.4.0}/pyproject.toml +4 -2
  5. {serum_render-0.3.0 → serum_render-0.4.0}/serum_render/cli.py +74 -12
  6. {serum_render-0.3.0 → serum_render-0.4.0}/serum_render/config.py +38 -0
  7. {serum_render-0.3.0 → serum_render-0.4.0}/serum_render/discover.py +6 -3
  8. {serum_render-0.3.0 → serum_render-0.4.0}/serum_render/engine.py +13 -2
  9. serum_render-0.4.0/serum_render/output.py +87 -0
  10. {serum_render-0.3.0 → serum_render-0.4.0}/serum_render/pool.py +63 -9
  11. {serum_render-0.3.0 → serum_render-0.4.0}/tests/test_cli.py +125 -1
  12. {serum_render-0.3.0 → serum_render-0.4.0}/tests/test_config.py +57 -0
  13. {serum_render-0.3.0 → serum_render-0.4.0}/tests/test_engine.py +17 -1
  14. {serum_render-0.3.0 → serum_render-0.4.0}/tests/test_isolated.py +3 -1
  15. {serum_render-0.3.0 → serum_render-0.4.0}/tests/test_output.py +21 -1
  16. serum_render-0.4.0/tests/test_pool.py +67 -0
  17. {serum_render-0.3.0 → serum_render-0.4.0}/tests/test_sanitize.py +9 -3
  18. serum_render-0.3.0/serum_render/output.py +0 -54
  19. {serum_render-0.3.0 → serum_render-0.4.0}/.github/workflows/publish.yml +0 -0
  20. {serum_render-0.3.0 → serum_render-0.4.0}/.github/workflows/tests.yml +0 -0
  21. {serum_render-0.3.0 → serum_render-0.4.0}/.gitignore +0 -0
  22. {serum_render-0.3.0 → serum_render-0.4.0}/KNOWN_ISSUES.md +0 -0
  23. {serum_render-0.3.0 → serum_render-0.4.0}/LICENSE +0 -0
  24. {serum_render-0.3.0 → serum_render-0.4.0}/docs/determinism-probe-2026-07-16.json +0 -0
  25. {serum_render-0.3.0 → serum_render-0.4.0}/docs/implementation.md +0 -0
  26. {serum_render-0.3.0 → serum_render-0.4.0}/scripts/_verify_loky_worker.py +0 -0
  27. {serum_render-0.3.0 → serum_render-0.4.0}/scripts/probe_determinism.py +0 -0
  28. {serum_render-0.3.0 → serum_render-0.4.0}/scripts/verify_dawdreamer.py +0 -0
  29. {serum_render-0.3.0 → serum_render-0.4.0}/scripts/verify_dawdreamer_serum2.py +0 -0
  30. {serum_render-0.3.0 → serum_render-0.4.0}/serum_render/__init__.py +0 -0
  31. {serum_render-0.3.0 → serum_render-0.4.0}/serum_render/__main__.py +0 -0
  32. {serum_render-0.3.0 → serum_render-0.4.0}/serum_render/api.py +0 -0
  33. {serum_render-0.3.0 → serum_render-0.4.0}/serum_render/formats.py +0 -0
  34. {serum_render-0.3.0 → serum_render-0.4.0}/serum_render/isolated.py +0 -0
  35. {serum_render-0.3.0 → serum_render-0.4.0}/serum_render/jobs.py +0 -0
  36. {serum_render-0.3.0 → serum_render-0.4.0}/tests/conftest.py +0 -0
  37. {serum_render-0.3.0 → serum_render-0.4.0}/tests/test_api.py +0 -0
  38. {serum_render-0.3.0 → serum_render-0.4.0}/tests/test_filename.py +0 -0
  39. {serum_render-0.3.0 → serum_render-0.4.0}/tests/test_jobs.py +0 -0
  40. {serum_render-0.3.0 → serum_render-0.4.0}/tests/test_midi.py +0 -0
  41. {serum_render-0.3.0 → serum_render-0.4.0}/tests/test_presets.py +0 -0
  42. {serum_render-0.3.0 → serum_render-0.4.0}/tests/test_serum1_smoke.py +0 -0
  43. {serum_render-0.3.0 → serum_render-0.4.0}/tests/test_serum2_smoke.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: serum-render
3
- Version: 0.3.0
3
+ Version: 0.4.0
4
4
  Summary: Batch-render Serum 1 (.fxp) and Serum 2 (.SerumPreset) presets to audio files via DawDreamer.
5
5
  Project-URL: Homepage, https://github.com/wiillownet/serum-render
6
6
  Project-URL: Repository, https://github.com/wiillownet/serum-render
@@ -18,8 +18,9 @@ Requires-Dist: dawdreamer
18
18
  Requires-Dist: loky
19
19
  Requires-Dist: mido
20
20
  Requires-Dist: numpy
21
+ Requires-Dist: psutil
21
22
  Requires-Dist: rich
22
- Requires-Dist: serum2-preset-loader>=0.1.1
23
+ Requires-Dist: serum2-preset-loader>=0.1.3
23
24
  Requires-Dist: soundfile
24
25
  Requires-Dist: typer
25
26
  Provides-Extra: dev
@@ -84,12 +85,13 @@ A directory containing both `.fxp` and `.SerumPreset` files renders as one mixed
84
85
  | `--duration` | `1.0` | Note-on duration (s). |
85
86
  | `--tail` | `1.0` | Release silence after note-off (s). |
86
87
  | `--sample-rate` | `44100` | Output sample rate. |
87
- | `--bit-depth` | `16` | `16`, `24`, or `32f`. |
88
- | `--format` | `wav` | `wav` or `npy` (raw float32 stereo array). |
88
+ | `--bit-depth` | `16` | `16`, `24`, or `32f`. Applies to `wav` and `flac` (`flac` takes `16` or `24`). |
89
+ | `--format` | `wav` | `wav`, `flac`, `ogg` (Vorbis, fixed quality), or `npy` (raw float32 stereo array). |
89
90
  | `--filename-template` | `{preset}` | Vars: `{preset}` `{note}` `{velocity}` `{folder}` `{subpath}`. |
90
91
  | `--midi` | — | Render a `.mid` file instead of a single note. |
91
92
  | `--workers` | `-1` | Parallel workers; `-1` = `cpu_count - 1`. |
92
93
  | `--skip-existing` | off | Skip presets whose output already exists. |
94
+ | `--skip-missing-format` | off | Render what the installed plugins cover instead of refusing the whole batch. |
93
95
  | `--no-recurse` | off | Don't descend into subdirectories. |
94
96
  | `--dry-run` | off | Print the render plan and exit. |
95
97
  | `--json` | off | Emit machine-readable events on stdout (see below). |
@@ -105,7 +107,7 @@ program:
105
107
  ```
106
108
  {"event":"start","schema":1,"total":4271,"workers":7}
107
109
  {"event":"result","status":"ok","path":".../Bass 1.fxp","peak":0.3325}
108
- {"event":"result","status":"skipped","path":"..."}
110
+ {"event":"result","status":"skipped","path":"...","reason":"exists"}
109
111
  {"event":"result","status":"error","path":"...","error":"..."}
110
112
  {"event":"done","ok":4268,"skipped":0,"failed":3,"elapsed":612.4}
111
113
  ```
@@ -122,6 +124,18 @@ loky workers inherit the parent's stdout, so a plugin printing from C
122
124
  could in principle interleave with the stream — trust the counts in
123
125
  `done` over a local tally of `result` events.
124
126
 
127
+ If a worker process dies (a plugin crash, an out-of-memory kill), the
128
+ batch stops: `done` still arrives, with an additional `aborted` string
129
+ saying so, and the exit code is `1`. Re-run with `--skip-existing` to
130
+ resume.
131
+
132
+ A `skipped` result carries a `reason`: `exists` when `--skip-existing`
133
+ found the output already written, or `no_plugin` when
134
+ `--skip-missing-format` dropped a preset whose plugin is not installed.
135
+ Both are counted in `done`'s `skipped`, and both are inside `start`'s
136
+ `total` — `total` covers every preset the run reports on, not just the
137
+ ones it renders.
138
+
125
139
  **The output shape is unstable until 1.0.**
126
140
 
127
141
  ## Library API
@@ -56,12 +56,13 @@ A directory containing both `.fxp` and `.SerumPreset` files renders as one mixed
56
56
  | `--duration` | `1.0` | Note-on duration (s). |
57
57
  | `--tail` | `1.0` | Release silence after note-off (s). |
58
58
  | `--sample-rate` | `44100` | Output sample rate. |
59
- | `--bit-depth` | `16` | `16`, `24`, or `32f`. |
60
- | `--format` | `wav` | `wav` or `npy` (raw float32 stereo array). |
59
+ | `--bit-depth` | `16` | `16`, `24`, or `32f`. Applies to `wav` and `flac` (`flac` takes `16` or `24`). |
60
+ | `--format` | `wav` | `wav`, `flac`, `ogg` (Vorbis, fixed quality), or `npy` (raw float32 stereo array). |
61
61
  | `--filename-template` | `{preset}` | Vars: `{preset}` `{note}` `{velocity}` `{folder}` `{subpath}`. |
62
62
  | `--midi` | — | Render a `.mid` file instead of a single note. |
63
63
  | `--workers` | `-1` | Parallel workers; `-1` = `cpu_count - 1`. |
64
64
  | `--skip-existing` | off | Skip presets whose output already exists. |
65
+ | `--skip-missing-format` | off | Render what the installed plugins cover instead of refusing the whole batch. |
65
66
  | `--no-recurse` | off | Don't descend into subdirectories. |
66
67
  | `--dry-run` | off | Print the render plan and exit. |
67
68
  | `--json` | off | Emit machine-readable events on stdout (see below). |
@@ -77,7 +78,7 @@ program:
77
78
  ```
78
79
  {"event":"start","schema":1,"total":4271,"workers":7}
79
80
  {"event":"result","status":"ok","path":".../Bass 1.fxp","peak":0.3325}
80
- {"event":"result","status":"skipped","path":"..."}
81
+ {"event":"result","status":"skipped","path":"...","reason":"exists"}
81
82
  {"event":"result","status":"error","path":"...","error":"..."}
82
83
  {"event":"done","ok":4268,"skipped":0,"failed":3,"elapsed":612.4}
83
84
  ```
@@ -94,6 +95,18 @@ loky workers inherit the parent's stdout, so a plugin printing from C
94
95
  could in principle interleave with the stream — trust the counts in
95
96
  `done` over a local tally of `result` events.
96
97
 
98
+ If a worker process dies (a plugin crash, an out-of-memory kill), the
99
+ batch stops: `done` still arrives, with an additional `aborted` string
100
+ saying so, and the exit code is `1`. Re-run with `--skip-existing` to
101
+ resume.
102
+
103
+ A `skipped` result carries a `reason`: `exists` when `--skip-existing`
104
+ found the output already written, or `no_plugin` when
105
+ `--skip-missing-format` dropped a preset whose plugin is not installed.
106
+ Both are counted in `done`'s `skipped`, and both are inside `start`'s
107
+ `total` — `total` covers every preset the run reports on, not just the
108
+ ones it renders.
109
+
97
110
  **The output shape is unstable until 1.0.**
98
111
 
99
112
  ## Library API
@@ -89,3 +89,57 @@ Two reasons that were considered and are explicitly **not** why, recorded so the
89
89
  **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.
90
90
 
91
91
  **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.
92
+
93
+ ## [2026-09-05] Render what the installed plugins cover, behind a flag
94
+
95
+ **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.
96
+
97
+ **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.
98
+
99
+ **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.
100
+
101
+ **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.
102
+
103
+ ## [2026-09-05] Expected plugin suffix lives beside the default plugin paths
104
+
105
+ **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.
106
+
107
+ **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.
108
+
109
+ **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.
110
+
111
+ ## [2026-09-06] Semantic Versioning, and what counts as observable
112
+
113
+ **Decision:** Patch releases carry fixes and performance work with no observable change. Minor releases carry any new flag, output format, `--json` event, or changed default; before 1.0 a minor may also break. 1.0 freezes the `--json` shape and the flag set. Purely additive `--json` keys do not bump the schema number. The same policy applies to serum2-preset-loader.
114
+
115
+ **Reason:** The GUI pins `serum-render` by range and reads the `--json` stream; it needs to know from the version number alone whether a new release can change what it parses. Recorded so the question is not re-derived per release.
116
+
117
+ ## [2026-09-06] Output formats live in serum-render, not the GUI
118
+
119
+ **Decision:** `--format` gains `flac` (16/24-bit) and `ogg` (Vorbis at libsndfile's default quality, `OGG_COMPRESSION_LEVEL` in output.py, no flag). One table in output.py drives validation, the extension, and the writer. Not MP3, not Opus.
120
+
121
+ **Reason:** The CLI owns what lands on disk: `--skip-existing`, collision suffixes, atomic writes and reruns all key on the final filename. A GUI-side transcode from WAV would need marker files to keep the CLI's skip predicate honest. libsndfile 1.2.2 already writes both containers, so this costs no dependency.
122
+
123
+ **Alternatives considered:** Transcoding in serum-render-gui, rejected for the reason above. An OGG quality flag, deferred until someone asks; the constant is named so it can be exposed without a search.
124
+
125
+ ## [2026-09-06] Sample-based presets: spread them out, recycle the worker after
126
+
127
+ **Decision:** `pool.spread_big_presets` spaces presets over 16 MB evenly through the job list, and `psutil` is a dependency so loky recycles a worker whose memory grew more than 300 MB past its post-first-job baseline.
128
+
129
+ **Reason:** Converting a 160 MB sample-based `.SerumPreset` (the Splice "Serum 2 Essential Keys" pack) peaks at ~2.9 GB in the worker and leaves ~2.7 GB resident afterwards; CPython does not return the freed float heap to the OS. Those presets sort together by folder, so all seven workers converted one at the same time and a 16 GB machine went 8 GB into swap. Spreading limits how many convert at once; recycling keeps a worker that touched one from carrying 2.7 GB through the rest of a 4000-preset run. Measured on the full library before merging.
130
+
131
+ **Alternatives considered:** Converting in a short-lived subprocess per preset, which frees the heap but does nothing about seven concurrent conversions and adds ~0.1 s to every Serum 2 preset. A cross-process semaphore for big presets, which loky cannot hand to its workers without reaching into its spawn internals. Rewriting the loader to transform CBOR at the byte level without decoding, the only real fix for the transient peak, far larger than the problem.
132
+
133
+ ## [2026-09-06] A dead worker stops the batch once
134
+
135
+ **Decision:** `iter_jobs` raises `WorkerDied` on loky's `TerminatedWorkerError`; the CLI prints one ABORTED line, still emits the summary and the `done` event (with an additive `aborted` message), and exits 1.
136
+
137
+ **Reason:** loky flags the executor broken after one worker dies and fails every pending future with the same message. Before this, a plugin crash on one preset produced thousands of identical per-preset errors, no hint which preset was involved, and a `done` event whose `failed` count looked like a real result. Which preset was running cannot be recovered from loky, so the message says so and points at `--skip-existing`.
138
+
139
+ ## [2026-09-06] Filenames keep letters in any script
140
+
141
+ **Decision:** `sanitize` keeps `\w` plus `-` instead of `[A-Za-z0-9_-]`.
142
+
143
+ **Reason:** A CJK-only preset name sanitized to an empty stem and the render was written under its folder's name (`Folder.wav`, then `Folder_1.wav`). Modern filesystems take Unicode filenames; the ASCII restriction bought nothing.
144
+
145
+ **Alternatives considered:** A hash fallback for an empty `{preset}`, which keeps ASCII output but gives the file a name nobody can read back to the preset.
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "serum-render"
7
- version = "0.3.0"
7
+ version = "0.4.0"
8
8
  description = "Batch-render Serum 1 (.fxp) and Serum 2 (.SerumPreset) presets to audio files via DawDreamer."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11,<3.13"
@@ -23,9 +23,11 @@ dependencies = [
23
23
  "typer",
24
24
  "rich",
25
25
  "loky",
26
+ # loky recycles memory-bloated workers only when psutil is importable
27
+ "psutil",
26
28
  "mido",
27
29
  "numpy",
28
- "serum2-preset-loader>=0.1.1",
30
+ "serum2-preset-loader>=0.1.3",
29
31
  ]
30
32
 
31
33
  [project.urls]
@@ -4,6 +4,7 @@ flags beat platform defaults), builds typed Jobs, and drives the pool.
4
4
  """
5
5
  from __future__ import annotations
6
6
 
7
+ import itertools
7
8
  import json
8
9
  import logging
9
10
  import time
@@ -29,7 +30,8 @@ from .discover import (
29
30
  )
30
31
  from .formats import PresetFormat
31
32
  from .jobs import Job
32
- from .pool import iter_jobs, resolve_worker_count
33
+ from .output import FORMATS, check_bit_depth
34
+ from .pool import WorkerDied, iter_jobs, resolve_worker_count
33
35
 
34
36
  logger = logging.getLogger("serum_render")
35
37
 
@@ -85,7 +87,7 @@ def render(
85
87
  tail: float = typer.Option(1.0, min=0.0, help="Release silence in seconds (>= 0)."),
86
88
  sample_rate: int = typer.Option(44100, "--sample-rate", min=1, help="Output sample rate in Hz."),
87
89
  bit_depth: str = typer.Option("16", "--bit-depth", help="Output bit depth: 16, 24, or 32f."),
88
- fmt: str = typer.Option("wav", "--format", help="Output container: wav or npy."),
90
+ fmt: str = typer.Option("wav", "--format", help="Output format: wav, flac, ogg (Vorbis), or npy (raw float32 array). Bit depth applies to wav and flac; flac takes 16 or 24."),
89
91
  filename_template: str = typer.Option(
90
92
  "{preset}", "--filename-template",
91
93
  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.",
@@ -93,6 +95,13 @@ def render(
93
95
  midi: Optional[Path] = typer.Option(None, "--midi", help="Path to a .mid file (overrides --note)."),
94
96
  workers: int = typer.Option(-1, "--workers", help="Parallel workers. -1 = cpu_count - 1."),
95
97
  skip_existing: bool = typer.Option(False, "--skip-existing", help="Skip if output file already exists."),
98
+ skip_missing_format: bool = typer.Option(
99
+ False, "--skip-missing-format",
100
+ help="Render the presets whose plugin is installed instead of refusing "
101
+ "the whole batch. Presets needing a missing plugin are reported "
102
+ "as skipped with reason 'no_plugin'. Still exits 2 if nothing is "
103
+ "renderable.",
104
+ ),
96
105
  deterministic: bool = typer.Option(
97
106
  False, "--deterministic",
98
107
  help="Render every preset in a fresh single-use process so batch "
@@ -127,8 +136,14 @@ def render(
127
136
 
128
137
  if bit_depth not in ("16", "24", "32f"):
129
138
  raise typer.BadParameter(f"--bit-depth must be 16, 24, or 32f (got {bit_depth!r}).")
130
- if fmt not in ("wav", "npy"):
131
- raise typer.BadParameter(f"--format must be wav or npy (got {fmt!r}).")
139
+ if fmt not in FORMATS:
140
+ raise typer.BadParameter(
141
+ f"--format must be one of {', '.join(FORMATS)} (got {fmt!r})."
142
+ )
143
+ try:
144
+ check_bit_depth(fmt, bit_depth)
145
+ except ValueError as exc:
146
+ raise typer.BadParameter(str(exc)) from None
132
147
 
133
148
  # Path.exists() returns True for VST3 bundle directories on macOS and
134
149
  # for plain .vst3 / .dll / .vst files on Windows + macOS — both shapes
@@ -191,6 +206,10 @@ def render(
191
206
  )
192
207
 
193
208
  missing = discovered_formats - set(plugin_paths)
209
+ # Presets dropped for want of a plugin. Reported as ordinary skipped
210
+ # results so `done`'s counts stay reconcilable, distinguished from
211
+ # skip-existing skips by `reason`.
212
+ skipped_results: list[dict] = []
194
213
  if missing:
195
214
  msgs = sorted(
196
215
  f"found {_EXT_FOR[m]} files but {_FLAG_FOR[m]} was not provided "
@@ -199,7 +218,27 @@ def render(
199
218
  )
200
219
  for m in msgs:
201
220
  typer.echo(m, err=True)
202
- raise typer.Exit(code=2)
221
+ # Refusing the whole batch is the default on purpose: a typo'd plugin
222
+ # flag must fail loudly rather than quietly render half a library.
223
+ if not skip_missing_format:
224
+ raise typer.Exit(code=2)
225
+ renderable = [(p, f) for p, f in preset_files if f in plugin_paths]
226
+ if not renderable:
227
+ typer.echo(
228
+ "No discovered preset has an installed plugin; nothing to render.",
229
+ err=True,
230
+ )
231
+ raise typer.Exit(code=2)
232
+ skipped_results = [
233
+ {
234
+ "status": "skipped",
235
+ "path": str(p.resolve()),
236
+ "reason": "no_plugin",
237
+ }
238
+ for p, f in preset_files
239
+ if f not in plugin_paths
240
+ ]
241
+ preset_files = renderable
203
242
 
204
243
  # Single-file mode: presets_root=None so {subpath} collapses out.
205
244
  # Resolve when a directory so `relative_to` works against the absolute
@@ -221,7 +260,7 @@ def render(
221
260
  raise typer.Exit(code=2) from None
222
261
  midi_str = str(midi.resolve())
223
262
 
224
- extension = ".npy" if fmt == "npy" else ".wav"
263
+ extension = FORMATS[fmt].extension
225
264
  stems = [
226
265
  compose_filename(filename_template, p, presets_root, note, velocity, pfmt)
227
266
  for p, pfmt in preset_files
@@ -245,12 +284,14 @@ def render(
245
284
  for (p, preset_fmt), out in zip(preset_files, output_paths)
246
285
  ]
247
286
 
287
+ total = len(jobs) + len(skipped_results)
288
+
248
289
  if dry_run:
249
290
  if json_out:
250
291
  # No separate "plan" event — a start with the total is the
251
292
  # same information, and one fewer branch for a consumer.
252
293
  _emit({
253
- "event": "start", "schema": _JSON_SCHEMA, "total": len(jobs),
294
+ "event": "start", "schema": _JSON_SCHEMA, "total": total,
254
295
  "workers": resolve_worker_count(workers),
255
296
  })
256
297
  else:
@@ -283,6 +324,22 @@ def render(
283
324
  else:
284
325
  result_iter = iter_jobs(jobs, n_workers, serum1_str, serum2_str, sample_rate)
285
326
 
327
+ # The dropped presets are already decided, so they lead the stream and a
328
+ # consumer sees one result per preset counted in `total`.
329
+ result_iter = itertools.chain(skipped_results, result_iter)
330
+
331
+ # A dead worker ends the batch, but the summary (and the `done` event a
332
+ # --json consumer is waiting on) still goes out with the counts so far.
333
+ aborted: list[str] = []
334
+
335
+ def _until_worker_dies(it):
336
+ try:
337
+ yield from it
338
+ except WorkerDied as exc:
339
+ aborted.append(str(exc))
340
+
341
+ result_iter = _until_worker_dies(result_iter)
342
+
286
343
  # --json is tested before --verbose: they are independent flags, and
287
344
  # the other order would silently drop the stream when both are set.
288
345
  # In verbose mode, per-preset DEBUG logs replace the progress bar so
@@ -292,7 +349,7 @@ def render(
292
349
  # the stream.
293
350
  if json_out:
294
351
  _emit({
295
- "event": "start", "schema": _JSON_SCHEMA, "total": len(jobs),
352
+ "event": "start", "schema": _JSON_SCHEMA, "total": total,
296
353
  "workers": n_workers,
297
354
  })
298
355
  for result in result_iter:
@@ -314,7 +371,7 @@ def render(
314
371
  TimeRemainingColumn(),
315
372
  ) as progress:
316
373
  task_id = progress.add_task(
317
- f"Rendering ({n_workers} workers)", total=len(jobs)
374
+ f"Rendering ({n_workers} workers)", total=total
318
375
  )
319
376
  for result in result_iter:
320
377
  results.append(result)
@@ -325,12 +382,17 @@ def render(
325
382
  errors = [r for r in results if r["status"] == "error"]
326
383
 
327
384
  if json_out:
328
- _emit({
385
+ done = {
329
386
  "event": "done", "ok": ok, "skipped": skipped,
330
387
  "failed": len(errors), "elapsed": round(time.monotonic() - t0, 3),
331
- })
388
+ }
389
+ if aborted:
390
+ done["aborted"] = aborted[0]
391
+ _emit(done)
332
392
  else:
333
393
  typer.echo(f"Done: {ok} rendered, {skipped} skipped, {len(errors)} failed.")
334
394
  for r in errors:
335
395
  typer.echo(f" FAIL {r.get('path')}: {r.get('error')}", err=True)
336
- raise typer.Exit(code=1 if errors else 0)
396
+ if aborted:
397
+ typer.echo(f"ABORTED: {aborted[0]}", err=True)
398
+ raise typer.Exit(code=1 if errors or aborted else 0)
@@ -30,6 +30,44 @@ _DEFAULT_PLUGIN_PATHS: dict[str, dict[PresetFormat, str]] = {
30
30
  }
31
31
 
32
32
 
33
+ # Expected binary suffix per platform per format, derived from the same
34
+ # knowledge as _DEFAULT_PLUGIN_PATHS above so a check and a default can never
35
+ # disagree. Serum 1 is VST2 (a different extension on every platform); Serum 2
36
+ # is VST3 everywhere. INVARIANT: never `.vst3` for SERUM1 — the Serum 1 VST3
37
+ # silently mis-loads .fxp presets, which is the failure this table exists to
38
+ # catch when a user browses by hand.
39
+ _PLUGIN_SUFFIXES: dict[str, dict[PresetFormat, str]] = {
40
+ "darwin": {PresetFormat.SERUM1: ".vst", PresetFormat.SERUM2: ".vst3"},
41
+ "win32": {PresetFormat.SERUM1: ".dll", PresetFormat.SERUM2: ".vst3"},
42
+ "linux": {PresetFormat.SERUM1: ".so", PresetFormat.SERUM2: ".vst3"},
43
+ }
44
+
45
+
46
+ def plugin_suffix_for(fmt: PresetFormat, platform: str | None = None) -> str | None:
47
+ """Expected binary suffix for a format on a platform, or None if the
48
+ platform is unknown (in which case callers should not enforce a check)."""
49
+ platform = platform if platform is not None else sys.platform
50
+ table = _PLUGIN_SUFFIXES.get(platform)
51
+ return None if table is None else table[fmt]
52
+
53
+
54
+ def plugin_path_looks_valid(
55
+ path: str | Path, fmt: PresetFormat, platform: str | None = None
56
+ ) -> bool:
57
+ """True when `path` exists and carries the suffix this format expects.
58
+
59
+ Existence is `exists()`, not `is_file()`: on macOS both plugin formats are
60
+ bundles — directories — so an is_file() check rejects every valid macOS
61
+ plugin. An unknown platform has no expectation to violate, so only
62
+ existence is checked there.
63
+ """
64
+ path = Path(path)
65
+ if not path.exists():
66
+ return False
67
+ suffix = plugin_suffix_for(fmt, platform)
68
+ return suffix is None or path.suffix.lower() == suffix
69
+
70
+
33
71
  # Where Serum keeps its factory presets when they have not been moved.
34
72
  # The macOS entries are verified against a real install (2026-09-01). The
35
73
  # Windows entries are NOT verified on a Windows machine — that is safe
@@ -9,7 +9,10 @@ import mido
9
9
 
10
10
  from .formats import PresetFormat, format_for_path, format_or_none
11
11
 
12
- _SANITIZE_RE = re.compile(r"[^A-Za-z0-9_-]")
12
+ # \w keeps letters and digits in any script: an ASCII-only class turned a
13
+ # CJK preset name into an empty stem, and the file was named after its
14
+ # folder instead.
15
+ _SANITIZE_RE = re.compile(r"[^\w-]")
13
16
  _UNDERSCORE_RUN_RE = re.compile(r"_+")
14
17
 
15
18
  # Stem truncation cap: leaves 4 chars of headroom for collision suffixes
@@ -59,8 +62,8 @@ def discover_presets(
59
62
  def sanitize(value: str) -> str:
60
63
  """
61
64
  Sanitize a single template-variable value for use in a filename.
62
- Keeps [A-Za-z0-9_-]; everything else (spaces, brackets, punctuation,
63
- unicode) becomes '_'. Runs of underscores collapse to one, and leading
65
+ Keeps word characters in any script plus '-'; everything else (spaces,
66
+ brackets, punctuation, symbols) becomes '_'. Runs of underscores collapse to one, and leading
64
67
  and trailing underscores are stripped.
65
68
  """
66
69
  value = value.strip()
@@ -11,6 +11,7 @@ serum2_preset_loader load inside EngineHost, in that order.
11
11
  from __future__ import annotations
12
12
 
13
13
  import logging
14
+ import os
14
15
  import tempfile
15
16
  import threading
16
17
  from dataclasses import dataclass
@@ -166,6 +167,9 @@ class EngineHost:
166
167
  # and reused for every job.
167
168
 
168
169
  _HOST: EngineHost | None = None
170
+ # loky workers have no parent-liveness check of their own: a killed CLI
171
+ # leaves them draining the queue, then idling out. Set by init_worker.
172
+ _PARENT_PID: int | None = None
169
173
 
170
174
 
171
175
  def init_worker(
@@ -174,7 +178,8 @@ def init_worker(
174
178
  sample_rate: int,
175
179
  ) -> None:
176
180
  """loky initializer — builds the per-process EngineHost."""
177
- global _HOST
181
+ global _HOST, _PARENT_PID
182
+ _PARENT_PID = os.getppid()
178
183
  _HOST = EngineHost(serum1_plugin_path, serum2_plugin_path, sample_rate)
179
184
  logger.debug(
180
185
  "Worker initialized (serum1=%s, serum2=%s)",
@@ -194,6 +199,8 @@ def run_job(job: Job) -> dict:
194
199
  Per-job errors become {"status": "error", ...} so one bad preset
195
200
  doesn't kill the batch.
196
201
  """
202
+ if _PARENT_PID is not None and os.getppid() != _PARENT_PID:
203
+ os._exit(0) # parent is gone; nobody will read the result
197
204
  try:
198
205
  if _HOST is None:
199
206
  raise RuntimeError("run_job called before init_worker")
@@ -202,7 +209,11 @@ def run_job(job: Job) -> dict:
202
209
  and job.skip_existing
203
210
  and Path(job.output_path).exists()
204
211
  ):
205
- return {"status": "skipped", "path": job.preset_path}
212
+ return {
213
+ "status": "skipped",
214
+ "path": job.preset_path,
215
+ "reason": "exists",
216
+ }
206
217
 
207
218
  audio = _HOST.render(job)
208
219
 
@@ -0,0 +1,87 @@
1
+ """Audio file writing. Part of the worker import graph — module level is
2
+ stdlib-only; numpy/soundfile load inside the function, after dawdreamer
3
+ has already been imported by EngineHost."""
4
+ from __future__ import annotations
5
+
6
+ import os
7
+ from pathlib import Path
8
+ from typing import NamedTuple
9
+
10
+
11
+ class Format(NamedTuple):
12
+ extension: str
13
+ sf_format: str | None # soundfile/libsndfile container; None = numpy
14
+ # bit depth -> libsndfile subtype; None = bit depth ignored
15
+ subtypes: dict[str, str] | None
16
+
17
+
18
+ # libsndfile's compression_level for Vorbis: 0.0 = largest/best, 1.0 =
19
+ # smallest. 0.6 is libsndfile's own default (Vorbis quality 0.4, ~128 kbps
20
+ # stereo). Named here so a --ogg-quality flag can expose it later.
21
+ OGG_COMPRESSION_LEVEL = 0.6
22
+
23
+ # The one table every output-format decision reads: --format validation,
24
+ # extension derivation, and the writer. libsndfile 1.2.2 covers all three
25
+ # audio containers; no extra dependency.
26
+ FORMATS: dict[str, Format] = {
27
+ "wav": Format(".wav", "WAV", {"16": "PCM_16", "24": "PCM_24", "32f": "FLOAT"}),
28
+ "flac": Format(".flac", "FLAC", {"16": "PCM_16", "24": "PCM_24"}),
29
+ # Vorbis at libsndfile's default quality; lossy, so bit depth is moot.
30
+ "ogg": Format(".ogg", "OGG", None),
31
+ "npy": Format(".npy", None, None),
32
+ }
33
+
34
+
35
+ def check_bit_depth(output_format: str, bit_depth: str) -> None:
36
+ """Raise ValueError if `bit_depth` is not writable in `output_format`."""
37
+ fmt = FORMATS[output_format]
38
+ if fmt.subtypes is not None and bit_depth not in fmt.subtypes:
39
+ raise ValueError(
40
+ f"{output_format} cannot be written at bit depth {bit_depth!r}; "
41
+ f"choose one of {', '.join(fmt.subtypes)}"
42
+ )
43
+
44
+
45
+ def write_audio(
46
+ audio, output_path: str, sample_rate: int, bit_depth: str, output_format: str
47
+ ) -> None:
48
+ """Write a (channels, samples) float32 array in `output_format` (see
49
+ FORMATS): wav/flac at the given bit depth, ogg (Vorbis) and npy (raw
50
+ float32) with bit depth ignored.
51
+
52
+ Writes to a sibling temp file and renames it into place, so a killed
53
+ render can never leave a truncated file at `output_path` —
54
+ skip_existing would otherwise skip that garbage forever on the
55
+ re-run. A SIGKILL does leave a stray `.tmp` behind; that is the
56
+ intended trade.
57
+
58
+ The temp suffix goes *after* the real extension (`a.wav.tmp`, not
59
+ `a.tmp.wav`) so strays stay out of `*.wav` globs. Both writers are
60
+ told their format explicitly, because each otherwise infers it from
61
+ the trailing extension: np.save would write `a.npy.tmp.npy`, and
62
+ sf.write raises on an unrecognised one.
63
+ """
64
+ import numpy as np
65
+
66
+ if output_format not in FORMATS:
67
+ raise ValueError(f"Unknown output format: {output_format!r}")
68
+ check_bit_depth(output_format, bit_depth)
69
+ fmt = FORMATS[output_format]
70
+
71
+ Path(output_path).parent.mkdir(parents=True, exist_ok=True)
72
+ tmp = f"{output_path}.tmp"
73
+ try:
74
+ if fmt.sf_format is None:
75
+ with open(tmp, "wb") as f:
76
+ np.save(f, audio)
77
+ else:
78
+ import soundfile as sf
79
+
80
+ subtype = fmt.subtypes[bit_depth] if fmt.subtypes else None
81
+ extra = {"compression_level": OGG_COMPRESSION_LEVEL} if output_format == "ogg" else {}
82
+ # soundfile expects (samples, channels) — transpose before writing.
83
+ sf.write(tmp, audio.T, sample_rate, subtype=subtype, format=fmt.sf_format, **extra)
84
+ os.replace(tmp, output_path)
85
+ except BaseException:
86
+ Path(tmp).unlink(missing_ok=True)
87
+ raise
@@ -9,6 +9,7 @@ from pathlib import Path
9
9
  from typing import Iterator
10
10
 
11
11
  from loky import get_reusable_executor
12
+ from loky.process_executor import TerminatedWorkerError
12
13
 
13
14
  from .engine import init_worker, run_job
14
15
  from .jobs import Job
@@ -16,6 +17,13 @@ from .jobs import Job
16
17
  logger = logging.getLogger("serum_render")
17
18
 
18
19
 
20
+ class WorkerDied(RuntimeError):
21
+ """A worker process was killed mid-batch (plugin crash, OOM kill). loky
22
+ flags the executor broken and fails every pending future with the same
23
+ message, so the batch stops here instead of reporting thousands of
24
+ identical errors."""
25
+
26
+
19
27
  def resolve_worker_count(workers: int) -> int:
20
28
  """-1 -> cpu_count - 1 (floor 1); otherwise max(1, workers)."""
21
29
  if workers == -1:
@@ -23,6 +31,38 @@ def resolve_worker_count(workers: int) -> int:
23
31
  return max(1, workers)
24
32
 
25
33
 
34
+ # Sample-based Serum 2 presets (Splice packs ship 90-160 MB files) cost
35
+ # ~3 GB of transient memory each to convert. They sort together by folder,
36
+ # so every worker hit one at once and 7 x 3 GB swapped a 16 GB machine.
37
+ _BIG_PRESET_BYTES = 16 * 2**20
38
+
39
+
40
+ def spread_big_presets(jobs: list[Job]) -> list[Job]:
41
+ """Return `jobs` with presets over _BIG_PRESET_BYTES spaced evenly
42
+ through the list, so the pool converts roughly one at a time.
43
+ Everything else keeps its order. Files that cannot be stat'ed count
44
+ as small; the worker reports them.
45
+
46
+ ponytail: order heuristic, not a limit. A hard cap needs a
47
+ cross-process semaphore loky cannot hand to workers.
48
+ """
49
+ big, small = [], []
50
+ for job in jobs:
51
+ try:
52
+ is_big = os.path.getsize(job.preset_path) > _BIG_PRESET_BYTES
53
+ except OSError:
54
+ is_big = False
55
+ (big if is_big else small).append(job)
56
+ if not big or not small:
57
+ return jobs
58
+ out: list[Job] = []
59
+ step = len(small) / len(big)
60
+ for i, b in enumerate(big):
61
+ out.extend(small[round(i * step):round((i + 1) * step)])
62
+ out.append(b)
63
+ return out
64
+
65
+
26
66
  def iter_jobs(
27
67
  jobs: list[Job],
28
68
  workers: int,
@@ -34,25 +74,39 @@ def iter_jobs(
34
74
  Submit every job to the reusable pool and yield result dicts as they
35
75
  complete (unordered — driven by whichever worker finishes first).
36
76
 
37
- The 30-minute idle timeout keeps workers warm for long-running
38
- embedders; the executor is a process-wide singleton owned by loky.
77
+ The 5-minute idle timeout keeps workers warm between batches; the
78
+ executor is a process-wide singleton owned by loky. (loky has no
79
+ per-job timeout, and workers only notice a dead parent when they pick
80
+ up their next job, so this is also how long orphans linger.)
81
+
82
+ With psutil installed (a dependency), loky recycles a worker whose
83
+ memory grew more than 300 MB past its post-first-job baseline. A
84
+ worker that converted one 160 MB sample-based preset holds ~2.7 GB
85
+ for life otherwise, and seven of them exceed this machine's RAM.
39
86
 
40
87
  If a worker process crashes, loky permanently flags the executor
41
- broken — every remaining future raises and is surfaced here as an
42
- error result. Re-running with skip_existing=True is idempotent for
43
- the jobs that already landed on disk.
88
+ broken and every remaining future raises: that surfaces once, as
89
+ WorkerDied. Re-running with skip_existing=True is idempotent for the
90
+ jobs that already landed on disk.
44
91
  """
45
92
  executor = get_reusable_executor(
46
93
  max_workers=resolve_worker_count(workers),
47
94
  initializer=init_worker,
48
95
  initargs=(serum1_plugin_path, serum2_plugin_path, sample_rate),
49
- timeout=1800,
96
+ timeout=300,
50
97
  )
51
- futures = {executor.submit(run_job, job): job for job in jobs}
98
+ futures = {executor.submit(run_job, job): job for job in spread_big_presets(jobs)}
52
99
  for future in as_completed(futures):
53
100
  job = futures[future]
54
101
  try:
55
102
  yield future.result()
103
+ except TerminatedWorkerError as exc:
104
+ pending = sum(1 for f in futures if not f.done())
105
+ raise WorkerDied(
106
+ "A worker process died (plugin crash or out of memory); "
107
+ f"{pending} preset(s) left unrendered. Re-run with "
108
+ f"--skip-existing to resume. ({exc})"
109
+ ) from exc
56
110
  except Exception as exc:
57
111
  logger.error("Worker error for %s: %s", job.preset_path, exc)
58
112
  yield {"status": "error", "path": job.preset_path, "error": str(exc)}
@@ -77,7 +131,7 @@ def render_isolated(
77
131
  and job.skip_existing
78
132
  and Path(job.output_path).exists()
79
133
  ):
80
- return {"status": "skipped", "path": job.preset_path}
134
+ return {"status": "skipped", "path": job.preset_path, "reason": "exists"}
81
135
 
82
136
  import json
83
137
  import subprocess
@@ -153,7 +207,7 @@ def iter_jobs_isolated(
153
207
  sample_rate,
154
208
  keep_audio,
155
209
  )
156
- for job in jobs
210
+ for job in spread_big_presets(jobs)
157
211
  ]
158
212
  for future in as_completed(futures):
159
213
  yield future.result()
@@ -93,7 +93,48 @@ def test_bad_format(fake_env, no_defaults):
93
93
  app, [str(presets), str(output), "--serum1", str(plugin), "--format", "mp3"]
94
94
  )
95
95
  assert result.exit_code != 0
96
- assert "must be wav or npy" in result.output
96
+ assert "must be one of wav, flac, ogg, npy" in result.output
97
+
98
+
99
+ def test_flac_rejects_32f(fake_env, no_defaults):
100
+ plugin, presets, output = fake_env
101
+ result = runner.invoke(
102
+ app, [str(presets), str(output), "--serum1", str(plugin),
103
+ "--format", "flac", "--bit-depth", "32f"]
104
+ )
105
+ assert result.exit_code != 0
106
+ assert "flac cannot be written at bit depth '32f'" in result.output
107
+
108
+
109
+ @pytest.mark.parametrize("fmt,ext", [("flac", ".flac"), ("ogg", ".ogg"), ("npy", ".npy")])
110
+ def test_format_sets_extension(fake_env, no_defaults, fmt, ext):
111
+ plugin, presets, output = fake_env
112
+ result = runner.invoke(
113
+ app, [str(presets), str(output), "--serum1", str(plugin),
114
+ "--format", fmt, "--dry-run"]
115
+ )
116
+ assert result.exit_code == 0
117
+ assert f"lead{ext}" in result.output
118
+
119
+
120
+ def test_worker_death_aborts_with_summary(fake_env, no_defaults, monkeypatch):
121
+ from serum_render.pool import WorkerDied
122
+
123
+ def dying_iter_jobs(jobs, *a, **k):
124
+ yield {"status": "ok", "path": jobs[0].preset_path, "peak": 0.5}
125
+ raise WorkerDied("A worker process died; 1 preset(s) left unrendered.")
126
+
127
+ monkeypatch.setattr(cli, "iter_jobs", dying_iter_jobs)
128
+ plugin, presets, output = fake_env
129
+ result = runner.invoke(
130
+ app, [str(presets), str(output), "--serum1", str(plugin), "--json"]
131
+ )
132
+ assert result.exit_code == 1
133
+ events = _json_lines(result.stdout)
134
+ assert events[-1]["event"] == "done"
135
+ assert events[-1]["ok"] == 1
136
+ assert "worker process died" in events[-1]["aborted"]
137
+ assert "ABORTED" in result.output
97
138
 
98
139
 
99
140
  def test_duration_zero_rejected(fake_env, no_defaults):
@@ -513,3 +554,86 @@ def test_json_default_plugin_notice_goes_to_stderr(fake_env):
513
554
  assert "Using default" in proc.stderr
514
555
  assert "Using default" not in proc.stdout
515
556
  assert _json_lines(proc.stdout) # still parses cleanly
557
+
558
+
559
+ # ---- --skip-missing-format ------------------------------------------------
560
+ #
561
+ # The common single-synth install: a library holding both formats with only
562
+ # one plugin present. Without the flag cli.py refuses the whole batch, which
563
+ # makes such a library entirely unrenderable.
564
+
565
+
566
+ @pytest.fixture
567
+ def mixed_env(tmp_path: Path):
568
+ """A Serum 1 plugin plus a library holding one preset of each format."""
569
+ plugin = tmp_path / "Serum.vst"
570
+ _touch(plugin)
571
+ presets = tmp_path / "presets"
572
+ _touch(presets / "one.fxp")
573
+ _touch(presets / "two.SerumPreset")
574
+ return plugin, presets, tmp_path / "out"
575
+
576
+
577
+ def test_mixed_library_without_the_flag_refuses_the_whole_batch(mixed_env, no_defaults):
578
+ """Default behaviour is unchanged: a missing plugin fails loudly rather
579
+ than quietly rendering half a library."""
580
+ plugin, presets, output = mixed_env
581
+ result = runner.invoke(app, [str(presets), str(output), "--serum1", str(plugin)])
582
+ assert result.exit_code == 2
583
+ assert "--serum2" in result.output
584
+
585
+
586
+ def test_skip_missing_format_counts_dropped_presets_in_total(mixed_env, no_defaults):
587
+ """`total` covers every preset the run reports on, matching how
588
+ skip-existing skips are already counted inside it."""
589
+ plugin, presets, output = mixed_env
590
+ result = runner.invoke(
591
+ app,
592
+ [str(presets), str(output), "--serum1", str(plugin),
593
+ "--skip-missing-format", "--dry-run", "--json"],
594
+ )
595
+ assert result.exit_code == 0, result.output
596
+ events = _json_lines(result.stdout)
597
+ assert len(events) == 1
598
+ assert events[0]["total"] == 2 # one renderable, one dropped
599
+
600
+
601
+ def test_skip_missing_format_reports_dropped_presets_as_skipped(
602
+ mixed_env, no_defaults, monkeypatch
603
+ ):
604
+ """The dropped presets arrive as ordinary skipped results carrying a
605
+ reason, so a consumer can tell them from skip-existing skips without a
606
+ new status value — and `done`'s counts still reconcile."""
607
+ plugin, presets, output = mixed_env
608
+ # No plugin to render the .fxp with, so stand in for the pool.
609
+ monkeypatch.setattr(cli, "iter_jobs", lambda *a, **k: iter([]))
610
+ result = runner.invoke(
611
+ app,
612
+ [str(presets), str(output), "--serum1", str(plugin),
613
+ "--skip-missing-format", "--json"],
614
+ )
615
+ assert result.exit_code == 0, result.output
616
+ events = _json_lines(result.stdout)
617
+ assert [e["event"] for e in events] == ["start", "result", "done"]
618
+ assert events[1]["status"] == "skipped"
619
+ assert events[1]["reason"] == "no_plugin"
620
+ assert events[1]["path"].endswith("two.SerumPreset")
621
+ assert events[2]["skipped"] == 1
622
+
623
+
624
+ def test_skip_missing_format_still_exits_2_when_nothing_is_renderable(
625
+ tmp_path: Path, no_defaults
626
+ ):
627
+ """An empty batch is the same misconfiguration the flag tolerates
628
+ partially — tolerating it completely would exit 0 having done nothing."""
629
+ plugin = tmp_path / "Serum.vst"
630
+ _touch(plugin)
631
+ presets = tmp_path / "presets"
632
+ _touch(presets / "only.SerumPreset")
633
+ result = runner.invoke(
634
+ app,
635
+ [str(presets), str(tmp_path / "out"), "--serum1", str(plugin),
636
+ "--skip-missing-format"],
637
+ )
638
+ assert result.exit_code == 2
639
+ assert "nothing to render" in result.output.lower()
@@ -244,3 +244,60 @@ def test_unknown_platform_returns_none(preset_env):
244
244
  def test_suffix_for_round_trips_every_format():
245
245
  for fmt in PresetFormat:
246
246
  assert format_for_path(Path(f"x{suffix_for(fmt)}")) is fmt
247
+
248
+
249
+ # ---- plugin suffix validation ---------------------------------------------
250
+ #
251
+ # Backs the GUI's path check. Reads the same platform knowledge as
252
+ # default_plugin_path so a check and a default cannot disagree.
253
+
254
+
255
+ def test_plugin_suffix_differs_per_platform_for_serum1():
256
+ """Serum 1 is VST2 — a different extension on every platform."""
257
+ assert config.plugin_suffix_for(PresetFormat.SERUM1, "darwin") == ".vst"
258
+ assert config.plugin_suffix_for(PresetFormat.SERUM1, "win32") == ".dll"
259
+ assert config.plugin_suffix_for(PresetFormat.SERUM1, "linux") == ".so"
260
+
261
+
262
+ def test_plugin_suffix_is_vst3_everywhere_for_serum2():
263
+ for platform in ("darwin", "win32", "linux"):
264
+ assert config.plugin_suffix_for(PresetFormat.SERUM2, platform) == ".vst3"
265
+
266
+
267
+ def test_plugin_suffix_unknown_platform_is_none():
268
+ assert config.plugin_suffix_for(PresetFormat.SERUM1, "testos") is None
269
+
270
+
271
+ def test_serum1_never_expects_vst3():
272
+ """The Serum 1 VST3 silently mis-loads .fxp presets — the failure this
273
+ table exists to catch when a user browses by hand."""
274
+ for platform in ("darwin", "win32", "linux"):
275
+ assert config.plugin_suffix_for(PresetFormat.SERUM1, platform) != ".vst3"
276
+
277
+
278
+ def test_plugin_path_accepts_a_macos_bundle_directory(tmp_path):
279
+ """Both plugin formats are bundles on macOS, so an is_file() check would
280
+ reject every valid macOS plugin."""
281
+ bundle = tmp_path / "Serum.vst"
282
+ bundle.mkdir()
283
+ assert config.plugin_path_looks_valid(bundle, PresetFormat.SERUM1, "darwin")
284
+
285
+
286
+ def test_plugin_path_rejects_the_wrong_extension(tmp_path):
287
+ wrong = tmp_path / "Serum.vst3"
288
+ wrong.mkdir()
289
+ assert not config.plugin_path_looks_valid(wrong, PresetFormat.SERUM1, "darwin")
290
+ assert config.plugin_path_looks_valid(wrong, PresetFormat.SERUM2, "darwin")
291
+
292
+
293
+ def test_plugin_path_rejects_a_missing_file(tmp_path):
294
+ assert not config.plugin_path_looks_valid(
295
+ tmp_path / "nope.vst", PresetFormat.SERUM1, "darwin"
296
+ )
297
+
298
+
299
+ def test_plugin_path_on_an_unknown_platform_checks_existence_only(tmp_path):
300
+ """No expectation to violate, so only existence is enforced."""
301
+ odd = tmp_path / "Serum.whatever"
302
+ odd.touch()
303
+ assert config.plugin_path_looks_valid(odd, PresetFormat.SERUM1, "testos")
@@ -245,7 +245,9 @@ def test_run_job_skip_existing(monkeypatch, tmp_path):
245
245
  skip_existing=True,
246
246
  )
247
247
  result = run_job(job)
248
- assert result == {"status": "skipped", "path": "/p.fxp"}
248
+ assert result == {
249
+ "status": "skipped", "path": "/p.fxp", "reason": "exists",
250
+ }
249
251
  assert "render_called_with" not in calls # never touched the engine
250
252
 
251
253
 
@@ -289,6 +291,20 @@ def test_run_job_returns_audio_when_no_output_path(monkeypatch):
289
291
  assert result["audio"].shape == (2, 4410)
290
292
 
291
293
 
294
+ def test_run_job_exits_when_parent_is_gone(monkeypatch):
295
+ exited: list[int] = []
296
+
297
+ def fake_exit(code):
298
+ exited.append(code)
299
+ raise SystemExit(code)
300
+
301
+ monkeypatch.setattr(engine, "_PARENT_PID", -1) # never our real parent
302
+ monkeypatch.setattr(engine.os, "_exit", fake_exit)
303
+ with pytest.raises(SystemExit):
304
+ run_job(Job(preset_path="/p.fxp", format=PresetFormat.SERUM1))
305
+ assert exited == [0]
306
+
307
+
292
308
  def test_run_job_wraps_render_errors(monkeypatch):
293
309
  class ExplodingEngine(FakeEngine):
294
310
  def render(self, duration):
@@ -87,4 +87,6 @@ def test_render_isolated_skips_without_spawning(tmp_path, monkeypatch):
87
87
 
88
88
  monkeypatch.setattr(subprocess, "run", boom)
89
89
  result = pool.render_isolated(job, "/Serum.vst", None, 44100, False)
90
- assert result == {"status": "skipped", "path": "/p.fxp"}
90
+ assert result == {
91
+ "status": "skipped", "path": "/p.fxp", "reason": "exists",
92
+ }
@@ -48,7 +48,27 @@ def test_unknown_bit_depth_raises(tmp_path: Path):
48
48
 
49
49
  def test_unknown_format_raises(tmp_path: Path):
50
50
  with pytest.raises(ValueError, match="format"):
51
- write_audio(_audio(), str(tmp_path / "a.flac"), 44100, "16", "flac")
51
+ write_audio(_audio(), str(tmp_path / "a.mp3"), 44100, "16", "mp3")
52
+
53
+
54
+ @pytest.mark.parametrize("depth,subtype", [("16", "PCM_16"), ("24", "PCM_24")])
55
+ def test_flac_bit_depths(tmp_path: Path, depth, subtype):
56
+ out = tmp_path / f"a_{depth}.flac"
57
+ write_audio(_audio(), str(out), 44100, depth, "flac")
58
+ info = sf.info(str(out))
59
+ assert (info.format, info.subtype, info.channels) == ("FLAC", subtype, 2)
60
+
61
+
62
+ def test_flac_rejects_float(tmp_path: Path):
63
+ with pytest.raises(ValueError, match="flac cannot be written at bit depth '32f'"):
64
+ write_audio(_audio(), str(tmp_path / "a.flac"), 44100, "32f", "flac")
65
+
66
+
67
+ def test_ogg_is_vorbis_and_ignores_bit_depth(tmp_path: Path):
68
+ out = tmp_path / "a.ogg"
69
+ write_audio(_audio(), str(out), 44100, "ignored", "ogg")
70
+ info = sf.info(str(out))
71
+ assert (info.format, info.subtype, info.channels) == ("OGG", "VORBIS", 2)
52
72
 
53
73
 
54
74
  # ---- atomic write ---------------------------------------------------------
@@ -0,0 +1,67 @@
1
+ """iter_jobs error surfacing. The executor is stubbed: a real loky crash
2
+ test would need a plugin-free initializer the pool does not offer."""
3
+ from __future__ import annotations
4
+
5
+ from concurrent.futures import Future
6
+
7
+ import pytest
8
+ from loky.process_executor import TerminatedWorkerError
9
+
10
+ import serum_render.pool as pool
11
+ from serum_render.formats import PresetFormat
12
+ from serum_render.jobs import Job
13
+
14
+
15
+ class _StubExecutor:
16
+ """Job 0 succeeds, job 1 raises like a normal per-job error, the rest
17
+ fail the way loky fails every pending future after a worker dies."""
18
+
19
+ def submit(self, fn, job):
20
+ f: Future = Future()
21
+ if job.note == 0:
22
+ f.set_result({"status": "ok", "path": job.preset_path})
23
+ elif job.note == 1:
24
+ f.set_exception(ValueError("bad preset"))
25
+ else:
26
+ f.set_exception(TerminatedWorkerError("worker was killed"))
27
+ return f
28
+
29
+
30
+ def test_iter_jobs_raises_worker_died_once(monkeypatch):
31
+ monkeypatch.setattr(pool, "get_reusable_executor", lambda **kw: _StubExecutor())
32
+ jobs = [Job(preset_path=f"/p{i}.fxp", format=PresetFormat.SERUM1, note=i) for i in range(4)]
33
+ seen = []
34
+ with pytest.raises(pool.WorkerDied, match="worker process died"):
35
+ for r in pool.iter_jobs(jobs, 1, "/s1", None, 44100):
36
+ seen.append(r["status"])
37
+ # as_completed order among already-done futures is arbitrary, so only
38
+ # the shape is checked: whatever arrived before the abort was a result.
39
+ assert set(seen) <= {"ok", "error"}
40
+
41
+
42
+ def _jobs(tmp_path, sizes):
43
+ jobs = []
44
+ for i, size in enumerate(sizes):
45
+ p = tmp_path / f"p{i:02d}.fxp"
46
+ p.write_bytes(b"x" * size)
47
+ jobs.append(Job(preset_path=str(p), format=PresetFormat.SERUM1))
48
+ return jobs
49
+
50
+
51
+ def test_spread_big_presets_spaces_them_out(tmp_path):
52
+ big = pool._BIG_PRESET_BYTES + 1
53
+ jobs = _jobs(tmp_path, [1] * 6 + [big] * 3)
54
+ out = pool.spread_big_presets(jobs)
55
+ assert sorted(j.preset_path for j in out) == sorted(j.preset_path for j in jobs)
56
+ big_positions = [i for i, j in enumerate(out) if j in jobs[6:]]
57
+ assert big_positions == [2, 5, 8]
58
+ # Small presets keep their relative order.
59
+ smalls = [j for j in out if j in jobs[:6]]
60
+ assert smalls == jobs[:6]
61
+
62
+
63
+ def test_spread_big_presets_noop_without_a_mix(tmp_path):
64
+ small = _jobs(tmp_path, [1, 1])
65
+ assert pool.spread_big_presets(small) == small
66
+ missing = [Job(preset_path=str(tmp_path / "gone.fxp"), format=PresetFormat.SERUM1)]
67
+ assert pool.spread_big_presets(missing) == missing
@@ -30,9 +30,15 @@ def test_brackets_and_punctuation():
30
30
  assert sanitize("Lead [FP]") == "Lead_FP"
31
31
 
32
32
 
33
- def test_unicode_replaced():
34
- # Accented chars are not [A-Za-z0-9_-], so they become '_'
35
- assert sanitize("café") == "caf"
33
+ def test_unicode_letters_kept():
34
+ # Letters in any script survive; an ASCII-only class turned a CJK-only
35
+ # name into an empty stem and the render was named after its folder.
36
+ assert sanitize("café") == "café"
37
+ assert sanitize("日本語 ピアノ") == "日本語_ピアノ"
38
+
39
+
40
+ def test_symbols_still_replaced():
41
+ assert sanitize("a★b") == "a_b"
36
42
 
37
43
 
38
44
  def test_mixed_punctuation_collapses():
@@ -1,54 +0,0 @@
1
- """Audio file writing. Part of the worker import graph — module level is
2
- stdlib-only; numpy/soundfile load inside the function, after dawdreamer
3
- has already been imported by EngineHost."""
4
- from __future__ import annotations
5
-
6
- import os
7
- from pathlib import Path
8
-
9
- _SUBTYPE_MAP = {"16": "PCM_16", "24": "PCM_24", "32f": "FLOAT"}
10
-
11
-
12
- def write_audio(
13
- audio, output_path: str, sample_rate: int, bit_depth: str, output_format: str
14
- ) -> None:
15
- """Write a (channels, samples) float32 array as wav (given bit depth)
16
- or npy (raw float32, bit depth ignored).
17
-
18
- Writes to a sibling temp file and renames it into place, so a killed
19
- render can never leave a truncated file at `output_path` —
20
- skip_existing would otherwise skip that garbage forever on the
21
- re-run. A SIGKILL does leave a stray `.tmp` behind; that is the
22
- intended trade.
23
-
24
- The temp suffix goes *after* the real extension (`a.wav.tmp`, not
25
- `a.tmp.wav`) so strays stay out of `*.wav` globs. Both writers are
26
- told their format explicitly, because each otherwise infers it from
27
- the trailing extension: np.save would write `a.npy.tmp.npy`, and
28
- sf.write raises on an unrecognised one.
29
- """
30
- import numpy as np
31
-
32
- if output_format not in ("wav", "npy"):
33
- raise ValueError(f"Unknown output format: {output_format!r}")
34
- subtype = None
35
- if output_format == "wav":
36
- subtype = _SUBTYPE_MAP.get(bit_depth)
37
- if subtype is None:
38
- raise ValueError(f"Unknown bit depth: {bit_depth!r}")
39
-
40
- Path(output_path).parent.mkdir(parents=True, exist_ok=True)
41
- tmp = f"{output_path}.tmp"
42
- try:
43
- if output_format == "npy":
44
- with open(tmp, "wb") as f:
45
- np.save(f, audio)
46
- else:
47
- import soundfile as sf
48
-
49
- # soundfile expects (samples, channels) — transpose before writing.
50
- sf.write(tmp, audio.T, sample_rate, subtype=subtype, format="WAV")
51
- os.replace(tmp, output_path)
52
- except BaseException:
53
- Path(tmp).unlink(missing_ok=True)
54
- raise
File without changes
File without changes