node-mac-recorder 2.22.7 → 2.22.8

package/index.js

@@ -856,13 +856,7 @@ class MacRecorder extends EventEmitter {
 					} catch (_) {}
 					this.sessionTimestamp = sessionTimestamp;
 
-					// CURSOR SYNC FIX: Wait additional 300ms for first frames to start
-					// This ensures cursor tracking aligns with actual video timeline
-					// ScreenCaptureKit needs ~200-350ms to actually start capturing frames
-					// We wait 300ms to ensure cursor starts AFTER first video frame
-					console.log('⏳ CURSOR SYNC: Waiting 300ms for first video frames...');
-					await new Promise(r => setTimeout(r, 300));
-
+					// Native sync_timeline handles A/V alignment - no JS-level delay needed
 					const syncTimestamp = Date.now();
 					this.syncTimestamp = syncTimestamp;
 					this.recordingStartTime = syncTimestamp;

package/package.json

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

package/src/audio_recorder.mm

@@ -336,8 +336,15 @@ static NSString *g_lastStandaloneAudioOutputPath = nil;
     }
     
     CMTime timestamp = CMSampleBufferGetPresentationTimeStamp(sampleBuffer);
+
+    // A/V SYNC: Hold audio samples until camera produces first frame
+    // This ensures both audio and camera files start from the same wall-clock moment
+    if (MRSyncShouldHoldAudioSample(timestamp)) {
+        return;
+    }
+
     MRSyncMarkAudioSample(timestamp);
