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

package/README.md

@@ -1,231 +1,78 @@
-# varg.ai sdk
+# varg
 
-video generation and editing tools sdk
+AI video generation from your terminal.
 
-## folder structure
+## Quick Start
 
-```
-sdk/
-│
-├── media/              # working directory for media files (images, videos, audio)
-├── output/             # generated output files
-│
-├── utilities/
-│
-├── lib/
-│   ├── pymovie/
-│   ├── opencv/
-│   ├── fal/
-│   ├── higgsfield/
-│   ├── ffmpeg/
-│   ├── remotion/
-│   ├── remotion.dev/
-│   └── motion.dev/
-│
-├── service/
-│   ├── image/          # image generation + SKILL.md
-│   ├── video/          # video generation + SKILL.md
-│   ├── voice/          # voice synthesis + SKILL.md
-│   ├── sync/           # lipsync + SKILL.md
-│   ├── captions/       # video captions + SKILL.md
-│   ├── edit/           # video editing + SKILL.md
-│   └── transcribe/     # audio transcription + SKILL.md
-│
-└── pipeline/
-    └── cookbooks/
+```bash
+bun install @vargai/sdk
 ```
 
-## installation
-
 ```bash
-bun install
+varg run image --prompt "cyberpunk cityscape at night"
+varg run video --prompt "camera flies through clouds" --duration 5
+varg run voice --text "Hello world" --voice rachel
 ```
 
-set environment variables in `.env`:
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `varg run <action>` | Run an action |
+| `varg list` | List all available actions |
+| `varg find <query>` | Search actions by keyword |
+| `varg which <action>` | Show action details and options |
+| `varg help` | Show help |
+
+## Actions
+
+| Action | Description | Example |
+|--------|-------------|---------|
+| `image` | Generate image from text | `varg run image --prompt "sunset"` |
+| `video` | Generate video from text or image | `varg run video --prompt "ocean waves" --image ./photo.jpg` |
+| `voice` | Text-to-speech | `varg run voice --text "Hello" --voice sam` |
+| `music` | Generate music | `varg run music --prompt "upbeat electronic"` |
+| `transcribe` | Audio to text/subtitles | `varg run transcribe --audio ./speech.mp3` |
+| `captions` | Add subtitles to video | `varg run captions --video ./clip.mp4` |
+| `sync` | Lipsync audio to video | `varg run sync --video ./face.mp4 --audio ./voice.mp3` |
+| `trim` | Trim video | `varg run trim --input ./video.mp4 --start 0 --end 10` |
+| `cut` | Remove section from video | `varg run cut --input ./video.mp4 --start 5 --end 8` |
+| `merge` | Combine videos | `varg run merge --inputs ./a.mp4 ./b.mp4` |
+| `split` | Split video at timestamps | `varg run split --input ./video.mp4 --timestamps 10,20,30` |
+| `fade` | Add fade in/out | `varg run fade --input ./video.mp4 --type both` |
+| `transition` | Add transitions between clips | `varg run transition --inputs ./a.mp4 ./b.mp4` |
+| `upload` | Upload file to S3 | `varg run upload --file ./video.mp4` |
+
+Use `varg run <action> --help` for all options.
+
+## Environment Variables
+
+<details>
+<summary>Required API keys</summary>
+
 ```bash
+# AI Providers
 FAL_API_KEY=fal_xxx
-HIGGSFIELD_API_KEY=hf_xxx
-HIGGSFIELD_SECRET=secret_xxx
 REPLICATE_API_TOKEN=r8_xxx
-ELEVENLABS_API_KEY=el_xxx
+ELEVENLABS_API_KEY=xxx
 GROQ_API_KEY=gsk_xxx
 FIREWORKS_API_KEY=fw_xxx
+HIGGSFIELD_API_KEY=hf_xxx
+HIGGSFIELD_SECRET=secret_xxx
+
+# Storage (Cloudflare R2)
 CLOUDFLARE_R2_API_URL=https://xxx.r2.cloudflarestorage.com
 CLOUDFLARE_ACCESS_KEY_ID=xxx
 CLOUDFLARE_ACCESS_SECRET=xxx
-CLOUDFLARE_R2_BUCKET=m
+CLOUDFLARE_R2_BUCKET=bucket-name
 ```
 
-## usage
-
-### as cli
-
-```bash
-# generate image with ai-sdk (recommended)
-bun run lib/ai-sdk/fal.ts generate_image "a beautiful sunset" "fal-ai/flux/dev" "16:9"
-
-# generate image with fal client (advanced features)
-bun run lib/fal.ts generate_image "a beautiful sunset"
-
-# generate video from image (supports local files)
-bun run lib/fal.ts image_to_video "person talking" media/image.jpg 5
-bun run lib/fal.ts image_to_video "person talking" https://example.com/image.jpg 5
-
-# generate soul character
-bun run lib/higgsfield.ts generate_soul "professional headshot"
-
-# generate video with replicate
-bun run lib/replicate.ts minimax "person walking on beach"
+</details>
 
-# generate voice with elevenlabs
-bun run lib/elevenlabs.ts tts "hello world" rachel output.mp3
+## Contributing
 
