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

package/action/captions/SKILL.md

@@ -1,170 +0,0 @@
----
-name: video-captions
-description: add auto-generated or custom subtitles to videos using groq/fireworks transcription and ffmpeg overlay. use when adding captions, subtitles, or text overlays to videos for accessibility or social media.
-allowed-tools: Read, Bash
----
-
-# video captions
-
-automatically generate and overlay subtitles on videos with customizable styling.
-
-## features
-
-- **auto-generation**: transcribe video audio using groq or fireworks
-- **custom srt support**: use existing subtitle files
-- **styling**: customize font, size, colors, position
-- **word-level timing**: fireworks provides precise word timestamps
-- **instant overlay**: ffmpeg-based subtitle rendering
-
-## usage
-
-### auto-generate captions
-```bash
-bun run service/captions.ts <videoPath> [outputPath] [options]
-```
-
-**basic example:**
-```bash
-bun run service/captions.ts media/video.mp4
-# outputs: media/video-captioned.mp4
-```
-
-**with options:**
-```bash
-bun run service/captions.ts media/video.mp4 output.mp4 --provider fireworks --font Arial --size 28
-```
-
-### use existing srt file
-```bash
-bun run service/captions.ts media/video.mp4 output.mp4 --srt media/video.srt
-```
-
-## options
-
-- `--srt <path>` - use existing srt file instead of auto-generating
-- `--provider <name>` - groq or fireworks (default: fireworks)
-- `--font <name>` - font name (default: Arial)
-- `--size <number>` - font size (default: 24)
-- `--color <hex>` - primary color in ASS format (default: &HFFFFFF white)
-- `--outline <hex>` - outline color in ASS format (default: &H000000 black)
-
-## as library
-
-```typescript
-import { addCaptions } from "./service/captions"
-
-const result = await addCaptions({
-  videoPath: "media/video.mp4",
-  output: "captioned.mp4",
-  provider: "fireworks", // or "groq"
-  style: {
-    fontName: "Helvetica",
-    fontSize: 28,
-    primaryColor: "&HFFFFFF",
-    outlineColor: "&H000000",
-    bold: true,
-    alignment: 2, // bottom center
-    marginV: 20
-  }
-})
-```
-
-## providers
-
-### fireworks (recommended)
-- **word-level timestamps** for precise timing
-- generates `.srt` format with detailed timing
-- better for social media content
-- slightly slower transcription
-
-### groq
-- **ultra-fast** transcription
-- plain text output (converted to srt)
-- sentence-level timing
-- great for quick previews
-
-## styling options
-
-```typescript
-interface SubtitleStyle {
-  fontName?: string      // default: Arial
-  fontSize?: number      // default: 24
-  primaryColor?: string  // default: &HFFFFFF (white)
-  outlineColor?: string  // default: &H000000 (black)
-  bold?: boolean         // default: true
-  alignment?: number     // 1-9, default: 2 (bottom center)
-  marginV?: number       // vertical margin, default: 20
-}
-```
-
-**alignment values:**
-```
-1 = bottom left    2 = bottom center    3 = bottom right
-4 = middle left    5 = middle center    6 = middle right
-7 = top left       8 = top center       9 = top right
-```
-
-## when to use
-
-use this skill when:
-- preparing videos for social media (tiktok, instagram, youtube)
-- adding accessibility features
-- creating educational or tutorial content
-- need word-level caption timing
-- translating videos with custom srt files
-
-## typical workflow
-
-1. create or edit video
-2. add captions with auto-transcription (this service)
-3. customize style for platform
-4. prepare for social media (edit service)
-
-## examples
-
-**tiktok/instagram style captions:**
-```bash
-bun run service/captions.ts video.mp4 captioned.mp4 \
-  --provider fireworks \
-  --font "Arial Black" \
-  --size 32 \
-  --color "&H00FFFF"
-```
-
-**professional style:**
-```bash
-bun run service/captions.ts video.mp4 output.mp4 \
-  --provider fireworks \
-  --font "Helvetica" \
-  --size 24
-```
-
-**with existing subtitles:**
-```bash
-bun run service/captions.ts video.mp4 final.mp4 \
-  --srt custom-subtitles.srt \
-  --font "Arial" \
-  --size 26
-```
-
-## output
-
-- generates `.srt` file if auto-transcribing
-- creates new video file with burned-in subtitles
-- preserves original video quality
-- audio is copied without re-encoding
-
-## environment variables
-
-required (for auto-transcription):
-- `GROQ_API_KEY` - for groq provider
-- `FIREWORKS_API_KEY` - for fireworks provider
-
-**system requirements:**
-- ffmpeg must be installed
-
-## processing time
-
-- transcription: 5-30 seconds (depending on video length)
-- overlay: 5-15 seconds (depending on video length)
-- total: typically under 1 minute

