podcli

Show whether Claude Code / Codex CLIs are available for AI-powered clip suggestion and content generation.

Returns configured manual paths (PODCLI_CLAUDE_PATH / PODCLI_CODEX_PATH) and auto-discovered binaries. Use manage_env(action=set, key=PODCLI_CLAUDE_PATH, value=...) to override when detection fails.

Analyze audio energy levels for a video or specific segments. Useful for finding high-energy moments. Defaults to the current UI video and suggestions if not specified.

STEP 3 — Export multiple clips at once as finished vertical shorts.

EASIEST: pass export_selected=true to export all selected clips in one go. Alternative: pass clip_numbers=[1, 3, 5] for specific ones. Everything (video, timestamps, settings) auto-loads from session state.

Pass exactly one of clips, clip_numbers, or export_selected. If several are given, an explicit clips array wins, then export_selected, then clip_numbers.

Each clip gets: 9:16 vertical crop, burned-in captions, normalized audio, H.264 MP4.

View previously created clips to avoid duplicates. Check before creating new clips.

Transcribe the same sample window of a file with two engines and report where their output disagrees, in 20s windows by default. This measures disagreement between the two engines' output, not accuracy against a ground-truth transcript. Neither engine is assumed correct. Writes comparison.json and a self-contained comparison.html (with a sample audio player and per-window seek buttons) to output_dir.

STEP 3 — Export a single clip as a finished vertical short (1080x1920, 9:16).

EASIEST: just pass clip_number (e.g. 3) — everything else auto-loads from session state. Output: H.264 MP4 with burned-in captions, normalized audio (-14 LUFS).

For batch export, use batch_create_clips instead. Caption styles: branded (professional), hormozi (bold/yellow), karaoke (progressive highlight), subtle (minimal). Crop modes: speaker (speaker-aware), face (face tracking), center (fixed center crop). Set keep_caption_overlay=true to retain a ProRes alpha overlay for DaVinci Resolve (export_to_davinci_resolve).

Export podcli shorts as a DaVinci Resolve FCPXML project.

Each short becomes a compound clip with V1 source + V2 ProRes 4444 alpha caption overlay — fully editable in free or Studio Resolve 20.x.

Requires the davinci_resolve integration to be enabled (manage_integrations action=enable name=davinci_resolve).

Read the current podcli session state and get guidance on what to do next. Returns: video path, transcript status, clip suggestions, settings, and workflow next steps.

IMPORTANT: Call this FIRST when starting a new conversation to understand the current state. Clips are numbered #1, #2, etc. Use these numbers with create_clip(clip_number), batch_create_clips(clip_numbers), modify_clip, and toggle_clip.

Set include_transcript=true to analyze transcript content. Returns a compact phrase-grouped markdown view (~10x smaller than raw segments) with speaker attribution, silence gaps, and optional energy peaks — the primary surface for reasoning about clip boundaries.

Import an external transcript (e.g. from a transcription service) into the UI. Skips Whisper entirely. The transcript must include word-level timestamps.

Poll the status of any background job (transcription, clip render, batch export, process_episode). Supports long-polling: pass wait_seconds (1–60) to block until the job changes state or the timeout elapses, whichever comes first. Paces Claude's polling naturally so the spinner doesn't spam and the user sees steady progress text.

Returns { status: 'running'|'done'|'error', progress, message, done, result? }. Use after transcribe_start, process_episode, or batch_create_clips(async_mode: true).

Read or manage the podcli knowledge base. These are .md files that provide context about the podcast (hosts, style, audience, etc). Always read the knowledge base before suggesting or creating clips.

List all rendered clip files in the output directory with file sizes and dates.

Register and manage reusable assets (logos, outros, intros, music, images). Reference them by name in create_clip/manage_reel instead of full paths. One logo/outro/intro/music can be the default, applied automatically when none is passed.

Manage portable config profiles and legacy path migration.

Actions: • status — active config home, cache dir, migration state (default) • migrate — move legacy project/.podcli/cache into data/cache (idempotent) • export — zip the active config home (knowledge, presets, assets, settings) • import — restore a bundle; backs up existing config before overwrite • use — activate a config home path (writes .podcli-home marker)

