@pneuma-craft/video 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -134,6 +134,13 @@ interface PlaybackEngineOptions {
      * omitted, subtitle tracks render nothing (legacy behavior).
      */
     subtitleRenderer?: SubtitleRenderer;
+    /**
+     * Render preview frames (planning-layer visuals attached to time points
+     * on a track) when no real clip covers the current time. Defaults to
+     * `true` for the playback engine — the user scrubbing the timeline
+     * should see the agent's planned vibe before any real video clips land.
+     */
+    includePreviewFrames?: boolean;
 }
 declare function createPlaybackEngine(options?: PlaybackEngineOptions): PlaybackEngine;
 
@@ -144,10 +151,30 @@ interface ExportEngineOptions {
      * preview. When omitted, subtitle tracks are skipped during export.
      */
     subtitleRenderer?: SubtitleRenderer;
+    /**
+     * Include preview frames (planning-layer visuals attached to time points
+     * on a track) in the exported video. Defaults to `false` because an export
+     * normally represents a finished cut. Set true for review-grade exports of
+     * unfinished timelines — e.g., agent producing a "草样片" for the user to
+     * scrub before committing to expensive real renders.
+     */
+    includePreviewFrames?: boolean;
 }
 declare function createExportEngine(options?: ExportEngineOptions): ExportEngine;
 
