Class RecordKit

Entry point for the RecordKit SDK, an instance is available as recordkit that can be imported from the module. Do not instantiate this class directly.

Hierarchy

  • EventEmitter
    • RecordKit

Methods

initialize on once off

Device Control

Configure capture devices, such as selecting a camera's active format or fetching an application's icon.

setCameraActiveFormat getCameraBestFormat getApplicationIcon

Discovery

Discover the windows and devices that are available to record.

getDisplays getWindows getCameras getMicrophones getAppleDevices getRunningApplications

Logging

Log what's going on to the console for easy debugging and troubleshooting. See the Logging and Error Handling guide for more information.

setLogLevel setCategoryLogLevel

Permissions

Check and request the apps permission to access the recording devices.

getCameraAuthorizationStatus getMicrophoneAuthorizationStatus getScreenRecordingAccess getSystemAudioRecordingAccess probeSystemAudioRecordingAccess getInputMonitoringAccess getAccessibilityControlAccess requestCameraAccess requestMicrophoneAccess requestScreenRecordingAccess requestSystemAudioRecordingAccess requestInputMonitoringAccess requestAccessibilityControlAccess

Preferred Devices

Read and update the user's preferred devices, so you can pre-select sensible defaults in your UI.

getUserPreferred updatePreferredMicrophone updatePreferredCamera updatePreferredDisplay updatePreferredAppleDevice

Recording

createRecorder

Window Control

Move, resize, center and maximize windows of other applications (requires Accessibility Control permission).

maximizeWindow resizeWindow centerWindow moveWindow

Methods

initialize

  • initialize(args): Promise<void>

  • Initialize the RecordKit SDK.

    ⚠️ Must be called before calling any other RecordKit method.

    Parameters

    • args: {
          rpcBinaryPath: string;
          fallbackToNodeModules?: boolean;
          logLevel?: LogLevel;
      }
      • rpcBinaryPath: string

        Path to the recordkit-rpc binary, most of the time this should be set to path.join(process.resourcesPath, 'recordkit-rpc').

      • Optional fallbackToNodeModules?: boolean

        Whether to fallback to the RPC binary from node_modules if the given path does not exist. When enabled an extra check to see if the given path exists is performed. Most of the time this should be set to !app.isPackaged.

      • Optional logLevel?: LogLevel

        Set the global log level. Defaults to debug.

        This is the same as calling setLogLevel right after initialization.

    Returns Promise<void>

on

  • on(event, listener): this

  • Fires for every log message emitted by RecordKit. See LogMessage.

    Parameters

    • event: "log"
    • listener: ((message) => void)
        • (message): void

        • Parameters

          Returns void

    Returns this

once

  • once(event, listener): this

  • Parameters

    • event: "log"
    • listener: ((message) => void)
        • (message): void

        • Parameters

          Returns void

    Returns this

    See

    RecordKit.on

off

  • off(event, listener): this

  • Parameters

    • event: "log"
    • listener: ((message) => void)
        • (message): void

        • Parameters

          Returns void

    Returns this

    See

    RecordKit.on

Device Control

setCameraActiveFormat

  • setCameraActiveFormat(camera, dimensions): Promise<void>

  • Selects the camera's active capture format that best matches the given dimensions (in pixels).

    Use this when you want the camera to deliver a specific resolution — typically before recording or before showing a live preview, so the preview renders at the intended resolution. The format stays in effect until something else changes it.

    The chosen format is the smallest format whose dimensions are ≥ the target, preferring biplanar YUV pixel formats, and falling back to the largest available format if nothing meets the target.

    Parameters

    • camera: string | Camera

      The camera to configure, either a Camera or its Camera.id.

    • dimensions: Size

      Target dimensions in pixels.

    Returns Promise<void>

    Remarks

    Rejects if the camera is unavailable, has no usable video format, or its configuration is locked by another process.

getCameraBestFormat

  • getCameraBestFormat(camera, dimensions): Promise<undefined | CameraFormat>

  • Returns the camera capture format that setCameraActiveFormat would select for the given dimensions (in pixels), without applying it. Returns undefined if the camera has no suitable format.

    Parameters

    Returns Promise<undefined | CameraFormat>

getApplicationIcon

  • getApplicationIcon(application): Promise<string>

  • Returns the icon of the given running application as a data:image/png;base64,... URL, usable directly as the src of an HTML <img> tag.

    Parameters

    Returns Promise<string>

Discovery

getDisplays

  • getDisplays(): Promise<Display[]>

  • A list of Mac displays that can be used for screen recording.

    Returns Promise<Display[]>

getWindows

  • getWindows(): Promise<Window[]>

  • A list of macOS windows that can be used for screen recording.

    Returns Promise<Window[]>

getCameras

  • getCameras(params?): Promise<Camera[]>

  • A list of cameras that are connected to the system.

    Parameters

    • Optional params: {
          includeDeskView?: boolean;
      }
      • Optional includeDeskView?: boolean

        Whether to include Desk View cameras in the results

    Returns Promise<Camera[]>

getMicrophones

  • getMicrophones(): Promise<Microphone[]>

  • A list of microphones that are connected to the system.

    Returns Promise<Microphone[]>

