---
id: crazynomad/skills/youtube-downloader
version: "eba7dcd2"
license: MIT
install: manual
updated: 2026-07-28
---

# youtube-downloader — This skill wraps yt-dlp to fetch videos from YouTube and over 1000 other platforms, with options for quality selection, audio extraction, subtitle capture, and playlist downloads. It preserves metadata and thumbnails while supporting resume on interrupted transfers.

Publisher: crazynomad · Stars: 27 · Updated: 2026-07-28

Install (manual): `git clone https://github.com/crazynomad/skills`

## SKILL.md

# YouTube Video Downloader (yt-dlp)

Download videos from YouTube and 1000+ other sites using yt-dlp.

## Description

A powerful video downloader skill based on yt-dlp that supports YouTube, Bilibili, Twitter/X, TikTok, and many other platforms. Features include format selection, audio extraction, subtitle download, playlist support, and metadata preservation.

## When to Use

Use this skill when users:
- Provide YouTube URLs and want to download videos
- Mention "download video", "下载视频", "save video from YouTube"
- Want to extract audio from videos (MP3)
- Need to download playlists or channels
- Want subtitles/captions from videos
- Request video download from supported sites (Bilibili, Twitter, TikTok, etc.)

## Features

- **Multi-Platform Support**: YouTube, Bilibili, Twitter/X, TikTok, Vimeo, and 1000+ sites
- **Format Selection**: Choose video quality (1080p, 720p, 4K) or audio-only
- **Audio Extraction**: Extract audio as MP3, M4A, or other formats
- **Subtitle Download**: Auto-download subtitles in multiple languages
- **Playlist Support**: Download entire playlists or channels
- **Metadata Preservation**: Save video info, thumbnails, and descriptions
- **Resume Support**: Continue interrupted downloads
- **Progress Display**: Real-time download progress

## Usage

### Basic Syntax

```bash
python scripts/download_video.py "VIDEO_URL" [OPTIONS]
```

### Common Scenarios

**Download single video (best quality)**:
```bash
python scripts/download_video.py "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
```

**Download video in specific quality**:
```bash
python scripts/download_video.py "https://www.youtube.com/watch?v=VIDEO_ID" -f 1080
```

**Extract audio only (MP3)**:
```bash
python scripts/download_video.py "https://www.youtube.com/watch?v=VIDEO_ID" --audio-only
```

**Download with subtitles**:
```bash
python scripts/download_video.py "https://www.youtube.com/watch?v=VIDEO_ID" --subtitles
```

**Download playlist**:
```bash
python scripts/download_video.py "https://www.youtube.com/playlist?list=PLAYLIST_ID" --playlist
```

**Download N videos from playlist**:
```bash
python scripts/download_video.py "https://www.youtube.com/playlist?list=PLAYLIST_ID" --playlist -n 5
```

**Specify output directory**:
```bash
python scripts/download_video.py "URL" -o /path/to/output
```

### Arguments

| Argument | Description | Default |
|----------|-------------|---------|
| `url` | Video/Playlist URL (required) | - |
| `-o, --output` | Output directory | Current directory |
| `-f, --format` | Video quality: `best`, `1080`, `720`, `480`, `360` | `best` |
| `--audio-only` | Extract audio only (MP3) | False |
| `--subtitles` | Download subtitles | False |
| `--sub-lang` | Subtitle language(s) | `en,zh-Hans` |
| `--playlist` | Enable playlist download | False |
| `-n, --count` | Number of videos from playlist | All |
| `--metadata` | Save video metadata JSON | True |
| `--thumbnail` | Download thumbnail | False |
| `--cookies` | Path to cookies file (for age-restricted content) | None |

## Dependencies

```bash
# Install yt-dlp
pip install yt-dlp --break-system-packages

# For audio extraction (optional)
# macOS
brew install ffmpeg

# Ubuntu/Debian
apt-get install ffmpeg
```

## Output Structure

### Single Video
```
OutputDir/
├── Video Title [VIDEO_ID].mp4     # Video file
├── Video Title [VIDEO_ID].json    # Metadata (if --metadata)
├── Video Title [VIDEO_ID].jpg     # Thumbnail (if --thumbnail)
└── Video Title [VIDEO_ID].en.vtt  # Subtitles (if --subtitles)
```

### Playlist
```
OutputDir/
└── PlaylistName/
    ├── playlist_info.json
    ├── 001 - Video Title.mp4
    ├── 001 - Video Title.json
    ├── 002 - Another Video.mp4
    └── ...
```

