@9b9387/android-stream-scrcpy 0.1.0

package/dist/service/types.js

@@ -0,0 +1,14 @@
+export var StreamState;
+(function (StreamState) {
+    StreamState["STOPPED"] = "stopped";
+    StreamState["STARTING"] = "starting";
+    StreamState["RUNNING"] = "running";
+    StreamState["STOPPING"] = "stopping";
+    StreamState["ERROR"] = "error";
+})(StreamState || (StreamState = {}));
+export var MediaKind;
+(function (MediaKind) {
+    MediaKind["VIDEO"] = "video";
+    MediaKind["AUDIO"] = "audio";
+    MediaKind["SESSION"] = "session";
+})(MediaKind || (MediaKind = {}));

package/dist/snapshot/ffmpeg-snapshot-cache.d.ts

@@ -0,0 +1,34 @@
+import { EventEmitter } from "node:events";
+import { ScrcpyStreamService } from "../service/index.js";
+import { Snapshot, SnapshotCacheOptions } from "./types.js";
+export interface JpegExtractionResult {
+    frames: Buffer<ArrayBufferLike>[];
+    remainder: Buffer<ArrayBufferLike>;
+}
+export declare function extractJpegFrames(buffer: Buffer<ArrayBufferLike>): JpegExtractionResult;
+export declare class FfmpegSnapshotCache extends EventEmitter {
+    private readonly service;
+    private readonly enabled;
+    private readonly fps;
+    private readonly quality;
+    private readonly ffmpegPath;
+    private readonly spawnProcess;
+    private process;
+    private subscription;
+    private stdoutBuffer;
+    private stderrTail;
+    private currentSnapshot;
+    private running;
+    constructor(service: ScrcpyStreamService, options?: SnapshotCacheOptions);
+    start(): void;
+    stop(): void;
+    latest(): Snapshot | null;
+    private buildFfmpegArgs;
+    private pumpVideoPackets;
+    private writePacket;
+    private handleStdout;
+    private handleStderr;
+    private handleProcessError;
+    private cleanup;
+    private formatStderrTail;
+}

package/dist/snapshot/ffmpeg-snapshot-cache.js

