dk-transcribe-summarize

name: dk-transcribe-summarize description: > Transcribe audio files or YouTube videos via subtitles or OpenRouter's multimodal API, generate 100-word and 400-word summaries using cloud models (OpenRouter) with local LLM fallback (LM Studio), and output the results as PDF, HTML, and Markdown files. Supports hybrid subtitle-first transcription, custom prompts, and automatic fallback across multiple models. Triggers on speech-to-text, audio transcription, YouTube download, or creating transcript documents with summaries. license: MIT compatibility: > Requires: ffmpeg, uv, Node.js (for yt-dlp JS challenge solving), Brave browser with YouTube login cookies, LM Studio (lms CLI) with a loaded model (fallback summarization only), OPENROUTER_API_KEY env var for transcription and cloud summarization. Python deps (auto-resolved by uv): requests, yt-dlp, fpdf2, mistune, webvtt-py, langdetect, mlx-whisper. metadata: author: dushyantkhosla model-default: gemma-4-e4b-it output-dir: /Users/dush/Code/transcribed// formats: pdf, html, md

Audio Transcribe & Summarize (PDF, HTML & Markdown)

Overview

Modular Python CLI tool (scripts/) that:

1. For YouTube URLs, tries subtitles first (hybrid mode) — downloads auto-captions, validates quality (WPM, repeated phrases, language detection), and uses them if good; falls back to audio transcription otherwise
2. Downloads audio from YouTube (or accepts a local mp3/m4a/wav file) when subtitles unavailable or --method audio
3. Transcribes audio via OpenRouter's multimodal API (xiaomi/mimo-v2.5) using the input_audio content type
4. Automatically chunks long audio (>10 min) into 10-min segments compressed to 16 kbps mono MP3 for reliable cloud transcription
5. Falls back through transcription models (MiMo → Gemini Flash Lite → Gemini Flash → mlx-whisper local), each with 1 retry (each attempt has 5 internal retries with linear backoff)
6. Generates ~100-word and ~400-word summaries — cloud-first via OpenRouter (same model cascade), falling back to local LLM via LM Studio (default: gemma-4-e4b-it) only if all cloud models fail or API key is unset
7. Supports custom prompts (--prompt) for single-summary mode (action items, key takeaways, etc.)
8. Verifies summaries are free of chain-of-thought contamination; retries with a strict prompt if detected
9. Writes three formats — PDF, HTML, and Markdown — to transcribed/<YYYY-MM-DD>/. PDF and HTML contain summaries only; Markdown includes the full transcript
10. Output filenames use {channel}-{title} format when channel metadata is available

When to Use

• Transcribing audio files (mp3, m4a, wav) to text
• Downloading and transcribing YouTube videos
• Generating summary documents from audio content
• Creating PDF/HTML/Markdown reports with transcripts and summaries
• Working offline for summarization (local LLM, no API cost)

Do NOT use for:

• Real-time transcription (batch/offline only)
• Videos longer than ~2 hours (API payload limits)
• Speaker diarization (no speaker labels)

Quick Reference

Script

Reusable tool: scripts/transcribe_pdf.py

cd /path/to/skill
uv run scripts/transcribe_pdf.py

Coding Standards

All Python scripts MUST use PEP 723 inline metadata

Every executable Python script in this skill must:

• Start with #!/usr/bin/env -S uv run --script shebang
• Include a # /// script block with requires-python and dependencies list
• Be runnable via uv run <script.py> without any pre-existing virtual environment

This ensures zero configuration — uv creates an isolated environment automatically.

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.10"
# dependencies = [
#     "requests>=2.32",
#     "yt-dlp",
#     "fpdf2>=2.8",
#     "mistune>=3",
#     "webvtt-py>=0.5",
#     "langdetect>=1.0",
#     "mlx-whisper>=0.4",
# ]
# ///

Non-executable modules (imported by scripts) do not need the shebang or script block.

Dependencies (PEP 723 inline metadata in transcribe_pdf.py):

• requests>=2.32 — HTTP client for OpenRouter and LM Studio APIs
• yt-dlp — YouTube audio download and subtitle extraction
• fpdf2>=2.8 — PDF generation
• mistune>=3 — Markdown-to-HTML conversion for HTML output
• webvtt-py>=0.5 — VTT subtitle parsing
• langdetect>=1.0 — Language detection for subtitle quality checks
• mlx-whisper>=0.4 — Local transcription fallback (Apple Silicon only)

How It Works

Phase 1: Input & Validation

