KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #developer-tools #ai-agent #claude-code #codex #typescript #ai-agents #deepseek-harness #mcp #cli #rust

youtube-downloader-script

★ 1 Open GitHub ↗

A script to download YT videos at best audio/video quality that utilizes yt-dlp, ffmpeg, mkvmerge and faster-whisper ai to generate subtitles and embed them to an mkv formatted video.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🎬 yt-dlp Automation Script For YouTube Video Download With Subtitle Embedder Using Faster-Whisper (macOS)(Apple Silicon Compatible)

This script downloads a single YouTube video, checks for manually uploaded English subtitles, and if not found, generates English subtitles using [Faster Whisper](https://github.com/guillaumekln/faster-whisper). It then embeds the subtitles into the final MKV file.

## ✅ Features

- Scans the URL and prompts with the actual available video qualities before downloading
- Prompts for browser cookie source, including Firefox, Arc, Chrome, Edge, Chromium, and exported cookies
- Uses `--no-playlist` so Mix and playlist URLs download only the requested video
- Detects and uses manually uploaded English subtitles if available
- Ignores YouTube auto-generated captions and falls back to Faster Whisper instead
- Converts `.vtt` subtitles to `.srt` and cleans them up
- Uses `Faster Whisper` (large-v2 or small model) for high-quality speech-to-text transcription if subtitles are missing
- Prepares normalized mono 16 kHz audio locally before Whisper transcription
- Embeds `.srt` subtitles directly into the downloaded `.mkv`
- Uses macOS system temporary directory
- Handles virtual environment and model downloads automatically
- Downloads up to 4K YouTube videos

## 🧰 Requirements

- macOS
- Python 3.8+
- Homebrew (used to install dependencies)
- Get cookies.txt LOCALLY (browser extension) (saved to `~/cookies.txt`)

### Dependencies installed via Homebrew:

- `ffmpeg`
- `mkvtoolnix`
- `Deno`

### Python Packages (installed in a virtual environment `~/whisper-env`):

- `faster-whisper`
- `yt-dlp[default]`

## 🚀 Setup Instructions

1. **Install Homebrew** (if not installed):
    ```sh
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    ```

2. **Export your Web Browser cookies** (e.g., with an extension like Get cookies.txt LOCALLY) and save them to:
    ```
    ~/cookies.txt
    ```

3. **Run the script:**
    ```sh
    ./yt-video-downloader-v1.4.2.sh
    ```

4. Paste your desired YouTube URL when prompted.
5. Choose one of the actual available video qualities when prompted and the script will handle the rest.

## 📂 Output

Final `.mkv` with embedded subtitles is saved to:
```
~/Downloads/
```

## ⚠️ Notes

- Mix and playlist URLs are accepted, but only the requested video is downloaded.
- You must watch YT video first so that extracted cookies from your web browser are updated with the cookies of you actually watching the video for the yt-dlp to be able to download the video
- cookies.txt must be saved in root of home directory because that's where the script looks for cookies file.
- If no manually uploaded English subtitles are found, the script transcribes audio using Faster Whisper.
- YouTube auto-generated captions are not used.
- It uses the macOS system temp directory (`/var/folders/...`) for temporary operations.
- If `large-v2` Faster Whisper model is not found locally, it defaults to `small`.

## Version

Current version: `v1.4.2`

### v1.4.2

- Added a cookie-source picker for installed browser profiles.
- Added support for Firefox, Arc Browser, Google Chrome, Brave, Microsoft Edge, Vivaldi, Chromium, and exported `~/cookies.txt`.
- Uses Arc through its Chromium profile path because yt-dlp does not expose a native `arc` browser alias.

### v1.4.1

- Expanded the quality menu to show individual video format entries instead of grouped resolutions.
- Added bitrate, file size, container, codec, and format ID details to help distinguish higher-bitrate 1080p options.

### v1.4.0

- Replaced generic quality presets with a `yt-dlp` format scan that lists only the qualities actually available for the pasted URL.
- Removed the MP4-only preference from the best-video selector so 4K and other high-quality WebM/AV1/VP9 formats are not accidentally excluded.
- Shows resolution, FPS, container types, and codec families in the quality menu.

### v1.3.1

- Improved Faster Whisper lyric transcription by replacing the long instructional prompt with a shorter lyric-focused prompt.
- Kept `large-v2` as the preferred model for Apple Silicon compatibility.
- Removed the extra saved SRT review copy after debugging was complete.

### v1.3.0

- Added quality-cap prompt.
- Added single-video handling with `--no-playlist`.
- Updated yt-dlp dependency handling to use `yt-dlp[default]` for YouTube JS challenge support.
- Removed separate YouTube audio-only download for Whisper.
- Added manually uploaded English subtitle preference with Faster Whisper fallback.
- Excluded YouTube auto-generated captions.
- Added normalized audio preprocessing and wider Whisper decoding for better lyric transcription.

## 🧹 Cleanup

All temporary files are automatically deleted after the script finishes.

## 📜 License

MIT License. Free to use and modify.

youtube-downloader-script

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README