Podcli

Open-source AI podcast clipper.
Generate short clips in 9:16, 16:9, or 1:1 with face tracking and burned-in captions. CLI, MCP server, and web app.

podcli.com · Quick start · MCP · Features

_{▶ Watch with sound on X}

podcli process episode.mp4

One command transcribes, picks the best moments, crops to the face, and burns captions in. Nothing leaves your machine.

What It Does

podcli takes a long-form podcast and turns it into a complete content operation:

Record episode
    ↓
Transcribe (Whisper, speaker detection)
    ↓
Find viral moments (Claude AI + audio energy + knowledge base)
    ↓
Render clips (9:16, 16:9, or 1:1, captions, smart crop, normalized audio)
    ↓
Generate content package (titles, descriptions, thumbnails, SEO)    ← PodStack
    ↓
Publish with optimization checklist                                  ← PodStack
    ↓
Review performance                                                   ← PodStack

The first half is video processing — podcli's core engine. The second half is content workflow — powered by PodStack, a set of Claude Code slash commands that ship with podcli. Both halves are deeply integrated: the clip suggestion engine reads from your PodStack knowledge base, uses your title formulas and voice rules, checks the episode database for duplicates, and outputs MCP-aligned fields that flow through to export.

How It Works (From a User's Perspective)

1. Drop in your episode

podcli            # then choose "Open Web UI"
# → http://localhost:3847

Drag your video into the Web UI, or use the CLI:

podcli process episode.mp4

2. Get clips automatically

podcli uses Claude to analyze your transcript against your show's knowledge base, finding the most viral moments. It scores each one on 4 dimensions, suggests clips with multi-cut segments (cutting out filler), and lets you toggle them on/off before rendering.

Clips come out as upload-ready Shorts: 1080x1920, 9:16 vertical, with burned-in captions, normalized audio, and your logo.

3. Generate the full content package

Open the project in Claude Code and run:

/produce-shorts

This runs the PodStack pipeline — a gstack-style workflow that gives you:

• 8-15 scored moments with timestamps, categories, and reasoning
• 8 title options per clip following your show's title spec (verified against 6 quality gates)
• Ready-to-paste descriptions with hooks, guest attribution, hashtags, SEO keywords
• Thumbnail briefs for both podcast (16:9) and shorts (9:16) formats
• Brand review that catches banned words, voice violations, and weak hooks
• Publish checklist covering pre-upload, at-publish, first-24-hours, and day 3-4 optimization

4. Publish and track

Run /publish-checklist when uploading. A week later, run /retro-episode with your YouTube Studio stats to see what worked and what to improve.

The Two Halves

Both halves share the same knowledge base (.podcli/knowledge/) — your show's brand, voice, title formulas, episode database, and style guide. Set it up once, everything stays on-brand.

Features

Video Processing

• AI clip suggestion — Claude/Codex-powered moment detection with knowledge base context, multi-cut segments, 4-dimension scoring
• Multi-format output — vertical 9:16, horizontal 16:9, or square 1:1 (--format, the studio selector, or the create_clip MCP tool); captions scale to each canvas. Defaults to vertical.
• Import from a URL — paste a YouTube or direct video link in the studio to download and process it
• Face tracking — YuNet face detection, exponential-smoothing camera, split-screen support, speaker-aware tracking with snap cooldown
• Burned-in captions — 4 styles: branded, hormozi, karaoke, subtle
• Hardware-accelerated encoding — VideoToolbox (Mac), NVENC (NVIDIA), VAAPI, CPU fallback
• Smart cropping — center crop or face tracking (handles split-screen, Riverside-style mixed layouts)
• Multi-segment clips — automatically cuts out filler, long pauses, and tangents
• Whisper transcription — auto-transcribe with speaker detection (tiny → large)
• Transcript import — paste Speaker (MM:SS), JSON, drag-drop .txt / .srt / .vtt

Content Workflow (PodStack)

• /process-transcript — extract and score best moments from any transcript
• /generate-titles — 8 titles per clip with 6-point verification checklist
• /generate-descriptions — descriptions + hashtags + SEO keywords
• /plan-thumbnails — thumbnail text + designer briefs for both formats
• /review-content — paranoid brand check (banned words, voice, title rules)
• /produce-shorts — full pipeline: transcript → publish-ready package
• /publish-checklist — pre/post-publish optimization
• /retro-episode — performance analysis after publishing

Infrastructure

• Knowledge base — .md files that teach the AI your brand, voice, and style
• Asset management — register logos and videos for quick reuse
• Clip history — tracks everything to avoid duplicates
• Preset system — save named configurations per show
• Content studio — generate titles, descriptions, tags, and hashtags in the web UI; regenerate any section with your own guidance, or ask for anything custom
• MCP server — 17 tools for Claude Desktop / Claude Code integration
• Web UI — single-page flow at localhost:3847
• CLI — one-command processing: podcli process episode.mp4

Knowledge Base

The knowledge base is what makes podcli understand your show. Drop .md files into .podcli/knowledge/ and both the video engine and content workflow use them. The clip suggestion engine reads 8 of these files (prioritized by relevance), checks the episode database for duplicate avoidance, and applies your voice rules and title formulas when generating suggestions.

PodStack ships with 13 starter templates that you fill in with your show's details:

Manage via the web UI at /knowledge.html (drag & drop, inline editor) or through the knowledge_base MCP tool.

MCP Server (Claude Integration)

podcli is a Model Context Protocol server — Claude can use it as a tool to create clips through conversation.

Claude Code — register the bundled MCP server in one command:

podcli mcp install

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "podcli": {
      "command": "podcli",
      "args": ["mcp"]
    }
  }
}

