FrancoStino/video-content-extractor

Video Content Extractor

Overview

Automatically extracts key frames from MP4 video files at configurable time intervals, performs OCR text recognition on each frame, and generates a structured Markdown report. The report includes video metadata (duration, resolution, codecs) and frame-by-frame OCR transcripts with timestamp references.

This skill is designed for Codex CLI and requires FFmpeg and Tesseract OCR installed on the local machine.

When to Use This Skill

• Use when you need to extract text content from video presentations, lectures, or screencasts.
• Use when you want to create searchable transcripts from video files without embedded subtitles.
• Use when you need to analyze video content programmatically and generate structured summaries.
• Use when the user asks to "read what is on screen" or "extract the content from this video."

How It Works

Step 1: Analyze Video Metadata

The skill uses ffprobe to extract video metadata: duration, resolution, frame rate, codec information, and file size.

Step 2: Extract Key Frames

Using FFmpeg, the skill captures frames at the configured interval (default: every 30 seconds). Each frame is saved as a timestamped JPEG image.

Step 3: OCR Text Recognition

Each extracted frame is processed by Tesseract OCR. If the default PSM mode returns no meaningful text, it falls back to fully automatic page segmentation.

Step 4: Generate Markdown Report

All extracted data is assembled into a structured Markdown document.

Examples

Example 1: Basic Extraction

Agent prompt: Use the video-content-extractor skill to extract content from lecture.mp4

Output generates lecture.md and lecture_frames/ directory.

Example 2: Custom Interval

Parameters: video_path, output_dir, interval(seconds), lang Extract every 60 seconds with English-only OCR: python scripts/extract_video.py recording.mp4 ./output 60 eng

Example 3: Bilingual Content

Extract with default Chinese + English OCR: python scripts/extract_video.py lecture.mp4 . 15 chi_sim+eng

Best Practices

• Use shorter intervals (10-15s) for fast-paced content with frequent text changes.
• Use longer intervals (30-60s) for presentation slides or slow lectures to reduce duplicate frames.
• For Chinese content, ensure Tesseract Chinese language pack is installed (chi_sim).

Limitations

• Requires FFmpeg and Tesseract OCR to be installed and accessible via PATH.
• Tesseract OCR accuracy depends on video quality, text size, and font clarity.
• Does not extract audio or perform speech-to-text transcription.
• Frame extraction is time-based (not scene-change-based), which may produce near-duplicate frames.
• Large videos with short intervals can generate many frames - ensure sufficient disk space.

Security and Safety Notes

• This skill only reads video files and writes extracted frames and Markdown reports.
• It does NOT send any data over the network - all processing is local.
• FFmpeg and Tesseract are invoked with fixed, pre-vetted arguments.
• The skill does not modify or delete the original video file.

Common Pitfalls

• Problem: Tesseract returns garbled text Solution: Ensure the correct language pack is installed. Run tesseract --list-langs to verify.

• Problem: FFmpeg fails with "not found" Solution: Make sure FFmpeg is on PATH. Run ffmpeg -version to verify.

• Problem: OCR is slow on large videos Solution: Increase the interval parameter to reduce frames processed.

Related Skills

• @media-summarizer - For summarizing video content using visual and audio cues.
• @document-ocr - For OCR on static images or scanned documents without video processing.