varg.ai-sdk 0.1.1 → 0.4.0-alpha.1

package/action/voice/SKILL.md

@@ -1,125 +0,0 @@
----
-name: voice-synthesis
-description: generate realistic text-to-speech audio using elevenlabs with multiple voice options. use when user needs voiceovers, narration, character voices, or audio for lipsync videos.
-allowed-tools: Read, Bash
----
-
-# voice synthesis
-
-generate high-quality text-to-speech audio with elevenlabs.
-
-## available voices
-
-- **rachel** - clear, professional female voice
-- **domi** - warm, friendly female voice
-- **bella** - energetic female voice
-- **antoni** - friendly male voice
-- **elli** - young, clear female voice
-- **josh** - deep, clear male voice
-- **arnold** - strong, authoritative male voice
-- **adam** - natural, conversational male voice
-- **sam** - raspy, character male voice
-
-## usage
-
-### generate voice
-```bash
-bun run service/voice.ts generate <text> [voice] [provider] [upload]
-```
-
-**parameters:**
-- `text` (required): text to convert to speech
-- `voice` (optional): voice name (default: rachel)
-- `provider` (optional): elevenlabs (default)
-- `upload` (optional): "true" to upload to s3
-
-**example:**
-```bash
-bun run service/voice.ts generate "hello world, this is my voice" rachel elevenlabs true
-```
-
-### shorthand for elevenlabs
-```bash
-bun run service/voice.ts elevenlabs <text> [voice] [upload]
-```
-
-**example:**
-```bash
-bun run service/voice.ts elevenlabs "welcome to our video" josh true
-```
-
-## as library
-
-```typescript
-import { generateVoice } from "./service/voice"
-
-const result = await generateVoice({
-  text: "hello world",
-  voice: "rachel",
-  provider: "elevenlabs",
-  upload: true,
-  outputPath: "media/voiceover.mp3"
-})
-
-console.log(result.provider)
-console.log(result.voiceId)
-console.log(result.uploadUrl)
-```
-
-## output
-
-returns `VoiceResult`:
-```typescript
-{
-  audio: Buffer,         // raw audio buffer
-  provider: string,      // "elevenlabs"
-  voiceId: string,       // actual voice id used
-  uploadUrl?: string     // s3 url if upload requested
-}
-```
-
-saves audio file to `media/voice-{timestamp}.mp3`
-
-## when to use
-
-use this skill when:
-- creating voiceovers for videos
-- generating narration or character dialogue
-- preparing audio for lipsync videos
-- need text-to-speech for talking character pipeline
-- testing different voice options
-
-## tips
-
-**voice selection:**
-- use **rachel** or **josh** for professional narration
-- use **bella** or **antoni** for friendly, casual content
-- use **arnold** for authoritative or dramatic content
-- use **sam** for character or stylized voices
-
-**text formatting:**
-- add punctuation for natural pauses
-- use shorter sentences for clearer speech
-- spell out numbers and abbreviations
-
-## integration with other services
-
-perfect companion for:
-- **lipsync service** - sync generated voice with video
-- **video generation** - create talking character videos
-- **captions service** - auto-generate subtitles from voiceover
-
-## environment variables
-
-required:
-- `ELEVENLABS_API_KEY` - for voice generation
-
-optional (for s3 upload):
-- `CLOUDFLARE_R2_API_URL`
-- `CLOUDFLARE_ACCESS_KEY_ID`
-- `CLOUDFLARE_ACCESS_SECRET`
-- `CLOUDFLARE_R2_BUCKET`
-
-## generation time
-
-expect 5-15 seconds depending on text length

package/action/voice/index.ts

