beqforge 0.2.2__tar.gz → 0.2.4__tar.gz

beqforge-0.2.4/.gitattributes

@@ -0,0 +1 @@
+*.cmd text eol=crlf

{beqforge-0.2.2 → beqforge-0.2.4}/.github/workflows/build-executable.yml

@@ -226,6 +226,14 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Attach the Windows designer launcher
+        if: runner.os == 'Windows' && startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v3
+        with:
+          files: packaging/designer/beqforge-designer.cmd
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
   publish:
     name: Publish Python package to PyPI
     needs: [validated_tests, package, build, create_release]

{beqforge-0.2.2 → beqforge-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: beqforge
-Version: 0.2.2
+Version: 0.2.4
 Summary: Audio-derived BEQ design, published filter optimisation and DSP validation
 License-File: LICENCE.md
 Requires-Python: <3.15,>=3.13
@@ -187,6 +187,12 @@ naming the array, rather than a design decline. Inline requests remain supported
 logs read, parse, decode, design and response timings; `tools/experiments/request_timing.py`
 measures cold and warm requests.
 
+**Several designs at once.** `--workers N` (1-8, default 1) runs N designs at once, each in
+its own worker process; further requests queue. `GET /health` reports it as `parallel`, so a
+caller can send each server as many designs as it takes rather than be configured with that
+number. Each design's fit pool gets an equal share of the machine's cores (`BEQ_FIT_WORKERS`,
+if set, stays each design's own). The share changes how long a fit takes, never its answer.
+
 Every `serve-designer` configuration option can also be set through an environment variable.
 Explicit CLI options take precedence; for repeatable options, CLI values replace the entire
 environment list. `--help` lists the variable beside each option. Other subcommands retain
@@ -207,6 +213,7 @@ their existing CLI configuration.
 | `--record-dir` | `BEQFORGE_RECORD_DIR` | path |
 | `--cache-dir` | `BEQFORGE_CACHE_DIR` | path |
 | `--shared-root` | `BEQFORGE_SHARED_ROOT` | path |
+| `--workers` | `BEQFORGE_WORKERS` | integer, 1-8 |
 | `--quiet` | `BEQFORGE_QUIET` | boolean |
 
 Booleans accept `true`/`false`, `yes`/`no`, `on`/`off` or `1`/`0`, ignoring case.
@@ -270,9 +277,9 @@ The image's defaults, all overridable with the environment variables above:
 
 It runs as uid/gid 1000 (`--build-arg PUID=… PGID=…` to change), which must be able to write
 the shared root and the cache: the server checks both with a write at startup. Its
-`HEALTHCHECK` asks `/health`, which answers while a design runs: designs run in a separate
-worker process, one at a time, so a caller sending several at once queues them; size the
-caller's timeout for that. `docker stop` stops a design in progress.
+`HEALTHCHECK` asks `/health`, which answers while a design runs: designs run in separate
+worker processes, `BEQFORGE_WORKERS` (default 1) at a time, so a caller sending more at once
+queues them; size the caller's timeout for that. `docker stop` stops a design in progress.
 
 Build and check it locally from the repository root:
 
@@ -284,6 +291,38 @@ python3 packaging/designer/smoke.py beqforge-designer
 The smoke script checks `/health` and one design inline and one by reference;
 `tests/test_designer_image.py` runs the same check against an in-process server.
 
+### Running the designer on Windows
+
+The release's `beqforge-windows-x86_64.exe` runs the same server natively, for a beqdesigner
+container (or install) that calls out to a Windows machine. Put `beqforge-designer.cmd`, which
+is attached to the same release (source: `packaging/designer/beqforge-designer.cmd`), beside the
+exe and double-click it, or run the exe directly:
+
+```bat
+beqforge-windows-x86_64.exe serve-designer --host 0.0.0.0 --port 8420 ^
+  --shared-root D:\beq\work --cache-dir %LOCALAPPDATA%\beqforge\cache
+```
+
+The launcher sets the image's defaults through the environment variables above, each only if
+not already set: `BEQFORGE_HOST=0.0.0.0`, `BEQFORGE_PORT=8420` and
+`BEQFORGE_CACHE_DIR=%LOCALAPPDATA%\beqforge\cache`. Arguments pass through to `serve-designer`.
+
+* **Listen on the network.** The CLI's default host is `127.0.0.1`, which a container cannot
+  reach; the launcher uses `0.0.0.0`. Windows Firewall asks the first time: allow private
+  networks.
+* **Shared root.** For audio by reference, set `BEQFORGE_SHARED_ROOT` (or edit the commented
+  line in the launcher) to the Windows folder bind-mounted into beqdesigner's container as its
+  work directory. Without it, beqdesigner must send audio inline.
+* **beqdesigner's side.** Under Docker Desktop on the same machine, register
+  `http://host.docker.internal:8420/design`; from another machine, use this one's LAN address.
+  Check `http://<address>:8420/health` from there first.
+* **Several at once.** Set `BEQFORGE_WORKERS` (or pass `--workers 2`) for a machine that can
+  design more than one title at a time; `/health` reports it as `parallel`.
+* **The rest.** The exe is unsigned, so SmartScreen warns on first run. `serve-designer` does not need `ffmpeg`. Close the window, or
+  press Ctrl+C, to stop.
+
+### Building and releasing
+
 For a machine without Python/`uv`, a standalone `beqforge` executable (every subcommand,
 including `serve-designer`) is built for Linux/macOS/Windows by
 `.github/workflows/build-executable.yml` on every `vX.Y.Z` tag, and attached to the matching

{beqforge-0.2.2 → beqforge-0.2.4}/README.md

@@ -161,6 +161,12 @@ naming the array, rather than a design decline. Inline requests remain supported
 logs read, parse, decode, design and response timings; `tools/experiments/request_timing.py`
 measures cold and warm requests.
 
+**Several designs at once.** `--workers N` (1-8, default 1) runs N designs at once, each in
+its own worker process; further requests queue. `GET /health` reports it as `parallel`, so a
+caller can send each server as many designs as it takes rather than be configured with that
+number. Each design's fit pool gets an equal share of the machine's cores (`BEQ_FIT_WORKERS`,
+if set, stays each design's own). The share changes how long a fit takes, never its answer.
+
 Every `serve-designer` configuration option can also be set through an environment variable.
 Explicit CLI options take precedence; for repeatable options, CLI values replace the entire
 environment list. `--help` lists the variable beside each option. Other subcommands retain
@@ -181,6 +187,7 @@ their existing CLI configuration.
 | `--record-dir` | `BEQFORGE_RECORD_DIR` | path |
 | `--cache-dir` | `BEQFORGE_CACHE_DIR` | path |
 | `--shared-root` | `BEQFORGE_SHARED_ROOT` | path |
+| `--workers` | `BEQFORGE_WORKERS` | integer, 1-8 |
 | `--quiet` | `BEQFORGE_QUIET` | boolean |
 
 Booleans accept `true`/`false`, `yes`/`no`, `on`/`off` or `1`/`0`, ignoring case.
@@ -244,9 +251,9 @@ The image's defaults, all overridable with the environment variables above:
 
 It runs as uid/gid 1000 (`--build-arg PUID=… PGID=…` to change), which must be able to write
 the shared root and the cache: the server checks both with a write at startup. Its
-`HEALTHCHECK` asks `/health`, which answers while a design runs: designs run in a separate
-worker process, one at a time, so a caller sending several at once queues them; size the
-caller's timeout for that. `docker stop` stops a design in progress.
+`HEALTHCHECK` asks `/health`, which answers while a design runs: designs run in separate
+worker processes, `BEQFORGE_WORKERS` (default 1) at a time, so a caller sending more at once
+queues them; size the caller's timeout for that. `docker stop` stops a design in progress.
 
 Build and check it locally from the repository root:
 
@@ -258,6 +265,38 @@ python3 packaging/designer/smoke.py beqforge-designer
 The smoke script checks `/health` and one design inline and one by reference;
 `tests/test_designer_image.py` runs the same check against an in-process server.
 
+### Running the designer on Windows
+
+The release's `beqforge-windows-x86_64.exe` runs the same server natively, for a beqdesigner
+container (or install) that calls out to a Windows machine. Put `beqforge-designer.cmd`, which
+is attached to the same release (source: `packaging/designer/beqforge-designer.cmd`), beside the
+exe and double-click it, or run the exe directly:
+
+```bat
+beqforge-windows-x86_64.exe serve-designer --host 0.0.0.0 --port 8420 ^
+  --shared-root D:\beq\work --cache-dir %LOCALAPPDATA%\beqforge\cache
+```
+
+The launcher sets the image's defaults through the environment variables above, each only if
+not already set: `BEQFORGE_HOST=0.0.0.0`, `BEQFORGE_PORT=8420` and
+`BEQFORGE_CACHE_DIR=%LOCALAPPDATA%\beqforge\cache`. Arguments pass through to `serve-designer`.
+
+* **Listen on the network.** The CLI's default host is `127.0.0.1`, which a container cannot
+  reach; the launcher uses `0.0.0.0`. Windows Firewall asks the first time: allow private
+  networks.
+* **Shared root.** For audio by reference, set `BEQFORGE_SHARED_ROOT` (or edit the commented
+  line in the launcher) to the Windows folder bind-mounted into beqdesigner's container as its
+  work directory. Without it, beqdesigner must send audio inline.
+* **beqdesigner's side.** Under Docker Desktop on the same machine, register
+  `http://host.docker.internal:8420/design`; from another machine, use this one's LAN address.
+  Check `http://<address>:8420/health` from there first.
+* **Several at once.** Set `BEQFORGE_WORKERS` (or pass `--workers 2`) for a machine that can
+  design more than one title at a time; `/health` reports it as `parallel`.
+* **The rest.** The exe is unsigned, so SmartScreen warns on first run. `serve-designer` does not need `ffmpeg`. Close the window, or
+  press Ctrl+C, to stop.
+
+### Building and releasing
+
 For a machine without Python/`uv`, a standalone `beqforge` executable (every subcommand,
 including `serve-designer`) is built for Linux/macOS/Windows by
 `.github/workflows/build-executable.yml` on every `vX.Y.Z` tag, and attached to the matching

{beqforge-0.2.2 → beqforge-0.2.4}/TODO.md

@@ -18,29 +18,32 @@ are retained so records and code comments remain traceable. Completed items are
 | Priority | ID | Status | Value, work and blocker or reason for parking |
 | --- | --- | --- | --- |
 | 1 | Playback contract | open | Reconcile the supplied bass-management model with the model actually used for targets, verification and clipping. Only `lpf_fs` is consumed today; check the ignored fields before claiming the listener's clipping cost. Caller propagation is an external subtask. |
-| 2 | E10 | open | Predeclare fresh content-goal validation before further tuning or a default change. Existing seeds and corpus have repeatedly informed development; writing the protocol needs no new audio. |
-| 3 | E1 | open | Add record-only scene-held-out verification: evidence independent of the material that generated the target. A gate needs a separate demonstrated benefit. |
-| 4 | Steep-filter scoring | open | Implement coloured/codec-like floors and recipe-specific truth bands under E10; inspect shape failures and published-ceiling excess. Existing titles can supply programme texture. |
-| 5 | Steep-filter default | blocked | Recovery improves substantially with `--content-edge`, but changing the default needs E10, the scoring above, listening judgements and more independent real steep titles. Safe House already works with the default; keep the option off meanwhile. |
-| 6 | F2 / device behaviour | in progress; first hardware pilot measured | Coefficient quantisation does not establish hardware accuracy. Limit changes need measured internal arithmetic/noise/limit cycles on a named device and a capture setup; the [measurement plan](plans/F2-device-precision-validation.md) specifies Python sweep/capture, optional REW cross-checks, software controls, single-entry/full-catalogue analysis and a standalone cross-platform executable. The `beqforge-device-check` preview includes frozen manifests, capture/recovery, CLI-only miniDSP controls (minidsp-rs 0.1.12, batched through `-f`) with float32 transport attribution, staged qualification/convergence, uncertainty-aware filter checks, entry/unique-cascade frequency distributions and matched-device deltas. First verified pilot on a miniDSP 2x4 HD (USB loopback, 96 kHz): the device plays its float32 coefficients as predicted (worst 0.0074 dB, 2-200 Hz), while float32 coefficients themselves put 18.8 dB of error into a 5 Hz Q 6 peak; see the plan, section 12. First catalogue sample (50 cascades): 49 play as predicted on every bin (worst 0.0082 dB); the 50th was clipped by the device and is to be remeasured (F2a, plan section 13). Next: the `grid` and `boundary` suites on hardware to map where float32 coefficients stop representing low, high-Q filters. No Q-limit change yet. |
-| 7 | Validation coverage (former TODO 10) | blocked | Broad real-programme generalisation needs the missing shapes and independently characterised paired releases listed below. Sparse titles exist; their absolute truth and wider sparse coverage remain missing. |
-| 8 | Identification | blocked | Generalising `N(f)` and its fit band needs independent, varied source material, especially paired releases. Sensitivity experiments can proceed; programme-only uncertainty cannot identify the cause of a droop. |
-| 9 | E4 | parked | No measured failure has been attributed to isolated ceiling holes. Reopen if unevenness or E9 excess is traced to such bins; smoothing may only reduce the raw licence. |
-| 10 | F4 follow-up | parked | Both fitter-objective selection spikes lost passes/true positives. Judge several fits only with a demonstrated usable alternative discarded before `_judge`; a smaller residual is insufficient evidence. |
-| 11 | F3 follow-up | parked | A fifth section moved no verdict when tried and costs more fitting. Reopen if an evidence-supported target has a demonstrated usable fit beyond four sections and no usable fit within four. |
-| 12 | T2 | parked | The steep-variant audit found no swept cap binding a weak winner. Derive caps only when a binding cap demonstrably prevents a better supported result. |
-| 13 | Residual (former TODO 5) | open | Correct the reported target error and its actual measurement band without changing fit selection. Primarily audit accuracy; any escalation/objective change is a separate, higher-impact decision. Non-parametric reporting is already allowed upstream. |
-| 14 | Authored features | parked | Manual `--exclude` works; no validated automatic detector exists. Reopen with real labelled features and negatives showing that detection preserves legitimate bass. |
-| 15 | Dynamic processing (former TODO 11) | parked | No suspected real case has scoped a useful tripwire. Reopen when compression/limiting demonstrably compromises this correction; non-LTI processing alone does not prove every BEQ is invalid. |
-| 16 | Tilted passband reference (goal/corpus follow-up) | parked | No real in-sub-band case needs a sloping reference yet; Dossier's abstention was decided. Reopen with one. Goal-aware corpus labels belong to the open E10 protocol work. Nearest so far: 13 Going on 30's mix tilts about −7 dB/oct above 50 Hz (bass is coherent across channels, ~200 Hz is not) and finds its plateau only through the one-sided fallback. That reference reads a 36 dB deficit below 25 Hz; each channel's own plateau reads 30-34 dB. A reference built from the channels would be 2-5 dB less generous there (see plans/done-design-and-pipeline.md, 11 October 2026). |
-| 17 | Mixed-channel policy | parked | `channel_scope` is currently an unpopulated optional response field, not a computed `mixed` finding awaiting a gate. Reopen with a case where existing per-channel restoration and common pricing produce an unsuitable mix correction. |
-| 18 | Fraction dial (former TODO 7) | parked | No user/title has needed partial licensed restoration as a preference; tilt and tolerance already ship. Reopen with a concrete requested outcome, then price and validate it like every target. |
-| 19 | Protective corner (former TODO 9) | parked | The corner is already derived from boost cap and implied order, floored by `lowest_frequency_hz`. No case requires an independent override or different fallback alignment; reopen with one. |
-| 20 | Device configuration on the wire | parked | The current contract deliberately omits device preference; server flags already configure realisation. Reopen if one server must serve different device formats/rates per request; then agree an upstream extension. Hardware validity remains F2. |
-| 21 | Catalogue comparison (former TODO 8) | parked | A disagreement detector has no demonstrated accuracy benefit. Reopen with an independent discrepancy to investigate; authored filters remain comparisons, never calibration targets. |
-| 22 | Performance | parked | Further reuse changes cost, not filter accuracy. Reopen after measuring repeated numerical identities or material remaining analysis cost; missed-fit search belongs to F3/F4 instead. |
-| 23 | Chart peak bias | parked | Deliberate catalogue-compatible per-bin maximum; it affects presentation only. Reopen if a reader needs an alternative percentile view; keep it distinct from the 95th-percentile evidence envelope. |
-| 24 | Documentation citations | open | Remove or repoint orphan references and stale descriptions of shipped behaviour. Low filter impact, but prevents future changes being based on obsolete assumptions. |
+| 2 | Texture yardstick band | open (E10 only) | Implemented: the mix's ripple is measured about a cubic over the unchanged band, so the LFE knee is trend. 9 (2009), Beauty and the Beast, Crazy, Stupid, Love and Despicable Me 3 now accept; Carrie stays declined. Probe and protocol unchanged; corpus 0/45 gate pass. Neither width-normalised form separated `broadband/5`. The degree was chosen on corpus and library data, so it needs the fresh E10 validation before it counts as settled; see [the outcome](plans/texture-yardstick-sub-band.md#outcome-17-october-2026). |
+| 3 | E10 | open | Predeclare fresh content-goal validation before further tuning or a default change. Existing seeds and corpus have repeatedly informed development; writing the protocol needs no new audio. |
+| 4 | E1 | open | Add record-only scene-held-out verification: evidence independent of the material that generated the target. A gate needs a separate demonstrated benefit. |
+| 5 | Steep-filter scoring | open | Implement coloured/codec-like floors and recipe-specific truth bands under E10; inspect shape failures and published-ceiling excess. Existing titles can supply programme texture. |
+| 6 | Steep-filter default | blocked | Recovery improves substantially with `--content-edge`, but changing the default needs E10, the scoring above, listening judgements and more independent real steep titles. Safe House already works with the default; keep the option off meanwhile. |
+| 7 | F2 / device behaviour | in progress; first hardware pilot measured | Coefficient quantisation does not establish hardware accuracy. Limit changes need measured internal arithmetic/noise/limit cycles on a named device and a capture setup; the [measurement plan](plans/F2-device-precision-validation.md) specifies Python sweep/capture, optional REW cross-checks, software controls, single-entry/full-catalogue analysis and a standalone cross-platform executable. The `beqforge-device-check` preview includes frozen manifests, capture/recovery, CLI-only miniDSP controls (minidsp-rs 0.1.12, batched through `-f`) with float32 transport attribution, staged qualification/convergence, uncertainty-aware filter checks, entry/unique-cascade frequency distributions and matched-device deltas. First verified pilot on a miniDSP 2x4 HD (USB loopback, 96 kHz): the device plays its float32 coefficients as predicted (worst 0.0074 dB, 2-200 Hz), while float32 coefficients themselves put 18.8 dB of error into a 5 Hz Q 6 peak; see the plan, section 12. First catalogue sample (50 cascades): 49 play as predicted on every bin (worst 0.0082 dB); the 50th was clipped by the device and is to be remeasured (F2a, plan section 13). Next: the `grid` and `boundary` suites on hardware to map where float32 coefficients stop representing low, high-Q filters. No Q-limit change yet. |
+| 8 | Validation coverage (former TODO 10) | blocked | Broad real-programme generalisation needs the missing shapes and independently characterised paired releases listed below. Sparse titles exist; their absolute truth and wider sparse coverage remain missing. |
+| 9 | Identification | blocked | Generalising `N(f)` and its fit band needs independent, varied source material, especially paired releases. Sensitivity experiments can proceed; programme-only uncertainty cannot identify the cause of a droop. |
+| 10 | E4 | parked | No measured failure has been attributed to isolated ceiling holes. Reopen if unevenness or E9 excess is traced to such bins; smoothing may only reduce the raw licence. |
+| 11 | F4 follow-up | parked | Both fitter-objective selection spikes lost passes/true positives. Judge several fits only with a demonstrated usable alternative discarded before `_judge`; a smaller residual is insufficient evidence. |
+| 12 | F3 follow-up | parked | A fifth section moved no verdict when tried and costs more fitting. Reopen if an evidence-supported target has a demonstrated usable fit beyond four sections and no usable fit within four. |
+| 13 | T2 | parked | The steep-variant audit found no swept cap binding a weak winner. Derive caps only when a binding cap demonstrably prevents a better supported result. |
+| 14 | Residual (former TODO 5) | open | Correct the reported target error and its actual measurement band without changing fit selection. Primarily audit accuracy; any escalation/objective change is a separate, higher-impact decision. Non-parametric reporting is already allowed upstream. |
+| 15 | Authored features | parked | Manual `--exclude` works; no validated automatic detector exists. Reopen with real labelled features and negatives showing that detection preserves legitimate bass. |
+| 16 | Dynamic processing (former TODO 11) | parked | No suspected real case has scoped a useful tripwire. Reopen when compression/limiting demonstrably compromises this correction; non-LTI processing alone does not prove every BEQ is invalid. |
+| 17 | Tilted passband reference (goal/corpus follow-up) | parked | No real in-sub-band case needs a sloping reference yet; Dossier's abstention was decided. Reopen with one. Goal-aware corpus labels belong to the open E10 protocol work. Nearest so far: 13 Going on 30's mix tilts about −7 dB/oct above 50 Hz (bass is coherent across channels, ~200 Hz is not) and finds its plateau only through the one-sided fallback. That reference reads a 36 dB deficit below 25 Hz; each channel's own plateau reads 30-34 dB. A reference built from the channels would be 2-5 dB less generous there (see plans/done-design-and-pipeline.md, 11 October 2026). |
+| 18 | Mixed-channel policy | parked | `channel_scope` is currently an unpopulated optional response field, not a computed `mixed` finding awaiting a gate. Reopen with a case where existing per-channel restoration and common pricing produce an unsuitable mix correction. |
+| 19 | Fraction dial (former TODO 7) | parked | No user/title has needed partial licensed restoration as a preference; tilt and tolerance already ship. Reopen with a concrete requested outcome, then price and validate it like every target. |
+| 20 | Protective corner (former TODO 9) | parked | The corner is already derived from boost cap and implied order, floored by `lowest_frequency_hz`. No case requires an independent override or different fallback alignment; reopen with one. |
+| 21 | Device configuration on the wire | parked | The current contract deliberately omits device preference; server flags already configure realisation. Reopen if one server must serve different device formats/rates per request; then agree an upstream extension. Hardware validity remains F2. |
+| 22 | Catalogue comparison (former TODO 8) | parked | A disagreement detector has no demonstrated accuracy benefit. Reopen with an independent discrepancy to investigate; authored filters remain comparisons, never calibration targets. |
+| 23 | Performance | parked | Further reuse changes cost, not filter accuracy. Reopen after measuring repeated numerical identities or material remaining analysis cost; missed-fit search belongs to F3/F4 instead. |
+| 24 | Chart peak bias | parked | Deliberate catalogue-compatible per-bin maximum; it affects presentation only. Reopen if a reader needs an alternative percentile view; keep it distinct from the 95th-percentile evidence envelope. |
+| 25 | Documentation citations | open | Remove or repoint orphan references and stale descriptions of shipped behaviour. Low filter impact, but prevents future changes being based on obsolete assumptions. |
+| 26 | Texture yardstick retune (library review) | parked | The cubic (row 2) keeps the 200 Hz band only because the sub-band cap admitted one synthetic negative, `broadband/5`: chance unevenness in noise bursts, at a 2.6 dB boost. With 45 gated cases a single case moves the gate's upper bound from 0.079 to 0.118. Carrie is still declined (0.85x about a cubic, 1.33x with the cap). Reopen when the beqdesigner library review (~1,290 titles) is complete. Then retune against its declines: the band edge, the trend degree, and whether the gate weights a false acceptance by its boost. The library holds no known negative, so it can expose wrong declines but not measure false acceptances. Any retune still needs the corpus or a fresh E10 set for that, ideally with negatives built from real programme texture (row 5). See [the outcome](plans/texture-yardstick-sub-band.md#outcome-17-october-2026). |
+| 27 | Parameter-space optimisation for several profiles | open | beqdesigner's main window will let a filter designer optimise a filter for chosen device profiles before publishing, in freq/Q/gain terms (a BEQ is published and loaded as parameters, so no catalogue schema change), minimising the worst error across all chosen profiles at once. The search belongs in `beqoptimiser`, beside `optimise()`; beqdesigner builds the interface. See [the request](plans/parameter-space-optimisation.md). |
 
 ## Review evidence
 

{beqforge-0.2.2 → beqforge-0.2.4}/beq_common/__init__.py

@@ -1,6 +1,6 @@
 """Shared filter primitives; no workflow package dependencies."""
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"
 
 from .types import BiquadSpec as BiquadSpec
 from .types import BiquadType as BiquadType

{beqforge-0.2.2 → beqforge-0.2.4}/beqforge/AGENTS.md

@@ -43,7 +43,7 @@ still holds: no other API, no other service, and the server is a thin transport
 | `beqforge/explain.py` | The plain-language account a designer response leads with — `found` (reference plateau, which channels carry it and which are silent, down to where there is real bass content, judged band, goal), `correction` (the cascade, then frequency by frequency what was wanted, what the content supports and before → after), `clipping` (the sub-feed peak and how far to turn the sub down, on the request's or the assumed bass management) and `alternatives` (why each other candidate lost). Reads the `Report`; measures and decides nothing. |
 | `beqforge/designer.py` | The `design(request) -> response` adapter between beqdesigner's `designer-interface.md` v1.1 and `beqforge.pipeline.run` — request/response dataclasses (1.1: every candidate the judge failed goes back in `rejected` with its failures, review only, beside the answer or the decline), wire-format (de)serialisation and the field-by-field mapping onto `Report`/`Candidate`/`Verdict`. Also `validate_response`, an independent re-implementation of beqdesigner's own §3-§5 rules (that repo isn't importable — PyQt6), called by the server before a response ever goes on the wire. Pure and independently testable; no socket. |
 | `tools/design_beq.py` | **The entry point.** One command, a filter and its reasoning. `--charts DIR` for the pictures; writes a `.run.json.gz` record beside the material unless `--no-record`. |
-| `tools/designer_server.py` | `beqforge serve-designer` — the HTTP transport (`designer-interface.md` §7.1) around `beqforge/designer.py`. Server-wide flags for device realisation/strategies/exclusions; everything per-title comes from the request. A `ThreadingHTTPServer`, so `/health` answers during a design, with every design run in one long-lived worker process started with "spawn" (`_DesignWorker`): the fitter forks worker processes (`beqforge.filters.PARALLEL_FITS`) when a fit escalates past one section count, and forking a multi-threaded process risks a deadlock, so the process that forks must stay single-threaded — the worker's log records come back over a `SimpleQueue`, not a `Queue`, for that reason. One worker keeps designs serial (the contract is one synchronous POST per `design()` call); a worker that dies answers 500 and is replaced. SIGTERM shuts down like Ctrl-C, stopping the worker's process group, fit pool included. Every response names its build (`beqforge_revision`); `--record-dir DIR` also writes each request's run record, named by a digest of the request audio, so a review-queue entry can be replayed. `--cache-dir DIR` keeps the stage cache there (`cache.DirStore`, one file per entry, atomic): a repeat request for a title skips the analysis — 110 s cold, 50 s warm on a 2-hour 8-channel title. Each request logs a timing line (read, parse, decode, design, respond, queued); `tools/experiments/request_timing.py` reports them. `--shared-root DIR` accepts audio by reference (contract 1.2, beqdesigner's `design/designer-by-reference.md` §3): an array names a WAV relative to DIR plus the SHA-256 of its decoded column, and `beqforge/reference.py` resolves, decodes and checks it; one that cannot be honoured is a 422 naming the array, never a decline. `GET /health` reports `contract_version` and `shared_root`. |
+| `tools/designer_server.py` | `beqforge serve-designer` — the HTTP transport (`designer-interface.md` §7.1) around `beqforge/designer.py`. Server-wide flags for device realisation/strategies/exclusions; everything per-title comes from the request. A `ThreadingHTTPServer`, so `/health` answers during a design, with every design run in a long-lived worker process started with "spawn" (`_DesignWorker`): the fitter forks worker processes (`beqforge.filters.PARALLEL_FITS`) when a fit escalates past one section count, and forking a multi-threaded process risks a deadlock, so the process that forks must stay single-threaded — the worker's log records come back over a `SimpleQueue`, not a `Queue`, for that reason. A worker designs one title at a time; `--workers N` (1-8) runs N of them, each request taking the next idle one, and `/health` reports N as `parallel` so a caller can size its sends from the designer. With N > 1 each worker's fit pool is `filters.FIT_WORKERS // N` (`fit_share`) unless `BEQ_FIT_WORKERS` is set: pool size changes timing, never an answer. A worker that dies answers 500 and is replaced; the others carry on. SIGTERM shuts down like Ctrl-C, stopping the worker's process group, fit pool included. Every response names its build (`beqforge_revision`); `--record-dir DIR` also writes each request's run record, named by a digest of the request audio, so a review-queue entry can be replayed. `--cache-dir DIR` keeps the stage cache there (`cache.DirStore`, one file per entry, atomic): a repeat request for a title skips the analysis — 110 s cold, 50 s warm on a 2-hour 8-channel title. Each request logs a timing line (read, parse, decode, design, respond, queued); `tools/experiments/request_timing.py` reports them. `--shared-root DIR` accepts audio by reference (contract 1.2, beqdesigner's `design/designer-by-reference.md` §3): an array names a WAV relative to DIR plus the SHA-256 of its decoded column, and `beqforge/reference.py` resolves, decodes and checks it; one that cannot be honoured is a 422 naming the array, never a decline. `GET /health` reports `contract_version`, `shared_root` and `parallel`. |
 | `tools/replay.py` | Redraw charts and export to beqdesigner from a record — no rerun, no extraction. Refuses on a stale record unless `--force`. |
 | `tools/extract.py` | ffmpeg → 1 kHz per-channel `.npz`. Requires an explicit supported channel layout; preserves layout provenance. Needs no beqdesigner. |
 | `tools/summarise.py` | Sanity-check an extraction before using it. |
@@ -333,7 +333,11 @@ least `min_judge_octaves` above the floor — no fixed top (historical review T6
   (`pipeline.passband_ripple_db`) is left alone: it abstains with `within_programme_ripple`
   before any strategy runs. That ripple is the title's own yardstick, so there is no constant.
   Crest to trough rather than a one-sided dip, because the reference sits on the crests. This
-  is what took the negative corpus from 4 false acceptances in 45 to 0.
+  is what took the negative corpus from 4 false acceptances in 45 to 0. The mix's ripple is
+  taken about a cubic in log frequency, so an LFE-led mix's knee above the crossover is trend,
+  not texture; each channel's is taken about a line. Don't shorten the band instead:
+  crest to trough shrinks with bin count, and the 1x boundary was calibrated on the full band
+  ([plans/texture-yardstick-sub-band.md](../plans/texture-yardstick-sub-band.md)).
 * **Steep filters: the default declines them; `judge_from_content_edge` is an opt-in that
   recovers them and lifts some noise.** Below a steep filter's edge the priced target already
   falls into the quiet floor with the programme — contrast bounds it — and the shape clauses

{beqforge-0.2.2 → beqforge-0.2.4}/beqforge/pipeline.py

@@ -772,6 +772,9 @@ MAINS_HZ = (50.0, 60.0)
 # inside the 50 Hz spacing so it never reaches the next harmonic
 HUM_NOTCH_HALF_WIDTH_HZ = 2.5
 HUM_SURROUND_HALF_WIDTH_HZ = 10.0
+# the mix's texture is measured about a cubic in log frequency, so an LFE-led mix's knee above
+# the crossover is trend, not ripple (plans/texture-yardstick-sub-band.md)
+MIX_TEXTURE_TREND_DEGREE = 3
 
 
 def mains_hum_notches(
@@ -815,7 +818,11 @@ def mains_hum_notches(
 
 
 def passband_ripple_db(
-    material: Material, params: "PipelineParams", noise_floor_hz: float = math.nan
+    material: Material,
+    params: "PipelineParams",
+    noise_floor_hz: float = math.nan,
+    *,
+    trend_degree: int = 1,
 ) -> tuple[float, tuple[float, float]] | None:
     """The programme's own texture where nothing is missing: crest-to-trough, dB, and where.
 
@@ -823,6 +830,17 @@ def passband_ripple_db(
     correction — the top of the judged band to the top of the analysis band — as the spread of
     the curve about its own log-frequency trend, so a tilted passband is not read as ripple.
 
+    The trend is a polynomial of `trend_degree` in log frequency. The mix's texture blocker
+    asks for a cubic (`MIX_TEXTURE_TREND_DEGREE`). In an LFE-led mix the level falls away
+    where the LFE channel's content ends (60-100 Hz), a knee a straight line cannot remove, so
+    it read as ripple and withheld a real deficit: 9 (2009) measured 8.8 dB of "ripple" against
+    a 6.2 dB shortfall, 2.2 dB about a cubic. The band is not shortened instead. Crest to
+    trough shrinks with the number of bins even on noise, so ending it at the crossover lowered
+    every yardstick and admitted a broadband negative on the corpus. A cubic keeps the band the
+    1x boundary was calibrated on and leaves the negatives where they were: at most 0.76x about
+    a cubic against 0.77x about a line, with every real and filtered title at 1.08x and up.
+    Each channel's own rule (`channels_missing_low_end`) keeps the line.
+
     Crest to trough, not a one-sided dip, because the reference sits near the 90th percentile
     of the spectrum, on the crests: a shortfall measured from it spans the whole swing. On the
     negative corpus (IMPROVEMENT_PLAN E2) every unfiltered title's low-end deficit came in
@@ -847,7 +865,7 @@ def passband_ripple_db(
         return None
     smooth = smooth_unexcluded(response, freqs, bands, 15, levels=True)[band]
     octaves = np.log2(freqs[band])
-    about = smooth - np.polyval(np.polyfit(octaves, smooth, 1), octaves)
+    about = smooth - np.polyval(np.polyfit(octaves, smooth, trend_degree), octaves)
     return float(np.max(about) - np.min(about)), (low, high)
 
 
@@ -1550,7 +1568,12 @@ def analyse(
                 f"programme (tracking stops at {diagnosis.noise_floor_hz:.1f} Hz), so there "
                 "is no bass passband to restore towards; restoration withheld"
             )
-        texture = passband_ripple_db(material, params, diagnosis.noise_floor_hz)
+        texture = passband_ripple_db(
+            material,
+            params,
+            diagnosis.noise_floor_hz,
+            trend_degree=MIX_TEXTURE_TREND_DEGREE,
+        )
         low_end = low_end_deficit_db(material, params, diagnosis.noise_floor_hz)
         if texture is not None and low_end is not None:
             ripple, (edge_low, edge_high) = texture

beqforge-0.2.4/packaging/designer/beqforge-designer.cmd

@@ -0,0 +1,33 @@
+@echo off
+rem Runs the beqforge designer for beqdesigner on Windows: `beqforge serve-designer`, with the
+rem container image's defaults (README, "Running the designer on Windows"). Keep this file
+rem beside the release's beqforge-windows-x86_64.exe and double-click it, or run it from a
+rem prompt with any extra serve-designer options, e.g. `beqforge-designer.cmd --record-dir D:\beq\records`.
+rem
+rem Every BEQFORGE_* variable already set in the environment wins over the defaults below.
+setlocal
+
+rem beqdesigner's work directory, as this machine sees it, so audio arrives by reference rather
+rem than inline. Uncomment and point it at the folder mounted into beqdesigner's container.
+rem if not defined BEQFORGE_SHARED_ROOT set "BEQFORGE_SHARED_ROOT=D:\beq\work"
+
+rem How many titles to design at once, if this machine can take more than one (0.2.4 on).
+rem if not defined BEQFORGE_WORKERS set "BEQFORGE_WORKERS=2"
+
+if not defined BEQFORGE_HOST set "BEQFORGE_HOST=0.0.0.0"
+if not defined BEQFORGE_PORT set "BEQFORGE_PORT=8420"
+if not defined BEQFORGE_CACHE_DIR set "BEQFORGE_CACHE_DIR=%LOCALAPPDATA%\beqforge\cache"
+
+set "EXE=%~dp0beqforge-windows-x86_64.exe"
+if not exist "%EXE%" set "EXE=%~dp0beqforge.exe"
+if not exist "%EXE%" (
+    echo beqforge-windows-x86_64.exe was not found beside %~nx0
+    pause
+    exit /b 1
+)
+
+"%EXE%" serve-designer %*
+set "STATUS=%ERRORLEVEL%"
+rem keep the window open on a startup error, so a double-click shows why
+if not "%STATUS%"=="0" pause
+exit /b %STATUS%

{beqforge-0.2.2 → beqforge-0.2.4}/plans/done-design-and-pipeline.md

@@ -748,6 +748,37 @@ beside the answer or the decline (probe unchanged; no decision touched).
     caller's; `beqforge_revision` is already in every response for it.
 
 
+## Several designs at once, advertised on `/health` (18 October 2026)
+
+A Windows machine that could design two titles at once was added beside the container as a
+second endpoint, and the only way to use it was two servers on two ports: one server had a
+single design worker. Saying how many each endpoint takes in beqdesigner's profile also put a
+fact about the designer's host in the caller's configuration.
+
+`serve-designer --workers N` (`BEQFORGE_WORKERS`, 1-8, the range beqdesigner accepts for an
+endpoint's `parallel`) now runs N `_DesignWorker`s, each still one spawned, single-threaded
+process. A request takes the next idle worker and waits for one when none is, so arrival order
+is kept and a worker that dies fails only its own request. `/health` gains `"parallel": N` for
+a caller to size its sends from; beqdesigner was sent the caller-side proposal. With N > 1 each
+worker's fit pool is `filters.FIT_WORKERS // N` (`fit_share`), so N designs do not each claim
+the whole machine; an explicit `BEQ_FIT_WORKERS` is left as each design's own. `_run_fits`
+returns results in submission order from fixed seeds, so pool size moves timing and never an
+answer. Nothing under `beqforge/` changed, so the decision regression probe does not apply.
+
+* **Checks.** New tests: with two workers a quick request is answered while a real design is
+  still running on the other (the same test fails with one worker, so it distinguishes them),
+  `/health` reports `parallel`, a count outside 1-8 is refused by the server and the CLI, the
+  option comes from the environment, and the fit share. Server, startup, image and parallel-fit
+  tests: 61 passed. `tools/smoke_test_exe.py` now starts the executable with `--workers 2` and
+  requires `parallel: 2`. Its three requests alternate between the workers, so both design for
+  real inside the frozen build and the cache hit is one worker reusing the other's entries. A
+  Linux PyInstaller build passed it, with no process left after shutdown. Windows and macOS
+  are covered by the release workflow's smoke test, not run here.
+* **Windows packaging.** `packaging/designer/beqforge-designer.cmd` starts the release's
+  Windows executable with the container's defaults and is attached to each release; the README
+  gains "Running the designer on Windows".
+
+
 ## The designer server answers `/health` during a design (17 October 2026)
 
 A deployed image went unhealthy while it designed correctly. `serve-designer` was a plain

beqforge-0.2.4/plans/parameter-space-optimisation.md

@@ -0,0 +1,75 @@
+# Optimising a filter's parameters for several device profiles at once
+
+**Status: design, not built.** A request from beqdesigner (October 2026), for a feature in its main window: a filter
+designer picks one or more device profiles, sees what each does to the filter, and asks for the filter to be optimised
+before it is published. The person who owns both projects decided that the search belongs here, in `beqoptimiser`, and
+beqdesigner only provides the interface. Parameter search is already listed as a follow-up in
+[F2-catalogue-filter-optimisation.md](F2-catalogue-filter-optimisation.md).
+
+## What is different from `optimise()`
+
+`optimise()` searches the coefficients of one cascade for one rate and precision, and returns custom SOS. This request
+needs:
+
+1. **Parameters out, not coefficients.** The result is each section's `freq`, `q` and `gain` (and its type unchanged).
+   A BEQ is published and loaded as parameters: beqdesigner's projects and exports, the catalogue, and ezbeq (which
+   rebuilds RBJ coefficients from the parameters at each device's rate when it has none published for it) all carry
+   parameters. Optimised parameters therefore need no new catalogue schema and reach every consumer as they are.
+2. **Several profiles jointly.** The same parameters are realised on every device. The search minimises the worst
+   matching-band error across all the profiles the caller passes (a minimax), so a change that helps one device cannot
+   quietly make another worse. The result reports each profile's error before and after.
+3. **Representable parameters.** Only values beqdesigner can show and the exports keep: `freq` to 0.01 Hz, `q` (and a
+   shelf's `S`) to 0.0001, `gain` to 0.01 dB. Search on that grid, or round and re-validate, so the result is exactly
+   what is published.
+
+## Proposed interface
+
+```python
+optimise_parameters(
+    sections,                 # the cascade as authored: beqoptimiser.core.Section (type, freq, q, gain), in order
+    *,
+    profiles,                 # [(rate, precision), ...]: 48000 or 96000, with Float32() or FixedPoint(i, f)
+    settings=None,            # Settings: margin, band, plus the parameter bounds below
+) -> ParameterResult
+```
+
+`ParameterResult` carries the outcome (with the same `replacement`/`improvement`/`no_replacement` rules as
+`optimise()`), the new sections when there is one, and per profile: the original error, the candidate's error and its
+guard (out-of-band) error, with the numerical version and settings for provenance.
+
+* **Reference:** each section's ideal float64 RBJ response, from the authored parameters, as now.
+* **Realised:** for each profile, the coefficients computed from the candidate parameters at that rate in float64,
+  then stored with that profile's precision (`quantise`), as a device that receives parameters (or coefficients
+  computed from them) would hold them.
+* **Bounds:** the parameters may only move as far as keeps the filter the author's: proposed defaults of ±1% in
+  frequency, ±2% in Q and ±0.1 dB in gain per section, configurable. A result outside them is not a correction of
+  the same filter.
+* **Sections it cannot change:** the request may contain other biquads (pass filters, a gain stage). They stay
+  fixed but count in the cascade's response; a cascade with nothing searchable returns `no_replacement`.
+
+## Open points for this repository to decide
+
+* **Whose RBJ:** the coefficients must be computed as the consumers compute them. beqdesigner (`model/iir.py`),
+  `beq_common.biquad` and ezbeq each implement the cookbook; check that they agree, including the shelf Q/S conversion,
+  to the precision a profile can resolve. If they do not, name the one a profile models.
+* **Search method:** a coordinate or pattern search on the parameter grid, a scalar minimiser per parameter as now, or
+  something else; deterministic, bounded and cacheable as `optimise()` is.
+* **Whether it ever helps:** benchmark against direct-coefficient search on the catalogue's float32/96 kHz worst cases
+  (e.g. the 5 Hz Q 6 peak the 2x4 HD pilot measured). Parameter search may recover little where the coefficient grid is
+  coarse; the outcome rules already report that honestly as `no_replacement`.
+
+## What beqdesigner will build around it
+
+* Device profiles: one per device it exports to (miniDSP HD-class: float32 at 96 kHz; earlier miniDSPs: Q5.23 fixed
+  point at 48 kHz; HTP-1 and JRiver compute in double precision, so nothing to show), plus profiles a user defines
+  (rate and storage). It uses `beqoptimiser`'s `Float32`/`FixedPoint` and `magnitude` for part (a).
+* Part (a), now: the main chart shows the filter as each chosen profile realises it, and its error against the ideal.
+* Part (b), after this ships: an *Optimise for devices* action on the filter, which calls `optimise_parameters` with the
+  ticked profiles, shows the before/after errors per profile and lets the designer accept the new parameters.
+
+## Completion criteria
+
+* `optimise_parameters` in `beqoptimiser` with tests covering: both rates, both precisions, the joint (minimax)
+  objective protecting each profile, the parameter grid and bounds, fixed non-searchable sections, and cache identity.
+* A short benchmark against `optimise()` on the catalogue report's worst float32 cases, recorded here.
+* Released in a `beqforge` version beqdesigner can pin.