vargai 0.4.0-alpha4 → 0.4.0-alpha40

package/package.json

@@ -3,7 +3,7 @@
   "module": "src/index.ts",
   "type": "module",
   "bin": {
-    "varg": "./src/cli/index.ts"
+    "vargai": "./src/cli/index.ts"
   },
   "scripts": {
     "check": "biome check . && tsc --noEmit",
@@ -34,14 +34,18 @@
   },
   "peerDependencies": {
     "typescript": "^5",
-    "ai": "^6.0.0"
+    "ai": "^6.0.0",
+    "zod": "^3.25.76 || ^4.1.8"
   },
   "dependencies": {
     "@ai-sdk/fal": "^1.0.23",
     "@ai-sdk/fireworks": "^2.0.16",
     "@ai-sdk/groq": "^3.0.12",
+    "@ai-sdk/google": "^3.0.13",
     "@ai-sdk/openai": "^3.0.9",
+    "@google/genai": "^1.0.0",
     "@ai-sdk/provider": "^3.0.2",
+    "@ai-sdk/provider-utils": "^4.0.4",
     "@ai-sdk/replicate": "^2.0.5",
     "@aws-sdk/client-s3": "^3.937.0",
     "@aws-sdk/s3-request-presigner": "^3.937.0",
@@ -61,9 +65,10 @@
     "react-dom": "^19.2.0",
     "remotion": "^4.0.377",
     "replicate": "^1.4.0",
+    "sharp": "^0.34.5",
     "zod": "^4.2.1"
   },
-  "version": "0.4.0-alpha4",
+  "version": "0.4.0-alpha40",
   "exports": {
     ".": "./src/index.ts",
     "./ai": "./src/ai-sdk/index.ts",
@@ -73,6 +78,7 @@
     "./react": "./src/react/index.ts",
     "./studio": "./src/studio/index.ts",
     "./jsx-runtime": "./src/react/runtime/jsx-runtime.ts",
-    "./jsx-dev-runtime": "./src/react/runtime/jsx-dev-runtime.ts"
+    "./jsx-dev-runtime": "./src/react/runtime/jsx-dev-runtime.ts",
+    "./editly": "./src/ai-sdk/providers/editly/index.ts"
   }
 }

package/pipeline/cookbooks/round-video-character.md

@@ -321,7 +321,7 @@ see all voices: `bun run lib/elevenlabs.ts voices`
 ```bash
 # required api keys
 export ELEVENLABS_API_KEY="your_key"
-export FAL_KEY="your_key"  # for wan-25 and image generation
+export FAL_API_KEY="your_key"  # for wan-25 and image generation (or set FAL_KEY)
 ```
 
 ## changelog

