vargai 0.3.1 → 0.4.0-alpha.1

package/package.json

@@ -10,8 +10,9 @@
     "lint": "biome check .",
     "format": "biome format --write .",
     "type-check": "tsc --noEmit",
-    "prepare": "husky install",
-    "size": "size-limit"
+    "prepare": "husky || true",
+    "size": "size-limit",
+    "studio": "bun run src/studio/index.ts"
   },
   "lint-staged": {
     "*.{js,ts,tsx}": [
@@ -32,11 +33,12 @@
     "lint-staged": "^16.2.7"
   },
   "peerDependencies": {
-    "typescript": "^5",
-    "ai": "^6.0.0"
+    "typescript": "^5"
   },
   "dependencies": {
     "@ai-sdk/fal": "^1.0.23",
+    "@ai-sdk/fireworks": "^2.0.16",
+    "@ai-sdk/groq": "^3.0.12",
     "@ai-sdk/openai": "^3.0.9",
     "@ai-sdk/provider": "^3.0.2",
     "@ai-sdk/replicate": "^2.0.5",
@@ -60,11 +62,14 @@
     "replicate": "^1.4.0",
     "zod": "^4.2.1"
   },
-  "version": "0.3.1",
+  "version": "0.4.0-alpha.1",
   "exports": {
     ".": "./src/index.ts",
+    "./ai": "./src/ai-sdk/index.ts",
     "./core": "./src/core/index.ts",
     "./providers": "./src/providers/index.ts",
-    "./definitions": "./src/definitions/index.ts"
+    "./definitions": "./src/definitions/index.ts",
+    "./react": "./src/react/index.ts",
+    "./studio": "./src/studio/index.ts"
   }
 }

package/src/ai-sdk/index.ts

@@ -25,25 +25,6 @@ export {
   type GenerateVideoResult,
   generateVideo,
 } from "./generate-video";
