@vargai/sdk 0.1.1

package/service/music/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: music-generation
+description: generate full songs and instrumentals using sonauto v2 via fal.ai. create music in any style with customizable tags, lyrics, tempo, and output formats. use when user needs background music, theme songs, soundtracks, or custom audio tracks.
+allowed-tools: Read, Bash
+---
+
+# music generation
+
+generate complete songs with vocals or instrumental tracks using sonauto v2 text-to-music model.
+
+## features
+
+- **text-to-music** - describe the song you want in natural language
+- **style tags** - specify exact genres and musical styles
+- **custom lyrics** - provide lyrics or generate instrumentals
+- **tempo control** - set bpm or auto-detect from style
+- **multiple formats** - output as mp3, wav, flac, ogg, or m4a
+- **multi-song generation** - generate up to 2 variations at once
+- **reproducible** - use seed parameter to regenerate same song
+
+## usage
+
+### generate from prompt
+```bash
+bun run service/music generate <prompt> [format] [numSongs] [upload]
+```
+
+**parameters:**
+- `prompt` (required): natural language description of the song
+- `format` (optional): mp3 (default), wav, flac, ogg, m4a
+- `numSongs` (optional): 1 (default) or 2
+- `upload` (optional): "true" to upload to s3
+
+**examples:**
+```bash
+# simple generation
+bun run service/music generate "A pop song about turtles flying"
+
+# generate 2 versions as mp3
+bun run service/music generate "upbeat electronic dance music" mp3 2
+
+# generate and upload to s3
+bun run service/music generate "sad acoustic ballad" mp3 1 true
+```
+
+### generate from style tags
+```bash
+bun run service/music tags <tag1> <tag2> ... [format] [upload]
+```
+
+**examples:**
+```bash
+# rock song
+bun run service/music tags "rock" "energetic" "electric guitar"
+
+# ambient track
+bun run service/music tags "ambient" "calm" "ethereal" wav
+
+# upload to s3
+bun run service/music tags "jazz" "smooth" "piano" mp3 true
+```
+
+explore all available tags at: https://sonauto.ai/tag-explorer
+
+### generate instrumental
+```bash
+bun run service/music instrumental <tag1> <tag2> ... [format] [upload]
+```
+
+**examples:**
+```bash
+# piano instrumental
+bun run service/music instrumental "piano" "calm" "ambient"
+
+# electronic instrumental
+bun run service/music instrumental "electronic" "upbeat" "synth" wav true
+```
+
+## as library
+
+```typescript
+import { generateMusic } from "./service/music"
+
+// generate from prompt
+const result = await generateMusic({
+  prompt: "A pop song about summer",
+  format: "mp3",
+  upload: true,
+  outputPath: "media/summer-song.mp3"
+})
+
+// generate from tags with custom lyrics
+const customSong = await generateMusic({
+  tags: ["rock", "energetic", "guitar"],
+  lyrics: "Verse 1\nI'm walking down the street\nFeeling the beat\n\nChorus\nThis is my song",
+  format: "mp3",
+  bpm: 120,
+  promptStrength: 2.5,
+  outputPath: "media/custom-rock.mp3"
+})
+
+// generate instrumental
+const instrumental = await generateMusic({
+  tags: ["ambient", "calm", "piano"],
+  lyrics: "", // empty for instrumental
+  format: "wav",
+  outputPath: "media/ambient-instrumental.wav"
+})
+
+console.log(result.seed) // save seed to regenerate exact song
+console.log(result.audio[0].url)
+console.log(result.uploadUrls)
+```
+
+## output
+
+returns `MusicResult`:
+```typescript
+{
+  seed: number,              // seed used (save for reproducibility)
+  tags?: string[],           // style tags used
+  lyrics?: string,           // lyrics used (if any)
+  audio: Array<{
+    url: string,             // download url
+    fileName: string,        // original filename
+    contentType: string,     // audio/mp3, audio/wav, etc
+    fileSize: number         // size in bytes
+  }>,
+  uploadUrls?: string[]      // s3 urls if upload requested
+}
+```
+
+saves audio file(s) to `media/music-{timestamp}.{format}`
+
+## advanced options
+
+```typescript
+interface GenerateMusicOptions {
+  prompt?: string;              // text description
+  tags?: string[];              // style tags
+  lyrics?: string;              // custom lyrics (empty string = instrumental)
+  seed?: number;                // for reproducibility
+  promptStrength?: number;      // 1.4-3.1, default 2 (higher = more prompt adherence)
+  balanceStrength?: number;     // 0-1, default 0.7 (higher = more natural vocals)
+  numSongs?: 1 | 2;            // generate variations (2 costs 1.5x)
+  format?: string;              // output format
+  bitRate?: 128 | 192 | 256 | 320;  // for mp3/m4a only
+  bpm?: number | "auto";        // beats per minute
+  upload?: boolean;             // upload to s3
+  outputPath?: string;          // local save path
+}
+```
+
+## when to use
+
+use this skill when:
+- creating background music for videos
+- generating theme songs or intros
+- producing soundtracks for content
+- testing different musical styles quickly
+- need instrumental tracks for voiceovers
+- creating audio for social media content
+- prototyping music ideas
+
+## tips
+
+**for better results:**
+- be specific with style descriptions
+- combine multiple style tags for unique sounds
+- use "auto" bpm to let the model choose appropriate tempo
+- generating 2 songs gives you variations to choose from
+- save the seed if you want to recreate the exact same song
+- use instrumental mode (empty lyrics) for background music
+
+**prompt strength:**
+- `1.4-2.0` - more natural, flowing music
+- `2.0-2.5` - balanced (recommended)
+- `2.5-3.1` - strict adherence to prompt (may sound less natural)
+
+**balance strength:**
+- `0.5-0.6` - sharper instrumentals, less clear vocals
+- `0.7` - balanced (recommended)
+- `0.8-1.0` - more natural vocals
+
+**format selection:**
+- `mp3` - best for web/social media (small size, good quality)
+- `wav` - uncompressed, best for further editing
+- `flac` - lossless compression
+- `ogg` - open format, good compression
+- `m4a` - apple devices, good compression
+
+## integration with other services
+
+perfect companion for:
+- **video service** - add background music to generated videos
+- **edit service** - combine music with video content
+- **voice service** - create instrumentals for voiceovers
+- **captions service** - sync music with captioned videos
+
+## environment variables
+
+required:
+- `FAL_API_KEY` - for music generation
+
+optional (for s3 upload):
+- `CLOUDFLARE_R2_API_URL`
+- `CLOUDFLARE_ACCESS_KEY_ID`
+- `CLOUDFLARE_ACCESS_SECRET`
+- `CLOUDFLARE_R2_BUCKET`
+
+## generation time
+
+expect 30-120 seconds depending on song complexity and duration. generating 2 songs takes longer but costs only 1.5x.
+
+## cost
+
+- 1 song: 1x credit
+- 2 songs: 1.5x credit
+
+## reproducibility
+
+to regenerate the exact same song:
+1. use the same `tags` and `lyrics` (not `prompt`)
+2. use the same `seed` from the previous result
+3. keep all other parameters identical
+4. keep `numSongs` the same
+
+note: using `prompt` instead of `tags` + `lyrics` will not guarantee reproducibility even with the same seed.
+