List, set, or unset global podcli settings stored in .env.

Keys: • HF_TOKEN — HuggingFace token for speaker detection • PODCLI_CLAUDE_PATH — manual path to Claude Code CLI when auto-discovery fails • PODCLI_CODEX_PATH — manual path to Codex CLI when auto-discovery fails

Actions: • list — show all settings, configured values, and AI CLI detection (default) • set — set a key (path must exist for PODCLI_*_PATH keys) • unset — remove a key (falls back to auto-discovery)

List, enable, or disable podcli integrations (editor exporters, platform uploads, productivity tools, AI helpers).

Actions: • list — return all installed integrations with their enabled state (default) • enable — turn an integration on (its tools become callable) • disable — turn an integration off (calls return a disabled error)

State persists at the active config home (integrations.json, gitignored).

Edit a full multicam podcast episode: map every camera and mic file to a person, sync them by audio (with clock-drift correction), auto-cut cameras to whoever is speaking, then render an MP4 or export a Premiere XML / FCPXML timeline that points at the original files. Flow: 'new' (folder or files, people) → check the guessed mapping with 'show' and fix it with 'map' → 'sync' → 'plan' → 'render' or 'export'. 'new' returns the session with guessed roles; calling it again on the same files reopens that edit. 'sync', 'plan' and 'render' start a background job and return job_id: poll job_status, then call 'show'. Mapping fields (people, sources, range_start, range_end, cut_settings, speaker_map, look, removals) apply on 'map', 'sync' and 'plan'; 'render' takes only look and stems. Changing who is in a file or where it sits clears the cut, so run 'plan' again. 'render' skips work when nothing changed and reuses shots it already encoded. Every render checks the finished file (frame count, a full decode, loudness and true peak) and reports outputs.validation; only a broken decode or a picture more than a frame off the cut fails it, the rest are warnings. Other actions: 'list', 'cut' (index, source_id: swap one shot's camera), 'set_cuts' (cuts: replace the whole cut with back-to-back shots), 'activity' (who speaks when, as spans per person), 'previews' (still frames per camera, looks: true adds every color look on every camera), 'preview' (background job: playback proxies, a mic mix and stills, for a browser editor such as podcli cloud), 'delete'. 'cloud' (background job, needs podcli login and Pro: sends previews and the edit to the podcli cloud editor; camera files stay here) and 'pull' (background job: renders the cut made in that editor from the files here). 'export' with review: true writes a review timeline: the whole episode, every camera on its own track under the cut, and each removal left in place, named 'Remove', labelled orange in Premiere and marked with its reason. 'import_timeline' (path) reads an FCP 7 XML timeline edited in Premiere or Resolve back as the cut and removals: deleted stretches become removals, kept ones are restored. With the DaVinci Resolve MCP server connected, import the review timeline into a Resolve project, color the 'Remove' clips, let the editor review, export the timeline as FCP 7 XML, then call 'import_timeline'. Call recordings work too: one file per person becomes a split screen, one gallery recording is split into a camera per tile; Premiere and FCPXML export refuse those layouts for now.

Save, load, list, or delete rendering presets. Presets store caption_style, crop_strategy, logo_path, and outro_path for quick reuse.

Create and iterate on a highlights reel. Detection runs once with action 'new'; after that, edit individual moments fast (longer/shorter/earlier/later/shift/drop/toggle) and rebuild without re-detecting. Pass video_paths (a list) to pool many videos and rank the best moments across all of them. Actions: 'new' (video_path or video_paths, profile, format, top_n, min_dur, max_dur), 'list', 'show' (session_id), 'edit' (session_id, index, op, seconds), 'build' (session_id), 'delete' (session_id).

Show, export, import, or reset the thumbnail template (colors, fonts, frame, box, layout) podcli uses to generate thumbnails. 'show' returns the effective config; 'export' writes it to a file path; 'import' replaces it from a file path; 'reset' reverts to the generic default; 'set_layout' picks the layout: 'single' (one face) or 'pair' (two people from the clip, guest left and host right, for interview clips; falls back to one face when podcli cannot tell two people apart).

Mine a YouTube channel's back catalog for clip-worthy moments without downloading any video. action='list' lists a channel's uploads (title, duration, upload date), flagging ones already mined into clip_history so you don't re-suggest from them. action='mine' fetches one video's existing captions (never the video itself), preferring the original-language track over an auto-translated one, and converts them to podcli's word-level transcript format. Feed the result straight into the suggest_clips flow the same way import_transcript's output is used. Never downloads a full video; that only happens if you separately choose to render a clip from one.

Adjust a suggested clip before exporting. Change timing, title, caption style, or opening hook. Use action='delete' to remove a clip entirely. Reference clips by clip_number (from get_ui_state).

Parse a raw speaker-labeled plain text transcript into word-level timestamps. Input format: 'Speaker (MM:SS)\ntext...\n\nSpeaker2 (MM:SS)\ntext...'. Uses the Python backend to generate accurate word timings.

One-shot episode job: transcribe, rank moments, render clips, write titles/descriptions/tags. Returns { job_id } immediately. Poll with job_status until done; the result is the same JSON podcli process --json prints (clip paths, durations, scores, titles, captions).

Does not require the web studio. For a shortlist without rendering, use rank_clip_candidates instead.

After transcribe_podcast, call this instead of reading the whole transcript. Returns ~20 pre-ranked, sentence-aligned candidates (start/end, duration, score, title, preview). Pick from the list, then submit winners with suggest_clips or render with create_clip.

Uses the cached transcript for video_path. Does not call an AI CLI.

Record per-episode workflow decisions (clip count, clip duration range, caption style, captions on/off, language, whether thumbnails are wanted, delivery target, free-form notes) so later runs against the same video never ask the same question twice. Keyed by the video's path + file size, not by session, so these answers survive a new episode overwriting ui-state.json. Pass only the fields you have an answer for; existing answers are preserved unless explicitly overwritten. get_ui_state lists any fields still unanswered as open questions.

Set the working video file without transcribing. Use this when you'll import a transcript separately. After this, either transcribe_podcast or import a transcript via import_transcript / parse_transcript.

STEP 2 — Submit your clip suggestions after analyzing the transcript.

Before calling this: read the transcript via get_ui_state(include_transcript: true) and identify the best viral moments.

Every suggestion must carry its own context. A clip that opens on an answer whose question stayed behind the cut is rejected: widen start_second so the question is inside the clip.

What it does: Stores your suggestions, assigns clip numbers (#1, #2, etc.), and pushes them to the Web UI for the user to review.

After this: the user reviews in the UI. Then export with batch_create_clips(export_selected: true) or create_clip(clip_number: N).

Select or deselect a suggested clip by clip_number. Selected clips are exported with export_selected.

STEP 1 — Transcribe a podcast video/audio file. This is typically the first tool you call.

What it does: Uses Whisper AI for word-level timestamps, with speaker detection (who said what) on by default. Speaker labels are what let a clip tell a question from an answer, so leave them on for any interview. Pass enable_diarization=false to skip them and save time on a single-speaker recording. Returns: Lightweight metadata only — duration, language, word/segment counts, speaker summary, and packed_ready flag. The actual transcript body is NOT returned here (it would be 500KB+ for a typical episode). Read the content via get_ui_state(include_transcript: true) which returns a compact phrase-grouped markdown view (~10x smaller than raw segments). Caching: Results are cached by file hash — same file won't be re-transcribed. Supported formats: MP4, MOV, WebM, MKV, MP3, WAV.

After transcription: call rank_clip_candidates(video_path) for a ~20-clip shortlist (do not read the whole transcript unless you need to rewrite a range). Or call process_episode(video_path) to transcribe, rank, and render in one job.

Start transcription as a background job and return a job_id immediately. Use this instead of transcribe_podcast for long files so you can narrate progress to the user while it runs (a 60-min episode takes 15–25 min).

Flow: call transcribe_start(file_path) → emit status text to user → call job_status(job_id, wait_seconds: 30) in a loop until done → then read the packed transcript via get_ui_state(include_transcript: true).

Requires the Web UI to be running (npm run ui). Returns { job_id, cached, status, estimate_minutes }.

Update rendering settings (caption style, crop strategy, logo, outro) in the Web UI.