vargai 0.4.0-alpha18 → 0.4.0-alpha19

package/README.md

@@ -1,115 +1,537 @@
 # varg
 
-AI video generation from your terminal.
+ai video generation sdk. jsx for videos, built on vercel ai sdk.
 
-## Quick Start
+## quickstart
 
 ```bash
 bun install vargai ai
 ```
 
-### SDK Usage
+set your api key:
+
+```bash
+export FAL_API_KEY=fal_xxx  # required
+export ELEVENLABS_API_KEY=xxx  # optional, for voice/music
+```
+
+create `hello.tsx`:
+
+```tsx
+import { render, Render, Clip, Image, Video } from "vargai/react";
+import { fal } from "vargai/ai";
+
+const fruit = Image({
+  prompt: "cute kawaii fluffy orange fruit character, round plush body, small black dot eyes, tiny smile, Pixar style",
+  model: fal.imageModel("nano-banana-pro"),
+  aspectRatio: "9:16",
+});
+
+await render(
+  <Render width={1080} height={1920}>
+    <Clip duration={3}>
+      <Video
+        prompt={{
+          text: "character waves hello enthusiastically, bounces up and down, eyes squint with joy",
+          images: [fruit],
+        }}
+        model={fal.videoModel("kling-v2.5")}
+      />
+    </Clip>
+  </Render>,
+  { output: "output/hello.mp4" }
+);
+```
+
+run it:
+
+```bash
+bun run hello.tsx
+```
+
+## installation
+
+```bash
+# with bun (recommended)
+bun install vargai ai
+
+# with npm
+npm install vargai ai
+```
+
+## ai sdk
+
+varg extends vercel's ai sdk with video, music, and lipsync. use familiar patterns:
 
 ```typescript
 import { generateImage } from "ai";
-import { File, fal, generateElement, generateVideo, scene } from "vargai";
+import { generateVideo, generateMusic, generateElement, scene, fal, elevenlabs } from "vargai/ai";
+
+// generate image
+const { image } = await generateImage({
+  model: fal.imageModel("flux-schnell"),
+  prompt: "cyberpunk cityscape at night",
+  aspectRatio: "16:9",
+});
+
+// animate to video
+const { video } = await generateVideo({
+  model: fal.videoModel("kling-v2.5"),
+  prompt: {
+    images: [image.uint8Array],
+    text: "camera slowly pans across the city",
+  },
+  duration: 5,
+});
+
+// generate music
+const { audio } = await generateMusic({
+  model: elevenlabs.musicModel(),
+  prompt: "cyberpunk ambient music, electronic",
+  duration: 10,
+});
+
+// save output
+await Bun.write("output/city.mp4", video.uint8Array);
+```
+
+### character consistency with elements
+
+create reusable elements for consistent generation across scenes:
+
+```typescript
+import { generateElement, scene, fal } from "vargai/ai";
+import { generateImage, generateVideo } from "ai";
 
-// generate a character from reference image
+// create character from reference
 const { element: character } = await generateElement({
   model: fal.imageModel("nano-banana-pro/edit"),
   type: "character",
   prompt: {
-    text: "cartoon character, simple style",
-    images: [await File.fromPath("media/reference.jpg").arrayBuffer()],
+    text: "woman in her 30s, brown hair, green eyes",
+    images: [referenceImageData],
   },
 });
 
-// generate scene with character
-const { image: frame } = await generateImage({
+// use in scenes - same character every time
+const { image: frame1 } = await generateImage({
   model: fal.imageModel("nano-banana-pro"),
-  prompt: scene`${character} walks through a forest`,
+  prompt: scene`${character} waves hello`,
 });
 
-// animate the frame
-const { video } = await generateVideo({
-  model: fal.videoModel("wan-2.5"),
+const { image: frame2 } = await generateImage({
+  model: fal.imageModel("nano-banana-pro"),
+  prompt: scene`${character} gives thumbs up`,
+});
+```
+
+### file handling
+
+```typescript
+import { File } from "vargai/ai";
+
+// load from disk
+const file = File.fromPath("media/portrait.jpg");
+
+// load from url
+const file = await File.fromUrl("https://example.com/video.mp4");
+
+// load from buffer
+const file = File.fromBuffer(uint8Array, "image/png");
+
+// get contents
+const buffer = await file.arrayBuffer();
+const base64 = await file.base64();
+```
+
+## jsx / react
+
+compose videos declaratively with jsx. everything is cached - same props = instant cache hit.
+
+```tsx
+import { render, Render, Clip, Image, Video, Music } from "vargai/react";
+import { fal, elevenlabs } from "vargai/ai";
+
+// kawaii fruit characters
+const CHARACTERS = [
+  { name: "orange", prompt: "cute kawaii fluffy orange fruit character, round plush body, Pixar style" },
+  { name: "strawberry", prompt: "cute kawaii fluffy strawberry fruit character, round plush body, Pixar style" },
+  { name: "lemon", prompt: "cute kawaii fluffy lemon fruit character, round plush body, Pixar style" },
+];
+
+const characterImages = CHARACTERS.map(char =>
+  Image({
+    prompt: char.prompt,
+    model: fal.imageModel("nano-banana-pro"),
+    aspectRatio: "9:16",
+  })
+);
+
+await render(
+  <Render width={1080} height={1920}>
+    <Music prompt="cute baby song, playful xylophone, kawaii vibes" model={elevenlabs.musicModel()} />
+    
+    {CHARACTERS.map((char, i) => (
+      <Clip key={char.name} duration={2.5}>
+        <Video
+          prompt={{
+            text: "character waves hello, bounces up and down, eyes squint with joy",
+            images: [characterImages[i]],
+          }}
+          model={fal.videoModel("kling-v2.5")}
+        />
+      </Clip>
+    ))}
+  </Render>,
+  { output: "output/kawaii-fruits.mp4" }
+);
+```
+
+### components
+
+| component | purpose | key props |
+|-----------|---------|-----------|
+| `<Render>` | root container | `width`, `height`, `fps` |
+| `<Clip>` | time segment | `duration`, `transition`, `cutFrom`, `cutTo` |
+| `<Image>` | ai or static image | `prompt`, `src`, `model`, `zoom`, `aspectRatio`, `resize` |
+| `<Video>` | ai or source video | `prompt`, `src`, `model`, `volume`, `cutFrom`, `cutTo` |
+| `<Speech>` | text-to-speech | `voice`, `model`, `volume`, `children` |
+| `<Music>` | background music | `prompt`, `src`, `model`, `volume`, `loop`, `ducking` |
+| `<Title>` | text overlay | `position`, `color`, `start`, `end` |
+| `<Subtitle>` | subtitle text | `backgroundColor` |
+| `<Captions>` | auto-generated subs | `src`, `srt`, `style`, `color`, `activeColor` |
+| `<Overlay>` | positioned layer | `left`, `top`, `width`, `height`, `keepAudio` |
+| `<Split>` | side-by-side | `direction` |
+| `<Slider>` | before/after reveal | `direction` |
+| `<Swipe>` | tinder-style cards | `direction`, `interval` |
+| `<TalkingHead>` | animated character | `character`, `src`, `voice`, `model`, `lipsyncModel` |
+| `<Packshot>` | end card with cta | `background`, `logo`, `cta`, `blinkCta` |
+
+### layout helpers
+
+```tsx
+import { Grid, SplitLayout } from "vargai/react";
+
+// grid layout
+<Grid columns={2}>
+  <Video prompt="scene 1" />
+  <Video prompt="scene 2" />
+</Grid>
+
+// split layout (before/after)
+<SplitLayout left={beforeVideo} right={afterVideo} />
+```
+
+### transitions
+
+67 gl-transitions available:
+
+```tsx
+<Clip transition={{ name: "fade", duration: 0.5 }}>
+<Clip transition={{ name: "crossfade", duration: 0.5 }}>
+<Clip transition={{ name: "wipeleft", duration: 0.5 }}>
+<Clip transition={{ name: "cube", duration: 0.8 }}>
+```
+
+### caption styles
+
+```tsx
+<Captions src={voiceover} style="tiktok" />     // word-by-word highlight
+<Captions src={voiceover} style="karaoke" />    // fill left-to-right
+<Captions src={voiceover} style="bounce" />     // words bounce in
+<Captions src={voiceover} style="typewriter" /> // typing effect
+```
+
+### talking head with lipsync
+
+```tsx
+import { render, Render, Clip, Image, Video, Speech, Captions, Music } from "vargai/react";
+import { fal, elevenlabs, higgsfield } from "vargai/ai";
+
+const voiceover = Speech({
+  model: elevenlabs.speechModel("eleven_v3"),
+  voice: "5l5f8iK3YPeGga21rQIX",
+  children: "With varg, you can create any videos at scale!",
+});
+
+// base character with higgsfield soul (realistic)
+const baseCharacter = Image({
+  prompt: "beautiful East Asian woman, sleek black bob hair, fitted black t-shirt, iPhone selfie, minimalist bedroom",
+  model: higgsfield.imageModel("soul", { styleId: higgsfield.styles.REALISTIC }),
+  aspectRatio: "9:16",
+});
+
+// animate the character
+const animatedCharacter = Video({
   prompt: {
-    text: `${character.text} walks through a forest`,
-    images: [frame.base64],
+    text: "woman speaking naturally, subtle head movements, friendly expression",
+    images: [baseCharacter],
   },
-  duration: 5,
+  model: fal.videoModel("kling-v2.5"),
 });
 
-await Bun.write("output/scene.mp4", video.uint8Array);
+await render(
+  <Render width={1080} height={1920}>
+    <Music prompt="modern tech ambient, subtle electronic" model={elevenlabs.musicModel()} volume={0.1} />
+    
+    <Clip duration={5}>
+      {/* lipsync: animated video + speech audio -> sync-v2 */}
+      <Video
+        prompt={{ video: animatedCharacter, audio: voiceover }}
+        model={fal.videoModel("sync-v2-pro")}
+      />
+    </Clip>
+    
+    <Captions src={voiceover} style="tiktok" color="#ffffff" />
+  </Render>,
+  { output: "output/talking-head.mp4" }
+);
 ```
 