@@ -0,0 +1,195 @@
+import { spawn } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { once } from "node:events";
+import { MediaKind, } from "../service/index.js";
+import { VideoCodec } from "../protocol/index.js";
+const JPEG_SOI = Buffer.from([0xff, 0xd8]);
+const JPEG_EOI = Buffer.from([0xff, 0xd9]);
+const DEFAULT_SNAPSHOT_FPS = 2;
+const DEFAULT_JPEG_QUALITY = 85;
+export function extractJpegFrames(buffer) {
+    const frames = [];
+    let offset = 0;
+    while (offset < buffer.length) {
+        const start = buffer.indexOf(JPEG_SOI, offset);
+        if (start === -1) {
+            const keep = buffer[buffer.length - 1] === 0xff
+                ? buffer.subarray(-1)
+                : Buffer.alloc(0);
+            return { frames, remainder: keep };
+        }
+        const end = buffer.indexOf(JPEG_EOI, start + JPEG_SOI.length);
+        if (end === -1) {
+            return { frames, remainder: buffer.subarray(start) };
+        }
+        const frameEnd = end + JPEG_EOI.length;
+        frames.push(Buffer.from(buffer.subarray(start, frameEnd)));
+        offset = frameEnd;
+    }
+    return { frames, remainder: Buffer.alloc(0) };
+}
+export class FfmpegSnapshotCache extends EventEmitter {
+    service;
+    enabled;
+    fps;
+    quality;
+    ffmpegPath;
+    spawnProcess;
+    process = null;
+    subscription = null;
+    stdoutBuffer = Buffer.alloc(0);
+    stderrTail = "";
+    currentSnapshot = null;
+    running = false;
+    constructor(service, options = {}) {
+        super();
+        this.service = service;
+        this.enabled = options.enabled !== false;
+        this.fps = normalizeFps(options.fps ?? DEFAULT_SNAPSHOT_FPS);
+        this.quality = normalizeJpegQuality(options.quality ?? DEFAULT_JPEG_QUALITY);
+        this.ffmpegPath = options.ffmpegPath ?? "ffmpeg";
+        this.spawnProcess =
+            options.spawnProcess ??
+                ((command, args) => spawn(command, args, {
+                    stdio: ["pipe", "pipe", "pipe"],
+                }));
+    }
+    start() {
+        if (!this.enabled || this.running)
+            return;
+        const videoCodec = this.service.currentMeta?.videoCodec;
+        if (videoCodec && videoCodec !== VideoCodec.H264) {
+            throw new Error(`snapshot cache only supports h264 video, got ${videoCodec}`);
+        }
+        this.running = true;
+        this.process = this.spawnProcess(this.ffmpegPath, this.buildFfmpegArgs());
+        this.process.stdout.on("data", (chunk) => this.handleStdout(chunk));
+        this.process.stderr.on("data", (chunk) => {
+            this.handleStderr(chunk);
+        });
+        this.process.once("error", (e) => this.handleProcessError(e));
+        this.process.once("exit", (code, signal) => {
+            if (this.running) {
+                this.cleanup({ clearSnapshot: true, killProcess: false });
+                this.emit("error", new Error(`ffmpeg exited unexpectedly: code=${code} signal=${signal}${this.formatStderrTail()}`));
+            }
+        });
+        this.subscription = this.service.subscribe();
+        void this.pumpVideoPackets();
+    }
+    stop() {
+        this.cleanup({ clearSnapshot: false, killProcess: true });
+    }
+    latest() {
+        return this.currentSnapshot;
+    }
+    buildFfmpegArgs() {
+        return [
+            "-hide_banner",
+            "-loglevel",
+            "error",
+            "-f",
+            "h264",
+            "-i",
+            "pipe:0",
+            "-vf",
+            [
+                "setparams=colorspace=bt709:color_primaries=bt709:color_trc=bt709",
+                `fps=${this.fps}`,
+                "format=yuvj420p",
+            ].join(","),
+            "-q:v",
+            String(jpegQualityToMjpegQscale(this.quality)),
+            "-f",
+            "image2pipe",
+            "-vcodec",
+            "mjpeg",
+            "pipe:1",
+        ];
+    }
+    async pumpVideoPackets() {
+        const subscription = this.subscription;
+        const proc = this.process;
+        if (!subscription || !proc)
+            return;
+        try {
+            for await (const packet of subscription) {
+                if (!this.running)
+                    break;
+                if (packet.kind !== MediaKind.VIDEO ||
+                    packet.payload.byteLength === 0) {
+                    continue;
+                }
+                await this.writePacket(proc, packet);
+            }
+        }
+        catch (e) {
+            if (this.running)
+                this.emit("error", e);
+        }
+    }
+    async writePacket(proc, packet) {
+        if (proc.stdin.write(packet.payload))
+            return;
+        await once(proc.stdin, "drain");
+    }
+    handleStdout(chunk) {
+        this.stdoutBuffer = Buffer.concat([this.stdoutBuffer, chunk]);
+        const result = extractJpegFrames(this.stdoutBuffer);
+        this.stdoutBuffer = result.remainder;
+        for (const frame of result.frames) {
+            this.currentSnapshot = {
+                contentType: "image/jpeg",
+                data: frame,
+                timestampMs: Date.now(),
+            };
+            this.emit("snapshot", this.currentSnapshot);
+        }
+    }
+    handleStderr(chunk) {
+        const text = chunk.toString("utf8");
+        this.stderrTail = (this.stderrTail + text).slice(-4000);
+        this.emit("ffmpegLog", text);
+    }
+    handleProcessError(e) {
+        if (!this.running)
+            return;
+        this.cleanup({ clearSnapshot: true, killProcess: false });
+        this.emit("error", e);
+    }
+    cleanup(options) {
+        this.running = false;
+        this.subscription?.return?.();
+        this.subscription = null;
+        const proc = this.process;
+        this.process = null;
+        if (proc) {
+            proc.stdin.end();
+            if (options.killProcess)
+                proc.kill();
+        }
+        this.stdoutBuffer = Buffer.alloc(0);
+        this.stderrTail = "";
+        if (options.clearSnapshot)
+            this.currentSnapshot = null;
+    }
+    formatStderrTail() {
+        const tail = this.stderrTail.trim();
+        return tail ? ` stderr=${tail}` : "";
+    }
+}
+function normalizeFps(value) {
+    if (!Number.isFinite(value) || value <= 0 || value > 60) {
+        throw new Error(`snapshot fps must be a finite number between 0 and 60`);
+    }
+    return value;
+}
+function normalizeJpegQuality(value) {
+    if (!Number.isFinite(value) || value < 1 || value > 100) {
+        throw new Error(`snapshot JPEG quality must be a finite number from 1 to 100`);
+    }
+    return Math.round(value);
+}
+function jpegQualityToMjpegQscale(quality) {
+    return Math.max(2, Math.min(31, Math.round(31 - (quality / 100) * 29)));
+}

