Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
3a06a0e
feat(vocal-throw-m3): callback-scoped authoritative native sample-fra…
masarray Nov 8, 2026
194357d
feat(m3): timestamp music onsets in authoritative native callback sam…
masarray Nov 8, 2026
6ccb678
feat(m3): share per-render sample origin with vocal FX inside one nat…
masarray Nov 8, 2026
4f84261
feat(m3): quantize only new echo starts to frozen native music sample…
masarray Nov 8, 2026
7c94ae7
feat(m3): epoch-fenced atomic phase transport to JUCE vocal echo proc…
masarray Nov 8, 2026
f5821a6
feat(m3): deliver measured beat onset grid to native vocal inserts wi…
masarray Nov 8, 2026
338b974
test(m3): exact native sample-grid delay onset and frozen-tail stabil…
masarray Nov 8, 2026
fe188e0
test(m3): correct manual quarter-note baseline at 120 BPM in 48k PCM …
masarray Nov 8, 2026
ea4d86b
test(m3): valid 180 BPM quarter grid anchored to earlier native music…
masarray Nov 8, 2026
ca8dc05
test(m3): timestamp real music onsets and assert one scoped native sa…
masarray Nov 8, 2026
719be4a
feat(m3): independent beat-phase confidence gate, safely retain BPM-o…
masarray Nov 8, 2026
ff6b30d
fix(m3): retain detected BPM when phase ambiguous, fail closed on sta…
masarray Nov 8, 2026
d60a44e
feat(m3): distinguish reliable Auto BPM from confidence-qualified nat…
masarray Nov 8, 2026
9e710a1
ui(m3): show distinct confidence-qualified beat-grid vs BPM-only states
masarray Nov 8, 2026
6d522e1
test(m3-ui): visual BPM-only vs native beat-grid readback in desktop/…
masarray Nov 8, 2026
e229496
test(m3): genuine PCM sample clock survives graph revision; confidenc…
masarray Nov 8, 2026
2dea914
docs(m3): sample-clock musical echo grid, no-RT-work contract and fie…
masarray Nov 8, 2026
07b6162
fix(m3-ui-test): tolerate legacy BPM-only native readbacks without gr…
masarray Nov 8, 2026
433109b
test(m3-ui): wait for a fresh native snapshot request before phase-lo…
masarray Nov 8, 2026
33364fe
test(m3): no-heap callback frame epoch reset and nested render-scope …
masarray Nov 8, 2026
fe6801a
dsp(tempo): incumbent octave hysteresis and strongest coherent beat-p…
masarray Nov 8, 2026
1b5a1c3
ui(vocal-throw): precision LCD, native readback status and exact shar…
masarray Nov 8, 2026
cbc07f1
style(vocal-throw): premium calm VST face with native LCD; delegate C…
masarray Nov 8, 2026
d85a520
test(vocal-throw): exact shared EQ/Compressor 24/26px Power/Close and…
masarray Nov 8, 2026
80fcc4e
dsp(tempo): conservative beat-grid lock under competing offbeat accents
masarray Nov 8, 2026
5097d42
test(tempo): strong offbeats never certify ambiguous phase; sustained…
masarray Nov 8, 2026
fd33e36
ui(fx): common semantic Power/Close chrome across EQ, Compressor and …
masarray Nov 8, 2026
52d1da3
ui(fx): common semantic Power/Close chrome across EQ, Compressor and …
masarray Nov 8, 2026
86bc2eb
ui(fx): common semantic Power/Close chrome across EQ, Compressor and …
masarray Nov 8, 2026
b920a3c
ui(fx): common semantic Power/Close chrome across EQ, Compressor and …
masarray Nov 8, 2026
6b48071
style(fx): one shared 24px Close / 26px Power chrome for all native b…
masarray Nov 8, 2026
8dbf6d5
test(fx): shared Power and Close class contract across EQ Compressor …
masarray Nov 8, 2026
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
45 changes: 45 additions & 0 deletions docs/ARSON_VOCAL_THROW_BEAT_GRID_M3_20261109.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@
# ArSon Vocal Throw M3 — native music beat-phase quantized echo

