# Podcli

> Open-source CLI and MCP server that turns long-form podcasts into upload-ready vertical clips for TikTok, YouTube Shorts, and Reels. Everything runs locally.

Podcli takes a podcast episode and returns vertical clips with burned-in captions, plus titles, descriptions, and thumbnail briefs. Claude or Codex picks the clips using a knowledge base that encodes your show's voice and rules. No accounts, no uploads, no SaaS. MIT licensed.

## What it does

- Transcribes with Whisper, including word-level timestamps and speaker diarization via pyannote.
- Finds viral moments by feeding the transcript plus your knowledge base to Claude or Codex. Each candidate is scored on four dimensions. The episode database is checked so you don't ship the same clip twice.
- Crops to 1080x1920 with YuNet face detection and per-clip mouth-motion speaker tracking. For 2-person split-screen interviews no audio diarization is needed for camera framing; mouth motion drives the speaker switch. Scene-cut count guards against jittery pans on B-roll-heavy clips. Mixed and single-face layouts fall through to a speaker-aware tracker.
- Burns in captions in four styles: branded, hormozi, karaoke, subtle. Captions are rendered via Remotion. Filler words are stripped. Timing is word-level.
- Exports with hardware encoding: VideoToolbox on Mac, NVENC on NVIDIA, VAAPI on Linux, CPU fallback everywhere.
- Writes 8 title options per clip, descriptions with hooks and SEO keywords, and two-line thumbnail briefs for 16:9 and 9:16.
- Ships as an MCP server with 19 tools. Plugs into Claude Code, Claude Desktop, and Codex.
- Web UI at localhost:3847 includes a live 9:16 phone-frame preview with the chosen caption style overlaid on the source video, plus an optional TikTok-feed wireframe so users see how the clip will sit inside the actual platform before rendering.

## How to use it

Three entry points, same pipeline:

1. CLI: `./podcli process episode.mp4 --top 8`
2. Web UI: `npm run ui`, then open `localhost:3847`. Drag in a video, review clips, pick caption style, export.
3. AI agent: add Podcli to Claude Code, Claude Desktop, or Codex as an MCP server. Say "clip this episode."

PodStack is a companion repo of nine slash commands that cover the content workflow before and after the video engine. It runs in Claude Code, OpenAI Codex, Cursor, or any AI coding tool that reads markdown. `setup.sh` auto-detects your tool and installs commands into `.claude/commands/`, `.codex/prompts/`, or `.cursor/rules/`, and falls back to a generic `commands/` folder for everything else.

Commands: `/plan-episode`, `/process-transcript`, `/generate-titles`, `/generate-descriptions`, `/plan-thumbnails`, `/review-content`, `/produce-shorts`, `/publish-checklist`, `/retro-episode`.

`/produce-shorts` is the master orchestrator. It runs the whole pipeline from transcript to publish-ready bundle. `/review-content` is a fix-first pass that dispatches parallel specialist subagents (voice, banned words, clickbait, standalone, SEO, title). `/retro-episode` appends patterns to `knowledge/13-learnings.md` so the next run reads them automatically.

## Install

```
git clone https://github.com/nmbrthirteen/podcli.git
cd podcli
./setup.sh
```

Requires Node 18 or newer, Python 3.10 or newer, and FFmpeg. Optional: Claude Code or Codex for AI clip suggestion.

## Pipeline (six stages)

1. Transcribe: Whisper + pyannote for word timestamps and speaker labels.
2. Score: Claude or Codex reads the transcript and your knowledge base, returns scored clip candidates.
3. Export: batch render 1080x1920 MP4s with captions and -14 LUFS audio.
4. Titles and descriptions: 8 title options per clip, descriptions with hooks and SEO keywords.
5. Thumbnails: two-line text briefs for podcast (16:9) and shorts (9:16).
6. Publish: pre-upload checklist, first-24-hours ops, day 3-4 optimization.

Stages 1 to 3 are the video engine. Stages 4 to 6 are PodStack slash commands.

## Knowledge base

The `.podcli/knowledge/` folder is 13 markdown files you fill out once. It teaches the AI your show, hosts, voice, title formulas, banned words, thumbnail rules, and episode history. The same files are read by the CLI, the Web UI, and the MCP tools.

## Caption styles

- branded: dark box on the active word, optional logo, safe default.
- hormozi: bold uppercase with a yellow highlight, for clips that need to hit hard.
- karaoke: whole line is visible, words light up as they're spoken, for story clips.
- subtle: small clean text at the bottom, stays out of the way.

Switch with `--caption-style {branded|hormozi|karaoke|subtle}`.

## MCP tools (19)

Transcript: `transcribe_podcast`, `transcribe_start`, `set_video`, `import_transcript`, `parse_transcript`.
Async: `job_status` (poll any transcribe or render job for live progress).
Clips: `suggest_clips`, `modify_clip`, `toggle_clip`, `create_clip`, `batch_create_clips`.
Context: `get_ui_state`, `knowledge_base`, `manage_assets`, `clip_history`, `analyze_energy`.
Config: `manage_presets`, `update_settings`, `list_outputs`.

## Links

- Site: https://podcli.com
- Source: https://github.com/nmbrthirteen/podcli
- PodStack slash commands: https://github.com/nmbrthirteen/podstack
- License: MIT
- Author: Nika Siradze (https://nikusha.com)

## FAQ

Q: Does Podcli upload my files anywhere?
A: No. Transcription, clip picking, cropping, and export happen on your machine. The only network calls are to the Claude or Codex API when you ask for AI clip suggestions, and those are optional.

Q: Do I need a GPU?
A: No. Hardware encoders are used when available but the CPU fallback works on any machine.

Q: Can I use a transcript I already have?
A: Yes. Use `--transcript file.txt` or the `import_transcript` MCP tool.

Q: Can Podcli write YouTube metadata too?
A: Yes. `/generate-titles` produces 8 title options per clip. `/generate-descriptions` writes descriptions with hooks, hashtags, and SEO keywords you can paste in.

Q: What license is Podcli under?
A: MIT.