Imager

Development biography · earlier archive

Development profile compiled from project source and retained records in October 2026. Dates and test results describe those records; they do not imply a new build, live acceptance test or public release.

Scope covered: the Imager Swift package and its visualisation capabilities. Complete; no remaining scope. Read-only inspection: no builds, benchmarks, app operation, or source/site edits were performed in this task.

IMPORTANT — media: there are zero real screenshots, videos or audio assets for Imager. Do not place any Imager imagery on the site from this response. Detail in section 7.

Project biography (approx. 830 words)

The problem. A stereo phase scope looks like a solved problem and is not. Most implementations compute an instantaneous per-bin "correlation" — the cosine of the phase difference between left and right in a single FFT frame — and present it as coherence. That number is mathematically unable to say what users want to know. Magnitude-squared coherence over one frame is identically 1 by construction, because |Sxy|² and Sxx·Syy are the same quantity when nothing has been averaged. So the display shows phase, but it cannot distinguish a stable stereo image from noise that happens to be momentarily aligned. The second common failure is the wideband summary: averaging per-bin cosines uniformly lets several hundred noise-floor bins, whose phase is essentially random, drag the headline figure toward zero even when the musically dominant content is perfectly correlated.

Origin. The DSP core began outside this package. The pre-September-2026 header of Sources/Imager/DSP/FFTProcessors.swift carried // HumCancellation and Created by dh on 05/12/2025; the current header has been rewritten to // Imager, so that provenance is historical rather than present in the source today. The surrounding module carries its own design contract in AGENTS.md, which reads as a remediation document: it names duplicate semantic models across parallel view variants, stale shader files, a .goniometer mode that was silently rendering as something else, and view code that had absorbed logic belonging to a state engine. Imager is the consolidation of that mess into one authoritative pipeline.

Distinctive ideas. Three choices separate it from a textbook scope.

First, coherence is measured properly. Auto- and cross-spectra are accumulated with exponential forgetting across frames (coherenceAveragingFrames, default 8), so per-bin magnitude-squared coherence becomes a real consistency measure. Wideband figures are then energy-weighted: correlation is the Parseval-equivalent lag-0 normalised cross-correlation, and the headline phase is the argument of the cross-power-weighted circular mean, so loud content decides the reading and the noise floor does not.

Second, phase is estimated rather than smoothed. The default estimator tracks (cos φ, sin φ) on the unit circle, where the ±π wrap simply does not exist as a discontinuity, using an adaptive Kalman filter from the local Kalman package. Process noise is derived from the scope's own latency control so the knob keeps its established meaning, while measurement noise self-tunes by residual covariance matching. A χ² validation gate rejects single-frame glitches — the near-π flips that low-coherence material produces — and coasts on prediction instead, then deliberately re-acquires in one step when a jump proves to be real. The estimator also publishes what it knows about itself: posterior variance, innovation-likelihood confidence, a convergence score, and whether the last frame was gated.

Third, the two render paths are held to a written contract rather than drifting apart. The uniform block is declared three times — in Swift for upload, in Metal for the kernels, and as a binding list for contract checking — and a mismatch would silently misalign every kernel with no compile error, so tests pin all three by name, order and type. Where a mode has no honest GPU equivalent, .goniometer routes to Canvas explicitly instead of quietly rendering as a different mode.

