@fortemate/vega-vvd-driver 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jegors Čemisovs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+# vega-vvd-driver
+
+Drive the Vega Virtual Device from scripts and AI agents: press remote keys, take screenshots, record video with sound, wait for the screen to change and check the TV safe area. A Node library, the `vvd` command and an MCP server.
+
+> **Unofficial.** Not made, endorsed or supported by Amazon. Amazon, Fire TV and Vega are trademarks of Amazon.com, Inc. or its affiliates.
+
+## 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.
+
+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.
+
+Its methods were worked out while building [Dice Chess for Fire TV](https://github.com/fortemate/dicechess-tv): scripts drove whole sessions with nobody at the emulator, took every screenshot of the game's gallery, checked its move animations frame by frame and recorded its [demo video](https://www.youtube.com/watch?v=Q7wWAmUp2Sc). The obstacles on the way are in that project's [friction log](https://fortemate.github.io/dicechess-tv/friction-log/) for Amazon, as FL-08, FL-09 and FL-28.
+
+## 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            |
+
+## What you need
+
+- The Vega SDK with its Virtual Device. The driver was built and tested with SDK 0.24.12112 on macOS (Apple silicon). The Linux locations are included but untested.
+- Node 20 or later.
+- ffmpeg, only for `record`.
+
+## Install
+
+```sh
+npm install -g @fortemate/vega-vvd-driver
+```
+
+Or inside a project: `npm install --save-dev @fortemate/vega-vvd-driver`, then `npx vvd`.
+
+To work on the driver itself, clone the repository, then run `npm ci` and `npm link`. Installing straight from Git with `npm install -g github:fortemate/vega-vvd-driver` does not work, at least with npm 11.19: for a global install from Git, npm runs the build without installing its dependencies, and it fails with `tsc: command not found`.
+
+## Quick start
+
+```sh
+vega virtual-device start --no-gui   # the window is optional
+vvd enable-grpc                      # needed after every start of the device
+vvd screenshot home.png
+vvd press down down ok
+vvd record demo.mp4 --seconds 20
+```
+
+## Commands
+
+| Command                                                    | What it does                                                                                                                                                                            |
+| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `vvd devices`                                              | Lists running devices whose gRPC endpoint is on                                                                                                                                         |
+| `vvd enable-grpc [--port 8554] [--console-port 5554]`      | Turns gRPC on through the emulator console. It is off after every start of the device                                                                                                   |
+| `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 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                                                                                                                                                            |
+
+Quote a repeated key in a shell, `'down*3'`, or zsh reads the `*` as a file pattern. When several devices run, `--pid <n>` picks one; `enable-grpc` picks a device's console with `--console-port` instead. Errors exit with 2, so that a script can tell them from "no change" and "not clear", which exit with 1.
+
+## For AI agents: the MCP server
+
+The server lets an agent operate the device and see the result. With Claude Code:
+
+```sh
+claude mcp add vvd -- vvd mcp
+```
+
+Other MCP clients start the command `vvd` with the argument `mcp`. With the driver installed inside a project, the command is `npx vvd mcp`.
+
+| Tool              | What it does                                                        |
+| ----------------- | ------------------------------------------------------------------- |
+| `list_devices`    | The running devices with gRPC on                                    |
+| `enable_grpc`     | Turns gRPC on after a start of the device                           |
+| `press_keys`      | Presses keys; with `screenshot_after`, returns the resulting screen |
+| `screenshot`      | The screen as a PNG image                                           |
+| `wait_for_change` | Waits until the screen changes, then returns it                     |
+| `record_video`    | Records an MP4 with sound                                           |
+| `check_safe_area` | Counts what sits in the TV safe-area margin                         |
+
+Then ask, for example: "Open Settings in the app on the Virtual Device, turn the music off and show me the screen."
+
+A model chooses the arguments, so they are bounded: at most 100 key presses per call, recordings of up to 600 seconds, and `record_video` writes only a new `.mp4`, `.mov` or `.mkv` file, unless it is told to `overwrite` one. When the client cancels a call, its presses, wait or recording stop. `vvd mcp --pid <n>` ties the server to one device.
+
+## As a library
+
+```ts
+import { Device, record } from '@fortemate/vega-vvd-driver';
+
+const device = Device.connect(); // the newest running VVD with gRPC on
+await device.press(['down', 'down', 'ok']);
+const png = await device.screenshot('png');
+await record(device, {
+  file: 'demo.mp4',
+  seconds: 10,
+  onStart: () => device.press(['right*3']),
+});
+device.close();
+```
+
+`device.waitForChange()`, `device.frames()` and `checkSafeArea()` cover the rest. Every call has a deadline (10 seconds, or `callTimeoutMs` given to `Device.connect`), so a stuck emulator fails a call instead of hanging it. `press`, `waitForChange`, `frames` and `record` take an AbortSignal as `signal`, and a cancelled press still releases its key. `onStart` runs alongside the recording, which ends when both have. See `src/index.ts` for everything exported.
+
+## 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.
+
+**Record a demo.** Script the presses, record while they run, and cut the best takes afterwards. Recording works without the device's window.
+
+```sh
+vvd record take.mp4 --seconds 30 &
+sleep 2 && vvd press 'ok*20' --gap 1300
+wait
+```
+
+**Check the safe area.** Open a screen of the app and run `vvd safe-area --background '#122737'` with the app's background colour. It works on screens with a solid background; the launcher's gradient does not count as one.
+
+## What works, and what silently does not
+
+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.
+- **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
+
+- **"No running Vega Virtual Device with gRPC found."** Start the device, then run `vvd enable-grpc`.
+- **"emulator_controller.proto not found."** Set `VVD_PROTO_DIR` to the directory in your Vega SDK that holds it (`…/vvd/images/tv/vmtools/agent/lib`).
+- **Several devices.** Pick one with `--pid`, from `vvd devices`.
+- **"The Vega Virtual Device did not answer in time."** The emulator is busy or stuck. Restart the device if it keeps happening.
+- **`record` fails at once.** Install ffmpeg.
+
+## How it works
+
+A running emulator with gRPC on writes `pid_<pid>.ini` into a per-user directory (`~/Library/Caches/TemporaryItems/avd/running` on macOS). It holds the gRPC port and a bearer token. The driver reads it, loads `emulator_controller.proto` from your own Vega SDK, and calls the emulator's `EmulatorController` service. To turn gRPC on, it signs in to the emulator console on port 5554 with the token in `~/.emulator_console_auth_token`.
+
+- Tokens are read at run time and never printed or logged. On the objects the library returns, the gRPC token is not enumerable, so it stays out of JSON and `util.inspect`. The console token goes only to a port that greets as an Android emulator console.
+- No file from the Vega SDK is copied or bundled: Amazon licenses the SDK to each developer. The proto is Android emulator code under Apache-2.0, and it is loaded from your installation.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). In short: `mise run setup`, then `mise run check`; with a device running and gRPC on, `npm run test:device`. The unit tests run the gRPC, console and recording paths against fakes, so they need neither a device nor ffmpeg.
+
+## Licence
+
+[MIT](LICENSE). Made by Jegors Čemisovs at [Fortemate](https://github.com/fortemate).

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// 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) => {
+    // -1: a long-running command (the MCP server) that exits on its own.
+    if (code >= 0)
+        process.exitCode = code;
+}, (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

@@ -0,0 +1,26 @@
+export declare const USAGE: string;
+export type Parsed = {
+    command: string | undefined;
+    positionals: string[];
+    values: {
+        pid?: string;
+        port?: string;
+        'console-port'?: string;
+        gap?: string;
+        seconds?: string;
+        fps?: string;
+        'no-audio'?: boolean;
+        timeout?: string;
+        background?: string;
+        margin?: string;
+        help?: boolean;
+        version?: boolean;
+    };
+};
+export declare const parseCli: (argv: readonly string[]) => Parsed;
+export declare const numberOption: (value: string | undefined, name: string, fallback: number, { min, max, integer }?: {
+    min?: number | undefined;
+    max?: number | undefined;
+    integer?: boolean | undefined;
+}) => number;
+export declare const main: (argv: readonly string[]) => Promise<number>;

package/dist/cli.js

@@ -0,0 +1,242 @@
+// The `vvd` command line.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseArgs } from 'node:util';
+import { enableGrpc } from "./console.js";
+import { Device } from "./device.js";
+import { findEmulators } from "./discovery.js";
+import { parseKeys } from "./keys.js";
+import { serveStdio } from "./mcp.js";
+import { encodePng } from "./png.js";
+import { record } from "./record.js";
+import { checkSafeArea, formatColour, parseColour } from "./safearea.js";
+import { VERSION } from "./version.js";
+export const USAGE = `vvd ${VERSION}: drive the Vega Virtual Device from scripts and AI agents.
+
+Usage: vvd <command> [options]
+
+Commands:
+  devices                    list running devices whose gRPC endpoint is on
+  enable-grpc                turn gRPC on (it is off after every start of the device)
+      --port <n>             gRPC port, default 8554
+      --console-port <n>     emulator console port, even, 5554 to 5682; default 5554
+  press <key...>             press 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 / ok:up hold and release
+      --gap <ms>             pause after each key, default 450
+  screenshot [file]          save the screen as a PNG, default vvd-<time>.png
+  record <file>              record the screen with sound to an MP4 (needs ffmpeg)
+      --seconds <n>          default 10
+      --fps <n>              default 30
+      --no-audio             video only
+  frames <dir>               save every distinct frame as a PNG, to check animations
+      --seconds <n>          default 3
+  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;
+                             exit 0 when clear, 1 when something sits in the margin
+      --background <#rrggbb> default: the most common colour in the margin
+      --margin <fraction>    default 0.05
+  mcp                        run the MCP server on stdio, for AI agents
+
+Options:
+  --pid <n>                  the device to drive when several run
+                             (every command but enable-grpc, which uses
+                             --console-port)
+  -h, --help, -v, --version
+
+Exit status: 0 on success, 1 for "no change" and "not clear", 2 on an error.
+`;
+export const parseCli = (argv) => {
+    const { values, positionals } = parseArgs({
+        args: [...argv],
+        allowPositionals: true,
+        strict: true,
+        options: {
+            pid: { type: 'string' },
+            port: { type: 'string' },
+            'console-port': { type: 'string' },
+            gap: { type: 'string' },
+            seconds: { type: 'string' },
+            fps: { type: 'string' },
+            'no-audio': { type: 'boolean' },
+            timeout: { type: 'string' },
+            background: { type: 'string' },
+            margin: { type: 'string' },
+            help: { type: 'boolean', short: 'h' },
+            version: { type: 'boolean', short: 'v' },
+        },
+    });
+    const [command, ...rest] = positionals;
+    return { command, positionals: rest, values };
+};
+// A whole number option, or its default.
+export const numberOption = (value, name, fallback, { min = 0, max = Number.MAX_SAFE_INTEGER, integer = true } = {}) => {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) ||
+        (integer && !Number.isInteger(parsed)) ||
+        parsed < min ||
+        parsed > max)
+        throw new Error(`--${name} must be ${integer ? 'a whole number' : 'a number'} from ${min} to ${max}`);
+    return parsed;
+};
+const stamp = () => new Date().toISOString().replace(/[:.]/g, '-');
+export const main = async (argv) => {
+    const { command, positionals, values } = parseCli(argv);
+    if (values.version) {
+        console.log(VERSION);
+        return 0;
+    }
+    if (values.help || !command) {
+        console.log(USAGE);
+        return command || values.help ? 0 : 2;
+    }
+    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.`);
+    }
+};

