Skip to content

fix(transport): anchor JUCE position polls at the IPC midpoint and slew - #1122

Open
odntht wants to merge 1 commit into
got-feedBack:mainfrom
odntht:fix/juce-transport-anchor
Open

odntht wants to merge 1 commit into
got-feedBack:mainfrom
odntht:fix/juce-transport-anchor

Conversation

@odntht

@odntht odntht commented Oct 16, 2026 •

Copy link
Copy Markdown

What was wrong

static/js/transport.js (jucePlayer._startPolling, lines 128-139 at eef58c8) polls getBackingPosition() every 100 ms in desktop/JUCE mode and interpolates between polls:

self._pos = await window.feedBackDesktop.audio.getBackingPosition();
self._pollAt = performance.now();

_pollAt is taken after the await, so every anchor is stale by the IPC round trip plus any delay before the renderer main thread resumes the await. The engine's position is also block-quantized (~10.7 ms at 512/48k). Each new sample therefore lands a few ms to tens of ms behind the extrapolation, and the clock that the highway, _audioTime(), plugins and song:position-changed read can step backwards on a poll. How often depends on IPC latency: rarely on a fast Linux box, more often with slow or jittery IPC (see measurements). An in-flight poll reply that crosses a seek() also overwrites the new position with the old one.

The fix

  • Take t0 before the call. The engine reads its position somewhere inside [t0, t1], so anchor the sample at the midpoint.
  • Fold small errors in by slewing. The clock runs up to 10% fast or slow until the error is absorbed, and it is never stepped. Between repositions the clock is monotonic.
  • Treat errors of 250 ms or more as a real discontinuity, for example an engine-side loop or a stall, and snap to them.
  • Replies with a round trip over 40 ms can't be anchored precisely. They only count if they show such a discontinuity.
  • Every reposition (seek, pause, rate change, route hand-off) goes through _setAnchor(). It bumps a generation, so a poll reply that was in flight across it is dropped. juce-audio.js uses it for the HTML5 to JUCE hand-off instead of writing _pos/_pollAt directly.

This stays consistent with #1117. That PR smooths the highway render clock downstream of setTime(). This PR fixes the source clock in JUCE mode, so #1117's loop gets a monotonic, unbiased input and only rarely needs its 50 ms snap. The two PRs are independent and don't touch the same files.

Evidence

New test tests/js/juce_transport_clock.test.js runs the real jucePlayer object (extracted from transport.js) against a simulated engine, IPC and a 60 Hz rAF sampler in virtual time. The engine position moves in 512-frame blocks. The engine reads its position at a random point inside each IPC round trip. The test asserts: no backward steps, a stddev of Δchart/Δwall below 0.08, max error below 30 ms, no bias under a constant 30 ms round trip, correct seek with a poll in flight, and a snap on an engine-side jump.

Same harness, 60 s × 5 seeds per scenario, origin/main vs this branch:

IPC scenario backward steps / 60 s stddev Δchart/Δwall max error mean lag
1-6 ms RTT, 10% slow (15-40 ms) 21 → 0 0.208 → 0.062 45.6 → 23.2 ms 3.2 → -0.3 ms
constant 30 ms RTT 1 → 0 0.093 → 0.046 25.3 → 10.3 ms 15.0 → 0.4 ms
2 ms IPC, reply delayed 0-50 ms (busy renderer) 86.6 → 0 0.469 → 0.068 60.8 → 25.4 ms 8.1 → 1.9 ms

These numbers come from a model of the IPC, not from the live app.

Measured in the real desktop app (Linux)

Same desktop build (desktop origin/main, real JUCE addon, ALSA HDMI 0 at 48 kHz / 256). The probe:

  1. loads a 150 s WAV with loadBackingTrack;
  2. calls jucePlayer.play();
  3. samples jucePlayer.currentTime on every rAF for 60 s (3602 frames);
  4. also runs an independent tight-RTT (< 4 ms) getBackingPosition() probe as the engine reference.

3 launches per cell, main → branch:

renderer stall backward steps (sum of 3 × 60 s) stddev Δclock/Δwall median clock − engine
none 0 → 0 0.054 → 0.033 -0.4..0.3 → 0.3..0.7 ms
30 ms every 1 s 1 → 0 0.054 → 0.029 -0.1..0.2 → 0.3..0.8 ms

Honest reading: on this Linux box the getBackingPosition round trip is well under 1 ms, so main barely steps backwards (1 step in 3 minutes). The real-app gain here is a ~40% smoother per-frame clock, with no backward steps and no measurable bias. The larger backward-step counts in the model table need slower or jittery IPC, as on a loaded Windows machine. I couldn't measure those systems.

