@fortemate/vega-vvd-driver 0.1.0

package/dist/device.js

@@ -0,0 +1,208 @@
+// A connection to one running Vega Virtual Device over the emulator's gRPC
+// API (EmulatorController): remote keys, screenshots and the device's audio.
+//
+// Every call has a deadline, so a wedged emulator fails a command instead of
+// hanging it, and every long operation takes an AbortSignal.
+import { join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { credentials, loadPackageDefinition, Metadata, status, } from '@grpc/grpc-js';
+import { loadSync } from '@grpc/proto-loader';
+import { findEmulator, findProtoDirectory, } from "./discovery.js";
+import { parseKeys } from "./keys.js";
+// How long one call may take by default. A 1080p PNG takes about half a
+// second on the VVD.
+export const CALL_TIMEOUT_MS = 10_000;
+// The device did not answer before a call's deadline.
+export class TimeoutError extends Error {
+    constructor() {
+        super('the Vega Virtual Device did not answer in time');
+        this.name = 'TimeoutError';
+    }
+}
+export class Device {
+    emulator;
+    #client;
+    #metadata;
+    #callTimeoutMs;
+    #streams = new Set();
+    constructor(emulator, client, metadata, callTimeoutMs) {
+        this.emulator = emulator;
+        this.#client = client;
+        this.#metadata = metadata;
+        this.#callTimeoutMs = callTimeoutMs;
+    }
+    // Connects to the newest running VVD with gRPC on, or to the given pid.
+    static connect(options = {}) {
+        const emulator = findEmulator(options);
+        const directory = options.protoDirectory ?? findProtoDirectory();
+        const definition = loadSync(join(directory, 'emulator_controller.proto'), {
+            includeDirs: [directory],
+            keepCase: true,
+            enums: String,
+            longs: String,
+        });
+        const control = loadPackageDefinition(definition).android.emulation.control;
+        const client = new control.EmulatorController(`127.0.0.1:${emulator.grpcPort}`, credentials.createInsecure(), 
+        // A 1080p frame is 6 MB, above gRPC's default limit.
+        { 'grpc.max_receive_message_length': 64 * 1024 * 1024 });
+        const metadata = new Metadata();
+        if (emulator.grpcToken)
+            metadata.add('authorization', `Bearer ${emulator.grpcToken}`);
+        return new Device(emulator, client, metadata, options.callTimeoutMs ?? CALL_TIMEOUT_MS);
+    }
+    // Ends the audio streams that are still open, then the connection.
+    close() {
+        for (const stream of this.#streams)
+            stream.cancel();
+        this.#streams.clear();
+        this.#client.close();
+    }
+    // One unary call, with a deadline, cancelled if the signal fires.
+    #call(start, { signal, deadline }) {
+        signal?.throwIfAborted();
+        return new Promise((resolve, reject) => {
+            const cancel = () => call.cancel();
+            const call = start({ deadline: deadline ?? Date.now() + this.#callTimeoutMs }, (error, reply) => {
+                signal?.removeEventListener('abort', cancel);
+                if (signal?.aborted)
+                    reject(signal.reason);
+                else if (error?.code === status.DEADLINE_EXCEEDED)
+                    reject(new TimeoutError());
+                else if (error)
+                    reject(error);
+                else
+                    resolve(reply);
+            });
+            signal?.addEventListener('abort', cancel, { once: true });
+        });
+    }
+    #sendKey(code, eventType, options = {}) {
+        return this.#call((callOptions, callback) => this.#client.sendKey({ codeType: 'Evdev', eventType, keyCode: code }, this.#metadata, callOptions, callback), options);
+    }
+    // Presses keys in order. Accepts names such as `ok`, `down*3`, `ok:down`,
+    // or steps already parsed. A cancelled press still releases its key.
+    async press(keys, options = {}) {
+        const steps = typeof keys[0] === 'string'
+            ? parseKeys(keys)
+            : keys;
+        const { signal } = options;
+        const gap = options.gapMs ?? 450;
+        const hold = options.holdMs ?? 90;
+        for (const step of steps) {
+            signal?.throwIfAborted();
+            if (step.half === 'press') {
+                let released = false;
+                try {
+                    await this.#sendKey(step.code, 'keydown', { signal });
+                    await sleep(hold, undefined, { signal });
+                    await this.#sendKey(step.code, 'keyup');
+                    released = true;
+                }
+                finally {
+                    if (!released)
+                        await this.#sendKey(step.code, 'keyup').catch(() => { });
+                }
+            }
+            else {
+                await this.#sendKey(step.code, step.half === 'down' ? 'keydown' : 'keyup', { signal });
+            }
+            await sleep(gap, undefined, { signal });
+        }
+    }
+    // One frame of the screen, as RGB888 or as a PNG file.
+    async screenshot(format = 'png', options = {}) {
+        const reply = await this.#call((callOptions, callback) => this.#client.getScreenshot({ format: format === 'png' ? 'PNG' : 'RGB888' }, this.#metadata, callOptions, callback), options);
+        const data = reply.image ?? Buffer.alloc(0);
+        if (data.length === 0)
+            throw new Error('the device returned an empty screen: is its display on?');
+        return {
+            width: reply.format?.width ?? 0,
+            height: reply.format?.height ?? 0,
+            data,
+            timestampUs: Number(reply.timestampUs ?? 0),
+        };
+    }
+    // A screenshot taken while polling until `endMs`: its deadline stays close
+    // to the end, and one that runs out after the end gives undefined.
+    async #poll(endMs, signal) {
+        try {
+            return await this.screenshot('rgb', {
+                signal,
+                deadline: Math.min(Date.now() + this.#callTimeoutMs, endMs + 1000),
+            });
+        }
+        catch (error) {
+            if (error instanceof TimeoutError && Date.now() >= endMs)
+                return undefined;
+            throw error;
+        }
+    }
+    // Waits until the screen differs from how it looked when the wait began.
+    // Polls screenshots: the emulator's own screenshot stream can stop
+    // delivering frames while the screen keeps changing.
+    async waitForChange(options = {}) {
+        const { signal } = options;
+        const endMs = Date.now() + (options.timeoutMs ?? 5000);
+        const first = await this.screenshot('rgb', { signal });
+        while (Date.now() < endMs) {
+            await sleep(options.intervalMs ?? 50, undefined, { signal });
+            const frame = await this.#poll(endMs, signal);
+            if (!frame)
+                return false;
+            if (!frame.data.equals(first.data))
+                return true;
+        }
+        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.
+    async frames(durationMs, onFrame, options = {}) {
+        const { signal } = options;
+        const endMs = Date.now() + durationMs;
+        let previous;
+        let count = 0;
+        while (Date.now() < endMs) {
+            const frame = await this.#poll(endMs, signal);
+            if (!frame)
+                break;
+            if (!previous || !frame.data.equals(previous)) {
+                previous = frame.data;
+                count += 1;
+                await onFrame(frame);
+            }
+            if (options.intervalMs)
+                await sleep(options.intervalMs, undefined, { signal });
+        }
+        return count;
+    }
+    // The device's audio as 16-bit little-endian stereo PCM at 44.1 kHz.
+    // Returns a function that stops the stream and gives back the packets that
+    // arrived, each with the time it was captured; calling it again gives the
+    // same packets. The emulator sends nothing while the device is silent, so
+    // the packets can have gaps; see assembleAudio in record.ts.
+    listen() {
+        const packets = [];
+        const stream = this.#client.streamAudio({
+            samplingRate: 44100,
+            channels: 'Stereo',
+            format: 'AUD_FMT_S16',
+            mode: 'MODE_REAL_TIME',
+        }, this.#metadata);
+        this.#streams.add(stream);
+        stream.on('data', (packet) => {
+            if (packet.audio?.length)
+                packets.push({
+                    timestampUs: Number(packet.timestamp ?? 0),
+                    pcm: packet.audio,
+                });
+        });
+        stream.on('error', () => {
+            // Cancelling the stream ends it with an error; nothing to report.
+        });
+        return () => {
+            if (this.#streams.delete(stream))
+                stream.cancel();
+            return packets;
+        };
+    }
+}

package/dist/discovery.d.ts

@@ -0,0 +1,27 @@
+export type Emulator = {
+    pid: number;
+    file: string;
+    grpcPort: number;
+    readonly grpcToken: string | undefined;
+    consolePort: number | undefined;
+    avdName: string | undefined;
+};
+export type SystemFacts = {
+    uid: number | undefined;
+    user: string | undefined;
+    tmp: string;
+};
+export declare const runningDirectories: (env?: NodeJS.ProcessEnv, home?: string, system?: SystemFacts) => string[];
+export declare const parseDiscovery: (text: string) => Map<string, string>;
+export type FindOptions = {
+    directories?: string[];
+    pid?: number;
+    alive?: (pid: number) => boolean;
+};
+export declare const findEmulators: (options?: FindOptions) => Emulator[];
+export declare class NoDeviceError extends Error {
+    constructor();
+}
+export declare const findEmulator: (options?: FindOptions) => Emulator;
+export declare const findProtoDirectory: (env?: NodeJS.ProcessEnv, home?: string) => string;
+export declare const consoleTokenFile: (home?: string) => string;

package/dist/discovery.js

@@ -0,0 +1,164 @@
+// Finding a running Vega Virtual Device. The VVD is built on the Android
+// emulator, and a running emulator whose gRPC endpoint is on advertises itself
+// in a discovery file, `pid_<pid>.ini`, in a per-user directory. The file holds
+// the gRPC port and an access token; the token is read here and never printed.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { homedir, tmpdir, userInfo } from 'node:os';
+import { join } from 'node:path';
+const userName = () => {
+    try {
+        return userInfo().username;
+    }
+    catch {
+        return undefined; // no entry in the user database
+    }
+};
+const systemFacts = () => ({
+    uid: process.getuid?.(),
+    user: userName(),
+    tmp: tmpdir(),
+});
+// Where a running emulator leaves its discovery file. The macOS location was
+// measured with the VVD. The Linux ones are untested with a VVD: the runtime
+// directory, then the Android emulator's fallbacks.
+export const runningDirectories = (env = process.env, home = homedir(), system = systemFacts()) => {
+    const { uid, user, tmp } = system;
+    return [
+        ...new Set([
+            join(home, 'Library/Caches/TemporaryItems/avd/running'),
+            env.XDG_RUNTIME_DIR ? join(env.XDG_RUNTIME_DIR, 'avd/running') : '',
+            uid === undefined ? '' : `/run/user/${uid}/avd/running`,
+            user ? `/tmp/android-${user}/avd/running` : '',
+            user ? join(tmp, `android-${user}`, 'avd/running') : '',
+            join(home, '.android/avd/running'),
+        ].filter(Boolean)),
+    ];
+};
+// A discovery file is `key=value` lines.
+export const parseDiscovery = (text) => {
+    const fields = new Map();
+    for (const line of text.split(/\r?\n/)) {
+        const at = line.indexOf('=');
+        if (at > 0)
+            fields.set(line.slice(0, at).trim(), line.slice(at + 1).trim());
+    }
+    return fields;
+};
+const isAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        // EPERM: the process exists but belongs to someone else.
+        return error.code === 'EPERM';
+    }
+};
+const toPort = (value) => {
+    const port = Number(value);
+    return Number.isInteger(port) && port > 0 ? port : undefined;
+};
+// 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 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))
+                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 });
+        }
+    }
+    return found
+        .sort((a, b) => b.modified - a.modified)
+        .map(({ emulator }) => emulator);
+};
+export class NoDeviceError extends Error {
+    constructor() {
+        super('No running Vega Virtual Device with gRPC found. Start it (vega virtual-device start), ' +
+            'then turn gRPC on with `vvd enable-grpc`: it is off after every start of the device.');
+        this.name = 'NoDeviceError';
+    }
+}
+// The one emulator to drive: the given pid, or the newest.
+export const findEmulator = (options = {}) => {
+    const [emulator] = findEmulators(options);
+    if (!emulator)
+        throw new NoDeviceError();
+    return emulator;
+};
+// The emulator's gRPC API is described by emulator_controller.proto, which
+// ships inside the Vega SDK (it is AOSP code under Apache-2.0). It is loaded
+// from the developer's own SDK rather than copied here. VVD_PROTO_DIR
+// overrides the search.
+const inVersion = (versionDir) => join(versionDir, 'vvd/images/tv/vmtools/agent/lib');
+const hasProto = (dir) => existsSync(join(dir, 'emulator_controller.proto'));
+// The SDK's own record of where it lives and which version is the default.
+const configuredVersion = (home) => {
+    try {
+        const config = JSON.parse(readFileSync(join(home, 'vega/config.json'), 'utf8'));
+        const [channel, version] = (config.defaultVersion ?? '').split('@');
+        return config.sdkPath && channel && version
+            ? join(config.sdkPath, 'vega-sdk', channel, version)
+            : undefined;
+    }
+    catch {
+        return undefined; // no config, or an unreadable one: scan instead
+    }
+};
+// Directories only: a stray file, such as Finder's .DS_Store, is skipped.
+const subdirectories = (dir) => {
+    try {
+        return readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() ||
+            (entry.isSymbolicLink() &&
+                statSync(join(dir, entry.name), {
+                    throwIfNoEntry: false,
+                })?.isDirectory() === true))
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+};
+// Every installed version, newest first by number: 0.24 comes before 0.9.
+const installedVersions = (sdkRoot) => subdirectories(sdkRoot).flatMap((channel) => subdirectories(join(sdkRoot, channel))
+    .sort((a, b) => b.localeCompare(a, undefined, { numeric: true }))
+    .map((version) => join(sdkRoot, channel, version)));
+export const findProtoDirectory = (env = process.env, home = homedir()) => {
+    if (env.VVD_PROTO_DIR)
+        return env.VVD_PROTO_DIR;
+    const configured = configuredVersion(home);
+    if (configured && hasProto(inVersion(configured)))
+        return inVersion(configured);
+    const found = installedVersions(join(home, 'vega/sdk/vega-sdk'))
+        .map(inVersion)
+        .find(hasProto);
+    if (!found)
+        throw new Error('emulator_controller.proto not found in the Vega SDK. Install the SDK, or set VVD_PROTO_DIR ' +
+            'to the directory that holds it.');
+    return found;
+};
+// The emulator console's token, which authenticates `auth <token>`.
+export const consoleTokenFile = (home = homedir()) => join(home, '.emulator_console_auth_token');

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { CALL_TIMEOUT_MS, Device, TimeoutError } from './device.ts';
+export type { AudioPacket, CallOptions, ConnectOptions, Frame, PressOptions, } from './device.ts';
+export { findEmulator, findEmulators, findProtoDirectory, NoDeviceError, parseDiscovery, runningDirectories, } from './discovery.ts';
+export type { Emulator, FindOptions, SystemFacts } from './discovery.ts';
+export { enableGrpc, isConsolePort, runConsole } from './console.ts';
+export type { ConsoleOptions } from './console.ts';
+export { KEY_CODES, KeyError, parseKey, parseKeys, REMOTE_KEYS, } from './keys.ts';
+export type { Half, KeyStep } from './keys.ts';
+export { assembleAudio, audioWithin, hasFfmpeg, record } from './record.ts';
+export type { RecordOptions, RecordResult } from './record.ts';
+export { checkSafeArea, formatColour, parseColour } from './safearea.ts';
+export type { Rgb, SafeAreaOptions, SafeAreaReport } from './safearea.ts';
+export { encodePng } from './png.ts';
+export { createServer, MAX_PRESSES, serveStdio, videoPath } from './mcp.ts';
+export type { ServerOptions } from './mcp.ts';
+export { VERSION } from './version.ts';

