| # Step-by-Step Setup and Usage Guide | |
| Author: algorembrant | |
| --- | |
| ## Prerequisites | |
| | Requirement | Minimum Version | Notes | | |
| |----------------------|-----------------|--------------------------------------------| | |
| | Python | 3.8 | 3.10+ recommended | | |
| | pip | 21.0 | | | |
| | Anthropic API Key | -- | Required for clean and summarize commands | | |
| You need an Anthropic API key to use the `clean`, `summarize`, and `pipeline` commands. | |
| Obtain one at: https://console.anthropic.com | |
| --- | |
| ## Step 1 — Get the Code | |
| **Option A: Git clone** | |
| ```bash | |
| git clone https://github.com/algorembrant/youtube-transcript-toolkit.git | |
| cd youtube-transcript-toolkit | |
| ``` | |
| **Option B: Download ZIP** | |
| Download and unzip, then open a terminal inside the project folder. | |
| --- | |
| ## Step 2 — Create a Virtual Environment | |
| **macOS / Linux** | |
| ```bash | |
| python3 -m venv .venv | |
| source .venv/bin/activate | |
| ``` | |
| **Windows (Command Prompt)** | |
| ```cmd | |
| python -m venv .venv | |
| .venv\Scripts\activate.bat | |
| ``` | |
| **Windows (PowerShell)** | |
| ```powershell | |
| python -m venv .venv | |
| .venv\Scripts\Activate.ps1 | |
| ``` | |
| You should see `(.venv)` at the start of your terminal prompt. | |
| --- | |
| ## Step 3 — Install Dependencies | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| Verify: | |
| ```bash | |
| pip show anthropic | |
| pip show youtube-transcript-api | |
| ``` | |
| --- | |
| ## Step 4 — Set Your Anthropic API Key | |
| **macOS / Linux (current session)** | |
| ```bash | |
| export ANTHROPIC_API_KEY="sk-ant-your-key-here" | |
| ``` | |
| **macOS / Linux (permanent — add to shell profile)** | |
| ```bash | |
| echo 'export ANTHROPIC_API_KEY="sk-ant-your-key-here"' >> ~/.zshrc | |
| source ~/.zshrc | |
| ``` | |
| **Windows (Command Prompt)** | |
| ```cmd | |
| set ANTHROPIC_API_KEY=sk-ant-your-key-here | |
| ``` | |
| **Windows (PowerShell)** | |
| ```powershell | |
| $env:ANTHROPIC_API_KEY = "sk-ant-your-key-here" | |
| ``` | |
| **Windows (permanent via System Settings)** | |
| 1. Search "Environment Variables" in Start Menu | |
| 2. Click "Edit the system environment variables" | |
| 3. Add a new variable: `ANTHROPIC_API_KEY` = your key | |
| The `fetch` and `list` commands do NOT require an API key. | |
| Only `clean`, `summarize`, and `pipeline` need it. | |
| --- | |
| ## Step 5 — Run Your First Commands | |
| ### Fetch a raw transcript (no API key needed) | |
| ```bash | |
| python main.py fetch "https://www.youtube.com/watch?v=dQw4w9WgXcQ" | |
| ``` | |
| ### See what languages are available | |
| ```bash | |
| python main.py list dQw4w9WgXcQ | |
| ``` | |
| ### Clean the transcript into paragraphs | |
| ```bash | |
| python main.py clean dQw4w9WgXcQ | |
| ``` | |
| ### Summarize the transcript | |
| ```bash | |
| python main.py summarize dQw4w9WgXcQ -m brief | |
| python main.py summarize dQw4w9WgXcQ -m detailed | |
| python main.py summarize dQw4w9WgXcQ -m bullets | |
| python main.py summarize dQw4w9WgXcQ -m outline | |
| ``` | |
| ### Run the full pipeline (fetch + clean + summarize) | |
| ```bash | |
| python main.py pipeline dQw4w9WgXcQ -m bullets | |
| ``` | |
| --- | |
| ## Step 6 — Save Output to Files | |
| ### Single video — specify a file path | |
| ```bash | |
| python main.py clean dQw4w9WgXcQ -o cleaned.txt | |
| python main.py summarize dQw4w9WgXcQ -m detailed -o summary.txt | |
| ``` | |
| ### Pipeline — specify a directory (creates 3 files per video) | |
| ```bash | |
| python main.py pipeline dQw4w9WgXcQ -o ./output/ | |
| ``` | |
| Files created: | |
| ``` | |
| ./output/ | |
| dQw4w9WgXcQ_transcript.txt | |
| dQw4w9WgXcQ_cleaned.txt | |
| dQw4w9WgXcQ_summary.txt | |
| ``` | |
| ### Batch — multiple videos at once | |
| ```bash | |
| python main.py pipeline VIDEO_ID_1 VIDEO_ID_2 VIDEO_ID_3 -o ./batch_output/ | |
| ``` | |
| --- | |
| ## Step 7 — Advanced Options | |
| ### Use the higher-quality model | |
| ```bash | |
| python main.py clean dQw4w9WgXcQ --quality | |
| python main.py summarize dQw4w9WgXcQ -m detailed --quality | |
| ``` | |
| Default model: `claude-haiku-4-5` (fast, cost-efficient) | |
| Quality model: `claude-sonnet-4-6` (better for complex or long transcripts) | |
| ### Disable streaming (show output only after completion) | |
| ```bash | |
| python main.py clean dQw4w9WgXcQ --no-stream | |
| ``` | |
| ### Request a non-English transcript | |
| ```bash | |
| python main.py clean dQw4w9WgXcQ -l ja # Japanese only | |
| python main.py clean dQw4w9WgXcQ -l es en # Spanish, fall back to English | |
| ``` | |
| ### Fetch raw transcript as SRT or JSON | |
| ```bash | |
| python main.py fetch dQw4w9WgXcQ -f srt -o captions.srt | |
| python main.py fetch dQw4w9WgXcQ -f json -o transcript.json | |
| python main.py fetch dQw4w9WgXcQ -f vtt -o captions.vtt | |
| ``` | |
| ### Fetch with timestamps | |
| ```bash | |
| python main.py fetch dQw4w9WgXcQ -t | |
| python main.py pipeline dQw4w9WgXcQ -t -o ./output/ | |
| ``` | |
| ### Pipeline — skip individual steps | |
| ```bash | |
| # Fetch and summarize without cleaning | |
| python main.py pipeline dQw4w9WgXcQ --skip-clean -m bullets | |
| # Fetch and clean without summarizing | |
| python main.py pipeline dQw4w9WgXcQ --skip-summary | |
| ``` | |
| --- | |
| ## Troubleshooting | |
| | Symptom | Likely Cause | Fix | | |
| |---------|-------------|-----| | |
| | `TranscriptsDisabled` error | Video owner disabled captions | Use a different video | | |
| | `VideoUnavailable` error | Private, deleted, or region-locked | Check URL; try VPN if region-locked | | |
| | `NoTranscriptFound` | Requested language missing | Run `list` to see available languages | | |
| | `AuthenticationError` | API key missing or wrong | Check `ANTHROPIC_API_KEY` env variable | | |
| | `ModuleNotFoundError` | Dependencies not installed | Run `pip install -r requirements.txt` | | |
| | Chunking messages in stderr | Transcript very long | Normal — multi-pass processing is automatic | | |
| | Output cuts off mid-sentence | max_tokens limit hit | This is rare; open an issue if it occurs | | |
| --- | |
| ## Project File Reference | |
| ``` | |
| main.py CLI entry point — all five commands | |
| fetcher.py YouTube direct caption API (no scraping) | |
| cleaner.py AI paragraph reformatter | |
| summarizer.py AI summarizer (4 modes) | |
| pipeline.py Orchestrates the full fetch -> clean -> summarize chain | |
| ai_client.py Anthropic API wrapper with chunking and streaming | |
| config.py Constants: model names, chunk size, summary modes | |
| requirements.txt Two dependencies | |
| README.md Full project documentation | |
| GUIDE.md This file | |
| LICENSE MIT License | |
| ``` | |