@bendyline/squisq-cli 2.8.9 → 2.8.11

package/README.md

@@ -84,17 +84,24 @@ squisq video doc.json -o out.mp4
 | `--dither`                         | GIF dithering: `bayer`, `sierra2_4a`, or `none`                      | `sierra2_4a`              |
 | `--bayer-scale`                    | Ordered Bayer strength, 0–5                                          | 3                         |
 | `-t, --theme`                      | Squisq theme id to apply                                             | none                      |
+| `--motion`                         | Motion profile: `calm`, `documentary` or `vibrant`                   | doc's, then theme's       |
 | `--transform`                      | Transform style to apply before rendering                            | none                      |
 | `--cover-preroll`                  | Seconds of cover-slide pre-roll before the story starts              | 2                         |
 | `--width` / `--height`             | Dimension overrides in pixels — **must be even**                     | MP4 1080p; GIF 960×540    |
 | `--overwrite`                      | Replace an existing output file (otherwise refuse and exit non-zero) | off                       |
 | `--no-auto-templates`              | Disable content-aware template auto-picking for unannotated headings | (auto on)                 |
+| `--frame-transport`                | MP4 frame delivery: `pipe` (stream stills to ffmpeg) or `memory`     | `pipe`                    |
+| `--capture-format`                 | MP4 still captured per frame: `png` or `jpeg` (pipe only)            | high `png`, else `jpeg`   |
+| `--frames-dir`                     | MP4 only: spool every captured still here and keep it after the run  | none                      |
+| `--resume`                         | MP4 only: reuse stills an identical render spooled in `--frames-dir` | off                       |
 
 Notes:
 
 - **Dimensions must be even.** `--width 851` is rejected immediately — before the document is read or a browser launches — with `Video width must be an even number of pixels (got 851) … Use 850 or 852.` Odd values are rejected rather than rounded, so a render never silently ships at a size you did not ask for. The rule is the same for MP4 and GIF, and matches browser export.
 - **An existing output file is never overwritten by default.** The check runs before rendering, so a colliding path costs you a second rather than a full capture. Pass `--overwrite` to replace.
 - FFmpeg failures report the one relevant line (e.g. `[libx264] width not divisible by 2 (851x480) (exit code 1)`) rather than dumping the whole command line and stderr buffer.
+- **MP4 frames stream to ffmpeg as they are captured.** Memory stays flat for a story of any length; `--frame-transport memory` restores the old retain-then-encode path, which is bounded to a few seconds of 1080p photo slides. `--frames-dir` keeps every still (plus a `manifest.json` naming the doc, size, rate, captions and animation settings), and `--resume` skips re-capturing stills that an identical render already spooled there.
+- **Portrait and custom sizes are composed natively.** The render page pins the player's viewport to the export size; a player bundle that ignores it fails the run before capture instead of producing a letterboxed landscape layout.
 
 ### `squisq image <input> [output]`
 
@@ -230,8 +237,13 @@ const result = await renderDocToMp4(doc, container, {
   captionStyle: 'social', // 'off' | 'standard' | 'social' (default 'off')
   animationsEnabled: false, // static slide changes; media/timing remain active
   coverPreRoll: 2, // seconds of cover-slide pre-roll (default 0)
+  frameTransport: 'pipe', // 'pipe' (default; streams stills to ffmpeg) | 'memory'
+  captureFormat: 'png', // 'png' | 'jpeg' (default: png for high quality, jpeg otherwise)
+  framesDir: './frames', // optional: keep every still + manifest; with resume: true, reuse them
+  onFrame: ({ index, totalFrames, captureMs, reused }) => {}, // per-frame throughput hook
   onProgress: (phase, pct) => console.log(`${phase}: ${pct}%`),
 });
