vargai 0.4.0-alpha32 → 0.4.0-alpha33

package/package.json

@@ -69,7 +69,7 @@
     "vargai": "^0.4.0-alpha11",
     "zod": "^4.2.1"
   },
-  "version": "0.4.0-alpha32",
+  "version": "0.4.0-alpha33",
   "exports": {
     ".": "./src/index.ts",
     "./ai": "./src/ai-sdk/index.ts",

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

@@ -126,7 +126,13 @@ export class RendiBackend implements FFmpegBackend {
       if (placeholder) {
         return placeholder;
       }
-      return arg;
+      let result = arg;
+      for (const [url, ph] of pathToPlaceholder) {
+        if (result.includes(url)) {
+          result = result.replaceAll(url, ph);
+        }
+      }
+      return result;
     });
 
     const filteredArgs = this.stripInternalFlags(commandArgs);

package/src/react/renderers/burn-captions.ts

@@ -0,0 +1,107 @@
+import { localBackend } from "@/ai-sdk/providers/editly";
+import type {
+  FFmpegBackend,
+  FFmpegOutput,
+} from "../../ai-sdk/providers/editly/backends/types";
+import { uploadBuffer } from "../../providers/storage";
+
+/**
+ * Resolves an FFmpegOutput to a string path/URL, uploading local files if needed.
+ *
+ * - URL input → returns URL as-is
+ * - File input + shouldUpload=false → returns local path
+ * - File input + shouldUpload=true → uploads to storage, returns URL
+ */
+async function resolveInputPathMaybeUpload(
+  input: FFmpegOutput,
+  options: { shouldUpload: boolean },
+): Promise<string> {
+  if (input.type === "url") return input.url;
+  if (!options.shouldUpload) return input.path;
+
+  const buffer = await Bun.file(input.path).arrayBuffer();
+  return uploadBuffer(
+    buffer,
+    `tmp/${Date.now()}-${input.path.split("/").pop()}`,
+    "application/octet-stream",
+  );
+}
+
+export interface CaptionOverlayOptions {
+  video: FFmpegOutput;
+  assPath: string;
+  outputPath: string;
+  backend?: FFmpegBackend;
+  verbose?: boolean;
+}
+
+/**
+ * Burns ASS subtitle captions onto a video using FFmpeg.
+ *
+ * {@link burnCaptions} composites the subtitle file directly into the video frames,
+ * producing a new video with hardcoded captions. Supports both local and cloud
+ * FFmpeg backends - when using a cloud backend, input files are automatically
+ * uploaded to storage.
+ *
+ * @param options - Configuration for the caption burn operation
+ * @param options.video - Source video as {@link FFmpegOutput} (file path or URL)
+ * @param options.assPath - Path to the ASS subtitle file to burn
+ * @param options.outputPath - Destination path for the output video (defaults to "output.mp4")
+ * @param options.backend - Optional {@link FFmpegBackend} for cloud processing; uses local FFmpeg if omitted
+ * @param options.verbose - Enable verbose FFmpeg logging
+ *
+ * @returns Promise resolving to {@link FFmpegOutput} containing the path or URL of the captioned video
+ *
+ * @throws May throw if FFmpeg execution fails, input files are missing, or upload fails for cloud backends
+ *
+ * @example
+ * ```ts
+ * const result = await burnCaptions({
+ *   video: { type: "file", path: "input.mp4" },
+ *   assPath: "captions.ass",
+ *   outputPath: "output-with-captions.mp4",
+ * });
+ * ```
+ */
+export async function burnCaptions(
+  options: CaptionOverlayOptions,
+): Promise<FFmpegOutput> {
+  const { video, assPath, outputPath = "output.mp4", verbose } = options;
+  const captions: FFmpegOutput = { type: "file", path: assPath };
+
+  const isCloud = options.backend !== undefined;
+
+  const videoInput = await resolveInputPathMaybeUpload(video, {
+    shouldUpload: isCloud,
+  });
+  const assInput = await resolveInputPathMaybeUpload(captions, {
+    shouldUpload: isCloud,
+  });
+
+  const backend = options.backend ?? localBackend;
+
+  // FFmpeg filter syntax requires escaping backslashes and colons
+  const escapedAssPath = assInput.replace(/\\/g, "\\\\").replace(/:/g, "\\:");
+
+  const result = await backend.run({
+    args: [
+      "-i",
+      videoInput,
+      "-vf",
+      `subtitles=${escapedAssPath}`,
+      "-crf",
+      "18",
+      "-preset",
+      "fast",
+      "-c:a",
+      "copy",
+      "-y",
+      outputPath,
+    ],
+    inputs: [videoInput, assInput],
+    outputPath,
+    verbose,
+  });
+
+  return result.output;
+}

