@bendyline/squisq-video-react 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,176 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { Doc, MediaProvider } from '@bendyline/squisq/schemas';
+import { VideoQuality, VideoOrientation, RenderHtmlOptions } from '@bendyline/squisq-video';
+import { CaptionMode } from '@bendyline/squisq-react';
+
+interface VideoExportModalProps {
+    /** The document to export */
+    doc: Doc;
+    /** Player IIFE bundle source */
+    playerScript: string;
+    /** Optional media provider for resolving images/audio */
+    mediaProvider?: MediaProvider;
+    /** Pre-collected images map (alternative to mediaProvider) */
+    images?: Map<string, ArrayBuffer>;
+    /** Pre-collected audio map */
+    audio?: Map<string, ArrayBuffer>;
+    /** Called when the modal should close */
+    onClose: () => void;
+}
+declare function VideoExportModal({ doc, playerScript, mediaProvider, images, audio, onClose, }: VideoExportModalProps): react_jsx_runtime.JSX.Element;
+
+interface VideoExportButtonProps {
+    /** The document to export */
+    doc: Doc;
+    /** Player IIFE bundle source */
+    playerScript: string;
+    /** Optional media provider for resolving images/audio */
+    mediaProvider?: MediaProvider;
+    /** Pre-collected images map */
+    images?: Map<string, ArrayBuffer>;
+    /** Pre-collected audio map */
+    audio?: Map<string, ArrayBuffer>;
+    /** Button label (default: "Export Video") */
+    label?: string;
+    /** Additional inline styles for the button */
+    style?: React.CSSProperties;
+    /** Whether the button is disabled */
+    disabled?: boolean;
+}
+declare function VideoExportButton({ doc, playerScript, mediaProvider, images, audio, label, style, disabled, }: VideoExportButtonProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * useVideoExport — Main orchestration hook for browser video export.
+ *
+ * Coordinates frame capture (hidden iframe + html2canvas) with
+ * main-thread WebCodecs encoding via mp4-muxer. Manages the full
+ * lifecycle: prepare → capture + encode → download.
+ *
+ * Encoding runs on the main thread because frame capture via html2canvas
+ * (~100-200ms per frame) is the bottleneck, not encoding (~1ms per frame
+ * with hardware-accelerated WebCodecs). Worker offloading would add
+ * complexity with minimal benefit.
+ *
+ * Usage:
+ *   const { state, progress, phase, startExport, cancel, downloadUrl } = useVideoExport();
+ *   <button onClick={() => startExport(doc, options)}>Export</button>
+ */
+
+type VideoExportState = 'idle' | 'preparing' | 'capturing' | 'encoding' | 'complete' | 'error';
+interface VideoExportConfig {
+    /** Encoding quality preset (default: 'normal') */
+    quality?: VideoQuality;
+    /** Frames per second (default: 30) */
+    fps?: number;
+    /** Viewport orientation (default: 'landscape') */
+    orientation?: VideoOrientation;
+    /**
+     * Map of relative image paths to binary data.
+     * Used to embed images into the render HTML.
+     */
+    images?: Map<string, ArrayBuffer>;
+    /**
+     * Map of audio segment names to binary data.
+     * Used to embed audio into the render HTML.
+     */
+    audio?: Map<string, ArrayBuffer>;
+    /** MediaProvider to resolve media URLs (alternative to passing images directly) */
+    mediaProvider?: MediaProvider;
+    /** Caption mode for the exported video (default: 'off') */
+    captionMode?: CaptionMode;
+    /** Player IIFE bundle (unused in browser export, kept for CLI/Playwright path) */
+    playerScript?: string;
+}
+interface VideoExportResult {
+    /** Current export state */
+    state: VideoExportState;
+    /** 0–100 progress percentage */
+    progress: number;
+    /** Human-readable description of the current phase */
+    phase: string;
+    /** Video duration detected from the doc (seconds) */
+    duration: number;
+    /** Encoder backend ('webcodecs' when active, null when idle) */
+    backend: 'webcodecs' | null;
+    /** Blob download URL (populated when state === 'complete') */
+    downloadUrl: string | null;
+    /** File size in bytes (populated when state === 'complete') */
+    fileSize: number;
+    /** Error message (populated when state === 'error') */
+    error: string | null;
+    /** Seconds elapsed since export started */
+    elapsed: number;
+    /** Estimated seconds remaining (0 when idle or complete) */
+    estimatedRemaining: number;
+    /** Start a new export */
+    startExport: (doc: Doc, config: VideoExportConfig) => Promise<void>;
+    /** Cancel an in-progress export */
+    cancel: () => void;
+    /** Reset state back to idle (e.g., after complete or error) */
+    reset: () => void;
+}
+declare function useVideoExport(): VideoExportResult;
+
+/**
+ * useFrameCapture — Hidden div + html2canvas frame capture.
+ *
+ * Mounts a DocPlayer in renderMode inside a hidden div (same document),
+ * then captures individual frames by seeking the player and rendering
+ * the DOM to a canvas via html2canvas.
+ *
+ * Uses React directly — no script injection, no iframes, no eval.
+ *
+ * Returns an ImageBitmap for each frame (transferable to a Worker).
+ */
+
+interface FrameCaptureHandle {
+    /** Initialize the hidden player. Returns the video duration in seconds. */
+    init: (doc: Doc, renderOptions: Omit<RenderHtmlOptions, 'playerScript'>, captionMode?: CaptionMode) => Promise<number>;
+    /** Capture a single frame at the given time (seconds). Returns an ImageBitmap. */
+    captureFrame: (time: number) => Promise<ImageBitmap>;
+    /** Clean up resources. */
+    destroy: () => void;
+}
+/**
+ * Hook that manages a hidden div for frame capture.
+ */
+declare function useFrameCapture(): FrameCaptureHandle;
+
+/**
+ * Main-thread WebCodecs encoder.
+ *
+ * Encodes video frames to MP4 using the WebCodecs API and mp4-muxer,
+ * running directly on the main thread. This is simpler and avoids
+ * worker module-resolution issues with bundlers. Since frame capture
+ * via html2canvas (~100-200ms per frame) is the bottleneck — not
+ * encoding (~1ms per frame with hardware-accelerated WebCodecs) —
+ * worker offloading provides minimal benefit.
+ *
+ * Requirements: Chrome 94+ / Edge 94+ (WebCodecs support).
+ */
+interface EncoderConfig {
+    width: number;
+    height: number;
+    fps: number;
+    quality: 'draft' | 'normal' | 'high';
+}
+interface MainThreadEncoder {
+    /** Encode a single frame. The bitmap is closed after encoding. */
+    encodeFrame(bitmap: ImageBitmap, frameIndex: number): void;
+    /** Flush pending frames and finalize the MP4. Returns the MP4 ArrayBuffer. */
+    finalize(): Promise<ArrayBuffer>;
+    /** Close the encoder without producing output (e.g., on cancel). */
+    close(): void;
+}
+/**
+ * Check whether the browser supports WebCodecs video encoding.
+ */
+declare function supportsWebCodecs(): boolean;
+/**
+ * Create a main-thread WebCodecs encoder.
+ *
+ * Throws if WebCodecs is not available.
+ */
+declare function createEncoder(config: EncoderConfig): MainThreadEncoder;
+
+export { type FrameCaptureHandle, type MainThreadEncoder, VideoExportButton, type VideoExportButtonProps, type VideoExportConfig, VideoExportModal, type VideoExportModalProps, type VideoExportResult, type VideoExportState, createEncoder, supportsWebCodecs, useFrameCapture, useVideoExport };