@appium/coresim 1.3.0 → 1.5.0

package/src/commands/video-stream.ts

@@ -0,0 +1,274 @@
+import {EventEmitter} from 'node:events';
+
+import {logger} from '@appium/support';
+
+import {wrapNativeError} from '../errors.js';
+import type {NativeSimctl} from '../native-simctl.js';
+import type {NativeVideoStreamHandle, VideoAccessUnit, VideoStreamOptions} from '../types.js';
+import {runCatchingAsync} from '../utils/index.js';
+
+declare module '../native-simctl.js' {
+  interface NativeSimctl {
+    startVideoStream(udid: string, options?: VideoStreamOptions): Promise<VideoStream>;
+  }
+}
+
+const log = logger.getLogger('CoreSim');
+
+// Matches the native side's own ThreadSafeFunction queue bound (see coresim.mm's
+// kAccessUnitQueueSize) — kept here too since the native bound alone provides no real
+// backpressure: _handleAccessUnit's emit-equivalent push always returns immediately, regardless of
+// how slow the actual accessUnits() consumer is, so without a bound of its own this queue could
+// otherwise grow without limit while a slow consumer falls behind.
+const MAX_BUFFERED_UNITS = 60;
+
+const SINGLE_CONSUMER_ERROR =
+  'VideoStream.accessUnits() supports only one active consumer at a time — a second concurrent call rejects.';
+
+/** `wrapNativeError` always throws — this just gets its thrown value back as a plain return, to emit rather than raise it. */
+function toTypedError(err: unknown): Error {
+  try {
+    wrapNativeError(err);
+  } catch (wrapped) {
+    return wrapped as Error;
+  }
+}
+
+/**
+ * Single-consumer FIFO between native's per-frame callback and `accessUnits()`. Unlike routing
+ * through `EventEmitter`, a unit pushed before any consumer has started iterating is retained
+ * (fixing the encoder's own first-frame/keyframe otherwise being lost to a startup race) rather
+ * than silently dropped.
+ *
+ * Bounded at `MAX_BUFFERED_UNITS`, but codec-aware about *how* it sheds load once a slow consumer
+ * falls behind: since frames only reference earlier frames they were encoded against (no
+ * `AllowFrameReordering`), dropping an arbitrary interframe would orphan every later one from its
+ * reference chain, corrupting decode from that point on even though delivery looks unbroken.
+ * Overflow instead clears the backlog entirely and enters a resync state, discarding every
+ * further interframe (not buffering them) until the next keyframe — self-decodable on its own —
+ * lets delivery resume cleanly.
+ */
+class AccessUnitQueue {
+  private readonly buffer: VideoAccessUnit[] = [];
+  private waiter:
+    | {resolve: (result: IteratorResult<VideoAccessUnit>) => void; reject: (err: unknown) => void}
+    | undefined;
+  private ended = false;
+  private error: unknown;
+  private resyncing = false;
+
+  /** @param onOverflow — called once when overflow first forces a resync, e.g. to request a fresh keyframe. */
+  constructor(private readonly onOverflow?: () => void) {}
+
+  push(unit: VideoAccessUnit): void {
+    if (this.ended) {
+      return;
+    }
+    if (this.resyncing) {
+      if (!unit.isKeyFrame) {
+        return; // still waiting for a self-decodable point to resume delivery from
+      }
+      this.resyncing = false;
+    }
+    if (this.waiter) {
+      const {resolve} = this.waiter;
+      this.waiter = undefined;
+      resolve({value: unit, done: false});
+      return;
+    }
+    this.buffer.push(unit);
+    if (this.buffer.length > MAX_BUFFERED_UNITS) {
+      this.buffer.length = 0;
+      this.resyncing = true;
+      this.onOverflow?.();
+    }
+  }
+
+  /** Ends the queue with an error — any pending or future `next()` rejects with it. */
+  fail(err: unknown): void {
+    if (this.ended) {
+      return;
+    }
+    this.ended = true;
+    this.error = err;
+    this.buffer.length = 0;
+    if (this.waiter) {
+      const {reject} = this.waiter;
+      this.waiter = undefined;
+      reject(err);
+    }
+  }
+
+  /** Ends the queue cleanly — any pending or future `next()` resolves `done`. */
+  end(): void {
+    if (this.ended) {
+      return;
+    }
+    this.ended = true;
+    this.buffer.length = 0;
+    if (this.waiter) {
+      const {resolve} = this.waiter;
+      this.waiter = undefined;
+      resolve({value: undefined, done: true});
+    }
+  }
+
+  /**
+   * Resolves `done` (not rejects) if `signal` aborts while waiting, mirroring `events.on()`.
+   * Checks cancellation/end *before* dequeuing, so an already-aborted signal or an already-ended
+   * queue never hands out a stale buffered unit — an aborted consumer, or a fresh iterator started
+   * after `stop()`, must see the boundary immediately rather than draining leftovers first.
+   */
+  next(signal: AbortSignal): Promise<IteratorResult<VideoAccessUnit>> {
+    if (signal.aborted) {
+      return Promise.resolve({value: undefined, done: true});
+    }
+    if (this.ended) {
+      return this.error ? Promise.reject(this.error) : Promise.resolve({value: undefined, done: true});
+    }
+    const buffered = this.buffer.shift();
+    if (buffered !== undefined) {
+      return Promise.resolve({value: buffered, done: false});
+    }
+    return new Promise((resolve, reject) => {
+      const onAbort = () => {
+        this.waiter = undefined;
+        resolve({value: undefined, done: true});
+      };
+      signal.addEventListener('abort', onAbort, {once: true});
+      this.waiter = {
+        resolve: (result) => {
+          signal.removeEventListener('abort', onAbort);
+          resolve(result);
+        },
+        reject: (err) => {
+          signal.removeEventListener('abort', onAbort);
+          reject(err);
+        },
+      };
+    });
+  }
+}
+
+/**
+ * A live video stream from `NativeSimctl.startVideoStream` — encodes the device's display in real
+ * time via VideoToolbox, unlike `startVideoRecording`, which drives CoreSimulator's own private,
+ * file-only recorder. Mirrors `appium-ios-remotexpc`'s `ScreenStreamCapture` shape
+ * (`accessUnits()`/`stop()`) for API consistency; the transport is otherwise unrelated.
+ */
+export class VideoStream extends EventEmitter {
+  private handle: NativeVideoStreamHandle | undefined;
+  private readonly stopController = new AbortController();
+  private stopPromise: Promise<void> | undefined;
+  // Requests a fresh keyframe on resync so delivery can resume immediately rather than waiting
+  // for the next periodic one — `handle` may not be attached yet on a startup-time overflow
+  // (vanishingly unlikely given MAX_BUFFERED_UNITS), in which case this is just a no-op.
+  private readonly queue = new AccessUnitQueue(() => this.handle?.requestKeyFrame());
+  private activeConsumers = 0;
+
+  /** @internal */
+  constructor(public readonly codec: 'h264' | 'hevc') {
+    super();
+  }
+
+  /** @internal */
+  _handleAccessUnit(unit: VideoAccessUnit): void {
+    this.queue.push(unit);
+  }
+
+  /**
+   * @internal
+   * An active `accessUnits()` consumer receives the error via the queue itself (thrown out of its
+   * `for await` loop, per that method's contract) rather than the `'error'` event, so `emit` is
+   * only used for an explicit external listener; with neither, it's logged instead of lost.
+   */
+  _handleError(err: unknown): void {
+    const error = toTypedError(err);
+    this.queue.fail(error);
+    if (this.listenerCount('error') > 0) {
+      this.emit('error', error);
+    } else if (this.activeConsumers === 0) {
+      log.error(`Unhandled VideoStream error: ${error.stack ?? error}`);
+    }
+  }
+
+  /** @internal */
+  _attachHandle(handle: NativeVideoStreamHandle): void {
+    this.handle = handle;
+  }
+
+  /**
+   * Yields each encoded access unit as it's produced, until {@link stop} is called or the stream
+   * errors (in which case the error is thrown out of the loop). Pass `signal` to stop iterating
+   * without treating that as an error. Mirrors `ScreenStreamCapture.accessUnits()`'s shape.
+   *
+   * Only one active consumer is supported at a time — a second concurrent call rejects rather
+   * than silently sharing (and corrupting) the first one's single internal waiter slot.
+   */
+  async *accessUnits(signal?: AbortSignal): AsyncGenerator<VideoAccessUnit> {
+    if (this.activeConsumers > 0) {
+      throw new Error(SINGLE_CONSUMER_ERROR);
+    }
+    const combined = signal ? AbortSignal.any([signal, this.stopController.signal]) : this.stopController.signal;
+    this.activeConsumers++;
+    try {
+      for (;;) {
+        const result = await this.queue.next(combined);
+        if (result.done) {
+          return;
+        }
+        yield result.value;
+      }
+    } finally {
+      this.activeConsumers--;
+    }
+  }
+
+  /** Stops the stream and releases the underlying encoder. Idempotent, including concurrently. */
+  async stop(): Promise<void> {
+    this.stopPromise ??= (async () => {
+      this.stopController.abort();
+      this.queue.end();
+      await this.handle?.stop();
+    })();
+    return this.stopPromise;
+  }
+}
+
+/**
+ * Starts encoding the device's display in real time. Resolves once the encoder has actually
+ * started; the returned {@link VideoStream}'s `accessUnits()` then yields each frame as it
+ * arrives. Independent of `startVideoRecording`/`stopVideoRecording` — both, and any number of
+ * concurrent streams, can run on the same device at once.
+ *
+ * @param udid — UDID of the device to stream; must be booted
+ * @param options — `displayId`, `codec`, `fps`, `bitrate` — see {@link VideoStreamOptions}
+ */
+export async function startVideoStream(
+  this: NativeSimctl,
+  udid: string,
+  options: VideoStreamOptions = {},
+): Promise<VideoStream> {
+  // The native poller clamps below 1 fps to 1 fps rather than actually polling that slowly, so a
+  // sub-1 value here would silently poll far more often than requested — rejected instead.
+  if (options.fps !== undefined && (!Number.isFinite(options.fps) || options.fps < 1)) {
+    throw new RangeError(`fps must be a finite number >= 1, got ${options.fps}`);
+  }
+  if (
+    options.bitrate !== undefined &&
+    (!Number.isFinite(options.bitrate) || options.bitrate <= 0 || options.bitrate > 2 ** 31 - 1)
+  ) {
+    throw new RangeError(`bitrate must be a positive number no greater than ${2 ** 31 - 1}, got ${options.bitrate}`);
+  }
+  const device = await runCatchingAsync(() => this._findDevice(udid));
+  const stream = new VideoStream(options.codec === 'hevc' ? 'hevc' : 'h264');
+  const handle = await runCatchingAsync(() =>
+    device.startVideoStream(
+      options,
+      (unit) => stream._handleAccessUnit(unit),
+      (err) => stream._handleError(err),
+    ),
+  );
+  stream._attachHandle(handle);
+  return stream;
+}

