node-mac-recorder 2.21.22 → 2.21.24

package/.cursor/worktrees.json

@@ -0,0 +1,5 @@
+{
+  "setup-worktree": [
+    "npm install"
+  ]
+}

package/CURSOR-SYNC-FIX.md

@@ -0,0 +1,85 @@
+# Cursor-Video Senkronizasyon Düzeltmesi
+
+## Problem
+Ekran videosu kaydedilirken custom cursor da kayıt ediliyor, ancak cursor'un tıklama/hareket kayıtları ekran videosundan ~0.5-1 saniye geriden geliyordu.
+
+## Çözüm
+
+### 1. Cursor Tracking Interval Azaltıldı
+- **Öncesi**: 20ms interval (50 FPS)
+- **Sonrası**: 5ms interval (200 FPS)
+- **Sonuç**: Cursor artık çok daha sık örnekleniyor, bu yüzden video frame'leri ile sync şansı çok daha yüksek
+
+### 2. Position Threshold Azaltıldı
+- **Öncesi**: 2 pixel minimum hareket
+- **Sonrası**: 1 pixel minimum hareket
+- **Sonuç**: Daha hassas tracking, küçük mouse hareketleri bile kaydediliyor
+
+### 3. Gerçek Test Sonuçları
+
+```
+📊 Cursor tracking analysis:
+   Total events captured: 193
+   Average capture rate: 41.5 FPS
+   Timing analysis:
+   - Average interval: 24.3ms (41.2 FPS)
+   - Min interval: 1.0ms
+   - Max interval: 765.0ms
+   ✅ Smooth cursor tracking
+```
+
+## Test Etme
+
+```bash
+# Kısa sync testi (5 saniye, mouse'u hareket ettir)
+node test-cursor-sync-mouse.js
+
+# Test sonrası video ve cursor dosyasını kontrol et:
+# - Video: test-output/sync-test-{timestamp}.mov
+# - Cursor: test-output/temp_cursor_{timestamp}.json
+```
+
+## Teknik Detaylar
+
+### Neden Native Event Tracking Kullanılmadı?
+Native `NSTimer` ve `CGEventTap` çalışıyor ama Node.js event loop ile uyumsuz. Timer callback'leri çağrılmıyor çünkü:
+- Node.js kendi event loop'unu kullanıyor
+- macOS main run loop block olmuyor
+- Bu yüzden timer callback'leri tetiklenmiyor
+
+### JavaScript Polling Neden Yeterli?
+- 5ms interval = 200 FPS sampling rate
+- Video 60 FPS = ~16.67ms per frame
+- Cursor her video frame'inde 3+ kez örnekleniyor
+- `shouldCaptureEvent` filtrelemesi sayesinde sadece değişiklikler kaydediliyor
+- Ortalama 40-50 FPS cursor data elde ediliyor (yeterli)
+
+### Sync Mekanizması
+1. **Unified Session Timestamp**: Hem video hem cursor aynı `sessionTimestamp` kullanıyor
+2. **Synchronized Start**: Video başladıktan hemen sonra cursor tracking başlıyor (aynı timestamp)
+3. **Relative Timestamps**: İkisi de başlangıçtan itibaren millisaniye cinsinden kaydediyor
+
+## Beklenen Sonuç
+
+- ✅ Cursor ve video aynı anda başlıyor (0ms fark)
+- ✅ Cursor her ~24ms'de bir örnekleniyor (smooth)
+- ✅ Click event'leri doğru yakalanıyor
+- ✅ Video frame'leri ile mükemmel sync
+
+## Ek Notlar
+
+### Çoklu Ekran Kullanımı
+Eğer cursor başka bir ekrandaysa `coordinateSystem: "video-relative-outside"` olarak işaretlenir. Bu normal ve cursor overlay render'ında handle edilmelidir.
+
+### Performance
+200 FPS sampling yüksek görünse de:
+- Change detection filtrelemesi var (sadece hareket olunca yazıyor)
+- Dosya boyutu küçük kalıyor
+- CPU overhead minimal
+
+### İleride İyileştirme
+Native event tracking için:
+- Ayrı thread'de CFRunLoop çalıştırılabilir
+- Veya GCD dispatch queue kullanılabilir
+- Ama şimdilik JavaScript polling yeterli ve güvenilir
+

package/CURSOR-SYNC-PERFECT.md

