yt-dlf/README.md

# yt-dlf

YouTube Downloader & Transcript Extractor — a local web frontend for `yt-dlp` and `ffmpeg`.

## Features

- Paste a YouTube URL and download the best available video quality
- Subtitles downloaded automatically in the video's original language, English, and German (where available)
- Subtitles converted to clean Markdown (timestamps stripped, text deduplicated and paragraph-wrapped)
- Optional audio extraction to MP3 via ffmpeg
- Real-time progress log streamed to the browser
- Files saved to `~/YouTube/<video title>/`

## Prerequisites

```bash
brew install yt-dlp ffmpeg
```

Node.js 16+ is required for the web app (tested with Node 26).

## Project Layout

```
yt-dlf/
├── scripts/
│   └── subtitle_to_markdown.py   # standalone CLI converter
├── src/
│   ├── lib/
│   │   └── subtitle.js           # JS conversion module (used by web app)
│   └── routes/
│       ├── api/download/
│       │   └── +server.js        # SSE endpoint — runs yt-dlp / ffmpeg
│       ├── +layout.svelte
│       └── +page.svelte          # UI
└── vite.config.js
```

## Running the web app

```bash
npm install       # first time only
npm run dev       # starts on http://localhost:5173
```

To use a custom port:

```bash
PORT=8080 npm run dev
```

## Standalone subtitle converter

Convert a `.vtt` or `.srt` subtitle file to Markdown directly from the terminal:

```bash
./scripts/subtitle_to_markdown.py video.en.vtt
./scripts/subtitle_to_markdown.py video.en.vtt output.md
```

Output is saved next to the input file (same name, `.md` extension) unless a second argument is given.