# DeepPluck V0.4.0 Transient & Noise Engine — Implementation Report

Date: 2026-08-30
Branch: `master`

## 1. Overall Result

Status: **partial — automated implementation and verification complete; listening and Cubase acceptance remain MANUAL VERIFICATION REQUIRED**.

The compact per-voice Transient & Noise Engine is implemented, documented, built, and covered by Debug and Release regression tests. Both layers are independently bypassable and expose Level, Decay, and Tone. They join the oscillator before the established main filter and therefore obey Filter Envelope, Amp Envelope, velocity, voice gain, sample-accurate note starts, reset, and voice stealing. Plugin identity and the first sixteen parameter IDs/order are unchanged. The implementation is not declared musically/host complete until the specified listening session and Cubase validation have actually been performed.

## 2. Starting Point

- Starting branch: `master`.
- Confirmed V0.3 implementation commit: `880c2de` (`DeepPluck V0.3.0 Filter Engine`).
- Confirmed V0.3 report commit at start: `e733d53`.
- The tracked working tree was clean. Pre-existing untracked `CubaseTest/`, `Docs/DeepPluck_V0.2.0a_Master_Prompt_Rev1.txt`, and `Docs/DeepPluck_V0.2.0b_MasterPrompt_Rev1.txt` were treated as user work and left untouched.
- The supplied V0.4 master prompt was verified byte-identical to the project copy; SHA-256: `78365A77CEFF65413394BB2B4F2EB813EB8AB3F681BD9F41558ACAA2760D5896`.
- Baseline V0.3 Debug and Release builds passed all 9/9 pre-existing CTest suites before implementation.

## 3. Scope

Implemented: one focused per-voice attack transient, one per-voice filtered noise layer, two independent bypasses, Level/Decay/Tone per layer, smoothing, live decay changes, deterministic noise seeding, state migration, 24-parameter presets, compact GUI controls, automated DSP/integration/regression tests, documentation, and local Debug/Release artifacts.

Deliberately excluded: Oscillator 2, unison, effects, modulation matrix, alternate transient types, alternate noise types, sustained noise mode, meters, limiter, oversampling, preset browser, installer, and automatic system VST3 installation.

## 4. Files

New:

- `Source/Synth/DeepPluckTransientNoise.h`
- `Source/Synth/DeepPluckTransientNoise.cpp`
- `Docs/DeepPluck_V0.4.0_Transient_Noise_MasterPrompt_Rev1.txt`
- this implementation report

Changed:

- `CMakeLists.txt`, `README.md`, `ARCHITECTURE.md`
- parameter, preset, editor, synthesiser, voice, and test sources under `Source/` and `Tests/`

Intentionally untouched: `JUCE/`, `CubaseTest/`, the two untracked V0.2 prompt files, system VST3 folders, and unrelated project history. Build products remain untracked.

## 5. Architecture and Signal Flow

Each of the fixed 16 voices owns one `DeepPluckTransientNoise` instance with private envelopes, filter states, phase, PRNG state, and smoothed values. The voice index is assigned once during synthesiser configuration and participates in deterministic noise seeding.

The implemented voice path is:

```text
PolyBLEP saw + transient wavelet + filtered noise
    -> existing per-voice nonlinear 24 dB low-pass
       (base Cutoff + key tracking + Filter Envelope, Resonance, Drive, bypass)
    -> existing Amp Envelope
    -> velocity and voice gain
    -> retained steal fade / voice sum
    -> smoothed Output gain
```

The parameter cache still loads APVTS atomics once per processor block into a trivially copyable snapshot. A voice receives snapshot changes per render segment. Note-On retriggers both one-shots; hard reset and voice reuse clear all layer state. The one-shots do not own voice lifetime: the Amp Envelope remains authoritative, so long Noise Decay cannot hold a voice open.

## 6. Transient Algorithm

