/video-processor

name: video-processor
description: Download and process videos from YouTube and other platforms. Supports video download, audio extraction, format conversion (mp4, webm), and Whisper transcription. Use when user mentions YouTube download, video conversion, audio extraction, transcription, mp4, webm, ffmpeg, yt-dlp, or whisper transcription.
metadata:
  author: iamzhihuix
  version: "1.0.0"

Video Processor

Instructions

This skill provides comprehensive video processing utilities including YouTube video download, audio extraction, format conversion, and audio transcription using yt-dlp, FFmpeg, and OpenAI's Whisper model.

Prerequisites

**Required tools** (must be installed in your environment):

• **yt-dlp**: Video downloader for YouTube and thousands of other sites

  # Install via pip
  pip install -U yt-dlp

  # Verify installation
  yt-dlp --version

• **FFmpeg**: Multimedia framework for video/audio processing

  # macOS
  brew install ffmpeg

  # Ubuntu/Debian
  apt-get install ffmpeg

  # Verify installation
  ffmpeg -version

• **OpenAI Whisper**: Speech-to-text transcription model

  # Install via pip
  pip install -U openai-whisper

  # Verify installation
  whisper --help

**Python packages** (included in script via PEP 723):

• click (CLI framework)
• ffmpeg-python (Python wrapper for FFmpeg)
• yt-dlp (video downloader)

Workflow

Use the `scripts/video_processor.py` script for all video processing tasks. The script provides a simple CLI with the following commands:

0. **Download Video from YouTube or Other Platforms** (NEW!)

Download videos from YouTube and thousands of other supported websites:

# Download video
uv run .claude/skills/video-processor/scripts/video_processor.py download "https://youtube.com/watch?v=..." output.mp4

# Download audio only (as MP3)
uv run .claude/skills/video-processor/scripts/video_processor.py download "https://youtube.com/watch?v=..." --audio-only

# Show video info without downloading
uv run .claude/skills/video-processor/scripts/video_processor.py download "https://youtube.com/watch?v=..." --info

# Download with subtitles
uv run .claude/skills/video-processor/scripts/video_processor.py download "https://youtube.com/watch?v=..." output.mp4 --subtitle

Options:

• `--audio-only`: Download audio only (extracts to MP3)
• `--subtitle`: Download and embed subtitles (supports en, zh-Hans, zh-Hant)
• `--info`: Show video information without downloading
• `--format`: Specify video format preference (default: best quality)

1. **Extract Audio from Video**

Extract the audio track from a video file:

uv run .claude/skills/video-processor/scripts/video_processor.py extract-audio input.mp4 output.wav

Options:

• `--format`: Output audio format (default: wav). Supports: wav, mp3, aac, flac
• Output is suitable for transcription or standalone audio use

2. **Convert Video to MP4**

Convert any video file to MP4 format:

uv run .claude/skills/video-processor/scripts/video_processor.py to-mp4 input.avi output.mp4

Options:

• `--codec`: Video codec (default: libx264). Common options: libx264, libx265, h264
• `--preset`: Encoding speed/quality preset (default: medium). Options: ultrafast, fast, medium, slow, veryslow

3. **Convert Video to WebM**

Convert any video file to WebM format (web-optimized):

uv run .claude/skills/video-processor/scripts/video_processor.py to-webm input.mp4 output.webm

Options:

• `--codec`: Video codec (default: libvpx-vp9). Options: libvpx, libvpx-vp9
• WebM is optimized for web playback and streaming

4. **Transcribe Audio with Whisper**

Transcribe audio or video files to text using OpenAI's Whisper model:

# Transcribe video file (audio will be extracted automatically)
uv run .claude/skills/video-processor/scripts/video_processor.py transcribe input.mp4 transcript.txt

# Transcribe audio file directly
uv run .claude/skills/video-processor/scripts/video_processor.py transcribe audio.wav transcript.txt

Options:

• `--model`: Whisper model size (default: base). Options:
• `tiny`: Fastest, lowest accuracy (~1GB RAM)
• `base`: Fast, good accuracy (~1GB RAM) **[DEFAULT]**
• `small`: Balanced (~2GB RAM)
• `medium`: High accuracy (~5GB RAM)
• `large`: Best accuracy, slowest (~10GB RAM)
• `--language`: Language code (default: auto-detect). Examples: en, es, fr, de, zh
• `--format`: Output format (default: txt). Options: txt, srt, vtt, json

**Transcription workflow:** 1. If input is video, FFmpeg extracts audio to temporary WAV file 2. Whisper processes the audio file 3. Transcription is saved in requested format 4. Temporary files are cleaned up automatically

5. **Combined Workflow Example**

Process a video end-to-end:

# 1. Extract audio for analysis
uv run .claude/skills/video-processor/scripts/video_processor.py extract-audio lecture.mp4 lecture.wav

# 2. Transcribe to SRT subtitles
uv run .claude/skills/video-processor/scripts/video_processor.py transcribe lecture.mp4 lecture.srt --format srt --model small

# 3. Convert to web format
uv run .claude/skills/video-processor/scripts/video_processor.py to-webm lecture.mp4 lecture.webm

Key Technical Details

**FFmpeg and Whisper Integration:**

• FFmpeg doesn't transcribe audio itself - it prepares audio for external transcription
• The workflow is: Extract audio (FFmpeg) → Transcribe (Whisper) → Optional: Re-integrate with video
• FFmpeg can pipe audio directly to Whisper for real-time processing (advanced use case)

**Audio Format for Transcription:**

• Whisper works best with WAV or MP3 formats
• Sample rate: 16kHz is optimal (script handles conversion automatically)
• The script extracts audio with optimal settings for Whisper

**Output Formats:**

• **txt**: Plain text transcript
• **srt**: SubRip subtitle format (includes timestamps)
• **vtt**: WebVTT subtitle format (web standard)
• **json**: Detai