1. validate_environment() — checks OPENROUTER_API_KEY, ffmpeg, uv, and lms are available
2. parse_args() or prompt_user() — accepts URL/file path, --method (hybrid/subtitles/audio), and optional --prompt

Phase 2: Transcription (Hybrid Pipeline)

For YouTube URLs with --method hybrid (default) or --method subtitles:

3. get_subtitles() — downloads auto-generated English subtitles via yt-dlp (VTT format)
4. check_subtitle_quality() — validates subtitle quality:
   • Word-per-minute rate (min 50 WPM)
   • Repeated phrase detection (flags garbled captions)
   • Language detection (must be English)
   • Minimum word count for long videos (500+ words for >10min)
5. If quality is "good" → parse_vtt() extracts text, skip to Phase 3
6. If quality is poor or subtitles unavailable → fall through to audio transcription

For --method audio or when subtitles fail:

7. download_audio() — downloads best audio via yt-dlp with:
   • Brave browser cookies (for YouTube auth)
   • JS runtime (Node.js) + EJS remote component (for n-challenge solving)
   • FFmpeg post-processing to .m4a
8. transcribe_with_fallback() — tries models in order, each with 1 retry (each attempt has 5 internal retries with linear backoff):
   • MiMo (xiaomi/mimo-v2.5) — cheapest, default
   • Gemini Flash Lite (google/gemini-2.5-flash-lite) — mid-tier
   • Gemini Flash (google/gemini-2.5-flash) — most capable
   • mlx-whisper (local, Apple Silicon) — zero cost, offline
   • Audio >10 min is auto-chunked into 10-min segments (16 kbps mono MP3)
   • If all models fail → raises TranscriptionFailed with detailed error

Phase 3: Summarization (Cloud-First)

9. summarize() → summarize_with_fallback() — generates summaries (cloud-first, local fallback):
   • Tries OpenRouter models in order: MiMo → Gemini Flash Lite → Gemini Flash
   • Each model has 1 retry with 5 internal retries per attempt
   • If all cloud models fail or OPENROUTER_API_KEY is unset → falls back to LM Studio
   • ensure_lmstudio_ready() — starts LM Studio server if needed, loads model (gemma-4-e4b-it)
   • local_chat() — calls LM Studio's OpenAI-compatible API
   • Special handling: Qwen models get enable_thinking: false to reduce CoT contamination
10. verify_summary() — checks each summary for CoT contamination:
    • Scans for trigger phrases: thinking process, analyze the, drafting, iterative, step-by-step, let me think, here's my reasoning
    • If detected → retries with strict prompt ("Output ONLY the summary text. No preamble, no analysis...")
    • If still contaminated → strips <thinking>, <reasoning> XML tags and numbered analysis lists via _strip_thinking()

Phase 4: Output & Cleanup

1. write_pdf(), write_html(), write_markdown() — writes three formats to transcribed/<YYYY-MM-DD>/:
   • Filename: {channel}-{title}.{ext} (or just {title}.{ext} if no channel)
   • PDF and HTML: title page + 100-word summary + 400-word summary (no transcript)
   • Markdown: metadata table + source info + summaries + full transcript
2. For custom prompts (--prompt):
   • summarize_custom() — generates single summary with custom instruction
   • write_custom_output() — writes PDF/HTML/Markdown with single summary section
   • Warns if transcript >5000 words (context window risk)
3. Cleanup — unload_lmstudio_model() frees GPU memory, removes temp directories

Verification

After each summary is generated, verify_summary() runs a three-stage pipeline:

1. Check — scans for CoT trigger phrases: thinking process, analyze the, drafting, iterative, step-by-step, let me think, here's my reasoning
2. Retry — if contamination detected, re-generates with a strict prompt: "Output ONLY the summary text. No preamble, no analysis, no thinking, no numbered steps, no meta-commentary."
3. Strip — if retry is still contaminated, runs _strip_thinking() as a safety net:
   • Removes <thinking>...</thinking> and <reasoning>...</reasoning> XML blocks
   • Removes Thinking: / Reasoning: / Thought: line headers
   • Removes numbered analysis list items (1., 2., etc.)

External Dependencies

The script is not fully self-contained. Here is every external dependency:

Runtime & CLI Tools

Python Packages (auto-resolved by uv run --script)

Environment Variables

Running Services

Network Access

File System

Note: The only dependencies uv resolves automatically are the seven Python packages listed above. Everything else — system tools, running services, browser cookies, API keys — must be present on the machine before running.

Configuration

Common Mistakes