Anamorph — Stereo Tools Audio Plugin

Anamorph (by RollyTech) is a stereo-field toolkit: it turns mono into stereo, controls stereo width (globally and per band), and provides the full set of stereo tools (M/S, mono-maker, channel utilities, monitoring) around a high-end diamond vectorscope. Built with CMake + JUCE only — it configures and builds entirely from the command line on a headless Linux machine, no IDE.

Headline features

• Turn mono into stereo and control stereo Width (global + up to 4 phase-coherent bands).
• Widening engine: Haas / Velvet-Noise / Chorus / Dimensional, with Drive (oversampled).
• Full stereo toolkit: M/S mode, Mono Maker, channel kill/swap/balance/polarity, Band Solo.
• Level Match (BS.1770) for fair A/B; A/B compare + per-slot Undo/Redo; presets.
• Diamond vectorscope, correlation + L/R Peak/RMS meters; click-free transitions throughout.

Project status

0.10.1 has an unpublished Draft Release, built from tag 0.10.1 on commit 8a0bdbc0 with JUCE 9.0.5. Its eleven assets were independently verified; see the current roadmap for provenance and hashes. Level-5, other applicable manual validation and completed-roadmap acceptance are owner-attested. ADR-0070 item 5 performance cost is owner-approved for the measured Intel Mac/workload scope. Public publication is not authorized. The following 0.10.0 draft description is historical.

0.10.0 draft release / JUCE 9.0.4 (verified 2026-10-31 UTC). The GitHub draft contains 11 verified assets from annotated tag 0.10.0 at 4c13688 (normal Release build 7), including PR #187's approved processor/restore fixes and PRs #191/#193's Linux VST3-only installation with legacy-resource preservation. The release remains Draft and unpublished. The next-release roadmap records current CI, asset hashes and development priorities. On 2026-10-31 (Asia/Shanghai), the owner explicitly confirmed relevant ADR approvals and real-machine testing completed/approved (NR-001/002). The detailed host matrix NR-003 is Deferred; individual unexecuted cases are not passed. PRs #195–#211 are integrated on main through c35a9d6b (2026-11-03, Asia/Shanghai). NR-024 protects Undo/Redo/A-B editor lifetime; NR-023 bounds transport arithmetic. State157 retains the repeated same-processor restore cycle. The callback investigation records integrated restore/scale guards, review-only imager corrections, and an unresolved framework lifetime finding. The NR-006 architecture is Accepted and its atomic-window implementation is on main. Current native CI/compile guards and reviewed codegen are complete; representative performance, owner cost acceptance and targeted native visual/editor-lifecycle acceptance remain pending. Post-tag development is not included in the existing draft assets.

Post-integration research includes the NR-012 alias study. Its bounded local measurements add no universal quality threshold or release approval.

The NR-011 execution record describes integrated additive transition coverage from #200. The NR-014 component record covers the integrated rotary accessibility-title correction and bounded metadata/key regression; native assistive-device and global focus acceptance remain pending. The owner-native validation package prepares representative performance and host/accessibility evidence collection; tool smoke does not close those acceptance gaps. Native/hardware/manual execution is owner-deferred for the current independent engineering-review round; acceptance remains outstanding. The release-readiness record preserves earlier identities and original/P1 human attestations with their scope. The earlier state/host record retains its development filename.

