@nonstrict/recordkit 0.51.0 → 0.52.0

package/src/RecordKit.ts

@@ -96,6 +96,8 @@ export class RecordKit extends EventEmitter {
   }
 
   /**
+   * A list of Mac displays that can be used for screen recording.
+   *
    * @group Discovery
    */
   async getDisplays(): Promise<Display[]> {
@@ -103,6 +105,8 @@ export class RecordKit extends EventEmitter {
   }
 
   /**
+   * A list of macOS windows that can be used for screen recording.
+   *
    * @group Discovery
    */
   async getWindows(): Promise<Window[]> {
@@ -110,13 +114,18 @@ export class RecordKit extends EventEmitter {
   }
 
   /**
+   * A list of cameras that are connected to the system.
+   *
+   * @param params.includeDeskView - Whether to include Desk View cameras in the results
    * @group Discovery
    */
-  async getCameras(): Promise<Camera[]> {
-    return await this.ipcRecordKit.nsrpc.perform({ type: 'Recorder', action: 'getCameras' }) as Camera[]
+  async getCameras(params?: { includeDeskView?: boolean }): Promise<Camera[]> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'Recorder', action: 'getCameras', params: { includeDeskView: params?.includeDeskView ?? false } }) as Camera[]
   }
 
   /**
+   * A list of microphones that are connected to the system.
+   *
    * @group Discovery
    */
   async getMicrophones(): Promise<Microphone[]> {
@@ -124,6 +133,8 @@ export class RecordKit extends EventEmitter {
   }
 
   /**
+   * A list of iOS devices that are connected to the system.
+   *
    * @group Discovery
    */
   async getAppleDevices(): Promise<AppleDevice[]> {
@@ -131,6 +142,8 @@ export class RecordKit extends EventEmitter {
   }
 
   /**
+   * A list of currently running applications that can be used for screen or audio recording.
+   *
    * @group Discovery
    */
   async getRunningApplications(): Promise<RunningApplication[]> {
@@ -138,6 +151,10 @@ export class RecordKit extends EventEmitter {
   }
 
   /**
+   * Indicates if camera can be used.
+   *
+   * Authorization status that indicates whether the user grants the app permission to capture video.
+   *
    * @group Permissions
    */
   async getCameraAuthorizationStatus(): Promise<AuthorizationStatus> {
@@ -145,6 +162,10 @@ export class RecordKit extends EventEmitter {
   }
 
   /**
+   * Indicates if microphone can be used.
+   *
+   * Authorization status that indicates whether the user grants the app permission to capture audio.
+   *
    * @group Permissions
    */
   async getMicrophoneAuthorizationStatus(): Promise<AuthorizationStatus> {
@@ -152,6 +173,8 @@ export class RecordKit extends EventEmitter {
   }
 
   /**
+   * Indicates if screen can be recorded.
+   *
    * @group Permissions
    */
   async getScreenRecordingAccess(): Promise<boolean> {
@@ -159,6 +182,38 @@ export class RecordKit extends EventEmitter {
   }
 
   /**
+   * Indicates if system audio can be recorded.
+   *
+   * @group Permissions
+   */
+  async getSystemAudioRecordingAccess(): Promise<boolean> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'getSystemAudioRecordingAccess' }) as boolean
+  }
+
+  /**
+   * Indicates if keystroke events of other apps can be recorded via Input Monitoring.
+   *
+   * @group Permissions
+   */
+  async getInputMonitoringAccess(): Promise<boolean> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'getInputMonitoringAccess' }) as boolean
+  }
+
+  /**
+   * Indicates if other apps can be controlled via Accessibility.
+   *
+   * @group Permissions
+   */
+  async getAccessibilityControlAccess(): Promise<boolean> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'getAccessibilityControlAccess' }) as boolean
+  }
+
+  /**
+   * Requests the user's permission to allow the app to capture the camera.
+   *
+   * Prompts the users if this is the first time requesting access, otherwise immediately returns.
+   *
+   * @returns Boolean value that indicates whether the user granted or denied access to your app.
    * @group Permissions
    */
   async requestCameraAccess(): Promise<boolean> {
@@ -166,6 +221,11 @@ export class RecordKit extends EventEmitter {
   }
 
   /**
+   * Requests the user's permission to allow the app to capture the microphone.
+   *
+   * Prompts the users if this is the first time requesting access, otherwise immediately returns.
+   *
+   * @returns Boolean value that indicates whether the user granted or denied access to your app.
    * @group Permissions
    */
   async requestMicrophoneAccess(): Promise<boolean> {
@@ -173,12 +233,64 @@ export class RecordKit extends EventEmitter {
   }
 
   /**
+   * Requests the user's permission to allow the app to capture the screen.
+   *
+   * If this is the first time requesting access, this shows dialog that lets th users open System Settings.
+   * In System Settings, the user can allow the app permission to do screen recording.
+   *
+   * Afterwards, the users needs to restart this app, for the permission to become active in the app.
+   *
    * @group Permissions
    */
   async requestScreenRecordingAccess(): Promise<void> {
     return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'requestScreenRecordingAccess' }) as void
   }
 