To reproduce: node --test tests/js/juce_transport_clock.test.js. For the main-vs-branch table, point the harness's simulate() at either version of transport.js.

Tests

  • npm run test:js: 1212 pass, 0 fail.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Bug Fixes
    • Improved playback-position accuracy and stability during JUCE playback, reducing backward jumps and timing drift.
    • Playback position now responds more reliably to seeks, playback-rate changes, pauses, and stops.
    • Reduced timing bias caused by communication delays and prevented outdated position updates from overriding a recent seek.

jucePlayer set its interpolation anchor to performance.now() after the
awaited getBackingPosition() resolved, so every anchor was stale by the
IPC round trip (plus any renderer main-thread delay before the await
resumed). With latency jitter and the engine's block-quantized position
the interpolated clock stepped backwards on many polls.

Take t0 before the call and anchor the sample at the midpoint of the
round trip. Fold small errors in by slewing the clock up to 10% fast or
slow instead of stepping, keep it monotonic between repositions, ignore
slow replies unless they show a real discontinuity (>= 250 ms snaps),
and drop poll replies that were in flight across a seek, pause or rate
change. The route hand-off in juce-audio.js re-anchors through the same
_setAnchor() helper.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Signed-off-by: odntht <odntht@gmail.com>
@coderabbitai

coderabbitai Bot commented Oct 16, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: defaults
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: 9583b772-3101-4d07-9466-99e257ed7536
📥 Commits

Reviewing files that changed from the base of the PR and between eef58c8 and 47ba3cb.

📒 Files selected for processing: 4
  • static/js/juce-audio.js
  • static/js/transport.js
  • tests/js/juce_engine_reroute.test.js
  • tests/js/juce_transport_clock.test.js

Included review availability: This review used your included allowance. Your plan provides up to 2 included reviews per hour; 0 remain after this review.

📝 Walkthrough

The JUCE player now interpolates between position polls and corrects its clock for IPC latency. Transport changes use clock anchors, and stale poll replies are discarded. New simulations test clock behavior under jitter, delay, seeks, and engine-side jumps.

Changes: JUCE transport clock

Layer / File(s) Summary
Clock correction and transport anchors
static/js/transport.js, static/js/juce-audio.js
The player adjusts polled positions for IPC latency, slews small errors, snaps larger errors, and prevents backward movement. Pause, seek, rate changes, stop, and JUCE routing use clock anchors. Poll replies are ignored when a transport change invalidates them.
Clock simulation and assertions
tests/js/juce_transport_clock.test.js, tests/js/juce_engine_reroute.test.js
The tests simulate position polls with configurable latency, jitter, seeks, and engine-side jumps. They check clock direction, rate variation, and error against engine time.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant jucePlayer
  participant JUCE_IPC
  participant JUCE_engine
  jucePlayer->>JUCE_IPC: Request engine position
  JUCE_IPC->>JUCE_engine: Read position
  JUCE_engine-->>JUCE_IPC: Return position
  JUCE_IPC-->>jucePlayer: Return position sample
  jucePlayer->>jucePlayer: Adjust sample and update clock
Loading

Suggested reviewers: byrongamatos

Merge Risk: ⚪ Minimal · up to 47ba3

No confirmed issue blocks merging. Seek and poll ordering remains unverified in the desktop bridge.

Pre-merge checks: Passed 3 · Failed 2

Failed Failed checks: 2 warnings

Check name Status Explanation Resolution
Description check Warning The description gives a detailed explanation of the problem, implementation, evidence, and test results. However, it does not include the required feedpak surface section or the required checklist con… Add the required feedpak surface section, complete the checklist for CHANGELOG.md, tests, and DCO sign-off, and include the issue link or state why no issue applies.
Docstring Coverage Warning Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 8 functions across 4 files. Write docstrings for the functions missing them to satisfy the coverage threshold.
Passed Passed checks: 3 passed
Check name Status Explanation
Title check Passed The title clearly and concisely describes the primary change: midpoint anchoring and slewing for JUCE transport position polls.
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Full details: Description check

Explanation

The description gives a detailed explanation of the problem, implementation, evidence, and test results. However, it does not include the required feedpak surface section or the required checklist confirmations, and it does not provide a direct issue link.

Resolution

Add the required feedpak surface section, complete the checklist for CHANGELOG.md, tests, and DCO sign-off, and include the issue link or state why no issue applies.

  • Fix all pre-merge checks with AI
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

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