SpectralProcessor

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.

>

SpectralForge Lab / SpectralProcessor (primary profile)

Biography

The problem. A conventional equaliser knows nothing about music. Pull 3 kHz down to soften a harsh vocal and you dull the consonants too; cut 80 Hz to tame one bass note and every other note loses weight. Meanwhile, two instruments competing for the same region is a relationship between harmonic series, not a collision between FFT bins. SpectralProcessor starts from that observation: estimate the note and its partials first, then let the user say what to preserve and what to yield.

Origin and motivation. The repository's documented origin is a C++ DSP core (Sources/SpectralProcessorCpp) with a Swift package around it and a vendored copy of the studio’s Kalman C++ library. The project's turning point is recorded in the repo itself. On 12 September 2026 a source and numerical review examined the package against a reported zipper-noise problem in Logic and concluded that the existing assurance had been "too broad". It found five P1 defects, including that neutral surgical processing attenuated audio by about 2.5 dB (measured unity-mask impulse gain 0.7498062849), that host automation ramps were discarded, that the render path allocated memory and took locks, that the spectrum display was drawn from a fixed sine function rather than measured audio, and that a graph gesture could switch on a hidden noise module with no visible control to turn it down.

That review is the project's defining document, and the repairs are evidenced beside it. Reviews/2026-09-12/SC_1_20_EXECUTION.md records the re-measurement after the window-overlap repair: HSEQ gain 0.9999997616 at 2047 samples of delay and the surgical unity mask 0.9999973178 at 4095 samples, both passing a SemanticCompute 1.20.0 parity check at absolute 2e-6 or relative 2e-5, with no amplitude compensation applied. The project agent confirmed the mechanism in source on 17 October 2026: the surgical engine now accumulates a squared-window weight alongside the output and divides sample by sample (SurgicalMaskingEngine.cpp:553-562), which is the correct weighted-overlap-add normalisation. The same source inspection identified the automation repair (the wrapper reads eventSampleTime, distinguishes AURenderEventParameterRamp and honours rampDurationSampleFrames), a declared latency property, and a lock-free atomic telemetry frame whose spectrum the editor actually draws.

Audience. Producers and mixing engineers who want corrective EQ that follows a performance; anyone trying to separate kick from bass or a vocal from a guitar without flattening either; and, through the C ABI, developers who want a harmonic-tracking spectral engine in their own project.

Distinctive ideas.

• Musical coordinates. A band can be positioned as Fixed, Harmonic or Between Harmonics, and harmonic targets are selected by order rather than by frequency.
• Estimation, not thresholds. Per-bin occupancy and per-partial amplitude are tracked by adaptive Kalman filters from the studio’s Kalman package, with innovation-based confidence, so the processor can say how sure it is.
• Masking as a negotiation. Instances publish their spectral occupancy to a shared group so one track can keep a region while another yields, instead of both cutting blindly.
• Evidence kept in the repository. The review, the failing diagnostic, the parity verdicts and an interactive failure report all sit in Reviews/2026-09-12/. The roadmap's own rule is that no capability ships "merely because a class, control or dependency exists".
• Honest idle state. Telemetry initialises to −120 dB and the editor shows -- dB when nothing is connected, rather than animating a dead plug-in.

A concrete user journey. Open SpectralForge Lab's all-in-one plug-in on a vocal. The header offers bypass, input and output gain and a process mix; the plug-in reports its processing latency to the host so parallel tracks stay aligned. Set the fundamental, or let the tracker find it, and the footer shows the tracked frequency and input/output levels measured from the audio. Choose a harmonic count and a harmonic gain to soften the upper partials of the sung note while the attack protection keeps consonants intact. For a kick-and-bass conflict, enable the surgical module on both, put them in the same group with different instance IDs, give one the Keep role and the other Make Room, and set carve depth, keep boost, sensitivity and sharpness; the shared occupancy map decides where each yields.

Boundary, stated by the project. The roadmap is explicit that this cannot recover information already lost in a mixed signal, and that subdividing an FFT does not separate perfectly overlapping sources. It can allocate space when separate tracks or an explicit sidechain exist.

Modules and what a visitor could see, hear or try

Eight AUv3 components ship from one extension (SpectralForgeLabAUv3/Info.plist, version 18, all aufx/SpPr):

