@houwert/conductor 0.25.0 → 0.27.0

package/dist/daemon/h264-annexb.js

@@ -0,0 +1,264 @@
+"use strict";
+/**
+ * H.264 Annex B streaming parser (daemon side).
+ *
+ * Splits the raw Annex B byte stream from the capture backend into access units,
+ * extracts SPS/PPS to build the stream config, and preserves each access unit
+ * **in Annex B form** (start codes intact) for forwarding to subscribers — the
+ * wire contract is "config + a sequence of Annex B access units, keyframe-led".
+ *
+ * Ported from Argus's electron/services/simulator/h264-parser.ts; the SPS
+ * bit-reader is identical, but access units are emitted as Annex B rather than
+ * converted to AVCC length-prefix (that conversion is left to WebCodecs clients).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.H264AnnexBParser = void 0;
+const NAL_SLICE = 1;
+const NAL_IDR = 5;
+const NAL_SPS = 7;
+const NAL_PPS = 8;
+// ── Exp-Golomb reader (minimal, for SPS parsing) ────────────────────────────
+class ExpGolombReader {
+    constructor(data) {
+        this.data = data;
+        this.byteOffset = 0;
+        this.bitOffset = 0;
+    }
+    readBit() {
+        if (this.byteOffset >= this.data.length)
+            return 0;
+        const bit = (this.data[this.byteOffset] >> (7 - this.bitOffset)) & 1;
+        this.bitOffset++;
+        if (this.bitOffset === 8) {
+            this.bitOffset = 0;
+            this.byteOffset++;
+        }
+        return bit;
+    }
+    readBits(n) {
+        let val = 0;
+        for (let i = 0; i < n; i++)
+            val = (val << 1) | this.readBit();
+        return val;
+    }
+    readUE() {
+        let zeros = 0;
+        while (this.readBit() === 0 && zeros < 31)
+            zeros++;
+        if (zeros === 0)
+            return 0;
+        return (1 << zeros) - 1 + this.readBits(zeros);
+    }
+    readSE() {
+        const val = this.readUE();
+        return val % 2 === 0 ? -(val >> 1) : (val + 1) >> 1;
+    }
+}
+/** Parse the SPS fields needed for config. `body` is the NAL after the header byte. */
+function parseSps(body) {
+    const r = new ExpGolombReader(body);
+    const profileIdc = r.readBits(8);
+    const constraintFlags = r.readBits(8);
+    const levelIdc = r.readBits(8);
+    r.readUE(); // seq_parameter_set_id
+    if ([100, 110, 122, 244, 44, 83, 86, 118, 128, 138, 139, 134].includes(profileIdc)) {
+        const chromaFormatIdc = r.readUE();
+        if (chromaFormatIdc === 3)
+            r.readBits(1);
+        r.readUE(); // bit_depth_luma_minus8
+        r.readUE(); // bit_depth_chroma_minus8
+        r.readBits(1); // qpprime_y_zero_transform_bypass_flag
+        if (r.readBits(1)) {
+            const count = chromaFormatIdc !== 3 ? 8 : 12;
+            for (let i = 0; i < count; i++) {
+                if (r.readBits(1)) {
+                    const size = i < 6 ? 16 : 64;
+                    let lastScale = 8;
+                    let nextScale = 8;
+                    for (let j = 0; j < size; j++) {
+                        if (nextScale !== 0)
+                            nextScale = (lastScale + r.readSE() + 256) % 256;
+                        lastScale = nextScale === 0 ? lastScale : nextScale;
+                    }
+                }
+            }
+        }
+    }
+    r.readUE(); // log2_max_frame_num_minus4
+    const picOrderCntType = r.readUE();
+    if (picOrderCntType === 0) {
+        r.readUE();
+    }
+    else if (picOrderCntType === 1) {
+        r.readBits(1);
+        r.readSE();
+        r.readSE();
+        const n = r.readUE();
+        for (let i = 0; i < n; i++)
+            r.readSE();
+    }
+    r.readUE(); // max_num_ref_frames
+    r.readBits(1); // gaps_in_frame_num_value_allowed_flag
+    const picWidthInMbsMinus1 = r.readUE();
+    const picHeightInMapUnitsMinus1 = r.readUE();
+    const frameMbsOnlyFlag = r.readBits(1);
+    let width = (picWidthInMbsMinus1 + 1) * 16;
+    let height = (2 - frameMbsOnlyFlag) * (picHeightInMapUnitsMinus1 + 1) * 16;
+    if (!frameMbsOnlyFlag)
+        r.readBits(1);
+    r.readBits(1); // direct_8x8_inference_flag
+    if (r.readBits(1)) {
+        // frame_cropping_flag — 4:2:0 crop units are 2px
+        const cl = r.readUE();
+        const cr = r.readUE();
+        const ct = r.readUE();
+        const cb = r.readUE();
+        width -= (cl + cr) * 2;
+        height -= (ct + cb) * 2;
+    }
+    return { profileIdc, constraintFlags, levelIdc, width, height };
+}
+function buildCodecString(info) {
+    const pp = info.profileIdc.toString(16).padStart(2, '0');
+    const cc = info.constraintFlags.toString(16).padStart(2, '0');
+    const ll = info.levelIdc.toString(16).padStart(2, '0');
+    return `avc1.${pp}${cc}${ll}`;
+}
+/** AVCDecoderConfigurationRecord from raw SPS/PPS NAL bodies (with NAL header byte). */
+function buildAvcC(sps, pps) {
+    const buf = Buffer.alloc(11 + sps.length + pps.length);
+    buf[0] = 1; // configurationVersion
+    buf[1] = sps[1]; // profile
+    buf[2] = sps[2]; // compatibility
+    buf[3] = sps[3]; // level
+    buf[4] = 0xff; // lengthSizeMinusOne = 3
+    buf[5] = 0xe1; // numOfSPS = 1
+    buf.writeUInt16BE(sps.length, 6);
+    Buffer.from(sps).copy(buf, 8);
+    const off = 8 + sps.length;
+    buf[off] = 1; // numOfPPS
+    buf.writeUInt16BE(pps.length, off + 1);
+    Buffer.from(pps).copy(buf, off + 3);
+    return buf;
+}
+/** Find the next Annex B start code (00 00 01 or 00 00 00 01). */
+function findStartCode(buf, offset) {
+    for (let i = offset; i < buf.length - 2; i++) {
+        if (buf[i] === 0 && buf[i + 1] === 0) {
+            if (buf[i + 2] === 1)
+                return { index: i, length: 3 };
+            if (buf[i + 2] === 0 && i + 3 < buf.length && buf[i + 3] === 1)
+                return { index: i, length: 4 };
+        }
+    }
+    return null;
+}
+/**
+ * Streaming Annex B parser. Feed raw capture bytes with push(); emits config
+ * once SPS+PPS are seen, then one Annex B access unit per VCL frame.
+ */
+class H264AnnexBParser {
+    constructor(cbs, fps = 30) {
+        this.cbs = cbs;
+        this.buffer = Buffer.alloc(0);
+        this.sps = null;
+        this.pps = null;
+        this.config = null;
+        // NALs (each Annex-B, start-code prefixed) buffered for the current access unit.
+        this.au = [];
+        this.auIsKey = false;
+        this.fps = fps;
+    }
+    reset() {
+        this.buffer = Buffer.alloc(0);
+        this.sps = null;
+        this.pps = null;
+        this.config = null;
+        this.au = [];
+        this.auIsKey = false;
+    }
+    push(chunk) {
+        this.buffer = this.buffer.length === 0 ? chunk : Buffer.concat([this.buffer, chunk]);
+        this.processBuffer();
+    }
+    processBuffer() {
+        let sc = findStartCode(this.buffer, 0);
+        if (!sc)
+            return;
+        while (true) {
+            const next = findStartCode(this.buffer, sc.index + sc.length);
+            if (!next)
+                break; // incomplete NAL — wait for more data
+            const nal = this.buffer.subarray(sc.index + sc.length, next.index);
+            // Keep the whole unit including start code so subscribers get Annex B.
+            const withStartCode = this.buffer.subarray(sc.index, next.index);
+            this.processNal(nal, withStartCode);
+            sc = next;
+        }
+        // Retain the trailing (unterminated) NAL for the next push.
+        if (sc.index > 0)
+            this.buffer = Buffer.from(this.buffer.subarray(sc.index));
+        // Guard against unbounded growth on a stuck stream.
+        if (this.buffer.length > 4 * 1024 * 1024) {
+            this.buffer = Buffer.from(this.buffer.subarray(-1024 * 1024));
+        }
+    }
+    processNal(nal, withStartCode) {
+        if (nal.length === 0)
+            return;
+        const nalType = nal[0] & 0x1f;
+        if (nalType === NAL_SPS) {
+            this.sps = Buffer.from(nal);
+            this.emitConfigIfReady();
+            return;
+        }
+        if (nalType === NAL_PPS) {
+            this.pps = Buffer.from(nal);
+            this.emitConfigIfReady();
+            return;
+        }
+        if (nalType === NAL_IDR || nalType === NAL_SLICE) {
+            // Flush any previously buffered AU before starting this VCL frame.
+            if (this.au.length > 0)
+                this.emitAccessUnit();
+            this.auIsKey = nalType === NAL_IDR;
+            this.au.push(Buffer.from(withStartCode));
+            this.emitAccessUnit();
+            return;
+        }
+        // SEI / AUD / other — attach to the current access unit.
+        this.au.push(Buffer.from(withStartCode));
+    }
+    emitAccessUnit() {
+        if (this.au.length === 0)
+            return;
+        if (!this.config) {
+            // Can't decode without config yet — drop until SPS/PPS arrive.
+            this.au = [];
+            this.auIsKey = false;
+            return;
+        }
+        const data = this.au.length === 1 ? this.au[0] : Buffer.concat(this.au);
+        this.cbs.onFrame(data, this.auIsKey);
+        this.au = [];
+        this.auIsKey = false;
+    }
+    emitConfigIfReady() {
+        if (this.config || !this.sps || !this.pps)
+            return;
+        const info = parseSps(this.sps.subarray(1));
+        this.config = {
+            codec: 'h264',
+            width: info.width,
+            height: info.height,
+            rotation: 0,
+            fps: this.fps,
+            codecString: buildCodecString(info),
+            sps: this.sps,
+            pps: this.pps,
+            avcC: buildAvcC(this.sps, this.pps),
+        };
+        this.cbs.onConfig(this.config);
+    }
+}
+exports.H264AnnexBParser = H264AnnexBParser;

