varg.ai-sdk 0.1.0

package/TEST_RESULTS.md

@@ -0,0 +1,122 @@
+# test results
+
+## ✅ both fal approaches working
+
+### approach 1: lib/ai-sdk/fal.ts (vercel ai sdk)
+
+```bash
+$ bun run lib/ai-sdk/fal.ts generate_image "futuristic spaceship" "fal-ai/flux/dev" "16:9"
+
+[ai-sdk/fal] generating image with fal-ai/flux/dev
+[ai-sdk/fal] prompt: futuristic spaceship interior
+[ai-sdk/fal] aspect ratio: 16:9
+[ai-sdk/fal] completed!
+
+image saved to: /tmp/fal-ai-sdk-1763772836608.png
+
+metadata:
+{
+  "images": [
+    {
+      "width": 1024,
+      "height": 576,
+      "contentType": "image/jpeg",
+      "nsfw": false
+    }
+  ]
+}
+```
+
+✅ benefits:
+- clean typed api
+- auto image save + open
+- aspect ratio support
+- consistent with other ai-sdk providers
+
+### approach 2: lib/fal.ts (fal client direct)
+
+```bash
+$ bun run lib/fal.ts generate_image "ancient temple ruins"
+
+[fal] generating image with fal-ai/flux-pro/v1.1
+[fal] prompt: ancient temple ruins at sunset
+[fal] processing...
+[fal] completed!
+
+{
+  "data": {
+    "images": [
+      {
+        "url": "https://v3b.fal.media/files/b/koala/L5LYGCHZ4aZ_CKZsmPbUe.jpg",
+        "width": 1024,
+        "height": 768,
+        "content_type": "image/jpeg"
+      }
+    ],
+    "seed": 2946158106
+  }
+}
+```
+
+✅ benefits:
+- full api access
+- queue updates
+- video support
+- custom parameters
+
+## cli tests ✅
+
+all help menus working:
+
+```bash
+bun run lib/ai-sdk/fal.ts                    # ✓
+bun run lib/fal.ts                            # ✓
+bun run lib/higgsfield.ts                     # ✓
+bun run service/image.ts                      # ✓
+bun run service/video.ts                      # ✓
+bun run utilities/s3.ts                       # ✓
+```
+
+## library imports ✅
+
+```typescript
+import { generateImage } from "./index"
+import * as aiSdkFal from "./index"
+
+// both approaches available
+```
+
+## actual generation tests ✅
+
+successfully generated and opened:
+- cyberpunk city (16:9, ai-sdk)
+- spaceship interior (16:9, ai-sdk)
+- temple ruins (4:3, fal client)
+- aurora borealis (4:3, fal client)
+
+all images ~15-20 seconds generation time
+
+## what works
+
+1. **dual fal implementations** - ai-sdk for simplicity, client for power ✓
+2. **all cli scripts executable** with proper help menus ✓
+3. **library imports functional** ✓
+4. **actual image generation working** ✓
+5. **automatic image opening** (ai-sdk version) ✓
+6. **queue progress updates** (fal client) ✓
+
+## file structure
+
+```
+lib/
+├── ai-sdk/
+│   └── fal.ts          # vercel ai sdk approach
+├── fal.ts              # fal client approach
+└── higgsfield.ts       # soul character generation
+```
+
+## recommendations
+
+- **use lib/ai-sdk/fal.ts** for standard image generation
+- **use lib/fal.ts** for video or advanced features
+- **use service/**.ts for high-level operations with s3 upload

package/action/captions/SKILL.md

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

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