### Metadata Example

```json
{
  "title": "Video Title",
  "uploader": "Channel Name",
  "upload_date": "2024-01-15",
  "duration": 300,
  "view_count": 1000000,
  "description": "Video description...",
  "tags": ["tag1", "tag2"],
  "video_file": "Video Title [VIDEO_ID].mp4"
}
```

## Claude Integration

When user requests video download:

1. **Read skill documentation**:
   ```python
   view("/mnt/skills/user/youtube-downloader/SKILL.md")
   ```

2. **Install dependencies** (if needed):
   ```bash
   pip install yt-dlp --break-system-packages
   ```

3. **Execute download**:
   ```bash
   python /mnt/skills/user/youtube-downloader/scripts/download_video.py \
     "USER_URL" -o /mnt/user-data/outputs
   ```

4. **Present files** to user:
   ```python
   present_files(["/mnt/user-data/outputs/..."])
   ```

## Supported Platforms

### Major Platforms
- **YouTube**: Videos, Shorts, Playlists, Channels, Live streams
- **Bilibili**: Videos, Episodes (may need cookies)
- **Twitter/X**: Video tweets
- **TikTok**: Videos (may need cookies)
- **Vimeo**: Videos
- **Twitch**: VODs, Clips

### Full List
yt-dlp supports 1000+ sites. Run `yt-dlp --list-extractors` for full list.

## Common Issues

**Q: Age-restricted videos?**
A: Use `--cookies` with exported browser cookies: `--cookies cookies.txt`

**Q: Format not available?**
A: Some videos may not have all quality options. Script will auto-select best available.

**Q: Download speed slow?**
A: This is usually server-side throttling. Consider using a VPN or waiting.

**Q: Need to login for private videos?**
A: Export cookies from your browser after logging in, then use `--cookies`.

**Q: Audio extraction fails?**
A: Install ffmpeg: `brew install ffmpeg` (macOS) or `apt install ffmpeg` (Linux)

## Example Conversations

**User**: "帮我下载这个 YouTube 视频: https://www.youtube.com/watch?v=dQw4w9WgXcQ"

**Claude**:
```bash
# Install yt-dlp
pip install yt-dlp --break-system-packages

# Download video
python /mnt/skills/user/youtube-downloader/scripts/download_video.py \
  "https://www.youtube.com/watch?v=dQw4w9WgXcQ" \
  -o /mnt/user-data/outputs

# Present files
present_files([...])
```

---

**User**: "下载这个 YouTube 视频的音频，我只要 MP3"

**Claude**:
```bash
python /mnt/skills/user/youtube-downloader/scripts/download_video.py \
  "VIDEO_URL" \
  --audio-only \
  -o /mnt/user-data/outputs
```

---

**User**: "Download this playlist, but only the first 5 videos"

**Claude**:
```bash
python /mnt/skills/user/youtube-downloader/scripts/download_video.py \
  "PLAYLIST_URL" \
  --playlist -n 5 \
  -o /mnt/user-data/outputs
```

## How It Works

### Workflow

1. **URL Parsing**: Detect platform and content type (video/playlist)
2. **Format Selection**: Determine best available format based on user preference
3. **Download**: Stream video/audio with progress display
4. **Post-Processing**: Extract audio (if requested), embed subtitles
5. **Metadata**: Save video information to JSON

### Under the Hood

This skill wraps yt-dlp with sensible defaults:
- Automatic format selection for best quality
- Proper filename sanitization
- Retry logic for failed downloads
- Progress display with ETA

## Limitations

- Some sites may require authentication (cookies)
- Age-restricted content needs browser cookies
- Download speed depends on source server
- Some DRM-protected content cannot be downloaded
- Live streams can only be downloaded after they end (VOD)

## Legal Notice

This tool is for personal use only. Please respect:
- YouTube Terms of Service
- Copyright laws in your jurisdiction
- Content creators' rights

Only download content you have the right to access. Do not redistribute copyrighted material.

## Version History

**v1.0** (Current)
- Initial release with yt-dlp wrapper
- Support for video, audio, subtitles, playlists
- Metadata and thumbnail preservation
- Multi-platform support

## References

- [yt-dlp GitHub](https://github.com/yt-dlp/yt-dlp)
- [yt-dlp Documentation](https://github.com/yt-dlp/yt-dlp#readme)
- [Supported Sites](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md)


[View on SkillFed](https://skillfed.io/crazynomad/skills/youtube-downloader) · [View on GitHub](https://github.com/crazynomad/skills)