@@ -1,136 +0,0 @@
-#!/usr/bin/env bun
-
-/**
- * voice service - high-level voice generation combining multiple providers
- * supports elevenlabs and future providers
- */
-
-import type { ActionMeta } from "../../cli/types";
-import { textToSpeech, VOICES } from "../../lib/elevenlabs";
-import { uploadFile } from "../../utilities/s3";
-
-export const meta: ActionMeta = {
-  name: "voice",
-  type: "action",
-  description: "text to speech generation",
-  inputType: "text",
-  outputType: "audio",
-  schema: {
-    input: {
-      type: "object",
-      required: ["text"],
-      properties: {
-        text: { type: "string", description: "text to convert to speech" },
-        voice: {
-          type: "string",
-          enum: ["rachel", "domi", "bella", "antoni", "josh", "adam", "sam"],
-          default: "rachel",
-          description: "voice to use",
-        },
-        output: {
-          type: "string",
-          format: "file-path",
-          description: "output file path",
-        },
-      },
-    },
-    output: { type: "string", format: "file-path", description: "audio path" },
-  },
-  async run(options) {
-    const { text, voice, output } = options as {
-      text: string;
-      voice?: string;
-      output?: string;
-    };
-    return generateVoice({ text, voice, outputPath: output });
-  },
-};
-
-// types
-export interface GenerateVoiceOptions {
-  text: string;
-  voice?: string;
-  provider?: "elevenlabs";
-  upload?: boolean;
-  outputPath?: string;
-}
-
-export interface VoiceResult {
-  audio: Buffer;
-  provider: string;
-  voiceId: string;
-  uploadUrl?: string;
-}
-
-// core functions
-export async function generateVoice(
-  options: GenerateVoiceOptions,
-): Promise<VoiceResult> {
-  const {
-    text,
-    voice = "rachel",
-    provider = "elevenlabs",
-    upload = false,
-    outputPath,
-  } = options;
-
-  if (!text) {
-    throw new Error("text is required");
-  }
-
-  console.log(`[voice] generating with ${provider} (${voice})...`);
-
-  let audio: Buffer;
-  let voiceId: string;
-
-  switch (provider) {
-    case "elevenlabs": {
-      // map friendly names to voice ids
-      const voiceMap: Record<string, string> = {
-        rachel: VOICES.RACHEL,
-        domi: VOICES.DOMI,
-        bella: VOICES.BELLA,
-        antoni: VOICES.ANTONI,
-        elli: VOICES.ELLI,
-        josh: VOICES.JOSH,
-        arnold: VOICES.ARNOLD,
-        adam: VOICES.ADAM,
-        sam: VOICES.SAM,
-      };
-
-      voiceId = voiceMap[voice.toLowerCase()] || voice;
-
-      audio = await textToSpeech({
-        text,
-        voiceId,
-        outputPath,
-      });
-      break;
-    }
-
-    default:
-      throw new Error(`unsupported provider: ${provider}`);
-  }
-
-  const result: VoiceResult = {
-    audio,
-    provider,
-    voiceId,
-  };
-
-  // upload to s3 if requested
-  if (upload && outputPath) {
-    const objectKey = `voice/${Date.now()}-${voice}.mp3`;
-    const uploadUrl = await uploadFile(outputPath, objectKey);
-    result.uploadUrl = uploadUrl;
-    console.log(`[voice] uploaded to ${uploadUrl}`);
-  }
-
-  return result;
-}
-
-// cli
-if (import.meta.main) {
-  const { runCli } = await import("../../cli/runner");
-  runCli(meta);
-}

package/cli/commands/find.ts

@@ -1,58 +0,0 @@
-/**
- * varg find command
- * fuzzy search by scanning filesystem
- */
-
-import { defineCommand } from "citty";
-import { search } from "../discover";
-import { box, c, header, separator } from "../ui";
-
-export const findCmd = defineCommand({
-  meta: {
-    name: "find",
-    description: "fuzzy search for models/actions",
-  },
-  args: {
-    query: {
-      type: "positional",
-      description: "search query",
-      required: true,
-    },
-  },
-  async run({ args }) {
-    const query = args.query;
-
-    if (!query) {
-      console.error(`${c.red("error:")} search query required`);
-      console.log(`\nusage: ${c.cyan("varg find <query>")}`);
-      process.exit(1);
-    }
-
-    const results = await search(query);
-
-    if (results.length === 0) {
-      console.log(`\nno matches for "${query}"`);
-      console.log(`\ntry ${c.cyan("varg list")} to see all available actions`);
-      return;
-    }
-
-    const content: string[] = [];
-    content.push("");
-    content.push(header("MATCHES"));
-    content.push("");
-
-    for (const action of results) {
-      content.push(
-        `  ${c.cyan(action.name.padEnd(16))}${action.inputType} → ${action.outputType}`,
-      );
-    }
-
-    content.push("");
-    content.push(separator());
-    content.push("");
-    content.push(`  run ${c.cyan("varg run <name> --help")} for usage`);
-    content.push("");
-
-    console.log(box(`search: "${query}"`, content));
-  },
-});

package/cli/commands/help.ts