Controls a visitor can actually operate: 40 automatable AU parameters, read from the parameter tree — bypass, inputGain, outputGain, processMix, fundamental, harmonicGain, harmonicQ, harmonicCount; noise (noiseLevel, noiseColour, noiseWidth, noiseTilt, noiseHighPass, noiseLowPass, noisePeakFrequency/Gain/Q); surgical (surgicalEnable, surgicalGroup, surgicalInstance, surgicalRole, surgicalMix, surgicalCarve, surgicalKeep, surgicalSensitivity, surgicalSharpness, surgicalF0, surgicalHarmonics, surgicalWidth); HackRF (hackRFEnable, hackRFMode, hackRFCenter, hackRFSpan, hackRFGain, hackRFSquelch, hackRFPacketBlend, hackRFSpectrumBlend, hackRFAudioLevel, hackRFAnomaly); and sidechainEnable.

Editor: a measured spectrum plot fed by the atomic telemetry frame at roughly 30 Hz, with input/output RMS and tracked fundamental read-outs.

Technical foundations

• Swift package : products SpectralProcessor, SpectralProcessorCpp, SpectralProcessorAUv3, the AudioZipRegressionTests executable and a SpectralProcessorTests test target. Dependencies are relative paths — ../../Kalman, ../../FIRFilters, ../Imager.
• Swift layer: HSEQProcessorHRF.swift (STFT, harmonic ownership, mask smoothing, transient protection, optional frequency tracking), LiveEQViewHRF.swift (band editing and backend interfaces), MetalHSEQBackendHRF.swift with MetalHSEQKernelsHRF.metal (GPU magnitude and mask multiply, with CPU fallback), and the four HSEQ Next modules (§3).
• Configuration safety: Config.requiresRebuild(comparedTo:) separates control-rate changes from structural ones; updateConfig returns .applied or .requiresRebuild and leaves the processor untouched in the second case, so FFT and tracker state is never resized under the render thread.
• C++ core: HSEQProcessor, SurgicalMaskingEngine, NoiseColourEngine, HackRFDawMonitor, SpectralProcessorDSP (biquad harmonic cascade), MetalHSEQBackend, and a vendored kalman/ tree (EKF, UKF, IMM, RTS smoother, adaptive Q/R, robust kernels, spectral denoiser).
• Kalman relationship: the review established that all three vendored .cpp files and every header except the denoiser match the studio’s CppKalman source; the local denoiser carries extra opt-in work (speech noise-floor hold, decision-directed SNR, gain floor) that is constructed but never processed, so it is not an active feature.

Maturity by feature

Dates and figures are from the repository's own documents or from the project agent’s 17 October 2026 source inspection. "Not verified" means no evidence exists, not that it fails.

Provenance caution for the site. The repository has essentially one commit ("Initial Commit"); the review's own table records that many files are staged additions deleted in the working tree while the AU projects, C++ sources, LiveEQView and tests are untracked, and states plainly that "Git cannot establish that these edits were authored by Claude." Treat the working tree, not the git history, as the artefact, and say so if provenance is ever questioned.

