node-mac-recorder 2.22.34 → 2.23.1

package/.claude/settings.local.json

@@ -50,7 +50,13 @@
       "Bash(ffmpeg:*)",
       "Bash(timeout 30 node:*)",
       "Bash(MAC_RECORDER_DEBUG=1 node test-camera-audio-sync.js:*)",
-      "WebSearch"
+      "WebSearch",
+      "mcp__plugin_context-mode_context-mode__ctx_execute_file",
+      "mcp__plugin_context-mode_context-mode__ctx_execute",
+      "mcp__plugin_context-mode_context-mode__ctx_batch_execute",
+      "Bash(nm -D /System/Library/Frameworks/AppKit.framework/AppKit)",
+      "Bash(otool -L /System/Library/Frameworks/AppKit.framework/AppKit)",
+      "Bash(mdfind -name CoreCursor)"
     ],
     "deny": [],
     "ask": []

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.22.34",
+	"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,
@@ -36,7 +37,8 @@ extern "C" bool startAVFoundationRecording(const std::string& outputPath,
                                            bool includeSystemAudio,
                                            NSString* audioDeviceId,
                                            NSString* audioOutputPath,
-                                           double requestedFrameRate) {
+                                           double requestedFrameRate,
+                                           NSString* qualityPreset) {
     
     if (g_avIsRecording) {
         NSLog(@"❌ AVFoundation recording already in progress");
@@ -123,27 +125,47 @@ extern "C" bool startAVFoundationRecording(const std::string& outputPath,
         
         MRLog(@"🎯 Recording size: %.0fx%.0f (using actual physical dimensions for Retina fix)", recordingSize.width, recordingSize.height);
         
-        // Video settings with macOS compatibility
-        NSString *codecKey;
-        if (@available(macOS 10.13, *)) {
-            codecKey = AVVideoCodecTypeH264;
-        } else {
-            // Fallback for older macOS versions
-            codecKey = AVVideoCodecH264;
+        NSString *normalizedQuality = @"high";
+        if ([qualityPreset isKindOfClass:[NSString class]] && qualityPreset.length > 0) {
+            normalizedQuality = [qualityPreset lowercaseString];
+            if (![normalizedQuality isEqualToString:@"low"] &&
+                ![normalizedQuality isEqualToString:@"medium"] &&
+                ![normalizedQuality isEqualToString:@"high"]) {
+                normalizedQuality = @"high";
+            }
         }
-        
-        NSInteger bitrate = (NSInteger)(recordingSize.width * recordingSize.height * 100);
-        bitrate = MAX(bitrate, 120 * 1000 * 1000);
-        bitrate = MIN(bitrate, 500 * 1000 * 1000);
-
-        NSLog(@"🎬 ULTRA QUALITY AVFoundation: %dx%d, bitrate=%.2fMbps",
-              (int)recordingSize.width, (int)recordingSize.height, bitrate / (1000.0 * 1000.0));
-
-        // Resolve target FPS
         double fps = requestedFrameRate > 0 ? requestedFrameRate : 60.0;
         if (fps < 1.0) fps = 1.0;
         if (fps > 120.0) fps = 120.0;
 
+        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);
+            qualityHint = @0.9;
+        }
+
+        MRLog(@"🎬 AVFoundation encoder (%@): %dx%d, codec=H.264 High Profile, bitrate=%.2fMbps",
+              normalizedQuality,
+              (int)recordingSize.width,
+              (int)recordingSize.height,
+              bitrate / (1000.0 * 1000.0));
+
         NSDictionary *videoSettings = @{
             AVVideoCodecKey: codecKey,
             AVVideoWidthKey: @((int)recordingSize.width),
@@ -153,13 +175,11 @@ extern "C" bool startAVFoundationRecording(const std::string& outputPath,
                 AVVideoMaxKeyFrameIntervalKey: @((int)fps),
                 AVVideoAllowFrameReorderingKey: @YES,
                 AVVideoExpectedSourceFrameRateKey: @((int)fps),
-                AVVideoQualityKey: @(1.0),
+                AVVideoQualityKey: qualityHint,
                 AVVideoProfileLevelKey: AVVideoProfileLevelH264HighAutoLevel,
                 AVVideoH264EntropyModeKey: AVVideoH264EntropyModeCABAC
             }
         };
-
-        NSLog(@"🔧 Using codec: %@", codecKey);
         
         // Create video input
         g_avVideoInput = [AVAssetWriterInput assetWriterInputWithMediaType:AVMediaTypeVideo outputSettings:videoSettings];

package/src/mac_recorder.mm

@@ -21,7 +21,8 @@ extern "C" {
                                    bool includeSystemAudio,
                                    NSString* audioDeviceId,
                                    NSString* audioOutputPath,
-                                   double frameRate);
+                                   double frameRate,
+                                   NSString* qualityPreset);
     bool stopAVFoundationRecording();
     bool isAVFoundationRecording();
     NSString* getAVFoundationAudioPath();
@@ -728,7 +729,8 @@ Napi::Value StartRecording(const Napi::CallbackInfo& info) {
                                                    bool includeSystemAudio,
                                                    NSString* audioDeviceId,
                                                    NSString* audioOutputPath,
-                                                   double frameRate);
+                                                   double frameRate,
+                                                   NSString* qualityPreset);
 
             // A/V SYNC: Start camera non-blocking BEFORE AVFoundation
             if (captureCamera) {
@@ -742,7 +744,8 @@ Napi::Value StartRecording(const Napi::CallbackInfo& info) {
             MRLog(@"🎯 SYNC: Starting screen recording");
             bool avResult = startAVFoundationRecording(outputPath, displayID, windowID, captureRect,
                                                       captureCursor, includeMicrophone, includeSystemAudio,
-                                                      audioDeviceId, audioOutputPath, frameRate);
+                                                      audioDeviceId, audioOutputPath, frameRate,
+                                                      qualityPreset ?: @"high");
 
             if (avResult) {
                 MRLog(@"🎥 RECORDING METHOD: AVFoundation");

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;
@@ -776,25 +777,18 @@ extern "C" NSString *ScreenCaptureKitCurrentAudioPath(void) {
         return NO;
     }
     
+    NSString *normalizedQuality = SCKNormalizeQualityPreset(g_qualityPreset);
     NSInteger bitrate = 0;
-    NSInteger bitrateMultiplier = 0;
     NSInteger minBitrate = 0;
     NSInteger maxBitrate = 0;
-    NSString *normalizedQuality = SCKNormalizeQualityPreset(g_qualityPreset);
-    SCKQualityBitrateForDimensions(normalizedQuality, width, height, &bitrate, &bitrateMultiplier, &minBitrate, &maxBitrate);
+    SCKQualityBitrateForDimensions(normalizedQuality, width, height, &bitrate, NULL, &minBitrate, &maxBitrate);
 
-    NSNumber *qualityHint = @1.0;
-    if ([normalizedQuality isEqualToString:@"medium"]) {
-        qualityHint = @0.9;
-    } else if ([normalizedQuality isEqualToString:@"low"]) {
-        qualityHint = @0.85;
-    }
+    NSNumber *qualityHint = [normalizedQuality isEqualToString:@"high"] ? @1.0 : ([normalizedQuality isEqualToString:@"medium"] ? @0.9 : @0.85);
 
-    MRLog(@"🎬 Screen encoder (%@): %ldx%ld, multiplier=%ld, bitrate=%.2fMbps (min=%ldMbps max=%ldMbps)",
+    MRLog(@"🎬 Screen encoder (%@): %ldx%ld, codec=H.264 High Profile, 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)));
@@ -804,12 +798,11 @@ extern "C" NSString *ScreenCaptureKitCurrentAudioPath(void) {
         AVVideoMaxKeyFrameIntervalKey: @(MAX(1, g_targetFPS)),
         AVVideoAllowFrameReorderingKey: @YES,
         AVVideoExpectedSourceFrameRateKey: @(MAX(1, g_targetFPS)),
-        AVVideoQualityKey: qualityHint,  // 0.0-1.0, higher is better
+        AVVideoQualityKey: qualityHint,
         AVVideoProfileLevelKey: AVVideoProfileLevelH264HighAutoLevel,
         AVVideoH264EntropyModeKey: AVVideoH264EntropyModeCABAC,
-        // Add data rate limits for consistent quality during motion
         AVVideoAverageNonDroppableFrameRateKey: @(MAX(1, g_targetFPS)),
-        AVVideoMaxKeyFrameIntervalDurationKey: @(1.0)  // Keyframe at least every second
+        AVVideoMaxKeyFrameIntervalDurationKey: @(1.0)
     };
 
     NSDictionary *videoSettings = @{