package/dist/console.d.ts

@@ -0,0 +1,9 @@
+export type ConsoleOptions = {
+    port?: number;
+    host?: string;
+    token?: string;
+    timeoutMs?: number;
+};
+export declare const runConsole: (commands: readonly string[], options?: ConsoleOptions) => Promise<string[]>;
+export declare const isConsolePort: (port: number) => boolean;
+export declare const enableGrpc: (grpcPort?: number, options?: ConsoleOptions) => Promise<void>;

package/dist/console.js

@@ -0,0 +1,87 @@
+// The emulator console: a line-based TCP service on localhost (5554 for the
+// first emulator). It authenticates with the token in
+// ~/.emulator_console_auth_token, which is sent and never printed.
+//
+// The driver needs it for one thing: `grpc <port>` turns on the gRPC endpoint,
+// which is off after every start of the VVD, and only then does the discovery
+// file appear. Keys do not go through here: the console's `event send` is
+// accepted and never reaches an app.
+import { readFileSync } from 'node:fs';
+import { connect } from 'node:net';
+import { consoleTokenFile } from "./discovery.js";
+// Every reply ends with a line that starts with OK or KO.
+const finished = (text) => /(^|\n)(OK|KO)[^\n]*\r?\n$/.test(text);
+// Runs console commands in order and returns each reply. A command answered
+// with KO rejects with the console's own message.
+export const runConsole = (commands, options = {}) => new Promise((resolve, reject) => {
+    const token = options.token ?? readFileSync(consoleTokenFile(), 'utf8').trim();
+    const port = options.port ?? 5554;
+    const socket = connect(port, options.host ?? '127.0.0.1');
+    const queue = [`auth ${token}`, ...commands];
+    const replies = [];
+    let buffer = '';
+    let greeted = false;
+    let settled = false;
+    const settle = (outcome) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        outcome();
+    };
+    const fail = (error) => settle(() => {
+        socket.destroy();
+        reject(error);
+    });
+    const timer = setTimeout(() => fail(new Error('the emulator console did not answer in time')), options.timeoutMs ?? 10_000);
+    const next = () => {
+        const command = queue.shift();
+        if (command === undefined) {
+            settle(() => {
+                socket.end('quit\r\n');
+                resolve(replies.slice(1)); // the first reply is to auth
+            });
+            return;
+        }
+        socket.write(`${command}\r\n`);
+    };
+    socket.setEncoding('utf8');
+    socket.on('error', fail);
+    socket.on('close', () => fail(new Error('the emulator console closed the connection')));
+    socket.on('data', (chunk) => {
+        buffer += chunk;
+        if (!finished(buffer))
+            return;
+        const reply = buffer;
+        buffer = '';
+        if (!greeted) {
+            // An emulator console greets with lines that start "Android Console",
+            // then OK. Whatever else answers on this port never gets the token.
+            if (!reply.includes('Android Console')) {
+                fail(new Error(`port ${port} is not an Android emulator console`));
+                return;
+            }
+            greeted = true;
+            next();
+            return;
+        }
+        const last = reply.trimEnd().split('\n').pop() ?? '';
+        if (last.startsWith('KO')) {
+            const sent = replies.length === 0 ? 'auth' : commands[replies.length - 1];
+            fail(new Error(`console refused "${sent.split(' ')[0]}": ${last.replace(/^KO:?\s*/, '').trim()}`));
+            return;
+        }
+        replies.push(reply);
+        next();
+    });
+});
+// The emulator takes an even console port from 5554 to 5682.
+export const isConsolePort = (port) => Number.isInteger(port) && port >= 5554 && port <= 5682 && port % 2 === 0;
+// Turns on the emulator's gRPC endpoint. Safe to repeat.
+export const enableGrpc = async (grpcPort = 8554, options = {}) => {
+    if (!isConsolePort(options.port ?? 5554))
+        throw new Error('the emulator console port is an even number from 5554 to 5682');
+    if (!Number.isInteger(grpcPort) || grpcPort < 1024 || grpcPort > 65535)
+        throw new Error('the gRPC port must be a whole number from 1024 to 65535');
+    await runConsole([`grpc ${grpcPort}`], options);
+};

