@houwert/conductor 0.25.0 → 0.26.0

package/dist/commands/stream-server.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HELP = void 0;
+exports.streamServer = streamServer;
+exports.HELP = `  stream-server                       Start (if needed) and print the live video-stream WebSocket for the device`;
+const runner_js_1 = require("../runner.js");
+const output_js_1 = require("../output.js");
+/**
+ * Ensure the device daemon + streaming-video socket are up and print the
+ * loopback WebSocket URL a viewer subscribes to for the live H.264 stream.
+ * See docs/device-video-stream.md.
+ */
+async function streamServer(opts = {}, sessionName = 'default') {
+    try {
+        const info = await (0, runner_js_1.streamServerInfo)(sessionName);
+        if (opts.json) {
+            (0, output_js_1.printData)(info, opts);
+        }
+        else {
+            console.log(`stream server [${info.device}] (${info.platform}, ${info.codec}): ${info.url}`);
+        }
+        return 0;
+    }
+    catch (err) {
+        (0, output_js_1.printError)(`stream-server — ${err instanceof Error ? err.message : String(err)}`, opts);
+        return 1;
+    }
+}

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/bootstrap.js

@@ -6,8 +6,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.detectPlatform = detectPlatform;
 exports.getDriverPort = getDriverPort;
 exports.getInputPort = getInputPort;
+exports.getStreamPort = getStreamPort;
 exports.getInprocDylibPath = getInprocDylibPath;
 exports.getHidBinaryPath = getHidBinaryPath;
+exports.getCaptureBinaryPath = getCaptureBinaryPath;
 exports.installDriver = installDriver;
 exports.isSimulatorBooted = isSimulatorBooted;
 exports.isPortOpen = isPortOpen;
@@ -93,6 +95,7 @@ const ANDROID_BASE_PORT = 3763;
 const WEB_BASE_PORT = 4075;
 const VEGA_BASE_PORT = 5075;
 const INPUT_BASE_PORT = 7075;
+const STREAM_BASE_PORT = 8075;
 const PORT_FILE = path_1.default.join(os_1.default.homedir(), '.conductor', 'ports.json');
 const PORT_LOCK = PORT_FILE + '.lock';
 const PORT_LOCK_TIMEOUT_MS = 5000;
@@ -200,6 +203,27 @@ async function getInputPort(deviceId) {
         return port;
     });
 }