The transient is a short bipolar sine wavelet starting at phase zero, avoiding an uncontrolled one-sample impulse and initial DC step:

```text
f = 650 * 2^(tone * log2(8000 / 650))
transient = sin(2*pi*phase) * oneShot * (0.45 * 10^(levelDb/20)) * bypassMix
phase += f / sampleRate
```

Tone maps logarithmically from 650 Hz to 8 kHz. A 0.25 ms micro attack precedes the exponential decay. The bounded oscillator frequency, bipolar waveform, phase-zero start, and 0.45 calibration control high-frequency and peak energy without a limiter or hard clip. Musically, this produces one continuous soft/woody-to-bright/focused articulation control while retaining the oscillator as the body of the pluck.

## 7. Noise Algorithm

Noise uses a per-voice xorshift32 generator. A hashed fixed base seed includes the voice index; each Note-On additionally mixes the MIDI note and a bounded per-voice note counter. Equal voice/note/counter histories reproduce exactly, while simultaneous voices are decorrelated. No clock, `random_device`, OS entropy, shared generator, or lock is involved.

The unsigned PRNG value maps to approximately `[-1, 1]`, then passes through a fixed 60 Hz DC blocker and two cascaded one-pole low-pass stages. Tone maps logarithmically from 500 Hz to `min(16 kHz, 0.45 * sampleRate)`. The output calibration is 0.30 before the Level gain and bypass mix. This gives one compact dark/soft-to-airy/clear texture control intended to add emotion and surface detail without masking the tonal core.

## 8. One-Shot Envelopes

After the fixed micro attack, Decay means the time from a peak of 1.0 to -60 dB (`0.001`). For current level `v` and `N = round(sampleRate * decaySeconds)`:

```text
coefficient = exp(log(0.001 / v) / N)
v[n+1] = v[n] * coefficient
```

At the defined end the envelope resets to exact zero. Transient Decay spans 1–100 ms; Noise Decay spans 5–1500 ms. Shortening or extending an active decay preserves the exact current level and recalculates only the remaining curve—no retrigger, rise, discontinuity, or return to micro attack. Note-Off does not start a separate source release; the shared Amp Envelope gates the full signal. Note-On retriggers, and hard stop/reuse resets deterministically.

## 9. Bypass and Smoothing

- Transient bypass: linear 5 ms mix ramp.
- Noise bypass: linear 5 ms mix ramp.
- Transient Level and Tone/frequency: 10 ms smoothing.
- Noise Level and Tone/filter coefficient: 20 ms smoothing.

Smoothers are initialized to the correct current value during prepare/reset and synchronized at Note-On, preventing startup ramps from stale values. Active automation changes do not reset either source or envelope. Internal processing continues during a bypass ramp and while muted, while the completed off state is exact zero. Expensive target mappings are recalculated only when the corresponding value changes, not per sample.

## 10. Parameters, State and Compatibility

The eight new host-automatable IDs are appended after the original sixteen:

| ID | Range | Fresh default |
|---|---:|---:|
| `transientEnabled` | off/on | on |
| `transientLevel` | -60..0 dB | -18 dB |
| `transientDecay` | 0.001..0.100 s | 0.012 s |
| `transientTone` | 0..1 | 0.55 |
| `noiseEnabled` | off/on | on |
| `noiseLevel` | -60..0 dB | -27 dB |
| `noiseDecay` | 0.005..1.500 s | 0.120 s |
| `noiseTone` | 0..1 | 0.35 |

A fresh V0.4 instance enables both layers. A valid state with none of the eight V0.4 IDs is classified as legacy: both layer enables become false, all six continuous values receive documented V0.4 defaults, and all existing values retain the established merge behavior. A partial V0.4 state keeps every supplied new value and assigns documented defaults to each truly missing new value; it never inherits unrelated prior live settings. Tests cover V0.1, V0.2, V0.3, partial V0.4, and complete 24-value roundtrip behavior.

