@fortemate/vega-vvd-driver 0.1.0 → 0.2.1

package/README.md

@@ -6,7 +6,7 @@ Drive the Vega Virtual Device from scripts and AI agents: press remote keys, tak
 
 ## Why
 
-The Vega SDK's `vega` command installs and launches apps on the Vega Virtual Device (VVD), but has no command to press a remote key or take a screenshot. Amazon's [Appium Vega driver](https://developer.amazon.com/docs/vega/0.24/appium-install.html) does both, and much more: it runs UI tests that find elements, on the VVD and on a Fire TV Stick. It needs an Appium 2 server, the driver package and the device's automation toolkit switched on, with Node 22 or earlier.
+The Vega SDK's `vega` command installs and launches apps on the Vega Virtual Device (VVD), but has no command to press a remote key or take a screenshot. On a Fire TV Stick, the device's own `gwsi-tool-screenshooter` takes one through `vega exec vda shell`, but the [VDA reference](https://developer.amazon.com/docs/vega/0.24/vda-tools.html) notes that the VVD doesn't support it. Amazon's [Appium Vega driver](https://developer.amazon.com/docs/vega/0.24/appium-install.html) does both, and much more: it runs UI tests that find elements, on the VVD and on a Fire TV Stick. It needs an Appium 2 server, the driver package and the device's automation toolkit switched on, with Node 22 or earlier.
 
 This driver is for lighter jobs on the VVD: a key press or a screenshot from a shell script, a video with sound, every frame of an animation, and an AI coding agent that can see what it built. It talks to the Android emulator that the VVD is built on, through the emulator's own gRPC API and console, so there is nothing to install on the device and no server to run.
 
@@ -14,15 +14,17 @@ Its methods were worked out while building [Dice Chess for Fire TV](https://gith
 
 ## Appium or this driver?
 
-| To…                                                 | Use                    |
-| --------------------------------------------------- | ---------------------- |
-| find elements, read their text, run a test suite    | Appium                 |
-| test on a Fire TV Stick                             | Appium                 |
-| press keys or take a screenshot from a shell script | this driver, or Appium |
-| record a video with sound                           | this driver            |
-| capture every frame of an animation                 | this driver            |
-| let an AI agent see and operate the VVD over MCP    | this driver            |
-| check the TV safe area                              | this driver            |
+| To…                                                 | Appium | this driver |
+| :-------------------------------------------------- | :----: | :---------: |
+| find elements, read their text, run a test suite    |   ✅   |      —      |
+| test on a Fire TV Stick                             |   ✅   |      —      |
+| press keys or take a screenshot from a shell script |   ✅   |     ✅      |
+| record a video with sound                           |   —    |     ✅      |
+| capture every frame of an animation                 |   —    |     ✅      |
+| let an AI agent see and operate the VVD over MCP    |   —    |     ✅      |
+| check the TV safe area                              |   ◯    |     ✅      |
+
+✅ a good fit · ◯ possible with your own code (take a screenshot, then check its edges) · — not supported
 
 ## What you need
 
@@ -59,7 +61,7 @@ vvd record demo.mp4 --seconds 20
 | `vvd press <key…> [--gap 450]`                             | Presses remote keys in order: `up down left right ok back menu playpause rewind fastforward`, a `KEY_*` name or an evdev code. `down*3` repeats, `ok:down` and `ok:up` hold and release |
 | `vvd screenshot [file]`                                    | Saves the screen as a PNG                                                                                                                                                               |
 | `vvd record <file> [--seconds 10] [--fps 30] [--no-audio]` | Records the screen with sound to an MP4. Needs ffmpeg                                                                                                                                   |
-| `vvd frames <dir> [--seconds 3]`                           | Saves every distinct frame as a PNG, named by the emulator's time                                                                                                                       |
+| `vvd frames <dir> [--seconds 3] [--max-frames 200]`        | Saves every distinct frame as a PNG, named by the emulator's time. The frames wait in memory until the capture ends: 6 MB each at the VVD's 1920x1080, and 2 GB at most                 |
 | `vvd wait-change [--timeout 5000]`                         | Exits 0 once the screen changes, 1 on timeout                                                                                                                                           |
 | `vvd safe-area [--background #rrggbb] [--margin 0.05]`     | Counts what sits in the outer 5% of each edge. Exits 0 when clear                                                                                                                       |
 | `vvd mcp`                                                  | Runs the MCP server on stdio                                                                                                                                                            |
@@ -110,7 +112,7 @@ device.close();
 
 ## Recipes
 
-**Check an animation.** Start `vvd frames ./frames --seconds 3`, then trigger the animation. Each distinct frame lands as a PNG named by the emulator's own clock. On the VVD, a 220 ms move slide in Dice Chess came through as 10 to 11 frames.
+**Check an animation.** Start `vvd frames ./frames --seconds 3`, then trigger the animation. Each distinct frame lands as a PNG named by the emulator's own clock. The frames wait in memory while the capture runs, about 6 MB each at 1080p, and are written when it ends, because encoding one takes 20 to 200 ms and the screen would go unwatched meanwhile. The capture stops at 200 frames, about 1.2 GB, unless `--max-frames` says otherwise, and in any case before the frames held pass 2 GB, 321 frames at 1080p; the frames it has are written either way. On the VVD on 28 September 2026, with SDK 0.24.12112, the 220 ms pawn slide of Dice Chess's first tutorial move came through with the pawn in flight in 4 to 6 frames, 23 to 55 ms apart. A screenshot takes longer while the screen changes, and that sets the pace.
 
 **Record a demo.** Script the presses, record while they run, and cut the best takes afterwards. Recording works without the device's window.
 
@@ -129,8 +131,8 @@ Measured on the VVD with Vega SDK 0.24.12112 on macOS:
 - **Keys.** The emulator's gRPC `sendKey`, with Linux evdev codes, reaches apps: it is the path the VVD's own on-screen remote uses. OK is `KEY_KPENTER`, and apps receive it as `kpenter`, not the `select` the remote's documentation names. `KEY_SELECT` and `KEY_OK` never arrive, because the emulator's virtual keyboard does not declare them. Back is `KEY_BACK`; `KEY_ESC` does not reach an app as Back.
 - **Dead ends.** The emulator console's `event send`, QEMU's `send-key` and `inputd-cli` on the device all report success and never reach an app.
 - **Home cannot be sent.** `KEY_HOMEPAGE` (172), `KEY_F1` and 170, the code Amazon's Appium documentation gives for Home, all leave the app on screen. To get back to the launcher, run `vega device launch-app -d VirtualDevice -a com.amazon.keplerlauncherapp.main`.
-- **Screenshots.** `getScreenshot` returns 1920x1080. A running process polls it at about 90 screenshots a second; `vvd screenshot` takes about half a second, most of it starting up. The emulator's `streamScreenshot` has delivered only its first frame while the screen kept changing, so the driver polls instead.
-- **Audio.** `streamAudio` sends nothing while the device is silent. `record` rebuilds the track on the video's clock from each packet's capture time and fills the gaps with silence, so a sound effect stays in sync.
+- **Screenshots.** `getScreenshot` returns 1920x1080. A running process polls it in RGB at about 57 screenshots a second of a still screen, 17 ms each, and at 16 to 43 a second while the screen changes, 23 to 61 ms each (measured on 28 September 2026). `vvd screenshot` takes about half a second, most of it starting up. The emulator's `streamScreenshot` has delivered only its first frame while the screen kept changing, so the driver polls instead. The device's `gwsi-tool-screenshooter` is for a Fire TV Stick: the VDA reference notes that the VVD doesn't support it, and on the VVD it wrote a 0-byte PNG or hung, with no error (28 September 2026).
+- **Audio.** `streamAudio` sends nothing while the device is silent, and while a sound plays each packet's capture time wanders by about ±10 ms around where the packet before it ends. `record` lays the packets of one sound back to back and places the sound where their capture times agree best, then fills the gaps between sounds with silence. A sound stays in sync, and a long one, such as speech or music, plays without holes ([#13](https://github.com/fortemate/vega-vvd-driver/issues/13)). Measured on the VVD.
 - **gRPC.** The endpoint is off after every start of the VVD, and the discovery file that the driver reads appears only once `grpc <port>` has been sent to the console. `vvd enable-grpc` does that.
 
 ## Troubleshooting

package/dist/bin.js

@@ -2,12 +2,14 @@
 // The executable behind `vvd`. Kept apart from cli.ts so that the tests can
 // import the command line without running it.
 import { main } from "./cli.js";
-main(process.argv.slice(2)).then((code) => {
+try {
+    const code = await main(process.argv.slice(2));
     // -1: a long-running command (the MCP server) that exits on its own.
     if (code >= 0)
         process.exitCode = code;
-}, (error) => {
+}
+catch (error) {
     // 2, so that scripts can tell an error from wait-change's "no change".
     console.error(`vvd: ${error.message ?? String(error)}`);
     process.exitCode = 2;
-});
+}

package/dist/cli.d.ts

@@ -1,3 +1,4 @@
+import { Device } from './device.ts';
 export declare const USAGE: string;
 export type Parsed = {
     command: string | undefined;
@@ -8,6 +9,7 @@ export type Parsed = {
         'console-port'?: string;
         gap?: string;
         seconds?: string;
+        'max-frames'?: string;
         fps?: string;
         'no-audio'?: boolean;
         timeout?: string;
@@ -23,4 +25,15 @@ export declare const numberOption: (value: string | undefined, name: string, fal
     max?: number | undefined;
     integer?: boolean | undefined;
 }) => number;
+export declare const MAX_FRAMES = 200;
+export declare const MAX_BYTES = 2000000000;
+export declare const saveFrames: (device: Device, dir: string, options: {
+    durationMs: number;
+    maxFrames?: number;
+    maxBytes?: number;
+    encode?: (width: number, height: number, rgb: Buffer) => Buffer;
+}) => Promise<{
+    count: number;
+    stopped: "max-frames" | "memory" | undefined;
+}>;
 export declare const main: (argv: readonly string[]) => Promise<number>;

package/dist/cli.js

@@ -30,8 +30,11 @@ Commands:
       --seconds <n>          default 10
       --fps <n>              default 30
       --no-audio             video only
-  frames <dir>               save every distinct frame as a PNG, to check animations
+  frames <dir>               save every distinct frame as a PNG, to check animations;
+                             frames wait in memory until the capture ends, 6 MB each
+                             at 1080p, and it stops before they pass 2 GB
       --seconds <n>          default 3
+      --max-frames <n>       stop after this many frames, default 200
   wait-change                exit 0 once the screen changes, 1 on a timeout
       --timeout <ms>         default 5000
   safe-area                  check the outer 5% of the screen against the background;
@@ -59,6 +62,7 @@ export const parseCli = (argv) => {
             'console-port': { type: 'string' },
             gap: { type: 'string' },
             seconds: { type: 'string' },
+            'max-frames': { type: 'string' },
             fps: { type: 'string' },
             'no-audio': { type: 'boolean' },
             timeout: { type: 'string' },
@@ -84,6 +88,170 @@ export const numberOption = (value, name, fallback, { min = 0, max = Number.MAX_
     return parsed;
 };
 const stamp = () => new Date().toISOString().replace(/[:.]/g, '-');
+// How many frames `vvd frames` holds by default: about 1.2 GB at 1080p.
+export const MAX_FRAMES = 200;
+// The most memory the held frames may take, whatever --max-frames says and
+// whatever the screen's size: 321 frames at 1080p.
+export const MAX_BYTES = 2_000_000_000;
+// Captures every distinct frame for `durationMs`, then writes each to `dir`
+// as frame-<ms>ms.png, the milliseconds on the emulator's clock from the
+// first frame. The frames wait in memory until the capture is over: encoding
+// one at 1080p takes 20 to 200 ms, and the next screenshot would wait for it.
+// The capture stops after `maxFrames`, or before the frames held would pass
+// `maxBytes`; the frames it has are written either way.
+export const saveFrames = async (device, dir, options) => {
+    const { durationMs, maxFrames = MAX_FRAMES, maxBytes = MAX_BYTES, encode = encodePng, } = options;
+    const held = [];
+    let bytes = 0;
+    // Fires at the first frame that does not fit, which is not kept: frames can
+    // differ in size, so each one is checked as it comes.
+    const full = new AbortController();
+    try {
+        await device.frames(durationMs, (frame) => {
+            if (bytes + frame.data.length > maxBytes) {
+                full.abort();
+                return;
+            }
+            held.push(frame);
+            bytes += frame.data.length;
+        }, { maxFrames, signal: full.signal });
+    }
+    catch (error) {
+        if (!full.signal.aborted)
+            throw error;
+    }
+    const first = held[0]?.timestampUs ?? 0;
+    for (const frame of held) {
+        const ms = Math.round((frame.timestampUs - first) / 1000);
+        writeFileSync(join(dir, `frame-${String(ms).padStart(6, '0')}ms.png`), encode(frame.width, frame.height, frame.data));
+    }
+    let stopped;
+    if (full.signal.aborted)
+        stopped = 'memory';
+    else if (held.length >= maxFrames)
+        stopped = 'max-frames';
+    return { count: held.length, stopped };
+};
+// Connects to the device, runs `body` with it, and lets go of the device
+// however `body` ends.
+const withDevice = async (pid, body) => {
+    const device = Device.connect({ pid });
+    try {
+        return await body(device);
+    }
+    finally {
+        device.close();
+    }
+};
+// The commands by name, each returning its exit status. Options are checked
+// before a device is looked for.
+const COMMANDS = {
+    devices({ pid }) {
+        const devices = findEmulators({ pid });
+        if (devices.length === 0) {
+            console.log('No running Vega Virtual Device with gRPC on. Start one, then run: vvd enable-grpc');
+            return 1;
+        }
+        for (const d of devices)
+            console.log(`pid ${d.pid}  grpc ${d.grpcPort}  console ${d.consolePort ?? '-'}  ${d.avdName ?? ''}`.trimEnd());
+        return 0;
+    },
+    async 'enable-grpc'({ values, pid }) {
+        if (pid !== undefined)
+            throw new Error('enable-grpc talks to an emulator console, not to a pid: use --console-port');
+        const port = numberOption(values.port, 'port', 8554, {
+            min: 1024,
+            max: 65535,
+        });
+        const consolePort = numberOption(values['console-port'], 'console-port', 5554, { min: 5554, max: 5682 });
+        await enableGrpc(port, { port: consolePort });
+        console.log(`gRPC is on at port ${port}.`);
+        return 0;
+    },
+    async press({ positionals, values, pid }) {
+        if (positionals.length === 0)
+            throw new Error('press needs at least one key, for example: vvd press down ok');
+        const steps = parseKeys(positionals); // fails before connecting on a typo
+        const gapMs = numberOption(values.gap, 'gap', 450, { max: 60000 });
+        await withDevice(pid, (device) => device.press(steps, { gapMs }));
+        return 0;
+    },
+    async screenshot({ positionals, pid }) {
+        const file = positionals[0] ?? `vvd-${stamp()}.png`;
+        const frame = await withDevice(pid, (device) => device.screenshot('png'));
+        writeFileSync(file, frame.data);
+        console.log(file);
+        return 0;
+    },
+    async record({ positionals, values, pid }) {
+        const file = positionals[0];
+        if (!file)
+            throw new Error('record needs a file, for example: vvd record demo.mp4 --seconds 20');
+        const options = {
+            file,
+            seconds: numberOption(values.seconds, 'seconds', 10, {
+                min: 1,
+                max: 3600,
+                integer: false,
+            }),
+            fps: numberOption(values.fps, 'fps', 30, { min: 1, max: 60 }),
+            audio: !values['no-audio'],
+        };
+        const result = await withDevice(pid, (device) => record(device, options));
+        console.log(`${result.file}: ${result.frames} frames, ${result.audioSeconds.toFixed(1)} s of audio`);
+        return 0;
+    },
+    async frames({ positionals, values, pid }) {
+        const dir = positionals[0];
+        if (!dir)
+            throw new Error('frames needs a directory, for example: vvd frames ./frames --seconds 3');
+        const seconds = numberOption(values.seconds, 'seconds', 3, {
+            min: 0.1,
+            max: 600,
+            integer: false,
+        });
+        const maxFrames = numberOption(values['max-frames'], 'max-frames', MAX_FRAMES, { min: 1, max: 10_000 });
+        mkdirSync(dir, { recursive: true });
+        const { count, stopped } = await withDevice(pid, (device) => saveFrames(device, dir, { durationMs: seconds * 1000, maxFrames }));
+        const why = {
+            'max-frames': `stopped at --max-frames ${maxFrames}`,
+            memory: `stopped at ${MAX_BYTES / 1e9} GB of frames in memory`,
+        };
+        console.log(stopped
+            ? `${count} distinct frames in ${dir}: ${why[stopped]} before the ${seconds} s were up`
+            : `${count} distinct frames in ${dir}`);
+        return 0;
+    },
+    async 'wait-change'({ values, pid }) {
+        const timeoutMs = numberOption(values.timeout, 'timeout', 5000, {
+            min: 1,
+            max: 3_600_000,
+        });
+        const changed = await withDevice(pid, (device) => device.waitForChange({ timeoutMs }));
+        console.log(changed ? 'changed' : 'no change');
+        return changed ? 0 : 1;
+    },
+    async 'safe-area'({ values, pid }) {
+        const options = {
+            background: values.background
+                ? parseColour(values.background)
+                : undefined,
+            margin: numberOption(values.margin, 'margin', 0.05, {
+                min: 0.01,
+                max: 0.25,
+                integer: false,
+            }),
+        };
+        const frame = await withDevice(pid, (device) => device.screenshot('rgb'));
+        const report = checkSafeArea(frame.data, frame.width, frame.height, options);
+        console.log(`${report.clear ? 'clear' : 'NOT clear'}: left=${report.left} right=${report.right} top=${report.top} bottom=${report.bottom} (background ${formatColour(report.background)})`);
+        return report.clear ? 0 : 1;
+    },
+    async mcp({ pid }) {
+        await serveStdio({ pid });
+        return -1; // keeps running until the client disconnects
+    },
+};
 export const main = async (argv) => {
     const { command, positionals, values } = parseCli(argv);
     if (values.version) {
@@ -97,146 +265,8 @@ export const main = async (argv) => {
     const pid = values.pid === undefined
         ? undefined
         : numberOption(values.pid, 'pid', 0, { min: 1 });
-    const connect = () => Device.connect({ pid });
-    switch (command) {
-        case 'devices': {
-            const devices = findEmulators({ pid });
-            if (devices.length === 0) {
-                console.log('No running Vega Virtual Device with gRPC on. Start one, then run: vvd enable-grpc');
-                return 1;
-            }
-            for (const d of devices)
-                console.log(`pid ${d.pid}  grpc ${d.grpcPort}  console ${d.consolePort ?? '-'}  ${d.avdName ?? ''}`.trimEnd());
-            return 0;
-        }
-        case 'enable-grpc': {
-            if (pid !== undefined)
-                throw new Error('enable-grpc talks to an emulator console, not to a pid: use --console-port');
-            const port = numberOption(values.port, 'port', 8554, {
-                min: 1024,
-                max: 65535,
-            });
-            const consolePort = numberOption(values['console-port'], 'console-port', 5554, { min: 5554, max: 5682 });
-            await enableGrpc(port, { port: consolePort });
-            console.log(`gRPC is on at port ${port}.`);
-            return 0;
-        }
-        case 'press': {
-            if (positionals.length === 0)
-                throw new Error('press needs at least one key, for example: vvd press down ok');
-            const steps = parseKeys(positionals); // fails before connecting on a typo
-            const device = connect();
-            try {
-                await device.press(steps, {
-                    gapMs: numberOption(values.gap, 'gap', 450, { max: 60000 }),
-                });
-            }
-            finally {
-                device.close();
-            }
-            return 0;
-        }
-        case 'screenshot': {
-            const file = positionals[0] ?? `vvd-${stamp()}.png`;
-            const device = connect();
-            try {
-                const frame = await device.screenshot('png');
-                writeFileSync(file, frame.data);
-                console.log(file);
-            }
-            finally {
-                device.close();
-            }
-            return 0;
-        }
-        case 'record': {
-            const file = positionals[0];
-            if (!file)
-                throw new Error('record needs a file, for example: vvd record demo.mp4 --seconds 20');
-            const device = connect();
-            try {
-                const result = await record(device, {
-                    file,
-                    seconds: numberOption(values.seconds, 'seconds', 10, {
-                        min: 1,
-                        max: 3600,
-                        integer: false,
-                    }),
-                    fps: numberOption(values.fps, 'fps', 30, { min: 1, max: 60 }),
-                    audio: !values['no-audio'],
-                });
-                console.log(`${result.file}: ${result.frames} frames, ${result.audioSeconds.toFixed(1)} s of audio`);
-            }
-            finally {
-                device.close();
-            }
-            return 0;
-        }
-        case 'frames': {
-            const dir = positionals[0];
-            if (!dir)
-                throw new Error('frames needs a directory, for example: vvd frames ./frames --seconds 3');
-            mkdirSync(dir, { recursive: true });
-            const device = connect();
-            try {
-                let first;
-                const count = await device.frames(numberOption(values.seconds, 'seconds', 3, {
-                    min: 0.1,
-                    max: 600,
-                    integer: false,
-                }) * 1000, (frame) => {
-                    first ??= frame.timestampUs;
-                    const ms = Math.round((frame.timestampUs - first) / 1000);
-                    writeFileSync(join(dir, `frame-${String(ms).padStart(6, '0')}ms.png`), encodePng(frame.width, frame.height, frame.data));
-                });
-                console.log(`${count} distinct frames in ${dir}`);
-            }
-            finally {
-                device.close();
-            }
-            return 0;
-        }
-        case 'wait-change': {
-            const device = connect();
-            try {
-                const changed = await device.waitForChange({
-                    timeoutMs: numberOption(values.timeout, 'timeout', 5000, {
-                        min: 1,
-                        max: 3_600_000,
-                    }),
-                });
-                console.log(changed ? 'changed' : 'no change');
-                return changed ? 0 : 1;
-            }
-            finally {
-                device.close();
-            }
-        }
-        case 'safe-area': {
-            const device = connect();
-            try {
-                const frame = await device.screenshot('rgb');
-                const report = checkSafeArea(frame.data, frame.width, frame.height, {
-                    background: values.background
-                        ? parseColour(values.background)
-                        : undefined,
-                    margin: numberOption(values.margin, 'margin', 0.05, {
-                        min: 0.01,
-                        max: 0.25,
-                        integer: false,
-                    }),
-                });
-                console.log(`${report.clear ? 'clear' : 'NOT clear'}: left=${report.left} right=${report.right} top=${report.top} bottom=${report.bottom} (background ${formatColour(report.background)})`);
-                return report.clear ? 0 : 1;
-            }
-            finally {
-                device.close();
-            }
-        }
-        case 'mcp':
-            await serveStdio({ pid });
-            return -1; // keeps running until the client disconnects
-        default:
-            throw new Error(`unknown command "${command}". Run vvd --help.`);
-    }
+    // Own names only, so that "constructor" and the like are not commands.
+    if (!Object.hasOwn(COMMANDS, command))
+        throw new Error(`unknown command "${command}". Run vvd --help.`);
+    return COMMANDS[command]({ positionals, values, pid });
 };

package/dist/device.d.ts

@@ -42,6 +42,7 @@ export declare class Device {
     }): Promise<boolean>;
     frames(durationMs: number, onFrame: (frame: Frame) => void | Promise<void>, options?: {
         intervalMs?: number;
+        maxFrames?: number;
         signal?: AbortSignal;
     }): Promise<number>;
     listen(): () => AudioPacket[];

package/dist/device.js

@@ -154,10 +154,21 @@ export class Device {
         }
         return false;
     }
-    // Calls `onFrame` with every distinct frame for `durationMs`. Useful to
-    // check an animation: a 220 ms slide comes through as about ten frames.
+    // Calls `onFrame` with every distinct frame for `durationMs`, or until
+    // `maxFrames` of them have come; `maxFrames` is a whole number from 1, and
+    // anything else is refused before the first screenshot. Useful to check an
+    // animation: on the VVD a screenshot takes 23 to 61 ms while the screen
+    // changes, and a 220 ms slide comes through as 4 to 6 frames.
+    //
+    // The next screenshot waits for `onFrame`, so keep it quick: encoding a
+    // 1080p PNG takes 20 to 200 ms, and frames that come meanwhile are missed.
+    // Hold the frames and save them once the capture is over, as `vvd frames`
+    // does; `maxFrames` bounds the memory, about 6 MB a frame at 1080p.
     async frames(durationMs, onFrame, options = {}) {
-        const { signal } = options;
+        const { signal, maxFrames = Infinity } = options;
+        const whole = Number.isInteger(maxFrames) && maxFrames >= 1;
+        if (!whole && maxFrames !== Infinity)
+            throw new RangeError(`maxFrames must be a whole number from 1, not ${maxFrames}`);
         const endMs = Date.now() + durationMs;
         let previous;
         let count = 0;
@@ -169,6 +180,8 @@ export class Device {
                 previous = frame.data;
                 count += 1;
                 await onFrame(frame);
+                if (count >= maxFrames)
+                    break;
             }
             if (options.intervalMs)
                 await sleep(options.intervalMs, undefined, { signal });

package/dist/discovery.js

@@ -58,41 +58,43 @@ const toPort = (value) => {
     const port = Number(value);
     return Number.isInteger(port) && port > 0 ? port : undefined;
 };
+// The emulator a discovery file describes, or undefined when the file names
+// no gRPC port.
+const readEmulator = (file, pid) => {
+    const fields = parseDiscovery(readFileSync(file, 'utf8'));
+    const grpcPort = toPort(fields.get('grpc.port'));
+    if (grpcPort === undefined)
+        return undefined;
+    return Object.defineProperty({
+        pid,
+        file,
+        grpcPort,
+        consolePort: toPort(fields.get('port.serial')),
+        avdName: fields.get('avd.name') || undefined,
+    }, 'grpcToken', { value: fields.get('grpc.token') || undefined, enumerable: false });
+};
 // The running emulators with gRPC on, newest first. Stale files left by an
 // emulator that has exited are skipped.
 export const findEmulators = (options = {}) => {
     const alive = options.alive ?? isAlive;
+    const wanted = (pid) => (options.pid === undefined || pid === options.pid) && alive(pid);
     const found = [];
     for (const directory of options.directories ?? runningDirectories()) {
         if (!existsSync(directory))
             continue;
         for (const name of readdirSync(directory)) {
-            const match = /^pid_(\d+)\.ini$/.exec(name);
-            if (!match)
-                continue;
-            const pid = Number(match[1]);
-            if (options.pid !== undefined && pid !== options.pid)
-                continue;
-            if (!alive(pid))
+            // NaN for a name that is no discovery file.
+            const pid = Number(/^pid_(\d+)\.ini$/.exec(name)?.[1]);
+            if (Number.isNaN(pid) || !wanted(pid))
                 continue;
             const file = join(directory, name);
-            const fields = parseDiscovery(readFileSync(file, 'utf8'));
-            const grpcPort = toPort(fields.get('grpc.port'));
-            if (grpcPort === undefined)
-                continue;
-            const emulator = Object.defineProperty({
-                pid,
-                file,
-                grpcPort,
-                consolePort: toPort(fields.get('port.serial')),
-                avdName: fields.get('avd.name') || undefined,
-            }, 'grpcToken', { value: fields.get('grpc.token') || undefined, enumerable: false });
-            found.push({ emulator, modified: statSync(file).mtimeMs });
+            const emulator = readEmulator(file, pid);
+            if (emulator)
+                found.push({ emulator, modified: statSync(file).mtimeMs });
         }
     }
-    return found
-        .sort((a, b) => b.modified - a.modified)
-        .map(({ emulator }) => emulator);
+    found.sort((a, b) => b.modified - a.modified);
+    return found.map(({ emulator }) => emulator);
 };
 export class NoDeviceError extends Error {
     constructor() {

package/dist/mcp.js

@@ -40,6 +40,8 @@ export const videoPath = (file, overwrite = false) => {
         throw new Error(`${path} exists; set overwrite to replace it`);
     return path;
 };
+// The same emulator, serving the same endpoint with the same token.
+const sameEndpoint = (a, b) => a.pid === b.pid && a.grpcPort === b.grpcPort && a.grpcToken === b.grpcToken;
 export const createServer = (options = {}) => {
     const server = new McpServer({ name: 'vega-vvd-driver', version: VERSION });
     const find = { pid: options.pid, directories: options.directories };
@@ -48,13 +50,7 @@ export const createServer = (options = {}) => {
     let device;
     const connected = () => {
         const [newest] = findEmulators(find);
-        const current = device?.emulator;
-        if (device &&
-            current &&
-            newest &&
-            current.pid === newest.pid &&
-            current.grpcPort === newest.grpcPort &&
-            current.grpcToken === newest.grpcToken)
+        if (device && newest && sameEndpoint(device.emulator, newest))
             return device;
         device?.close();
         device = undefined; // a failed connect below must not leave it cached

package/dist/record.js

@@ -4,10 +4,11 @@
 // Frames are polled with getScreenshot and written to ffmpeg at a fixed frame
 // rate, repeating the latest frame when the screen is still. The emulator's
 // streamScreenshot was tried first and can stop delivering frames while the
-// screen keeps changing; polling keeps up at about 90 screenshots a second at
-// 1080p. The audio comes from streamAudio. The emulator sends nothing while
-// the device is silent, so the track is rebuilt on the video's clock from each
-// packet's capture time, with silence in the gaps.
+// screen keeps changing. Polling does not stop: on the VVD a 1080p screenshot
+// takes about 17 ms, or 23 to 61 ms while the screen changes. The audio comes
+// from streamAudio. The emulator sends nothing while the device is silent, so
+// the track is rebuilt on the video's clock from the packets' capture times,
+// with silence in the gaps; see assembleAudio for how.
 //
 // However a recording ends, it cleans up after itself: ffmpeg is stopped, the
 // audio stream is cancelled and the working directory is removed.
@@ -48,23 +49,91 @@ const abortable = (promise, signal) => {
 };
 const SAMPLE_RATE = 44100;
 const FRAME_BYTES = 4; // 16-bit stereo
+// A packet's capture time wanders by about ±10 ms around where the packet
+// before it ends, and a stream starts with smaller packets (#13). Laid each at
+// its own time, the packets of one sound would leave holes and cut into each
+// other several times a second, which is heard as a rattle. So consecutive
+// packets are laid back to back, the way the device played them, and each run
+// of them is placed as a whole where the capture times agree best: their
+// median. A run ends where the device sent nothing, a silence that leaves a
+// step in time longer than SILENCE_US, and where it has drifted from the clock
+// by more than DRIFT_US. Its first SETTLE_US are not held to the clock: there
+// the small packets' capture times run ahead of their audio, by more than
+// DRIFT_US at the start of some sounds, and splitting there would cut a hole
+// just after the sound begins.
+const SILENCE_US = 50_000;
+const DRIFT_US = 100_000;
+const SETTLE_US = 500_000;
+const framesOf = (packet) => Math.floor(packet.pcm.length / FRAME_BYTES);
+const usOf = (frames) => (frames / SAMPLE_RATE) * 1e6;
+// The packets in the order they arrived, which is the order they were played,
+// cut into runs at each silence.
+const runsOf = (packets) => {
+    const runs = [];
+    let run = [];
+    for (const packet of packets) {
+        const last = run.at(-1);
+        if (last &&
+            Math.abs(packet.timestampUs - (last.timestampUs + usOf(framesOf(last)))) >
+                SILENCE_US) {
+            runs.push(run);
+            run = [];
+        }
+        run.push(packet);
+    }
+    if (run.length)
+        runs.push(run);
+    return runs;
+};
+// Where a run's first frame belongs on a clock that starts at `startUs`, in
+// microseconds: each packet's capture time less the audio before it in the
+// run, and the median of those, which jitter and the first small packets do
+// not move.
+const anchorOf = (run, startUs) => {
+    let before = 0;
+    const offsets = run.map((packet) => {
+        const offset = packet.timestampUs - startUs - usOf(before);
+        before += framesOf(packet);
+        return offset;
+    });
+    offsets.sort((a, b) => a - b);
+    return offsets[Math.floor(offsets.length / 2)];
+};
+// The run split where a packet, past the run's first SETTLE_US of audio, has
+// drifted more than DRIFT_US from the place the run gives it, so a long sound
+// follows the clock: the part before the first such packet, and the rest.
+const steady = (run, startUs) => {
+    const anchor = anchorOf(run, startUs);
+    let before = 0;
+    for (let i = 0; i < run.length; i++) {
+        const drift = run[i].timestampUs - startUs - (anchor + usOf(before));
+        if (usOf(before) > SETTLE_US && Math.abs(drift) > DRIFT_US)
+            return [run.slice(0, i), run.slice(i)];
+        before += framesOf(run[i]);
+    }
+    return [[...run], []];
+};
 // Lays audio packets on a timeline that starts at `startUs` and lasts
-// `seconds`, as 16-bit stereo PCM: silence where nothing arrived, and a packet
-// that starts earlier than the audio before it overwrites the overlap. Packets
-// captured before the start are cut; the result is exactly as long as asked.
+// `seconds`, as 16-bit stereo PCM, with silence where nothing arrived. Audio
+// placed before the start is cut, and past the end is dropped; the result is
+// exactly as long as asked. Where two runs overlap, the later one is heard.
 export const assembleAudio = (packets, startUs, seconds) => {
     const track = Buffer.alloc(Math.round(seconds * SAMPLE_RATE) * FRAME_BYTES);
-    for (const packet of packets) {
-        const frames = Math.floor(packet.pcm.length / FRAME_BYTES);
-        let offset = Math.round(((packet.timestampUs - startUs) / 1e6) * SAMPLE_RATE);
-        let from = 0;
-        if (offset < 0) {
-            from = -offset;
-            offset = 0;
+    const pending = runsOf(packets);
+    while (pending.length) {
+        const [run, rest] = steady(pending.shift(), startUs);
+        if (rest.length)
+            pending.unshift(rest);
+        let offset = Math.round((anchorOf(run, startUs) / 1e6) * SAMPLE_RATE);
+        for (const packet of run) {
+            const frames = framesOf(packet);
+            const from = Math.max(0, -offset);
+            const at = offset + from;
+            offset += frames;
+            if (from >= frames || at * FRAME_BYTES >= track.length)
+                continue;
+            packet.pcm.copy(track, at * FRAME_BYTES, from * FRAME_BYTES, frames * FRAME_BYTES);
         }
-        if (from >= frames || offset * FRAME_BYTES >= track.length)
-            continue;
-        packet.pcm.copy(track, offset * FRAME_BYTES, from * FRAME_BYTES, frames * FRAME_BYTES);
     }
     return track;
 };
@@ -244,7 +313,7 @@ export const record = async (device, options) => {
     }
     finally {
         stopAudio?.();
-        if (encoder && encoder.exitCode === null && encoder.signalCode === null) {
+        if (encoder?.exitCode === null && encoder.signalCode === null) {
             encoder.stdin.destroy();
             encoder.kill('SIGKILL');
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fortemate/vega-vvd-driver",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Unofficial driver for the Vega Virtual Device: remote keys, screenshots and video with sound, from scripts and AI agents. CLI, Node library and MCP server.",
   "keywords": [
     "vega",
@@ -46,6 +46,7 @@
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "test": "node --test test/*.test.ts",
+    "coverage": "node -e \"require('node:fs').mkdirSync('coverage', { recursive: true })\" && node --test --experimental-test-coverage --test-coverage-exclude='test/**' --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/lcov.info test/*.test.ts",
     "test:device": "VVD_INTEGRATION=1 node --test test/device.test.ts",
     "prepare": "npm run build"
   },