-### CLI Usage
+### ugc transformation video
+
+```tsx
+import { render, Render, Clip, Image, Video, Speech, Captions, Music, Title, SplitLayout } from "vargai/react";
+import { fal, elevenlabs, higgsfield } from "vargai/ai";
+
+const CHARACTER = "woman in her 30s, brown hair, green eyes";
+
+// before: generated with higgsfield soul
+const beforeImage = Image({
+  prompt: `${CHARACTER}, overweight, tired expression, loose grey t-shirt, bathroom mirror selfie`,
+  model: higgsfield.imageModel("soul", { styleId: higgsfield.styles.REALISTIC }),
+  aspectRatio: "9:16",
+});
+
+// after: edit with nano-banana-pro using before as reference
+const afterImage = Image({
+  prompt: { 
+    text: `${CHARACTER}, fit slim, confident smile, fitted black tank top, same bathroom, same woman 40 pounds lighter`,
+    images: [beforeImage] 
+  },
+  model: fal.imageModel("nano-banana-pro/edit"),
+  aspectRatio: "9:16",
+});
+
+const beforeVideo = Video({
+  prompt: { text: "woman looks down sadly, sighs, tired expression", images: [beforeImage] },
+  model: fal.videoModel("kling-v2.5"),
+});
+
+const afterVideo = Video({
+  prompt: { text: "woman smiles confidently, touches hair, proud expression", images: [afterImage] },
+  model: fal.videoModel("kling-v2.5"),
+});
+
+const voiceover = Speech({
+  model: elevenlabs.speechModel("eleven_multilingual_v2"),
+  children: "With this technique I lost 40 pounds in just 3 months!",
+});
+
+await render(
+  <Render width={1080 * 2} height={1920}>
+    <Music prompt="upbeat motivational pop, inspiring transformation" model={elevenlabs.musicModel()} volume={0.15} />
+    
+    <Clip duration={5}>
+      <SplitLayout direction="horizontal" left={beforeVideo} right={afterVideo} />
+      <Title position="top" color="#ffffff">My 3-Month Transformation</Title>
+    </Clip>
+    
+    <Captions src={voiceover} style="tiktok" color="#ffffff" />
+  </Render>,
+  { output: "output/transformation.mp4" }
+);
+```
+
+### render options
+
+```tsx
+// save to file
+await render(<Render>...</Render>, { output: "output/video.mp4" });
+
+// with cache directory
+await render(<Render>...</Render>, { 
+  output: "output/video.mp4",
+  cache: ".cache/ai"
+});
+
+// get buffer directly
+const buffer = await render(<Render>...</Render>);
+await Bun.write("video.mp4", buffer);
+```
+
+## studio
+
+visual editor for video workflows. write code or use node-based interface.
 
 ```bash
-varg run image --prompt "cyberpunk cityscape at night"
-varg run video --prompt "camera flies through clouds" --duration 5
-varg run voice --text "Hello world" --voice rachel
+bun run studio
+# opens http://localhost:8282
+```
+
+features:
+- monaco code editor with typescript support
+- node graph visualization of workflow
+- step-by-step execution with previews
+- cache viewer for generated media
+
+## skills
+
+skills are multi-step workflows that combine actions into pipelines. located in `skills/` directory.
+
+## supported providers
+
+### fal (primary)
+
+```typescript
+import { fal } from "vargai/ai";
+
+// image models
+fal.imageModel("flux-schnell")          // fast generation
+fal.imageModel("flux-pro")              // high quality
+fal.imageModel("flux-dev")              // development
+fal.imageModel("nano-banana-pro")       // versatile
+fal.imageModel("nano-banana-pro/edit")  // image-to-image editing
+fal.imageModel("recraft-v3")            // alternative
+
+// video models
+fal.videoModel("kling-v2.5")            // high quality video
+fal.videoModel("kling-v2.1")            // previous version
+fal.videoModel("wan-2.5")               // good for characters
+fal.videoModel("minimax")               // alternative
+
+// lipsync models
+fal.videoModel("sync-v2")               // lip sync
+fal.videoModel("sync-v2-pro")           // pro lip sync
+
+// transcription
+fal.transcriptionModel("whisper")
 ```
 
