ViralMint

The open-source, local-first video pipeline for creators

Scout trends → clip long videos → build captioned shorts scene by scene → 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

English · 简体中文 · 日本語

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, a scene-by-scene video studio, 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, build captioned videos scene by scene in a studio where you hear every line before you render, 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

Battle-tested: a 4,000-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.

Related MCP server: Oh My Cassette

🎯 Features

🔍 Scout

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).

🧠 Analyze

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.

🎬 Smart Video Studio

Write or paste a script — or let your AI draft one from a topic — and it becomes a project of up to 40 scenes. Every scene has a voice take you can play and a stock clip you can watch (Pexels or Pixabay, portrait-first for vertical video) or one of your own. Rewrite a line and only that scene is re-voiced; split, merge, reorder, swap clips, pick the look, music and caption style, then render exactly what you previewed. Captions are word-by-word, with CJK / Arabic / Thai support.

✂️ Clip Studio

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.

🎞️ Motion Graphics

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.

🗂️ Library

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.

💬 Chat

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. 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.

📲 Messaging

Two-way chat from your phone via Telegram, WhatsApp, Discord, Slack — connect one under Settings → Messaging with a one-time pairing code, so the bot answers only you. Command the planner from anywhere and get job alerts as they finish.

⬇️ Universal downloader

yt-dlp under the hood — YouTube, TikTok, Bilibili, Instagram, Twitter/X, SoundCloud, Vimeo, and 1,800+ other sites. No watermarks, no ads, no cap. Pick quality, container, subtitles, cover art and metadata; a stalled or failing download says why instead of hanging, and Cancel really stops it.

🧰 22 built-in tools

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.

🆓 What works without API keys

The expensive parts are free and local. You only pay for the AI you choose to plug in.

YouTube / TikTok / Pexels still need free API keys — links in the BYOK section.

🚀 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.

📦 Prefer an installer? Prebuilt apps for macOS, Windows and Linux are on the Releases page. On macOS, take -mac.dmg for Apple Silicon (M1 or later) or -mac-intel.dmg for an Intel Mac (from the first release that ships it; older releases are Apple Silicon only, so 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/v1 for 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.

🧩 Use it from Claude Code, Codex or Cursor (MCP)

ViralMint serves the Model Context Protocol at http://127.0.0.1:16888/mcp/, so an AI agent can run the whole pipeline in plain language — "find a breakout in home espresso, analyze it, and make me an original 45-second Short".

1. Start ViralMint and open MCP in the sidebar.

2. Pick your client (Claude Code, Claude Desktop, Codex, Cursor, Windsurf, Gemini CLI) and paste the snippet it shows. For Claude Code that's one claude mcp add line.

3. Click Test connection — it runs the same handshake your client will.

69 tools cover research (scout, breakouts, news, search demand, keyword scoring), acquisition (download, import, channels), creation (Smart Video, scripts, batch, motion graphics), the Clip Studio picker (suggest / auto-cut / manual cut), all the single-purpose editing tools, and job control (wait_for_job returns the finished file's path). Six built-in prompts (viralmint:create_viral_short, viralmint:repurpose_long_form, …) give the agent known-good recipes, and resources expose your recent videos, channels, niches and transcripts.

• Your keys, your bill. AI-backed tools run on the provider you configured under Settings → AI Provider — exactly like the UI.

• Token-gated. Every request needs the Bearer token from the /mcp page (stored at <data dir>/mcp_token; rotate it there). The page only shows the token to a browser on the same computer, even in LAN mode.

• File-path tools read files on the machine running ViralMint. That's what lets an agent say "caption ~/Desktop/clip.mp4" — and why the token deserves the same care as an SSH key.

• Nothing is posted for you. No MCP tool uploads or publishes; you post the finished video yourself.

🔑 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.

⚠️ 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             │
                     │  Smart Video · Clip Studio · Motion Graphics   │
                     │  Tools · MCP · Settings (incl. Messaging)      │
                     └─────────────────┬──────────────────────────────┘
                                       │  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       │
                     │  Smart Video ───── scenes → voice takes →      │
                     │                    stock/own clips → render    │
                     │  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

📸 Screenshots

📁 Project structure

ViralMint/
├── run.py                          # 🚀 Single entry point
├── launcher.py                     # System-tray launcher (the desktop app's entry point)
│
├── backend/
│   ├── agents/                     # Planner, Scout, Download, Analyzer, Generator
│   ├── api/                        # REST + WebSocket endpoints
│   ├── core/                       # AI client, BYOK key resolver, crypto, WebSocket manager
│   ├── mcp/                        # MCP server at /mcp — tools, prompts, resources
│   ├── 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 · Smart Video ·
│       │                           #   Clip Studio · Motion Graphics · Tools · MCP · Settings
│       ├── components/             # Reusable UI (chat, settings, videos, …)
│       ├── hooks/                  # WebSocket, settings, jobs, source video
│       └── store/                  # Zustand global state
│
├── tests/                          # pytest suite (4,000+ 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

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