node-mac-recorder 2.24.16 → 2.24.17

package/package.json

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

package/src/audio_recorder.mm

@@ -7,6 +7,34 @@
 static dispatch_queue_t g_audioCaptureQueue = nil;
 static NSString *g_lastStandaloneAudioOutputPath = nil;
 
+// A real PCM prefix survives readers/exporters that normalize track timestamps
+// and ignore MOV empty edits. Allocation is bounded even for a bad device PTS.
+static CMSampleBufferRef MRCreateSilentAudioPrefix(CMSampleBufferRef sample, double seconds) {
+    CMAudioFormatDescriptionRef format = CMSampleBufferGetFormatDescription(sample);
+    const AudioStreamBasicDescription *asbd = format ? CMAudioFormatDescriptionGetStreamBasicDescription(format) : NULL;
+    if (!asbd || asbd->mFormatID != kAudioFormatLinearPCM ||
+        !isfinite(seconds) || seconds <= 0 || seconds > 30 ||
+        !isfinite(asbd->mSampleRate) || asbd->mSampleRate <= 0 ||
+        asbd->mBytesPerFrame == 0) return NULL;
+    double frameCount = floor(seconds * asbd->mSampleRate);
+    double byteCount = frameCount * asbd->mBytesPerFrame;
+    if (frameCount < 1 || byteCount > 32 * 1024 * 1024) return NULL;
+    CMBlockBufferRef block = NULL;
+    OSStatus status = CMBlockBufferCreateWithMemoryBlock(kCFAllocatorDefault, NULL, (size_t)byteCount,
+        kCFAllocatorDefault, NULL, 0, (size_t)byteCount, 0, &block);
+    if (status != noErr || !block) return NULL;
+    status = CMBlockBufferFillDataBytes(0, block, 0, (size_t)byteCount);
+    CMSampleBufferRef silence = NULL;
+    if (status == noErr) {
+        CMSampleTimingInfo timing = { CMTimeMake(1, (int32_t)asbd->mSampleRate), kCMTimeZero, kCMTimeInvalid };
+        size_t frameSize = asbd->mBytesPerFrame;
+        CMSampleBufferCreateReady(kCFAllocatorDefault, block, format, (CMItemCount)frameCount,
+            1, &timing, 1, &frameSize, &silence);
+    }
+    CFRelease(block);
+    return silence;
+}
+
 @interface NativeAudioRecorder : NSObject<AVCaptureAudioDataOutputSampleBufferDelegate>
 
 @property (nonatomic, strong) AVAssetWriter *writer;
@@ -14,6 +42,7 @@ static NSString *g_lastStandaloneAudioOutputPath = nil;
 @property (nonatomic, strong) AVCaptureSession *session;
 @property (nonatomic, strong) AVCaptureAudioDataOutput *audioOutput;
 @property (nonatomic, assign) BOOL writerStarted;
+@property (nonatomic, assign) BOOL primaryPrefixWritten;
 @property (nonatomic, assign) CMTime startTime;
 @property (nonatomic, strong) NSString *outputPath;
 
@@ -78,8 +107,10 @@ static NSString *g_lastStandaloneAudioOutputPath = nil;
     AVFileType requestedFileType = AVFileTypeQuickTimeMovie;
     BOOL requestedWebM = NO;
     if (@available(macOS 15.0, *)) {
-        requestedFileType = @"public.webm";
-        requestedWebM = YES;
+        if (!MRSyncUsesPrimaryTimeline()) {
+            requestedFileType = @"public.webm";
+            requestedWebM = YES;
+        }
     }
     
     @try {
@@ -281,7 +312,8 @@ static NSString *g_lastStandaloneAudioOutputPath = nil;
     @catch (NSException *exception) { NSLog(@"[Recorder] Microphone delegate detach: %@", exception.reason); }
     [outputToStop release];
     if (g_audioCaptureQueue) dispatch_sync(g_audioCaptureQueue, ^{});
-    MRFinishAssetWriterSafely(self.writer, 8.0);
+    MRFinishAssetWriterSafely(self.writer, 8.0,
+        MRSyncUsesPrimaryTimeline() ? MRSyncGetStopLimitSeconds() : -1.0);
 
     self.writer = nil;
     self.writerInput = nil;
@@ -298,7 +330,8 @@ static NSString *g_lastStandaloneAudioOutputPath = nil;
 - (void)captureOutput:(AVCaptureOutput *)output didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer fromConnection:(AVCaptureConnection *)connection {
     if (!self.session || output != self.audioOutput) return;
     @try {
-    if (MRSyncIsPaused()) {
+    BOOL primaryTimeline = MRSyncUsesPrimaryTimeline();
+    if (!primaryTimeline && MRSyncIsPaused()) {
         return;
     }
     if (!CMSampleBufferDataIsReady(sampleBuffer)) {
@@ -318,6 +351,11 @@ static NSString *g_lastStandaloneAudioOutputPath = nil;
     }
     
     CMTime timestamp = CMSampleBufferGetPresentationTimeStamp(sampleBuffer);
+    CMClockRef captureClock = self.session.masterClock;
+    if (primaryTimeline) {
+        timestamp = MRSyncHostTimestamp(timestamp, captureClock);
+        if (!CMTIME_IS_NUMERIC(MRSyncPrimaryMediaTime(timestamp))) return;
+    }
 
     // Keep microphone warm-up outside the recording until the USB iPhone movie
     // output has actually started writing its first frame.
@@ -327,7 +365,7 @@ static NSString *g_lastStandaloneAudioOutputPath = nil;
 
     // 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)) {
+    if (!primaryTimeline && MRSyncShouldHoldAudioSample(timestamp)) {
         return;
     }
 
@@ -340,12 +378,25 @@ static NSString *g_lastStandaloneAudioOutputPath = nil;
         }
         [self.writer startSessionAtSourceTime:kCMTimeZero];
         self.writerStarted = YES;
-        self.startTime = timestamp;
+        self.primaryPrefixWritten = NO;
+        self.startTime = primaryTimeline ? MRSyncPrimaryStartTimestamp() : timestamp;
     }
     
     if (!self.writerInput.readyForMoreMediaData) {
         return;
     }
+
+    if (primaryTimeline && !self.primaryPrefixWritten) {
+        double leadingSeconds = CMTimeGetSeconds(MRSyncPrimaryMediaTime(timestamp));
+        CMSampleBufferRef silence = MRCreateSilentAudioPrefix(sampleBuffer, leadingSeconds);
+        if (silence) {
+            BOOL appended = [self.writerInput appendSampleBuffer:silence];
+            CFRelease(silence);
+            if (!appended) return;
+        }
+        self.primaryPrefixWritten = YES;
+        if (!self.writerInput.readyForMoreMediaData) return;
+    }
     
     if (CMTIME_IS_INVALID(self.startTime)) {
         self.startTime = timestamp;
@@ -372,7 +423,10 @@ static NSString *g_lastStandaloneAudioOutputPath = nil;
                         if (CMTIME_COMPARE_INLINE(adjustedPTS, <, kCMTimeZero)) {
                             adjustedPTS = kCMTimeZero;
                         }
-                        adjustedPTS = MRSyncAdjustForPauses(adjustedPTS);
+                        adjustedPTS = primaryTimeline
+                            ? MRSyncPrimaryMediaTime(MRSyncHostTimestamp(timingInfo[i].presentationTimeStamp, captureClock))
+                            : MRSyncAdjustForPauses(adjustedPTS);
+                        if (!CMTIME_IS_NUMERIC(adjustedPTS)) shouldDropBuffer = YES;
                         timingInfo[i].presentationTimeStamp = adjustedPTS;
                         
                         if (stopLimit > 0) {
@@ -392,7 +446,9 @@ static NSString *g_lastStandaloneAudioOutputPath = nil;
                         if (CMTIME_COMPARE_INLINE(adjustedDTS, <, kCMTimeZero)) {
                             adjustedDTS = kCMTimeZero;
                         }
-                        timingInfo[i].decodeTimeStamp = MRSyncAdjustForPauses(adjustedDTS);
+                        timingInfo[i].decodeTimeStamp = primaryTimeline
+                            ? MRSyncPrimaryMediaTime(MRSyncHostTimestamp(timingInfo[i].decodeTimeStamp, captureClock))
+                            : MRSyncAdjustForPauses(adjustedDTS);
                     }
                 }
                 
@@ -412,6 +468,9 @@ static NSString *g_lastStandaloneAudioOutputPath = nil;
         }
     }
 
