@remotion/player: Fix audio hiccups on rapid play/pause toggling

[iliya-vidrush]

Fixes #8984

Problem

Rapidly toggling play/pause in the Player caused audible audio hiccups: the sound stopped and restarted stepwise instead of settling to the final state, and every restart faded in.

Two independent mechanisms caused this:

1. resume() in shared-audio-tags.tsx ramped the master gain 0 to 1 over 30 ms on every resume, so every play toggle produced an audible dip - even when the context merely unfroze nodes that suspend() had frozen in place sample-exact.
2. The statechange listener in use-playback.ts force-moved the audio sync anchor on every suspend. It never notified the media players, so the already-queued (frozen) nodes stayed scheduled against the old anchor and were misaligned by the shift after resume.

Changes

• remotion: resume() only applies the fade-in when there are nodes in nodesToResume that need to be started. Those begin mid-waveform and can click, which is what the fade is for. A plain unfreeze is sample-exact and no longer fades.
• @remotion/player: the suspend re-anchor now goes through the normal drift guard (ALLOWED_GLOBAL_TIME_ANCHOR_SHIFT + latency) instead of force: true. On a plain pause the drift is below the guard, so the anchor stays put and pause/play becomes a pure freeze/unfreeze of the same scheduled nodes - no teardown, no re-prime. If the drift does exceed the guard, the anchor is corrected and 'changed' is dispatched so the media players rebuild their queue against the new anchor (previously the anchor moved silently, leaving the frozen queue misaligned).
• @remotion/player: removed the now-unused force option from setGlobalTimeAnchor.
• Type cleanups: extracted the inline option types in shared-audio-tags.tsx, set-global-time-anchor.ts and use-playback.ts into named types. No behavior change.

Tradeoffs

• Small drift (below the guard) is no longer zeroed on every pause. It can accumulate across many toggles until the guard trips, which then triggers one clean re-anchor + rebuild. The maximum tolerated A/V drift is unchanged - it is the same guard the seek path already applies during playback. The old per-pause "correction" was itself defective, since it de-synced the frozen queue by the shift.
• A pure resume no longer fades in, so sound starts instantly at a non-zero-crossing - the same kind of step as the existing abrupt stop on pause (there was never a fade-out). Browsers apply their own short ramp on context suspend/resume, so I expect this to be inaudible, but it is the one thing that needs a listen test.

Testing

• tsgo clean on core, player and media; oxfmt and eslint clean on the changed files.
• bun test: 557 pass in core, 30 pass in player; the media browser suite passes (70 tests, 29 files).
• Still open: before/after measurement of the queued-ahead value from the debug overlay while mashing play/pause, as described in @remotion/media: Audio hiccups on rapid play/pause toggling in the Player #8984.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
bugs	Ready	Preview, Comment	Jul 13, 2026 6:39am
remotion	Ready	Preview, Comment	Jul 13, 2026 6:39am

[pullfrog]

Reviewed changes — fix rapid play/pause audio hiccups in the Player by conditionally skipping the resume fade-in and removing the forced audio-context-suspend re-anchor.

• packages/core/src/audio/shared-audio-tags.tsx — only applies the 30 ms master-gain fade-in when nodesToResume has entries; pure resume/unfreeze paths no longer dip the gain, which removes the per-play fade artifact.
• packages/player/src/set-global-time-anchor.ts — removes the force option and the force-specific logging, making every anchor update go through the same drift guard.
• packages/player/src/use-playback.ts — on statechange to suspended/running-to-suspended, setGlobalTimeAnchor is now called without force; if the drift exceeds the guard it dispatches 'changed', otherwise the queued nodes stay in place.

⚠️ Suspend statechange handler reads live frame, which can mis-represent a pure pause as drift

On a plain pause, suspend() is requested immediately, but the statechange event fires asynchronously once the context actually suspends. By then the Player may have rendered additional frames (or already be resuming). The handler calls getCurrentFrame() at event time to compute the anchor, but the frozen audio nodes were scheduled against the frame that was current when suspend() was requested, not against whatever frame is current when the event eventually fires.

If those two frames differ, setGlobalTimeAnchor can report a shift that is larger than the guard even though the audio queue itself is still aligned with the original anchor. Because this path now dispatches 'changed' on large shifts, it can tear down and rebuild the audio iterator in the middle of a rapid pause/play burst — reintroducing the kind of hiccup the PR is meant to remove.

This is most likely to happen when the user toggles play/pause faster than the audio context's suspend latency.

Technical details

# Suspend statechange handler reads live frame

