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