Skip to content

fchevallieratecna/screencapturekit-node

 
 

Repository files navigation

ScreenCaptureKit Node.js

A Node.js wrapper for Apple's ScreenCaptureKit module. This package allows screen recording on macOS with optimal performance using Apple's native APIs.

Features

  • High-performance screen recording
  • HDR (High Dynamic Range) support for macOS 13+ (Ventura)
  • System audio capture
  • Microphone audio capture (macOS 15+)
  • Direct-to-file recording (simplified API for macOS 15+)
  • Post-processing capabilities for audio tracks with FFmpeg
  • Cropping support (capture specific screen areas)
  • Multiple options control (FPS, cursor display, click highlighting)
  • Support for various video codecs (H264, HEVC, ProRes)
  • Listing available screens and audio devices

Requirements

  • macOS 10.13 (High Sierra) or newer
  • Node.js 14 or newer
  • FFmpeg (for post-processing audio tracks)

FFmpeg Installation

FFmpeg is required for post-processing audio tracks. Here's how to install it on different systems:

macOS

Using Homebrew:

brew install ffmpeg

Linux (Debian/Ubuntu)

Using apt package manager:

sudo apt update && sudo apt install ffmpeg

Windows

You have several options:

  1. Using Chocolatey (recommended if you have Chocolatey installed):
choco install ffmpeg
  1. Using the MSI Installer (easiest method):

    • Download the FFmpeg Installer from GitHub
    • Run the MSI file and follow the installation wizard
    • FFmpeg will be automatically added to your system PATH
  2. Manual Installation:

    • Download FFmpeg from ffmpeg.org
    • Extract the archive
    • Add FFmpeg to your system PATH manually

To verify the installation on any system, open a terminal/command prompt and run:

ffmpeg -version

Installation

npm install screencapturekit

Usage

Simple Screen Recording

import createScreenRecorder from 'screencapturekit';

const recorder = createScreenRecorder();

// Start recording
await recorder.startRecording();

// Wait for desired duration...
setTimeout(async () => {
  // Stop recording
  const videoPath = await recorder.stopRecording();
  console.log('Video recorded at:', videoPath);
}, 5000);

Recording with Advanced Options

import createScreenRecorder from 'screencapturekit';

const recorder = createScreenRecorder();

// Start recording with options
await recorder.startRecording({
  fps: 60,
  showCursor: true,
  highlightClicks: true,
  screenId: 0,
  videoCodec: 'h264',
  enableHDR: true, // Enable HDR recording (macOS 13+)
  microphoneDeviceId: 'device-id', // Enable microphone capture (macOS 15+)
  recordToFile: true, // Use direct recording API (macOS 15+)
  cropArea: {
    x: 0,
    y: 0,
    width: 1920,
    height: 1080
  }
});

// Wait...

// Stop recording
const videoPath = await recorder.stopRecording();

List Available Screens

import { screens } from 'screencapturekit';

const availableScreens = await screens();
console.log(availableScreens);

List Audio Devices

import { audioDevices, microphoneDevices } from 'screencapturekit';

// System audio devices
const systemAudio = await audioDevices();
console.log(systemAudio);

// Microphone devices
const mics = await microphoneDevices();
console.log(mics);

Check Support for Features

import { supportsHDRCapture, supportsDirectRecordingAPI, supportsMicrophoneCapture } from 'screencapturekit';

if (supportsHDRCapture) {
  console.log('Your system supports HDR capture');
}

if (supportsDirectRecordingAPI) {
  console.log('Your system supports direct-to-file recording');
}

if (supportsMicrophoneCapture) {
  console.log('Your system supports microphone capture');
}

Recording Options

Option Type Default Description
fps number 30 Frames per second
cropArea object undefined Cropping area {x, y, width, height}
showCursor boolean true Display cursor in recording
highlightClicks boolean false Highlight mouse clicks
screenId number 0 ID of screen to capture
audioDeviceId number undefined System audio device ID
microphoneDeviceId string undefined Microphone device ID (macOS 15+)
videoCodec string 'h264' Video codec ('h264', 'hevc', 'proRes422', 'proRes4444')
enableHDR boolean false Enable HDR recording (macOS 13+)
recordToFile boolean false Use direct recording API (macOS 15+)
audioOnly boolean false Record audio only, will convert to mp3 after recording

Post-processing

When both system audio and microphone are recorded, the library uses FFmpeg to merge these tracks into a single video file. This happens automatically in the stopRecording() method. Make sure you have FFmpeg installed on your system.

Development

npm install
npm run build

Tests

npm test

License

MIT

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Swift 38.5%
  • JavaScript 35.9%
  • TypeScript 25.6%