Dark Factory — Video Intake

Overview

Claude cannot read video or audio natively (the Read tool handles images, PDFs, and notebooks only). This skill decomposes a video into things Claude can read — a timestamped transcript and sampled frames — then guides turning that into Dark Factory requirements via df-product-owner and df-data-transform-lens.

Two phases: Intake (mechanical, a script) → Extract (judgment, you + the DF skills).

When to Use

• The user hands you a video/recording/demo/walkthrough and wants it summarized, documented, or turned into requirements.
• "Can you watch / process / consume / transcribe this video?"
• "Extract requirements from this demo recording for the dark factory build."
• A screen-recorded SME/customer walkthrough that should become a PO requirements package.

Prerequisites

• ffmpeg (+ ffprobe) — brew install ffmpeg (macOS) / apt install ffmpeg (Debian).
• whisper-cpp — brew install whisper-cpp (provides the whisper-cli binary). The ggml model auto-downloads to ~/.cache/whisper-cpp on first run and is reused after.
• On Apple Silicon whisper-cli uses Metal/GPU automatically (≈24 s for a 9-min clip).

If a tool is missing the script prints the exact install command and exits — install, then re-run.

Phase 1 — Intake (run the script)

One command does probe → audio → transcript → frames:

bash "${CLAUDE_PLUGIN_ROOT:-$HOME/.claude/skills/df-video-intake}/scripts/extract-video.sh" "<path/to/video.mp4>" [interval_seconds] [model]

• interval_seconds (default 12) — one frame every N seconds. ~9 min → ~45 frames.
• model (default small.en) — base.en (faster, ~148 MB) · small.en (best quality/speed) · medium.en (slower, more accurate).

Output lands in <video-dir>/<video-basename>-extract/: probe.txt, audio.wav, transcript.txt, transcript.srt (timestamped), frames/iv_NNNN.jpg.

Frame ↔ time: iv_NNNN.jpg ≈ (NNNN-1) × interval seconds in. This is the join key back to the SRT.

Why fixed-interval, not scene detection

For screen recordings, ffmpeg scene-change detection (select='gt(scene,0.3)') fails — the UI changes gradually (scrolling, inline edits), so it yields ~0 frames. Fixed-interval sampling guarantees coverage and clean timestamp alignment. (Scene detection is still fine for edited video with hard cuts — not the usual demo case.)

Phase 2 — Extract (read, then turn into DF requirements)

1. Read transcript.txt in full. For a narrated demo it carries ~80% of the semantics and is cheap (text). The .srt gives you [mm:ss] timestamps to cite.
2. Read frames selectively, guided by the transcript. Each image costs context, so don't bulk-read all 45 — jump to the timestamps where the narration references a screen/state (iv_NNNN ≈ time/interval). The transcript says intent; the frame is ground truth (demos often narrate one thing while showing another — frames catch it).
3. Invoke the DF lens + PO skills — this skill ends where they begin:
   • df-data-transform-lens — name the data nodes (origin/authority/governance) and transforms (pure|effect) the demo reveals.
   • df-product-owner — produce Vision + Requirements (data contracts + validation rules) + Test Scenarios from the transcript+frames.
4. Tag every claim Confirmed (stated/shown) · Inferred · Assumption · Open. A demo is one person's narration — never silently promote a guess to a requirement.
5. Cite evidence inline: [mm:ss] for narration, ivNNNN for the frame that proves it.
6. Flag effects — any ask that sends/charges/notifies/writes-external or reads PHI (e.g. "test against a real chart") so the SA assigns idempotency + compensation.

Output artifact convention

• Write the extraction as a new, source-derived doc next to the video (e.g. requirements-docs/<name>-requirements-extraction.md), with frontmatter marking it status: source-derived (NOT canonical).
• Do not silently mutate governed docs/po/ docs. If the repo already has a PO package, add a short "Relationship to existing docs/po" table mapping each extracted requirement to existing scenarios (Inferred), and offer a separate reconcile/gap-check.
• End with an Open questions list — the things a cold Solution Architect would need answered before designing (the df-product-owner exit-gate test).

Verification

• transcript.txt is non-empty and coherent (skim whisper.log if not — bad audio, wrong model, or a non-English track needs a non-.en model).
• Frame count ≈ duration / interval; spot-read one mid frame for legibility.
• Every requirement in the output carries a tag + at least one [mm:ss]/ivNNNN cite.
• Effects and Open questions sections are present.

Worked example

A ~9-minute product demo, run through this skill end to end (intake script → transcript+frames → df-product-owner), yielded a dozen requirements and several state-change test scenarios in PO format. Keep your own worked examples in your organisation layer, next to the artifacts they cite.

Troubleshooting

Resources

• scripts/extract-video.sh — the intake pipeline (executed, not loaded into context).
• Pairs with: df-data-transform-lens, df-product-owner (and downstream df-solution-architect).