node-mac-recorder 1.2.7 → 1.2.9

package/.claude/settings.local.json

@@ -0,0 +1,13 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(node:*)",
+      "Bash(timeout:*)",
+      "Bash(rm:*)",
+      "Bash(python3:*)",
+      "Bash(grep:*)",
+      "Bash(cat:*)"
+    ],
+    "deny": []
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,120 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+node-mac-recorder is a Node.js native addon that provides macOS screen recording capabilities using AVFoundation. The package allows recording of full screens, specific windows, or custom areas, with support for multi-display setups, audio capture, and cursor tracking.
+
+## 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)` - Begin real-time cursor tracking to JSON
+- `stopCursorCapture()` - Stop tracking and close output file
+- `getCursorPosition()` - Get current cursor position and state
+
+### 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 (`started`, `stopped`, `completed`)
+- Automatic permission checking before operations
+- Error handling with descriptive messages for permission issues
+
+### Platform Requirements
+- macOS only (enforced in install.js)
+- Native module compilation required on install
+- Requires screen recording and accessibility permissions
+
+### File Outputs
+- Video recordings: `.mov` format (H.264/AAC)
+- Cursor data: JSON format with timestamped events
+- 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.

package/cursor-data.json

@@ -0,0 +1 @@
+[{"x":1151,"y":726,"timestamp":20,"cursorType":"text","type":"move"}

package/debug-cursor-output.json

@@ -0,0 +1 @@
+[{"x":48,"y":72,"timestamp":22,"unixTimeMs":1752410259890,"cursorType":"pointer","type":"move"},{"x":47,"y":71,"timestamp":87,"unixTimeMs":1752410259955,"cursorType":"pointer","type":"mousedown"},{"x":47,"y":71,"timestamp":107,"unixTimeMs":1752410259975,"cursorType":"pointer","type":"move"},{"x":47,"y":71,"timestamp":169,"unixTimeMs":1752410260037,"cursorType":"pointer","type":"mouseup"},{"x":47,"y":71,"timestamp":781,"unixTimeMs":1752410260649,"cursorType":"default","type":"move"}]

package/debug-cursor.js

@@ -0,0 +1,50 @@
+const MacRecorder = require('./index.js');
+const fs = require('fs');
+
+// Create a minimal direct test
+const recorder = new MacRecorder();
+
+// Get current cursor position to test the new field
+console.log('Testing cursor position API...');
+const pos = recorder.getCursorPosition();
+console.log('Current cursor position:', JSON.stringify(pos, null, 2));
+
+// Test if we can start/stop cursor tracking
+console.log('\nTesting cursor tracking start/stop...');
+const testFile = 'debug-cursor-output.json';
+
+// Remove existing file
+if (fs.existsSync(testFile)) {
+    fs.unlinkSync(testFile);
+}
+
+const started = recorder.startCursorCapture(testFile);
+console.log('Start result:', started);
+
+if (started) {
+    // Wait 1 second and check what gets written
+    setTimeout(() => {
+        recorder.stopCursorCapture();
+        console.log('Stopped tracking');
+        
+        // Check file content
+        if (fs.existsSync(testFile)) {
+            const content = fs.readFileSync(testFile, 'utf8');
+            console.log('\nFile content:');
+            console.log(content);
+            
+            // Parse and pretty print
+            try {
+                const data = JSON.parse(content);
+                console.log('\nParsed data:');
+                console.log(JSON.stringify(data, null, 2));
+            } catch (e) {
+                console.log('Error parsing JSON:', e.message);
+            }
+        } else {
+            console.log('No output file created');
+        }
+    }, 1000);
+} else {
+    console.log('Failed to start cursor tracking');
+}

package/index.js

@@ -50,6 +50,9 @@ class MacRecorder extends EventEmitter {
 		// Display cache için async initialization
 		this.cachedDisplays = null;
 		this.refreshDisplayCache();
+
+		// Native cursor warm-up (cold start delay'ini önlemek için)
+		this.warmUpCursor();
 	}
 
 	/**
@@ -582,6 +585,7 @@ class MacRecorder extends EventEmitter {
 							x: x,
 							y: y,
 							timestamp: timestamp,
+							unixTimeMs: Date.now(),
 							cursorType: position.cursorType,
 							type: position.eventType || "move",
 						};
@@ -735,6 +739,21 @@ class MacRecorder extends EventEmitter {
 		}
 	}
 
+	/**
+	 * Native cursor modülünü warm-up yapar (cold start delay'ini önler)
+	 */
+	warmUpCursor() {
+		// Async warm-up to prevent blocking constructor
+		setTimeout(() => {
+			try {
+				// Silent warm-up call
+				nativeBinding.getCursorPosition();
+			} catch (error) {
+				// Ignore warm-up errors
+			}
+		}, 10); // 10ms delay to not block initialization
+	}
+
 	/**
 	 * getCurrentCursorPosition alias for getCursorPosition (backward compatibility)
 	 */

package/package.json

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

package/quick-cursor-test.js

@@ -0,0 +1,20 @@
+const MacRecorder = require('./index.js');
+const recorder = new MacRecorder();
+
+console.log('Starting 3-second cursor test...');
+const testPath = 'quick-cursor-test.json';
+
+// Start cursor tracking
+const started = recorder.startCursorCapture(testPath);
+if (started) {
+    console.log('Cursor tracking started, collecting data for 3 seconds...');
+    
+    setTimeout(() => {
+        console.log('Stopping cursor tracking...');
+        recorder.stopCursorCapture();
+        console.log('Done! Check quick-cursor-test.json');
+    }, 3000);
+} else {
+    console.log('Failed to start cursor tracking');
+    process.exit(1);
+}

package/quick-cursor-test.json

@@ -0,0 +1 @@
+[{"x":798,"y":526,"timestamp":20,"unixTimeMs":1752410795804,"cursorType":"text","type":"move"}]

package/src/cursor_tracker.mm

@@ -199,7 +199,9 @@ CGEventRef eventCallback(CGEventTapProxy proxy, CGEventType type, CGEventRef eve
         }
         
         CGPoint location = CGEventGetLocation(event);
-        NSTimeInterval timestamp = [[NSDate date] timeIntervalSinceDate:g_trackingStartTime] * 1000; // milliseconds
+        NSDate *currentDate = [NSDate date];
+        NSTimeInterval timestamp = [currentDate timeIntervalSinceDate:g_trackingStartTime] * 1000; // milliseconds
+        NSTimeInterval unixTimeMs = [currentDate timeIntervalSince1970] * 1000; // unix timestamp in milliseconds
         NSString *cursorType = getCursorType();
         NSString *eventType = @"move";
         
@@ -230,7 +232,8 @@ CGEventRef eventCallback(CGEventTapProxy proxy, CGEventType type, CGEventRef eve
         NSDictionary *cursorInfo = @{
             @"x": @((int)location.x),
             @"y": @((int)location.y),
-            @"timestamp": @((int)timestamp),
+            @"timestamp": @(timestamp),
+            @"unixTimeMs": @(unixTimeMs),
             @"cursorType": cursorType,
             @"type": eventType
         };
@@ -258,14 +261,17 @@ void cursorTimerCallback() {
             CFRelease(event);
         }
         
-        NSTimeInterval timestamp = [[NSDate date] timeIntervalSinceDate:g_trackingStartTime] * 1000; // milliseconds
+        NSDate *currentDate = [NSDate date];
+        NSTimeInterval timestamp = [currentDate timeIntervalSinceDate:g_trackingStartTime] * 1000; // milliseconds
+        NSTimeInterval unixTimeMs = [currentDate timeIntervalSince1970] * 1000; // unix timestamp in milliseconds
         NSString *cursorType = getCursorType();
         
         // Cursor data oluştur
         NSDictionary *cursorInfo = @{
             @"x": @((int)location.x),
             @"y": @((int)location.y),
-            @"timestamp": @((int)timestamp),
+            @"timestamp": @(timestamp),
+            @"unixTimeMs": @(unixTimeMs),
             @"cursorType": cursorType,
             @"type": @"move"
         };

package/test-both-cursor.json

@@ -0,0 +1 @@
+[{"x":798,"y":526,"timestamp":21,"unixTimeMs":1752410827986,"cursorType":"text","type":"move"}]

package/test-both.js

@@ -0,0 +1,46 @@
+const MacRecorder = require('./index.js');
+const recorder = new MacRecorder();
+
+console.log('Testing screen recording + cursor tracking together...');
+
+async function testBoth() {
+    try {
+        // Start both simultaneously
+        console.log('Starting screen recording...');
+        await recorder.startRecording('./test-recordings/test-both.mov');
+        
+        console.log('Starting cursor tracking...');
+        await recorder.startCursorCapture('./test-both-cursor.json');
+        
+        console.log('Both running for 3 seconds...');
+        
+        // Let them run together for 3 seconds
+        await new Promise(resolve => setTimeout(resolve, 3000));
+        
+        // Stop both
+        console.log('Stopping both...');
+        await recorder.stopRecording();
+        recorder.stopCursorCapture();
+        
+        console.log('✅ Both completed successfully!');
+        
+        // Check results
+        const fs = require('fs');
+        if (fs.existsSync('./test-recordings/test-both.mov')) {
+            const stats = fs.statSync('./test-recordings/test-both.mov');
+            console.log(`Video file: ${stats.size} bytes`);
+        }
+        
+        if (fs.existsSync('./test-both-cursor.json')) {
+            const content = fs.readFileSync('./test-both-cursor.json', 'utf8');
+            const data = JSON.parse(content);
+            console.log(`Cursor data: ${data.length} entries`);
+            console.log('Sample entry:', JSON.stringify(data[0], null, 2));
+        }
+        
+    } catch (error) {
+        console.error('Error:', error.message);
+    }
+}
+
+testBoth();

package/test-cursor-visible.js

@@ -0,0 +1,41 @@
+const MacRecorder = require('./index.js');
+const recorder = new MacRecorder();
+
+async function testCursorVisibility() {
+    console.log('Testing cursor visibility in screen recording...');
+    
+    try {
+        // Test 1: Cursor hidden (default)
+        console.log('🎬 Recording with cursor HIDDEN...');
+        await recorder.startRecording('./test-recordings/cursor-hidden.mov', {
+            captureCursor: false
+        });
+        
+        await new Promise(resolve => setTimeout(resolve, 2000));
+        await recorder.stopRecording();
+        console.log('✅ Hidden cursor recording done');
+        
+        // Test 2: Cursor visible  
+        console.log('🎬 Recording with cursor VISIBLE...');
+        await recorder.startRecording('./test-recordings/cursor-visible.mov', {
+            captureCursor: true
+        });
+        
+        await new Promise(resolve => setTimeout(resolve, 2000));
+        await recorder.stopRecording();
+        console.log('✅ Visible cursor recording done');
+        
+        // Check file sizes
+        const fs = require('fs');
+        const hiddenStats = fs.statSync('./test-recordings/cursor-hidden.mov');
+        const visibleStats = fs.statSync('./test-recordings/cursor-visible.mov');
+        
+        console.log(`Hidden cursor video: ${hiddenStats.size} bytes`);
+        console.log(`Visible cursor video: ${visibleStats.size} bytes`);
+        
+    } catch (error) {
+        console.error('Error:', error.message);
+    }
+}
+
+testCursorVisibility();

package/test-native-cursor.js

@@ -0,0 +1,31 @@
+const nativeBinding = require('./build/Release/mac_recorder.node');
+
+console.log('Testing native cursor tracking...');
+
+// Test native startCursorTracking function directly
+const testFile = 'native-cursor-test.json';
+const started = nativeBinding.startCursorTracking(testFile);
+
+console.log('Native tracking started:', started);
+
+if (started) {
+    setTimeout(() => {
+        const stopped = nativeBinding.stopCursorTracking();
+        console.log('Native tracking stopped:', stopped);
+        
+        const fs = require('fs');
+        if (fs.existsSync(testFile)) {
+            const content = fs.readFileSync(testFile, 'utf8');
+            console.log('\nNative output:');
+            try {
+                const data = JSON.parse(content);
+                console.log(JSON.stringify(data.slice(0, 3), null, 2)); // Show first 3 entries
+                console.log('Total entries:', data.length);
+            } catch (e) {
+                console.log('Raw content:', content.substring(0, 500));
+            }
+        }
+    }, 2000);
+} else {
+    console.log('Failed to start native tracking');
+}