@vidtreo/recorder 1.7.10 → 1.7.11

package/dist/index.d.ts

@@ -194,7 +194,7 @@ export type MediaStats = {
     videoDuration: number;
 };
 export declare function inspectMedia(blob: Blob): Promise<MediaStats>;
-export declare function transcodePreservingCadence(blob: Blob): Promise<Blob>;
+export declare function transcodePreservingCadence(blob: Blob, expectedDurationSeconds: number): Promise<Blob>;
 
 export {};
 
@@ -1560,6 +1560,7 @@ import { type VisibilityInterval } from "../utils/tab-visibility-tracker";
 export type StopRecordingResult = {
     blob: Blob;
     captureFrameRate?: number;
+    expectedDurationSeconds?: number;
     tabVisibilityIntervals: VisibilityInterval[];
     recordingStats?: StreamRecordingStats;
     encoderAcceleration?: VideoHardwareAcceleration;
@@ -1591,6 +1592,11 @@ export declare class StreamRecordingState {
     private mediaRecorderStopReject;
     private mediaRecorderError;
     private safeCaptureFrameRate;
+    private safeCaptureStartTime;
+    private safeCaptureExpectedDurationSeconds;
+    private mediaRecorderRequestedMimeType;
+    private mediaRecorderGeneration;
+    private isSafeCaptureSettled;
     private mediaRecorderErrorTimeoutId;
     private readonly streamManager;
     private readonly dependencies;
@@ -1614,20 +1620,25 @@ export declare class StreamRecordingState {
     private clearRecordingTimer;
     private clearBufferSizeInterval;
     private resetRecordingState;
+    private resolveActiveRecordingDurationSeconds;
     private startSafeCaptureRecording;
+    private isActiveSafeCaptureGeneration;
+    private createSafeCaptureRecorder;
     private resolveEffectiveSafeCaptureFrameRate;
     private applySafeCaptureTrackConstraints;
     private resolveSafeCaptureVideoConstraints;
     private stopSafeCaptureRecording;
+    private cleanupSafeCaptureRecording;
     private resolveSafeCaptureMimeType;
-    private resolvePreferredSafeCaptureMimeType;
-    private shouldPreferWebmSafeCapture;
+    private resolveRecordedMimeType;
+    private resolveSafeCaptureMimeTypeCandidates;
     private scheduleMediaRecorderErrorFinalizeTimeout;
     private clearMediaRecorderErrorTimeout;
     private createMediaRecorderError;
     private createEmptyMediaRecorderError;
     private updateMediaRecorderErrorDiagnostics;
     private buildMediaRecorderDiagnostics;
+    private assignSafeCaptureErrorDiagnostics;
     private getMediaRecorderChunkSize;
     private resetPauseState;
     private resolveTabVisibilityOverlayText;
@@ -3175,12 +3186,20 @@ export type VideoPacketSummary = {
     packetCount: number;
 };
 export type DeferredVideoStatsValidation = {
+    expectedDurationSeconds: number;
     output: VideoPacketSummary | null;
     source: VideoPacketSummary | null;
+    stage?: "source" | "output";
     targetFrameRate: number;
 };
+export type DeferredTranscodeContext = {
+    expectedDurationSeconds: number;
+};
+export type DeferredTranscodeResult = TranscodeResult & {
+    diagnostics: Record<string, string | number | boolean>;
+};
 export declare function validateDeferredVideoStats(validation: DeferredVideoStatsValidation): void;
-export declare function transcodeDeferredVideo(input: Blob, config: TranscodeConfig, onProgress?: (progress: number) => void): Promise<TranscodeResult>;
+export declare function transcodeDeferredVideo(input: Blob, config: TranscodeConfig, onProgress: ((progress: number) => void) | undefined, context: DeferredTranscodeContext): Promise<DeferredTranscodeResult>;
 
 export type VidtreoRecorderConfig = {
     apiKey: string;

package/dist/index.js

@@ -5287,6 +5287,7 @@ var ANDROID_SAFE_CAPTURE_CONSTRAINTS = {
 };
 var LOW_RESOURCE_SAFE_CAPTURE_FRAME_RATE = 20;
 var ANDROID_SAFE_CAPTURE_FRAME_RATE = 24;
+var SAFE_CAPTURE_TIMESLICE_MS = 1000;
 var MEDIA_RECORDER_ERROR_FINALIZE_TIMEOUT_MS = 5000;
 var ANDROID_POST_RECORDING_TRANSCODE_REASON = "android-post-recording-transcode";
 var MEDIA_RECORDER_ERROR_CODE = "recording.mediarecorder-error";
@@ -5324,6 +5325,11 @@ class StreamRecordingState {
   mediaRecorderStopReject = null;
   mediaRecorderError = null;
   safeCaptureFrameRate = null;
+  safeCaptureStartTime = null;
+  safeCaptureExpectedDurationSeconds = null;
+  mediaRecorderRequestedMimeType = null;
+  mediaRecorderGeneration = 0;
+  isSafeCaptureSettled = false;
   mediaRecorderErrorTimeoutId = null;
   streamManager;
   dependencies;
@@ -5466,7 +5472,8 @@ class StreamRecordingState {
     this.startRecordingTimer();
   }
   async stopRecording() {
-    const recordingElapsedSeconds = (this.dependencies.getCurrentTimestamp() - this.recordingStartTime - this.totalPausedTime) / MILLISECONDS_PER_SECOND2;
+    const stopTimestamp = this.dependencies.getCurrentTimestamp();
+    const recordingElapsedSeconds = this.resolveActiveRecordingDurationSeconds(stopTimestamp);
     logger.debug("[StreamRecordingState] stopRecording called", {
       hasStreamProcessor: !!this.streamProcessor,
       isRecording: this.isRecording(),
@@ -5497,11 +5504,12 @@ class StreamRecordingState {
     }
     let result;
     if (this.activeRouteDecision.route === "safe-capture-post-recording-transcode") {
-      const safeCaptureResult = await this.stopSafeCaptureRecording();
+      const safeCaptureResult = await this.stopSafeCaptureRecording(recordingElapsedSeconds);
       logger.debug("[StreamRecordingState] Finalizing MediaRecorder capture");
       result = {
         blob: safeCaptureResult.blob,
         captureFrameRate: safeCaptureResult.captureFrameRate,
+        expectedDurationSeconds: safeCaptureResult.expectedDurationSeconds,
         mediaRecorderDiagnostics: safeCaptureResult.diagnostics
       };
     } else {
@@ -5520,6 +5528,7 @@ class StreamRecordingState {
     return {
       blob: result.blob,
       captureFrameRate: result.captureFrameRate,
+      expectedDurationSeconds: result.expectedDurationSeconds,
       tabVisibilityIntervals,
       recordingStats: result.recordingStats,
       encoderAcceleration: result.encoderAcceleration,
@@ -5544,7 +5553,7 @@ class StreamRecordingState {
   resumeRecording() {
     if (this.pauseStartTime !== null) {
       const pausedDuration = this.dependencies.getCurrentTimestamp() - this.pauseStartTime;
-      this.totalPausedTime += pausedDuration;
+      this.totalPausedTime += Math.max(0, pausedDuration);
       this.pauseStartTime = null;
     }
     if (this.tabVisibilityTracker) {
@@ -5639,6 +5648,18 @@ class StreamRecordingState {
     this.totalPausedTime = 0;
     this.pauseStartTime = null;
   }
+  resolveActiveRecordingDurationSeconds(timestamp) {
+    let startTime = this.recordingStartTime;
+    if (this.safeCaptureStartTime !== null) {
+      startTime = this.safeCaptureStartTime;
+    }
+    let pausedTime = this.totalPausedTime;
+    if (this.pauseStartTime !== null) {
+      pausedTime += Math.max(0, timestamp - this.pauseStartTime);
+    }
+    const activeDuration = Math.max(0, timestamp - startTime - pausedTime);
+    return activeDuration / MILLISECONDS_PER_SECOND2;
+  }
   async startSafeCaptureRecording(mediaStream, config) {
     if (typeof MediaRecorder === "undefined") {
       throw createUnsupportedRouteError({
@@ -5654,9 +5675,13 @@ class StreamRecordingState {
     this.safeCaptureFrameRate = this.resolveEffectiveSafeCaptureFrameRate(mediaStream, config);
     this.mediaRecorderChunks = [];
     this.mediaRecorderError = null;
-    const preferredMimeType = this.resolvePreferredSafeCaptureMimeType(config);
-    const recorderOptions = preferredMimeType === undefined ? undefined : { mimeType: preferredMimeType };
-    const recorder = new MediaRecorder(mediaStream, recorderOptions);
+    this.safeCaptureExpectedDurationSeconds = null;
+    this.isSafeCaptureSettled = false;
+    const generation = this.mediaRecorderGeneration + 1;
+    this.mediaRecorderGeneration = generation;
+    const selection = await this.createSafeCaptureRecorder(mediaStream);
+    const recorder = selection.recorder;
+    this.mediaRecorderRequestedMimeType = selection.requestedMimeType === undefined ? null : selection.requestedMimeType;
     this.mediaRecorder = recorder;
     this.mediaRecorderStopPromise = new Promise((resolve, reject) => {
       this.mediaRecorderStopResolve = resolve;
@@ -5666,40 +5691,76 @@ class StreamRecordingState {
       return;
     });
     recorder.ondataavailable = (event) => {
+      if (!this.isActiveSafeCaptureGeneration(generation)) {
+        return;
+      }
       if (event.data.size > 0) {
         this.mediaRecorderChunks.push(event.data);
       }
     };
     recorder.onstop = () => {
+      if (!this.isActiveSafeCaptureGeneration(generation)) {
+        return;
+      }
+      this.isSafeCaptureSettled = true;
       this.clearMediaRecorderErrorTimeout();
       if (this.mediaRecorderError !== null) {
         this.updateMediaRecorderErrorDiagnostics(recorder);
         this.mediaRecorderStopReject?.(this.mediaRecorderError);
         return;
       }
-      const mimeType = recorder.mimeType || this.resolveSafeCaptureMimeType();
+      const mimeType = this.resolveRecordedMimeType(recorder);
       const blob = new Blob(this.mediaRecorderChunks, { type: mimeType });
       const diagnostics = this.buildMediaRecorderDiagnostics(recorder);
       const captureFrameRate = this.safeCaptureFrameRate;
+      let expectedDurationSeconds = this.safeCaptureExpectedDurationSeconds;
+      if (expectedDurationSeconds === null) {
+        expectedDurationSeconds = this.resolveActiveRecordingDurationSeconds(this.dependencies.getCurrentTimestamp());
+      }
       if (captureFrameRate === null) {
         this.mediaRecorderStopReject?.(new Error("Safe capture frame rate is unavailable"));
         return;
       }
       diagnostics.mediaRecorderCaptureFrameRate = captureFrameRate;
+      diagnostics.mediaRecorderExpectedDurationSeconds = expectedDurationSeconds;
       if (blob.size > 0) {
         this.mediaRecorderStopResolve?.({
           blob,
           captureFrameRate,
-          diagnostics
+          diagnostics,
+          expectedDurationSeconds
         });
         return;
       }
       this.mediaRecorderStopReject?.(this.createEmptyMediaRecorderError(recorder));
     };
     recorder.onerror = (event) => {
+      if (!this.isActiveSafeCaptureGeneration(generation)) {
+        return;
+      }
       this.mediaRecorderError = this.createMediaRecorderError(event, recorder);
     };
-    recorder.start();
+    this.safeCaptureStartTime = this.dependencies.getCurrentTimestamp();
+    recorder.start(SAFE_CAPTURE_TIMESLICE_MS);
+  }
+  isActiveSafeCaptureGeneration(generation) {
+    return generation === this.mediaRecorderGeneration && !this.isSafeCaptureSettled;
+  }
+  async createSafeCaptureRecorder(mediaStream, candidateIndex = 0) {
+    const candidateMimeTypes = this.resolveSafeCaptureMimeTypeCandidates();
+    const requestedMimeType = candidateMimeTypes[candidateIndex];
+    if (requestedMimeType === undefined) {
+      return {
+        recorder: new MediaRecorder(mediaStream)
+      };
+    }
+    const recorder = await Promise.resolve().then(() => new MediaRecorder(mediaStream, {
+      mimeType: requestedMimeType
+    })).catch(() => null);
+    if (recorder !== null) {
+      return { recorder, requestedMimeType };
+    }
+    return await this.createSafeCaptureRecorder(mediaStream, candidateIndex + 1);
   }
   resolveEffectiveSafeCaptureFrameRate(mediaStream, config) {
     const videoTrack = mediaStream.getVideoTracks()[0];
@@ -5728,6 +5789,9 @@ class StreamRecordingState {
     }
     const videoTracks = mediaStream.getVideoTracks();
     await Promise.all(videoTracks.map(async (track) => {
+      if (typeof track.applyConstraints !== "function") {
+        return;
+      }
       try {
         await track.applyConstraints(constraints);
       } catch (error) {
@@ -5745,36 +5809,62 @@ class StreamRecordingState {
     }
     return null;
   }
-  async stopSafeCaptureRecording() {
+  async stopSafeCaptureRecording(expectedDurationSeconds) {
     const recorder = this.mediaRecorder;
     const stopPromise = this.mediaRecorderStopPromise;
     if (!(recorder && stopPromise)) {
       throw new Error("Safe capture recorder was not started");
     }
-    if (recorder.state !== "inactive") {
-      recorder.stop();
-    }
-    this.scheduleMediaRecorderErrorFinalizeTimeout(recorder);
-    try {
-      return await stopPromise;
-    } finally {
-      this.mediaRecorder = null;
-      this.mediaRecorderChunks = [];
-      this.mediaRecorderStopPromise = null;
-      this.mediaRecorderStopResolve = null;
-      this.mediaRecorderStopReject = null;
-      this.mediaRecorderError = null;
-      this.safeCaptureFrameRate = null;
-      this.clearMediaRecorderErrorTimeout();
-      this.activeRouteDecision = DEFAULT_ROUTE_DECISION;
-    }
+    this.safeCaptureExpectedDurationSeconds = expectedDurationSeconds;
+    return await Promise.resolve().then(() => {
+      if (recorder.state !== "inactive") {
+        recorder.stop();
+      }
+      this.scheduleMediaRecorderErrorFinalizeTimeout(recorder);
+      return stopPromise;
+    }).then((result) => {
+      result.expectedDurationSeconds = expectedDurationSeconds;
+      result.diagnostics.mediaRecorderExpectedDurationSeconds = expectedDurationSeconds;
+      return result;
+    }).finally(() => {
+      this.cleanupSafeCaptureRecording();
+    });
+  }
+  cleanupSafeCaptureRecording() {
+    this.mediaRecorder = null;
+    this.mediaRecorderChunks = [];
+    this.mediaRecorderStopPromise = null;
+    this.mediaRecorderStopResolve = null;
+    this.mediaRecorderStopReject = null;
+    this.mediaRecorderError = null;
+    this.safeCaptureFrameRate = null;
+    this.safeCaptureStartTime = null;
+    this.safeCaptureExpectedDurationSeconds = null;
+    this.mediaRecorderRequestedMimeType = null;
+    this.mediaRecorderGeneration += 1;
+    this.isSafeCaptureSettled = false;
+    this.clearMediaRecorderErrorTimeout();
+    this.activeRouteDecision = DEFAULT_ROUTE_DECISION;
   }
   resolveSafeCaptureMimeType() {
     const mediaStream = this.streamManager.getStream();
     const hasVideo = (mediaStream?.getVideoTracks().length ?? 0) > 0;
     return hasVideo ? "video/webm" : "audio/webm";
   }
-  resolvePreferredSafeCaptureMimeType(config) {
+  resolveRecordedMimeType(recorder) {
+    if (recorder.mimeType.trim().length > 0) {
+      return recorder.mimeType;
+    }
+    const chunkWithMimeType = this.mediaRecorderChunks.find((chunk) => chunk.type.trim().length > 0);
+    if (chunkWithMimeType !== undefined) {
+      return chunkWithMimeType.type;
+    }
+    if (this.mediaRecorderRequestedMimeType !== null) {
+      return this.mediaRecorderRequestedMimeType;
+    }
+    return this.resolveSafeCaptureMimeType();
+  }
+  resolveSafeCaptureMimeTypeCandidates() {
     const canUseMimeType = (mimeType) => {
       if (typeof MediaRecorder.isTypeSupported !== "function") {
         return false;
@@ -5791,22 +5881,7 @@ class StreamRecordingState {
       "video/mp4;codecs=avc1.42001f,mp4a.40.2",
       "video/mp4"
     ];
-    let candidateMimeTypes = mp4CandidateMimeTypes;
-    if (this.shouldPreferWebmSafeCapture(config)) {
-      candidateMimeTypes = [
-        ...webmCandidateMimeTypes,
-        ...mp4CandidateMimeTypes
-      ];
-    } else if (config.format !== "mp4") {
-      candidateMimeTypes = webmCandidateMimeTypes;
-    }
-    return candidateMimeTypes.find(canUseMimeType);
-  }
-  shouldPreferWebmSafeCapture(config) {
-    if (config.format !== "mp4") {
-      return false;
-    }
-    return this.activeRouteDecision.reasonCodes.includes(ANDROID_POST_RECORDING_TRANSCODE_REASON);
+    return [...webmCandidateMimeTypes, ...mp4CandidateMimeTypes].filter(canUseMimeType);
   }
   scheduleMediaRecorderErrorFinalizeTimeout(recorder) {
     if (this.mediaRecorderErrorTimeoutId !== null) {
@@ -5833,9 +5908,10 @@ class StreamRecordingState {
     const error = new Error("Browser recording failed before upload could start");
     error.name = "MediaRecorderRecordingError";
     error.code = MEDIA_RECORDER_ERROR_CODE;
-    error.mediaRecorderMimeType = recorder.mimeType;
+    error.mediaRecorderMimeType = this.resolveRecordedMimeType(recorder);
     error.mediaRecorderChunkCount = this.mediaRecorderChunks.length;
     error.mediaRecorderChunkSize = this.getMediaRecorderChunkSize();
+    this.assignSafeCaptureErrorDiagnostics(error);
     if (browserError?.name) {
       error.mediaRecorderErrorName = browserError.name;
     }
@@ -5848,9 +5924,10 @@ class StreamRecordingState {
     const error = new Error("Browser recording produced no data before upload could start");
     error.name = "MediaRecorderEmptyDataError";
     error.code = MEDIA_RECORDER_EMPTY_ERROR_CODE;
-    error.mediaRecorderMimeType = recorder.mimeType;
+    error.mediaRecorderMimeType = this.resolveRecordedMimeType(recorder);
     error.mediaRecorderChunkCount = this.mediaRecorderChunks.length;
     error.mediaRecorderChunkSize = this.getMediaRecorderChunkSize();
+    this.assignSafeCaptureErrorDiagnostics(error);
     if (this.mediaRecorderError?.mediaRecorderErrorName) {
       error.mediaRecorderErrorName = this.mediaRecorderError.mediaRecorderErrorName;
     }
@@ -5863,17 +5940,21 @@ class StreamRecordingState {
     if (this.mediaRecorderError === null) {
       return;
     }
-    this.mediaRecorderError.mediaRecorderMimeType = recorder.mimeType;
+    this.mediaRecorderError.mediaRecorderMimeType = this.resolveRecordedMimeType(recorder);
     this.mediaRecorderError.mediaRecorderChunkCount = this.mediaRecorderChunks.length;
     this.mediaRecorderError.mediaRecorderChunkSize = this.getMediaRecorderChunkSize();
+    this.assignSafeCaptureErrorDiagnostics(this.mediaRecorderError);
   }
   buildMediaRecorderDiagnostics(recorder) {
     const diagnostics = {
-      mediaRecorderMimeType: recorder.mimeType,
+      mediaRecorderMimeType: this.resolveRecordedMimeType(recorder),
       mediaRecorderChunkCount: this.mediaRecorderChunks.length,
       mediaRecorderChunkSize: this.getMediaRecorderChunkSize(),
       mediaRecorderHadError: this.mediaRecorderError !== null
     };
+    if (this.mediaRecorderRequestedMimeType !== null) {
+      diagnostics.mediaRecorderRequestedMimeType = this.mediaRecorderRequestedMimeType;
+    }
     if (this.mediaRecorderError?.mediaRecorderErrorName) {
       diagnostics.mediaRecorderErrorName = this.mediaRecorderError.mediaRecorderErrorName;
     }
@@ -5882,6 +5963,15 @@ class StreamRecordingState {
     }
     return diagnostics;
   }
+  assignSafeCaptureErrorDiagnostics(error) {
+    error.deferredIntegrityStage = "capture";
+    if (this.mediaRecorderRequestedMimeType !== null) {
+      error.mediaRecorderRequestedMimeType = this.mediaRecorderRequestedMimeType;
+    }
+    if (this.safeCaptureExpectedDurationSeconds !== null) {
+      error.mediaRecorderExpectedDurationSeconds = this.safeCaptureExpectedDurationSeconds;
+    }
+  }
   getMediaRecorderChunkSize() {
     return this.mediaRecorderChunks.reduce((total, chunk) => total + chunk.size, 0);
   }
@@ -5965,6 +6055,12 @@ class StreamRecordingState {
     this.mediaRecorderStopResolve = null;
     this.mediaRecorderStopReject = null;
     this.mediaRecorderError = null;
+    this.safeCaptureFrameRate = null;
+    this.safeCaptureStartTime = null;
+    this.safeCaptureExpectedDurationSeconds = null;
+    this.mediaRecorderRequestedMimeType = null;
+    this.mediaRecorderGeneration += 1;
+    this.isSafeCaptureSettled = false;
     this.clearMediaRecorderErrorTimeout();
     this.activeRouteDecision = DEFAULT_ROUTE_DECISION;
     if (this.streamProcessor) {
@@ -6112,6 +6208,7 @@ var RECORDING_CODEC_UNSUPPORTED_CODES = new Set([
   "recording.video-codec-unavailable"
 ]);
 var RECORDING_SERVER_TRANSCODE_FALLBACK_CODES = new Set([
+  "recording.deferred-transcode-integrity",
   "recording.post-recording-transcode-fallback",
   "transcode.post-recording-fallback",
   "route.post-recording-transcode-fallback"
@@ -6354,7 +6451,7 @@ function resolveDeviceError(input) {
 // package.json
 var package_default = {
   name: "@vidtreo/recorder",
-  version: "1.7.10",
+  version: "1.7.11",
   type: "module",
   description: "Vidtreo SDK for browser-based video recording and transcoding. Features include camera/screen recording, real-time MP4 transcoding, audio level analysis, mute/pause controls, source switching, device selection, and automatic backend uploads. Similar to Ziggeo and Addpipe, Vidtreo provides enterprise-grade video processing capabilities for web applications.",
   main: "./dist/index.js",
@@ -6439,12 +6536,23 @@ var MAX_RETRY_ATTEMPTS = 3;
 var MAX_PENDING_EVENTS = 100;
 var BRACKET_ERROR_CODE_PATTERN = /\[([a-z]+(?:[.-][a-z0-9]+)+)\]/i;
 var INLINE_ERROR_CODE_PATTERN = /\b([a-z]+(?:[.-][a-z0-9]+)+)\b/i;
-var MEDIA_RECORDER_ERROR_PROPERTY_KEYS = [
+var RECORDING_INTEGRITY_ERROR_PROPERTY_KEYS = [
   "mediaRecorderErrorName",
   "mediaRecorderErrorMessage",
   "mediaRecorderMimeType",
   "mediaRecorderChunkCount",
-  "mediaRecorderChunkSize"
+  "mediaRecorderChunkSize",
+  "mediaRecorderExpectedDurationSeconds",
+  "mediaRecorderRequestedMimeType",
+  "deferredIntegrityStage",
+  "deferredSourceDurationSeconds",
+  "deferredSourcePacketCount",
+  "deferredSourcePacketRate",
+  "deferredSourceMaximumPacketGap",
+  "deferredOutputDurationSeconds",
+  "deferredOutputPacketCount",
+  "deferredOutputPacketRate",
+  "deferredOutputMaximumPacketGap"
 ];
 function resolveInstallationId(dependencies) {
   const storageProvider = dependencies.storageProvider;
@@ -6800,7 +6908,7 @@ class TelemetryClient {
     }
     const candidate = error;
     let properties = {};
-    for (const key of MEDIA_RECORDER_ERROR_PROPERTY_KEYS) {
+    for (const key of RECORDING_INTEGRITY_ERROR_PROPERTY_KEYS) {
       const value = candidate[key];
       if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
         properties = { ...properties, [key]: value };
@@ -22797,64 +22905,126 @@ var MAXIMUM_DURATION_DIFFERENCE_RATIO = 0.05;
 var MINIMUM_DURATION_TOLERANCE_SECONDS = 0.25;
 var MAXIMUM_FRAME_GAP_MULTIPLIER = 5;
 var MINIMUM_FRAME_GAP_TOLERANCE_SECONDS = 0.25;
+var LONG_RECORDING_THRESHOLD_SECONDS = 3;
+var LONG_RECORDING_DURATION_TOLERANCE_SECONDS = 1.5;
+var LONG_RECORDING_DURATION_TOLERANCE_RATIO = 0.15;
+var SHORT_RECORDING_DURATION_TOLERANCE_SECONDS = 0.75;
+var SHORT_RECORDING_DURATION_TOLERANCE_RATIO = 0.5;
 var INTEGRITY_ERROR_CODE = "recording.deferred-transcode-integrity";
-function createIntegrityError(message) {
+function createIntegrityError(message, diagnostics = {}) {
   const error = new Error(message);
   error.name = "DeferredTranscodeIntegrityError";
   error.code = INTEGRITY_ERROR_CODE;
   error.isRecoverable = true;
+  Object.assign(error, diagnostics);
   return error;
 }
-function validatePacketSummary(summary, label) {
+function validatePacketSummary(summary, label, diagnostics) {
   if (!Number.isFinite(summary.averagePacketRate)) {
-    throw createIntegrityError(`${label} video packet rate is invalid`);
+    throw createIntegrityError(`${label} video packet rate is invalid`, diagnostics);
   }
   if (!Number.isFinite(summary.duration)) {
-    throw createIntegrityError(`${label} video duration is invalid`);
+    throw createIntegrityError(`${label} video duration is invalid`, diagnostics);
   }
   if (!Number.isFinite(summary.maximumPacketGap)) {
-    throw createIntegrityError(`${label} video maximum packet gap is invalid`);
+    throw createIntegrityError(`${label} video maximum packet gap is invalid`, diagnostics);
   }
   if (summary.averagePacketRate <= 0 || summary.duration <= 0) {
-    throw createIntegrityError(`${label} video packet statistics are empty`);
+    throw createIntegrityError(`${label} video packet statistics are empty`, diagnostics);
   }
   if (summary.maximumPacketGap < 0) {
-    throw createIntegrityError(`${label} video maximum packet gap is invalid`);
+    throw createIntegrityError(`${label} video maximum packet gap is invalid`, diagnostics);
   }
   if (!Number.isInteger(summary.packetCount) || summary.packetCount <= 0) {
-    throw createIntegrityError(`${label} video packet count is invalid`);
+    throw createIntegrityError(`${label} video packet count is invalid`, diagnostics);
+  }
+}
+function validateMaximumFrameGap(summary, label, targetFrameRate, diagnostics) {
+  const maximumPacketGap = Math.max(MINIMUM_FRAME_GAP_TOLERANCE_SECONDS, MAXIMUM_FRAME_GAP_MULTIPLIER / targetFrameRate);
+  if (summary.maximumPacketGap > maximumPacketGap) {
+    throw createIntegrityError(`${label} video contains a material frame gap`, diagnostics);
   }
 }
-function validateFrameCadence(summary, label, targetFrameRate) {
+function validateOutputFrameDensity(summary, targetFrameRate, diagnostics) {
   const minimumPacketRate = targetFrameRate * MINIMUM_FRAME_DENSITY_RATIO;
   if (summary.averagePacketRate < minimumPacketRate) {
-    throw createIntegrityError(`${label} video frame density is below the capture target`);
+    throw createIntegrityError("Output video frame density is below the capture target", diagnostics);
   }
-  const maximumPacketGap = Math.max(MINIMUM_FRAME_GAP_TOLERANCE_SECONDS, MAXIMUM_FRAME_GAP_MULTIPLIER / targetFrameRate);
-  if (summary.maximumPacketGap > maximumPacketGap) {
-    throw createIntegrityError(`${label} video contains a material frame gap`);
+}
+function buildIntegrityDiagnostics(validation) {
+  let stage = "output";
+  if (validation.stage !== undefined) {
+    stage = validation.stage;
+  }
+  const diagnostics = {
+    deferredIntegrityStage: stage
+  };
+  assignFiniteDiagnostic(diagnostics, "mediaRecorderExpectedDurationSeconds", validation.expectedDurationSeconds);
+  if (validation.source !== null) {
+    assignFiniteDiagnostic(diagnostics, "deferredSourceDurationSeconds", validation.source.duration);
+    assignFiniteDiagnostic(diagnostics, "deferredSourcePacketCount", validation.source.packetCount);
+    assignFiniteDiagnostic(diagnostics, "deferredSourcePacketRate", validation.source.averagePacketRate);
+    assignFiniteDiagnostic(diagnostics, "deferredSourceMaximumPacketGap", validation.source.maximumPacketGap);
+  }
+  if (validation.output !== null) {
+    assignFiniteDiagnostic(diagnostics, "deferredOutputDurationSeconds", validation.output.duration);
+    assignFiniteDiagnostic(diagnostics, "deferredOutputPacketCount", validation.output.packetCount);
+    assignFiniteDiagnostic(diagnostics, "deferredOutputPacketRate", validation.output.averagePacketRate);
+    assignFiniteDiagnostic(diagnostics, "deferredOutputMaximumPacketGap", validation.output.maximumPacketGap);
+  }
+  return diagnostics;
+}
+function assignFiniteDiagnostic(diagnostics, key, value) {
+  if (Number.isFinite(value)) {
+    diagnostics[key] = value;
+  }
+}
+function resolveLifecycleDurationTolerance(expectedDurationSeconds) {
+  if (expectedDurationSeconds >= LONG_RECORDING_THRESHOLD_SECONDS) {
+    return Math.max(LONG_RECORDING_DURATION_TOLERANCE_SECONDS, expectedDurationSeconds * LONG_RECORDING_DURATION_TOLERANCE_RATIO);
+  }
+  return Math.max(SHORT_RECORDING_DURATION_TOLERANCE_SECONDS, expectedDurationSeconds * SHORT_RECORDING_DURATION_TOLERANCE_RATIO);
+}
+function validateLifecycleCoverage(summary, label, expectedDurationSeconds, diagnostics) {
+  const durationDifference = Math.abs(summary.duration - expectedDurationSeconds);
+  const tolerance = resolveLifecycleDurationTolerance(expectedDurationSeconds);
+  if (durationDifference > tolerance) {
+    throw createIntegrityError(`${label} video duration does not cover the active recording`, diagnostics);
   }
 }
 function validateDeferredVideoStats(validation) {
+  const diagnostics = buildIntegrityDiagnostics(validation);
+  if (!Number.isFinite(validation.expectedDurationSeconds) || validation.expectedDurationSeconds < 0) {
+    throw createIntegrityError("Deferred transcode requires a valid active recording duration", diagnostics);
+  }
   if (!Number.isFinite(validation.targetFrameRate) || validation.targetFrameRate <= 0) {
-    throw createIntegrityError("Deferred transcode requires a valid capture frame rate");
+    throw createIntegrityError("Deferred transcode requires a valid capture frame rate", diagnostics);
+  }
+  if (validation.source === null) {
+    throw createIntegrityError("Deferred transcode source has no primary video track", diagnostics);
   }
-  if (!(validation.source && validation.output)) {
-    throw createIntegrityError("Deferred transcode source or output has no primary video track");
+  validatePacketSummary(validation.source, "Source", diagnostics);
+  validateMaximumFrameGap(validation.source, "Source", validation.targetFrameRate, diagnostics);
+  validateLifecycleCoverage(validation.source, "Source", validation.expectedDurationSeconds, diagnostics);
+  if (validation.stage === "source") {
+    return;
+  }
+  if (validation.output === null) {
+    throw createIntegrityError("Deferred transcode output has no primary video track", diagnostics);
   }
-  validatePacketSummary(validation.source, "Source");
-  validatePacketSummary(validation.output, "Output");
-  validateFrameCadence(validation.source, "Source", validation.targetFrameRate);
-  validateFrameCadence(validation.output, "Output", validation.targetFrameRate);
+  validatePacketSummary(validation.output, "Output", diagnostics);
+  validateOutputFrameDensity(validation.output, validation.targetFrameRate, diagnostics);
+  validateMaximumFrameGap(validation.output, "Output", validation.targetFrameRate, diagnostics);
+  validateLifecycleCoverage(validation.output, "Output", validation.expectedDurationSeconds, diagnostics);
   const durationDifference = Math.abs(validation.source.duration - validation.output.duration);
   const durationTolerance = Math.max(MINIMUM_DURATION_TOLERANCE_SECONDS, validation.source.duration * MAXIMUM_DURATION_DIFFERENCE_RATIO);
   if (durationDifference > durationTolerance) {
-    throw createIntegrityError("Deferred transcode output duration differs materially from source");
+    throw createIntegrityError("Deferred transcode output duration differs materially from source", diagnostics);
   }
   const minimumPacketRate = validation.targetFrameRate * MINIMUM_FRAME_DENSITY_RATIO;
   const minimumPacketCount = Math.floor(validation.source.duration * minimumPacketRate);
   if (validation.output.averagePacketRate < minimumPacketRate || validation.output.packetCount < minimumPacketCount) {
-    throw createIntegrityError("Deferred transcode output lost material video frame density");
+    throw createIntegrityError("Deferred transcode output lost material video frame density", diagnostics);
   }
 }
 async function inspectVideoPackets(blob) {
@@ -22897,27 +23067,72 @@ async function inspectVideoPackets(blob) {
     input.dispose();
   }
 }
-async function inspectDeferredVideo(blob, label) {
+async function inspectDeferredVideo(blob, label, diagnostics) {
   return await inspectVideoPackets(blob).catch((error) => {
     const message = extractErrorMessage(error);
-    throw createIntegrityError(`Could not inspect ${label} deferred video: ${message}`);
+    throw createIntegrityError(`Could not inspect ${label} deferred video: ${message}`, diagnostics);
   });
 }
-async function transcodeDeferredVideo(input, config, onProgress) {
+async function transcodeDeferredVideo(input, config, onProgress, context) {
   const targetFrameRate = config.fps;
   if (typeof targetFrameRate !== "number" || !Number.isFinite(targetFrameRate) || targetFrameRate <= 0) {
-    throw createIntegrityError("Deferred transcode requires a valid capture frame rate");
+    throw createIntegrityError("Deferred transcode requires a valid capture frame rate", {
+      deferredIntegrityStage: "source",
+      mediaRecorderExpectedDurationSeconds: context.expectedDurationSeconds
+    });
   }
-  const source = await inspectDeferredVideo(input, "source");
+  const source = await inspectDeferredVideo(input, "source", {
+    deferredIntegrityStage: "source",
+    mediaRecorderExpectedDurationSeconds: context.expectedDurationSeconds
+  });
   validateDeferredVideoStats({
-    output: source,
+    expectedDurationSeconds: context.expectedDurationSeconds,
+    output: null,
     source,
+    stage: "source",
     targetFrameRate
   });
-  const result = await transcodeVideo(input, config, onProgress);
-  const output = await inspectDeferredVideo(result.blob, "output");
-  validateDeferredVideoStats({ output, source, targetFrameRate });
-  return result;
+  const transcodeDiagnostics = buildIntegrityDiagnostics({
+    expectedDurationSeconds: context.expectedDurationSeconds,
+    output: null,
+    source,
+    stage: "source",
+    targetFrameRate
+  });
+  transcodeDiagnostics.deferredIntegrityStage = "transcode";
+  const result = await transcodeVideo(input, config, onProgress).catch((error) => {
+    let transcodeError;
+    if (error instanceof Error) {
+      transcodeError = error;
+    } else {
+      transcodeError = new Error(extractErrorMessage(error));
+    }
+    Object.assign(transcodeError, transcodeDiagnostics);
+    throw transcodeError;
+  });
+  const outputDiagnostics = {
+    deferredIntegrityStage: "output",
+    mediaRecorderExpectedDurationSeconds: context.expectedDurationSeconds
+  };
+  if (source !== null) {
+    outputDiagnostics.deferredSourceDurationSeconds = source.duration;
+    outputDiagnostics.deferredSourcePacketCount = source.packetCount;
+    outputDiagnostics.deferredSourcePacketRate = source.averagePacketRate;
+    outputDiagnostics.deferredSourceMaximumPacketGap = source.maximumPacketGap;
+  }
+  const output = await inspectDeferredVideo(result.blob, "output", outputDiagnostics);
+  const validation = {
+    expectedDurationSeconds: context.expectedDurationSeconds,
+    output,
+    source,
+    stage: "output",
+    targetFrameRate
+  };
+  validateDeferredVideoStats(validation);
+  return {
+    ...result,
+    diagnostics: buildIntegrityDiagnostics(validation)
+  };
 }
 
 // src/core/recording/recording-manager.ts
@@ -23171,7 +23386,8 @@ class RecordingManager {
       this.callbacks.onStopAudioTracking();
       logger.debug("[RecordingManager] Stopping recording in stream manager");
       const stopResult = await this.streamManager.stopRecording();
-      const finalBlob = await this.resolveFinalRecordingBlob(stopResult.blob, stopResult.captureFrameRate);
+      const finalResult = await this.resolveFinalRecordingBlob(stopResult.blob, stopResult.captureFrameRate, stopResult.expectedDurationSeconds);
+      const finalBlob = finalResult.blob;
       logger.info("[RecordingManager] Recording stopped, blob size:", finalBlob.size);
       this.recordingState = RECORDING_STATE_IDLE;
       this.callbacks.onStateChange(this.recordingState);
@@ -23193,6 +23409,9 @@ class RecordingManager {
       if (stopResult.mediaRecorderDiagnostics !== undefined) {
         Object.assign(telemetryProperties, stopResult.mediaRecorderDiagnostics);
       }
+      if (finalResult.diagnostics !== undefined) {
+        Object.assign(telemetryProperties, finalResult.diagnostics);
+      }
       return {
         blob: finalBlob,
         telemetryProperties
@@ -23273,13 +23492,16 @@ class RecordingManager {
     this.recordingStartTime = null;
     this.maxTimeRemaining = null;
   }
-  async resolveFinalRecordingBlob(blob, captureFrameRate) {
+  async resolveFinalRecordingBlob(blob, captureFrameRate, expectedDurationSeconds) {
     if (this.activeRouteDecision.route !== "safe-capture-post-recording-transcode") {
-      return blob;
+      return { blob };
     }
     if (!this.activeRecordingConfig) {
       throw new Error("Recording config unavailable for final video processing");
     }
+    if (typeof expectedDurationSeconds !== "number" || !Number.isFinite(expectedDurationSeconds) || expectedDurationSeconds < 0) {
+      throw new Error("Recording active duration unavailable for final video processing");
+    }
     const transcodeConfig = {
       ...this.activeRecordingConfig,
       fps: this.resolveDeferredCaptureFrameRate(captureFrameRate),
@@ -23288,9 +23510,12 @@ class RecordingManager {
     this.callbacks.onTranscodingProgress?.(0);
     const result = await this.dependencies.transcodeVideo(blob, transcodeConfig, (progress) => {
       this.callbacks.onTranscodingProgress?.(progress);
-    });
+    }, { expectedDurationSeconds });
     this.callbacks.onTranscodingProgress?.(1);
-    return result.blob;
+    return {
+      blob: result.blob,
+      diagnostics: result.diagnostics
+    };
   }
   resolveDeferredCaptureFrameRate(captureFrameRate) {
     if (typeof captureFrameRate === "number" && Number.isFinite(captureFrameRate) && captureFrameRate > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vidtreo/recorder",
-  "version": "1.7.10",
+  "version": "1.7.11",
   "type": "module",
   "description": "Vidtreo SDK for browser-based video recording and transcoding. Features include camera/screen recording, real-time MP4 transcoding, audio level analysis, mute/pause controls, source switching, device selection, and automatic backend uploads. Similar to Ziggeo and Addpipe, Vidtreo provides enterprise-grade video processing capabilities for web applications.",
   "main": "./dist/index.js",