@ai-matrx/capture 0.5.4 → 0.5.6

package/dist/react.d.cts

@@ -776,6 +776,35 @@ declare function nextCameraDevice<T extends {
     deviceId: string;
 }>(cameras: readonly T[], currentDeviceId: string | null | undefined): T | null;
 
+/**
+ * The one terminal video contract shared by the package-owned MediaRecorder
+ * engine and host adapters. Emitted bytes are stronger MIME evidence than a
+ * requested/recorder format, and a delivered recording always carries a
+ * positive integer duration.
+ */
+interface FinalizeCapturedVideoOptions {
+    parts: readonly BlobPart[];
+    /** MIME observed on emitted/final Blob data — the strongest authority. */
+    emittedMime?: string | null | undefined;
+    /** MediaRecorder-reported MIME — fallback when emitted bytes have none. */
+    recorderMime?: string | null | undefined;
+    durationMs: number;
+    fileNamePrefix: string;
+    /** Injectable filename clock for deterministic tests. */
+    timestampMs?: number;
+}
+interface CapturedVideoResult {
+    file: File;
+    mime: string;
+    durationMs: number;
+}
+/**
+ * Finalize recording bytes without letting requested MIME, filename, and
+ * duration drift apart. Unknown/non-video formats fail loudly rather than
+ * producing a mislabeled upload.
+ */
+declare function finalizeCapturedVideo(options: FinalizeCapturedVideoOptions): CapturedVideoResult;
+
 /**
  * src/engine/permissions.ts — permission pre-checks + error classification
  * for the default engine (and for hosts, so they stop re-implementing the
@@ -986,4 +1015,4 @@ interface CloudLibrarySheetProps {
 }
 declare function CloudLibrarySheet({ open, onClose, items, loading, busy, onOpenItem, onUpload, title, }: CloudLibrarySheetProps): React__default.JSX.Element | null;
 
-export { CameraCapture, type CameraCaptureProps, CameraCaptureV3, type CameraCaptureV3Props, CameraFeed, type CaptureAspect, type CaptureCameraEngine, type CaptureCameraMode, type CaptureCameraSlots, type CaptureCameraV3Slots, type CaptureCloudLibraryItem, type CaptureCloudPort, CaptureExpandingField, type CaptureExpandingFieldProps, CaptureFilmstrip, type CaptureFilmstripProps, type CaptureMediaItem, type CaptureMediaSession, type CaptureOptionTile, CaptureRail, type CaptureRailAction, type CaptureRailProps, CaptureSheet, type CaptureSheetAction, type CaptureSheetProps, type CaptureTimerSetting, CloudLibrarySheet, type CloudLibrarySheetProps, CountdownOverlay, type DefaultCaptureEngine, type DefaultEngineOptions, GridOverlay, HoldShutter, type HoldShutterProps, ImageEditSheet, type ImageEditSheetProps, type MediaPermissionState, MediaViewer, type MediaViewerProps, type MicInterruptionReason, type MicStreamState, ModeSelector, type ModeSelectorProps, OptionsGridPanel, type OptionsGridPanelProps, PHOTO_JPEG_QUALITY, type ResolvedMedia, ShutterButton, type ShutterButtonProps, type TrackControls, ZoomRow, type ZoomRowProps, acquireWarmMic, adoptWarmAudioStream, buildWarmMicConstraints, classifyCameraBlockReason, cropBlobToAspect, getMediaUrl, getWarmMicState, hardStopWarmMic, invalidateMedia, isMediaDenialError, nextCameraDevice, notifyMicPermissionRevoked, primeMedia, queryCameraPermission, queryMicPermission, releaseWarmMic, setPreferredMicDeviceId, shouldCombineMicPrompt, subscribeWarmMic, subscribeWarmMicInterruption, useDefaultCaptureEngine, useMediaUrl, useTrackControls, warmMicDebug };
+export { CameraCapture, type CameraCaptureProps, CameraCaptureV3, type CameraCaptureV3Props, CameraFeed, type CaptureAspect, type CaptureCameraEngine, type CaptureCameraMode, type CaptureCameraSlots, type CaptureCameraV3Slots, type CaptureCloudLibraryItem, type CaptureCloudPort, CaptureExpandingField, type CaptureExpandingFieldProps, CaptureFilmstrip, type CaptureFilmstripProps, type CaptureMediaItem, type CaptureMediaSession, type CaptureOptionTile, CaptureRail, type CaptureRailAction, type CaptureRailProps, CaptureSheet, type CaptureSheetAction, type CaptureSheetProps, type CaptureTimerSetting, type CapturedVideoResult, CloudLibrarySheet, type CloudLibrarySheetProps, CountdownOverlay, type DefaultCaptureEngine, type DefaultEngineOptions, type FinalizeCapturedVideoOptions, GridOverlay, HoldShutter, type HoldShutterProps, ImageEditSheet, type ImageEditSheetProps, type MediaPermissionState, MediaViewer, type MediaViewerProps, type MicInterruptionReason, type MicStreamState, ModeSelector, type ModeSelectorProps, OptionsGridPanel, type OptionsGridPanelProps, PHOTO_JPEG_QUALITY, type ResolvedMedia, ShutterButton, type ShutterButtonProps, type TrackControls, ZoomRow, type ZoomRowProps, acquireWarmMic, adoptWarmAudioStream, buildWarmMicConstraints, classifyCameraBlockReason, cropBlobToAspect, finalizeCapturedVideo, getMediaUrl, getWarmMicState, hardStopWarmMic, invalidateMedia, isMediaDenialError, nextCameraDevice, notifyMicPermissionRevoked, primeMedia, queryCameraPermission, queryMicPermission, releaseWarmMic, setPreferredMicDeviceId, shouldCombineMicPrompt, subscribeWarmMic, subscribeWarmMicInterruption, useDefaultCaptureEngine, useMediaUrl, useTrackControls, warmMicDebug };

package/dist/react.d.ts

@@ -776,6 +776,35 @@ declare function nextCameraDevice<T extends {
     deviceId: string;
 }>(cameras: readonly T[], currentDeviceId: string | null | undefined): T | null;
 
+/**
+ * The one terminal video contract shared by the package-owned MediaRecorder
+ * engine and host adapters. Emitted bytes are stronger MIME evidence than a
+ * requested/recorder format, and a delivered recording always carries a
+ * positive integer duration.
+ */
+interface FinalizeCapturedVideoOptions {
+    parts: readonly BlobPart[];
+    /** MIME observed on emitted/final Blob data — the strongest authority. */
+    emittedMime?: string | null | undefined;
+    /** MediaRecorder-reported MIME — fallback when emitted bytes have none. */
+    recorderMime?: string | null | undefined;
+    durationMs: number;
+    fileNamePrefix: string;
+    /** Injectable filename clock for deterministic tests. */
+    timestampMs?: number;
+}
+interface CapturedVideoResult {
+    file: File;
+    mime: string;
+    durationMs: number;
+}
+/**
+ * Finalize recording bytes without letting requested MIME, filename, and
+ * duration drift apart. Unknown/non-video formats fail loudly rather than
+ * producing a mislabeled upload.
+ */
+declare function finalizeCapturedVideo(options: FinalizeCapturedVideoOptions): CapturedVideoResult;
+
 /**
  * src/engine/permissions.ts — permission pre-checks + error classification
  * for the default engine (and for hosts, so they stop re-implementing the
@@ -986,4 +1015,4 @@ interface CloudLibrarySheetProps {
 }
 declare function CloudLibrarySheet({ open, onClose, items, loading, busy, onOpenItem, onUpload, title, }: CloudLibrarySheetProps): React__default.JSX.Element | null;
 
-export { CameraCapture, type CameraCaptureProps, CameraCaptureV3, type CameraCaptureV3Props, CameraFeed, type CaptureAspect, type CaptureCameraEngine, type CaptureCameraMode, type CaptureCameraSlots, type CaptureCameraV3Slots, type CaptureCloudLibraryItem, type CaptureCloudPort, CaptureExpandingField, type CaptureExpandingFieldProps, CaptureFilmstrip, type CaptureFilmstripProps, type CaptureMediaItem, type CaptureMediaSession, type CaptureOptionTile, CaptureRail, type CaptureRailAction, type CaptureRailProps, CaptureSheet, type CaptureSheetAction, type CaptureSheetProps, type CaptureTimerSetting, CloudLibrarySheet, type CloudLibrarySheetProps, CountdownOverlay, type DefaultCaptureEngine, type DefaultEngineOptions, GridOverlay, HoldShutter, type HoldShutterProps, ImageEditSheet, type ImageEditSheetProps, type MediaPermissionState, MediaViewer, type MediaViewerProps, type MicInterruptionReason, type MicStreamState, ModeSelector, type ModeSelectorProps, OptionsGridPanel, type OptionsGridPanelProps, PHOTO_JPEG_QUALITY, type ResolvedMedia, ShutterButton, type ShutterButtonProps, type TrackControls, ZoomRow, type ZoomRowProps, acquireWarmMic, adoptWarmAudioStream, buildWarmMicConstraints, classifyCameraBlockReason, cropBlobToAspect, getMediaUrl, getWarmMicState, hardStopWarmMic, invalidateMedia, isMediaDenialError, nextCameraDevice, notifyMicPermissionRevoked, primeMedia, queryCameraPermission, queryMicPermission, releaseWarmMic, setPreferredMicDeviceId, shouldCombineMicPrompt, subscribeWarmMic, subscribeWarmMicInterruption, useDefaultCaptureEngine, useMediaUrl, useTrackControls, warmMicDebug };
+export { CameraCapture, type CameraCaptureProps, CameraCaptureV3, type CameraCaptureV3Props, CameraFeed, type CaptureAspect, type CaptureCameraEngine, type CaptureCameraMode, type CaptureCameraSlots, type CaptureCameraV3Slots, type CaptureCloudLibraryItem, type CaptureCloudPort, CaptureExpandingField, type CaptureExpandingFieldProps, CaptureFilmstrip, type CaptureFilmstripProps, type CaptureMediaItem, type CaptureMediaSession, type CaptureOptionTile, CaptureRail, type CaptureRailAction, type CaptureRailProps, CaptureSheet, type CaptureSheetAction, type CaptureSheetProps, type CaptureTimerSetting, type CapturedVideoResult, CloudLibrarySheet, type CloudLibrarySheetProps, CountdownOverlay, type DefaultCaptureEngine, type DefaultEngineOptions, type FinalizeCapturedVideoOptions, GridOverlay, HoldShutter, type HoldShutterProps, ImageEditSheet, type ImageEditSheetProps, type MediaPermissionState, MediaViewer, type MediaViewerProps, type MicInterruptionReason, type MicStreamState, ModeSelector, type ModeSelectorProps, OptionsGridPanel, type OptionsGridPanelProps, PHOTO_JPEG_QUALITY, type ResolvedMedia, ShutterButton, type ShutterButtonProps, type TrackControls, ZoomRow, type ZoomRowProps, acquireWarmMic, adoptWarmAudioStream, buildWarmMicConstraints, classifyCameraBlockReason, cropBlobToAspect, finalizeCapturedVideo, getMediaUrl, getWarmMicState, hardStopWarmMic, invalidateMedia, isMediaDenialError, nextCameraDevice, notifyMicPermissionRevoked, primeMedia, queryCameraPermission, queryMicPermission, releaseWarmMic, setPreferredMicDeviceId, shouldCombineMicPrompt, subscribeWarmMic, subscribeWarmMicInterruption, useDefaultCaptureEngine, useMediaUrl, useTrackControls, warmMicDebug };

package/dist/react.js

@@ -3033,6 +3033,43 @@ function warmMicDebug() {
   };
 }
 
+// src/engine/video-result.ts
+var VIDEO_EXTENSIONS = {
+  "video/mp4": "mp4",
+  "video/webm": "webm",
+  "video/ogg": "ogv",
+  "video/quicktime": "mov"
+};
+function firstNonEmpty(...values) {
+  for (const value of values) {
+    const normalized = value?.trim();
+    if (normalized) return normalized;
+  }
+  return "video/webm";
+}
+function finalizeCapturedVideo(options) {
+  if (!Number.isFinite(options.durationMs)) {
+    throw new Error("finalizeCapturedVideo requires a finite duration.");
+  }
+  const mime = firstNonEmpty(options.emittedMime, options.recorderMime);
+  const container = mime.split(";")[0]?.trim().toLowerCase() ?? "";
+  const extension = VIDEO_EXTENSIONS[container];
+  if (!extension) {
+    throw new Error(
+      `finalizeCapturedVideo requires a recognized video MIME; received "${mime}".`
+    );
+  }
+  const durationMs = Math.max(1, Math.round(options.durationMs));
+  const blob = new Blob([...options.parts], { type: mime });
+  const timestampMs = options.timestampMs ?? Date.now();
+  const file = new File(
+    [blob],
+    `${options.fileNamePrefix}-video-${timestampMs}.${extension}`,
+    { type: mime }
+  );
+  return { file, mime, durationMs };
+}
+
 // src/engine/useDefaultEngine.ts
 var RECORDING_MIME_LADDER = [
   'video/mp4;codecs="avc1.42E01E,mp4a.40.2"',
@@ -3287,16 +3324,15 @@ function useDefaultCaptureEngine(options) {
         if (entry.micHeld) releaseWarmMic();
         recorderRef.current = null;
         setRecording(false);
-        const durationMs = Math.round(performance.now() - entry.startedAt);
-        const type = recorder.mimeType || entry.chunks[0]?.type || "video/webm";
-        const blob = new Blob(entry.chunks, { type });
-        const ext = type.includes("mp4") ? "mp4" : "webm";
-        callbacksRef.current.onVideo(
-          new File([blob], `${fileNamePrefix}-video-${Date.now()}.${ext}`, {
-            type
-          }),
-          durationMs
-        );
+        const captured = finalizeCapturedVideo({
+          parts: entry.chunks,
+          // Emitted chunk MIME is stronger evidence than recorder.mimeType.
+          emittedMime: entry.chunks.find((chunk) => chunk.type)?.type,
+          recorderMime: recorder.mimeType,
+          durationMs: performance.now() - entry.startedAt,
+          fileNamePrefix
+        });
+        callbacksRef.current.onVideo(captured.file, captured.durationMs);
       };
       recorder.start(1e3);
       setRecordElapsedSeconds(0);
@@ -3499,6 +3535,7 @@ export {
   buildWarmMicConstraints,
   classifyCameraBlockReason,
   cropBlobToAspect,
+  finalizeCapturedVideo,
   getMediaUrl,
   getWarmMicState,
   hardStopWarmMic,