The test suite directly verifies the complete host parameter order. Manufacturer code `Tntx`, plugin code `DpV1`, bundle identifier `de.tonetrax.deeppluck`, buses, formats, MIDI contract, and existing parameter meanings/units remain unchanged. Generated VST3 component CID is `ABCDEF019182FAEB546E747844705631`; controller CID is `ABCDEF011234ABCD546E747844705631`.

## 11. Presets and GUI

All four factory presets retain their original sixteen values and append these settings:

| Preset | Transient | Noise |
|---|---|---|
| Deep Pluck | on, -18 dB, 0.012 s, 0.55 | on, -27 dB, 0.120 s, 0.35 |
| Soft Pluck | on, -24 dB, 0.020 s, 0.35 | on, -25 dB, 0.220 s, 0.25 |
| Tight Pluck | on, -13 dB, 0.006 s, 0.72 | on, -32 dB, 0.055 s, 0.48 |
| Long Pluck | on, -21 dB, 0.016 s, 0.48 | on, -24 dB, 0.320 s, 0.30 |

`Deep Pluck` equals the fresh APVTS defaults. Matching evaluates all 24 parameters and reports `Custom` for any non-factory combination. The development editor is 1180 × 930, displays V0.4.0, and adds one compact Transient & Noise row with two enable toggles and six rotary controls. Disabled-layer controls dim to 45% alpha. Attachments preserve host automation/state ownership; opening the editor does not modify parameters.

Compilation and hidden standalone launch smoke tests passed. Actual visual inspection of alignment, clipping, readability, and interaction is **MANUAL VERIFICATION REQUIRED**.

## 12. Gain Staging, DC and Headroom

Transient and Noise use fixed source calibrations of 0.45 and 0.30 respectively before their dB Level controls. No limiter, compressor, hard clip, or sample clamp was added.

Measured 16-voice peaks in the automated stress suite:

| Condition | Peak |
|---|---:|
| Fresh default | 0.455535 |
| Deep Pluck | 0.230145 |
| Soft Pluck | 0.156296 |
| Tight Pluck | 0.444188 |
| Long Pluck | 0.158884 |
| Maximum V0.4 layer/filter stress sequence | 0.320016 |

The isolated existing filter stress peak remains bounded at 1.23405. The noise DC assertion passed with absolute rendered mean below 0.01 for the measured one-shot; the transient begins at an exact tested zero crossing. Subjective tonal balance and perceived headroom remain part of listening acceptance.

## 13. Realtime Review

The new audio hot path performs no allocation, container growth, lock, file/network access, logging, string operation, ValueTree traversal, parameter-ID lookup, or entropy acquisition. Parameter atomics are still read into one block snapshot. PRNG state is per voice. Target gain/frequency/filter computations occur per changed segment value, not per sample. Active transient processing uses one sine plus bounded arithmetic; active noise uses xorshift and fixed filter arithmetic. Envelope/filter histories reset to finite values, all public parameter inputs are clamped/sanitized, and non-finite output triggers a controlled local reset. Existing JUCE no-denormals scope remains active at processor level.

## 14. Builds and Artifacts

Final commands and results:

```text
cmake --fresh -S . -B build -G "Visual Studio 18 2026" -A x64  -> PASS
cmake --build build --config Debug --parallel                   -> PASS
ctest --test-dir build -C Debug --output-on-failure             -> 11/11 PASS
cmake --build build --config Release --parallel                 -> PASS
ctest --test-dir build -C Release --output-on-failure           -> 11/11 PASS
```

Local deliverables:

- `D:\0A_VST_Development\Artifacts\Debug\DeepPluck.exe` — 27,148,800 bytes
- `D:\0A_VST_Development\Artifacts\Debug\DeepPluck.vst3` — complete bundle; inner binary 24,762,368 bytes
- `D:\0A_VST_Development\Artifacts\Release\DeepPluck.exe` — 8,965,120 bytes
- `D:\0A_VST_Development\Artifacts\Release\DeepPluck.vst3` — complete bundle; inner binary 7,783,424 bytes

