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
Cut a long video into shorts on a real timeline — drag across its own frames, snap to sentence boundaries, or let the AI propose the moments. Scouting, transcription, AI video, motion graphics and publishing all run from the same app.
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 on a real timeline, write original scripts with the AI of your choice, render captioned stock-footage videos, design animated motion graphics — 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 22 FFmpeg tools — the heavy lifting costs $0. Pay only for the AI you choose to plug in. |
Battle-tested: a 2,300-test pytest suite runs on every commit, plus a browser harness that drives the real app end to end. 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, cut on a real timeline. Drag across a filmstrip of the source's own frames, watch the first and last frame of your cut as you move the handles, and snap to sentence boundaries so a clip never opens mid-word. Type an exact timecode, paste times from show notes, or ask the AI — its picks land as blocks you can retime or delete before anything renders, scored on hook, flow, value, trend-fit and shareability. In a hurry, Auto-cut does the whole thing in one press and tells you how many clips that means first. |
|
A third kind of output, with no footage in it at all: kinetic typography, animated stat cards, lower thirds, product showcases. Describe what you want and the AI writes a real composition; refine it in an embedded animation studio with a timeline, layers and an inspector, then render it entirely on your own machine. Installs on demand — it isn't in the download. |
One faceted view over everything you own — renders, downloads, every tool output, your music folder. Two questions get two controls: tabs say what a file is (video / image / audio / files), chips say where it came from (created / edited / sources), so a downloaded mp3 doesn't have to pick a side. Group by source to see a download beside everything you made from it, and open Activity from any page to watch work in flight. |
|
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, crop, compress, GIF, speed, trim, subtitles, watermark, merge, auto-zoom, music-visualizer, voice-over, silence removal, video download, 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 and a history of what it produced. |
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, crop, compress, GIF, speed, trim, watermark, merge, auto-zoom, music-visualizer, subtitles… | FFmpeg + Whisper | $0 |
| Motion-graphics rendering | Local HyperFrames engine | $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 · Scout · Channels · Library │
│ Stock Video · Clip Studio · Motion Graphics │
│ Tools · Messaging · 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 │
│ Motion Renderer ─ local HyperFrames engine │
│ 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 |
|
Clip Studio — the cutting bench Drag across the source's own frames. Speech lane, sentence snapping, IN/OUT previews, and typeable timecodes. Nothing renders until you press Cut. |
Auto-cut — the express laneTrust the AI and skip the review step. It says how many clips that means for this video before you press the button. |
Library — everything you ownOne view over renders, downloads, every tool output and your music folder. Tabs say what a file is; chips say where it came from. |
Motion Graphics — designed video, rendered locallyKinetic type, stat cards, lower thirds. The AI writes the composition; you refine it on a timeline and render on your own machine. |
Smart Video studioScript → voiceover → stock footage → word-by-word captions → music, in one pass. Mix in your own clips and pick a visual style. |
Tools — 22 utilitiesReframe, crop, compress, watermark, GIF, speed, trim, subtitles, voice-over, hook analysis — most run locally with no API key. |
Chat — the agent that runs itPaste a URL, name a niche, or ask for a video. It dispatches the right agent and reports back in the same thread. |
Messaging — drive it from your phoneConnect Telegram, WhatsApp, Discord or Slack to command the same agent and get job alerts as they finish. |
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,
│ # motion rendering, library index, …
│
├── frontend/
│ └── src/
│ ├── pages/ # Chat · Scout · Channels · Library · Stock Video ·
│ │ # Clip Studio · Motion Graphics · Tools · Messaging
│ ├── components/ # Reusable UI (chat, settings, videos, …)
│ ├── hooks/ # WebSocket, settings, jobs, source video
│ └── store/ # Zustand global state
│
├── tests/ # pytest suite (2,300+ 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