Skip to content

🎥 Make videos programmatically with React

Simplify pending Player frame tracking and cover delayed commits

Jonny Burgerec71fa4e015e
diff --git a/packages/player/src/pending-playback-frame.ts b/packages/player/src/pending-playback-frame.ts
deleted file mode 100644
index 97d2fe9a84..0000000000
--- a/packages/player/src/pending-playback-frame.ts
+++ /dev/null
@@ -1,38 +0,0 @@
-/**
- * The playback loop requests frames through a React state update, which commits
- * asynchronously. When every animation frame advances the timeline (e.g. 2x
- * playback of a 30fps composition on a 60Hz display), the next tick can run
- * before the previous update has committed. Advancing from the stale committed
- * frame then drops a frame permanently, and playback falls behind real time.
- *
- * Tracks the frame the loop last requested and, in request order, the frames it
- * advanced from that may still be the committed frame. Reading one of those back
- * means the request is still pending; any other frame came from elsewhere (e.g.
- * a seek) and is adopted.
- */
-export const createPendingPlaybackFrame = () => {
- let requestedFrame: number | null = null;
- let supersededFrames: number[] = [];
-
- return {
- resolve(committedFrame: number): number {
- if (requestedFrame !== null && committedFrame !== requestedFrame) {
- const index = supersededFrames.indexOf(committedFrame);
- if (index !== -1) {
- // Updates commit in request order, so frames superseded before the
- // committed one can't be read back anymore.
- supersededFrames = supersededFrames.slice(index);
- return requestedFrame;
- }
- }
-
- requestedFrame = null;
- supersededFrames = [];
- return committedFrame;
- },
- request(fromFrame: number, nextFrame: number) {
- supersededFrames.push(fromFrame);
- requestedFrame = nextFrame;
- },
- };
-};
diff --git a/packages/player/src/test/pending-playback-frame.test.ts b/packages/player/src/test/pending-playback-frame.test.ts
deleted file mode 100644
index 2ea1390a03..0000000000
--- a/packages/player/src/test/pending-playback-frame.test.ts
+++ /dev/null
@@ -1,147 +0,0 @@
-import {expect, test} from 'bun:test';
-import {calculateNextFrame} from '../calculate-next-frame.js';
-import {createPendingPlaybackFrame} from '../pending-playback-frame.js';
-
-// Mirrors the playback loop: one tick per animation frame on a 60Hz display.
-// `commitLate(tick)` decides whether React commits a requested frame only after
-// the next tick has already read the current frame.
-const play = ({
- ticks,
- playbackSpeed,
- commitLate,
- trackPending = true,
- startFrame = 0,
- lastFrame = 100_000,
- shouldLoop = false,
- seek,
-}: {
- ticks: number;
- playbackSpeed: number;
- commitLate: (tick: number) => boolean;
- trackPending?: boolean;
- startFrame?: number;
- lastFrame?: number;
- shouldLoop?: boolean;
- seek?: {atTick: number; frame: number};
-}) => {
- let committedFrame = startFrame;
- let queuedFrame: number | null = null;
- let framesAdvanced = 0;
- const pendingFrame = createPendingPlaybackFrame();
-
- for (let tick = 1; tick <= ticks; tick++) {
- if (seek?.atTick === tick) {
- // Seeks write the frame ref synchronously.
- committedFrame = seek.frame;
- queuedFrame = null;
- }
-
- const currentFrame = trackPending
- ? pendingFrame.resolve(committedFrame)
- : committedFrame;
- const {nextFrame, framesToAdvance} = calculateNextFrame({
- time: (tick * 1000) / 60,
- currentFrame,
- playbackSpeed,
- fps: 30,
- actualFirstFrame: 0,
- actualLastFrame: lastFrame,
- framesAdvanced,
- shouldLoop,
- });
- framesAdvanced += framesToAdvance;
- if (nextFrame !== currentFrame) {
- pendingFrame.request(currentFrame, nextFrame);
- queuedFrame = nextFrame;
- }
-
- if (queuedFrame !== null && !commitLate(tick)) {
- committedFrame = queuedFrame;
- queuedFrame = null;
- }
- }
-
- return queuedFrame ?? committedFrame;
-};
-
-const every = (n: number) => (tick: number) => tick % n === 0;
-
-test('Late commits drop frames at 2x without tracking the pending frame', () => {
- expect(
- play({
- ticks: 300,
- playbackSpeed: 2,
- commitLate: every(23),
- trackPending: false,
- }),
- ).toBeLessThan(300);
-});
-
-test('Playback keeps real time at 2x when commits land after the next tick', () => {
- expect(play({ticks: 300, playbackSpeed: 2, commitLate: every(23)})).toBe(300);
- expect(play({ticks: 300, playbackSpeed: 2, commitLate: every(2)})).toBe(300);
- expect(play({ticks: 300, playbackSpeed: 2, commitLate: () => true})).toBe(
- 300,
- );
-});
-
-test('Playback keeps real time at 1x and 4x with late commits', () => {
- expect(play({ticks: 300, playbackSpeed: 1, commitLate: every(3)})).toBe(150);
- expect(play({ticks: 300, playbackSpeed: 4, commitLate: every(3)})).toBe(600);
-});
-
-test('A seek during playback is adopted while a request is pending', () => {
- expect(
- play({
- ticks: 300,
- playbackSpeed: 2,
- commitLate: every(2),
- startFrame: 600,
- seek: {atTick: 151, frame: 100},
- }),
- ).toBe(100 + 150);
-});
-
-test('Looping playback wraps instead of sticking to the first frame', () => {
- expect(
- play({
- ticks: 300,
- playbackSpeed: 2,
- commitLate: every(2),
- lastFrame: 99,
- shouldLoop: true,
- }),
- ).toBe(300 % 100);
-});
-
-test('Consistently late commits keep seeks to earlier frames working', () => {
- // Every commit lands one tick late, so the committed frame is always the
- // frame the previous request advanced from.
- const pendingFrame = createPendingPlaybackFrame();
- const inFlight: {frame: number; visibleFromTick: number}[] = [];
- let committedFrame = 0;
- for (let tick = 1; tick <= 6000; tick++) {
- while (inFlight.length > 0 && inFlight[0].visibleFromTick <= tick) {
- committedFrame = inFlight.shift()!.frame;
- }
-
- const currentFrame = pendingFrame.resolve(committedFrame);
- pendingFrame.request(currentFrame, currentFrame + 1);
- inFlight.push({frame: currentFrame + 1, visibleFromTick: tick + 2});
- }
-
- expect(committedFrame).toBe(5998);
- expect(pendingFrame.resolve(5998)).toBe(6000);
- expect(pendingFrame.resolve(10)).toBe(10);
-});
-
-test('A pending request survives a commit of an intermediate request', () => {
- const pendingFrame = createPendingPlaybackFrame();
- pendingFrame.request(pendingFrame.resolve(100), 101);
- pendingFrame.request(pendingFrame.resolve(100), 102);
- pendingFrame.request(pendingFrame.resolve(101), 103);
- expect(pendingFrame.resolve(101)).toBe(103);
- expect(pendingFrame.resolve(102)).toBe(103);
- // 100 was superseded before 102 committed, so reading it back is a seek.
- expect(pendingFrame.resolve(100)).toBe(100);
-});
diff --git a/packages/player/src/test/playback-frame.test.tsx b/packages/player/src/test/playback-frame.test.tsx
new file mode 100644
index 0000000000..848fe5a06e
--- /dev/null
+++ b/packages/player/src/test/playback-frame.test.tsx
@@ -0,0 +1,91 @@
+import {expect, spyOn, test} from 'bun:test';
+import {createRef} from 'react';
+import {useCurrentFrame} from 'remotion';
+import type {PlayerRef} from '../player-methods.js';
+import {Player} from '../Player.js';
+import {usePlayerMethods} from '../use-player-methods.js';
+import {act, cleanup, fireEvent, render} from './test-utils.js';
+
+test('Playback advances from pending frames and resumes from an explicit seek', () => {
+ let now = 0;
+ let nextRaf = 0;
+ const rafs = new Map<number, FrameRequestCallback>();
+ const clock = spyOn(performance, 'now').mockImplementation(() => now);
+ const raf = spyOn(globalThis, 'requestAnimationFrame').mockImplementation(
+ (callback) => {
+ const id = ++nextRaf;
+ rafs.set(id, callback);
+ return id;
+ },
+ );
+ const cancel = spyOn(globalThis, 'cancelAnimationFrame').mockImplementation(
+ (id) => {
+ rafs.delete(id);
+ },
+ );
+ const player = createRef<PlayerRef>();
+ const Composition = () => {
+ const frame = useCurrentFrame();
+ const {seek} = usePlayerMethods();
+
+ return (
+ <>
+ <output>Frame {frame}</output>
+ <button type="button" onClick={() => seek(100)}>
+ Seek to frame 100
+ </button>
+ </>
+ );
+ };
+
+ const tick = (time: number) => {
+ now = time;
+ const pending = [...rafs.values()];
+ rafs.clear();
+ for (const callback of pending) {
+ callback(time);
+ }
+ };
+
+ try {
+ const view = render(
+ <Player
+ ref={player}
+ component={Composition}
+ durationInFrames={1000}
+ initialFrame={100}
+ compositionWidth={320}
+ compositionHeight={180}
+ fps={30}
+ playbackRate={2}
+ initiallyMuted
+ numberOfSharedAudioTags={0}
+ />,
+ );
+ act(() => player.current!.play());
+ act(() => {
+ // Two 60 Hz ticks run before React commits either frame update.
+ tick(17);
+ tick(34);
+ });
+ expect(view.getByText('Frame 102')).toBeTruthy();
+ act(() => tick(51));
+ expect(view.getByText('Frame 103')).toBeTruthy();
+
+ act(() => {
+ tick(68);
+ tick(85);
+ // Seek while frames are pending, without pausing playback.
+ fireEvent.click(view.getByRole('button', {name: 'Seek to frame 100'}));
+ tick(102);
+ });
+ expect(view.getByText('Frame 101')).toBeTruthy();
+ act(() => tick(119));
+ expect(view.getByText('Frame 102')).toBeTruthy();
+ } finally {
+ cleanup();
+ clock.mockRestore();
+ raf.mockRestore();
+ cancel.mockRestore();
+ }
+});
diff --git a/packages/player/src/use-playback.ts b/packages/player/src/use-playback.ts
index c6e5e3bae8..67100741ed 100644
--- a/packages/player/src/use-playback.ts
+++ b/packages/player/src/use-playback.ts
@@ -7,7 +7,6 @@ import type {BrowserMediaControlsBehavior} from './browser-mediasession.js';
import {useBrowserMediaSession} from './browser-mediasession.js';
import {calculateNextFrame} from './calculate-next-frame.js';
import {useIsBackgrounded} from './is-backgrounded.js';
-import {createPendingPlaybackFrame} from './pending-playback-frame.js';
import {setGlobalTimeAnchor} from './set-global-time-anchor.js';
import {type UsePlayerMethods, usePlayerMethods} from './use-player-methods.js';
@@ -57,7 +56,7 @@ export const usePlayback = ({
Internals.Timeline.useTimelineSetFrameWithoutSeek();
const sharedAudioContext = useContext(Internals.SharedAudioContext);
const {setPlayerMuted} = useContext(Internals.SetMediaVolumeContext);
- const {isBuffering, subscribeBuffering} = useContext(
+ const {isBuffering, subscribeBuffering, seek} = useContext(
Internals.SetTimelineContext,
);
const logLevel = Internals.useLogLevel();
@@ -203,7 +202,8 @@ export const usePlayback = ({
| null = null;
let startedTime = performance.now();
let framesAdvanced = 0;
- const pendingFrame = createPendingPlaybackFrame();
+ let playbackFrame = getCurrentFrame();
+ let lastSeekRevision = seek?.revision.current ?? null;
const cancelQueuedFrame = () => {
if (reqAnimFrameCall !== null) {
@@ -238,7 +238,14 @@ export const usePlayback = ({
const actualLastFrame = outFrame ?? config.durationInFrames - 1;
const actualFirstFrame = inFrame ?? 0;
- const currentFrame = pendingFrame.resolve(getCurrentFrame());
+ const seekRevision = seek?.revision.current ?? null;
+ if (seekRevision !== lastSeekRevision) {
+ playbackFrame = getCurrentFrame();
+ lastSeekRevision = seekRevision;
+ }
+
+ // React may not have committed the previous playback update yet.
+ const currentFrame = playbackFrame;
const {nextFrame, framesToAdvance, hasEnded} = calculateNextFrame({
time,
currentFrame,
@@ -261,7 +268,7 @@ export const usePlayback = ({
: nextFrame;
if (frameToDisplay !== currentFrame && !isBuffering()) {
- pendingFrame.request(currentFrame, frameToDisplay);
+ playbackFrame = frameToDisplay;
setFrameFromPlayback((c) => ({...c, [config.id]: frameToDisplay}));
}
@@ -378,6 +385,7 @@ export const usePlayback = ({
sharedAudioContext,
setPlayerMuted,
subscribeBuffering,
+ seek,
logLevel,
muted,
]);