Content
# Video-Learn-MCP
Claude Code plugin — Learn from videos. Automatically download videos, extract key frames, transcribe audio to text, and pair images with text to help you efficiently learn video course content.
## Supported Video Sources
| Platform | Support Status |
|------|----------|
| Local Video Files | Fully Supported |
| YouTube | Fully Supported |
| Bilibili | Fully Supported |
## Installation
### Plugin Installation (Recommended)
```bash
# 1. Add plugin repository
claude plugin marketplace add zyunyi0612/video-learn-mcp
# 2. Install plugin
claude plugin install video-learn
```
After installation, restart Claude Code, and MCP Server and `/video-learn` Skill will be automatically loaded without manual configuration.
### External Dependencies (Auto-Detected)
When running `/video-learn` for the first time, the Skill will automatically detect if the following dependencies are installed. If any are missing, they will be automatically installed:
| Dependency | Purpose | Auto-Installation Method |
|------|------|-------------|
| ffmpeg | Video frame extraction, audio extraction | `brew install ffmpeg` / `apt-get install ffmpeg` |
| yt-dlp | Download YouTube/Bilibili videos | `pip3 install yt-dlp[default]` |
| faster-whisper | Audio transcription | `pip3 install faster-whisper` |
| cryptography | YouTube cookies auto-export | `pip3 install cryptography` |
| certifi | Resolve macOS SSL certificate issues | `pip3 install certifi` |
> Python 3.10+ is required (faster-whisper requires). Python 3.12+ pip installation will automatically add the `--break-system-packages` parameter.
If you want to manually install in advance, you can run:
```bash
# macOS
brew install ffmpeg
pip3 install yt-dlp faster-whisper cryptography certifi
# Linux
sudo apt-get install ffmpeg
pip3 install yt-dlp faster-whisper cryptography certifi
```
### Manual Installation (Without Plugin System)
If you don't want to install via the plugin system, you can manually install:
```bash
git clone https://github.com/zyunyi0612/video-learn-mcp.git ~/video-learn-mcp
cd ~/video-learn-mcp
chmod +x install.sh
./install.sh
```
The installation script will automatically handle all dependencies, compilation, MCP configuration, and Skill installation.
## Usage
In Claude Code, enter:
```
/video-learn https://www.youtube.com/watch?v=xxxxx
/video-learn /path/to/local/video.mp4
/video-learn https://www.bilibili.com/video/BVxxxxx
```
### Optional Parameters
```
/video-learn <URL> --model large-v3 # Specify Whisper model
/video-learn <URL> --interval 10 # Frame extraction interval (seconds)
/video-learn <URL> --smart # Intelligent scene detection frame extraction
/video-learn <URL> --lang en # Specify language
/video-learn <URL> --proxy http://127.0.0.1:7890 # Proxy address
```
## Workflow
After using the `/video-learn` command, the Skill will **step-by-step call** MCP tools through the task system, and display progress in real-time after each step:
```
[Task 1] Dependency check (video-check-deps) → Auto-detect and install missing dependencies
[Task 2] Video download (video-download) → Report video title, duration
[Task 3] Key frame extraction (video-extract-frames) → Report frame extraction count
[Task 4] Audio transcription (video-transcribe) → Report transcription segments, language, text preview
[Task 5] Image-text pairing (video-assemble) → Report paired groups
Analysis + Generate learning notes → Output notes.md
```
Each task is managed through TaskCreate/TaskUpdate to ensure strict sequential execution and no repeated calls.
Each MCP tool has a built-in **Lock file + Fingerprint** idempotent mechanism: repeated calls with the same parameters will automatically return cached results and not execute time-consuming operations repeatedly. Lock files are marked as `done` after task completion instead of being deleted to ensure subsequent repeated calls can immediately hit the cache.
## MCP Tools
| Tool Name | Function |
|--------|------|
| `video-check-deps` | Check if system dependencies are installed (ffmpeg, yt-dlp, Python 3.10+, faster-whisper, etc.) |
| `video-download` | Download or obtain video files |
| `video-extract-frames` | Extract key frame images from videos |
| `video-transcribe` | Transcribe video audio into timestamped text |
| `video-assemble` | Pair extracted frames with transcribed text by timestamp |
## Output Structure
```
~/Downloads/video-learn/2026-04-21_Video_Title/
├── Video_Title.mp4 # Downloaded video
├── frames/ # Extracted frame images
│ ├── frame_00001.png
│ └── ...
├── transcript/ # Transcription results
│ └── transcript.json
├── paired_results.json # Image-text paired data
└── notes.md # AI-generated learning notes
```
## Configuration
Edit `config.json` in the plugin directory (or the project root directory during manual installation):
```json
{
"whisper": {
"model": "large-v3",
"language": "zh",
"device": "auto",
"compute_type": "int8"
},
"extractor": {
"mode": "interval",
"interval_seconds": 5,
"scene_threshold": 0.3
},
"output": {
"base_dir": "~/Downloads/video-learn",
"keep_video": true
},
"downloader": {
"proxy": "",
"cookies_file": "",
"max_resolution": "1080p"
}
}
```
### Whisper Model Selection
| Model | Speed | Accuracy | Applicable Scenarios |
|------|------|--------|----------|
| `small` | Fast | General | Quick processing |
| `medium` | Medium | High | Balanced choice |
| `large-v3` | Slow | Highest | Many proper nouns, high accuracy required |
## System Requirements
- macOS or Linux
- Python 3.10+
- Node.js 18+
- Approximately 1-3GB disk space (Whisper model cache)
## Frequently Asked Questions
**Q: pip3 install reports "externally-managed-environment"?**
A: Python 3.12+ requires adding the `--break-system-packages` parameter. The Skill's automatic installation has handled this issue. Please add this parameter during manual installation.
**Q: yt-dlp installation not found?**
A: pip-installed executable files may not be in PATH. The Skill will automatically create a soft link to `~/.local/bin/`. Manual solution: `export PATH="$HOME/.local/bin:$PATH"`
**Q: YouTube download fails?**
A: Requires Chrome browser login to Google account, and the plugin will automatically read cookies.
**Q: Bilibili high-definition video download fails?**
A: Some high-definition videos require login. After logging in to Bilibili, set the `cookies_file` path in `config.json`.
**Q: Transcription speed is slow?**
A: Change `whisper.model` to `small`, sacrificing accuracy for speed.
**Q: Too many or too few frame images?**
A: Adjust `extractor.interval_seconds` or use `"mode": "smart"` for automatic scene change detection.
## License
MIT