package/src/react/renderers/render.ts

@@ -14,6 +14,7 @@ import type {
   Layer,
   VideoLayer,
 } from "../../ai-sdk/providers/editly/types";
+
 import type {
   CaptionsProps,
   ClipProps,
@@ -25,6 +26,7 @@ import type {
   SpeechProps,
   VargElement,
 } from "../types";
+import { burnCaptions } from "./burn-captions";
 import { renderCaptions } from "./captions";
 import { renderClip } from "./clip";
 import type { RenderContext } from "./context";
@@ -271,7 +273,7 @@ export async function renderRoot(
   const editlyTaskId = addTask(progress, "editly", "ffmpeg");
   startTask(progress, editlyTaskId);
 
-  await editly({
+  const editlyResult = await editly({
     outPath: tempOutPath,
     width: ctx.width,
     height: ctx.height,
@@ -280,27 +282,50 @@ export async function renderRoot(
     audioTracks: audioTracks.length > 0 ? audioTracks : undefined,
     shortest: props.shortest,
     verbose: options.verbose,
+    backend: options.backend,
   });
 
   completeTask(progress, editlyTaskId);
 
+  let output = editlyResult.output;
+
   if (hasCaptions && captionsResult) {
     const captionsTaskId = addTask(progress, "captions", "ffmpeg");
     startTask(progress, captionsTaskId);
 
-    const { $ } = await import("bun");
-    await $`ffmpeg -y -i ${tempOutPath} -vf "ass=${captionsResult.assPath}" -crf 18 -preset slow -c:a copy ${finalOutPath}`.quiet();
+    output = await burnCaptions({
+      video: output,
+      assPath: captionsResult.assPath,
+      outputPath: finalOutPath,
+      backend: options.backend,
+      verbose: options.verbose,
+    });
+
+    if (!options.backend) {
+      ctx.tempFiles.push(tempOutPath);
+    }
 
-    ctx.tempFiles.push(tempOutPath);
     completeTask(progress, captionsTaskId);
   }
 
+  let finalBuffer: ArrayBuffer;
+  if (output.type === "url") {
+    const res = await fetch(output.url);
+    if (!res.ok)
+      throw new Error(`Failed to download final render: ${res.status}`);
+    finalBuffer = await res.arrayBuffer();
+    if (options.output) {
+      await Bun.write(options.output, finalBuffer);
+    }
+  } else {
+    finalBuffer = await Bun.file(output.path).arrayBuffer();
+  }
+
   if (!options.quiet && mode === "preview" && placeholderCount.total > 0) {
     console.log(
       `\x1b[36mℹ preview mode: ${placeholderCount.total} placeholders used (${placeholderCount.images} images, ${placeholderCount.videos} videos)\x1b[0m`,
     );
   }
 
-  const result = await Bun.file(finalOutPath).arrayBuffer();
-  return new Uint8Array(result);
+  return new Uint8Array(finalBuffer);
 }

package/src/react/types.ts

@@ -1,4 +1,5 @@
 import type { ImageModelV3, SpeechModelV3 } from "@ai-sdk/provider";
+import type { FFmpegBackend } from "@/ai-sdk/providers/editly/backends";
 import type { MusicModelV3 } from "../ai-sdk/music-model";
 import type {
   CropPosition,
@@ -260,6 +261,7 @@ export interface RenderOptions {
   verbose?: boolean;
   mode?: RenderMode;
   defaults?: DefaultModels;
+  backend?: FFmpegBackend;
 }
 
 export interface ElementPropsMap {