package/dist/device.d.ts

@@ -0,0 +1,48 @@
+import { type Emulator, type FindOptions } from './discovery.ts';
+import { type KeyStep } from './keys.ts';
+export declare const CALL_TIMEOUT_MS = 10000;
+export type ConnectOptions = FindOptions & {
+    protoDirectory?: string;
+    callTimeoutMs?: number;
+};
+export type PressOptions = {
+    gapMs?: number;
+    holdMs?: number;
+    signal?: AbortSignal;
+};
+export type CallOptions = {
+    signal?: AbortSignal;
+    deadline?: number;
+};
+export type Frame = {
+    width: number;
+    height: number;
+    data: Buffer;
+    timestampUs: number;
+};
+export type AudioPacket = {
+    timestampUs: number;
+    pcm: Buffer;
+};
+export declare class TimeoutError extends Error {
+    constructor();
+}
+export declare class Device {
+    #private;
+    readonly emulator: Emulator;
+    private constructor();
+    static connect(options?: ConnectOptions): Device;
+    close(): void;
+    press(keys: readonly string[] | readonly KeyStep[], options?: PressOptions): Promise<void>;
+    screenshot(format?: 'png' | 'rgb', options?: CallOptions): Promise<Frame>;
+    waitForChange(options?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+    frames(durationMs: number, onFrame: (frame: Frame) => void | Promise<void>, options?: {
+        intervalMs?: number;
+        signal?: AbortSignal;
+    }): Promise<number>;
+    listen(): () => AudioPacket[];
+}