Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.
Python ai-toolsauto-captionscaptionscliffmpegmcpmcp-serveropusclip-alternativepodcast-clipspodcastsshortform-videovertical-videowhisper
fix: ready to opensource
Nika Siradzea4f600e0dcea
diff --git a/.env.example b/.env.exampleindex a408daf..a645db3 100644--- a/.env.example+++ b/.env.example@@ -13,7 +13,7 @@ FFPROBE_PATH=# Python path (leave blank to auto-detect venv)PYTHON_PATH=-# Working directory (defaults to ~/.podcli)+# Working directory (defaults to .podcli/ in project root)PODCLI_HOME=# Loggingdiff --git a/LICENSE b/LICENSEnew file mode 100644index 0000000..36a335c--- /dev/null+++ b/LICENSE@@ -0,0 +1,21 @@+MIT License++Copyright (c) 2025 podcli contributors++Permission is hereby granted, free of charge, to any person obtaining a copy+of this software and associated documentation files (the "Software"), to deal+in the Software without restriction, including without limitation the rights+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell+copies of the Software, and to permit persons to whom the Software is+furnished to do so, subject to the following conditions:++The above copyright notice and this permission notice shall be included in all+copies or substantial portions of the Software.++THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE+SOFTWARE.diff --git a/README.md b/README.mdindex 623e4d1..b3a60d6 100644--- a/README.md+++ b/README.md@@ -1,36 +1,35 @@# podcli-AI-powered podcast clip generator. Takes a long-form podcast video, identifies viral moments, and exports upload-ready TikTok / YouTube Shorts (1080×1920, 9:16, burned captions, normalized audio).+AI-powered podcast clip generator. Takes a long-form podcast video, identifies viral moments, and exports upload-ready TikTok / YouTube Shorts (1080x1920, 9:16, burned captions, normalized audio).## Features-- **Auto clip suggestion** — text heuristics + audio energy analysis for smarter scoring-- **Hardware-accelerated encoding** — auto-detects VideoToolbox (Mac), NVENC (NVIDIA), VAAPI, or falls back to CPU-- **Burned-in captions** — word-level timestamps with branded, hormozi, karaoke, or subtle styles-- **Smooth gradient overlay** — alpha-blended PNG overlay (no banding)-- **Smart cropping** — center crop or face detection+- **Auto clip suggestion** — text heuristics + audio energy analysis+- **Burned-in captions** — 4 styles: branded (dark box highlight), hormozi (bold pop-on), karaoke (progressive highlight), subtle (clean bottom text)+- **Hardware-accelerated encoding** — auto-detects VideoToolbox (Mac), NVENC (NVIDIA), VAAPI, or CPU fallback+- **Smart cropping** — center crop or face detection (OpenCV)+- **Knowledge base** — drop `.md` files to give the AI context about your podcast, hosts, and style+- **Asset management** — register logos and videos by name for quick reuse+- **Clip history** — tracks all generated clips to avoid duplicates- **Transcript import** — paste `Speaker (MM:SS)` format, JSON, or drag-and-drop `.txt` files- **Whisper transcription** — auto-transcribe with OpenAI Whisper (tiny → large)-- **CLI mode** — one-command processing: `./podcli process video.mp4 --top 5`- **Preset system** — save and load named configurations per show-- **MCP server** — use as a Claude Desktop / Claude Code tool+- **MCP server** — use as a Claude Desktop / Claude Code tool (7 tools)- **Web UI** — single-page flow: input → suggest → review → export-----+- **CLI mode** — one-command processing: `./podcli process video.mp4 --top 5`## Prerequisites| Tool | Install ||------|---------|-| **Node.js** ≥ 18 | [nodejs.org](https://nodejs.org) |-| **Python** ≥ 3.10 | [python.org](https://python.org) |+| **Node.js** >= 18 | [nodejs.org](https://nodejs.org) |+| **Python** >= 3.10 | [python.org](https://python.org) || **FFmpeg** | `brew install ffmpeg` / `sudo apt install ffmpeg` |-----## Quick Start```bash+git clone <repo-url> podclicd podclichmod +x setup.sh podcli./setup.sh@@ -41,7 +40,8 @@ This will:1. Check system dependencies (Node, Python, FFmpeg)2. Create a Python virtual environment and install packages3. Install Node packages and build TypeScript-4. Launch the web UI at **http://localhost:3847**+4. Create the local `.podcli/` data directory+5. Launch the web UI at **http://localhost:3847**### Setup options@@ -49,216 +49,182 @@ This will:./setup.sh # full install + launch UI./setup.sh --install # install only./setup.sh --ui # launch UI only (skip install)-./setup.sh --mcp # print MCP config+./setup.sh --mcp # print MCP config for Claude```----+## Usage++### Web UI++```bash+./setup.sh --ui+# → http://localhost:3847+```-## Usage (CLI)+1. **Set video** — drag-and-drop or enter a local path+2. **Add transcript** — drag a `.txt` file, paste `Speaker (MM:SS)` text, or auto-transcribe with Whisper+3. **Generate Clips** — analyzes audio energy + transcript to suggest viral moments+4. **Review** — toggle clips on/off, pick caption style, crop mode, logo+5. **Export** — batch-renders selected clips with hardware acceleration+6. **Preview / Download** — watch results inline, download individual clips-Process a video in one command — no UI needed:+### CLI```bash-# Basic: auto-transcribe + suggest top 5 clips + export+# Auto-transcribe + suggest top 5 clips + export./podcli process video.mp4# With existing transcript./podcli process video.mp4 --transcript transcript.txt --top 5-# With a saved preset-./podcli process video.mp4 -t transcript.txt --preset myshow-# Full options./podcli process video.mp4 \--transcript transcript.txt \--top 8 \- --output ./clips \--caption-style branded \--crop center \- --logo ~/logo.png \- --time-adjust -1+ --logo logo.png```### Presets-Save your settings so you don't reconfigure each time:-```bash-# Save a preset-./podcli presets save myshow --caption-style branded --logo ~/logo.png --top 5--# List presets+./podcli presets save myshow --caption-style branded --logo logo.png --top 5./podcli presets list--# Show preset details-./podcli presets show myshow--# Use a preset./podcli process video.mp4 --preset myshow--# Delete a preset-./podcli presets delete myshow-```--Presets are stored in `~/.podcli/presets/`.--### System info--```bash-./podcli info-```--Shows detected encoder (VideoToolbox, NVENC, CPU), platform, and FFmpeg flags.-------## Usage (Web UI)--1. **Set video** — drag-and-drop a video file or enter a local path-2. **Add transcript** — drag a `.txt` file, paste `Speaker (MM:SS)` text, or use Whisper auto-transcription-3. **Click "Generate Clips"** — podcli analyzes audio energy, parses transcript, and suggests clips-4. **Review** — toggle clips on/off, adjust settings (caption style, crop, logo)-5. **Export** — batch-renders all selected clips with hardware acceleration-6. **Preview / Retry / Download** — watch results inline, re-export individual clips--The encoder badge in the header shows which encoder is active (e.g., VIDEOTOOLBOX, NVENC, or CPU).--### Transcript format--```-Speaker Name (00:00)-What they said goes here as plain text.--Another Speaker (00:45)-Their response text here.```-The time offset field (default: -1s) shifts all timestamps to sync with audio.-------## Usage (MCP Server)+### MCP Server (Claude integration)-podcli is also a [Model Context Protocol](https://modelcontextprotocol.io) server — Claude can use it as a tool to create clips programmatically.+podcli is a [Model Context Protocol](https://modelcontextprotocol.io) server — Claude can use it as a tool to create clips through conversation.-### Claude Desktop--Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:+**Claude Desktop** — add to `claude_desktop_config.json`:```json{"mcpServers": {"podcli": {"command": "node",- "args": ["/absolute/path/to/podcli/dist/index.js"],+ "args": ["/path/to/podcli/dist/index.js"],"env": {- "PYTHON_PATH": "/absolute/path/to/podcli/venv/bin/python3"+ "PYTHON_PATH": "/path/to/podcli/venv/bin/python3"}}}}```-### Claude Code+**Claude Code:**```bash-claude mcp add podcli -- node /absolute/path/to/podcli/dist/index.js+claude mcp add podcli -- node /path/to/podcli/dist/index.js```-Or run `./setup.sh --mcp` to get the exact config with your paths filled in.+Run `./setup.sh --mcp` to get the exact config with your paths filled in.-### Available MCP tools+#### MCP Tools| Tool | Description ||------|-------------|-| `transcribe_podcast` | Transcribe audio with Whisper |-| `suggest_clips` | Get AI-suggested clip timestamps |-| `create_clip` | Render a single short clip |-| `batch_clips` | Render multiple clips in one go |+| `transcribe_podcast` | Transcribe audio/video with Whisper |+| `suggest_clips` | Submit clip suggestions (includes duplicate check) |+| `create_clip` | Render a single short-form clip |+| `batch_create_clips` | Render multiple clips in one batch |+| `knowledge_base` | Read/write podcast context files |+| `manage_assets` | Register/list reusable assets (logos, videos) |+| `clip_history` | View previously created clips, check for duplicates |++## Knowledge Base----+Drop `.md` files into `.podcli/knowledge/` to give the AI context about your podcast. The MCP server reads these before every request.++Suggested files:+- `podcast.md` — show name, format, episode structure+- `hosts.md` — host names, speaking styles+- `style.md` — preferred caption style, logo, colors+- `audience.md` — target audience, platform preferences+- `avoid.md` — topics or segments to skip++Manage via the web UI at `/knowledge.html` (drag & drop, inline editor) or through the `knowledge_base` MCP tool.++## Caption Styles++| Style | Look |+|-------|------|+| **branded** | Large bold text, dark box highlight on active word, gradient overlay, optional logo |+| **hormozi** | Bold uppercase pop-on text, yellow active word (Alex Hormozi style) |+| **karaoke** | Full sentence visible, words highlight progressively |+| **subtle** | Clean minimal white text at bottom |## Project Structure```podcli/-├── podcli # CLI entry point (shell wrapper)+├── podcli # CLI entry point├── setup.sh # one-command install & launch├── package.json-├── tsconfig.json├── .env.example│-├── src/ # TypeScript source+├── src/ # TypeScript│ ├── index.ts # MCP server entry (stdio)│ ├── server.ts # MCP tool definitions-│ ├── config/paths.ts # path resolution-│ ├── models/index.ts # shared types+│ ├── config/paths.ts+│ ├── models/index.ts│ ├── handlers/ # MCP tool handlers-│ │ ├── transcribe.handler.ts-│ │ ├── suggest-clips.handler.ts-│ │ ├── create-clip.handler.ts-│ │ └── batch-clips.handler.ts│ ├── services/-│ │ ├── python-executor.ts # spawns Python backend-│ │ └── file-manager.ts+│ │ ├── python-executor.ts+│ │ ├── file-manager.ts+│ │ ├── asset-manager.ts+│ │ ├── clips-history.ts+│ │ ├── knowledge-base.ts+│ │ └── transcript-cache.ts│ └── ui/-│ ├── web-server.ts # Express server + SSE + REST API-│ └── public/index.html # React single-page UI+│ ├── web-server.ts # Express server + API+│ └── public/ # Frontend (React SPA)│-├── backend/ # Python backend+├── backend/ # Python│ ├── main.py # stdin/stdout JSON dispatcher-│ ├── cli.py # CLI entry point (argparse)-│ ├── presets.py # preset save/load system+│ ├── cli.py # CLI entry point+│ ├── presets.py│ ├── requirements.txt-│ ├── services/-│ │ ├── transcription.py # Whisper wrapper-│ │ ├── video_processor.py # FFmpeg clip rendering (hw-accel)-│ │ ├── audio_analyzer.py # RMS energy analysis for scoring-│ │ ├── encoder.py # hardware encoder detection-│ │ ├── clip_generator.py # full pipeline orchestration-│ │ ├── caption_renderer.py # ASS subtitle generation-│ │ └── transcript_parser.py # Speaker (MM:SS) parser+│ ├── services/ # Whisper, FFmpeg, captions, etc.│ └── config/-│ └── caption_styles.py # ASS subtitle style presets+│ └── caption_styles.py│-└── data/ # runtime data (gitignored)- ├── cache/transcripts/- ├── working/uploads/- ├── output/- └── logs/+└── .podcli/ # local data (gitignored)+ ├── assets/ # registered logos, videos+ ├── cache/transcripts/ # cached transcriptions+ ├── history/ # generated clip history+ ├── knowledge/ # .md context files for AI+ ├── output/ # rendered clips+ ├── presets/ # saved configurations+ └── working/ # temp files```-----## ConfigurationCopy `.env.example` to `.env` (setup.sh does this automatically):-```bash-cp .env.example .env-```-| Variable | Default | Description ||----------|---------|-------------|-| `WHISPER_MODEL` | `base` | Whisper model size |+| `WHISPER_MODEL` | `base` | Whisper model size (tiny, base, small, medium, large) || `WHISPER_DEVICE` | `auto` | `cpu`, `cuda`, or `auto` || `PYTHON_PATH` | (venv) | Path to Python binary |-| `PODCLI_HOME` | `~/.podcli` | Data directory |+| `PODCLI_HOME` | `.podcli/` | Data directory (relative to project root) || `FFMPEG_PATH` | `ffmpeg` | Custom FFmpeg path || `LOG_LEVEL` | `info` | Logging verbosity |----+## Transcript Format-## Caption Styles+```+Speaker Name (00:00)+What they said goes here as plain text.-| Style | Look |-|-------|------|-| **branded** | Gradient overlay + boxed word highlight + optional logo |-| **hormozi** | Bold pop-on text (Alex Hormozi style) |-| **karaoke** | Word-by-word highlight |-| **subtle** | Clean, minimal white text |+Another Speaker (00:45)+Their response text here.+```----+The time offset field (default: -1s) shifts all timestamps to sync with audio.## Licensediff --git a/backend/presets.py b/backend/presets.pyindex 147d938..5d72ab6 100644--- a/backend/presets.py+++ b/backend/presets.py@@ -2,15 +2,17 @@Preset/template system for podcli.Save and load named configurations so you don't reconfigure settings-for every episode. Stored as JSON in ~/.podcli/presets/+for every episode. Stored as JSON in .podcli/presets/"""import osimport jsonfrom typing import Optional+# Default to .podcli/ in the project root (two levels up from backend/)+_PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))PRESETS_DIR = os.path.join(- os.environ.get("PODCLI_HOME", os.path.expanduser("~/.podcli")),+ os.environ.get("PODCLI_HOME", os.path.join(_PROJECT_ROOT, ".podcli")),"presets",)diff --git a/package.json b/package.jsonindex 4dd81a1..2979c5c 100644--- a/package.json+++ b/package.json@@ -1,11 +1,31 @@{"name": "podcli","version": "1.0.0",- "description": "podcli — AI-powered podcast clip generator for TikTok/YouTube Shorts",+ "description": "AI-powered podcast clip generator for TikTok/YouTube Shorts. Transcribe, find viral moments, export vertical clips with burned captions.","type": "module",+ "license": "MIT","main": "dist/index.js",+ "bin": {+ "podcli": "./podcli"+ },+ "engines": {+ "node": ">=18.0.0"+ },+ "keywords": [+ "podcast",+ "clips",+ "tiktok",+ "youtube-shorts",+ "reels",+ "video",+ "captions",+ "whisper",+ "mcp",+ "claude",+ "ffmpeg"+ ],"scripts": {- "build": "tsc",+ "build": "tsc && cp -r src/ui/public dist/ui/","start": "node dist/index.js","dev": "tsx src/index.ts","ui": "tsx src/ui/web-server.ts",diff --git a/setup.sh b/setup.shindex 52a7ecc..ef6cac1 100755--- a/setup.sh+++ b/setup.sh@@ -59,8 +59,8 @@ install() {echo ""echo "━━━ [2/6] Creating directories ━━━"- CLIPPER_HOME="${PODCLI_HOME:-$HOME/.podcli}"- mkdir -p "$CLIPPER_HOME"/{cache/transcripts,working,working/uploads,output,logs}+ CLIPPER_HOME="${PODCLI_HOME:-$SCRIPT_DIR/.podcli}"+ mkdir -p "$CLIPPER_HOME"/{cache/transcripts,working,working/uploads,output,logs,assets,history,knowledge}echo " ✓ $CLIPPER_HOME"echo ""diff --git a/src/server.ts b/src/server.tsindex e85fb0a..b2baaad 100644--- a/src/server.ts+++ b/src/server.ts@@ -293,7 +293,7 @@ export function createServer(): McpServer {try {if (action === "read_all") {const text = await kb.readAll();- return { content: [{ type: "text" as const, text: text || "Knowledge base is empty. Add .md files to ~/.podcli/knowledge/" }] };+ return { content: [{ type: "text" as const, text: text || "Knowledge base is empty. Add .md files to .podcli/knowledge/ in the project directory." }] };}if (action === "list") {const files = await kb.listFiles();diff --git a/src/services/asset-manager.ts b/src/services/asset-manager.tsindex e0e956b..3cc7b87 100644--- a/src/services/asset-manager.ts+++ b/src/services/asset-manager.ts@@ -70,7 +70,7 @@ export class AssetManager {return null;}- /** Copy a file into ~/.podcli/assets/ and register it. */+ /** Copy a file into .podcli/assets/ and register it. */async importFile(sourcePath: string, name: string, type: Asset["type"]): Promise<Asset> {await this.ensureDir();const destPath = join(this.assetsDir, basename(sourcePath));