Video Requirement Infer

Small local utility for repeated video requirement reviews.

It does the boring parts consistently:

• probe the video
• extract audio with ffmpeg
• transcribe with faster-whisper
• sample frames on a fixed interval
• extract scene-change frames
• build contact sheets
• generate a markdown file with requirement-like transcript lines (when requirement patterns are configured)
• apply custom term mappings for transcript normalization (optional)

It can also run as a local MCP server so Codex/Claude-style clients can call it as a tool.

Run

uv run --project projects/video_requirement_infer \
python projects/video_requirement_infer/analyze_video.py \
--input "/home/ukd/Downloads/Auftrag - Projekt.mp4" \
--output /tmp/auftrag_review \
--sample-interval 30 \
--model base.en \
--language en

Trim Video Segments

Process only a specific time range (e.g., last 3 minutes of a 10-minute video):

uv run --project projects/video_requirement_infer \
python projects/video_requirement_infer/analyze_video.py \
--input "/path/to/video.mp4" \
--output /tmp/review_last_3min \
--start-time 420 \
--end-time 600 \
--sample-interval 30 \
--model base.en \
--language en

Optional: Custom Term Mapping

Apply custom term substitutions to normalize domain-specific vocabulary in transcripts:

echo '{"legacy_api": "modern_api", "abbr": "abbreviation"}' > /tmp/terms.json

uv run --project projects/video_requirement_infer \
python projects/video_requirement_infer/analyze_video.py \
--input "/path/to/video.mp4" \
--output /tmp/review \
--term-map /tmp/terms.json

When not provided: No term normalization is applied; the normalized transcript matches the raw transcript.

Optional: Custom Requirement Patterns

Customize which keywords trigger requirement detection in transcript lines:

echo '["must", "should", "need", "require", "mandatory"]' > /tmp/patterns.json

uv run --project projects/video_requirement_infer \
python projects/video_requirement_infer/analyze_video.py \
--input "/path/to/video.mp4" \
--output /tmp/review \
--requirement-patterns /tmp/patterns.json

When not provided: No requirement candidate detection is performed; requirements_candidates.md will be empty.

Configuration Examples

Example configuration files are provided in the examples/ directory:

• examples/term_map.json - Example term mapping format
• examples/requirement_patterns.json - Example requirement patterns format

Copy and customize these for your domain:

cp examples/term_map.json my_project_terms.json
cp examples/requirement_patterns.json my_project_patterns.json
# Edit the files for your specific domain

Run As MCP

uv run --project /home/ukd/projects/video_requirement_infer \
  python /home/ukd/projects/video_requirement_infer/mcp_server.py

Example Codex registration:

codex mcp add video-requirement-infer -- \
  uv run --project /home/ukd/projects/video_requirement_infer \
  python /home/ukd/projects/video_requirement_infer/mcp_server.py

Output

The output folder contains:

• metadata.json
• audio.wav
• transcript_raw.txt
• transcript_normalized.txt
• requirements_candidates.md
• analysis_report.md
• frames_interval/
• frames_scene/
• contact_sheet_interval.jpg
• contact_sheet_scene.jpg

Notes

• ffmpeg and ffprobe must be installed on the machine.
• The tool extracts transcripts, samples frames, and optionally normalizes terms and detects requirement patterns based on your configuration.
• Term mapping and requirement patterns are optional - if not provided, the tool will still transcribe and extract frames, but skip normalization and requirement detection.
• This tool prepares evidence; final product decisions still need human review.
• MCP tool returns compact summaries plus artifact paths, not the full raw blobs inline.