getAppleDevices

  • getAppleDevices(): Promise<AppleDevice[]>

  • A list of iOS devices that are connected to the system.

    Returns Promise<AppleDevice[]>

getRunningApplications

  • getRunningApplications(): Promise<RunningApplication[]>

  • A list of currently running applications that can be used for screen or audio recording.

    Returns Promise<RunningApplication[]>

Logging

setLogLevel

  • setLogLevel(logLevel): Promise<void>

  • Set the global log level. Defaults to debug.

    Messages with a lower level than this will be ignored and not passed to any log handlers.

    Parameters

    Returns Promise<void>

setCategoryLogLevel

  • setCategoryLogLevel(params): Promise<void>

  • Overrides the global log level for a specific category. Defaults to the global log level.

    Messages in the given category with a lower level than this will be ignored and not passed to any log handlers.

    Parameters

    • params: {
          category: string;
          logLevel?: LogLevel;
      }
      • category: string
      • Optional logLevel?: LogLevel

    Returns Promise<void>

Permissions

getCameraAuthorizationStatus

  • getCameraAuthorizationStatus(): Promise<AuthorizationStatus>

  • Indicates if camera can be used.

    Authorization status that indicates whether the user grants the app permission to capture video.

    Returns Promise<AuthorizationStatus>

getMicrophoneAuthorizationStatus

  • getMicrophoneAuthorizationStatus(): Promise<AuthorizationStatus>

  • Indicates if microphone can be used.

    Authorization status that indicates whether the user grants the app permission to capture audio.

    Returns Promise<AuthorizationStatus>

getScreenRecordingAccess

  • getScreenRecordingAccess(): Promise<boolean>

  • Indicates if screen can be recorded.

    Returns Promise<boolean>

getSystemAudioRecordingAccess

probeSystemAudioRecordingAccess

  • probeSystemAudioRecordingAccess(options?): Promise<boolean>

  • Probes whether system audio can actually be recorded with the given backend by attempting a short silent capture.

    Unlike getSystemAudioRecordingAccess, which reads the recorded permission state, this verifies the permission is truly usable, immediately detecting cases where the OS reports a permission as granted but capture would still fail (e.g. after the user revokes it).

    Parameters

    Returns Promise<boolean>

    Remarks

    If the permission state is still undetermined, this may trigger the system audio permission prompt.

getInputMonitoringAccess

  • getInputMonitoringAccess(): Promise<boolean>

  • Indicates if keystroke events of other apps can be recorded via Input Monitoring.

    Returns Promise<boolean>

getAccessibilityControlAccess

  • getAccessibilityControlAccess(): Promise<boolean>

  • Indicates if other apps can be controlled via Accessibility.

    Returns Promise<boolean>

requestCameraAccess

  • requestCameraAccess(): Promise<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 Promise<boolean>

    Boolean value that indicates whether the user granted or denied access to your app.

requestMicrophoneAccess

  • requestMicrophoneAccess(): Promise<boolean>

  • 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 Promise<boolean>

    Boolean value that indicates whether the user granted or denied access to your app.

requestScreenRecordingAccess

  • requestScreenRecordingAccess(): Promise<void>

  • Requests the user's permission to allow the app to capture the screen.

    Afterwards, the users needs to restart this app, for the permission to become active in the app.

    Returns Promise<void>

requestSystemAudioRecordingAccess

  • requestSystemAudioRecordingAccess(options?): Promise<boolean>

  • Requests the user's permission to allow the app to capture system audio.

    Permission path depends on the selected backend:

    • default and coreAudio: system audio capture permission
    • screenCaptureKit: Screen Recording permission
    • _beta_coreAudio: deprecated alias for coreAudio

    For the screenCaptureKit backend the user must restart the app before the granted permission becomes active. The default and coreAudio backends return the live granted/denied result with no restart required (macOS 14.2+).

    Parameters

    Returns Promise<boolean>

    Boolean value that indicates whether the user granted or denied access to your app.

requestInputMonitoringAccess

  • requestInputMonitoringAccess(): Promise<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.

    Returns Promise<void>

requestAccessibilityControlAccess

  • requestAccessibilityControlAccess(): Promise<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.

    Returns Promise<void>

Preferred Devices