package/dist/index.js

@@ -0,0 +1,10 @@
+// The library: everything the `vvd` command and the MCP server are built from.
+export { CALL_TIMEOUT_MS, Device, TimeoutError } from "./device.js";
+export { findEmulator, findEmulators, findProtoDirectory, NoDeviceError, parseDiscovery, runningDirectories, } from "./discovery.js";
+export { enableGrpc, isConsolePort, runConsole } from "./console.js";
+export { KEY_CODES, KeyError, parseKey, parseKeys, REMOTE_KEYS, } from "./keys.js";
+export { assembleAudio, audioWithin, hasFfmpeg, record } from "./record.js";
+export { checkSafeArea, formatColour, parseColour } from "./safearea.js";
+export { encodePng } from "./png.js";
+export { createServer, MAX_PRESSES, serveStdio, videoPath } from "./mcp.js";
+export { VERSION } from "./version.js";

package/dist/keys.d.ts

@@ -0,0 +1,13 @@
+export declare const KEY_CODES: Readonly<Record<string, number>>;
+export declare const REMOTE_KEYS: Readonly<Record<string, string>>;
+export type Half = 'press' | 'down' | 'up';
+export type KeyStep = {
+    name: string;
+    code: number;
+    half: Half;
+};
+export declare class KeyError extends Error {
+    constructor(message: string);
+}
+export declare const parseKey: (argument: string) => KeyStep[];
+export declare const parseKeys: (argumentsList: readonly string[]) => KeyStep[];