@@ -1,70 +0,0 @@
-/**
- * varg help command
- */
-
-import { defineCommand } from "citty";
-import { box, c, header, separator } from "../ui";
-
-export const helpCmd = defineCommand({
-  meta: {
-    name: "help",
-    description: "show help",
-  },
-  run() {
-    const content: string[] = [];
-    content.push("");
-    content.push("  AI video infrastructure from your terminal.");
-    content.push("");
-    content.push(separator());
-    content.push("");
-    content.push(header("USAGE"));
-    content.push("");
-    content.push(`  varg ${c.cyan("<command>")} [target] [options]`);
-    content.push("");
-    content.push(separator());
-    content.push("");
-    content.push(header("COMMANDS"));
-    content.push("");
-    content.push(`  ${c.cyan("run".padEnd(12))}run a model or action`);
-    content.push(`  ${c.cyan("list".padEnd(12))}discover what's available`);
-    content.push(
-      `  ${c.cyan("find".padEnd(12))}fuzzy search for models/actions`,
-    );
-    content.push(
-      `  ${c.cyan("which".padEnd(12))}inspect what's behind an action`,
-    );
-    content.push(`  ${c.cyan("help".padEnd(12))}show this help`);
-    content.push("");
-    content.push(separator());
-    content.push("");
-    content.push(header("EXAMPLES"));
-    content.push("");
-    content.push(`  ${c.dim("# generate video from text")}`);
-    content.push(`  varg run kling --prompt "a cat dancing"`);
-    content.push("");
-    content.push(`  ${c.dim("# animate an image")}`);
-    content.push(`  varg run image-to-video --image ./cat.png`);
-    content.push("");
-    content.push(`  ${c.dim("# transcribe audio")}`);
-    content.push(`  varg run transcribe ./video.mp4`);
-    content.push("");
-    content.push(`  ${c.dim("# see what's available")}`);
-    content.push(`  varg list`);
-    content.push("");
-    content.push(separator());
-    content.push("");
-    content.push(header("ENVIRONMENT"));
-    content.push("");
-    content.push(`  ${c.dim("FAL_KEY".padEnd(24))}fal.ai api key`);
-    content.push(
-      `  ${c.dim("REPLICATE_API_TOKEN".padEnd(24))}replicate api key`,
-    );
-    content.push(
-      `  ${c.dim("ELEVENLABS_API_KEY".padEnd(24))}elevenlabs api key`,
-    );
-    content.push(`  ${c.dim("GROQ_API_KEY".padEnd(24))}groq api key`);
-    content.push("");
-
-    console.log(box("varg", content));
-  },
-});

package/cli/commands/list.ts

@@ -1,49 +0,0 @@
-/**
- * varg list command
- * discover what's available by scanning filesystem
- */
-
-import { defineCommand } from "citty";
-import { discoverActions } from "../discover";
-import { box, c, header, separator, table } from "../ui";
-
-export const listCmd = defineCommand({
-  meta: {
-    name: "list",
-    description: "discover what's available",
-  },
-  args: {
-    filter: {
-      type: "positional",
-      description: "filter by type",
-      required: false,
-    },
-  },
-  async run() {
-    const actions = await discoverActions();
-
-    const content: string[] = [];
-    content.push("");
-
-    content.push(header("ACTIONS"));
-    content.push("");
-
-    const rows = actions.map((a) => ({
-      name: a.name,
-      description:
-        `${a.inputType} → ${a.outputType}`.padEnd(20) + a.description,
-    }));
-
-    content.push(...table(rows));
-    content.push("");
-
-    content.push(separator());
-    content.push("");
-    content.push(
-      `  ${actions.length} actions · run ${c.cyan("varg run <action> --info")} for details`,
-    );
-    content.push("");
-
-    console.log(box("varg", content));
-  },
-});

package/cli/commands/run.ts

