pidcast

Tip

✨ A URL or audio file in, an Obsidian-ready Markdown transcript with smart LLM analysis out.

pidcast is a single-shot CLI for podcast and YouTube transcription with optional LLM analysis. Built for engineers and knowledge-workers who want searchable, source-attributed notes out of long-form audio — without leaving the terminal. Whisper.cpp or ElevenLabs handles speech-to-text; Groq or Claude handles the analysis; output lands as Markdown with YAML front matter, ready for Obsidian.

Note

📦 Installation · 🔧 Setup · ⚡ Usage · 🎙️ Library · 🗣️ Speaker diarization · 📊 Evals · 📚 Documentation

🎬 Demo

$ uv run pidcast "https://youtube.com/watch?v=VIDEO_ID"
[1/5] Downloading audio ............................. ok (3m 21s)
[2/5] Normalizing to 16kHz mono WAV ................. ok
[3/5] Transcribing (whisper.cpp, large-v3-turbo) .... ok (4m 02s)
[4/5] Analyzing (groq, llama-3.3-70b-versatile) ..... ok
[5/5] Writing Markdown .............................. ok
→ 2026-05-11_Episode_Title.md  (12,847 words, 3 speakers)

📦 Installation

Requirements: Python ≥ 3.10, ffmpeg, and (for local transcription) a built whisper.cpp.

# 1. Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Clone and sync
git clone https://github.com/kintecus/pidcast && cd pidcast && uv sync

# 3. Optional: ffmpeg
brew install ffmpeg              # macOS — or: apt install ffmpeg

🔧 Setup

uv run pidcast setup

The wizard configures:

• Transcription backend — local whisper.cpp (private, free) or ElevenLabs Scribe v2 (cloud, faster)
• API keys — Groq for analysis, optionally ElevenLabs for cloud transcription, optionally HuggingFace for diarization
• Output paths — transcript directory and optional Obsidian vault

At any time, check the live state of your tooling and env:

uv run pidcast doctor

Configuration is read from .env (see .env.example). Full variable reference: docs/development-guide.md.

⚡ Usage

# YouTube, Apple Podcasts URL, or local audio file
uv run pidcast "https://youtube.com/watch?v=VIDEO_ID"
uv run pidcast "https://podcasts.apple.com/.../id123?i=456"
uv run pidcast "/path/to/audio.mp3"

# Pick a transcription provider
uv run pidcast "URL" --transcription-provider elevenlabs

# Transcription only by default. Opt into LLM analysis with --analyze,
# or by passing any analysis flag (-a, --provider, --claude-model, -m, --save, -o)
uv run pidcast "URL" --analyze
uv run pidcast "URL" -a key_points
uv run pidcast "URL" --provider claude --claude-model opus

# Custom front matter tags (overrides auto-inferred source tags)
uv run pidcast "/path/to/meeting.mp3" --tags meeting,standup,weekly

# Strip silence before decoding to curb whisper hallucinations (needs a Silero VAD model)
uv run pidcast "URL" --vad
uv run pidcast "URL" --vad --vad-threshold 0.6   # raise the speech-probability cutoff

# Test settings on a 2-minute slice before committing to a long run
uv run pidcast "URL" --test

# Reveal the finished file in Finder when the run completes
uv run pidcast "URL" --reveal

# Reuse an existing transcript
uv run pidcast analyze transcript.md          # re-analyze
uv run pidcast diarize transcript.md          # retry diarization

# Ukrainian Discord recap (Claude CLI): lists the episode's stories, you pick, it writes <= 1900 chars
uv run pidcast discord transcript.md                       # play format, Opus, copies to clipboard
uv run pidcast discord transcript.md --style digest        # prose digest instead of a play
uv run pidcast discord transcript.md --pick 3,9 --model sonnet

# Knowledge notes for long episodes (Claude CLI): maps the themes, you check the ones to go deep on,
# it writes an executive summary + a detailed section per checked theme (the rest get one line)
uv run pidcast notes transcript.md                         # saved next to the transcript, Opus
uv run pidcast notes transcript.md -o --focus "eval infra"  # into the Obsidian vault, with a steer
uv run pidcast notes transcript.md --pick 4,2 --model sonnet