package/dist/keys.js

@@ -0,0 +1,85 @@
+// Remote keys by name. The VVD takes Linux evdev key codes through the
+// emulator's gRPC `sendKey`, the path its on-screen remote uses.
+//
+// Measured on the VVD (Vega SDK 0.24):
+// - OK is KEY_KPENTER, which is what the on-screen remote sends; apps receive
+//   it as `kpenter`, not the `select` that the remote documentation names.
+//   KEY_SELECT and KEY_OK are not declared by the emulator's virtual keyboard,
+//   so they never arrive.
+// - Back is KEY_BACK. KEY_ESC does not reach an app as Back over gRPC.
+export const KEY_CODES = {
+    KEY_ESC: 1,
+    KEY_ENTER: 28,
+    KEY_F1: 59,
+    KEY_F2: 60,
+    KEY_F3: 61,
+    KEY_F4: 62,
+    KEY_F5: 63,
+    KEY_KPENTER: 96,
+    KEY_UP: 103,
+    KEY_LEFT: 105,
+    KEY_RIGHT: 106,
+    KEY_DOWN: 108,
+    KEY_MENU: 139,
+    KEY_BACK: 158,
+    KEY_PLAYPAUSE: 164,
+    KEY_REWIND: 168,
+    KEY_HOMEPAGE: 172,
+    KEY_FASTFORWARD: 208,
+};
+// The remote's buttons, by the names a script would use.
+export const REMOTE_KEYS = {
+    up: 'KEY_UP',
+    down: 'KEY_DOWN',
+    left: 'KEY_LEFT',
+    right: 'KEY_RIGHT',
+    ok: 'KEY_KPENTER',
+    select: 'KEY_KPENTER',
+    back: 'KEY_BACK',
+    menu: 'KEY_MENU',
+    playpause: 'KEY_PLAYPAUSE',
+    rewind: 'KEY_REWIND',
+    fastforward: 'KEY_FASTFORWARD',
+};
+export class KeyError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'KeyError';
+    }
+}
+// Own properties only: `constructor` or `__proto__` must not pass for a key.
+const codeOf = (name) => {
+    const lower = name.toLowerCase();
+    if (Object.hasOwn(REMOTE_KEYS, lower))
+        return KEY_CODES[REMOTE_KEYS[lower]];
+    const upper = name.toUpperCase();
+    if (Object.hasOwn(KEY_CODES, upper))
+        return KEY_CODES[upper];
+    if (/^\d+$/.test(name)) {
+        const code = Number(name);
+        if (code > 0 && code < 0x300)
+            return code;
+    }
+    throw new KeyError(`unknown key "${name}": use ${Object.keys(REMOTE_KEYS).join(', ')}, a KEY_* name or an evdev code`);
+};
+// Parses one key argument:
+//   ok        press and release
+//   ok:down   only the press, to hold a key
+//   ok:up     only the release
+//   down*3    press three times
+export const parseKey = (argument) => {
+    const match = /^([^:*]+)(?::(down|up))?(?:\*(\d+))?$/i.exec(argument.trim());
+    if (!match)
+        throw new KeyError(`cannot read key "${argument}"`);
+    const [, name, half, times] = match;
+    const count = times === undefined ? 1 : Number(times);
+    if (count < 1 || count > 100)
+        throw new KeyError(`repeat count in "${argument}" must be 1 to 100`);
+    const step = {
+        name,
+        code: codeOf(name),
+        half: half?.toLowerCase() ?? 'press',
+    };
+    return Array.from({ length: count }, () => step);
+};
+export const parseKeys = (argumentsList) => argumentsList.flatMap(parseKey);

package/dist/mcp.d.ts

@@ -0,0 +1,10 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const MAX_PRESSES = 100;
+export type ServerOptions = {
+    pid?: number;
+    directories?: string[];
+    protoDirectory?: string;
+};
+export declare const videoPath: (file: string, overwrite?: boolean) => string;
+export declare const createServer: (options?: ServerOptions) => McpServer;
+export declare const serveStdio: (options?: ServerOptions) => Promise<void>;