@@ -1,237 +0,0 @@
-/**
- * varg run command
- * execute actions by scanning filesystem
- */
-
-import { existsSync } from "node:fs";
-import { defineCommand } from "citty";
-import { resolve } from "../discover";
-import type { Meta } from "../types";
-import { box, c, runningBox } from "../ui";
-
-interface RunOptions {
-  [key: string]: string | boolean | undefined;
-  info?: boolean;
-  schema?: boolean;
-  json?: boolean;
-  quiet?: boolean;
-}
-
-function parseArgs(args: string[]): { target: string; options: RunOptions } {
-  const options: RunOptions = {};
-  let target = "";
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (!arg) continue;
-
-    if (arg.startsWith("--")) {
-      const key = arg.slice(2);
-      if (
-        key === "info" ||
-        key === "schema" ||
-        key === "json" ||
-        key === "quiet"
-      ) {
-        options[key] = true;
-      } else {
-        const value = args[++i];
-        if (value) options[key] = value;
-      }
-    } else if (!target) {
-      target = arg;
-    } else {
-      // positional args - check if it looks like a file
-      if (existsSync(arg) || arg.startsWith("./") || arg.startsWith("/")) {
-        if (!options.image && !options.audio) {
-          options.image = arg;
-        }
-      } else if (!options.prompt && !options.text) {
-        options.prompt = arg;
-      }
-    }
-  }
-
-  return { target, options };
-}
-
-function showHelp(item: Meta) {
-  const content: string[] = [];
-  content.push("");
-  content.push(`  ${item.description}`);
-  content.push("");
-  content.push(c.bold(c.dim("  USAGE")));
-  content.push("");
-
-  const required = item.schema.input.required;
-  const reqArgs = required.map((r) => `--${r} <${r}>`).join(" ");
-  content.push(`    varg run ${item.name} ${reqArgs} [options]`);
-
-  content.push("");
-  content.push(c.bold(c.dim("  OPTIONS")));
-  content.push("");
-
-  for (const [key, prop] of Object.entries(item.schema.input.properties)) {
-    const req = item.schema.input.required.includes(key);
-    const reqTag = req ? c.yellow(" (required)") : "";
-    const defaultVal =
-      prop.default !== undefined ? c.dim(` default: ${prop.default}`) : "";
-    const enumVals = prop.enum ? c.dim(` [${prop.enum.join(", ")}]`) : "";
-
-    content.push(
-      `    --${key.padEnd(12)}${prop.description}${reqTag}${defaultVal}${enumVals}`,
-    );
-  }
-
-  content.push("");
-  content.push(`    --json          output result as json`);
-  content.push(`    --quiet         minimal output`);
-  content.push(`    --info          show this help`);
-  content.push("");
-
-  console.log(box(`action: ${item.name}`, content));
-}
-
-function showSchema(item: Meta) {
-  const schema = {
-    name: item.name,
-    type: item.type,
-    description: item.description,
-    input: item.schema.input,
-    output: item.schema.output,
-  };
-
-  console.log(JSON.stringify(schema, null, 2));
-}
-
-export const runCmd = defineCommand({
-  meta: {
-    name: "run",
-    description: "run a model or action",
-  },
-  args: {
-    target: {
-      type: "positional",
-      description: "action to run",
-      required: false,
-    },
-    info: {
-      type: "boolean",
-      description: "show action info",
-    },
-    schema: {
-      type: "boolean",
-      description: "show action schema as json",
-    },
-    json: {
-      type: "boolean",
-      description: "output result as json",
-    },
-    quiet: {
-      type: "boolean",
-      description: "minimal output",
-    },
-  },
-  async run({ rawArgs }) {
-    // use rawArgs for dynamic action options
-    const { target, options } = parseArgs(rawArgs);
-
-    if (!target) {
-      console.error(`${c.red("error:")} target required`);
-      console.log(`\nusage: ${c.cyan("varg run <action> [options]")}`);
-      console.log(`\nrun ${c.cyan("varg list")} to see available actions`);
-      process.exit(1);
-    }
-
-    const item = await resolve(target);
-
-    if (!item) {
-      console.error(`${c.red("error:")} '${target}' not found`);
-      console.log(`\nrun ${c.cyan("varg list")} to see available actions`);
-      process.exit(1);
-    }
-
-    if (options.info) {
-      showHelp(item);
-      return;
-    }
-
-    if (options.schema) {
-      showSchema(item);
-      return;
-    }
-
-    // validate required args
-    for (const req of item.schema.input.required) {
-      if (!options[req]) {
-        console.error(`${c.red("error:")} --${req} is required`);
-        console.log(`\nrun ${c.cyan(`varg run ${target} --info`)} for usage`);
-        process.exit(1);
-      }
-    }
-
-    // build params for display
-    const params: Record<string, string> = {};
-    for (const key of Object.keys(item.schema.input.properties)) {
-      if (options[key] && typeof options[key] === "string") {
-        params[key] = options[key] as string;
-      }
-    }
-
-    if (!options.quiet && !options.json) {
-      console.log(runningBox(target, params, "running"));
-    }
-
-    const startTime = Date.now();
-
-    try {
-      const result = await item.run(options);
-      const elapsed = Date.now() - startTime;
-
-      if (options.json) {
-        console.log(JSON.stringify({ success: true, result, time: elapsed }));
-      } else if (options.quiet) {
-        console.log(JSON.stringify(result));
-      } else {
-        // extract url from result if present
-        const resultObj = result as Record<string, unknown> | null;
-        const url =
-          resultObj?.imageUrl || resultObj?.videoUrl || resultObj?.url || null;
-
-        console.log("\x1b[2J\x1b[H");
-        console.log(
-          runningBox(target, params, "done", {
-            output: url ? "saved" : "done",
-            time: elapsed,
-          }),
-        );
-
-        // print url outside box so it's clickable
-        if (url) {
-          console.log(`\n  ${c.cyan("url")}  ${url}\n`);
-        }
-      }
-    } catch (err) {
-      const elapsed = Date.now() - startTime;
-      const errorMsg = err instanceof Error ? err.message : String(err);
-
-      if (options.json) {
-        console.log(
-          JSON.stringify({ success: false, error: errorMsg, time: elapsed }),
-        );
-      } else if (options.quiet) {
-        console.error(errorMsg);
-      } else {
-        console.log("\x1b[2J\x1b[H");
-        console.log(
-          runningBox(target, params, "error", {
-            error: errorMsg,
-            time: elapsed,
-          }),
-        );
-      }
-
-      process.exit(1);
-    }
-  },
-});