+    // Never feed absolute device-clock timestamps into a zero-based iPhone
+    // writer if allocation or retiming failed.
+    if (primaryTimeline && bufferToAppend == sampleBuffer) shouldDropBuffer = YES;
     if (stopLimit > 0 && !shouldDropBuffer && bufferToAppend == sampleBuffer) {
         // No timing info available; approximate using buffer timestamp.
         CMTime pts = CMSampleBufferGetPresentationTimeStamp(sampleBuffer);

package/src/camera_recorder.mm

@@ -111,6 +111,7 @@ static void MRCameraRemoveFileIfExists(NSString *path) {
 @property (nonatomic, strong) AVAssetWriterInputPixelBufferAdaptor *pixelBufferAdaptor;
 @property (nonatomic, assign) CMTime startTime;
 @property (nonatomic, assign) BOOL writerStarted;
+@property (nonatomic, assign) BOOL primaryPrefixWritten;
 @property (nonatomic, copy) NSString *outputPath;
 @property (nonatomic, copy) NSString *lastFinishedOutputPath;
 
@@ -510,7 +511,8 @@ didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer
     if (self.stopInFlight || !self.isRecording || output != self.videoOutput) return;
     @try {
 
-    if (MRSyncIsPaused()) {
+    BOOL primaryTimeline = MRSyncUsesPrimaryTimeline();
+    if (!primaryTimeline && MRSyncIsPaused()) {
         return;
     }
 
@@ -532,6 +534,12 @@ didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer
     }
 
     CMTime timestamp = CMSampleBufferGetPresentationTimeStamp(sampleBuffer);
+    CMTime primaryMediaTime = kCMTimeInvalid;
+    if (primaryTimeline) {
+        timestamp = MRSyncHostTimestamp(timestamp, self.session.masterClock);
+        primaryMediaTime = MRSyncPrimaryMediaTime(timestamp);
+        if (!CMTIME_IS_NUMERIC(primaryMediaTime)) return;
+    }
 
     // Drop camera warm-up frames until the primary source (USB iPhone screen)
     // has committed its first frame. This keeps all files on one t=0 boundary.
@@ -549,7 +557,7 @@ didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer
     [self completeStart:YES token:self.activeToken];
 
     // Hold camera frames until we see audio so timelines stay aligned
-    if (MRSyncShouldHoldVideoFrame(timestamp)) {
+    if (!primaryTimeline && MRSyncShouldHoldVideoFrame(timestamp)) {
         return;
     }
 
@@ -561,13 +569,16 @@ didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer
         }
         [self.writer startSessionAtSourceTime:kCMTimeZero];  // CRITICAL: t=0 timeline
         self.writerStarted = YES;
+        self.primaryPrefixWritten = NO;
         
         // LIP SYNC FIX: Align camera startTime with audio's first timestamp for perfect lip sync
         // This ensures camera and audio start from the same reference point
         CMTime audioFirstTimestamp = MRSyncAudioFirstTimestamp();
         CMTime alignmentOffset = MRSyncVideoAlignmentOffset();
         
-        if (CMTIME_IS_VALID(audioFirstTimestamp)) {
+        if (primaryTimeline) {
+            self.startTime = MRSyncPrimaryStartTimestamp();
+        } else if (CMTIME_IS_VALID(audioFirstTimestamp)) {
             // Use audio's first timestamp as reference - this is the key to lip sync
             self.startTime = audioFirstTimestamp;
             CMTime offset = CMTimeSubtract(timestamp, audioFirstTimestamp);
@@ -606,7 +617,7 @@ didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer
         // This should not happen if sync is working correctly
         adjustedTimestamp = kCMTimeZero;
     }
-    adjustedTimestamp = MRSyncAdjustForPauses(adjustedTimestamp);
+    adjustedTimestamp = primaryTimeline ? primaryMediaTime : MRSyncAdjustForPauses(adjustedTimestamp);
 
     // LIP SYNC FIX: Check stopLimit OR elapsed time to drop frames after recording duration
     // This prevents camera from recording longer than audio
@@ -650,6 +661,15 @@ didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer
         return;
     }
 
+    // Keep a late camera's initial delay in the media itself. Some demuxers
+    // discard MOV empty edits and would otherwise pull the camera ahead of mic.
+    if (primaryTimeline && !self.primaryPrefixWritten) {
+        if (CMTimeCompare(adjustedTimestamp, kCMTimeZero) > 0 &&
+            ![self.pixelBufferAdaptor appendPixelBuffer:pixelBuffer withPresentationTime:kCMTimeZero]) return;
+        self.primaryPrefixWritten = YES;
+        if (!self.writerInput.readyForMoreMediaData) return;
+    }
+
     // Append to writer with normalized timestamp
     BOOL success = [self.pixelBufferAdaptor appendPixelBuffer:pixelBuffer
                                          withPresentationTime:adjustedTimestamp];

package/src/ios_device_recorder.mm

@@ -17,7 +17,7 @@ extern "C" bool isStandaloneAudioRecording(void);
 extern "C" bool pauseIOSDeviceRecording(void);
 extern "C" bool resumeIOSDeviceRecording(void);
 
-@interface MRIOSDeviceRecorder : NSObject <AVCaptureFileOutputRecordingDelegate>
+@interface MRIOSDeviceRecorder : NSObject <AVCaptureFileOutputRecordingDelegate, AVCaptureFileOutputDelegate>
 @property(nonatomic, strong) AVCaptureSession *session;
 @property(nonatomic, strong) AVCaptureDeviceInput *deviceInput;
 @property(nonatomic, strong) AVCaptureMovieFileOutput *movieOutput;
@@ -27,6 +27,7 @@ extern "C" bool resumeIOSDeviceRecording(void);
 @property(atomic) BOOL finishCompleted;
 @property(atomic) BOOL startRequested;
 @property(atomic) BOOL stopRequested;
+@property(atomic) BOOL segmentStartPending;
 @property(atomic, strong) NSError *finishError;
 @property(atomic) BOOL paused;
 @property(atomic) BOOL segmentStartCompleted;
@@ -42,7 +43,8 @@ extern "C" bool resumeIOSDeviceRecording(void);
 @property(nonatomic) BOOL captureMicrophone;
 @property(nonatomic, copy) NSString *cameraOutputPath;
 @property(nonatomic, copy) NSString *audioOutputPath;
-@property(nonatomic, strong) NSDate *primaryStartedAt;
+@property(atomic) CMTime primaryStartHostTime;
+@property(atomic) CMTime stopHostTime;
 @end
 
 static BOOL MRIOSHasProducedMedia(MRIOSDeviceRecorder *recorder) {
@@ -67,10 +69,6 @@ static void MRIOSMarkSegmentStarted(MRIOSDeviceRecorder *recorder,
     recorder.segmentStartCompleted = YES;
     if (!recorder.startCompleted) {
         recorder.startCompleted = YES;
-        recorder.primaryStartedAt = [NSDate date];
-        if (!recorder.stopRequested) {
-            MRSyncMarkPrimaryStarted(CMClockGetTime(CMClockGetHostTimeClock()));
-        }
     }
     if (!confirmedByDelegate) {
         MRLog(@"✅ iPhone capture start confirmed from recorded media progress");
@@ -79,6 +77,36 @@ static void MRIOSMarkSegmentStarted(MRIOSDeviceRecorder *recorder,
 
 @implementation MRIOSDeviceRecorder
 
+- (BOOL)captureOutputShouldProvideSampleAccurateRecordingStart:(AVCaptureOutput *)output {
+    return YES;
+}
+
+- (void)captureOutput:(AVCaptureFileOutput *)output
+        didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer
+        fromConnection:(AVCaptureConnection *)connection {
+    if (!self.segmentStartPending || !CMSampleBufferDataIsReady(sampleBuffer)) return;
+    @synchronized (self) {
+        if (!self.segmentStartPending || self.stopRequested) return;
+        CMTime hostTime = MRSyncHostTimestamp(
+            CMSampleBufferGetPresentationTimeStamp(sampleBuffer), self.session.masterClock);
+        if (!CMTIME_IS_NUMERIC(hostTime)) return;
+        self.segmentStartPending = NO;
+        @try {
+            // macOS guarantees that a start requested inside this delegate
+            // includes this exact sample. The later didStart/progress signal
+            // confirms success but must never redefine the media's origin.
+            [output startRecordingToOutputFileURL:[NSURL fileURLWithPath:self.currentSegmentPath]
+                               recordingDelegate:self];
+            self.primaryStartHostTime = hostTime;
+            MRSyncMarkPrimaryStarted(hostTime);
+        } @catch (NSException *exception) {
+            self.segmentFinishError = [NSError errorWithDomain:@"MacRecorderIOS" code:18
+                userInfo:@{NSLocalizedDescriptionKey: exception.reason ?: @"iPhone sample start failed"}];
+            self.segmentFinishCompleted = YES;
+        }
+    }
+}
+
 - (void)captureOutput:(AVCaptureFileOutput *)captureOutput
         didStartRecordingToOutputFileAtURL:(NSURL *)fileURL
         fromConnections:(NSArray<AVCaptureConnection *> *)connections {
@@ -303,27 +331,27 @@ static BOOL MRIOSFileOutputSucceeded(NSError *error) {
     return [successfullyFinished boolValue];
 }
 
-static NSTimeInterval MRIOSRecordedDurationSeconds(MRIOSDeviceRecorder *recorder) {
+static NSTimeInterval MRIOSRecordedDurationSeconds(MRIOSDeviceRecorder *recorder, CMTime hostTime) {
+    if (CMTIME_IS_NUMERIC(recorder.primaryStartHostTime)) {
+        return MAX(0.0, CMTimeGetSeconds(CMTimeSubtract(hostTime, recorder.primaryStartHostTime)));
+    }
     CMTime duration = recorder.movieOutput.recordedDuration;
     if (CMTIME_IS_NUMERIC(duration) &&
         CMTIME_COMPARE_INLINE(duration, >=, kCMTimeZero)) {
         return MAX(0.0, CMTimeGetSeconds(duration));
     }
-    if (recorder.primaryStartedAt) {
-        return MAX(0.0, -[recorder.primaryStartedAt timeIntervalSinceNow]);
-    }
     return 0.0;
 }
 
-static void MRIOSBeginPauseRange(MRIOSDeviceRecorder *recorder) {
-    recorder.pauseStartedAtSeconds = MRIOSRecordedDurationSeconds(recorder);
+static void MRIOSBeginPauseRange(MRIOSDeviceRecorder *recorder, CMTime hostTime) {
+    recorder.pauseStartedAtSeconds = MRIOSRecordedDurationSeconds(recorder, hostTime);
     MRLog(@"⏸️ iPhone capture pause marker at %.3f seconds",
           recorder.pauseStartedAtSeconds);
 }
 
-static void MRIOSEndPauseRange(MRIOSDeviceRecorder *recorder) {
+static void MRIOSEndPauseRange(MRIOSDeviceRecorder *recorder, CMTime hostTime) {
     if (recorder.pauseStartedAtSeconds < 0.0) return;
-    NSTimeInterval end = MRIOSRecordedDurationSeconds(recorder);
+    NSTimeInterval end = MRIOSRecordedDurationSeconds(recorder, hostTime);
     NSTimeInterval start = recorder.pauseStartedAtSeconds;
     recorder.pauseStartedAtSeconds = -1.0;
     if (end <= start) return;
@@ -358,8 +386,7 @@ static BOOL MRIOSStartNextSegment(MRIOSDeviceRecorder *recorder, NSError **error
     recorder.segmentFinishError = nil;
     recorder.recording = NO;
 
-    [recorder.movieOutput startRecordingToOutputFileURL:[NSURL fileURLWithPath:segmentPath]
-                                      recordingDelegate:recorder];
+    recorder.segmentStartPending = YES;
     // AVCaptureMovieFileOutput can begin writing before its delegate callback
     // is delivered. That callback may be queued behind Electron's synchronous
     // native call, so requiring only the callback creates a false timeout even
@@ -391,7 +418,7 @@ static BOOL MRIOSStartNextSegment(MRIOSDeviceRecorder *recorder, NSError **error
               (unsigned long)recorder.movieOutput.connections.count);
         if (errorOut) {
             BOOL connectedButNoFrames = recorder.session.isRunning &&
-                recorder.movieOutput.isRecording && durationSeconds <= 0.0;
+                (recorder.segmentStartPending || recorder.movieOutput.isRecording) && durationSeconds <= 0.0;
             *errorOut = recorder.segmentFinishError ?: (connectedButNoFrames
                 ? MRIOSNoFramesError()
                 : [NSError errorWithDomain:@"MacRecorderIOS"
@@ -405,9 +432,10 @@ static BOOL MRIOSStartNextSegment(MRIOSDeviceRecorder *recorder, NSError **error
 }
 
 static BOOL MRIOSStopCurrentSegment(MRIOSDeviceRecorder *recorder) {
-    if (recorder.movieOutput.isRecording) {
-        [recorder.movieOutput stopRecording];
+    @synchronized (recorder) {
+        recorder.segmentStartPending = NO;
     }
+    if (recorder.movieOutput.isRecording) [recorder.movieOutput stopRecording];
     if (recorder.segmentStartCompleted && !recorder.segmentFinishCompleted) {
         if (!MRWaitForFlag(^bool{ return recorder.segmentFinishCompleted; }, 20.0)) {
             MRLog(@"⚠️ iPhone segment is still finalizing");
@@ -692,7 +720,9 @@ extern "C" bool startIOSDeviceRecording(NSString *outputPath,
         recorder.captureMicrophone = captureMicrophone;
         recorder.cameraOutputPath = cameraOutputPath;
         recorder.audioOutputPath = audioOutputPath;
-        recorder.primaryStartedAt = nil;
+        recorder.primaryStartHostTime = kCMTimeInvalid;
+        recorder.stopHostTime = kCMTimeInvalid;
+        recorder.movieOutput.delegate = recorder;
 
         g_iosRecorder = recorder;
         [recorder.session beginConfiguration];
@@ -728,12 +758,11 @@ extern "C" bool startIOSDeviceRecording(NSString *outputPath,
         recorder.movieOutput.movieFragmentInterval = CMTimeMakeWithSeconds(2.0, 600);
         g_iosRecorder = recorder;
 
-        // Camera and microphone sessions are prepared first but discard their
-        // warm-up samples until AVCaptureMovieFileOutput confirms the iPhone's
-        // first frame. Every produced file therefore starts at the same t=0.
+        // Use the sample-accurate USB origin for every file, including a camera
+        // or microphone whose first callback arrives later.
         MRSyncConfigure(captureMicrophone);
         MRSyncConfigureCamera(captureCamera);
-        MRSyncConfigurePrimaryStart(captureCamera || captureMicrophone);
+        MRSyncConfigurePrimaryStart(YES);
 
         if (captureCamera) {
             NSError *cameraError = nil;
@@ -838,15 +867,24 @@ extern "C" bool stopIOSDeviceRecording(void) {
         MRIOSDeviceRecorder *recorder = g_iosRecorder;
         if (!recorder) return true;
 
-        recorder.stopRequested = YES;
-        if (recorder.primaryStartedAt) {
-            NSTimeInterval duration = MAX(0.0,
-                -[recorder.primaryStartedAt timeIntervalSinceNow] - MRSyncGetPausedDurationSeconds());
-            MRSyncSetStopLimitSeconds(duration);
+        CMTime stopHostTime;
+        @synchronized (recorder) {
+            if (!CMTIME_IS_NUMERIC(recorder.stopHostTime)) {
+                recorder.stopHostTime = CMClockGetTime(CMClockGetHostTimeClock());
+            }
+            stopHostTime = recorder.stopHostTime;
+            recorder.stopRequested = YES;
+            recorder.segmentStartPending = NO;
         }
+        // Request the USB stop before waiting for either auxiliary writer.
+        // Do not hold the delegate lock across an AVFoundation stop call.
+        if (recorder.movieOutput.isRecording) [recorder.movieOutput stopRecording];
         if (recorder.paused) {
-            MRIOSEndPauseRange(recorder);
+            MRIOSEndPauseRange(recorder, stopHostTime);
+            MRSyncResumeAtHostTime(stopHostTime);
         }
+        CMTime mediaStopTime = MRSyncPrimaryMediaTime(stopHostTime);
+        if (CMTIME_IS_NUMERIC(mediaStopTime)) MRSyncSetStopLimitSeconds(CMTimeGetSeconds(mediaStopTime));
 
         BOOL cameraStopped = YES;
         BOOL microphoneStopped = YES;
@@ -894,6 +932,7 @@ extern "C" bool stopIOSDeviceRecording(void) {
         } @catch (NSException *exception) {
             MRLog(@"⚠️ iPhone capture teardown warning: %@", exception.reason);
         }
+        recorder.movieOutput.delegate = nil;
         recorder.movieOutput = nil;
         recorder.deviceInput = nil;
         recorder.session = nil;
@@ -906,7 +945,7 @@ extern "C" bool stopIOSDeviceRecording(void) {
         recorder.outputPath = nil;
         recorder.cameraOutputPath = nil;
         recorder.audioOutputPath = nil;
-        recorder.primaryStartedAt = nil;
+        recorder.primaryStartHostTime = kCMTimeInvalid;
         g_iosRecorder = nil;
         [recorder release];
 
@@ -948,12 +987,13 @@ extern "C" bool pauseIOSDeviceRecording(void) {
             // Do not stop or pause AVCaptureMovieFileOutput here. USB iPhone
             // muxed sources may fail to re-arm their compressor on resume.
             // Capture continuously and trim this time range during finalization.
-            MRIOSBeginPauseRange(recorder);
-            MRSyncPause();
+            CMTime pauseHostTime = CMClockGetTime(CMClockGetHostTimeClock());
+            MRIOSBeginPauseRange(recorder, pauseHostTime);
+            MRSyncPauseAtHostTime(pauseHostTime);
             recorder.paused = YES;
             return true;
         } @catch (NSException *exception) {
-            MRSyncResume();
+            MRSyncResumeAtHostTime(CMClockGetTime(CMClockGetHostTimeClock()));
             MRLog(@"❌ iPhone pause failed: %@", exception.reason);
             return false;
         }
@@ -967,9 +1007,10 @@ extern "C" bool resumeIOSDeviceRecording(void) {
         if (!recorder.paused) return recorder.movieOutput.isRecording;
         if (!recorder.movieOutput.isRecording) return false;
         @try {
-            MRIOSEndPauseRange(recorder);
+            CMTime resumeHostTime = CMClockGetTime(CMClockGetHostTimeClock());
+            MRIOSEndPauseRange(recorder, resumeHostTime);
             recorder.paused = NO;
-            MRSyncResume();
+            MRSyncResumeAtHostTime(resumeHostTime);
             return true;
         } @catch (NSException *exception) {
             MRLog(@"❌ iPhone resume failed: %@", exception.reason);

package/src/sync_timeline.h

@@ -40,6 +40,16 @@ void MRSyncConfigurePrimaryStart(BOOL expectPrimary);
 void MRSyncMarkPrimaryStarted(CMTime timestamp);
 BOOL MRSyncShouldHoldForPrimary(CMTime timestamp);
 
+// iPhone-only timeline. Convert each capture session's PTS to the host clock
+// before comparing sources; preserve late arrivals instead of rebasing each
+// file to its own first sample. Invalid media time means discard the sample.
+BOOL MRSyncUsesPrimaryTimeline(void);
+CMTime MRSyncPrimaryStartTimestamp(void);
+CMTime MRSyncHostTimestamp(CMTime timestamp, CMClockRef captureClock);
+CMTime MRSyncPrimaryMediaTime(CMTime hostTimestamp);
+void MRSyncPauseAtHostTime(CMTime timestamp);
+void MRSyncResumeAtHostTime(CMTime timestamp);
+
 // Optional hard stop limit (seconds) shared across capture components.
 void MRSyncSetStopLimitSeconds(double seconds);
 double MRSyncGetStopLimitSeconds(void);

package/src/sync_timeline.mm

@@ -1,5 +1,6 @@
 #import "sync_timeline.h"
 #import "logging.h"
+#include <vector>
 
 static dispatch_queue_t MRSyncQueue() {
     static dispatch_once_t onceToken;
@@ -34,6 +35,8 @@ static BOOL g_primaryReady = YES;
 static CMTime g_primaryStartTimestamp = kCMTimeInvalid;
 static CMTime g_primaryHoldFirstTimestamp = kCMTimeInvalid;
 static BOOL g_primaryHoldLogged = NO;
+struct MRPrimaryPauseRange { CMTime start; CMTime end; };
+static std::vector<MRPrimaryPauseRange> g_primaryPauses;
 
 void MRSyncConfigure(BOOL expectAudio) {
     dispatch_sync(MRSyncQueue(), ^{
@@ -58,6 +61,7 @@ void MRSyncConfigure(BOOL expectAudio) {
         g_primaryStartTimestamp = kCMTimeInvalid;
         g_primaryHoldFirstTimestamp = kCMTimeInvalid;
         g_primaryHoldLogged = NO;
+        g_primaryPauses.clear();
     });
 }
 
@@ -94,7 +98,10 @@ double MRSyncGetPausedDurationSeconds(void) {
     __block double duration = 0;
     dispatch_sync(MRSyncQueue(), ^{
         duration = g_totalPausedSeconds;
-        if (g_isPaused && g_pauseStartedAt > 0) {
+        if (g_expectPrimary && g_isPaused && !g_primaryPauses.empty()) {
+            duration += MAX(0, CMTimeGetSeconds(CMTimeSubtract(
+                CMClockGetTime(CMClockGetHostTimeClock()), g_primaryPauses.back().start)));
+        } else if (g_isPaused && g_pauseStartedAt > 0) {
             duration += MAX(0, CFAbsoluteTimeGetCurrent() - g_pauseStartedAt);
         }
     });
@@ -318,12 +325,67 @@ void MRSyncConfigurePrimaryStart(BOOL expectPrimary) {
         g_primaryStartTimestamp = kCMTimeInvalid;
         g_primaryHoldFirstTimestamp = kCMTimeInvalid;
         g_primaryHoldLogged = NO;
+        g_primaryPauses.clear();
     });
     if (expectPrimary) {
         MRLog(@"🔄 A/V SYNC: Primary-source start barrier enabled");
     }
 }
 
+BOOL MRSyncUsesPrimaryTimeline(void) {
+    __block BOOL enabled = NO;
+    dispatch_sync(MRSyncQueue(), ^{ enabled = g_expectPrimary; });
+    return enabled;
+}
+
+CMTime MRSyncPrimaryStartTimestamp(void) {
+    __block CMTime timestamp = kCMTimeInvalid;
+    dispatch_sync(MRSyncQueue(), ^{ timestamp = g_primaryStartTimestamp; });
+    return timestamp;
+}
+
+CMTime MRSyncHostTimestamp(CMTime timestamp, CMClockRef captureClock) {
+    if (!CMTIME_IS_NUMERIC(timestamp) || !captureClock) return kCMTimeInvalid;
+    return CMSyncConvertTime(timestamp, captureClock, CMClockGetHostTimeClock());
+}
+
+CMTime MRSyncPrimaryMediaTime(CMTime hostTimestamp) {
+    if (!CMTIME_IS_NUMERIC(hostTimestamp)) return kCMTimeInvalid;
+    __block CMTime result = kCMTimeInvalid;
+    dispatch_sync(MRSyncQueue(), ^{
+        if (!g_expectPrimary || !CMTIME_IS_NUMERIC(g_primaryStartTimestamp) ||
+            CMTimeCompare(hostTimestamp, g_primaryStartTimestamp) < 0) return;
+        CMTime paused = kCMTimeZero;
+        for (const auto &range : g_primaryPauses) {
+            if (CMTimeCompare(hostTimestamp, range.start) < 0) break;
+            if (!CMTIME_IS_NUMERIC(range.end) || CMTimeCompare(hostTimestamp, range.end) < 0) return;
+            paused = CMTimeAdd(paused, CMTimeSubtract(range.end, range.start));
+        }
+        result = CMTimeSubtract(CMTimeSubtract(hostTimestamp, g_primaryStartTimestamp), paused);
+    });
+    return result;
+}
+
+void MRSyncPauseAtHostTime(CMTime timestamp) {
+    if (!CMTIME_IS_NUMERIC(timestamp)) return;
+    dispatch_sync(MRSyncQueue(), ^{
+        if (!g_expectPrimary || g_isPaused) return;
+        g_primaryPauses.push_back({timestamp, kCMTimeInvalid});
+        g_isPaused = YES;
+    });
+}
+
+void MRSyncResumeAtHostTime(CMTime timestamp) {
+    if (!CMTIME_IS_NUMERIC(timestamp)) return;
+    dispatch_sync(MRSyncQueue(), ^{
+        if (!g_expectPrimary || !g_isPaused || g_primaryPauses.empty()) return;
+        auto &range = g_primaryPauses.back();
+        range.end = CMTimeMaximum(timestamp, range.start);
+        g_totalPausedSeconds += CMTimeGetSeconds(CMTimeSubtract(range.end, range.start));
+        g_isPaused = NO;
+    });
+}
+
 void MRSyncMarkPrimaryStarted(CMTime timestamp) {
     if (!CMTIME_IS_VALID(timestamp)) return;
 

package/tests/ios-sync-probe.mm

@@ -0,0 +1,249 @@
+// Exercise the production delegates and MOV writers without opening devices.
+#import "../src/sync_timeline.mm"
+#import "../src/audio_recorder.mm"
+#import "../src/camera_recorder.mm"
+#import "../src/ios_device_recorder.mm"
+#include <unistd.h>
+
+@interface MRProbeSession : AVCaptureSession
+@property(nonatomic, assign) CMClockRef probeClock;
+@end
+@implementation MRProbeSession
+- (CMClockRef)masterClock { return self.probeClock ?: CMClockGetHostTimeClock(); }
+- (BOOL)isRunning { return NO; }
+@end
+
+@interface MRProbeMovieOutput : AVCaptureMovieFileOutput
+@property NSUInteger starts;
+@end
+@implementation MRProbeMovieOutput
+- (void)startRecordingToOutputFileURL:(NSURL *)url recordingDelegate:(id<AVCaptureFileOutputRecordingDelegate>)delegate {
+    self.starts += 1;
+}
+@end
+
+static CMTime T(double seconds) { return CMTimeMakeWithSeconds(seconds, 48000); }
+
+static CMSampleBufferRef Video(double seconds) {
+    CVPixelBufferRef pixels = NULL;
+    CVPixelBufferCreate(kCFAllocatorDefault, 64, 64, kCVPixelFormatType_32BGRA,
+        (CFDictionaryRef)@{(id)kCVPixelBufferIOSurfacePropertiesKey: @{}}, &pixels);
+    CVPixelBufferLockBaseAddress(pixels, 0);
+    memset(CVPixelBufferGetBaseAddress(pixels), 128, CVPixelBufferGetDataSize(pixels));
+    CVPixelBufferUnlockBaseAddress(pixels, 0);
+    CMVideoFormatDescriptionRef format = NULL;
+    CMVideoFormatDescriptionCreateForImageBuffer(kCFAllocatorDefault, pixels, &format);
+    CMSampleTimingInfo timing = { T(1.0 / 30), T(seconds), kCMTimeInvalid };
+    CMSampleBufferRef sample = NULL;
+    CMSampleBufferCreateReadyWithImageBuffer(kCFAllocatorDefault, pixels, format, &timing, &sample);
+    CFRelease(format);
+    CFRelease(pixels);
+    return sample;
+}
+
+static CMSampleBufferRef Audio(double seconds) {
+    AudioStreamBasicDescription asbd = {};
+    asbd.mSampleRate = 48000;
+    asbd.mFormatID = kAudioFormatLinearPCM;
+    asbd.mFormatFlags = kAudioFormatFlagIsSignedInteger | kAudioFormatFlagIsPacked;
+    asbd.mBytesPerPacket = asbd.mBytesPerFrame = 2;
+    asbd.mFramesPerPacket = asbd.mChannelsPerFrame = 1;
+    asbd.mBitsPerChannel = 16;
+    CMAudioFormatDescriptionRef format = NULL;
+    CMAudioFormatDescriptionCreate(kCFAllocatorDefault, &asbd, 0, NULL, 0, NULL, NULL, &format);
+    CMBlockBufferRef block = NULL;
+    CMBlockBufferCreateWithMemoryBlock(kCFAllocatorDefault, NULL, 1920,
+        kCFAllocatorDefault, NULL, 0, 1920, 0, &block);
+    CMBlockBufferFillDataBytes(0, block, 0, 1920);
+    char *data = NULL;
+    CMBlockBufferGetDataPointer(block, 0, NULL, NULL, &data);
+    for (int i = 0; i < 960; i++) ((int16_t *)data)[i] = (int16_t)(8000 * sin(i * 2 * M_PI / 48));
+    CMSampleTimingInfo timing = { T(1.0 / 48000), T(seconds), kCMTimeInvalid };
+    size_t size = 2;
+    CMSampleBufferRef sample = NULL;
+    CMSampleBufferCreateReady(kCFAllocatorDefault, block, format, 960, 1, &timing, 1, &size, &sample);
+    CFRelease(format);
+    CFRelease(block);
+    return sample;
+}
+
+static void WaitForInput(AVAssetWriterInput *input) {
+    for (int i = 0; input && !input.readyForMoreMediaData && i < 2000; i++) usleep(1000);
+}
+
+static Napi::Value Run(const Napi::CallbackInfo &info) {
+    @autoreleasepool {
+        NSString *directory = [NSString stringWithUTF8String:info[0].As<Napi::String>().Utf8Value().c_str()];
+        NSMutableArray *failures = [NSMutableArray array];
+        NSUInteger checks = 0;
+        auto check = [&](BOOL ok, NSString *message) { checks++; if (!ok) [failures addObject:message]; };
+        auto near = [&](CMTime actual, double expected, NSString *message) {
+            check(CMTIME_IS_NUMERIC(actual) && fabs(CMTimeGetSeconds(actual) - expected) < 0.0001, message);
+        };
+
+        MRSyncConfigure(YES);
+        MRSyncConfigureCamera(YES);
+        MRSyncConfigurePrimaryStart(YES);
+        check(!CMTIME_IS_NUMERIC(MRSyncPrimaryMediaTime(T(100))), @"warmup must not enter a writer");
+        MRIOSDeviceRecorder *phone = [[[MRIOSDeviceRecorder alloc] init] autorelease];
+        phone.session = [[[MRProbeSession alloc] init] autorelease];
+        MRProbeMovieOutput *movie = [[[MRProbeMovieOutput alloc] init] autorelease];
+        phone.movieOutput = movie;
+        phone.currentSegmentPath = [directory stringByAppendingPathComponent:@"phone.mov"];
+        phone.primaryStartHostTime = kCMTimeInvalid;
+        phone.segmentStartPending = YES;
+        CMSampleBufferRef first = Video(100);
+        [phone captureOutput:movie didOutputSampleBuffer:first fromConnection:nil];
+        [phone captureOutput:movie didOutputSampleBuffer:first fromConnection:nil];
+        CFRelease(first);
+        check(movie.starts == 1, @"sample-accurate USB start must happen exactly once");
+        near(MRSyncPrimaryStartTimestamp(), 100, @"origin must come from the first USB sample");
+        MRIOSMarkSegmentStarted(phone, NO);
+        MRIOSMarkSegmentStarted(phone, YES);
+        near(MRSyncPrimaryStartTimestamp(), 100, @"delayed progress/delegate must not move the origin");
+        check(!CMTIME_IS_NUMERIC(MRSyncPrimaryMediaTime(T(99.9))), @"pre-origin samples are discarded");
+        near(MRSyncPrimaryMediaTime(T(100.6)), 0.6, @"late camera keeps its actual offset");
+        check(!CMTIME_IS_NUMERIC(MRSyncHostTimestamp(T(100), NULL)), @"missing capture clock is rejected");
+
+        // Distinct session clock epochs must not become an A/V offset.
+        CMTimebaseRef cameraClock = NULL, audioClock = NULL;
+        CMTimebaseCreateWithSourceClock(kCFAllocatorDefault, CMClockGetHostTimeClock(), &cameraClock);
+        CMTimebaseCreateWithSourceClock(kCFAllocatorDefault, CMClockGetHostTimeClock(), &audioClock);
+        CMTimebaseSetTime(cameraClock, T(2000));
+        CMTimebaseSetRate(cameraClock, 1);
+        CMTimebaseSetTime(audioClock, T(500));
+        CMTimebaseSetRate(audioClock, 1);
+        MRProbeSession *cameraSession = [[[MRProbeSession alloc] init] autorelease];
+        cameraSession.probeClock = (CMClockRef)cameraClock;
+        MRProbeSession *audioSession = [[[MRProbeSession alloc] init] autorelease];
+        audioSession.probeClock = (CMClockRef)audioClock;
+
+        CameraRecorder *camera = [[[CameraRecorder alloc] init] autorelease];
+        camera.session = cameraSession;
+        camera.videoOutput = [[[AVCaptureVideoDataOutput alloc] init] autorelease];
+        camera.outputPath = [directory stringByAppendingPathComponent:@"camera.mov"];
+        camera.isRecording = YES;
+        NativeAudioRecorder *microphone = [[[NativeAudioRecorder alloc] init] autorelease];
+        microphone.session = audioSession;
+        microphone.audioOutput = [[[AVCaptureAudioDataOutput alloc] init] autorelease];
+        microphone.outputPath = [directory stringByAppendingPathComponent:@"microphone.mov"];
+        auto sendVideo = [&](double time) {
+            WaitForInput(camera.writerInput);
+            double sourceTime = CMTimeGetSeconds(CMSyncConvertTime(T(time), CMClockGetHostTimeClock(), cameraClock));
+            CMSampleBufferRef sample = Video(sourceTime);
+            [camera captureOutput:camera.videoOutput didOutputSampleBuffer:sample fromConnection:nil];
+            CFRelease(sample);
+        };
+        auto sendAudio = [&](double time) {
+            WaitForInput(microphone.writerInput);
+            double sourceTime = CMTimeGetSeconds(CMSyncConvertTime(T(time), CMClockGetHostTimeClock(), audioClock));
+            CMSampleBufferRef sample = Audio(sourceTime);
+            [microphone captureOutput:microphone.audioOutput didOutputSampleBuffer:sample fromConnection:nil];
+            CFRelease(sample);
+        };
+        // Deliberately start the mic 400 ms before the camera. Both must retain
+        // their offsets to the phone, without waiting for the other device.
+        for (int i = 0; i < 40; i++) sendAudio(100.2 + i * 0.02);
+        for (int i = 0; i < 12; i++) sendVideo(100.6 + i / 30.0);
+        near(microphone.startTime, 100, @"mic writer uses USB origin");
+        near(camera.startTime, 100, @"camera writer uses USB origin");
+        MRSyncPauseAtHostTime(T(101));
+        phone.pauseRanges = [NSMutableArray array];
+        MRIOSBeginPauseRange(phone, T(101));
+        near(MRSyncPrimaryMediaTime(T(100.99)), 0.99, @"buffer queued before pause retains its timestamp");
+        check(!CMTIME_IS_NUMERIC(MRSyncPrimaryMediaTime(T(101.1))), @"paused samples are dropped");
+        sendAudio(102);
+        sendVideo(102);
+        MRSyncResumeAtHostTime(T(104));
+        MRIOSEndPauseRange(phone, T(104));
+        check(phone.pauseRanges.count == 1 &&
+            fabs(phone.pauseRanges[0][@"start"].doubleValue - 1) < 0.0001 &&
+            fabs(phone.pauseRanges[0][@"end"].doubleValue - 4) < 0.0001,
+            @"phone trims the exact same 1-to-4-second range as camera and microphone");
+        check(!CMTIME_IS_NUMERIC(MRSyncPrimaryMediaTime(T(102))), @"late delivery of a paused sample is still dropped");
+        near(MRSyncPrimaryMediaTime(T(104.5)), 1.5, @"resume removes exactly the phone's pause range");
+        for (int i = 0; i < 50; i++) sendAudio(104 + i * 0.02);
+        for (int i = 0; i < 30; i++) sendVideo(104 + i / 30.0);
+        MRSyncSetStopLimitSeconds(2);
+        check(MRFinishAssetWriterSafely(camera.writer, 5, 2), @"camera MOV finalizes");
+        check(MRFinishAssetWriterSafely(microphone.writer, 5, 2), @"microphone MOV finalizes");
+        for (NSString *kind in @[@"camera", @"microphone"]) {
+            NSURL *url = [NSURL fileURLWithPath:[directory stringByAppendingPathComponent:[kind stringByAppendingString:@".mov"]]];
+            AVURLAsset *asset = [AVURLAsset URLAssetWithURL:url options:nil];
+            BOOL isCamera = [kind isEqualToString:@"camera"];
+            AVAssetTrack *track = [asset tracksWithMediaType:isCamera ? AVMediaTypeVideo : AVMediaTypeAudio].firstObject;
+            check(track != nil, [kind stringByAppendingString:@" track exists"]);
+            if (!track) continue;
+            check(fabs(CMTimeGetSeconds(asset.duration) - 2) < 0.04, [kind stringByAppendingString:@" has the shared stop boundary"]);
+            NSError *error = nil;
+            AVAssetReader *reader = [AVAssetReader assetReaderWithAsset:asset error:&error];
+            AVAssetReaderOutput *output = isCamera
+                ? [AVAssetReaderTrackOutput assetReaderTrackOutputWithTrack:track outputSettings:nil]
+                : [AVAssetReaderAudioMixOutput assetReaderAudioMixOutputWithAudioTracks:@[track]
+                    audioSettings:@{AVFormatIDKey: @(kAudioFormatLinearPCM), AVLinearPCMBitDepthKey: @16,
+                        AVLinearPCMIsFloatKey: @NO, AVLinearPCMIsNonInterleaved: @NO}];
+            [reader addOutput:output];
+            [reader startReading];
+            CMTime previous = kCMTimeInvalid;
+            CMTime firstPTS = kCMTimeInvalid;
+            CMTime lastPTS = kCMTimeInvalid;
+            double firstSound = -1;
+            double secondVideoPTS = INFINITY;
+            NSUInteger count = 0;
+            while (CMSampleBufferRef sample = [output copyNextSampleBuffer]) {
+                CMTime pts = CMSampleBufferGetPresentationTimeStamp(sample);
+                if (CMSampleBufferGetTotalSampleSize(sample) == 0) { CFRelease(sample); continue; }
+                CMTime dts = CMSampleBufferGetDecodeTimeStamp(sample);
+                if (!CMTIME_IS_NUMERIC(dts)) dts = pts;
+                check(!CMTIME_IS_NUMERIC(previous) || CMTimeCompare(dts, previous) >= 0,
+                    [kind stringByAppendingString:@" has monotonic decode timestamps after pause"]);
+                previous = dts;
+                firstPTS = CMTIME_IS_NUMERIC(firstPTS) ? CMTimeMinimum(firstPTS, pts) : pts;
+                lastPTS = CMTIME_IS_NUMERIC(lastPTS) ? CMTimeMaximum(lastPTS, pts) : pts;
+                if (isCamera && CMTimeGetSeconds(pts) > 0.001) secondVideoPTS = MIN(secondVideoPTS, CMTimeGetSeconds(pts));
+                if (!isCamera && firstSound < 0) {
+                    CMBlockBufferRef block = CMSampleBufferGetDataBuffer(sample);
+                    size_t length = CMBlockBufferGetDataLength(block);
+                    std::vector<int16_t> pcm(length / sizeof(int16_t));
+                    CMBlockBufferCopyDataBytes(block, 0, length, pcm.data());
+                    for (size_t i = 0; i < pcm.size(); i++) {
+                        if (abs(pcm[i]) > 500) { firstSound = CMTimeGetSeconds(pts) + i / 48000.0; break; }
+                    }
+                }
+                count++;
+                CFRelease(sample);
+            }
+            check(fabs(CMTimeGetSeconds(firstPTS)) < 0.04,
+                [NSString stringWithFormat:@"%@ starts at zero even when a reader ignores empty edits (%.3f)", kind, CMTimeGetSeconds(firstPTS)]);
+            if (isCamera) check(fabs(secondVideoPTS - 0.6) < 0.04, @"camera holds its first frame until the actual capture time");
+            else check(fabs(firstSound - 0.2) < 0.04,
+                [NSString stringWithFormat:@"microphone leading silence preserves sound onset (%.3f)", firstSound]);
+            check(count > 1 && CMTimeGetSeconds(lastPTS) > 1.5,
+                [NSString stringWithFormat:@"%@ contains media on both sides of pause (count %lu, last PTS %.3f)", kind, count, CMTimeGetSeconds(lastPTS)]);
+        }
+        // Repeated pauses across a long session: no callback-time accumulation.
+        for (int i = 0; i < 100; i++) {
+            MRSyncPauseAtHostTime(T(110 + i * 10));
+            MRSyncResumeAtHostTime(T(113 + i * 10));
+        }
+        near(MRSyncPrimaryMediaTime(T(1110)), 707, @"100 pauses preserve the common long-recording timeline");
+        MRSyncConfigure(NO);
+        check(!MRSyncUsesPrimaryTimeline(), @"desktop recording does not inherit the iPhone timeline");
+        check(!MRSyncShouldHoldVideoFrame(T(200)), @"desktop camera barrier remains unchanged");
+        near(MRSyncAdjustForPauses(T(5)), 5, @"desktop pause duration resets between recordings");
+        cameraSession.probeClock = nil;
+        audioSession.probeClock = nil;
+        CFRelease(cameraClock);
+        CFRelease(audioClock);
+        Napi::Object result = Napi::Object::New(info.Env());
+        result.Set("checks", Napi::Number::New(info.Env(), checks));
+        result.Set("failures", Napi::String::New(info.Env(), [[failures componentsJoinedByString:@"\n"] UTF8String]));
+        return result;
+    }
+}
+
+static Napi::Object InitProbe(Napi::Env env, Napi::Object exports) {
+    exports.Set("run", Napi::Function::New(env, Run));
+    return exports;
+}
+NODE_API_MODULE(ios_sync_probe, InitProbe)

package/tests/ios-sync.test.cjs

@@ -0,0 +1,30 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { execFileSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+test('iPhone, camera and microphone preserve one media timeline through delayed startup and pauses', {
+  skip: process.platform !== 'darwin', timeout: 120000,
+}, (t) => {
+  const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'recorder-ios-sync-'));
+  t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
+  const headers = [
+    process.env.npm_config_nodedir && path.join(process.env.npm_config_nodedir, 'include/node'),
+    path.join(os.homedir(), 'Library/Caches/node-gyp', process.versions.node, 'include/node'),
+    path.resolve(path.dirname(process.execPath), '../include/node'),
+  ].filter(Boolean).find((p) => fs.existsSync(path.join(p, 'node_api.h')));
+  assert.ok(headers, 'Node headers required; run npm run rebuild first');
+  const binary = path.join(directory, 'ios-sync-probe.node');
+  execFileSync('xcrun', ['clang++', '-std=c++17', '-bundle', '-undefined', 'dynamic_lookup',
+    '-DNAPI_DISABLE_CPP_EXCEPTIONS', '-Wno-deprecated-declarations',
+    '-I', headers, '-I', path.dirname(require.resolve('node-addon-api')),
+    path.join(__dirname, 'ios-sync-probe.mm'), '-o', binary,
+    ...['Foundation', 'AVFoundation', 'CoreMedia', 'CoreVideo', 'CoreMediaIO', 'IOKit', 'CoreAudio']
+      .flatMap((framework) => ['-framework', framework]),
+  ], { timeout: 60000, stdio: 'pipe' });
+  const result = require(binary).run(directory);
+  t.diagnostic(`${result.checks} native timing and MOV checks`);
+  assert.equal(result.failures, '');
+});