beqforge 0.2.8__tar.gz → 0.2.9__tar.gz

{beqforge-0.2.8 → beqforge-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: beqforge
-Version: 0.2.8
+Version: 0.2.9
 Summary: Audio-derived BEQ design, published filter optimisation and DSP validation
 License-File: LICENCE.md
 Requires-Python: <3.15,>=3.13

{beqforge-0.2.8 → beqforge-0.2.9}/TODO.md

@@ -43,7 +43,9 @@ are retained so records and code comments remain traceable. Completed items are
 | 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 | Keep run records and logs by default | open | `serve-designer` keeps no run record and no log file unless told to, so the Windows designer's 432 library titles (111 declines) have no records and can be reviewed only from their responses. Default records and a rotating log to the platform's per-user data directory (as the `.cmd` already does for the cache), set and declare `/records` in the image, report `record_dir` on `/health`. See [the handoff](plans/default-record-and-log-locations.md). |
-| 28 | Fit sensitivity to arithmetic | open | The same request can get a different filter on a different processor. On the synthetic BW4 24 Hz title, `counterfactual` gave 2 sections here and 3 on Linux and macOS CI; `parametric`'s boost was 15.21 dB on this AVX-512 machine, 15.78 dB with Haswell BLAS kernels and 16.49 dB on CI. `flatten` matched everywhere. It's repeatable on one machine, so last-digit differences grow into a different local optimum. This already matters in practice: beqdesigner's library run uses two designers on different hardware (the unraid container and the Windows exe), so the same title may come back different depending on which one designed it. beqdesigner's out-of-date filter compares only design version and settings, so it can't catch that. Measure it on real titles first: run the baseline set under `OPENBLAS_CORETYPE=Haswell` (or on another CPU) and compare verdicts and corrected curves. Then decide whether the fit needs a deterministic tie-break or a conditioning fix, or whether only the golden's coverage does. See [the correction](plans/design-version.md#correction-after-the-v026-release-tests). |
+| 28 | Fit sensitivity to arithmetic | open | The same request can get a different filter on a different processor. On the synthetic BW4 24 Hz title, `counterfactual` gave 2 sections here and 3 on Linux and macOS CI; `parametric`'s boost was 15.21 dB on this AVX-512 machine, 15.78 dB with Haswell BLAS kernels and 16.49 dB on CI. `flatten` matched everywhere. It's repeatable on one machine, so last-digit differences grow into a different local optimum. This already matters in practice: beqdesigner's library run uses two designers on different hardware (the unraid container and the Windows exe), so the same title may come back different depending on which one designed it. beqdesigner's out-of-date filter compares only design version and settings, so it can't catch that. Measure it on real titles first: run the baseline set under `OPENBLAS_CORETYPE=Haswell` (or on another CPU) and compare verdicts and corrected curves. Then decide whether the fit needs a deterministic tie-break or a conditioning fix, or whether only the golden's coverage does. See [the correction](plans/design-version.md#correction-after-the-v026-release-tests). Measured after TODO 29's fix 2: the fitter is BLAS-independent, and on the 11 baseline titles an emulated older CPU changed only 28 Years Later's parametric (a 0.001 dB target difference amplified by the fit); rounding targets to 0.001 dB before fitting is the cheap thing to try ([measurements](plans/library-review-improvements.md#row-28-different-answers-by-machine-after-fix-2)). |
+| 29 | Library review improvements | in progress | From beqdesigner's review of all 279 declines in its full-library run: F2's unmeasured floor still reported as a measurement (4 titles, live on 0.2.5), a near-miss over-lift rejecting the whole design (7), the tilt check (5), the texture retune cases for row 26 (9), the absolute scene margin (4), the dialogue-band reference (2), a plateau at the filter floor (1), DC offset, infrasonic plateaus, and different answers by machine. Evidence, ids and run records per item in [the proposal](plans/library-review-improvements.md). Fix 1 (the unmeasured floor wording) and fix 2 (the fit scored on the published parameters; The Quiet Girl now designs, Bugonia now declines on coverage below 8.1 Hz) fix 3 (mains-hum notches filled before the deficit is measured) and fix 4 (the fit bounded by the judge's over-lift bar; Crazy Heart's flatten now passes) O2 (an infrasonic plateau refused as the reference) and O1 (a stepping DC offset reported) are done; see [the outcomes](plans/library-review-improvements.md#outcomes). The research items are measured and none is built: see [the research](plans/library-review-improvements.md#research-after-the-fixes) (1b has no contained fix; 6 rescues one plausible title; 7 is item 5; 5 and 4 are experiments for the protocol, corpus and E10). |
+| 30 | Contract 1.5: design adjustments | built, unreleased | beqdesigner can ask for a different design per title: ignore a band, a floor, a boost cap, a tilted goal, a note. `beqforge/adjustments.py` answers each, on branch `contract-1.5-adjustments`: default answers unchanged (golden; probe `--tol 0`, all 11 titles), 936 tests pass. Left: merge, and a release, which turns the browser's adjustments on. See [the outcome](plans/contract-1.5-adjustments.md#outcome). |
 
 ## Review evidence
 

{beqforge-0.2.8 → beqforge-0.2.9}/beq_common/__init__.py

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

{beqforge-0.2.8 → beqforge-0.2.9}/beqforge/AGENTS.md

@@ -33,6 +33,7 @@ still holds: no other API, no other service, and the server is a thin transport
 | `beqforge/harness.py` | Synthetic ground truth — known-filter injection and constructed negatives. |
 | `beqforge/verify.py` | Applies a design and measures the corrected low end, **including the error the device's own coefficient rounding adds** — so what is judged is what will play. **The only check that can say a filter is wrong rather than merely inaccurate.** |
 | `beqforge/diagnose.py` | Per-channel decomposition: mix shares, the level-independence test (R2), band tracking, and each channel's own plateau reference. Where the evidence for a rolloff actually is. |
+| `beqforge/dc_offset.py` | A channel's DC offset and the steps in it a correction would lift into thumps (TODO 29, O1). Report-only: `analyse` adds one evidence note per channel found, no decision reads it. A static offset needs nothing (headroom filters the sub feed with the full transfer, 0 Hz included), and a DC-blocking high-pass does not touch a step's 4-20 Hz transient. Three tests, no dB constant: a persistent offset whose step would reach the channel's 90th-percentile programme level in 4-20 Hz, a step whose transient does, and (with other channels) one that stands out of every other channel near it. |
 | `beqforge/accept.py` | The acceptance model. The cliff, flatness, turnover and overshoot tests are comparative and so need no calibrated threshold; the shape request (`target_tilt_db_per_octave` and its tolerances) is a stated preference; realisability is judged on the curve the device will play rather than against a drift constant. Tilt, level and extent judge against *intent* (`before_db` + the evidence-priced target), not flat, so a partial correction is judged on whether it achieved what it was licensed to. `recovered_fraction` and `shaping_fraction` report how much of the deficit was licensed and how much of the correction's peak lies below the level-independence floor — record-only diagnostics, not in the designer response; `Candidate.confidence` is a separate, uncalibrated ordinal (`pipeline.correction_evidence_score`), not derived from either. Headroom (`required_offset_db`) is reported, never gated. |
 | `beqforge/pipeline.py` | The repeatable process — diagnose, propose, fit, judge. Holds the `STRATEGIES` registry. |
 | `beqforge/cache.py` | Stage cache — the analysis, and any strategy declaring `cache_modules`. On by default; keyed per stage so work on the fitter does not drop the analysis. |
@@ -41,6 +42,7 @@ still holds: no other API, no other service, and the server is a thin transport
 | `beqforge/beqd.py` | Export to a `.beq` beqdesigner project. A separate job from the record: idiomatic in their UI, allowed to be lossy. |
 | `beqforge/cli.py` | `beqforge <subcommand> ...` — the installed entry point. Strips the subcommand off argv and hands the rest to the matching script in `tools/` unchanged. |
 | `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), `fit` (how closely the filter as played delivers the boost the content supports — a match to the target, not a verdict on it) and `alternatives` (why each other candidate lost). Reads the `Report`; measures and decides nothing. |
+| `beqforge/adjustments.py` | Contract 1.5's adjustments: what a request asks a design to change (`exclude_band`, `floor`, `max_boost`, `goal_tilt`, `note`), set on that request's `PipelineParams` only, and the answer to each (`honoured`, `adapted`, `declined`, `not_understood`); `/health`'s `adjustment_kinds`. Pure. See `plans/contract-1.5-adjustments.md`. |
 | `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; 1.3: `residual_db` and its companions come from `Candidate.target_fit`, never `fit_error_db`; 1.4: `design_version` (`DESIGN_VERSION`, bumped only by a change that can alter an answer, guarded by `tests/test_design_golden.py`), `design_settings` (`design_settings_digest`, the non-default server settings that can change an answer) and `designer_build` on every response), 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 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 the logical processors less one, divided by N and capped at `filters.FIT_WORKERS` (`fit_share`), unless `BEQ_FIT_WORKERS` is set; `--cores N` instead caps the designs' total at N, split evenly, still at most `filters.FIT_WORKERS` each: concurrent designs are what can use SMT threads, and 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`, `parallel`, and 1.4's `design_version`, `design_settings`, `design_settings_detail` and `designer_build`. |

{beqforge-0.2.8 → beqforge-0.2.9}/beqforge/accept.py

@@ -202,8 +202,10 @@ class AcceptParams:
     Kept because the fitter still screens on it to *prefer* a robust cascade among equals, which
     is a legitimate tiebreak and the reason cancelling cascades rarely reach acceptance at all.
     The p90 is over `drift_samples` jitters of the published parameters — note that this explores
-    coefficient sets near the published one rather than the rounding the published filter itself
-    undergoes, which `verify` measures directly and which comes to 0.006-0.014 dB."""
+    coefficient sets near the published one rather than the device's rounding of the published
+    filter itself, which `verify` measures directly and which the fit now scores on the published
+    parameters too (TODO 29). That rounding is not negligible: on a steep cascade it can run to
+    several dB, which is why the fit has to see it."""
 
 
 @dataclass(frozen=True, slots=True)
@@ -387,6 +389,33 @@ def turnover_db_per_octave(
     return slope, material, float(freqs[peak])
 
 
+def overlift_bar_db(
+    correction: Correction, params: AcceptParams
+) -> tuple[np.ndarray, np.ndarray]:
+    """The guarded bins and the most the corrected curve may reach in each: `assess`'s over-lift bar.
+
+    The guard runs from the bottom of the design grid to the top of the judged band, below the
+    judged floor too, because a shelf can still boost that region. In each bin the corrected
+    curve may reach the higher of the requested shape and the material, plus the level
+    tolerance and half the material's own roughness. Depends on the material and the judged
+    band only, never on a filter, so the fitter scores against the same bar before anything is
+    fitted (`overlift_allowance` in `pipeline`).
+    """
+    guard = (correction.freqs >= DESIGN_GRID[0]) & (
+        correction.freqs <= correction.band_hz[1]
+    )
+    slack = spectral_roughness(correction, params.roughness_degree) / 2.0
+    bar = (
+        np.maximum(
+            correction.requested_db(params.target_tilt_db_per_octave)[guard],
+            correction.before_db[guard],
+        )
+        + params.level_tolerance_db
+        + slack
+    )
+    return guard, bar
+
+
 def spectral_roughness(correction: Correction, degree: int = 3) -> float:
     """How far the *input* departs from a smooth trend over the judged band.
 
@@ -580,19 +609,7 @@ def assess(
             "rolloff"
         )
 
-    # Guard below the judged floor too: a shelf can still boost that region.
-    guard = (correction.freqs >= DESIGN_GRID[0]) & (
-        correction.freqs <= correction.band_hz[1]
-    )
-    slack = spectral_roughness(correction, params.roughness_degree) / 2.0
-    bar = (
-        np.maximum(
-            correction.requested_db(params.target_tilt_db_per_octave)[guard],
-            correction.before_db[guard],
-        )
-        + params.level_tolerance_db
-        + slack
-    )
+    guard, bar = overlift_bar_db(correction, params)
     overshoot = correction.after_db[guard] - bar
     worst = int(np.argmax(overshoot))
     if _at(float(overshoot[worst]), quantum) > 0.0:

beqforge-0.2.9/beqforge/adjustments.py

@@ -0,0 +1,365 @@
+"""Contract 1.5's adjustments: what a caller asks a design to change, and beqforge's answer to each.
+
+beqdesigner's `designer-interface.md` §2 "Adjustments" and §3 "Adjustment outcomes"; the handoff that set out this
+mapping is [plans/contract-1.5-adjustments.md](../plans/contract-1.5-adjustments.md). Each kind lands on a dial
+`serve-designer` already has, set for this one request:
+
+* `exclude_band` (`low_hz`, `high_hz`): appended to `PipelineParams.exclude_bands_hz`, the list `--exclude` fills.
+* `floor` (`hz`): `PipelineParams.lowest_frequency_hz`, raised (never lowered below the server's).
+* `max_boost` (`db`): `PipelineParams.max_target_boost_db`, a ceiling on every strategy's target beside the evidence's
+  (`pipeline.priced_by_evidence`), and `parametric_max_boost_db` and every `restore_caps_db` capped at it.
+* `goal_tilt` (`db_per_octave`): `AcceptParams.target_tilt_db_per_octave`, which `--goal-tilt` sets, for this request.
+* `note`: free text, kept in the answer's reason and not acted on.
+
+Nothing here can make beqforge publish what its evidence does not support (§4): every kind narrows or weakens a
+design, or changes the goal the judge then holds the design to. A request with no adjustments is not touched, so its
+answer is the 1.4 answer. Pure: no I/O, no fitting.
+"""
+
+import dataclasses
+import math
+from dataclasses import dataclass
+
+import numpy as np
+
+from beqforge.filters import biquad_sos, magnitude_db
+from beqforge.pipeline import DESIGN_GRID, PipelineParams, Report
+
+KINDS = ("exclude_band", "floor", "max_boost", "goal_tilt", "note")
+OUTCOMES = ("honoured", "adapted", "declined", "not_understood")
+
+MAX_TILT_DB_PER_OCTAVE = 3.0
+"""The steepest goal tilt taken. `AcceptParams.target_tilt_db_per_octave` documents roughly 6 dB of headroom for
++2 dB/octave; past 3 the goal asks more of the bottom than any title in the baseline set had to give."""
+
+
+@dataclass(frozen=True, slots=True)
+class DesignAdjustment:
+    """§2: one change asked for."""
+
+    id: str
+    kind: str
+    params: dict
+    text: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class AdjustmentOutcome:
+    """§3: what was done with one adjustment."""
+
+    id: str
+    outcome: str
+    applied: dict | None = None
+    reason: str | None = None
+
+
+def adjustments_from_json(body: object) -> tuple[DesignAdjustment, ...]:
+    """The request's `adjustments`, checked for shape only (§2: an unknown kind or a bad parameter is answered, not
+    refused). Absent or null is none.
+
+    Raises:
+        TypeError: when it is not a list of objects, or one's `params` is not an object.
+        ValueError: when one has no `id` or `kind`, or two share an id.
+    """
+    if body is None:
+        return ()
+    if not isinstance(body, list):
+        raise TypeError("adjustments must be a list")
+    seen: set[str] = set()
+    adjustments = []
+    for i, item in enumerate(body):
+        if not isinstance(item, dict):
+            raise TypeError(f"adjustments[{i}] must be an object")
+        ident, kind, params = item.get("id"), item.get("kind"), item.get("params", {})
+        if (
+            not isinstance(ident, str)
+            or not ident
+            or not isinstance(kind, str)
+            or not kind
+        ):
+            raise ValueError(f"adjustments[{i}] needs a non-empty id and kind")
+        if not isinstance(params, dict):
+            raise TypeError(f"adjustments[{i}].params must be an object")
+        if ident in seen:
+            raise ValueError(f"adjustment id {ident!r} is used twice")
+        seen.add(ident)
+        text = item.get("text")
+        adjustments.append(
+            DesignAdjustment(
+                ident, kind, dict(params), text if isinstance(text, str) else None
+            )
+        )
+    return tuple(adjustments)
+
+
+def outcome_to_json(outcome: AdjustmentOutcome) -> dict:
+    return {
+        "id": outcome.id,
+        "outcome": outcome.outcome,
+        "applied": outcome.applied,
+        "reason": outcome.reason,
+    }
+
+
+def kinds_for(params: PipelineParams) -> dict[str, dict]:
+    """`/health`'s `adjustment_kinds` (§7.1): each kind this server takes, its parameters' defaults this server's own
+    settings, so a caller's form opens on what the server would do."""
+    low, high = params.diagnose.band_hz
+    return {
+        "exclude_band": {
+            "description": "Leave a frequency range alone: neither evidence of a rolloff nor something to correct.",
+            "params": {
+                "low_hz": {
+                    "type": "number",
+                    "unit": "Hz",
+                    "minimum": low,
+                    "maximum": high,
+                },
+                "high_hz": {
+                    "type": "number",
+                    "unit": "Hz",
+                    "minimum": low,
+                    "maximum": high,
+                },
+            },
+        },
+        "floor": {
+            "description": "Restore nothing below this frequency: no section is placed lower.",
+            "params": {
+                "hz": {
+                    "type": "number",
+                    "unit": "Hz",
+                    "minimum": params.lowest_frequency_hz,
+                    "maximum": high / 2,
+                    "default": params.lowest_frequency_hz,
+                },
+            },
+        },
+        "max_boost": {
+            "description": "Boost no more than this anywhere.",
+            "params": {
+                "db": {
+                    "type": "number",
+                    "unit": "dB",
+                    "minimum": 1.0,
+                    "maximum": max(params.restore_caps_db),
+                    "default": params.parametric_max_boost_db,
+                },
+            },
+        },
+        "goal_tilt": {
+            "description": "Tilt the goal towards the bottom: positive for more bass than flat, negative for less.",
+            "params": {
+                "db_per_octave": {
+                    "type": "number",
+                    "unit": "dB/oct",
+                    "minimum": -MAX_TILT_DB_PER_OCTAVE,
+                    "maximum": MAX_TILT_DB_PER_OCTAVE,
+                    "default": params.accept.target_tilt_db_per_octave,
+                },
+            },
+        },
+        "note": {
+            "description": "Anything else, in words. Kept with the design; not acted on."
+        },
+    }
+
+
+def _number(params: dict, name: str) -> float | None:
+    value = params.get(name)
+    if (
+        isinstance(value, bool)
+        or not isinstance(value, (int, float))
+        or not math.isfinite(value)
+    ):
+        return None
+    return float(value)
+
+
+def _declined(adjustment: DesignAdjustment, reason: str) -> AdjustmentOutcome:
+    return AdjustmentOutcome(adjustment.id, "declined", None, reason)
+
+
+def apply_adjustments(
+    params: PipelineParams, adjustments: tuple[DesignAdjustment, ...]
+) -> tuple[PipelineParams, dict[str, AdjustmentOutcome]]:
+    """The parameters this request designs with, and a provisional outcome for every adjustment (`finish_outcomes`
+    revisits them once the design is made). Order does not matter: the result is the same whichever comes first,
+    except that of two asks of a kind that takes one value, the first by id is used and the other declined."""
+    outcomes: dict[str, AdjustmentOutcome] = {}
+    band_low, band_high = params.diagnose.band_hz
+    excluded = list(params.exclude_bands_hz)
+    floor, cap, tilt = params.lowest_frequency_hz, None, None
+    taken: dict[str, str] = {}
+    for adjustment in sorted(adjustments, key=lambda a: a.id):
+        kind, p = adjustment.kind, adjustment.params
+        if kind in ("floor", "max_boost", "goal_tilt") and kind in taken:
+            outcomes[adjustment.id] = _declined(
+                adjustment, f"only one {kind} is taken: {taken[kind]} was used"
+            )
+            continue
+        if kind == "exclude_band":
+            low, high = _number(p, "low_hz"), _number(p, "high_hz")
+            if low is None or high is None or low >= high:
+                outcomes[adjustment.id] = _declined(
+                    adjustment, "low_hz and high_hz must be numbers, low below high"
+                )
+                continue
+            used = (max(low, band_low), min(high, band_high))
+            if used[0] >= used[1]:
+                outcomes[adjustment.id] = _declined(
+                    adjustment,
+                    f"{low:g}-{high:g} Hz is outside the band analysed ({band_low:g}-{band_high:g} Hz)",
+                )
+                continue
+            excluded.append(used)
+            applied = {"low_hz": used[0], "high_hz": used[1]}
+            outcomes[adjustment.id] = (
+                AdjustmentOutcome(adjustment.id, "honoured", applied)
+                if used == (low, high)
+                else AdjustmentOutcome(
+                    adjustment.id,
+                    "adapted",
+                    applied,
+                    f"narrowed to the band analysed ({band_low:g}-{band_high:g} Hz)",
+                )
+            )
+        elif kind == "floor":
+            hz = _number(p, "hz")
+            if hz is None or hz <= 0:
+                outcomes[adjustment.id] = _declined(
+                    adjustment, "hz must be a positive number"
+                )
+                continue
+            if hz >= band_high / 2:
+                outcomes[adjustment.id] = _declined(
+                    adjustment,
+                    f"{hz:g} Hz leaves too little of the band analysed (to {band_high:g} Hz) to correct",
+                )
+                continue
+            taken[kind] = adjustment.id
+            if hz < params.lowest_frequency_hz:
+                outcomes[adjustment.id] = AdjustmentOutcome(
+                    adjustment.id,
+                    "adapted",
+                    {"hz": params.lowest_frequency_hz},
+                    f"nothing is placed below {params.lowest_frequency_hz:g} Hz on any title: nothing was measured there",
+                )
+                continue
+            floor = hz
+            outcomes[adjustment.id] = AdjustmentOutcome(
+                adjustment.id, "honoured", {"hz": hz}
+            )
+        elif kind == "max_boost":
+            db = _number(p, "db")
+            if db is None or db <= 0:
+                outcomes[adjustment.id] = _declined(
+                    adjustment, "db must be a positive number"
+                )
+                continue
+            taken[kind] = adjustment.id
+            cap = db
+            outcomes[adjustment.id] = AdjustmentOutcome(
+                adjustment.id, "honoured", {"db": db}
+            )
+        elif kind == "goal_tilt":
+            rate = _number(p, "db_per_octave")
+            if rate is None:
+                outcomes[adjustment.id] = _declined(
+                    adjustment, "db_per_octave must be a number"
+                )
+                continue
+            if abs(rate) > MAX_TILT_DB_PER_OCTAVE:
+                outcomes[adjustment.id] = _declined(
+                    adjustment,
+                    f"a tilt beyond ±{MAX_TILT_DB_PER_OCTAVE:g} dB/oct is not taken",
+                )
+                continue
+            taken[kind] = adjustment.id
+            tilt = rate
+            outcomes[adjustment.id] = AdjustmentOutcome(
+                adjustment.id, "honoured", {"db_per_octave": rate}
+            )
+        elif kind == "note":
+            outcomes[adjustment.id] = AdjustmentOutcome(
+                adjustment.id,
+                "not_understood",
+                None,
+                "a note is kept with the design, not acted on",
+            )
+        else:
+            outcomes[adjustment.id] = AdjustmentOutcome(
+                adjustment.id,
+                "not_understood",
+                None,
+                f"beqforge takes {', '.join(KINDS)}; not {kind!r}",
+            )
+    changes: dict = {}
+    if excluded != list(params.exclude_bands_hz):
+        changes["exclude_bands_hz"] = tuple(excluded)
+    if floor != params.lowest_frequency_hz:
+        changes["lowest_frequency_hz"] = floor
+    if cap is not None:
+        changes["max_target_boost_db"] = cap
+        changes["parametric_max_boost_db"] = min(params.parametric_max_boost_db, cap)
+        changes["restore_caps_db"] = tuple(
+            sorted({min(c, cap) for c in params.restore_caps_db})
+        )
+    if tilt is not None:
+        changes["accept"] = dataclasses.replace(
+            params.accept, target_tilt_db_per_octave=tilt
+        )
+    return (dataclasses.replace(params, **changes) if changes else params), outcomes
+
+
+def peak_boost_db(filters: list, fs: float) -> float:
+    """The most a cascade boosts anywhere on the design grid, as realised at `fs`."""
+    if not filters:
+        return 0.0
+    return float(np.max(magnitude_db(biquad_sos(list(filters), fs), DESIGN_GRID, fs)))
+
+
+def finish_outcomes(
+    outcomes: dict[str, AdjustmentOutcome],
+    adjustments: tuple[DesignAdjustment, ...],
+    report: Report,
+    params: PipelineParams,
+) -> list[AdjustmentOutcome]:
+    """The answers in the request's order, once the design is made: a cap the realised filters still go past is
+    `adapted` (the fit meets a target within a tolerance, so it can overshoot a little: say by how much), and an
+    adjustment that was applied when the design then declined says so (it may be why the evidence left was too thin)."""
+    accepted = report.accepted
+    peak = (
+        peak_boost_db(accepted.filters, params.realisation.fs)
+        if accepted is not None
+        else None
+    )
+    finished = []
+    for adjustment in adjustments:
+        outcome = outcomes[adjustment.id]
+        if (
+            adjustment.kind == "max_boost"
+            and outcome.outcome == "honoured"
+            and peak is not None
+            and outcome.applied is not None
+            and peak
+            > outcome.applied["db"]
+            + params.residual_target_db  # within the fit's own tolerance: met
+        ):
+            outcome = AdjustmentOutcome(
+                adjustment.id,
+                "adapted",
+                {"db": round(peak, 2)},
+                f"capped at {outcome.applied['db']:g} dB; the realised design peaks at {peak:.1f} dB",
+            )
+        elif (
+            accepted is None
+            and outcome.outcome in ("honoured", "adapted")
+            and not outcome.reason
+        ):
+            outcome = dataclasses.replace(
+                outcome,
+                reason="applied; with it the evidence left did not support a design (see the decline)",
+            )
+        finished.append(outcome)
+    return finished

{beqforge-0.2.8 → beqforge-0.2.9}/beqforge/cache.py

@@ -291,6 +291,7 @@ def analysis_to_json(analysis: Analysis) -> dict[str, Any]:
             "level_spread_db": _pack(diagnosis.level_spread_db),
             "filter_floor_hz": _num(diagnosis.filter_floor_hz),
             "noise_floor_hz": _num(diagnosis.noise_floor_hz),
+            "tracking_measured": bool(diagnosis.tracking_measured),
         },
         "envelopes": {
             "freqs": _pack(envelopes.freqs),
@@ -342,6 +343,7 @@ def analysis_from_json(raw: dict[str, Any]) -> Analysis:
         level_spread_db=_unpack(d["level_spread_db"]),
         filter_floor_hz=_back(d["filter_floor_hz"]),
         noise_floor_hz=_back(d["noise_floor_hz"]),
+        tracking_measured=bool(d.get("tracking_measured", True)),
     )
     envelopes = Envelopes(
         freqs=_unpack(e["freqs"]),

beqforge-0.2.9/beqforge/dc_offset.py

@@ -0,0 +1,130 @@
+"""A channel's DC offset, and the steps in it a correction would turn into thumps (TODO 29, O1).
+
+Reported, never decided on. A static offset needs nothing here: `measure_headroom` filters the
+sub feed with the device's full transfer, 0 Hz included, so the lifted offset is already in the
+measured peak. What it does not show is an offset that *steps*. Each step is an infrasonic
+transient, and a correction boosting the bottom octaves lifts it by its gain there: Desperately
+Seeking Susan's FR carries -48 dBFS of drifting offset whose steps stand 15-22 dB above FL in
+4-20 Hz, heard as thumps once corrected. A DC-blocking high-pass would not help — at 1, 3 or
+5 Hz it left those transients where they were, since a step's energy reaches far above any
+blocker's corner — so the honest response is to say so.
+"""
+
+from dataclasses import dataclass
+
+import numpy as np
+from scipy import ndimage, signal
+
+from beqforge.material import Material
+
+STEP_BAND_HZ = (4.0, 20.0)
+"""Where a step's transient is measured: the band a correction boosts most."""
+
+LEVEL_HALF_WIDTH_S = 15
+"""Half the window, in seconds, the slow DC level is the median over. Long enough that a scene's
+bass does not move it, short enough to follow an offset that changes at an edit."""
+
+
+@dataclass(frozen=True, slots=True)
+class DcSteps:
+    """One channel's offset and the steps in it that stand out of the programme."""
+
+    channel: str
+    offset_dbfs: float
+    """The channel's typical slow DC level, re full scale."""
+    steps_s: tuple[int, ...]
+    """Where each step is, to the second."""
+    worst_excess_db: float
+    """How far the largest step's transient rises above the programme's own level in the band."""
+
+    def note(self) -> str:
+        times = ", ".join(f"{s // 60}:{s % 60:02d}" for s in self.steps_s[:5])
+        more = f" and {len(self.steps_s) - 5} more" if len(self.steps_s) > 5 else ""
+        return (
+            f"DC offset: {self.channel} carries a {self.offset_dbfs:.0f} dBFS offset that steps "
+            f"{len(self.steps_s)} time(s) (at {times}{more}); each step is an infrasonic "
+            f"transient up to {self.worst_excess_db:.1f} dB above the programme's own "
+            f"{STEP_BAND_HZ[0]:g}-{STEP_BAND_HZ[1]:g} Hz level, and a correction boosting that "
+            "band lifts it by its gain there, as a thump; headroom already counts the offset "
+            "itself"
+        )
+
+
+def dc_steps(material: Material) -> list[DcSteps]:
+    """The channels whose DC offset steps audibly, by three tests and no dB constant.
+
+    A channel qualifies when its slow DC level (the median of per-second means over
+    `LEVEL_HALF_WIDTH_S` either side) is persistently large enough that a step in it would reach
+    the programme: the band's response to a step of that size exceeds the 90th percentile of the
+    channel's per-second peak in `STEP_BAND_HZ`, the level its own programme regularly reaches
+    there. Each step reported is a change in that level whose transient exceeds it too, and, with
+    other channels to compare, near which this channel's band level stands out of every other's:
+    programme bass arrives in several channels at once, a step in one channel's offset does not.
+
+    The 90th percentile, not the median, because a sparse channel — an LFE silent most of the
+    time — has a median near nothing, and every small drift cleared it. The persistent offset,
+    because an LFE carries infrasonic content no other channel does, so it always stands out.
+    On 34 titles at hand only Desperately Seeking Susan's FR qualifies.
+    """
+    fs = int(material.fs)
+    if not material.channels or fs <= 2 * STEP_BAND_HZ[1]:
+        return []
+    seconds = min(len(x) for x in material.channels.values()) // fs
+    if seconds <= 2 * LEVEL_HALF_WIDTH_S:
+        return []
+    band = signal.butter(4, STEP_BAND_HZ, btype="band", fs=fs, output="sos")
+    unit_step = np.r_[np.zeros(4 * fs), np.ones(4 * fs)]
+    step_gain = float(np.max(np.abs(signal.sosfilt(band, unit_step))))
+    peaks = {
+        name: np.abs(signal.sosfilt(band, np.asarray(x, dtype=np.float64)))[
+            : seconds * fs
+        ]
+        .reshape(seconds, fs)
+        .max(axis=1)
+        for name, x in material.channels.items()
+    }
+    found: list[DcSteps] = []
+    for name, x in material.channels.items():
+        means = (
+            np.asarray(x[: seconds * fs], dtype=np.float64)
+            .reshape(seconds, fs)
+            .mean(axis=1)
+        )
+        level = ndimage.median_filter(
+            means, size=2 * LEVEL_HALF_WIDTH_S + 1, mode="nearest"
+        )
+        programme = float(np.percentile(peaks[name], 90))
+        offset = float(np.median(np.abs(level)))
+        if programme <= 0.0 or offset * step_gain <= programme:
+            continue
+        shift = np.zeros(seconds)
+        shift[LEVEL_HALF_WIDTH_S : seconds - LEVEL_HALF_WIDTH_S] = (
+            level[2 * LEVEL_HALF_WIDTH_S :] - level[: seconds - 2 * LEVEL_HALF_WIDTH_S]
+        )
+        candidates, _ = signal.find_peaks(
+            np.abs(shift), distance=2 * LEVEL_HALF_WIDTH_S
+        )
+        others = [peaks[k] for k in material.channels if k != name]
+        steps: list[int] = []
+        worst = 0.0
+        for centre in candidates:
+            transient = abs(float(shift[centre])) * step_gain
+            if transient <= programme:
+                continue
+            window = slice(
+                max(centre - LEVEL_HALF_WIDTH_S, 1),
+                min(centre + LEVEL_HALF_WIDTH_S + 1, seconds),
+            )
+            if others and peaks[name][window].max() <= max(
+                o[window].max() for o in others
+            ):
+                continue
+            # to the second: the largest jump between consecutive means in the window
+            jumps = np.abs(np.diff(means[window.start - 1 : window.stop]))
+            steps.append(int(window.start + np.argmax(jumps)))
+            worst = max(worst, 20.0 * np.log10(transient / programme))
+        if steps:
+            found.append(
+                DcSteps(name, 20.0 * np.log10(offset), tuple(steps), float(worst))
+            )
+    return found