+/**
+ * Assign and persist a streaming-video WebSocket port for a device. Its own
+ * namespace: a device has a driver port (control), an input port (pointer/key
+ * frames), and this stream port (H.264 video fan-out).
+ */
+async function getStreamPort(deviceId) {
+    return withPortLock(() => {
+        const state = readPortState();
+        if (!state.streamAssignments)
+            state.streamAssignments = {};
+        if (state.nextStreamPort === undefined)
+            state.nextStreamPort = STREAM_BASE_PORT;
+        if (state.streamAssignments[deviceId] !== undefined) {
+            return state.streamAssignments[deviceId];
+        }
+        const port = state.nextStreamPort++;
+        state.streamAssignments[deviceId] = port;
+        writePortState(state);
+        return port;
+    });
+}
 // ── Driver paths (bundled dev fallback + runtime download cache) ──────────────
 /**
  * Walk up from __dirname to find the package root (the directory containing
@@ -274,6 +298,20 @@ async function getHidBinaryPath() {
     const p = path_1.default.join(dir, 'ios-hid', 'conductor-hid');
     return fs_1.default.existsSync(p) ? p : null;
 }
+/**
+ * Absolute path to the host-side Simulator video capture binary
+ * (`ios-capture/conductor-capture`), built by
+ * `packages/ios-capture/tools/build-capture.sh`. Captures the framebuffer via
+ * SimulatorKit and serves a VideoToolbox H.264 Annex B stream. Returns null if
+ * it hasn't been built (streaming falls back to unavailable).
+ */
+async function getCaptureBinaryPath() {
+    const dir = await getDriversDir().catch(() => null);
+    if (!dir)
+        return null;
+    const p = path_1.default.join(dir, 'ios-capture', 'conductor-capture');
+    return fs_1.default.existsSync(p) ? p : null;
+}
 async function ensureDriversCache(pkgRoot) {
     const pkgJsonPath = path_1.default.join(pkgRoot, 'package.json');
     const pkg = JSON.parse(fs_1.default.readFileSync(pkgJsonPath, 'utf-8'));

package/dist/index.js

@@ -30,6 +30,7 @@ const press_key_js_1 = require("./commands/press-key.js");
 const session_js_1 = require("./commands/session.js");
 const daemon_js_1 = require("./commands/daemon.js");
 const input_server_js_1 = require("./commands/input-server.js");
+const stream_server_js_1 = require("./commands/stream-server.js");
 const install_js_1 = require("./commands/install.js");
 const init_js_1 = require("./commands/init.js");
 const device_pool_js_1 = require("./commands/device-pool.js");
@@ -135,6 +136,7 @@ const COMMAND_HELP = {
     'daemon-stop': daemon_js_1.HELP_DAEMON_STOP,
     'daemon-status': daemon_js_1.HELP_DAEMON_STATUS,
     'input-server': input_server_js_1.HELP,
+    'stream-server': stream_server_js_1.HELP,
     'device-pool': device_pool_js_1.HELP,
     'run-parallel': run_parallel_js_1.HELP,
     'run-sequence': run_sequence_js_1.HELP,
@@ -847,6 +849,9 @@ async function main() {
         case 'input-server':
             exitCode = await (0, input_server_js_1.inputServer)(opts, sessionName);
             break;
+        case 'stream-server':
+            exitCode = await (0, stream_server_js_1.streamServer)(opts, sessionName);
+            break;
         case 'device-pool': {
             const acquire = argv['acquire'];
             const release = argv['release'];

package/dist/runner.js

@@ -4,6 +4,7 @@ exports.detectFirstDevice = detectFirstDevice;
 exports.getDriver = getDriver;
 exports.prewarmDriver = prewarmDriver;
 exports.inputServerInfo = inputServerInfo;
+exports.streamServerInfo = streamServerInfo;
 exports.runDirect = runDirect;
 exports.spawnCommand = spawnCommand;
 exports.runInlineFlow = runInlineFlow;
@@ -276,6 +277,50 @@ async function inputServerInfo(sessionName = 'default') {
     }
     throw new Error(`Input server for ${deviceId} did not come up within timeout.`);
 }
+/**
+ * Resolve the streaming-video socket for a session's device, starting the
+ * daemon (and its driver + video server) if needed. Returns the loopback
+ * WebSocket URL a viewer subscribes to. Throws if the platform has no live
+ * stream, the capture binary isn't built, or the port never comes up.
+ */
+async function streamServerInfo(sessionName = 'default') {
+    const deviceId = await resolveDeviceId(sessionName);
+    if (!deviceId) {
+        throw new Error('No device found. Connect a device or start a simulator, then run again.');
+    }
+    const platform = await (0, bootstrap_js_1.detectPlatform)(deviceId);
+    if (platform !== 'ios' && platform !== 'tvos') {
+        throw new Error(`Live video streaming is not yet available for ${platform} devices.`);
+    }
+    await (0, client_js_1.startDaemon)(deviceId);
+    // The video server starts just after the input server — poll status until its port appears.
+    const start = Date.now();
+    const deadline = start + 60000;
+    while (Date.now() < deadline) {
+        const status = await (0, client_js_1.fetchDaemonStatus)(deviceId);
+        if (status && typeof status.streamPort === 'number') {
+            return {
+                device: deviceId,
+                platform,
+                streamPort: status.streamPort,
+                url: `ws://127.0.0.1:${status.streamPort}/stream?device=${encodeURIComponent(deviceId)}&platform=${platform}`,
+                codec: 'h264',
+            };
+        }
+        // A daemon whose input server is up but that still reports no streamPort
+        // after a grace period means the capture binary isn't built/available —
+        // fail fast rather than waiting out the full timeout.
+        if (status &&
+            status.streamPort === null &&
+            typeof status.inputPort === 'number' &&
+            Date.now() - start > 5000) {
+            throw new Error(`Video capture backend is not available for ${deviceId} ` +
+                `(the conductor-capture binary is missing from the installed drivers).`);
+        }
+        await new Promise((r) => setTimeout(r, 500));
+    }
+    throw new Error(`Video server for ${deviceId} did not come up within timeout.`);
+}
 /**
  * Execute a function with the driver for the given session.
  * Returns a RunResult for consistent error handling across commands.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@houwert/conductor",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "CLI tool for mobile app interactions — optimized for AI agents",
   "license": "MIT",
   "repository": {

package/skills/conductor-device-interact/SKILL.md

@@ -52,6 +52,7 @@ conductor assert-visible "Dashboard"
 | `conductor clipboard read` / `clipboard write <text>` / `paste` | Clipboard (iOS) |
 | `conductor list-options [command]` | List valid values for enumerated params |
 | `conductor input-server` | Start (if needed) and print the streaming-input WebSocket URL for the device |
+| `conductor stream-server` | Start (if needed) and print the live video-stream WebSocket URL for the device |
 
 ## Streaming input (host IDEs)
 
@@ -65,6 +66,20 @@ accepts normalized (0..1) frames: `pointer{id,phase,x,y}`, `key{code,mods,down}`
 owns coord→device translation and keymaps. For scripted, one-off actions use the
 discrete commands above — this is for interactive host UIs.
 
+## Streaming video (host IDEs / device viewers)
+
+For live device mirroring, `conductor stream-server` ensures the daemon + capture
+backend are up and prints the loopback URL
+(`ws://127.0.0.1:<port>/stream?device=<id>&platform=<ios|tvos|android|web>`; also
+in `daemon-status --json` as `streamPort`). One capture fans out to N subscribers.
+On connect the server sends a JSON `config` frame
+(`{t:"config",codec:"h264",width,height,rotation,fps,sps,pps,avcC,codecString}`),
+then **binary** frames — each one H.264 Annex B access unit, keyframe-led; a late
+joiner gets the cached config + a keyframe immediately. iOS/tvOS only for now
+(host-side SimulatorKit → VideoToolbox capture); Android/web are follow-ons.
+This is capture only — input stays on `input-server`. For a still image use
+`screenshot` / `capture-ui`; this socket is for continuous low-latency mirroring.
+
 ## Discovering valid values
 
 Several commands only accept a fixed set of values (`press-key <key>`,