• Version 0.10.1 (pre-1.0, unpublished draft), in the internal-testing phase — builds go to testers for evaluation, not to customers (see Licensing; internal record: docs/COMMERCIAL_STATUS.md).
• 0.9.5 is a performance release, and it changes nothing you can hear. With Velvet Noise selected, the plug-in was rebuilding its whole ~45 ms decorrelation window from scratch on every processing block — a cost set by the window rather than by the block, so it hurt most where buffers are small and sample rates are high. At 192 kHz with a 32-sample buffer it had grown to most of the plug-in's work. The window is now carried forward instead of rebuilt: −14 % of the engine's instruction count at 48 kHz / 32 samples, −32 % at 192 kHz / 32, −5 % at the common 48 kHz / 128. The audio is bit-identical — proven by the 32-scenario engine twin dump and a 180-configuration sweep over every algorithm, four sample rates and five buffer sizes — and reported latency, parameters and saved state are untouched.
• 0.9.4 was a maintenance release: JUCE 9.0.0 → 9.0.1, plus the move to the C++23 language standard, and one interaction fix — a control covered by an open drop-down no longer lights up as though you were pointing at it. Apart from that fix, the only change to Anamorph's own source is one added #include (ADR-0027), and the sound, reported latency, parameters and saved state are unchanged — proven by 32-scenario engine twin dumps that are bit-identical both across the two JUCE versions and across C++17 vs C++23, both self-test suites, and pluginval at strictness 10 in both modes. Building from source now needs a C++23 compiler; installed builds are unaffected. What the JUCE bump brings is upstream maintenance in the framework the editor sits on: on Linux a busy message queue can no longer starve the window system (upstream's unresponsive-GUI fix), screens are detected on more window managers and a missing input-device list no longer crashes; on Windows a thin unpainted seam at panel edges under fractional display scaling is gone; on macOS, renderer and shutdown guards. ADR-0026, ADR-0027.
• 0.9.3 is a round of interaction fixes. The Multiband add-split preview line keeps following the pointer instead of occasionally hanging at one spot on a quiet track; a click that closes a menu now only closes the menu — it can no longer also close a panel, discard a half-typed preset name or nudge a control underneath; an open menu no longer outlives the plug-in window — hiding it, closing it or switching to another application closes the menu too, so nothing is left floating and the first click on return goes to the control you aimed at; right-click menus size themselves to their longest item and grey out what you cannot pick; and turning Tooltips off now takes effect at once. One visible change beyond the fixes: the Widen row's two drop-downs are now equal width with the join between them on the panel's centre line. Installers: the Linux installer now asks where to install and defaults to your own account (~/.vst3, no root needed), and the macOS .pkg re-installs properly after the app or a plug-in has been moved or deleted — it used to update the moved copy and report success while the standard location stayed empty. Nothing in src/ changed for either: saved state, parameters and the DSP are unchanged.
• 0.9.2 fixes the preset drop-down (it no longer stays on screen — or crashes on click — after the plug-in window closes) and lets a user preset share a factory preset's name without losing its place in the menu; the Settings control Window Size is now labelled UI Scale. Saved state, parameters and the DSP are unchanged.
• 0.9.1 changed the manufacturer code (Anmf → RTec, the vendor identifier now shared with the second RollyTech plug-in). It is host-facing identity, so sessions saved with a pre-0.9.1 build report Anamorph as missing — re-insert the plug-in and re-load the preset. Audio, parameters and presets are unchanged. ADR-0023 · KI-016.
• Active development on a feature-branch → PR → main workflow.
• Validation gate: 76 DSP self-tests + the 142-test state-compatibility suite + pluginval strictness 10 (both modes ×3, blocking on all three CI platforms).
• A green build + pluginval pass is "ready to audition," not final sign-off (audio/visual quality needs a DAW — see docs/procedures/TESTING.md).

Supported platforms & formats

• Formats: VST3 (all platforms), AU (macOS, for Logic/GarageBand), Standalone. AAX is not supported.
• Platforms: Linux x86-64, Windows x86-64, macOS universal (arm64 + x86_64).
• I/O: stereo→stereo and mono→stereo (output is always stereo; mono→mono is not supported).
• Full matrix + status: docs/architecture/COMPATIBILITY_MATRIX.md.

Requirements

• Runtime, x86-64: an Intel Haswell (2013) / AMD Excavator (2015) CPU or newer for every x86-64 binary — the Linux build and the macOS x86_64 slice, compiled -march=haswell (ADR-0031), and the Windows build, compiled /arch:AVX2 (ADR-0032). Below that floor the failure is an illegal-instruction fault inside the host (SIGILL; STATUS_ILLEGAL_INSTRUCTION on Windows). Only Apple Silicon carries no ISA floor. docs/policies/COMPATIBILITY_POLICY.md.
• CMake ≥ 3.22, a C++23 compiler, Ninja (recommended). JUCE 9.0.5 is fetched automatically (pinned to an immutable commit via CMake FetchContent) or pointed at a local checkout.
• Linux build deps install via scripts/setup-linux.sh. See docs/procedures/BUILD.md.

Quick start (headless Linux)

# 1. Install build dependencies (Ubuntu; safe to re-run)
scripts/setup-linux.sh

# 2. Configure + build (fetches the pinned JUCE commit via CMake FetchContent)
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release        # ...or: scripts/build.sh

# 3. Run the headless self-tests (DSP + state compatibility)
scripts/run-tests.sh

