Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions .github/workflows/harmony-fast-dsp.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,10 +25,22 @@ jobs:
run: |
g++ -std=c++20 -O2 -Wall -Wextra tests/harmony_pitch_synchronous_test.cpp -o /tmp/arson-harmony-psola
/tmp/arson-harmony-psola
- name: Prove low-register 65 Hz causal lookback and reject unsafe 16 ms claim
run: |
g++ -std=c++20 -O2 -Wall -Wextra tests/harmony_low_register_quality_gate_test.cpp -o /tmp/harmonice-low-singer
/tmp/harmonice-low-singer
- name: Compile and run complete engine dry, pitch, stereo and graph-independent PCM fixtures
run: |
g++ -std=c++20 -O2 -Wall -Wextra tests/harmony_dsp_test.cpp -o /tmp/arson-harmony-engine
/tmp/arson-harmony-engine
- name: Compile offline 32/24/16 ms PDC and partition safety matrix (NOT singer QA)
run: |
g++ -std=c++20 -O2 -Wall -Wextra tests/harmony_latency_candidate_test.cpp -o /tmp/harmonice-latency-study
/tmp/harmonice-latency-study
- name: Measure 32/24/16 ms DSP-only CPU tails on same Linux runner (non-gating)
run: |
g++ -std=c++20 -O2 -Wall -Wextra tests/harmony_cpu_profile_test.cpp -o /tmp/harmonice-cpu-study
/tmp/harmonice-cpu-study --latency-quick
- name: Verify stage separation, mono and exact PCM
run: |
g++ -std=c++20 -O2 -Wall -Wextra tests/harmony_stage_spatial_test.cpp -o /tmp/arson-harmony-spatial
Expand All @@ -37,3 +49,4 @@ jobs:
run: |
g++ -std=c++20 -O2 -Wall -Wextra tools/harmony_offline_ab.cpp -o /tmp/arson-harmony-ab
/tmp/arson-harmony-ab --self-test
python3 tests/harmonice_quality_report_contract_test.py /tmp/arson-harmony-ab
15 changes: 15 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,21 @@ if(BUILD_TESTING)
add_executable(ARMixHarmonyOfflineAb tools/harmony_offline_ab.cpp)
target_compile_features(ARMixHarmonyOfflineAb PRIVATE cxx_std_20)
add_test(NAME NativeHarmonyOfflineDryAndABRenderHarness COMMAND ARMixHarmonyOfflineAb --self-test)
add_test(NAME NativeHarmoniceSyntheticWavABAndQualityReport
COMMAND "${Python3_EXECUTABLE}" "${CMAKE_CURRENT_SOURCE_DIR}/tests/harmonice_quality_report_contract_test.py"
"$<TARGET_FILE:ARMixHarmonyOfflineAb>")
# P1 experimental grain comparison: no change to the shipping 32 ms DSP.
# CTest only proves bounded PCM/PDC/partition parity, not vocal quality.
add_executable(ARMixHarmoniceLatencyStudyTests tests/harmony_latency_candidate_test.cpp)
target_compile_features(ARMixHarmoniceLatencyStudyTests PRIVATE cxx_std_20)
add_test(NAME NativeHarmoniceOfflineLatencyCandidatePcmSafety
COMMAND ARMixHarmoniceLatencyStudyTests)
# Explicit causal low-singer bound: 16ms cannot safely promise PSOLA
# coverage across the documented 65Hz source range.
add_executable(ARMixHarmoniceLowSingerGate tests/harmony_low_register_quality_gate_test.cpp)
target_compile_features(ARMixHarmoniceLowSingerGate PRIVATE cxx_std_20)
add_test(NAME NativeHarmoniceLowSingerPsolaCausalCoverage
COMMAND ARMixHarmoniceLowSingerGate)
add_executable(ARMixHarmonyPitchSyncTests tests/harmony_pitch_synchronous_test.cpp)
target_compile_features(ARMixHarmonyPitchSyncTests PRIVATE cxx_std_20)
add_test(NAME NativeHarmonyPitchSynchronousFormantCandidateAndBlockParity COMMAND ARMixHarmonyPitchSyncTests)
Expand Down
61 changes: 61 additions & 0 deletions docs/HARMONICE_P1_QUALITY_LATENCY_EVIDENCE_20261110.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# Harmonice P1 — latency/quality engineering evidence, 2026-11-10