package/dist/daemon/server.js

@@ -28,6 +28,8 @@ const input_server_js_1 = require("./input-server.js");
 const input_router_js_1 = require("./input-router.js");
 const input_backends_js_1 = require("./input-backends.js");
 const ios_hid_js_1 = require("../drivers/ios-hid.js");
+const video_server_js_1 = require("./video-server.js");
+const video_source_js_1 = require("./video-source.js");
 const log_collector_js_1 = require("./log-collector.js");
 const session_js_1 = require("../session.js");
 const sessionName = process.argv[2] ?? 'default';
@@ -86,6 +88,8 @@ let logCollector = null;
 let inputServer = null;
 let inputPort = null;
 let hidClient = null;
+let videoServer = null;
+let streamPort = null;
 /**
  * Start the streaming-input WebSocket server for the current device, once its
  * driver is up. iOS/tvOS/Android only — web keeps its per-event REST path.
@@ -139,6 +143,33 @@ async function startInputServerForPlatform() {
     inputPort = port;
     dlog(`input server listening on ${port}`);
 }
+/**
+ * Start the streaming-video WebSocket server for the current device, once its
+ * driver is up. iOS/tvOS only for now (host-side SimulatorKit capture); the
+ * binary must be built/downloaded. Capture is lazy: it doesn't spawn until the
+ * first subscriber connects, and stops when the last one leaves.
+ */
+async function startVideoServerForPlatform() {
+    if (videoServer)
+        return;
+    if (driverPlatform !== 'ios' && driverPlatform !== 'tvos')
+        return;
+    const binary = await (0, bootstrap_js_1.getCaptureBinaryPath)();
+    if (!binary) {
+        dlog('video capture binary not present — stream server disabled for this device');
+        return;
+    }
+    const port = await (0, bootstrap_js_1.getStreamPort)(sessionName);
+    videoServer = await (0, video_server_js_1.startVideoServer)({
+        port,
+        device: sessionName,
+        platform: driverPlatform,
+        makeSource: (hub) => new video_source_js_1.IOSCaptureSource(binary, sessionName, hub, dlog),
+        dlog,
+    });
+    streamPort = port;
+    dlog(`video server listening on ${port}`);
+}
 const DRIVER_HEALTH_INTERVAL_MS = 10000; // Check driver health every 10s
 let _restartInProgress = false;
 let _driverStarted = false;
