screencapturekit/dist/index.d.cts

A nodejs wrapper over a swift CLI program which is a wrapper over ScreenCaptureKit module with HDR and microphone support

import { ExecaChildProcess } from 'execa';

/**
 * Interface defining a cropping area for recording.
 * @typedef {Object} CropArea
 * @property {number} x - The X position of the starting point of the area.
 * @property {number} y - The Y position of the starting point of the area.
 * @property {number} width - The width of the area to capture.
 * @property {number} height - The height of the area to capture.
 */
type CropArea = {
    x: number;
    y: number;
    width: number;
    height: number;
};

type Screen = {
    id: number;
    width: number;
    height: number;
};

type AudioDevice = {
    id: string;
    name: string;
    manufacturer: string;
};

type MicrophoneDevice = AudioDevice;

/**
 * Options for screen recording.
 * @typedef {Object} RecordingOptions
 * @property {number} fps - Frames per second.
 * @property {CropArea} [cropArea] - Area of the screen to capture.
 * @property {boolean} showCursor - Show the cursor in the recording.
 * @property {boolean} highlightClicks - Highlight mouse clicks.
 * @property {number} screenId - Identifier of the screen to capture.
 * @property {string} [audioDeviceId] - Identifier of the system audio device.
 * @property {string} [microphoneDeviceId] - Identifier of the microphone device.
 * @property {string} videoCodec - Video codec to use.
 * @property {boolean} [enableHDR] - Enable HDR recording (on macOS 13.0+).
 * @property {boolean} [recordToFile] - Use the direct recording API (on macOS 14.0+).
 * @property {boolean} [audioOnly] - Record audio only, will convert to mp3 after recording.
 */
type RecordingOptions = {
    fps: number;
    cropArea?: CropArea;
    showCursor: boolean;
    highlightClicks: boolean;
    screenId: number;
    audioDeviceId?: string;
    microphoneDeviceId?: string;
    videoCodec?: string;
    enableHDR?: boolean;
    recordToFile?: boolean;
    audioOnly?: boolean;
};

/**
 * Internal options for recording with ScreenCaptureKit.
 * @typedef {Object} RecordingOptionsForScreenCaptureKit
 * @property {string} destination - URL of the destination file.
 * @property {number} framesPerSecond - Frames per second.
 * @property {boolean} showCursor - Show the cursor in the recording.
 * @property {boolean} highlightClicks - Highlight mouse clicks.
 * @property {number} screenId - Identifier of the screen to capture.
 * @property {string} [audioDeviceId] - Identifier of the system audio device.
 * @property {string} [microphoneDeviceId] - Identifier of the microphone device.
 * @property {string} [videoCodec] - Video codec to use.
 * @property {Array} [cropRect] - Coordinates of the cropping area.
 * @property {boolean} [enableHDR] - Enable HDR recording.
 * @property {boolean} [useDirectRecordingAPI] - Use the direct recording API.
 * @private
 */
type RecordingOptionsForScreenCaptureKit = {
    destination: string;
    framesPerSecond: number;
    showCursor: boolean;
    highlightClicks: boolean;
    screenId: number;
    audioDeviceId?: string;
    microphoneDeviceId?: string;
    videoCodec?: string;
    cropRect?: [[x: number, y: number], [width: number, height: number]];
    enableHDR?: boolean;
    useDirectRecordingAPI?: boolean;
};

/**
 * Main class for screen recording with ScreenCaptureKit.
 * Allows capturing the screen using Apple's native APIs.
 */
declare class ScreenCaptureKit {
    /** Path to the output video file. */
    videoPath: string | null;
    /** The ongoing recording process. */
    recorder?: ExecaChildProcess;
    /** Unique identifier of the recording process. */
    processId: string | null;
    /** Options used for recording */
    private currentOptions?;
    /** Path to the final processed video file */
    processedVideoPath: string | null;
    /**
     * Creates a new instance of ScreenCaptureKit.
     * Checks that the macOS version is compatible (10.13+).
     * @throws {Error} If the macOS version is not supported.
     */
    constructor();
    /**
     * Checks that recording has been started.
     * @throws {Error} If recording has not been started.
     * @private
     */
    throwIfNotStarted(): void;
    /**
     * Starts screen recording.
     * @param {Partial<RecordingOptions>} options - Recording options.
     * @param {number} [options.fps=30] - Frames per second.
     * @param {CropArea} [options.cropArea] - Area of the screen to capture.
     * @param {boolean} [options.showCursor=true] - Show the cursor.
     * @param {boolean} [options.highlightClicks=false] - Highlight mouse clicks.
     * @param {number} [options.screenId=0] - Screen ID to capture.
     * @param {string} [options.audioDeviceId] - System audio device ID.
     * @param {string} [options.microphoneDeviceId] - Microphone device ID.
     * @param {string} [options.videoCodec="h264"] - Video codec to use.
     * @param {boolean} [options.enableHDR=false] - Enable HDR recording.
     * @param {boolean} [options.recordToFile=false] - Use the direct recording API.
     * @returns {Promise<void>} A promise that resolves when recording starts.
     * @throws {Error} If recording is already in progress or if the options are invalid.
     */
    startRecording({ fps, cropArea, showCursor, highlightClicks, screenId, audioDeviceId, microphoneDeviceId, videoCodec, enableHDR, recordToFile, audioOnly, }?: Partial<RecordingOptions>): Promise<unknown>;
    /**
     * Stops the ongoing recording and processes the video to merge audio tracks if needed.
     * @returns {Promise<string|null>} A promise that resolves with the path to the processed video file.
     * @throws {Error} If recording has not been started.
     */
    stopRecording(): Promise<string | null>;
}
/**
 * Creates and returns a new instance of ScreenCaptureKit.
 * @returns {ScreenCaptureKit} A new instance of the screen recorder.
 */
declare function export_default(): ScreenCaptureKit;
/**
 * Specific error for ScreenCaptureKit operations
 */
declare class ScreenCaptureKitError extends Error {
    constructor(message: string);
}
/**
 * Retrieves the list of screens available for recording.
 * @returns {Promise<Screen[]>} A promise that resolves with an array of objects representing the screens.
 * @throws {ScreenCaptureKitError} If screen retrieval fails.
 */
declare const screens: () => Promise<Screen[]>;
/**
 * Retrieves the list of system audio devices available for recording.
 * @returns {Promise<AudioDevice[]>} A promise that resolves with an array of objects representing the audio devices.
 * @throws {ScreenCaptureKitError} If audio device retrieval fails.
 */
declare const audioDevices: () => Promise<AudioDevice[]>;
/**
 * Retrieves the list of microphone devices available for recording.
 * @returns {Promise<MicrophoneDevice[]>} A promise that resolves with an array of objects representing the microphones.
 * @throws {ScreenCaptureKitError} If microphone retrieval fails.
 */
declare const microphoneDevices: () => Promise<MicrophoneDevice[]>;
/**
 * Indicates whether the current system supports HDR capture.
 * @type {boolean}
 */
declare const supportsHDRCapture: boolean;
/**
 * Map of video codecs available on the system.
 * @type {Map<string, string>}
 */
declare const videoCodecs: Map<string, string>;

export { type AudioDevice, type CropArea, type MicrophoneDevice, type RecordingOptions, type RecordingOptionsForScreenCaptureKit, type Screen, ScreenCaptureKit, ScreenCaptureKitError, audioDevices, export_default as default, microphoneDevices, screens, supportsHDRCapture, videoCodecs };