@nonstrict/recordkit 0.87.1 → 0.97.0

package/src/Recorder.ts

@@ -1,7 +1,8 @@
 import { randomUUID } from "crypto";
 import { NSRPC } from "./NonstrictRPC.js";
 import { EventEmitter } from "events";
-import { AppleDevice, Camera, Display, Microphone, RunningApplication, Window } from "./RecordKit.js";
+import { AppleDevice, Bounds, Camera, Display, Microphone, RunningApplication, Window } from "./RecordKit.js";
+import type { RecordKitErrorCode } from "./Errors.js";
 
 /**
  * Converts RPC audio buffer data to AudioStreamBuffer format
@@ -51,6 +52,22 @@ function convertRPCParamsToAudioStreamBuffer(params: any): AudioStreamBuffer | n
   }
 }
 
+/**
+ * Registers the per-segment callback of a {@link JSONOutputOptions} (if any) as an RPC closure,
+ * replacing the function with the closure target so the options object can be serialized.
+ * @internal
+ */
+function registerJSONOutputSegmentCallback(output: JSONOutputOptions | undefined, rpc: NSRPC, object: Recorder, prefix: string) {
+  if (output && output.output == 'segmented' && output.segmentCallback) {
+    const segmentHandler = output.segmentCallback;
+    (output as any).segmentCallback = rpc.registerClosure({
+      handler: (params) => { segmentHandler(params.path as string) },
+      prefix,
+      lifecycle: object
+    });
+  }
+}
+
 /**
  * @group Recording
  */
@@ -62,9 +79,7 @@ export class Recorder extends EventEmitter {
   static async newInstance(rpc: NSRPC, schema: {
     output_directory?: string
     items: RecorderSchemaItem[]
-    settings?: {
-      allowFrameReordering?: boolean
-    }
+    settings?: RecorderSettings
   }): Promise<Recorder> {
     const target = 'Recorder_' + randomUUID();
     const object = new Recorder(rpc, target);
@@ -98,6 +113,7 @@ export class Recorder extends EventEmitter {
             lifecycle: object
           });
         }
+        registerJSONOutputSegmentCallback(item.inputEventsOutput, rpc, object, 'Display.onInputEventsSegment')
       }
       if (item.type == 'windowBasedCrop') {
         if (typeof item.window != 'number') {
@@ -111,6 +127,21 @@ export class Recorder extends EventEmitter {
             lifecycle: object
           });
         }
