AI-powered YouTube video clipper for Claude Code. Download videos, generate semantic chapters, clip segments, translate subtitles to bilingual format, and burn subtitles into videos.
English | 简体中文
Features • Installation • Usage • Requirements • Configuration • Troubleshooting
- AI Semantic Analysis - Generate fine-grained chapters (2-5 minutes each) by understanding video content, not just mechanical time splitting
- Precise Clipping - Use FFmpeg to extract video segments with frame-accurate timing
- Bilingual Subtitles - Batch translate subtitles to Chinese/English with 95% API call reduction
- Subtitle Burning - Hardcode bilingual subtitles into videos with customizable styling
- Content Summarization - Auto-generate social media content (Xiaohongshu, Douyin, WeChat)
npx skills add https://github.com/op7418/Youtube-clipper-skillThis command will automatically install the skill to ~/.claude/skills/youtube-clipper/.
git clone https://github.com/op7418/Youtube-clipper-skill.git
cd Youtube-clipper-skill
bash install_as_skill.shThe install script will:
- Copy files to
~/.claude/skills/youtube-clipper/ - Install Python dependencies (yt-dlp, pysrt, python-dotenv)
- Check system dependencies (Python, yt-dlp, FFmpeg)
- Create
.envconfiguration file
| Dependency | Version | Purpose | Installation |
|---|---|---|---|
| Python | 3.8+ | Script execution | python.org |
| yt-dlp | Latest | YouTube download | brew install yt-dlp (macOS)sudo apt install yt-dlp (Ubuntu)pip install yt-dlp (pip) |
| FFmpeg with libass | Latest | Video processing & subtitle burning | brew install ffmpeg-full (macOS)sudo apt install ffmpeg libass-dev (Ubuntu) |
These are automatically installed by the install script:
yt-dlp- YouTube downloaderpysrt- SRT subtitle parserpython-dotenv- Environment variable management
macOS users: The standard ffmpeg package from Homebrew does NOT include libass support (required for subtitle burning). You must install ffmpeg-full:
# Remove standard ffmpeg (if installed)
brew uninstall ffmpeg
# Install ffmpeg-full (includes libass)
brew install ffmpeg-fullVerify libass support:
ffmpeg -filters 2>&1 | grep subtitles
# Should output: subtitles V->V (...)Simply tell Claude to clip a YouTube video:
Clip this YouTube video: https://youtube.com/watch?v=VIDEO_ID
or
剪辑这个 YouTube 视频：https://youtube.com/watch?v=VIDEO_ID
- Environment Check - Verifies yt-dlp, FFmpeg, and Python dependencies
- Video Download - Downloads video (up to 1080p) and English subtitles
- AI Chapter Analysis - Claude analyzes subtitles to generate semantic chapters (2-5 min each)
- User Selection - Choose which chapters to clip and processing options
- Processing - Clips video, translates subtitles, burns subtitles (if requested)
- Output - Organized files in
./youtube-clips/<timestamp>/
For each clipped chapter:
./youtube-clips/20260122_143022/
└── Chapter_Title/
├── Chapter_Title_clip.mp4 # Original clip (no subtitles)
├── Chapter_Title_with_subtitles.mp4 # With burned subtitles
├── Chapter_Title_bilingual.srt # Bilingual subtitle file
└── Chapter_Title_summary.md # Social media content
The skill uses environment variables for customization. Edit ~/.claude/skills/youtube-clipper/.env:
# FFmpeg path (auto-detected if empty)
FFMPEG_PATH=
# Output directory (default: current working directory)
OUTPUT_DIR=./youtube-clips
# Video quality limit (720, 1080, 1440, 2160)
MAX_VIDEO_HEIGHT=1080
# Translation batch size (20-25 recommended)
TRANSLATION_BATCH_SIZE=20
# Target language for translation
TARGET_LANGUAGE=中文
# Target chapter duration in seconds (180-300 recommended)
TARGET_CHAPTER_DURATION=180For full configuration options, see .env.example.
Input:
Clip this video: https://youtube.com/watch?v=Ckt1cj0xjRM
Output (AI-generated chapters):
1. [00:00 - 03:15] AGI as an exponential curve, not a point in time
2. [03:15 - 06:30] China's gap in AI development
3. [06:30 - 09:45] The impact of chip bans
...
Result: Select chapters → Get clipped videos with bilingual subtitles + social media content
Input:
Clip this lecture video and create bilingual subtitles: https://youtube.com/watch?v=LECTURE_ID
Options:
- Generate bilingual subtitles: Yes
- Burn subtitles into video: Yes
- Generate summary: Yes
Result: High-quality clips ready for sharing on social media platforms
Unlike mechanical time-based splitting, this skill uses Claude's AI to:
- Understand content semantics
- Identify natural topic transitions
- Generate meaningful chapter titles and summaries
- Ensure complete coverage with no gaps
Example:
❌ Mechanical splitting: [0:00-30:00], [30:00-60:00]
✅ AI semantic analysis:
- [00:00-03:15] AGI definition
- [03:15-07:30] China's AI landscape
- [07:30-12:00] Chip ban impacts
Translates 20 subtitles at once instead of one-by-one:
- 95% reduction in API calls
- 10x faster translation
- Better translation consistency
Generated subtitle files contain both English and Chinese:
1
00:00:00,000 --> 00:00:03,500
This is the English subtitle
这是中文字幕
2
00:00:03,500 --> 00:00:07,000
Another English line
另一行中文Error: Option not found: subtitles or filter not found
Solution: Install ffmpeg-full (macOS) or ensure libass-dev is installed (Ubuntu):
# macOS
brew uninstall ffmpeg
brew install ffmpeg-full
# Ubuntu
sudo apt install ffmpeg libass-devSolution: Set a proxy in .env:
YT_DLP_PROXY=http://proxy-server:port
# or
YT_DLP_PROXY=socks5://proxy-server:portCause: API rate limiting or network issues
Solution: The skill automatically retries up to 3 times. If persistent, check:
- Network connectivity
- Claude API status
- Reduce
TRANSLATION_BATCH_SIZEin.env
Issue: Filenames with :, /, ?, etc. may cause errors
Solution: The skill automatically sanitizes filenames by:
- Removing special characters:
/ \ : * ? " < > | - Replacing spaces with underscores
- Limiting length to 100 characters
- SKILL.md - Complete workflow and technical details
- TECHNICAL_NOTES.md - Implementation notes and design decisions
- FIXES_AND_IMPROVEMENTS.md - Changelog and bug fixes
- references/ - FFmpeg, yt-dlp, and subtitle formatting guides
Contributions are welcome! Please:
- Report bugs via GitHub Issues
- Submit feature requests
- Open pull requests for improvements
This project is licensed under the MIT License - see the LICENSE file for details.
- Claude Code - The AI-powered CLI tool
- yt-dlp - YouTube download engine
- FFmpeg - Video processing powerhouse
Made with ❤️ by op7418
If this skill helps you, please give it a ⭐️