ViralMint
The open-source, local-first video pipeline for creators
Scout trends → clip long videos → generate captioned shorts → design motion graphics → polish with 22 local tools. 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 22 editing tools 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 get back a finished MP4 with an AI-drafted title, description and tags, ready to post. Drive it from a browser, or chat with it on Telegram, WhatsApp, Discord, or Slack.
✨ Why ViralMint
| 🔒 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, or point it at any OpenAI-compatible server (Ollama, LM Studio, vLLM…). Encrypted at rest with Fernet (AES-128-CBC, HMAC-signed), sent straight to the provider — there is no ViralMint server in between. |
| 🤖 Agents, not a chat wrapper | Purpose-built agents — Planner, Scout, Download, Analyzer and Generator — orchestrated by a streaming AI chat that actually runs the work. |
| ✂️ Clip, generate, or design | Three ways to a finished video: cut shorts from a long source on a real timeline, generate a captioned stock-footage video from a script, or author motion graphics with no footage at all. |
| 📱 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 built-in tools (most of them pure FFmpeg + Whisper) — the heavy lifting costs $0. Pay only for the AI you choose to plug in. |
Battle-tested: a 2,900-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.
🎯 Features
🔍 ScoutMulti-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). |
🧠 AnalyzeLocal 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. |
🎬 GenerateFull 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. |
✂️ Clip StudioOne 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. |
🎞️ Motion GraphicsA 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. |
🗂️ LibraryOne 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. |
💬 ChatStreaming 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. The chat reads your live pipeline — downloaded-but-not-clipped, generated-but-not-posted, scouted-but-not-downloaded — and suggests the single highest-value next step instead of waiting to be asked. |
📲 MessagingTwo-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. |
⬇️ Universal downloaderyt-dlp under the hood — YouTube, TikTok, Bilibili, Instagram, Twitter/X, SoundCloud, Vimeo, and 1,800+ other sites. No watermarks, no ads, no cap. |
🧰 22 built-in toolsSingle-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. |
🆓 What works without API keys
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.
🚀 Quick Start
Prerequisites
| 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 |
Install & run
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.py
The first run installs frontend deps, builds the SPA, starts the API, and opens your browser at http://localhost:16888.
📦 Prefer an installer? Prebuilt apps for macOS, Windows and Linux are on the Releases page. The macOS build is for Apple Silicon (M1 or later); on an Intel Mac, run from source as above.
💡 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. Prefer your own server? Pick OpenAI-compatible and enter its base URL (e.g.
http://localhost:11434/v1for Ollama) and model name — no key needed for local servers. Edge TTS, Whisper, FFmpeg, and yt-dlp all work offline with zero configuration.
Build a desktop app from source (optional)
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.sh
Output 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.
🔑 Bring your own keys (BYOK)
Every key can be set in .env or per-user inside the app under Settings — whichever is set takes priority. Per-user keys are Fernet-encrypted (AES-128-CBC + HMAC-SHA256) 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 · any OpenAI-compatible server | console.anthropic.com · platform.openai.com · openrouter.ai/keys · your server's base URL — Settings → AI Provider | Pay-per-use (free on a local server) |
| 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 |
| 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.
🏗️ Architecture
┌────────────────────────────────────────────────┐
│ 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 │
│ Messaging ─────── Telegram · WhatsApp · │
│ Discord · Slack │
└─────────────────┬──────────────────────────────┘
│
┌────────────────────────┼─────────────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌──────────────────────┐ ┌──────────────────┐
│ SQLite local │ │ storage/ on disk │ │ External APIs │
│ (encrypted │ │ videos · audio · │ │ (BYOK, direct) │
│ credentials) │ │ thumbnails · sfx │ │ │
└─────────────────┘ └──────────────────────┘ └──────────────────┘
Tech stack
| 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) · any OpenAI-compatible server (Ollama, LM Studio, vLLM…) |
| Transcription | faster-whisper (local, multilingual, CPU int8) |
| 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-128-CBC + HMAC-SHA256) for credentials at rest |
📸 Screenshots
|
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. |
📁 Project structure
ViralMint/
├── run.py # 🚀 Single entry point
├── launcher.py # System-tray launcher (optional)
│
├── backend/
│ ├── agents/ # Planner, Scout, Download, Analyzer, Generator
│ ├── 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,900+ tests)
├── storage/ # Downloaded videos, audio, generated output (gitignored)
│
├── requirements.txt
├── .env.example
├── CONTRIBUTING.md
├── SECURITY.md
└── LICENSE # AGPL-3.0
🤝 Contributing
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.
📜 License & responsible use
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, 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.
🙋 Don't want to self-host?
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 — 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. The hosted tools most people arrive through: the AI video clipper for YouTube, the YouTube video downloader, the AI caption generator and the AI video generator. Otherwise, everything you need is right here — read on and python run.py.
⭐ If ViralMint is useful to you, star it
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