-export {
-  generatePlaceholder,
-  type ImagePlaceholderFallbackOptions,
-  imagePlaceholderFallbackMiddleware,
-  type MusicModelMiddleware,
-  type MusicPlaceholderFallbackOptions,
-  musicPlaceholderFallbackMiddleware,
-  type PlaceholderFallbackOptions,
-  type PlaceholderOptions,
-  type PlaceholderResult,
-  placeholderFallbackMiddleware,
-  type RenderMode,
-  type VideoModelMiddleware,
-  withImagePlaceholderFallback,
-  withMusicPlaceholderFallback,
-  withPlaceholderFallback,
-  wrapMusicModel,
-  wrapVideoModel,
-} from "./middleware";
 export type {
   MusicModelV3,
   MusicModelV3CallOptions,
@@ -61,8 +42,8 @@ export {
   type ElevenLabsProvider,
   elevenlabs,
   VOICES,
-} from "./providers/elevenlabs";
-export { createFal, type FalProvider, fal } from "./providers/fal";
+} from "./providers/elevenlabs-provider";
+export { createFal, type FalProvider, fal } from "./providers/fal-provider";
 export {
   createHiggsfield,
   type HiggsfieldImageModelSettings,

package/src/cli/commands/index.ts

@@ -1,9 +1,6 @@
-/**
- * CLI commands exports
- */
-
 export { findCmd, showFindHelp } from "./find.tsx";
 export { helpCmd, showHelp } from "./help.tsx";
 export { listCmd, showListHelp } from "./list.tsx";
+export { renderCmd } from "./render.tsx";
 export { runCmd, showRunHelp, showTargetHelp } from "./run.tsx";
 export { showWhichHelp, whichCmd } from "./which.tsx";

package/src/cli/commands/render.tsx

@@ -0,0 +1,71 @@
+import { defineCommand } from "citty";
+import { render } from "../../react/render";
+import type { VargElement } from "../../react/types";
+
+export const renderCmd = defineCommand({
+  meta: {
+    name: "render",
+    description: "render a react component to video",
+  },
+  args: {
+    file: {
+      type: "positional",
+      description: "component file (.tsx)",
+      required: true,
+    },
+    output: {
+      type: "string",
+      alias: "o",
+      description: "output path",
+    },
+    cache: {
+      type: "string",
+      alias: "c",
+      description: "cache directory",
+      default: ".cache/ai",
+    },
+    quiet: {
+      type: "boolean",
+      alias: "q",
+      description: "minimal output",
+      default: false,
+    },
+  },
+  async run({ args }) {
+    const file = args.file as string;
+
+    if (!file) {
+      console.error("usage: varg render <component.tsx> [-o output.mp4]");
+      process.exit(1);
+    }
+
+    const resolvedPath = Bun.resolveSync(file, process.cwd());
+    const mod = await import(resolvedPath);
+    const component: VargElement = mod.default;
+
+    if (!component || component.type !== "render") {
+      console.error("error: default export must be a <Render> element");
+      process.exit(1);
+    }
+
+    const outputPath =
+      args.output ??
+      `output/${file
+        .replace(/\.tsx?$/, "")
+        .split("/")
+        .pop()}.mp4`;
+
+    if (!args.quiet) {
+      console.log(`rendering ${file} → ${outputPath}`);
+    }
+
+    const buffer = await render(component, {
+      output: outputPath,
+      cache: args.cache,
+    });
+
+    if (!args.quiet) {
+      console.log(`done! ${buffer.byteLength} bytes → ${outputPath}`);
+    }
+  },
+});

package/src/cli/index.ts

@@ -15,6 +15,7 @@ import {
   findCmd,
   helpCmd,
   listCmd,
+  renderCmd,
   runCmd,
   showFindHelp,
   showHelp,
@@ -99,6 +100,7 @@ const main = defineCommand({
   },
   subCommands: {
     run: runCmd,
+    render: renderCmd,
     list: listCmd,
     ls: listCmd,
     find: findCmd,

package/src/react/cli.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env bun
+
+import { parseArgs } from "node:util";
+import { render } from "./render";
+import type { VargElement } from "./types";
+
+const { values, positionals } = parseArgs({
+  args: Bun.argv.slice(2),
+  options: {
+    output: { type: "string", short: "o" },
+    cache: { type: "string", short: "c", default: ".cache/ai" },
+    quiet: { type: "boolean", short: "q", default: false },
+  },
+  allowPositionals: true,
+});
+
+const [file] = positionals;
+
+if (!file) {
+  console.error("usage: bun react/cli.ts <component.tsx> [-o output.mp4]");
+  process.exit(1);
+}
+
+const resolvedPath = Bun.resolveSync(file, process.cwd());
+const mod = await import(resolvedPath);
+const component: VargElement = mod.default;
+
+if (!component || component.type !== "render") {
+  console.error("error: default export must be a <Render> element");
+  process.exit(1);
+}
+
+const outputPath =
+  values.output ??
+  `output/${file
+    .replace(/\.tsx?$/, "")
+    .split("/")
+    .pop()}.mp4`;
+
+if (!values.quiet) {
+  console.log(`rendering ${file} → ${outputPath}`);
+}
+
+const buffer = await render(component, {
+  output: outputPath,
+  cache: values.cache,
+  quiet: values.quiet,
+});
+
+if (!values.quiet) {
+  console.log(`done! ${buffer.byteLength} bytes → ${outputPath}`);
+}

package/src/react/elements.ts

@@ -0,0 +1,146 @@
+import type {
+  AnimateProps,
+  CaptionsProps,
+  ClipProps,
+  ImageProps,
+  MusicProps,
+  OverlayProps,
+  PackshotProps,
+  RenderProps,
+  SliderProps,
+  SpeechProps,
+  SplitProps,
+  SubtitleProps,
+  SwipeProps,
+  TalkingHeadProps,
+  TitleProps,
+  VargElement,
+  VargNode,
+  VideoProps,
+} from "./types";
+
+function normalizeChildren(children: unknown): VargNode[] {
+  if (children === null || children === undefined) return [];
+  if (Array.isArray(children))
+    return children.flat().flatMap(normalizeChildren);
+  return [children as VargNode];
+}
+
+function createElement<T extends VargElement["type"]>(
+  type: T,
+  props: Record<string, unknown>,
+  children: unknown,
+): VargElement<T> {
+  const { children: _, ...restProps } = props;
+  return {
+    type,
+    props: restProps,
+    children: normalizeChildren(children ?? props.children),
+  };
+}
+
+export function Render(props: RenderProps): VargElement<"render"> {
+  return createElement(
+    "render",
+    props as Record<string, unknown>,
+    props.children,
+  );
+}
+
+export function Clip(props: ClipProps): VargElement<"clip"> {
+  return createElement(
+    "clip",
+    props as Record<string, unknown>,
+    props.children,
+  );
+}
+
+export function Overlay(props: OverlayProps): VargElement<"overlay"> {
+  return createElement(
+    "overlay",
+    props as Record<string, unknown>,
+    props.children,
+  );
+}
+
+export function Image(props: ImageProps): VargElement<"image"> {
+  return createElement("image", props as Record<string, unknown>, undefined);
+}
+
+export function Video(props: VideoProps): VargElement<"video"> {
+  return createElement("video", props as Record<string, unknown>, undefined);
+}
+
+export function Animate(props: AnimateProps): VargElement<"animate"> {
+  return createElement("animate", props as Record<string, unknown>, undefined);
+}
+
+export function Speech(props: SpeechProps): VargElement<"speech"> {
+  return createElement(
+    "speech",
+    props as Record<string, unknown>,
+    props.children,
+  );
+}
+
+export function TalkingHead(
+  props: TalkingHeadProps,
+): VargElement<"talking-head"> {
+  return createElement(
+    "talking-head",
+    props as Record<string, unknown>,
+    props.children,
+  );
+}
+
+export function Title(props: TitleProps): VargElement<"title"> {
+  return createElement(
+    "title",
+    props as Record<string, unknown>,
+    props.children,
+  );
+}
+
+export function Subtitle(props: SubtitleProps): VargElement<"subtitle"> {
+  return createElement(
+    "subtitle",
+    props as Record<string, unknown>,
+    props.children,
+  );
+}
+
+export function Music(props: MusicProps): VargElement<"music"> {
+  return createElement("music", props as Record<string, unknown>, undefined);
+}
+
+export function Captions(props: CaptionsProps): VargElement<"captions"> {
+  return createElement("captions", props as Record<string, unknown>, undefined);
+}
+
+export function Split(props: SplitProps): VargElement<"split"> {
+  return createElement(
+    "split",
+    props as Record<string, unknown>,
+    props.children,
+  );
+}
+
+export function Slider(props: SliderProps): VargElement<"slider"> {
+  return createElement(
+    "slider",
+    props as Record<string, unknown>,
+    props.children,
+  );
+}
+
+export function Swipe(props: SwipeProps): VargElement<"swipe"> {
+  return createElement(
+    "swipe",
+    props as Record<string, unknown>,
+    props.children,
+  );
+}
+
+export function Packshot(props: PackshotProps): VargElement<"packshot"> {
+  return createElement("packshot", props as Record<string, unknown>, undefined);
+}

package/src/react/examples/branching.tsx

@@ -0,0 +1,66 @@
+import { elevenlabs } from "../../ai-sdk/providers/elevenlabs-provider";
+import { fal } from "../../ai-sdk/providers/fal-provider";
+import { Animate, Clip, Image, Render, Speech, Title } from "..";
+
+// Non-linear tree: multiple clips with independent branches
+// Clip 1: TalkingHead (Image -> Animate + Speech)
+// Clip 2: Split comparison (2 independent Images)
+// Clip 3: Product shot with music
+
+const character = Image({
+  prompt:
+    "friendly tech reviewer, young man with glasses, studio lighting, professional headshot",
+  model: fal.imageModel("flux-schnell"),
+});
+
+const _productBefore = Image({
+  prompt:
+    "old smartphone, cracked screen, slow, outdated design, on white background",
+  model: fal.imageModel("flux-schnell"),
+});
+
+const _productAfter = Image({
+  prompt:
+    "sleek new smartphone, edge-to-edge display, premium design, on white background",
+  model: fal.imageModel("flux-schnell"),
+});
+
+const packshot = Image({
+  prompt:
+    "smartphone floating with gradient background, product photography, premium feel",
+  model: fal.imageModel("flux-schnell"),
+});
+
+export default (
+  <Render width={1080} height={1920}>
+    {/* Clip 1: Talking head intro */}
+    <Clip duration={5}>
+      <Animate
+        image={character}
+        model={fal.videoModel("wan-2.5")}
+        motion="talking naturally, slight head movements, friendly expression"
+      />
+      <Speech voice="adam" model={elevenlabs.speechModel("turbo")}>
+        Hey everyone! Today we're looking at the biggest smartphone upgrade of
+        the year.
+      </Speech>
+    </Clip>
+
+    {/* Clip 2: Before/after comparison - branches into 2 images */}
+    <Clip duration={4} transition={{ name: "fade", duration: 0.5 }}>
+      <Image
+        prompt="split screen comparison layout"
+        model={fal.imageModel("flux-schnell")}
+      />
+      <Title position="top">Before vs After</Title>
+    </Clip>
+
+    {/* Clip 3: Product packshot */}
+    <Clip duration={3} transition={{ name: "fade", duration: 0.5 }}>
+      {packshot}
+      <Title position="bottom" color="#ffffff">
+        Available Now
+      </Title>
+    </Clip>
+  </Render>
+);

package/src/react/examples/captions-demo.tsx

@@ -0,0 +1,37 @@
+import { elevenlabs } from "../../ai-sdk/providers/elevenlabs-provider";
+import { Captions, Clip, Image, Render, render, Speech } from "..";
+
+async function main() {
+  const speech = Speech({
+    model: elevenlabs.speechModel("eleven_multilingual_v2"),
+    voice: "adam",
+    children:
+      "Hello world! This is a test of the captions system with word level timestamps.",
+  });
+
+  const video = (
+    <Render width={1080} height={1920}>
+      <Clip duration={5}>
+        <Image src="media/cyberpunk-street.png" resize="contain" />
+      </Clip>
+      <Clip duration={5}>
+        <Image src="media/cyberpunk-street.png" resize="cover" />
+      </Clip>
+      <Clip duration={5}>
+        <Image src="media/cyberpunk-street.png" />
+      </Clip>
+      <Captions src={speech} style="tiktok" />
+    </Render>
+  );
+
+  console.log("rendering captions demo with speech transcription...\n");
+
+  await render(video, {
+    output: "output/captions-demo.mp4",
+    cache: ".cache/ai",
+  });
+
+  console.log("\ndone! check output/captions-demo.mp4");
+}
+
+main().catch(console.error);

package/src/react/examples/character-video.tsx

@@ -0,0 +1,84 @@
+import { elevenlabs } from "../../ai-sdk/providers/elevenlabs-provider";
+import { fal } from "../../ai-sdk/providers/fal-provider";
+import { Animate, Clip, Image, Music, Render, render } from "..";
+
+const MADI_REF =
+  "https://s3.varg.ai/fellowers/madi/character_shots/madi_shot_03_closeup.png";
+
+// TikTok timeline structure:
+// 0-2s: HOOK - frontal close-up, grab attention
+// 2-4s: 45° medium shot + expression change
+// 4-6s: low angle or extreme close-up
+// 6-8s: high angle + new emotion
+const SCENES = [
+  {
+    // 0-2s: HOOK - frontal extreme close-up, surprised/curious expression
+    prompt:
+      "extreme close-up face shot, surprised expression with wide eyes, looking directly at camera, holding peach near lips",
+    motion:
+      "eyes widen in surprise, eyebrows raise slightly, subtle head tilt forward. Static shot, no camera movement.",
+  },
+  {
+    // 2-4s: 45° medium shot, playful grimace while eating
+    prompt:
+      "45-degree angle medium shot showing face and hands, biting into peach with exaggerated enjoyment, juice on lips, playful expression",
+    motion:
+      "turns head 45 degrees, bites into peach, juice drips down chin, hands move expressively. Slow push-in camera movement.",
+  },
+  {
+    // 4-6s: low angle (up shot), confident/powerful vibe
+    prompt:
+      "low angle shot from below, looking down at camera with confident smirk, holding peach triumphantly, dramatic perspective",
+    motion:
+      "looks down at camera with growing smile, raises peach slightly, confident head tilt. Static camera, slight lens distortion.",
+  },
+  {
+    // 6-8s: high angle (down shot), playful vulnerability + CTA energy
+    prompt:
+      "high angle shot from above, looking up at camera with playful smile, arms spread wide, peach in one hand, endearing expression",
+    motion:
+      "looks up at camera, expression shifts from neutral to excited smile, subtle wink, slight forward lean. Gentle camera tilt down.",
+  },
+];
+
+async function main() {
+  console.log("creating madi peach video (animated)...\n");
+
+  const video = (
+    <Render width={1080} height={1920}>
+      <Music
+        prompt="upbeat electronic pop, energetic female vocal chops, modern tiktok vibe, catchy melody"
+        model={elevenlabs.musicModel()}
+        duration={8}
+      />
+
+      {SCENES.map((scene) => (
+        <Clip key={scene.prompt} duration={2}>
+          <Animate
+            image={Image({
+              prompt: { text: scene.prompt, images: [MADI_REF] },
+              model: fal.imageModel("nano-banana-pro/edit"),
+              aspectRatio: "9:16",
+              resize: "cover",
+            })}
+            motion={scene.motion}
+            model={fal.videoModel("wan-2.5")}
+            duration={5}
+          />
+        </Clip>
+      ))}
+    </Render>
+  );
+
+  console.log("rendering", SCENES.length, "animated clips in parallel...");
+
+  const buffer = await render(video, {
+    output: "output/react-madi.mp4",
+    cache: ".cache/ai",
+  });
+
+  console.log(`\ndone! ${buffer.byteLength} bytes`);
+  console.log("output: output/react-madi.mp4");
+}
+
+main().catch(console.error);

package/src/react/examples/grid.tsx

@@ -0,0 +1,53 @@
+import { fal } from "../../ai-sdk/providers/fal-provider";
+import { Clip, Grid, Image, Render, render, Title } from "..";
+
+const CHARACTER_PROMPTS = [
+  { name: "Warrior", prompt: "fierce warrior with sword, armor" },
+  { name: "Mage", prompt: "mystical mage with glowing staff, robes" },
+  { name: "Rogue", prompt: "stealthy rogue with daggers, hooded" },
+  { name: "Healer", prompt: "gentle healer with staff, white robes" },
+  { name: "Archer", prompt: "skilled archer with bow, leather armor" },
+  { name: "Knight", prompt: "noble knight with shield, heavy armor" },
+  { name: "Necro", prompt: "dark necromancer with skull staff" },
+  { name: "Paladin", prompt: "holy paladin with hammer, golden armor" },
+  { name: "Bard", prompt: "charismatic bard with lute, colorful" },
+  { name: "Druid", prompt: "nature druid with wooden staff, leaves" },
+  { name: "Monk", prompt: "disciplined monk with wrapped fists" },
+  { name: "Assassin", prompt: "deadly assassin with hidden blades" },
+];
+
+async function main() {
+  console.log("creating 3x4 character grid...\n");
+
+  const baseStyle = "fantasy portrait, stylized art, vibrant colors";
+
+  const images = CHARACTER_PROMPTS.map(({ prompt }) =>
+    Image({
+      prompt: `${prompt}, ${baseStyle}`,
+      model: fal.imageModel("flux-schnell"),
+    }),
+  );
+
+  const video = (
+    <Render width={1080} height={1440}>
+      <Clip duration={5}>
+        <Grid columns={3}>{images}</Grid>
+        <Title position="bottom" color="#ffffff">
+          Fantasy Characters
+        </Title>
+      </Clip>
+    </Render>
+  );
+
+  console.log("video tree:", JSON.stringify(video, null, 2));
+
+  const buffer = await render(video, {
+    output: "output/react-grid.mp4",
+    cache: ".cache/ai",
+  });
+
+  console.log(`\ndone! ${buffer.byteLength} bytes`);
+  console.log("output: output/react-grid.mp4");
+}
+
+main().catch(console.error);

package/src/react/examples/layouts-demo.tsx

@@ -0,0 +1,57 @@
+import {
+  Clip,
+  Image,
+  Packshot,
+  Render,
+  render,
+  Slider,
+  Split,
+  Swipe,
+  Title,
+} from "..";
+
+async function main() {
+  const img1 = Image({ src: "media/cyberpunk-street.png" });
+  const img2 = Image({ src: "media/fal-coffee-shop.png" });
+  const img3 = Image({ src: "media/kirill.png" });
+
+  const video = (
+    <Render width={1280} height={720}>
+      <Clip duration={3}>
+        <Split direction="horizontal">{[img1, img2]}</Split>
+        <Title position="bottom">Split Layout</Title>
+      </Clip>
+
+      <Clip duration={4} transition={{ name: "fade", duration: 0.5 }}>
+        <Slider direction="horizontal">{[img1, img2, img3]}</Slider>
+      </Clip>
+
+      <Clip duration={4} transition={{ name: "fade", duration: 0.5 }}>
+        <Swipe direction="left" interval={1.5}>
+          {[img1, img2, img3]}
+        </Swipe>
+      </Clip>
+
+      <Clip duration={3} transition={{ name: "fade", duration: 0.5 }}>
+        <Packshot
+          background="#1a1a2e"
+          logo="media/cyberpunk-street.png"
+          logoPosition="center"
+          logoSize="50%"
+          cta="Subscribe for more!"
+          ctaColor="#FFD700"
+        />
+      </Clip>
+    </Render>
+  );
+
+  console.log("rendering layouts demo...\n");
+
+  await render(video, {
+    output: "output/layouts-demo.mp4",
+  });
+
+  console.log("\ndone! check output/layouts-demo.mp4");
+}
+
+main().catch(console.error);