|
| 1 | +# ArSonMix — Harmonice Duo, Doubler & Shared Built-in FX User Presets |
| 2 | +**2026-11-11 · Owner requirements / actionable implementation blueprint · NOT YET IMPLEMENTED** |
| 3 | + |
| 4 | +## Context and required reconciliation |
| 5 | +Audit: main moved from `a07b16e1c6f04473d328ddd1deab607774375ee3` to `a05485e5aa6682dbc196ce99ee50763eebd1dc19`. Read live head before code. [Harmonice P0 draft #529](https://github.com/masarray/arsonmix/pull/529) already works on natural stereo lead Pitch Tune, register-aware ensemble and premium small switch. Do not overwrite its files; add minimal 2-button change through that owner or after integration. [Latency experiment #521](https://github.com/masarray/arsonmix/pull/521) is research-only; retain established 1536 sample/32ms 48k DSP PDC until separately proven safe. Follow `docs/architecture/FEATURE_EXTENSION_PLAYBOOK.md` and `docs/architecture/MAINTAINABILITY_EXECUTION_V1_20261111.md`. |
| 6 | + |
| 7 | +## Owner-reported bugs |
| 8 | +1. Harmonice VOICES GUI only offers **3 / 4 / 5**, although native `Settings::voices` accepts **2–5** and factory `Natural Duo` preset sets `voices:2`. **Expose 2 as an equal first-class option.** |
| 9 | +2. There is no simple unison vocal **Doubler** (BOSS VE-like double-track sound). **Doubler must NOT be mistaken for Duo:** Duo = 2 pitched harmony voices plus original lead; Doubler = a synthetic additional same-melody performance with controlled natural microtiming, timbre and detune. |
| 10 | +3. All built-in FX (**Parametric EQ, Compressor, Harmonice, ArSon Vocal Throw**, future native FX) need persistent **user-created presets** independent of a session; a 'Custom' label or factory preset selector alone is insufficient. |
| 11 | +4. Existing robotic Pitch Tune and raw checkbox remain urgent separate P0 issues. Current draft #529 addresses them; after tests, correction must be transparent/natural, compact toggle theme-matched; selecting a voice preset must not silently turn Pitch Tune on. |
| 12 | + |
| 13 | +## Verified repo seams |
| 14 | +- `site/preview-v2/assets/mixer-native-harmony.js`: only 3,4,5 buttons, factory Duo `voices:2`, valid range 2..5; native editor uses queued control + ACK/readback. |
| 15 | +- `engine/builtin_fx/HarmonyDsp.h`: pitched wet backing shifters and spatial room, but no distinct unison Doubler mode. |
| 16 | +- `site/preview-v2/assets/mixer-native-compressor.js` and `mixer-native-vocal-throw.js`: fixed Factory presets / 'CUSTOM' display; no persistent user library. `mixer-native-peq.js`: editable EQ without shared preset bar. |
| 17 | +- `engine/builtin_fx/Channel{Eq,Compressor,Harmony}Processor.h`, `VocalThrowProcessor.h`: separate native parameter/state implementations. `restoreUnpublishedState` is for an unpublished processor, NOT automatic live preset recall. |
| 18 | +- Existing `src/NativePresetArchive.h` / `docs/P2_NATIVE_PRESETS.md` `.armix` archives represent My Sounds/whole multi-insert chain including vendor state, NOT a per-built-in-FX preset. `.smix` is a mixer session. Avoid conflating all three. |
| 19 | + |
| 20 | +## Professional UX and acoustic references |
| 21 | +- [FabFilter Pro-Q 4 saving presets](https://www.fabfilter.com/help/pro-q/presets/savingpresets) + [loading presets](https://www.fabfilter.com/help/pro-q/presets/loadingpresets): header preset name, Save As, factory/user organization, confirmation before user overwrite, dirty state. Adopt behaviors not copyrighted artwork. |
| 22 | +- [iZotope Nectar 3 preset window](https://s3.amazonaws.com/izotopedownloads/docs/nectar300/en/presets/index.html): factory vs Custom and Working Settings. |
| 23 | +- [Valhalla DSP preset menu](https://valhalladsp.com/2012/03/12/valhallaubermod-the-preset-menu/): lightweight dropdown/Save As, portable copy. Advanced clipboard/favorites optional. |
| 24 | +- [BOSS VE-20 Double/Harmony](https://www.manualslib.com/manual/141723/Boss-Vocal-Performer-Ve-20.html?page=18): Double and Unison are distinct from pitched harmonization. Adapt clear product semantics. |
| 25 | + |
| 26 | +## P0: Direct 2-voice selector |
| 27 | +- VOICES `[2] [3] [4] [5]`, equal size, compact, keyboard accessible, selected state follows accepted native DSP readback, not speculative click. Tooltip "2 harmony voices + lead". |
| 28 | +- `Natural Duo` must visibly select 2; selecting 2 must send real `voices=2` and highlight after matching instance/revision DSP ACK+snapshot. Native editor reopen, `.smix` recall, device reconnect and switching 2→5→2 agree. |
| 29 | +- No implicit Pitch Tune enable on Duo, 2/3/4/5 or other preset. Do not change legacy voice count semantics. Add Chromium desktop/compact screenshots and direct button/preset/ACK tests. |
| 30 | +- PR #529 owns the same GUI file: do not produce two competing edits. |
| 31 | + |
| 32 | +## P1: Real Doubler engine and UX |
| 33 | +- One explicit, versioned `HarmonyMode::Harmony | Doubler` (name adjustable) carried by DSP settings, state serialization/migration, native GUI control and accepted readback. **Never use voices=1 as a fake flag or reinterpret existing 2 as doubling.** Old saved states map to Harmony with original voice count. |
| 34 | +- Doubler generates a parallel unison take of lead F0/melody, with small deterministic phrase-aware timing deviations, subtle cent variation and individualized spectral contour, modest stereo/room. Avoid one fixed slap delay, extreme flanging, artificial note hops, constant over-vibrato or vocal muddiness. |
| 35 | +- Compact UX: `DOUBLER | HARMONY` segmented choice or explicit `Double Light` / `Double Wide` real audio presets next to existing controls. Relevance of Key/Music should be truthful; Doubler does not require Music key and cannot secretly activate lead Pitch Tune. |
| 36 | +- Harmony retains 2–5 pitched wet voices; `Natural Duo` remains two harmonic backing parts, not unison. Shared Space/Wet/Color/Gain, delayed original lead, existing rack bypass and PDC. |
| 37 | +- Tests: dry/Wet0 exact lead, F0 of unison double vs pitched duo distinct, mono phase and stereo stability, 32–192k rate, callbacks 64/128/256, device restart, v1/v2/updated-schema migration, CPU and real-singer loudness-matched A/B. Naturalness is **not** verified by synthetic PCM. |
| 38 | + |
| 39 | +## P1: Shared professional preset bar for ALL native built-in FX |
| 40 | +Compact conceptual header, adjusted to each editor width (not a bulky popup): |
| 41 | +``` |
| 42 | +[ Factory: Vocal Warm ▼ * ] [‹] [›] [Save ▾] [FX Power] [Close] |
| 43 | +Menu: Factory / My Presets / Save As... / Save / Rename / Delete |
| 44 | +``` |
| 45 | +- One reusable `BuiltInFxPresetBar` UX/controller, with per-editor styling only; no four bespoke preset systems and no oversized fonts/cards. |
| 46 | +- Factory presets immutable; user can start from them and `Save As` a new named user preset. Applied changes show `Modified` or *; never silently overwrite Factory. |
| 47 | +- Save As: small anchored floating name editor, current suggested name preselected, optional category, Save/Cancel, Enter/Esc and focus restoration. Duplicate same effect/category/name gets explicit conflict handling. Save overwrites a user-owned preset only with suitable confirmation; Save As always creates new ID. |
| 48 | +- My Presets browsable in same dropdown, category grouping, sort stable, selected name, optional prev/next; on cramped editor hide prev/next before hiding Save As. Rename/delete only users and confirm. Recall dirty working sound with transparent unsaved-change warning or lightweight working settings/undo. No fake SAVE while DSP pending. |
| 49 | +- Native apply shows temporary honest pending status; persistent save only confirms after atomic disk commit, preset recall only confirms after exact DSP-applied ACK plus readback. Browser preview cannot pretend there is native audio. |
| 50 | +- Avoid chrome context menu, overflow, drag conflicts; preserve compact theme and accessible keyboard interactions. |
| 51 | + |
| 52 | +## Single durable native preset library (not localStorage) |
| 53 | +- Distinguish `.smix` mixer session, `.armix` My Sounds/FX chain, and a **separate per-FX preset format** (candidate versioned `*.armixfx`; choose exact format after auditing existing codecs). |
| 54 | +- A single CONTROL/worker-owned `BuiltInFxPresetRepository` (name tentative) stores user presets per `catalogId`. Stable `presetId` survives rename; record owner Factory/User, name, category, validated schemaVersion+typed parameters, timestamp. No immutable preset identity based on channel, slot, device or GUI label. |
| 55 | +- Use installed/portable workspace paths per `src/PortableWorkspace.h`; never put user-owned presets inside public repo or bundled release. Atomic temp-file + same-volume rename, size/name limits, safe Unicode, no path traversal/symlink escape, corruption/unsupported version fail closed, duplicate collision handling, safe backups. |
| 56 | +- One shared native contract `list/saveAs/save/recall/rename/delete` with requestId, catalogId, presetId, stable FX instanceId, channelId and current graph/document/device/library revisions. List/library actions cannot mutate DSP unexpectedly. Stale/reordered/removed instance requests get negative ACK. |
| 57 | +- **Save:** capture truly accepted, last-applied DSP parameters for exact FX instance after outstanding edits settle. No unsafe calls to realtime-owned `getStateInformation`. Disk save on worker/control and only then success. |
| 58 | +- **Recall:** worker parse/validate+migrate, control thread precompute immutable parameters, send to existing FX SPSC, native apply and accepted snapshot readback confirm. Never set unpublished-only state directly on a published processor, never file IO/parse/alloc/lock in audio callback. Parameter-only recall should not rebuild graph or force MUTE/MONITOR/ARM/APPLY. |
| 59 | +- Adapter/codec per effect: EQ band state; Compressor threshold/ratio/envelope/mix; Harmonice voice count/mode/key/wet/space/color/gain plus explicit correction; Vocal Throw delay/trigger/ducking/manual tempo. No broad Main.cpp switch proliferation; align with maintainability host-seam plan. |
| 60 | +- **Portable vs session-bound state:** A Harmony preset may contain manual key/scale and a Music mode preference, but must not embed another session's arbitrary `guideChannelId` as a globally portable binding. Similarly do not persist Vocal Throw live Music ChannelId, detected BPM, throw audio buffers or live meter. Use safe Manual fallback; session-only bindings belong to `.smix`. |
| 61 | +- **Excluded:** physical I/O, channel fader/mute/solo, WIRE, FX Rack power/slot bypass, VST3 vendor states, live audio history and global mixer session. External VST3's own preset UI remains separate. |
| 62 | + |
| 63 | +## Milestones / release gates |
| 64 | +**M0:** audit live main, #529, actual DSP codecs and portability; clarify exact bridge/owner, no duplicate host. |
| 65 | +**M1 P0:** visible 2 button, Duo parity, actual GUI/native tests/screenshots, coordinated with #529. |
| 66 | +**M2 P1:** authentic Doubler DSP mode + migrations + Double Light/Wide presets, PCM tests, A/B stems. |
| 67 | +**M3 P1:** shared native preset repository and reusable compact preset bar, prove true disk Save As / restart / another channel / audio recall on one FX. |
| 68 | +**M4 P1:** same proven service/UX integrated into EQ, Compressor, Harmonice, Vocal Throw, with individual adapters and no duplication. |
| 69 | +**M5:** selective exact-SHA native/Chromium tests, portable roundtrip, corrupt/disk-full/read-only failure, stale ACK, session/device/reorder, physical Windows ASIO singer and CPU/XRUN qualification. |
| 70 | + |
| 71 | +**Acceptance matrix:** |
| 72 | +1. VOICES 2 and Duo both render exact native `voices=2`; 2/3/4/5 parity survives restart. |
| 73 | +2. Doubler unison target vs Duo pitched targets are **audibly different and musically correct** with unchanged lead when Pitch Tune OFF. |
| 74 | +3. Every built-in: Save As → change parameters → recall → audible DSP change → cold reopen → My Presets remains → recall same preset on a second channel. |
| 75 | +4. Factory is immutable; user Save/Rename/Delete/CANCEL work; dirty state truthful. |
| 76 | +5. Corrupt/missing/duplicate preset, incompatible plugin, disk-full, stale device epoch, changed FX slot leave audio/session unmodified and report an actionable failure. |
| 77 | +6. Full `.smix` session and legacy `.armix` chain unchanged; presets survive device rebind/portable move; no second PCM authority/RT work. |
| 78 | +7. Do not claim physical ASIO or real-singer naturalness from a green CI test. Measure callback p95/p99/XRUN and listening A/B separately. |
| 79 | + |
| 80 | +**Execution instruction:** This is a repository-backed implementation plan, NOT completed feature code. Next engineering thread must reconcile current #529 ownership, implement actual DSP/GUI/preset storage in a small number of meaningful PRs, test and show exact SHA, Windows GUI screenshots, A/B audio, and honest unverified FAT gates. |
0 commit comments