@vargai/sdk 0.1.1

package/cli/ui.ts

@@ -0,0 +1,185 @@
+/**
+ * terminal ui helpers for varg cli
+ * beautiful boxes and formatting
+ */
+
+const COLORS = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  red: "\x1b[31m",
+  gray: "\x1b[90m",
+};
+
+export const c = {
+  reset: (s: string) => `${COLORS.reset}${s}${COLORS.reset}`,
+  bold: (s: string) => `${COLORS.bold}${s}${COLORS.reset}`,
+  dim: (s: string) => `${COLORS.dim}${s}${COLORS.reset}`,
+  green: (s: string) => `${COLORS.green}${s}${COLORS.reset}`,
+  yellow: (s: string) => `${COLORS.yellow}${s}${COLORS.reset}`,
+  blue: (s: string) => `${COLORS.blue}${s}${COLORS.reset}`,
+  magenta: (s: string) => `${COLORS.magenta}${s}${COLORS.reset}`,
+  cyan: (s: string) => `${COLORS.cyan}${s}${COLORS.reset}`,
+  red: (s: string) => `${COLORS.red}${s}${COLORS.reset}`,
+  gray: (s: string) => `${COLORS.gray}${s}${COLORS.reset}`,
+};
+
+// strip ansi codes for length calculation
+// biome-ignore lint/complexity/useRegexLiterals: literal triggers noControlCharactersInRegex
+const ANSI_REGEX = new RegExp("\x1b\\[[0-9;]*m", "g");
+function stripAnsi(s: string): string {
+  return s.replace(ANSI_REGEX, "");
+}
+
+// box drawing characters
+const BOX = {
+  topLeft: "┌",
+  topRight: "┐",
+  bottomLeft: "└",
+  bottomRight: "┘",
+  horizontal: "─",
+  vertical: "│",
+  line: "─",
+};
+
+export const WIDTH = 71;
+
+export function box(title: string, content: string[]): string {
+  const lines: string[] = [];
+
+  // top border with title
+  const titlePart = title ? `${BOX.line} ${title} ` : "";
+  const remainingWidth = WIDTH - 2 - stripAnsi(titlePart).length;
+  lines.push(
+    `${BOX.topLeft}${titlePart}${BOX.horizontal.repeat(remainingWidth)}${BOX.topRight}`,
+  );
+
+  // content lines
+  for (const line of content) {
+    const stripped = stripAnsi(line);
+    const padding = WIDTH - 2 - stripped.length;
+    if (padding >= 0) {
+      lines.push(`${BOX.vertical}${line}${" ".repeat(padding)}${BOX.vertical}`);
+    } else {
+      // truncate if too long
+      lines.push(
+        `${BOX.vertical}${line.slice(0, WIDTH - 5)}...${BOX.vertical}`,
+      );
+    }
+  }
+
+  // bottom border
+  lines.push(
+    `${BOX.bottomLeft}${BOX.horizontal.repeat(WIDTH - 2)}${BOX.bottomRight}`,
+  );
+
+  return lines.join("\n");
+}
+
+export function separator(): string {
+  return `  ${c.dim(BOX.horizontal.repeat(WIDTH - 4))}`;
+}
+
+export function header(text: string): string {
+  return c.bold(c.dim(`  ${text}`));
+}
+
+export function row(label: string, value: string, indent = 2): string {
+  const spaces = " ".repeat(indent);
+  const labelWidth = 14;
+  const paddedLabel = label.padEnd(labelWidth);
+  return `${spaces}${c.dim(paddedLabel)}${value}`;
+}
+
+export function success(message: string): string {
+  return `  ${c.green("✓")} ${message}`;
+}
+
+export function error(message: string): string {
+  return `  ${c.red("✗")} ${message}`;
+}
+
+export function spinner(message: string): string {
+  return `  ${c.cyan("◐")} ${message}`;
+}
+
+export function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`;
+  const s = Math.round(ms / 1000);
+  return `${s}s`;
+}
+
+export function formatCost(dollars: number): string {
+  return `$${dollars.toFixed(3)}`;
+}
+
+// table formatting for list command
+export interface TableRow {
+  name: string;
+  description: string;
+  providers?: string;
+}
+
+export function table(rows: TableRow[], nameWidth = 16): string[] {
+  const lines: string[] = [];
+
+  for (const row of rows) {
+    const name = row.name.padEnd(nameWidth);
+    const desc = row.description;
+    const providers = row.providers ? c.dim(row.providers) : "";
+
+    if (providers) {
+      lines.push(`  ${c.cyan(name)}${desc.padEnd(30)}${providers}`);
+    } else {
+      lines.push(`  ${c.cyan(name)}${desc}`);
+    }
+  }
+
+  return lines;
+}
+
+// progress output for running commands
+export function runningBox(
+  name: string,
+  params: Record<string, string>,
+  status: "running" | "done" | "error",
+  result?: { output?: string; cost?: number; error?: string; time?: number },
+): string {
+  const content: string[] = [""];
+
+  // params
+  for (const [key, value] of Object.entries(params)) {
+    const displayValue =
+      value.length > 40 ? `"${value.slice(0, 37)}..."` : `"${value}"`;
+    content.push(row(key, displayValue));
+  }
+
+  content.push("");
+
+  // status
+  if (status === "running") {
+    content.push(spinner("generating..."));
+  } else if (status === "done" && result) {
+    content.push(success(`done in ${formatDuration(result.time || 0)}`));
+    content.push("");
+    if (result.output) {
+      content.push(row("output", result.output));
+    }
+    if (result.cost) {
+      content.push(row("cost", formatCost(result.cost)));
+    }
+  } else if (status === "error" && result?.error) {
+    content.push(error("failed"));
+    content.push("");
+    content.push(row("error", result.error));
+  }
+
+  content.push("");
+
+  return box(name, content);
+}

package/index.ts

@@ -0,0 +1,75 @@
+/**
+ * varg.ai sdk
+ * video generation and editing tools
+ */
+
+// re-export external clients
+export { fal } from "@ai-sdk/fal";
+export { replicate } from "@ai-sdk/replicate";
+export { fal as falClient } from "@fal-ai/client";
+export { HiggsfieldClient } from "@higgsfield/client";
+// action exports (excluding meta to avoid conflicts)
+export {
+  type AddCaptionsOptions,
+  addCaptions,
+  type SubtitleStyle,
+} from "./action/captions";
+export {
+  type CreateMontageOptions,
+  createMontage,
+  type EditPipelineOptions,
+  type EditPipelineStep,
+  editPipeline,
+  mergeWithAudio,
+  type PrepareForSocialOptions,
+  prepareForSocial,
+  quickResize,
+  quickTrim,
+} from "./action/edit";
+export {
+  generateWithFal,
+  generateWithSoul,
+  type ImageGenerationResult,
+} from "./action/image";
+export {
+  type LipsyncOptions,
+  lipsync,
+  lipsyncOverlay,
+  lipsyncWav2Lip,
+  type Wav2LipOptions,
+} from "./action/sync";
+export {
+  type TranscribeOptions,
+  type TranscribeResult,
+  transcribe,
+} from "./action/transcribe";
+export {
+  generateVideoFromImage,
+  generateVideoFromText,
+  type VideoGenerationResult,
+} from "./action/video";
+export {
+  type GenerateVoiceOptions,
+  generateVoice,
+  type VoiceResult,
+} from "./action/voice";
+// lib exports - ai-sdk/fal (provider)
+export * as aiSdkFal from "./lib/ai-sdk/fal";
+// lib exports - ai-sdk/replicate (provider)
+export * as aiSdkReplicate from "./lib/ai-sdk/replicate";
+// lib exports - elevenlabs
+export * from "./lib/elevenlabs";
+// lib exports - fal (client)
+export * from "./lib/fal";
+// lib exports - ffmpeg
+export * from "./lib/ffmpeg";
+// lib exports - fireworks
+export * from "./lib/fireworks";
+// lib exports - groq
+export * from "./lib/groq";
+// lib exports - higgsfield
+export * from "./lib/higgsfield";
+// lib exports - replicate
+export * from "./lib/replicate";
+// utilities exports
+export * from "./utilities/s3";

package/lib/README.md

@@ -0,0 +1,144 @@
+# lib/ modules
+
+## two fal implementations
+
+### lib/ai-sdk/fal.ts - ai-sdk provider (recommended for images)
+
+uses `@ai-sdk/fal` with the vercel ai sdk's `experimental_generateImage`
+
+**benefits:**
+- clean, typed api via vercel ai sdk
+- automatic image format handling (uint8array)
+- consistent interface with other ai providers
+- built-in aspect ratio support
+- better for standard image generation
+
+**example:**
+```bash
+bun run lib/ai-sdk/fal.ts generate_image "cyberpunk city" "fal-ai/flux/dev" "16:9"
+```
+
+**code:**
+```typescript
+import { fal } from "@ai-sdk/fal"
+import { experimental_generateImage as generateImage } from "ai"
+
+const { image, providerMetadata } = await generateImage({
+  model: fal.image("fal-ai/flux/dev"),
+  prompt: "beautiful sunset",
+  aspectRatio: "16:9",
+})
+```
+
+### lib/fal.ts - fal client direct (for video & advanced features)
+
+uses `@fal-ai/client` directly with the raw fal api
+
+**benefits:**
+- access to all fal features (video, advanced params)
+- streaming/queue updates
+- full control over api parameters
+- required for video generation (no ai-sdk support yet)
+- **supports local images** - automatically uploads local files to fal storage
+
+**examples:**
+```bash
+# image generation
+bun run lib/fal.ts generate_image "aurora borealis" "fal-ai/flux-pro/v1.1"
+
+# video from url
+bun run lib/fal.ts image_to_video "person talking" "https://image.url" 5
+
+# video from local file (auto-uploads)
+bun run lib/fal.ts image_to_video "ocean waves" "./media/beach.jpg" 10
+```
+
+**code:**
+```typescript
+import { imageToVideo } from "./lib/fal"
+
+// works with both urls and local files
+const result = await imageToVideo({
+  prompt: "person talking",
+  imageUrl: "./local/image.jpg", // or "https://..."
+  duration: 5,
+})
+
+// local files are automatically uploaded to fal storage
+```
+
+## when to use which?
+
+| use case | approach |
+|----------|----------|
+| standard image generation | ai-sdk provider ✓ |
+| video generation | fal client direct ✓ |
+| advanced fal features | fal client direct ✓ |
+| multi-provider app | ai-sdk provider ✓ |
+| custom queue handling | fal client direct ✓ |
+
+## higgsfield.ts
+
+uses `@higgsfield/client` for soul character generation
+
+**features:**
+- generate soul images with custom styles
+- create and manage character references
+- list available soul styles
+- poll for job completion
+
+**example:**
+```bash
+HF_API_KEY=xxx HF_API_SECRET=xxx bun run lib/higgsfield.ts generate_soul "professional headshot"
+```
+
+## elevenlabs.ts
+
+uses `@elevenlabs/elevenlabs-js` for voice, music, and sound effects generation
+
+**features:**
+- text-to-speech with multiple voices
+- music generation from text prompts
+- sound effects generation
+- voice management
+
+**examples:**
+```bash
+# text-to-speech
+bun run lib/elevenlabs.ts tts "hello world" rachel output.mp3
+
+# music generation
+bun run lib/elevenlabs.ts music "upbeat electronic dance music" 30000 music.mp3
+
+# sound effects
+bun run lib/elevenlabs.ts sfx "ocean waves crashing" 5 waves.mp3
+
+# list voices
+bun run lib/elevenlabs.ts voices
+```
+
+**code:**
+```typescript
+import { textToSpeech, generateMusic, generateSoundEffect } from "./lib/elevenlabs"
+
+// voice
+const audio = await textToSpeech({
+  text: "hello world",
+  voiceId: "rachel",
+  outputPath: "output.mp3"
+})
+
+// music
+const music = await generateMusic({
+  prompt: "epic orchestral music",
+  musicLengthMs: 60000,
+  outputPath: "music.mp3"
+})
+
+// sound effects
+const sfx = await generateSoundEffect({
+  text: "thunder and rain",
+  durationSeconds: 10,
+  outputPath: "sfx.mp3"
+})
+```

package/lib/ai-sdk/fal.ts

@@ -0,0 +1,106 @@
+#!/usr/bin/env bun
+/**
+ * fal.ai wrapper using @ai-sdk/fal provider
+ * recommended for standard image generation with vercel ai sdk
+ *
+ * usage: bun run lib/ai-sdk/fal.ts <command> <args>
+ */
+
+import { fal } from "@ai-sdk/fal";
+import { experimental_generateImage as generateImageAI } from "ai";
+
+export async function generateImage(args: {
+  prompt: string;
+  model?: string;
+  aspectRatio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4";
+}) {
+  const modelId = args.model || "fal-ai/flux/dev";
+
+  console.log(`[ai-sdk/fal] generating image with ${modelId}`);
+  console.log(`[ai-sdk/fal] prompt: ${args.prompt}`);
+  if (args.aspectRatio) {
+    console.log(`[ai-sdk/fal] aspect ratio: ${args.aspectRatio}`);
+  }
+
+  try {
+    const { image, providerMetadata } = await generateImageAI({
+      model: fal.image(modelId),
+      prompt: args.prompt,
+      aspectRatio: args.aspectRatio,
+    });
+
+    console.log("[ai-sdk/fal] completed!");
+
+    // return in consistent format
+    return {
+      image: {
+        url: image.base64 ? `data:image/png;base64,${image.base64}` : undefined,
+        uint8Array: image.uint8Array,
+      },
+      metadata: providerMetadata?.fal,
+    };
+  } catch (error) {
+    console.error("[ai-sdk/fal] error:", error);
+    throw error;
+  }
+}
+
+// cli runner
+if (import.meta.main) {
+  const [command, ...args] = process.argv.slice(2);
+
+  switch (command) {
+    case "generate_image": {
+      if (!args[0]) {
+        console.log(`
+usage:
+  bun run lib/ai-sdk/fal.ts generate_image <prompt> [model] [aspectRatio]
+
+examples:
+  bun run lib/ai-sdk/fal.ts generate_image "sunset over ocean" "fal-ai/flux/dev" "16:9"
+  bun run lib/ai-sdk/fal.ts generate_image "portrait photo" "fal-ai/flux-pro/v1.1" "9:16"
+
+available models:
+  - fal-ai/flux/dev (default, fast)
+  - fal-ai/flux-pro/v1.1 (high quality)
+  - fal-ai/flux/schnell (very fast)
+  - fal-ai/ideogram/character (character consistency)
+        `);
+        process.exit(1);
+      }
+
+      const result = await generateImage({
+        prompt: args[0],
+        model: args[1],
+        aspectRatio: args[2] as
+          | "1:1"
+          | "16:9"
+          | "9:16"
+          | "4:3"
+          | "3:4"
+          | undefined,
+      });
+
+      // save image to file
+      if (result.image.uint8Array) {
+        const filename = `/tmp/fal-ai-sdk-${Date.now()}.png`;
+        await Bun.write(filename, result.image.uint8Array);
+        console.log(`\nimage saved to: ${filename}`);
+
+        // open image
+        await Bun.spawn(["open", filename]);
+      }
+
+      console.log("\nmetadata:");
+      console.log(JSON.stringify(result.metadata, null, 2));
+      break;
+    }
+
+    default:
+      console.log(`
+usage:
+  bun run lib/ai-sdk/fal.ts generate_image <prompt> [model] [aspectRatio]
+      `);
+      process.exit(1);
+  }
+}

package/lib/ai-sdk/replicate.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env bun
+/**
+ * replicate wrapper using @ai-sdk/replicate provider
+ * recommended for standard image generation with vercel ai sdk
+ *
+ * usage: bun run lib/ai-sdk/replicate.ts <command> <args>
+ */
+
+import { replicate } from "@ai-sdk/replicate";
+import { experimental_generateImage as generateImageAI } from "ai";
+
+export async function generateImage(args: {
+  prompt: string;
+  model?: string;
+  aspectRatio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4";
+}) {
+  const modelId = args.model || "black-forest-labs/flux-dev";
+
+  console.log(`[ai-sdk/replicate] generating image with ${modelId}`);
+  console.log(`[ai-sdk/replicate] prompt: ${args.prompt}`);
+  if (args.aspectRatio) {
+    console.log(`[ai-sdk/replicate] aspect ratio: ${args.aspectRatio}`);
+  }
+
+  try {
+    const { image, providerMetadata } = await generateImageAI({
+      model: replicate.image(modelId),
+      prompt: args.prompt,
+      aspectRatio: args.aspectRatio,
+    });
+
+    console.log("[ai-sdk/replicate] completed!");
+
+    // return in consistent format
+    return {
+      image: {
+        url: image.base64 ? `data:image/png;base64,${image.base64}` : undefined,
+        uint8Array: image.uint8Array,
+      },
+      metadata: providerMetadata?.replicate,
+    };
+  } catch (error) {
+    console.error("[ai-sdk/replicate] error:", error);
+    throw error;
+  }
+}
+
+// cli runner
+if (import.meta.main) {
+  const [command, ...args] = process.argv.slice(2);
+
+  switch (command) {
+    case "generate_image": {
+      if (!args[0]) {
+        console.log(`
+usage:
+  bun run lib/ai-sdk/replicate.ts generate_image <prompt> [model] [aspectRatio]
+
+examples:
+  bun run lib/ai-sdk/replicate.ts generate_image "sunset over ocean" "black-forest-labs/flux-dev" "16:9"
+  bun run lib/ai-sdk/replicate.ts generate_image "portrait photo" "black-forest-labs/flux-1.1-pro" "9:16"
+  bun run lib/ai-sdk/replicate.ts generate_image "cyberpunk city" "black-forest-labs/flux-schnell" "1:1"
+
+available models:
+  - black-forest-labs/flux-dev (default, fast)
+  - black-forest-labs/flux-1.1-pro (high quality)
+  - black-forest-labs/flux-schnell (very fast)
+  - stability-ai/sdxl (stable diffusion xl)
+        `);
+        process.exit(1);
+      }
+
+      const result = await generateImage({
+        prompt: args[0],
+        model: args[1],
+        aspectRatio: args[2] as
+          | "1:1"
+          | "16:9"
+          | "9:16"
+          | "4:3"
+          | "3:4"
+          | undefined,
+      });
+
+      // save image to file
+      if (result.image.uint8Array) {
+        const filename = `/tmp/replicate-ai-sdk-${Date.now()}.png`;
+        await Bun.write(filename, result.image.uint8Array);
+        console.log(`\nimage saved to: ${filename}`);
+
+        // open image
+        await Bun.spawn(["open", filename]);
+      }
+
+      console.log("\nmetadata:");
+      console.log(JSON.stringify(result.metadata, null, 2));
+      break;
+    }
+
+    default:
+      console.log(`
+usage:
+  bun run lib/ai-sdk/replicate.ts generate_image <prompt> [model] [aspectRatio]
+      `);
+      process.exit(1);
+  }
+}