vargai 0.4.0-alpha81 → 0.4.0-alpha83

package/package.json

@@ -71,7 +71,7 @@
     "zod": "^4.2.1"
   },
   "sideEffects": false,
-  "version": "0.4.0-alpha81",
+  "version": "0.4.0-alpha83",
   "exports": {
     ".": "./src/index.ts",
     "./ai": "./src/ai-sdk/index.ts",

package/src/ai-sdk/examples/garry-tan-varg.ts

@@ -0,0 +1,61 @@
+/**
+ * Garry Tan Talking Head Video
+ * Generate a video of Garry Tan saying "varg.ai is cool!"
+ */
+
+import {
+  generateImage,
+  experimental_generateSpeech as generateSpeech,
+} from "ai";
+import { elevenlabs, File, fal, generateVideo } from "../index";
+
+async function main() {
+  const script = `varg.ai is cool!`;
+
+  console.log("generating Garry Tan image and voice in parallel...");
+  const [imageResult, speechResult] = await Promise.all([
+    generateImage({
+      model: fal.imageModel("flux-schnell"),
+      prompt:
+        "Garry Tan, Y Combinator CEO, Asian American man, short dark hair, glasses, friendly smile, professional headshot, studio lighting, clean background, looking at camera",
+      n: 1,
+    }),
+    generateSpeech({
+      model: elevenlabs.speechModel("turbo"),
+      text: script,
+      voice: "adam",
+    }),
+  ]);
+
+  const firstImage = imageResult.images[0];
+  if (!firstImage) throw new Error("No image generated");
+  const image = File.from(firstImage);
+  const audio = File.from(speechResult.audio);
+
+  console.log(`image: ${(await image.data()).byteLength} bytes`);
+  console.log(`audio: ${(await audio.data()).byteLength} bytes`);
+
+  await Bun.write("output/garry-tan-image.png", await image.data());
+  await Bun.write("output/garry-tan-voice.mp3", await audio.data());
+
+  console.log("\nanimating Garry Tan (5 seconds)...");
+  const { video } = await generateVideo({
+    model: fal.videoModel("wan-2.5"),
+    prompt: {
+      text: "man talking naturally, moving mouth while speaking, subtle head movements, professional demeanor, blinking naturally",
+      images: [await image.data()],
+    },
+    duration: 5,
+  });
+
+  const output = File.from(video);
+  console.log(`video: ${(await output.data()).byteLength} bytes`);
+  await Bun.write("output/garry-tan-varg.mp4", await output.data());
+
+  console.log("\ndone! files saved to output/");
+  console.log("- output/garry-tan-image.png");
+  console.log("- output/garry-tan-voice.mp3");
+  console.log("- output/garry-tan-varg.mp4");
+}
+
+main().catch(console.error);

package/src/ai-sdk/middleware/placeholder.ts

@@ -84,22 +84,40 @@ export async function generatePlaceholder(
   const { $ } = await import("bun");
 
   try {
+    let ffmpegResult: Awaited<ReturnType<typeof $>>;
+
     if (type === "audio") {
-      await $`ffmpeg -y -f lavfi -i anullsrc=r=44100:cl=stereo -t ${duration} -c:a libmp3lame ${outputPath}`.quiet();
+      ffmpegResult =
+        await $`ffmpeg -y -f lavfi -i anullsrc=r=44100:cl=stereo -t ${duration} -c:a libmp3lame ${outputPath}`
+          .quiet()
+          .nothrow();
     } else if (type === "image") {
       const colorInput = `color=c=0x${hexColor}:s=${width}x${height}:d=1`;
       const labelY = `(h/2)-${labelFontSize}`;
       const promptY = `(h/2)+${Math.floor(labelFontSize * 0.5)}`;
       const drawLabel = `drawtext=text='${typeLabel}':fontcolor=white:fontsize=${labelFontSize}:x=(w-text_w)/2:y=${labelY}`;
       const drawPrompt = `drawtext=text='${promptText}':fontcolor=white@0.7:fontsize=${promptFontSize}:x=(w-text_w)/2:y=${promptY}`;
-      await $`ffmpeg -y -f lavfi -i ${colorInput} -vf ${drawLabel},${drawPrompt} -frames:v 1 -update 1 ${outputPath}`.quiet();
+      ffmpegResult =
+        await $`ffmpeg -y -f lavfi -i ${colorInput} -vf ${drawLabel},${drawPrompt} -frames:v 1 -update 1 ${outputPath}`
+          .quiet()
+          .nothrow();
     } else {
       const colorInput = `color=c=0x${hexColor}:s=${width}x${height}:d=${duration}:r=30`;
       const labelY = `(h/2)-${labelFontSize}`;
       const promptY = `(h/2)+${Math.floor(labelFontSize * 0.5)}`;
       const drawLabel = `drawtext=text='${typeLabel}':fontcolor=white:fontsize=${labelFontSize}:x=(w-text_w)/2:y=${labelY}`;
       const drawPrompt = `drawtext=text='${promptText}':fontcolor=white@0.7:fontsize=${promptFontSize}:x=(w-text_w)/2:y=${promptY}`;
-      await $`ffmpeg -y -f lavfi -i ${colorInput} -vf ${drawLabel},${drawPrompt} -c:v libx264 -preset ultrafast -pix_fmt yuv420p ${outputPath}`.quiet();
+      ffmpegResult =
+        await $`ffmpeg -y -f lavfi -i ${colorInput} -vf ${drawLabel},${drawPrompt} -c:v libx264 -preset ultrafast -pix_fmt yuv420p ${outputPath}`
+          .quiet()
+          .nothrow();
+    }
+
+    if (ffmpegResult.exitCode !== 0) {
+      const stderr = ffmpegResult.stderr.toString().trim();
+      throw new Error(
+        `ffmpeg placeholder failed (exit ${ffmpegResult.exitCode}): ${stderr || "unknown error"}`,
+      );
     }
 
     const data = await Bun.file(outputPath).bytes();

package/src/ai-sdk/providers/editly/backends/local.ts

@@ -1,3 +1,5 @@
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 import { $ } from "bun";
 import { File } from "../../../file";
 import type {
@@ -86,14 +88,20 @@ export class LocalBackend implements FFmpegBackend {
       outputPath,
     ];
 
+    // Ensure the output directory exists (ffmpeg cannot create directories)
+    mkdirSync(dirname(outputPath), { recursive: true });
+
     if (verbose) {
       console.log("ffmpeg", ffmpegArgs.join(" "));
     }
 
-    const result = await $`ffmpeg ${ffmpegArgs}`.quiet();
+    const result = await $`ffmpeg ${ffmpegArgs}`.quiet().nothrow();
 
     if (result.exitCode !== 0) {
-      throw new Error(`ffmpeg failed with exit code ${result.exitCode}`);
+      const stderr = result.stderr.toString().trim();
+      throw new Error(
+        `ffmpeg failed (exit ${result.exitCode}): ${stderr || "unknown error"}`,
+      );
     }
 
     return { output: { type: "file", path: outputPath } };

package/src/ai-sdk/providers/editly/editly.test.ts

@@ -1409,4 +1409,114 @@ describe("editly", () => {
       }),
     ).rejects.toThrow("produced no video output");
   });
+
+  // Per-clip overlay tests (feature/per-clip-overlay)
+
+  test("clip-local video overlay with start/stop timing", async () => {
+    const outPath = "output/editly-test-clip-overlay-timing.mp4";
+    if (existsSync(outPath)) unlinkSync(outPath);
+
+    await editly({
+      outPath,
+      width: 1280,
+      height: 720,
+      fps: 30,
+      clips: [
+        {
+          duration: 4,
+          layers: [
+            { type: "fill-color", color: "#1a1a2e" },
+            {
+              type: "video",
+              path: VIDEO_1,
+              width: "30%",
+              height: "30%",
+              left: "68%",
+              top: "2%",
+              start: 1,
+              stop: 3,
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(existsSync(outPath)).toBe(true);
+    const info = await ffprobe(outPath);
+    expect(info.duration).toBeCloseTo(4, 0);
+  });
+
+  test("clip-local image overlay with start/stop timing", async () => {
+    const outPath = "output/editly-test-clip-image-overlay-timing.mp4";
+    if (existsSync(outPath)) unlinkSync(outPath);
+
+    await editly({
+      outPath,
+      width: 1280,
+      height: 720,
+      fps: 30,
+      clips: [
+        {
+          duration: 4,
+          layers: [
+            { type: "fill-color", color: "#1a1a2e" },
+            {
+              type: "image-overlay",
+              path: IMAGE_SQUARE,
+              position: "top-right",
+              width: "20%",
+              start: 1,
+              stop: 3,
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(existsSync(outPath)).toBe(true);
+    const info = await ffprobe(outPath);
+    expect(info.duration).toBeCloseTo(4, 0);
+  });
+
+  test("clip-local overlay only appears in its clip, not in others", async () => {
+    const outPath = "output/editly-test-clip-overlay-scoped.mp4";
+    if (existsSync(outPath)) unlinkSync(outPath);
+
+    await editly({
+      outPath,
+      width: 1280,
+      height: 720,
+      fps: 30,
+      clips: [
+        {
+          duration: 2,
+          layers: [{ type: "fill-color", color: "#ff0000" }],
+          transition: { name: "fade", duration: 0.3 },
+        },
+        {
+          duration: 2,
+          layers: [
+            { type: "fill-color", color: "#00ff00" },
+            {
+              type: "image-overlay",
+              path: IMAGE_SQUARE,
+              position: "center",
+              width: "30%",
+              start: 0.5,
+              stop: 1.5,
+            },
+          ],
+          transition: { name: "fade", duration: 0.3 },
+        },
+        {
+          duration: 2,
+          layers: [{ type: "fill-color", color: "#0000ff" }],
+        },
+      ],
+    });
+
+    expect(existsSync(outPath)).toBe(true);
+    const info = await ffprobe(outPath);
+    expect(info.duration).toBeGreaterThan(4);
+  });
 });

package/src/ai-sdk/providers/editly/index.ts

@@ -168,6 +168,15 @@ function isImageOverlayLayer(layer: Layer): boolean {
   return layer.type === "image-overlay";
 }
 
+/**
+ * Clip-local image overlay: has start/stop timing (from <Overlay start end> inside <Clip>).
+ * These should be composited within their clip with enable expressions.
+ */
+function isClipLocalImageOverlay(layer: Layer): boolean {
+  if (!isImageOverlayLayer(layer)) return false;
+  return layer.start !== undefined || layer.stop !== undefined;
+}
+
 function isOverlayLayer(layer: Layer): boolean {
   return isVideoOverlayLayer(layer) || isImageOverlayLayer(layer);
 }
@@ -216,6 +225,10 @@ function buildBaseClipFilter(
     (l) => l && isClipLocalVideoOverlay(l),
   ) as VideoLayer[];
 
+  const clipLocalImageOverlays = clip.layers.filter(
+    (l) => l && isClipLocalImageOverlay(l),
+  ) as ImageOverlayLayer[];
+
   for (let i = 0; i < baseLayers.length; i++) {
     const layer = baseLayers[i];
     if (!layer) continue;
@@ -253,7 +266,10 @@ function buildBaseClipFilter(
     }
   }
 
-  if (!baseLabel && clipLocalOverlays.length > 0) {
+  if (
+    !baseLabel &&
+    (clipLocalOverlays.length > 0 || clipLocalImageOverlays.length > 0)
+  ) {
     const fillFilter = getFillColorFilter(
       { type: "fill-color", color: "#000000" },
       inputIdx,
@@ -295,12 +311,50 @@ function buildBaseClipFilter(
       width,
       height,
       outputLabel,
+      clip.duration,
     );
     filters.push(positionFilter);
     baseLabel = outputLabel;
     inputIdx++;
   }
 
+  // Composite clip-local image overlays (from <Overlay start end> inside <Clip>)
+  for (let i = 0; i < clipLocalImageOverlays.length; i++) {
+    const layer = clipLocalImageOverlays[i];
+    if (!layer) continue;
+
+    if (!baseLabel) {
+      throw new Error(
+        `Clip ${clipIndex} is missing a base layer for image overlay placement`,
+      );
+    }
+
+    const imgFilter = getImageOverlayFilter(
+      layer,
+      inputIdx,
+      width,
+      height,
+      clip.duration,
+    );
+
+    inputs.push(layer.path);
+    filters.push(imgFilter.filterComplex);
+
+    const outputLabel = `clip${clipIndex}imgov${i}`;
+    const posFilter = getImageOverlayPositionFilter(
+      baseLabel,
+      imgFilter.outputLabel,
+      layer,
+      width,
+      height,
+      outputLabel,
+      clip.duration,
+    );
+    filters.push(posFilter);
+    baseLabel = outputLabel;
+    inputIdx++;
+  }
+
   if (!baseLabel) {
     throw new Error(
       `Clip ${clipIndex} produced no video output — ensure it has at least one visual layer (video, image, or fill-color)`,
@@ -356,7 +410,12 @@ function collectImageOverlays(
 
   for (const clip of clips) {
     for (const layer of clip.layers) {
-      if (layer && isImageOverlayLayer(layer)) {
+      // Skip clip-local image overlays (with start/stop) — they are composited per-clip
+      if (
+        layer &&
+        isImageOverlayLayer(layer) &&
+        !isClipLocalImageOverlay(layer)
+      ) {
         const imgLayer = layer as ImageOverlayLayer;
         const key = `${imgLayer.path}:${JSON.stringify(imgLayer.position ?? "")}:${imgLayer.width ?? ""}:${imgLayer.height ?? ""}`;
         const existing = overlays.get(key);

package/src/ai-sdk/providers/editly/layers.ts

@@ -247,6 +247,7 @@ export function getOverlayFilter(
   width: number,
   height: number,
   outputLabel: string,
+  clipDuration?: number,
 ): string {
   const baseX = layer.left !== undefined ? parseSize(layer.left, width) : 0;
   const baseY = layer.top !== undefined ? parseSize(layer.top, height) : 0;
@@ -266,7 +267,8 @@ export function getOverlayFilter(
     yExpr = `${baseY}-overlay_h`;
   }
 
-  return `[${baseLabel}][${overlayLabel}]overlay=${xExpr}:${yExpr}:shortest=1[${outputLabel}]`;
+  const enable = getEnableExpr(layer.start, layer.stop, clipDuration ?? 9999);
+  return `[${baseLabel}][${overlayLabel}]overlay=${xExpr}:${yExpr}:shortest=1${enable}[${outputLabel}]`;
 }
 
 export function getImageFilter(
@@ -594,9 +596,11 @@ export function getImageOverlayPositionFilter(
   width: number,
   height: number,
   outputLabel: string,
+  clipDuration?: number,
 ): string {
   const { x, y } = resolvePositionForOverlay(layer.position, width, height);
-  return `[${baseLabel}][${overlayLabel}]overlay=${x}:${y}:shortest=1[${outputLabel}]`;
+  const enable = getEnableExpr(layer.start, layer.stop, clipDuration ?? 9999);
+  return `[${baseLabel}][${overlayLabel}]overlay=${x}:${y}:shortest=1${enable}[${outputLabel}]`;
 }
 
 function getEnableExpr(

package/src/cli/commands/render.tsx

@@ -1,7 +1,7 @@
 /** @jsxImportSource react */
 
-import { existsSync, mkdirSync } from "node:fs";
-import { resolve } from "node:path";
+import { existsSync, mkdirSync, unlinkSync } from "node:fs";
+import { dirname, resolve } from "node:path";
 import { defineCommand } from "citty";
 import { Box, Text } from "ink";
 import { render } from "../../react/render";
@@ -11,12 +11,22 @@ import { renderStatic } from "../ui/render.ts";
 
 const AUTO_IMPORTS = `/** @jsxImportSource vargai */
 import { Captions, Clip, Image, Music, Overlay, Packshot, Render, Slider, Speech, Split, Subtitle, Swipe, TalkingHead, Title, Video, Grid } from "vargai/react";
-import { fal, elevenlabs, replicate } from "vargai/ai";
+import { fal, elevenlabs, replicate, varg } from "vargai/ai";
 `;
 
 async function detectDefaultModels(): Promise<DefaultModels | undefined> {
   const defaults: DefaultModels = {};
 
+  // Gateway provider — single key for all models (recommended)
+  if (process.env.VARG_API_KEY) {
+    const { varg } = await import("../../ai-sdk/providers/varg");
+    defaults.image = varg.imageModel("nano-banana-pro");
+    defaults.video = varg.videoModel("kling-v3");
+    defaults.speech = varg.speechModel("eleven_v3");
+    defaults.music = varg.musicModel("music_v1");
+  }
+
+  // Direct providers override gateway when available
   const falKey = process.env.FAL_API_KEY ?? process.env.FAL_KEY;
   if (falKey) {
     const { fal } = await import("../../ai-sdk/providers/fal");
@@ -26,7 +36,7 @@ async function detectDefaultModels(): Promise<DefaultModels | undefined> {
 
   if (process.env.ELEVENLABS_API_KEY) {
     const { elevenlabs } = await import("../../ai-sdk/providers/elevenlabs");
-    defaults.speech = elevenlabs.speechModel("eleven_multilingual_v2");
+    defaults.speech = elevenlabs.speechModel("eleven_v3");
     defaults.music = elevenlabs.musicModel("music_v1");
   }
 
@@ -73,13 +83,23 @@ async function loadComponent(filePath: string): Promise<VargElement> {
 
   if (hasVargaiImport) {
     const tmpFile = `${tmpDir}/${Date.now()}.tsx`;
-    await Bun.write(tmpFile, source);
+    // Resolve @jsxImportSource to absolute path so it works from the cache dir
+    const runtimeDir = resolve(pkgDir, "src/react/runtime");
+    const resolvedSource = source.replace(
+      /@jsxImportSource\s+vargai/,
+      `@jsxImportSource ${runtimeDir}`,
+    );
+    await Bun.write(tmpFile, resolvedSource);
 
     try {
       const mod = await import(tmpFile);
       return resolveDefaultExport(mod);
     } finally {
-      (await Bun.file(tmpFile).exists()) && (await Bun.write(tmpFile, ""));
+      try {
+        unlinkSync(tmpFile);
+      } catch {
+        /* ignore cleanup errors */
+      }
     }
   }
 
@@ -96,7 +116,11 @@ async function loadComponent(filePath: string): Promise<VargElement> {
     const mod = await import(tmpFile);
     return resolveDefaultExport(mod);
   } finally {
-    (await Bun.file(tmpFile).exists()) && (await Bun.write(tmpFile, ""));
+    try {
+      unlinkSync(tmpFile);
+    } catch {
+      /* ignore cleanup errors */
+    }
   }
 }
 
@@ -166,6 +190,9 @@ async function runRender(
     .pop();
   const outputPath = (args.output as string) ?? `output/${basename}.mp4`;
 
+  // Ensure the output directory exists (ffmpeg cannot create directories)
+  mkdirSync(dirname(outputPath), { recursive: true });
+
   if (!args.quiet) {
     const modeLabel = mode === "preview" ? " (fast)" : "";
     console.log(`rendering ${file} → ${outputPath}${modeLabel}`);

package/src/react/examples/omnihuman15-react-test.tsx

@@ -0,0 +1,58 @@
+/**
+ * OmniHuman v1.5 React syntax test
+ *
+ * Uses a local image + local audio file to generate a talking video.
+ *
+ * Run: bun run src/react/examples/omnihuman15-react-test.tsx
+ * Output: output/omnihuman15-react-test.mp4
+ */
+
+import { fal } from "../../ai-sdk/providers/fal";
+import { Clip, Render, render, Video } from "..";
+
+const IMAGE_PATH = "output/garry-tan-image.png";
+const AUDIO_PATH = "output/garry-tan-voice.mp3";
+
+const video = (
+  <Render width={720} height={1280}>
+    <Clip duration={5}>
+      <Video
+        model={fal.videoModel("omnihuman-v1.5")}
+        prompt={{
+          text: "friendly professional talking head, natural blinking, subtle head movement",
+          images: [IMAGE_PATH],
+          audio: AUDIO_PATH,
+        }}
+        providerOptions={{
+          fal: {
+            resolution: "720p",
+            turbo_mode: true,
+          },
+        }}
+      />
+    </Clip>
+  </Render>
+);
+
+async function main() {
+  if (!process.env.FAL_API_KEY && !process.env.FAL_KEY) {
+    console.error("ERROR: FAL_API_KEY/FAL_KEY not found in environment");
+    process.exit(1);
+  }
+
+  const result = await render(video, {
+    output: "output/omnihuman15-react-test.mp4",
+    cache: ".cache/ai",
+  });
+
+  console.log(
+    `ok: output/omnihuman15-react-test.mp4 (${(result.video.byteLength / 1024 / 1024).toFixed(2)} MB)`,
+  );
+}
+
+if (import.meta.main) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/src/react/renderers/clip.ts

@@ -12,6 +12,7 @@ import type {
   ClipProps,
   ImageProps,
   MusicProps,
+  OverlayProps,
   SpeechProps,
   VargElement,
   VargNode,
@@ -231,11 +232,79 @@ async function renderClipLayers(
       }
 
       case "overlay": {
-        console.warn(
-          "[varg] Warning: <Overlay> placed inside <Clip> will be ignored. " +
-            "Move <Overlay> to be a sibling of <Clip> inside <Render>. " +
-            "See: https://github.com/vargHQ/sdk/issues/45",
-        );
+        const overlayProps = element.props as OverlayProps;
+        for (const overlayChild of element.children) {
+          if (
+            !overlayChild ||
+            typeof overlayChild !== "object" ||
+            !("type" in overlayChild)
+          )
+            continue;
+          const overlayChildElement = overlayChild as VargElement;
+
+          if (overlayChildElement.type === "image") {
+            const hasPosition =
+              overlayProps.left !== undefined ||
+              overlayProps.top !== undefined ||
+              overlayProps.width !== undefined ||
+              overlayProps.height !== undefined;
+
+            pending.push({
+              type: "async",
+              promise: renderImage(
+                overlayChildElement as VargElement<"image">,
+                ctx,
+              )
+                .then((file) => ctx.backend.resolvePath(file))
+                .then((path) =>
+                  hasPosition
+                    ? ({
+                        type: "image-overlay",
+                        path,
+                        width: overlayProps.width,
+                        height: overlayProps.height,
+                        position: {
+                          x: overlayProps.left ?? 0,
+                          y: overlayProps.top ?? 0,
+                        },
+                        start: overlayProps.start,
+                        stop: overlayProps.end,
+                      } as ImageOverlayLayer)
+                    : ({
+                        type: "image",
+                        path,
+                        start: overlayProps.start,
+                        stop: overlayProps.end,
+                      } as ImageLayer),
+                ),
+            });
+          } else if (overlayChildElement.type === "video") {
+            pending.push({
+              type: "async",
+              promise: renderVideo(
+                overlayChildElement as VargElement<"video">,
+                ctx,
+              )
+                .then((file) => ctx.backend.resolvePath(file))
+                .then(
+                  (path) =>
+                    ({
+                      type: "video",
+                      path,
+                      mixVolume: overlayProps.keepAudio
+                        ? (overlayProps.volume ?? 1)
+                        : 0,
+                      left: overlayProps.left,
+                      top: overlayProps.top,
+                      width: overlayProps.width,
+                      height: overlayProps.height,
+                      start: overlayProps.start,
+                      stop: overlayProps.end,
+                    }) as VideoLayer,
+                ),
+            });
+          }
+        }
         break;
       }
     }

package/src/react/renderers/render.ts

@@ -246,12 +246,24 @@ export async function renderRoot(
     // offsets (they all start at the container's position in the timeline).
     const firstLeafClipIndex = clipIndexCounter; // before recursion increments it
 
-    // Recurse into child clips
+    // Collect overlays from container level — these get injected into each
+    // child clip so the overlay appears across all inner clips.
+    const containerOverlays: VargElement[] = [];
+    for (const el of nonClipChildren) {
+      if (el.type === "overlay") {
+        containerOverlays.push(el);
+      }
+    }
+
+    // Recurse into child clips, injecting container-level overlays
     for (const childClip of childClips) {
+      if (containerOverlays.length > 0) {
+        childClip.children = [...childClip.children, ...containerOverlays];
+      }
       flattenClip(childClip);
     }
 
-    // Process non-clip children at the container level
+    // Process remaining non-clip children at the container level
     for (const el of nonClipChildren) {
       if (el.type === "captions") {
         hoistedCaptions.push({
@@ -264,6 +276,7 @@ export async function renderRoot(
           clipIndex: firstLeafClipIndex,
         });
       }
+      // overlay: already handled above (distributed to child clips)
       // Image/Video at container level: not supported yet (would need
       // background layer spanning all child clips — a future feature)
     }

package/src/react/resolve.ts

@@ -276,7 +276,16 @@ async function sliceAudio(
 
   // Fallback: no backend (top-level `await` outside render()) — use local ffmpeg directly.
   const inputPath = await file.toTempFile();
-  await $`ffmpeg -y -ss ${start} -i ${inputPath} -t ${duration} -acodec libmp3lame -q:a 2 ${outPath}`.quiet();
+  const sliceResult =
+    await $`ffmpeg -y -ss ${start} -i ${inputPath} -t ${duration} -acodec libmp3lame -q:a 2 ${outPath}`
+      .quiet()
+      .nothrow();
+  if (sliceResult.exitCode !== 0) {
+    const stderr = sliceResult.stderr.toString().trim();
+    throw new Error(
+      `ffmpeg audio slice failed (exit ${sliceResult.exitCode}): ${stderr || "unknown error"}`,
+    );
+  }
 
   const sliced = await Bun.file(outPath).arrayBuffer();
   try {

package/src/react/types.ts

@@ -121,6 +121,10 @@ export interface ClipProps extends BaseProps {
 }
 
 export interface OverlayProps extends BaseProps, PositionProps, AudioProps {
+  /** Start time in seconds (relative to parent clip). Only used when inside a <Clip>. */
+  start?: number;
+  /** End time in seconds (relative to parent clip). Only used when inside a <Clip>. */
+  end?: number;
   children?: VargNode;
 }
 

package/src/react/warnings.test.ts

@@ -3,7 +3,7 @@ import { existsSync, unlinkSync, writeFileSync } from "node:fs";
 
 describe("warnings", () => {
   test(
-    "issue #45: warns when Overlay is placed inside Clip",
+    "issue #45: Overlay inside Clip renders without warning",
     async () => {
       const script = `
 import { Clip, Image, Overlay, Render, render } from "./src/react/index";
@@ -45,8 +45,10 @@ await render(
       unlinkSync(tmpFile);
 
       const output = stdout + stderr;
-      expect(output).toContain("Overlay");
-      expect(output).toContain("Clip");
+      // <Overlay> inside <Clip> is now valid — no warning should be emitted
+      expect(output).not.toContain(
+        "<Overlay> placed inside <Clip> will be ignored",
+      );
       expect(existsSync("output/test-issue-45.mp4")).toBe(true);
     },
     { timeout: 15000 },

package/.claude/settings.local.json

@@ -1,7 +0,0 @@
-{
-  "permissions": {
-    "allow": ["Bash(bun run:*)", "WebFetch(domain:fal.ai)"],
-    "deny": [],
-    "ask": []
-  }
-}

package/.env.example

@@ -1,33 +0,0 @@
-# fal.ai api key
-FAL_API_KEY=fal_xxx
-
-# higgsfield credentials
-HIGGSFIELD_API_KEY=hf_xxx
-HIGGSFIELD_SECRET=secret_xxx
-
-# elevenlabs api key
-ELEVENLABS_API_KEY=el_xxx
-
-# groq api key (ultra-fast whisper transcription)
-GROQ_API_KEY=gsk_xxx
-
-# fireworks api key (word-level transcription with timestamps)
-FIREWORKS_API_KEY=fw_xxx
-
-# cloudflare r2 / s3 storage
-CLOUDFLARE_R2_API_URL=https://xxx.r2.cloudflarestorage.com
-CLOUDFLARE_ACCESS_KEY_ID=xxx
-CLOUDFLARE_ACCESS_SECRET=xxx
-CLOUDFLARE_R2_BUCKET=m
-
-# replicate (optional)
-REPLICATE_API_TOKEN=r8_xxx
-
-# apify (web scraping actors)
-APIFY_TOKEN=apify_api_xxx
-
-# decart ai (real-time & batch video/image)
-DECART_API_KEY=decart_xxx
-
-# together ai (fast flux-schnell, no queue)
-TOGETHER_API_KEY=together_xxx

package/.github/workflows/ci.yml

@@ -1,23 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-jobs:
-  lint-and-format:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - name: Install dependencies
-        run: bun install
-
-      - name: Check
-        run: bun run check

package/.husky/README.md

@@ -1,102 +0,0 @@
-# Git Hooks Configuration
-
-This project uses [Husky](https://typicode.github.io/husky/) to manage Git hooks for maintaining code quality and security.
-
-## Installed Hooks
-
-### `pre-commit`
-Runs before each commit:
-- **Gitleaks** - Scans staged files for secrets and credentials
-- **Lint-staged** - Runs Biome linter/formatter on staged files
-
-### `commit-msg`
-Validates commit messages:
-- **Commitlint** - Enforces [Conventional Commits](https://www.conventionalcommits.org/) format
-
-### `pre-push`
-Runs before pushing to remote:
-- **TypeScript type checking** - Ensures no type errors before push
-
-## Commit Message Format
-
-Follow the Conventional Commits specification:
-
-```
-<type>(<scope>): <subject>
-
-<body>
-
-<footer>
-```
-
-### Types
-- `feat`: New feature
-- `fix`: Bug fix
-- `docs`: Documentation changes
-- `style`: Code style changes (formatting, etc)
-- `refactor`: Code refactoring
-- `perf`: Performance improvements
-- `test`: Test changes
-- `build`: Build system changes
-- `ci`: CI/CD changes
-- `chore`: Other changes
-- `revert`: Revert previous commit
-
-### Examples
-```bash
-feat: add video generation API
-fix(transcribe): handle empty audio files
-docs: update installation guide
-refactor: simplify audio processing pipeline
-```
-
-## Available Scripts
-
-```bash
-# Run linter
-bun run lint
-
-# Format code
-bun run format
-
-# Type check
-bun run type-check
-
-# Check bundle size
-bun run size
-```
-
-## Bypassing Hooks
-
-⚠️ **Not recommended** - Only use when absolutely necessary:
-
-```bash
-# Skip all hooks
-git commit --no-verify -m "emergency fix"
-
-# Skip specific checks by setting env vars
-HUSKY=0 git commit -m "skip all hooks"
-```
-
-## Troubleshooting
-
-If hooks aren't running:
-
-```bash
-# Reinstall hooks
-rm -rf .husky/_
-bun run prepare
-chmod +x .husky/pre-commit .husky/commit-msg .husky/pre-push
-```
-
-## Size Limits
-
-Bundle size limits are defined in `.size-limit.json`. Check size before publishing:
-
-```bash
-bun run size
-```
-
-
-
-

package/.husky/commit-msg

@@ -1,6 +0,0 @@
-# Check commit message format
-bunx --no -- commitlint --edit ${1}
-
-
-
-

package/.husky/pre-commit

@@ -1,9 +0,0 @@
-# Check for secrets with gitleaks
-gitleaks protect --staged
-
-# Run linters on staged files
-bunx lint-staged
-
-
-
-

package/.husky/pre-push

@@ -1,6 +0,0 @@
-# Run type checking before push
-bun run type-check
-
-
-
-