**Branch:** `feature/arson-vocal-throw-phase-grid-m3-20261109`; builds on draft M2 PR #474 (which builds on M1 PR #469). Product issue #473. **Not a hardware-certified stage release.**

## What changed

A stable BPM alone cannot locate the *beat boundary*. M3 shares the existing native ChannelId audio renderer's monotonically increasing callback frame counter with its built-in FX processing, then quantizes **only the newly scheduled echo** when the selected MUSIC ChannelId has a credible beat-phase estimate.

```
ONE native ASIO/JUCE ChannelId render (epoch + graph revision)
beginAudioBlock(frames) -> monotonic native sample-frame start
NativeBeatFrameScope (thread-local, callback-only and restored on exit)
pre-FX MUSIC ChannelId -> 10ms nonmutating energy frames
each summary carries its exact observed audio end-frame (within 10ms)
SPSC -> existing control timer -> BPM, onset anchor, phase confidence
CONTROL publishes BPM + sample-frame anchor + epoch/revision to FX
-> atomic version-fenced snapshot (one read attempt per callback)
VOICE FX on SAME callback/thread
-> read versioned tempo + scoped native frame origin
-> if source/epoch/revision invalid: accepted Manual/TAP
-> if BPM stable, beat phase weak: BPM-derived interval, NO grid
-> if BPM and phase credible: snapshot anchor & interval at THROW
-> freeze voice with existing two-tail bounded PCM
-> schedule next echo at FIRST native music grid point >=
intended (phrase end + musical subdivision), with correction
bounded to ONE subdivision and zero change to dry PCM
-> already sounding echo tails retain frozen timing across BPM/graph edits
```

### Realtime invariant
No new audio callback, dynamic allocation, model inference, FFT, lock, waiting, JS audio, logging or file I/O from the callback. Channel PCM enters one mixer graph and is never processed twice. The timing scope is a trivially copied thread-local struct, no global audio clock thread. Tempo/phase inference (up to 121 BPM candidates) is CONTROL-only. Packed atomic scalar fields are protected by an even/odd version; the audio callback makes **one** bounded read attempt and immediately falls back on inconsistency.

### Confidence and fallback
- BPM confidence and beat-phase confidence are independent. A musical onset beat grid is used only if a majority of percussive onset strength agrees on a single pulse lattice.
- Ambiguous rhythmic patterns remain **AUTO BPM · BPM only**, not a speculative grid. A missing source or stale graph becomes **Manual / TAP** without losing the accepted preset.
- A 10ms analysis window means onset time has approximately up to one window of inherent beat-position uncertainty, even though *subsequent scheduling* uses exact callback sample indices. This is not sample-perfect transient detection.
- Phase quantization is measured against **pre-FX** selected music PCM, not against a fully latency-compensated external performance clock. Vendor VST3 latency, off-beat percussion, compressed music, drift, sample-rate changes, ASIO callback reentrancy and sparse backing must still pass field tests.

### Automated acceptance
- Native DSP unit test verifies an actual frozen phrase's first echo is scheduled on the music frame lattice and remains there after transport disappears, compared with Manual/TAP quarter-note fallback; repeats at 64/128-frame PCM chunks with callback heap forbidden.
- Native graph PCM test stamps the selected music ChannelId from one authoritative callback at variable 64+36 sample chunks, verifies anchored BPM/phase confidence at 72/95/120/160 BPM, one block-clock scope, frame counter continuity after a graph revision, and restoration of callback-only context.
- Desktop/mobile Chromium smoke explicitly distinguishes a native ACKed source's **BPM only** from **BEAT GRID** status. No user-facing opt-in or extra monitor/arm step.

