@9b9387/android-stream-scrcpy 0.1.1 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 9b9387
+
+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

@@ -4,6 +4,8 @@ TypeScript scrcpy client library for Node.js and Electron. It starts `scrcpy-ser
 
 The bundled protocol implementation targets scrcpy `4.0`. Protocol code is versioned so future versions, such as `4.1`, can be added side by side without rewriting the backend or service layers.
 
+> Runtime note: the root package is Node-only. Use it from a Node.js process, an Electron main process, a Next.js Node runtime route/server, or another long-lived backend process. Do not import the root package from browser code, Next.js Client Components, or Edge Runtime handlers.
+
 ## Project Structure
 
 ```text
@@ -45,6 +47,10 @@ node-lib/
       scrcpy-stream-service.ts
       types.ts
       index.ts
+    snapshot/
+      ffmpeg-snapshot-cache.ts
+      types.ts
+      index.ts
     websocket/
       binary-packet.ts
       control-json.ts
@@ -59,18 +65,19 @@ node-lib/
 - `src/protocol/`: scrcpy wire protocol implementation. `core/` contains shared binary helpers and protocol interfaces; `registry.ts` selects a protocol adapter by version; `v4_0/` contains scrcpy 4.0 frame, control, device, codec, and server-option logic.
 - `src/backend/`: adbkit-only device integration. `adb/` wraps adbkit operations, `io/` contains socket reading utilities, `server/` builds and normalizes scrcpy server launch details, and `scrcpy-backend.ts` orchestrates the streaming connection.
 - `src/service/`: public stream service. It manages state, caches decoder config/session snapshots, and exposes `for await...of` media packet subscriptions.
+- `src/snapshot/`: optional Node-side screenshot cache. It pipes H.264 packets into ffmpeg and stores the latest JPEG frame.
 - `src/websocket/`: optional `ws` bridge for browser clients. It is exported from the `./websocket` subpath and is not part of the root API.
 - `examples/`: runnable examples kept outside the library build.
 
-## Install And Build
+## Install
+
+Install the package in your application:
 
 ```bash
-cd node-lib
-npm install
-npm run build
+npm install @9b9387/android-stream-scrcpy
 ```
 
-Core runtime dependency is only `@devicefarmer/adbkit`. The library does not call the `adb` system command directly.
+Core runtime dependency is `@devicefarmer/adbkit`. The library does not call the `adb` system command directly.
 
 If your application uses the optional WebSocket bridge, install `ws` in the application:
 
@@ -78,6 +85,25 @@ If your application uses the optional WebSocket bridge, install `ws` in the appl
 npm install ws
 ```
 
+If your application uses the optional screenshot cache, make sure `ffmpeg` is available on `PATH`, or pass `ffmpegPath` to `FfmpegSnapshotCache`.
+
+## Build From Source
+
+```bash
+cd node-lib
+npm install
+npm run build
+```
+
+## Package Entrypoints
+
+- `@9b9387/android-stream-scrcpy`: Node-only service/backend API.
+- `@9b9387/android-stream-scrcpy/protocol`: protocol adapters and types. This is the safest entrypoint for code that only needs scrcpy protocol constants, codecs, and message types.
+- `@9b9387/android-stream-scrcpy/websocket`: optional Node-only `ws` bridge.
+- `@9b9387/android-stream-scrcpy/snapshot`: optional Node-only ffmpeg screenshot cache.
+
+The package is ESM-only and requires Node.js 20 or newer.
+
 ## Run Examples
 
 Run the console stream demo:
@@ -225,22 +251,82 @@ const snapshots = new FfmpegSnapshotCache(service, {
   enabled: true,
   fps: 2,
   quality: 85,
+  // Optional robustness knobs (defaults shown):
+  drainTimeoutMs: 5000, // tear down ffmpeg if stdin stalls this long
+  killTimeoutMs: 2000, // SIGTERM grace before SIGKILL on stop()
+  staleTimeoutMs: 10000, // emit "stale" when no new frame for this long (0 = off)
+  maxStdoutBytes: 16 * 1024 * 1024, // cap on the JPEG reassembly buffer
 });
 
 await service.start();
-snapshots.start();
+snapshots.start(); // must be called after service.start()
 
+// Non-blocking read of the most recent frame (may be null before the first):
 const latest = snapshots.latest();
-if (latest) {
-  // latest.contentType === "image/jpeg"
-  // latest.data is a Buffer containing JPEG bytes.
+
+// Or wait up to N ms for the first/next frame instead of busy-polling 404s:
+try {
+  const shot = await snapshots.waitForFresh(3000);
+  // shot.contentType === "image/jpeg"; shot.data is a JPEG Buffer
+} catch {
+  // no frame within the timeout — surface a 503 / "warming up" to the client
 }
+
+// Observe a stalled stream (device asleep, encoder paused, etc.):
+snapshots.on("stale", ({ ageMs }) => {
+  console.warn(`no new snapshot for ${ageMs}ms`);
+});
 ```
 
 The first implementation supports H.264 input and JPEG output. The configured
 `fps` limits how often ffmpeg emits JPEG frames; ffmpeg still receives the
 continuous H.264 stream so inter-frame decoding remains correct.
 