package/service/music/index.ts

@@ -0,0 +1,296 @@
+#!/usr/bin/env bun
+
+/**
+ * music service - high-level music generation using sonauto via fal.ai
+ * supports text-to-music with customizable styles, lyrics, and parameters
+ */
+
+import { textToMusic } from "../../lib/fal";
+import { uploadFromUrl } from "../../utilities/s3";
+import { writeFile } from "node:fs/promises";
+
+// types
+export interface GenerateMusicOptions {
+  prompt?: string;
+  tags?: string[];
+  lyrics?: string;
+  seed?: number;
+  promptStrength?: number;
+  balanceStrength?: number;
+  numSongs?: 1 | 2;
+  format?: "flac" | "mp3" | "wav" | "ogg" | "m4a";
+  bitRate?: 128 | 192 | 256 | 320;
+  bpm?: number | "auto";
+  upload?: boolean;
+  outputPath?: string;
+}
+
+export interface MusicResult {
+  seed: number;
+  tags?: string[];
+  lyrics?: string;
+  audio: Array<{
+    url: string;
+    fileName: string;
+    contentType: string;
+    fileSize: number;
+  }>;
+  uploadUrls?: string[];
+}
+
+// core functions
+export async function generateMusic(
+  options: GenerateMusicOptions,
+): Promise<MusicResult> {
+  const {
+    prompt,
+    tags,
+    lyrics,
+    seed,
+    promptStrength = 2,
+    balanceStrength = 0.7,
+    numSongs = 1,
+    format = "mp3",
+    bitRate,
+    bpm = "auto",
+    upload = false,
+    outputPath,
+  } = options;
+
+  if (!prompt && !tags) {
+    throw new Error("either prompt or tags is required");
+  }
+
+  console.log(`[music] generating ${numSongs} song(s)...`);
+  if (prompt) console.log(`[music] prompt: ${prompt}`);
+  if (tags) console.log(`[music] tags: ${tags.join(", ")}`);
+  if (lyrics) console.log(`[music] lyrics: ${lyrics.substring(0, 50)}...`);
+
+  const result = await textToMusic({
+    prompt,
+    tags,
+    lyricsPrompt: lyrics,
+    seed,
+    promptStrength,
+    balanceStrength,
+    numSongs,
+    outputFormat: format,
+    outputBitRate: bitRate,
+    bpm,
+  });
+
+  const musicResult: MusicResult = {
+    seed: result.data.seed,
+    tags: result.data.tags,
+    lyrics: result.data.lyrics,
+    audio: Array.isArray(result.data.audio)
+      ? result.data.audio.map((a: any) => ({
+          url: a.url,
+          fileName: a.file_name,
+          contentType: a.content_type,
+          fileSize: a.file_size,
+        }))
+      : [
+          {
+            url: result.data.audio.url,
+            fileName: result.data.audio.file_name,
+            contentType: result.data.audio.content_type,
+            fileSize: result.data.audio.file_size,
+          },
+        ],
+  };
+
+  // save files locally if requested
+  if (outputPath) {
+    for (let i = 0; i < musicResult.audio.length; i++) {
+      const audio = musicResult.audio[i];
+      const ext = format || "wav";
+      const filePath =
+        musicResult.audio.length === 1
+          ? outputPath
+          : outputPath.replace(/\.[^.]+$/, `-${i + 1}.${ext}`);
+
+      // download the audio
+      const response = await fetch(audio.url);
+      const buffer = await response.arrayBuffer();
+      await writeFile(filePath, Buffer.from(buffer));
+      console.log(`[music] saved to ${filePath}`);
+    }
+  }
+
+  // upload to s3 if requested
+  if (upload) {
+    const uploadUrls: string[] = [];
+    for (let i = 0; i < musicResult.audio.length; i++) {
+      const audio = musicResult.audio[i];
+      const objectKey = `music/${Date.now()}-${i + 1}.${format || "wav"}`;
+      const uploadUrl = await uploadFromUrl(audio.url, objectKey);
+      uploadUrls.push(uploadUrl);
+      console.log(`[music] uploaded to ${uploadUrl}`);
+    }
+    musicResult.uploadUrls = uploadUrls;
+  }
+
+  return musicResult;
+}
+
+// cli
+async function cli() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === "help") {
+    console.log(`
+usage:
+  bun run service/music <command> [args]
+
+commands:
+  generate <prompt> [format] [numSongs] [upload]   generate music from prompt
+  tags <tags...> [format] [upload]                 generate music from tags
+  instrumental <tags...> [format] [upload]         generate instrumental track
+  help                                             show this help
+
+examples:
+  bun run service/music generate "A pop song about turtles flying"
+  bun run service/music generate "upbeat electronic" mp3 2 true
+  bun run service/music tags "rock" "energetic" "guitar" mp3
+  bun run service/music instrumental "ambient" "calm" "piano" wav true
+
+formats:
+  mp3 (default), wav, flac, ogg, m4a
+
+environment:
+  FAL_API_KEY - required for music generation
+  CLOUDFLARE_* - required for upload
+    `);
+    process.exit(0);
+  }
+
+  try {
+    switch (command) {
+      case "generate": {
+        const prompt = args[1];
+        const format = (args[2] || "mp3") as "flac" | "mp3" | "wav" | "ogg" | "m4a";
+        const numSongs = (parseInt(args[3]) || 1) as 1 | 2;
+        const upload = args[4] === "true";
+
+        if (!prompt) {
+          throw new Error("prompt is required");
+        }
+
+        const outputPath = `media/music-${Date.now()}.${format}`;
+
+        const result = await generateMusic({
+          prompt,
+          format,
+          numSongs,
+          upload,
+          outputPath,
+        });
+
+        console.log(`[music] result:`, {
+          seed: result.seed,
+          tags: result.tags,
+          audioCount: result.audio.length,
+          outputPath,
+          uploadUrls: result.uploadUrls,
+        });
+        break;
+      }
+
+      case "tags": {
+        // collect all tag arguments until we hit format/upload
+        const tags: string[] = [];
+        let format: "flac" | "mp3" | "wav" | "ogg" | "m4a" = "mp3";
+        let upload = false;
+
+        for (let i = 1; i < args.length; i++) {
+          const arg = args[i];
+          if (["mp3", "wav", "flac", "ogg", "m4a"].includes(arg)) {
+            format = arg as "flac" | "mp3" | "wav" | "ogg" | "m4a";
+          } else if (arg === "true") {
+            upload = true;
+          } else {
+            tags.push(arg);
+          }
+        }
+
+        if (tags.length === 0) {
+          throw new Error("at least one tag is required");
+        }
+
+        const outputPath = `media/music-${Date.now()}.${format}`;
+
+        const result = await generateMusic({
+          tags,
+          format,
+          upload,
+          outputPath,
+        });
+
+        console.log(`[music] result:`, {
+          seed: result.seed,
+          tags: result.tags,
+          audioCount: result.audio.length,
+          outputPath,
+          uploadUrls: result.uploadUrls,
+        });
+        break;
+      }
+
+      case "instrumental": {
+        // same as tags but with empty lyrics
+        const tags: string[] = [];
+        let format: "flac" | "mp3" | "wav" | "ogg" | "m4a" = "mp3";
+        let upload = false;
+
+        for (let i = 1; i < args.length; i++) {
+          const arg = args[i];
+          if (["mp3", "wav", "flac", "ogg", "m4a"].includes(arg)) {
+            format = arg as "flac" | "mp3" | "wav" | "ogg" | "m4a";
+          } else if (arg === "true") {
+            upload = true;
+          } else {
+            tags.push(arg);
+          }
+        }
+
+        if (tags.length === 0) {
+          throw new Error("at least one tag is required");
+        }
+
+        const outputPath = `media/music-${Date.now()}.${format}`;
+
+        const result = await generateMusic({
+          tags,
+          lyrics: "", // empty string for instrumental
+          format,
+          upload,
+          outputPath,
+        });
+
+        console.log(`[music] result:`, {
+          seed: result.seed,
+          tags: result.tags,
+          audioCount: result.audio.length,
+          outputPath,
+          uploadUrls: result.uploadUrls,
+        });
+        break;
+      }
+
+      default:
+        console.error(`unknown command: ${command}`);
+        console.log(`run 'bun run service/music help' for usage`);
+        process.exit(1);
+    }
+  } catch (error) {
+    console.error(`[music] error:`, error);
+    process.exit(1);
+  }
+}
+
+if (import.meta.main) {
+  cli();
+}
+