package/skills/varg-video-generation/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: varg-video-generation
+description: Generate AI videos using varg SDK React engine. Use when creating videos, animations, talking characters, slideshows, or social media content.
+license: MIT
+metadata:
+  author: vargHQ
+  version: "1.0.0"
+compatibility: Requires bun runtime. FAL_KEY required. Optional ELEVENLABS_API_KEY, REPLICATE_API_TOKEN, GROQ_API_KEY
+allowed-tools: Bash(bun:*) Bash(cat:*) Read Write Edit
+---
+
+# Video Generation with varg React Engine
+
+Generate AI videos using declarative JSX syntax with automatic caching and parallel generation.
+
+## Quick Setup
+
+Initialize a new project:
+
+```bash
+bunx vargai init
+```
+
+Or just create hello.tsx starter:
+
+```bash
+bunx vargai hello
+```
+
+Check existing API keys:
+
+```bash
+cat .env 2>/dev/null | grep -E "^(FAL_KEY|ELEVENLABS_API_KEY)=" || echo "No API keys found"
+```
+
+## Required API Keys
+
+### FAL_KEY (Required)
+
+| Detail | Value |
+|--------|-------|
+| Provider | Fal.ai |
+| Get it | https://fal.ai/dashboard/keys |
+| Free tier | Yes (limited credits) |
+| Used for | Image generation (Flux), Video generation (Wan 2.5, Kling) |
+
+If user doesn't have `FAL_KEY`:
+1. Direct them to https://fal.ai/dashboard/keys
+2. Create account and generate API key
+3. Add to `.env` file: `FAL_KEY=fal_xxxxx`
+
+### Optional Keys
+
+| Feature | Key | Provider | URL |
+|---------|-----|----------|-----|
+| Music/Voice | `ELEVENLABS_API_KEY` | ElevenLabs | https://elevenlabs.io/app/settings/api-keys |
+| Lipsync | `REPLICATE_API_TOKEN` | Replicate | https://replicate.com/account/api-tokens |
+| Transcription | `GROQ_API_KEY` | Groq | https://console.groq.com/keys |
+
+**Warn user about missing optional keys but continue with available features.**
+
+## Available Features by API Key
+
+**FAL_API_KEY only:**
+- Image generation (Flux models)
+- Image-to-video animation (Wan 2.5, Kling)
+- Text-to-video generation
+- Slideshows with transitions
+- Ken Burns zoom effects
+
+**FAL + ELEVENLABS:**
+- All above, plus:
+- AI-generated background music
+- Text-to-speech voiceovers
+- Talking character videos
+
+**All keys:**
+- Full production pipeline with lipsync and auto-captions
+
+## Quick Templates
+
+### Simple Slideshow (FAL only)
+
+```tsx
+/** @jsxImportSource vargai */
+import { Render, Clip, Image } from "vargai/react";
+
+const SCENES = ["sunset over ocean", "mountain peaks", "city at night"];
+
+export default (
+  <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>
+);
+```
+
+### Animated Video (FAL + ElevenLabs)
+
+```tsx
+/** @jsxImportSource vargai */
+import { Render, Clip, Image, Video, Music } from "vargai/react";
+import { fal, elevenlabs } from "vargai/ai";
+
+const cat = Image({ prompt: "cute cat on windowsill" });
+
+export default (
+  <Render width={1080} height={1920}>
+    <Music prompt="upbeat electronic" model={elevenlabs.musicModel()} />
+    <Clip duration={5}>
+      <Video
+        prompt={{ text: "cat turns head, blinks slowly", images: [cat] }}
+        model={fal.videoModel("wan-2.5")}
+      />
+    </Clip>
+  </Render>
+);
+```
+
+### Talking Character
+
+```tsx
+/** @jsxImportSource vargai */
+import { Render, Clip, Image, Video, Speech, Captions } from "vargai/react";
+import { fal, elevenlabs } from "vargai/ai";
+
+const robot = Image({ prompt: "friendly robot, blue metallic", aspectRatio: "9:16" });
+
+const voiceover = Speech({
+  model: elevenlabs.speechModel("eleven_multilingual_v2"),
+  voice: "adam",
+  children: "Hello! I'm your AI assistant. Let's create something amazing!",
+});
+
+export default (
+  <Render width={1080} height={1920}>
+    <Clip duration={5}>
+      <Video
+        prompt={{ text: "robot talking, subtle head movements", images: [robot] }}
+        model={fal.videoModel("wan-2.5")}
+      />
+    </Clip>
+    <Captions src={voiceover} style="tiktok" />
+  </Render>
+);
+```
+
+
+
+## Running Videos
+
+```bash
+bunx vargai render your-video.tsx
+```
+
+## Key Components
+
+| Component | Purpose | Required Key |
+|-----------|---------|--------------|
+| `<Render>` | Root container | - |
+| `<Clip>` | Sequential segment | - |
+| `<Image>` | AI image | FAL |
+| `<Animate>` | Image-to-video | FAL |
+| `<Music>` | Background music | ElevenLabs |
+| `<Speech>` | Text-to-speech | ElevenLabs |
+
+## Common Patterns
+
+### Character Consistency
+
+```tsx
+const character = Image({ prompt: "blue robot" });
+// Reuse same reference = same generated image
+<Animate image={character} motion="waving" />
+<Animate image={character} motion="dancing" />
+```
+
+### Transitions
+
+```tsx
+<Clip transition={{ name: "fade", duration: 0.5 }}>
+// Options: fade, crossfade, wipeleft, cube, slideup, etc.
+```
+
+### Aspect Ratios
+
+- `9:16` - TikTok, Reels, Shorts (vertical)
+- `16:9` - YouTube (horizontal)
+- `1:1` - Instagram (square)
+
+### Zoom Effects
+
+```tsx
+<Image prompt="landscape" zoom="in" />   // Zoom in
+<Image prompt="landscape" zoom="out" />  // Zoom out
+<Image prompt="landscape" zoom="left" /> // Pan left
+```
+
+## Troubleshooting
+
+### "FAL_KEY not found"
+- Check `.env` file exists in project root
+- Ensure no spaces around `=` sign
+- Restart terminal after adding keys
+
+### "Rate limit exceeded"
+- Free tier has limited credits
+- Wait or upgrade plan
+- Use caching to avoid regenerating
+
+### "Video generation failed"
+- Check prompt doesn't violate content policy
+- Try simpler motion descriptions
+- Reduce video duration
+
+## Next Steps
+
+1. Run `bunx vargai init` to initialize project
+2. Add your FAL_KEY to `.env`
+3. Run `bunx vargai render hello.tsx`
+4. Or ask the agent: "create a 10 second tiktok video about cats"

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 |