-## Commands
+### elevenlabs
+
+```typescript
+import { elevenlabs } from "vargai/ai";
 
-| Command | Description |
-|---------|-------------|
-| `varg run <action>` | Run an action |
-| `varg list` | List all available actions |
-| `varg find <query>` | Search actions by keyword |
-| `varg which <action>` | Show action details and options |
-| `varg help` | Show help |
+// speech models
+elevenlabs.speechModel("eleven_turbo_v2")       // fast tts (default)
+elevenlabs.speechModel("eleven_multilingual_v2") // multilingual
 
-## Actions
+// music model
+elevenlabs.musicModel()  // music generation
 
-| Action | Description | Example |
-|--------|-------------|---------|
-| `image` | Generate image from text | `varg run image --prompt "sunset"` |
-| `video` | Generate video from text or image | `varg run video --prompt "ocean waves" --image ./photo.jpg` |
-| `voice` | Text-to-speech | `varg run voice --text "Hello" --voice sam` |
-| `music` | Generate music | `varg run music --prompt "upbeat electronic"` |
-| `transcribe` | Audio to text/subtitles | `varg run transcribe --audio ./speech.mp3` |
-| `captions` | Add subtitles to video | `varg run captions --video ./clip.mp4` |
-| `sync` | Lipsync audio to video | `varg run sync --video ./face.mp4 --audio ./voice.mp3` |
-| `trim` | Trim video | `varg run trim --input ./video.mp4 --start 0 --end 10` |
-| `cut` | Remove section from video | `varg run cut --input ./video.mp4 --start 5 --end 8` |
-| `merge` | Combine videos | `varg run merge --inputs ./a.mp4 ./b.mp4` |
-| `split` | Split video at timestamps | `varg run split --input ./video.mp4 --timestamps 10,20,30` |
-| `fade` | Add fade in/out | `varg run fade --input ./video.mp4 --type both` |
-| `transition` | Add transitions between clips | `varg run transition --inputs ./a.mp4 ./b.mp4` |
-| `upload` | Upload file to S3 | `varg run upload --file ./video.mp4` |
+// available voices: rachel, adam, bella, josh, sam, antoni, elli, arnold, domi
+```
 
