Skip to content

Commit 3cc6003

Browse files
committed
fix(record): bound the overlay's output check by its budget
The playability wait after the export polled on its own schedule, so a slow check could still run past the overlay budget and rename the composited file afterwards. It now stops at the deadline, and an expired budget keeps the recorded video.
1 parent 2e769e4 commit 3cc6003

5 files changed

Lines changed: 49 additions & 6 deletions

File tree

‎packages/capture-kit/src/recording/__tests__/overlay.test.ts‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,7 @@ import {
3434
} from '../overlay.ts';
3535
import { AppError } from '@agent-device/kernel/errors';
3636
import { runCmd } from '@agent-device/host-kit/command';
37+
import { waitForPlayableVideo } from '../video.ts';
3738

3839
function helperScriptArgs(): string[] {
3940
const helperCall = mockRunCmd.mock.calls.find(([cmd]) => cmd !== 'xcrun');
@@ -290,3 +291,25 @@ test('overlay keeps the plain failure when the export failed with budget to spar
290291
message: 'Failed to add touch overlays to the recording',
291292
});
292293
});
294+
295+
test('overlay keeps the video as recorded when verifying the export spent its budget', async () => {
296+
vi.useFakeTimers({ toFake: ['Date'] });
297+
const videoPath = path.join(tmpDir, 'recording.mp4');
298+
const telemetryPath = path.join(tmpDir, 'recording.gesture-telemetry.json');
299+
fs.writeFileSync(videoPath, 'original');
300+
fs.writeFileSync(telemetryPath, '{"events":[]}');
301+
const deadline = startRecordingOverlayBudget();
302+
vi.mocked(waitForPlayableVideo).mockImplementationOnce(async () => {
303+
vi.setSystemTime(Date.now() + OVERLAY_BUDGET_MS);
304+
});
305+
306+
await expect(
307+
overlayRecordingTouches({ videoPath, telemetryPath, deadline }),
308+
).rejects.toMatchObject({
309+
code: 'COMMAND_FAILED',
310+
message: `Failed to add touch overlays to the recording: the export did not finish within its ${OVERLAY_BUDGET_MS}ms budget; a lower --fps renders faster`,
311+
});
312+
expect(vi.mocked(waitForPlayableVideo)).toHaveBeenCalledWith(expect.any(String), { deadline });
313+
expect(fs.readFileSync(videoPath, 'utf8')).toBe('original');
314+
expect(fs.readdirSync(tmpDir).filter((name) => name.includes('agent-device-'))).toEqual([]);
315+
});