@@ -0,0 +1,138 @@
+# ✅ Cursor-Video Senkronizasyon Tamamen Çözüldü!
+
+## Asıl Sorun
+
+Cursor tracking **hemen** başlıyordu, ama video'nun ilk frame'ini yakalaması **~100-200ms** sürüyordu.
+
+```
+ÖNCE:
+t=0ms:    startRecording() çağrılır
+t=0ms:    Cursor tracking başlar ✅
+t=150ms:  İlk video frame yakalanır ❌ (CURSOR ÖNDE!)
+```
+
+Bu yüzden cursor event'leri video'dan önce geliyordu - **cursor önde, video geride!**
+
+## Çözüm: İlk Frame Senkronizasyonu
+
+### 1. Native Tarafta: İlk Frame Timestamp'ini Kaydet
+
+**ScreenCaptureKit** (`screen_capture_kit.mm`):
+```objc
+static NSTimeInterval g_actualRecordingStartTime = 0;
+
+- (void)stream:didOutputSampleBuffer:ofType: {
+    if (!g_videoWriterStarted) {
+        // İlk frame yakalandığında
+        g_actualRecordingStartTime = [[NSDate date] timeIntervalSince1970] * 1000;
+        MRLog(@"🎞️ First frame captured at %.0f", g_actualRecordingStartTime);
+    }
+}
+```
+
+**AVFoundation** (`avfoundation_recorder.mm`):
+```objc
+static NSTimeInterval g_avActualRecordingStartTime = 0;
+
+if (g_avFrameNumber == 0) {
+    // İlk frame yazıldığında
+    g_avActualRecordingStartTime = [[NSDate date] timeIntervalSince1970] * 1000;
+    MRLog(@"🎞️ AVFoundation first frame written at %.0f", g_avActualRecordingStartTime);
+}
+```
+
+### 2. JavaScript Tarafta: İlk Frame'i Bekle
+
+```javascript
+// Poll for actual recording start (when first frame is captured)
+console.log('⏳ SYNC: Waiting for first video frame...');
+const maxWaitMs = 2000;
+const pollInterval = 10;
+let actualStartTime = 0;
+
+while (waitedMs < maxWaitMs) {
+    actualStartTime = nativeBinding.getActualRecordingStartTime();
+    if (actualStartTime > 0) {
+        console.log(`✅ SYNC: First frame captured at ${actualStartTime}ms`);
+        break;
+    }
+    await new Promise(resolve => setTimeout(resolve, pollInterval));
+    waitedMs += pollInterval;
+}
+
+// Cursor tracking'i ACTUAL start time ile başlat
+await this.startCursorCapture(cursorFilePath, {
+    startTimestamp: actualStartTime  // ← PERFECT SYNC!
+});
+```
+
+## Sonuç: Mükemmel Senkronizasyon!
+
+```
+ŞIMDI:
+t=0ms:    startRecording() çağrılır
+t=150ms:  İlk video frame yakalanır ✅
+t=150ms:  Cursor tracking başlar ✅ (TAM SENKRON!)
+```
+
+### Test Sonuçları:
+```
+✅ SYNC: First frame captured at 1761818226539.994ms (waited 30ms)
+🎯 SYNC: Starting cursor tracking at ACTUAL recording start: 1761818226539.994
+   First cursor event: t=19.006ms (video'dan 19ms sonra - mükemmel!)
+```
+
+## Teknik Detaylar
+
+### Neden Bu Yaklaşım Çalışıyor?
+
+1. **Video recording başlatma** → Native sistem hazırlanıyor
+2. **İlk frame yakalanıyor** → GERÇEK kayıt başlangıcı (100-200ms sonra)
+3. **Cursor tracking başlıyor** → Aynı timestamp'ten başlıyor
+4. **Sonuç**: Cursor ve video TAM SENKRON!
+
+### Timing Analizi
+
+- **Bekleme süresi**: ~30ms (çok hızlı!)
+- **İlk cursor event**: İlk frame'den 19ms sonra
+- **Senkronizasyon farkı**: <20ms (algılanamaz!)
+
+### Ek İyileştirmeler
+
+1. **5ms cursor interval** (200 FPS sampling)
+2. **1px minimum threshold** (hassas tracking)
+3. **Change detection filtering** (sadece hareket varsa kaydet)
+
+## Test Etme
+
+```bash
+node test-cursor-sync-mouse.js
+```
+
+Test sırasında mouse'u hareket ettir ve tıkla. Sonuçta:
+- ✅ Video ve cursor aynı anda başlıyor
+- ✅ Tıklama event'leri doğru timing'de
+- ✅ Mouse hareketi smooth ve senkronize
+
+## Kullanım
+
+```javascript
+const recorder = new MacRecorder();
+
+// Normal kullanım - senkronizasyon otomatik!
+await recorder.startRecording('output.mov', {
+    captureCursor: false, // Sistem cursor'unu gizle
+    frameRate: 60
+});
+
+// Cursor tracking otomatik olarak video'nun ilk frame'ini bekler
+// ve mükemmel senkronizasyonla başlar!
+```
+
+## Özet
+
+🎯 **Problem Çözüldü**: Cursor artık video ile TAM SENKRONIZE!
+✅ **Timing**: İlk frame'den <20ms sonra cursor tracking başlıyor
+⚡ **Performance**: Sadece ~30ms bekleme süresi
+🔥 **Sonuç**: Mükemmel cursor-video sync!
+

package/electron-safe-index.js

