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:

• If input is video, FFmpeg extracts audio to temporary WAV file

• Whisper processes the audio file

• Transcription is saved in requested format

• 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: Detailed JSON with word-level timestamps

Error Handling

The script includes comprehensive error handling:

• Validates input files exist

• Checks FFmpeg and Whisper are installed

• Provides clear error messages for missing dependencies

• Handles temporary file cleanup on errors

Performance Tips

• Use tiny or base models for quick drafts

• Use small or medium for production transcriptions

• Use large only when maximum accuracy is required

• For long videos, consider extracting audio first, then transcribe in segments

• WebM conversion with VP9 takes longer but produces smaller files

Examples

Example 1: Quick Video to MP4 Conversion

User request:

I have an AVI file from my old camera. Can you convert it to MP4?

You would:

• Use the to-mp4 command with default settings: uv run .claude/skills/video-processor/scripts/video_processor.py to-mp4 old_video.avi output.mp4

• Confirm the conversion completed successfully

• Inform the user about the output file location

Example 2: Extract Audio and Transcribe

User request:

I recorded a lecture video and need a transcript. Can you extract the audio and transcribe it?

You would:

• First extract the audio: uv run .claude/skills/video-processor/scripts/video_processor.py extract-audio lecture.mp4 lecture.wav

• Then transcribe using the base model (good balance of speed/accuracy): uv run .claude/skills/video-processor/scripts/video_processor.py transcribe lecture.mp4 transcript.txt --model base

• Share the transcript.txt file with the user

Example 3: Create Web-Optimized Video with Subtitles

User request:

I need to put this video on my website with subtitles. Can you help?

You would:

• Convert to WebM for web optimization: uv run .claude/skills/video-processor/scripts/video_processor.py to-webm presentation.mp4 presentation.webm

• Generate SRT subtitle file: uv run .claude/skills/video-processor/scripts/video_processor.py transcribe presentation.mp4 subtitles.srt --format srt --model small

• Inform user they now have:

• presentation.webm (web-optimized video)

• subtitles.srt (subtitle file for embedding)

Example 4: High-Quality Transcription with Language Specification

User request:

I have a Spanish interview video that needs an accurate transcript for publication.

You would:

• Use a larger model with language specified for best accuracy: uv run .claude/skills/video-processor/scripts/video_processor.py transcribe interview.mp4 transcript.txt --model medium --language es

• Optionally create SRT for review: uv run .claude/skills/video-processor/scripts/video_processor.py transcribe interview.mp4 transcript.srt --format srt --model medium --language es

• Review the transcript with the user and make any necessary corrections

Example 5: Batch Processing Multiple Videos

User request:

I have a folder of training videos that all need to be converted to WebM and transcribed.

You would:

• List all video files in the directory: ls training_videos/*.mp4

• For each video file, run the conversion and transcription:

For each video: video1.mp4, video2.mp4, etc.

uv run .claude/skills/video-processor/scripts/video_processor.py to-webm training_videos/video1.mp4 output/video1.webm uv run .claude/skills/video-processor/scripts/video_processor.py transcribe training_videos/video1.mp4 output/video1.txt --model base

Repeat for each file

• Confirm all conversions and transcriptions completed

• Provide summary of output files

Summary

The video-processor skill provides a unified interface for common video processing tasks:

• Audio extraction: Extract audio tracks in various formats

• Format conversion: Convert to MP4 (universal) or WebM (web-optimized)

• Transcription: Speech-to-text with multiple output formats

• Flexible: CLI arguments for model selection, language, and output formats

All operations are handled through a single, well-documented script with sensible defaults and comprehensive error handling.