README.md

---
license: mit
sdk: static
colorFrom: blue
colorTo: red
tags:
  - youtube
  - transcript
  - api
  - fetch
  - clean
  - summarize
  - python
  - tools

---

![Python](https://img.shields.io/badge/Python-3.8%2B-blue?style=flat-square&logo=python&logoColor=white)
![Anthropic](https://img.shields.io/badge/Powered%20by-Anthropic%20Claude-blueviolet?style=flat-square)
![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)
![No Scraping](https://img.shields.io/badge/No%20Scraping-Direct%20API-brightgreen?style=flat-square)
![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey?style=flat-square)
![Author](https://img.shields.io/badge/Author-algorembrant-orange?style=flat-square)

---

# 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.