MCP Tools

Caption Styles

Project Structure

podcli/
├── cli/                      # Go launcher (native binary, provisioning, self-update)
├── install.sh / install.ps1 # node-less installers
├── setup.sh                  # dev environment setup (venv + npm)
├── package.json
├── CLAUDE.md                 # PodStack master config
│
├── .claude/commands/         # PodStack slash commands
│   ├── process-transcript.md
│   ├── generate-titles.md
│   ├── generate-descriptions.md
│   ├── plan-thumbnails.md
│   ├── review-content.md
│   ├── produce-shorts.md
│   ├── publish-checklist.md
│   └── retro-episode.md
│
├── src/                      # TypeScript
│   ├── index.ts              # MCP server entry (stdio)
│   ├── server.ts             # MCP tool definitions
│   ├── config/paths.ts
│   ├── models/index.ts
│   ├── handlers/             # MCP tool handlers
│   ├── services/
│   │   ├── python-executor.ts
│   │   ├── file-manager.ts
│   │   ├── asset-manager.ts
│   │   ├── clips-history.ts
│   │   ├── knowledge-base.ts
│   │   └── transcript-cache.ts
│   └── ui/
│       ├── web-server.ts     # Express server + API
│       └── public/           # Frontend (React SPA)
│
├── backend/                  # Python
│   ├── main.py               # stdin/stdout JSON dispatcher
│   ├── cli.py                # CLI entry point
│   ├── presets.py
│   ├── requirements.txt
│   ├── models/               # ML model files
│   │   └── face_detection_yunet_2023mar.onnx
│   ├── services/             # Whisper, FFmpeg, captions, face tracking, etc.
│   │   ├── face_detector.py  # shared YuNet face detector
│   │   └── ...
│   └── config/
│       └── caption_styles.py
│
├── .podcli/                  # config home (gitignored) — knowledge, presets, assets
│   ├── knowledge/
│   ├── assets/
│   ├── presets/
│   └── history/
└── data/                     # runtime data (gitignored) — cache, output, working
    ├── cache/                # CLI transcription cache + remotion bundle
    │   └── transcripts/      # MCP/UI transcript cache
    ├── output/               # rendered clips
    └── working/              # temp uploads and task dirs

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.