package/dist/snapshot/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./ffmpeg-snapshot-cache.js";
+export * from "./types.js";

package/dist/snapshot/index.js

@@ -0,0 +1,2 @@
+export * from "./ffmpeg-snapshot-cache.js";
+export * from "./types.js";

package/dist/snapshot/types.d.ts

@@ -0,0 +1,15 @@
+import { ChildProcessWithoutNullStreams } from "node:child_process";
+export interface Snapshot {
+    contentType: "image/jpeg";
+    data: Buffer<ArrayBufferLike>;
+    timestampMs: number;
+}
+export interface SnapshotCacheOptions {
+    enabled?: boolean;
+    fps?: number;
+    quality?: number;
+    ffmpegPath?: string;
+    spawnProcess?: FfmpegProcessFactory;
+}
+export type FfmpegProcess = Pick<ChildProcessWithoutNullStreams, "stdin" | "stdout" | "stderr" | "kill" | "on" | "once">;
+export type FfmpegProcessFactory = (command: string, args: string[]) => FfmpegProcess;

package/dist/snapshot/types.js

@@ -0,0 +1 @@
+export {};

package/dist/websocket/binary-packet.d.ts

@@ -0,0 +1,2 @@
+import { MediaPacket } from "../service/types.js";
+export declare function serializeMediaPacket(packet: MediaPacket): Uint8Array;

package/dist/websocket/binary-packet.js

@@ -0,0 +1,33 @@
+import { MediaKind } from "../service/types.js";
+import { WEBSOCKET_HEADER_SIZE, WEBSOCKET_KIND_AUDIO, WEBSOCKET_KIND_SESSION, WEBSOCKET_KIND_VIDEO, } from "./types.js";
+export function serializeMediaPacket(packet) {
+    let kind = WEBSOCKET_KIND_VIDEO;
+    let flags = 0;
+    let pts = packet.ptsUs;
+    let size = packet.payload.length;
+    let payload = packet.payload;
+    if (packet.config)
+        flags |= 0x01;
+    if (packet.keyFrame)
+        flags |= 0x02;
+    if (packet.kind === MediaKind.AUDIO) {
+        kind = WEBSOCKET_KIND_AUDIO;
+    }
+    else if (packet.kind === MediaKind.SESSION) {
+        kind = WEBSOCKET_KIND_SESSION;
+        size = 0;
+        payload = new Uint8Array(0);
+        // The browser bridge uses the 64-bit timestamp slot for session dimensions:
+        // high 32 bits = width, low 32 bits = height.
+        pts = (BigInt(packet.width ?? 0) << 32n) | BigInt(packet.height ?? 0);
+    }
+    const buf = new Uint8Array(WEBSOCKET_HEADER_SIZE + payload.byteLength);
+    const view = new DataView(buf.buffer);
+    view.setUint8(0, kind);
+    view.setUint8(1, flags);
+    view.setUint16(2, 0);
+    view.setUint32(4, size);
+    view.setBigUint64(8, pts);
+    buf.set(payload, WEBSOCKET_HEADER_SIZE);
+    return buf;
+}

