@vargai/sdk 0.1.1

package/action/transcribe/index.ts

@@ -0,0 +1,210 @@
+#!/usr/bin/env bun
+
+/**
+ * audio transcription service
+ * supports groq whisper, fireworks api, and future providers
+ */
+
+import { writeFileSync } from "node:fs";
+import { toFile } from "groq-sdk/uploads";
+import type { ActionMeta } from "../../cli/types";
+import {
+  convertFireworksToSRT,
+  transcribeWithFireworks as fireworksTranscribe,
+} from "../../lib/fireworks";
+import { GROQ_MODELS, transcribeAudio as groqTranscribe } from "../../lib/groq";
+
+export const meta: ActionMeta = {
+  name: "transcribe",
+  type: "action",
+  description: "speech to text transcription",
+  inputType: "audio",
+  outputType: "text",
+  schema: {
+    input: {
+      type: "object",
+      required: ["audio"],
+      properties: {
+        audio: {
+          type: "string",
+          format: "file-path",
+          description: "audio/video file to transcribe",
+        },
+        provider: {
+          type: "string",
+          enum: ["groq", "fireworks"],
+          default: "groq",
+          description: "transcription provider",
+        },
+        output: {
+          type: "string",
+          format: "file-path",
+          description: "output file path",
+        },
+      },
+    },
+    output: { type: "string", description: "transcribed text" },
+  },
+  async run(options) {
+    const { audio, provider, output } = options as {
+      audio: string;
+      provider?: "groq" | "fireworks";
+      output?: string;
+    };
+    return transcribe({ audioUrl: audio, provider, outputPath: output });
+  },
+};
+
+// types
+export interface TranscribeOptions {
+  audioUrl: string; // url or local file path
+  provider?: "groq" | "fireworks";
+  model?: string;
+  language?: string;
+  outputFormat?: "text" | "srt";
+  outputPath?: string;
+}
+
+export interface TranscribeResult {
+  success: boolean;
+  text?: string;
+  srt?: string;
+  error?: string;
+}
+
+// groq transcription
+async function transcribeWithGroq(
+  audioUrl: string,
+  options: {
+    model?: string;
+    language?: string;
+    outputFormat?: "text" | "srt";
+  },
+): Promise<TranscribeResult> {
+  try {
+    console.log("[transcribe] using groq whisper...");
+
+    // load audio file (local or remote)
+    let audioBuffer: ArrayBuffer;
+    let fileName = "audio.mp3";
+
+    if (audioUrl.startsWith("http://") || audioUrl.startsWith("https://")) {
+      // fetch remote file
+      const audioResponse = await fetch(audioUrl);
+      audioBuffer = await audioResponse.arrayBuffer();
+    } else {
+      // read local file with bun
+      const file = Bun.file(audioUrl);
+      audioBuffer = await file.arrayBuffer();
+      fileName = audioUrl.split("/").pop() || "audio.mp3";
+    }
+
+    const audioFile = await toFile(audioBuffer, fileName);
+
+    // transcribe with groq
+    const text = await groqTranscribe({
+      file: audioFile,
+      model: options.model || GROQ_MODELS.WHISPER_LARGE,
+      language: options.language,
+    });
+
+    console.log("[transcribe] groq transcription complete");
+
+    if (options.outputFormat === "srt") {
+      // groq returns plain text, so we need to convert to srt
+      // for now just return text with warning
+      console.warn(
+        "[transcribe] groq returns plain text, use fireworks for srt format",
+      );
+      return { success: true, text, srt: text };
+    }
+
+    return { success: true, text };
+  } catch (error) {
+    console.error("[transcribe] groq error:", error);
+    return {
+      success: false,
+      error:
+        error instanceof Error ? error.message : "groq transcription failed",
+    };
+  }
+}
+
+// fireworks transcription (with srt support)
+async function transcribeWithFireworks(
+  audioUrl: string,
+): Promise<TranscribeResult> {
+  try {
+    console.log("[transcribe] using fireworks api...");
+
+    const data = await fireworksTranscribe({
+      audioPath: audioUrl,
+    });
+
+    const srtText = convertFireworksToSRT(data.words || []);
+    console.log("[transcribe] fireworks transcription complete");
+
+    return { success: true, srt: srtText, text: data.text };
+  } catch (error) {
+    console.error("[transcribe] fireworks error:", error);
+    return {
+      success: false,
+      error:
+        error instanceof Error
+          ? error.message
+          : "fireworks transcription failed",
+    };
+  }
+}
+
+// main transcription function
+export async function transcribe(
+  options: TranscribeOptions,
+): Promise<TranscribeResult> {
+  const {
+    audioUrl,
+    provider = "groq",
+    model,
+    language,
+    outputFormat = "text",
+    outputPath,
+  } = options;
+
+  if (!audioUrl) {
+    throw new Error("audioUrl is required");
+  }
+
+  console.log(`[transcribe] transcribing ${audioUrl} with ${provider}...`);
+
+  let result: TranscribeResult;
+
+  // choose provider
+  if (provider === "groq") {
+    result = await transcribeWithGroq(audioUrl, {
+      model,
+      language,
+      outputFormat,
+    });
+  } else if (provider === "fireworks") {
+    result = await transcribeWithFireworks(audioUrl);
+  } else {
+    throw new Error(`unknown provider: ${provider}`);
+  }
+
+  // save to file if requested
+  if (result.success && outputPath) {
+    const content = outputFormat === "srt" ? result.srt : result.text;
+    if (content) {
+      writeFileSync(outputPath, content);
+      console.log(`[transcribe] saved to ${outputPath}`);
+    }
+  }
+
+  return result;
+}
+
+// cli
+if (import.meta.main) {
+  const { runCli } = await import("../../cli/runner");
+  runCli(meta);
+}