package/action/captions/index.ts

@@ -1,227 +0,0 @@
-#!/usr/bin/env bun
-
-/**
- * video captioning service
- * generates and overlays subtitles on videos using ffmpeg
- * supports auto-generation via groq/fireworks or custom srt files
- */
-
-import { existsSync } from "node:fs";
-import ffmpeg from "fluent-ffmpeg";
-import { transcribe } from "../transcribe";
-
-// types
-export interface AddCaptionsOptions {
-  videoPath: string;
-  srtPath?: string; // optional existing srt file
-  output: string;
-  provider?: "groq" | "fireworks"; // only used if srtPath not provided
-  style?: SubtitleStyle;
-}
-
-export interface SubtitleStyle {
-  fontName?: string; // default: Arial
-  fontSize?: number; // default: 24
-  primaryColor?: string; // default: &HFFFFFF (white)
-  outlineColor?: string; // default: &H000000 (black)
-  bold?: boolean; // default: true
-  alignment?: number; // 1-9, default: 2 (bottom center)
-  marginV?: number; // vertical margin, default: 20
-}
-
-// default subtitle style
-const DEFAULT_STYLE: Required<SubtitleStyle> = {
-  fontName: "Arial",
-  fontSize: 24,
-  primaryColor: "&HFFFFFF", // white
-  outlineColor: "&H000000", // black
-  bold: true,
-  alignment: 2, // bottom center
-  marginV: 20,
-};
-
-// main function to add captions to video
-export async function addCaptions(
-  options: AddCaptionsOptions,
-): Promise<string> {
-  const { videoPath, srtPath, output, provider = "fireworks", style } = options;
-
-  if (!videoPath) {
-    throw new Error("videoPath is required");
-  }
-  if (!output) {
-    throw new Error("output is required");
-  }
-  if (!existsSync(videoPath)) {
-    throw new Error(`video file not found: ${videoPath}`);
-  }
-
-  console.log("[captions] adding captions to video...");
-
-  // determine srt file path
-  let finalSrtPath = srtPath;
-
-  // if no srt file provided, auto-generate it
-  if (!finalSrtPath) {
-    console.log(
-      `[captions] no srt file provided, auto-generating with ${provider}...`,
-    );
-
-    // generate srt file from video audio
-    const tempSrtPath = videoPath.replace(/\.[^.]+$/, ".srt");
-
-    const result = await transcribe({
-      audioUrl: videoPath,
-      provider,
-      outputFormat: "srt",
-      outputPath: tempSrtPath,
-    });
-
-    if (!result.success) {
-      throw new Error(`failed to generate subtitles: ${result.error}`);
-    }
-
-    finalSrtPath = tempSrtPath;
-    console.log(`[captions] generated subtitles at ${finalSrtPath}`);
-  }
-
-  if (!existsSync(finalSrtPath)) {
-    throw new Error(`srt file not found: ${finalSrtPath}`);
-  }
-
-  // merge style with defaults
-  const finalStyle = { ...DEFAULT_STYLE, ...style };
-
-  // build subtitle filter with style
-  const subtitlesFilter = `subtitles=${finalSrtPath}:force_style='FontName=${finalStyle.fontName},FontSize=${finalStyle.fontSize},PrimaryColour=${finalStyle.primaryColor},OutlineColour=${finalStyle.outlineColor},Bold=${finalStyle.bold ? -1 : 0},Alignment=${finalStyle.alignment},MarginV=${finalStyle.marginV}'`;
-
-  console.log("[captions] overlaying subtitles on video...");
-
-  return new Promise((resolve, reject) => {
-    ffmpeg(videoPath)
-      .videoFilters(subtitlesFilter)
-      .outputOptions(["-c:a", "copy"]) // copy audio without re-encoding
-      .output(output)
-      .on("end", () => {
-        console.log(`[captions] saved to ${output}`);
-        resolve(output);
-      })
-      .on("error", (err) => {
-        console.error("[captions] error:", err);
-        reject(err);
-      })
-      .run();
-  });
-}
-
-// cli
-async function cli() {
-  const args = process.argv.slice(2);
-  const command = args[0];
-
-  if (!command || command === "help") {
-    console.log(`
-usage:
-  bun run service/captions.ts <videoPath> [outputPath] [options]
-
-arguments:
-  videoPath      - path to input video file
-  outputPath     - path to output video (default: video-captioned.mp4)
-
-options:
-  --srt <path>       - use existing srt file instead of auto-generating
-  --provider <name>  - groq | fireworks (default: fireworks)
-  --font <name>      - font name (default: Arial)
-  --size <number>    - font size (default: 24)
-  --color <hex>      - primary color in ASS format (default: &HFFFFFF)
-  --outline <hex>    - outline color in ASS format (default: &H000000)
-
-examples:
-  # auto-generate captions with fireworks
-  bun run service/captions.ts media/fitness-demo.mp4
-
-  # auto-generate with groq (faster, plain text)
-  bun run service/captions.ts media/fitness-demo.mp4 output.mp4 --provider groq
-
-  # use existing srt file
-  bun run service/captions.ts media/fitness-demo.mp4 output.mp4 --srt media/fitness-demo.srt
-
-  # customize style
-  bun run service/captions.ts media/video.mp4 output.mp4 --font "Helvetica" --size 28
-
-requirements:
-  ffmpeg must be installed on your system
-  brew install ffmpeg (macos)
-  apt-get install ffmpeg (linux)
-    `);
-    process.exit(0);
-  }
-
-  try {
-    const videoPath = args[0];
-    let outputPath = args[1];
-
-    if (!videoPath) {
-      throw new Error("videoPath is required");
-    }
-
-    // parse options
-    let srtPath: string | undefined;
-    let provider: "groq" | "fireworks" = "fireworks";
-    const style: SubtitleStyle = {};
-
-    for (let i = 1; i < args.length; i++) {
-      const arg = args[i];
-
-      if (arg === "--srt") {
-        srtPath = args[++i];
-      } else if (arg === "--provider") {
-        provider = args[++i] as "groq" | "fireworks";
-      } else if (arg === "--font") {
-        style.fontName = args[++i];
-      } else if (arg === "--size") {
-        const size = args[++i];
-        if (!size) {
-          throw new Error("--size requires a number");
-        }
-        style.fontSize = Number.parseInt(size, 10);
-      } else if (arg === "--color") {
-        const color = args[++i];
-        if (!color) {
-          throw new Error("--color requires a hex color");
-        }
-        style.primaryColor = color;
-      } else if (arg === "--outline") {
-        const outline = args[++i];
-        if (!outline) {
-          throw new Error("--outline requires a hex color");
-        }
-        style.outlineColor = outline;
-      } else if (!arg?.startsWith("--") && !outputPath) {
-        outputPath = arg;
-      }
-    }
-
-    // default output path
-    if (!outputPath) {
-      outputPath = videoPath.replace(/\.[^.]+$/, "-captioned.mp4");
-    }
-
-    await addCaptions({
-      videoPath,
-      srtPath,
-      output: outputPath,
-      provider,
-      style,
-    });
-
-    console.log("\ndone! video with captions saved to:", outputPath);
-  } catch (error) {
-    console.error("[captions] error:", error);
-    process.exit(1);
-  }
-}
-
-if (import.meta.main) {
-  cli();
-}

