Scout trends → clip long videos → generate AI shorts → auto-publish to YouTube & TikTok. All on your machine. Bring your own API keys. No SaaS in the middle. No telemetry.
Quick Start • Features • What's free • BYOK • Contributing
Chat with the AI agent — paste a URL, ask it to scout a niche, or kick off a workflow, and it runs the right pipeline in the background.
What manual creators do across a dozen tabs and apps, ViralMint runs as one local workflow. Find trending videos across YouTube, TikTok and Douyin, transcribe and analyze them with local Whisper, cut long videos into publishable shorts, write original scripts with the AI of your choice, render captioned stock-footage videos — and post directly to YouTube and TikTok. Drive it from a browser, or chat with it on Telegram, WhatsApp, Discord, or Slack.
| 🔒 100% local | SQLite, local Whisper, local FFmpeg. Your scripts, transcripts, downloads, and generated videos never leave your machine. |
| 🔑 BYOK, no middleman | Bring your own Anthropic / OpenAI / OpenRouter / YouTube / Pexels keys. Encrypted at rest with AES-256, sent straight to the provider — there is no ViralMint server in between. |
| 🤖 Agents, not a chat wrapper | Six purpose-built agents — Planner, Scout, Download, Analyzer, Generator, and Uploader — orchestrated by a streaming AI chat that actually runs the work. |
| 📤 It publishes for you | Direct upload to YouTube and TikTok with AI-drafted titles, descriptions, tags, and thumbnails. The full loop, not just generation. |
| 📱 Runs from your phone | Two-way chat with the planner over Telegram, WhatsApp, Discord, or Slack — and job alerts in the same thread. |
| 🆓 Free out of the box | Local Whisper, Edge TTS (400+ voices), royalty-free music, Pexels stock, and 18 FFmpeg tools — the heavy lifting costs $0. Pay only for the AI you choose to plug in. |
Battle-tested: a ~1,000-test pytest suite (999 and counting) runs on every commit. AGPL-3.0 — fork it, modify it, build a business on it.
|
Multi-platform trend discovery across YouTube, TikTok, and Douyin (plus any yt-dlp-supported site via dynamic search), with AI virality scoring, Google-Trends demand signals, view-velocity analysis, and outlier detection (3×–20× the channel baseline). |
Local Whisper transcription with clean long-form handling, plus AI insight extraction — hook, structure, tone, retention risks, suggested titles, and a ready-to-run recreate prompt — scored per segment with concrete improvement suggestions. |
|
Full pipeline: AI script → TTS voiceover → Pexels stock footage matched to keywords → phrase-aware animated captions (with CJK / Arabic / Thai support) → balanced background music → AI thumbnail → finished MP4. |
One long video → many publishable shorts. AI finds the best moments and scores each on hook, flow, value, trend-fit and shareability, snaps cuts to sentence boundaries, and drops re-told stories. Bias picks by platform or genre, describe what you want ("every joke that landed"), or hand-pick manual time ranges — with optional silence trimming, emoji captions, and a burned-in hook overlay. |
|
Direct upload to YouTube (OAuth) and TikTok (OAuth or session cookie) with platform-optimized titles, descriptions, tags, and thumbnails — so a finished video actually gets posted. |
Streaming WebSocket chat that orchestrates every agent. Say "scout cooking videos" or "download this URL" and it just runs. Tappable quick-reply chips, follow-up questions that never lock the composer, and rich result cards that persist across reloads. |
|
Two-way chat from your phone via Telegram, WhatsApp, Discord, Slack. Command the planner from anywhere and get job alerts as they finish — same agent, different transport. |
yt-dlp under the hood — YouTube, TikTok, Bilibili, Instagram, Twitter/X, SoundCloud, Vimeo, and 1,800+ other sites. No watermarks, no ads, no cap. |
|
Single-purpose utilities — captions, reframe, GIF, speed, trim, subtitles, watermark, merge, auto-zoom, music-visualizer, voice-over, plus AI helpers (translate, metadata, hook analysis, auto-chapters). Most run 100% locally on FFmpeg + Whisper — no API key. Each has an inline result preview. |
The chat reads your live pipeline — downloaded-but-not-clipped, generated-but-not-uploaded, scouted-but-not-downloaded — and suggests the single highest-value next step instead of waiting to be asked. |
The expensive parts are free and local. You only pay for the AI you choose to plug in.
| Feature | Powered by | Cost |
|---|---|---|
| Video downloading from 1,800+ sites | yt-dlp | $0 |
| Audio transcription | Local faster-whisper | $0 |
| Voiceover (400+ voices, 70+ languages) | Edge TTS | $0 |
| Word-by-word animated captions | FFmpeg + ASS subtitles | $0 |
| Background music library | Royalty-free local library | $0 |
| Sound-effects auto-placement | FFmpeg-synthesized | $0 |
| Tools: reframe, GIF, speed, trim, watermark, merge, auto-zoom, music-visualizer, subtitles… | FFmpeg + Whisper | $0 |
YouTube / TikTok / Pexels still need free API keys — links in the BYOK section.
| Tool | macOS | Linux | Windows |
|---|---|---|---|
| Python 3.11+ | brew install python |
apt install python3.11 |
python.org |
| Node.js 18+ | brew install node |
apt install nodejs npm |
nodejs.org |
| FFmpeg | brew install ffmpeg |
apt install ffmpeg |
ffmpeg.org |
| ImageMagick | brew install imagemagick |
apt install imagemagick |
imagemagick.org |
git clone https://github.com/openclaw-easy/ViralMint.git
cd ViralMint
python -m venv venv && source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env # optional — keys can also be set in the UI
python run.pyThe first run installs frontend deps, builds the SPA, starts the API, and opens your browser at http://localhost:16888.
💡 No API key yet? Open Settings → AI Provider after launch and paste an Anthropic, OpenAI, or OpenRouter key. OpenRouter is a single gateway to 300+ models — one key gets you Claude, GPT, Gemini, Llama, and Mistral. Edge TTS, Whisper, FFmpeg, and yt-dlp all work offline with zero configuration.
Prefer a clickable app to a terminal command? A self-contained PyInstaller pipeline builds a macOS .dmg, Linux .tar.gz, or Windows .zip from this source — your browser is still the UI.
PYTHON_BIN=./venv/bin/python VIRALMINT_VERSION=0.1.0-dev \
bash desktop/scripts/build-app.shOutput lands in desktop/release/. First build takes ~10–15 min (PyInstaller bundling is the long pole). Skip flags, signing/notarization env vars, and the smoke-test recipe are in desktop/README.md.
Every key can be set in .env or per-user inside the app under Settings — whichever is set takes priority. Per-user keys are AES-256 encrypted before storage. Keys go straight to the provider; ViralMint has no backend server in the middle.
| For | Provider | Where | Cost |
|---|---|---|---|
| AI chat, scripting, analysis | Anthropic · OpenAI · OpenRouter | console.anthropic.com · platform.openai.com · openrouter.ai/keys — Settings → AI Provider | Pay-per-use |
| YouTube scouting · comments · My Channels | YouTube Data API v3 | console.cloud.google.com/apis/credentials — Settings → Service API Keys | Free 10K units/day |
| Stock footage | Pexels | pexels.com/api | Free |
| Premium voiceover (optional) | OpenAI TTS | platform.openai.com | Pay-per-use |
| TikTok / Douyin scouting | TikHub API (recommended) | tikhub.io | Free tier |
| YouTube / TikTok upload | OAuth | One-click in Settings | Free |
| Telegram / Discord / Slack | Bot tokens | Settings → Messaging | Free |
| QR-scan pairing | Settings → Messaging | Free |
⚠️ TikTok / Douyin session-cookie scouting is available as an advanced fallback in Settings, but it violates the platforms' Terms of Service and the cookie's account is the one the platform sees acting. Use the TikHub API path unless you have specifically accepted that risk. See LEGAL.md for details.
┌────────────────────────────────────────────────┐
│ React 18 + MUI 7 SPA │
│ (served by FastAPI in production) │
│ Chat · Channels · Library · Stock Video │
│ Clip Studio · Messaging · Tools · Settings │
└─────────────────┬──────────────────────────────┘
│ HTTP + WebSocket
▼
┌────────────────────────────────────────────────┐
│ FastAPI · localhost:16888 │
├────────────────────────────────────────────────┤
│ Planner Agent ─── streaming chat + actions │
│ Scout Agent ───── YouTube · TikTok · Douyin │
│ (+ yt-dlp dynamic search) │
│ Download Agent ── yt-dlp (1,800+ sites) │
│ Analyzer Agent ── Whisper + AI insights │
│ Generator Agent ─ Script → TTS → Stock → │
│ Captions → Music → MP4 │
│ Uploader Agent ── YouTube + TikTok OAuth │
│ Messaging ─────── Telegram · WhatsApp · │
│ Discord · Slack │
└─────────────────┬──────────────────────────────┘
│
┌────────────────────────┼─────────────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌──────────────────────┐ ┌──────────────────┐
│ SQLite local │ │ storage/ on disk │ │ External APIs │
│ (encrypted │ │ videos · audio · │ │ (BYOK, direct) │
│ credentials) │ │ thumbnails · sfx │ │ │
└─────────────────┘ └──────────────────────┘ └──────────────────┘
| Layer | Stack |
|---|---|
| Backend | Python 3.11+ · FastAPI · SQLAlchemy 2.0 (async) · SQLite · WebSockets |
| Frontend | React 18 · Vite · MUI 7 · Zustand · React Router 6 |
| AI (BYOK) | Anthropic Claude SDK · OpenAI SDK · OpenRouter (300+ models via one key) |
| Transcription | faster-whisper (local, multilingual, GPU-aware) |
| TTS | Edge TTS (free) · OpenAI TTS |
| Video | Pexels stock · FFmpeg · Ken Burns image fallback |
| Captions | FFmpeg + ASS (word-by-word highlight animation) |
| Download | yt-dlp (1,800+ sites) |
| Messaging | python-telegram-bot · discord.py · slack-sdk · neonize (WhatsApp) |
| Security | Fernet (AES-256) for credentials at rest |
Library — Scout resultsVideos discovered across platforms, sorted by AI virality score, downloadable in one click. |
Clip Studio — viral clip extractionAI picks the best 30–60s moments from a long video, scores them, and burns captions automatically. |
Messaging — chat from your phoneConnect Telegram, WhatsApp, Discord, or Slack to control the planner and receive job notifications. |
My Channels — channel analyticsConnect any YouTube/TikTok channel by URL. View counts, engagement, median views, and outlier detection. |
Smart Video studioMix your own clips with stock footage; word-by-word captions; background music; live cost estimator. |
Tools — 18 utilitiesReframe, watermark, GIF, speed, trim, subtitles, voice-over, hook analysis — most run locally with no API key. |
ViralMint/
├── run.py # 🚀 Single entry point
├── launcher.py # System-tray launcher (optional)
│
├── backend/
│ ├── agents/ # Planner, Scout, Download, Analyzer, Generator, Uploader
│ ├── api/ # REST + WebSocket endpoints
│ ├── core/ # AI client, BYOK key resolver, crypto, WebSocket manager
│ ├── messaging/ # Telegram / WhatsApp / Discord / Slack channels
│ ├── models/ # SQLAlchemy models
│ └── services/ # TTS, video gen, captions, music, yt-dlp, Whisper, …
│
├── frontend/
│ └── src/
│ ├── pages/ # Chat · Channels · Library · Stock Video · Clip Studio · …
│ ├── components/ # Reusable UI (chat, settings, videos, …)
│ ├── hooks/ # WebSocket, settings, jobs, source video
│ └── store/ # Zustand global state
│
├── tests/ # pytest suite (~1,000 tests)
├── storage/ # Downloaded videos, audio, generated output (gitignored)
│
├── requirements.txt
├── .env.example
├── CONTRIBUTING.md
├── SECURITY.md
└── LICENSE # AGPL-3.0
Pull requests welcome — bug fixes, new platforms, additional messaging channels, performance work, docs, anything. Read CONTRIBUTING.md for the workflow and house style, and the Code of Conduct before opening your first issue.
- 📋 Recent changes: CHANGELOG.md
- 🐛 Report a bug: open an issue
- 💡 Request a feature: open an issue
- 🔐 Security vulnerability: SECURITY.md — do not file a public issue.
ViralMint is licensed under the GNU Affero General Public License v3.0 (LICENSE).
- ✅ Free for personal use, commercial use, modification, and redistribution
- ✅ Run a SaaS on top of it
⚠️ If you distribute it (or run it as a public network service), you must share your modified source under the same AGPL-3.0 terms
ViralMint is a tool you run on your own machine. The maintainers don't host your content or proxy your API calls — every action is you, acting on your own platforms and keys. Read LEGAL.md before using the scouting and downloader features so you understand what's sanctioned (YouTube Data API, OAuth uploads, Pexels), what's at-your-own-risk (TikTok/Douyin session-cookie scouting), and what you're responsible for under each platform's Terms of Service.
There's also a hosted build at viralmint.net — the same scout + analyze + generate engine, signed and notarized, with no API keys to wire up (prepaid credits instead of BYOK). It's closed-source and doesn't auto-upload — a different set of trade-offs for people who'd rather not run their own keys and installs. Full comparison + FAQ: docs/hosted-vs-self-hosted.md. Otherwise, everything you need is right here — read on and python run.py.
Stars are the single biggest thing that helps this project — they attract contributors, unlock awesome-list eligibility, and tell other creators it's worth a look. It takes one click.
⭐ Star openclaw-easy/ViralMint
📈 See ViralMint's star history →
Built with FastAPI, React, Whisper, FFmpeg, and a lot of async Python.
Website: viralmint.net · Source: github.com/openclaw-easy/ViralMint · License: AGPL-3.0