# Discovery
uv run pidcast list analyses         # list analysis types
uv run pidcast list models           # list LLM models
uv run pidcast list whisper-models   # list Whisper models
uv run pidcast list presets          # list presets
uv run pidcast info                  # show where transcripts, audio, logs, and run history live

pidcast is verb-first: bare pidcast "URL" is shorthand for pidcast transcribe "URL". Run pidcast --help for the full command list, or pidcast <command> --help for a command's flags.

By default, transcripts, kept audio, logs, and the run history live under the XDG data dir (~/.local/share/pidcast/, or $XDG_DATA_HOME/pidcast/) — not in the repo. Override the whole tree with PIDCAST_DATA_DIR, set a fixed transcript directory with --output-dir or the output_dir key in ~/.config/pidcast/config.yaml, and run pidcast info to see what resolves.

--reveal opens the finished file in the OS file manager (selected in Finder on macOS, in Explorer on Windows; Linux opens the containing folder). It picks the analysis file when analysis ran — including the Obsidian vault copy under -o — and falls back to the transcript. Make it the default with reveal_on_success: true in ~/.config/pidcast/config.yaml, and suppress it for one run with --no-reveal. Non-interactive runs never reveal, and lib sync/lib process ignore the config default (pass --reveal explicitly there; you still get at most one window per run).

Available analysis types: executive_summary (default), summary, key_points, action_items, comprehensive. Every type ends with a Shareable Brief — a punchy headline (≤ 15 words) plus a 3–5 sentence quick-take suitable for sending to a friend.

Claude model aliases: sonnet (claude-sonnet-4-6, default), opus (claude-opus-4-6), haiku (claude-haiku-4-5).

Whisper anti-hallucination: on the whisper path, --suppress-nst is ON by default (suppresses non-speech tokens), and repeated identical lines are collapsed in post-processing. For long files with stretches of silence, add --vad to strip silence before decoding — it needs a Silero VAD model pointed at by WHISPER_VAD_MODEL in .env (no-ops with a warning if none is found; pidcast doctor reports its status). Tune the speech-probability cutoff with --vad-threshold (default 0.50).

🎙️ Library

Subscribe to podcast feeds and process new episodes in one command.

# Add a show by name (searches Apple Podcasts + iTunes) or by RSS URL
uv run pidcast lib add "99% Invisible"
uv run pidcast lib add "https://feeds.example.com/podcast.xml"

# Inspect
uv run pidcast lib list                    # all shows
uv run pidcast lib show 1 --episodes 10    # recent episodes for show ID 1

# Process one episode
uv run pidcast lib process "99% Invisible" --latest
uv run pidcast lib process "99% Invisible" --match "episode title"

# Process all new episodes across the library
uv run pidcast lib sync

# Roll up recent processing history into a digest
uv run pidcast lib digest

Library file: ~/.config/pidcast/library.yaml (macOS/Linux) or %APPDATA%\pidcast\library.yaml (Windows). Human-readable, hand-editable.

🗣️ Speaker diarization

Identify who said what. Two paths:

• whisper + pyannote (--diarize with --transcription-provider whisper): runs locally, needs a HuggingFace token to download the model on first use. Install with uv pip install 'pidcast[diarize]', set HUGGINGFACE_TOKEN in .env, and accept the license at pyannote/speaker-diarization-3.1 and pyannote/segmentation-3.0.
• ElevenLabs built-in (--diarize with --transcription-provider elevenlabs): no extra setup, runs as part of the transcription API call.

uv run pidcast "URL" --diarize

Output adds **Speaker 1** / **Speaker 2** labels inline and front matter fields speaker_count and diarized: true.

📊 Evals

Compare provider output quality on the same transcript, judged by Claude Opus:

uv run pidcast-eval --compare groq,claude --transcript-file transcript.txt --title "Episode"
uv run pidcast-eval --run-matrix           # all prompt × model × reference combos

Reports land under the data dir, in evals/comparisons/ (run pidcast info to resolve it; default ~/.local/share/pidcast/evals/comparisons/). See docs/development-guide.md for the full eval matrix flags.

📚 Documentation

• Architecture — system structure, data flow, component boundaries
• Development guide — env setup, testing, CI, conventions
• Architecture Decision Records — why-we-chose decisions
• CLAUDE.md — Claude Code agent instructions for this repo