package/test-import.ts

@@ -0,0 +1,7 @@
+import { generateImage, imageToVideo, uploadFromUrl } from "./index";
+
+console.log("✓ imports successful");
+console.log("available functions:");
+console.log("- generateImage:", typeof generateImage);
+console.log("- imageToVideo:", typeof imageToVideo);
+console.log("- uploadFromUrl:", typeof uploadFromUrl);

package/test-services.ts

@@ -0,0 +1,97 @@
+#!/usr/bin/env bun
+
+/**
+ * test script for all sdk services
+ * saves all media files to media/ directory
+ */
+
+import { generateImage as generateFalImage } from "./lib/ai-sdk/fal";
+import { generateImage as generateReplicateImage } from "./lib/ai-sdk/replicate";
+import { textToSpeech } from "./lib/elevenlabs";
+import { runImage } from "./lib/replicate";
+
+async function testFalImage() {
+  console.log("\n=== testing fal image generation ===");
+
+  const result = await generateFalImage({
+    prompt: "a cozy coffee shop interior with warm lighting",
+    model: "fal-ai/flux/dev",
+    aspectRatio: "16:9",
+  });
+
+  if (result.image.uint8Array) {
+    const filename = "media/fal-coffee-shop.png";
+    await Bun.write(filename, result.image.uint8Array);
+    console.log(`✓ saved to ${filename}`);
+  }
+}
+
+async function testReplicateImage() {
+  console.log("\n=== testing replicate image generation ===");
+
+  const result = await generateReplicateImage({
+    prompt: "a mystical forest with glowing mushrooms",
+    model: "black-forest-labs/flux-dev",
+    aspectRatio: "1:1",
+  });
+
+  if (result.image.uint8Array) {
+    const filename = "media/replicate-forest.png";
+    await Bun.write(filename, result.image.uint8Array);
+    console.log(`✓ saved to ${filename}`);
+  }
+}
+
+async function testReplicateClient() {
+  console.log("\n=== testing replicate client (flux) ===");
+
+  try {
+    const output = await runImage({
+      model: "black-forest-labs/flux-schnell",
+      input: { prompt: "a serene zen garden with cherry blossoms" },
+    });
+
+    // output is array of FileOutput objects
+    if (Array.isArray(output) && output[0]) {
+      const imageUrl = output[0].toString();
+      console.log(`✓ generated image: ${imageUrl}`);
+
+      // download and save
+      const response = await fetch(imageUrl);
+      const buffer = await response.arrayBuffer();
+      const filename = "media/replicate-zen-garden.png";
+      await Bun.write(filename, buffer);
+      console.log(`✓ saved to ${filename}`);
+    }
+  } catch (error) {
+    console.error("✗ replicate client error:", error);
+  }
+}
+
+async function testElevenlabs() {
+  console.log("\n=== testing elevenlabs tts ===");
+
+  try {
+    await textToSpeech({
+      text: "welcome to varg ai sdk, your complete video production toolkit",
+      voiceId: "21m00Tcm4TlvDq8ikWAM",
+      outputPath: "media/welcome.mp3",
+    });
+    console.log("✓ saved to media/welcome.mp3");
+  } catch (error) {
+    console.error("✗ elevenlabs error:", error);
+  }
+}
+
+async function main() {
+  console.log("🚀 testing varg.ai sdk services...\n");
+
+  await testFalImage();
+  await testReplicateImage();
+  await testReplicateClient();
+  await testElevenlabs();
+
+  console.log("\n✨ all tests complete! check media/ directory");
+}
+
+main().catch(console.error);

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false
+  }
+}