package/src/coresim.mm

@@ -10,13 +10,16 @@
 
 #include <napi.h>
 
+#import <AVFoundation/AVFoundation.h>
 #import <Foundation/Foundation.h>
 
 #include <sys/wait.h>
 #include <unistd.h>
 
+#include <algorithm>
 #include <cerrno>
 #include <cstring>
+#include <mutex>
 #include <stdexcept>
 #include <string>
 #include <vector>
@@ -30,6 +33,8 @@
 #include "native/sim_process.h"
 #include "native/sim_screenshot.h"
 #include "native/sim_service_context.h"
+#include "native/sim_video_recording.h"
+#include "native/sim_video_stream.h"
 #include "native/tcc_privacy.h"
 #include "native/value_bridge.h"
 
@@ -95,11 +100,36 @@ NSError* MakeSpawnPathError(NSString* message) {
   return [NSError errorWithDomain:@"com.appium.coresim.spawn" code:1 userInfo:@{NSLocalizedDescriptionKey : message}];
 }
 
+// Standard bin dirs to search, in order, when `path` is a bare command name (no `/`) — mirrors
+// the guest's default $PATH. There's no way to query the guest's actual $PATH (no shell, no env
+// to read before a process even exists), so this is a fixed best-effort list, not a real PATH
+// search — a binary installed somewhere else won't be found this way.
+NSArray<NSString*>* BareCommandSearchDirs() { return @[ @"usr/bin", @"bin", @"usr/sbin", @"sbin", @"usr/local/bin" ]; }
+
+// Resolves a bare command name (e.g. "launchctl") against BareCommandSearchDirs() under
+// `runtimeRoot`, mirroring how `simctl spawn` resolves a bare name against the guest's $PATH —
+// CoreSimulator's own spawn API takes only a literal path, so it does no such resolution itself.
+NSString* ResolveBareCommand(NSString* runtimeRoot, NSString* name, NSError** error) {
+  NSFileManager* fm = [NSFileManager defaultManager];
+  for (NSString* dir in BareCommandSearchDirs()) {
+    NSString* candidate = [runtimeRoot stringByAppendingPathComponent:[dir stringByAppendingPathComponent:name]];
+    BOOL isDirectory = NO;
+    if ([fm fileExistsAtPath:candidate isDirectory:&isDirectory] && !isDirectory &&
+        [fm isExecutableFileAtPath:candidate]) {
+      return candidate;
+    }
+  }
+  *error = MakeSpawnPathError(
+      [NSString stringWithFormat:@"'%@' not found in the Simulator runtime's standard bin directories", name]);
+  return nil;
+}
+
 // `spawnWithPath:options:...` can run anything the host user can execute, so Spawn() confines it
 // to the Simulator's own runtime image rather than trusting `path` as a literal host path — a