Install

No prerequisites — the install fetches a self-contained binary, and the first run provisions everything it needs (Python, Node, FFmpeg, whisper.cpp, models) into a managed directory. You don't need Go, Node, Python, or FFmpeg installed.

macOS / Linux

curl -fsSL https://podcli.com/install.sh | sh

Windows (PowerShell)

irm https://podcli.com/install.ps1 | iex

Then just run it — the first launch sets itself up:

podcli                       # interactive menu (and Web UI)
podcli process episode.mp4   # transcribe + export clips

Supported platforms: macOS (Apple Silicon), Linux (x64 / arm64), Windows (x64). Intel Macs are coming in a follow-up release.

To uninstall, remove podcli and everything under its managed folder — runtime, models, cache, and your config, knowledge, presets, assets, and history:

podcli uninstall

This removes all managed data by default. Run podcli uninstall --dry-run first to see exactly what will be removed, and back up the folder if you want to keep any of it. (--purge is kept as a no-op alias.)

Optional, for AI clip suggestion and the PodStack slash commands: install Claude Code or Codex (auto-detected).

Building from source needs Go 1.23+ (and Node for the studio bundle); see plans/native-cli.md.

Usage

Web UI

podcli            # then choose "Open Web UI"
# → http://localhost:3847

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

CLI

# One command. Auto-transcribes, picks moments, renders clips.
podcli process episode.mp4

With more control:

# Use an existing transcript instead of transcribing
podcli process episode.mp4 --transcript transcript.txt --top 5

# Full options
podcli process episode.mp4 \
  --transcript transcript.txt \
  --top 8 \
  --caption-style branded \
  --crop center \
  --logo logo.png

Presets

podcli presets save myshow --caption-style branded --logo logo.png --top 5
podcli presets list
podcli process video.mp4 --preset myshow

Content Workflow (PodStack)

Open the project in Claude Code, then use slash commands:

# Full pipeline — transcript to publish-ready package
/produce-shorts

# Individual steps
/process-transcript        # extract moments from a transcript
/generate-titles           # get 8 title options for a clip
/generate-descriptions     # get descriptions + hashtags
/plan-thumbnails           # get thumbnail briefs for your designer
/review-content            # brand and quality review
/publish-checklist         # pre/post-publish ops
/retro-episode             # performance analysis

Or just paste a transcript — Claude auto-detects the input and runs the right command.

Configuration

Copy .env.example to .env (setup.sh does this automatically):

Config profiles (multi-show / multi-machine)

Portable bundles zip your config home (not cache or rendered clips):

podcli config export ~/backups/myshow.zip
podcli config import ~/backups/myshow.zip --home ~/.podcli-myshow --activate
podcli config status

Activate a config root without importing: podcli config use ~/.podcli-myshow (writes .podcli-home in the project).

Upgrading from older layouts

Older releases stored transcription cache under project/.podcli/cache/ (now data/cache/) and presets under project/presets/ (now .podcli/presets/). After upgrading, migration runs automatically when legacy files are still present (CLI, Web UI, MCP). To preview or run manually:

podcli config migrate --dry-run   # preview only
podcli config migrate             # apply (same as auto when legacy cache exists)

One source of truth: settings live in config home (PODCLI_HOME or .podcli/, tracked by .podcli-home); heavy/runtime files live under data (PODCLI_DATA or data/). The marker file only points at which config home is active — it does not replace either root.

MCP: manage_config(action=migrate).

Web UI: Config profiles (when npm run ui is running).

See CONTRIBUTING.md for development conventions.

License

AGPL-3.0. See LICENSE.

Need to use Podcli without AGPL terms? A commercial license is available — email siradze@nikusha.me with a one-line description of your use case.