node-mac-recorder 1.14.1 → 1.15.0

package/CLAUDE.md

@@ -73,10 +73,22 @@ The package handles complex multi-display coordinate transformations:
 - `checkPermissions()` - Verify macOS recording permissions
 
 ### Cursor Tracking
-- `startCursorCapture(filepath)` - Begin real-time cursor tracking to JSON
+- `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
@@ -90,9 +102,14 @@ The package handles complex multi-display coordinate transformations:
 
 ### Common Development Patterns
 - All recording operations are Promise-based
-- Event emission for recording state changes (`started`, `stopped`, `completed`)
+- 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
 - macOS only (enforced in install.js)
@@ -102,6 +119,13 @@ The package handles complex multi-display coordinate transformations:
 ### 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

package/index.js

@@ -302,6 +302,13 @@ class MacRecorder extends EventEmitter {
 						this.emit("timeUpdate", elapsed);
 					}, 1000);
 
+					// Kayıt tam başladığı anda event emit et
+					this.emit("recordingStarted", {
+						outputPath: this.outputPath,
+						timestamp: this.recordingStartTime,
+						options: this.options
+					});
+					
 					this.emit("started", this.outputPath);
 					resolve(this.outputPath);
 				} else {
@@ -506,9 +513,12 @@ class MacRecorder extends EventEmitter {
 	/**
 	 * Cursor capture başlatır - otomatik olarak dosyaya yazmaya başlar
 	 * Recording başlatılmışsa otomatik olarak display-relative koordinatlar kullanır
-	 * @param {string} filepath - Cursor data JSON dosya yolu
+	 * @param {string|number} intervalOrFilepath - Cursor data JSON dosya yolu veya interval
+	 * @param {Object} options - Cursor capture seçenekleri
+	 * @param {Object} options.windowInfo - Pencere bilgileri (window-relative koordinatlar için)
+	 * @param {boolean} options.windowRelative - Koordinatları pencereye göre relative yap
 	 */
-	async startCursorCapture(intervalOrFilepath = 100) {
+	async startCursorCapture(intervalOrFilepath = 100, options = {}) {
 		let filepath;
 		let interval = 20; // Default 50 FPS
 
@@ -528,8 +538,20 @@ class MacRecorder extends EventEmitter {
 			throw new Error("Cursor capture is already running");
 		}
 
-		// Recording başlatılmışsa o display'i kullan, yoksa main display kullan
-		if (this.recordingDisplayInfo) {
+		// Koordinat sistemi belirle: window-relative, display-relative veya global
+		if (options.windowRelative && options.windowInfo) {
+			// Window-relative koordinatlar için pencere bilgilerini kullan
+			this.cursorDisplayInfo = {
+				displayId: options.windowInfo.displayId || null,
+				x: options.windowInfo.x || 0,
+				y: options.windowInfo.y || 0,
+				width: options.windowInfo.width,
+				height: options.windowInfo.height,
+				windowRelative: true,
+				windowInfo: options.windowInfo
+			};
+		} else if (this.recordingDisplayInfo) {
+			// Recording başlatılmışsa o display'i kullan
 			this.cursorDisplayInfo = this.recordingDisplayInfo;
 		} else {
 			// Main display bilgisini al (her zaman relative koordinatlar için)
@@ -568,23 +590,42 @@ class MacRecorder extends EventEmitter {
 						const position = nativeBinding.getCursorPosition();
 						const timestamp = Date.now() - this.cursorCaptureStartTime;
 
-						// Global koordinatları display-relative'e çevir
+						// Global koordinatları relative koordinatlara çevir
 						let x = position.x;
 						let y = position.y;
+						let coordinateSystem = "global";
 
 						if (this.cursorDisplayInfo) {
-							// Display offset'lerini çıkar
+							// Offset'leri çıkar (display veya window)
 							x = position.x - this.cursorDisplayInfo.x;
 							y = position.y - this.cursorDisplayInfo.y;
 
-							// Display bounds kontrolü - cursor display dışındaysa kaydetme
-							if (
-								x < 0 ||
-								y < 0 ||
-								x >= this.cursorDisplayInfo.width ||
-								y >= this.cursorDisplayInfo.height
-							) {
-								return; // Bu frame'i skip et
+							if (this.cursorDisplayInfo.windowRelative) {
+								// Window-relative koordinatlar
+								coordinateSystem = "window-relative";
+								
+								// Window bounds kontrolü - cursor window dışındaysa kaydetme
+								if (
+									x < 0 ||
+									y < 0 ||
+									x >= this.cursorDisplayInfo.width ||
+									y >= this.cursorDisplayInfo.height
+								) {
+									return; // Bu frame'i skip et - cursor pencere dışında
+								}
+							} else {
+								// Display-relative koordinatlar
+								coordinateSystem = "display-relative";
+								
+								// Display bounds kontrolü
+								if (
+									x < 0 ||
+									y < 0 ||
+									x >= this.cursorDisplayInfo.width ||
+									y >= this.cursorDisplayInfo.height
+								) {
+									return; // Bu frame'i skip et - cursor display dışında
+								}
 							}
 						}
 
@@ -595,6 +636,14 @@ class MacRecorder extends EventEmitter {
 							unixTimeMs: Date.now(),
 							cursorType: position.cursorType,
 							type: position.eventType || "move",
+							coordinateSystem: coordinateSystem,
+							...(this.cursorDisplayInfo?.windowRelative && {
+								windowInfo: {
+									width: this.cursorDisplayInfo.width,
+									height: this.cursorDisplayInfo.height,
+									originalWindow: this.cursorDisplayInfo.windowInfo
+								}
+							})
 						};
 
 						// Sadece eventType değiştiğinde veya pozisyon değiştiğinde kaydet

package/package.json

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

package/overlay-test.js

@@ -1,84 +0,0 @@
-const MacRecorder = require('./index');
-
-async function testOverlayImprovements() {
-    console.log('🎯 Testing Overlay Improvements\n');
-    
-    const recorder = new MacRecorder();
-    const WindowSelector = MacRecorder.WindowSelector;
-    const selector = new WindowSelector();
-    
-    try {
-        console.log('1️⃣ Testing Window Selection with custom buttons...');
-        console.log('   - Custom "Start Record" and "Cancel" buttons should appear');
-        console.log('   - ESC key should cancel selection');
-        console.log('   - Cancel button should cancel selection');
-        console.log('   - Starting window selection...\n');
-        
-        // Start window selection (non-blocking)
-        await selector.startSelection();
-        
-        console.log('✅ Window selection started. Move mouse over windows to see overlay.');
-        console.log('   - Press ESC to cancel');
-        console.log('   - Click Cancel button to cancel');
-        console.log('   - Click Start Record to select window\n');
-        
-        // Wait for selection or timeout
-        const startTime = Date.now();
-        const timeout = 30000; // 30 seconds
-        
-        while (selector.getStatus().isSelecting && (Date.now() - startTime) < timeout) {
-            await new Promise(resolve => setTimeout(resolve, 100));
-        }
-        
-        const selectedWindow = selector.getSelectedWindow();
-        
-        if (selectedWindow) {
-            console.log('🎬 Window selected:', selectedWindow.appName, '-', selectedWindow.title);
-            console.log('   Size:', selectedWindow.width + 'x' + selectedWindow.height);
-            console.log('   Position: (' + selectedWindow.x + ', ' + selectedWindow.y + ')');
-            
-            console.log('\n2️⃣ Testing Recording Preview Overlay...');
-            console.log('   - Should show darkened overlay with window area transparent');
-            
-            await selector.showRecordingPreview(selectedWindow);
-            console.log('✅ Recording preview shown. Check if window area is highlighted.');
-            
-            // Wait 3 seconds
-            await new Promise(resolve => setTimeout(resolve, 3000));
-            
-            await selector.hideRecordingPreview();
-            console.log('✅ Recording preview hidden.');
-            
-        } else {
-            console.log('🚫 No window selected (cancelled or timeout)');
-        }
-        
-        console.log('\n3️⃣ Testing Screen Selection with custom buttons...');
-        console.log('   - Custom "Start Record" and "Cancel" buttons should appear on each screen');
-        console.log('   - ESC key should cancel selection');
-        console.log('   - Cancel button should cancel selection');
-        
-        const selectedScreen = await selector.selectScreen().catch(err => {
-            console.log('🚫 Screen selection cancelled:', err.message);
-            return null;
-        });
-        
-        if (selectedScreen) {
-            console.log('🖥️ Screen selected:', selectedScreen.name);
-            console.log('   Resolution:', selectedScreen.resolution);
-            console.log('   Position: (' + selectedScreen.x + ', ' + selectedScreen.y + ')');
-        } else {
-            console.log('🚫 No screen selected (cancelled or timeout)');
-        }
-        
-        console.log('\n🎉 Overlay improvements test completed!');
-        
-    } catch (error) {
-        console.error('❌ Test failed:', error.message);
-    } finally {
-        await selector.cleanup();
-    }
-}
-
-// Run test
-testOverlayImprovements().catch(console.error);