skill

video-extractor-skill

rmarchiori/video-extractor-skillcommunitylistedunreviewed

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/rmarchiori/video-extractor-skill itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 23, 2026

Video Extractor Skill

Cross-platform video analysis tool for extracting audio transcripts and intelligently sampled frames with synchronized timestamps from video files.

Initial Release (v1.0.0): Time-range extraction, state management with resume capability, and enhanced security validation!

Claude Code Skill

This is an official Claude Code Skill that enables Claude to analyze video content through automated extraction of audio transcripts and visual frames. The skill is automatically activated when users request video analysis tasks.

Skill Definition: See SKILL.md for the complete skill specification including:

Activation triggers and usage patterns
Detailed instructions for Claude
Configuration options and examples
Integration workflows

Features

🎵 Audio Processing: Extract and transcribe audio using OpenAI Whisper with precise timestamps
🖼️ Smart Frame Extraction: Intelligent similarity filtering to keep only unique frames
⏱️ Real-Time Progress Tracking: Visual progress bars for audio extraction, frame extraction, and filtering
🎬 Time-Range Extraction: Extract specific segments using --start, --end, or --duration
💾 State Management: Resume interrupted operations with automatic checkpoint recovery
🔗 Synchronized Timestamps: Frame timestamps align with transcript timestamps for rich contextual analysis
🎯 Flexible Modes: Audio-only, frames-only, or combined extraction
📝 Multiple Output Formats: TXT, JSON, SRT, VTT subtitles with timestamps
📁 Organized Output: Clean folder structure with timestamp-based naming
📊 Metadata Generation: Comprehensive JSON metadata linking visual and audio content by time
🛡️ Security Validation: Input validation with path traversal and command injection protection
💻 Cross-Platform: Works on Windows, macOS, and Linux
⚡ Performance Optimized: Default 10-second frame interval balances quality and speed

Why Timestamp Correlation Matters

The synchronized timestamps enable powerful contextual analysis:

UI/UX Design Reviews: Extract mockup screenshots at the exact moment they're discussed
Tutorial Analysis: Connect code demonstrations to verbal explanations
Meeting Analysis: Capture presentation slides with speaker context
Technical Presentations: Link architecture diagrams to technical explanations

See SKILL.md for detailed examples of timestamp correlation benefits.

Quick Start

Installation for Claude Code

Automated Installation (Recommended):

# Windows (PowerShell)
.\install-skill.ps1 -Type personal

# Unix/Linux/macOS
./install-skill.sh personal

This installs the skill for all your Claude Code projects. The skill will be automatically available when you ask Claude to analyze videos. See INSTALLATION-GUIDE.md for detailed instructions, testing guide, and troubleshooting.

Installation as Standalone Tool

1. Install FFmpeg:

Automated Installation (Recommended):

# Windows (PowerShell - Run as Administrator)
.\install-ffmpeg-windows.ps1

# Linux/macOS
chmod +x install-ffmpeg-unix.sh
./install-ffmpeg-unix.sh

The scripts automatically download, install, and configure FFmpeg for your system.

Manual Installation:

# Windows (Chocolatey)
choco install ffmpeg

# Windows (winget)
winget install ffmpeg

# macOS
brew install ffmpeg

# Linux (Debian/Ubuntu)
sudo apt-get install ffmpeg

# Linux (Fedora/RHEL)
sudo dnf install ffmpeg

2. Install Video Extractor Dependencies:

pip install -r requirements.txt

Note: This project is primarily a Claude Code skill. For standalone use, run the script directly with Python after installing dependencies.

Basic Usage

Extract both audio and frames:

python video_extractor.py video.mp4

Audio transcription only:

python video_extractor.py podcast.mp4 --audio-only

Frame extraction only:

python video_extractor.py presentation.mp4 --frames-only

Extract specific time range:

# Extract from 5 minutes to 10 minutes
python video_extractor.py video.mp4 --start 00:05:00 --end 00:10:00

# Extract first 30 seconds
python video_extractor.py video.mp4 --duration 30

# Extract 2 minutes starting from 1:30
python video_extractor.py video.mp4 --start 00:01:30 --duration 120

Custom settings:

python video_extractor.py video.mp4 --frame-interval 5 --whisper-model medium --output-dir ./output

Progress Tracking:

The tool now shows real-time progress for all operations:

🎵 Extracting audio ━━━━━━━━━━━━━━━━━━━╸━━━━━━ 65% • 1m 30s/2m 20s ⏳ 0:00:50
🎬 Extracting frames ━━━━━━━━━━━━━━━━━━━━━━━━━ 100% • 22m 10s/22m 14s ✓
🔍 Filtering frames ━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% • 132/132 • kept 4/133 ✓

Windows Users

This tool is fully compatible with Windows! Use PowerShell or Command Prompt:

# Basic usage
video-extractor C:\Videos\video.mp4

