@bendyline/squisq-video-react 2.2.10 → 2.3.0

package/README.md

@@ -76,10 +76,15 @@ function App() {
 
 ## Components
 
-| Component           | Description                                                                        |
-| ------------------- | ---------------------------------------------------------------------------------- |
-| `VideoExportModal`  | Full modal UI — configure MP4/GIF, captions, motion, quality, fps, and orientation |
-| `VideoExportButton` | Drop-in button that opens the export modal via portal                              |
+| Component               | Description                                                                        |
+| ----------------------- | ---------------------------------------------------------------------------------- |
+| `VideoExportModal`      | Full modal UI — configure MP4/GIF, captions, motion, quality, fps, and orientation |
+| `VideoExportButton`     | Drop-in button that opens the export modal via portal                              |
+| `CoverImageExportModal` | Save the managed cover as PNG, JPEG, or WebP with bounded resolution controls      |
+
+Import `CoverImageExportModal` from
+`@bendyline/squisq-video-react/cover-image` when a surface only needs cover
+capture. This entry point excludes the MP4/GIF encoder worker graph.
 
 ## Hooks
 
@@ -94,11 +99,16 @@ The `VideoExportModal` lets users configure:
 
 - **Format:** MP4 video or animated GIF
 - **Quality:** draft, normal, or high
-- **FPS:** 10, 15, 24, or 30
+- **FPS:** 10, 15, 24, or 30; MP4 defaults to 30 fps and GIF to 10 fps
 - **Orientation:** MP4 defaults to 1920x1080/1080x1920; GIF defaults to 960x540/540x960
 - **Captions:** off, standard, or social
 - **Animations & transitions:** enabled by default for MP4 and disabled by default for GIF
 
+Managed covers inherit `squisq-cover-duration` and `squisq-cover-playback`
+from document frontmatter. `preroll` adds the cover before story frame zero
+and shifts audio; `overlay` keeps the exported duration unchanged while the
+story and audio advance underneath the visible cover.
+
 ## Using the Hook Directly
 
 For custom export UIs, use `useVideoExport` directly:

package/dist/{chunk-2XACUF6E.js → chunk-32QCPFXE.js}

@@ -1,8 +1,9 @@
 import {
+  DEFAULT_MP4_SPILL_THRESHOLD_BYTES,
   applyWebCodecsBackpressure,
   createMp4Muxer,
   resolveWebCodecsQueueLimit
-} from "./chunk-MEPETH5V.js";
+} from "./chunk-5MFQMJ5Z.js";
 
 // src/mainThreadEncoder.ts
 import { bitrateForQuality, validateVideoExportOptions } from "@bendyline/squisq-video";
@@ -24,6 +25,14 @@ async function supportsWebCodecsH264(config) {
     return false;
   }
 }
