{"id":"4895a5f8-876f-4401-87e0-8f5889d0fdd1","slug":"video-extractor-skill","kind":"skill","name":"video-extractor-skill","summary":"","owner":"rmarchiori","repoUrl":"https://github.com/rmarchiori/video-extractor-skill","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"skill","createdAt":"2025-10-24T16:35:46.000Z","addedAt":"2026-10-21T22:10:10.479Z","logoUrl":"https://avatars.githubusercontent.com/u/13880165?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["design-media"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T21:33:13.094Z","sample":false,"url":"https://conduits.dev/tools/video-extractor-skill","language":"Python","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Video Extractor Skill\n\n**Cross-platform video analysis tool** for extracting audio transcripts and intelligently sampled frames with synchronized timestamps from video files.\n\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![Cross-Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey.svg)]()\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Version](https://img.shields.io/badge/version-1.0.0-brightgreen.svg)]()\n\n**Initial Release (v1.0.0)**: Time-range extraction, state management with resume capability, and enhanced security validation!\n\n## Claude Code Skill\n\nThis 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.\n\n**Skill Definition**: See [SKILL.md](SKILL.md) for the complete skill specification including:\n- Activation triggers and usage patterns\n- Detailed instructions for Claude\n- Configuration options and examples\n- Integration workflows\n\n## Features\n\n- **🎵 Audio Processing**: Extract and transcribe audio using OpenAI Whisper with precise timestamps\n- **🖼️ Smart Frame Extraction**: Intelligent similarity filtering to keep only unique frames\n- **⏱️ Real-Time Progress Tracking**: Visual progress bars for audio extraction, frame extraction, and filtering\n- **🎬 Time-Range Extraction**: Extract specific segments using --start, --end, or --duration\n- **💾 State Management**: Resume interrupted operations with automatic checkpoint recovery\n- **🔗 Synchronized Timestamps**: Frame timestamps align with transcript timestamps for rich contextual analysis\n- **🎯 Flexible Modes**: Audio-only, frames-only, or combined extraction\n- **📝 Multiple Output Formats**: TXT, JSON, SRT, VTT subtitles with timestamps\n- **📁 Organized Output**: Clean folder structure with timestamp-based naming\n- **📊 Metadata Generation**: Comprehensive JSON metadata linking visual and audio content by time\n- **🛡️ Security Validation**: Input validation with path traversal and command injection protection\n- **💻 Cross-Platform**: Works on Windows, macOS, and Linux\n- **⚡ Performance Optimized**: Default 10-second frame interval balances quality and speed\n\n### Why Timestamp Correlation Matters\n\nThe synchronized timestamps enable powerful contextual analysis:\n- **UI/UX Design Reviews**: Extract mockup screenshots at the exact moment they're discussed\n- **Tutorial Analysis**: Connect code demonstrations to verbal explanations\n- **Meeting Analysis**: Capture presentation slides with speaker context\n- **Technical Presentations**: Link architecture diagrams to technical explanations\n\nSee [SKILL.md](SKILL.md) for detailed examples of timestamp correlation benefits.\n\n## Quick Start\n\n### Installation for Claude Code\n\n**Automated Installation (Recommended):**\n\n```bash\n# Windows (PowerShell)\n.\\install-skill.ps1 -Type personal\n\n# Unix/Linux/macOS\n./install-skill.sh personal\n```\n\nThis 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](docs/INSTALLATION-GUIDE.md) for detailed instructions, testing guide, and troubleshooting.\n\n### Installation as Standalone Tool\n\n**1. Install FFmpeg:**\n\n**Automated Installation (Recommended):**\n\n```powershell\n# Windows (PowerShell - Run as Administrator)\n.\\install-ffmpeg-windows.ps1\n\n# Linux/macOS\nchmod +x install-ffmpeg-unix.sh\n./install-ffmpeg-unix.sh\n```\n\nThe scripts automatically download, install, and configure FFmpeg for your system.\n\n**Manual Installation:**\n\n```powershell\n# Windows (Chocolatey)\nchoco install ffmpeg\n\n# Windows (winget)\nwinget install ffmpeg\n\n# macOS\nbrew install ffmpeg\n\n# Linux (Debian/Ubuntu)\nsudo apt-get install ffmpeg\n\n# Linux (Fedora/RHEL)\nsudo dnf install ffmpeg\n```\n\n**2. Install Video Extractor Dependencies:**\n\n```bash\npip install -r requirements.txt\n```\n\nNote: This project is primarily a Claude Code skill. For standalone use, run the script directly with Python after installing dependencies.\n\n### Basic Usage\n\n**Extract both audio and frames:**\n```bash\npython video_extractor.py video.mp4\n```\n\n**Audio transcription only:**\n```bash\npython video_extractor.py podcast.mp4 --audio-only\n```\n\n**Frame extraction only:**\n```bash\npython video_extractor.py presentation.mp4 --frames-only\n```\n\n**Extract specific time range:**\n```bash\n# Extract from 5 minutes to 10 minutes\npython video_extractor.py video.mp4 --start 00:05:00 --end 00:10:00\n\n# Extract first 30 seconds\npython video_extractor.py video.mp4 --duration 30\n\n# Extract 2 minutes starting from 1:30\npython video_extractor.py video.mp4 --start 00:01:30 --duration 120\n```\n\n**Custom settings:**\n```bash\npython video_extractor.py video.mp4 --frame-interval 5 --whisper-model medium --output-dir ./output\n```\n\n**Progress Tracking:**\n\nThe tool now shows real-time progress for all operations:\n```\n🎵 Extracting audio ━━━━━━━━━━━━━━━━━━━╸━━━━━━ 65% • 1m 30s/2m 20s ⏳ 0:00:50\n🎬 Extracting frames ━━━━━━━━━━━━━━━━━━━━━━━━━ 100% • 22m 10s/22m 14s ✓\n🔍 Filtering frames ━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% • 132/132 • kept 4/133 ✓\n```\n\n## Windows Users\n\nThis tool is fully compatible with Windows! Use PowerShell or Command Prompt:\n\n```powershell\n# Basic usage\nvideo-extractor C:\\Videos\\video.mp4\n\n# With quotes for spaces\nvideo-extractor \"My Video (2024).mp4\" --audio-only\n\n# Custom output location\nvideo-extractor video.mp4 --output-dir $env:USERPROFILE\\output\n```\n\n**Example Scripts:**\n- Windows Batch: `examples/basic_usage.bat`\n- PowerShell: `examples/basic_usage.ps1`\n- Bash: `examples/basic_usage.sh`\n\n## Platform Support\n\n| Platform | Status | Notes |\n|----------|--------|-------|\n| Windows 10/11 | ✅ Fully Supported | PowerShell, CMD, or Git Bash |\n| macOS | ✅ Fully Supported | Intel and Apple Silicon |\n| Linux | ✅ Fully Supported | Ubuntu, Debian, Fedora, Arch |\n\n## Output Structure\n\n```\nvideo_output/\n└── video_name/\n    ├── video_name.mp3              # Extracted audio\n    ├── video_name.txt              # Plain text transcript\n    ├── video_name.json             # JSON transcript with timestamps\n    ├── video_name.srt              # SRT subtitles\n    ├── video_name.vtt              # WebVTT subtitles\n    ├── frames/                     # Extracted frames\n    │   ├── video_name_00_00_03_000.jpg\n    │   ├── video_name_00_00_06_000.jpg\n    │   └── frames_metadata.json\n    └── SUMMARY.md                  # Processing summary\n```\n\n## Documentation\n\n- **[Installation Guide](docs/installation.md)** - Detailed installation instructions for all platforms\n- **[Usage Guide](docs/usage.md)** - Command-line options and examples\n- **[Examples](docs/examples.md)** - Common usage patterns and workflows\n- **[Troubleshooting](docs/troubleshooting.md)** - Platform-specific troubleshooting and solutions\n\n## Command Line Options\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `video_path` | Path to input video file | (required) |\n| `--output-dir` | Output directory | `video_output` |\n| `--frame-interval` | Extract 1 frame every N seconds | `10` |\n| `--similarity-threshold` | Frame similarity (0-1, higher = more filtering) | `0.7` |\n| `--whisper-model` | Whisper model: tiny, base, small, medium, large | `base` |\n| `--start, -s` | Start time (HH:MM:SS, MM:SS, or seconds) | - |\n| `--end, -e` | End time (HH:MM:SS, MM:SS, or seconds) | - |\n| `--duration, -d` | Duration from start (seconds or HH:MM:SS) | - |\n| `--audio-only` | Extract and transcribe audio only | - |\n| `--frames-only` | Extract frames only | - |\n| `--no-similarity-filter` | Keep all frames without filtering | - |\n\nRun `python video_extractor.py --help` for complete options.\n\n## Requirements\n\n- **Python 3.8+** - [Download](https://www.python.org/downloads/)\n- **FFmpeg** - Media processing ([Installation guide](docs/installation.md))\n- **OpenAI Whisper** - Installed automatically with `pip install`\n\n## Examples\n\n**High-quality audio transcription:**\n```bash\npython video_extractor.py interview.mp4 --audio-only --whisper-model large\n```\n\n**Extract highlights from long video:**\n```bash\n# Extract the key presentation section (10:30 to 25:45)\npython video_extractor.py webinar.mp4 --start 00:10:30 --end 00:25:45\n```\n\n**Extract intro segment:**\n```bash\n# Get first 2 minutes\npython video_extractor.py video.mp4 --duration 120\n```\n\n**High-frequency frame extraction:**\n```bash\npython video_extractor.py tutorial.mp4 --frames-only --frame-interval 1\n```\n\n**Keep all frames without filtering:**\n```bash\npython video_extractor.py animation.mp4 --no-similarity-filter\n```\n\n**Process multiple videos (PowerShell):**\n```powershell\nGet-ChildItem *.mp4 | ForEach-Object { python video_extractor.py $_.FullName }\n```\n\nMore examples in [docs/examples.md](docs/examples.md)\n\n## Troubleshooting\n\nCommon issues and solutions:\n\n- **Windows**: FFmpeg not found → Add to PATH or reinstall\n- **macOS**: Command not found → Check pip installation location\n- **Linux**: Permission denied → Use `--user` flag or check permissions\n- **All platforms**: Out of memory → Use smaller Whisper model (tiny/base)\n\nSee [docs/troubleshooting.md](docs/troubleshooting.md) for comprehensive troubleshooting.\n\n## Development\n\n### Setup Development Environment\n\n```bash\n# Clone repository\ngit clone https://github.com/ricmarchiori/video-extractor-skill.git\ncd video-extractor-skill\n\n# Install development dependencies\npip install -r requirements-dev.txt\n```\n\n### Running Quality Checks\n\n**Unix/Linux/macOS:**\n```bash\n# Run all quality checks (lint + typecheck + tests)\n./quality-check.sh quality\n\n# Run individual checks\n./quality-check.sh test          # Run tests with coverage\n./quality-check.sh lint          # Run flake8 linter\n./quality-check.sh typecheck     # Run mypy type checker\n./quality-check.sh format        # Format code with black\n\n# Or use Make\nmake quality                     # Run all quality checks\nmake test                        # Run tests only\n```\n\n**Windows (PowerShell):**\n```powershell\n# Run all quality checks\n.\\quality-check.ps1 quality\n\n# Run individual checks\n.\\quality-check.ps1 test         # Run tests with coverage\n.\\quality-check.ps1 lint         # Run flake8 linter\n.\\quality-check.ps1 typecheck    # Run mypy type checker\n.\\quality-check.ps1 format       # Format code with black\n```\n\n### Quality Standards\n\n- **Test Coverage**: Minimum 70% code coverage required\n- **Linting**: Flake8 with max line length 100\n- **Type Checking**: Mypy type hints throughout\n- **Code Formatting**: Black code formatter\n\n## Contributing\n\nContributions are welcome! Please follow these steps:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Run quality checks (`./quality-check.sh quality`)\n5. Commit your changes (`git commit -m 'Add amazing feature'`)\n6. Push to the branch (`git push origin feature/amazing-feature`)\n7. Open a Pull Request\n\nPlease ensure all tests pass and code meets quality standards before submitting.\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n## Acknowledgments\n\n- [OpenAI Whisper](https://github.com/openai/whisper) - Audio transcription\n- [FFmpeg](https://ffmpeg.org/) - Media processing\n- [Pillow](https://python-pillow.org/) & [ImageHash](https://github.com/JohannesBuchner/imagehash) - Image processing\n"}