## Affected sites
- `packages/player/src/use-playback.ts:144` — `absoluteTimeInSeconds: getCurrentFrame() / config.fps` uses the current frame at event time, not the frame that was current when the suspend was requested.
- `packages/player/src/use-playback.ts:153` — if `setGlobalTimeAnchor` returns `true`, the handler dispatches `'changed'`, which in `@remotion/media` triggers `audioSyncAnchorChanged()` -> `destroyIterator()` -> re-prime.

## Required outcome
A pure pause/play cycle should not trigger an anchor change or audio queue rebuild.
The anchor computation on `statechange` should reflect the playhead position that the currently queued audio nodes were scheduled against.

## Suggested approach
Capture the frame at the moment `suspend()` is requested (or at least at the moment playback transitions from playing to paused) in a ref, and use that ref value in the `statechange` handler instead of `getCurrentFrame()`.

For example, the effect that handles `playing` changes could store the current frame in a ref when it calls `sharedAudioContext.suspend()`, and the `statechange` handler could read that ref.

## Open questions for the human
- Is the current behavior already known to be safe on all target browsers, or has it been observed to re-hiccup in practice during very rapid toggling?
- Does the seek effect (keyed on `frame`) already provide enough correction when a real seek happens during the suspended window?

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

test

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

Important

The latest commit (c0e9a30) correctly captures the frame at the moment of the explicit suspend() request, addressing the prior review's concern about using the live frame at statechange time. One remaining issue: suspendRequestFrame is never reset after an explicit pause/resume cycle, so a later browser-initiated AudioContext suspend could re-anchor against a stale frame.

Reviewed changes (since prior Pullfrog review) — Added suspendRequestFrame so the statechange handler re-anchors against the frame that was current when suspend() was requested, and dispatches 'changed' only when the anchor actually moves past the drift guard.

• packages/player/src/use-playback.ts — suspendRequestFrame ref is set before each Remotion-initiated suspend() and consumed in the statechange handler.
• packages/player/src/use-playback.ts — setGlobalTimeAnchor is no longer called with force: true; the drift guard plus a 'changed' dispatch replace the forced re-anchor.
• packages/core/src/audio/shared-audio-tags.tsx and packages/player/src/set-global-time-anchor.ts — type cleanups.

⚠️ Stale suspendRequestFrame on browser-initiated suspend

suspendRequestFrame.current is only overwritten right before Remotion-initiated suspend() calls (lines 185, 216, 276). After the user resumes playback, the ref keeps the frame from the last explicit pause. If the browser later auto-suspends the AudioContext (e.g., tab backgrounding or iOS audio policy), the statechange handler still runs and re-anchors against that old frame instead of falling back to getCurrentFrame() via the ?? operator — because the ref is no longer null.

That can move the anchor to the wrong time and, because the handler now dispatches 'changed' on a large shift, trigger an unnecessary audio queue rebuild.

Technical details

# Stale `suspendRequestFrame` on browser-initiated suspend

## Affected sites
- `packages/player/src/use-playback.ts:81` — ref declaration
- `packages/player/src/use-playback.ts:154` — consumes the ref in the statechange handler
- `packages/player/src/use-playback.ts:185` — sets ref when `!playing`
- `packages/player/src/use-playback.ts:216` — sets ref when `!isPlaying()`
- `packages/player/src/use-playback.ts:276` — sets ref during buffering

## Required outcome
- A browser-initiated `AudioContext` suspend must not re-anchor against a stale frame from an earlier Remotion-initiated pause.
- The explicit suspend path must continue to use the frame captured at the moment `suspend()` is requested.

## Suggested approach
Reset `suspendRequestFrame.current = null` when playback resumes, so the `?? getCurrentFrame()` fallback is used for auto-suspends. Add the reset in two places:
- At the top of the `playing` branch in `useEffect` (after the `if (!playing) { ... return; }` block).
- In the effect's cleanup function.
This mirrors the fact that the ref is only meaningful while transitioning into a Remotion-requested suspend.

ℹ️ Nitpicks

• packages/player/src/use-playback.ts:276 — The buffering suspend site only sets suspendRequestFrame.current inside the !muted branch, while the other two suspend sites set it unconditionally. Consider moving the assignment outside the muted check for consistency.

  ^{｜ View workflow run ｜ via Pullfrog ｜ Using Kimi K2 (free via Pullfrog for OSS) ｜ 𝕏}

[samohovets]

Thanks for taking on this! I can still reproduce the issue though (0:08 in the video)

The issue is reproducing both when the external audio interface is selected and the embedded one (MacBook speakers)

audio-choppiness.mp4

[JonnyBurger]

We are more aggressively closing AI-generated PRs if they are not obvious and in this case, we found an issue.
Please make a better repro / better demonstrate that this solves an issue / make a smaller PR with more obvious intention, it will be easier to merge for us. Thanks nonetheless!