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
feat: add Codex CLI fallback, update README for deep PodStack integration
Nika Siradze6173a25da620
diff --git a/README.md b/README.mdindex 4e1706c..70ad51a 100644--- a/README.md+++ b/README.md@@ -27,7 +27,7 @@ Publish with optimization checklist ← PodStacReview performance ← PodStack```-The first half is **video processing** — podcli's core engine. The second half is **content workflow** — powered by [PodStack](https://github.com/nmbrthirteen/podstack), a set of Claude Code slash commands that ship with podcli.+The first half is **video processing** — podcli's core engine. The second half is **content workflow** — powered by [PodStack](https://github.com/nmbrthirteen/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.---@@ -80,7 +80,7 @@ Run `/publish-checklist` when uploading. A week later, run `/retro-episode` with| | Video Engine (podcli core) | Content Workflow (PodStack) ||---|---|---|| **What** | Transcription, clip detection, rendering | Titles, descriptions, thumbnails, publishing |-| **How** | Python + FFmpeg + Whisper + OpenCV + Claude | Claude Code slash commands |+| **How** | Python + FFmpeg + Whisper + OpenCV + Claude/Codex | Claude Code slash commands || **Interface** | Web UI, CLI, MCP tools | `/slash-commands` in Claude Code || **Output** | `.mp4` files ready to upload | Content packages ready to paste into YouTube |@@ -91,7 +91,7 @@ Both halves share the same **knowledge base** (`.podcli/knowledge/`) — your sh## Features### Video Processing-- **AI clip suggestion** — Claude-powered moment detection with knowledge base context, multi-cut segments, 4-dimension scoring+- **AI clip suggestion** — Claude/Codex-powered moment detection with knowledge base context, multi-cut segments, 4-dimension scoring- **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@@ -129,6 +129,7 @@ Both halves share the same **knowledge base** (`.podcli/knowledge/`) — your sh| **Python** >= 3.10 | [python.org](https://python.org) || **FFmpeg** | `brew install ffmpeg` / `sudo apt install ffmpeg` || **Claude Code** (optional) | [docs.anthropic.com](https://docs.anthropic.com/en/docs/claude-code) — needed for PodStack slash commands |+| **Codex** (optional) | [openai.com/codex](https://openai.com/index/introducing-codex/) — alternative AI engine for clip suggestion (auto-detected if Claude is unavailable) |## Quick Start@@ -225,7 +226,7 @@ Or just paste a transcript — Claude auto-detects the input and runs the right## 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 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:diff --git a/backend/services/claude_suggest.py b/backend/services/claude_suggest.pyindex 3a13516..a66dcac 100644--- a/backend/services/claude_suggest.py+++ b/backend/services/claude_suggest.py@@ -1,10 +1,10 @@"""-Clip suggestion via Claude Code.+Clip suggestion via AI CLI (Claude Code or Codex).-Delegates moment selection to Claude, which uses the PodStack knowledge base+Delegates moment selection to an AI CLI, which uses the PodStack knowledge base(.podcli/knowledge/) and CLAUDE.md for context-aware clip extraction.-Falls back to heuristic scoring if Claude is unavailable.+Priority: Claude Code → Codex → heuristic fallback."""import json@@ -15,28 +15,47 @@ import tempfilefrom typing import Optional, Callable-def _find_claude() -> Optional[str]:- """Find the claude CLI binary."""- # Check common locations- for path in [- os.path.expanduser("~/.local/bin/claude"),- "/usr/local/bin/claude",- "/opt/homebrew/bin/claude",- ]:+def _find_cli(name: str, extra_paths: list[str] = None) -> Optional[str]:+ """Find a CLI binary by name. Checks extra_paths first, then PATH."""+ for path in (extra_paths or []):if os.path.exists(path):return path-- # Check PATHtry:- result = subprocess.run(["which", "claude"], capture_output=True, text=True, timeout=5)+ result = subprocess.run(["which", name], capture_output=True, text=True, timeout=5)if result.returncode == 0 and result.stdout.strip():return result.stdout.strip()except Exception:pass-return None+def _find_ai_cli() -> tuple[Optional[str], str]:+ """+ Find the best available AI CLI.++ Returns (path, engine) where engine is "claude" or "codex".+ Returns (None, "") if neither is available.+ """+ # Prefer Claude Code+ claude = _find_cli("claude", [+ os.path.expanduser("~/.local/bin/claude"),+ "/usr/local/bin/claude",+ "/opt/homebrew/bin/claude",+ ])+ if claude:+ return claude, "claude"++ # Fall back to Codex+ codex = _find_cli("codex", [+ "/usr/local/bin/codex",+ "/opt/homebrew/bin/codex",+ ])+ if codex:+ return codex, "codex"++ return None, ""++def _load_existing_shorts(episodes_path: str) -> list[str]:"""Extract existing short titles from episode database to avoid duplicates."""if not os.path.exists(episodes_path):@@ -195,16 +214,18 @@ def suggest_with_claude(progress_callback: Optional[Callable[[int, str], None]] = None,) -> Optional[list[dict]]:"""- Use Claude Code to extract the best clip moments from transcript segments.+ Use an AI CLI (Claude Code or Codex) to extract the best clip moments.- Returns list of clip dicts or None if Claude is unavailable.+ Tries Claude Code first, falls back to Codex. Returns None if neither+ is available."""- claude_path = _find_claude()- if not claude_path:+ cli_path, engine = _find_ai_cli()+ if not cli_path:return Noneif progress_callback:- progress_callback(0, "Preparing transcript for Claude...")+ label = "Claude" if engine == "claude" else "Codex"+ progress_callback(0, f"Preparing transcript for {label}...")# Build transcript text from segmentslines = []@@ -234,27 +255,57 @@ def suggest_with_claude(prompt_file = f.nameif progress_callback:- progress_callback(20, "Asking Claude to analyze transcript...")+ label = "Claude" if engine == "claude" else "Codex"+ progress_callback(20, f"Asking {label} to analyze transcript...")try:- # Pipe prompt via stdin — avoids shell escaping and arg size limits- # Run from the podcli project dir so it picks up CLAUDE.md + knowledge base- result = subprocess.run(- f'cat "{prompt_file}" | "{claude_path}" --print -p -',- capture_output=True,- text=True,- cwd=project_dir,- timeout=300, # 5 min max- shell=True,- )+ # Run the AI CLI to analyze the transcript+ if engine == "codex":+ # Codex: use `codex exec` with --output-last-message to capture response+ output_file = prompt_file + ".out"+ result = subprocess.run(+ [+ cli_path, "exec",+ "--full-auto",+ "-o", output_file,+ prompt,+ ],+ capture_output=True,+ text=True,+ cwd=project_dir,+ timeout=300,+ )+ # Read response from output file+ if os.path.exists(output_file):+ with open(output_file) as f:+ result = subprocess.CompletedProcess(+ args=result.args,+ returncode=result.returncode,+ stdout=f.read(),+ stderr=result.stderr,+ )+ try:+ os.unlink(output_file)+ except Exception:+ pass+ else:+ # Claude: pipe prompt via stdin with --print mode+ result = subprocess.run(+ f'cat "{prompt_file}" | "{cli_path}" --print -p -',+ capture_output=True,+ text=True,+ cwd=project_dir,+ timeout=300,+ shell=True,+ )if result.returncode != 0:if progress_callback:- progress_callback(0, f"Claude returned error: {result.stderr[:200]}")+ progress_callback(0, f"{label} returned error: {result.stderr[:200]}")return Noneif progress_callback:- progress_callback(80, "Parsing Claude's suggestions...")+ progress_callback(80, f"Parsing {label}'s suggestions...")# Parse JSON from Claude's responseresponse = result.stdout.strip()@@ -348,21 +399,21 @@ def suggest_with_claude(normalized.sort(key=lambda x: x["start_second"])if progress_callback:- progress_callback(100, f"Claude suggested {len(normalized)} clips")+ progress_callback(100, f"{label} suggested {len(normalized)} clips")return normalizedexcept json.JSONDecodeError as e:if progress_callback:- progress_callback(0, f"Could not parse Claude's response as JSON: {e}")+ progress_callback(0, f"Could not parse {label}'s response as JSON: {e}")return Noneexcept subprocess.TimeoutExpired:if progress_callback:- progress_callback(0, "Claude timed out (5 min limit)")+ progress_callback(0, f"{label} timed out (5 min limit)")return Noneexcept Exception as e:if progress_callback:- progress_callback(0, f"Claude error: {e}")+ progress_callback(0, f"{label} error: {e}")return Nonefinally:# Clean up temp filediff --git a/src/ui/web-server.ts b/src/ui/web-server.tsindex 5b9219b..39bb136 100644--- a/src/ui/web-server.ts+++ b/src/ui/web-server.ts@@ -1203,24 +1203,31 @@ app.post("/api/generate-prompt", (req, res) => {res.json({ prompt, action, context: ctx });});-// --- Claude-powered clip suggestion (same as CLI) ---+// --- AI-powered clip suggestion (Claude Code or Codex) ---app.post("/api/claude-suggest", async (req, res) => {const { top_n = 5 } = req.body;- // Find claude binary+ // Find AI CLI: prefer Claude, fall back to Codexconst homedir = require("os").homedir();const claudeCandidates = [join(homedir, ".local", "bin", "claude"),"/usr/local/bin/claude","/opt/homebrew/bin/claude",];+ const codexCandidates = [+ "/usr/local/bin/codex",+ "/opt/homebrew/bin/codex",+ ];const claudePath = claudeCandidates.find((p) => existsSync(p));+ const codexPath = !claudePath ? codexCandidates.find((p) => existsSync(p)) : undefined;+ const aiPath = claudePath || codexPath;+ const engine: "claude" | "codex" = claudePath ? "claude" : "codex";- if (!claudePath) {+ if (!aiPath) {res.json({- error: "Claude Code not found",- message: "Install Claude Code: https://docs.anthropic.com/en/docs/claude-code",+ error: "No AI CLI found (Claude Code or Codex)",+ message: "Install Claude Code (https://docs.anthropic.com/en/docs/claude-code) or Codex (https://openai.com/index/introducing-codex/)",fallback: "clipboard",clips: [],});@@ -1340,21 +1347,28 @@ ${transcriptText}`;try {const { execSync } = require("child_process");- const result = execSync(- `cat "${tmpFile}" | "${claudePath}" --print -p -`,- {- cwd: process.cwd(),- timeout: 300_000,- maxBuffer: 10 * 1024 * 1024,- encoding: "utf-8",- }- );+ let result: string;++ if (engine === "codex") {+ const outFile = tmpFile + ".out";+ execSync(+ `"${aiPath}" exec --full-auto -o "${outFile}" "$(cat "${tmpFile}")"`,+ { cwd: process.cwd(), timeout: 300_000, maxBuffer: 10 * 1024 * 1024, encoding: "utf-8" }+ );+ result = existsSync(outFile) ? readFileSync(outFile, "utf-8") : "";+ try { require("fs").unlinkSync(outFile); } catch {}+ } else {+ result = execSync(+ `cat "${tmpFile}" | "${aiPath}" --print -p -`,+ { cwd: process.cwd(), timeout: 300_000, maxBuffer: 10 * 1024 * 1024, encoding: "utf-8" }+ );+ }// Parse JSON from responseconst jsonStart = result.indexOf("{");const jsonEnd = result.lastIndexOf("}") + 1;if (jsonStart < 0 || jsonEnd <= jsonStart) {- res.status(500).json({ error: "Claude did not return valid JSON" });+ res.status(500).json({ error: `${engine === "claude" ? "Claude" : "Codex"} did not return valid JSON` });return;}@@ -1402,9 +1416,10 @@ ${transcriptText}`;broadcastSSE("state-sync", uiState);}- res.json({ clips, source: "claude" });+ res.json({ clips, source: engine });} catch (err: any) {- res.status(500).json({ error: `Claude failed: ${err.message?.substring(0, 200)}` });+ const label = engine === "claude" ? "Claude" : "Codex";+ res.status(500).json({ error: `${label} failed: ${err.message?.substring(0, 200)}` });} finally {try { require("fs").unlinkSync(tmpFile); } catch {}}