Stories: Play resumes at the exact paused or sought moment

startScene takes fromProgress and starts partway into a shot: the camera
goes on along the rest of the flight, the hold waits only what is left
and the scene clock carries on from the same point.
This commit is contained in:
Sameh Khamis committed 2026-11-16 13:24:59 -08:00
1 parent fec84dbf78
commit 8734f5e515
11 files changed
+341 -45

No files matched your search

+8 -3
View File
@@ -258,10 +258,15 @@ class PlaybackClock {
this._shotProgressTimer = timer;
}
startScene(scene, shot, token) {
/** Drive the scene clock through one shot, `offsetSec` into it when resuming. */
startScene(scene, shot, token, offsetSec = 0) {
this.stopSceneTimer();
const generation = this._sceneGeneration;
const timing = this.timingForShot(scene, shot);
const offset = Math.max(
0,
Math.min(timing.durationSec, Number(offsetSec) || 0),
);
if (
generation !== this._sceneGeneration ||
this._destroyed ||
@@ -269,8 +274,8 @@ class PlaybackClock {
token.signal?.aborted
)
return timing;
const startedAt = this.now();
this.publish(scene, shot, timing.startElapsedSec, {
const startedAt = this.now() - offset * 1000;
this.publish(scene, shot, timing.startElapsedSec + offset, {
running: true,
});
if (
+12 -3
View File
@@ -26,7 +26,9 @@ export function buildPlaybackQueue(
/**
* Run ordered shots through an application-supplied playback adapter.
*
* Each phase receives {scene, shot, index, total, token}. The adapter owns
* Each phase receives {scene, shot, index, total, token, resume}. `resume` is
* the queue item's own, opaque to the runner: a queue may start partway into
* its first shot, and the adapter decides what that means. The adapter owns
* camera/rendering resources and must observe token.signal or token.cancelled
* while awaiting work. The runner rechecks both after every phase; it cannot
* interrupt an adapter that ignores cancellation. No timers, UI, storage,
@@ -68,7 +70,7 @@ export async function playSceneQueue(
throw new Error(`Could not leave scene: ${previousScene.title}`);
}
for (let index = 0; index < queue.length && !cancelled(); index++) {
const { scene, shot } = queue[index];
const { scene, shot, resume = null } = queue[index];
if (activeScene && activeScene.id !== scene.id) {
const toRelease = activeScene;
activeScene = null;
@@ -76,7 +78,14 @@ export async function playSceneQueue(
if (cancelled()) break;
}
activeScene = scene;
const context = { scene, shot, index, total: queue.length, token };
const context = {
scene,
shot,
index,
total: queue.length,
token,
resume,
};
for (const phase of SHOT_PHASES) {
if (cancelled()) break;
await adapter[phase](context);
+12 -3
View File
@@ -19,7 +19,12 @@ export function createCameraMotion({
disposed = true;
cancel();
},
play(move, token) {
/**
* Play one move. `fromProgress` starts partway in, as if the move had
* already run that share of its duration; `sample` replaces the authored
* sampler (a resumed ordinary flight follows its own path).
*/
play(move, token, { fromProgress = 0, sample = sampleCameraMove } = {}) {
cancel();
if (disposed || token?.cancelled || token?.signal?.aborted)
return Promise.resolve(false);
@@ -27,7 +32,11 @@ export function createCameraMotion({
throw new RangeError('Camera move duration must be positive');
return new Promise((resolve, reject) => {
const run = { handle: null, finish: null };
const startedAt = now();
const startOffset =
Math.min(1, Math.max(0, Number(fromProgress) || 0)) *
move.durationSec *
1000;
const startedAt = now() - startOffset;
const onAbort = () => run.finish(false);
run.finish = (completed, error) => {
if (active !== run) return;
@@ -51,7 +60,7 @@ export function createCameraMotion({
1,
Math.max(0, (now() - startedAt) / (move.durationSec * 1000)),
);
if (applyPose(sampleCameraMove(move, progress)) === false) {
if (applyPose(sample(move, progress)) === false) {
run.finish(false);
return;
}
+84 -8
View File
@@ -53,7 +53,11 @@ import {
effectiveShotHoldSec,
shotRuntimeDurationSec,
} from './shotPresentation.js';
import { sceneTimingForShot, sceneSeekState } from '../director/timeline.js';
import {
sceneTimingForShot,
sceneSeekState,
cameraAtProgress,
} from '../director/timeline.js';
import { createPlaybackClock } from '../director/clock.js';
import {
normalizeLayerEntry,
@@ -2165,6 +2169,9 @@ export class SceneDirector {
* @param {boolean} [options.single=false] - Play only the named scene instead of
* round-robining through the whole project (voice playback uses this).
* @param {string|null} [options.afterShotId=null] - Begin after this shot without wrapping
* @param {number|null} [options.fromProgress=null] - Begin at this point of the
* start scene (0–1 of its clock), partway into a shot when it falls inside
* one: camera, hold and clock carry on from there, as after a seek.
* @param {boolean} [options.preview=true] - Enter recording preview and release the scene on exit
* @returns {Promise<{started: boolean, reason?: string, shots?: number}>}
*/
@@ -2177,7 +2184,12 @@ export class SceneDirector {
async _startScene(
sceneId,
{ single = false, afterShotId = null, preview = true } = {},
{
single = false,
afterShotId = null,
fromProgress = null,
preview = true,
} = {},
) {
if (this._running) return { started: false, reason: 'already-running' };
@@ -2192,6 +2204,18 @@ export class SceneDirector {
if (index < 0) return { started: false, reason: 'shot-not-found' };
queue = queue.slice(index + 1);
if (!queue.length) return { started: false, reason: 'scene-complete' };
} else if (fromProgress !== null) {
const scene = this._project.scenes.find(({ id }) => id === startSceneId);
const resume = scene ? this._sceneSeekState(scene, fromProgress) : null;
const index = resume
? queue.findIndex(
({ scene, shot }) =>
scene.id === startSceneId && shot.id === resume.shot.id,
)
: -1;
if (index < 0) return { started: false, reason: 'shot-not-found' };
queue = queue.slice(index);
if (resume.shotElapsedSec > 0) queue[0] = { ...queue[0], resume };
}
if (!queue.length) {
this._updateStatus(() => t('No shots to run'));
@@ -2249,7 +2273,8 @@ export class SceneDirector {
return (
sum +
(item.shot.durationSec || 0) +
this._effectiveShotHoldSec(item.scene, item.shot)
this._effectiveShotHoldSec(item.scene, item.shot) -
(item.resume?.shotElapsedSec || 0)
);
}, 0);
@@ -2759,9 +2784,22 @@ export class SceneDirector {
return true;
}
/** Use the authored sampler only for explicit moves; ordinary shots keep their existing flights. */
async _flyShotCamera(scene, shot, durationSec, token) {
/**
* Use the authored sampler only for explicit moves; ordinary shots keep their
* existing flights. A resumed shot (`fromProgress` > 0) continues along the
* path a seek samples, so it goes on from exactly where the seek framed it.
*/
async _flyShotCamera(scene, shot, durationSec, token, fromProgress = 0) {
const move = resolveCameraMove(scene, shot);
if (fromProgress > 0)
return this._resumeShotCamera(
scene,
shot,
move,
durationSec,
token,
fromProgress,
);
if (!move)
return this._flyCamera(
resolveCameraPose(scene, shot.camera),
@@ -2776,6 +2814,35 @@ export class SceneDirector {
this.stopScene(msg('Camera move interrupted'));
}
/** Play the rest of a shot's flight from `fromProgress` of the way along. */
async _resumeShotCamera(scene, shot, move, durationSec, token, fromProgress) {
const index = scene.shots.indexOf(shot);
const from = resolveCameraPose(
scene,
scene.shots[index - 1]?.camera || shot.camera,
);
const to = resolveCameraPose(scene, shot.camera);
// A resumed ordinary flight is driven frame by frame like an authored
// move, so a camera gesture during it stops the run the same way.
const authored = this._usesAuthoredCamera;
this._usesAuthoredCamera = true;
let completed;
try {
completed = await this._cameraMotion.play(
{ ...move, durationSec },
token,
{
fromProgress,
...(move ? {} : { sample: (_, p) => cameraAtProgress(from, to, p) }),
},
);
} finally {
if (!token.cancelled) this._usesAuthoredCamera = authored;
}
if (!completed && !token.cancelled && !this._destroyed)
this.stopScene(msg('Camera move interrupted'));
}
/**
* Fly the camera to the given position over the specified duration
* using cubic ease-in-out. Resolves when the flight completes, is cancelled,
@@ -2831,7 +2898,16 @@ export class SceneDirector {
}
/** Let an opt-in media owner finish playback and its fade before the next flight. */
async _holdShot(scene, shot, token) {
async _holdShot(scene, shot, token, resume = null) {
// Resumed inside the hold: its layers were set to that moment, as a seek
// sets them, so only the rest of the hold is left to wait.
if (resume?.holdElapsedSec > 0) {
await this._sleep(
Math.max(0, resume.holdDurationSec - resume.holdElapsedSec) * 1000,
token,
);
return;
}
const readers = Object.entries(
this._layerStatesForShot(scene, shot),
).flatMap(([id, state]) => {
@@ -2890,8 +2966,8 @@ export class SceneDirector {
}
/** Drive the public authored clock through one running shot. */
_startSceneClockTicker(scene, shot, token) {
return this._clock.startScene(scene, shot, token);
_startSceneClockTicker(scene, shot, token, offsetSec = 0) {
return this._clock.startScene(scene, shot, token, offsetSec);
}
/**
+93
View File
@@ -2032,6 +2032,99 @@ test('startScene resolves its result, resumes after a shot without a scene id, a
} finally { await director.destroy(); restore(); }
});
/** Drive frame-by-frame camera motion headlessly for one test. */
function installAnimationFrames() {
const original = globalThis.requestAnimationFrame;
const originalCancel = globalThis.cancelAnimationFrame;
globalThis.requestAnimationFrame = (callback) => setTimeout(callback, 16);
globalThis.cancelAnimationFrame = (handle) => clearTimeout(handle);
return () => {
globalThis.requestAnimationFrame = original;
globalThis.cancelAnimationFrame = originalCancel;
};
}
test('a run resumed inside a flight goes on from that point of the path and clock', async () => {
const { director, viewer, restore } = makeDirector();
const restoreFrames = installAnimationFrames();
const clock = [];
director.subscribeSceneClock((snap) => clock.push(snap));
const poses = [];
const setView = director._setCameraView.bind(director);
director._setCameraView = (pose) => {
poses.push(pose);
return setView(pose);
};
try {
// 0.75 of a 0.4 s scene: halfway along shot B's 0.2 s flight.
const run = director.startScene('scene-1', {
single: true,
fromProgress: 0.75,
preview: false,
});
await settle(40);
const first = clock.find((snap) => snap.running);
assert.equal(first.shotId, 'shot-b', 'starts in the shot that moment is in');
assert.ok(Math.abs(first.sceneElapsedSec - 0.3) < 1e-9, 'the clock starts at the moment');
// The first frame is the seek's own framing, halfway from A to B.
assert.ok(poses.length, 'the camera is driven from where it is');
assert.ok(Math.abs(poses[0].lat - -10) < 0.5, 'halfway from A to B');
assert.deepEqual(await run, { started: true, shots: 1 });
assert.equal(poses.at(-1).lat, -30, 'and ends on shot B');
assert.equal(viewer.flights.length, 0, 'no fresh flight from the shot start');
assert.equal(director._lastRun.wasCancelled, false);
} finally { await director.destroy(); restoreFrames(); restore(); }
});
test('a run resumed inside a hold keeps the seek’s layer state and waits only the rest of it', async () => {
const project = structuredClone(PROJECT_FIXTURE);
project.scenes[0].shots[0].holdSec = 0.6;
const { director, viewer, restore } = makeDirector({ project });
const layerCalls = [];
const layerStates = director._layerStatesForShot.bind(director);
director._layerStatesForShot = (scene, shot, options) => {
layerCalls.push({ shot, options });
return layerStates(scene, shot, options);
};
const clock = [];
director.subscribeSceneClock((snap) => clock.push(snap));
const poses = [];
const setView = director._setCameraView.bind(director);
director._setCameraView = (pose) => {
poses.push(pose);
return setView(pose);
};
const sleeps = [];
const sleep = director._sleep.bind(director);
director._sleep = (ms, token) => {
sleeps.push(ms);
return sleep(ms, token);
};
try {
// Shot A is 0.2 s of flight and 0.6 s of hold; the scene is 1 s long.
// 0.6 of it is 0.4 s into A's hold, with 0.2 s of it left.
const started = Date.now();
const result = await director.startScene('scene-1', {
single: true,
fromProgress: 0.6,
preview: false,
});
assert.deepEqual(result, { started: true, shots: 2 });
const first = clock.find((snap) => snap.running);
assert.equal(first.shotId, 'shot-a');
assert.ok(Math.abs(first.sceneElapsedSec - 0.6) < 1e-9);
assert.ok(Math.abs(sleeps[0] - 200) < 1e-6, 'only the rest of the hold');
assert.ok(Date.now() - started < 700, 'the shot is not replayed');
// Shot A's camera is placed at its end; only shot B flies.
assert.equal(poses[0].lat, 10);
assert.equal(viewer.flights.length, 1);
const seekStates = layerCalls.filter(({ options }) => options?.sceneSeek);
assert.equal(seekStates.length, 1, 'shot A’s layers are given the moment');
assert.equal(seekStates[0].shot.id, 'shot-a');
assert.ok(Math.abs(seekStates[0].options.sceneSeek.holdElapsedSec - 0.4) < 1e-9);
} finally { await director.destroy(); restore(); }
});
test('a caught run failure resolves as run-failed, not success (#971)', async () => {
const { director, styleManager, restore } = makeDirector();
const warn = console.warn;
+44 -9
View File
@@ -2,6 +2,14 @@
import { t } from '../i18n/index.js';
import { displaySceneTitle, displayShotTitle } from './recipes.js';
/**
* A run resumed partway into its first shot carries the seek state of that
* moment (`resume`). Inside the shot's hold, its layers take that moment's
* state as a seek gives it, and only the rest of the hold is waited out; inside
* its flight, the camera goes on from where it is along the rest of the path.
*/
const inHold = (resume) => resume?.holdElapsedSec > 0;
export function createScenePlaybackAdapter(director, defaultShotDurationSec) {
let timing;
let travel;
@@ -37,10 +45,14 @@ export function createScenePlaybackAdapter(director, defaultShotDurationSec) {
{ isCurrent: () => !token.cancelled && !token.signal?.aborted },
);
},
async applyLayers({ scene, shot, token }) {
async applyLayers({ scene, shot, token, resume }) {
director._setSceneMediaPlayback(scene, shot, token);
const result = await director._applyLayerStates(
director._layerStatesForShot(scene, shot),
director._layerStatesForShot(
scene,
shot,
inHold(resume) ? { cameraSettled: true, sceneSeek: resume } : {},
),
token,
);
if (
@@ -51,20 +63,43 @@ export function createScenePlaybackAdapter(director, defaultShotDurationSec) {
throw new Error('Data packs unavailable');
return result;
},
travel({ scene, shot, token }) {
travel({ scene, shot, token, resume }) {
director._loadedSceneId = scene.id;
const duration = shot.durationSec || defaultShotDurationSec;
timing = director._startSceneClockTicker(scene, shot, token);
travel = director._beginShotTravel(scene, shot, duration);
const flight = director._flyShotCamera(scene, shot, duration, token);
const cameraProgress = resume?.cameraProgress ?? 0;
timing = director._startSceneClockTicker(
scene,
shot,
token,
resume?.shotElapsedSec ?? 0,
);
if (cameraProgress >= 1) {
travel = null;
director._setCameraView(resume.camera);
return;
}
travel = director._beginShotTravel(
scene,
shot,
duration * (1 - cameraProgress),
);
const flight = director._flyShotCamera(
scene,
shot,
duration,
token,
cameraProgress,
);
director._publishShotTravel(scene, shot, travel);
return flight;
},
settle({ scene, shot, token }) {
settle({ scene, shot, token, resume }) {
// Resumed inside the hold, the layers already hold that moment's state.
if (inHold(resume)) return;
director._settleShotLayerStates(scene, shot, token, travel);
},
hold({ scene, shot, token }) {
return director._holdShot(scene, shot, token);
hold({ scene, shot, token, resume }) {
return director._holdShot(scene, shot, token, resume);
},
completeShot({ scene, shot, index }) {
director._clock.stopSceneTimer();
+4 -5
View File
@@ -30,7 +30,7 @@ export function directorSettled(director) {
* panel plays it, and reports the scene clock in the shape the Stories
* timeline reads. SceneDirector has no pause: pausing seeks to the current
* moment (which stops the run and frames it), and playing again starts the
* run at the shot that moment is in.
* run from that same moment.
*
* @param {import('../scenes/director.js').SceneDirector} director
* @param {object} story A catalog story of kind 'gev'.
@@ -124,14 +124,13 @@ export function createGevPlayer(director, story, hooks = {}) {
wallMs = 0;
shotIndex = 0;
}
const shots = director.listShots(sceneId);
const afterShotId =
shotIndex > 0 ? (shots[shotIndex - 1]?.id ?? null) : null;
playing = true;
tick();
// Go on from the exact moment shown: partway into its shot, with the
// camera, the hold and the clock carrying on from there.
const result = await director.startScene(sceneId, {
single: true,
afterShotId,
fromProgress: durationMs ? wallMs / durationMs : 0,
preview: true,
});
// startScene resolves after the run finishes, not when it starts.
+67 -5
View File
@@ -34,7 +34,7 @@ function deferredDirector({ running = false } = {}) {
seekScene: (id, f) => calls.push(`seek ${f}`),
startScene: (_id, options) => {
director.startAfterShotId = options.afterShotId;
director.startOptions = options;
calls.push('start');
director.running = true;
return new Promise((resolve) => {
@@ -154,7 +154,11 @@ test('Play from a paused link in the final quarter-second stays in the final sho
59800,
'the link is not treated as complete',
);
assert.equal(director.startAfterShotId, 'a', 'resume in the final shot');
assert.equal(
director.startOptions.fromProgress,
59800 / 60000,
'resume at the same moment of the final shot',
);
director.finishRun();
await playing;
});
@@ -166,7 +170,7 @@ test('Play after the actual end still starts the scene from shot one', async ()
const playing = player.play();
await turns();
assert.equal(player.state.wallMs, 0);
assert.equal(director.startAfterShotId, null);
assert.equal(director.startOptions.fromProgress, 0);
director.finishRun();
await playing;
});
@@ -196,7 +200,11 @@ test('in the director’s order, a paused link near the end resumes in its final
assert.equal(player.state.wallMs, 59800, 'not rounded to the end');
const playing = player.play();
await turns();
assert.equal(director.startAfterShotId, 'a', 'resume in the final shot');
assert.equal(
director.startOptions.fromProgress,
59800 / 60000,
'resume at the same moment of the final shot',
);
director.finishRun();
await playing;
});
@@ -215,7 +223,61 @@ test('a run that ends on its own is rounded to the end, and Play then starts ove
const playing = player.play();
await turns();
assert.equal(player.state.wallMs, 0);
assert.equal(director.startAfterShotId, null, 'from the first shot');
assert.equal(director.startOptions.fromProgress, 0, 'from the start');
director.finishRun();
await playing;
});
test('Play after Pause goes on from the paused moment, not the shot’s start', async () => {
const director = deferredDirector();
const player = createGevPlayer(director, story);
const playing = player.play();
await turns();
// The run is 42 s in, 12 s into the second shot, when it is paused.
director.publish({
sceneDurationSec: 60,
sceneElapsedSec: 42,
shotIndex: 1,
running: true,
});
player.pause();
director.finishRun();
await playing;
assert.equal(player.state.wallMs, 42000);
const again = player.play();
await turns();
assert.equal(director.startOptions.fromProgress, 42000 / 60000);
director.finishRun();
await again;
});
test('Play after a seek goes on from the time sought', async () => {
const director = deferredDirector();
const player = createGevPlayer(director, story);
player.seek(12345);
const playing = player.play();
await turns();
assert.equal(director.startOptions.fromProgress, 12345 / 60000);
assert.equal(director.startOptions.afterShotId, undefined);
director.finishRun();
await playing;
});
test('Play from a paused link goes on from the link’s time', async () => {
const director = deferredDirector();
const player = createGevPlayer(director, story);
// Opening a paused link seeks to its time, and the director reports it.
player.seek(17500);
director.publish({
sceneDurationSec: 60,
sceneElapsedSec: 17.5,
shotIndex: 0,
running: false,
seeking: true,
});
const playing = player.play();
await turns();
assert.equal(director.startOptions.fromProgress, 17500 / 60000);
director.finishRun();
await playing;
});