@appium/coresim 1.3.0 → 1.5.0

package/src/types.ts

@@ -128,6 +128,54 @@ 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
@@ -230,6 +278,24 @@ export interface NativeSpawnResult {
  */
 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 {
   // Trivial in-memory accessors — kept synchronous on the native side (see coresim.mm), never a
@@ -278,6 +344,16 @@ export interface NativeDeviceHandle {
   getWebInspectorSocket(): Promise<string>;
   screenshot(options?: {format?: 'png' | 'jpeg'; displayId?: string; 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>;
 }