The Release `moduleinfo.json` reports product/version `DeepPluck`/`0.4.0`, vendor `ToneTrax`, and the unchanged class identities. Debug and Release standalone executables both remained alive during a two-second hidden launch smoke test and were then stopped cleanly. Nothing was installed to a system folder.

## 15. Automated Tests

Every suite passed in both Debug and Release:

1. `parameters` — 24 IDs/order/ranges/defaults, cache, presets, complete roundtrip, legacy and partial migration.
2. `oscillator` — safety, pitch, phase, PolyBLEP regression; non-harmonic energy ratio 0.0286427.
3. `envelope` — bounds/timing and live ADSR contracts.
4. `filter` — impulse/DC/sine stability, slope, resonance, drive, stress; measured slope 24.2165 dB/oct.
5. `filter_envelope` — bipolar modulation, key tracking, smoothing, bypass identity, live release.
6. `transient_noise` — source bounds, exact timing, Tone, DC, Level, deterministic PRNG/decorrelation, live Decay, bypass.
7. `transient_noise_integration` — exact both-off legacy path, full-source filter/Amp routing, offsets, live bypass, lifecycle.
8. `synthesiser` — voice ownership, velocity, release, steal, headroom.
9. `sample_accuracy` — MIDI event offsets.
10. `matrix` — 44.1/48/96 kHz × 1/32/64/127/512 samples.
11. `smoothing_stability` — automation, presets, 16-voice and repeated lifecycle stress.

Key source measurements at 48 kHz: 10 ms Transient Decay finished in 492 samples including the 12-sample micro attack; 50 ms Noise Decay finished in 2424 samples including the 24-sample micro attack; bright/dark noise difference-energy ratio 257.562; per-voice normalized noise correlation 0.05929. Complete Debug run: 0.86 s. Complete Release run: 0.33 s.

## 16. Listening Acceptance

The following tests have not been represented as completed: fresh default first impression; Legacy A/B; Transient bypass/level/decay/tone; Noise bypass/level/decay/tone; combined layers; Amp Envelope interaction; main filter interaction; live automation; velocity/polyphony/stealing; all four presets; mono/tonal balance; final Sound Manifest acceptance.

Actual finding for each item: **MANUAL VERIFICATION REQUIRED**. Automated measurements demonstrate technical behavior only and are not substituted for a listening verdict.

## 17. Cubase Validation

No system installation or Cubase session was performed. Therefore plugin discovery/identity, V0.3 project recall, fresh default and presets, automation read/write, MIDI timing, visible GUI, realtime/offline audio quality, multiple instances, unload/reload, host CPU, and project save/reopen are each **MANUAL VERIFICATION REQUIRED**.

Use the complete Release bundle at `D:\0A_VST_Development\Artifacts\Release\DeepPluck.vst3`. Record the Cubase version, 44.1/48/96 kHz test rates, tested buffer sizes (including 32/64/127/512 where supported), and every individual result in the release checklist. The bundle must be recognized as the same instrument and a V0.3 project must restore with both new layers off.

## 18. Performance and Stability

Automated stability exercised 1/4/8/16-note cases, the 17th-note steal, repeated note cycles, parameter extremes, live bypass/decay changes, 44.1/48/96 kHz, and blocks of 1/32/64/127/512 samples. All samples remained finite; voices returned to zero ownership without growth or hangs. The implementation adds one short sine per active transient sample and one xorshift plus two one-pole stages per active noise sample. Long noise one-shots do not prolong voice life.

No profiler or Cubase CPU meter was run. Host CPU percentage, multi-instance limits, realtime/offline parity, and device-specific denormal performance are **MANUAL VERIFICATION REQUIRED**.

## 19. Sound Manifest Review