# 4. Validate the VST3 with pluginval — the release gate is BOTH modes, x3 each
scripts/run-pluginval.sh 10 deterministic
scripts/run-pluginval.sh 10 randomise

The produced plugin is typically at build/Anamorph_artefacts/Release/VST3/Anamorph.vst3.

Installing (users)

Releases are published on the GitHub Releases page (draft → published after the manual audition): per platform an installer (Windows Inno Setup installer and macOS .pkg, both with component selection; on Linux the zip itself carries install.sh) and a plain zip (flat contents — extracting shows the files directly), plus SHA256SUMS.txt and RELEASE_MANIFEST.txt. Both routes install to the standard locations — system-wide on Windows and macOS; on Linux install.sh asks, and defaults to a per-user install into ~/.vst3 that needs no root. Step-by-step: docs/user/INSTALLATION.md; full manual: docs/user/USER_MANUAL.md. Prebuilt binaries for all three OSes are also uploaded as GitHub Actions artifacts on every push (macOS bundles are ad-hoc signed, not notarized — see packaging/macos/INSTALL.txt).

New to the plug-in? The manual's Quick start takes you from download to first widened sound. Testing a pre-release build? SUPPORT.md is the internal testing guide — what a tester may do with a build, what to check first, and what a test report must contain.

To build without network (JUCE already on disk): cmake -B build -DANAMORPH_JUCE_PATH=/path/to/JUCE ...

Architecture (one paragraph)

A format-agnostic DSP core (src/dsp/, the AnamorphDSP library) driven by a POD parameter snapshot, behind a thin plugin wrapper + GUI (src/, src/gui/). The signal chain is strictly serial: Input conditioning → Effect engine (Drive → algorithm → Width → Multiband) → Dry/Wet Mix → Mono Maker (post-Mix) → Output → Band Solo monitor (post-everything) → metering. Oversampling wraps only the nonlinear stages. Full detail: docs/architecture/.

Documentation

The JUCE 9.0.5 review packet supports Accepted ADR-0071. It is developer investigation evidence; the configured dependency is 9.0.5 under explicit owner Architecture Review approval; Level-5 listening and native/manual acceptance are now PASS — owner-attested for 9.0.5, recorded 2026-11-04 (Asia/Shanghai). Exact tested payload/environment details were not supplied. PR #213 is merged; no release is authorized.

The full technical documentation lives in docs/:

• Start here: docs/SOURCE_OF_TRUTH.md · docs/HANDOVER.md · docs/REPOSITORY_MAP.md
• For users: docs/user/ (installation guide, user manual)
• Architecture & decisions: docs/architecture/ (signal flow, DSP algorithms, parameters, state, threading, latency, ADRs)
• How-to: docs/procedures/ (build, CI/CD, testing, packaging, release)
• Rules (binding): docs/policies/ (real-time audio, threading, DSP, compatibility, AI-agent)
• History & status: CHANGELOG.md · docs/POSTMORTEMS.md · docs/KNOWN_ISSUES.md · docs/FUTURE_RISKS.md
• Option B review: bounded experiment and B2 implementation record · separate retained outcomes (supporting evidence; B2 integrated through owner-reviewed #222, native/release acceptance separate) · B2 execution evidence · integrated-source component verification
• Callback investigation: review and decisions · JUCE 9.0.4 evidence · JUCE 9.0.5 NR-026 evidence · reproduction package · Accepted ADR-0072 (B2 integrated through owner-reviewed #222)
• Test isolation: Linux State-suite execution evidence · disconnect-control execution (supporting engineering records) · protected redirect review
• Multiband text input: focused investigation and regression evidence.

The documentation falls into four classes, kept deliberately separate:

Accepted ADR-0073 records the owner-approved Linux shipping/TSan environment decision; the Architecture Review Gate is approved and cleared.

Class	Documents	Audience
User	docs/user/INSTALLATION.md · docs/user/USER_MANUAL.md (incl. its Quick start and FAQ)	anyone running the plug-in
Internal / testing	SUPPORT.md · the bug-report form	internal and beta testers
Legal / licensing	EULA.md (draft) · PRIVACY.md · TRADEMARKS.md · NOTICE · THIRD_PARTY_LICENSES.md	everyone; Anamorph's own LICENSE is still pending — see below
Developer	everything under docs/ not listed above (architecture, procedures, policies, status, including Accepted ADR-0072 for the approved NR-026 B2 architecture), measurement/planning records under worklogs/ (including the native validation package, the NR-014 component record, ScopeBuffer review packet, diagnostic inventory, CI memcheck budget follow-up, next-release execution register, NR-026 supporting evidence and reproduction package, 0.9.10 state/host decisions and native icon integration), plus AGENTS.md (primary contributor/agent instructions), CLAUDE.md (Claude-compatible import), and docs/COMMERCIAL_STATUS.md	maintainers and AI agents

The user manual, SUPPORT.md, NOTICE and THIRD_PARTY_LICENSES.md are attached to every release as version-named assets; per-platform install steps ship inside each package as INSTALL.txt. Developer documentation is not shipped, with two documented exceptions: docs/KNOWN_ISSUES.md and CHANGELOG.md are developer-authored but deliberately tester-surfaced (SUPPORT.md routes testers to both).

Licensing

Anamorph is a closed-source commercial product — it is not open-source software. The source being readable here is not a licence: no LICENSE file is present, and this repository grants no right to use, copy, modify or redistribute the code or binaries beyond what written permission from RollyTech provides (all rights reserved by default). Nothing under docs/ is a source-code licence.

Three strands, kept separate:

• Anamorph's own terms — still to be settled. EULA.md is an unapproved draft with every open decision marked; it is not in force and no build ships it. Testers hold an evaluation-only permission (SUPPORT.md §1).
• Third-party dependency licences — attribution for the shipped binaries is in NOTICE; the full verified inventory (component, purpose, origin, licence, obligations) is in THIRD_PARTY_LICENSES.md. Both are published with every release. Anamorph is built on JUCE, whose modules are dual-licensed AGPLv3 or commercial; a closed-source distribution model cannot use the AGPLv3 arm, so the commercial JUCE tier must be in place before commercial distribution. Commercial VST3 distribution requires reviewing Steinberg's licensing requirements separately.
• Product data and names — PRIVACY.md (Anamorph collects nothing and makes no network connections) and TRADEMARKS.md.

The open owner/legal decisions are indexed in docs/COMMERCIAL_STATUS.md §4 and recorded authoritatively in THIRD_PARTY_LICENSES.md §"Open licensing decisions" and docs/architecture/RELEASE_HARDENING_PLAN.md.

Contributors and AI agents: read AGENTS.md and docs/policies/AI_AGENT_POLICY.md before changing code — some changes (parameter IDs, serialization, threading, DSP order, latency) are hard-stop, human-review-required. CLAUDE.md is a Claude-compatible import of AGENTS.md.

Simple vs. Advanced mode

Simple (default) is the Widen core around the vectorscope (algorithm, Drive, Amount, Width). Advanced adds the Input, Output, and Multiband modules; Advanced-only modules default-bypass when Advanced is off while their values are remembered. Settings (Oversampling, UI Scale, persistence, tooltips, animations) are host-hidden session state.

Namespace inventory/validation: worklog; ADR-0063 is Accepted under explicit final owner approval; implementation is merged. The namespace worklog records its original native-validation limits. Later real receipt-installation evidence at f8e4e7f000db68b40cdea5e1a5c2d43fb4b983ac is tracked in PR #174; DAW recall and human shell appearance remain separate manual work.

Installer icon validation and ownership: worklog, Accepted ADR-0064; owner approval and #172 merge are recorded, with native visual limits preserved.

The corrected 0.10.0 Linux candidate installs only VST3 and keeps Standalone portable in the ZIP. It removes desktop publication and leaves legacy desktop resources and installed Standalone copies untouched. See Accepted ADR-0069 and the installation guide. PR #193 is already merged and rebuilt in the current draft. Owner approval and real-machine completion are recorded separately from native CI evidence; this development work changes no tag/release. ADR-0065 remains the historical desktop-era record.

Installed-receipt decision: ADR-0066 is Accepted by the owner's direct confirmation on 2026-10-25. PR #174 merged as 04e6ed48acc3532a112ab8a6ea1fb969f4abc83b; its installed-receipt implementation is effective on main. ADR-0065 and its helper amendment are also effective through PR #175 merge 14bde706e2d121c9970cf00c757cb12d3178b9a5. Native fixtures are in scripts/fixtures/macos-receipts; scripts/test-macos-receipt-gates.py checks the production scheduling contract.