package/dist/websocket/control-json.d.ts

@@ -0,0 +1,2 @@
+import { ControlMessage } from "../protocol/index.js";
+export declare function parseControlJson(payload: any): ControlMessage | null;

package/dist/websocket/control-json.js

@@ -0,0 +1,129 @@
+import { ACTION_DOWN, ACTION_MOVE, ACTION_UP, BUTTON_PRIMARY, ControlMessageType, KEY_ACTION_DOWN, KEY_ACTION_UP, POINTER_ID_GENERIC_FINGER, POINTER_ID_MOUSE, } from "../protocol/index.js";
+export function parseControlJson(payload) {
+    const type = (payload.type || "").toLowerCase();
+    switch (type) {
+        case "touch": {
+            const action = parseTouchAction(payload.action);
+            return {
+                type: ControlMessageType.INJECT_TOUCH_EVENT,
+                action,
+                pointerId: parsePointerId(payload.pointerId),
+                x: payload.x,
+                y: payload.y,
+                screenWidth: payload.screenWidth,
+                screenHeight: payload.screenHeight,
+                pressure: payload.pressure ?? (action !== ACTION_UP ? 1.0 : 0.0),
+                actionButton: payload.actionButton ??
+                    (action === ACTION_DOWN || action === ACTION_UP ? BUTTON_PRIMARY : 0),
+                buttons: payload.buttons ?? (action !== ACTION_UP ? BUTTON_PRIMARY : 0),
+            };
+        }
+        case "scroll":
+            return {
+                type: ControlMessageType.INJECT_SCROLL_EVENT,
+                x: payload.x,
+                y: payload.y,
+                screenWidth: payload.screenWidth,
+                screenHeight: payload.screenHeight,
+                hScroll: payload.hScroll ?? 0.0,
+                vScroll: payload.vScroll ?? 0.0,
+                buttons: payload.buttons ?? 0,
+            };
+        case "key":
+            return {
+                type: ControlMessageType.INJECT_KEYCODE,
+                action: parseKeyAction(payload.action),
+                keycode: payload.keycode,
+                repeat: payload.repeat ?? 0,
+                metaState: payload.metaState ?? 0,
+            };
+        case "text":
+            return { type: ControlMessageType.INJECT_TEXT, text: payload.text ?? "" };
+        case "back":
+            return {
+                type: ControlMessageType.BACK_OR_SCREEN_ON,
+                action: parseKeyAction(payload.action),
+            };
+        case "home":
+            return {
+                type: ControlMessageType.INJECT_KEYCODE,
+                action: parseKeyAction(payload.action),
+                keycode: 3,
+            };
+        case "app_switch":
+            return {
+                type: ControlMessageType.INJECT_KEYCODE,
+                action: parseKeyAction(payload.action),
+                keycode: 187,
+            };
+        case "power":
+            return {
+                type: ControlMessageType.INJECT_KEYCODE,
+                action: parseKeyAction(payload.action),
+                keycode: 26,
+            };
+        case "expand_notifications":
+            return { type: ControlMessageType.EXPAND_NOTIFICATION_PANEL };
+        case "expand_settings":
+            return { type: ControlMessageType.EXPAND_SETTINGS_PANEL };
+        case "collapse_panels":
+            return { type: ControlMessageType.COLLAPSE_PANELS };
+        case "rotate":
+            return { type: ControlMessageType.ROTATE_DEVICE };
+        case "reset_video":
+            return { type: ControlMessageType.RESET_VIDEO };
+        case "set_clipboard":
+            return {
+                type: ControlMessageType.SET_CLIPBOARD,
+                sequence: BigInt(payload.sequence ?? 0),
+                text: payload.text ?? "",
+                paste: !!payload.paste,
+            };
+        case "get_clipboard":
+            return {
+                type: ControlMessageType.GET_CLIPBOARD,
+                copyKey: payload.copyKey ?? 0,
+            };
+        case "set_display_power":
+            return { type: ControlMessageType.SET_DISPLAY_POWER, on: !!payload.on };
+        case "start_app":
+            return { type: ControlMessageType.START_APP, name: payload.name ?? "" };
+        default:
+            return null;
+    }
+}
+function parseTouchAction(value) {
+    if (typeof value === "number")
+        return value;
+    const text = String(value).toLowerCase();
+    if (text === "down" || text === "pointer_down")
+        return ACTION_DOWN;
+    if (text === "up" || text === "pointer_up")
+        return ACTION_UP;
+    if (text === "move")
+        return ACTION_MOVE;
+    throw new Error(`unknown touch action: ${value}`);
+}
+function parseKeyAction(value) {
+    if (typeof value === "number")
+        return value;
+    const text = String(value).toLowerCase();
+    if (text === "down")
+        return KEY_ACTION_DOWN;
+    if (text === "up")
+        return KEY_ACTION_UP;
+    throw new Error(`unknown key action: ${value}`);
+}
+function parsePointerId(value) {
+    if (value === null || value === undefined)
+        return POINTER_ID_GENERIC_FINGER;
+    if (typeof value === "string") {
+        const text = value.toLowerCase();
+        if (text === "mouse")
+            return POINTER_ID_MOUSE;
+        if (text === "finger")
+            return POINTER_ID_GENERIC_FINGER;
+        return BigInt(text);
+    }
+    return BigInt(value);
+}