-    
+
     if (!self.writerStarted) {
         if (![self.writer startWriting]) {
             NSLog(@"❌ Audio writer failed to start: %@", self.writer.error);

package/src/camera_recorder.mm

@@ -526,6 +526,9 @@ didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer
 
     CMTime timestamp = CMSampleBufferGetPresentationTimeStamp(sampleBuffer);
 
+    // A/V SYNC: Signal camera's first frame to release audio hold
+    MRSyncMarkCameraFirstFrame(timestamp);
+
     // Hold camera frames until we see audio so timelines stay aligned
     if (MRSyncShouldHoldVideoFrame(timestamp)) {
         return;
@@ -807,8 +810,8 @@ didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer
 
         [session startRunning];
 
-        // Give session a brief moment to warm up
-        [NSThread sleepForTimeInterval:0.5];
+        // A/V SYNC FIX: Removed 500ms warmup delay that was causing lip sync issues.
+        // The delegate pattern starts writing on first frame, no warmup needed.
 
         if (self.stopInFlight || token != self.activeToken) {
             [session stopRunning];

package/src/mac_recorder.mm

@@ -476,6 +476,10 @@ Napi::Value StartRecording(const Napi::CallbackInfo& info) {
     bool captureScreenAudio = captureSystemAudio || (screenCaptureSupportsMic && captureMicrophone);
     bool captureAnyAudio = captureScreenAudio || captureStandaloneMic;
     MRSyncConfigure(captureAnyAudio);
+    // A/V SYNC: Configure bidirectional barrier when camera is active
+    if (captureCamera) {
+        MRSyncConfigureCamera(YES);
+    }
     NSString *preferredAudioDeviceId = nil;
     if (captureSystemAudio && systemAudioDeviceId && [systemAudioDeviceId length] > 0) {
         preferredAudioDeviceId = systemAudioDeviceId;
@@ -619,28 +623,42 @@ Napi::Value StartRecording(const Napi::CallbackInfo& info) {
                     // Use ScreenCaptureKit with window exclusion and timeout protection
                     NSError *sckError = nil;
 
-                    // CRITICAL SYNC FIX: Start camera BEFORE ScreenCaptureKit
-                    // This allows camera warmup to happen in parallel with async ScreenCaptureKit init
+                    // A/V SYNC: Start camera non-blocking BEFORE ScreenCaptureKit
+                    // Camera warmup overlaps with async SCK initialization
                     if (captureCamera) {
-                        MRLog(@"🎥 Starting camera recording BEFORE ScreenCaptureKit (parallel warmup)");
-                        if (!startCameraWithConfirmation(true, &cameraOutputPath, cameraDeviceId, outputPath, sessionTimestamp)) {
+                        MRLog(@"🎥 Starting camera recording non-blocking (parallel with SCK init)");
+                        if (!startCameraIfRequested(true, &cameraOutputPath, cameraDeviceId, outputPath, sessionTimestamp)) {
                             MRLog(@"❌ Camera failed to start - aborting recording");
                             return Napi::Boolean::New(env, false);
                         }
                     }
 
-                    // Set timeout for ScreenCaptureKit initialization
-                    // Attempt to start ScreenCaptureKit with safety wrapper
+                    // Start SCK immediately - don't wait for camera confirmation
                     @try {
                         MRLog(@"🎯 SYNC: Starting ScreenCaptureKit recording");
                         if ([ScreenCaptureKitRecorder startRecordingWithConfiguration:sckConfig
                                                                              delegate:g_delegate
                                                                                 error:&sckError]) {
 
-                            // ScreenCaptureKit başlatma başarılı - validation yapmıyoruz
                             MRLog(@"🎬 RECORDING METHOD: ScreenCaptureKit");
                             MRLog(@"✅ SYNC: ScreenCaptureKit recording started successfully");
 
+                            // A/V SYNC: Wait for camera AFTER SCK started
+                            if (captureCamera) {
+                                if (!waitForCameraRecordingStart(8.0)) {
+                                    double cameraStartTs = currentCameraRecordingStartTime();
+                                    if (cameraStartTs > 0 || isCameraRecording()) {
+                                        MRLog(@"⚠️ Camera did not confirm start within 8.0s but appears running; continuing");
+                                    } else {
+                                        MRLog(@"❌ Camera did not signal recording start within 8.0s");
+                                        stopCameraRecording();
+                                        [ScreenCaptureKitRecorder stopRecording];
+                                        return Napi::Boolean::New(env, false);
+                                    }
+                                }
+                                MRLog(@"✅ Camera recording confirmed (started in parallel with SCK)");
+                            }
+
                             g_isRecording = true;
                             MRMarkRecordingStartTimestamp();
 
@@ -712,6 +730,15 @@ Napi::Value StartRecording(const Napi::CallbackInfo& info) {
                                                    NSString* audioOutputPath,
                                                    double frameRate);
 
+            // A/V SYNC: Start camera non-blocking BEFORE AVFoundation
+            if (captureCamera) {
+                MRLog(@"🎥 Starting camera recording non-blocking (parallel with AVF init)");
+                if (!startCameraIfRequested(true, &cameraOutputPath, cameraDeviceId, outputPath, sessionTimestamp)) {
+                    MRLog(@"❌ Camera failed to start - aborting recording");
+                    return Napi::Boolean::New(env, false);
+                }
+            }
+
             MRLog(@"🎯 SYNC: Starting screen recording");
             bool avResult = startAVFoundationRecording(outputPath, displayID, windowID, captureRect,
                                                       captureCursor, includeMicrophone, includeSystemAudio,
@@ -721,13 +748,20 @@ Napi::Value StartRecording(const Napi::CallbackInfo& info) {
                 MRLog(@"🎥 RECORDING METHOD: AVFoundation");
                 MRLog(@"✅ SYNC: Screen recording started successfully");
 
+                // A/V SYNC: Wait for camera AFTER AVF started
                 if (captureCamera) {
-                    MRLog(@"🎥 Starting camera recording for AVFoundation fallback");
-                    if (!startCameraWithConfirmation(true, &cameraOutputPath, cameraDeviceId, outputPath, sessionTimestamp)) {
-                        MRLog(@"❌ Camera failed to start for AVFoundation - stopping");
-                        stopAVFoundationRecording();
-                        return Napi::Boolean::New(env, false);
+                    if (!waitForCameraRecordingStart(8.0)) {
+                        double cameraStartTs = currentCameraRecordingStartTime();
+                        if (cameraStartTs > 0 || isCameraRecording()) {
+                            MRLog(@"⚠️ Camera did not confirm start within 8.0s but appears running; continuing");
+                        } else {
+                            MRLog(@"❌ Camera did not signal recording start within 8.0s");
+                            stopCameraRecording();
+                            stopAVFoundationRecording();
+                            return Napi::Boolean::New(env, false);
+                        }
                     }
+                    MRLog(@"✅ Camera recording confirmed (started in parallel with AVF)");
                 }
 
                 // NOTE: Audio is handled internally by AVFoundation, no need for standalone audio

package/src/screen_capture_kit.mm

@@ -631,8 +631,14 @@ extern "C" NSString *ScreenCaptureKitCurrentAudioPath(void) {
     }
     
     CMTime presentationTime = CMSampleBufferGetPresentationTimeStamp(sampleBuffer);
+
+    // A/V SYNC: Hold audio samples until camera produces first frame
+    if (MRSyncShouldHoldAudioSample(presentationTime)) {
+        return;
+    }
+
     MRSyncMarkAudioSample(presentationTime);
-    
+
     if (!g_audioWriterStarted) {
         if (![g_audioWriter startWriting]) {
             NSLog(@"❌ Audio writer failed to start: %@", g_audioWriter.error);

package/src/sync_timeline.h

@@ -26,6 +26,12 @@ CMTime MRSyncVideoAlignmentOffset(void);
 // Returns the first audio timestamp observed for the current session.
 CMTime MRSyncAudioFirstTimestamp(void);
 
+// Bidirectional camera-audio barrier: ensures both start writing from the
+// same wall-clock moment for perfect lip sync.
+void MRSyncConfigureCamera(BOOL expectCamera);
+void MRSyncMarkCameraFirstFrame(CMTime timestamp);
+BOOL MRSyncShouldHoldAudioSample(CMTime timestamp);
+
 // Optional hard stop limit (seconds) shared across capture components.
 void MRSyncSetStopLimitSeconds(double seconds);
 double MRSyncGetStopLimitSeconds(void);

package/src/sync_timeline.mm

@@ -18,6 +18,13 @@ static CMTime g_audioFirstTimestamp = kCMTimeInvalid;
 static CMTime g_alignmentDelta = kCMTimeInvalid;
 static double g_stopLimitSeconds = -1.0;
 
+// Bidirectional barrier: camera side
+static BOOL g_expectCamera = NO;
+static BOOL g_cameraReady = YES;
+static CMTime g_cameraFirstTimestamp = kCMTimeInvalid;
+static CMTime g_audioHoldFirstTimestamp = kCMTimeInvalid;
+static BOOL g_audioHoldLogged = NO;
+
 void MRSyncConfigure(BOOL expectAudio) {
     dispatch_sync(MRSyncQueue(), ^{
         g_expectAudio = expectAudio;
@@ -27,6 +34,12 @@ void MRSyncConfigure(BOOL expectAudio) {
         g_audioFirstTimestamp = kCMTimeInvalid;
         g_alignmentDelta = kCMTimeInvalid;
         g_stopLimitSeconds = -1.0;
+        // Reset camera barrier state
+        g_expectCamera = NO;
+        g_cameraReady = YES;
+        g_cameraFirstTimestamp = kCMTimeInvalid;
+        g_audioHoldFirstTimestamp = kCMTimeInvalid;
+        g_audioHoldLogged = NO;
     });
 }
 
@@ -145,6 +158,93 @@ CMTime MRSyncAudioFirstTimestamp(void) {
     return ts;
 }
 
+void MRSyncConfigureCamera(BOOL expectCamera) {
+    dispatch_sync(MRSyncQueue(), ^{
+        g_expectCamera = expectCamera;
+        g_cameraReady = expectCamera ? NO : YES;
+        g_cameraFirstTimestamp = kCMTimeInvalid;
+        g_audioHoldFirstTimestamp = kCMTimeInvalid;
+        g_audioHoldLogged = NO;
+    });
+    if (expectCamera) {
+        MRLog(@"🔄 A/V SYNC: Bidirectional barrier enabled - audio will wait for camera");
+    }
+}
+
+void MRSyncMarkCameraFirstFrame(CMTime timestamp) {
+    if (!CMTIME_IS_VALID(timestamp)) {
+        return;
+    }
+
+    __block BOOL logRelease = NO;
+    dispatch_sync(MRSyncQueue(), ^{
+        if (g_cameraReady) {
+            return;
+        }
+        if (!CMTIME_IS_VALID(g_cameraFirstTimestamp)) {
+            g_cameraFirstTimestamp = timestamp;
+        }
+        g_cameraReady = YES;
+        g_audioHoldFirstTimestamp = kCMTimeInvalid;
+        g_audioHoldLogged = NO;
+        logRelease = YES;
+    });
+
+    if (logRelease) {
+        MRLog(@"🎥 A/V SYNC: Camera first frame received - releasing audio hold");
+    }
+}
+
+BOOL MRSyncShouldHoldAudioSample(CMTime timestamp) {
+    if (!CMTIME_IS_VALID(timestamp)) {
+        return NO;
+    }
+
+    __block BOOL shouldHold = NO;
+    __block BOOL logHold = NO;
+    __block BOOL logRelease = NO;
+
+    dispatch_sync(MRSyncQueue(), ^{
+        if (!g_expectCamera || g_cameraReady) {
+            shouldHold = NO;
+            return;
+        }
+
+        // Camera not yet ready - hold audio samples
+        if (!CMTIME_IS_VALID(g_audioHoldFirstTimestamp)) {
+            g_audioHoldFirstTimestamp = timestamp;
+            shouldHold = YES;
+            if (!g_audioHoldLogged) {
+                g_audioHoldLogged = YES;
+                logHold = YES;
+            }
+            return;
+        }
+
+        // Safety timeout: release after 1.0s even if camera hasn't started
+        CMTime elapsed = CMTimeSubtract(timestamp, g_audioHoldFirstTimestamp);
+        CMTime maxWait = CMTimeMakeWithSeconds(1.0, 600);
+        if (CMTIME_COMPARE_INLINE(elapsed, >, maxWait)) {
+            g_cameraReady = YES;
+            g_audioHoldFirstTimestamp = kCMTimeInvalid;
+            g_audioHoldLogged = NO;
+            shouldHold = NO;
+            logRelease = YES;
+            return;
+        }
+
+        shouldHold = YES;
+    });
+
+    if (logHold) {
+        MRLog(@"⏸️ A/V SYNC: Audio holding samples until camera produces first frame (max 1.0s)");
+    } else if (logRelease) {
+        MRLog(@"▶️ A/V SYNC: Audio hold released by timeout (camera not detected within 1.0s)");
+    }
+
+    return shouldHold;
+}
+
 void MRSyncSetStopLimitSeconds(double seconds) {
     dispatch_sync(MRSyncQueue(), ^{
         g_stopLimitSeconds = seconds;