ViralMint

The open-source viral content pipeline

Scout trends → Analyze competitors → Generate videos → Auto-publish → Run anywhere from your phone.
100% local. Bring your own API keys. No SaaS lock-in. No telemetry.

🌐 Website • Quick Start • Features • Architecture • API Keys • Contributing

🚦 Two ways to use ViralMint

Same scout + analyze + generate engine. Different operational trade-offs. Pick the one that matches how you want to work.

git clone https://github.com/openclaw-easy/ViralMint
cd ViralMint && python run.py

The README below documents the self-host variant — keep reading if that's the path you want, or hop over to viralmint.net for the hosted experience.

What manual creators do every day, ViralMint automates in one workflow.
Find trending videos across 5 platforms, transcribe and analyze them with local Whisper, write original scripts with AI, render stock-footage videos with word-by-word captions, and post directly to YouTube and TikTok — all from a single command. Talk to it from a browser, or chat with it on Telegram, WhatsApp, Discord, or Slack.

_{Chat with the AI agent: paste a URL, ask for a scout, or kick off a workflow — it runs the right pipeline in the background.}

✨ Why ViralMint

🚀 Quick Start

Prerequisites

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.

💡 Don't have an API key yet? Open Settings → AI Provider after launch and paste your Anthropic, OpenAI, or OpenRouter key directly into the UI. OpenRouter is a unified gateway — a single key gets you Claude, GPT, Gemini, Llama, and Mistral. Edge TTS, Whisper, FFmpeg, and yt-dlp work offline with zero configuration.

Build a desktop .app from source (optional)

If you'd rather have a clickable .app than a terminal command, the repo includes a self-contained PyInstaller pipeline that produces a macOS .dmg, Linux .tar.gz, or Windows .zip of this OSS source — same code, no terminal needed at runtime.

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 live in desktop/README.md.

Note: this build is a vanilla bundle of the OSS app — your browser is the UI, no tray launcher, no auto-update, no signed binaries unless you provide a Developer ID. The richer desktop experience (Tools page, AI Music tab, Visual Style preset, signed-and-notarized installer) comes from the prebuilt viralmint.net installer.

🎯 Features

📸 Screenshots

Library — Scout results 154 videos discovered, sorted by AI virality score, downloadable in one click.	Clip Studio — viral clip extraction AI picks the best 30–60s moments from a long video, scores them, and burns captions automatically.
Messaging — chat from your phone Connect Telegram, WhatsApp, Discord, or Slack to control the planner agent and receive job notifications.	My Channels — channel analytics Connect any YouTube/TikTok channel by URL. View counts, engagement, median views, and outlier detection.
Smart Video studio (extras like the Visual Style preset and AI Music tab are exclusive to the desktop installer) Mix your own clips with stock footage; word-by-word captions; background music; cost estimator.	Tools (bundled in the desktop installer) Quick Chain, AI Image, AI Music, Voice-over, Reframe, Watermark, Translate + Dub, Hook Detector — single-purpose utilities for finishing videos.

🆓 What works without API keys

YouTube/TikTok/Pexels still require free API keys — links in the next section.

🔑 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 AES-256 encrypted before storage. Keys go straight to the provider; ViralMint has no backend server in the middle.

⚠️ TikTok / Douyin session-cookie scouting is also available as an advanced fallback in Settings, but it violates the platforms' Terms of Service and the cookie's TikTok/Douyin account is the one TikTok/Douyin 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 · Channels · Library · Stock Video       │
                     │  Clip Studio · Messaging · Settings            │
                     └─────────────────┬──────────────────────────────┘
                                       │  HTTP + WebSocket
                                       ▼
                     ┌────────────────────────────────────────────────┐
                     │           FastAPI · localhost:16888            │
                     ├────────────────────────────────────────────────┤
                     │  Planner Agent ─── streaming chat + actions    │
                     │  Scout Agent ───── YouTube · TikTok · Douyin · │
                     │                    Google Trends               │
                     │  Download Agent ── yt-dlp (1000+ 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    │    │                  │
    └─────────────────┘    └──────────────────────┘    └──────────────────┘

Tech stack

📁 Project structure

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 · …
│       ├── components/             # Reusable UI (chat, settings, videos, …)
│       ├── hooks/                  # WebSocket, settings, jobs, source video
│       └── store/                  # Zustand global state
│
├── tests/                          # pytest test suite (92 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 review the Code of Conduct before opening your first issue.

• 📋 Recent changes: see CHANGELOG.md
• 🐛 Report a bug: open an issue
• 💡 Request a feature: open an issue
• 🔐 Security vulnerability: see SECURITY.md — do not file a public issue.

📜 License & terms of use

ViralMint is licensed under the GNU Affero General Public License v3.0 (LICENSE).

In practice that means:

• ✅ Free for personal use, commercial use, modification, redistribution
• ✅ Run a SaaS on top of it
• ⚠️ If you distribute it (or run it as a public network service), you must share the 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.

⭐ Star history

---

Built with FastAPI, React, Whisper, FFmpeg, and a lot of async Python.