| --- |
| license: mit |
| sdk: static |
| colorFrom: blue |
| colorTo: red |
| tags: |
| - youtube |
| - transcript |
| - api |
| - fetch |
| - clean |
| - summarize |
| - python |
| - tools |
|
|
| --- |
| |
|  |
|  |
|  |
|  |
|  |
|  |
|
|
| --- |
|
|
| # YouTube Transcript Toolkit |
|
|
| A fast, zero-scraping command-line toolkit that fetches YouTube transcripts |
| directly via the caption API, then uses the Anthropic Claude API to reformat |
| them into clean paragraphs and produce multi-mode summaries. |
|
|
| No Selenium. No BeautifulSoup. No headless browsers. Two AI-powered |
| post-processing features built on top of direct caption API access. |
|
|
| --- |
|
|
| ## Architecture |
|
|
| ``` |
| main.py CLI entry point — five commands (fetch, list, clean, summarize, pipeline) |
| fetcher.py Direct YouTube caption API — no HTML parsing |
| cleaner.py AI paragraph reformatter (Anthropic Claude) |
| summarizer.py AI summarizer with 4 output modes (Anthropic Claude) |
| pipeline.py Orchestrates fetch -> clean -> summarize in one pass |
| ai_client.py Shared Anthropic API wrapper with chunking and streaming |
| config.py Model names, limits, summary modes, defaults |
| ``` |
|
|
| --- |
|
|
| ## Features |
|
|
| - Direct caption API — transcript fetch is near-instant regardless of video length |
| - Paragraph Cleaner — reformats fragmented auto-captions into readable prose (no content removed) |
| - Summarizer — four modes: brief, detailed, bullet points, hierarchical outline |
| - Full pipeline — fetch + clean + summarize in a single command |
| - Token streaming — see AI output in real time as it generates |
| - Automatic chunking — handles transcripts of any length by splitting and merging |
| - Fast model by default (claude-haiku), quality model available via --quality flag |
| - Batch processing — multiple video IDs/URLs in one command |
| - Output formats — plain text, JSON, SRT, WebVTT for the raw transcript |
|
|
| --- |
|
|
| ## Installation |
|
|
| ```bash |
| git clone https://github.com/algorembrant/youtube-transcript-toolkit.git |
| cd youtube-transcript-toolkit |
| python -m venv .venv |
| source .venv/bin/activate # Windows: .venv\Scripts\activate |
| pip install -r requirements.txt |
| export ANTHROPIC_API_KEY="sk-ant-..." # Windows: set ANTHROPIC_API_KEY=sk-ant-... |
| ``` |
|
|
| --- |
|
|
| ## Commands |
|
|
| ### fetch — raw transcript only (no AI) |
|
|
| ```bash |
| python main.py fetch "https://www.youtube.com/watch?v=VIDEO_ID" |
| python main.py fetch VIDEO_ID -f srt -o transcript.srt |
| python main.py fetch VIDEO_ID -f json -o transcript.json |
| python main.py fetch VIDEO_ID -t # with timestamps |
| python main.py fetch VIDEO_ID -l es en # Spanish, fall back to English |
| ``` |
|
|
| ### list — available languages |
|
|
| ```bash |
| python main.py list VIDEO_ID |
| ``` |
|
|
| ### clean — reformat into paragraphs |
|
|
| ```bash |
| python main.py clean VIDEO_ID |
| python main.py clean VIDEO_ID -o cleaned.txt |
| python main.py clean VIDEO_ID --quality # use higher-quality model |
| python main.py clean VIDEO_ID --no-stream # disable live token output |
| ``` |
|
|
| ### summarize — AI-generated summary |
|
|
| ```bash |
| python main.py summarize VIDEO_ID # brief (default) |
| python main.py summarize VIDEO_ID -m detailed |
| python main.py summarize VIDEO_ID -m bullets |
| python main.py summarize VIDEO_ID -m outline |
| python main.py summarize VIDEO_ID -m detailed --quality -o summary.txt |
| ``` |
|
|
| ### pipeline — fetch + clean + summarize |
|
|
| ```bash |
| python main.py pipeline VIDEO_ID |
| python main.py pipeline VIDEO_ID -m bullets -o ./output/ |
| python main.py pipeline VIDEO_ID --skip-clean # fetch + summarize only |
| python main.py pipeline VIDEO_ID --skip-summary # fetch + clean only |
| python main.py pipeline ID1 ID2 ID3 -o ./batch/ # batch |
| ``` |
|
|
| --- |
|
|
| ## Summary Modes |
|
|
| | Mode | Description | |
| |------------|--------------------------------------------------| |
| | `brief` | 3-5 sentence executive summary | |
| | `detailed` | Multi-section prose: Overview, Key Points, etc. | |
| | `bullets` | Key takeaways grouped under bold thematic headers| |
| | `outline` | Hierarchical Roman-numeral topic outline | |
|
|
| --- |
|
|
| ## Model Selection |
|
|
| | Flag | Model Used | Best For | |
| |-------------|-----------------------------|------------------------------------| |
| | (default) | claude-haiku-4-5 | Speed, short-to-medium transcripts | |
| | `--quality` | claude-sonnet-4-6 | Long transcripts, deep summaries | |
|
|
| --- |
|
|
| ## CLI Reference |
|
|
| ``` |
| usage: main.py {fetch,list,clean,summarize,pipeline} [options] video [video ...] |
| |
| commands: |
| fetch Fetch raw transcript (no AI) |
| list List available transcript languages |
| clean Fetch + AI paragraph formatting |
| summarize Fetch + AI summarization |
| pipeline Fetch + clean + summarize in one pass |
| |
| shared options: |
| -l, --languages LANG [LANG ...] Language codes, in order of preference |
| -o, --output PATH Output file (single) or directory (batch) |
| --quality Use higher-quality Claude model |
| --no-stream Disable live token streaming |
| |
| fetch / pipeline options: |
| -f, --format {text,json,srt,vtt} Raw transcript format (default: text) |
| -t, --timestamps Add timestamps to plain-text output |
| |
| clean / summarize / pipeline options: |
| -m, --mode {brief,detailed,bullets,outline} Summary mode (default: brief) |
| |
| pipeline options: |
| --skip-clean Skip paragraph cleaning step |
| --skip-summary Skip summarization step |
| ``` |
|
|
| --- |
|
|
| ## Output Files (pipeline with -o) |
|
|
| When using `pipeline -o ./output/`, three files are saved per video: |
|
|
| ``` |
| ./output/ |
| VIDEO_ID_transcript.txt Raw transcript |
| VIDEO_ID_cleaned.txt Paragraph-cleaned transcript |
| VIDEO_ID_summary.txt Summary |
| ``` |
|
|
| --- |
|
|
| ## Chunking Strategy |
|
|
| Transcripts larger than 60,000 characters are automatically split into chunks |
| at paragraph or sentence boundaries. Each chunk is processed independently, |
| then the partial results are merged in a final synthesis pass. This allows |
| the toolkit to handle full-length lecture recordings, long-form interviews, |
| and documentary transcripts without hitting token limits. |
|
|
| --- |
|
|
| ## Supported URL Formats |
|
|
| ``` |
| https://www.youtube.com/watch?v=VIDEO_ID |
| https://youtu.be/VIDEO_ID |
| https://www.youtube.com/shorts/VIDEO_ID |
| https://www.youtube.com/embed/VIDEO_ID |
| VIDEO_ID (raw 11-character ID) |
| ``` |
|
|
| --- |
|
|
| ## Error Reference |
|
|
| | Error | Cause | |
| |-------------------------|--------------------------------------------------| |
| | `TranscriptsDisabled` | Video owner has disabled captions | |
| | `VideoUnavailable` | Video is private, deleted, or region-locked | |
| | `NoTranscriptFound` | Requested language does not exist | |
| | `NoTranscriptAvailable` | No captions of any kind exist for this video | |
| | `AuthenticationError` | ANTHROPIC_API_KEY is missing or invalid | |
|
|
| --- |
|
|
| ## Dependencies |
|
|
| | Package | Version | Purpose | |
| |------------------------|------------|--------------------------------------| |
| | anthropic | >=0.40.0 | Claude API (clean + summarize) | |
| | youtube-transcript-api | 0.6.2 | Direct YouTube caption API access | |
|
|
| --- |
|
|
| ## License |
|
|
| MIT License. See `LICENSE` for details. |
|
|
| --- |
|
|
| ## Disclaimer |
|
|
| This tool uses YouTube's publicly accessible caption endpoint and the Anthropic |
| API for personal, educational, and research use. An Anthropic API key is required |
| for the clean and summarize features. Review YouTube's Terms of Service before |
| using this tool in a production or commercial context. |
|
|