‎packages/capture-kit/src/recording/overlay.ts‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ export function getRecordingOverlaySupportWarning(
2929
* the caller gets "Daemon request timed out" while the daemon finishes the stop. So the overlay must
3030
* end well inside it. The budget starts with the stop's finalization, so the playability checks
3131
* before the overlay (on a cold host they compile their validator first) come out of it, as do
32-
* compiling the helper, its export and its exit; past it the stop keeps the raw video and its
32+
* compiling the helper, its export, its exit and verifying its output; past it the stop keeps the raw video and its
3333
* gesture telemetry, with a warning.
3434
*/
3535
export const OVERLAY_BUDGET_MS = 70_000;
@@ -104,7 +104,14 @@ async function exportProcessedVideo(params: {
104104
exportOverran = deadline.remainingMs() <= HELPER_EXIT_GRACE_MS;
105105
throw error;
106106
}
107-
await waitForPlayableVideo(outputPath);
107+
await waitForPlayableVideo(outputPath, { deadline });
108+
if (deadline.isExpired()) {
109+
exportOverran = true;
110+
throw new AppError(
111+
'COMMAND_FAILED',
112+
'The composited video was not verified within the budget',
113+
);
114+
}
108115
fs.renameSync(outputPath, videoPath);
109116
} catch (error) {
110117
const description = exportOverran

‎packages/capture-kit/src/recording/video.test.ts‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@ import { runCmd } from '@agent-device/host-kit/command';
55
import { likelyPlayableWebmContainer } from '../__tests__/test-utils/video-fixtures.ts';
66
import { mkdtempForTestSync } from '../tmp-dir.fixtures.ts';
77
import { mp4Atom, mp4MovieHeader } from './mp4.fixtures.ts';
8-
import { isPlayableVideo } from './video.ts';
8+
import { Deadline } from '@agent-device/host-kit/retry';
9+
import { isPlayableVideo, waitForPlayableVideo } from './video.ts';
910

1011
vi.mock('@agent-device/host-kit/command', () => ({
1112
runCmd: vi.fn(async () => ({ exitCode: 0, stdout: '', stderr: '' })),
@@ -53,3 +54,11 @@ test('refuses an MP4 container that never declares a movie header', async () =>
5354
await expect(isPlayableVideo(writeFixture('no-moov.mp4', container))).resolves.toBe(false);
5455
expect(runCmd).not.toHaveBeenCalled();
5556
});
57+
58+
test('waiting for a playable video stops polling once its deadline passes', async () => {
59+
const filePath = path.join(mkdtempForTestSync('agent-device-video-wait-'), 'never-playable.mp4');
60+
fs.writeFileSync(filePath, '');
61+
const started = Date.now();
62+
await waitForPlayableVideo(filePath, { pollMs: 60_000, deadline: Deadline.fromTimeoutMs(0) });
63+
expect(Date.now() - started).toBeLessThan(1_000);
64+
});

‎packages/capture-kit/src/recording/video.ts‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import fs from 'node:fs';
22
import { AppError } from '@agent-device/kernel/errors';
33
import { runCmd } from '@agent-device/host-kit/command';
4-
import { sleep } from '@agent-device/host-kit/retry';
4+
import { type Deadline, sleep } from '@agent-device/host-kit/retry';
55
import { buildSwiftToolEnv, compileSwiftSourceText } from './swift-cache.ts';
66

77
import { hasPlayableWebmStructure } from './video-webm.ts';
@@ -119,9 +119,10 @@ function isSwiftVideoValidatorError(error: unknown): boolean {
119119
);
120120
}
121121

122+
/** Polls until the file plays, for `attempts` polls or until `deadline` passes, whichever is first. */
122123
export async function waitForPlayableVideo(
123124
filePath: string,
124-
options: { pollMs?: number; attempts?: number } = {},
125+
options: { pollMs?: number; attempts?: number; deadline?: Deadline } = {},
125126
): Promise<void> {
126127
const pollMs = options.pollMs ?? 150;
127128
const attempts = options.attempts ?? 12;
@@ -130,6 +131,9 @@ export async function waitForPlayableVideo(
130131
if (await isPlayableVideo(filePath)) {
131132
return;
132133
}
134+
if (options.deadline?.isExpired()) {
135+
return;
136+
}
133137
await sleep(pollMs);
134138
}
135139
}

‎website/docs/docs/commands.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -956,7 +956,7 @@ agent-device record stop # Stop active recording
956956
- `record start` defaults to app scope and needs a session from `open <app>`. Use `--scope device` or `--scope system` for whole-screen capture (multiple apps, settings, home screen) where the backend supports it.
957957
- iOS recording works on simulators and CoreDevice-backed physical devices. Physical devices capture runner screenshots, not a native video stream: no audio, dropped frames are expected, and the default is 15 FPS. `--fps <n>` (1-120) caps the rate; a busy app or long command yields fewer frames.
958958
- `--quality medium|high` (default `medium`) sets export quality on Android and Limrun; Apple export always keeps the captured resolution. Numeric `5`-`7` map to `medium` and `8`-`10` to `high`.
959-
- With touch visualization on, recordings also produce a gesture telemetry sidecar. Burned-in touch overlays export only on macOS hosts; elsewhere `record stop` returns the raw video and telemetry with `overlayWarning`. The overlay renders at most 30 FPS (or `--fps` if lower) within a fixed budget, which also covers the video checks that run before it; an export past the budget returns the raw video with `overlayWarning`. On a host that has not run a recording before, part of that budget goes to one-time tool setup, so the first `record stop` of a long recording is more likely to return the raw video.
959+
- With touch visualization on, recordings also produce a gesture telemetry sidecar. Burned-in touch overlays export only on macOS hosts; elsewhere `record stop` returns the raw video and telemetry with `overlayWarning`. The overlay renders at most 30 FPS (or `--fps` if lower) within a fixed budget, which also covers the video checks that run before and after it; an export past the budget returns the raw video with `overlayWarning`. On a host that has not run a recording before, part of that budget goes to one-time tool setup, so the first `record stop` of a long recording is more likely to return the raw video.
960960
- Android uses `adb shell screenrecord` (180s limit per clip). Longer recordings are split into MP4 chunks while the daemon stays alive; after a daemon restart, `record stop` recovers only chunks listed in the device manifest. A clip can end before `record stop` when the screen stopped changing; `durationMs` is wall-clock time, and `capturedDurationMs` plus a warning report how much the video covers.
961961
- Limrun sessions always record the whole screen and refuse `--fps` and `--hide-touches` with `INVALID_ARGS`. A failed download is retried by the next `record stop`; nothing survives a daemon restart.
962962
- A busy iOS simulator recording slot returns non-retriable `DEVICE_IN_USE` with `details.reason: apple_simulator_recording_busy`. Run `record stop` in the session that owns the recording; if no recording is active, ask the host operator to restart the CoreSimulator stream service.

0 commit comments

Comments
 (0)