Skip to content

Fix correctness bugs in Adjust Sync BPM/offset detection - #370

Open
petoollu wants to merge 10 commits into
uvcat7:betafrom
petoollu:fix/adjust-sync-detection
Open

petoollu wants to merge 10 commits into
uvcat7:betafrom
petoollu:fix/adjust-sync-detection

Conversation

@petoollu

@petoollu petoollu commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Correctness and robustness fixes for the "Find BPM" detector in the Adjust Sync dialog (AdjustSync.cpp → FindTempo.cpp → FindOnsets.cpp). The detector was already accurate — these are not accuracy improvements, and measurements against a reference pack (including a 120 BPM metronome with exact-boundary clicks) confirm the fixes don't move the results:

before after
BPM correct, reference pack 5 / 5 5 / 5
Offset mean absolute error, reference pack 11.9 ms 12.3 ms
BPM correct, second corpus 12 / 12 12 / 12
Offset mean absolute error, second corpus 28.1 ms 28.2 ms
  • Thread cancellation never worked: BackgroundThread::getStopToken() returned a token tied to the jthread's pre-start() state, so cancellation could never fire and also raced with Sound::Thread's worker. Fixed by owning a std::stop_source in the constructor.
  • Hamming window misalignment in GapConfidence: wrapping past position 0 restarted the window at its own index 0 instead of continuing from the wrapped offset, suppressing scores in the first half-window of every candidate interval.
  • One-element OOB write in GapData::wrappedOnsets when a BPM candidate rounds to exactly the minimum (89 BPM).
  • Redundant ~230 MB allocation: AdjustForOffbeats rebuilt a whole-waveform slope array once per BPM candidate (up to 3x); now computed once and shared.
  • Misleading confidence percentage: candidate fitness was shown as a share of the sum of all candidates (so a correct top pick could read 34–53%) instead of relative to the best candidate (now always 100% for the top pick).

Two plausible-looking changes were tried, measured, and deliberately not made — see docs/adjust-sync-detection-fixes.md for why (clearing aubio's onset delay, and extending loudness weighting past the first 100 onsets), along with the known, not-yet-addressed weaknesses (hard-clamped BPM search range, a latent tie-break in AdjustForOffbeats).

Full write-up with validation methodology: docs/adjust-sync-detection-fixes.md.

petoollu and others added 10 commits September 13, 2026 09:43
BackgroundThread::getStopToken() returned thread.get_stop_token(). A
default-constructed std::jthread has no stop state, and start() replaces the
whole jthread object, so:

  - TempoDetectorImp took its token before start() and got a permanently dead
    token. stop_possible() was false and the MarkProgress cancellation check
    in the BPM detector could never fire, so closing the Adjust Sync dialog or
    restarting detection blocked the UI thread in join() until the whole
    analysis finished.
  - Sound::Thread took its token from inside the worker, racing with the
    assignment to thread in start().

Give BackgroundThread its own stop_source, created in the constructor, so a
token is valid before, during and after start(). OggConversionThread does not
poll the token and is unaffected. No effect on detection results.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
GapConfidence slides a Hamming window over the wrapped onset histogram to
score a candidate beat position. When the window wrapped past position 0, the
loop start was clamped to 0 and the window then restarted at its own index 0
instead of continuing from where the wrapped part left off, double-counting
the low window weights and never reaching the high ones.

A lone onset sitting exactly on the candidate position should always score the
window's peak weight of 1.0. Before this change it scored 0.08 at position 0,
0.10 at 100 and 0.54 at 512, reaching 1.0 only from 1023 onwards. Positions in
the first half window of an interval could therefore never win, which put a
blind spot over roughly the first 2-3% of every candidate interval.

The fix can only raise a score that was being suppressed, never lower a
correct one. Measured effect is small: a fraction of a millisecond of offset
on most songs, and on a sparse 17 s reference file it replaces a spurious
160.111 BPM third candidate with a sensible 128.160.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
GapData::wrappedOnsets was sized bufferSize, but callers index it with
(int)fmod(onsetPos, intervalf), where intervalf is a double that can sit a
fraction above the integer bufferSize the caller sized it from. At the bottom
of the BPM range, when RoundBPMValues tests a candidate rounded down to
exactly 89 BPM, that index reaches bufferSize itself and writes one element
past the end.

CalculateOffset already guarded this by adding 1.0 to its buffer size; the
path through CalculateBPM did not. Allocate the slack in GapData so every call
site is covered. No behaviour change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
AdjustForOffbeats built a slope representation of the entire waveform, one
double per frame, and did it once for every BPM candidate: up to three times
per detection with identical results. On a ten-minute song at 48 kHz that is a
~230 MB allocation and a full pass over the audio, repeated three times.

Hoist it into CalculateOffset and pass it in. Also adds a null check on the
allocation, which was previously missing and would have been dereferenced by
ComputeSlopes. Performance only, no change to results.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Each candidate's fitness was divided by the sum of all candidates' fitness and
shown as a percentage. With three candidates the top one can never exceed 100%
and can read as low as 34%, so a perfectly good detection displayed as "53%"
purely because two other candidates happened to survive. That reads as low
confidence when it is really just three-way arithmetic.

Fitness values are relative scores with a fitted baseline subtracted; their
absolute size means nothing and they can go negative, so a share of the sum is
not a confidence. Scale against the best candidate instead, so the top pick
always reads 100% and the others say how much weaker they are. Guard against a
non-positive best value while we are here. Display only.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Two things in the onset stage look like obvious bugs, were changed, measured,
and changed back. Write down the measurements so they are not re-attempted.

aubio's onset delay: aubio_onset_get_last() returns (last_onset - delay), and
since ArrowVortex analyses a decoded buffer offline rather than streaming, the
delay reads like a latency allowance that does not apply. Against a metronome
with clicks on exact 0.25 s boundaries, aubio's positions average 5.2 ms
before the true attack with the delay left alone and 19.3 ms after it once
cleared. The delay is compensating for the peak picker's group delay and is
correct as shipped.

The 100-onset limit on loudness weighting: extending it to every onset made no
measurable difference on full-length songs and broke a 17 s, 113-onset sync
test at 128 BPM, demoting the correct BPM to third behind a spurious 160 BPM.
Uniform weighting is more robust when onsets are sparse.

Also adds the missing null check on new_aubio_onset.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Describes how Find BPM works end to end, what each of the fixes in this branch
changed, the two changes that were rejected after measurement, the known
weaknesses that remain, and how to validate future changes to these files.

The validation note is the important part: hand-synced charts carry their own
systematic bias and are not usable as ground truth for the detector.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Same Thread.h/Thread.cpp conflict as before: beta's independent
thread-cancellation fix (std::thread + shared_ptr<atomic_bool>, for
broader platform support) supersedes this branch's own fix, which used
std::jthread's stop_source/stop_token. Took beta's version as-is.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant