vargai 0.4.0-alpha.1 → 0.4.0-alpha100

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,39 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project team at **hello@varg.ai**. All complaints will be reviewed
+and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

package/LICENSE.md

@@ -1,5 +1,3 @@
-LICENSE
-
 Apache License
 Version 2.0, January 2004
 http://www.apache.org/licenses/

package/README.md

@@ -1,74 +1,320 @@
-# varg
+<p align="center">
+  <h1 align="center">varg — AI Video Generation SDK</h1>
+  <p align="center">Create AI videos with JSX. One SDK for Kling, Flux, ElevenLabs, Sora and more. Built on Vercel AI SDK.</p>
+</p>
 
-AI video generation from your terminal.
+<p align="center">
+  <a href="https://www.npmjs.com/package/vargai"><img src="https://img.shields.io/npm/v/vargai.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/vargai"><img src="https://img.shields.io/npm/dm/vargai.svg" alt="npm downloads"></a>
+  <a href="https://github.com/vargHQ/sdk/stargazers"><img src="https://img.shields.io/github/stars/vargHQ/sdk" alt="GitHub stars"></a>
+  <a href="https://github.com/vargHQ/sdk/blob/main/LICENSE.md"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a>
+</p>
 
-## Quick Start
+<p align="center">
+  <a href="https://docs.varg.ai">Docs</a> &middot; <a href="https://app.varg.ai">Dashboard</a> &middot; <a href="https://docs.varg.ai/quickstart">Quickstart</a> &middot; <a href="https://docs.varg.ai/sdk/models">Models</a> &middot; <a href="https://discord.gg/varg">Discord</a>
+</p>
+
+---
+
+**varg** is an open-source TypeScript SDK for AI video generation. One API key, one gateway — generate images, video, speech, music, lipsync, and captions through `varg.*` providers. Write videos as JSX components (like React), render locally or in the cloud.
+
+## Get started
+
+### For AI agents (recommended)
+
+Install the varg skill into Claude Code, Cursor, Windsurf, or any agent that supports skills. Zero code — just prompt.
+
+```bash
+# 1. Install the varg skill
+npx -y skills add vargHQ/skills --all --copy -y
+
+# 2. Set your API key (get one at app.varg.ai)
+export VARG_API_KEY=varg_live_xxx
+
+# 3. Create your first video
+claude "create a 10-second product video for white sneakers, 9:16, UGC style, with captions and background music"
+```
+
+The agent writes declarative JSX, varg handles AI generation + caching + rendering.
+
+### For developers
 
 ```bash
-bun install @vargai/sdk
+# Install with bun (recommended)
+bun install vargai ai
+
+# Or with npm
+npm install vargai ai
+
+# Set up project (auth, skills, hello.tsx, cache dirs)
+bunx vargai init
 ```
 
+`vargai init` handles everything: signs you in, installs the agent skill, creates a starter template, and sets up your project structure.
+
+Then render the starter template:
+
 ```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
+bunx vargai render hello.tsx
+```
+
+Or ask your AI agent to create something from scratch.
+
+## How it works
+
 ```
+Your prompt / JSX code
+        |
+   varg gateway (api.varg.ai)
+   /     |      \        \
+ Kling  Flux  ElevenLabs  Wan ...   (AI providers)
+   \     |      /        /
+    varg render engine
+        |
+   output.mp4
+```
+
+- **One API key** (`VARG_API_KEY`) routes to all providers through the varg gateway
+- **Declarative JSX** — compose videos like React components with `<Clip>`, `<Video>`, `<Music>`, `<Captions>`
+- **Automatic caching** — same props = instant cache hit at $0. Re-render without re-generating
+- **Local or cloud** — render with `bunx vargai render` locally, or submit via the Cloud Render API
+
+## Quick examples
+
+### Image to video
+
+```tsx
+import { Render, Clip, Image, Video } from "vargai/react";
+import { varg } from "vargai/ai";
+
+const character = Image({
+  prompt: "cute kawaii orange cat, round body, big eyes, Pixar style",
+  model: varg.imageModel("nano-banana-pro"),
+  aspectRatio: "9:16",
+});
+
+export default (
+  <Render width={1080} height={1920}>
+    <Clip duration={5}>
+      <Video
+        prompt={{ text: "cat waves hello, bounces happily", images: [character] }}
+        model={varg.videoModel("kling-v3")}
+      />
+    </Clip>
+  </Render>
+);
+```
+
+```bash
+bunx vargai render hello.tsx
+```
+
+### With music and captions
+
+```tsx
+import { Render, Clip, Image, Video, Speech, Captions, Music } from "vargai/react";
+import { varg } from "vargai/ai";
+
+const character = Image({
+  model: varg.imageModel("nano-banana-pro"),
+  prompt: "friendly robot, blue metallic, expressive eyes",
+  aspectRatio: "9:16",
+});
+
+const voiceover = Speech({
+  model: varg.speechModel("eleven_v3"),
+  voice: "adam",
+  children: "Hello! I'm your AI assistant. Let me show you something cool!",
+});
+
+export default (
+  <Render width={1080} height={1920}>
+    <Music prompt="upbeat electronic, cheerful" model={varg.musicModel()} volume={0.15} />
+    <Clip duration={5}>
+      <Video
+        prompt={{ text: "robot talking, subtle head movements", images: [character] }}
+        model={varg.videoModel("kling-v3")}
+      />
+    </Clip>
+    <Captions src={voiceover} style="tiktok" color="#ffffff" withAudio />
+  </Render>
+);
+```
+
+### Talking head with lipsync
+
+```tsx
+import { Render, Clip, Image, Video, Speech, Captions, Music } from "vargai/react";
+import { varg } from "vargai/ai";
 
-## Commands
-
-| 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 |
-
-## Actions
-
-| 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` |
-
-Use `varg run <action> --help` for all options.
-
-## Environment Variables
+const voiceover = Speech({
+  model: varg.speechModel("eleven_v3"),
+  voice: "josh",
+  children: "With varg, you can create any videos at scale!",
+});
+
+const baseCharacter = Image({
+  prompt: "woman, sleek black bob hair, fitted black t-shirt, natural look",
+  model: varg.imageModel("nano-banana-pro"),
+  aspectRatio: "9:16",
+});
+
+const animatedCharacter = Video({
+  prompt: {
+    text: "woman speaking naturally, subtle head movements, friendly expression",
+    images: [baseCharacter],
+  },
+  model: varg.videoModel("kling-v3"),
+});
+
+export default (
+  <Render width={1080} height={1920}>
+    <Music prompt="modern tech ambient, subtle electronic" model={varg.musicModel()} volume={0.1} />
+    <Clip duration={5}>
+      <Video
+        prompt={{ video: animatedCharacter, audio: voiceover }}
+        model={varg.videoModel("sync-v2-pro")}
+      />
+    </Clip>
+    <Captions src={voiceover} style="tiktok" color="#ffffff" withAudio />
+  </Render>
+);
+```
+
+## 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`, `withAudio` |
+| `<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` |
+
+### 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
+```
+
+### 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 }}>
+```
+
+## Models
+
+All models are accessed through `varg.*` — one API key, one provider.
+
+```typescript
+import { varg } from "vargai/ai";
+```
+
+### Video
+
+| Model | Use case | Credits (5s) |
+|-------|----------|-------------|
+| `varg.videoModel("kling-v3")` | Best quality, latest | 150 |
+| `varg.videoModel("kling-v3-standard")` | Good quality, cheaper | 50 |
+| `varg.videoModel("kling-v2.5")` | Previous gen, reliable | 50 |
+| `varg.videoModel("wan-2.5")` | Good for characters | 50 |
+| `varg.videoModel("minimax")` | Alternative | 50 |
+| `varg.videoModel("sync-v2-pro")` | Lipsync (video + audio) | 50 |
+
+### Image
+
+| Model | Use case | Credits |
+|-------|----------|---------|
+| `varg.imageModel("nano-banana-pro")` | Versatile, fast | 5 |
+| `varg.imageModel("nano-banana-pro/edit")` | Image-to-image editing | 5 |
+| `varg.imageModel("flux-schnell")` | Fast generation | 5 |
+| `varg.imageModel("flux-pro")` | High quality | 25 |
+| `varg.imageModel("recraft-v3")` | Alternative | 10 |
+
+### Audio
+
+| Model | Use case | Credits |
+|-------|----------|---------|
+| `varg.speechModel("eleven_v3")` | Text-to-speech | 25 |
+| `varg.speechModel("eleven_multilingual_v2")` | Multilingual TTS | 25 |
+| `varg.musicModel()` | Music generation | 25 |
+| `varg.transcriptionModel("whisper")` | Speech-to-text | 5 |
+
+1 credit = $0.01. Cache hits are always free.
+
+## CLI
+
+```bash
+bunx vargai login                              # sign in (email OTP or API key)
+bunx vargai init                               # set up project (auth + skills + template)
+bunx vargai render video.tsx                   # render a video
+bunx vargai render video.tsx --preview         # free preview with placeholders
+bunx vargai render video.tsx --verbose         # render with detailed output
+bunx vargai balance                            # check credit balance
+bunx vargai topup                              # add credits
+bunx vargai run image --prompt "sunset"        # generate a single image
+bunx vargai run video --prompt "ocean waves"   # generate a single video
+bunx vargai list                               # list available models and actions
+bunx vargai studio                             # open visual editor
+```
+
+## Environment
+
+```bash
+# Required — one key for everything
+VARG_API_KEY=varg_live_xxx
+```
+
+Get your API key at [app.varg.ai](https://app.varg.ai). Bun auto-loads `.env` files.
 
 <details>
-<summary>Required API keys</summary>
+<summary>Bring your own keys (optional)</summary>
+
+You can use provider keys directly if you prefer:
 
 ```bash
-# AI Providers
-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
-HIGGSFIELD_SECRET=secret_xxx
-
-# Storage (Cloudflare R2)
-CLOUDFLARE_R2_API_URL=https://xxx.r2.cloudflarestorage.com
-CLOUDFLARE_ACCESS_KEY_ID=xxx
-CLOUDFLARE_ACCESS_SECRET=xxx
-CLOUDFLARE_R2_BUCKET=bucket-name
+FAL_API_KEY=fal_xxx                # fal.ai direct
+ELEVENLABS_API_KEY=xxx             # ElevenLabs direct
+OPENAI_API_KEY=sk_xxx              # OpenAI / Sora
+REPLICATE_API_TOKEN=r8_xxx         # Replicate
 ```
 
+See the [BYOK docs](https://docs.varg.ai/sdk/byok) for details.
+
 </details>
 
+## Pricing
+
+| Action | Model | Credits | Cost |
+|--------|-------|---------|------|
+| Image | nano-banana-pro | 5 | $0.05 |
+| Image | flux-pro | 25 | $0.25 |
+| Video (5s) | kling-v3 | 150 | $1.50 |
+| Speech | eleven_v3 | 25 | $0.25 |
+| Music | music_v1 | 25 | $0.25 |
+| Cache hit | any | 0 | $0.00 |
+
+A typical 3-clip video costs $2-5. Cache hits are always free.
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup.

package/garry-tan-varg.tsx

@@ -0,0 +1,46 @@
+import { elevenlabs, fal } from "vargai/ai";
+import {
+  Captions,
+  Clip,
+  Image,
+  Render,
+  render,
+  Speech,
+  Video,
+} from "vargai/react";
+
+// Garry Tan's face image
+const GARRY_TAN_IMAGE =
+  "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRLInrQmohhXbLY10G90yT0AJJCJdArYifp-IDKUmJQlwui0tnLihiHw9OzLfLfbofr5chH2s4&s=10";
+
+// Create speech first
+const voiceover = Speech({
+  model: elevenlabs.speechModel("eleven_v3"),
+  voice: "adam",
+  children: "varg.ai is cool!",
+});
+
+// Animate Garry's face to talk
+const animatedGarry = Video({
+  prompt: {
+    text: "man speaking naturally, subtle head movements, friendly expression",
+    images: [GARRY_TAN_IMAGE],
+  },
+  model: fal.videoModel("kling-v2.5"),
+});
+
+// Sync lip movements with audio
+const syncedVideo = Video({
+  prompt: { video: animatedGarry, audio: voiceover },
+  model: fal.videoModel("sync-v2-pro"),
+});
+
+await render(
+  <Render width={1080} height={1920}>
+    <Clip duration={5}>{syncedVideo}</Clip>
+    <Captions src={voiceover} style="tiktok" color="#ffffff" withAudio />
+  </Render>,
+  { output: "output/garry-tan-varg.mp4" },
+);
+
+console.log("Done! Video saved to output/garry-tan-varg.mp4");

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",
@@ -33,19 +33,24 @@
     "lint-staged": "^16.2.7"
   },
   "peerDependencies": {
-    "typescript": "^5"
+    "typescript": "^5",
+    "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/google": "^3.0.13",
     "@ai-sdk/groq": "^3.0.12",
     "@ai-sdk/openai": "^3.0.9",
     "@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",
     "@elevenlabs/elevenlabs-js": "^2.28.0",
     "@fal-ai/client": "^1.7.2",
+    "@google/genai": "^1.0.0",
     "@higgsfield/client": "^0.1.2",
     "@inkjs/ui": "^2.0.0",
     "@remotion/cli": "^4.0.377",
@@ -56,13 +61,50 @@
     "fluent-ffmpeg": "^2.1.3",
     "groq-sdk": "^0.36.0",
     "ink": "^6.5.1",
+    "p-limit": "^6.2.0",
+    "p-map": "^7.0.4",
     "react": "^19.2.0",
     "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-alpha.1",
+  "description": "AI video generation SDK — JSX for videos. Generate, compose and render AI videos with Kling, Flux, ElevenLabs, and more through one API. Built on Vercel AI SDK.",
+  "keywords": [
+    "ai-video",
+    "video-generation",
+    "ai-sdk",
+    "typescript",
+    "jsx",
+    "text-to-video",
+    "image-to-video",
+    "ai-video-api",
+    "kling",
+    "flux",
+    "elevenlabs",
+    "vercel-ai-sdk",
+    "video-editing",
+    "ai-tools",
+    "generative-ai",
+    "video-api",
+    "text-to-speech",
+    "music-generation",
+    "lipsync",
+    "video-rendering"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vargHQ/sdk.git"
+  },
+  "homepage": "https://varg.ai",
+  "bugs": {
+    "url": "https://github.com/vargHQ/sdk/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "varg.ai <hello@varg.ai> (https://varg.ai)",
+  "sideEffects": false,
+  "version": "0.4.0-alpha100",
   "exports": {
     ".": "./src/index.ts",
     "./ai": "./src/ai-sdk/index.ts",
@@ -70,6 +112,10 @@
     "./providers": "./src/providers/index.ts",
     "./definitions": "./src/definitions/index.ts",
     "./react": "./src/react/index.ts",
-    "./studio": "./src/studio/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",
+    "./editly": "./src/ai-sdk/providers/editly/index.ts",
+    "./file": "./src/ai-sdk/file.ts"
   }
 }

package/src/ai-sdk/cache.ts

@@ -11,7 +11,10 @@ export interface WithCacheOptions {
 
 type CacheKeyDeps = (string | number | boolean | null | undefined)[];
 
-type WithCacheKey<T> = Omit<T, "cacheKey"> & { cacheKey?: CacheKeyDeps };
+type WithCacheKey<T> = Omit<T, "cacheKey" | "skipCacheWrite"> & {
+  cacheKey?: CacheKeyDeps;
+  skipCacheWrite?: boolean;
+};
 
 type CachedFn<T, R> = (options: WithCacheKey<T>) => Promise<R>;
 
@@ -43,7 +46,7 @@ function parseTTL(ttl: number | string | undefined): number | undefined {
   const match = ttl.match(/^(\d+)(s|m|h|d)$/);
   if (!match) return undefined;
 
-  const value = Number.parseInt(match[1]!, 10);
+  const value = Number.parseInt(match[1] ?? "0", 10);
   const unit = match[2];
 
   switch (unit) {
@@ -60,7 +63,8 @@ function parseTTL(ttl: number | string | undefined): number | undefined {
   }
 }
 
-function depsToKey(prefix: string, deps: CacheKeyDeps): string {
+/** Build a cache key string from a prefix and an array of dependencies. */
+export function depsToKey(prefix: string, deps: CacheKeyDeps): string {
   const depsStr = deps.map((d) => String(d ?? "")).join(":");
   return prefix ? `${prefix}:${depsStr}` : depsStr;
 }
@@ -106,7 +110,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>,
@@ -115,9 +119,8 @@ export function withCache<T extends object, R>(
   const storage = options.storage ?? defaultStorage;
   const ttl = parseTTL(options.ttl ?? DEFAULT_TTL);
   const prefix = fn.name || "anonymous";
-
   return async (opts: WithCacheKey<T>): Promise<R> => {
-    const { cacheKey, ...rest } = opts;
+    const { cacheKey, skipCacheWrite, ...rest } = opts;
 
     if (!cacheKey) {
       return fn(rest as T);
@@ -128,10 +131,11 @@ export function withCache<T extends object, R>(
     if (cached !== undefined) {
       return cached as R;
     }
-
     const result = await fn(rest as T);
-    const flattened = flatten(result);
-    await storage.set(key, flattened, ttl);
+    if (!skipCacheWrite) {
+      const flattened = flatten(result);
+      await storage.set(key, flattened, ttl);
+    }
 
     return result;
   };