package/dist/websocket/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./scrcpy-websocket-bridge.js";
+export * from "./binary-packet.js";
+export * from "./control-json.js";
+export * from "./types.js";

package/dist/websocket/index.js

@@ -0,0 +1,4 @@
+export * from "./scrcpy-websocket-bridge.js";
+export * from "./binary-packet.js";
+export * from "./control-json.js";
+export * from "./types.js";

package/dist/websocket/scrcpy-websocket-bridge.d.ts

@@ -0,0 +1,10 @@
+import { ScrcpyStreamService } from "../service/scrcpy-stream-service.js";
+import { WebSocketBridgeOptions } from "./types.js";
+export declare class ScrcpyWebSocketBridge {
+    private service;
+    private wss;
+    constructor(service: ScrcpyStreamService, options?: WebSocketBridgeOptions);
+    close(): void;
+    private handleConnection;
+    private createInitMessage;
+}

package/dist/websocket/scrcpy-websocket-bridge.js

@@ -0,0 +1,75 @@
+import { WebSocket, WebSocketServer } from "ws";
+import { serializeMediaPacket } from "./binary-packet.js";
+import { parseControlJson } from "./control-json.js";
+import { WEBSOCKET_HEADER_SIZE, WEBSOCKET_KIND_AUDIO, WEBSOCKET_KIND_SESSION, WEBSOCKET_KIND_VIDEO, } from "./types.js";
+export class ScrcpyWebSocketBridge {
+    service;
+    wss;
+    constructor(service, options = {}) {
+        this.service = service;
+        this.wss = new WebSocketServer({
+            port: options.port,
+            server: options.server,
+            path: options.path || "/ws/scrcpy",
+        });
+        this.wss.on("connection", (ws) => this.handleConnection(ws));
+    }
+    close() {
+        this.wss.close();
+    }
+    async handleConnection(ws) {
+        ws.send(JSON.stringify(this.createInitMessage()));
+        const subscription = this.service.subscribe();
+        ws.on("message", (data) => {
+            try {
+                const payload = JSON.parse(data.toString());
+                const msg = parseControlJson(payload);
+                if (msg)
+                    this.service.sendControlMessage(msg);
+            }
+            catch (e) {
+                ws.send(JSON.stringify({ type: "error", message: e.message }));
+            }
+        });
+        ws.on("close", () => {
+            subscription.return?.();
+        });
+        try {
+            for await (const packet of subscription) {
+                if (ws.readyState !== WebSocket.OPEN)
+                    break;
+                ws.send(serializeMediaPacket(packet));
+            }
+        }
+        catch {
+            ws.close();
+        }
+    }
+    createInitMessage() {
+        const meta = this.service.currentMeta;
+        return {
+            type: "init",
+            state: this.service.currentState,
+            device: {
+                name: meta?.deviceName ?? null,
+                width: meta?.width ?? null,
+                height: meta?.height ?? null,
+                video_codec: meta?.videoCodec ?? null,
+                audio_codec: meta?.audioCodec ?? null,
+            },
+            binary_header: {
+                size: WEBSOCKET_HEADER_SIZE,
+                kinds: {
+                    video: WEBSOCKET_KIND_VIDEO,
+                    audio: WEBSOCKET_KIND_AUDIO,
+                    session: WEBSOCKET_KIND_SESSION,
+                },
+                flags: {
+                    config: 0x01,
+                    key_frame: 0x02,
+                    client_resized: 0x04,
+                },
+            },
+        };
+    }
+}

