@bendyline/squisq-video-react 2.1.0 → 2.2.1

package/dist/chunk-VILZP3GL.js

@@ -0,0 +1,856 @@
+import {
+  EXPORT_AUDIO_CHANNELS,
+  EXPORT_AUDIO_SAMPLE_RATE,
+  audioBufferToWav,
+  createEncoder,
+  encodeAacTrack,
+  muxAudioWithFfmpegWasm,
+  renderAudioTimeline,
+  selectAudioTier,
+  supportsWebCodecs,
+  supportsWebCodecsAac,
+  supportsWebCodecsH264
+} from "./chunk-YZN7D4IC.js";
+
+// src/hooks/useFrameCapture.ts
+import { createElement } from "react";
+import { createRoot } from "react-dom/client";
+import { useRef, useCallback, useMemo } from "react";
+import { DocPlayer, MediaContext } from "@bendyline/squisq-react";
+import html2canvas from "html2canvas";
+var MIME_MAP = {
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  bmp: "image/bmp",
+  avif: "image/avif"
+};
+function createInlineProvider(images) {
+  const blobUrls = /* @__PURE__ */ new Map();
+  const mimeTypes = /* @__PURE__ */ new Map();
+  for (const [path, buffer] of images) {
+    const ext = path.split(".").pop()?.toLowerCase() ?? "";
+    const mime = MIME_MAP[ext] ?? "application/octet-stream";
+    blobUrls.set(path, URL.createObjectURL(new Blob([buffer], { type: mime })));
+    mimeTypes.set(path, mime);
+  }
+  return {
+    async resolveUrl(relativePath) {
+      return blobUrls.get(relativePath) ?? relativePath;
+    },
+    async listMedia() {
+      return [...blobUrls.keys()].map((name) => ({
+        name,
+        mimeType: mimeTypes.get(name) ?? "application/octet-stream",
+        size: images.get(name)?.byteLength ?? 0
+      }));
+    },
+    async addMedia() {
+      throw new Error("Read-only");
+    },
+    async removeMedia() {
+      throw new Error("Read-only");
+    },
+    dispose() {
+      blobUrls.forEach((url) => URL.revokeObjectURL(url));
+      blobUrls.clear();
+    }
+  };
+}
+function useFrameCapture() {
+  const containerRef = useRef(null);
+  const rootRef = useRef(null);
+  const renderAPIRef = useRef(null);
+  const mediaProviderRef = useRef(null);
+  const dimensionsRef = useRef({ width: 1920, height: 1080 });
+  const init = useCallback(
+    async (doc, renderOptions, captionMode) => {
+      if (rootRef.current || containerRef.current || mediaProviderRef.current) {
+        const oldRoot = rootRef.current;
+        const oldContainer = containerRef.current;
+        const oldMediaProvider = mediaProviderRef.current;
+        rootRef.current = null;
+        containerRef.current = null;
+        renderAPIRef.current = null;
+        mediaProviderRef.current = null;
+        await new Promise((resolve) => {
+          setTimeout(() => {
+            if (oldRoot) oldRoot.unmount();
+            if (oldContainer) oldContainer.remove();
+            oldMediaProvider?.dispose();
+            resolve();
+          }, 0);
+        });
+      }
+      const width = renderOptions.width ?? 1920;
+      const height = renderOptions.height ?? 1080;
+      const animationsEnabled = renderOptions.animationsEnabled ?? true;
+      dimensionsRef.current = { width, height };
+      const container = document.createElement("div");
+      container.style.cssText = `position:fixed;left:0;top:0;width:${width}px;height:${height}px;opacity:0;pointer-events:none;z-index:-1;overflow:hidden;`;
+      document.body.appendChild(container);
+      containerRef.current = container;
+      const renderRoot = document.createElement("div");
+      renderRoot.id = "squisq-capture-root";
+      renderRoot.style.cssText = `width:${width}px;height:${height}px;`;
+      container.appendChild(renderRoot);
+      const mediaProvider = renderOptions.images ? createInlineProvider(renderOptions.images) : null;
+      mediaProviderRef.current = mediaProvider;
+      const root = createRoot(renderRoot);
+      rootRef.current = root;
+      const captionsEnabled = captionMode !== void 0 && captionMode !== "off";
+      const captionStyle = captionMode === "social" ? "social" : "standard";
+      let resolveRenderAPI;
+      const renderAPIReady = new Promise((resolve) => {
+        resolveRenderAPI = resolve;
+      });
+      const playerElement = createElement(DocPlayer, {
+        doc,
+        basePath: ".",
+        renderMode: true,
+        animationsEnabled,
+        showControls: false,
+        autoPlay: false,
+        forceViewport: { width, height, name: "export" },
+        captionsEnabled,
+        captionStyle,
+        onRenderAPIReady: (api) => {
+          if (containerRef.current !== container) return;
+          renderAPIRef.current = api;
+          if (api) resolveRenderAPI(api);
+        }
+      });
+      await new Promise((resolve) => setTimeout(resolve, 0));
+      if (mediaProvider) {
+        root.render(createElement(MediaContext.Provider, { value: mediaProvider }, playerElement));
+      } else {
+        root.render(playerElement);
+      }
+      return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          const api = renderAPIRef.current;
+          const hasSeek = typeof api?.seekTo === "function";
+          const hasDur = typeof api?.getDuration === "function";
+          const rootEl = containerRef.current?.querySelector("#squisq-capture-root");
+          const hasPlayer = rootEl ? rootEl.querySelector(".doc-player") !== null : false;
+          reject(
+            new Error(
+              `Render API did not initialize within 15s. seekTo=${hasSeek}, getDuration=${hasDur}, player=${hasPlayer}, root=${!!rootEl}`
+            )
+          );
+        }, 15e3);
+        void renderAPIReady.then((api) => {
+          clearTimeout(timeout);
+          resolve(api.getDuration());
+        });
+      });
+    },
+    []
+  );
+  const captureFrame = useCallback(async (time) => {
+    const container = containerRef.current;
+    const api = renderAPIRef.current;
+    if (!container || !api) {
+      throw new Error("Frame capture not initialized \u2014 call init() first");
+    }
+    const { width, height } = dimensionsRef.current;
+    await api.seekTo(time);
+    await new Promise(
+      (resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve()))
+    );
+    const root = container.querySelector("#squisq-capture-root");
+    if (!root) {
+      throw new Error("Capture root element not found");
+    }
+    const canvas = await html2canvas(root, {
+      width,
+      height,
+      scale: 1,
+      useCORS: true,
+      allowTaint: true,
+      backgroundColor: "#000000",
+      logging: false
+    });
+    const bitmap = await createImageBitmap(canvas);
+    return bitmap;
+  }, []);
+  const destroy = useCallback(() => {
+    if (rootRef.current) {
+      rootRef.current.unmount();
+      rootRef.current = null;
+    }
+    if (containerRef.current) {
+      containerRef.current.remove();
+      containerRef.current = null;
+    }
+    mediaProviderRef.current?.dispose();
+    mediaProviderRef.current = null;
+    renderAPIRef.current = null;
+  }, []);
+  return useMemo(() => ({ init, captureFrame, destroy }), [init, captureFrame, destroy]);
+}
+
+// src/hooks/useVideoExport.ts
+import { useState, useRef as useRef2, useCallback as useCallback2, useEffect } from "react";
+import {
+  DEFAULT_INTERACTIVE_RESOURCE_POLICY,
+  fetchResourceBytes
+} from "@bendyline/squisq/markdown";
+import {
+  resolveDimensions,
+  computeAudioTimeline,
+  resolveFfmpegWasmLoad as resolveFfmpegWasmLoad2,
+  QUALITY_PRESETS
+} from "@bendyline/squisq-video";
+
+// src/workerEncoder.ts
+import { validateVideoExportOptions } from "@bendyline/squisq-video";
+function createWorkerEncoder(config) {
+  validateVideoExportOptions(config);
+  const worker = new Worker(new URL("./workers/encode.worker.js", import.meta.url), {
+    type: "module"
+  });
+  let state = "open";
+  let fatalError = null;
+  let finalizeResolve = null;
+  let finalizeReject = null;
+  let readyResolve = null;
+  let readyReject = null;
+  let readySettled = false;
+  const frameWaiters = /* @__PURE__ */ new Map();
+  const ready = new Promise((resolve, reject) => {
+    readyResolve = resolve;
+    readyReject = reject;
+  });
+  const frameDuration = 1e6 / config.fps;
+  function post(msg, transfer) {
+    worker.postMessage(msg, transfer ?? []);
+  }
+  const currentState = () => state;
+  worker.onmessage = (event) => {
+    const msg = event.data;
+    switch (msg.type) {
+      case "capabilities":
+        readySettled = true;
+        readyResolve?.(msg.backend);
+        readyResolve = readyReject = null;
+        break;
+      case "frame-complete": {
+        const waiter = frameWaiters.get(msg.frameIndex);
+        waiter?.resolve();
+        frameWaiters.delete(msg.frameIndex);
+        break;
+      }
+      case "complete":
+        state = "closed";
+        finalizeResolve?.(msg.data);
+        finalizeResolve = finalizeReject = null;
+        worker.terminate();
+        break;
+      case "error": {
+        const err = new Error(msg.message);
+        fatalError = err;
+        state = "closed";
+        readySettled = true;
+        readyReject?.(err);
+        finalizeReject?.(err);
+        for (const waiter of frameWaiters.values()) waiter.reject(err);
+        frameWaiters.clear();
+        readyResolve = readyReject = null;
+        finalizeResolve = finalizeReject = null;
+        worker.terminate();
+        break;
+      }
+    }
+  };
+  worker.onerror = (event) => {
+    const err = new Error(event.message || "Worker error");
+    fatalError = err;
+    state = "closed";
+    readySettled = true;
+    readyReject?.(err);
+    finalizeReject?.(err);
+    for (const waiter of frameWaiters.values()) waiter.reject(err);
+    frameWaiters.clear();
+    readyResolve = readyReject = null;
+    finalizeResolve = finalizeReject = null;
+    worker.terminate();
+  };
+  post({
+    type: "init",
+    width: config.width,
+    height: config.height,
+    fps: config.fps,
+    quality: config.quality,
+    ...config.totalFrames !== void 0 ? { totalFrames: config.totalFrames } : {},
+    ...config.ffmpegWasm ? { ffmpegWasm: config.ffmpegWasm } : {}
+  });
+  return {
+    ready,
+    encodeFrame(bitmap, frameIndex) {
+      if (state !== "open" || fatalError) {
+        bitmap.close();
+        return Promise.reject(fatalError ?? new Error("Encoder is not accepting frames"));
+      }
+      if (frameWaiters.has(frameIndex)) {
+        bitmap.close();
+        return Promise.reject(new Error(`Frame ${frameIndex} was submitted more than once`));
+      }
+      let resolveFrame;
+      let rejectFrame;
+      const promise = new Promise((resolve, reject) => {
+        resolveFrame = resolve;
+        rejectFrame = reject;
+      });
+      frameWaiters.set(frameIndex, { promise, resolve: resolveFrame, reject: rejectFrame });
+      const timestamp = Math.round(frameIndex * frameDuration);
+      post({ type: "frame", bitmap, frameIndex, timestamp }, [bitmap]);
+      return promise;
+    },
+    async finalize() {
+      if (state !== "open") throw new Error("Encoder already closed or finalizing");
+      if (fatalError) throw fatalError;
+      state = "finalizing";
+      await Promise.all(Array.from(frameWaiters.values(), (waiter) => waiter.promise));
+      if (currentState() === "closed") {
+        throw fatalError ?? new Error("Encoder closed during finalization");
+      }
+      return new Promise((resolve, reject) => {
+        finalizeResolve = resolve;
+        finalizeReject = reject;
+        post({ type: "finalize" });
+      });
+    },
+    close() {
+      if (state === "closed") return;
+      state = "closed";
+      const err = new Error("Encoder closed");
+      if (!readySettled) {
+        readySettled = true;
+        readyReject?.(err);
+      }
+      finalizeReject?.(err);
+      for (const waiter of frameWaiters.values()) waiter.reject(err);
+      frameWaiters.clear();
+      readyResolve = readyReject = null;
+      finalizeResolve = finalizeReject = null;
+      post({ type: "cancel" });
+      worker.terminate();
+    }
+  };
+}
+
+// src/gifTranscode.ts
+import {
+  ffmpegGifOutputArgs,
+  resolveFfmpegWasmLoad
+} from "@bendyline/squisq-video";
+function buildGifFfmpegArgs(options) {
+  return ["-y", "-i", "video.mp4", ...ffmpegGifOutputArgs(options), "out.gif"];
+}
+async function transcodeMp4ToGifWithFfmpegWasm(videoMp4, options, loadConfig, signal) {
+  if (videoMp4.byteLength === 0) {
+    throw new Error("Cannot create an animated GIF from an empty MP4.");
+  }
+  if (signal?.aborted) {
+    throw new DOMException("Animated GIF export was cancelled.", "AbortError");
+  }
+  const load = resolveFfmpegWasmLoad(loadConfig, "Animated GIF export", {
+    classWorkerURL: new URL("./workers/ffmpeg.class-worker.js", import.meta.url).href
+  });
+  const args = buildGifFfmpegArgs(options);
+  const { FFmpeg } = await import("@ffmpeg/ffmpeg");
+  const ffmpeg = new FFmpeg();
+  let terminated = false;
+  const terminate = () => {
+    if (terminated) return;
+    terminated = true;
+    ffmpeg.terminate();
+  };
+  const handleAbort = () => terminate();
+  signal?.addEventListener("abort", handleAbort, { once: true });
+  try {
+    await ffmpeg.load(load);
+    if (signal?.aborted) {
+      throw new DOMException("Animated GIF export was cancelled.", "AbortError");
+    }
+    await ffmpeg.writeFile("video.mp4", videoMp4);
+    if (signal?.aborted) {
+      throw new DOMException("Animated GIF export was cancelled.", "AbortError");
+    }
+    const exitCode = await ffmpeg.exec(args);
+    if (signal?.aborted) {
+      throw new DOMException("Animated GIF export was cancelled.", "AbortError");
+    }
+    if (exitCode !== 0) {
+      throw new Error(`ffmpeg.wasm GIF transcode failed with exit code ${exitCode}`);
+    }
+    const data = await ffmpeg.readFile("out.gif");
+    return data instanceof Uint8Array ? data : new TextEncoder().encode(data);
+  } finally {
+    signal?.removeEventListener("abort", handleAbort);
+    terminate();
+  }
+}
+
+// src/hooks/useVideoExport.ts
+var MAX_EXPORT_MEDIA_FILES = 256;
+var MAX_EXPORT_MEDIA_FILE_BYTES = 64 * 1024 * 1024;
+var MAX_EXPORT_MEDIA_TOTAL_BYTES = 256 * 1024 * 1024;
+function toArrayBuffer(bytes) {
+  return bytes.slice().buffer;
+}
+function collectDocumentMediaReferences(doc) {
+  const references = /* @__PURE__ */ new Set();
+  const seen = /* @__PURE__ */ new WeakSet();
+  const visit = (value) => {
+    if (typeof value === "string") {
+      references.add(value);
+      if (value.startsWith("./")) references.add(value.slice(2));
+      return;
+    }
+    if (!value || typeof value !== "object" || seen.has(value)) return;
+    seen.add(value);
+    if (Array.isArray(value)) {
+      value.forEach(visit);
+      return;
+    }
+    Object.values(value).forEach(visit);
+  };
+  visit(doc);
+  return references;
+}
+async function resolveAudioBuffers(clips, sources) {
+  const srcs = new Set(clips.map((c) => c.src));
+  const out = /* @__PURE__ */ new Map();
+  for (const src of srcs) {
+    let data = sources.audio?.get(src) ?? sources.images?.get(src);
+    if (!data && sources.mediaProvider) {
+      try {
+        const url = await sources.mediaProvider.resolveUrl(src);
+        const resource = await fetchResourceBytes(url, {
+          policy: sources.resourcePolicy
+        });
+        data = toArrayBuffer(resource.bytes);
+      } catch {
+      }
+    }
+    if (data) out.set(src, data);
+  }
+  return out;
+}
+function useVideoExport() {
+  const [state, setState] = useState("idle");
+  const [progress, setProgress] = useState(0);
+  const [phase, setPhase] = useState("");
+  const [duration, setDuration] = useState(0);
+  const [outputFormat, setOutputFormat] = useState("mp4");
+  const [backend, setBackend] = useState(null);
+  const [downloadUrl, setDownloadUrl] = useState(null);
+  const [fileSize, setFileSize] = useState(0);
+  const [audioIncluded, setAudioIncluded] = useState(false);
+  const [audioSkippedReason, setAudioSkippedReason] = useState(null);
+  const [error, setError] = useState(null);
+  const [elapsed, setElapsed] = useState(0);
+  const [estimatedRemaining, setEstimatedRemaining] = useState(0);
+  const encoderRef = useRef2(null);
+  const gifAbortRef = useRef2(null);
+  const cancelledRef = useRef2(false);
+  const downloadUrlRef = useRef2(null);
+  const startTimeRef = useRef2(0);
+  const elapsedTimerRef = useRef2(null);
+  const frameCapture = useFrameCapture();
+  useEffect(() => {
+    return () => {
+      if (elapsedTimerRef.current) clearInterval(elapsedTimerRef.current);
+      if (downloadUrlRef.current) {
+        URL.revokeObjectURL(downloadUrlRef.current);
+      }
+      if (encoderRef.current) {
+        encoderRef.current.close();
+      }
+      gifAbortRef.current?.abort();
+      frameCapture.destroy();
+    };
+  }, [frameCapture]);
+  const reset = useCallback2(() => {
+    if (downloadUrlRef.current) {
+      URL.revokeObjectURL(downloadUrlRef.current);
+      downloadUrlRef.current = null;
+    }
+    if (encoderRef.current) {
+      encoderRef.current.close();
+      encoderRef.current = null;
+    }
+    gifAbortRef.current?.abort();
+    gifAbortRef.current = null;
+    frameCapture.destroy();
+    setState("idle");
+    setProgress(0);
+    setPhase("");
+    setDuration(0);
+    setOutputFormat("mp4");
+    setBackend(null);
+    setDownloadUrl(null);
+    setFileSize(0);
+    setAudioIncluded(false);
+    setAudioSkippedReason(null);
+    setError(null);
+    setElapsed(0);
+    setEstimatedRemaining(0);
+    if (elapsedTimerRef.current) clearInterval(elapsedTimerRef.current);
+    cancelledRef.current = false;
+  }, [frameCapture]);
+  const cancel = useCallback2(() => {
+    cancelledRef.current = true;
+    if (elapsedTimerRef.current) clearInterval(elapsedTimerRef.current);
+    if (encoderRef.current) {
+      encoderRef.current.close();
+      encoderRef.current = null;
+    }
+    gifAbortRef.current?.abort();
+    gifAbortRef.current = null;
+    frameCapture.destroy();
+    setState("idle");
+    setProgress(0);
+    setPhase("Cancelled");
+  }, [frameCapture]);
+  const startExport = useCallback2(
+    async (doc, config) => {
+      cancelledRef.current = false;
+      if (downloadUrlRef.current) {
+        URL.revokeObjectURL(downloadUrlRef.current);
+        downloadUrlRef.current = null;
+      }
+      setDownloadUrl(null);
+      setFileSize(0);
+      setAudioIncluded(false);
+      setAudioSkippedReason(null);
+      setError(null);
+      const quality = config.quality ?? "normal";
+      const effectiveOutputFormat = config.outputFormat ?? "mp4";
+      const fps = config.fps ?? (effectiveOutputFormat === "gif" ? 10 : 30);
+      const orientation = config.orientation ?? "landscape";
+      const animationsEnabled = config.animationsEnabled ?? effectiveOutputFormat === "mp4";
+      const audioPolicy = config.audioPolicy ?? "require";
+      setOutputFormat(effectiveOutputFormat);
+      try {
+        const gifDefaults = orientation === "portrait" ? { width: 540, height: 960 } : { width: 960, height: 540 };
+        const { width, height } = resolveDimensions({
+          orientation,
+          fps,
+          quality,
+          ...config.width !== void 0 ? { width: config.width } : effectiveOutputFormat === "gif" ? { width: gifDefaults.width } : {},
+          ...config.height !== void 0 ? { height: config.height } : effectiveOutputFormat === "gif" ? { height: gifDefaults.height } : {}
+        });
+        const webCodecsAvailable = supportsWebCodecs();
+        const sharedArrayBufferAvailable = typeof SharedArrayBuffer !== "undefined";
+        if (effectiveOutputFormat === "gif" && !sharedArrayBufferAvailable) {
+          throw new Error(
+            "Animated GIF export requires ffmpeg.wasm and SharedArrayBuffer (Cross-Origin-Isolation headers)."
+          );
+        }
+        if (effectiveOutputFormat === "gif") {
+          resolveFfmpegWasmLoad2(config.ffmpegWasm, "Animated GIF export");
+        }
+        if (!webCodecsAvailable && !sharedArrayBufferAvailable) {
+          throw new Error(
+            "No video encoder available. WebCodecs requires Chrome 94+ / Edge 94+, and the ffmpeg.wasm fallback requires SharedArrayBuffer (Cross-Origin-Isolation headers)."
+          );
+        }
+        setState("preparing");
+        setPhase("Loading document\u2026");
+        setProgress(0);
+        setElapsed(0);
+        setEstimatedRemaining(0);
+        startTimeRef.current = performance.now();
+        if (elapsedTimerRef.current) clearInterval(elapsedTimerRef.current);
+        elapsedTimerRef.current = setInterval(() => {
+          setElapsed(Math.floor((performance.now() - startTimeRef.current) / 1e3));
+        }, 1e3);
+        let images = config.images;
+        if (!images && config.mediaProvider) {
+          images = /* @__PURE__ */ new Map();
+          const entries = await config.mediaProvider.listMedia();
+          const references = collectDocumentMediaReferences(doc);
+          const neededEntries = entries.filter(
+            (entry) => references.has(entry.name) || references.has(`./${entry.name}`)
+          );
+          if (neededEntries.length > MAX_EXPORT_MEDIA_FILES) {
+            throw new Error(
+              `Document references ${neededEntries.length} media files; browser export supports at most ${MAX_EXPORT_MEDIA_FILES}.`
+            );
+          }
+          let totalMediaBytes = 0;
+          for (const entry of neededEntries) {
+            if (cancelledRef.current) return;
+            if (entry.size > MAX_EXPORT_MEDIA_FILE_BYTES) {
+              throw new Error(`Media file "${entry.name}" is too large for browser video export.`);
+            }
+            const url2 = await config.mediaProvider.resolveUrl(entry.name);
+            const resource = await fetchResourceBytes(url2, {
+              policy: {
+                ...DEFAULT_INTERACTIVE_RESOURCE_POLICY,
+                ...config.resourcePolicy,
+                maxBytes: Math.min(
+                  config.resourcePolicy?.maxBytes ?? MAX_EXPORT_MEDIA_FILE_BYTES,
+                  MAX_EXPORT_MEDIA_FILE_BYTES
+                )
+              }
+            });
+            const data = toArrayBuffer(resource.bytes);
+            totalMediaBytes += data.byteLength;
+            if (totalMediaBytes > MAX_EXPORT_MEDIA_TOTAL_BYTES) {
+              throw new Error("Referenced media exceeds the browser video export memory limit.");
+            }
+            images.set(entry.name, data);
+          }
+        }
+        const docDuration = await frameCapture.init(
+          doc,
+          { images, audio: config.audio, width, height, animationsEnabled },
+          config.captionMode
+        );
+        if (cancelledRef.current) return;
+        setDuration(docDuration);
+        if (docDuration <= 0) {
+          throw new Error("Document has zero duration \u2014 nothing to export");
+        }
+        const totalFrames = Math.ceil(docDuration * fps);
+        setPhase("Starting encoder\u2026");
+        setProgress(5);
+        const canUseWebCodecs = webCodecsAvailable && await supportsWebCodecsH264({ width, height, fps, quality });
+        const audioBitrate = (QUALITY_PRESETS[quality] ?? QUALITY_PRESETS.normal).audioBitrate;
+        const timeline = effectiveOutputFormat === "mp4" && audioPolicy !== "omit" ? computeAudioTimeline(doc, 0) : [];
+        const aacSupported = timeline.length > 0 ? await supportsWebCodecsAac(EXPORT_AUDIO_SAMPLE_RATE, EXPORT_AUDIO_CHANNELS) : false;
+        const tierDecision = selectAudioTier({
+          hasClips: timeline.length > 0,
+          aacSupported,
+          sharedArrayBufferAvailable,
+          canUseMainThreadWebCodecs: canUseWebCodecs
+        });
+        let renderedAudio = null;
+        let audioIncludedLocal = false;
+        let audioReasonLocal = tierDecision.reason;
+        if (timeline.length > 0 && tierDecision.tier === 3 && audioPolicy === "require") {
+          throw new Error(tierDecision.reason ?? "This browser cannot include the document audio.");
+        }
+        if (tierDecision.tier === 1 || tierDecision.tier === 2) {
+          setPhase("Preparing audio\u2026");
+          try {
+            const buffers = await resolveAudioBuffers(timeline, {
+              audio: config.audio,
+              images,
+              mediaProvider: config.mediaProvider,
+              resourcePolicy: config.resourcePolicy
+            });
+            const missingSources = [...new Set(timeline.map((clip) => clip.src))].filter(
+              (src) => !buffers.has(src)
+            );
+            if (missingSources.length > 0) {
+              audioReasonLocal = `Audio files could not be loaded: ${missingSources.join(", ")}`;
+              if (audioPolicy === "require") throw new Error(audioReasonLocal);
+            }
+            if (buffers.size === 0) {
+              audioReasonLocal ?? (audioReasonLocal = "Audio files for this document could not be loaded.");
+            } else {
+              const totalAudioDur = timeline.reduce(
+                (max, c) => Math.max(max, c.startSec + c.durationSec),
+                docDuration
+              );
+              renderedAudio = await renderAudioTimeline(
+                timeline,
+                buffers,
+                totalAudioDur,
+                EXPORT_AUDIO_SAMPLE_RATE
+              );
+            }
+          } catch (audioErr) {
+            renderedAudio = null;
+            audioReasonLocal = `Audio could not be prepared: ${audioErr instanceof Error ? audioErr.message : String(audioErr)}`;
+            if (audioPolicy === "require") throw new Error(audioReasonLocal);
+          }
+        }
+        const useInlineAudio = renderedAudio !== null && tierDecision.tier === 1;
+        const useFfmpegAudio = renderedAudio !== null && tierDecision.tier === 2;
+        if (cancelledRef.current) return;
+        let encoder;
+        if (canUseWebCodecs) {
+          encoder = createEncoder({
+            width,
+            height,
+            fps,
+            quality,
+            ...useInlineAudio && renderedAudio ? {
+              audio: {
+                numberOfChannels: renderedAudio.numberOfChannels,
+                sampleRate: renderedAudio.sampleRate
+              }
+            } : {}
+          });
+          setBackend("webcodecs");
+        } else if (sharedArrayBufferAvailable) {
+          const workerEncoder = createWorkerEncoder({
+            width,
+            height,
+            fps,
+            quality,
+            totalFrames,
+            ffmpegWasm: config.ffmpegWasm
+          });
+          encoder = workerEncoder;
+          const selectedBackend = await workerEncoder.ready;
+          setBackend(selectedBackend);
+          setPhase(
+            selectedBackend === "ffmpeg-wasm" ? "Starting encoder (ffmpeg.wasm)\u2026" : "Starting encoder\u2026"
+          );
+        } else {
+          throw new Error(
+            "WebCodecs H.264 is unavailable in this browser and the ffmpeg.wasm fallback requires SharedArrayBuffer (Cross-Origin-Isolation headers)."
+          );
+        }
+        encoderRef.current = encoder;
+        if (cancelledRef.current) return;
+        setState("capturing");
+        const captureStartTime = performance.now();
+        const UI_UPDATE_INTERVAL = 10;
+        for (let i = 0; i < totalFrames; i++) {
+          if (cancelledRef.current) return;
+          const time = i / fps;
+          if (i % UI_UPDATE_INTERVAL === 0 || i === totalFrames - 1) {
+            const captureProgress = Math.round(i / totalFrames * 90);
+            setProgress(5 + captureProgress);
+            setPhase(`Capturing frame ${i + 1}/${totalFrames} (${time.toFixed(1)}s)`);
+            if (i > 0) {
+              const elapsedCapture = (performance.now() - captureStartTime) / 1e3;
+              const avgPerFrame = elapsedCapture / i;
+              const remaining = Math.round(avgPerFrame * (totalFrames - i));
+              setEstimatedRemaining(remaining);
+            }
+          }
+          const bitmap = await frameCapture.captureFrame(time);
+          if (cancelledRef.current) {
+            bitmap.close();
+            return;
+          }
+          await encoder.encodeFrame(bitmap, i);
+        }
+        if (cancelledRef.current) return;
+        if (useInlineAudio && renderedAudio && encoder.addAudioChunk) {
+          setState("encoding");
+          setPhase("Encoding audio\u2026");
+          try {
+            await encodeAacTrack(
+              renderedAudio,
+              { addAudioChunk: encoder.addAudioChunk.bind(encoder) },
+              audioBitrate
+            );
+            audioIncludedLocal = true;
+          } catch (audioErr) {
+            audioIncludedLocal = false;
+            audioReasonLocal = `Audio encoding failed: ${audioErr instanceof Error ? audioErr.message : String(audioErr)}`;
+            if (audioPolicy === "require") throw new Error(audioReasonLocal);
+          }
+        }
+        setState("encoding");
+        setPhase(effectiveOutputFormat === "gif" ? "Finalizing GIF frames\u2026" : "Finalizing video\u2026");
+        setProgress(95);
+        let outputBytes = await encoder.finalize();
+        encoderRef.current = null;
+        if (cancelledRef.current) return;
+        if (effectiveOutputFormat === "gif") {
+          setPhase("Generating GIF palette\u2026");
+          const videoOnly = outputBytes instanceof Uint8Array ? outputBytes : new Uint8Array(outputBytes);
+          const gifAbort = new AbortController();
+          gifAbortRef.current = gifAbort;
+          try {
+            outputBytes = await transcodeMp4ToGifWithFfmpegWasm(
+              videoOnly,
+              { width, height, loop: 0 },
+              config.ffmpegWasm,
+              gifAbort.signal
+            );
+          } finally {
+            if (gifAbortRef.current === gifAbort) gifAbortRef.current = null;
+          }
+        } else if (useFfmpegAudio && renderedAudio) {
+          setPhase("Muxing audio\u2026");
+          try {
+            const wav = audioBufferToWav(renderedAudio);
+            const videoOnly = outputBytes instanceof Uint8Array ? outputBytes : new Uint8Array(outputBytes);
+            outputBytes = await muxAudioWithFfmpegWasm(
+              videoOnly,
+              wav,
+              audioBitrate,
+              config.ffmpegWasm
+            );
+            audioIncludedLocal = true;
+          } catch (audioErr) {
+            audioIncludedLocal = false;
+            audioReasonLocal = `Audio muxing failed: ${audioErr instanceof Error ? audioErr.message : String(audioErr)}`;
+            if (audioPolicy === "require") throw new Error(audioReasonLocal);
+          }
+        }
+        if (cancelledRef.current) return;
+        const finalBytes = outputBytes instanceof Uint8Array ? outputBytes.slice() : new Uint8Array(outputBytes);
+        const mimeType = effectiveOutputFormat === "gif" ? "image/gif" : "video/mp4";
+        const blob = new Blob([finalBytes], { type: mimeType });
+        const url = URL.createObjectURL(blob);
+        downloadUrlRef.current = url;
+        setDownloadUrl(url);
+        setFileSize(finalBytes.byteLength);
+        setAudioIncluded(audioIncludedLocal);
+        setAudioSkippedReason(
+          effectiveOutputFormat === "gif" || audioIncludedLocal ? null : audioReasonLocal
+        );
+        setState("complete");
+        setProgress(100);
+        setPhase("Export complete");
+        setEstimatedRemaining(0);
+        if (elapsedTimerRef.current) clearInterval(elapsedTimerRef.current);
+        frameCapture.destroy();
+      } catch (err) {
+        if (elapsedTimerRef.current) clearInterval(elapsedTimerRef.current);
+        if (cancelledRef.current) return;
+        const message = err instanceof Error ? err.message : String(err);
+        setState("error");
+        setError(message);
+        setPhase("Export failed");
+        if (encoderRef.current) {
+          encoderRef.current.close();
+          encoderRef.current = null;
+        }
+        gifAbortRef.current?.abort();
+        gifAbortRef.current = null;
+        frameCapture.destroy();
+      }
+    },
+    [frameCapture]
+  );
+  return {
+    state,
+    progress,
+    phase,
+    duration,
+    outputFormat,
+    backend,
+    downloadUrl,
+    fileSize,
+    audioIncluded,
+    audioSkippedReason,
+    error,
+    elapsed,
+    estimatedRemaining,
+    startExport,
+    cancel,
+    reset
+  };
+}
+
+export {
+  useFrameCapture,
+  useVideoExport
+};