package/action/edit/SKILL.md

@@ -1,235 +0,0 @@
----
-name: video-editing
-description: edit videos with ffmpeg operations including resize, trim, concat, social media optimization, and montage creation. use for video editing, format conversion, social media prep, merging clips, or batch video operations.
-allowed-tools: Read, Bash
----
-
-# video editing
-
-comprehensive video editing service combining ffmpeg operations into common workflows.
-
-## commands
-
-### prepare for social media
-```bash
-bun run service/edit.ts social <input> <output> <platform> [audioPath]
-```
-
-automatically resize and optimize for platform specs:
-- **tiktok**: 1080x1920 (9:16)
-- **instagram**: 1080x1920 (9:16)
-- **youtube-shorts**: 1080x1920 (9:16)
-- **youtube**: 1920x1080 (16:9)
-- **twitter**: 1280x720 (16:9)
-
-**example:**
-```bash
-bun run service/edit.ts social raw.mp4 tiktok.mp4 tiktok
-bun run service/edit.ts social raw.mp4 ig.mp4 instagram audio.mp3
-```
-
-### create montage
-```bash
-bun run service/edit.ts montage <output> <clip1> <clip2> [clip3...]
-```
-
-combine multiple video clips into one:
-
-**example:**
-```bash
-bun run service/edit.ts montage final.mp4 intro.mp4 main.mp4 outro.mp4
-```
-
-### quick trim
-```bash
-bun run service/edit.ts trim <input> <output> <start> [end]
-```
-
-extract a segment from video:
-
-**example:**
-```bash
-bun run service/edit.ts trim long.mp4 short.mp4 10 30
-# extracts seconds 10-30
-```
-
-### quick resize
-```bash
-bun run service/edit.ts resize <input> <output> <preset>
-```
-
-resize to common aspect ratios:
-- **vertical**: 9:16 (1080x1920)
-- **square**: 1:1 (1080x1080)
-- **landscape**: 16:9 (1920x1080)
-- **4k**: 3840x2160
-
-**example:**
-```bash
-bun run service/edit.ts resize raw.mp4 vertical.mp4 vertical
-```
-
-### merge with audio
-```bash
-bun run service/edit.ts merge_audio <audio> <output> <video1> [video2...]
-```
-
-concatenate videos and add audio overlay:
-
-**example:**
-```bash
-bun run service/edit.ts merge_audio song.mp3 final.mp4 clip1.mp4 clip2.mp4
-```
-
-## as library
-
-```typescript
-import { 
-  prepareForSocial,
-  createMontage,
-  quickTrim,
-  quickResize,
-  mergeWithAudio,
-  editPipeline
-} from "./service/edit"
-
-// social media optimization
-await prepareForSocial({
-  input: "raw.mp4",
-  output: "tiktok.mp4",
-  platform: "tiktok",
-  withAudio: "audio.mp3"
-})
-
-// create montage
-await createMontage({
-  clips: ["clip1.mp4", "clip2.mp4"],
-  output: "montage.mp4",
-  maxClipDuration: 5,
-  targetResolution: { width: 1920, height: 1080 }
-})
-
-// trim video
-await quickTrim("video.mp4", "trimmed.mp4", 10, 30)
-
-// resize video
-await quickResize("video.mp4", "resized.mp4", "vertical")
-
-// merge videos with audio
-await mergeWithAudio(
-  ["clip1.mp4", "clip2.mp4"],
-  "audio.mp3",
-  "final.mp4"
-)
-```
-
-## advanced: edit pipeline
-
-chain multiple operations:
-
-```typescript
-import { editPipeline } from "./service/edit"
-
-await editPipeline({
-  steps: [
-    {
-      operation: "resize",
-      options: {
-        input: "raw.mp4",
-        width: 1080,
-        height: 1920
-      }
-    },
-    {
-      operation: "add_audio",
-      options: {
-        videoPath: "temp.mp4",
-        audioPath: "music.mp3"
-      }
-    },
-    {
-      operation: "trim",
-      options: {
-        input: "temp2.mp4",
-        start: 0,
-        duration: 30
-      }
-    }
-  ],
-  finalOutput: "final.mp4"
-})
-```
-
-**available operations:**
-- `concat` - concatenate videos
-- `add_audio` - overlay audio
-- `resize` - change dimensions
-- `trim` - extract segment
-- `convert` - change format
-- `extract_audio` - extract audio track
-
-## when to use
-
-use this skill when:
-- preparing videos for social media platforms
-- combining multiple video clips
-- extracting segments from longer videos
-- resizing to specific aspect ratios
-- adding background music to video montages
-- batch processing video files
-- optimizing videos for specific platforms
-
-## typical workflows
-
-### social media content
-1. create or edit raw video
-2. add captions (captions service)
-3. prepare for platform (this service)
-4. upload
-
-### video montage
-1. collect multiple clips
-2. create montage (this service)
-3. add audio overlay (this service)
-4. add captions if needed (captions service)
-
-### talking character for social
-1. generate character (image service)
-2. animate (video service)
-3. sync with voice (sync service)
-4. add captions (captions service)
-5. optimize for tiktok/instagram (this service)
-
-## tips
-
-**social media optimization:**
-- use platform-specific presets for correct aspect ratio
-- vertical format (9:16) works for tiktok, instagram reels, youtube shorts
-- landscape (16:9) works for youtube, twitter
-
-**montage creation:**
-- all clips should have similar resolution for best results
-- use `maxClipDuration` to keep montage paced
-- `targetResolution` ensures consistent quality
-
-**trimming:**
-- start time is in seconds
-- end time is optional (omit to trim to end of video)
-- use for extracting highlights or removing unwanted sections
-
-## environment variables
-
-no api keys required - uses ffmpeg
-
-**system requirements:**
-- ffmpeg must be installed
-- `brew install ffmpeg` (macos)
-- `apt-get install ffmpeg` (linux)
-
-## processing time
-
-depends on operation and video size:
-- trim: 5-10 seconds
-- resize: 10-30 seconds
-- concat: 10-30 seconds per clip
-- social optimization: 15-45 seconds