+        registerJSONOutputSegmentCallback(item.inputEventsOutput, rpc, object, 'WindowBasedCrop.onInputEventsSegment')
+      }
+      if (item.type == 'desktopIndependentWindow') {
+        if (typeof item.window != 'number') {
+          item.window = item.window.id
+        }
+        if (item.output == 'segmented' && item.segmentCallback) {
+          const segmentHandler = item.segmentCallback;
+          (item as any).segmentCallback = rpc.registerClosure({
+            handler: (params) => { segmentHandler(params.path as string) },
+            prefix: 'DesktopIndependentWindow.onSegment',
+            lifecycle: object
+          });
+        }
+        registerJSONOutputSegmentCallback(item.inputEventsOutput, rpc, object, 'DesktopIndependentWindow.onInputEventsSegment')
       }
       if (item.type == 'appleDeviceStaticOrientation') {
         if (typeof item.device != 'string') {
@@ -202,11 +233,16 @@ export class Recorder extends EventEmitter {
       prefix: 'Recorder.onAbort',
       lifecycle: object
     });
+    const onSignalsChangedInstance = rpc.registerClosure({
+      handler: (params) => { weakRefObject.deref()?.emit('signals', (params as { signals: Signal[] }).signals) },
+      prefix: 'Recorder.onSignalsChanged',
+      lifecycle: object
+    });
 
     await rpc.initialize({
       target,
       type: 'Recorder',
-      params: { schema, onAbortInstance },
+      params: { schema, onAbortInstance, onSignalsChangedInstance },
       lifecycle: object
     });
 
@@ -220,23 +256,164 @@ export class Recorder extends EventEmitter {
     this.target = target;
   }
 
-  async prepare() {
-    await this.rpc.perform({ target: this.target, action: 'prepare' });
+  /**
+   * Prepares the recording session for instant recording, allocating resources and validating the
+   * configuration.
+   *
+   * Preparing ahead of time lets {@link start} begin recording instantly; without it, starting incurs
+   * a setup delay.
+   *
+   * @returns The expected {@link BundleInfo} describing the file assets that will be produced by this
+   * recording, allowing you to inspect the planned output (filenames, asset types, sizes) before
+   * recording starts.
+   */
+  async prepare(): Promise<BundleInfo> {
+    return await this.rpc.perform({ target: this.target, action: 'prepare' }) as BundleInfo;
   }
 
+  /**
+   * Starts recording. If the session was not already {@link prepare}d this performs setup first,
+   * incurring a short delay; call {@link prepare} ahead of time to start instantly.
+   */
   async start() {
     await this.rpc.perform({ target: this.target, action: 'start' });
   }
 
+  /**
+   * Pauses the recording. The capture hardware remains active so recording can be resumed quickly.
+   *
+   * Call {@link resume} to continue recording, or {@link stop} to finish.
+   */
+  async pause() {
+    await this.rpc.perform({ target: this.target, action: 'pause' });
+  }
+
+  /**
+   * Resumes a recording that was previously paused with {@link pause}.
+   */
+  async resume() {
+    await this.rpc.perform({ target: this.target, action: 'resume' });
+  }
+
+  /**
+   * Stops the recording, finalizes the output files, and returns the {@link RecordingResult}
+   * describing the completed bundle. The recorder cannot be reused after stopping.
+   *
+   * @remarks Known limitation: when the recording failed, the returned promise rejects with the
+   * failure but the partial recording result is not available over the RPC bridge (the Swift API
+   * surfaces it as `PartialResultError`). Any partially-written files do remain on disk in the
+   * bundle inside the schema's `output_directory`.
+   */
   async stop(): Promise<RecordingResult> {
     return await this.rpc.perform({ target: this.target, action: 'stop' }) as RecordingResult;
   }
 
+  /**
+   * Cancels the recording and releases its resources without finalizing output. Use this to discard
+   * an in-progress or prepared recording; call {@link stop} instead to keep the result.
+   */
   async cancel() {
     await this.rpc.manualRelease(this.target)
   }
 }
 
+/**
+ * Typed event overloads for {@link Recorder}. Declaration-merges with the class so that
+ * `recorder.on('abort', reason => …)` receives a typed {@link AbortReason} instead of `any`.
+ *
+ * @group Recording
+ */
+export interface Recorder {
+  /** Fires when the recording is aborted by an error or a system interruption. */
+  on(event: 'abort', listener: (reason: AbortReason) => void): this;
+  /** @see {@link Recorder.on} */
+  once(event: 'abort', listener: (reason: AbortReason) => void): this;
+  /** @see {@link Recorder.on} */
+  off(event: 'abort', listener: (reason: AbortReason) => void): this;
+  /** @see {@link Recorder.on} */
+  emit(event: 'abort', reason: AbortReason): boolean;
+
+  /**
+   * Fires whenever the set of active {@link Signal}s changes, with all signals active at that
+   * moment. An empty array means everything is healthy again. Events are asynchronous, so one can
+   * still arrive just after {@link Recorder.stop} resolved; the last one is always an empty array.
+   */
+  on(event: 'signals', listener: (signals: Signal[]) => void): this;
+  /** @see {@link Recorder.on} */
+  once(event: 'signals', listener: (signals: Signal[]) => void): this;
+  /** @see {@link Recorder.on} */
+  off(event: 'signals', listener: (signals: Signal[]) => void): this;
+  /** @see {@link Recorder.on} */
+  emit(event: 'signals', signals: Signal[]): boolean;
+}
+
+/**
+ * Settings that apply to the whole recording session.
+ *
+ * @group Recording
+ */
+export interface RecorderSettings {
+  /**
+   * Specifies if RecordKit is allowed to do frame reordering in video files. Defaults to `true`.
+   *
+   * When enabled, to achieve the best compression some video encoders can reorder frames and
+   * generate B-frames.
+   */
+  allowFrameReordering?: boolean
+  /**
+   * Whether a successful recording updates the user's preferred devices for the sources it used.
+   * Defaults to `true`.
+   *
+   * When enabled, starting a recording sets the devices in the schema as the user's preferred
+   * devices (for the device types that support this).
+   */
+  updatesUserPreferred?: boolean
+  /** Target duration, in whole seconds, of each audio segment when using segmented output. Defaults to `6`. Fractional values are not supported. */
+  audioSegmentDuration?: number
+  /** Target duration, in whole seconds, of each video segment when using segmented output. Defaults to `2`. Fractional values are not supported. */
+  videoSegmentDuration?: number
+  /**
+   * Maximum interval, in seconds, between keyframes in the video stream. Defaults to no forced
+   * interval.
+   *
+   * When set, the encoder places a keyframe at least every this many seconds. The frame-count based
+   * maximum keyframe interval is computed automatically from the video frame rate. When omitted, the
+   * encoder uses its default keyframe-placement heuristic.
+   */
+  keyframeIntervalDuration?: number
+  /**
+   * Free disk space, in bytes, below which a running recording is aborted.
+   * Defaults to `104857600` (100 MB).
+   *
+   * While recording, RecordKit periodically checks the actual available capacity of the volume the
+   * recording is written to (purgeable/opportunistic space is not counted). Shortly after the
+   * available capacity drops below this level the recording is aborted with an
+   * `insufficientDiskSpace` error. Keep it high enough to absorb whatever is still written between
+   * two checks and to leave room to finalize the recording.
+   * Set to `0` to never abort on disk space (record until the disk is full), which may result in a
+   * corrupt recording. A `diskSpaceWarningLevel` keeps being reported either way.
+   *
+   * @see {@link RecorderSettings.diskSpaceWarningLevel}, the higher level that warns instead of
+   * aborting.
+   */
+  diskSpaceAbortLevel?: number
+  /**
+   * Free disk space, in bytes, below which the recording volume counts as running low.
+   * Defaults to `157286400` (150 MB).
+   *
+   * Checked once during `prepare()`, which fails with an `insufficientDiskSpace` error when the
+   * volume is already below it, and then periodically while recording. Dropping below it during a
+   * recording does not interrupt anything, it raises a `lowDiskSpace` {@link Signal} on the
+   * `signals` event so your app can warn the user; the signal clears again once enough space is
+   * freed up.
+   *
+   * Set this higher than `diskSpaceAbortLevel` so there is room to warn before the recording is
+   * aborted at that lower level. Set to `0` to disable both the prepare-time check and the
+   * signal.
+   */
+  diskSpaceWarningLevel?: number
+}
+
 /**
  * @group Recording
  */
@@ -244,6 +421,7 @@ export type RecorderSchemaItem =
   | WebcamSchema
   | DisplaySchema
   | WindowBasedCropSchema
+  | DesktopIndependentWindowSchema
   | AppleDeviceStaticOrientationSchema
   | AppleDeviceSchema
   | SystemAudioSchema
@@ -251,101 +429,302 @@ export type RecorderSchemaItem =
   | MicrophoneSchema
 
 /**
- * Creates a recorder item for a webcam movie file, using the provided microphone and camera. Output is stored in a RecordKit bundle.
+ * A width/height pair. The unit (pixels or points) depends on the consuming API — see the
+ * documentation of the specific method or option that takes this value.
  *
  * @group Recording Schemas
  */
-export type WebcamSchema = {
-  type: 'webcam'
-  camera: Camera | string
-  microphone: Microphone | string
-  /** Video codec for the recording. Defaults to 'h264'. */
-  videoCodec?: VideoCodec
-  preserveActiveCameraConfiguration?: boolean
-  leftAudioChannelOnly?: boolean
-  audioDelay?: number
-  output?: 'singleFile'
-  filename?: string
-} | {
+export interface Size {
+  width: number
+  height: number
+}
+
+/**
+ * Content that can be excluded from a screen recording.
+ *
+ * - `currentProcess`: Exclude the windows of the process hosting the recorder from the recording.
+ * - `screenRecordingIndicator`: Exclude the orange screen-recording indicator from the recording.
+ *
+ * @remarks From Electron the process hosting the recorder is the bundled `recordkit-rpc` helper,
+ * not your app — so `currentProcess` does not exclude your app's own windows. To exclude those,
+ * pass your process IDs (e.g. `process.pid`) via the schema item's `excludedProcessIDs`.
+ *
+ * @group Recording Schemas
+ */
+export type ScreenRecordingExcludeOption = 'currentProcess' | 'screenRecordingIndicator'
+
+/**
+ * Output configuration for JSON sidecar files such as the mouse/keyboard input-event log.
+ *
+ * - `singleFile`: Write all events to a single JSON file (optionally named via `filename`).
+ * - `segmented`: Write events to multiple segmented JSON files; `segmentCallback` is invoked with the
+ *   path of each segment as it is written to disk.
+ *
+ * @group Recording Schemas
+ */
+export type JSONOutputOptions =
+  | { output?: 'singleFile', filename?: string }
+  | { output: 'segmented', filenamePrefix?: string, segmentCallback?: (url: string) => void }
+
+interface WebcamSchemaBase {
   type: 'webcam'
+  /** The camera to record, either a {@link Camera} or its `id`. */
   camera: Camera | string
+  /** The microphone to record alongside the camera, either a {@link Microphone} or its `id`. */
   microphone: Microphone | string
+  /** Caps the output video to at most these dimensions (in pixels), preserving aspect ratio. */
+  maxVideoDimensions?: Size
   /** Video codec for the recording. Defaults to 'h264'. */
   videoCodec?: VideoCodec
+  /**
+   * When `true`, leaves the camera's active format/configuration untouched instead of letting
+   * RecordKit reconfigure the device for the requested recording. Defaults to `false`.
+   */
   preserveActiveCameraConfiguration?: boolean
+  /** Record only the left channel of the microphone (useful for mono lavalier mics). Defaults to `false`. */
   leftAudioChannelOnly?: boolean
+  /** Delay applied to the microphone audio relative to the video, in seconds, to correct lip-sync. Defaults to `0`. */
   audioDelay?: number
-  output: 'segmented'
-  filenamePrefix?: string
-  segmentCallback?: (url: string) => void
+  /** Echo cancellation applied to the microphone audio. Defaults to `'off'`. */
+  echoCancellation?: EchoCancellation
+  /** Background blur applied to the camera video. Defaults to `'off'`. */
+  backgroundBlur?: BackgroundBlur
 }
 
 /**
- * Creates a recorder item for recording a single display. Output is stored in a RecordKit bundle.
+ * Creates a recorder item for a webcam movie file, using the provided microphone and camera. Output is stored in a RecordKit bundle.
  *
  * @group Recording Schemas
  */
-export type DisplaySchema = {
-  type: 'display'
-  display: Display | number // UInt32
-  /** Color space for the recording. Defaults to 'sRGB'. Note: 'displayP3' requires 'hevc' video codec. */
-  colorSpace?: ColorSpace
-  /** Video codec for the recording. Defaults to 'h264'. */
-  videoCodec?: VideoCodec
-  shows_cursor?: boolean
-  mouse_events?: boolean
-  keyboard_events?: boolean
-  include_audio?: boolean
-  output?: 'singleFile'
-  filename?: string
-} | {
+export type WebcamSchema =
+  | (WebcamSchemaBase & {
+      output?: 'singleFile'
+      filename?: string
+    })
+  | (WebcamSchemaBase & {
+      output: 'segmented'
+      filenamePrefix?: string
+      segmentCallback?: (url: string) => void
+    })
+
+/**
+ * Acoustic echo cancellation applied to microphone audio. Captures system/playback audio via Core
+ * Audio process taps and removes it from the microphone signal in real time using WebRTC AEC3.
+ *
+ * - `'off'`: No echo cancellation (default).
+ * - `'aggressive'`: Maximum echo removal at the cost of speech quality — aggressive suppression,
+ *   high-pass filter, and residual echo gate at 16 kHz. Optimized for speech-to-text pipelines where
+ *   echo removal matters more than audio fidelity.
+ * - `'balanced'`: Balanced echo removal that preserves speech quality — balanced suppression with
+ *   high-pass filter but no residual echo gate at 48 kHz. Optimized for recording pipelines where
+ *   audio fidelity is more important than pure echo removal.
+ * - An object for full control over the AEC3 configuration; omitted fields default to the `'balanced'`
+ *   preset.
+ *
+ * @remarks Requires macOS 14.2 or later (Core Audio process taps). On older versions, preparing the
+ * recorder fails with a `configurationNotSupported` error.
+ *
+ * @group Recording Schemas
+ */
+export type EchoCancellation =
+  | 'off'
+  | 'aggressive'
+  | 'balanced'
+  | {
+      /**
+       * Sample rate the echo canceller runs at, in Hz. Defaults to `48000`. 16 kHz is sufficient for
+       * speech-to-text; 48 kHz preserves full audio fidelity.
+       */
+      sampleRate?: 16000 | 32000 | 48000
+      /**
+       * Echo suppression mode. Defaults to `'balanced'`.
+       *
+       * - `'balanced'`: Conservative suppression that allows AEC3's transparent mode (passes audio
+       *   through unchanged when no echo is detected) and protects near-end speech during double-talk.
+       *   Best where speech naturalness matters.
+       * - `'aggressive'`: Disables near-end speech detection so echo is suppressed even during
+       *   double-talk; removes ~2 dB more echo but attenuates speech by 3-5 dB.
+       */
+      suppressionMode?: 'balanced' | 'aggressive'
+      /**
+       * Apply a high-pass filter on the capture signal to remove DC offset and low-frequency noise
+       * that can interfere with the adaptive filter. Defaults to `true`.
+       */
+      highPassFilter?: boolean
+      /**
+       * Apply a post-AEC3 gate that attenuates output when the speaker is active but output is quiet
+       * (likely residual echo, not speech). Catches echo the suppressor misses, at the cost of
+       * occasional clipping of quiet speech. Defaults to `false`.
+       */
+      residualEchoGate?: boolean
+    }
+
+/**
+ * Background blur applied to camera video. The person is segmented from each frame using Apple's
+ * Vision person segmentation and composited over a Gaussian-blurred copy of the background, keeping
+ * the foreground subject sharp while blurring the background.
+ *
+ * - `'off'`: No background blur (default).
+ * - `'balanced'`: Default-quality blur with a moderate background blur radius and soft mask edges.
+ * - `'fast'`: Faster, lower-quality blur for lower-end hardware.
+ * - An object for full control over the Vision-based configuration; omitted fields default to the
+ *   `'balanced'` preset.
+ *
+ * @group Recording Schemas
+ */
+export type BackgroundBlur =
+  | 'off'
+  | 'balanced'
+  | 'fast'
+  | {
+      /**
+       * Trade-off between segmentation speed and accuracy. Defaults to `'balanced'`.
+       *
+       * - `'accurate'`: Best segmentation quality, highest cost.
+       * - `'balanced'`: Default trade-off between quality and cost.
+       * - `'fast'`: Lowest cost, suitable for real-time on lower-end hardware.
+       */
+      quality?: 'accurate' | 'balanced' | 'fast'
+      /**
+       * Sigma for the Gaussian blur applied to the background. Larger values produce a stronger blur;
+       * `0` disables the blur (the background is the original image). Defaults to `10`.
+       */
+      blurRadius?: number
+      /**
+       * Sigma for the Gaussian blur applied to the segmentation mask to soften foreground/background
+       * transitions; `0` keeps the raw mask edges. Defaults to `3`.
+       */
+      featherRadius?: number
+    }
+
+interface DisplaySchemaBase {
   type: 'display'
+  /** The display to record, either a {@link Display} or its numeric id. */
   display: Display | number // UInt32
+  /** Crop rectangle (in points, top-left origin) within the display. Defaults to the full display. */
+  crop?: Bounds
+  /**
+   * Content to exclude from the recording. Defaults to `['currentProcess', 'screenRecordingIndicator']`.
+   * Pass an explicit (possibly empty) array to override the default.
+   */
+  excludeOptions?: ScreenRecordingExcludeOption[]
+  /** Process IDs of applications to exclude from the recording. */
+  excludedProcessIDs?: number[] // Int32
   /** Color space for the recording. Defaults to 'sRGB'. Note: 'displayP3' requires 'hevc' video codec. */
   colorSpace?: ColorSpace
+  /** Minimum interval between frames, in seconds. Caps the frame rate (e.g. `1/30` for 30 fps). Defaults to uncapped. */
+  minimumFrameInterval?: number
+  /** Caps the output video to at most these dimensions (in pixels), preserving aspect ratio. */
+  maxVideoDimensions?: Size
   /** Video codec for the recording. Defaults to 'h264'. */
   videoCodec?: VideoCodec
+  /** Whether to draw the mouse cursor into the recording. Defaults to `true`. */
   shows_cursor?: boolean
+  /** Whether to capture mouse input events into a JSON sidecar file. Defaults to `false`. */
   mouse_events?: boolean
+  /** Whether to capture keyboard input events into a JSON sidecar file. Defaults to `false`. */
   keyboard_events?: boolean
+  /** Output configuration for the mouse/keyboard input-event JSON sidecar files. */
+  inputEventsOutput?: JSONOutputOptions
+  /** Whether to also record the display's audio. Defaults to `false`. */
   include_audio?: boolean
-  output: 'segmented'
-  filenamePrefix?: string
-  segmentCallback?: (url: string) => void
 }
 
 /**
- * Creates a recorder item for recording the initial crop of a window on a display. Output is stored in a RecordKit bundle.
+ * Creates a recorder item for recording a single display. Output is stored in a RecordKit bundle.
  *
  * @group Recording Schemas
  */
-export type WindowBasedCropSchema = {
+export type DisplaySchema =
+  | (DisplaySchemaBase & {
+      output?: 'singleFile'
+      filename?: string
+    })
+  | (DisplaySchemaBase & {
+      output: 'segmented'
+      filenamePrefix?: string
+      segmentCallback?: (url: string) => void
+    })
+
+interface WindowBasedCropSchemaBase {
   type: 'windowBasedCrop'
+  /** The window to record, either a {@link Window} or its numeric id. */
   window: Window | number // UInt32
   /** Color space for the recording. Defaults to 'sRGB'. Note: 'displayP3' requires 'hevc' video codec. */
   colorSpace?: ColorSpace
+  /** Minimum interval between frames, in seconds. Caps the frame rate (e.g. `1/30` for 30 fps). Defaults to uncapped. */
+  minimumFrameInterval?: number
+  /** Caps the output video to at most these dimensions (in pixels), preserving aspect ratio. */
+  maxVideoDimensions?: Size
   /** Video codec for the recording. Defaults to 'h264'. */
   videoCodec?: VideoCodec
+  /** Whether to draw the mouse cursor into the recording. Defaults to `true`. */
   shows_cursor?: boolean
+  /** Whether to capture mouse input events into a JSON sidecar file. Defaults to `false`. */
   mouse_events?: boolean
+  /** Whether to capture keyboard input events into a JSON sidecar file. Defaults to `false`. */
   keyboard_events?: boolean
-  output?: 'singleFile'
-  filename?: string
-} | {
-  type: 'windowBasedCrop'
+  /** Output configuration for the mouse/keyboard input-event JSON sidecar files. */
+  inputEventsOutput?: JSONOutputOptions
+  /** Whether to also record the audio of the window's application. Defaults to `false`. */
+  include_audio?: boolean
+}
+
+/**
+ * Creates a recorder item for recording the initial crop of a window on a display. Output is stored in a RecordKit bundle.
+ *
+ * @group Recording Schemas
+ */
+export type WindowBasedCropSchema =
+  | (WindowBasedCropSchemaBase & {
+      output?: 'singleFile'
+      filename?: string
+    })
+  | (WindowBasedCropSchemaBase & {
+      output: 'segmented'
+      filenamePrefix?: string
+      segmentCallback?: (url: string) => void
+    })
+
+interface DesktopIndependentWindowSchemaBase {
+  type: 'desktopIndependentWindow'
   window: Window | number // UInt32
   /** Color space for the recording. Defaults to 'sRGB'. Note: 'displayP3' requires 'hevc' video codec. */
   colorSpace?: ColorSpace
+  /** Minimum interval between frames, in seconds. Caps the frame rate (e.g. `1/30` for 30 fps). Defaults to uncapped. */
+  minimumFrameInterval?: number
+  /** Caps the output video to at most these dimensions (in pixels), preserving aspect ratio. */
+  maxVideoDimensions?: Size
   /** Video codec for the recording. Defaults to 'h264'. */
   videoCodec?: VideoCodec
   shows_cursor?: boolean
   mouse_events?: boolean
   keyboard_events?: boolean
-  output: 'segmented'
-  filenamePrefix?: string
-  segmentCallback?: (url: string) => void
+  /** Output configuration for the mouse/keyboard input-event JSON sidecar files. */
+  inputEventsOutput?: JSONOutputOptions
+  /** Whether to also record the audio of the window's application. Defaults to `false`. */
+  include_audio?: boolean
 }
 
+/**
+ * Creates a recorder item that records a single window, following it across the desktop independently of
+ * what is drawn on screen (the window can be moved or partially off-screen and is still captured in full).
+ * Output is stored in a RecordKit bundle.
+ *
+ * @remarks Requires macOS 13.1 or later.
+ * @group Recording Schemas
+ */
+export type DesktopIndependentWindowSchema =
+  | (DesktopIndependentWindowSchemaBase & {
+      output?: 'singleFile'
+      filename?: string
+    })
+  | (DesktopIndependentWindowSchemaBase & {
+      output: 'segmented'
+      filenamePrefix?: string
+      segmentCallback?: (url: string) => void
+    })
+
 /**
  * Creates a recorder item for an Apple device screen recording, using the provided deviceID. Output is stored in a RecordKit bundle.
  *
@@ -418,10 +797,14 @@ export type MicrophoneOutputOptionsType = 'singleFile' | 'segmented' | 'stream'
 
 /**
  * Creates a recorder item for recording system audio. By default current process audio is excluded. Output is stored in a RecordKit bundle.
- * 
+ *
  * When using `mode: 'exclude'`, all system audio is recorded except for excluded applications.
  * When using `mode: 'include'`, only audio from specified applications is recorded.
- * 
+ *
+ * @remarks The default `excludeOptions: ['currentProcess']` refers to the process hosting the
+ * recorder — from Electron that is the bundled `recordkit-rpc` helper, which plays no audio. To
+ * exclude your own app's audio, pass its process IDs via `excludedProcessIDs`.
+ *
  * @group Recording Schemas
  */
 export type SystemAudioSchema = {
@@ -502,33 +885,37 @@ export type ApplicationAudioSchema = {
   streamCallback?: (audioBuffer: AudioStreamBuffer) => void
 }
 
+interface MicrophoneSchemaCommon {
+  type: 'microphone'
+  microphone: Microphone | string
+  /** Echo cancellation applied to the microphone audio. Defaults to `'off'`. */
+  echoCancellation?: EchoCancellation
+}
+
 /**
  * Creates a recorder item for an audio file, using the provided microphone. Output is stored in a RecordKit bundle.
- * 
+ *
  * @group Recording Schemas
  */
-export type MicrophoneSchema = {
-  type: 'microphone'
-  microphone: Microphone | string
-  leftChannelOnly?: boolean
-  audioDelay?: number
-  output?: 'singleFile'
-  filename?: string
-} | {
-  type: 'microphone'
-  microphone: Microphone | string
-  leftChannelOnly?: boolean
-  audioDelay?: number
-  output: 'segmented'
-  filenamePrefix?: string
-  segmentCallback?: (url: string) => void
-} | {
-  type: 'microphone'
-  microphone: Microphone | string
-  output: 'stream'
-  /** Called with real-time audio buffer data compatible with Web Audio API */
-  streamCallback?: (audioBuffer: AudioStreamBuffer) => void
-}
+export type MicrophoneSchema =
+  | (MicrophoneSchemaCommon & {
+      leftChannelOnly?: boolean
+      audioDelay?: number
+      output?: 'singleFile'
+      filename?: string
+    })
+  | (MicrophoneSchemaCommon & {
+      leftChannelOnly?: boolean
+      audioDelay?: number
+      output: 'segmented'
+      filenamePrefix?: string
+      segmentCallback?: (url: string) => void
+    })
+  | (MicrophoneSchemaCommon & {
+      output: 'stream'
+      /** Called with real-time audio buffer data compatible with Web Audio API */
+      streamCallback?: (audioBuffer: AudioStreamBuffer) => void
+    })
 
 /**
  * Audio buffer compatible with Web Audio API
@@ -547,13 +934,54 @@ export interface AudioStreamBuffer {
 }
 
 
+/**
+ * A condition detected during a recording that might need the user's attention.
+ *
+ * Unlike an {@link AbortReason} a signal never ends the recording, it reports something being off
+ * while recording continues, so your app can warn the user and let them fix it. A signal stays in
+ * the list emitted on the `signals` event for as long as the condition holds.
+ *
+ * @group Recording
+ */
+export interface Signal {
+  /** The kind of condition that was detected. */
+  kind: SignalKind
+  // The only signal reported today concerns the recording as a whole, so no source is ever sent.
+  // The audio signals are what will populate this, along with the SignalSource type below:
+  //   /** What the signal is about, omitted when it concerns the recording as a whole. */
+  //   source?: SignalSource
+}
+
+/**
+ * The kind of condition a {@link Signal} reports.
+ *
+ * @group Recording
+ */
+export type SignalKind =
+  // Waiting on the audio signals, kept here so the shape is settled:
+  //   /** The recorded audio is silent, or so quiet it is very likely unusable. */
+  //   | 'audioSilence'
+  /**
+   * Free space on the recording volume dropped below
+   * {@link RecorderSettings.diskSpaceWarningLevel}. The recording continues, but keeps eating into
+   * the space that is left; below {@link RecorderSettings.diskSpaceAbortLevel} it is aborted with
+   * an `insufficientDiskSpace` error instead. A paused recording is never aborted, since nothing is
+   * being written; it is reported on and aborts after resuming.
+   */
+  | 'lowDiskSpace'
+
+// The part of the recording a Signal originated from. No cases yet, and TypeScript has no empty
+// union, so it stays commented out until the audio signals land:
+//   export type SignalSource =
+//     | { type: 'microphone'; id: string; }
+
 /**
  * @group Recording
  */
 export type AbortReason =
   | { reason: 'userStopped'; result: RecordingResult; }
-  | { reason: 'interrupted'; result: RecordingResult; error: any; }
-  | { reason: 'failed'; error: any; }
+  | { reason: 'interrupted'; result: RecordingResult; error: RecordKitError | NSErrorPayload; }
+  | { reason: 'failed'; result: RecordingResult; error: RecordKitError | NSErrorPayload; }
 
 /**
  * @group Recording
@@ -570,9 +998,9 @@ export interface RecordingResult {
  */
 export interface RecordKitError {
   name: "RecordKitError"
-  /** Error code, used for grouping related errors */
-  code: string
-  /** Error code number */
+  /** Error code, used for grouping related errors. See {@link RecordKitErrorCode} for the full list of codes. */
+  code: RecordKitErrorCode
+  /** Error code number. See {@link RECORDKIT_ERROR_CODE_NUMBERS}. */
   codeNumber: number
   /** Message describing the problem and possible recovery options, intended to be shown directly to the end-user. */
   message: string
@@ -581,12 +1009,62 @@ export interface RecordKitError {
 }
 
 /**
+ * An error produced outside RecordKit's own error domain — a raw `NSError` surfaced over the bridge.
+ *
+ * Distinguished from {@link RecordKitError} by its `name` discriminator. See the
+ * [Logging and Error Handling guide](https://recordkit.dev/guides/logging-and-errors#error-handling).
+ *
+ * @group Recording
+ */
+export interface NSErrorPayload {
+  name: "NSError"
+  /** The `NSError` domain (e.g. `"NSOSStatusErrorDomain"`). */
+  errorDomain: string
+  /** The `NSError` code within {@link NSErrorPayload.errorDomain}. */
+  errorCode: number
+  /** Localized, user-facing description of the error. */
+  message: string
+  /** Detailed technical description of this error, used in debugging. */
+  debugDescription: string
+}
+
+/**
+ * An error raised by the RPC bridge itself rather than by a RecordKit recording — for example
+ * calling a method on a recorder that was already cancelled, requesting a feature that needs a
+ * newer macOS version, or referencing a window or camera that cannot be found.
+ *
+ * Distinguished from {@link RecordKitError} and {@link NSErrorPayload} by its `name` discriminator.
+ *
+ * @group Recording
+ */
+export interface RPCErrorPayload {
+  name: "RPCError"
+  /** Message describing the problem, intended to be shown directly to the end-user. */
+  message: string
+  /** The same message as {@link RPCErrorPayload.message}, kept under its legacy field name. */
+  userMessage: string
+  /** Detailed technical description of this error, used in debugging. */
+  debugDescription: string
+}
+
+/**
+ * Describes a recording bundle's contents (the parsed `recordkit.json`). Mirrors the Swift
+ * `RKBundleInfo`; the per-event sidecar types live in `RecordingMetadata.ts`.
+ *
  * @group Recording
  */
 export interface BundleInfo {
   version: 1,
+  /** Total duration of the recording, in seconds. */
+  duration: number,
   files: {
     type: 'screen' | 'webcam' | 'audio' | 'mouse' | 'systemAudio' | 'appleDevice' | 'topWindow'
     filename: string
+    /** Filenames of related sidecar files for this asset (e.g. input-event JSON), relative to the bundle. */
+    related?: string[]
+    /** Logical size of the recorded area, in points (e.g. `2560x1440` for a Retina 5K display). */
+    recordingSize?: { width: number, height: number }
+    /** Dimensions of the output video, in pixels. */
+    videoDimensions?: { width: number, height: number }
   }[]
 }