custom-mac-screen-share

Bindings for macOS ScreenCaptureKit with enhanced security features.

Based on @indutny/mac-screen-share with security improvements.

Security Enhancements

This fork includes critical security fixes:

• ✅ Input validation - Width, height, and frameRate are validated to prevent DoS attacks
• ✅ Integer overflow protection - Buffer size calculations are checked for overflow
• ✅ Graceful error handling - Invalid frames are skipped instead of crashing the process
• ✅ Deadlock prevention - 30-second timeout on frame processing to prevent hangs
• ✅ Thread safety - Improved synchronization for buffer access

Installation

npm install custom-mac-screen-share

Requirements: macOS 15.0 or later

Usage

import { Stream } from 'custom-mac-screen-share';

const stream = new Stream({
  width: 1024, // Valid range: 1-7680
  height: 768, // Valid range: 1-4320
  frameRate: 10, // Valid range: 1-120

  onStart() {},
  onStop(error) {},
  onFrame(frame, width, height) {
    // Frame is in Nv12 encoding (YUV 4:2:0 format)
    // frame: Buffer containing the raw video data
    // width, height: actual frame dimensions
  },
});

// Later
stream.stop();

API Reference

new Stream(options)

Creates a new screen capture stream and opens the native macOS picker.

Options:

• width (number, required): Output width in pixels (1-7680)
• height (number, required): Output height in pixels (1-4320)
• frameRate (number, required): Target frame rate (1-120 fps)
• onStart (function, required): Called when capture starts after user selection
• onStop (function, required): Called when capture stops, receives optional error
• onFrame (function, required): Called for each captured frame with (buffer, width, height)

Stream.stop()

Stops the screen capture stream.

isSupported

Boolean indicating whether ScreenCaptureKit is available on the current system.

LICENSE

This software is licensed under the MIT License.