-// deliberately breaking restriction (see CLAUDE.md). `path` is resolved as relative to the
-// runtime root, then re-verified (via -stringByStandardizingPath, which collapses ".."/".") to
-// still fall under it, since `path` may come from arbitrary caller input.
+// deliberately breaking restriction (see CLAUDE.md). A bare name (no `/`) is resolved via
+// ResolveBareCommand above instead; otherwise `path` is resolved as relative to the runtime root,
+// then re-verified (via -stringByStandardizingPath, which collapses ".."/".") to still fall under
+// it, since `path` may come from arbitrary caller input.
 NSString* ResolveRuntimeBinaryPath(id device, NSString* path, NSError** error) {
   id runtime = DeviceRuntime(device);
   if (runtime == nil) {
@@ -107,6 +137,9 @@ NSString* ResolveRuntimeBinaryPath(id device, NSString* path, NSError** error) {
     return nil;
   }
   NSString* runtimeRoot = coresim::RuntimeRootPath(runtime).stringByStandardizingPath;
+  if (![path containsString:@"/"]) {
+    return ResolveBareCommand(runtimeRoot, path, error);
+  }
   NSString* resolved = [runtimeRoot stringByAppendingPathComponent:path].stringByStandardizingPath;
   if (resolved != runtimeRoot && ![resolved hasPrefix:[runtimeRoot stringByAppendingString:@"/"]]) {
     *error = MakeSpawnPathError(
@@ -161,10 +194,104 @@ struct AddonInstanceData {
   Napi::FunctionReference deviceConstructor;
   Napi::FunctionReference deviceSetConstructor;
   Napi::FunctionReference serviceContextConstructor;
+  Napi::FunctionReference videoStreamConstructor;
+  // Every VideoStreamSession currently backing a live NativeVideoStream, so the env cleanup hook
+  // below can stop them (and thus release their ThreadSafeFunctions) before Node force-tears-down
+  // this Environment's own TSFNs — see that hook for why this ordering matters.
+  std::mutex activeVideoStreamsMutex;
+  std::vector<std::shared_ptr<coresim::VideoStreamSession>> activeVideoStreams;
 };
 
+void RegisterActiveStream(Napi::Env env, const std::shared_ptr<coresim::VideoStreamSession>& session) {
+  auto* instanceData = env.GetInstanceData<AddonInstanceData>();
+  std::lock_guard<std::mutex> lock(instanceData->activeVideoStreamsMutex);
+  instanceData->activeVideoStreams.push_back(session);
+}
+
+void DeregisterActiveStream(Napi::Env env, const std::shared_ptr<coresim::VideoStreamSession>& session) {
+  auto* instanceData = env.GetInstanceData<AddonInstanceData>();
+  std::lock_guard<std::mutex> lock(instanceData->activeVideoStreamsMutex);
+  auto& streams = instanceData->activeVideoStreams;
+  streams.erase(std::remove(streams.begin(), streams.end(), session), streams.end());
+}
+
+// Stops every still-registered stream, blocking until each has fully torn down (including its own
+// onEnd_ releasing its ThreadSafeFunctions) — see the env cleanup hook this backs, in Init below,
+// for why this must run to completion before returning.
+void StopAllActiveStreams(AddonInstanceData* instanceData) {
+  std::vector<std::shared_ptr<coresim::VideoStreamSession>> streams;
+  {
+    std::lock_guard<std::mutex> lock(instanceData->activeVideoStreamsMutex);
+    streams.swap(instanceData->activeVideoStreams);
+  }
+  for (auto& session : streams) {
+    session->Stop();
+  }
+}
+
 }  // namespace
 
+// Wraps a live coresim::VideoStreamSession. Access units/errors are delivered live via the
+// callbacks passed directly to startVideoStream, not through this object — it only exposes `stop()`.
+class NativeVideoStream : public Napi::ObjectWrap<NativeVideoStream> {
+ public:
+  static void Init(Napi::Env env);
+  static Napi::Object NewInstance(Napi::Env env, std::shared_ptr<coresim::VideoStreamSession> session);
+  explicit NativeVideoStream(const Napi::CallbackInfo& info);
+
+ private:
+  std::shared_ptr<coresim::VideoStreamSession> session_;
+
+  Napi::Value Stop(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+    auto session = session_;
+    return RunAsyncVoid(env, [session]() { session->Stop(); });
+  }
+
+  // Trivial in-memory flag set (see sim_video_stream.h) — no CoreSimulator dispatch, so kept
+  // synchronous like the other pure accessors in this file.
+  Napi::Value RequestKeyFrame(const Napi::CallbackInfo& info) {
+    if (session_) {
+      session_->RequestKeyFrame();
+    }
+    return info.Env().Undefined();
+  }
+
+  // Hands teardown off to a background queue instead of letting the default finalizer run
+  // ~VideoStreamSession()'s blocking Stop() synchronously on whatever thread GC runs on.
+  void Finalize(Napi::Env env) override {
+    auto session = std::move(session_);
+    if (session) {
+      DeregisterActiveStream(env, session);
+      dispatch_async(dispatch_get_global_queue(DISPATCH_QUEUE_PRIORITY_DEFAULT, 0), ^{
+        session->Stop();
+      });
+    }
+  }
+};
+
+NativeVideoStream::NativeVideoStream(const Napi::CallbackInfo& info) : Napi::ObjectWrap<NativeVideoStream>(info) {
+  auto* boxed = info[0].As<Napi::External<std::shared_ptr<coresim::VideoStreamSession>>>().Data();
+  session_ = *boxed;
+  RegisterActiveStream(info.Env(), session_);
+}
+
+void NativeVideoStream::Init(Napi::Env env) {
+  Napi::Function ctor = DefineClass(env, "NativeVideoStream",
+                                    {
+                                        InstanceMethod<&NativeVideoStream::Stop>("stop"),
+                                        InstanceMethod<&NativeVideoStream::RequestKeyFrame>("requestKeyFrame"),
+                                    });
+  env.GetInstanceData<AddonInstanceData>()->videoStreamConstructor = Napi::Persistent(ctor);
+}
+
+Napi::Object NativeVideoStream::NewInstance(Napi::Env env, std::shared_ptr<coresim::VideoStreamSession> session) {
+  auto* boxed = new std::shared_ptr<coresim::VideoStreamSession>(std::move(session));
+  Napi::Function ctor = env.GetInstanceData<AddonInstanceData>()->videoStreamConstructor.Value();
+  return ctor.New({Napi::External<std::shared_ptr<coresim::VideoStreamSession>>::New(
+      env, boxed, [](Napi::Env /*env*/, std::shared_ptr<coresim::VideoStreamSession>* data) { delete data; })});
+}
+
 class NativeDevice : public Napi::ObjectWrap<NativeDevice> {
  public:
   static void Init(Napi::Env env);
@@ -699,6 +826,173 @@ class NativeDevice : public Napi::ObjectWrap<NativeDevice> {
         [](Napi::Env env, NSArray* result) -> Napi::Value { return NSObjectToJsValue(env, result); });
   }
 
+  // Mirrors `simctl io <udid> recordVideo` (see sim_video_recording.mm). Resolves once the first
+  // frame is recorded — see CLAUDE.md for the race hit by calling StopVideoRecording any earlier.
+  Napi::Value StartVideoRecording(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+    id device = device_;
+    NSString* outputFile = @(info[0].As<Napi::String>().Utf8Value().c_str());
+    NSString* displayId = nil;
+    coresim::VideoMaskPolicy mask = coresim::VideoMaskPolicy::kIgnored;
+    NSDictionary* assetWriterOutputSettings = @{};
+    if (info.Length() > 1 && info[1].IsObject()) {
+      Napi::Object options = info[1].As<Napi::Object>();
+      if (options.Has("displayId") && options.Get("displayId").IsString()) {
+        displayId = @(options.Get("displayId").As<Napi::String>().Utf8Value().c_str());
+      }
+      if (options.Has("mask") && options.Get("mask").IsString()) {
+        std::string maskValue = options.Get("mask").As<Napi::String>().Utf8Value();
+        if (maskValue == "alpha") {
+          mask = coresim::VideoMaskPolicy::kAlpha;
+        } else if (maskValue == "black") {
+          mask = coresim::VideoMaskPolicy::kBlack;
+        }
+      }
+      if (options.Has("codec") && options.Get("codec").IsString()) {
+        std::string codecValue = options.Get("codec").As<Napi::String>().Utf8Value();
+        AVVideoCodecType codecType = codecValue == "hevc" ? AVVideoCodecTypeHEVC : AVVideoCodecTypeH264;
+        assetWriterOutputSettings = @{AVVideoCodecKey : codecType};
+      }
+    }
+    return RunAsyncVoid(env, [device, displayId, mask, assetWriterOutputSettings, outputFile]() {
+      dispatch_semaphore_t sema = dispatch_semaphore_create(0);
+      dispatch_queue_t queue = dispatch_queue_create("com.appium.coresim.recordVideo", DISPATCH_QUEUE_SERIAL);
+      __block NSError* capturedError = nil;
+      NSError* resolveError = nil;
+      BOOL ok = coresim::StartVideoRecording(
+          device, displayId, mask, assetWriterOutputSettings, outputFile, queue,
+          ^(NSError* asyncError) {
+            capturedError = asyncError;
+            dispatch_semaphore_signal(sema);
+          },
+          &resolveError);
+      ThrowIfFailed(ok, resolveError);
+      dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
+      if (capturedError != nil) {
+        throw NSErrorException(capturedError);
+      }
+    });
+  }
+
+  // Stops a recording started by StartVideoRecording above. Resolves once the video file has been
+  // finalized on disk and is safe to read.
+  Napi::Value StopVideoRecording(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+    id device = device_;
+    return RunAsyncVoid(env, [device]() {
+      dispatch_semaphore_t sema = dispatch_semaphore_create(0);
+      dispatch_queue_t queue = dispatch_queue_create("com.appium.coresim.stopRecordVideo", DISPATCH_QUEUE_SERIAL);
+      __block NSError* capturedError = nil;
+      NSError* resolveError = nil;
+      BOOL ok = coresim::StopVideoRecording(
+          device, queue,
+          ^(NSError* asyncError) {
+            capturedError = asyncError;
+            dispatch_semaphore_signal(sema);
+          },
+          &resolveError);
+      ThrowIfFailed(ok, resolveError);
+      dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);
+      if (capturedError != nil) {
+        throw NSErrorException(capturedError);
+      }
+    });
+  }
+
+  // Real-time encoding via public VideoToolbox APIs (see sim_video_stream.mm) — no private API,
+  // no file. `onAccessUnit`/`onError` are invoked live for as long as the stream runs; the
+  // returned NativeVideoStream only exposes `stop()`.
+  Napi::Value StartVideoStream(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+    id device = device_;
+    NSString* displayId = nil;
+    coresim::VideoStreamCodec codec = coresim::VideoStreamCodec::kH264;
+    double fps = 15.0;
+    int bitrate = 2000000;
+    if (info.Length() > 0 && info[0].IsObject()) {
+      Napi::Object options = info[0].As<Napi::Object>();
+      if (options.Has("displayId") && options.Get("displayId").IsString()) {
+        displayId = @(options.Get("displayId").As<Napi::String>().Utf8Value().c_str());
+      }
+      if (options.Has("codec") && options.Get("codec").IsString() &&
+          options.Get("codec").As<Napi::String>().Utf8Value() == "hevc") {
+        codec = coresim::VideoStreamCodec::kHEVC;
+      }
+      if (options.Has("fps") && options.Get("fps").IsNumber()) {
+        fps = options.Get("fps").As<Napi::Number>().DoubleValue();
+      }
+      if (options.Has("bitrate") && options.Get("bitrate").IsNumber()) {
+        bitrate = options.Get("bitrate").As<Napi::Number>().Int32Value();
+      }
+    }
+    Napi::Function onAccessUnit = info[1].As<Napi::Function>();
+    Napi::Function onError = info[2].As<Napi::Function>();
+
+    // Must be constructed on the main thread, like Spawn's own exitTsfn above; released exactly
+    // once each, via onEnd (see sim_video_stream.h).
+    //
+    // accessUnitTsfn's queue is bounded, unlike every other one-shot-callback ThreadSafeFunction
+    // in this addon — a slow-draining consumer would otherwise let queued frame buffers grow
+    // unbounded; BlockingCall below naturally throttles the encoder once this fills instead.
+    static constexpr size_t kAccessUnitQueueSize = 60;
+    Napi::ThreadSafeFunction accessUnitTsfn =
+        Napi::ThreadSafeFunction::New(env, onAccessUnit, "coresim video stream access unit", kAccessUnitQueueSize, 1);
+    Napi::ThreadSafeFunction errorTsfn =
+        Napi::ThreadSafeFunction::New(env, onError, "coresim video stream error", 0, 1);
+
+    coresim::VideoStreamOptions options{codec, displayId, fps, bitrate};
+    return RunAsync<std::shared_ptr<coresim::VideoStreamSession>>(
+        env,
+        [device, options, accessUnitTsfn, errorTsfn]() mutable -> std::shared_ptr<coresim::VideoStreamSession> {
+          auto session = std::make_shared<coresim::VideoStreamSession>(
+              device, options,
+              [accessUnitTsfn](coresim::VideoAccessUnit unit) mutable {
+                accessUnitTsfn.BlockingCall([unit = std::move(unit)](Napi::Env env, Napi::Function jsCallback) mutable {
+                  // The Environment can already be mid-teardown by the time a queued callback
+                  // like this one actually runs (e.g. worker.terminate() while frames were still
+                  // piling up) — node-addon-api's own WrapVoidCallback would otherwise re-throw
+                  // whatever escapes here as a JS exception, which itself aborts the process on a
+                  // torn-down env instead of just failing to deliver a frame nothing can receive
+                  // anymore. See CLAUDE.md.
+                  try {
+                    Napi::Object obj = Napi::Object::New(env);
+                    obj.Set("data", Napi::Buffer<uint8_t>::Copy(env, unit.data.data(), unit.data.size()));
+                    obj.Set("isKeyFrame", Napi::Boolean::New(env, unit.isKeyFrame));
+                    obj.Set("sequence", Napi::Number::New(env, static_cast<double>(unit.sequence)));
+                    obj.Set("timestampMicros", Napi::Number::New(env, static_cast<double>(unit.timestampMicros)));
+                    jsCallback.Call({obj});
+                  } catch (...) {
+                  }
+                });
+              },
+              [errorTsfn](NSError* error) mutable {
+                NSErrorException exception(error);
+                errorTsfn.BlockingCall([exception](Napi::Env env, Napi::Function jsCallback) {
+                  // See accessUnitTsfn's callback above.
+                  try {
+                    jsCallback.Call({NSErrorExceptionToJsError(env, exception).Value()});
+                  } catch (...) {
+                  }
+                });
+              },
+              [accessUnitTsfn, errorTsfn]() mutable {
+                accessUnitTsfn.Release();
+                errorTsfn.Release();
+              });
+          try {
+            session->Start();
+          } catch (...) {
+            accessUnitTsfn.Release();
+            errorTsfn.Release();
+            throw;
+          }
+          return session;
+        },
+        [](Napi::Env env, std::shared_ptr<coresim::VideoStreamSession> session) -> Napi::Value {
+          return NativeVideoStream::NewInstance(env, session);
+        });
+  }
+
   // Option dictionary keys for `spawnWithPath:options:...` aren't part of the ObjC runtime
   // metadata this addon resolves selectors from (they're string literals inside CoreSimulator's
   // own implementation) — confirmed by resolving each `SimDeviceSpawnKey*` symbol at runtime via
@@ -884,6 +1178,9 @@ void NativeDevice::Init(Napi::Env env) {
                       InstanceMethod<&NativeDevice::GetWebInspectorSocket>("getWebInspectorSocket"),
                       InstanceMethod<&NativeDevice::Screenshot>("screenshot"),
                       InstanceMethod<&NativeDevice::GetDisplays>("getDisplays"),
+                      InstanceMethod<&NativeDevice::StartVideoRecording>("startVideoRecording"),
+                      InstanceMethod<&NativeDevice::StopVideoRecording>("stopVideoRecording"),
+                      InstanceMethod<&NativeDevice::StartVideoStream>("startVideoStream"),
                       InstanceMethod<&NativeDevice::Spawn>("spawn"),
                   });
   env.GetInstanceData<AddonInstanceData>()->deviceConstructor = Napi::Persistent(ctor);
@@ -1112,10 +1409,19 @@ Napi::Value FrameworkVersionBinding(const Napi::CallbackInfo& info) {
 Napi::Object Init(Napi::Env env, Napi::Object exports) {
   // Runs once per Environment (see AddonInstanceData above) — never shared across a
   // worker_threads instance also `require()`-ing this addon.
-  env.SetInstanceData(new AddonInstanceData());
+  auto* instanceData = new AddonInstanceData();
+  env.SetInstanceData(instanceData);
+  // Node force-releases any ThreadSafeFunctions still outstanding when an Environment (e.g. a
+  // worker_threads Worker) tears down — racing our own release of the same TSFNs (fired
+  // asynchronously from NativeVideoStream::Finalize, or never, if a running stream's JS wrapper
+  // was never explicitly stopped) crashes the process. Cleanup hooks are guaranteed to run before
+  // that automatic TSFN teardown, so stopping every active stream here — synchronously, blocking
+  // until each has released its own TSFNs — establishes the ordering Node itself doesn't.
+  env.AddCleanupHook(StopAllActiveStreams, instanceData);
   NativeDevice::Init(env);
   NativeDeviceSet::Init(env);
   NativeServiceContext::Init(env);
+  NativeVideoStream::Init(env);
   exports.Set("sharedServiceContext", Napi::Function::New(env, SharedServiceContextBinding));
   exports.Set("frameworkVersion", Napi::Function::New(env, FrameworkVersionBinding));
   return exports;

package/src/index.ts

@@ -1,6 +1,7 @@
 export {NativeSimError, NativeSimUnavailableError, NativeSimDispatchError, NativeSimOperationError} from './errors.js';
 export {NativeSimctl} from './native-simctl.js';
 export {SpawnedProcess} from './commands/spawn.js';
+export {VideoStream} from './commands/video-stream.js';
 export type {AppContainerType} from './commands/app.js';
 export type {BiometricName} from './commands/biometric.js';
 export {
@@ -20,4 +21,7 @@ export {
   type SimProcessInfo,
   type SimRuntimeInfo,
   type SpawnOptions,
+  type VideoAccessUnit,
+  type VideoRecordingOptions,
+  type VideoStreamOptions,
 } from './types.js';