@@ -239,6 +270,15 @@ async function main() {
             }
             inputServer = null;
         }
+        if (videoServer) {
+            try {
+                await videoServer.close();
+            }
+            catch {
+                /* ok */
+            }
+            videoServer = null;
+        }
         if (hidClient) {
             hidClient.stop();
             hidClient = null;
@@ -366,6 +406,7 @@ async function main() {
                 platform: driverPlatform,
                 driverPort,
                 inputPort,
+                streamPort,
                 cdpUrl: cdpUrl ?? null,
                 cdpTargetId: cdpTargetId ?? null,
                 chromiumCdpPort: driverPlatform === 'web' ? (0, web_server_js_1.getCdpPort)() : null,
@@ -419,6 +460,12 @@ async function main() {
                     catch (err) {
                         dlog(`Input server startup error: ${err instanceof Error ? err.message : String(err)}`);
                     }
+                    try {
+                        await startVideoServerForPlatform();
+                    }
+                    catch (err) {
+                        dlog(`Video server startup error: ${err instanceof Error ? err.message : String(err)}`);
+                    }
                 }
                 // Start collecting logs once the driver is (or was already) running.
                 if (_driverStarted) {

package/dist/daemon/video-hub.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Fan-out hub for a single device's H.264 stream: one capture, N subscribers.
+ *
+ * Mirrors Argus's videoForward.ts. The last-seen config and the last keyframe
+ * access unit are cached so a late subscriber can configure its decoder and
+ * start rendering immediately, without waiting for the next natural keyframe.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VideoHub = void 0;
+class VideoHub {
+    constructor() {
+        this.listeners = new Set();
+        this.lastConfig = null;
+        this.lastKeyframe = null;
+    }
+    get subscriberCount() {
+        return this.listeners.size;
+    }
+    /**
+     * Subscribe. If a config (and keyframe) are already cached they are delivered
+     * synchronously so the decoder starts without waiting. Returns an unsubscribe.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        if (this.lastConfig) {
+            listener.onConfig(this.lastConfig);
+            if (this.lastKeyframe)
+                listener.onFrame(this.lastKeyframe, true);
+        }
+        return () => this.listeners.delete(listener);
+    }
+    emitConfig(config) {
+        this.lastConfig = config;
+        // A config change invalidates the cached keyframe (dimensions may differ).
+        this.lastKeyframe = null;
+        for (const l of this.listeners)
+            l.onConfig(config);
+    }
+    emitFrame(annexB, keyFrame) {
+        if (keyFrame)
+            this.lastKeyframe = annexB;
+        for (const l of this.listeners)
+            l.onFrame(annexB, keyFrame);
+    }
+    /** Current coded dimensions, if known. */
+    dims() {
+        return this.lastConfig
+            ? { width: this.lastConfig.width, height: this.lastConfig.height }
+            : null;
+    }
+    /** Drop cached state when capture ends. */
+    clear() {
+        this.lastConfig = null;
+        this.lastKeyframe = null;
+    }
+}
+exports.VideoHub = VideoHub;

package/dist/daemon/video-protocol.js

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Streaming device-video protocol (conductor ⇄ subscribers).
+ *
+ * The capture counterpart to input-protocol.ts. A persistent per-device
+ * WebSocket carries a low-latency H.264 stream: on connect the server sends one
+ * JSON `config` frame (codec + dimensions + SPS/PPS), then a sequence of
+ * **binary** frames, each a single H.264 Annex B access unit (keyframe-led). One
+ * capture feeds N subscribers (fan-out); a late joiner always gets the cached
+ * config + a fresh keyframe immediately.
+ *
+ * Web devices advertise a different codec (JPEG over CDP screencast) in the same
+ * `config` frame so clients pick a decoder from the wire, not the URL.
+ *
+ * See docs/device-video-stream.md for the design.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VIDEO_PROTOCOL_VERSION = void 0;
+exports.toConfigFrame = toConfigFrame;
+exports.VIDEO_PROTOCOL_VERSION = 1;
+/** Serialize an in-daemon config into the JSON frame sent to a subscriber. */
+function toConfigFrame(cfg, device, platform) {
+    return {
+        t: 'config',
+        protocol: exports.VIDEO_PROTOCOL_VERSION,
+        device,
+        platform,
+        codec: cfg.codec,
+        width: cfg.width,
+        height: cfg.height,
+        rotation: cfg.rotation,
+        fps: cfg.fps,
+        codecString: cfg.codecString,
+        sps: cfg.sps ? cfg.sps.toString('base64') : undefined,
+        pps: cfg.pps ? cfg.pps.toString('base64') : undefined,
+        avcC: cfg.avcC ? cfg.avcC.toString('base64') : undefined,
+    };
+}

package/dist/daemon/video-server.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startVideoServer = startVideoServer;
+/**
+ * Streaming video WebSocket server (one per device daemon).
+ *
+ * The capture counterpart to input-server.ts. Bound to loopback; N clients open
+ * a socket and receive one JSON `config` frame followed by binary H.264 Annex B
+ * access units. All subscribers share one capture via a VideoHub — the first
+ * connection starts the capture backend, the last one out stops it. A late
+ * joiner gets the cached config + keyframe immediately (hub responsibility).
+ */
+const ws_1 = require("ws");
+const video_protocol_js_1 = require("./video-protocol.js");
+const video_hub_js_1 = require("./video-hub.js");
+function sendJson(ws, frame) {
+    if (ws.readyState === ws_1.WebSocket.OPEN)
+        ws.send(JSON.stringify(frame));
+}
+function startVideoServer(opts) {
+    const host = opts.host ?? '127.0.0.1';
+    const dlog = opts.dlog ?? (() => { });
+    const hub = new video_hub_js_1.VideoHub();
+    const source = opts.makeSource(hub);
+    // Serialize start/stop so a rapid connect/disconnect churn can't race the
+    // capture backend into an inconsistent state.
+    let lifecycle = Promise.resolve();
+    const runExclusive = (fn) => {
+        lifecycle = lifecycle.then(fn, fn);
+        return lifecycle;
+    };
+    return new Promise((resolve, reject) => {
+        const wss = new ws_1.WebSocketServer({ host, port: opts.port });
+        wss.on('error', reject);
+        wss.on('listening', () => {
+            const addr = wss.address();
+            const boundPort = typeof addr === 'object' && addr ? addr.port : opts.port;
+            dlog(`video socket ready at ws://${host}:${boundPort}/stream (${opts.platform})`);
+            resolve({
+                port: boundPort,
+                hub,
+                close: () => runExclusive(async () => {
+                    for (const client of wss.clients)
+                        client.close();
+                    await source.stop().catch(() => { });
+                    await new Promise((res) => wss.close(() => res()));
+                }),
+            });
+        });
+        wss.on('connection', (ws) => {
+            const listener = {
+                onConfig: (config) => sendJson(ws, (0, video_protocol_js_1.toConfigFrame)(config, opts.device, opts.platform)),
+                onFrame: (annexB, _keyFrame) => {
+                    if (ws.readyState === ws_1.WebSocket.OPEN)
+                        ws.send(annexB);
+                },
+            };
+            const unsubscribe = hub.subscribe(listener);
+            const wasFirst = hub.subscriberCount === 1;
+            if (wasFirst) {
+                void runExclusive(async () => {
+                    try {
+                        await source.start();
+                    }
+                    catch (err) {
+                        dlog(`capture start error: ${err instanceof Error ? err.message : String(err)}`);
+                        sendJson(ws, {
+                            t: 'notice',
+                            code: 'capture_failed',
+                            msg: 'capture backend failed to start',
+                        });
+                    }
+                });
+            }
+            const teardown = () => {
+                unsubscribe();
+                if (hub.subscriberCount === 0) {
+                    void runExclusive(() => source.stop().catch(() => { }));
+                }
+            };
+            ws.on('close', teardown);
+            ws.on('error', (err) => {
+                dlog(`video socket error: ${err instanceof Error ? err.message : String(err)}`);
+            });
+            // Clients are pure subscribers; inbound messages are ignored.
+        });
+    });
+}

package/dist/daemon/video-source.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IOSCaptureSource = void 0;
+/**
+ * Capture sources — the producer half of the video stream. A source drives one
+ * platform's capture and feeds decoded config/access-units into a VideoHub. The
+ * video server ref-counts subscribers and calls start()/stop() so exactly one
+ * capture runs while ≥1 subscriber is connected (last one out stops it).
+ *
+ * iOS/tvOS: spawns the host-side `conductor-capture` binary (packages/ios-capture),
+ * which captures the Simulator framebuffer via SimulatorKit, VideoToolbox-encodes
+ * H.264, and serves a raw Annex B TCP stream. We connect to that port, parse the
+ * elementary stream, and forward.
+ */
+const child_process_1 = require("child_process");
+const net_1 = __importDefault(require("net"));
+const readline_1 = __importDefault(require("readline"));
+const h264_annexb_js_1 = require("./h264-annexb.js");
+/** Restart the capture backend at most this often if the TCP stream drops. */
+const RESTART_BACKOFF_MS = 1000;
+class IOSCaptureSource {
+    constructor(binaryPath, udid, hub, dlog = () => { }) {
+        this.binaryPath = binaryPath;
+        this.udid = udid;
+        this.hub = hub;
+        this.dlog = dlog;
+        this.proc = null;
+        this.rl = null;
+        this.socket = null;
+        this.parser = null;
+        this.pending = [];
+        this.active = false;
+        this.restarting = false;
+    }
+    async start() {
+        if (this.active)
+            return;
+        this.active = true;
+        await this.spawnAndCapture();
+    }
+    async spawnAndCapture() {
+        this.proc = (0, child_process_1.spawn)(this.binaryPath, [], { stdio: ['pipe', 'pipe', 'inherit'] });
+        this.rl = readline_1.default.createInterface({ input: this.proc.stdout });
+        this.rl.on('line', (line) => {
+            const resolve = this.pending.shift();
+            if (!resolve)
+                return;
+            try {
+                resolve(JSON.parse(line));
+            }
+            catch {
+                resolve({ ok: false, error: `bad response: ${line}` });
+            }
+        });
+        this.proc.on('exit', (code) => {
+            this.dlog(`capture backend exited (code=${code ?? '?'})`);
+            this.proc = null;
+            this.rl = null;
+            while (this.pending.length)
+                this.pending.shift()({ ok: false, error: 'capture exited' });
+            this.maybeRestart();
+        });
+        const res = await this.send({ cmd: 'start_capture', udid: this.udid });
+        if (!res.ok || typeof res.port !== 'number') {
+            throw new Error(`start_capture failed: ${res.error ?? 'no port returned'}`);
+        }
+        this.connectStream(res.port);
+        this.dlog(`capture started, streaming H.264 from 127.0.0.1:${res.port}`);
+    }
+    connectStream(port) {
+        const parser = new h264_annexb_js_1.H264AnnexBParser({
+            onConfig: (config) => {
+                this.dlog(`H.264 config ${config.codecString} ${config.width}x${config.height}`);
+                this.hub.emitConfig(config);
+            },
+            onFrame: (annexB, keyFrame) => this.hub.emitFrame(annexB, keyFrame),
+        });
+        this.parser = parser;
+        const socket = net_1.default.connect(port, '127.0.0.1', () => {
+            this.dlog(`connected to capture stream on ${port}`);
+        });
+        socket.on('data', (chunk) => parser.push(chunk));
+        socket.on('error', (err) => this.dlog(`capture stream error: ${err.message}`));
+        socket.on('close', () => {
+            this.dlog('capture stream closed');
+            this.maybeRestart();
+        });
+        this.socket = socket;
+    }
+    /** If capture died while subscribers still want it, relaunch after a short backoff. */
+    maybeRestart() {
+        if (!this.active || this.restarting)
+            return;
+        this.restarting = true;
+        this.teardownTransport();
+        setTimeout(() => {
+            this.restarting = false;
+            if (!this.active)
+                return;
+            this.dlog('restarting capture backend');
+            this.spawnAndCapture().catch((err) => this.dlog(`capture restart failed: ${err.message}`));
+        }, RESTART_BACKOFF_MS).unref?.();
+    }
+    teardownTransport() {
+        this.socket?.destroy();
+        this.socket = null;
+        this.parser?.reset();
+        this.parser = null;
+    }
+    async stop() {
+        if (!this.active)
+            return;
+        this.active = false;
+        try {
+            if (this.proc)
+                await this.send({ cmd: 'stop_capture' }).catch(() => { });
+        }
+        finally {
+            this.teardownTransport();
+            this.rl?.close();
+            this.rl = null;
+            this.proc?.kill();
+            this.proc = null;
+            this.hub.clear();
+            this.dlog('capture stopped');
+        }
+    }
+    send(req) {
+        return new Promise((resolve) => {
+            if (!this.proc || !this.proc.stdin?.writable) {
+                resolve({ ok: false, error: 'capture process not running' });
+                return;
+            }
+            this.pending.push(resolve);
+            this.proc.stdin.write(JSON.stringify(req) + '\n');
+        });
+    }
+}
+exports.IOSCaptureSource = IOSCaptureSource;

package/dist/drivers/android.js

@@ -75,6 +75,10 @@ class AndroidDriver {
         this._recordingProcess = null;
         this._recordingOutputPath = '';
     }
+    /** adb serial of the target device (used by out-of-process helpers like record-video). */
+    get serial() {
+        return this.deviceId;
+    }
     async connect() {
         const packageDef = loadPackageDef();
         // eslint-disable-next-line @typescript-eslint/no-explicit-any