package/action/video/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: video-generation
+description: generate videos from images or text prompts using fal.ai. use when user wants to animate images, create videos from text, or needs ai video generation with 5-10 second clips.
+allowed-tools: Read, Bash
+---
+
+# video generation
+
+generate ai videos from images or text using fal.ai with automatic s3 upload support.
+
+## capabilities
+
+- **image-to-video**: animate static images with motion prompts
+- **text-to-video**: generate videos directly from text descriptions
+- supports 5 or 10 second duration
+- automatic s3 upload
+
+## usage
+
+### generate from image
+```bash
+bun run service/video.ts from_image <prompt> <imageUrl> [duration] [upload]
+```
+
+**parameters:**
+- `prompt` (required): motion description (e.g., "camera pan left")
+- `imageUrl` (required): url of the source image
+- `duration` (optional): 5 or 10 seconds (default: 5)
+- `upload` (optional): "true" to upload to s3
+
+**example:**
+```bash
+bun run service/video.ts from_image "person talking naturally" https://example.com/headshot.jpg 5 true
+```
+
+### generate from text
+```bash
+bun run service/video.ts from_text <prompt> [duration] [upload]
+```
+
+**parameters:**
+- `prompt` (required): video scene description
+- `duration` (optional): 5 or 10 seconds (default: 5)
+- `upload` (optional): "true" to upload to s3
+
+**example:**
+```bash
+bun run service/video.ts from_text "waves crashing on beach at sunset" 10 true
+```
+
+## as library
+
+```typescript
+import { generateVideoFromImage, generateVideoFromText } from "./service/video"
+
+// animate an image
+const videoResult = await generateVideoFromImage(
+  "camera zoom in slowly",
+  "https://example.com/portrait.jpg",
+  { duration: 5, upload: true }
+)
+console.log(videoResult.videoUrl)
+console.log(videoResult.uploaded) // s3 url if upload=true
+
+// generate from text
+const textVideo = await generateVideoFromText(
+  "forest path with sunlight filtering through trees",
+  { duration: 10, upload: true }
+)
+```
+
+## output
+
+returns `VideoGenerationResult`:
+```typescript
+{
+  videoUrl: string,      // direct video url
+  duration?: number,     // actual video duration
+  uploaded?: string      // s3 url if upload requested
+}
+```
+
+## when to use
+
+use this skill when:
+- animating character headshots or portraits
+- creating motion from static images
+- generating video clips from text descriptions
+- preparing videos for lipsync or editing pipeline
+- need short form video content (5-10s)
+
+## tips
+
+**for character animation:**
+- use subtle prompts like "person talking naturally" or "slight head movement"
+- keep duration at 5 seconds for character shots
+- combine with lipsync for talking videos
+
+**for scene generation:**
+- be descriptive about camera movement and scene dynamics
+- 10 seconds works better for landscape/scene videos
+
+## environment variables
+
+required:
+- `FAL_API_KEY` - for fal video generation
+
+optional (for s3 upload):
+- `CLOUDFLARE_R2_API_URL`
+- `CLOUDFLARE_ACCESS_KEY_ID`
+- `CLOUDFLARE_ACCESS_SECRET`
+- `CLOUDFLARE_R2_BUCKET`
+
+## generation time
+
+expect 2-3 minutes per video clip

