@bendyline/squisq-video 1.2.0 → 1.2.2

package/README.md

@@ -15,29 +15,36 @@ npm install @bendyline/squisq-video
 
 ## What's Inside
 
-| Module          | Description                                                            |
-| --------------- | ---------------------------------------------------------------------- |
-| **renderHtml**  | Generate self-contained HTML with embedded media for headless capture  |
-| **wasmEncoder** | Encode PNG frames + audio to MP4 using ffmpeg.wasm                     |
-| **types**       | Quality presets, orientation dimensions, and shared video export types |
+| Export                                                                                                          | Description                                                                                                     |
+| --------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| `generateRenderHtml(doc, options)`                                                                              | Self-contained HTML page with embedded media for headless frame capture                                         |
+| `framesToMp4Wasm(frames, audio, options)`                                                                       | Encode PNG frames (+ optional audio) to MP4 via ffmpeg.wasm                                                     |
+| `computeAudioTimeline(doc, coverPreRoll?)`                                                                      | Flatten a doc's narration + timed media into absolute-timed audio clips (browser export and CLI mix share this) |
+| `bitrateForQuality(quality, width, height)`                                                                     | Target H.264 bitrate (`w*h*bitsPerPixel`) — the single source of truth for WebCodecs bitrate                    |
+| `QUALITY_PRESETS`, `ORIENTATION_DIMENSIONS`, `resolveDimensions`                                                | Quality/dimension presets and helpers                                                                           |
+| `VideoExportOptions`, `VideoQuality`, `VideoOrientation`, `QualityPreset`, `EncoderResult`, `AudioTimelineClip` | Shared types                                                                                                    |
+| `fetchFile`                                                                                                     | Re-export of `@ffmpeg/util`'s `fetchFile` for preparing audio bytes                                             |
+
+This package is the shared foundation under [@bendyline/squisq-video-react](https://www.npmjs.com/package/@bendyline/squisq-video-react) (in-browser export UI) and [@bendyline/squisq-cli](https://www.npmjs.com/package/@bendyline/squisq-cli) (`squisq video`, which pairs the render HTML with Playwright capture and native ffmpeg encoding).
 
 ## Quick Start
 
 ### Generate Render HTML
 
-Create a self-contained HTML page that mounts a Squisq player with a seekable API — suitable for headless frame capture with Playwright or Puppeteer:
+Create a self-contained HTML page that mounts the standalone Squisq player in render mode, with all images and audio embedded as base64 data URIs. The page exposes `window.seekTo(time)` and `window.getDuration()` so a headless browser (Playwright, Puppeteer) can step through frames and screenshot each one:
 
 ```ts
 import { generateRenderHtml } from '@bendyline/squisq-video';
-
-const html = generateRenderHtml({
-  doc,
-  playerScript, // URL or inline script for squisq-player.global.js
-  images, // Map<string, ArrayBuffer> of embedded images
-  audio, // Map<string, ArrayBuffer> of audio segments
+import { PLAYER_BUNDLE } from '@bendyline/squisq-react/standalone-source';
+
+const html = generateRenderHtml(doc, {
+  playerScript: PLAYER_BUNDLE, // the IIFE player bundle source string
+  images, // Map<string, ArrayBuffer> — embedded as data URIs
+  audio, // Map<string, ArrayBuffer> — embedded as data URIs
+  width: 1920, // default 1920
+  height: 1080, // default 1080
+  captionStyle: 'standard', // 'standard' | 'social' — omit for no captions
 });
-
-// The rendered page exposes window.seekTo(time) and window.getDuration()
 ```
 
 ### Encode Frames to MP4
@@ -45,24 +52,42 @@ const html = generateRenderHtml({
 ```ts
 import { framesToMp4Wasm } from '@bendyline/squisq-video';
 
-const mp4Bytes = await framesToMp4Wasm({
-  frames, // Uint8Array[] of PNG frame data
-  audio, // optional audio ArrayBuffer
-  fps: 30,
-  width: 1920,
-  height: 1080,
-  quality: 'normal',
-  onProgress: (pct) => console.log(`${pct}% done`),
-});
+const { data, duration } = await framesToMp4Wasm(
+  frames, // Uint8Array[] — PNG frame bytes, in order
+  audioBytes, // Uint8Array | null — optional WAV/MP3/AAC track (muxed as AAC)
+  {
+    fps: 30, // default 30
+    quality: 'normal', // 'draft' | 'normal' | 'high' (default 'normal')
+    orientation: 'landscape', // 'landscape' | 'portrait' (default 'landscape')
+    // width / height override the orientation defaults
+    onProgress: (percent, phase) => console.log(`${phase}: ${percent}%`),
+  },
+);
+// data: Uint8Array of MP4 bytes; duration: seconds (frames.length / fps)
+```
+
+Encoding is H.264 (`libx264`, `yuv420p`) with optional AAC audio; frames are scaled/padded to the target dimensions preserving aspect ratio. ffmpeg.wasm needs `SharedArrayBuffer` — in browsers that means COOP/COEP headers; Node 18+ works out of the box.
+
+### Schedule a Doc's Audio
+
+`computeAudioTimeline(doc, coverPreRoll?)` turns a doc's narration segments and timed media clips into a flat list of absolute-timed `AudioTimelineClip`s. It's pure and Node-testable, and is the single source of truth both the browser MP4 export and the CLI mix path use to place audio (so the two never drift). Narration segments are laid sequentially; timed media clips are placed at their absolute positions; every start is shifted by `coverPreRoll` (default 0) to stay in sync with a silent cover pre-roll.
+
+```ts
+import { computeAudioTimeline } from '@bendyline/squisq-video';
+
+const clips = computeAudioTimeline(doc, 2); // [{ src, startSec, sourceInSec, durationSec }, …]
 ```
 
 ## Quality Presets
 
-| Preset   | CRF | Speed     | Use Case               |
-| -------- | --- | --------- | ---------------------- |
-| `draft`  | 28  | ultrafast | Quick previews         |
-| `normal` | 23  | medium    | General-purpose export |
-| `high`   | 18  | slow      | Final output           |
+Each `QualityPreset` also carries `bitsPerPixel` (for WebCodecs bitrate
+targeting via `bitrateForQuality`) and `audioBitrate` (target AAC bits/sec):
+
+| Preset   | FFmpeg preset | CRF | bits/pixel | AAC bitrate | Use Case               |
+| -------- | ------------- | --- | ---------- | ----------- | ---------------------- |
+| `draft`  | ultrafast     | 28  | 2          | 96 kbps     | Quick previews         |
+| `normal` | medium        | 23  | 4          | 128 kbps    | General-purpose export |
+| `high`   | slow          | 18  | 8          | 192 kbps    | Final output           |
 
 ## Orientation Dimensions
 
@@ -71,12 +96,16 @@ const mp4Bytes = await framesToMp4Wasm({
 | `landscape` | 1920  | 1080   |
 | `portrait`  | 1080  | 1920   |
 
+`resolveDimensions(options)` applies these defaults, honoring explicit `width`/`height` overrides.
+
+See the full [API Reference](../../docs/API.md#bendylinesquisq-video) for all types.
+
 ## Related Packages
 
 | Package                                                                                      | Description                                     |
 | -------------------------------------------------------------------------------------------- | ----------------------------------------------- |
 | [@bendyline/squisq](https://www.npmjs.com/package/@bendyline/squisq)                         | Headless core — schemas, templates, markdown    |
-| [@bendyline/squisq-react](https://www.npmjs.com/package/@bendyline/squisq-react)             | React components for rendering docs             |
+| [@bendyline/squisq-react](https://www.npmjs.com/package/@bendyline/squisq-react)             | React components + standalone player bundle     |
 | [@bendyline/squisq-video-react](https://www.npmjs.com/package/@bendyline/squisq-video-react) | React UI for in-browser video export            |
 | [@bendyline/squisq-cli](https://www.npmjs.com/package/@bendyline/squisq-cli)                 | CLI for document conversion and video rendering |
 

package/dist/index.d.ts

@@ -24,9 +24,29 @@ interface QualityPreset {
     preset: string;
     /** FFmpeg -crf value (lower = higher quality, 0-51 range) */
     crf: number;
+    /**
+     * Bits per pixel for WebCodecs bitrate targeting.
+     * Target bitrate = width * height * bitsPerPixel (see {@link bitrateForQuality}).
+     * These values reproduce the historical per-quality formula exactly:
+     * the old code used a `width * height * 4` baseline, halved for draft and
+     * doubled for high — i.e. 2 / 4 / 8 bits per pixel.
+     */
+    bitsPerPixel: number;
+    /** Target AAC audio bitrate in bits/sec for muxed audio tracks. */
+    audioBitrate: number;
 }
 /** Quality preset lookup — shared between wasm and native encoders. */
 declare const QUALITY_PRESETS: Record<VideoQuality, QualityPreset>;
+/**
+ * Target H.264 bitrate (bits/sec) for a given quality at a given resolution.
+ *
+ * Computes `width * height * preset.bitsPerPixel`. With bitsPerPixel of
+ * 2 / 4 / 8 (draft / normal / high) this is numerically identical to the
+ * legacy formula (`width * height * 4` baseline, ×0.5 for draft, ×2 for high)
+ * that previously lived in both the main-thread and worker WebCodecs encoders.
+ * The single source of truth now lives here so every encode path agrees.
+ */
+declare function bitrateForQuality(q: VideoQuality, width: number, height: number): number;
 /** Viewport dimensions for each orientation. */
 declare const ORIENTATION_DIMENSIONS: Record<VideoOrientation, {
     width: number;
@@ -66,6 +86,49 @@ declare function resolveDimensions(options: VideoExportOptions): {
     height: number;
 };
 
+/**
+ * audioTimeline — Pure scheduling of a doc's audio onto the export timeline.
+ *
+ * Browser-pure and Node-testable: turns a {@link Doc} into a flat list of
+ * absolute-timed {@link AudioTimelineClip}s. This is the single source of
+ * truth the browser MP4 export uses to place audio, and it deliberately
+ * replicates the exact schedule math the CLI mix path uses so both agree:
+ *
+ *  - Narration segments (`doc.audio.segments[]`) are laid **sequentially**,
+ *    each starting where the previous one ended — mirroring the CLI, which
+ *    concatenates the segment files in order.
+ *  - Timed media clips (`block.media` + `doc.documentMedia`) are placed at
+ *    their **absolute** doc-timeline positions via the shared
+ *    `resolveMediaSchedule()` helper (the same one the CLI calls), honouring
+ *    each clip's trim window (`sourceIn` / `absoluteEnd - absoluteStart`).
+ *  - Every start time is shifted by `coverPreRoll` so a cover pre-roll padding
+ *    (silent leading frames) keeps audio in sync.
+ */
+
+/** One audio source placed on the absolute export timeline. */
+interface AudioTimelineClip {
+    /** Source path (mp3/webm/mp4/…), relative to the doc's media dir. */
+    src: string;
+    /** Absolute second on the export timeline where this clip starts. */
+    startSec: number;
+    /** In-point within the source file to begin playback from. */
+    sourceInSec: number;
+    /** Played length in seconds (the trimmed window of the source). */
+    durationSec: number;
+}
+/**
+ * Flatten a doc's narration + timed-media audio into absolute-timed clips.
+ *
+ * Pure — depends only on `doc` (and reuses `resolveMediaSchedule` from core so
+ * the browser export and the CLI mix never drift). Returns `[]` for a doc with
+ * no audio at all.
+ *
+ * @param doc - The document to schedule audio for.
+ * @param coverPreRoll - Leading silent padding (seconds) added ahead of every
+ *   clip, matching the cover-slide pre-roll frames. Default 0.
+ */
+declare function computeAudioTimeline(doc: Doc, coverPreRoll?: number): AudioTimelineClip[];
+
 /**
  * Render HTML Generation for Video Frame Capture
  *
@@ -111,6 +174,29 @@ interface RenderHtmlOptions {
  */
 declare function generateRenderHtml(doc: Doc, options: RenderHtmlOptions): string;
 
+/**
+ * FFmpeg argument builders — the single source of truth for translating a
+ * {@link VideoQuality} into ffmpeg CLI flags. Shared verbatim by every
+ * ffmpeg-based encode path: the wasm encoder ({@link ./wasmEncoder}), the
+ * video-react fallback worker, and the CLI native encoder. Deriving these
+ * from {@link QUALITY_PRESETS} keeps the browser and CLI byte-for-byte aligned.
+ *
+ * Pure, dependency-free, and unit-testable in isolation (the actual ffmpeg
+ * invocations live behind wasm/child-process boundaries that are awkward to
+ * exercise directly).
+ */
+
+/**
+ * H.264 speed/quality flags (`-preset`, `-crf`) for a quality level.
+ * @example ffmpegVideoQualityArgs('high') // ['-preset', 'slow', '-crf', '18']
+ */
+declare function ffmpegVideoQualityArgs(quality: VideoQuality): string[];
+/**
+ * AAC audio-bitrate flag value in ffmpeg's `k` shorthand for a quality level.
+ * @example audioBitrateArg('high') // '192k'
+ */
+declare function audioBitrateArg(quality: VideoQuality): string;
+
 /**
  * WASM Video Encoder
  *
@@ -131,4 +217,4 @@ declare function generateRenderHtml(doc: Doc, options: RenderHtmlOptions): strin
  */
 declare function framesToMp4Wasm(frames: Uint8Array[], audio: Uint8Array | null, options?: VideoExportOptions): Promise<EncoderResult>;
 
-export { type EncoderResult, ORIENTATION_DIMENSIONS, QUALITY_PRESETS, type QualityPreset, type RenderHtmlOptions, type VideoExportOptions, type VideoOrientation, type VideoQuality, framesToMp4Wasm, generateRenderHtml, resolveDimensions };
+export { type AudioTimelineClip, type EncoderResult, ORIENTATION_DIMENSIONS, QUALITY_PRESETS, type QualityPreset, type RenderHtmlOptions, type VideoExportOptions, type VideoOrientation, type VideoQuality, audioBitrateArg, bitrateForQuality, computeAudioTimeline, ffmpegVideoQualityArgs, framesToMp4Wasm, generateRenderHtml, resolveDimensions };

package/dist/index.js

@@ -1,9 +1,13 @@
 // src/types.ts
 var QUALITY_PRESETS = {
-  draft: { preset: "ultrafast", crf: 28 },
-  normal: { preset: "medium", crf: 23 },
-  high: { preset: "slow", crf: 18 }
+  draft: { preset: "ultrafast", crf: 28, bitsPerPixel: 2, audioBitrate: 96e3 },
+  normal: { preset: "medium", crf: 23, bitsPerPixel: 4, audioBitrate: 128e3 },
+  high: { preset: "slow", crf: 18, bitsPerPixel: 8, audioBitrate: 192e3 }
 };
+function bitrateForQuality(q, width, height) {
+  const preset = QUALITY_PRESETS[q] ?? QUALITY_PRESETS.normal;
+  return Math.round(width * height * preset.bitsPerPixel);
+}
 var ORIENTATION_DIMENSIONS = {
   landscape: { width: 1920, height: 1080 },
   portrait: { width: 1080, height: 1920 }
@@ -17,6 +21,33 @@ function resolveDimensions(options) {
   };
 }
 
+// src/audioTimeline.ts
+import { resolveMediaSchedule } from "@bendyline/squisq/schemas";
+function computeAudioTimeline(doc, coverPreRoll = 0) {
+  const preRoll = coverPreRoll > 0 ? coverPreRoll : 0;
+  const clips = [];
+  let cursor = 0;
+  for (const seg of doc.audio?.segments ?? []) {
+    const durationSec = Math.max(0, seg.duration);
+    if (durationSec > 0 && seg.src) {
+      clips.push({ src: seg.src, startSec: cursor + preRoll, sourceInSec: 0, durationSec });
+    }
+    cursor += durationSec;
+  }
+  for (const clip of resolveMediaSchedule(doc)) {
+    if (clip.kind !== "audio") continue;
+    const durationSec = Math.max(0, clip.absoluteEnd - clip.absoluteStart);
+    if (durationSec <= 0 || !clip.src) continue;
+    clips.push({
+      src: clip.src,
+      startSec: clip.absoluteStart + preRoll,
+      sourceInSec: clip.sourceIn,
+      durationSec
+    });
+  }
+  return clips;
+}
+
 // src/renderHtml.ts
 var MIME_MAP = {
   jpg: "image/jpeg",
@@ -105,6 +136,16 @@ html,body{margin:0;padding:0;width:${width}px;height:${height}px;overflow:hidden
 </html>`;
 }
 
+// src/ffmpegArgs.ts
+function ffmpegVideoQualityArgs(quality) {
+  const preset = QUALITY_PRESETS[quality] ?? QUALITY_PRESETS.normal;
+  return ["-preset", preset.preset, "-crf", String(preset.crf)];
+}
+function audioBitrateArg(quality) {
+  const preset = QUALITY_PRESETS[quality] ?? QUALITY_PRESETS.normal;
+  return `${preset.audioBitrate / 1e3}k`;
+}
+
 // src/wasmEncoder.ts
 import { FFmpeg } from "@ffmpeg/ffmpeg";
 import { fetchFile } from "@ffmpeg/util";
@@ -112,7 +153,6 @@ async function framesToMp4Wasm(frames, audio, options = {}) {
   const fps = options.fps ?? 30;
   const quality = options.quality ?? "normal";
   const { width, height } = resolveDimensions(options);
-  const preset = QUALITY_PRESETS[quality];
   const onProgress = options.onProgress;
   if (frames.length === 0) {
     throw new Error("No frames provided for encoding");
@@ -147,17 +187,14 @@ async function framesToMp4Wasm(frames, audio, options = {}) {
   args.push(
     "-c:v",
     "libx264",
-    "-preset",
-    preset.preset,
-    "-crf",
-    String(preset.crf),
+    ...ffmpegVideoQualityArgs(quality),
     "-pix_fmt",
     "yuv420p",
     "-vf",
     `scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2`
   );
   if (audio) {
-    args.push("-c:a", "aac", "-b:a", "128k", "-shortest");
+    args.push("-c:a", "aac", "-b:a", audioBitrateArg(quality), "-shortest");
   }
   args.push("output.mp4");
   await ffmpeg.exec(args);
@@ -179,7 +216,11 @@ async function framesToMp4Wasm(frames, audio, options = {}) {
 export {
   ORIENTATION_DIMENSIONS,
   QUALITY_PRESETS,
+  audioBitrateArg,
+  bitrateForQuality,
+  computeAudioTimeline,
   fetchFile,
+  ffmpegVideoQualityArgs,
   framesToMp4Wasm,
   generateRenderHtml,
   resolveDimensions

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts","../src/renderHtml.ts","../src/wasmEncoder.ts"],"sourcesContent":["/**\n * Video Export Types\n *\n * Shared type definitions for video encoding and render HTML generation.\n * Used by both the browser-based encoder and the CLI native encoder.\n */\n\n/**\n * Video quality preset.\n * Controls the H.264 encoding speed/quality trade-off and constant rate factor.\n *\n * - draft:  ultrafast preset, CRF 28 — fast encode, lower quality (~1-2 Mbps)\n * - normal: medium preset, CRF 23 — balanced (~3-5 Mbps)\n * - high:   slow preset, CRF 18 — best quality, slowest (~8-12 Mbps)\n */\nexport type VideoQuality = 'draft' | 'normal' | 'high';\n\n/** Viewport orientation for video output. */\nexport type VideoOrientation = 'landscape' | 'portrait';\n\n/** Encoding preset parameters mapped from VideoQuality. */\nexport interface QualityPreset {\n  /** FFmpeg -preset value (ultrafast, medium, slow) */\n  preset: string;\n  /** FFmpeg -crf value (lower = higher quality, 0-51 range) */\n  crf: number;\n}\n\n/** Quality preset lookup — shared between wasm and native encoders. */\nexport const QUALITY_PRESETS: Record<VideoQuality, QualityPreset> = {\n  draft: { preset: 'ultrafast', crf: 28 },\n  normal: { preset: 'medium', crf: 23 },\n  high: { preset: 'slow', crf: 18 },\n};\n\n/** Viewport dimensions for each orientation. */\nexport const ORIENTATION_DIMENSIONS: Record<VideoOrientation, { width: number; height: number }> = {\n  landscape: { width: 1920, height: 1080 },\n  portrait: { width: 1080, height: 1920 },\n};\n\n/** Options for video export encoding. */\nexport interface VideoExportOptions {\n  /** Frames per second (default: 30) */\n  fps?: number;\n  /** Video width in pixels (default: based on orientation) */\n  width?: number;\n  /** Video height in pixels (default: based on orientation) */\n  height?: number;\n  /** Encoding quality preset (default: 'normal') */\n  quality?: VideoQuality;\n  /** Viewport orientation (default: 'landscape') */\n  orientation?: VideoOrientation;\n  /**\n   * Progress callback. Called during encoding with completion percentage and phase description.\n   * @param percent - 0-100 completion percentage\n   * @param phase - Human-readable description of current phase (e.g., 'encoding', 'muxing')\n   */\n  onProgress?: (percent: number, phase: string) => void;\n}\n\n/** Result from the wasm encoder. */\nexport interface EncoderResult {\n  /** MP4 file bytes */\n  data: Uint8Array;\n  /** Video duration in seconds */\n  duration: number;\n}\n\n/**\n * Resolve dimensions from options, applying orientation defaults.\n */\nexport function resolveDimensions(options: VideoExportOptions): {\n  width: number;\n  height: number;\n} {\n  const orientation = options.orientation ?? 'landscape';\n  const defaults = ORIENTATION_DIMENSIONS[orientation];\n  return {\n    width: options.width ?? defaults.width,\n    height: options.height ?? defaults.height,\n  };\n}\n","/**\n * Render HTML Generation for Video Frame Capture\n *\n * Generates a self-contained HTML document that loads the SquisqPlayer standalone\n * bundle in renderMode, embedding all images and audio as base64 data URIs.\n *\n * The generated page exposes `window.seekTo(time)`, `window.getDuration()`, etc.\n * via the SquisqRenderAPI, enabling Playwright (or any headless browser) to step\n * through frames and capture screenshots.\n *\n * Browser-pure: uses only btoa() and Uint8Array — no Node.js APIs.\n */\n\nimport type { Doc } from '@bendyline/squisq/schemas';\n\n// ── Types ──────────────────────────────────────────────────────────\n\nexport interface RenderHtmlOptions {\n  /** The IIFE player bundle source code (from PLAYER_BUNDLE) */\n  playerScript: string;\n\n  /**\n   * Map of relative image paths (as they appear in the Doc) to binary data.\n   * Converted to base64 data URIs and embedded in the HTML.\n   */\n  images?: Map<string, ArrayBuffer>;\n\n  /**\n   * Map of audio segment names/paths to binary audio data.\n   * Converted to base64 data URIs and embedded in the HTML.\n   */\n  audio?: Map<string, ArrayBuffer>;\n\n  /** Viewport width in CSS pixels (default: 1920) */\n  width?: number;\n\n  /** Viewport height in CSS pixels (default: 1080) */\n  height?: number;\n\n  /** Caption style for the rendered video. Omit for no captions. */\n  captionStyle?: 'standard' | 'social';\n}\n\n// ── MIME Detection ─────────────────────────────────────────────────\n\nconst MIME_MAP: Record<string, string> = {\n  jpg: 'image/jpeg',\n  jpeg: 'image/jpeg',\n  png: 'image/png',\n  gif: 'image/gif',\n  webp: 'image/webp',\n  svg: 'image/svg+xml',\n  bmp: 'image/bmp',\n  avif: 'image/avif',\n  mp3: 'audio/mpeg',\n  wav: 'audio/wav',\n  ogg: 'audio/ogg',\n  mp4: 'video/mp4',\n  webm: 'video/webm',\n};\n\nfunction inferMimeType(filename: string): string {\n  const ext = filename.split('.').pop()?.toLowerCase() ?? '';\n  return MIME_MAP[ext] ?? 'application/octet-stream';\n}\n\n// ── Base64 Encoding (browser-pure) ────────────────────────────────\n\n/**\n * Convert an ArrayBuffer to a base64 data URI.\n * Uses only standard Web APIs (Uint8Array + btoa).\n */\nfunction arrayBufferToDataUrl(buffer: ArrayBuffer, mimeType: string): string {\n  const bytes = new Uint8Array(buffer);\n  let binary = '';\n  for (let i = 0; i < bytes.length; i++) {\n    binary += String.fromCharCode(bytes[i]);\n  }\n  return `data:${mimeType};base64,${btoa(binary)}`;\n}\n\n// ── Escaping ───────────────────────────────────────────────────────\n\n/**\n * Prevent `</script>` from prematurely closing the script tag.\n */\nfunction escapeForScript(str: string): string {\n  return str.replace(/<\\/(script)/gi, '<\\\\/$1');\n}\n\n/** Escape HTML special characters. */\nfunction escapeHtml(str: string): string {\n  return str\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n    .replace(/\"/g, '&quot;');\n}\n\n// ── HTML Generation ────────────────────────────────────────────────\n\n/**\n * Generate a self-contained HTML document for headless video frame capture.\n *\n * The page mounts the SquisqPlayer in renderMode, which exposes the\n * SquisqRenderAPI on `window` (seekTo, getDuration, getCaptions, etc.).\n *\n * @param doc - The Doc to render\n * @param options - Render HTML options including player script and media\n * @returns Complete HTML string ready to be loaded in a headless browser\n */\nexport function generateRenderHtml(doc: Doc, options: RenderHtmlOptions): string {\n  const { playerScript, images, audio, width = 1920, height = 1080, captionStyle } = options;\n\n  // Build base64 image map\n  const imageMap: Record<string, string> = {};\n  if (images) {\n    for (const [path, buffer] of images.entries()) {\n      imageMap[path] = arrayBufferToDataUrl(buffer, inferMimeType(path));\n    }\n  }\n\n  // Build base64 audio map\n  const audioMap: Record<string, string> = {};\n  let hasAudio = false;\n  if (audio) {\n    for (const [name, buffer] of audio.entries()) {\n      audioMap[name] = arrayBufferToDataUrl(buffer, inferMimeType(name));\n      hasAudio = true;\n    }\n  }\n\n  const docJson = escapeForScript(JSON.stringify(doc));\n  const imageMapJson = escapeForScript(JSON.stringify(imageMap));\n  const audioMapJson = hasAudio ? escapeForScript(JSON.stringify(audioMap)) : 'null';\n\n  return `<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n<meta charset=\"UTF-8\">\n<meta name=\"viewport\" content=\"width=${width}, height=${height}\">\n<title>${escapeHtml('Squisq Video Render')}</title>\n<style>\n*,*::before,*::after{box-sizing:border-box}\nhtml,body{margin:0;padding:0;width:${width}px;height:${height}px;overflow:hidden;background:#000}\n#squisq-root{width:${width}px;height:${height}px;display:flex;align-items:center;justify-content:center}\n</style>\n</head>\n<body>\n<div id=\"squisq-root\"></div>\n<script>${escapeForScript(playerScript)}</script>\n<script>\n(function(){\n  var doc = JSON.parse(${JSON.stringify(docJson)});\n  var images = JSON.parse(${JSON.stringify(imageMapJson)});\n  var audio = ${audioMapJson === 'null' ? 'null' : 'JSON.parse(' + JSON.stringify(audioMapJson) + ')'};\n  SquisqPlayer.mount(document.getElementById(\"squisq-root\"), doc, {\n    mode: \"slideshow\",\n    images: images,\n    audio: audio,\n    autoPlay: false,\n    basePath: \".\",\n    renderMode: true${captionStyle ? `,\\n    captionStyle: ${JSON.stringify(captionStyle)}` : ''}\n  });\n})();\n</script>\n</body>\n</html>`;\n}\n","/**\n * WASM Video Encoder\n *\n * Encodes PNG frame screenshots into an MP4 video using ffmpeg.wasm.\n * Browser-pure — no Node.js APIs. Works in any environment with SharedArrayBuffer\n * support (browsers with COOP/COEP headers, or Node 18+).\n *\n * Uses @ffmpeg/ffmpeg for H.264 encoding and optional AAC audio muxing.\n */\n\nimport { FFmpeg } from '@ffmpeg/ffmpeg';\nimport { fetchFile } from '@ffmpeg/util';\n\nimport type { VideoExportOptions, EncoderResult } from './types.js';\nimport { QUALITY_PRESETS, resolveDimensions } from './types.js';\n\n/**\n * Encode an array of PNG frame screenshots into an MP4 video.\n *\n * @param frames - Array of PNG image bytes (one per frame, in order)\n * @param audio - Optional WAV/MP3/AAC audio bytes to mux into the video\n * @param options - Encoding options (fps, quality, dimensions, progress)\n * @returns Encoded MP4 data and duration metadata\n */\nexport async function framesToMp4Wasm(\n  frames: Uint8Array[],\n  audio: Uint8Array | null,\n  options: VideoExportOptions = {},\n): Promise<EncoderResult> {\n  const fps = options.fps ?? 30;\n  const quality = options.quality ?? 'normal';\n  const { width, height } = resolveDimensions(options);\n  const preset = QUALITY_PRESETS[quality];\n  const onProgress = options.onProgress;\n\n  if (frames.length === 0) {\n    throw new Error('No frames provided for encoding');\n  }\n\n  const duration = frames.length / fps;\n\n  // Initialize ffmpeg.wasm\n  const ffmpeg = new FFmpeg();\n\n  ffmpeg.on('progress', ({ progress }) => {\n    if (onProgress) {\n      const percent = Math.round(progress * 100);\n      onProgress(Math.min(percent, 99), 'encoding');\n    }\n  });\n\n  await ffmpeg.load();\n\n  onProgress?.(0, 'writing frames');\n\n  // Write frame PNGs to virtual filesystem\n  const padLen = String(frames.length).length;\n  for (let i = 0; i < frames.length; i++) {\n    const name = `frame-${String(i + 1).padStart(padLen, '0')}.png`;\n    await ffmpeg.writeFile(name, frames[i]);\n\n    // Report frame-write progress (0-40% of total)\n    if (onProgress && i % 10 === 0) {\n      onProgress(Math.round((i / frames.length) * 40), 'writing frames');\n    }\n  }\n\n  // Write audio if provided\n  if (audio) {\n    await ffmpeg.writeFile('audio-input', audio);\n  }\n\n  onProgress?.(40, 'encoding');\n\n  // Build ffmpeg command\n  const padPattern = `frame-%0${padLen}d.png`;\n  const args = ['-y', '-framerate', String(fps), '-i', padPattern];\n\n  // Add audio input\n  if (audio) {\n    args.push('-i', 'audio-input');\n  }\n\n  // Video encoding settings\n  args.push(\n    '-c:v',\n    'libx264',\n    '-preset',\n    preset.preset,\n    '-crf',\n    String(preset.crf),\n    '-pix_fmt',\n    'yuv420p',\n    '-vf',\n    `scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2`,\n  );\n\n  // Audio encoding\n  if (audio) {\n    args.push('-c:a', 'aac', '-b:a', '128k', '-shortest');\n  }\n\n  args.push('output.mp4');\n\n  // Run encoding\n  await ffmpeg.exec(args);\n\n  onProgress?.(95, 'reading output');\n\n  // Read the output file\n  const data = await ffmpeg.readFile('output.mp4');\n\n  // Cleanup virtual filesystem\n  for (let i = 0; i < frames.length; i++) {\n    const name = `frame-${String(i + 1).padStart(padLen, '0')}.png`;\n    await ffmpeg.deleteFile(name);\n  }\n  if (audio) {\n    await ffmpeg.deleteFile('audio-input');\n  }\n  await ffmpeg.deleteFile('output.mp4');\n\n  ffmpeg.terminate();\n\n  onProgress?.(100, 'done');\n\n  // ffmpeg.readFile returns Uint8Array for binary files\n  const outputData = data instanceof Uint8Array ? data : new TextEncoder().encode(data as string);\n\n  return { data: outputData, duration };\n}\n\n// Re-export fetchFile for convenience — consumers may need it to prepare audio bytes\nexport { fetchFile };\n"],"mappings":";AA6BO,IAAM,kBAAuD;AAAA,EAClE,OAAO,EAAE,QAAQ,aAAa,KAAK,GAAG;AAAA,EACtC,QAAQ,EAAE,QAAQ,UAAU,KAAK,GAAG;AAAA,EACpC,MAAM,EAAE,QAAQ,QAAQ,KAAK,GAAG;AAClC;AAGO,IAAM,yBAAsF;AAAA,EACjG,WAAW,EAAE,OAAO,MAAM,QAAQ,KAAK;AAAA,EACvC,UAAU,EAAE,OAAO,MAAM,QAAQ,KAAK;AACxC;AAiCO,SAAS,kBAAkB,SAGhC;AACA,QAAM,cAAc,QAAQ,eAAe;AAC3C,QAAM,WAAW,uBAAuB,WAAW;AACnD,SAAO;AAAA,IACL,OAAO,QAAQ,SAAS,SAAS;AAAA,IACjC,QAAQ,QAAQ,UAAU,SAAS;AAAA,EACrC;AACF;;;ACrCA,IAAM,WAAmC;AAAA,EACvC,KAAK;AAAA,EACL,MAAM;AAAA,EACN,KAAK;AAAA,EACL,KAAK;AAAA,EACL,MAAM;AAAA,EACN,KAAK;AAAA,EACL,KAAK;AAAA,EACL,MAAM;AAAA,EACN,KAAK;AAAA,EACL,KAAK;AAAA,EACL,KAAK;AAAA,EACL,KAAK;AAAA,EACL,MAAM;AACR;AAEA,SAAS,cAAc,UAA0B;AAC/C,QAAM,MAAM,SAAS,MAAM,GAAG,EAAE,IAAI,GAAG,YAAY,KAAK;AACxD,SAAO,SAAS,GAAG,KAAK;AAC1B;AAQA,SAAS,qBAAqB,QAAqB,UAA0B;AAC3E,QAAM,QAAQ,IAAI,WAAW,MAAM;AACnC,MAAI,SAAS;AACb,WAAS,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;AACrC,cAAU,OAAO,aAAa,MAAM,CAAC,CAAC;AAAA,EACxC;AACA,SAAO,QAAQ,QAAQ,WAAW,KAAK,MAAM,CAAC;AAChD;AAOA,SAAS,gBAAgB,KAAqB;AAC5C,SAAO,IAAI,QAAQ,iBAAiB,QAAQ;AAC9C;AAGA,SAAS,WAAW,KAAqB;AACvC,SAAO,IACJ,QAAQ,MAAM,OAAO,EACrB,QAAQ,MAAM,MAAM,EACpB,QAAQ,MAAM,MAAM,EACpB,QAAQ,MAAM,QAAQ;AAC3B;AAcO,SAAS,mBAAmB,KAAU,SAAoC;AAC/E,QAAM,EAAE,cAAc,QAAQ,OAAO,QAAQ,MAAM,SAAS,MAAM,aAAa,IAAI;AAGnF,QAAM,WAAmC,CAAC;AAC1C,MAAI,QAAQ;AACV,eAAW,CAAC,MAAM,MAAM,KAAK,OAAO,QAAQ,GAAG;AAC7C,eAAS,IAAI,IAAI,qBAAqB,QAAQ,cAAc,IAAI,CAAC;AAAA,IACnE;AAAA,EACF;AAGA,QAAM,WAAmC,CAAC;AAC1C,MAAI,WAAW;AACf,MAAI,OAAO;AACT,eAAW,CAAC,MAAM,MAAM,KAAK,MAAM,QAAQ,GAAG;AAC5C,eAAS,IAAI,IAAI,qBAAqB,QAAQ,cAAc,IAAI,CAAC;AACjE,iBAAW;AAAA,IACb;AAAA,EACF;AAEA,QAAM,UAAU,gBAAgB,KAAK,UAAU,GAAG,CAAC;AACnD,QAAM,eAAe,gBAAgB,KAAK,UAAU,QAAQ,CAAC;AAC7D,QAAM,eAAe,WAAW,gBAAgB,KAAK,UAAU,QAAQ,CAAC,IAAI;AAE5E,SAAO;AAAA;AAAA;AAAA;AAAA,uCAI8B,KAAK,YAAY,MAAM;AAAA,SACrD,WAAW,qBAAqB,CAAC;AAAA;AAAA;AAAA,qCAGL,KAAK,aAAa,MAAM;AAAA,qBACxC,KAAK,aAAa,MAAM;AAAA;AAAA;AAAA;AAAA;AAAA,UAKnC,gBAAgB,YAAY,CAAC;AAAA;AAAA;AAAA,yBAGd,KAAK,UAAU,OAAO,CAAC;AAAA,4BACpB,KAAK,UAAU,YAAY,CAAC;AAAA,gBACxC,iBAAiB,SAAS,SAAS,gBAAgB,KAAK,UAAU,YAAY,IAAI,GAAG;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,sBAO/E,eAAe;AAAA,oBAAwB,KAAK,UAAU,YAAY,CAAC,KAAK,EAAE;AAAA;AAAA;AAAA;AAAA;AAAA;AAMhG;;;AC9JA,SAAS,cAAc;AACvB,SAAS,iBAAiB;AAa1B,eAAsB,gBACpB,QACA,OACA,UAA8B,CAAC,GACP;AACxB,QAAM,MAAM,QAAQ,OAAO;AAC3B,QAAM,UAAU,QAAQ,WAAW;AACnC,QAAM,EAAE,OAAO,OAAO,IAAI,kBAAkB,OAAO;AACnD,QAAM,SAAS,gBAAgB,OAAO;AACtC,QAAM,aAAa,QAAQ;AAE3B,MAAI,OAAO,WAAW,GAAG;AACvB,UAAM,IAAI,MAAM,iCAAiC;AAAA,EACnD;AAEA,QAAM,WAAW,OAAO,SAAS;AAGjC,QAAM,SAAS,IAAI,OAAO;AAE1B,SAAO,GAAG,YAAY,CAAC,EAAE,SAAS,MAAM;AACtC,QAAI,YAAY;AACd,YAAM,UAAU,KAAK,MAAM,WAAW,GAAG;AACzC,iBAAW,KAAK,IAAI,SAAS,EAAE,GAAG,UAAU;AAAA,IAC9C;AAAA,EACF,CAAC;AAED,QAAM,OAAO,KAAK;AAElB,eAAa,GAAG,gBAAgB;AAGhC,QAAM,SAAS,OAAO,OAAO,MAAM,EAAE;AACrC,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;AACtC,UAAM,OAAO,SAAS,OAAO,IAAI,CAAC,EAAE,SAAS,QAAQ,GAAG,CAAC;AACzD,UAAM,OAAO,UAAU,MAAM,OAAO,CAAC,CAAC;AAGtC,QAAI,cAAc,IAAI,OAAO,GAAG;AAC9B,iBAAW,KAAK,MAAO,IAAI,OAAO,SAAU,EAAE,GAAG,gBAAgB;AAAA,IACnE;AAAA,EACF;AAGA,MAAI,OAAO;AACT,UAAM,OAAO,UAAU,eAAe,KAAK;AAAA,EAC7C;AAEA,eAAa,IAAI,UAAU;AAG3B,QAAM,aAAa,WAAW,MAAM;AACpC,QAAM,OAAO,CAAC,MAAM,cAAc,OAAO,GAAG,GAAG,MAAM,UAAU;AAG/D,MAAI,OAAO;AACT,SAAK,KAAK,MAAM,aAAa;AAAA,EAC/B;AAGA,OAAK;AAAA,IACH;AAAA,IACA;AAAA,IACA;AAAA,IACA,OAAO;AAAA,IACP;AAAA,IACA,OAAO,OAAO,GAAG;AAAA,IACjB;AAAA,IACA;AAAA,IACA;AAAA,IACA,SAAS,KAAK,IAAI,MAAM,6CAA6C,KAAK,IAAI,MAAM;AAAA,EACtF;AAGA,MAAI,OAAO;AACT,SAAK,KAAK,QAAQ,OAAO,QAAQ,QAAQ,WAAW;AAAA,EACtD;AAEA,OAAK,KAAK,YAAY;AAGtB,QAAM,OAAO,KAAK,IAAI;AAEtB,eAAa,IAAI,gBAAgB;AAGjC,QAAM,OAAO,MAAM,OAAO,SAAS,YAAY;AAG/C,WAAS,IAAI,GAAG,IAAI,OAAO,QAAQ,KAAK;AACtC,UAAM,OAAO,SAAS,OAAO,IAAI,CAAC,EAAE,SAAS,QAAQ,GAAG,CAAC;AACzD,UAAM,OAAO,WAAW,IAAI;AAAA,EAC9B;AACA,MAAI,OAAO;AACT,UAAM,OAAO,WAAW,aAAa;AAAA,EACvC;AACA,QAAM,OAAO,WAAW,YAAY;AAEpC,SAAO,UAAU;AAEjB,eAAa,KAAK,MAAM;AAGxB,QAAM,aAAa,gBAAgB,aAAa,OAAO,IAAI,YAAY,EAAE,OAAO,IAAc;AAE9F,SAAO,EAAE,MAAM,YAAY,SAAS;AACtC;","names":[]}
+{"version":3,"sources":["../src/types.ts","../src/audioTimeline.ts","../src/renderHtml.ts","../src/ffmpegArgs.ts","../src/wasmEncoder.ts"],"sourcesContent":["/**\n * Video Export Types\n *\n * Shared type definitions for video encoding and render HTML generation.\n * Used by both the browser-based encoder and the CLI native encoder.\n */\n\n/**\n * Video quality preset.\n * Controls the H.264 encoding speed/quality trade-off and constant rate factor.\n *\n * - draft:  ultrafast preset, CRF 28 — fast encode, lower quality (~1-2 Mbps)\n * - normal: medium preset, CRF 23 — balanced (~3-5 Mbps)\n * - high:   slow preset, CRF 18 — best quality, slowest (~8-12 Mbps)\n */\nexport type VideoQuality = 'draft' | 'normal' | 'high';\n\n/** Viewport orientation for video output. */\nexport type VideoOrientation = 'landscape' | 'portrait';\n\n/** Encoding preset parameters mapped from VideoQuality. */\nexport interface QualityPreset {\n  /** FFmpeg -preset value (ultrafast, medium, slow) */\n  preset: string;\n  /** FFmpeg -crf value (lower = higher quality, 0-51 range) */\n  crf: number;\n  /**\n   * Bits per pixel for WebCodecs bitrate targeting.\n   * Target bitrate = width * height * bitsPerPixel (see {@link bitrateForQuality}).\n   * These values reproduce the historical per-quality formula exactly:\n   * the old code used a `width * height * 4` baseline, halved for draft and\n   * doubled for high — i.e. 2 / 4 / 8 bits per pixel.\n   */\n  bitsPerPixel: number;\n  /** Target AAC audio bitrate in bits/sec for muxed audio tracks. */\n  audioBitrate: number;\n}\n\n/** Quality preset lookup — shared between wasm and native encoders. */\nexport const QUALITY_PRESETS: Record<VideoQuality, QualityPreset> = {\n  draft: { preset: 'ultrafast', crf: 28, bitsPerPixel: 2, audioBitrate: 96_000 },\n  normal: { preset: 'medium', crf: 23, bitsPerPixel: 4, audioBitrate: 128_000 },\n  high: { preset: 'slow', crf: 18, bitsPerPixel: 8, audioBitrate: 192_000 },\n};\n\n/**\n * Target H.264 bitrate (bits/sec) for a given quality at a given resolution.\n *\n * Computes `width * height * preset.bitsPerPixel`. With bitsPerPixel of\n * 2 / 4 / 8 (draft / normal / high) this is numerically identical to the\n * legacy formula (`width * height * 4` baseline, ×0.5 for draft, ×2 for high)\n * that previously lived in both the main-thread and worker WebCodecs encoders.\n * The single source of truth now lives here so every encode path agrees.\n */\nexport function bitrateForQuality(q: VideoQuality, width: number, height: number): number {\n  const preset = QUALITY_PRESETS[q] ?? QUALITY_PRESETS.normal;\n  return Math.round(width * height * preset.bitsPerPixel);\n}\n\n/** Viewport dimensions for each orientation. */\nexport const ORIENTATION_DIMENSIONS: Record<VideoOrientation, { width: number; height: number }> = {\n  landscape: { width: 1920, height: 1080 },\n  portrait: { width: 1080, height: 1920 },\n};\n\n/** Options for video export encoding. */\nexport interface VideoExportOptions {\n  /** Frames per second (default: 30) */\n  fps?: number;\n  /** Video width in pixels (default: based on orientation) */\n  width?: number;\n  /** Video height in pixels (default: based on orientation) */\n  height?: number;\n  /** Encoding quality preset (default: 'normal') */\n  quality?: VideoQuality;\n  /** Viewport orientation (default: 'landscape') */\n  orientation?: VideoOrientation;\n  /**\n   * Progress callback. Called during encoding with completion percentage and phase description.\n   * @param percent - 0-100 completion percentage\n   * @param phase - Human-readable description of current phase (e.g., 'encoding', 'muxing')\n   */\n  onProgress?: (percent: number, phase: string) => void;\n}\n\n/** Result from the wasm encoder. */\nexport interface EncoderResult {\n  /** MP4 file bytes */\n  data: Uint8Array;\n  /** Video duration in seconds */\n  duration: number;\n}\n\n/**\n * Resolve dimensions from options, applying orientation defaults.\n */\nexport function resolveDimensions(options: VideoExportOptions): {\n  width: number;\n  height: number;\n} {\n  const orientation = options.orientation ?? 'landscape';\n  const defaults = ORIENTATION_DIMENSIONS[orientation];\n  return {\n    width: options.width ?? defaults.width,\n    height: options.height ?? defaults.height,\n  };\n}\n","/**\n * audioTimeline — Pure scheduling of a doc's audio onto the export timeline.\n *\n * Browser-pure and Node-testable: turns a {@link Doc} into a flat list of\n * absolute-timed {@link AudioTimelineClip}s. This is the single source of\n * truth the browser MP4 export uses to place audio, and it deliberately\n * replicates the exact schedule math the CLI mix path uses so both agree:\n *\n *  - Narration segments (`doc.audio.segments[]`) are laid **sequentially**,\n *    each starting where the previous one ended — mirroring the CLI, which\n *    concatenates the segment files in order.\n *  - Timed media clips (`block.media` + `doc.documentMedia`) are placed at\n *    their **absolute** doc-timeline positions via the shared\n *    `resolveMediaSchedule()` helper (the same one the CLI calls), honouring\n *    each clip's trim window (`sourceIn` / `absoluteEnd - absoluteStart`).\n *  - Every start time is shifted by `coverPreRoll` so a cover pre-roll padding\n *    (silent leading frames) keeps audio in sync.\n */\n\nimport type { Doc } from '@bendyline/squisq/schemas';\nimport { resolveMediaSchedule } from '@bendyline/squisq/schemas';\n\n/** One audio source placed on the absolute export timeline. */\nexport interface AudioTimelineClip {\n  /** Source path (mp3/webm/mp4/…), relative to the doc's media dir. */\n  src: string;\n  /** Absolute second on the export timeline where this clip starts. */\n  startSec: number;\n  /** In-point within the source file to begin playback from. */\n  sourceInSec: number;\n  /** Played length in seconds (the trimmed window of the source). */\n  durationSec: number;\n}\n\n/**\n * Flatten a doc's narration + timed-media audio into absolute-timed clips.\n *\n * Pure — depends only on `doc` (and reuses `resolveMediaSchedule` from core so\n * the browser export and the CLI mix never drift). Returns `[]` for a doc with\n * no audio at all.\n *\n * @param doc - The document to schedule audio for.\n * @param coverPreRoll - Leading silent padding (seconds) added ahead of every\n *   clip, matching the cover-slide pre-roll frames. Default 0.\n */\nexport function computeAudioTimeline(doc: Doc, coverPreRoll = 0): AudioTimelineClip[] {\n  const preRoll = coverPreRoll > 0 ? coverPreRoll : 0;\n  const clips: AudioTimelineClip[] = [];\n\n  // ── Narration: laid sequentially (matches the CLI's ordered concat). ──\n  let cursor = 0;\n  for (const seg of doc.audio?.segments ?? []) {\n    const durationSec = Math.max(0, seg.duration);\n    if (durationSec > 0 && seg.src) {\n      clips.push({ src: seg.src, startSec: cursor + preRoll, sourceInSec: 0, durationSec });\n    }\n    cursor += durationSec;\n  }\n\n  // ── Timed media clips: absolute positions from the shared schedule. ──\n  for (const clip of resolveMediaSchedule(doc)) {\n    if (clip.kind !== 'audio') continue;\n    const durationSec = Math.max(0, clip.absoluteEnd - clip.absoluteStart);\n    if (durationSec <= 0 || !clip.src) continue;\n    clips.push({\n      src: clip.src,\n      startSec: clip.absoluteStart + preRoll,\n      sourceInSec: clip.sourceIn,\n      durationSec,\n    });\n  }\n\n  return clips;\n}\n","/**\n * Render HTML Generation for Video Frame Capture\n *\n * Generates a self-contained HTML document that loads the SquisqPlayer standalone\n * bundle in renderMode, embedding all images and audio as base64 data URIs.\n *\n * The generated page exposes `window.seekTo(time)`, `window.getDuration()`, etc.\n * via the SquisqRenderAPI, enabling Playwright (or any headless browser) to step\n * through frames and capture screenshots.\n *\n * Browser-pure: uses only btoa() and Uint8Array — no Node.js APIs.\n */\n\nimport type { Doc } from '@bendyline/squisq/schemas';\n\n// ── Types ──────────────────────────────────────────────────────────\n\nexport interface RenderHtmlOptions {\n  /** The IIFE player bundle source code (from PLAYER_BUNDLE) */\n  playerScript: string;\n\n  /**\n   * Map of relative image paths (as they appear in the Doc) to binary data.\n   * Converted to base64 data URIs and embedded in the HTML.\n   */\n  images?: Map<string, ArrayBuffer>;\n\n  /**\n   * Map of audio segment names/paths to binary audio data.\n   * Converted to base64 data URIs and embedded in the HTML.\n   */\n  audio?: Map<string, ArrayBuffer>;\n\n  /** Viewport width in CSS pixels (default: 1920) */\n  width?: number;\n\n  /** Viewport height in CSS pixels (default: 1080) */\n  height?: number;\n\n  /** Caption style for the rendered video. Omit for no captions. */\n  captionStyle?: 'standard' | 'social';\n}\n\n// ── MIME Detection ─────────────────────────────────────────────────\n\nconst MIME_MAP: Record<string, string> = {\n  jpg: 'image/jpeg',\n  jpeg: 'image/jpeg',\n  png: 'image/png',\n  gif: 'image/gif',\n  webp: 'image/webp',\n  svg: 'image/svg+xml',\n  bmp: 'image/bmp',\n  avif: 'image/avif',\n  mp3: 'audio/mpeg',\n  wav: 'audio/wav',\n  ogg: 'audio/ogg',\n  mp4: 'video/mp4',\n  webm: 'video/webm',\n};\n\nfunction inferMimeType(filename: string): string {\n  const ext = filename.split('.').pop()?.toLowerCase() ?? '';\n  return MIME_MAP[ext] ?? 'application/octet-stream';\n}\n\n// ── Base64 Encoding (browser-pure) ────────────────────────────────\n\n/**\n * Convert an ArrayBuffer to a base64 data URI.\n * Uses only standard Web APIs (Uint8Array + btoa).\n */\nfunction arrayBufferToDataUrl(buffer: ArrayBuffer, mimeType: string): string {\n  const bytes = new Uint8Array(buffer);\n  let binary = '';\n  for (let i = 0; i < bytes.length; i++) {\n    binary += String.fromCharCode(bytes[i]);\n  }\n  return `data:${mimeType};base64,${btoa(binary)}`;\n}\n\n// ── Escaping ───────────────────────────────────────────────────────\n\n/**\n * Prevent `</script>` from prematurely closing the script tag.\n */\nfunction escapeForScript(str: string): string {\n  return str.replace(/<\\/(script)/gi, '<\\\\/$1');\n}\n\n/** Escape HTML special characters. */\nfunction escapeHtml(str: string): string {\n  return str\n    .replace(/&/g, '&amp;')\n    .replace(/</g, '&lt;')\n    .replace(/>/g, '&gt;')\n    .replace(/\"/g, '&quot;');\n}\n\n// ── HTML Generation ────────────────────────────────────────────────\n\n/**\n * Generate a self-contained HTML document for headless video frame capture.\n *\n * The page mounts the SquisqPlayer in renderMode, which exposes the\n * SquisqRenderAPI on `window` (seekTo, getDuration, getCaptions, etc.).\n *\n * @param doc - The Doc to render\n * @param options - Render HTML options including player script and media\n * @returns Complete HTML string ready to be loaded in a headless browser\n */\nexport function generateRenderHtml(doc: Doc, options: RenderHtmlOptions): string {\n  const { playerScript, images, audio, width = 1920, height = 1080, captionStyle } = options;\n\n  // Build base64 image map\n  const imageMap: Record<string, string> = {};\n  if (images) {\n    for (const [path, buffer] of images.entries()) {\n      imageMap[path] = arrayBufferToDataUrl(buffer, inferMimeType(path));\n    }\n  }\n\n  // Build base64 audio map\n  const audioMap: Record<string, string> = {};\n  let hasAudio = false;\n  if (audio) {\n    for (const [name, buffer] of audio.entries()) {\n      audioMap[name] = arrayBufferToDataUrl(buffer, inferMimeType(name));\n      hasAudio = true;\n    }\n  }\n\n  const docJson = escapeForScript(JSON.stringify(doc));\n  const imageMapJson = escapeForScript(JSON.stringify(imageMap));\n  const audioMapJson = hasAudio ? escapeForScript(JSON.stringify(audioMap)) : 'null';\n\n  return `<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n<meta charset=\"UTF-8\">\n<meta name=\"viewport\" content=\"width=${width}, height=${height}\">\n<title>${escapeHtml('Squisq Video Render')}</title>\n<style>\n*,*::before,*::after{box-sizing:border-box}\nhtml,body{margin:0;padding:0;width:${width}px;height:${height}px;overflow:hidden;background:#000}\n#squisq-root{width:${width}px;height:${height}px;display:flex;align-items:center;justify-content:center}\n</style>\n</head>\n<body>\n<div id=\"squisq-root\"></div>\n<script>${escapeForScript(playerScript)}</script>\n<script>\n(function(){\n  var doc = JSON.parse(${JSON.stringify(docJson)});\n  var images = JSON.parse(${JSON.stringify(imageMapJson)});\n  var audio = ${audioMapJson === 'null' ? 'null' : 'JSON.parse(' + JSON.stringify(audioMapJson) + ')'};\n  SquisqPlayer.mount(document.getElementById(\"squisq-root\"), doc, {\n    mode: \"slideshow\",\n    images: images,\n    audio: audio,\n    autoPlay: false,\n    basePath: \".\",\n    renderMode: true${captionStyle ? `,\\n    captionStyle: ${JSON.stringify(captionStyle)}` : ''}\n  });\n})();\n</script>\n</body>\n</html>`;\n}\n","/**\n * FFmpeg argument builders — the single source of truth for translating a\n * {@link VideoQuality} into ffmpeg CLI flags. Shared verbatim by every\n * ffmpeg-based encode path: the wasm encoder ({@link ./wasmEncoder}), the\n * video-react fallback worker, and the CLI native encoder. Deriving these\n * from {@link QUALITY_PRESETS} keeps the browser and CLI byte-for-byte aligned.\n *\n * Pure, dependency-free, and unit-testable in isolation (the actual ffmpeg\n * invocations live behind wasm/child-process boundaries that are awkward to\n * exercise directly).\n */\n\nimport { QUALITY_PRESETS, type VideoQuality } from './types.js';\n\n/**\n * H.264 speed/quality flags (`-preset`, `-crf`) for a quality level.\n * @example ffmpegVideoQualityArgs('high') // ['-preset', 'slow', '-crf', '18']\n */\nexport function ffmpegVideoQualityArgs(quality: VideoQuality): string[] {\n  const preset = QUALITY_PRESETS[quality] ?? QUALITY_PRESETS.normal;\n  return ['-preset', preset.preset, '-crf', String(preset.crf)];\n}\n\n/**\n * AAC audio-bitrate flag value in ffmpeg's `k` shorthand for a quality level.\n * @example audioBitrateArg('high') // '192k'\n */\nexport function audioBitrateArg(quality: VideoQuality): string {\n  const preset = QUALITY_PRESETS[quality] ?? QUALITY_PRESETS.normal;\n  return `${preset.audioBitrate / 1000}k`;\n}\n","/**\n * WASM Video Encoder\n *\n * Encodes PNG frame screenshots into an MP4 video using ffmpeg.wasm.\n * Browser-pure — no Node.js APIs. Works in any environment with SharedArrayBuffer\n * support (browsers with COOP/COEP headers, or Node 18+).\n *\n * Uses @ffmpeg/ffmpeg for H.264 encoding and optional AAC audio muxing.\n */\n\nimport { FFmpeg } from '@ffmpeg/ffmpeg';\nimport { fetchFile } from '@ffmpeg/util';\n\nimport type { VideoExportOptions, EncoderResult } from './types.js';\nimport { resolveDimensions } from './types.js';\nimport { ffmpegVideoQualityArgs, audioBitrateArg } from './ffmpegArgs.js';\n\n/**\n * Encode an array of PNG frame screenshots into an MP4 video.\n *\n * @param frames - Array of PNG image bytes (one per frame, in order)\n * @param audio - Optional WAV/MP3/AAC audio bytes to mux into the video\n * @param options - Encoding options (fps, quality, dimensions, progress)\n * @returns Encoded MP4 data and duration metadata\n */\nexport async function framesToMp4Wasm(\n  frames: Uint8Array[],\n  audio: Uint8Array | null,\n  options: VideoExportOptions = {},\n): Promise<EncoderResult> {\n  const fps = options.fps ?? 30;\n  const quality = options.quality ?? 'normal';\n  const { width, height } = resolveDimensions(options);\n  const onProgress = options.onProgress;\n\n  if (frames.length === 0) {\n    throw new Error('No frames provided for encoding');\n  }\n\n  const duration = frames.length / fps;\n\n  // Initialize ffmpeg.wasm\n  const ffmpeg = new FFmpeg();\n\n  ffmpeg.on('progress', ({ progress }) => {\n    if (onProgress) {\n      const percent = Math.round(progress * 100);\n      onProgress(Math.min(percent, 99), 'encoding');\n    }\n  });\n\n  await ffmpeg.load();\n\n  onProgress?.(0, 'writing frames');\n\n  // Write frame PNGs to virtual filesystem\n  const padLen = String(frames.length).length;\n  for (let i = 0; i < frames.length; i++) {\n    const name = `frame-${String(i + 1).padStart(padLen, '0')}.png`;\n    await ffmpeg.writeFile(name, frames[i]);\n\n    // Report frame-write progress (0-40% of total)\n    if (onProgress && i % 10 === 0) {\n      onProgress(Math.round((i / frames.length) * 40), 'writing frames');\n    }\n  }\n\n  // Write audio if provided\n  if (audio) {\n    await ffmpeg.writeFile('audio-input', audio);\n  }\n\n  onProgress?.(40, 'encoding');\n\n  // Build ffmpeg command\n  const padPattern = `frame-%0${padLen}d.png`;\n  const args = ['-y', '-framerate', String(fps), '-i', padPattern];\n\n  // Add audio input\n  if (audio) {\n    args.push('-i', 'audio-input');\n  }\n\n  // Video encoding settings\n  args.push(\n    '-c:v',\n    'libx264',\n    ...ffmpegVideoQualityArgs(quality),\n    '-pix_fmt',\n    'yuv420p',\n    '-vf',\n    `scale=${width}:${height}:force_original_aspect_ratio=decrease,pad=${width}:${height}:(ow-iw)/2:(oh-ih)/2`,\n  );\n\n  // Audio encoding\n  if (audio) {\n    args.push('-c:a', 'aac', '-b:a', audioBitrateArg(quality), '-shortest');\n  }\n\n  args.push('output.mp4');\n\n  // Run encoding\n  await ffmpeg.exec(args);\n\n  onProgress?.(95, 'reading output');\n\n  // Read the output file\n  const data = await ffmpeg.readFile('output.mp4');\n\n  // Cleanup virtual filesystem\n  for (let i = 0; i < frames.length; i++) {\n    const name = `frame-${String(i + 1).padStart(padLen, '0')}.png`;\n    await ffmpeg.deleteFile(name);\n  }\n  if (audio) {\n    await ffmpeg.deleteFile('audio-input');\n  }\n  await ffmpeg.deleteFile('output.mp4');\n\n  ffmpeg.terminate();\n\n  onProgress?.(100, 'done');\n\n  // ffmpeg.readFile returns Uint8Array for binary files\n  const outputData = data instanceof Uint8Array ? data : new TextEncoder().encode(data as string);\n\n  return { data: outputData, duration };\n}\n\n// Re-export fetchFile for convenience — consumers may need it to prepare audio bytes\nexport { fetchFile };\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/squisq-video",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "Video encoding and render HTML generation for Squisq documents — browser-pure, works in Node and browser",
   "license": "MIT",
   "author": "Bendyline",
@@ -40,7 +40,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@bendyline/squisq": "1.5.0",
+    "@bendyline/squisq": "1.5.2",
     "@ffmpeg/ffmpeg": "0.12.15",
     "@ffmpeg/util": "0.12.2"
   },