Skip to content

Commit ddf7b2a

Browse files
authored
docs(fx): specify Harmonice Duo/Doubler and user presets
1 parent a05485e commit ddf7b2a

1 file changed

Lines changed: 80 additions & 0 deletions

File tree

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
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

Comments
 (0)