Design evidence supports the intended warm/soft/rounded/musical/emotional direction: phase-zero bipolar transient instead of an impulse, log Tone controls, dark default Noise Tone, conservative -18/-27 dB defaults, full routing through the musical low-pass and Amp Envelope, deterministic per-voice texture, and no loudness-restoring limiter. The design intentionally protects low-mid body and dynamics while allowing controlled articulation and air.

Attack harshness, perceived noise dominance, high-frequency fatigue, low-mid warmth, bass cleanliness, dynamic feel, and emotional character cannot be accepted without listening. Mandatory development question: *Does this improve DeepPluck as an emotional Deep House pluck instrument without weakening its identity?* Engineering answer: the design and measurements make that outcome plausible; final musical answer is **MANUAL VERIFICATION REQUIRED**.

## 20. Regression Review

- Plugin IDs, product identity, buses, formats, MIDI contract: unchanged; manifest inspected.
- Original 16 parameter IDs, order, ranges, defaults, units, and meanings: unchanged; order and values tested.
- Existing four preset values: unchanged; new values appended and full matching tested.
- V0.1/V0.2/V0.3 state restore: tested; legacy layers off and continuous defaults deterministic.
- Complete and partial V0.4 state behavior: tested.
- Both layers off: numerically identical established source path after bypass completion.
- Filter On shapes the complete source sum; Filter Envelope and key tracking remain per voice: tested.
- Amp Envelope, velocity, voice gain, sample offsets, Note-Off, reset, and stealing govern the full source: tested.
- Existing oscillator, Amp Envelope, filter, Filter Envelope, voice lifecycle, matrix, and stability suites: all pass unchanged expectations.
- No Oscillator 2, unison, effects, or extra layer modes were introduced.

## 21. Known Limitations and Technical Debt

Priority 1: complete and document the full listening and Cubase acceptance matrix before release/tagging.

Priority 2: profile Release CPU with 16 voices and several host instances at 96 kHz/small buffers; automated correctness tests do not establish a host CPU budget.

Priority 3: visually inspect the fixed 1180 × 930 editor at relevant Windows scaling factors.

Priority 4: the transient sine is calculated directly during its short active interval; only replace it with a lookup/recurrence if profiling proves material benefit.

Priority 5: host-sample-accurate parameter queues remain outside the current block-snapshot architecture. This is pre-existing and was not expanded.

## 22. Git

- Implementation commit: `2a5fbb5` — `feat: add per-voice transient and noise engine`.
- Report commit: the focused commit containing this file; its hash is reported in the final handoff.
- No push was performed.
- Excluded user files remain untracked and unchanged: `CubaseTest/`, `Docs/DeepPluck_V0.2.0a_Master_Prompt_Rev1.txt`, `Docs/DeepPluck_V0.2.0b_MasterPrompt_Rev1.txt`.
- Expected final status contains only those three pre-existing untracked paths.

## 23. Design Review

- Did the implementation improve musical quality? **Technically likely, subjectively not yet accepted.** It provides controlled articulation and texture with conservative defaults and full musical routing.
- Did complexity increase, and was it justified? **Yes.** One small per-voice component, eight parameters, and two test suites are proportionate to two independently controllable sources; no mode or feature matrix was added.
- Does it follow the Sound Manifest? **By design and measured behavior, yes; final auditory confirmation remains open.**
- Would a musician immediately hear or feel the improvement? **Expected, but MANUAL VERIFICATION REQUIRED.**
- Keep, refactor, or revert? **Keep pending manual acceptance.** Refactor only if host profiling or listening reveals a concrete issue; there is no automated evidence supporting revert.

## 24. Next Milestone Recommendation

Run one focused **V0.4.0 Musical & Cubase Release Acceptance** milestone: perform the complete listening checklist and Cubase matrix, profile host CPU, fix only acceptance-blocking V0.4 defects, then tag/release V0.4.0. Do not begin Oscillator 2, unison, or effects before this gate is passed.