+### Lifecycle & resource safety
+
+- `FfmpegSnapshotCache` listens to the service state: when the service stops or
+  errors, the ffmpeg process is killed automatically, so it never lingers as an
+  orphan across reconnects. You should still call `snapshots.stop()` explicitly
+  when you tear a session down yourself.
+- `waitForFresh()` resolves immediately if a frame is cached, otherwise it
+  resolves on the next frame or rejects after the timeout — use it in HTTP
+  handlers so a single request never hangs and clients never busy-poll.
+- The WebSocket bridge applies backpressure: a slow client's droppable video
+  frames are dropped (config/keyframe/session packets are preserved) once its
+  outbound buffer exceeds `maxBufferedBytes` (8MiB default), preventing
+  unbounded memory growth. Tune via `new ScrcpyWebSocketBridge(service, { maxBufferedBytes })`.
+
+For multi-device streaming and per-device screenshot HTTP routes, see
+[docs/multi-device-screenshot.md](./docs/multi-device-screenshot.md) (Web integration guide, 中文).
+
+## Next.js And Electron Usage
+
+### Next.js
+
+Use this package only from the server side of a self-hosted or long-lived Node.js runtime:
+
+```typescript
+export const runtime = "nodejs";
+
+import { ScrcpyStreamService } from "@9b9387/android-stream-scrcpy";
+```
+
+Do not import the root package from Client Components, browser bundles, Middleware,
+or Edge Runtime route handlers. The backend opens ADB sockets and long-lived media
+streams, so a custom Node.js server or separate local daemon is usually a better
+fit than a short-lived serverless function.
+
+### Electron
+
+Create and manage `ScrcpyStreamService` in the main process. Renderer processes
+should communicate with the main process through IPC or connect to the optional
+WebSocket bridge.
+
+When packaging Electron apps, make sure `assets/scrcpy-server-v4.0.jar` is copied
+as a runtime resource. If your packager moves or packs assets into an archive,
+pass an explicit `serverJarPath` to `ScrcpyStreamService`. If screenshot caching
+is enabled, also ship `ffmpeg` yourself or pass `ffmpegPath`.
+
 ## Protocol Versioning
 
 `protocolVersion` defaults to `"4.0"`:
@@ -266,6 +352,32 @@ npm run lint
 npm run typecheck
 npm test
 npm run build
