@appium/coresim 1.4.0 → 1.5.0

package/lib/src/types.d.ts

@@ -104,6 +104,51 @@ export interface ScreenshotOptions {
      */
     quality?: number;
 }
+/** Options for `NativeSimctl.startVideoRecording`. */
+export interface VideoRecordingOptions {
+    /**
+     * Which display to record, by `id` from `getDisplays()`. Defaults to the primary display
+     * (falling back to the first renderable display if none is primary, e.g. tvOS).
+     */
+    displayId?: string;
+    /** Video codec — `'h264'` (default) or `'hevc'`. */
+    codec?: 'h264' | 'hevc';
+    /**
+     * For a non-rectangular display (e.g. a Dynamic Island cutout): `'ignored'` (default) saves the
+     * unmasked framebuffer, `'black'` renders the mask black, `'alpha'` is not supported and
+     * behaves like `'black'`.
+     */
+    mask?: 'ignored' | 'alpha' | 'black';
+}
+/** Options for `NativeSimctl.startVideoStream`. */
+export interface VideoStreamOptions {
+    /**
+     * Which display to stream, by `id` from `getDisplays()`. Defaults to the primary display
+     * (falling back to the first renderable display if none is primary, e.g. tvOS).
+     */
+    displayId?: string;
+    /** Video codec — `'h264'` (default) or `'hevc'`. */
+    codec?: 'h264' | 'hevc';
+    /**
+     * Max frames/sec to poll the framebuffer at — an unchanged frame is never re-encoded, so this
+     * is an upper bound, not a guarantee. Must be >= 1. Defaults to 15.
+     */
+    fps?: number;
+    /** Target average bitrate, in bits/sec. Defaults to 2,000,000 (2 Mbps). */
+    bitrate?: number;
+}
+/**
+ * One encoded frame from `VideoStream.accessUnits()` — Annex-B NAL units. A keyframe's `data` has
+ * parameter sets (SPS/PPS, or VPS/SPS/PPS for HEVC) prepended, so it's self-decodable alone.
+ */
+export interface VideoAccessUnit {
+    data: Buffer;
+    isKeyFrame: boolean;
+    /** Monotonically increasing per stream, starting at 0. */
+    sequence: number;
+    /** Microseconds since the stream started. */
+    timestampMicros: number;
+}
 /**
  * Options for `NativeSimctl.spawnProcess`, passed through to CoreSimulator's
  * `spawnWithPath:options:terminationQueue:terminationHandler:error:`. Only keys confirmed
@@ -195,6 +240,21 @@ export interface NativeSpawnResult {
  * mirroring Node's own `ChildProcess` `'exit'` event — exactly one of `code`/`signal` is set.
  */
 export type NativeSpawnExitCallback = (code: number | null, signal: number | null) => void;
+/** Raw shape of an access unit as the native addon delivers it — see {@link VideoAccessUnit}. */
+export interface NativeVideoAccessUnit {
+    data: Buffer;
+    isKeyFrame: boolean;
+    sequence: number;
+    timestampMicros: number;
+}
+export type NativeVideoAccessUnitCallback = (unit: NativeVideoAccessUnit) => void;
+export type NativeVideoErrorCallback = (err: Error) => void;
+/** A live encoder session, wrapped by `coresim.mm`'s `NativeVideoStream` — what `NativeDeviceHandle.startVideoStream()` resolves to. */
+export interface NativeVideoStreamHandle {
+    stop(): Promise<void>;
+    /** Forces the next encoded frame to be a keyframe — trivial in-memory flag, so synchronous. */
+    requestKeyFrame(): void;
+}
 /** A `SimDevice`, wrapped by `coresim.mm`'s `NativeDevice` — what `NativeSimctl`'s `_findDevice()` resolves to. */
 export interface NativeDeviceHandle {
     udid(): string;
@@ -245,6 +305,18 @@ export interface NativeDeviceHandle {
         quality?: number;
     }): Promise<Buffer>;
     getDisplays(): Promise<SimDisplayInfo[]>;
+    startVideoRecording(outputFile: string, options?: {
+        displayId?: string;
+        codec?: 'h264' | 'hevc';
+        mask?: 'ignored' | 'alpha' | 'black';
+    }): Promise<void>;
+    stopVideoRecording(): Promise<void>;
+    startVideoStream(options: {
+        displayId?: string;
+        codec?: 'h264' | 'hevc';
+        fps?: number;
+        bitrate?: number;
+    } | undefined, onAccessUnit: NativeVideoAccessUnitCallback, onError: NativeVideoErrorCallback): Promise<NativeVideoStreamHandle>;
     spawn(path: string, options: SpawnOptions | undefined, onExit: NativeSpawnExitCallback): Promise<NativeSpawnResult>;
 }
 /** A `SimDeviceSet`, wrapped by `coresim.mm`'s `NativeDeviceSet`. */

