dk-transcribe-summarize

Files (16)

• SKILL.md
• audio.cpython-313.pyc · scripts/__pycache__/
• config.cpython-313.pyc · scripts/__pycache__/
• llm.cpython-313.pyc · scripts/__pycache__/
• output.cpython-313.pyc · scripts/__pycache__/
• utils.cpython-313.pyc · scripts/__pycache__/
• audio.py · scripts/
• config.py · scripts/
• llm.py · scripts/
• output.py · scripts/
• test_helpers.py · scripts/
• transcribe_pdf.py · scripts/
• utils.py · scripts/
• whisper_local.py · scripts/
• 2026-06-07-hybrid-transcription-plan.md · specs/
• hybrid-transcription-spec.md · specs/

SKILL.md (first lines)

# 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

| Step | Command |
|------|---------|
| Run (default) | `cd scripts && uv run transcribe_pdf.py` |
| Run with URL | `cd scripts && uv run transcribe_pdf.py "https://youtube.com/..."` |
| Subtitles only | `cd scripts && uv run transcribe_pdf.py --method subtitles` |
| Audio only | `cd scripts && uv run transcribe_pdf.py --method audio` |
| Custom prompt | `cd scripts && uv run transcribe_pdf.py "..." --prompt "Extract action items"` |
| Input | Paste local path or YouTube URL at prompt (if no CLI arg) |
| Output | `transcribed/<YYYY-MM-DD>/<channel>-<title>.{pdf,html,md}` |
| API key | `OPENROUTER_API_KEY` env var (for transcription and cloud summarization) |
| Local model | Override with `LOCAL_MODEL_NAME` env var (default: `gemma-4-e4b-it`) |
| Prerequisites | `ffmpeg`, `uv`, `lms` (LM Studio CLI), Node.js |

## Script

Reusable tool: `scripts/transcribe_pdf.py`

```bash
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.

```python
#!/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

From dushyantkhosla/agent-skills, MIT.

More from dushyantkhosla/agent-skills