+  /**
+   * Requests the user's permission to allow the app to capture system audio.
+   *
+   * If this is the first time requesting access, this shows dialog that lets th users open System Settings.
+   * In System Settings, the user can allow the app permission to do screen recording.
+   *
+   * Afterwards, the users needs to restart this app, for the permission to become active in the app.
+   *
+   * @remarks Currently, system audio recording is currently implemented using ScreenCaptureKit,
+   * which means the users needs to grant screen recording access.
+   *
+   * @group Permissions
+   */
+  async requestSystemAudioRecordingAccess(): Promise<void> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'requestSystemAudioRecordingAccess' }) as void
+  }
+
+  /**
+   * Requests the users's permission to monitor keystrokes of other apps via Input Monitoring.
+   *
+   * If this is the first time requesting access, this shows dialog that lets th users open System Settings.
+   * In System Settings, the user can allow the app permission to monitor other apps.
+   *
+   * Afterwards, the users needs to restart this app, for the permission to become active in the app.
+   *
+   * @group Permissions
+   */
+  async requestInputMonitoringAccess(): Promise<void> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'requestInputMonitoringAccess' }) as void
+  }
+
+  /**
+   * Requests the users's permission to control other apps via Accessibility permissions.
+   *
+   * If this is the first time requesting access, this shows dialog that lets th users open System Settings.
+   * In System Settings, the user can allow the app permission to control apps.
+   *
+   * Afterwards, the users needs to restart this app, for the permission to become active in the app.
+   *
+   * @group Permissions
+   */
+  async requestAccessibilityControlAccess(): Promise<void> {
+    return await this.ipcRecordKit.nsrpc.perform({ type: 'AuthorizationStatus', action: 'requestAccessibilityControlAccess' }) as void
+  }
+
   async createRecorder(
     schema: {
       output_directory?: string
@@ -212,33 +324,82 @@ export type AuthorizationStatus =
   | 'authorized' // Application is authorized to access the hardware.
 
 /**
+ * An external iOS device that can be used for screen recording.
+ * 
  * @group Discovery
  */
 export interface AppleDevice {
+  /** An identifier that uniquely identifies the device. */
   id: string;
+  
+  /** A localized device name for display in the user interface. */
   name: string;
+  
+  /** The model of this device. */
   model_id?: string;
+  
+  /** 
+   * The current availability state of this device.
+   * 
+   * - `available`: Device can be recorded
+   * - `notPaired`: Device cannot be recorded because it is connected but not paired (recovery: "Tap 'Trust' on iPhone")
+   * - `notConnected`: Device cannot be recorded because it is currently not connected (recovery: "Connect via cable")
+   * - `pairedNeedsConnect`: Device cannot be recorded because it is paired but currently not connected (recovery: "(Re-)connect via cable")
+   * - `pairedNeedsReconnect`: Device cannot be recorded because it needs to be reconnected (recovery: "Unplug cable, and reconnect again")
+   */
   availability: 'available' | 'notPaired' | 'notConnected' | 'pairedNeedsConnect' | 'pairedNeedsReconnect'
 }
 
 /**
+ * A running macOS application of which windows or audio can be recorded.
+ * 
  * @group Discovery
  */
 export interface RunningApplication {
+  /** Identifier for this application (process id). */
   id: number; // Int32
+  
+  /** Display name of the application. */
   name?: string;
+  
+  /** Bundle identifier of the application (e.g., "com.apple.Safari"). */
   bundle_identifier?: string;
+  
+  /** 
+   * The current availability state of this application.
+   * 
+   * - `available`: Application can be recorded
+   * - `notRunning`: Application cannot be recorded because it is not (or no longer) running
+   */
   availability: 'available' | 'notRunning'
 }
 
 /**
+ * A camera whose video can be recorded.
+ * 
  * @group Discovery
  */
 export interface Camera {
+  /** An identifier that uniquely identifies the camera. */
   id: string;
+  
+  /** A localized camera name for display in the user interface. */
   name: string;
+  
+  /** The model ID of this camera. */
   model_id: string;
+  
+  /** The manufacturer of this camera. */
   manufacturer: string;
+  
+  /** 
+   * The current availability state of this camera.
+   * 
+   * - `available`: Camera can be recorded
+   * - `lidClosed`: Camera cannot be recorded because the MacBook lid is closed (recovery: "Open MacBook lid")
+   * - `unknownSuspended`: Camera cannot be recorded because it is suspended for some unknown reason (recovery: "Unsuspend camera")
+   * - `notConnected`: Camera cannot be recorded because it is currently not connected (recovery: "Connect camera")
+   */
   availability: 'available' | 'lidClosed' | 'unknownSuspended' | 'notConnected'
 
   /**
@@ -251,35 +412,86 @@ export interface Camera {
 }
 
 /**
+ * A microphone whose audio can be recorded.
+ * 
  * @group Discovery
  */
 export interface Microphone {
+  /** An identifier that uniquely identifies the microphone. */
   id: string;
+  
+  /** A localized microphone name for display in the user interface. */
   name: string;
+  
+  /** The model ID of this microphone. */
   model_id: string;
+  
+  /** The manufacturer of this microphone. */
   manufacturer: string;
+  
+  /** 
+   * The current availability state of this microphone.
+   * 
+   * - `available`: Microphone can be recorded
+   * - `lidClosed`: Microphone cannot be recorded because the MacBook lid is closed (recovery: "Open MacBook lid")
+   * - `unknownSuspended`: Microphone cannot be recorded because it is suspended for some unknown reason (recovery: "Unsuspend microphone")
+   * - `notConnected`: Microphone cannot be recorded because it is currently not connected (recovery: "Connect microphone")
+   */
   availability: 'available' | 'lidClosed' | 'unknownSuspended' | 'notConnected'
 }
 
 /**
+ * A Mac display that can be used for screen recording.
+ * 
  * @group Discovery
  */
 export interface Display {
+  /** An identifier that uniquely identifies this Mac display (CGDirectDisplayID). */
   id: number; // UInt32
+  
+  /** Name of this display. */
   localizedName?: string;
+  
+  /** Frame of the display, relative to the main display. Uses top-left coordinate space. */
   frame: Bounds
+  
+  /** Indicates if this is the main display. */
   isMain: boolean
+  
+  /** 
+   * The current availability state of this display.
+   * 
+   * - `available`: A display can be recorded
+   * - `lidClosed`: A display cannot be recorded, because the MacBook lid is closed (recovery: "Open MacBook lid")
+   * - `notConnected`: A display cannot be screen recorded, because it is currently not connected (recovery: "Connect display")
+   */
+  availability: 'available' | 'lidClosed' | 'notConnected'
 }
 
 /**
+ * A macOS window that can be used for screen recording.
+ * 
  * @group Discovery
  */
 export interface Window {
+  /** An identifier that uniquely identifies this macOS window (CGWindowID). */
   id: number; // UInt32
+  
+  /** Title of the window. */
   title?: string;
+  
+  /** Frame of the window, relative to the main display. Uses top-left coordinate space. */
   frame: Bounds
+  
+  /** 
+   * The level of the window relative to other windows.
+   */
   level: number // Int
+  
+  /** Process ID of the application that owns this window. */
   application_process_id?: number // Int32
+  
+  /** Name of the application that owns this window. */
   application_name?: string
 }
 

package/src/Recorder.ts

@@ -136,6 +136,8 @@ export type RecorderSchemaItem =
   | ApplicationAudioSchema
 
 /**
+ * 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 interface WebcamSchema {
@@ -146,6 +148,8 @@ export interface WebcamSchema {
 }
 
 /**
+ * Creates a recorder item for recording a single display. Output is stored in a RecordKit bundle.
+ * 
  * @group Recording Schemas
  */
 export type DisplaySchema = {
@@ -170,6 +174,8 @@ export type DisplaySchema = {
 }
 
 /**
+ * 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 = {
@@ -192,6 +198,8 @@ export type WindowBasedCropSchema = {
 }
 
 /**
+ * Creates a recorder item for an Apple device screen recording, using the provided deviceID. Output is stored in a RecordKit bundle.
+ * 
  * @group Recording Schemas
  */
 export interface AppleDeviceStaticOrientationSchema {
@@ -206,6 +214,11 @@ export interface AppleDeviceStaticOrientationSchema {
 export type SystemAudioMode = 'exclude' | 'include'
 
 /**
+ * Enumeration specifying the backend to use for system audio recording.
+ * 
+ * - `screenCaptureKit`: Use ScreenCaptureKit for system audio recording.
+ * - `_beta_coreAudio`: This a beta feature, it is not fully implemented yet. Do not use in production. Currently only records single files in .caf format.
+ * 
  * @group Recording Schemas
  */
 export type SystemAudioBackend = 'screenCaptureKit' | '_beta_coreAudio'
@@ -216,6 +229,11 @@ export type SystemAudioBackend = 'screenCaptureKit' | '_beta_coreAudio'
 export type AudioOutputOptionsType = 'singleFile' | 'segmented'
 
 /**
+ * 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.
+ * 
  * @group Recording Schemas
  */
 export type SystemAudioSchema = {
@@ -253,6 +271,8 @@ export type SystemAudioSchema = {
 }
 
 /**
+ * Creates a recorder item for recording the audio of a single application. Output is stored in a RecordKit bundle.
+ * 
  * @group Recording Schemas
  */
 export type ApplicationAudioSchema = {