# With quotes for spaces
video-extractor "My Video (2024).mp4" --audio-only

# Custom output location
video-extractor video.mp4 --output-dir $env:USERPROFILE\output

Example Scripts:

Windows Batch: examples/basic_usage.bat
PowerShell: examples/basic_usage.ps1
Bash: examples/basic_usage.sh

Platform Support

Platform	Status	Notes
Windows 10/11	✅ Fully Supported	PowerShell, CMD, or Git Bash
macOS	✅ Fully Supported	Intel and Apple Silicon
Linux	✅ Fully Supported	Ubuntu, Debian, Fedora, Arch

Output Structure

video_output/
└── video_name/
    ├── video_name.mp3              # Extracted audio
    ├── video_name.txt              # Plain text transcript
    ├── video_name.json             # JSON transcript with timestamps
    ├── video_name.srt              # SRT subtitles
    ├── video_name.vtt              # WebVTT subtitles
    ├── frames/                     # Extracted frames
    │   ├── video_name_00_00_03_000.jpg
    │   ├── video_name_00_00_06_000.jpg
    │   └── frames_metadata.json
    └── SUMMARY.md                  # Processing summary

Documentation

Installation Guide - Detailed installation instructions for all platforms
Usage Guide - Command-line options and examples
Examples - Common usage patterns and workflows
Troubleshooting - Platform-specific troubleshooting and solutions

Command Line Options

Option	Description	Default
`video_path`	Path to input video file	(required)
`--output-dir`	Output directory	`video_output`
`--frame-interval`	Extract 1 frame every N seconds	`10`
`--similarity-threshold`	Frame similarity (0-1, higher = more filtering)	`0.7`
`--whisper-model`	Whisper model: tiny, base, small, medium, large	`base`
`--start, -s`	Start time (HH:MM:SS, MM:SS, or seconds)	-
`--end, -e`	End time (HH:MM:SS, MM:SS, or seconds)	-
`--duration, -d`	Duration from start (seconds or HH:MM:SS)	-
`--audio-only`	Extract and transcribe audio only	-
`--frames-only`	Extract frames only	-
`--no-similarity-filter`	Keep all frames without filtering	-

Run python video_extractor.py --help for complete options.

Requirements

Python 3.8+ - Download
FFmpeg - Media processing (Installation guide)
OpenAI Whisper - Installed automatically with pip install

Examples

High-quality audio transcription:

python video_extractor.py interview.mp4 --audio-only --whisper-model large

Extract highlights from long video:

# Extract the key presentation section (10:30 to 25:45)
python video_extractor.py webinar.mp4 --start 00:10:30 --end 00:25:45

Extract intro segment:

# Get first 2 minutes
python video_extractor.py video.mp4 --duration 120

High-frequency frame extraction:

python video_extractor.py tutorial.mp4 --frames-only --frame-interval 1

Keep all frames without filtering:

python video_extractor.py animation.mp4 --no-similarity-filter

Process multiple videos (PowerShell):

Get-ChildItem *.mp4 | ForEach-Object { python video_extractor.py $_.FullName }

More examples in docs/examples.md

Troubleshooting

Common issues and solutions:

Windows: FFmpeg not found → Add to PATH or reinstall
macOS: Command not found → Check pip installation location
Linux: Permission denied → Use --user flag or check permissions
All platforms: Out of memory → Use smaller Whisper model (tiny/base)

See docs/troubleshooting.md for comprehensive troubleshooting.

Development

Setup Development Environment

# Clone repository
git clone https://github.com/ricmarchiori/video-extractor-skill.git
cd video-extractor-skill

# Install development dependencies
pip install -r requirements-dev.txt

Running Quality Checks

Unix/Linux/macOS:

# Run all quality checks (lint + typecheck + tests)
./quality-check.sh quality

# Run individual checks
./quality-check.sh test          # Run tests with coverage
./quality-check.sh lint          # Run flake8 linter
./quality-check.sh typecheck     # Run mypy type checker
./quality-check.sh format        # Format code with black

# Or use Make
make quality                     # Run all quality checks
make test                        # Run tests only

Windows (PowerShell):

# Run all quality checks
.\quality-check.ps1 quality

# Run individual checks
.\quality-check.ps1 test         # Run tests with coverage
.\quality-check.ps1 lint         # Run flake8 linter
.\quality-check.ps1 typecheck    # Run mypy type checker
.\quality-check.ps1 format       # Format code with black

Quality Standards

Test Coverage: Minimum 70% code coverage required
Linting: Flake8 with max line length 100
Type Checking: Mypy type hints throughout
Code Formatting: Black code formatter

Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run quality checks (./quality-check.sh quality)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Please ensure all tests pass and code meets quality standards before submitting.

License

MIT License - see LICENSE for details.

Acknowledgments

OpenAI Whisper - Audio transcription
FFmpeg - Media processing
Pillow & ImageHash - Image processing