-declare function createFrameRenderer(decoder: MediaDecoder, compositor: Compositor, width: number, height: number, subtitleRenderer?: SubtitleRenderer): FrameRenderer;
+interface CreateFrameRendererOptions {
+    readonly subtitleRenderer?: SubtitleRenderer;
+    /**
+     * Render preview frames in tracks where no real clip covers the current
+     * time. Defaults to false — preview frames are a planning-layer visual
+     * that should NOT appear in final exports unless explicitly requested.
+     * Engines wire their own defaults: PlaybackEngine passes true, ExportEngine
+     * passes false.
+     */
+    readonly includePreviewFrames?: boolean;
+}
+type LegacyArg = SubtitleRenderer | CreateFrameRendererOptions | undefined;
+declare function createFrameRenderer(decoder: MediaDecoder, compositor: Compositor, width: number, height: number, optionsOrLegacySubtitleRenderer?: LegacyArg): FrameRenderer;
 
 interface MasterClockOptions {
     audioContext: AudioContext;

package/dist/index.d.ts

@@ -134,6 +134,13 @@ interface PlaybackEngineOptions {
      * omitted, subtitle tracks render nothing (legacy behavior).
      */
     subtitleRenderer?: SubtitleRenderer;
+    /**
+     * Render preview frames (planning-layer visuals attached to time points
+     * on a track) when no real clip covers the current time. Defaults to
+     * `true` for the playback engine — the user scrubbing the timeline
+     * should see the agent's planned vibe before any real video clips land.
+     */
+    includePreviewFrames?: boolean;
 }
 declare function createPlaybackEngine(options?: PlaybackEngineOptions): PlaybackEngine;
 
@@ -144,10 +151,30 @@ interface ExportEngineOptions {
      * preview. When omitted, subtitle tracks are skipped during export.
      */
     subtitleRenderer?: SubtitleRenderer;
+    /**
+     * Include preview frames (planning-layer visuals attached to time points
+     * on a track) in the exported video. Defaults to `false` because an export
+     * normally represents a finished cut. Set true for review-grade exports of
+     * unfinished timelines — e.g., agent producing a "草样片" for the user to
+     * scrub before committing to expensive real renders.
+     */
+    includePreviewFrames?: boolean;
 }
 declare function createExportEngine(options?: ExportEngineOptions): ExportEngine;
 
-declare function createFrameRenderer(decoder: MediaDecoder, compositor: Compositor, width: number, height: number, subtitleRenderer?: SubtitleRenderer): FrameRenderer;
+interface CreateFrameRendererOptions {
+    readonly subtitleRenderer?: SubtitleRenderer;
+    /**
+     * Render preview frames in tracks where no real clip covers the current
+     * time. Defaults to false — preview frames are a planning-layer visual
+     * that should NOT appear in final exports unless explicitly requested.
+     * Engines wire their own defaults: PlaybackEngine passes true, ExportEngine
+     * passes false.
+     */
+    readonly includePreviewFrames?: boolean;
+}
+type LegacyArg = SubtitleRenderer | CreateFrameRendererOptions | undefined;
+declare function createFrameRenderer(decoder: MediaDecoder, compositor: Compositor, width: number, height: number, optionsOrLegacySubtitleRenderer?: LegacyArg): FrameRenderer;
 
 interface MasterClockOptions {
     audioContext: AudioContext;

package/dist/index.js

@@ -436,31 +436,58 @@ async function createCompositor(width, height, type = "auto") {
 
 // src/frame-renderer.ts
 import { resolveFrame } from "@pneuma-craft/timeline";
-function createFrameRenderer(decoder, compositor, width, height, subtitleRenderer) {
+function normalizeOptions(arg) {
+  if (arg === void 0) return {};
+  if (typeof arg === "function") return { subtitleRenderer: arg };
+  return arg;
+}
+function createFrameRenderer(decoder, compositor, width, height, optionsOrLegacySubtitleRenderer) {
+  const options = normalizeOptions(optionsOrLegacySubtitleRenderer);
+  const { subtitleRenderer, includePreviewFrames = false } = options;
   return {
     async renderFrame(composition, time) {
       const resolved = resolveFrame(composition, time);
-      const videoClips = resolved.clips.filter((rc) => rc.track.type === "video");
-      const subtitleClips = subtitleRenderer ? resolved.clips.filter((rc) => rc.track.type === "subtitle") : [];
+      const clipsByTrack = /* @__PURE__ */ new Map();
+      for (const rc of resolved.clips) {
+        const arr = clipsByTrack.get(rc.track.id);
+        if (arr) arr.push(rc);
+        else clipsByTrack.set(rc.track.id, [rc]);
+      }
+      const previewByTrack = /* @__PURE__ */ new Map();
+      for (const rpf of resolved.previewFrames) previewByTrack.set(rpf.track.id, rpf);
       const layers = [];
-      for (let i = 0; i < videoClips.length; i++) {
-        const rc = videoClips[i];
-        const source = await decoder.decodeVideoFrame(
-          rc.clip.assetId,
-          rc.localTime,
-          width,
-          height
-        );
-        layers.push({
-          source,
-          opacity: 1,
-          zIndex: i
-        });
+      let zIndex = 0;
+      for (const track of composition.tracks) {
+        if (track.type !== "video") continue;
+        const trackClips = clipsByTrack.get(track.id);
+        if (trackClips && trackClips.length > 0) {
+          for (const rc of trackClips) {
+            const source = await decoder.decodeVideoFrame(
+              rc.clip.assetId,
+              rc.localTime,
+              width,
+              height
+            );
+            layers.push({ source, opacity: 1, zIndex: zIndex++ });
+          }
+          continue;
+        }
+        if (includePreviewFrames) {
+          const rpf = previewByTrack.get(track.id);
+          if (rpf) {
+            const source = await decoder.decodeVideoFrame(
+              rpf.previewFrame.assetId,
+              0,
+              width,
+              height
+            );
+            layers.push({ source, opacity: 1, zIndex: zIndex++ });
+          }
+        }
       }
-      if (subtitleRenderer && subtitleClips.length > 0) {
-        const baseZ = videoClips.length;
-        for (let i = 0; i < subtitleClips.length; i++) {
-          const rc = subtitleClips[i];
+      if (subtitleRenderer) {
+        const subtitleClips = resolved.clips.filter((rc) => rc.track.type === "subtitle");
+        for (const rc of subtitleClips) {
           const rendered = await subtitleRenderer({
             clip: rc.clip,
             localTime: rc.localTime,
@@ -468,11 +495,7 @@ function createFrameRenderer(decoder, compositor, width, height, subtitleRendere
             height
           });
           if (rendered) {
-            layers.push({
-              source: rendered,
-              opacity: 1,
-              zIndex: baseZ + i
-            });
+            layers.push({ source: rendered, opacity: 1, zIndex: zIndex++ });
           }
         }
       }
@@ -873,6 +896,7 @@ function createPlaybackEngine(options) {
   const compositorType = options?.compositorType ?? "canvas2d";
   const decodeTimeoutMs = options?.decodeTimeoutMs ?? DEFAULT_DECODE_TIMEOUT_MS;
   const subtitleRenderer = options?.subtitleRenderer;
+  const includePreviewFrames = options?.includePreviewFrames ?? true;
   let _state = "idle";
   let _playbackRate = 1;
   let _loop = null;
@@ -1041,7 +1065,7 @@ function createPlaybackEngine(options) {
           _compositor,
           composition.settings.width,
           composition.settings.height,
-          subtitleRenderer
+          { subtitleRenderer, includePreviewFrames }
         );
         _clock = createMasterClock({
           audioContext: _audioContext,
@@ -1207,6 +1231,7 @@ import {
 } from "mediabunny";
 function createExportEngine(options) {
   const subtitleRenderer = options?.subtitleRenderer;
+  const includePreviewFrames = options?.includePreviewFrames ?? false;
   const progressListeners = /* @__PURE__ */ new Set();
   let abortController = null;
   function notifyProgress(progress) {
@@ -1229,7 +1254,10 @@ function createExportEngine(options) {
       const decoderAudioCtx = new OfflineAudioContext(1, 1, composition.settings.sampleRate || 48e3);
       const decoder = createMediaDecoder(resolver, decoderAudioCtx);
       const compositor = await createCompositor(width, height, "canvas2d");
-      const renderer = createFrameRenderer(decoder, compositor, width, height, subtitleRenderer);
+      const renderer = createFrameRenderer(decoder, compositor, width, height, {
+        subtitleRenderer,
+        includePreviewFrames
+      });
       try {
         const format = options2.format === "webm" ? new WebMOutputFormat() : new Mp4OutputFormat({ fastStart: "in-memory" });
         const target = new BufferTarget();