-Use `varg run <action> --help` for all options.
+### higgsfield
 
-## Environment Variables
+```typescript
+import { higgsfield } from "vargai/ai";
 
-<details>
-<summary>Required API keys</summary>
+// character-focused image generation with 100+ styles
+higgsfield.imageModel("soul")
+higgsfield.imageModel("soul", { 
+  styleId: higgsfield.styles.REALISTIC,
+  quality: "1080p"
+})
+
+// styles include: REALISTIC, ANIME, EDITORIAL_90S, Y2K, GRUNGE, etc.
+```
+
+### openai
+
+```typescript
+import { openai } from "vargai/ai";
+
+// sora video generation
+openai.videoModel("sora-2")
+openai.videoModel("sora-2-pro")
+
+// also supports all standard openai models via @ai-sdk/openai
+```
+
+### replicate
+
+```typescript
+import { replicate } from "vargai/ai";
+
+// background removal
+replicate.imageModel("851-labs/background-remover")
+
+// any replicate model
+replicate.imageModel("owner/model-name")
+```
+
+## supported models
+
+### video generation
+
+| model | provider | capabilities |
+|-------|----------|--------------|
+| kling-v2.5 | fal | text-to-video, image-to-video |
+| kling-v2.1 | fal | text-to-video, image-to-video |
+| wan-2.5 | fal | image-to-video, good for characters |
+| minimax | fal | text-to-video, image-to-video |
+| sora-2 | openai | text-to-video, image-to-video |
+| sync-v2-pro | fal | lipsync (video + audio input) |
+
+### image generation
+
+| model | provider | capabilities |
+|-------|----------|--------------|
+| flux-schnell | fal | fast text-to-image |
+| flux-pro | fal | high quality text-to-image |
+| nano-banana-pro | fal | text-to-image, versatile |
+| nano-banana-pro/edit | fal | image-to-image editing |
+| recraft-v3 | fal | text-to-image |
+| soul | higgsfield | character-focused, 100+ styles |
+
+### audio
+
+| model | provider | capabilities |
+|-------|----------|--------------|
+| eleven_turbo_v2 | elevenlabs | fast text-to-speech |
+| eleven_multilingual_v2 | elevenlabs | multilingual tts |
+| music_v1 | elevenlabs | text-to-music |
+| whisper | fal | speech-to-text |
+
+## environment variables
 
 ```bash
-# AI Providers
+# required
 FAL_API_KEY=fal_xxx
-REPLICATE_API_TOKEN=r8_xxx
-ELEVENLABS_API_KEY=xxx
-GROQ_API_KEY=gsk_xxx
-FIREWORKS_API_KEY=fw_xxx
-HIGGSFIELD_API_KEY=hf_xxx
+
+# optional - enable additional features
+ELEVENLABS_API_KEY=xxx          # voice and music
+REPLICATE_API_TOKEN=r8_xxx      # background removal, other models
+OPENAI_API_KEY=sk_xxx           # sora video
+HIGGSFIELD_API_KEY=hf_xxx       # soul character images
 HIGGSFIELD_SECRET=secret_xxx
+GROQ_API_KEY=gsk_xxx            # fast transcription
 
-# Storage (Cloudflare R2)
+# storage (for upload)
 CLOUDFLARE_R2_API_URL=https://xxx.r2.cloudflarestorage.com
 CLOUDFLARE_ACCESS_KEY_ID=xxx
 CLOUDFLARE_ACCESS_SECRET=xxx
 CLOUDFLARE_R2_BUCKET=bucket-name
 ```
 
-</details>
+## cli
 
-## Contributing
+```bash
+varg run image --prompt "sunset over mountains"
+varg run video --prompt "ocean waves" --duration 5
+varg run voice --text "Hello world" --voice rachel
+varg list              # list all actions
+varg studio            # open visual editor
+```
+
+## contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup.
+see [CONTRIBUTING.md](CONTRIBUTING.md) for development setup.
 
-## License
+## license
 
 Apache-2.0 — see [LICENSE.md](LICENSE.md)
+
+

package/launch-videos/06-kawaii-fruits.tsx

@@ -69,8 +69,8 @@ export default (
       <Clip key={char.name} duration={2.5}>
         <Video
           prompt={{
-            text: "character waves hello e nthusiastically, bounces up and down slightly, eyes squint with joy, tiny feet wiggle",
-            images: [characterImages[i]],
+            text: "character waves hello enthusiastically, bounces up and down slightly, eyes squint with joy, tiny feet wiggle",
+            images: [characterImages[i]!],
           }}
           model={fal.videoModel("kling-v2.5")}
           duration={5}

package/package.json

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

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();
     },
   };
 }

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

