# twitter-video-downloader

> Download videos from Twitter/X using yt-dlp or gallery-dl with automatic quality selection

- Author: sawyer zhang
- Repository: alexzhang2015/cc-skills
- Version: 20260127125908
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/alexzhang2015/cc-skills
- Web: https://mule.run/skillshub/@@alexzhang2015/cc-skills~twitter-video-downloader:20260127125908

---

---
name: twitter-video-downloader
description: Download videos from Twitter/X using yt-dlp or gallery-dl with automatic quality selection
---

# Twitter Video Downloader

Automated tool for downloading videos from Twitter (X) with quality control and multiple download methods.

## Features

- Download videos from Twitter/X URLs
- Automatic quality selection (highest by default)
- Multiple quality options (1080p, 720p, 480p)
- Custom filename support
- Fallback methods if primary tool unavailable
- Support for both twitter.com and x.com domains

## Dependencies

**Required** (install at least one):
- `yt-dlp` (recommended) - `brew install yt-dlp`
- `gallery-dl` (alternative) - `brew install gallery-dl`

## Usage

### Basic Download

```bash
# Python version (recommended)
python3 download_twitter_video.py https://x.com/i/status/2015851783655194640

# Shell version
./download_twitter_video.sh https://x.com/i/status/2015851783655194640
```

### Custom Output

```bash
# Specify output directory
python3 download_twitter_video.py https://x.com/i/status/123456789 -o videos/

# Custom filename
python3 download_twitter_video.py https://x.com/i/status/123456789 -f my_video

# Both directory and filename
python3 download_twitter_video.py https://x.com/i/status/123456789 -o videos/ -f awesome_video
```

### Quality Selection

```bash
# Download in specific quality
python3 download_twitter_video.py https://x.com/i/status/123456789 -q 720p

# Available qualities: highest, 1080p, 720p, 480p
python3 download_twitter_video.py https://x.com/i/status/123456789 -q 480p
```

## Implementation Details

### Python Implementation

Located at: `download_twitter_video.py`

**Key functions:**
- `extract_tweet_id(url)` - Extracts tweet ID from various Twitter URL formats
- `download_video(tweet_url, output_dir, quality, filename)` - Main download function

**Features:**
- Pattern matching for multiple URL formats (twitter.com, x.com)
- Quality mapping for yt-dlp format strings
- Automatic directory creation
- Error handling and fallback suggestions

### Shell Implementation

Located at: `download_twitter_video.sh`

**Features:**
- Color-coded console output
- Automatic timestamp-based filenames
- Support for both yt-dlp and gallery-dl
- User-friendly error messages
- Fallback instructions if tools not installed

## URL Format Support

The tool supports various Twitter URL formats:
```
https://twitter.com/username/status/123456789
https://x.com/username/status/123456789
https://twitter.com/i/status/123456789
https://x.com/i/status/123456789
```

## Quality Options

| Quality | Description | yt-dlp Format |
|---------|-------------|---------------|
| highest | Best available quality | `best` |
| 1080p   | Max 1080p resolution | `best[height<=1080]` |
| 720p    | Max 720p resolution | `best[height<=720]` |
| 480p    | Max 480p resolution | `best[height<=480]` |

## Error Handling

### No Download Tool Installed

If neither yt-dlp nor gallery-dl is installed, the script will:
1. Show installation instructions
2. Provide manual download alternative (twittervideodownloader.com)
3. Exit with helpful error message

### Invalid URL

If the URL doesn't contain a valid tweet ID:
1. Extract tweet ID using regex patterns
2. Validate tweet ID format (10+ digits)
3. Show error if extraction fails

## Best Practices

**When to use:**
- Downloading Twitter videos for offline viewing
- Archiving important video content
- Getting highest quality version of videos
- Batch downloading multiple videos

**Installation:**
```bash
# macOS
brew install yt-dlp

# Linux
sudo apt install yt-dlp
# or
pip install yt-dlp

# Windows
winget install yt-dlp
```

## Examples

### Example 1: Quick Download
```bash
# Download video with default settings
python3 download_twitter_video.py https://x.com/i/status/2015851783655194640

# Output: twitter_video_2015851783655194640.mp4
```

### Example 2: Organized Downloads
```bash
# Create organized structure
mkdir -p downloads/twitter/
python3 download_twitter_video.py https://x.com/i/status/123456789 \
  -o downloads/twitter/ \
  -f interesting_video \
  -q 1080p

# Output: downloads/twitter/interesting_video.mp4
```

### Example 3: Batch Download
```bash
# Download multiple videos
urls=(
  "https://x.com/i/status/123456789"
  "https://x.com/i/status/987654321"
  "https://x.com/i/status/555666777"
)

for url in "${urls[@]}"; do
  python3 download_twitter_video.py "$url" -o batch_downloads/
done
```

## Integration with Claude Code

When using this skill in Claude Code workflows:

1. **Extract URLs from conversations**: Parse Twitter URLs from user messages
2. **Auto-download referenced videos**: Download videos when user shares Twitter links
3. **Quality selection based on context**: Choose appropriate quality based on use case
4. **Batch processing**: Handle multiple video downloads efficiently

## Troubleshooting

### Issue: yt-dlp not found
```bash
# Solution: Install yt-dlp
brew install yt-dlp
```

### Issue: Permission denied
```bash
# Solution: Make script executable
chmod +x download_twitter_video.sh
```

### Issue: Network errors
```bash
# Solution: Check internet connection and try again
# Twitter may also be rate-limiting requests
```

### Issue: Video unavailable
```bash
# Possible reasons:
# - Tweet deleted
# - Account private
# - Video removed by Twitter
# - Geo-restricted content
```

## Security Considerations

- Only download videos from trusted sources
- Respect copyright and terms of service
- Don't use for unauthorized redistribution
- Be aware of Twitter's rate limiting

## Future Enhancements

Potential improvements:
- Thumbnail extraction
- Subtitle/caption download
- Multiple video format support
- Progress bar for large downloads
- Resume interrupted downloads
- Playlist/thread support

## Related Tools

- **yt-dlp**: Universal video downloader
- **gallery-dl**: Image and video gallery downloader
- **twitter-dl**: Twitter-specific downloader
- **youtube-dl**: Original video downloader (predecessor to yt-dlp)