package/action/video/index.ts

@@ -0,0 +1,125 @@
+#!/usr/bin/env bun
+/**
+ * video generation service combining fal and higgsfield
+ * usage: bun run service/video.ts <command> <args>
+ */
+
+import type { ActionMeta } from "../../cli/types";
+import { imageToVideo, textToVideo } from "../../lib/fal";
+import { uploadFromUrl } from "../../utilities/s3";
+
+export const meta: ActionMeta = {
+  name: "video",
+  type: "action",
+  description: "generate video from text or image",
+  inputType: "text/image",
+  outputType: "video",
+  schema: {
+    input: {
+      type: "object",
+      required: ["prompt"],
+      properties: {
+        prompt: { type: "string", description: "what to generate" },
+        image: {
+          type: "string",
+          format: "file-path",
+          description: "input image (enables image-to-video)",
+        },
+        duration: {
+          type: "integer",
+          enum: [5, 10],
+          default: 5,
+          description: "video duration in seconds",
+        },
+      },
+    },
+    output: { type: "string", format: "file-path", description: "video path" },
+  },
+  async run(options) {
+    const { prompt, image, duration } = options as {
+      prompt: string;
+      image?: string;
+      duration?: 5 | 10;
+    };
+    if (image) {
+      return generateVideoFromImage(prompt, image, { duration });
+    }
+    return generateVideoFromText(prompt, { duration });
+  },
+};
+
+export interface VideoGenerationResult {
+  videoUrl: string;
+  duration?: number;
+  uploaded?: string;
+}
+
+export async function generateVideoFromImage(
+  prompt: string,
+  imageUrl: string,
+  options: { duration?: 5 | 10; upload?: boolean } = {},
+): Promise<VideoGenerationResult> {
+  console.log("[service/video] generating video from image");
+
+  const result = await imageToVideo({
+    prompt,
+    imageUrl,
+    duration: options.duration,
+  });
+
+  const videoUrl = result.data?.video?.url;
+  if (!videoUrl) {
+    throw new Error("no video url in result");
+  }
+
+  let uploaded: string | undefined;
+  if (options.upload) {
+    const timestamp = Date.now();
+    const objectKey = `videos/generated/${timestamp}.mp4`;
+    uploaded = await uploadFromUrl(videoUrl, objectKey);
+    console.log(`[service/video] uploaded to ${uploaded}`);
+  }
+
+  return {
+    videoUrl,
+    duration: result.data?.duration,
+    uploaded,
+  };
+}
+
+export async function generateVideoFromText(
+  prompt: string,
+  options: { duration?: 5 | 10; upload?: boolean } = {},
+): Promise<VideoGenerationResult> {
+  console.log("[service/video] generating video from text");
+
+  const result = await textToVideo({
+    prompt,
+    duration: options.duration,
+  });
+
+  const videoUrl = result.data?.video?.url;
+  if (!videoUrl) {
+    throw new Error("no video url in result");
+  }
+
+  let uploaded: string | undefined;
+  if (options.upload) {
+    const timestamp = Date.now();
+    const objectKey = `videos/generated/${timestamp}.mp4`;
+    uploaded = await uploadFromUrl(videoUrl, objectKey);
+    console.log(`[service/video] uploaded to ${uploaded}`);
+  }
+
+  return {
+    videoUrl,
+    duration: result.data?.duration,
+    uploaded,
+  };
+}
+
+// cli
+if (import.meta.main) {
+  const { runCli } = await import("../../cli/runner");
+  runCli(meta);
+}

package/action/voice/SKILL.md

@@ -0,0 +1,125 @@
+---
+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

@@ -0,0 +1,136 @@
+#!/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);
+}