-# transcribe audio to text/subtitles
-bun run service/transcribe media/audio.mp3 groq
-bun run service/transcribe media/audio.mp3 fireworks output.srt
-bun run lib/fireworks.ts media/audio.mp3 output.srt
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup.
 
-# edit video with ffmpeg
-bun run lib/ffmpeg.ts concat output.mp4 video1.mp4 video2.mp4
-
-# lipsync video with audio
-bun run service/sync overlay video.mp4 audio.mp3 synced.mp4
-
-# upload file to s3
-bun run utilities/s3.ts upload ./video.mp4 videos/output.mp4
-```
-
-### as library
-
-```typescript
-import { generateImage, imageToVideo } from "varg.ai-sdk"
-import { uploadFromUrl } from "varg.ai-sdk"
-
-// generate image
-const img = await generateImage({
-  prompt: "a beautiful sunset",
-  model: "fal-ai/flux-pro/v1.1",
-})
-
-// animate it
-const video = await imageToVideo({
-  prompt: "camera pan across scene",
-  imageUrl: img.data.images[0].url,
-  duration: 5,
-})
-
-// upload to s3
-const url = await uploadFromUrl(
-  video.data.video.url,
-  "videos/sunset.mp4"
-)
-
-console.log(`uploaded: ${url}`)
-```
-
-## modules
-
-### lib
-core libraries for video/audio/ai processing:
-- **ai-sdk/fal**: fal.ai using vercel ai sdk (recommended for images)
-- **ai-sdk/replicate**: replicate.com using vercel ai sdk
-- **fal**: fal.ai using direct client (for video & advanced features, supports local file uploads)
-- **higgsfield**: soul character generation
-- **replicate**: replicate.com api (minimax, kling, luma, flux)
-- **elevenlabs**: text-to-speech and voice generation
-- **groq**: ultra-fast whisper transcription (audio to text)
-- **fireworks**: word-level audio transcription with timestamps (srt/vtt)
-- **ffmpeg**: video editing operations (concat, trim, resize, etc.)
-- **remotion**: programmatic video creation with react
-
-### media folder
-- **media/**: working directory for storing input media files (images, videos, audio)
-- **output/**: directory for generated/processed output files
-- use `media/` for source files, `output/` for results
-- fal.ts supports local file paths from `media/` folder
-
-### service
-high-level services combining multiple libs. each service includes a SKILL.md for claude code agent skills:
-- **image**: image generation (fal + higgsfield)
-- **video**: video generation from image/text
-- **voice**: voice generation with multiple providers (elevenlabs)
-- **transcribe**: audio transcription with groq whisper or fireworks (srt support)
-- **sync**: lipsync workflows (wav2lip, audio overlay)
-- **captions**: auto-generate and overlay subtitles on videos
-- **edit**: video editing workflows (resize, trim, concat, social media prep)
-
-### utilities
-- **s3**: cloudflare r2 / s3 storage operations
-
-### pipeline
-- **cookbooks**: step-by-step recipes for complex workflows (includes talking-character SKILL.md)
-
-## key learnings
-
-### remotion batch rendering with variations
-when creating multiple video variations (e.g., 15 videos with different images):
-
-**❌ don't do this:**
-```bash
-# overwriting files causes caching issues
-for i in 1..15; do
-  cp woman-$i-before.jpg lib/remotion/public/before.jpg  # overwrites!
-  cp woman-$i-after.jpg lib/remotion/public/after.jpg    # overwrites!
-  render video
-done
-# result: all videos show the same woman (the last one)
-```
-
-**✅ do this instead:**
-```typescript
-// 1. use unique filenames for each variation
-// lib/remotion/public/woman-01-before.jpg, woman-02-before.jpg, etc.
-
-// 2. pass variation id as prop
-interface Props { variationId?: string }
-const MyComp: React.FC<Props> = ({ variationId = "01" }) => {
-  const beforeImg = staticFile(`woman-${variationId}-before.jpg`);
-  const afterImg = staticFile(`woman-${variationId}-after.jpg`);
-}
-
-// 3. register multiple compositions with unique props
-registerRoot(() => (
-  <>
-    {Array.from({ length: 15 }, (_, i) => {
-      const variationId = String(i + 1).padStart(2, "0");
-      return (
-        <Composition
-          id={`MyVideo-${variationId}`}
-          component={MyComp}
-          defaultProps={{ variationId }}
-          {...otherProps}
-        />
-      );
-    })}
-  </>
-));
-
-// 4. render each composition
-bun run lib/remotion/index.ts render root.tsx MyVideo-01 output-01.mp4
-bun run lib/remotion/index.ts render root.tsx MyVideo-02 output-02.mp4
-```
+## License
 
-**why this matters:**
-- remotion's `staticFile()` caches based on filename
-- overwriting files between renders causes all videos to use the last cached version
-- unique filenames + props ensure each render uses correct assets
-
-### fal.ai nsfw content filtering
-fal.ai automatically filters content that may be nsfw:
-
-**symptoms:**
-- image generation succeeds but returns empty file (~7.6KB)
-- no error message
-- happens with certain clothing/body descriptions
-
-**solution:**
-- be explicit about modest, full-coverage clothing:
-  - ✅ "long sleeve athletic top and full length leggings"
-  - ❌ "athletic wear" (vague, may trigger filter)
-- add "professional", "modest", "appropriate" to prompts
-- always check file sizes after batch generation (< 10KB = filtered)
+Apache-2.0 — see [LICENSE.md](LICENSE.md)

package/SKILLS.md

@@ -42,9 +42,16 @@ located in `service/<name>/SKILL.md`:
    - transcribe audio to text or subtitles using groq/fireworks
    - cli: `bun run service/transcribe <audioUrl> <provider> [outputPath]`
 
+### library skills
+
+8. **apify-scraping** (`lib/apify.ts`)
+   - run apify actors for web scraping (tiktok, google maps, social media, etc.)
+   - cli: `bun run lib/apify.ts run <actor_id> [input_json]`
+   - example: `bun run lib/apify.ts run clockworks/tiktok-scraper '{"hashtags":["viral"],"resultsPerPage":10}'`
+
 ### utility skills
 
-8. **telegram-send** (external: `/Users/aleks/Github/Badaboom1995/rumble-b2c`)
+9. **telegram-send** (external: `/Users/aleks/Github/Badaboom1995/rumble-b2c`)
    - send videos to telegram users/channels as round videos
    - automatically converts to 512x512 square format for telegram
    - cli: `cd /Users/aleks/Github/Badaboom1995/rumble-b2c && bun run scripts/telegram-send-video.ts <videoPath> <@username>`
@@ -54,16 +61,22 @@ located in `service/<name>/SKILL.md`:
 
 located in `pipeline/cookbooks/SKILL.md`:
 
-9. **talking-character-pipeline** (`pipeline/cookbooks/`)
-   - complete workflow to create talking character videos
-   - combines: character generation → voiceover → animation → lipsync → captions → social prep
+10. **talking-character-pipeline** (`pipeline/cookbooks/`)
+    - complete workflow to create talking character videos
+    - combines: character generation → voiceover → animation → lipsync → captions → social prep
+
+11. **round-video-character** (`pipeline/cookbooks/round-video-character.md`)
+    - create realistic round selfie videos for telegram using nano banana pro + wan 2.5
+    - workflow: generate selfie first frame (person in setting) → voiceover → wan 2.5 video
+    - uses: `bun run lib/fal.ts`, `bun run lib/replicate.ts`, `bun run lib/elevenlabs.ts`
+    - input: text script + profile photo
+    - output: extreme close-up selfie video with authentic camera shake, lighting, and audio
 
-10. **round-video-character** (`pipeline/cookbooks/round-video-character.md`)
-   - create realistic round selfie videos for telegram using nano banana pro + wan 2.5
-   - workflow: generate selfie first frame (person in setting) → voiceover → wan 2.5 video
-   - uses: `bun run lib/fal.ts`, `bun run lib/replicate.ts`, `bun run lib/elevenlabs.ts`
-   - input: text script + profile photo
-   - output: extreme close-up selfie video with authentic camera shake, lighting, and audio
+12. **trendwatching** (`pipeline/cookbooks/trendwatching.md`)
+    - discover viral tiktok content for any topic/hashtag
+    - uses apify tiktok scraper to find trending videos
+    - get engagement metrics: plays, likes, shares, comments
+    - cli: `bun run lib/apify.ts run clockworks/tiktok-scraper '{"hashtags":["topic"],"resultsPerPage":10}'`
 
 ## structure
 
@@ -145,9 +158,11 @@ each skill includes:
 | video-captions | captions | add subtitles, accessibility |
 | video-editing | edit | resize, trim, social media optimization |
 | audio-transcription | transcribe | speech-to-text, subtitle generation |
+| apify-scraping | lib/apify | web scraping via apify actors (tiktok, etc.) |
 | telegram-send | external | send videos to telegram as round videos |
 | talking-character-pipeline | pipeline | end-to-end talking character videos |
 | round-video-character | pipeline | telegram round selfie videos with wan 2.5 |
+| trendwatching | pipeline | discover viral tiktok content by hashtag |
 
 ## see also
 
@@ -155,3 +170,4 @@ each skill includes:
 - [STRUCTURE.md](STRUCTURE.md) - detailed module organization
 - [pipeline/cookbooks/talking-character.md](pipeline/cookbooks/talking-character.md) - talking character workflow
 - [pipeline/cookbooks/round-video-character.md](pipeline/cookbooks/round-video-character.md) - telegram round selfie video cookbook
+- [pipeline/cookbooks/trendwatching.md](pipeline/cookbooks/trendwatching.md) - discover viral tiktok content

package/biome.json

@@ -6,7 +6,13 @@
     "useIgnoreFile": true
   },
   "files": {
-    "ignoreUnknown": false
+    "ignoreUnknown": false,
+    "includes": [
+      "**",
+      "!node_modules",
+      "!sdk-py-reference",
+      "!src/ai-sdk/examples/*.tsx"
+    ]
   },
   "formatter": {
     "enabled": true,