@@ -44,8 +44,8 @@ class ElectronSafeMacRecorder extends EventEmitter {
 		this.options = {
 			includeMicrophone: false,
 			includeSystemAudio: false,
-			quality: "medium",
-			frameRate: 30,
+			quality: "high",
+			frameRate: 60,
 			captureArea: null,
 			captureCursor: false,
 			showClicks: false,

package/index.js

@@ -43,8 +43,8 @@ class MacRecorder extends EventEmitter {
 		this.options = {
 			includeMicrophone: false, // Default olarak mikrofon kapalı
 			includeSystemAudio: false, // Default olarak sistem sesi kapalı - kullanıcı explicit olarak açmalı
-			quality: "medium",
-			frameRate: 30,
+			quality: "high",
+			frameRate: 60,
 			captureArea: null, // { x, y, width, height }
 			captureCursor: false, // Default olarak cursor gizli
 			showClicks: false,
@@ -181,6 +181,13 @@ class MacRecorder extends EventEmitter {
 		if (options.captureCamera !== undefined) {
 			this.options.captureCamera = options.captureCamera === true;
 		}
+		if (options.frameRate !== undefined) {
+			const fps = parseInt(options.frameRate, 10);
+			if (!Number.isNaN(fps) && fps > 0) {
+				// Clamp reasonable range 1-120
+				this.options.frameRate = Math.min(Math.max(fps, 1), 120);
+			}
+		}
 		if (options.cameraDeviceId !== undefined) {
 			this.options.cameraDeviceId =
 				typeof options.cameraDeviceId === "string" && options.cameraDeviceId.length > 0
@@ -497,6 +504,8 @@ class MacRecorder extends EventEmitter {
 					captureCamera: this.options.captureCamera === true,
 					cameraDeviceId: this.options.cameraDeviceId || null,
 					sessionTimestamp,
+					frameRate: this.options.frameRate || 60,
+					quality: this.options.quality || "high",
 				};
 
 					if (cameraFilePath) {
@@ -542,7 +551,8 @@ class MacRecorder extends EventEmitter {
 					console.warn('❌ Native recording failed to start:', error.message);
 				}
 
-				// Only start cursor if native recording started successfully
+				// CRITICAL SYNC FIX: Wait for first video frame before starting cursor
+				// This ensures cursor and video start at the EXACT same time
 				if (success) {
 					const standardCursorOptions = {
 						videoRelative: true,
@@ -551,11 +561,36 @@ class MacRecorder extends EventEmitter {
 									  this.options.captureArea ? 'area' : 'display',
 						captureArea: this.options.captureArea,
 						windowId: this.options.windowId,
-						startTimestamp: sessionTimestamp // Use the same timestamp base
+						startTimestamp: sessionTimestamp // Will be updated with actual start time
 					};
 
 					try {
-						console.log('🎯 SYNC: Starting cursor tracking at timestamp:', sessionTimestamp);
+						// Poll for actual recording start (when first frame is captured)
+						console.log('⏳ SYNC: Waiting for first video frame...');
+						const maxWaitMs = 2000; // Max 2 seconds wait
+						const pollInterval = 10; // Check every 10ms
+						let waitedMs = 0;
+						let actualStartTime = 0;
+						
+						while (waitedMs < maxWaitMs) {
+							actualStartTime = nativeBinding.getActualRecordingStartTime();
+							if (actualStartTime > 0) {
+								console.log(`✅ SYNC: First frame captured at ${actualStartTime}ms (waited ${waitedMs}ms)`);
+								break;
+							}
+							await new Promise(resolve => setTimeout(resolve, pollInterval));
+							waitedMs += pollInterval;
+						}
+						
+						if (actualStartTime > 0) {
+							// Use actual start time for perfect sync
+							standardCursorOptions.startTimestamp = actualStartTime;
+							console.log('🎯 SYNC: Starting cursor tracking at ACTUAL recording start:', actualStartTime);
+						} else {
+							// Fallback to session timestamp if first frame not detected
+							console.warn('⚠️ SYNC: First frame not detected, using session timestamp');
+						}
+						
 						await this.startCursorCapture(cursorFilePath, standardCursorOptions);
 						console.log('✅ SYNC: Cursor tracking started successfully');
 					} catch (cursorError) {
@@ -998,21 +1033,23 @@ class MacRecorder extends EventEmitter {
 
 		const last = this.lastCapturedData;
 
-		// Event type değişmişse
+		// Event type değişmişse (click, drag, vs)
 		if (currentData.type !== last.type) {
 			return true;
 		}
 
-		// Pozisyon değişmişse (minimum 2 pixel tolerans)
-		if (
-			Math.abs(currentData.x - last.x) >= 2 ||
-			Math.abs(currentData.y - last.y) >= 2
-		) {
+		// Cursor type değişmişse (pointer, text, vs)
+		if (currentData.cursorType !== last.cursorType) {
 			return true;
 		}
 
-		// Cursor type değişmişse
-		if (currentData.cursorType !== last.cursorType) {
+		// SYNC FIX: Reduced threshold for better sync (1 pixel instead of 2)
+		// With 200 FPS sampling, we can afford more granular position tracking
+		// Pozisyon değişmişse (minimum 1 pixel - hassas tracking)
+		if (
+			Math.abs(currentData.x - last.x) >= 1 ||
+			Math.abs(currentData.y - last.y) >= 1
+		) {
 			return true;
 		}
 
@@ -1033,11 +1070,14 @@ class MacRecorder extends EventEmitter {
 	 */
 	async startCursorCapture(intervalOrFilepath = 100, options = {}) {
 		let filepath;
-		let interval = 20; // Default 50 FPS
+		// SYNC FIX: Use 5ms interval (200 FPS) for ultra-smooth cursor tracking
+		// This high sampling rate ensures cursor is always in sync with 60 FPS video
+		// Even if we sample 200 times per second, we only write on position/event changes (efficient)
+		let interval = 5; // Default 200 FPS for perfect sync
 
 		// Parameter parsing: number = interval, string = filepath
 		if (typeof intervalOrFilepath === "number") {
-			interval = Math.max(10, intervalOrFilepath); // Min 10ms
+			interval = Math.max(5, intervalOrFilepath); // Min 5ms for sync
 			filepath = `cursor-data-${Date.now()}.json`;
 		} else if (typeof intervalOrFilepath === "string") {
 			filepath = intervalOrFilepath;
@@ -1132,6 +1172,10 @@ class MacRecorder extends EventEmitter {
 
 		return new Promise((resolve, reject) => {
 			try {
+				// NOTE: Native cursor tracking (NSTimer/CFRunLoop) doesn't work with Node.js event loop
+				// Using JavaScript setInterval with high frequency (5ms = 200 FPS) instead
+				// This provides excellent sync with minimal overhead due to change-detection filtering
+				
 				// Dosyayı oluştur ve temizle
 				const fs = require("fs");
 				fs.writeFileSync(filepath, "[");
@@ -1236,7 +1280,7 @@ class MacRecorder extends EventEmitter {
 					return resolve(false);
 				}
 
-				// Interval'ı durdur
+				// Stop JavaScript interval
 				clearInterval(this.cursorCaptureInterval);
 				this.cursorCaptureInterval = null;
 

package/package.json

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

package/src/avfoundation_recorder.mm

@@ -25,6 +25,9 @@ static CMTime g_avStartTime;
 static void* g_avAudioRecorder = nil;
 static NSString* g_avAudioOutputPath = nil;
 
+// SYNC FIX: Track actual recording start time (when first frame is captured)
+static NSTimeInterval g_avActualRecordingStartTime = 0;
+
 // AVFoundation screen recording implementation
 extern "C" bool startAVFoundationRecording(const std::string& outputPath,
                                            CGDirectDisplayID displayID,
@@ -34,7 +37,8 @@ extern "C" bool startAVFoundationRecording(const std::string& outputPath,
                                            bool includeMicrophone,
                                            bool includeSystemAudio,
                                            NSString* audioDeviceId,
-                                           NSString* audioOutputPath) {
+                                           NSString* audioOutputPath,
+                                           double requestedFrameRate) {
     
     if (g_avIsRecording) {
         NSLog(@"❌ AVFoundation recording already in progress");
@@ -129,15 +133,20 @@ extern "C" bool startAVFoundationRecording(const std::string& outputPath,
         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;
+
         NSDictionary *videoSettings = @{
             AVVideoCodecKey: codecKey,
             AVVideoWidthKey: @((int)recordingSize.width),
             AVVideoHeightKey: @((int)recordingSize.height),
             AVVideoCompressionPropertiesKey: @{
                 AVVideoAverageBitRateKey: @(bitrate),
-                AVVideoMaxKeyFrameIntervalKey: @30,
+                AVVideoMaxKeyFrameIntervalKey: @((int)fps),
                 AVVideoAllowFrameReorderingKey: @YES,
-                AVVideoExpectedSourceFrameRateKey: @60,
+                AVVideoExpectedSourceFrameRateKey: @((int)fps),
                 AVVideoQualityKey: @(0.95),  // 0.0-1.0, higher is better
                 AVVideoProfileLevelKey: AVVideoProfileLevelH264HighAutoLevel,
                 AVVideoH264EntropyModeKey: AVVideoH264EntropyModeCABAC
@@ -266,7 +275,7 @@ extern "C" bool startAVFoundationRecording(const std::string& outputPath,
             }
         }
 
-        // Start capture timer (10 FPS for Electron compatibility)
+        // Start capture timer using target FPS
         dispatch_queue_t captureQueue = dispatch_queue_create("AVFoundationCaptureQueue", DISPATCH_QUEUE_SERIAL);
         g_avTimer = dispatch_source_create(DISPATCH_SOURCE_TYPE_TIMER, 0, 0, captureQueue);
         
@@ -275,7 +284,7 @@ extern "C" bool startAVFoundationRecording(const std::string& outputPath,
             return false;
         }
         
-        uint64_t interval = NSEC_PER_SEC / 10; // 10 FPS for Electron stability
+        uint64_t interval = (uint64_t)(NSEC_PER_SEC / fps);
         dispatch_source_set_timer(g_avTimer, dispatch_time(DISPATCH_TIME_NOW, 0), interval, interval / 10);
         
         // Retain objects before passing to block to prevent deallocation
@@ -371,9 +380,14 @@ extern "C" bool startAVFoundationRecording(const std::string& outputPath,
                             
                             // Write frame only if input is ready
                             if (localVideoInput && localVideoInput.readyForMoreMediaData) {
-                                CMTime frameTime = CMTimeAdd(g_avStartTime, CMTimeMakeWithSeconds(g_avFrameNumber / 10.0, 600));
+                                CMTime frameTime = CMTimeAdd(g_avStartTime, CMTimeMakeWithSeconds(((double)g_avFrameNumber) / fps, 600));
                                 BOOL appendSuccess = [localPixelBufferAdaptor appendPixelBuffer:pixelBuffer withPresentationTime:frameTime];
                                 if (appendSuccess) {
+                                    // SYNC FIX: Record actual start time when first frame is written
+                                    if (g_avFrameNumber == 0) {
+                                        g_avActualRecordingStartTime = [[NSDate date] timeIntervalSince1970] * 1000; // milliseconds
+                                        MRLog(@"🎞️ AVFoundation first frame written (actual start time: %.0f)", g_avActualRecordingStartTime);
+                                    }
                                     g_avFrameNumber++;
                                 } else {
                                     NSLog(@"⚠️ Failed to append pixel buffer");
@@ -401,8 +415,8 @@ extern "C" bool startAVFoundationRecording(const std::string& outputPath,
         dispatch_resume(g_avTimer);
         g_avIsRecording = true;
         
-        MRLog(@"🎥 AVFoundation recording started: %dx%d @ 10fps", 
-              (int)recordingSize.width, (int)recordingSize.height);
+        MRLog(@"🎥 AVFoundation recording started: %dx%d @ %.0ffps", 
+              (int)recordingSize.width, (int)recordingSize.height, fps);
         
         return true;
         
@@ -473,6 +487,7 @@ extern "C" bool stopAVFoundationRecording() {
         g_avVideoInput = nil;
         g_avPixelBufferAdaptor = nil;
         g_avFrameNumber = 0;
+        g_avActualRecordingStartTime = 0;
         
         MRLog(@"✅ AVFoundation recording stopped");
         return true;
@@ -487,6 +502,11 @@ extern "C" bool isAVFoundationRecording() {
     return g_avIsRecording;
 }
 
+// SYNC FIX: Get actual recording start time for AVFoundation
+extern "C" NSTimeInterval getAVFoundationActualStartTime() {
+    return g_avActualRecordingStartTime;
+}
+
 extern "C" NSString* getAVFoundationAudioPath() {
     return g_avAudioOutputPath;
 }

package/src/cursor_tracker.mm

@@ -1032,7 +1032,9 @@ Napi::Value StartCursorTracking(const Napi::CallbackInfo& info) {
         // NSTimer kullan (main thread'de çalışır)
         g_timerTarget = [[CursorTimerTarget alloc] init];
         
-        g_cursorTimer = [NSTimer timerWithTimeInterval:0.05 // 50ms (20 FPS)
+        // SYNC FIX: Match screen recording frame rate (60 FPS = 16.67ms)
+        // This ensures cursor tracking is synchronized with video frames
+        g_cursorTimer = [NSTimer timerWithTimeInterval:0.01667 // 16.67ms (60 FPS) - matches screen recording
                                                 target:g_timerTarget
                                               selector:@selector(timerCallback:)
                                               userInfo:nil

package/src/electron_safe/screen_capture_electron.mm

@@ -121,12 +121,27 @@ static void initializeSafeQueue() {
             SCDisplay *targetDisplay = nil;
             
             if (displayId) {
+                // First, try matching by real CGDirectDisplayID
                 for (SCDisplay *display in content.displays) {
                     if (display.displayID == [displayId unsignedIntValue]) {
                         targetDisplay = display;
                         break;
                     }
                 }
+
+                // If not matched, treat provided value as index (0-based or 1-based)
+                if (!targetDisplay && content.displays.count > 0) {
+                    NSUInteger count = content.displays.count;
+                    NSUInteger idx0 = (NSUInteger)[displayId unsignedIntValue];
+                    if (idx0 < count) {
+                        targetDisplay = content.displays[idx0];
+                    } else if ([displayId unsignedIntegerValue] > 0) {
+                        NSUInteger idx1 = [displayId unsignedIntegerValue] - 1;
+                        if (idx1 < count) {
+                            targetDisplay = content.displays[idx1];
+                        }
+                    }
+                }
             }
             
             if (!targetDisplay && content.displays.count > 0) {
@@ -154,9 +169,45 @@ static void initializeSafeQueue() {
         }
         
         // Video configuration
-        config.width = 1920;
-        config.height = 1080;
-        config.minimumFrameInterval = CMTimeMake(1, 30); // 30 FPS
+        // Prefer the target display's native resolution when available
+        if (filter && [filter isKindOfClass:[SCContentFilter class]]) {
+            // Try to infer dimensions from selected display or capture area
+            NSDictionary *captureArea = options[@"captureArea"];
+            if (captureArea) {
+                config.width = (size_t)[captureArea[@"width"] doubleValue];
+                config.height = (size_t)[captureArea[@"height"] doubleValue];
+            } else {
+                // Find the selected display again to get dimensions
+                NSNumber *displayId = options[@"displayId"];
+                if (displayId) {
+                    for (SCDisplay *display in content.displays) {
+                        if (display.displayID == [displayId unsignedIntValue]) {
+                            config.width = (size_t)display.width;
+                            config.height = (size_t)display.height;
+                            break;
+                        }
+                    }
+                }
+            }
+        }
+        
+        // Fallback default resolution if not set above
+        if (config.width == 0 || config.height == 0) {
+            config.width = 1920;
+            config.height = 1080;
+        }
+        
+        // Frame rate from options (default 60)
+        NSInteger fps = 60;
+        if (options[@"frameRate"]) {
+            NSInteger v = [options[@"frameRate"] integerValue];
+            if (v > 0) {
+                if (v < 1) v = 1;
+                if (v > 120) v = 120;
+                fps = v;
+            }
+        }
+        config.minimumFrameInterval = CMTimeMake(1, (int)fps);
         config.queueDepth = 8;
         
         // Capture area if specified

package/src/mac_recorder.mm

@@ -19,9 +19,11 @@ extern "C" {
                                    bool includeMicrophone,
                                    bool includeSystemAudio,
                                    NSString* audioDeviceId,
-                                   NSString* audioOutputPath);
+                                   NSString* audioOutputPath,
+                                   double frameRate);
     bool stopAVFoundationRecording();
     bool isAVFoundationRecording();
+    NSTimeInterval getAVFoundationActualStartTime();
     NSString* getAVFoundationAudioPath();
 
     NSArray<NSDictionary *> *listCameraDevices();
@@ -204,6 +206,7 @@ Napi::Value StartRecording(const Napi::CallbackInfo& info) {
     NSString *cameraOutputPath = nil;
     int64_t sessionTimestamp = 0;
     NSString *audioOutputPath = nil;
+    double frameRate = 60.0;
     
     if (info.Length() > 1 && info[1].IsObject()) {
         Napi::Object options = info[1].As<Napi::Object>();
@@ -271,33 +274,57 @@ Napi::Value StartRecording(const Napi::CallbackInfo& info) {
         if (options.Has("sessionTimestamp") && options.Get("sessionTimestamp").IsNumber()) {
             sessionTimestamp = options.Get("sessionTimestamp").As<Napi::Number>().Int64Value();
         }
+
+        // Frame rate
+        if (options.Has("frameRate") && options.Get("frameRate").IsNumber()) {
+            double fps = options.Get("frameRate").As<Napi::Number>().DoubleValue();
+            if (fps > 0) {
+                // Clamp to reasonable range
+                if (fps < 1.0) fps = 1.0;
+                if (fps > 120.0) fps = 120.0;
+                frameRate = fps;
+            }
+        }
         
-        // Display ID
+        // Display ID (accepts either real CGDirectDisplayID or index [0-based or 1-based])
         if (options.Has("displayId") && !options.Get("displayId").IsNull()) {
             double displayIdNum = options.Get("displayId").As<Napi::Number>().DoubleValue();
             
-            // Use the display ID directly (not as an index)
-            // The JavaScript layer passes the actual CGDirectDisplayID
-            displayID = (CGDirectDisplayID)displayIdNum;
+            // First, assume the provided value is a real CGDirectDisplayID
+            CGDirectDisplayID candidateID = (CGDirectDisplayID)displayIdNum;
             
-            // Verify that this display ID is valid
-            uint32_t displayCount;
+            // Verify against active displays
+            uint32_t displayCount = 0;
             CGGetActiveDisplayList(0, NULL, &displayCount);
             if (displayCount > 0) {
                 CGDirectDisplayID *displays = (CGDirectDisplayID*)malloc(displayCount * sizeof(CGDirectDisplayID));
                 CGGetActiveDisplayList(displayCount, displays, &displayCount);
                 
-                bool validDisplay = false;
+                bool matchedByID = false;
                 for (uint32_t i = 0; i < displayCount; i++) {
-                    if (displays[i] == displayID) {
-                        validDisplay = true;
+                    if (displays[i] == candidateID) {
+                        matchedByID = true;
+                        displayID = candidateID;
                         break;
                     }
                 }
                 
-                if (!validDisplay) {
-                    // Fallback to main display if invalid ID provided
-                    displayID = CGMainDisplayID();
+                if (!matchedByID) {
+                    // Tolerant mapping: allow passing index instead of CGDirectDisplayID
+                    // Try 0-based index
+                    int idx0 = (int)displayIdNum;
+                    if (idx0 >= 0 && idx0 < (int)displayCount) {
+                        displayID = displays[idx0];
+                    } else {
+                        // Try 1-based index (common in user examples)
+                        int idx1 = (int)displayIdNum - 1;
+                        if (idx1 >= 0 && idx1 < (int)displayCount) {
+                            displayID = displays[idx1];
+                        } else {
+                            // Fallback to main display
+                            displayID = CGMainDisplayID();
+                        }
+                    }
                 }
                 
                 free(displays);
@@ -400,6 +427,8 @@ Napi::Value StartRecording(const Napi::CallbackInfo& info) {
                 if (sessionTimestamp != 0) {
                     sckConfig[@"sessionTimestamp"] = @(sessionTimestamp);
                 }
+                // Pass requested frame rate
+                sckConfig[@"frameRate"] = @(frameRate);
                 
                 if (!CGRectIsNull(captureRect)) {
                     sckConfig[@"captureRect"] = @{
@@ -511,7 +540,8 @@ Napi::Value StartRecording(const Napi::CallbackInfo& info) {
                                                    bool includeMicrophone,
                                                    bool includeSystemAudio,
                                                    NSString* audioDeviceId,
-                                                   NSString* audioOutputPath);
+                                                   NSString* audioOutputPath,
+                                                   double frameRate);
 
             // CRITICAL SYNC FIX: Start camera BEFORE screen recording for perfect sync
             // This ensures both capture their first frame at approximately the same time
@@ -529,7 +559,8 @@ Napi::Value StartRecording(const Napi::CallbackInfo& info) {
             // Now start screen recording immediately after camera
             MRLog(@"🎯 SYNC: Starting screen recording immediately");
             bool avResult = startAVFoundationRecording(outputPath, displayID, windowID, captureRect,
-                                                      captureCursor, includeMicrophone, includeSystemAudio, audioDeviceId, audioOutputPath);
+                                                      captureCursor, includeMicrophone, includeSystemAudio,
+                                                      audioDeviceId, audioOutputPath, frameRate);
 
             if (avResult) {
                 MRLog(@"🎥 RECORDING METHOD: AVFoundation");
@@ -1027,6 +1058,26 @@ Napi::Value GetRecordingStatus(const Napi::CallbackInfo& info) {
     return Napi::Boolean::New(env, isRecording);
 }
 
+// SYNC FIX: Get actual recording start time (when first frame was captured)
+Napi::Value GetActualRecordingStartTime(const Napi::CallbackInfo& info) {
+    Napi::Env env = info.Env();
+    
+    NSTimeInterval startTime = 0;
+    
+    // Check ScreenCaptureKit first
+    if (@available(macOS 12.3, *)) {
+        startTime = [ScreenCaptureKitRecorder getActualRecordingStartTime];
+    }
+    
+    // Check AVFoundation if ScreenCaptureKit didn't return a time
+    if (startTime == 0) {
+        startTime = getAVFoundationActualStartTime();
+    }
+    
+    // Return 0 if not started yet, otherwise return the actual start time in milliseconds
+    return Napi::Number::New(env, startTime);
+}
+
 // NAPI Function: Get Window Thumbnail
 Napi::Value GetWindowThumbnail(const Napi::CallbackInfo& info) {
     Napi::Env env = info.Env();
@@ -1355,6 +1406,7 @@ Napi::Object Init(Napi::Env env, Napi::Object exports) {
     exports.Set(Napi::String::New(env, "getDisplays"), Napi::Function::New(env, GetDisplays));
     exports.Set(Napi::String::New(env, "getWindows"), Napi::Function::New(env, GetWindows));
     exports.Set(Napi::String::New(env, "getRecordingStatus"), Napi::Function::New(env, GetRecordingStatus));
+    exports.Set(Napi::String::New(env, "getActualRecordingStartTime"), Napi::Function::New(env, GetActualRecordingStartTime));
     exports.Set(Napi::String::New(env, "checkPermissions"), Napi::Function::New(env, CheckPermissions));
     
     // Thumbnail functions

package/src/screen_capture_kit.h

@@ -15,5 +15,6 @@ API_AVAILABLE(macos(12.3))
 + (void)finalizeRecording;
 + (void)finalizeVideoWriter;
 + (void)cleanupVideoWriter;
++ (NSTimeInterval)getActualRecordingStartTime;
 
 @end

package/src/screen_capture_kit.mm

@@ -32,11 +32,15 @@ static BOOL g_audioWriterStarted = NO;
 
 static NSInteger g_configuredSampleRate = 48000;
 static NSInteger g_configuredChannelCount = 2;
+static NSInteger g_targetFPS = 60;
 
 // Frame rate debugging
 static NSInteger g_frameCount = 0;
 static CFAbsoluteTime g_firstFrameTime = 0;
 
+// SYNC FIX: Track actual recording start time (when first frame is captured)
+static NSTimeInterval g_actualRecordingStartTime = 0;
+
 static void CleanupWriters(void);
 static AVAssetWriterInputPixelBufferAdaptor * _Nullable CurrentPixelBufferAdaptor(void) {
     if (!g_pixelBufferAdaptorRef) {
@@ -98,6 +102,7 @@ static void CleanupWriters(void) {
         // Reset frame counting
         g_frameCount = 0;
         g_firstFrameTime = 0;
+        g_actualRecordingStartTime = 0;
     }
     
     if (g_audioWriter) {
@@ -189,7 +194,12 @@ extern "C" NSString *ScreenCaptureKitCurrentAudioPath(void) {
         [g_videoWriter startSessionAtSourceTime:presentationTime];
         g_videoStartTime = presentationTime;
         g_videoWriterStarted = YES;
-        MRLog(@"🎞️ Video writer session started @ %.3f", CMTimeGetSeconds(presentationTime));
+        
+        // SYNC FIX: Record the ACTUAL recording start time (when first frame is captured)
+        // This is the TRUE sync point - cursor tracking should use this timestamp
+        g_actualRecordingStartTime = [[NSDate date] timeIntervalSince1970] * 1000; // milliseconds
+        MRLog(@"🎞️ Video writer session started @ %.3f (actual start time: %.0f)", 
+              CMTimeGetSeconds(presentationTime), g_actualRecordingStartTime);
     }
     
     if (!g_videoInput.readyForMoreMediaData) {
@@ -342,9 +352,9 @@ extern "C" NSString *ScreenCaptureKitCurrentAudioPath(void) {
 
     NSDictionary *compressionProps = @{
         AVVideoAverageBitRateKey: @(bitrate),
-        AVVideoMaxKeyFrameIntervalKey: @30,
+        AVVideoMaxKeyFrameIntervalKey: @(MAX(1, g_targetFPS)),
         AVVideoAllowFrameReorderingKey: @YES,
-        AVVideoExpectedSourceFrameRateKey: @60,
+        AVVideoExpectedSourceFrameRateKey: @(MAX(1, g_targetFPS)),
         AVVideoQualityKey: @(0.95),  // 0.0-1.0, higher is better (0.95 = excellent)
         AVVideoProfileLevelKey: AVVideoProfileLevelH264HighAutoLevel,
         AVVideoH264EntropyModeKey: AVVideoH264EntropyModeCABAC
@@ -524,6 +534,17 @@ extern "C" NSString *ScreenCaptureKitCurrentAudioPath(void) {
     NSString *audioOutputPath = MRNormalizePath(config[@"audioOutputPath"]);
     NSNumber *sessionTimestampNumber = config[@"sessionTimestamp"];
     
+    // Extract requested frame rate
+    NSNumber *frameRateNumber = config[@"frameRate"];
+    if (frameRateNumber && [frameRateNumber respondsToSelector:@selector(intValue)]) {
+        NSInteger fps = [frameRateNumber intValue];
+        if (fps < 1) fps = 1;
+        if (fps > 120) fps = 120;
+        g_targetFPS = fps;
+    } else {
+        g_targetFPS = 60;
+    }
+    
     MRLog(@"🎬 Starting PURE ScreenCaptureKit recording (NO AVFoundation)");
     MRLog(@"🔧 Config: cursor=%@ mic=%@ system=%@ display=%@ window=%@ crop=%@", 
           captureCursor, includeMicrophone, includeSystemAudio, displayId, windowId, captureRect);
@@ -641,7 +662,7 @@ extern "C" NSString *ScreenCaptureKitCurrentAudioPath(void) {
         SCStreamConfiguration *streamConfig = [[SCStreamConfiguration alloc] init];
         streamConfig.width = recordingWidth;
         streamConfig.height = recordingHeight;
-        streamConfig.minimumFrameInterval = CMTimeMake(1, 60); // 60 FPS for smooth recording
+        streamConfig.minimumFrameInterval = CMTimeMake(1, (int)MAX(1, g_targetFPS));
         streamConfig.pixelFormat = kCVPixelFormatType_32BGRA;
         streamConfig.scalesToFit = NO;
 
@@ -650,7 +671,7 @@ extern "C" NSString *ScreenCaptureKitCurrentAudioPath(void) {
             streamConfig.queueDepth = 8; // Larger queue for smoother capture
         }
 
-        MRLog(@"🎬 ScreenCaptureKit config: %ldx%ld @ 60fps", (long)recordingWidth, (long)recordingHeight);
+        MRLog(@"🎬 ScreenCaptureKit config: %ldx%ld @ %ldfps", (long)recordingWidth, (long)recordingHeight, (long)g_targetFPS);
         
         BOOL shouldCaptureMic = includeMicrophone ? [includeMicrophone boolValue] : NO;
         BOOL shouldCaptureSystemAudio = includeSystemAudio ? [includeSystemAudio boolValue] : NO;
@@ -735,8 +756,8 @@ extern "C" NSString *ScreenCaptureKitCurrentAudioPath(void) {
         BOOL shouldShowCursor = captureCursor ? [captureCursor boolValue] : YES;
         streamConfig.showsCursor = shouldShowCursor;
         
-        MRLog(@"🎥 Pure ScreenCapture config: %ldx%ld @ 30fps, cursor=%d", 
-              recordingWidth, recordingHeight, shouldShowCursor);
+        MRLog(@"🎥 Pure ScreenCapture config: %ldx%ld @ %ldfps, cursor=%d", 
+              recordingWidth, recordingHeight, (long)g_targetFPS, shouldShowCursor);
         
         NSError *writerError = nil;
         if (![ScreenCaptureKitRecorder prepareVideoWriterWithWidth:recordingWidth height:recordingHeight error:&writerError]) {
@@ -933,9 +954,16 @@ BOOL isScreenCaptureKitCleaningUp() API_AVAILABLE(macos(12.3)) {
         g_isRecording = NO;
         g_isCleaningUp = NO;  // Reset cleanup flag
         g_outputPath = nil;
+        g_actualRecordingStartTime = 0;
         
         MRLog(@"🧹 Pure ScreenCaptureKit cleanup complete");
     }
 }
 
+// SYNC FIX: Get the actual recording start time (when first frame was captured)
+// This is the TRUE sync point for cursor tracking
++ (NSTimeInterval)getActualRecordingStartTime {
+    return g_actualRecordingStartTime;
+}
+
 @end