@@ -53,11 +53,11 @@ export interface MusicPlaceholderFallbackOptions {
 export function musicPlaceholderFallbackMiddleware(
   options: MusicPlaceholderFallbackOptions,
 ): MusicModelMiddleware {
-  const { mode, onFallback } = options;
+  const { mode } = options;
 
   return {
     wrapGenerate: async ({ doGenerate, params, model }) => {
-      const createPlaceholderResult = async () => {
+      if (mode === "preview") {
         const placeholder = await generatePlaceholder({
           type: "audio",
           prompt: params.prompt,
@@ -69,7 +69,7 @@ export function musicPlaceholderFallbackMiddleware(
           warnings: [
             {
               type: "other" as const,
-              message: "placeholder: provider skipped or failed",
+              message: "placeholder: preview mode",
             },
           ],
           response: {
@@ -78,21 +78,9 @@ export function musicPlaceholderFallbackMiddleware(
             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));
-        onFallback?.(error, params.prompt);
-        return createPlaceholderResult();
-      }
+      return doGenerate();
     },
   };
 }

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

@@ -1,7 +1,7 @@
 import type { VideoModelV3, VideoModelV3CallOptions } from "../video-model";
 import { generatePlaceholder } from "./placeholder";
 
-export type RenderMode = "strict" | "default" | "preview";
+export type RenderMode = "strict" | "preview";
 
 export interface VideoModelMiddleware {
   transformParams?: (options: {
@@ -55,11 +55,11 @@ export interface PlaceholderFallbackOptions {
 export function placeholderFallbackMiddleware(
   options: PlaceholderFallbackOptions,
 ): VideoModelMiddleware {
-  const { mode, onFallback } = options;
+  const { mode } = options;
 
   return {
     wrapGenerate: async ({ doGenerate, params, model }) => {
-      const createPlaceholderResult = async () => {
+      if (mode === "preview") {
         const [width, height] = (params.resolution?.split("x").map(Number) ?? [
           1080, 1920,
         ]) as [number, number];
@@ -76,7 +76,7 @@ export function placeholderFallbackMiddleware(
           warnings: [
             {
               type: "other" as const,
-              message: "placeholder: provider skipped or failed",
+              message: "placeholder: preview mode",
             },
           ],
           response: {
@@ -85,21 +85,9 @@ export function placeholderFallbackMiddleware(
             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));
-        onFallback?.(error, params.prompt);
-        return createPlaceholderResult();
-      }
+      return doGenerate();
     },
   };
 }

package/src/ai-sdk/providers/fal.ts

@@ -58,7 +58,12 @@ const IMAGE_MODELS: Record<string, string> = {
 };
 
 // Models that use image_size instead of aspect_ratio
-const IMAGE_SIZE_MODELS = new Set(["seedream-v4.5/edit"]);
+const IMAGE_SIZE_MODELS = new Set([
+  "flux-schnell",
+  "flux-dev",
+  "flux-pro",
+  "seedream-v4.5/edit",
+]);
 
 // Map aspect ratio strings to image_size enum values
 const ASPECT_RATIO_TO_IMAGE_SIZE: Record<string, string> = {

package/src/cli/commands/help.tsx

@@ -21,44 +21,37 @@ function CommandRow({ name, description }: CommandRowProps) {
 
 function HelpView() {
   const examples = [
-    {
-      command: 'varg run video --prompt "ocean waves"',
-      description: "generate a video from text",
-    },
-    {
-      command: 'varg run video --prompt "person talking" --image photo.jpg',
-      description: "generate video from image",
-    },
-    {
-      command: 'varg run voice --text "hello world" --voice sam',
-      description: "text to speech",
-    },
-    { command: "varg list", description: "see all available" },
-    {
-      command: "varg which video",
-      description: "inspect an action or model",
-    },
+    { command: "varg init", description: "create hello.tsx starter" },
+    { command: "varg render hello.tsx", description: "render jsx to video" },
+    { command: "varg preview hello.tsx", description: "fast preview mode" },
   ];
 
   return (
     <VargBox title="varg">
       <Box marginBottom={1}>
-        <Text>ai video infrastructure from your terminal</Text>
+        <Text>ai video generation sdk. jsx for videos.</Text>
       </Box>
 
       <Header>COMMANDS</Header>
       <Box flexDirection="column" marginY={1}>
-        <CommandRow name="run" description="run a model, action, or skill" />
-        <CommandRow name="list" description="discover what's available" />
         <CommandRow
-          name="find"
-          description="search for models, actions, skills"
+          name="init"
+          description="create hello.tsx starter project"
+        />
+        <CommandRow name="render" description="render jsx component to video" />
+        <CommandRow name="preview" description="fast preview (placeholders)" />
+        <CommandRow
+          name="studio"
+          description="visual editor at localhost:8282"
+        />
+        <CommandRow name="run" description="run a single model or action" />
+        <CommandRow
+          name="list"
+          description="discover models, actions, skills"
         />
-        <CommandRow name="which" description="inspect a specific item" />
-        <CommandRow name="help" description="show this help" />
       </Box>
 
-      <Header>EXAMPLES</Header>
+      <Header>QUICKSTART</Header>
       <Box marginTop={1}>
         <HelpBlock examples={examples} />
       </Box>

package/src/cli/commands/index.ts

@@ -1,7 +1,13 @@
 export { findCmd, showFindHelp } from "./find.tsx";
 export { helpCmd, showHelp } from "./help.tsx";
+export { initCmd, showInitHelp } from "./init.tsx";
 export { listCmd, showListHelp } from "./list.tsx";
-export { fastCmd, previewCmd, renderCmd } from "./render.ts";
+export {
+  previewCmd,
+  renderCmd,
+  showPreviewHelp,
+  showRenderHelp,
+} from "./render.tsx";
 export { runCmd, showRunHelp, showTargetHelp } from "./run.tsx";
 export { studioCmd } from "./studio.ts";
 export { showWhichHelp, whichCmd } from "./which.tsx";

package/src/cli/commands/init.tsx

@@ -0,0 +1,116 @@
+/** @jsxImportSource react */
+
+import { existsSync, mkdirSync } from "node:fs";
+import { defineCommand } from "citty";
+import { Box, Text } from "ink";
+import { Header, HelpBlock, VargBox, VargText } from "../ui/index.ts";
+import { renderStatic } from "../ui/render.ts";
+
+const HELLO_TEMPLATE = `import { Render, Clip, Image, Video, assets } from "vargai/react";
+import { fal } from "vargai/ai";
+
+const girl = Image({
+  prompt: {
+    text: \`Using the attached reference images, generate a photorealistic three-quarter editorial portrait of the exact same character — maintain identical face, hairstyle, and proportions from Image 1.
+
+Framing: Head and shoulders, cropped at upper chest. Direct eye contact with camera.
+
+Natural confident expression, relaxed shoulders.
+Preserve the outfit neckline and visible clothing details from reference.
+
+Background: Deep black with two contrasting orange gradient accents matching Reference 2. Soft gradient bleed, no hard edges.
+
+Shot on 85mm f/1.4 lens, shallow depth of field. Clean studio lighting — soft key light on face, subtle rim light on hair and shoulders for separation. High-end fashion editorial aesthetic.\`,
+    images: [assets.characters.orangeGirl, assets.backgrounds.orangeGradient],
+  },
+  model: fal.imageModel("nano-banana-pro/edit"),
+  aspectRatio: "9:16",
+});
+
+export default (
+  <Render width={1080} height={1920}>
+    <Clip duration={5}>
+      <Video
+        prompt={{
+          text: "She waves hello warmly, natural smile, friendly expression. Studio lighting, authentic confident slightly playful atmosphere. Camera static. Intense orange lighting.",
+          images: [girl],
+        }}
+        model={fal.videoModel("kling-v2.5")}
+      />
+    </Clip>
+  </Render>
+);
+`;
+
+function InitHelpView() {
+  const examples = [
+    { command: "varg init", description: "create hello.tsx in current dir" },
+    { command: "varg init my-project", description: "create in my-project/" },
+  ];
+
+  return (
+    <VargBox title="varg init">
+      <Box marginBottom={1}>
+        <Text>initialize a new varg project with hello.tsx template.</Text>
+      </Box>
+
+      <Header>USAGE</Header>
+      <Box paddingLeft={2} marginBottom={1}>
+        <VargText variant="accent">varg init [directory]</VargText>
+      </Box>
+
+      <Header>EXAMPLES</Header>
+      <Box marginTop={1}>
+        <HelpBlock examples={examples} />
+      </Box>
+    </VargBox>
+  );
+}
+
+export function showInitHelp() {
+  renderStatic(<InitHelpView />);
+}
+
+export const initCmd = defineCommand({
+  meta: {
+    name: "init",
+    description: "initialize project with hello.tsx",
+  },
+  args: {
+    directory: {
+      type: "positional",
+      description: "project directory (default: current)",
+      required: false,
+    },
+  },
+  async run({ args }) {
+    const dir = (args.directory as string) || ".";
+    const outputDir = `${dir}/output`;
+    const cacheDir = `${dir}/.cache/ai`;
+    const helloPath = `${dir}/hello.tsx`;
+
+    if (!existsSync(dir) && dir !== ".") {
+      mkdirSync(dir, { recursive: true });
+      console.log(`created ${dir}/`);
+    }
+
+    if (!existsSync(outputDir)) {
+      mkdirSync(outputDir, { recursive: true });
+      console.log(`created ${outputDir}/`);
+    }
+
+    if (!existsSync(cacheDir)) {
+      mkdirSync(cacheDir, { recursive: true });
+      console.log(`created ${cacheDir}/`);
+    }
+
+    if (existsSync(helloPath)) {
+      console.log(`hello.tsx already exists, skipping`);
+    } else {
+      await Bun.write(helloPath, HELLO_TEMPLATE);
+      console.log(`created ${helloPath}`);
+    }
+
+    console.log(`\ndone! run: bunx vargai render hello.tsx`);
+  },
+});

package/src/cli/commands/{render.ts → render.tsx}

@@ -1,8 +1,13 @@
+/** @jsxImportSource react */
+
 import { existsSync, mkdirSync } from "node:fs";
 import { resolve } from "node:path";
 import { defineCommand } from "citty";
+import { Box, Text } from "ink";
 import { render } from "../../react/render";
 import type { DefaultModels, RenderMode, VargElement } from "../../react/types";
+import { Header, HelpBlock, VargBox, VargText } from "../ui/index.ts";
+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, SplitLayout } from "vargai/react";
@@ -127,8 +132,7 @@ async function runRender(
   const outputPath = (args.output as string) ?? `output/${basename}.mp4`;
 
   if (!args.quiet) {
-    const modeLabel =
-      mode === "preview" ? " (fast)" : mode === "strict" ? "" : " (preview)";
+    const modeLabel = mode === "preview" ? " (fast)" : "";
     console.log(`rendering ${file} → ${outputPath}${modeLabel}`);
   }
 
@@ -163,21 +167,140 @@ export const renderCmd = defineCommand({
 export const previewCmd = defineCommand({
   meta: {
     name: "preview",
-    description: "render with fallback placeholders on errors",
-  },
-  args: sharedArgs,
-  async run({ args }) {
-    await runRender(args, "default", "preview");
-  },
-});
-
-export const fastCmd = defineCommand({
-  meta: {
-    name: "fast",
     description: "render with all placeholders (no generation)",
   },
   args: sharedArgs,
   async run({ args }) {
-    await runRender(args, "preview", "fast");
+    await runRender(args, "preview", "preview");
   },
 });
+
+function RenderHelpView() {
+  const examples = [
+    {
+      command: "varg render video.tsx",
+      description: "render component to output/video.mp4",
+    },
+    {
+      command: "varg render video.tsx -o my-video.mp4",
+      description: "custom output path",
+    },
+    {
+      command: "varg preview video.tsx",
+      description: "fast preview with placeholders",
+    },
+  ];
+
+  return (
+    <VargBox title="varg render">
+      <Box marginBottom={1}>
+        <Text>
+          render jsx components to video. the react engine for ai video.
+        </Text>
+      </Box>
+
+      <Header>USAGE</Header>
+      <Box paddingLeft={2} marginBottom={1}>
+        <VargText variant="accent">
+          varg render {"<file.tsx>"} [options]
+        </VargText>
+      </Box>
+
+      <Header>OPTIONS</Header>
+      <Box flexDirection="column" paddingLeft={2} marginBottom={1}>
+        <Text>
+          <VargText variant="accent">-o, --output </VargText>output path
+          (default: output/{"<name>"}.mp4)
+        </Text>
+        <Text>
+          <VargText variant="accent">-c, --cache </VargText>cache directory
+          (default: .cache/ai)
+        </Text>
+        <Text>
+          <VargText variant="accent">--no-cache </VargText>disable cache
+        </Text>
+        <Text>
+          <VargText variant="accent">-q, --quiet </VargText>minimal output
+        </Text>
+        <Text>
+          <VargText variant="accent">-v, --verbose </VargText>show ffmpeg
+          commands
+        </Text>
+      </Box>
+
+      <Header>COMPONENTS</Header>
+      <Box flexDirection="column" paddingLeft={2} marginBottom={1}>
+        <Text>{"<Render>"} root container (width, height, fps)</Text>
+        <Text>{"<Clip>"} time segment with duration</Text>
+        <Text>{"<Video>"} ai-generated or source video</Text>
+        <Text>{"<Image>"} ai-generated or static image</Text>
+        <Text>{"<Speech>"} text-to-speech audio</Text>
+        <Text>{"<Music>"} background music</Text>
+        <Text>{"<Captions>"} auto-generated subtitles</Text>
+      </Box>
+
+      <Header>EXAMPLES</Header>
+      <Box marginTop={1}>
+        <HelpBlock examples={examples} />
+      </Box>
+    </VargBox>
+  );
+}
+
+function PreviewHelpView() {
+  const examples = [
+    {
+      command: "varg preview video.tsx",
+      description: "quick test without ai calls",
+    },
+    {
+      command: "varg preview video.tsx -o test.mp4",
+      description: "preview to custom path",
+    },
+  ];
+
+  return (
+    <VargBox title="varg preview">
+      <Box marginBottom={1}>
+        <Text>
+          fast preview mode - uses placeholders instead of ai generation.
+        </Text>
+      </Box>
+
+      <Header>USAGE</Header>
+      <Box paddingLeft={2} marginBottom={1}>
+        <VargText variant="accent">
+          varg preview {"<file.tsx>"} [options]
+        </VargText>
+      </Box>
+
+      <Header>OPTIONS</Header>
+      <Box flexDirection="column" paddingLeft={2} marginBottom={1}>
+        <Text>
+          <VargText variant="accent">-o, --output </VargText>output path
+          (default: output/{"<name>"}.mp4)
+        </Text>
+        <Text>
+          <VargText variant="accent">-q, --quiet </VargText>minimal output
+        </Text>
+        <Text>
+          <VargText variant="accent">-v, --verbose </VargText>show ffmpeg
+          commands
+        </Text>
+      </Box>
+
+      <Header>EXAMPLES</Header>
+      <Box marginTop={1}>
+        <HelpBlock examples={examples} />
+      </Box>
+    </VargBox>
+  );
+}
+
+export function showRenderHelp() {
+  renderStatic(<RenderHelpView />);
+}
+
+export function showPreviewHelp() {
+  renderStatic(<PreviewHelpView />);
+}

package/src/cli/index.ts

@@ -12,16 +12,19 @@ import { defineCommand, runMain } from "citty";
 import { registry } from "../core/registry";
 import { allDefinitions } from "../definitions";
 import {
-  fastCmd,
   findCmd,
   helpCmd,
+  initCmd,
   listCmd,
   previewCmd,
   renderCmd,
   runCmd,
   showFindHelp,
   showHelp,
+  showInitHelp,
   showListHelp,
+  showPreviewHelp,
+  showRenderHelp,
   showRunHelp,
   showTargetHelp,
   showWhichHelp,
@@ -47,9 +50,11 @@ for (const provider of providers.all()) {
 const args = process.argv.slice(2);
 const hasHelp = args.includes("--help") || args.includes("-h");
 
-// Map subcommands to their help functions
 const subcommandHelp: Record<string, () => void> = {
   run: showRunHelp,
+  render: showRenderHelp,
+  preview: showPreviewHelp,
+  init: showInitHelp,
   list: showListHelp,
   ls: showListHelp,
   find: showFindHelp,
@@ -104,11 +109,11 @@ const main = defineCommand({
     description: "ai video infrastructure from your terminal",
   },
   subCommands: {
-    run: runCmd,
+    init: initCmd,
     render: renderCmd,
     preview: previewCmd,
-    fast: fastCmd,
     studio: studioCmd,
+    run: runCmd,
     list: listCmd,
     ls: listCmd,
     find: findCmd,

package/src/react/assets.ts

@@ -0,0 +1,9 @@
+export const assets = {
+  characters: {
+    orangeGirl: "https://s3.varg.ai/uploads/images/1_0475e227.png",
+  },
+  backgrounds: {
+    orangeGradient:
+      "https://s3.varg.ai/uploads/images/xyearp51qvve-zi3nrcve-zbno2hfgt5gergjrof_995f553d.png",
+  },
+} as const;

package/src/react/index.ts

@@ -1,4 +1,5 @@
 export type { SizeValue } from "../ai-sdk/providers/editly/types";
+export { assets } from "./assets";
 export {
   Captions,
   Clip,

package/src/react/renderers/render.ts

@@ -53,17 +53,9 @@ export async function renderRoot(
   const props = element.props as RenderProps;
   const progress = createProgressTracker(options.quiet ?? false);
 
-  const mode: RenderMode = options.mode ?? "default";
+  const mode: RenderMode = options.mode ?? "strict";
   const placeholderCount = { images: 0, videos: 0, total: 0 };
 
-  const onFallback = (error: Error, prompt: string) => {
-    if (!options.quiet) {
-      console.warn(
-        `\x1b[33m⚠ provider failed: ${error.message} → placeholder\x1b[0m`,
-      );
-    }
-  };
-
   const trackPlaceholder = (type: "image" | "video") => {
     placeholderCount[type === "image" ? "images" : "videos"]++;
     placeholderCount.total++;
@@ -87,14 +79,6 @@ export async function renderRoot(
 
     if (mode === "preview") {
       trackPlaceholder("image");
-    }
-
-    try {
-      return await cachedGenerateImage(opts);
-    } catch (error) {
-      if (mode === "strict") throw error;
-      trackPlaceholder("image");
-      onFallback(error as Error, String(opts.prompt));
       const wrappedModel = wrapImageModel({
         model: opts.model,
         middleware: imagePlaceholderFallbackMiddleware({
@@ -104,19 +88,13 @@ export async function renderRoot(
       });
       return generateImage({ ...opts, model: wrappedModel });
     }
+
+    return cachedGenerateImage(opts);
   };
 
   const wrapGenerateVideo: typeof generateVideo = async (opts) => {
     if (mode === "preview") {
       trackPlaceholder("video");
-    }
-
-    try {
-      return await cachedGenerateVideo(opts);
-    } catch (error) {
-      if (mode === "strict") throw error;
-      trackPlaceholder("video");
-      onFallback(error as Error, String(opts.prompt));
       const wrappedModel = wrapVideoModel({
         model: opts.model,
         middleware: placeholderFallbackMiddleware({
@@ -126,6 +104,8 @@ export async function renderRoot(
       });
       return generateVideo({ ...opts, model: wrappedModel });
     }
+
+    return cachedGenerateVideo(opts);
   };
 
   const ctx: RenderContext = {
@@ -314,16 +294,10 @@ export async function renderRoot(
     completeTask(progress, captionsTaskId);
   }
 
-  if (!options.quiet && placeholderCount.total > 0) {
-    if (mode === "preview") {
-      console.log(
-        `\x1b[36mℹ preview mode: ${placeholderCount.total} placeholders used (${placeholderCount.images} images, ${placeholderCount.videos} videos)\x1b[0m`,
-      );
-    } else {
-      console.warn(
-        `\x1b[33m⚠ ${placeholderCount.total} elements used placeholders - run with --strict for production\x1b[0m`,
-      );
-    }
+  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();

package/src/react/renderers/video.ts

@@ -145,7 +145,8 @@ export async function renderVideo(
     const { video } = await ctx.generateVideo({
       model,
       prompt: resolvedPrompt,
-      duration: 5,
+      duration: props.duration ?? 5,
+      aspectRatio: props.aspectRatio,
       cacheKey,
     } as Parameters<typeof generateVideo>[0]);
 

package/src/react/types.ts

@@ -118,6 +118,7 @@ export type VideoProps = BaseProps &
     src?: string;
     model?: VideoModelV3;
     resize?: ResizeMode;
+    aspectRatio?: `${number}:${number}`;
   };
 
 export interface SpeechProps extends BaseProps, VolumeProps {
@@ -201,7 +202,7 @@ export interface PackshotProps extends BaseProps {
   duration?: number;
 }
 
-export type RenderMode = "strict" | "default" | "preview";
+export type RenderMode = "strict" | "preview";
 
 export interface DefaultModels {
   image?: ImageModelV3;

package/tsconfig.json

@@ -35,7 +35,7 @@
       "vargai/jsx-dev-runtime": ["./src/react/runtime/jsx-dev-runtime.ts"]
     }
   },
-  "include": ["src/**/*"],
+  "include": ["src/**/*", "launch-videos/**/*"],
   "exclude": [
     "node_modules",
     "action",