**Status: experimental; NOT PRODUCTION APPROVED.** Shipping native `ChannelHarmonyProcessor` calls only `Engine::prepare(rate)`, retaining the approved **32 ms algorithmic latency**. Do not advertise a new live latency, guaranteed acoustic naturalness or physical ASIO XRUN result.

## Checkpoints / independent ownership

- Baseline main `6bcf88af30629d2e20026bfa8e0a84163c06c29e`.
- Reliability parent [#509](https://github.com/masarray/arsonmix/pull/509) at `618cb67c476ffe41904175cc87890f075c9c3b21`, exact SHA Windows [run 42735079669](https://github.com/masarray/arsonmix/actions/runs/42735079669): 80/80 CTest PASS, FAT/Inno preview artifacts. 8 ms sample-rate-correct bypass and one-shot Music guide detector reset verified at that specific SHA.
- This experiment [#514](https://github.com/masarray/arsonmix/pull/514), stacked over #509, **isolates offline-only 24/16 ms preparations**. Neither mixer/device ownership nor live plugin default PDC is changed.
- Rejected CPU cursor experiment [#515](https://github.com/masarray/arsonmix/pull/515): exact same PCM but inconsistent callback tails and worse measured p50/p95; closed **unmerged**.
- Shared owner PR [#512](https://github.com/masarray/arsonmix/pull/512) overlaps #509's JUCE processor and bypass/music tests. Do **not** blindly merge #509 or its stack with #512; reconcile on current main only when the shared mixer owner is ready. Vocal Throw #507 remains separate and owner-listening blocked.

## Real latency, fixed PDC and causal PSOLA limits

Granular algorithmic delay = two 16 ms grains. Candidate delay is still **twice the actual grain length**, rounded to device-rate frames: no underreporting to JUCE/PDC. Synthetic native PCM fixture verifies Wet0 exact delayed impulse, bounded wet output, opposite-polarity stereo, stable output for callback partitions 64/127/256, at 44.1/48/96 kHz. Actual sample counts:

| Rate | 32 ms reference | 24 ms study | 16 ms study |
|---|---:|---:|---:|
| 44.1 kHz | 1412 | 1058 | 706 |
| 48 kHz | 1536 | 1152 | 768 |
| 96 kHz | 3072 | 2304 | 1536 |

**Important negative quality result, based on DSP source physics and actual shifter PCM:** `HarmonyPitchSynchronous` requires `fixedDelay >= 1.2 * sourcePeriod`. At **65 Hz**, the causal minimum is **18.46 ms**. Consequently **16 ms cannot use the pitch-synchronous path at 65 Hz**; the real shifter returns not-ready and the engine falls back to its earlier granular shifter. That fallback is an existing intended safety mechanism, but not evidence of formant-stable natural backing singers. **16 ms is rejected as a full-range quality candidate** under the current architecture. At 65 Hz 24 ms and 32 ms do produce pitch-synchronous output, proven at 44.1/48/96 kHz; 82/110/220 Hz controls also checked with 64/127 partition identity. This does *not* mean 24 ms is automatically acoustically acceptable; it merely clears one physical feasibility gate.

Candidate 24 ms reduces nominal algorithmic latency by **8 ms**, but no live runtime switch exists. True round-trip latency additionally includes ASIO buffers, input/output converters, device and other FX graph/PDC; it has **not been measured**.

## Reproducible PCM and listening instrumentation

Compile the existing native console tool, then run:

```bash
# Optional reproducible DIAGNOSTIC samples (not human singing)
ARMixHarmonyOfflineAb --synthetic-corpus /tmp/harmonice-synthetic
# Human listening source; keep original singer recordings private
ARMixHarmonyOfflineAb --latency-study path/to/original-vocal.wav /tmp/harmonice-listen
```

Accepted source: original mono/stereo PCM16/PCM24 or IEEE float32 WAV, 32–192 kHz, <=60 sec. The second command writes a reference 32 ms wet mix/dry lead and 24/16 ms candidate wet mix/dry lead **time-aligned to 32 ms**, plus `latency-study.json` with actual PDC frames, alignment offsets, source-to-source RMS difference, backing-only RMS, stereo-side/mono-fold RMS, peak sample, largest adjacent-sample step, and 65 Hz causal support. These are **diagnostics, not perceptual naturalness scores**. The WAVs are not loudness-matched; level-match separately and blind-randomize before judging sound.

The synthetic corpus includes low C2 (65 Hz), A3 (220 Hz), A4 (440 Hz), opposite-phase stereo A3, deterministically generated vowel-like harmonics, syllable onset, release and breath-like noise. Every fixture, WAV container and JSON report has an executable Python contract. There are **no original adult singer recordings in this repository** and no acoustic certification implied.

## CPU: same-runner synthetic DSP evidence, non-gating

Previous [Linux benchmark run 42752957451](https://github.com/masarray/arsonmix/actions/runs/42752957451), five backing voices, live Music key detector, 64 samples, Wet 50%, Space 60%, sustained synthetic A3:

| Rate | 32 ms p99.9 | 24 ms p99.9 | 16 ms p99.9 |
|---|---:|---:|---:|
| 48 kHz | 31.24 µs | 26.42 µs | 27.04 µs |
| 96 kHz | 23.82 µs | 27.40 µs | 25.02 µs |

No consistent synthetic CPU win or p99.9 promise; host/machine noise and lack of Windows ASIO integration make this an exploratory measurement only.

## Decision / next acceptance gates

1. **Retain 32 ms production PDC and shipping sound unchanged.** 16 ms not allowed to ship as full-range candidate.
2. 24 ms is **research-only**, pending human adult singer original recordings from low bass through soprano, consonant attacks, vibrato and stereo anti-phase, perceptually level-matched and aligned blind A/B against the exact 32 ms reference SHA; reject on metallic artifacts, formant deviation, unstable notes, stereo fold and altered room tails.
3. Windows full MSVC+CTest at **the final exact candidate SHA** plus FAT provenance if a preview is needed. PR draft quick CI is not proof of the Windows full job. Keep expensive workflows selective.
4. Physical 30-min Windows ASIO singer session with 64/128/256, 48/96 kHz where supported, guide drop/reacquisition, rack/slot bypass, device loss/restart, WIRE/SOURCE ONLY, .smix, Compressor/Player. Measure actual round-trip latency and XRUNs.
5. Neither #514 nor any QA mirror may be merged/published as stable while these gates remain open. Do not bring Vocal Throw into this task.

**Quality verdict:** exact dry timing and deterministic synthetic bounds are proven; low-note 16 ms physics disqualifies it; 24 ms remains a plausible, *unqualified* listening candidate; real-singer naturalness and Windows ASIO performance remain **NOT VERIFIED**.
22 changes: 19 additions & 3 deletions engine/builtin_fx/ChannelHarmonyProcessor.h
Original file line number Diff line number Diff line change
Expand Up @@ -33,15 +33,24 @@ class ChannelHarmonyProcessor final : public juce::AudioProcessor,
return b.getMainInputChannelSet()==juce::AudioChannelSet::stereo() &&
b.getMainOutputChannelSet()==juce::AudioChannelSet::stereo();
}
void prepareToPlay(double rate,int) override {
void prepareToPlay(double rate,int maximumExpectedSamplesPerBlock) override {
ready_=dsp_.prepare(rate)&&guide_.prepare(rate)&&dsp_.setSettings(accepted_);
guideSource_.store(accepted_.guideMode==1?accepted_.guideChannelId:0,
std::memory_order_release);
guideAge_=0;guideObservedKey_.store(-1,std::memory_order_relaxed);
guideObservedScale_.store(-1,std::memory_order_relaxed);
guideConfidence_.store(0.f,std::memory_order_relaxed);
publishEffectiveKey();
if(ready_) {sampleRate_=rate;setLatencySamples(dsp_.latencySamples());}
if(ready_) {
// FxInstance samples the AudioProcessor rate once, when its fixed
// 8 ms bypass envelope is prepared. Native built-ins are prepared
// directly; without JUCE rate metadata it otherwise sees zero
// and fades in only 64 samples at real 48/96 kHz device rates.
setRateAndBufferSizeDetails(rate,
std::max(1,maximumExpectedSamplesPerBlock));
sampleRate_=rate;
setLatencySamples(dsp_.latencySamples());
}
}
void releaseResources() override {ready_=false;}
void processBlock(juce::AudioBuffer<float>& samples,juce::MidiBuffer&) override {
Expand All @@ -50,9 +59,16 @@ class ChannelHarmonyProcessor final : public juce::AudioProcessor,
consumeRealtimeEdits();
// Missing/deleted/disconnected source must not leave a stale accepted
// tonal estimate running indefinitely. Manual Key is the fallback.
const int guideTimeout=static_cast<int>(sampleRate_*2.);
const bool guideWasFresh=guideAge_<=guideTimeout;
guideAge_=std::min(guideAge_+samples.getNumSamples(),
static_cast<int>(sampleRate_*3.));
if(guideAge_>static_cast<int>(sampleRate_*2.)){
if(guideWasFresh&&guideAge_>guideTimeout){
// The guide source went missing. A detector that still retains
// old chroma would publish the old key on the FIRST resumed
// source block, before gathering fresh evidence. Invalidate once
// at the missing-source boundary, not at every audio callback.
guide_.reset();
dsp_.setGuideKey(-1,-1);
guideObservedKey_.store(-1,std::memory_order_relaxed);
guideObservedScale_.store(-1,std::memory_order_relaxed);
Expand Down
19 changes: 17 additions & 2 deletions engine/builtin_fx/HarmonyDsp.h
Original file line number Diff line number Diff line change
Expand Up @@ -73,10 +73,24 @@ class Engine final {
// history = 15360, so 16384 frames retain the full rate/ratio budget.
// Halves the three large audio rings per instance without RT allocation.
static constexpr std::size_t capacity=16384;
bool prepare(double rate) noexcept {
// Production ALWAYS uses the established 32 ms PDC. This opt-in entry
// exists ONLY for offline source-aligned latency/sound studies. Never
// select a shorter grain from session state, UI, or the ASIO callback.
bool prepare(double rate) noexcept {return prepareWithGrain(rate,0);}
bool prepareForOfflineLatencyStudy(double rate,int algorithmicMs) noexcept {
if(!std::isfinite(rate)||rate<32000.||rate>192000.||
(algorithmicMs!=24&&algorithmicMs!=16))return false;
// Device-rate frames, never a fixed-size millisecond approximation.
const int candidateGrain=static_cast<int>(std::lround(
rate*static_cast<double>(algorithmicMs)/2000.));
return prepareWithGrain(rate,candidateGrain);
}
private:
bool prepareWithGrain(double rate,int candidateGrain) noexcept {
if(!std::isfinite(rate)||rate<32000.||rate>192000.)return false;
rate_=rate;
grain_=std::clamp(static_cast<int>(std::round(rate*0.016)),256,3072);
grain_=candidateGrain>0?candidateGrain:
std::clamp(static_cast<int>(std::round(rate*0.016)),256,3072);
latency_=2*grain_;
decimation_=std::max(1,static_cast<int>(std::round(rate/12000.)));
detectEvery_=std::max(128,static_cast<int>(rate/150.));
Expand Down Expand Up @@ -127,6 +141,7 @@ class Engine final {
processed_=false;settings_=Settings{};
return setSettings(settings_);
}
public:
// Prepared on the CONTROL thread. Immutable edit data is copied through
// the existing SPSC; applying it on the callback needs only fixed copies.
struct PreparedSettings {
Expand Down
112 changes: 112 additions & 0 deletions tests/harmonice_quality_report_contract_test.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,112 @@
#!/usr/bin/env python3
"""Harmonice offline quality-study contract. Synthetic output != singer qualification.

This verifier tests the real C++ WAV renderer, not just isolated fake metrics:
four synthetic sources, 32/24/16ms source alignment, float32 RIFF integrity,
candidate causal bass limitation, dry-lead sample identity and honest metadata.
"""
import json
import math
from pathlib import Path
import struct
import subprocess
import sys
import tempfile

CASES = {
"SYNTHETIC_low_C2_65Hz": False,
"SYNTHETIC_mid_A3_220Hz": False,
"SYNTHETIC_high_A4_440Hz": False,
"SYNTHETIC_antiphase_A3_220Hz": True,
}


def float32_stereo(path: Path):
data = path.read_bytes()
assert len(data) >= 44 and data[:4] == b"RIFF" and data[8:12] == b"WAVE", path
assert int.from_bytes(data[4:8], "little") + 8 == len(data), path
cursor, audio, fmt = 12, None, None
while cursor + 8 <= len(data):
tag = data[cursor:cursor + 4]
n = int.from_bytes(data[cursor + 4:cursor + 8], "little")
begin = cursor + 8
assert begin + n <= len(data), path
if tag == b"fmt ":
fmt = struct.unpack_from("<HHIIHH", data, begin)
if tag == b"data":
audio = memoryview(data)[begin:begin + n]
cursor = begin + n + (n & 1)
assert fmt is not None and fmt[0] == 3 and fmt[1] == 2
assert fmt[2] == 48000 and fmt[4] == 8 and fmt[5] == 32
assert audio is not None and len(audio) % 8 == 0
assert len(audio) >= 48000 * 8
return audio


def check_file_pair(base: Path, aligned: Path, reference_offset: int, tolerance=0.0):
a, b = float32_stereo(base), float32_stereo(aligned)
assert len(a) == len(b), (base, aligned)
for offset in range(reference_offset * 8, len(a), 8):
al, ar = struct.unpack_from("<ff", a, offset)
bl, br = struct.unpack_from("<ff", b, offset)
assert all(map(math.isfinite, (al, ar, bl, br))), aligned
assert abs(al - bl) <= tolerance and abs(ar - br) <= tolerance, (
base, aligned, offset // 8, (al, ar), (bl, br)
)


def main(exe: str):
with tempfile.TemporaryDirectory(prefix="harmonice_quality_") as temp:
folder = Path(temp) / "quality"
subprocess.run([exe, "--synthetic-corpus", str(folder)], check=True,
timeout=180)
disclaimer = (folder / "READ_ME_FIRST.txt").read_text()
assert "NOT recordings of humans" in disclaimer
for name, antiphase in CASES.items():
source = float32_stereo(folder / (name + ".wav"))
if antiphase:
for k in range(2000, len(source) // 8, 397):
l, r = struct.unpack_from("<ff", source, k * 8)
assert l == -r
else:
for k in range(2000, len(source) // 8, 397):
l, r = struct.unpack_from("<ff", source, k * 8)
assert l == r
output = folder / name
metrics = json.loads((output / "latency-study.json").read_text())
assert metrics["productionPdcFrames"] == 1536
assert metrics["sourceRate"] == 48000
assert metrics["physicalAsioMeasured"] is False
assert metrics["humanSingerListeningPassed"] is False
assert metrics["syntheticFormantsProved"] is False
assert [x["targetMs"] for x in metrics["experimentalCandidates"]] == [24, 16]
assert math.isfinite(metrics["baselineBackingRms"])
reference = output / "harmonice_32ms_dry.wav"
for candidate in metrics["experimentalCandidates"]:
ms = candidate["targetMs"]
expected_frames = {24: 1152, 16: 768}[ms]
assert candidate["reportedPdcFrames"] == expected_frames
assert candidate["offlineAlignmentFrames"] == 1536 - expected_frames
assert candidate["qualityAccepted"] is False
assert candidate["pitchSync65HzCausallySupported"] is (ms == 24)
assert abs(candidate["alignedDryDifferenceRms"]) < 1e-7
for metric in ("wetBackingRms", "wetBackingRmsRelativeTo32ms",
"stereoSideRms", "monoFoldRms", "maximumAbsSample",
"maximumOneSampleStep", "alignedMixDifferenceRms"):
assert math.isfinite(candidate[metric]), (name, ms, metric)
assert candidate[metric] >= 0
assert candidate["maximumAbsSample"] <= 4
check_file_pair(
reference, output / f"harmonice_{ms}ms_dry_aligned.wav",
1536 + 256
)
print(f"HARMONICE_SYNTHETIC_CORPUS_VALID source={name} "
"dry_alignment=sample_exact 16ms_bass_gate=blocked "
"no_human_singer_quality_claim=true")
print("Harmonice four-fixture WAV/JSON quality contract PASS (synthetic only)")


if __name__ == "__main__":
if len(sys.argv) != 2:
raise SystemExit("usage: harmonice_quality_report_contract_test.py <harmonice-ab-exe>")
main(sys.argv[1])
Loading
Loading