+npm pack --dry-run
 ```
 
 End-to-end streaming requires a connected Android device. Unit tests cover protocol serialization/parsing, backend option normalization, subscriber queue behavior, and WebSocket packet encoding.
+
+## Publish
+
+Before publishing, make sure you are logged in to the npm account that owns the
+`@9b9387` scope:
+
+```bash
+npm whoami
+```
+
+Run the release checks and inspect the tarball contents:
+
+```bash
+npm run typecheck
+npm run test
+npm run lint
+npm run build
+npm pack --dry-run
+```
+
+Publish the public scoped package:
+
+```bash
+npm publish --access public
+```

package/dist/backend/io/buffered-stream-reader.d.ts

@@ -1,9 +1,10 @@
 import * as net from "node:net";
 export declare class BufferedStreamReader {
+    private readonly maxBufferBytes;
     private buffer;
     private waiters;
     private ended;
-    constructor(stream: net.Socket);
+    constructor(stream: net.Socket, maxBufferBytes?: number);
     readExact(n: number): Promise<Uint8Array>;
     private rejectAll;
     private checkWaiters;

package/dist/backend/io/buffered-stream-reader.js

@@ -1,11 +1,23 @@
 import { concatBytes } from "../../protocol/core/binary.js";
+// Safety cap on the reassembly buffer. A single scrcpy frame is well under
+// this; exceeding it means the stream is desynchronized or a bogus frame size
+// was read, so we fail fast instead of growing memory without bound.
+const DEFAULT_MAX_BUFFER_BYTES = 64 * 1024 * 1024;
 export class BufferedStreamReader {
+    maxBufferBytes;
     buffer = new Uint8Array(0);
     waiters = [];
     ended = false;
-    constructor(stream) {
+    constructor(stream, maxBufferBytes = DEFAULT_MAX_BUFFER_BYTES) {
+        this.maxBufferBytes = maxBufferBytes;
         stream.on("data", (chunk) => {
             this.buffer = concatBytes([this.buffer, chunk]);
+            if (this.buffer.byteLength > this.maxBufferBytes) {
+                this.ended = true;
+                this.rejectAll(new Error(`stream reader buffer exceeded ${this.maxBufferBytes} bytes; aborting`));
+                stream.destroy();
+                return;
+            }
             this.checkWaiters();
         });
         stream.on("error", (err) => {

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

@@ -12,6 +12,10 @@ export declare class FfmpegSnapshotCache extends EventEmitter {
     private readonly fps;
     private readonly quality;
     private readonly ffmpegPath;
+    private readonly drainTimeoutMs;
+    private readonly killTimeoutMs;
+    private readonly staleTimeoutMs;
+    private readonly maxStdoutBytes;
     private readonly spawnProcess;
     private process;
     private subscription;
@@ -19,16 +23,31 @@ export declare class FfmpegSnapshotCache extends EventEmitter {
     private stderrTail;
     private currentSnapshot;
     private running;
+    private staleTimer;
+    private staleEmitted;
+    private readonly onServiceState;
     constructor(service: ScrcpyStreamService, options?: SnapshotCacheOptions);
     start(): void;
     stop(): void;
     latest(): Snapshot | null;
+    /**
+     * Resolve with a snapshot, waiting up to `timeoutMs` for the first frame if
+     * the cache has not produced one yet. Lets HTTP handlers avoid both a busy
+     * 404-poll loop and an unbounded hang while ffmpeg warms up.
+     */
+    waitForFresh(timeoutMs?: number): Promise<Snapshot>;
     private buildFfmpegArgs;
     private pumpVideoPackets;
     private writePacket;
+    private waitForDrain;
     private handleStdout;
     private handleStderr;
     private handleProcessError;
+    private handlePumpError;
+    private startStaleWatchdog;
+    private bindServiceState;
+    private unbindServiceState;
     private cleanup;
+    private killProcess;
     private formatStderrTail;
 }

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

@@ -1,12 +1,16 @@
 import { spawn } from "node:child_process";
 import { EventEmitter } from "node:events";
-import { once } from "node:events";
-import { MediaKind, } from "../service/index.js";
+import { MediaKind, StreamState, } 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;
+const DEFAULT_DRAIN_TIMEOUT_MS = 5000;
+const DEFAULT_KILL_TIMEOUT_MS = 2000;
+const DEFAULT_STALE_TIMEOUT_MS = 10000;
+const DEFAULT_MAX_STDOUT_BYTES = 16 * 1024 * 1024;
+const STALE_CHECK_INTERVAL_MS = 1000;
 export function extractJpegFrames(buffer) {
     const frames = [];
     let offset = 0;
@@ -34,6 +38,10 @@ export class FfmpegSnapshotCache extends EventEmitter {
     fps;
     quality;
     ffmpegPath;
+    drainTimeoutMs;
+    killTimeoutMs;
+    staleTimeoutMs;
+    maxStdoutBytes;
     spawnProcess;
     process = null;
     subscription = null;
@@ -41,6 +49,9 @@ export class FfmpegSnapshotCache extends EventEmitter {
     stderrTail = "";
     currentSnapshot = null;
     running = false;
+    staleTimer = null;
+    staleEmitted = false;
+    onServiceState;
     constructor(service, options = {}) {
         super();
         this.service = service;
@@ -48,11 +59,23 @@ export class FfmpegSnapshotCache extends EventEmitter {
         this.fps = normalizeFps(options.fps ?? DEFAULT_SNAPSHOT_FPS);
         this.quality = normalizeJpegQuality(options.quality ?? DEFAULT_JPEG_QUALITY);
         this.ffmpegPath = options.ffmpegPath ?? "ffmpeg";
+        this.drainTimeoutMs = options.drainTimeoutMs ?? DEFAULT_DRAIN_TIMEOUT_MS;
+        this.killTimeoutMs = options.killTimeoutMs ?? DEFAULT_KILL_TIMEOUT_MS;
+        this.staleTimeoutMs = options.staleTimeoutMs ?? DEFAULT_STALE_TIMEOUT_MS;
+        this.maxStdoutBytes = options.maxStdoutBytes ?? DEFAULT_MAX_STDOUT_BYTES;
         this.spawnProcess =
             options.spawnProcess ??
                 ((command, args) => spawn(command, args, {
                     stdio: ["pipe", "pipe", "pipe"],
                 }));
+        this.onServiceState = (state) => {
+            // When the underlying stream stops or errors out, the subscription dries
+            // up but ffmpeg would otherwise linger as an orphan process. Tear it down
+            // so each device's ffmpeg lifetime is bounded by its service.
+            if (state === StreamState.STOPPED || state === StreamState.ERROR) {
+                this.stop();
+            }
+        };
     }
     start() {
         if (!this.enabled || this.running)
@@ -62,6 +85,8 @@ export class FfmpegSnapshotCache extends EventEmitter {
             throw new Error(`snapshot cache only supports h264 video, got ${videoCodec}`);
         }
         this.running = true;
+        this.staleEmitted = false;
+        this.bindServiceState();
         this.process = this.spawnProcess(this.ffmpegPath, this.buildFfmpegArgs());
         this.process.stdout.on("data", (chunk) => this.handleStdout(chunk));
         this.process.stderr.on("data", (chunk) => {
@@ -75,6 +100,7 @@ export class FfmpegSnapshotCache extends EventEmitter {
             }
         });
         this.subscription = this.service.subscribe();
+        this.startStaleWatchdog();
         void this.pumpVideoPackets();
     }
     stop() {
@@ -83,6 +109,40 @@ export class FfmpegSnapshotCache extends EventEmitter {
     latest() {
         return this.currentSnapshot;
     }
+    /**
+     * Resolve with a snapshot, waiting up to `timeoutMs` for the first frame if
+     * the cache has not produced one yet. Lets HTTP handlers avoid both a busy
+     * 404-poll loop and an unbounded hang while ffmpeg warms up.
+     */
+    waitForFresh(timeoutMs = 3000) {
+        if (this.currentSnapshot)
+            return Promise.resolve(this.currentSnapshot);
+        if (!this.running || !this.enabled) {
+            return Promise.reject(new Error("snapshot cache is not running"));
+        }
+        return new Promise((resolve, reject) => {
+            const onShot = (shot) => {
+                cleanup();
+                resolve(shot);
+            };
+            const onError = (e) => {
+                cleanup();
+                reject(e);
+            };
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new Error(`snapshot not available within ${timeoutMs}ms`));
+            }, timeoutMs);
+            timer.unref?.();
+            const cleanup = () => {
+                clearTimeout(timer);
+                this.removeListener("snapshot", onShot);
+                this.removeListener("error", onError);
+            };
+            this.once("snapshot", onShot);
+            this.once("error", onError);
+        });
+    }
     buildFfmpegArgs() {
         return [
             "-hide_banner",
@@ -124,17 +184,45 @@ export class FfmpegSnapshotCache extends EventEmitter {
             }
         }
         catch (e) {
-            if (this.running)
-                this.emit("error", e);
+            this.handlePumpError(e);
         }
     }
     async writePacket(proc, packet) {
         if (proc.stdin.write(packet.payload))
             return;
-        await once(proc.stdin, "drain");
+        await this.waitForDrain(proc);
+    }
+    waitForDrain(proc) {
+        return new Promise((resolve, reject) => {
+            const onDrain = () => {
+                cleanup();
+                resolve();
+            };
+            const onError = (e) => {
+                cleanup();
+                reject(e);
+            };
+            const timer = setTimeout(() => {
+                cleanup();
+                reject(new Error(`ffmpeg stdin did not drain within ${this.drainTimeoutMs}ms`));
+            }, this.drainTimeoutMs);
+            timer.unref?.();
+            const cleanup = () => {
+                clearTimeout(timer);
+                proc.stdin.removeListener("drain", onDrain);
+                proc.stdin.removeListener("error", onError);
+            };
+            proc.stdin.once("drain", onDrain);
+            proc.stdin.once("error", onError);
+        });
     }
     handleStdout(chunk) {
         this.stdoutBuffer = Buffer.concat([this.stdoutBuffer, chunk]);
+        // Guard against a corrupt/headerless ffmpeg stream where no EOI ever
+        // arrives: without a cap the remainder would grow without bound.
+        if (this.stdoutBuffer.byteLength > this.maxStdoutBytes) {
+            this.stdoutBuffer = this.stdoutBuffer.subarray(-this.maxStdoutBytes);
+        }
         const result = extractJpegFrames(this.stdoutBuffer);
         this.stdoutBuffer = result.remainder;
         for (const frame of result.frames) {
@@ -143,6 +231,7 @@ export class FfmpegSnapshotCache extends EventEmitter {
                 data: frame,
                 timestampMs: Date.now(),
             };
+            this.staleEmitted = false;
             this.emit("snapshot", this.currentSnapshot);
         }
     }
@@ -157,8 +246,44 @@ export class FfmpegSnapshotCache extends EventEmitter {
         this.cleanup({ clearSnapshot: true, killProcess: false });
         this.emit("error", e);
     }
+    handlePumpError(e) {
+        if (!this.running)
+            return;
+        // A pump failure (e.g. stdin stalled past the drain timeout) means ffmpeg
+        // is wedged; kill it so the cache can be restarted cleanly.
+        this.cleanup({ clearSnapshot: true, killProcess: true });
+        this.emit("error", e);
+    }
+    startStaleWatchdog() {
+        if (this.staleTimeoutMs <= 0)
+            return;
+        const timer = setInterval(() => {
+            if (!this.running || !this.currentSnapshot || this.staleEmitted)
+                return;
+            const age = Date.now() - this.currentSnapshot.timestampMs;
+            if (age > this.staleTimeoutMs) {
+                this.staleEmitted = true;
+                this.emit("stale", { ageMs: age, snapshot: this.currentSnapshot });
+            }
+        }, STALE_CHECK_INTERVAL_MS);
+        timer.unref?.();
+        this.staleTimer = timer;
+    }
+    bindServiceState() {
+        const emitter = this.service;
+        emitter.on?.("state", this.onServiceState);
+    }
+    unbindServiceState() {
+        const emitter = this.service;
+        emitter.removeListener?.("state", this.onServiceState);
+    }
     cleanup(options) {
         this.running = false;
+        this.unbindServiceState();
+        if (this.staleTimer) {
+            clearInterval(this.staleTimer);
+            this.staleTimer = null;
+        }
         this.subscription?.return?.();
         this.subscription = null;
         const proc = this.process;
@@ -166,13 +291,27 @@ export class FfmpegSnapshotCache extends EventEmitter {
         if (proc) {
             proc.stdin.end();
             if (options.killProcess)
-                proc.kill();
+                this.killProcess(proc);
         }
         this.stdoutBuffer = Buffer.alloc(0);
         this.stderrTail = "";
         if (options.clearSnapshot)
             this.currentSnapshot = null;
     }
+    killProcess(proc) {
+        proc.kill();
+        // Escalate to SIGKILL if ffmpeg ignores the polite signal.
+        const timer = setTimeout(() => {
+            try {
+                proc.kill("SIGKILL");
+            }
+            catch {
+                // process already gone
+            }
+        }, this.killTimeoutMs);
+        timer.unref?.();
+        proc.once("exit", () => clearTimeout(timer));
+    }
     formatStderrTail() {
         const tail = this.stderrTail.trim();
         return tail ? ` stderr=${tail}` : "";

package/dist/snapshot/types.d.ts

@@ -9,6 +9,27 @@ export interface SnapshotCacheOptions {
     fps?: number;
     quality?: number;
     ffmpegPath?: string;
+    /**
+     * Max time to wait for ffmpeg stdin to drain before treating the process as
+     * stalled and tearing it down. Defaults to 5000ms.
+     */
+    drainTimeoutMs?: number;
+    /**
+     * Grace period after SIGTERM before escalating to SIGKILL on stop. Defaults
+     * to 2000ms.
+     */
+    killTimeoutMs?: number;
+    /**
+     * Emit a `stale` event when the newest snapshot is older than this many ms
+     * (e.g. the device stopped producing frames). 0 disables. Defaults to
+     * 10000ms.
+     */
+    staleTimeoutMs?: number;
+    /**
+     * Cap on the internal ffmpeg stdout reassembly buffer, guarding against a
+     * corrupt stream with no JPEG end marker. Defaults to 16MiB.
+     */
+    maxStdoutBytes?: number;
     spawnProcess?: FfmpegProcessFactory;
 }
 export type FfmpegProcess = Pick<ChildProcessWithoutNullStreams, "stdin" | "stdout" | "stderr" | "kill" | "on" | "once">;

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

@@ -3,8 +3,10 @@ import { WebSocketBridgeOptions } from "./types.js";
 export declare class ScrcpyWebSocketBridge {
     private service;
     private wss;
+    private readonly maxBufferedBytes;
     constructor(service: ScrcpyStreamService, options?: WebSocketBridgeOptions);
     close(): void;
     private handleConnection;
+    private isDroppable;
     private createInitMessage;
 }

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

@@ -1,12 +1,17 @@
 import { WebSocket, WebSocketServer } from "ws";
+import { MediaKind } from "../service/types.js";
 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";
+const DEFAULT_MAX_BUFFERED_BYTES = 8 * 1024 * 1024;
 export class ScrcpyWebSocketBridge {
     service;
     wss;
+    maxBufferedBytes;
     constructor(service, options = {}) {
         this.service = service;
+        this.maxBufferedBytes =
+            options.maxBufferedBytes ?? DEFAULT_MAX_BUFFERED_BYTES;
         this.wss = new WebSocketServer({
             port: options.port,
             server: options.server,
@@ -38,6 +43,14 @@ export class ScrcpyWebSocketBridge {
             for await (const packet of subscription) {
                 if (ws.readyState !== WebSocket.OPEN)
                     break;
+                // Apply backpressure: when the client falls behind, drop droppable
+                // frames instead of letting ws buffer them without bound. Config,
+                // key frames and session packets are kept so the decoder can recover.
+                if (this.maxBufferedBytes > 0 &&
+                    ws.bufferedAmount > this.maxBufferedBytes &&
+                    this.isDroppable(packet)) {
+                    continue;
+                }
                 ws.send(serializeMediaPacket(packet));
             }
         }
@@ -45,6 +58,9 @@ export class ScrcpyWebSocketBridge {
             ws.close();
         }
     }
+    isDroppable(packet) {
+        return (packet.kind === MediaKind.VIDEO && !packet.config && !packet.keyFrame);
+    }
     createInitMessage() {
         const meta = this.service.currentMeta;
         return {

package/dist/websocket/types.d.ts

@@ -2,6 +2,12 @@ export interface WebSocketBridgeOptions {
     port?: number;
     server?: any;
     path?: string;
+    /**
+     * Drop media frames for a connection whose outbound buffer exceeds this many
+     * bytes. Protects the process from unbounded memory growth when a client is
+     * slower than the stream. 0 disables. Defaults to 8MiB.
+     */
+    maxBufferedBytes?: number;
 }
 export declare const WEBSOCKET_HEADER_SIZE = 16;
 export declare const WEBSOCKET_KIND_VIDEO = 1;

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "@9b9387/android-stream-scrcpy",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "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"
@@ -15,12 +21,18 @@
     "./snapshot": {
       "import": "./dist/snapshot/index.js",
       "types": "./dist/snapshot/index.d.ts"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist",
-    "assets"
+    "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",
@@ -28,9 +40,33 @@
     "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"
   },