@vidtreo/recorder 1.7.8 → 1.7.10

package/dist/index.d.ts

@@ -185,6 +185,19 @@ export {};
 
 export {};
 
+export type MediaStats = {
+    audioChannels: number;
+    audioDuration: number;
+    audioSampleRate: number;
+    videoFrameCount: number;
+    videoFrameRate: number;
+    videoDuration: number;
+};
+export declare function inspectMedia(blob: Blob): Promise<MediaStats>;
+export declare function transcodePreservingCadence(blob: Blob): Promise<Blob>;
+
+export {};
+
 export {};
 
 export {};
@@ -1546,6 +1559,7 @@ import type { TranscodeConfig } from "../transcode/transcode-types";
 import { type VisibilityInterval } from "../utils/tab-visibility-tracker";
 export type StopRecordingResult = {
     blob: Blob;
+    captureFrameRate?: number;
     tabVisibilityIntervals: VisibilityInterval[];
     recordingStats?: StreamRecordingStats;
     encoderAcceleration?: VideoHardwareAcceleration;
@@ -1576,6 +1590,7 @@ export declare class StreamRecordingState {
     private mediaRecorderStopResolve;
     private mediaRecorderStopReject;
     private mediaRecorderError;
+    private safeCaptureFrameRate;
     private mediaRecorderErrorTimeoutId;
     private readonly streamManager;
     private readonly dependencies;
@@ -1600,6 +1615,7 @@ export declare class StreamRecordingState {
     private clearBufferSizeInterval;
     private resetRecordingState;
     private startSafeCaptureRecording;
+    private resolveEffectiveSafeCaptureFrameRate;
     private applySafeCaptureTrackConstraints;
     private resolveSafeCaptureVideoConstraints;
     private stopSafeCaptureRecording;
@@ -1919,13 +1935,13 @@ export declare class RecorderController {
 
 import type { CameraStreamManager } from "../stream/stream";
 import { StreamProcessor } from "../stream/stream-processor";
+import { transcodeDeferredVideo } from "../transcode/deferred-video-transcoder";
 import type { TranscodeConfig } from "../transcode/transcode-types";
-import { transcodeVideo } from "../transcode/video-transcoder";
 export type RecordingStopResult = {
     blob: Blob;
     telemetryProperties: Record<string, unknown>;
 };
-type TranscodeVideoDependency = typeof transcodeVideo;
+type TranscodeVideoDependency = typeof transcodeDeferredVideo;
 type RecordingManagerDependencies = {
     transcodeVideo: TranscodeVideoDependency;
 };
@@ -1979,6 +1995,7 @@ export declare class RecordingManager {
     cleanup(): void;
     private resetRecordingState;
     private resolveFinalRecordingBlob;
+    private resolveDeferredCaptureFrameRate;
     private resetPauseState;
     private getOrCreateStreamProcessor;
     private resolveRouteDecision;
@@ -3151,6 +3168,20 @@ export declare function getFileExtensionForOutputFormat(format: OutputFormat): s
 export declare function transcodeVideo(input: TranscodeInput, config?: Partial<TranscodeConfig>, onProgress?: (progress: number) => void): Promise<TranscodeResult>;
 export declare function transcodeVideoForNativeCamera(file: File, config?: Partial<TranscodeConfig>, onProgress?: (progress: number) => void): Promise<TranscodeResult>;
 
+export type VideoPacketSummary = {
+    averagePacketRate: number;
+    duration: number;
+    maximumPacketGap: number;
+    packetCount: number;
+};
+export type DeferredVideoStatsValidation = {
+    output: VideoPacketSummary | null;
+    source: VideoPacketSummary | null;
+    targetFrameRate: number;
+};
+export declare function validateDeferredVideoStats(validation: DeferredVideoStatsValidation): void;
+export declare function transcodeDeferredVideo(input: Blob, config: TranscodeConfig, onProgress?: (progress: number) => void): Promise<TranscodeResult>;
+
 export type VidtreoRecorderConfig = {
     apiKey: string;
     apiUrl?: string;

package/dist/index.js

@@ -1890,6 +1890,9 @@ function createConversionOptions(config, optimizeForSpeed = false) {
   if (config.codec !== undefined) {
     video.codec = config.codec;
   }
+  if (config.latencyMode !== undefined) {
+    video.latencyMode = config.latencyMode;
+  }
   if (optimizeForSpeed) {
     video.bitrateMode = "variable";
     video.latencyMode = "realtime";
@@ -5282,7 +5285,8 @@ var ANDROID_SAFE_CAPTURE_CONSTRAINTS = {
   height: { ideal: 720, max: 720 },
   frameRate: { ideal: 24, max: 24 }
 };
-var SAFE_CAPTURE_TIMESLICE_MS = 1000;
+var LOW_RESOURCE_SAFE_CAPTURE_FRAME_RATE = 20;
+var ANDROID_SAFE_CAPTURE_FRAME_RATE = 24;
 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";
@@ -5319,6 +5323,7 @@ class StreamRecordingState {
   mediaRecorderStopResolve = null;
   mediaRecorderStopReject = null;
   mediaRecorderError = null;
+  safeCaptureFrameRate = null;
   mediaRecorderErrorTimeoutId = null;
   streamManager;
   dependencies;
@@ -5496,6 +5501,7 @@ class StreamRecordingState {
       logger.debug("[StreamRecordingState] Finalizing MediaRecorder capture");
       result = {
         blob: safeCaptureResult.blob,
+        captureFrameRate: safeCaptureResult.captureFrameRate,
         mediaRecorderDiagnostics: safeCaptureResult.diagnostics
       };
     } else {
@@ -5513,6 +5519,7 @@ class StreamRecordingState {
     });
     return {
       blob: result.blob,
+      captureFrameRate: result.captureFrameRate,
       tabVisibilityIntervals,
       recordingStats: result.recordingStats,
       encoderAcceleration: result.encoderAcceleration,
@@ -5644,6 +5651,7 @@ class StreamRecordingState {
       });
     }
     await this.applySafeCaptureTrackConstraints(mediaStream);
+    this.safeCaptureFrameRate = this.resolveEffectiveSafeCaptureFrameRate(mediaStream, config);
     this.mediaRecorderChunks = [];
     this.mediaRecorderError = null;
     const preferredMimeType = this.resolvePreferredSafeCaptureMimeType(config);
@@ -5672,8 +5680,18 @@ class StreamRecordingState {
       const mimeType = recorder.mimeType || this.resolveSafeCaptureMimeType();
       const blob = new Blob(this.mediaRecorderChunks, { type: mimeType });
       const diagnostics = this.buildMediaRecorderDiagnostics(recorder);
+      const captureFrameRate = this.safeCaptureFrameRate;
+      if (captureFrameRate === null) {
+        this.mediaRecorderStopReject?.(new Error("Safe capture frame rate is unavailable"));
+        return;
+      }
+      diagnostics.mediaRecorderCaptureFrameRate = captureFrameRate;
       if (blob.size > 0) {
-        this.mediaRecorderStopResolve?.({ blob, diagnostics });
+        this.mediaRecorderStopResolve?.({
+          blob,
+          captureFrameRate,
+          diagnostics
+        });
         return;
       }
       this.mediaRecorderStopReject?.(this.createEmptyMediaRecorderError(recorder));
@@ -5681,7 +5699,27 @@ class StreamRecordingState {
     recorder.onerror = (event) => {
       this.mediaRecorderError = this.createMediaRecorderError(event, recorder);
     };
-    recorder.start(SAFE_CAPTURE_TIMESLICE_MS);
+    recorder.start();
+  }
+  resolveEffectiveSafeCaptureFrameRate(mediaStream, config) {
+    const videoTrack = mediaStream.getVideoTracks()[0];
+    if (videoTrack && typeof videoTrack.getSettings === "function") {
+      const frameRate = videoTrack.getSettings().frameRate;
+      if (typeof frameRate === "number" && Number.isFinite(frameRate) && frameRate > 0) {
+        return frameRate;
+      }
+    }
+    const reasonCodes = this.activeRouteDecision.reasonCodes;
+    if (reasonCodes.includes(ANDROID_POST_RECORDING_TRANSCODE_REASON)) {
+      return ANDROID_SAFE_CAPTURE_FRAME_RATE;
+    }
+    if (reasonCodes.includes("insufficient-device-memory") || reasonCodes.includes("insufficient-hardware-concurrency") || reasonCodes.includes("encoding-capability-unsupported") || reasonCodes.includes("encoding-not-smooth") || reasonCodes.includes("encoding-not-power-efficient")) {
+      return LOW_RESOURCE_SAFE_CAPTURE_FRAME_RATE;
+    }
+    if (typeof config.fps === "number" && Number.isFinite(config.fps) && config.fps > 0) {
+      return config.fps;
+    }
+    return LOW_RESOURCE_SAFE_CAPTURE_FRAME_RATE;
   }
   async applySafeCaptureTrackConstraints(mediaStream) {
     const constraints = this.resolveSafeCaptureVideoConstraints();
@@ -5726,6 +5764,7 @@ class StreamRecordingState {
       this.mediaRecorderStopResolve = null;
       this.mediaRecorderStopReject = null;
       this.mediaRecorderError = null;
+      this.safeCaptureFrameRate = null;
       this.clearMediaRecorderErrorTimeout();
       this.activeRouteDecision = DEFAULT_ROUTE_DECISION;
     }
@@ -6315,7 +6354,7 @@ function resolveDeviceError(input) {
 // package.json
 var package_default = {
   name: "@vidtreo/recorder",
-  version: "1.7.8",
+  version: "1.7.10",
   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",
@@ -22751,6 +22790,136 @@ class StreamProcessor {
   }
 }
 
+// src/core/transcode/deferred-video-transcoder.ts
+import { ALL_FORMATS as ALL_FORMATS2, BlobSource as BlobSource3, EncodedPacketSink, Input as Input3 } from "mediabunny";
+var MINIMUM_FRAME_DENSITY_RATIO = 0.9;
+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 INTEGRITY_ERROR_CODE = "recording.deferred-transcode-integrity";
+function createIntegrityError(message) {
+  const error = new Error(message);
+  error.name = "DeferredTranscodeIntegrityError";
+  error.code = INTEGRITY_ERROR_CODE;
+  error.isRecoverable = true;
+  return error;
+}
+function validatePacketSummary(summary, label) {
+  if (!Number.isFinite(summary.averagePacketRate)) {
+    throw createIntegrityError(`${label} video packet rate is invalid`);
+  }
+  if (!Number.isFinite(summary.duration)) {
+    throw createIntegrityError(`${label} video duration is invalid`);
+  }
+  if (!Number.isFinite(summary.maximumPacketGap)) {
+    throw createIntegrityError(`${label} video maximum packet gap is invalid`);
+  }
+  if (summary.averagePacketRate <= 0 || summary.duration <= 0) {
+    throw createIntegrityError(`${label} video packet statistics are empty`);
+  }
+  if (summary.maximumPacketGap < 0) {
+    throw createIntegrityError(`${label} video maximum packet gap is invalid`);
+  }
+  if (!Number.isInteger(summary.packetCount) || summary.packetCount <= 0) {
+    throw createIntegrityError(`${label} video packet count is invalid`);
+  }
+}
+function validateFrameCadence(summary, label, targetFrameRate) {
+  const minimumPacketRate = targetFrameRate * MINIMUM_FRAME_DENSITY_RATIO;
+  if (summary.averagePacketRate < minimumPacketRate) {
+    throw createIntegrityError(`${label} video frame density is below the capture target`);
+  }
+  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 validateDeferredVideoStats(validation) {
+  if (!Number.isFinite(validation.targetFrameRate) || validation.targetFrameRate <= 0) {
+    throw createIntegrityError("Deferred transcode requires a valid capture frame rate");
+  }
+  if (!(validation.source && validation.output)) {
+    throw createIntegrityError("Deferred transcode source or output has no primary video track");
+  }
+  validatePacketSummary(validation.source, "Source");
+  validatePacketSummary(validation.output, "Output");
+  validateFrameCadence(validation.source, "Source", validation.targetFrameRate);
+  validateFrameCadence(validation.output, "Output", validation.targetFrameRate);
+  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");
+  }
+  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");
+  }
+}
+async function inspectVideoPackets(blob) {
+  const input = new Input3({
+    formats: ALL_FORMATS2,
+    source: new BlobSource3(blob)
+  });
+  const videoTrack = await input.getPrimaryVideoTrack();
+  if (videoTrack === null) {
+    input.dispose();
+    return null;
+  }
+  try {
+    const packetSink = new EncodedPacketSink(videoTrack);
+    const timestamps = [];
+    let firstTimestamp = Number.POSITIVE_INFINITY;
+    let lastEndTimestamp = Number.NEGATIVE_INFINITY;
+    for await (const packet of packetSink.packets(undefined, undefined, {
+      metadataOnly: true
+    })) {
+      timestamps.push(packet.timestamp);
+      firstTimestamp = Math.min(firstTimestamp, packet.timestamp);
+      lastEndTimestamp = Math.max(lastEndTimestamp, packet.timestamp + packet.duration);
+    }
+    timestamps.sort((left, right) => left - right);
+    let maximumPacketGap = 0;
+    for (let index = 1;index < timestamps.length; index += 1) {
+      maximumPacketGap = Math.max(maximumPacketGap, timestamps[index] - timestamps[index - 1]);
+    }
+    const duration = lastEndTimestamp - firstTimestamp;
+    const packetCount = timestamps.length;
+    const averagePacketRate = packetCount > 0 ? packetCount / duration : 0;
+    return {
+      averagePacketRate,
+      duration,
+      maximumPacketGap,
+      packetCount
+    };
+  } finally {
+    input.dispose();
+  }
+}
+async function inspectDeferredVideo(blob, label) {
+  return await inspectVideoPackets(blob).catch((error) => {
+    const message = extractErrorMessage(error);
+    throw createIntegrityError(`Could not inspect ${label} deferred video: ${message}`);
+  });
+}
+async function transcodeDeferredVideo(input, config, onProgress) {
+  const targetFrameRate = config.fps;
+  if (typeof targetFrameRate !== "number" || !Number.isFinite(targetFrameRate) || targetFrameRate <= 0) {
+    throw createIntegrityError("Deferred transcode requires a valid capture frame rate");
+  }
+  const source = await inspectDeferredVideo(input, "source");
+  validateDeferredVideoStats({
+    output: source,
+    source,
+    targetFrameRate
+  });
+  const result = await transcodeVideo(input, config, onProgress);
+  const output = await inspectDeferredVideo(result.blob, "output");
+  validateDeferredVideoStats({ output, source, targetFrameRate });
+  return result;
+}
+
 // src/core/recording/recording-manager.ts
 var DEFAULT_COUNTDOWN_DURATION = 5000;
 var MILLISECONDS_PER_SECOND4 = 1000;
@@ -22759,12 +22928,15 @@ var RECORDING_TIMER_INTERVAL = 1000;
 var RECORDING_STATE_RECORDING = "recording";
 var RECORDING_STATE_IDLE = "idle";
 var RECORDING_STATE_COUNTDOWN = "countdown";
+var LOW_RESOURCE_SAFE_CAPTURE_FRAME_RATE2 = 20;
+var ANDROID_SAFE_CAPTURE_FRAME_RATE2 = 24;
+var ANDROID_POST_RECORDING_TRANSCODE_REASON2 = "android-post-recording-transcode";
 var DEFAULT_ROUTE_DECISION2 = {
   route: "local-webcodecs",
   reasonCodes: ["webcodecs-supported", "target-codec-supported"]
 };
 var DEFAULT_RECORDING_MANAGER_DEPENDENCIES = {
-  transcodeVideo
+  transcodeVideo: transcodeDeferredVideo
 };
 
 class RecordingManager {
@@ -22999,7 +23171,7 @@ 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);
+      const finalBlob = await this.resolveFinalRecordingBlob(stopResult.blob, stopResult.captureFrameRate);
       logger.info("[RecordingManager] Recording stopped, blob size:", finalBlob.size);
       this.recordingState = RECORDING_STATE_IDLE;
       this.callbacks.onStateChange(this.recordingState);
@@ -23101,20 +23273,34 @@ class RecordingManager {
     this.recordingStartTime = null;
     this.maxTimeRemaining = null;
   }
-  async resolveFinalRecordingBlob(blob) {
+  async resolveFinalRecordingBlob(blob, captureFrameRate) {
     if (this.activeRouteDecision.route !== "safe-capture-post-recording-transcode") {
       return blob;
     }
     if (!this.activeRecordingConfig) {
       throw new Error("Recording config unavailable for final video processing");
     }
+    const transcodeConfig = {
+      ...this.activeRecordingConfig,
+      fps: this.resolveDeferredCaptureFrameRate(captureFrameRate),
+      latencyMode: "quality"
+    };
     this.callbacks.onTranscodingProgress?.(0);
-    const result = await this.dependencies.transcodeVideo(blob, this.activeRecordingConfig, (progress) => {
+    const result = await this.dependencies.transcodeVideo(blob, transcodeConfig, (progress) => {
       this.callbacks.onTranscodingProgress?.(progress);
     });
     this.callbacks.onTranscodingProgress?.(1);
     return result.blob;
   }
+  resolveDeferredCaptureFrameRate(captureFrameRate) {
+    if (typeof captureFrameRate === "number" && Number.isFinite(captureFrameRate) && captureFrameRate > 0) {
+      return captureFrameRate;
+    }
+    if (this.activeRouteDecision.reasonCodes.includes(ANDROID_POST_RECORDING_TRANSCODE_REASON2)) {
+      return ANDROID_SAFE_CAPTURE_FRAME_RATE2;
+    }
+    return LOW_RESOURCE_SAFE_CAPTURE_FRAME_RATE2;
+  }
   resetPauseState() {
     this.isPaused = false;
     this.pauseStartTime = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vidtreo/recorder",
-  "version": "1.7.8",
+  "version": "1.7.10",
   "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",