package/lib/src/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appium/coresim",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Native bindings to CoreSimulator.framework for Apple platform simulator control",
   "bugs": {
     "url": "https://github.com/appium/coresim/issues"

package/src/commands/video-recording.ts

@@ -0,0 +1,128 @@
+import path from 'node:path';
+
+import type {NativeSimctl} from '../native-simctl.js';
+import type {VideoRecordingOptions} from '../types.js';
+import {runCatchingAsync} from '../utils/index.js';
+
+declare module '../native-simctl.js' {
+  interface NativeSimctl {
+    startVideoRecording(udid: string, outputFile: string, options?: VideoRecordingOptions): Promise<void>;
+    stopVideoRecording(udid: string): Promise<void>;
+    isVideoRecording(udid: string): Promise<boolean>;
+  }
+}
+
+// One device's recording lifecycle: `start` is the in-flight (or already-settled)
+// startVideoRecording call, so a concurrent stopVideoRecording can always wait for it to fully
+// resolve before racing it natively. `stop`, once set, is the in-flight native stop call shared by
+// every concurrent stopVideoRecording for this same recording — see stopVideoRecording for why a
+// second one must reuse it rather than issuing its own.
+interface RecordingState {
+  readonly start: Promise<void>;
+  stop?: Promise<void>;
+}
+
+// Tracks which devices currently have an active recording — module-level since the constraint (at
+// most one per device) is CoreSimulator's own, not per-NativeSimctl-instance.
+const activeRecordings = new Map<string, RecordingState>();
+
+/**
+ * Starts recording the device's display to `outputFile` — the native equivalent of `simctl io
+ * <udid> recordVideo`. Resolves once the first frame has actually been recorded, so it's always
+ * safe to call {@link stopVideoRecording} immediately after. Only one recording may be active per
+ * device at a time; starting a second one while the first is still running rejects. Rejects with
+ * `NativeSimUnavailableError` if this CoreSimulator predates the private capture API — confirmed
+ * missing on Xcode 16.4's, present on Xcode 26.5+ (Apple documents no exact version floor).
+ *
+ * @param udid — UDID of the device to record; must be booted
+ * @param outputFile — filesystem path to write the video to; resolved against `process.cwd()` if
+ *   relative, since the native layer requires an absolute path
+ * @param options — `displayId`, `codec`, `mask` — see {@link VideoRecordingOptions}
+ * @throws {Error} if a recording is already in progress for this device
+ */
+export async function startVideoRecording(
+  this: NativeSimctl,
+  udid: string,
+  outputFile: string,
+  options: VideoRecordingOptions = {},
+): Promise<void> {
+  const key = udid.toLowerCase();
+  if (activeRecordings.has(key)) {
+    throw new Error(`A video recording is already in progress for device '${udid}'`);
+  }
+  const absoluteOutputFile = path.resolve(outputFile);
+  const startPromise = runCatchingAsync(async () =>
+    (await this._findDevice(udid)).startVideoRecording(absoluteOutputFile, options),
+  );
+  // Marked before the native call resolves, not after, so a concurrent startVideoRecording for the
+  // same device is rejected immediately instead of racing this one — rolled back below on failure.
+  const state: RecordingState = {start: startPromise};
+  activeRecordings.set(key, state);
+  try {
+    await startPromise;
+  } catch (e) {
+    // Only clear our own entry — a concurrent stopVideoRecording (see below) may already have.
+    if (activeRecordings.get(key) === state) {
+      activeRecordings.delete(key);
+    }
+    throw e;
+  }
+}
+
+/**
+ * Stops a recording previously started by {@link startVideoRecording} on the same device.
+ * Resolves once the video file has been finalized on disk and is safe to read. If `start` is still
+ * in flight (e.g. a concurrent caller stopping as soon as {@link isVideoRecording} turns `true`),
+ * waits for it to settle first — issuing the native stop call any earlier is a silent CoreSimulator
+ * race (see CLAUDE.md).
+ *
+ * Safe to call concurrently or to retry after a failure: every concurrent call for the same
+ * recording shares a single in-flight native stop call rather than each issuing its own (which
+ * could otherwise stop whatever *new* recording has since started on this device instead), and a
+ * failed stop — even one that failed before ever reaching the native recorder, e.g. a transient
+ * device-lookup error — leaves the recording tracked as still active so a retry can reach the
+ * native call rather than the caller losing the ability to stop it at all.
+ *
+ * @param udid — UDID of the device to stop recording
+ * @throws {Error} if no recording is currently in progress for this device
+ */
+export async function stopVideoRecording(this: NativeSimctl, udid: string): Promise<void> {
+  const key = udid.toLowerCase();
+  const state = activeRecordings.get(key);
+  if (!state) {
+    throw new Error(`No video recording is in progress for device '${udid}'`);
+  }
+  try {
+    await state.start;
+  } catch {
+    // start itself failed — its own catch already cleaned up activeRecordings; nothing to stop.
+    throw new Error(`No video recording is in progress for device '${udid}'`);
+  }
+  const stopPromise = (state.stop ??= runCatchingAsync(async () =>
+    (await this._findDevice(udid)).stopVideoRecording(),
+  ));
+  try {
+    await stopPromise;
+  } catch (e) {
+    // Only clear our own attempt, and only if it's still the current one — a future call must be
+    // able to retry the native stop rather than replaying this same rejection forever, but must
+    // not clobber a newer attempt another concurrent caller may have already started instead.
+    if (state.stop === stopPromise) {
+      state.stop = undefined;
+    }
+    throw e;
+  }
+  if (activeRecordings.get(key) === state) {
+    activeRecordings.delete(key);
+  }
+}
+
+/**
+ * Whether a recording started by {@link startVideoRecording} is currently active for this device.
+ * Pure local state — no CoreSimulator dispatch — so this never rejects with a native error.
+ *
+ * @param udid — UDID of the device to check
+ */
+export async function isVideoRecording(this: NativeSimctl, udid: string): Promise<boolean> {
+  return activeRecordings.has(udid.toLowerCase());
+}

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;
+}