node-mac-recorder 2.23.0 → 2.23.1

package/AGENTS.md

@@ -0,0 +1,192 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## Project Overview
+
+**ELECTRON-FIRST PRIORITY**: node-mac-recorder is a Node.js native addon specifically designed and optimized for Electron.js applications. It provides macOS screen recording capabilities using ScreenCaptureKit (macOS 15+) and AVFoundation (macOS 13+). The package allows recording of full screens, specific windows, or custom areas, with support for multi-display setups, audio capture, and cursor tracking.
+
+### **🚀 CRITICAL: Electron.js Support**
+This module is **PRIMARILY BUILT FOR ELECTRON.JS**. All features work seamlessly in Electron applications without any restrictions. Both ScreenCaptureKit and AVFoundation are fully supported in Electron environments.
+
+## Build System & Commands
+
+### Building the Native Module
+
+```bash
+npm run build      # Build the native module using node-gyp
+npm run rebuild    # Clean rebuild of the native module
+npm run clean      # Clean build artifacts
+npm install        # Runs install.js which builds the module automatically
+```
+
+### Testing
+
+```bash
+npm test           # Run the main test suite (test.js)
+node cursor-test.js # Test cursor tracking functionality only
+node test.js       # Run comprehensive API tests
+```
+
+### Development
+
+The package uses node-gyp for building the native C++/Objective-C module. Requires:
+
+- macOS 10.15+ (Catalina or later)
+- Xcode Command Line Tools
+- Node.js 14+
+
+## Architecture
+
+### Core Components
+
+**Main Entry Point**
+
+- `index.js` - Main MacRecorder class (EventEmitter-based)
+- Handles all high-level recording operations and coordinate transformations
+
+**Native Module** (`src/`)
+
+- `mac_recorder.mm` - Main native module entry point and N-API bindings
+- `screen_capture.mm` - AVFoundation-based screen/window recording
+- `audio_capture.mm` - Audio device enumeration and capture
+- `cursor_tracker.mm` - Real-time cursor position and event tracking
+
+**Build Configuration**
+
+- `binding.gyp` - Native module build configuration
+- Links against AVFoundation, ScreenCaptureKit, AppKit, and other macOS frameworks
+
+### Key Features
+
+1. **Multi-Display Support**: Automatic display detection and coordinate conversion
+2. **Window Recording**: Smart window detection with thumbnail generation
+3. **Audio Control**: Separate microphone and system audio controls with device selection
+4. **Cursor Tracking**: Real-time cursor position, type, and click event capture
+5. **Permission Management**: Built-in macOS permission checking and requesting
+
+### Coordinate System Handling
+
+The package handles complex multi-display coordinate transformations:
+
+- Global macOS coordinates (can be negative for secondary displays)
+- Display-relative coordinates (always positive, 0-based)
+- Automatic window-to-display mapping for recording
+
+## API Structure
+
+### Main Class Methods
+
+- `startRecording(outputPath, options)` - Begin screen/window recording
+- `stopRecording()` - Stop recording and finalize video file
+- `getWindows()` - List all recordable application windows
+- `getDisplays()` - Get all available displays with metadata
+- `getAudioDevices()` - Enumerate available audio input devices
+- `checkPermissions()` - Verify macOS recording permissions
+
+### Cursor Tracking
+
+- `startCursorCapture(filepath, options)` - Begin real-time cursor tracking to JSON
+  - `options.windowInfo` - Window information for window-relative coordinates
+  - `options.windowRelative` - Set to true for window-relative coordinates
+- `stopCursorCapture()` - Stop tracking and close output file
+- `getCursorPosition()` - Get current cursor position and state
+
+### Events
+
+The MacRecorder class emits the following events:
+
+- `recordingStarted` - Emitted immediately when recording starts with recording details
+- `started` - Emitted when recording is confirmed started (legacy event)
+- `stopped` - Emitted when recording stops
+- `completed` - Emitted when recording file is finalized
+- `timeUpdate` - Emitted every second with elapsed time
+- `cursorCaptureStarted` - Emitted when cursor capture begins
+- `cursorCaptureStopped` - Emitted when cursor capture ends
+
+### Thumbnails
+
+- `getWindowThumbnail(windowId, options)` - Capture window preview image
+- `getDisplayThumbnail(displayId, options)` - Capture display preview image
+
+## Development Notes
+
+### Testing Strategy
+
+- Use `npm test` for full API validation
+- `cursor-test.js` for testing cursor tracking specifically
+- Test files create output in `test-output/` directory
+
+### Common Development Patterns
+
+- All recording operations are Promise-based
+- Event emission for recording state changes (`recordingStarted`, `started`, `stopped`, `completed`)
+- `recordingStarted` event provides immediate notification with recording details
+- Automatic permission checking before operations
+- Error handling with descriptive messages for permission issues
+- Cursor tracking supports multiple coordinate systems:
+  - Global coordinates (default)
+  - Display-relative coordinates (when recording)
+  - Window-relative coordinates (with windowInfo parameter)
+
+### Platform Requirements & Framework Selection
+
+**ELECTRON-FIRST ARCHITECTURE:**
+- **Primary Target**: Electron.js applications (full support, no restrictions)
+- **Secondary**: Node.js standalone applications
+- macOS only (enforced in install.js)
+- Native module compilation required on install
+- Requires screen recording and accessibility permissions
+
+**Framework Selection Logic (Electron Priority):**
+- **macOS 15+ + Electron**: ScreenCaptureKit with full capabilities
+- **macOS 15+ + Node.js**: ScreenCaptureKit with full capabilities  
+- **macOS 14 + Electron**: AVFoundation with full capabilities
+- **macOS 13 + Electron**: AVFoundation with limited features
+- **macOS 14 + Node.js**: AVFoundation with full capabilities
+- **macOS 13 + Node.js**: AVFoundation with limited features
+
+### File Outputs
+
+- Video recordings: `.mov` format (H.264/AAC)
+- Cursor data: JSON format with timestamped events
+  - `x`, `y`: Cursor coordinates (coordinate system dependent)
+  - `timestamp`: Time from capture start (ms)
+  - `unixTimeMs`: Unix timestamp
+  - `cursorType`: macOS cursor type
+  - `type`: Event type (move, click, etc.)
+  - `coordinateSystem`: "global", "display-relative", or "window-relative"
+  - `windowInfo`: Window metadata (when using window-relative coordinates)
+- Thumbnails: Base64-encoded PNG data URIs
+
+## Troubleshooting
+
+### Build Issues
+
+1. Ensure Xcode Command Line Tools: `xcode-select --install`
+2. Clean rebuild: `npm run clean && npm run build`
+3. Check Node.js version compatibility (14+)
+
+### Runtime Issues
+
+1. Permission failures: Check System Preferences > Security & Privacy
+2. Recording failures: Verify target windows/displays are accessible
+3. Audio issues: Check audio device availability and permissions
+
+### Native Module Loading
+
+The module tries loading from `build/Release/` first, then falls back to `build/Debug/` with helpful error messages if neither exists.
+
+### **⚡ CRITICAL IMPLEMENTATION NOTES**
+
+**ELECTRON.JS IS THE PRIMARY TARGET:**
+1. **No Electron Restrictions**: All Electron detection logic is for optimization, NOT blocking
+2. **Framework Support**: Both ScreenCaptureKit and AVFoundation work perfectly in Electron
+3. **Environment Detection**: Code detects Electron to provide enhanced logging and optimization
+4. **macOS Compatibility**: 
+   - macOS 15+ (Sequoia+): Use ScreenCaptureKit for best performance
+   - macOS 14 (Sonoma): Use AVFoundation with full feature set
+   - macOS 13 (Ventura): Use AVFoundation with basic features
+5. **Error Handling**: Any "Recording failed to start" errors should trigger fallback logic, never blocking
+
+**NEVER BLOCK ELECTRON ENVIRONMENTS** - This is a core design principle.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "node-mac-recorder",
-	"version": "2.23.0",
+	"version": "2.23.1",
 	"description": "Native macOS screen recording package for Node.js applications",
 	"main": "index.js",
 	"keywords": [

package/src/avfoundation_recorder.mm

@@ -25,6 +25,7 @@ static int64_t g_avFrameNumber = 0;
 static CMTime g_avStartTime;
 static void* g_avAudioRecorder = nil;
 static NSString* g_avAudioOutputPath = nil;
+static const NSInteger kAVFoundationHighQualityVideoBitrate = 50 * 1000 * 1000;
 
 // AVFoundation screen recording implementation
 extern "C" bool startAVFoundationRecording(const std::string& outputPath,
@@ -133,52 +134,52 @@ extern "C" bool startAVFoundationRecording(const std::string& outputPath,
                 normalizedQuality = @"high";
             }
         }
-        BOOL useProRes = [normalizedQuality isEqualToString:@"high"];
-
         double fps = requestedFrameRate > 0 ? requestedFrameRate : 60.0;
         if (fps < 1.0) fps = 1.0;
         if (fps > 120.0) fps = 120.0;
 
-        NSDictionary *videoSettings = nil;
-        if (useProRes) {
-            MRLog(@"🎬 AVFoundation encoder (high): %dx%d, codec=ProRes 422 HQ",
-                  (int)recordingSize.width, (int)recordingSize.height);
-            videoSettings = @{
-                AVVideoCodecKey: AVVideoCodecTypeAppleProRes422HQ,
-                AVVideoWidthKey: @((int)recordingSize.width),
-                AVVideoHeightKey: @((int)recordingSize.height)
-            };
-        } else {
-            NSString *codecKey = AVVideoCodecTypeH264;
-            NSInteger multiplier = [normalizedQuality isEqualToString:@"medium"] ? 18 : 10;
-            NSInteger minBitrate = [normalizedQuality isEqualToString:@"medium"] ? (18 * 1000 * 1000) : (10 * 1000 * 1000);
-            NSInteger maxBitrate = [normalizedQuality isEqualToString:@"medium"] ? (80 * 1000 * 1000) : (45 * 1000 * 1000);
-            NSInteger bitrate = (NSInteger)(recordingSize.width * recordingSize.height * multiplier);
+        NSString *codecKey = AVVideoCodecTypeH264;
+        NSInteger bitrate = kAVFoundationHighQualityVideoBitrate;
+        NSNumber *qualityHint = @1.0;
+
+        if ([normalizedQuality isEqualToString:@"low"]) {
+            NSInteger multiplier = 10;
+            NSInteger minBitrate = 10 * 1000 * 1000;
+            NSInteger maxBitrate = 45 * 1000 * 1000;
+            bitrate = (NSInteger)(recordingSize.width * recordingSize.height * multiplier);
+            bitrate = MAX(bitrate, minBitrate);
+            bitrate = MIN(bitrate, maxBitrate);
+            qualityHint = @0.85;
+        } else if ([normalizedQuality isEqualToString:@"medium"]) {
+            NSInteger multiplier = 18;
+            NSInteger minBitrate = 18 * 1000 * 1000;
+            NSInteger maxBitrate = 80 * 1000 * 1000;
+            bitrate = (NSInteger)(recordingSize.width * recordingSize.height * multiplier);
             bitrate = MAX(bitrate, minBitrate);
             bitrate = MIN(bitrate, maxBitrate);
-            NSNumber *qualityHint = [normalizedQuality isEqualToString:@"medium"] ? @0.9 : @0.85;
+            qualityHint = @0.9;
+        }
 
-            MRLog(@"🎬 AVFoundation encoder (%@): %dx%d, codec=H.264, bitrate=%.2fMbps",
-                  normalizedQuality,
-                  (int)recordingSize.width,
-                  (int)recordingSize.height,
-                  bitrate / (1000.0 * 1000.0));
+        MRLog(@"🎬 AVFoundation encoder (%@): %dx%d, codec=H.264 High Profile, bitrate=%.2fMbps",
+              normalizedQuality,
+              (int)recordingSize.width,
+              (int)recordingSize.height,
+              bitrate / (1000.0 * 1000.0));
 
-            videoSettings = @{
-                AVVideoCodecKey: codecKey,
-                AVVideoWidthKey: @((int)recordingSize.width),
-                AVVideoHeightKey: @((int)recordingSize.height),
-                AVVideoCompressionPropertiesKey: @{
-                    AVVideoAverageBitRateKey: @(bitrate),
-                    AVVideoMaxKeyFrameIntervalKey: @((int)fps),
-                    AVVideoAllowFrameReorderingKey: @YES,
-                    AVVideoExpectedSourceFrameRateKey: @((int)fps),
-                    AVVideoQualityKey: qualityHint,
-                    AVVideoProfileLevelKey: AVVideoProfileLevelH264HighAutoLevel,
-                    AVVideoH264EntropyModeKey: AVVideoH264EntropyModeCABAC
-                }
-            };
-        }
+        NSDictionary *videoSettings = @{
+            AVVideoCodecKey: codecKey,
+            AVVideoWidthKey: @((int)recordingSize.width),
+            AVVideoHeightKey: @((int)recordingSize.height),
+            AVVideoCompressionPropertiesKey: @{
+                AVVideoAverageBitRateKey: @(bitrate),
+                AVVideoMaxKeyFrameIntervalKey: @((int)fps),
+                AVVideoAllowFrameReorderingKey: @YES,
+                AVVideoExpectedSourceFrameRateKey: @((int)fps),
+                AVVideoQualityKey: qualityHint,
+                AVVideoProfileLevelKey: AVVideoProfileLevelH264HighAutoLevel,
+                AVVideoH264EntropyModeKey: AVVideoH264EntropyModeCABAC
+            }
+        };
         
         // Create video input
         g_avVideoInput = [AVAssetWriterInput assetWriterInputWithMediaType:AVMediaTypeVideo outputSettings:videoSettings];

package/src/screen_capture_kit.mm

@@ -165,6 +165,7 @@ static NSInteger g_targetFPS = 60;
 static NSString *g_qualityPreset = @"high";
 static NSInteger g_frameCount = 0;
 static CFAbsoluteTime g_firstFrameTime = 0;
+static const NSInteger kSCKHighQualityVideoBitrate = 50 * 1000 * 1000;
 
 // Quality helpers
 static NSString *SCKNormalizeQualityPreset(id preset) {
@@ -213,10 +214,10 @@ static void SCKQualityBitrateForDimensions(NSString *preset,
         multiplier = 18;
         minBitrate = 18 * 1000 * 1000;
         maxBitrate = 80 * 1000 * 1000;
-    } else { // high/default - ULTRA quality
-        multiplier = 120;
-        minBitrate = 120 * 1000 * 1000;
-        maxBitrate = 600 * 1000 * 1000;
+    } else { // high/default - fixed high-quality H.264 target
+        multiplier = 0;
+        minBitrate = kSCKHighQualityVideoBitrate;
+        maxBitrate = kSCKHighQualityVideoBitrate;
     }
 
     double base = ((double)MAX(1, width)) * ((double)MAX(1, height)) * (double)multiplier;
@@ -777,58 +778,39 @@ extern "C" NSString *ScreenCaptureKitCurrentAudioPath(void) {
     }
     
     NSString *normalizedQuality = SCKNormalizeQualityPreset(g_qualityPreset);
-    BOOL useProRes = [normalizedQuality isEqualToString:@"high"];
-
-    NSDictionary *videoSettings = nil;
-
-    if (useProRes) {
-        // Screen Studio-style: ProRes 422 HQ — intra-frame, visually lossless,
-        // hardware-accelerated on Apple Silicon. Best for editor scrubbing & high-zoom clarity.
-        MRLog(@"🎬 Screen encoder (high): %ldx%ld, codec=ProRes 422 HQ",
-              (long)width, (long)height);
-
-        videoSettings = @{
-            AVVideoCodecKey: AVVideoCodecTypeAppleProRes422HQ,
-            AVVideoWidthKey: @(width),
-            AVVideoHeightKey: @(height)
-        };
-    } else {
-        NSInteger bitrate = 0;
-        NSInteger bitrateMultiplier = 0;
-        NSInteger minBitrate = 0;
-        NSInteger maxBitrate = 0;
-        SCKQualityBitrateForDimensions(normalizedQuality, width, height, &bitrate, &bitrateMultiplier, &minBitrate, &maxBitrate);
-
-        NSNumber *qualityHint = [normalizedQuality isEqualToString:@"medium"] ? @0.9 : @0.85;
-
-        MRLog(@"🎬 Screen encoder (%@): %ldx%ld, codec=H.264, multiplier=%ld, bitrate=%.2fMbps (min=%ldMbps max=%ldMbps)",
-              normalizedQuality,
-              (long)width,
-              (long)height,
-              (long)bitrateMultiplier,
-              bitrate / (1000.0 * 1000.0),
-              (long)(minBitrate / (1000 * 1000)),
-              (long)(maxBitrate / (1000 * 1000)));
-
-        NSDictionary *compressionProps = @{
-            AVVideoAverageBitRateKey: @(bitrate),
-            AVVideoMaxKeyFrameIntervalKey: @(MAX(1, g_targetFPS)),
-            AVVideoAllowFrameReorderingKey: @YES,
-            AVVideoExpectedSourceFrameRateKey: @(MAX(1, g_targetFPS)),
-            AVVideoQualityKey: qualityHint,
-            AVVideoProfileLevelKey: AVVideoProfileLevelH264HighAutoLevel,
-            AVVideoH264EntropyModeKey: AVVideoH264EntropyModeCABAC,
-            AVVideoAverageNonDroppableFrameRateKey: @(MAX(1, g_targetFPS)),
-            AVVideoMaxKeyFrameIntervalDurationKey: @(1.0)
-        };
-
-        videoSettings = @{
-            AVVideoCodecKey: AVVideoCodecTypeH264,
-            AVVideoWidthKey: @(width),
-            AVVideoHeightKey: @(height),
-            AVVideoCompressionPropertiesKey: compressionProps
-        };
-    }
+    NSInteger bitrate = 0;
+    NSInteger minBitrate = 0;
+    NSInteger maxBitrate = 0;
+    SCKQualityBitrateForDimensions(normalizedQuality, width, height, &bitrate, NULL, &minBitrate, &maxBitrate);
+
+    NSNumber *qualityHint = [normalizedQuality isEqualToString:@"high"] ? @1.0 : ([normalizedQuality isEqualToString:@"medium"] ? @0.9 : @0.85);
+
+    MRLog(@"🎬 Screen encoder (%@): %ldx%ld, codec=H.264 High Profile, bitrate=%.2fMbps (min=%ldMbps max=%ldMbps)",
+          normalizedQuality,
+          (long)width,
+          (long)height,
+          bitrate / (1000.0 * 1000.0),
+          (long)(minBitrate / (1000 * 1000)),
+          (long)(maxBitrate / (1000 * 1000)));
+
+    NSDictionary *compressionProps = @{
+        AVVideoAverageBitRateKey: @(bitrate),
+        AVVideoMaxKeyFrameIntervalKey: @(MAX(1, g_targetFPS)),
+        AVVideoAllowFrameReorderingKey: @YES,
+        AVVideoExpectedSourceFrameRateKey: @(MAX(1, g_targetFPS)),
+        AVVideoQualityKey: qualityHint,
+        AVVideoProfileLevelKey: AVVideoProfileLevelH264HighAutoLevel,
+        AVVideoH264EntropyModeKey: AVVideoH264EntropyModeCABAC,
+        AVVideoAverageNonDroppableFrameRateKey: @(MAX(1, g_targetFPS)),
+        AVVideoMaxKeyFrameIntervalDurationKey: @(1.0)
+    };
+
+    NSDictionary *videoSettings = @{
+        AVVideoCodecKey: AVVideoCodecTypeH264,
+        AVVideoWidthKey: @(width),
+        AVVideoHeightKey: @(height),
+        AVVideoCompressionPropertiesKey: compressionProps
+    };
     
     g_videoInput = [AVAssetWriterInput assetWriterInputWithMediaType:AVMediaTypeVideo outputSettings:videoSettings];
     g_videoInput.expectsMediaDataInRealTime = YES;