+// result: { duration, frameCount, outputPath, reusedFrameCount?, framesDir? }
 
 console.log(`Rendered ${result.frameCount} frames (${result.duration}s) → ${result.outputPath}`);
 ```

package/dist/{api-QLYK5AQE.js → api-P7LOLIZT.js}

@@ -9,6 +9,7 @@ import {
   convert,
   createCliRegistry,
   extractThumbnails,
+  ffmpegPipeArgs,
   prepareConversion,
   readInput,
   renderDocCoverToPng,
@@ -17,14 +18,14 @@ import {
   renderDocToMp4,
   resolveDashboardDimensions,
   validateDashboardImageDimensions
-} from "./chunk-XD2ICI5G.js";
+} from "./chunk-6MZC4YQV.js";
 import {
   GIF_EXPORT_DEFAULTS,
   framesToGifNative,
   framesToGifNativeBytes,
   framesToMp4Native,
   framesToMp4NativeBytes
-} from "./chunk-GGVASRPG.js";
+} from "./chunk-Y5XKUWJ5.js";
 export {
   CapturedFrameBudgetError,
   ConversionError,
@@ -36,6 +37,7 @@ export {
   convert,
   createCliRegistry,
   extractThumbnails,
+  ffmpegPipeArgs,
   framesToGifNative,
   framesToGifNativeBytes,
   framesToMp4Native,

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import { Doc } from '@bendyline/squisq/schemas';
+import { Doc, MotionSpec } from '@bendyline/squisq/schemas';
 import { DashboardStyleId } from '@bendyline/squisq/doc';
 import { ContentContainer } from '@bendyline/squisq/storage';
 export { MemoryContentContainer } from '@bendyline/squisq/storage';
@@ -8,6 +8,68 @@ import { FormatRegistry, FormatId, ConvertOptions, ConvertSource, ConversionResu
 export { ConversionError, ConversionErrorCode, ConversionErrorOptions, ConversionResult, ConvertOptions, ConvertSource, FormatDefinition, FormatId, FormatRegistry, NormalizedInput, PreparedConversion, PreparedExportOptions } from '@bendyline/squisq-formats';
 import { MarkdownDocument } from '@bendyline/squisq/markdown';
 
+/**
+ * Frame sinks for offline MP4 rendering.
+ *
+ * The capture loop produces one encoded still (PNG or JPEG) per output frame
+ * and hands it to a sink. Two kinds exist:
+ *
+ * - {@link createFfmpegPipeSink} streams stills into one long-running ffmpeg
+ *   process over stdin (`image2pipe`) so x264 encodes as frames arrive and
+ *   memory stays flat however long the document is. This replaced the
+ *   retain-every-PNG-then-encode design, whose 256 MB budget held only a few
+ *   seconds of 1080p photo slides.
+ * - {@link openDirectoryFrameStore} spools stills to a directory next to a
+ *   manifest, so a render can be inspected frame by frame and resumed after
+ *   an interruption without re-capturing frames already on disk.
+ *
+ * Related: api.ts (`renderDocToMp4`), runFfmpeg.ts (stderr digest),
+ * @bendyline/squisq-video ffmpegArgs.ts (quality and mux flags).
+ *
+ * Gotchas: the pipe sink honours stdin backpressure, so a slow encoder slows
+ * capture rather than buffering frames. A wall-clock timeout would fire on
+ * every long render, so the sink watches for silence instead: a frame write
+ * or an ffmpeg stderr line counts as activity.
+ */
+
+/** Still-image format captured from the browser for each frame. */
+type CaptureFormat = 'png' | 'jpeg';
+/** Everything the pipe encoder needs; mirrors the memory path's ffmpeg flags. */
+interface FfmpegPipeSinkOptions {
+    ffmpegPath: string;
+    outputPath: string;
+    fps: number;
+    width: number;
+    height: number;
+    quality: VideoQuality;
+    captureFormat: CaptureFormat;
+    /** Pre-mixed audio file to mux, or null for a silent video. */
+    audioPath: string | null;
+    signal?: AbortSignal;
+    /** Fail when neither a frame nor encoder output arrives for this long (default 120 s). */
+    idleTimeoutMs?: number;
+}
+/** ffmpeg arguments for the streaming (`image2pipe`) H.264 encode. Pure; unit-tested. */
+declare function ffmpegPipeArgs(options: Omit<FfmpegPipeSinkOptions, 'ffmpegPath' | 'signal' | 'idleTimeoutMs'>): string[];
+/**
+ * Identity of a spooled render. A spool is reusable only when every value
+ * matches: a different doc, size, rate, caption or animation setting changes
+ * the pixels, and a different capture format changes the bytes on disk.
+ */
+interface FrameManifest {
+    generatedBy: 'squisq-cli';
+    docHash: string;
+    fps: number;
+    width: number;
+    height: number;
+    captionStyle: string | null;
+    /** JSON of the motion spec the frames were captured with (`null` = doc/theme default). */
+    motion?: string | null;
+    animationsEnabled: boolean;
+    coverPreRoll: number;
+    captureFormat: CaptureFormat;
+}
+
 /**
  * CLI format registry.
  *
@@ -284,8 +346,44 @@ interface RenderDocToMp4Options {
     height?: number;
     /** Caption mode to bake into the video (default: off). */
     captionStyle?: 'off' | 'standard' | 'social';
+    /**
+     * Motion profile override: `calm` (pre-profile output), `documentary` or
+     * `vibrant`, or a spec with overrides. Omitted → the doc's `motion` /
+     * frontmatter `squisq-motion`, then the theme's `renderStyle.motionProfile`.
+     */
+    motion?: MotionSpec | null;
     /** Render layer animations and block transitions (default: true). */
     animationsEnabled?: boolean;
+    /**
+     * How captured stills reach the encoder (default: 'pipe').
+     *
+     * - 'pipe' streams each still into one long-running ffmpeg process as it is
+     *   captured, so memory stays flat for documents of any length.
+     * - 'memory' retains every still until capture completes, then encodes.
+     *   Bounded by {@link MAX_CAPTURED_FRAME_BYTES} (a few seconds of 1080p
+     *   photo slides); kept for callers that depend on the old semantics.
+     */
+    frameTransport?: 'pipe' | 'memory';
+    /**
+     * Still-image format captured from the browser per frame (default: 'png'
+     * for high quality, otherwise 'jpeg'). Chromium encodes a 1080p PNG in
+     * hundreds of milliseconds but a JPEG in tens, and JPEG stills are
+     * converted to limited-range yuv420p and indistinguishable after H.264 at
+     * draft/normal CRF; PNG keeps the capture lossless for the high preset.
+     * Pipe transport only.
+     */
+    captureFormat?: CaptureFormat;
+    /**
+     * Spool every captured still into this directory next to a manifest, and
+     * keep them after the render for inspection. With `resume`, a spool whose
+     * manifest matches this render supplies its frames instead of re-capturing
+     * them. Pipe transport only.
+     */
+    framesDir?: string;
+    /** Reuse frames already present in `framesDir` from an identical render. */
+    resume?: boolean;
+    /** Per-frame callback for hosts that measure throughput or tee frames. Pipe transport only. */
+    onFrame?: (frame: RenderedFrameInfo) => void;
     /**
      * Seconds of cover-slide pre-roll before the story starts (default: 0).
      *
@@ -315,6 +413,8 @@ interface RenderDocToGifOptions {
     height?: number;
     /** Caption mode to bake into the GIF (default: standard). */
     captionStyle?: 'off' | 'standard' | 'social';
+    /** Motion profile override (see {@link RenderDocToMp4Options.motion}). */
+    motion?: MotionSpec | null;
     /** Seconds of cover-slide pre-roll (default: 0). */
     coverPreRoll?: number;
     /** Render layer animations and block transitions (default: false). */
@@ -330,6 +430,20 @@ interface RenderDocToGifOptions {
     /** Progress callback. */
     onProgress?: (phase: string, percent: number) => void;
 }
+/** One output frame as it passes through the render loop. */
+interface RenderedFrameInfo {
+    /** Zero-based index in the output sequence; cover pre-roll frames come first. */
+    index: number;
+    /** Timeline second rendered (0 during the cover pre-roll). */
+    time: number;
+    isCover: boolean;
+    /** Frames the render emits in total, pre-roll included. */
+    totalFrames: number;
+    /** True when the still came from a resumed spool instead of a capture. */
+    reused: boolean;
+    /** Milliseconds spent seeking and capturing (0 when reused). */
+    captureMs: number;
+}
 /** Result returned by renderDocToMp4. */
 interface RenderDocToMp4Result {
     /** Duration of the rendered video in seconds (including pre-roll). */
@@ -338,6 +452,10 @@ interface RenderDocToMp4Result {
     frameCount: number;
     /** Output file path. */
     outputPath: string;
+    /** Frames supplied by a resumed spool instead of a capture (pipe transport). */
+    reusedFrameCount?: number;
+    /** Spool directory holding every captured still, when one was requested. */
+    framesDir?: string;
 }
 /** Result returned by renderDocToGif. */
 interface RenderDocToGifResult extends RenderDocToMp4Result {
@@ -442,4 +560,4 @@ interface ExtractThumbnailsOptions {
  */
 declare function extractThumbnails(options: ExtractThumbnailsOptions): Promise<void>;
 
-export { CapturedFrameBudgetError, type CliConvertOptions, type ExtractThumbnailsOptions, GIF_EXPORT_DEFAULTS, type GifExportOptions, type GifFormatOptions, MAX_CAPTURED_FRAME_BYTES, type Mp4FormatOptions, type NativeVideoExportOptions, type PngFormatOptions, type ReadInputResult, type RenderCoverPngOptions, type RenderCoverPngResult, type RenderDashboardPngOptions, type RenderDashboardPngResult, type RenderDocToGifOptions, type RenderDocToGifResult, type RenderDocToMp4Options, type RenderDocToMp4Result, type ThumbnailSpec, convert, createCliRegistry, extractThumbnails, framesToGifNative, framesToGifNativeBytes, framesToMp4Native, framesToMp4NativeBytes, prepareConversion, readInput, renderDocCoverToPng, renderDocToDashboardPng, renderDocToGif, renderDocToMp4 };
+export { type CaptureFormat, CapturedFrameBudgetError, type CliConvertOptions, type ExtractThumbnailsOptions, type FrameManifest, GIF_EXPORT_DEFAULTS, type GifExportOptions, type GifFormatOptions, MAX_CAPTURED_FRAME_BYTES, type Mp4FormatOptions, type NativeVideoExportOptions, type PngFormatOptions, type ReadInputResult, type RenderCoverPngOptions, type RenderCoverPngResult, type RenderDashboardPngOptions, type RenderDashboardPngResult, type RenderDocToGifOptions, type RenderDocToGifResult, type RenderDocToMp4Options, type RenderDocToMp4Result, type RenderedFrameInfo, type ThumbnailSpec, convert, createCliRegistry, extractThumbnails, ffmpegPipeArgs, framesToGifNative, framesToGifNativeBytes, framesToMp4Native, framesToMp4NativeBytes, prepareConversion, readInput, renderDocCoverToPng, renderDocToDashboardPng, renderDocToGif, renderDocToMp4 };