@livedesk/hub 0.1.0 → 0.1.1

package/src/mode4-atlas-worker.js

@@ -0,0 +1,439 @@
+#!/usr/bin/env node
+
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { existsSync } from 'node:fs';
+import { decodeLzo1xBlock } from './lzo1x.js';
+
+const require = createRequire(import.meta.url);
+const DEFAULT_WIDTH = 1920;
+const DEFAULT_HEIGHT = 1080;
+const DEFAULT_FPS = 20;
+const MAX_DEVICES = 100;
+const FRAME_POOL_SIZE = 8;
+const MAX_TILE_WIDTH = 480;
+const MAX_TILE_HEIGHT = 270;
+
+const rgb565Red = new Uint8Array(65_536);
+const rgb565Green = new Uint8Array(65_536);
+const rgb565Blue = new Uint8Array(65_536);
+for (let pixel = 0; pixel < 65_536; pixel += 1) {
+  rgb565Red[pixel] = (((pixel >> 11) & 0x1f) * 255 / 31) | 0;
+  rgb565Green[pixel] = (((pixel >> 5) & 0x3f) * 255 / 63) | 0;
+  rgb565Blue[pixel] = ((pixel & 0x1f) * 255 / 31) | 0;
+}
+
+let config = normalizeConfig({});
+let layoutVersion = 0;
+let layout = [];
+let latestTiles = new Map();
+let framePool = [];
+let encoder = null;
+let encoderCandidateIndex = 0;
+let encoderCandidates = [];
+let encoderOutputSeen = false;
+let encoderGeneration = 0;
+let encoderRestartTimer = null;
+let encoderStartupTimer = null;
+let inputWaitTimer = null;
+let outputBuffer = Buffer.alloc(0);
+let frameSeq = 0;
+let tickTimer = null;
+let nextTickAt = 0;
+let closed = false;
+let lastComposeMs = 0;
+let poolStarved = 0;
+const ENCODER_STARTUP_OUTPUT_TIMEOUT_MS = 8_000;
+
+function clamp(value, min, max, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) ? Math.max(min, Math.min(max, Math.round(number))) : fallback;
+}
+
+function normalizeConfig(value) {
+  const deviceIds = [...new Set((Array.isArray(value?.deviceIds) ? value.deviceIds : [])
+    .map(item => String(item || '').trim()).filter(Boolean))].slice(0, MAX_DEVICES);
+  const maxWidth = clamp(value?.width, 640, 3840, DEFAULT_WIDTH);
+  const maxHeight = clamp(value?.height, 360, 2160, DEFAULT_HEIGHT);
+  const sharpTiles = Number(value?.tileWidth) >= 480 || Number(value?.tileHeight) >= 270;
+  const sourceTileWidth = sharpTiles ? 480 : 320;
+  const sourceTileHeight = sharpTiles ? 270 : 180;
+  const count = Math.max(1, deviceIds.length);
+  const columns = Math.max(1, Math.ceil(Math.sqrt(count)));
+  const rows = Math.max(1, Math.ceil(count / columns));
+  const tileWidth = Math.max(2, Math.min(sourceTileWidth, Math.floor(maxWidth / columns))) & ~1;
+  const tileHeight = Math.max(2, Math.min(sourceTileHeight, Math.floor(maxHeight / rows))) & ~1;
+  return {
+    deviceIds,
+    maxWidth,
+    maxHeight,
+    width: tileWidth * columns,
+    height: tileHeight * rows,
+    columns,
+    rows,
+    tileWidth,
+    tileHeight,
+    sourceTileWidth,
+    sourceTileHeight,
+    fps: clamp(value?.fps, 1, 30, DEFAULT_FPS)
+  };
+}
+
+function send(message) {
+  if (process.connected) process.send?.(message);
+}
+
+function resolveFfmpegPaths() {
+  const paths = [];
+  const add = value => {
+    const path = String(value || '').trim();
+    if (!path || paths.includes(path)) return;
+    if (path === 'ffmpeg' || existsSync(path)) paths.push(path);
+  };
+  add(process.env.LIVEDESK_FFMPEG);
+  try { add(require('@ffmpeg-installer/ffmpeg')?.path); } catch {}
+  try { add(require('ffmpeg-static')); } catch {}
+  add('ffmpeg');
+  return paths;
+}
+
+function buildEncoderCandidates() {
+  const codecCandidates = process.platform === 'win32'
+    ? [
+        ['windows-nvenc', ['-c:v', 'h264_nvenc', '-preset', 'llhp', '-profile:v', 'baseline', '-rc:v', 'cbr_ld_hq', '-b:v', '6M', '-maxrate', '6M', '-bufsize', '1M', '-rc-lookahead', '0', '-zerolatency', '1', '-g', String(config.fps), '-bf', '0']],
+        ['windows-qsv', ['-c:v', 'h264_qsv', '-preset', 'veryfast', '-global_quality', '28', '-look_ahead', '0', '-g', String(config.fps), '-bf', '0']],
+        ['windows-amf', ['-c:v', 'h264_amf', '-quality', 'speed', '-usage', 'lowlatency', '-rc', 'cqp', '-qp_i', '25', '-qp_p', '28', '-g', String(config.fps), '-bf', '0']]
+      ]
+    : process.platform === 'darwin'
+      ? [['macos-videotoolbox', ['-c:v', 'h264_videotoolbox', '-realtime', '1', '-allow_sw', '0', '-b:v', '6M', '-g', String(config.fps), '-bf', '0']]]
+      : [['linux-nvenc', ['-c:v', 'h264_nvenc', '-preset', 'llhp', '-profile:v', 'baseline', '-rc-lookahead', '0', '-zerolatency', '1', '-g', String(config.fps), '-bf', '0']]];
+  codecCandidates.push(['software-x264', [
+    '-c:v', 'libx264', '-preset', 'ultrafast', '-tune', 'zerolatency',
+    '-profile:v', 'baseline', '-crf', '28', '-g', String(config.fps),
+    '-keyint_min', String(config.fps), '-sc_threshold', '0', '-bf', '0',
+    '-x264-params', 'aud=1:repeat-headers=1'
+  ]]);
+  return resolveFfmpegPaths().flatMap(path => codecCandidates.map(([name, args]) => ({ path, name, args })));
+}
+
+function startEncoder() {
+  if (closed || encoder || encoderCandidates.length === 0) return;
+  if (encoderCandidateIndex >= encoderCandidates.length) {
+    send({ type: 'status', state: 'error', error: 'No Mode 4 H.264 encoder is available.' });
+    return;
+  }
+  const candidate = encoderCandidates[encoderCandidateIndex++];
+  encoderGeneration += 1;
+  const args = [
+    '-hide_banner', '-loglevel', 'warning',
+    '-f', 'rawvideo', '-pixel_format', 'rgb24',
+    '-video_size', `${config.width}x${config.height}`,
+    '-framerate', String(config.fps), '-i', 'pipe:0', '-an',
+    ...candidate.args,
+    '-bsf:v', 'h264_metadata=aud=insert', '-f', 'h264', 'pipe:1'
+  ];
+  const child = spawn(candidate.path, args, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+  encoder = { child, candidate, inputSeen: false };
+  encoderOutputSeen = false;
+  outputBuffer = Buffer.alloc(0);
+  child.stdout.on('data', appendEncodedBytes);
+  child.stdin.on('error', error => {
+    if (encoder?.child === child && !isClosedPipeError(error)) {
+      send({ type: 'log', level: 'warn', message: `Mode 4 ${candidate.name} input: ${error.message}` });
+    }
+  });
+  child.stderr.on('data', chunk => {
+    const message = String(chunk || '').trim();
+    if (message) send({ type: 'log', level: 'warn', message: `Mode 4 ${candidate.name}: ${message.slice(0, 600)}` });
+  });
+  child.on('error', error => send({ type: 'log', level: 'warn', message: `Mode 4 ${candidate.name}: ${error.message}` }));
+  child.on('exit', code => {
+    clearTimeout(encoderStartupTimer);
+    encoderStartupTimer = null;
+    const wasCurrent = encoder?.child === child;
+    if (wasCurrent) encoder = null;
+    flushEncodedUnit();
+    if (closed) return;
+    send({ type: 'status', state: 'encoder-restart', encoder: candidate.name, code, emitted: encoderOutputSeen });
+    clearTimeout(encoderRestartTimer);
+    encoderRestartTimer = setTimeout(startEncoder, encoderOutputSeen ? 800 : 120);
+  });
+  send({ type: 'status', state: 'encoder-starting', encoder: candidate.name });
+}
+
+function isClosedPipeError(error) {
+  const code = String(error?.code || '').toUpperCase();
+  const message = String(error?.message || '').toLowerCase();
+  return code === 'EPIPE' || code === 'EOF' || code === 'ERR_STREAM_DESTROYED'
+    || message.includes('write eof') || message.includes('broken pipe');
+}
+
+function armEncoderStartupTimer(child, candidate) {
+  clearTimeout(encoderStartupTimer);
+  encoderStartupTimer = setTimeout(() => {
+    if (encoder?.child === child && encoder.inputSeen && !encoderOutputSeen) {
+      send({ type: 'log', level: 'warn', message: `Mode 4 ${candidate.name}: no output after receiving input; trying the next encoder.` });
+      try { child.kill(); } catch {}
+    }
+  }, ENCODER_STARTUP_OUTPUT_TIMEOUT_MS);
+}
+
+function stopEncoder() {
+  clearTimeout(encoderRestartTimer);
+  encoderRestartTimer = null;
+  clearTimeout(encoderStartupTimer);
+  encoderStartupTimer = null;
+  const child = encoder?.child;
+  encoder = null;
+  if (!child) return;
+  try { child.stdin.end(); } catch {}
+  setTimeout(() => { try { child.kill(); } catch {} }, 250).unref?.();
+}
+
+function findStartCodes(buffer) {
+  const starts = [];
+  for (let index = 0; index + 3 < buffer.length; index += 1) {
+    if (buffer[index] !== 0 || buffer[index + 1] !== 0) continue;
+    if (buffer[index + 2] === 1) {
+      starts.push({ offset: index, header: index + 3 });
+      index += 2;
+    } else if (buffer[index + 2] === 0 && buffer[index + 3] === 1) {
+      starts.push({ offset: index, header: index + 4 });
+      index += 3;
+    }
+  }
+  return starts;
+}
+
+function appendEncodedBytes(chunk) {
+  outputBuffer = outputBuffer.length ? Buffer.concat([outputBuffer, chunk]) : Buffer.from(chunk);
+  while (true) {
+    const auds = findStartCodes(outputBuffer).filter(start => (outputBuffer[start.header] & 0x1f) === 9);
+    if (auds.length < 2) break;
+    const boundary = auds[1].offset;
+    emitEncodedUnit(outputBuffer.subarray(0, boundary));
+    outputBuffer = outputBuffer.subarray(boundary);
+  }
+}
+
+function flushEncodedUnit() {
+  if (outputBuffer.length > 0) emitEncodedUnit(outputBuffer);
+  outputBuffer = Buffer.alloc(0);
+}
+
+function emitEncodedUnit(payload) {
+  if (!payload?.length) return;
+  const starts = findStartCodes(payload);
+  const isKeyFrame = starts.some(start => (payload[start.header] & 0x1f) === 5);
+  encoderOutputSeen = true;
+  clearTimeout(encoderStartupTimer);
+  encoderStartupTimer = null;
+  frameSeq += 1;
+  send({
+    type: 'frame',
+    payload: Buffer.from(payload),
+    metadata: {
+      frameSeq,
+      streamFrameSeq: frameSeq,
+      width: config.width,
+      height: config.height,
+      fps: config.fps,
+      durationUs: Math.round(1_000_000 / config.fps),
+      timestampUs: Math.round(frameSeq * 1_000_000 / config.fps),
+      isKeyFrame,
+      chunkType: isKeyFrame ? 'key' : 'delta',
+      hardwareEncoder: encoder?.candidate?.name || '',
+      encoderGeneration,
+      layoutVersion,
+      composeMs: lastComposeMs,
+      poolStarved,
+      readyTileCount: latestTiles.size,
+      tileCount: config.deviceIds.length
+    }
+  });
+}
+
+function rebuildLayout() {
+  const { columns, rows, tileWidth, tileHeight } = config;
+  layoutVersion += 1;
+  layout = config.deviceIds.map((deviceId, index) => ({
+    deviceId,
+    index,
+    column: index % columns,
+    row: Math.floor(index / columns),
+    x: (index % columns) * tileWidth,
+    y: Math.floor(index / columns) * tileHeight,
+    width: tileWidth,
+    height: tileHeight
+  }));
+  for (const tile of latestTiles.values()) tile.rendered = null;
+  framePool = Array.from({ length: FRAME_POOL_SIZE }, () => Buffer.alloc(config.width * config.height * 3));
+  send({ type: 'layout', layoutVersion, width: config.width, height: config.height, columns, rows, tiles: layout });
+}
+
+function renderTile(tileState, tileLayout) {
+  const sourceWidth = tileState.width;
+  const sourceHeight = tileState.height;
+  const scale = Math.min(tileLayout.width / sourceWidth, tileLayout.height / sourceHeight);
+  const width = Math.max(1, Math.floor(sourceWidth * scale));
+  const height = Math.max(1, Math.floor(sourceHeight * scale));
+  const pixels = Buffer.allocUnsafe(width * height * 3);
+  let target = 0;
+  if (width === sourceWidth && height === sourceHeight) {
+    for (let source = 0; source < tileState.rgb565.length; source += 2) {
+      const pixel = tileState.rgb565[source] | (tileState.rgb565[source + 1] << 8);
+      pixels[target++] = rgb565Red[pixel];
+      pixels[target++] = rgb565Green[pixel];
+      pixels[target++] = rgb565Blue[pixel];
+    }
+  } else {
+  for (let y = 0; y < height; y += 1) {
+    const sourceY = Math.min(sourceHeight - 1, Math.floor((y + 0.5) * sourceHeight / height));
+    for (let x = 0; x < width; x += 1) {
+      const sourceX = Math.min(sourceWidth - 1, Math.floor((x + 0.5) * sourceWidth / width));
+      const source = (sourceY * sourceWidth + sourceX) * 2;
+      const pixel = tileState.rgb565[source] | (tileState.rgb565[source + 1] << 8);
+      pixels[target++] = rgb565Red[pixel];
+      pixels[target++] = rgb565Green[pixel];
+      pixels[target++] = rgb565Blue[pixel];
+    }
+  }
+  }
+  tileState.rendered = {
+    pixels,
+    width,
+    height,
+    x: tileLayout.x + Math.floor((tileLayout.width - width) / 2),
+    y: tileLayout.y + Math.floor((tileLayout.height - height) / 2),
+    layoutVersion
+  };
+}
+
+function ingestFrame(message) {
+  const deviceId = String(message.deviceId || '');
+  if (!deviceId || !config.deviceIds.includes(deviceId)) return;
+  const width = clamp(message.width, 1, config.sourceTileWidth, 0);
+  const height = clamp(message.height, 1, config.sourceTileHeight, 0);
+  const expectedLength = width * height * 2;
+  if (!width || !height || Number(message.uncompressedByteLength) !== expectedLength) return;
+  try {
+    const compressed = Buffer.isBuffer(message.payload) ? message.payload : Buffer.from(message.payload || []);
+    const rgb565 = decodeLzo1xBlock(new Uint8Array(compressed), expectedLength);
+    const tileState = { width, height, rgb565, rendered: null, frameSeq: Number(message.frameSeq || 0) };
+    latestTiles.set(deviceId, tileState);
+    if (!encoder && encoderCandidates.length > 0) startEncoder();
+    if (config.deviceIds.length > 0 && config.deviceIds.every(id => latestTiles.has(id))) {
+      clearTimeout(inputWaitTimer);
+      inputWaitTimer = null;
+    }
+    const tileLayout = layout.find(item => item.deviceId === deviceId);
+    if (tileLayout) renderTile(tileState, tileLayout);
+  } catch (error) {
+    send({ type: 'log', level: 'warn', message: `Mode 4 frame rejected for ${deviceId}: ${error.message}` });
+  }
+}
+
+function writeAtlasFrame() {
+  if (latestTiles.size === 0) return;
+  if (!encoder) {
+    startEncoder();
+    return;
+  }
+  const composeStartedAt = performance.now();
+  const target = framePool.pop();
+  const stdin = encoder?.child?.stdin;
+  if (!target || !stdin || stdin.destroyed || !stdin.writable) {
+    if (!target) poolStarved += 1;
+    return;
+  }
+  target.fill(0);
+  for (const tileLayout of layout) {
+    const tileState = latestTiles.get(tileLayout.deviceId);
+    if (!tileState) continue;
+    if (!tileState.rendered || tileState.rendered.layoutVersion !== layoutVersion) renderTile(tileState, tileLayout);
+    const rendered = tileState.rendered;
+    for (let row = 0; row < rendered.height; row += 1) {
+      const sourceStart = row * rendered.width * 3;
+      const targetStart = ((rendered.y + row) * config.width + rendered.x) * 3;
+      rendered.pixels.copy(target, targetStart, sourceStart, sourceStart + rendered.width * 3);
+    }
+  }
+  lastComposeMs = Math.max(0, performance.now() - composeStartedAt);
+  try {
+    const encoderEntry = encoder;
+    if (!encoderEntry.inputSeen) {
+      encoderEntry.inputSeen = true;
+      armEncoderStartupTimer(encoderEntry.child, encoderEntry.candidate);
+    }
+    stdin.write(target, error => {
+      framePool.push(target);
+      if (error && encoder?.child === encoderEntry.child && !isClosedPipeError(error)) {
+        send({ type: 'log', level: 'warn', message: `Mode 4 encoder write: ${error.message}` });
+      }
+    });
+  } catch (error) {
+    framePool.push(target);
+    if (!isClosedPipeError(error)) send({ type: 'log', level: 'warn', message: `Mode 4 encoder write: ${error.message}` });
+  }
+}
+
+function startComposeClock() {
+  clearTimeout(tickTimer);
+  const intervalMs = 1000 / config.fps;
+  nextTickAt = performance.now() + intervalMs;
+  const tick = () => {
+    if (closed) return;
+    writeAtlasFrame();
+    const now = performance.now();
+    nextTickAt += intervalMs;
+    if (nextTickAt < now - intervalMs) nextTickAt = now + intervalMs;
+    tickTimer = setTimeout(tick, Math.max(0, nextTickAt - performance.now()));
+  };
+  tickTimer = setTimeout(tick, intervalMs);
+}
+
+function configure(value) {
+  const next = normalizeConfig(value);
+  const encoderChanged = next.width !== config.width || next.height !== config.height || next.fps !== config.fps;
+  config = next;
+  latestTiles = new Map([...latestTiles].filter(([deviceId]) => config.deviceIds.includes(deviceId)));
+  clearTimeout(inputWaitTimer);
+  inputWaitTimer = config.deviceIds.length > 0 ? setTimeout(() => {
+    const missing = config.deviceIds.filter(deviceId => !latestTiles.has(deviceId));
+    if (missing.length > 0) {
+      send({
+        type: 'log',
+        level: 'warn',
+        message: `Mode 4 waiting for Mode 2 input from ${missing.length}/${config.deviceIds.length} devices: ${missing.slice(0, 8).join(', ')}`
+      });
+    }
+  }, 3000) : null;
+  rebuildLayout();
+  if (encoderChanged || !encoder) {
+    stopEncoder();
+    encoderCandidates = buildEncoderCandidates();
+    encoderCandidateIndex = 0;
+    if (latestTiles.size > 0) startEncoder();
+  }
+  startComposeClock();
+}
+
+process.on('message', message => {
+  if (message?.type === 'configure') configure(message);
+  else if (message?.type === 'frame') ingestFrame(message);
+  else if (message?.type === 'close') shutdown();
+});
+
+function shutdown() {
+  if (closed) return;
+  closed = true;
+  clearTimeout(tickTimer);
+  clearTimeout(inputWaitTimer);
+  stopEncoder();
+  setTimeout(() => process.exit(0), 50).unref?.();
+}
+
+process.on('disconnect', shutdown);
+process.on('SIGTERM', shutdown);
+process.on('SIGINT', shutdown);
+send({ type: 'status', state: 'ready' });

package/src/mode4-atlas.js

@@ -0,0 +1,129 @@
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const workerPath = fileURLToPath(new URL('./mode4-atlas-worker.js', import.meta.url));
+
+export class Mode4AtlasSession {
+  constructor(options = {}) {
+    this.onFrame = typeof options.onFrame === 'function' ? options.onFrame : () => {};
+    this.onLayout = typeof options.onLayout === 'function' ? options.onLayout : () => {};
+    this.onStatus = typeof options.onStatus === 'function' ? options.onStatus : () => {};
+    this.deviceIds = [];
+    this.deviceSet = new Set();
+    this.config = null;
+    this.closed = false;
+    this.worker = null;
+    this.restartTimer = null;
+    this.pendingFrames = new Map();
+    this.frameSendsInFlight = new Set();
+    this.workerGeneration = 0;
+    this.startWorker();
+  }
+
+  startWorker() {
+    if (this.closed || this.worker) return;
+    const workerGeneration = ++this.workerGeneration;
+    const worker = fork(workerPath, [], {
+      env: { ...process.env },
+      stdio: ['ignore', 'ignore', 'ignore', 'ipc'],
+      serialization: 'advanced',
+      windowsHide: true
+    });
+    this.worker = worker;
+    worker.on('message', message => {
+      if (message?.type === 'frame' && message.metadata && message.payload) {
+        this.onFrame({
+          metadata: { ...message.metadata, workerGeneration },
+          payload: Buffer.from(message.payload)
+        });
+      } else if (message?.type === 'layout') {
+        this.onLayout(message);
+      } else if (message?.type === 'status' || message?.type === 'log') {
+        this.onStatus(message);
+      }
+    });
+    worker.on('exit', code => {
+      if (this.worker === worker) this.worker = null;
+      this.frameSendsInFlight.clear();
+      if (this.closed) return;
+      this.onStatus({ type: 'status', state: 'worker-restart', code });
+      clearTimeout(this.restartTimer);
+      this.restartTimer = setTimeout(() => {
+        this.startWorker();
+        if (this.config) this.worker?.send({ type: 'configure', ...this.config });
+      }, 750);
+    });
+    worker.on('error', error => this.onStatus({ type: 'status', state: 'worker-error', error: error.message }));
+    if (this.config) {
+      worker.send({ type: 'configure', ...this.config }, () => {
+        for (const deviceId of this.pendingFrames.keys()) this.pumpDeviceFrame(deviceId);
+      });
+    }
+  }
+
+  configure(options = {}) {
+    this.deviceIds = [...new Set((Array.isArray(options.deviceIds) ? options.deviceIds : [])
+      .map(value => String(value || '').trim()).filter(Boolean))].slice(0, 100);
+    this.deviceSet = new Set(this.deviceIds);
+    this.pendingFrames = new Map([...this.pendingFrames].filter(([deviceId]) => this.deviceSet.has(deviceId)));
+    this.config = {
+      deviceIds: this.deviceIds,
+      width: Number(options.width || 1920),
+      height: Number(options.height || 1080),
+      tileWidth: Number(options.tileWidth || 320),
+      tileHeight: Number(options.tileHeight || 180),
+      fps: Number(options.fps || 20)
+    };
+    this.worker?.send({ type: 'configure', ...this.config });
+  }
+
+  pumpDeviceFrame(deviceId) {
+    if (this.closed || !this.worker || this.frameSendsInFlight.has(deviceId)) return;
+    const message = this.pendingFrames.get(deviceId);
+    if (!message) return;
+    this.pendingFrames.delete(deviceId);
+    this.frameSendsInFlight.add(deviceId);
+    try {
+      this.worker.send(message, error => {
+        this.frameSendsInFlight.delete(deviceId);
+        if (error && !this.closed) {
+          this.onStatus({ type: 'log', level: 'warn', message: `Mode 4 input ${deviceId}: ${error.message}` });
+        }
+        this.pumpDeviceFrame(deviceId);
+      });
+    } catch (error) {
+      this.frameSendsInFlight.delete(deviceId);
+      this.onStatus({ type: 'log', level: 'warn', message: `Mode 4 input ${deviceId}: ${error.message}` });
+    }
+  }
+
+  ingest(frameEvent) {
+    if (this.closed || !this.worker) return;
+    const frame = frameEvent?.frame || {};
+    const deviceId = String(frameEvent?.deviceId || frame.deviceId || '').trim();
+    const mode = String(frame.frameMode || frame.mode || '').toLowerCase();
+    if (!this.deviceSet.has(deviceId) || mode !== 'mode2-lzo' || !Buffer.isBuffer(frameEvent?.payload)) return;
+    this.pendingFrames.set(deviceId, {
+      type: 'frame',
+      deviceId,
+      frameSeq: Number(frame.frameSeq || 0),
+      width: Number(frame.width || 0),
+      height: Number(frame.height || 0),
+      uncompressedByteLength: Number(frame.uncompressedByteLength || 0),
+      payload: frameEvent.payload
+    });
+    this.pumpDeviceFrame(deviceId);
+  }
+
+  close() {
+    if (this.closed) return;
+    this.closed = true;
+    clearTimeout(this.restartTimer);
+    this.pendingFrames.clear();
+    this.frameSendsInFlight.clear();
+    const worker = this.worker;
+    this.worker = null;
+    try { worker?.send({ type: 'close' }); } catch {}
+    setTimeout(() => { try { worker?.kill(); } catch {} }, 400).unref?.();
+  }
+}