### Deferred release qualification
Physical ASIO 64/128 frame loops at 44.1/48/96 kHz; on-stage singer/backing leakage, syncopated 4/4 and half/double-time, large FX PDC, dropout/replug, fade/no-click audition, real CPU/xrun vs bypass, and sustained stress still require field evidence. Do not merge while the PR chain and these safety gates remain unresolved.
49 changes: 48 additions & 1 deletion engine/builtin_fx/VocalThrow.h
Original file line number Diff line number Diff line change
Expand Up @@ -100,6 +100,22 @@ class VocalThrow final {
// frozen tail keeps its interval when a backing track changes tempo.
void setMusicIntervalSamples(std::uint32_t samples) noexcept {
musicIntervalSamples_=samples;
gridValid_=false; // BPM-only mode never claims a measured beat grid.
}
// AUDIO: the JUCE insert reads the one accepted ChannelId block clock
// and control-prepared music onset anchor. Onsets are observed in 10ms
// windows, so beat-phase is approximate (not sample-perfect detection).
// The local->graph sample mapping is taken before every FX processing
// block; it works even when the insert was added after playback began.
void setMusicBeatGrid(std::uint32_t intervalSamples,
std::uint64_t anchorFrame,
std::uint64_t blockStartFrame,
bool locked) noexcept {
musicIntervalSamples_=locked?intervalSamples:0;
gridValid_=locked&&intervalSamples>0;
gridAnchorFrame_=anchorFrame;
gridBlockStartFrame_=blockStartFrame;
gridLocalStartFrame_=clock_;
}
// AUDIO: triggers the most recent word/phrase, preferring the latest
// vocal end if the singer stopped within the last 700 ms.
Expand Down Expand Up @@ -217,6 +233,8 @@ class VocalThrow final {
std::uint64_t copyEnd=0,freezeCount=0;
std::size_t copyIndex=0,sourceIndex=0;
std::uint32_t edgeSamples=0;
std::uint64_t gridAnchorFrame=0,gridCueFrame=0,gridCueLocal=0;
bool gridValid=false;
bool copying=false,playing=false;
};
bool freezeAt(std::uint64_t end) noexcept {
Expand All @@ -239,6 +257,14 @@ class VocalThrow final {
slot->active=settings_;
if(musicIntervalSamples_)
slot->active.intervalSamples=musicIntervalSamples_;
// Freeze the same accepted beat grid as the captured phrase.
// Later tempo changes, stale epochs or an unplugged MUSIC WIRE do
// not re-time an already accepted echo tail.
slot->gridValid=gridValid_;
slot->gridAnchorFrame=gridAnchorFrame_;
slot->gridCueFrame=gridBlockStartFrame_+
(gridValid_?clock_-gridLocalStartFrame_:0);
slot->gridCueLocal=clock_;
slot->copying=true;
++throwCount_;
return true;
Expand All @@ -258,7 +284,24 @@ class VocalThrow final {
if(voice.sourceIndex==historyL_.size())voice.sourceIndex=0;
if(voice.copyIndex!=voice.freezeCount)return;
voice.copying=false;
const auto first=std::max(clock_,voice.copyEnd+voice.active.intervalSamples);
std::uint64_t first=std::max(
clock_,voice.copyEnd+voice.active.intervalSamples);
if(voice.gridValid && voice.active.intervalSamples &&
first>=voice.gridCueLocal) {
const auto interval=voice.active.intervalSamples;
const auto globalFirst=voice.gridCueFrame+
(first-voice.gridCueLocal);
// Quantize only the echo onset, never the singer's dry PCM.
// Use unsigned arithmetic and bound grid correction to one
// subdivision, protecting against a stale/future anchor.
if(globalFirst>=voice.gridAnchorFrame) {
const auto remainder=
(globalFirst-voice.gridAnchorFrame)%interval;
if(remainder)first+=interval-remainder;
} else if(voice.gridAnchorFrame-globalFirst<=interval) {
first+=voice.gridAnchorFrame-globalFirst;
}
}
float amplitude=1.f;
for(int tap=0;tap<voice.active.settings.repeats;++tap) {
const auto slot=static_cast<std::size_t>(tap);
Expand Down Expand Up @@ -286,6 +329,8 @@ class VocalThrow final {
voice.copyIndex=voice.sourceIndex=0;
voice.edgeSamples=0;
voice.copying=voice.playing=false;
voice.gridValid=false;
voice.gridAnchorFrame=voice.gridCueFrame=voice.gridCueLocal=0;
voice.repeatStarts.fill(0);voice.repeatGains.fill(0.f);
}
std::fill(historyL_.begin(),historyL_.end(),0.f);
Expand All @@ -301,6 +346,8 @@ class VocalThrow final {
float duck_=1.f,wetSmoothed_=.42f;
double rate_=0.;
std::uint32_t musicIntervalSamples_=0;
std::uint64_t gridAnchorFrame_=0,gridBlockStartFrame_=0,gridLocalStartFrame_=0;
bool gridValid_=false;
unsigned throwCount_=0;
bool armed_=false,manualInCurrentPhrase_=false,ready_=false;
};
Expand Down
47 changes: 43 additions & 4 deletions engine/builtin_fx/VocalThrowProcessor.h
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
#include "VocalThrow.h"
#include "FxSpsc.h"
#include "../core/RealtimeNativeFxControl.h"
#include "../core/NativeBeatFrameContext.h"
#include <juce_audio_processors/juce_audio_processors.h>
#include <atomic>
#include <cstdint>
Expand Down Expand Up @@ -69,10 +70,31 @@ class VocalThrowProcessor final : public juce::AudioProcessor,
void processBlock(juce::AudioBuffer<double>&,juce::MidiBuffer&) override{}
void consumeRealtimeEdits() noexcept override {
if(!ready_)return;
// One atomic acquire per callback, before queueing the newest throw.
// A source change and button click cannot freeze the previous BPM.
core_.setMusicIntervalSamples(
musicInterval_.load(std::memory_order_acquire));
// One bounded attempt, never spin in ASIO. The native PCM callback
// is the ONLY owner of a valid block sample clock. A stale epoch,
// graph revision, or torn control publication falls back to TAP.
const auto block=armix::mixer::NativeBeatFrameScope::current();
const auto v0=gridVersion_.load(std::memory_order_acquire);
bool valid=block.valid && (v0&1U)==0U;
std::uint64_t anchor=0;
std::uint32_t interval=0;
if(valid) {
const auto epoch=gridEpoch_.load(std::memory_order_relaxed);
const auto revision=gridRevision_.load(std::memory_order_relaxed);
anchor=gridAnchor_.load(std::memory_order_relaxed);
interval=musicInterval_.load(std::memory_order_relaxed);
const auto v1=gridVersion_.load(std::memory_order_acquire);
valid=v0==v1 && block.epoch==epoch &&
block.revision==revision && interval>0;
}
// Low-confidence music can provide a real BPM while its beat
// position is ambiguous. Keep that useful interval, but do NOT
// claim grid quantization. If the whole transport is stale/torn,
// fall all the way back to accepted Manual/TAP.
if(valid&&anchor>0&&anchor<=block.startFrame)
core_.setMusicBeatGrid(interval,anchor,block.startFrame,true);
else
core_.setMusicIntervalSamples(valid?interval:0);
Edit e{};
if(!done_.canPush()||!commands_.pop(e))return;
const bool applied=e.kind==CommandKind::settings?
Expand Down Expand Up @@ -101,6 +123,21 @@ class VocalThrowProcessor final : public juce::AudioProcessor,
musicInterval_.store(valid?packet.intervalSamples:0,
std::memory_order_release);
}
// CONTROL ONLY: one source-derived BPM+phase packet is fenced by the
// accepted native PCM epoch/revision. The sample-grid anchor comes from
// onset timestamped INSIDE the same audio callback (10ms granularity).
// Writer is the existing serialized JUCE timer, not a second thread.
void publishMusicGrid(float bpm,std::uint64_t anchorFrame,
std::uint64_t epoch,
std::uint64_t revision) noexcept {
gridVersion_.fetch_add(1,std::memory_order_acq_rel); // odd, unstable
publishMusicBpm(bpm);
gridAnchor_.store(bpm>=60.f&&bpm<=200.f?anchorFrame:0,
std::memory_order_relaxed);
gridEpoch_.store(epoch,std::memory_order_relaxed);
gridRevision_.store(revision,std::memory_order_relaxed);
gridVersion_.fetch_add(1,std::memory_order_release); // even, ready
}
bool queueSettings(const VocalThrowSettings& settings,std::uint64_t id) noexcept {
if(!ready_||id==0)return false;
Edit e{};e.id=id;e.kind=CommandKind::settings;
Expand Down Expand Up @@ -180,6 +217,8 @@ class VocalThrowProcessor final : public juce::AudioProcessor,
VocalThrowSettings accepted_{};
std::atomic<unsigned> observedThrows_{0};
std::atomic<std::uint32_t> musicInterval_{0};
std::atomic<std::uint64_t> gridVersion_{0},gridAnchor_{0};
std::atomic<std::uint64_t> gridEpoch_{0},gridRevision_{0};
std::atomic<bool> observedTail_{false};
double rate_=0.;
float lastTempoBpm_=0.f; // CONTROL only
Expand Down
6 changes: 6 additions & 0 deletions engine/core/DynamicNativeSessionPublisher.h
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
#include "DynamicPreparedMixerBlock.h"
#include "DynamicConsoleRoutingView.h"
#include "NativeMusicTempoMonitor.h"
#include "NativeBeatFrameContext.h"
#include "RealtimeRoutePublisher.h"
#include "RealtimeRenderPermit.h"
#include <algorithm>
Expand Down Expand Up @@ -202,6 +203,11 @@ class DynamicNativeSessionPublisher final {
if(!exclusive) {
clearOutputs();return false;
}
// One sample domain for all ChannelIds and their FX racks. This
// fixed-time callback-local scope also fences bypassed/stale inserts;
// no second transport thread, allocation or callback is introduced.
const auto startFrame=musicTempo_.beginAudioBlock(deviceEpoch,frames);
NativeBeatFrameScope frameScope{deviceEpoch,snap->graphRevision,startFrame};
// Prepared FX takes precedence over the legacy external callback.
// NEVER invoke both: that would double-compress or double-reverb.
// Snapshot ownership pins the M4 instance throughout this callback;
Expand Down
32 changes: 32 additions & 0 deletions engine/core/NativeBeatFrameContext.h
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
// SPDX-License-Identifier: AGPL-3.0-only
#pragma once
#include <cstdint>

// A tiny callback-local sample-clock context, NOT a transport or second
// callback. The native ChannelId publisher owns the authoritative frame
// counter. JUCE's built-in VocalThrow reads the same context only while
// it is rendering as an insert on that callback thread. No heap or locks.
namespace armix::mixer {
struct NativeBeatFrameContext final {
std::uint64_t epoch=0,revision=0,startFrame=0;
bool valid=false;
};
inline thread_local NativeBeatFrameContext currentNativeBeatFrame{};

class NativeBeatFrameScope final {
public:
explicit NativeBeatFrameScope(std::uint64_t epoch,std::uint64_t revision,
std::uint64_t startFrame) noexcept
: previous_(currentNativeBeatFrame) {
currentNativeBeatFrame={epoch,revision,startFrame,epoch!=0&&revision!=0};
}
~NativeBeatFrameScope() noexcept {currentNativeBeatFrame=previous_;}
NativeBeatFrameScope(const NativeBeatFrameScope&)=delete;
NativeBeatFrameScope& operator=(const NativeBeatFrameScope&)=delete;
static NativeBeatFrameContext current() noexcept {
return currentNativeBeatFrame;
}
private:
NativeBeatFrameContext previous_{};
};
} // namespace armix::mixer
Loading
Loading