| # Step-by-Step Setup Guide | |
| --- | |
| ## Prerequisites | |
| | Requirement | Minimum Version | | |
| |-------------|-----------------| | |
| | Python | 3.8 | | |
| | pip | 21.0 | | |
| --- | |
| ## Step 1 — Clone or Download the Project | |
| If you have Git installed: | |
| ```bash | |
| git clone https://github.com/your-username/youtube-transcript-fetcher.git | |
| cd youtube-transcript-fetcher | |
| ``` | |
| Or download and unzip the archive, then open a terminal inside the folder. | |
| --- | |
| ## Step 2 — Create a Virtual Environment (Recommended) | |
| **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 when the environment is active. | |
| --- | |
| ## Step 3 — Install Dependencies | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| Verify the install: | |
| ```bash | |
| pip show youtube-transcript-api | |
| ``` | |
| --- | |
| ## Step 4 — Run the Script | |
| ### Basic usage — print transcript to terminal | |
| ```bash | |
| python main.py "https://www.youtube.com/watch?v=dQw4w9WgXcQ" | |
| ``` | |
| ### Save to a file | |
| ```bash | |
| python main.py "https://youtu.be/dQw4w9WgXcQ" -o transcript.txt | |
| ``` | |
| ### Export as SRT subtitles | |
| ```bash | |
| python main.py dQw4w9WgXcQ -f srt -o transcript.srt | |
| ``` | |
| ### Export as JSON | |
| ```bash | |
| python main.py dQw4w9WgXcQ -f json -o transcript.json | |
| ``` | |
| ### Include timestamps in plain-text output | |
| ```bash | |
| python main.py dQw4w9WgXcQ -t | |
| ``` | |
| ### Request a specific language | |
| ```bash | |
| python main.py dQw4w9WgXcQ -l es # Spanish | |
| python main.py dQw4w9WgXcQ -l ja ko en # Japanese, then Korean, then English | |
| ``` | |
| ### List all available languages for a video | |
| ```bash | |
| python main.py dQw4w9WgXcQ --list | |
| ``` | |
| ### Batch — multiple videos saved to a directory | |
| ```bash | |
| python main.py VIDEO_ID_1 VIDEO_ID_2 VIDEO_ID_3 -o ./transcripts/ | |
| ``` | |
| --- | |
| ## Step 5 — Deactivate the Virtual Environment (When Done) | |
| ```bash | |
| deactivate | |
| ``` | |
| --- | |
| ## Troubleshooting | |
| | Error | Cause | Fix | | |
| |-------|-------|-----| | |
| | `TranscriptsDisabled` | The video owner turned off transcripts | Nothing can be done; try another video | | |
| | `VideoUnavailable` | Video is private, deleted, or region-locked | Check the URL; use a VPN if region-locked | | |
| | `NoTranscriptFound` | Requested language does not exist | Run `--list` and pick an available language | | |
| | `ModuleNotFoundError` | Dependencies not installed | Run `pip install -r requirements.txt` | | |
| | Empty output | Video has no speech or very short content | Confirm the video has captions enabled | | |
| --- | |
| ## Input Formats Accepted | |
| All of the following point to the same video and are equally valid input: | |
| ``` | |
| https://www.youtube.com/watch?v=dQw4w9WgXcQ | |
| https://youtu.be/dQw4w9WgXcQ | |
| https://www.youtube.com/shorts/dQw4w9WgXcQ | |
| https://www.youtube.com/embed/dQw4w9WgXcQ | |
| dQw4w9WgXcQ | |
| ``` | |
| --- | |
| ## Output Formats | |
| | Flag | Format | Best For | | |
| |------|--------|----------| | |
| | `text` (default) | Plain text, one line per caption segment | Reading, summarization, NLP | | |
| | `json` | JSON array with `text`, `start`, `duration` fields | Programmatic processing | | |
| | `srt` | SubRip subtitle format | Video players, Premiere, DaVinci | | |
| | `vtt` | WebVTT subtitle format | HTML5 video, browsers | |