+var RECLAIMED_CODEC_ERROR = /codec reclaimed due to inactivity/i;
+var MAX_CODEC_RECOVERY_ATTEMPTS = 2;
+function toError(caught) {
+  return caught instanceof Error ? caught : new Error(String(caught));
+}
+function isReclaimedCodecError(error) {
+  return RECLAIMED_CODEC_ERROR.test(error.message);
+}
 function createEncoder(config) {
   validateVideoExportOptions(config);
   if (!supportsWebCodecs()) {
@@ -35,64 +44,141 @@ function createEncoder(config) {
     width: config.width,
     height: config.height,
     fps: config.fps,
-    ...config.audio ? { audio: config.audio } : {}
+    ...config.audio ? { audio: config.audio } : {},
+    ...config.spillOutputToBlob ? { spillToBlobThresholdBytes: DEFAULT_MP4_SPILL_THRESHOLD_BYTES } : {}
   });
   let closed = false;
   let fatalError = null;
+  let recoverableError = null;
   const frameDuration = 1e6 / config.fps;
   const queueLimit = resolveWebCodecsQueueLimit(config);
   let framesSinceFlush = 0;
+  let forceNextKeyFrame = false;
+  let encoderGeneration = 0;
+  let encoder;
   function fail(err) {
     closed = true;
     if (encoder.state !== "closed") encoder.close();
     return fatalError ?? err;
   }
-  const encoder = new VideoEncoder({
-    output(chunk, meta) {
-      if (closed) return;
-      muxer.addVideoChunk(chunk, meta ?? void 0);
-    },
-    error(err) {
-      fatalError ?? (fatalError = new Error(`WebCodecs encoder error: ${err.message}`));
-    }
-  });
-  encoder.configure({
-    // Deliberate profile split from the fallback worker (avc1.42001f, Baseline):
-    // this primary WebCodecs path targets H.264 High@4.0 for better quality up
-    // to 1080p; the wasm-fallback worker uses Baseline for max decoder compat.
+  const videoEncoderConfig = {
+    // Deliberate profile split from the fallback worker (avc1.42001f,
+    // Baseline): this primary WebCodecs path targets H.264 High@4.0 for
+    // better quality up to 1080p; the wasm-fallback worker uses Baseline for
+    // maximum decoder compatibility.
     codec: "avc1.640028",
-    // H.264 High profile, level 4.0 (supports up to 1080p)
     width: config.width,
     height: config.height,
     bitrate: bitrateForQuality(config.quality, config.width, config.height),
     framerate: config.fps
-  });
-  return {
-    async encodeFrame(source, frameIndex) {
-      if (fatalError) {
-        if ("close" in source) source.close();
-        throw fail(fatalError);
+  };
+  function createConfiguredVideoEncoder() {
+    const generation = ++encoderGeneration;
+    const nextEncoder = new VideoEncoder({
+      output(chunk, meta) {
+        if (closed || generation !== encoderGeneration) return;
+        muxer.addVideoChunk(chunk, meta ?? void 0);
+      },
+      error(err) {
+        if (closed || generation !== encoderGeneration || fatalError || recoverableError) return;
+        const wrapped = new Error(`WebCodecs encoder error: ${err.message}`);
+        if (isReclaimedCodecError(wrapped)) {
+          recoverableError = wrapped;
+        } else {
+          fatalError = wrapped;
+        }
       }
-      if (closed) {
-        if ("close" in source) source.close();
-        throw new Error("Encoder already closed");
+    });
+    nextEncoder.configure(videoEncoderConfig);
+    return nextEncoder;
+  }
+  function recoverCodec() {
+    const previousEncoder = encoder;
+    recoverableError = null;
+    if (previousEncoder.state !== "closed") previousEncoder.close();
+    encoder = createConfiguredVideoEncoder();
+    framesSinceFlush = 0;
+    forceNextKeyFrame = true;
+  }
+  encoder = createConfiguredVideoEncoder();
+  async function finishVideoEncoding() {
+    if (closed) throw new Error("Encoder already closed");
+    let recoveryAttempts = 0;
+    while (true) {
+      if (fatalError) throw fail(fatalError);
+      if (recoverableError) {
+        if (recoveryAttempts >= MAX_CODEC_RECOVERY_ATTEMPTS) {
+          throw fail(recoverableError);
+        }
+        recoverCodec();
+        recoveryAttempts++;
       }
       try {
-        const drained = await applyWebCodecsBackpressure(encoder, queueLimit, framesSinceFlush);
-        if (drained) framesSinceFlush = 0;
-        if (fatalError) throw fail(fatalError);
-        if (closed) throw new Error("Encoder already closed");
-        const timestamp = Math.round(frameIndex * frameDuration);
-        const frame = new VideoFrame(source, { timestamp });
+        await encoder.flush();
+      } catch (caught) {
+        const error = toError(caught);
+        if (!recoverableError && isReclaimedCodecError(error)) {
+          recoverableError = error;
+        }
+        if (recoverableError && recoveryAttempts < MAX_CODEC_RECOVERY_ATTEMPTS) continue;
+        throw fail(fatalError ?? recoverableError ?? error);
+      }
+      if (fatalError) throw fail(fatalError);
+      if (recoverableError) continue;
+      break;
+    }
+    encoder.close();
+    closed = true;
+  }
+  return {
+    async encodeFrame(source, frameIndex) {
+      try {
         try {
-          const keyFrame = frameIndex % 30 === 0;
-          encoder.encode(frame, { keyFrame });
-          framesSinceFlush++;
-        } finally {
-          frame.close();
+          let recoveryAttempts = 0;
+          while (true) {
+            if (fatalError) throw fail(fatalError);
+            if (closed) throw new Error("Encoder already closed");
+            if (recoverableError) {
+              if (recoveryAttempts >= MAX_CODEC_RECOVERY_ATTEMPTS) {
+                throw fail(recoverableError);
+              }
+              recoverCodec();
+              recoveryAttempts++;
+            }
+            try {
+              const drained = await applyWebCodecsBackpressure(
+                encoder,
+                queueLimit,
+                framesSinceFlush
+              );
+              if (drained) framesSinceFlush = 0;
+              if (fatalError) throw fail(fatalError);
+              if (recoverableError) continue;
+              if (closed) throw new Error("Encoder already closed");
+              const timestamp = Math.round(frameIndex * frameDuration);
+              const frame = new VideoFrame(source, { timestamp });
+              try {
+                const keyFrame = forceNextKeyFrame || frameIndex % 30 === 0;
+                encoder.encode(frame, { keyFrame });
+                framesSinceFlush++;
+                forceNextKeyFrame = false;
+              } finally {
+                frame.close();
+              }
+              if (recoverableError) continue;
+              return;
+            } catch (caught) {
+              const error = toError(caught);
+              if (!recoverableError && isReclaimedCodecError(error)) {
+                recoverableError = error;
+              }
+              if (recoverableError && recoveryAttempts < MAX_CODEC_RECOVERY_ATTEMPTS) continue;
+              throw fail(fatalError ?? recoverableError ?? error);
+            }
+          }
+        } catch (caught) {
+          throw fail(toError(caught));
         }
-      } catch (err) {
-        throw fail(err instanceof Error ? err : new Error(String(err)));
       } finally {
         if ("close" in source) source.close();
       }
@@ -102,18 +188,13 @@ function createEncoder(config) {
       muxer.addAudioChunk(chunk, meta);
     },
     async finalize() {
-      if (closed) throw new Error("Encoder already closed");
-      if (fatalError) throw fail(fatalError);
-      try {
-        await encoder.flush();
-      } catch (err) {
-        throw fail(err instanceof Error ? err : new Error(String(err)));
-      }
-      if (fatalError) throw fail(fatalError);
-      encoder.close();
-      closed = true;
+      await finishVideoEncoding();
       return muxer.finalize();
     },
+    async finalizeBlob() {
+      await finishVideoEncoding();
+      return muxer.finalizeBlob();
+    },
     close() {
       if (closed) return;
       closed = true;
@@ -186,25 +267,35 @@ async function renderAudioTimeline(clips, buffers, totalDurationSec, sampleRate
   if (requiredFailures.length > 0) {
     throw new Error(`No decodable audio track was found in: ${requiredFailures.join(", ")}`);
   }
-  let scheduledNodes = 0;
-  for (const clip of clips) {
-    const buffer = decoded.get(clip.src);
-    if (!buffer) {
-      if (clip.sourceKind === "video") continue;
-      throw new Error(`Audio source was not decoded: ${clip.src}`);
+  const scheduledNodes = [];
+  try {
+    for (const clip of clips) {
+      const buffer = decoded.get(clip.src);
+      if (!buffer) {
+        if (clip.sourceKind === "video") continue;
+        throw new Error(`Audio source was not decoded: ${clip.src}`);
+      }
+      const node = ctx.createBufferSource();
+      node.buffer = buffer;
+      node.connect(ctx.destination);
+      const when = Math.max(0, clip.startSec);
+      const offset = Math.max(0, clip.sourceInSec);
+      const duration = Math.max(0, clip.durationSec);
+      node.start(when, offset, duration);
+      scheduledNodes.push(node);
     }
-    const node = ctx.createBufferSource();
-    node.buffer = buffer;
-    node.connect(ctx.destination);
-    const when = Math.max(0, clip.startSec);
-    const offset = Math.max(0, clip.sourceInSec);
-    const duration = Math.max(0, clip.durationSec);
-    node.start(when, offset, duration);
-    scheduledNodes++;
+    if (scheduledNodes.length === 0) return null;
+    return await ctx.startRendering();
+  } finally {
+    for (const node of scheduledNodes) {
+      node.disconnect();
+      node.buffer = null;
+    }
+    decoded.clear();
   }
-  if (scheduledNodes === 0) return null;
-  return ctx.startRendering();
 }
+var AAC_FRAME_SAMPLES = 1024;
+var MAX_AAC_QUEUE_SECONDS = 2;
 async function encodeAacTrack(audioBuffer, sink, bitrate) {
   if (typeof AudioEncoder === "undefined" || typeof AudioData === "undefined") {
     throw new Error("WebCodecs AudioEncoder is not available.");
@@ -219,34 +310,47 @@ async function encodeAacTrack(audioBuffer, sink, bitrate) {
     }
   });
   encoder.configure({ codec: "mp4a.40.2", sampleRate, numberOfChannels: channels, bitrate });
-  const FRAME = 1024;
   const total = audioBuffer.length;
+  const queueLimit = Math.max(
+    1,
+    Math.ceil(sampleRate * MAX_AAC_QUEUE_SECONDS / AAC_FRAME_SAMPLES)
+  );
   const channelData = [];
   for (let ch = 0; ch < channels; ch++) {
     channelData.push(audioBuffer.getChannelData(ch));
   }
-  for (let offset = 0; offset < total; offset += FRAME) {
-    if (encodeError) break;
-    const count = Math.min(FRAME, total - offset);
-    const planar = new Float32Array(count * channels);
-    for (let ch = 0; ch < channels; ch++) {
-      planar.set(channelData[ch].subarray(offset, offset + count), ch * count);
+  try {
+    for (let offset = 0; offset < total; offset += AAC_FRAME_SAMPLES) {
+      if (encodeError) throw encodeError;
+      if (encoder.encodeQueueSize >= queueLimit) {
+        await encoder.flush();
+        if (encodeError) throw encodeError;
+      }
+      const count = Math.min(AAC_FRAME_SAMPLES, total - offset);
+      const planar = new Float32Array(count * channels);
+      for (let ch = 0; ch < channels; ch++) {
+        planar.set(channelData[ch].subarray(offset, offset + count), ch * count);
+      }
+      const timestamp = Math.round(offset / sampleRate * 1e6);
+      const audioData = new AudioData({
+        format: "f32-planar",
+        sampleRate,
+        numberOfFrames: count,
+        numberOfChannels: channels,
+        timestamp,
+        data: planar
+      });
+      try {
+        encoder.encode(audioData);
+      } finally {
+        audioData.close();
+      }
     }
-    const timestamp = Math.round(offset / sampleRate * 1e6);
-    const audioData = new AudioData({
-      format: "f32-planar",
-      sampleRate,
-      numberOfFrames: count,
-      numberOfChannels: channels,
-      timestamp,
-      data: planar
-    });
-    encoder.encode(audioData);
-    audioData.close();
+    await encoder.flush();
+    if (encodeError) throw encodeError;
+  } finally {
+    if (encoder.state !== "closed") encoder.close();
   }
-  await encoder.flush();
-  encoder.close();
-  if (encodeError) throw encodeError;
 }
 function audioBufferToWav(buffer) {
   const channels = buffer.numberOfChannels;

package/dist/{chunk-MEPETH5V.js → chunk-5MFQMJ5Z.js}

@@ -1905,8 +1905,151 @@ ensureNotFinalized_fn = function() {
 };
 
 // src/mp4Mux.ts
+var DEFAULT_MP4_SPILL_THRESHOLD_BYTES = 32 * 1024 * 1024;
+var ChunkedMp4Output = class {
+  constructor(spillThresholdBytes = null) {
+    this.spillThresholdBytes = spillThresholdBytes;
+    this.writes = [];
+    this.spilled = [];
+    this.bufferedBytes = 0;
+    this.length = 0;
+  }
+  write(data, position) {
+    const owned = new Uint8Array(data);
+    const end = position + owned.byteLength;
+    if (position >= this.length) {
+      this.writes.push({ position, data: owned });
+      this.bufferedBytes += owned.byteLength;
+      this.length = end;
+      this.maybeSpill();
+      return;
+    }
+    const updated = [];
+    for (const existing of this.writes) {
+      const existingEnd = existing.position + existing.data.byteLength;
+      if (existingEnd <= position || existing.position >= end) {
+        updated.push(existing);
+        continue;
+      }
+      if (existing.position < position) {
+        updated.push({
+          position: existing.position,
+          data: existing.data.subarray(0, position - existing.position)
+        });
+      }
+      if (existingEnd > end) {
+        updated.push({
+          position: end,
+          data: existing.data.subarray(end - existing.position)
+        });
+      }
+    }
+    updated.push({ position, data: owned });
+    updated.sort((left, right) => left.position - right.position);
+    this.writes = updated;
+    this.bufferedBytes = updated.reduce((sum, write) => sum + write.data.byteLength, 0);
+    this.length = Math.max(this.length, end);
+    this.maybeSpill();
+  }
+  overlapsSpilled(write) {
+    const end = write.position + write.data.byteLength;
+    return this.spilled.some(
+      (part) => part.position < end && part.position + part.size > write.position
+    );
+  }
+  /**
+   * Consolidate buffered writes into Blob parts once they exceed the
+   * threshold. Writes overlapping an already-spilled region are patches over
+   * Blob bytes; they stay in memory (they are tiny) and win at assembly.
+   */
+  maybeSpill() {
+    if (this.spillThresholdBytes === null || this.bufferedBytes < this.spillThresholdBytes) return;
+    const spillable = this.writes.filter((write) => !this.overlapsSpilled(write)).sort((left, right) => left.position - right.position);
+    if (spillable.length === 0) return;
+    const keep = new Set(spillable);
+    let run = [];
+    const flushRun = () => {
+      if (run.length === 0) return;
+      const position = run[0].position;
+      const size = run.reduce((sum, write) => sum + write.data.byteLength, 0);
+      this.spilled.push({
+        position,
+        size,
+        blob: new Blob(run.map((write) => write.data))
+      });
+      run = [];
+    };
+    for (const write of spillable) {
+      const previous = run[run.length - 1];
+      if (previous && previous.position + previous.data.byteLength !== write.position) flushRun();
+      run.push(write);
+    }
+    flushRun();
+    this.spilled.sort((left, right) => left.position - right.position);
+    this.writes = this.writes.filter((write) => !keep.has(write));
+    this.bufferedBytes = this.writes.reduce((sum, write) => sum + write.data.byteLength, 0);
+  }
+  /** Regions in position order; in-memory writes take precedence over Blobs. */
+  assembleParts() {
+    const boundaries = /* @__PURE__ */ new Set([0, this.length]);
+    for (const write of this.writes) {
+      boundaries.add(write.position);
+      boundaries.add(write.position + write.data.byteLength);
+    }
+    for (const part of this.spilled) {
+      boundaries.add(part.position);
+      boundaries.add(part.position + part.size);
+    }
+    const sorted = [...boundaries].sort((left, right) => left - right);
+    const parts = [];
+    for (let i = 0; i + 1 < sorted.length; i++) {
+      const start = sorted[i];
+      const end = sorted[i + 1];
+      if (end <= start) continue;
+      const write = this.writes.find(
+        (candidate) => candidate.position <= start && candidate.position + candidate.data.byteLength >= end
+      );
+      if (write) {
+        parts.push(write.data.subarray(start - write.position, end - write.position));
+        continue;
+      }
+      const part = this.spilled.find(
+        (candidate) => candidate.position <= start && candidate.position + candidate.size >= end
+      );
+      if (part) {
+        parts.push(part.blob.slice(start - part.position, end - part.position));
+        continue;
+      }
+      parts.push(new Uint8Array(end - start));
+    }
+    return parts;
+  }
+  toArrayBuffer() {
+    if (this.spilled.length > 0) {
+      throw new Error("Spilled MP4 output can only finalize to a Blob");
+    }
+    const output = new Uint8Array(this.length);
+    for (const write of this.writes) output.set(write.data, write.position);
+    this.release();
+    return output.buffer;
+  }
+  toBlob() {
+    const blob = new Blob(this.assembleParts(), { type: "video/mp4" });
+    this.release();
+    return blob;
+  }
+  release() {
+    this.writes = [];
+    this.spilled = [];
+    this.bufferedBytes = 0;
+    this.length = 0;
+  }
+};
 function createMp4Muxer(options) {
-  const target = new ArrayBufferTarget();
+  const output = new ChunkedMp4Output(options.spillToBlobThresholdBytes ?? null);
+  const target = new StreamTarget({
+    onData: (data, position) => output.write(data, position)
+  });
   const muxer = new Muxer({
     target,
     video: {
@@ -1930,6 +2073,12 @@ function createMp4Muxer(options) {
     // releases the sample payload immediately.
     fastStart: false
   });
+  let finalized = false;
+  const finalizeMuxer = () => {
+    if (finalized) throw new Error("MP4 muxer already finalized");
+    muxer.finalize();
+    finalized = true;
+  };
   return {
     hasAudioTrack: options.audio !== void 0,
     addVideoChunk(chunk, meta) {
@@ -1945,8 +2094,12 @@ function createMp4Muxer(options) {
       muxer.addAudioChunkRaw(data, type, timestampMicros, durationMicros, meta);
     },
     finalize() {
-      muxer.finalize();
-      return target.buffer;
+      finalizeMuxer();
+      return output.toArrayBuffer();
+    },
+    finalizeBlob() {
+      finalizeMuxer();
+      return output.toBlob();
     }
   };
 }
@@ -1973,6 +2126,7 @@ function shouldEncodeFfmpegBatch(frameCount, byteLength, fps) {
 }
 
 export {
+  DEFAULT_MP4_SPILL_THRESHOLD_BYTES,
   createMp4Muxer,
   resolveWebCodecsQueueLimit,
   applyWebCodecsBackpressure,

package/dist/{chunk-ERG6OLLO.js → chunk-CRXJOZSH.js}

@@ -1,6 +1,6 @@
 import {
   useVideoExport
-} from "./chunk-GLOLS2CQ.js";
+} from "./chunk-U3RSDWQL.js";
 
 // src/VideoExportModal.tsx
 import { useState, useCallback, useId, useRef } from "react";
@@ -174,7 +174,7 @@ function VideoExportModal({
   const initialOutputFormat = defaultConfig?.outputFormat ?? "mp4";
   const [outputFormat, setOutputFormat] = useState(initialOutputFormat);
   const [quality, setQuality] = useState(defaultConfig?.quality ?? "normal");
-  const [fps, setFps] = useState(defaultConfig?.fps ?? (initialOutputFormat === "gif" ? 10 : 24));
+  const [fps, setFps] = useState(defaultConfig?.fps ?? (initialOutputFormat === "gif" ? 10 : 30));
   const [orientation, setOrientation] = useState(
     defaultConfig?.orientation ?? "landscape"
   );
@@ -251,7 +251,7 @@ function VideoExportModal({
       setAnimationsEnabled(false);
       setCaptionMode("standard");
     } else {
-      setFps(24);
+      setFps(30);
       setAnimationsEnabled(true);
       setCaptionMode("off");
     }