getUserPreferred

  • getUserPreferred(): Promise<UserPreferred>

  • The user's preferred devices for each source type, ordered most-preferred first.

    RecordKit remembers which devices the user last recorded with (unless disabled via the recorder's updatesUserPreferred setting). Use this to pre-select a sensible default device in your UI.

    Returns Promise<UserPreferred>

updatePreferredMicrophone

  • updatePreferredMicrophone(microphone): Promise<void>

  • Records the given microphone as the user's most-preferred microphone.

    Call this whenever the user manually selects a microphone, so it can be pre-selected later via getUserPreferred. The selection moves to the front of UserPreferred.microphoneIDs.

    Parameters

    Returns Promise<void>

updatePreferredCamera

  • updatePreferredCamera(camera): Promise<void>

  • Records the given camera as the user's most-preferred camera.

    Call this whenever the user manually selects a camera, so it can be pre-selected later via getUserPreferred. The selection moves to the front of UserPreferred.cameraIDs.

    Parameters

    Returns Promise<void>

updatePreferredDisplay

  • updatePreferredDisplay(display): Promise<void>

  • Records the given display as the user's most-preferred display.

    Call this whenever the user manually selects a display, so it can be pre-selected later via getUserPreferred. The selection moves to the front of UserPreferred.displayIDs.

    Parameters

    Returns Promise<void>

updatePreferredAppleDevice

  • updatePreferredAppleDevice(device): Promise<void>

  • Records the given Apple device as the user's most-preferred Apple device.

    Call this whenever the user manually selects an Apple device, so it can be pre-selected later via getUserPreferred. The selection moves to the front of UserPreferred.appleDeviceIDs.

    Parameters

    Returns Promise<void>

Recording

createRecorder

  • createRecorder(schema): Promise<Recorder>

  • Creates a Recorder for the given schema.

    The schema describes what to record (its items, e.g. a webcam, display, microphone or system audio), where to write the resulting RecordKit bundle (output_directory), and optional session-wide RecorderSettings. Call Recorder.prepare then Recorder.start on the returned recorder.

    Parameters

    Returns Promise<Recorder>

    Remarks

    The given schema is consumed: device/window objects in its items are replaced by their IDs and any callbacks are registered internally. Pass a fresh schema object per call rather than reusing one.

Window Control

maximizeWindow

  • maximizeWindow(window, options?): Promise<void>

  • Maximizes the given window, resizing it to fill the display's visible area (excluding the menu bar and Dock) and centering it on that display.

    Requires Accessibility Control permission (see getAccessibilityControlAccess).

    Parameters

    • window: number | Window

      The window to maximize, either a Window or its Window.id.

    • Optional options: {
          display?: number | Display;
      }
      • Optional display?: number | Display

        The display to maximize onto, either a Display or its Display.id. Defaults to the window's current display.

    Returns Promise<void>

    Remarks

    Rejects if the window cannot be maximized — typically because Accessibility permission is missing, the target display cannot be found, or the window is minimized or closed.

resizeWindow

  • resizeWindow(window, size, options?): Promise<void>

  • Resizes the given window to the given size (in points), keeping it centered on its display.

    Requires Accessibility Control permission (see getAccessibilityControlAccess).

    Parameters

    • window: number | Window

      The window to resize, either a Window or its Window.id.

    • size: Size

      The new size in points.

    • Optional options: {
          display?: number | Display;
      }
      • Optional display?: number | Display

        The display to center on, either a Display or its Display.id. Defaults to the window's current display.

    Returns Promise<void>

    Remarks

    The requested size is clipped to the display's visible frame if it would be larger. After resizing, the window is re-centered so that a window which could not shrink/grow to the requested size still ends up centered. Rejects if Accessibility permission is missing, the target display cannot be found, or the window is minimized, closed, or does not support resizing.

centerWindow

  • centerWindow(window, options?): Promise<void>

  • Centers the given window within the visible area (excluding the menu bar and Dock) of its display, keeping its current size.

    Requires Accessibility Control permission (see getAccessibilityControlAccess).

    Parameters

    • window: number | Window

      The window to center, either a Window or its Window.id.

    • Optional options: {
          display?: number | Display;
      }
      • Optional display?: number | Display

        The display to center on, either a Display or its Display.id. Defaults to the window's current display.

    Returns Promise<void>

    Remarks

    Rejects if Accessibility permission is missing, the target display cannot be found, or the window is minimized, closed, or does not support moving.

moveWindow

  • moveWindow(window, position): Promise<void>

  • Moves the given window so its top-left corner is at the given position (in points, top-left origin).

    Requires Accessibility Control permission (see getAccessibilityControlAccess).

    Parameters

    • window: number | Window

      The window to move, either a Window or its Window.id.

    • position: {
          x: number;
          y: number;
      }

      The new top-left origin for the window, in points (top-left coordinate space).

      • x: number
      • y: number

    Returns Promise<void>

    Remarks

    Rejects if Accessibility permission is missing, or the window is minimized, closed, or does not support moving.

Settings

Member Visibility

Theme

On This Page

initializeononceoffsetCameraActiveFormatgetCameraBestFormatgetApplicationIcongetDisplaysgetWindowsgetCamerasgetMicrophonesgetAppleDevicesgetRunningApplicationssetLogLevelsetCategoryLogLevelgetCameraAuthorizationStatusgetMicrophoneAuthorizationStatusgetScreenRecordingAccessgetSystemAudioRecordingAccessprobeSystemAudioRecordingAccessgetInputMonitoringAccessgetAccessibilityControlAccessrequestCameraAccessrequestMicrophoneAccessrequestScreenRecordingAccessrequestSystemAudioRecordingAccessrequestInputMonitoringAccessrequestAccessibilityControlAccessgetUserPreferredupdatePreferredMicrophoneupdatePreferredCameraupdatePreferredDisplayupdatePreferredAppleDevicecreateRecordermaximizeWindowresizeWindowcenterWindowmoveWindow

Generated using TypeDoc