Intended audience. Developers of Apple-platform audio software who need a trustworthy imaging display: mastering and metering tools, noise-and-hum analysis utilities, and the NoiseColour application family, for which the package carries compile-time stubs (#if !canImport(NoiseColourCore)) so it builds standalone and defers to real host types when they are present. It is not aimed at end users; there is no app to install.

What a developer actually does. The documented journey is short. You hold a PhaseScopeAudioBridge as a @StateObject, install an AVAudioEngine input tap, and call bridge.push(buffer:) from the audio callback — which only copies into a bounded ring, because FFT, FIR, cross-spectrum and Kalman work all run on a serial analysis queue. You then read bridge.latest and pass its fields into PhaseScopeProView. Published telemetry is coalesced to 60 Hz so SwiftUI is never driven at audio rate, while telemetryHandler still delivers every analysis frame for callers who want full resolution. For a captured buffer or a file, analyzeOffline(left:right:) runs synchronously and sees every hop, because the real-time path deliberately drops audio it cannot keep up with and counts what it dropped.

Honest standing. This is strong engineering at pre-release maturity. The library builds clean and a 71-test suite passed in both debug and release on a development branch on 2026-09-05. But Imager has never been seen running: there is no host app in the repository, no captured screenshot, no demo recording, and — as of this conversation's git snapshot — a single commit in history with every current source file uncommitted. It is a well-built component awaiting an application, and the site copy should say so rather than imply a shipped product.

Modules and features

Authored in this package unless marked otherwise. "Visitor-visible" is assessed honestly — most of this is library surface, not something a website visitor can see or try today.

Scope modes: .polarSample, .polar, .lissajous use the Metal renderer when requested; .goniometer is an intentional Canvas path, documented rather than silently remapped.

From dependencies, not authored here: FIR window library, Savitzky–Golay smoother, BS.1770 true-peak meter and STFT (FIRFilters); adaptive Kalman filters, scalar smoother and innovation-convergence tracker (Kalman); CPU reference execution, compatibility doctor and external-MSL validation (SemanticCompute, tests only); all FFT primitives (Apple Accelerate/vDSP).

Technical foundations

• Swift 6.2 tools / Swift 6 strict concurrency. Real-time types are @unchecked Sendable with documented invariants: the audio thread only writes a bounded ring under a short lock; analysis is confined to a serial queue; UI state is published on main.
• Apple Accelerate / vDSP is the live FFT and the vectorised hot path throughout. This is deliberate and documented: the per-hop transform is small and latency-sensitive, so it stays on vDSP rather than moving to GPU.
• FIRFilters (local, ../../FIRFilters) supplies window coefficients, normalised to unit RMS to match the vDSP_HANN_NORM convention so absolute dB levels did not move when windows were swapped, plus Savitzky–Golay smoothing and true-peak metering.
• Kalman (local, ../../Kalman) supplies KalmanCore (adaptive filters, scalar smoother) and KalmanIMM (InnovationConvergenceTracker, used for the phase stability score).
• SemanticCompute 1.21.0 is pinned by exact version from a Git URL and is deliberately not linked into the shipping Imager target — test target only. Per the README this keeps MCP and reference-execution machinery away from the audio callback and stops a developer's adjacent checkout from silently changing a verification result. It acts as a numerical oracle for FIR window coefficients, FFT magnitude/dB, centroid, flux, stereo cross-phase/correlation and STFT composition, and as an external-MSL validator that compiles, dispatches and reads back a deterministic pixel for each live Metal kernel when a Metal device exists.
• Metal for the GPU render path, with Canvas as a genuine fallback rather than a stub.

Maturity by feature, with evidence

Evidence is labelled by where it comes from. Two code lines exist: the main checkout (the project archive, current and most advanced) and a development worktree (.claude/worktrees/firfilters-kalman-upgrade-005bf7, branch claude/firfilters-kalman-upgrade-005bf7).

Conflicting/outdated information to be aware of: the worktree's AGENTS.md contains dated "Detection pipeline contract" and "Pipeline wiring" sections (2026-09-05) that are not present in the main checkout's AGENTS.md, while the main checkout contains later features (stereoTrace, AVAudioPCMBuffer input, SemanticCompute 1.21 oracle) absent from the worktree. The two lines have diverged. SEMANTICCOMPUTE_UPGRADES.md carries a self-flagged notice that its file/line citations predate the detection rewrite.

Limitations, roadmap, FAQs

Known limitations

• Nothing is committed or released. The work exists as uncommitted changes across two divergent lines.
• No application, no demo, no media. The scope has never been observed running.
• Very high OS floor — macOS 26 / iOS 26. Per FIRFilters' manifest commentary this is dictated by RemezEngine, not by Imager's own needs; lowering it requires lowering RemezEngine first.
• Not self-contained. Requires FIRFilters and Kalman checked out as siblings at ../../. Absolute developer paths have been replaced with relative ones, but the siblings are still mandatory.
• .goniometer has no GPU path by deliberate choice, so one of four modes always renders on Canvas.
• Reported phase variance is conservative for inputs cleaner than the latency-implied dynamics, a documented consequence of fixing process noise and adapting only measurement noise.
• GPU numerical validation is conditional on a Metal device being present.

Roadmap (aspirations, not built)

• Lower the three scope kernels through SemanticCompute's Pointwise2DLowering so the CPU reference, MSL and portable C provably agree. Documented as priority 1 in SEMANTICCOMPUTE_UPGRADES.md, and assessed as larger than a mechanical port: SemanticCompute exposes canned family lowerings rather than a path to author an existing hand-written kernel as IR, so doing it properly makes the IR the source of truth for the shader.
• An offline/batch stereo-imaging analyser as a golden reference for the live vDSP path.
• Accessibility work: express estimator confidence through geometry rather than hue, per the module's own accessibility rules.
• The remaining engine/view consolidation phases in AGENTS.md (the public view still holds some logic the contract assigns to the engine).

FAQs

• Can I download or try Imager? No. It is an unreleased local Swift package with no public distribution and no demo application.
• Why is its coherence reading different from other phase scopes? Because it averages cross-spectra over time before computing coherence. A single-frame magnitude-squared coherence is always 1, so an instantaneous reading cannot measure stereo consistency; the wideband figures are also energy-weighted so the noise floor does not dominate.
• Does it run on the audio thread? No. The audio callback only copies into a bounded ring. FFT, FIR, cross-spectrum and Kalman work run on a serial analysis queue, and SwiftUI updates are coalesced to 60 Hz by default.
• Is the GPU path numerically identical to the Canvas path? Not claimed. They are held to a shared written contract, with tests pinning the uniform layout across its three declarations and, when a Metal device is present, an external-MSL validator comparing a deterministic pixel per kernel. Full numeric parity of the kernels is roadmap, not fact.
• Does it use SemanticCompute at runtime? No, by design. SemanticCompute is a test-only numerical oracle, pinned to 1.21.0, and is not linked into the shipping target.