Roadmap (aspiration; from the project's own documents, not shipped)

ROADMAP_HSEQ_NEXT.md and HSEQ_NEXT_COMPLETE_ROADMAP.md (both 12 September 2026, both explicitly proposals) define releases as evidence gates, not dates: Foundation (trustworthy processing), 1.0 (complete single-source harmonic EQ: monophonic tracking, fixed and harmonic bands, dynamics, transient protection, presets, native editor), 1.5 (one explicit sidechain with Keep / Make Room roles), 2.0 (opt-in cross-plugin groups, harmonic relationship map, deterministic shared masks, a Relationships workspace), then specialist products (Mix Space, Harmonic Inspector, FIR Tone Designer, Noise Texture, Spectral QA Workbench). Explicitly not promised for 1.0: polyphonic separation, automatic cross-process track discovery, partial resynthesis, a complete FIR workbench, RF hardware integration.

Known limitations

• Nothing is released or installed; no AU validation or Logic session has been demonstrated to pass. The original Logic zipper report is not shown to be resolved.
• Shared masking has no reliable track identity, expiry or cross-process transport; two default instances can collide, and a stopped publisher can linger.
• RF Monitor and HackRF DAW Monitor do not produce a calibrated RF spectrum and have no live data source.
• FIR Subband Lab is not a filter-bank product.
• The 74-check suite tolerates sample jumps of 0.90–0.95 and peaks of 1.70–1.80, so it can miss audible discontinuities.
• Parity evidence covers specific buffers only: 32 Metal bins, not full HSEQ CPU/GPU parity, no iOS GPU, no perceptual claim.
• The vendored C++ denoiser's extra features are inactive.
• Eight plug-in names currently share largely one engine and editor; the roadmap itself says the first release should be one excellent EQ instead.

FAQs

• Can I buy or download it? No. It is unreleased, unsigned and not installed; there is no public link.
• What does "harmonic-aware" actually mean? A band can be placed relative to the tracked note and its harmonic order, not just at a fixed frequency, and the engine estimates each partial's amplitude and confidence with Kalman filters.
• Is the spectrum display real? Yes, now. It is fed by a lock-free telemetry frame measured in the render path and shows -- dB and −120 dB when there is nothing to show. An earlier version drew a fixed sine shape; that was found in the 12 September review and replaced.
• Does the RF monitor analyse radio? Not yet. It has the ingestion API but nothing feeds it, and its IQ path does not perform a frequency transform.
• Why is a critical review published with the project? Because the measured defects and their repairs are the evidence. The surgical path went from 0.75 gain and a failed parity check to 0.9999973 and a pass, and both numbers are in the repository.

SpectralProcessorCpp — reusable DSP SDK (technical sub-profile)

What it is: the C++17 engine set behind every plug-in, usable independently through a C ABI (SpectralProcessorCAPI.h, 19 entry points): SPDSPProcessorCreate/Prepare/Reset/SetParameters/ProcessPlanar/ProcessInterleaved/Destroy, and SPHSEQProcessorCreate/Reset/UpdateConfig/CurrentFundamentalHz/ProcessHop/ProcessSamples/CopyPartials/CopyLastAppliedMask/CopyLastHarmonicWeight/Destroy, plus two default-config helpers.

Maturity: builds as a SwiftPM target and compiles directly into both Xcode projects; covered by the 74-check regression executable; the harmonic and surgical paths carry the 2026-09-12 neutral-reconstruction evidence. No versioned release, no package registry entry, no API stability promise. Header-only additions are preferred because the Xcode targets compile C++ from an explicit file list and link no Accelerate.

HSEQ Next — product direction with implemented groundwork (sub-profile)

Status: the roadmaps are proposals (12 September 2026) and HSEQ Next is a working name, but the state layer is implemented and tested, so it is more than an idea.

Implemented in Sources/SpectralProcessor/: HSEQNextState.swift (schema version 1; processing modes Track/Mix/Render; band positions Fixed / Harmonic / Between Harmonics; harmonic selection; relationship policies; participant roles and status; dynamics; musical band and musical state; relationship rules; session configuration with a persistent track ID; partial and runtime telemetry — with hard protocol limits of 24 bands, 64 participants, 64 partials, 4097 spectrum bins, 128 relationship rules and a 1 MiB payload), HSEQStateCodec.swift (bounded JSON coding that normalises values and rejects oversized payloads and unsupported schemas before encoding or decoding), HSEQTelemetryInbox.swift (a Swift actor holding at most one frame per runtime instance, rejecting duplicate or out-of-order producer sequences, explicitly documented as not for the audio callback) and HSEQNextStateValidation.swift.

Tests (20, names read today; pass state today unknown): state normalisation and duplicate band IDs, self/duplicate peer-rule dropping, telemetry array normalisation and invalid-partial rejection, future-schema rejection, sequence ordering per instance, codec round-trips and oversize/schema rejection, inbox sequencing and capacity, HSEQ control-vs-structural configuration updates, and the NoiseColour controller wrapper.

Why it matters for the site: it is the honest answer to "how would cross-plug-in cooperation work safely" — opt-in, session-scoped, bounded, with runtime peer identity deliberately excluded from recalled preset state. No UI, no transport and no coordinator exist yet.

HarmonicShield EQ (second Xcode project)

A separate, smaller macOS app and AUv3 (HarmonicShieldEQ.xcodeproj; display name "HarmonicShield EQ"; version 1.0 build 15; one component, subtype HShE, description "Harmonic-safe EQ and de-harshing plugin using the C++ SpectralProcessor core"). It builds on the same C++ core but is a generation behind the SpectralForge extension (build 15 vs 18) and its wrapper was named in the review's automation finding. Treat it as a focused variant of the same engine, not a second product, unless the owner says otherwise. No media; not installed.