This project provides a Claude AI skill that enables it to process and analyze video content. It addresses the limitation of AI models being unable to directly consume video by extracting key visual and auditory information, generating structured reports, and optionally integrating with knowledge management systems like Obsidian. This empowers users to quickly understand video content, analyze specific segments, or diagnose issues from recordings.

How It Works

The core pipeline leverages yt-dlp for video downloading and ffmpeg for frame extraction. It prioritizes free, native video captions for transcription, falling back to the Whisper API (Groq or OpenAI) when captions are unavailable. A key innovation is scene-change frame extraction, capturing one frame per detected cut rather than fixed intervals, which optimizes token usage for longer videos. The initial 10 seconds undergo a "hook microscope" analysis with dense frames and word-level transcription to dissect video openings. Claude then processes these frames and transcripts to generate a structured report.

Quick Start & Requirements

• Installation:
  • Claude Code: /plugin marketplace add taoufik123-collab/claude-watch followed by /plugin install watch@claude-watch.
  • claude.ai (web): Download the watch.skill file from the latest release and upload it via Settings → Capabilities → Skills. Requires "Code execution and file creation" to be enabled.
  • Codex: git clone https://github.com/taoufik123-collab/claude-watch.git ~/.codex/skills/watch.
• Prerequisites: ffmpeg and yt-dlp are required. Installation is automated via brew on macOS; Linux/Windows users receive specific command-line instructions on first run. An API key for Groq (preferred) or OpenAI Whisper is needed for videos lacking native captions.
• Configuration: An optional WATCH_VAULT_DIR environment variable can be set to enable Obsidian auto-save, with automatic detection of common vault locations.
• Links: Repository: https://github.com/taoufik123-collab/claude-watch

Highlighted Details

• Scene-Change Frame Extraction: Utilizes ffmpeg's scene detection (select=gt(scene,...)) to extract frames only at shot changes, bounding token costs irrespective of video duration.
• 0-10s Hook Microscope: Analyzes the critical opening seconds with a denser frame rate (up to 2 fps) and word-level Whisper transcription to detail how a video captures attention.
• Structured Reports: Generates report.md files with explicit <!-- pending Claude fill: ... --> markers, guiding Claude's analysis process.
• Optional Obsidian Auto-Save: Integrates with Obsidian vaults by staging processed reports and offering wiki ingest, creating connected knowledge entries.

Maintenance & Community

Contributors are listed in AUTHORS.md. The project utilizes GitHub Actions for automated building and releasing of the watch.skill bundle upon tag pushes. Specific community channels (e.g., Discord, Slack) or roadmaps are not detailed in the provided documentation.

Licensing & Compatibility

The project is released under the MIT License, inheriting its permissive terms from the claude-video project it extends. This license permits commercial use and integration into closed-source applications without significant restrictions.

Limitations & Caveats

Accuracy is best for videos under 10 minutes; longer content may require focused analysis using --start/--end flags due to a "sparse scan" warning. Hard technical limits include a maximum of 2 frames per second and 100 frames per video. The Whisper API has a 25MB audio upload limit (approximately 50 minutes), necessitating native captions or focused analysis for longer audio tracks. The skill only supports public URLs accessible via yt-dlp and local files, excluding private or authenticated platforms.