package/dist/websocket/types.d.ts

@@ -0,0 +1,9 @@
+export interface WebSocketBridgeOptions {
+    port?: number;
+    server?: any;
+    path?: string;
+}
+export declare const WEBSOCKET_HEADER_SIZE = 16;
+export declare const WEBSOCKET_KIND_VIDEO = 1;
+export declare const WEBSOCKET_KIND_AUDIO = 2;
+export declare const WEBSOCKET_KIND_SESSION = 3;

package/dist/websocket/types.js

@@ -0,0 +1,4 @@
+export const WEBSOCKET_HEADER_SIZE = 16;
+export const WEBSOCKET_KIND_VIDEO = 1;
+export const WEBSOCKET_KIND_AUDIO = 2;
+export const WEBSOCKET_KIND_SESSION = 3;

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@9b9387/android-stream-scrcpy",
+  "version": "0.1.0",
+  "description": "Versioned scrcpy protocol client for Node.js/Electron",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./protocol": {
+      "import": "./dist/protocol/index.js",
+      "types": "./dist/protocol/index.d.ts"
+    },
+    "./websocket": {
+      "import": "./dist/websocket/index.js",
+      "types": "./dist/websocket/index.d.ts"
+    },
+    "./snapshot": {
+      "import": "./dist/snapshot/index.js",
+      "types": "./dist/snapshot/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "prettier --check .",
+    "format": "prettier --write .",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run typecheck && npm run test && npm run lint && npm run build",
+    "example:demo": "npm run build && node --loader ts-node/esm examples/demo.ts",
+    "example:server": "npm run build && node --loader ts-node/esm examples/server.ts"
+  },
+  "keywords": [
+    "scrcpy",
+    "android",
+    "adb",
+    "streaming",
+    "electron",
+    "nextjs",
+    "typescript"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/9b9387/android-stream.git",
+    "directory": "node-lib"
+  },
+  "bugs": {
+    "url": "https://github.com/9b9387/android-stream/issues"
+  },
+  "homepage": "https://github.com/9b9387/android-stream/tree/main/node-lib#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@devicefarmer/adbkit": "^3.2.3"
+  },
+  "peerDependencies": {
+    "ws": "^8.16.0"
+  },
+  "peerDependenciesMeta": {
+    "ws": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@types/ws": "^8.18.1",
+    "prettier": "^3.8.3",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.6",
+    "ws": "^8.20.1"
+  }
+}