vargai 0.4.0-alpha2 → 0.4.0-alpha21

package/skills/varg-video-generation/references/templates.md

@@ -0,0 +1,380 @@
+# Video Generation Templates
+
+Complete code templates for common video generation patterns.
+
+## Table of Contents
+
+1. [Simple Slideshow](#simple-slideshow)
+2. [Animated Video with Music](#animated-video-with-music)
+3. [Talking Character](#talking-character)
+4. [TikTok Multi-Clip](#tiktok-multi-clip)
+5. [Character with Consistent Style](#character-with-consistent-style)
+6. [Split Screen Comparison](#split-screen-comparison)
+
+---
+
+## Simple Slideshow
+
+**Requirements:** FAL_API_KEY only
+
+Basic image slideshow with transitions and zoom effects.
+
+```tsx
+// slideshow.tsx
+import { render, Render, Clip, Image } from "vargai/react";
+
+const SCENES = [
+  "sunset over ocean, cinematic golden hour",
+  "mountain peaks at dawn, misty atmosphere", 
+  "city skyline at night, neon lights",
+  "forest path in autumn, fallen leaves",
+];
+
+async function main() {
+  await render(
+    <Render width={1080} height={1920}>
+      {SCENES.map((prompt, i) => (
+        <Clip 
+          key={i} 
+          duration={3} 
+          transition={{ name: "fade", duration: 0.5 }}
+        >
+          <Image prompt={prompt} zoom="in" />
+        </Clip>
+      ))}
+    </Render>,
+    { output: "output/slideshow.mp4" }
+  );
+  
+  console.log("Done! output/slideshow.mp4");
+}
+
+main();
+```
+
+Run: `bun run slideshow.tsx`
+
+---
+
+## Animated Video with Music
+
+**Requirements:** FAL_API_KEY + ELEVENLABS_API_KEY
+
+Video with AI-generated animation and background music.
+
+```tsx
+// animated-video.tsx
+import { render, Render, Clip, Image, Animate, Music } from "vargai/react";
+import { fal, elevenlabs } from "vargai/ai";
+
+async function main() {
+  await render(
+    <Render width={1080} height={1920}>
+      <Music
+        prompt="upbeat electronic pop, energetic, modern tiktok vibe"
+        model={elevenlabs.musicModel()}
+        duration={10}
+        volume={0.7}
+      />
+
+      <Clip duration={5}>
+        <Animate
+          image={Image({ 
+            prompt: "cute cat sitting on windowsill, golden hour lighting",
+            model: fal.imageModel("flux-schnell")
+          })}
+          motion="cat slowly turns head, blinks, tail swishes gently"
+          model={fal.videoModel("wan-2.5")}
+          duration={5}
+        />
+      </Clip>
+
+      <Clip duration={5} transition={{ name: "fade", duration: 0.5 }}>
+        <Animate
+          image={Image({ 
+            prompt: "same cat stretching on windowsill, yawning"
+          })}
+          motion="cat stretches, yawns widely, settles back down"
+          model={fal.videoModel("wan-2.5")}
+          duration={5}
+        />
+      </Clip>
+    </Render>,
+    { output: "output/cat-video.mp4" }
+  );
+}
+
+main();
+```
+
+---
+
+## Talking Character
+
+**Requirements:** FAL_API_KEY + ELEVENLABS_API_KEY
+
+Character that speaks with animated movement.
+
+```tsx
+// talking-character.tsx
+import { render, Render, Clip, Image, Animate, Speech } from "vargai/react";
+import { fal, elevenlabs } from "vargai/ai";
+
+const CHARACTER = "friendly cartoon robot, blue metallic body, expressive LED eyes, studio background";
+
+const SCRIPT = `
+Hello! I'm your AI assistant.
+Today I'm going to show you something amazing.
+Let's create some videos together!
+`;
+
+async function main() {
+  await render(
+    <Render width={1080} height={1920}>
+      <Clip duration="auto">
+        <Animate
+          image={Image({ 
+            prompt: CHARACTER, 
+            aspectRatio: "9:16",
+            model: fal.imageModel("flux-schnell")
+          })}
+          motion="robot talking naturally, subtle head movements, eyes blink occasionally, friendly gestures"
+          model={fal.videoModel("wan-2.5")}
+        />
+        <Speech 
+          voice="adam" 
+          model={elevenlabs.speechModel("turbo")}
+        >
+          {SCRIPT}
+        </Speech>
+      </Clip>
+    </Render>,
+    { output: "output/talking-robot.mp4" }
+  );
+}
+
+main();
+```
+
+**Available voices:** `adam`, `rachel`, `bella`, `sam`, `josh`
+
+---
+
+## TikTok Multi-Clip
+
+**Requirements:** FAL_API_KEY + ELEVENLABS_API_KEY
+
+Multi-scene TikTok-style video with varied camera angles.
+
+```tsx
+// tiktok-video.tsx
+import { render, Render, Clip, Image, Animate, Music, Title } from "vargai/react";
+import { fal, elevenlabs } from "vargai/ai";
+
+const CHARACTER = "confident young woman, casual style, bright smile, modern apartment";
+
+const SCENES = [
+  { 
+    prompt: "extreme close-up face, surprised expression, wide eyes",
+    motion: "eyes widen in surprise, eyebrows raise, subtle gasp"
+  },
+  { 
+    prompt: "medium shot, laughing genuinely, hand on chest",
+    motion: "head tilts back slightly, genuine laugh, shoulders shake"
+  },
+  { 
+    prompt: "close-up, knowing smirk, raised eyebrow",
+    motion: "slow smile forms, eyebrow raises, subtle head nod"
+  },
+  { 
+    prompt: "medium shot, waving at camera, bright smile",
+    motion: "waves energetically at camera, bright smile, slight bounce"
+  },
+];
+
+async function main() {
+  await render(
+    <Render width={1080} height={1920}>
+      <Music
+        prompt="trendy tiktok music, upbeat, catchy hook, viral sound"
+        model={elevenlabs.musicModel()}
+        duration={8}
+        volume={0.6}
+      />
+
+      {SCENES.map((scene, i) => (
+        <Clip 
+          key={i} 
+          duration={2} 
+          transition={{ name: "fade", duration: 0.3 }}
+        >
+          <Animate
+            image={Image({ 
+              prompt: `${CHARACTER}, ${scene.prompt}`,
+              aspectRatio: "9:16",
+              model: fal.imageModel("flux-schnell")
+            })}
+            motion={scene.motion}
+            model={fal.videoModel("wan-2.5")}
+            duration={5}
+          />
+          {i === 0 && (
+            <Title position="bottom">POV: When it actually works</Title>
+          )}
+        </Clip>
+      ))}
+    </Render>,
+    { output: "output/tiktok-video.mp4" }
+  );
+}
+
+main();
+```
+
+---
+
+## Character with Consistent Style
+
+**Requirements:** FAL_API_KEY
+
+Reuse the same character reference for visual consistency across clips.
+
+```tsx
+// consistent-character.tsx
+import { render, Render, Clip, Image, Animate } from "vargai/react";
+import { fal } from "vargai/ai";
+
+async function main() {
+  // Define character once - same reference = same generated image
+  const character = Image({ 
+    prompt: "cute cartoon fox, orange fur, big eyes, friendly expression",
+    model: fal.imageModel("flux-schnell"),
+    aspectRatio: "9:16"
+  });
+
+  await render(
+    <Render width={1080} height={1920}>
+      <Clip duration={3}>
+        <Animate
+          image={character}
+          motion="fox waves hello, tail wagging"
+          model={fal.videoModel("wan-2.5")}
+          duration={3}
+        />
+      </Clip>
+      
+      <Clip duration={3} transition={{ name: "fade", duration: 0.5 }}>
+        <Animate
+          image={character}
+          motion="fox dances happily, spinning around"
+          model={fal.videoModel("wan-2.5")}
+          duration={3}
+        />
+      </Clip>
+      
+      <Clip duration={3} transition={{ name: "fade", duration: 0.5 }}>
+        <Animate
+          image={character}
+          motion="fox blows a kiss at camera, winks"
+          model={fal.videoModel("wan-2.5")}
+          duration={3}
+        />
+      </Clip>
+    </Render>,
+    { output: "output/fox-video.mp4" }
+  );
+}
+
+main();
+```
+
+---
+
+## Split Screen Comparison
+
+**Requirements:** FAL_API_KEY
+
+Side-by-side comparison layout.
+
+```tsx
+// split-screen.tsx
+import { render, Render, Clip, Image, Animate, Split, Title } from "vargai/react";
+import { fal } from "vargai/ai";
+
+async function main() {
+  const before = Image({ 
+    prompt: "messy room, clothes everywhere, unmade bed",
+    aspectRatio: "3:4"
+  });
+  
+  const after = Image({ 
+    prompt: "clean organized room, made bed, tidy shelves",
+    aspectRatio: "3:4"
+  });
+
+  await render(
+    <Render width={1080} height={1920}>
+      <Clip duration={5}>
+        <Split direction="horizontal">
+          <Animate 
+            image={before} 
+            motion="camera slowly pans across messy room"
+            model={fal.videoModel("wan-2.5")}
+          />
+          <Animate 
+            image={after} 
+            motion="camera slowly pans across clean room"
+            model={fal.videoModel("wan-2.5")}
+          />
+        </Split>
+        <Title position="bottom">
+          BEFORE          AFTER
+        </Title>
+      </Clip>
+    </Render>,
+    { output: "output/split-comparison.mp4" }
+  );
+}
+
+main();
+```
+
+---
+
+## Component Reference
+
+| Component | Props | Description |
+|-----------|-------|-------------|
+| `<Render>` | `width`, `height`, `fps` | Root container |
+| `<Clip>` | `duration`, `transition` | Sequential segment |
+| `<Image>` | `prompt`, `src`, `model`, `aspectRatio`, `zoom` | AI or static image |
+| `<Animate>` | `image`, `motion`, `model`, `duration` | Image-to-video |
+| `<Video>` | `src`, `prompt`, `model`, `keepAudio` | Video file or generated |
+| `<Music>` | `prompt`, `model`, `duration`, `volume`, `loop` | Background music |
+| `<Speech>` | `voice`, `model`, `children` | Text-to-speech |
+| `<Title>` | `position`, `color`, `start`, `end` | Text overlay |
+| `<Split>` | `direction` | Side-by-side layout |
+
+## Transitions
+
+Available transition effects:
+
+- `fade` - Simple fade
+- `crossfade` - Cross dissolve
+- `wipeleft`, `wiperight`, `wipeup`, `wipedown` - Directional wipes
+- `slideleft`, `slideright`, `slideup`, `slidedown` - Slides
+- `cube` - 3D cube rotation
+- `pixelize` - Pixelation effect
+
+```tsx
+<Clip transition={{ name: "cube", duration: 0.8 }}>
+```
+
+## Aspect Ratios
+
+| Ratio | Use Case | Dimensions |
+|-------|----------|------------|
+| `9:16` | TikTok, Reels, Shorts | 1080x1920 |
+| `16:9` | YouTube, Twitter | 1920x1080 |
+| `1:1` | Instagram posts | 1080x1080 |
+| `4:5` | Instagram portrait | 1080x1350 |

package/skills/varg-video-generation/scripts/setup.ts

@@ -0,0 +1,265 @@
+#!/usr/bin/env bun
+/**
+ * varg-video-generation setup script
+ *
+ * This script initializes a project for AI video generation.
+ * Can be run standalone by agents or via bunx vargai.
+ *
+ * Usage:
+ *   bun scripts/setup.ts
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+
+const COLORS = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  red: "\x1b[31m",
+  cyan: "\x1b[36m",
+};
+
+const log = {
+  info: (msg: string) =>
+    console.log(`${COLORS.blue}info${COLORS.reset} ${msg}`),
+  success: (msg: string) =>
+    console.log(`${COLORS.green}done${COLORS.reset} ${msg}`),
+  warn: (msg: string) =>
+    console.log(`${COLORS.yellow}warn${COLORS.reset} ${msg}`),
+  error: (msg: string) =>
+    console.log(`${COLORS.red}error${COLORS.reset} ${msg}`),
+  step: (msg: string) =>
+    console.log(
+      `\n${COLORS.bold}${COLORS.cyan}==>${COLORS.reset} ${COLORS.bold}${msg}${COLORS.reset}`,
+    ),
+};
+
+// .env template
+const ENV_TEMPLATE = `# Varg AI Video Generation - API Keys
+# Get your keys from the URLs below
+
+# REQUIRED - Fal.ai (image & video generation)
+# Get it: https://fal.ai/dashboard/keys
+FAL_API_KEY=
+
+# OPTIONAL - ElevenLabs (music & voice)
+# Get it: https://elevenlabs.io/app/settings/api-keys
+ELEVENLABS_API_KEY=
+
+# OPTIONAL - Replicate (lipsync)
+# Get it: https://replicate.com/account/api-tokens
+REPLICATE_API_TOKEN=
+
+# OPTIONAL - Groq (transcription)
+# Get it: https://console.groq.com/keys
+GROQ_API_KEY=
+`;
+
+// Example video file
+const EXAMPLE_VIDEO = `/**
+ * Example: Simple animated video
+ * Run: bun run examples/my-first-video.tsx
+ */
+import { render, Render, Clip, Image, Animate } from "vargai/react";
+import { fal } from "vargai/ai";
+
+async function main() {
+  console.log("Creating your first AI video...\\n");
+
+  await render(
+    <Render width={720} height={720}>
+      <Clip duration={3}>
+        <Animate
+          image={Image({
+            prompt: "a friendly robot waving hello, cartoon style, blue colors",
+            model: fal.imageModel("flux-schnell"),
+            aspectRatio: "1:1",
+          })}
+          motion="robot waves hello, friendly gesture"
+          model={fal.videoModel("wan-2.5")}
+          duration={3}
+        />
+      </Clip>
+    </Render>,
+    { 
+      output: "output/my-first-video.mp4",
+      cache: ".cache/ai"
+    }
+  );
+
+  console.log("\\nDone! Check output/my-first-video.mp4");
+}
+
+main().catch(console.error);
+`;
+
+async function main() {
+  console.log(`
+${COLORS.bold}${COLORS.cyan}varg-video-generation${COLORS.reset} ${COLORS.dim}setup${COLORS.reset}
+`);
+
+  const cwd = process.cwd();
+
+  // Step 1: Check/create directories
+  log.step("Setting up project structure");
+
+  const dirs = ["output", ".cache/ai", "examples"];
+  for (const dir of dirs) {
+    const path = join(cwd, dir);
+    if (!existsSync(path)) {
+      mkdirSync(path, { recursive: true });
+      log.success(`Created ${dir}/`);
+    } else {
+      log.info(`${dir}/ already exists`);
+    }
+  }
+
+  // Step 2: Check/create .env
+  log.step("Checking API keys");
+
+  const envPath = join(cwd, ".env");
+  let envContent = "";
+  let hasFalKey = false;
+
+  if (existsSync(envPath)) {
+    envContent = readFileSync(envPath, "utf8");
+    hasFalKey = /^FAL_API_KEY=.+/m.test(envContent);
+
+    if (hasFalKey) {
+      log.success("FAL_API_KEY found in .env");
+    } else {
+      log.warn("FAL_API_KEY not found in .env");
+    }
+
+    // Check optional keys
+    const hasElevenLabs = /^ELEVENLABS_API_KEY=.+/m.test(envContent);
+    const hasReplicate = /^REPLICATE_API_TOKEN=.+/m.test(envContent);
+    const hasGroq = /^GROQ_API_KEY=.+/m.test(envContent);
+
+    if (hasElevenLabs)
+      log.info("ELEVENLABS_API_KEY found (music/voice enabled)");
+    if (hasReplicate) log.info("REPLICATE_API_TOKEN found (lipsync enabled)");
+    if (hasGroq) log.info("GROQ_API_KEY found (transcription enabled)");
+
+    if (!hasElevenLabs && !hasReplicate && !hasGroq) {
+      log.info("No optional keys found (basic video generation only)");
+    }
+  } else {
+    log.warn(".env file not found");
+  }
+
+  // If no FAL key, prompt for it
+  if (!hasFalKey) {
+    console.log(`
+${COLORS.yellow}FAL_API_KEY is required for video generation.${COLORS.reset}
+
+Get your free API key at: ${COLORS.cyan}https://fal.ai/dashboard/keys${COLORS.reset}
+`);
+
+    process.stdout.write("Enter your FAL_API_KEY (or press Enter to skip): ");
+
+    const falKey = await new Promise<string>((resolve) => {
+      let input = "";
+      process.stdin.setEncoding("utf8");
+      process.stdin.once("data", (data) => {
+        input = data.toString().trim();
+        resolve(input);
+      });
+    });
+
+    if (falKey) {
+      if (existsSync(envPath)) {
+        const newEnvContent = envContent.includes("FAL_API_KEY")
+          ? envContent.replace(/^FAL_API_KEY=.*/m, `FAL_API_KEY=${falKey}`)
+          : `${envContent}\nFAL_API_KEY=${falKey}`;
+        writeFileSync(envPath, newEnvContent);
+      } else {
+        writeFileSync(
+          envPath,
+          ENV_TEMPLATE.replace("FAL_API_KEY=", `FAL_API_KEY=${falKey}`),
+        );
+      }
+      log.success("FAL_API_KEY saved to .env");
+      hasFalKey = true;
+    } else {
+      if (!existsSync(envPath)) {
+        writeFileSync(envPath, ENV_TEMPLATE);
+        log.info("Created .env template - add your keys manually");
+      }
+    }
+  }
+
+  // Step 3: Create example file
+  log.step("Creating example files");
+
+  const examplePath = join(cwd, "examples/my-first-video.tsx");
+  if (!existsSync(examplePath)) {
+    writeFileSync(examplePath, EXAMPLE_VIDEO);
+    log.success("Created examples/my-first-video.tsx");
+  } else {
+    log.info("examples/my-first-video.tsx already exists");
+  }
+
+  // Step 4: Add to .gitignore
+  log.step("Updating .gitignore");
+
+  const gitignorePath = join(cwd, ".gitignore");
+  const gitignoreEntries = [".env", ".cache/", "output/"];
+  let gitignoreContent = existsSync(gitignorePath)
+    ? readFileSync(gitignorePath, "utf8")
+    : "";
+
+  let added = false;
+  for (const entry of gitignoreEntries) {
+    if (!gitignoreContent.includes(entry)) {
+      gitignoreContent += `\n${entry}`;
+      added = true;
+    }
+  }
+
+  if (added) {
+    writeFileSync(gitignorePath, gitignoreContent.trim() + "\n");
+    log.success("Updated .gitignore");
+  } else {
+    log.info(".gitignore already configured");
+  }
+
+  // Summary
+  console.log(`
+${COLORS.green}${COLORS.bold}Setup complete!${COLORS.reset}
+
+${COLORS.bold}Next steps:${COLORS.reset}
+`);
+
+  if (!hasFalKey) {
+    console.log(`  ${COLORS.yellow}1. Add FAL_API_KEY to .env${COLORS.reset}
+     Get it at: https://fal.ai/dashboard/keys
+`);
+  }
+
+  console.log(`  ${hasFalKey ? "1" : "2"}. Install vargai package:
+     ${COLORS.cyan}bun add vargai${COLORS.reset}
+
+  ${hasFalKey ? "2" : "3"}. Run your first video:
+     ${COLORS.cyan}bun run examples/my-first-video.tsx${COLORS.reset}
+
+${COLORS.dim}Documentation: https://github.com/vargHQ/sdk${COLORS.reset}
+`);
+
+  process.exit(0);
+}
+
+main().catch((error) => {
+  log.error(error.message);
+  process.exit(1);
+});

package/src/ai-sdk/cache.ts

@@ -106,7 +106,7 @@ function flatten(value: unknown): unknown {
  * });
  * ```
  */
-const DEFAULT_TTL = "1h";
+const DEFAULT_TTL = "7d";
 
 export function withCache<T extends object, R>(
   fn: (options: T) => Promise<R>,

package/src/ai-sdk/middleware/wrap-image-model.ts

@@ -15,12 +15,12 @@ export interface ImagePlaceholderFallbackOptions {
 export function imagePlaceholderFallbackMiddleware(
   options: ImagePlaceholderFallbackOptions,
 ): ImageModelV3Middleware {
-  const { mode, onFallback } = options;
+  const { mode } = options;
 
   return {
     specificationVersion: "v3",
     wrapGenerate: async ({ doGenerate, params, model }) => {
-      const createPlaceholderResult = async () => {
+      if (mode === "preview") {
         const [width, height] = (params.size?.split("x").map(Number) ?? [
           1024, 1024,
         ]) as [number, number];
@@ -42,7 +42,7 @@ export function imagePlaceholderFallbackMiddleware(
           warnings: [
             {
               type: "other" as const,
-              message: "placeholder: provider skipped or failed",
+              message: "placeholder: preview mode",
             },
           ],
           response: {
@@ -51,26 +51,9 @@ export function imagePlaceholderFallbackMiddleware(
             headers: undefined,
           },
         };
-      };
-
-      if (mode === "preview") {
-        return createPlaceholderResult();
       }
 
-      try {
-        return await doGenerate();
-      } catch (e) {
-        if (mode === "strict") throw e;
-
-        const error = e instanceof Error ? e : new Error(String(e));
-        const promptText =
-          typeof params.prompt === "string"
-            ? params.prompt
-            : ((params.prompt as { text?: string } | undefined)?.text ??
-              "placeholder");
-        onFallback?.(error, promptText);
-        return createPlaceholderResult();
-      }
+      return doGenerate();
     },
   };
 }