Obsidian-Knowledge-Base/docs/superpowers/specs/2026-07-08-video-note-extractor-design.md

Video Note Extractor — Design Spec

Purpose

Extract timed text transcripts and single-frame screenshots from tutorial video directories, for use in AI-assisted markdown note writing. Targeted at STM32 / embedded tutorial collections, but intentionally collection-agnostic.

Commands

parse — Extract timed text from subtitle files

python tools/extract.py parse <input> [--outdir <dir>]

• input: path to a single .mp4 file, or a directory containing .mp4 files (scans recursively).
• outdir: output root. Default ./transcripts/.

Output structure (mirrors input directory layout):

<outdir>/
└── transcripts/
    └── <collection-name>/
        └── <video-name>.txt

Each .txt file contains lines of:

[HH:MM:SS.mmm] <subtitle text>

frame — Extract a single frame as JPEG

python tools/extract.py frame <video> <timestamp> --outpath <path>

• video: path to .mp4 file.
• timestamp: HH:MM:SS or SSS (seconds).
• outpath: where to write the JPEG image (parent directory created automatically).

Subtitle resolution priority

For each .mp4, find the best-matching subtitle file:

1. Same basename + .srt, excluding _英文.srt / _English.srt.
2. Same basename + .ass (parse [Events] → Dialogue lines, strip ASS override tags like {\\fn...}).
3. Neither → print warning, skip.

Dependencies

• Python ≥ 3.10 (stdlib only for parse)
• ffmpeg / ffprobe on PATH (only for frame)

Anti-goals (explicitly out of scope)

• No VAD / Silero / ONNX integration.
• No ASR / API calls.
• No batch screenshot extraction.
• No markdown generation — the output .txt files are consumed by a human or AI note-writer.

Usage flow (intended)

1. python tools/extract.py parse <collection-dir> --outdir ./transcripts
2. Read .txt files → decide which timestamps need screenshots.
3. python tools/extract.py frame <video> <ts> --outpath <notes>/assets/<name>.jpg
4. Write markdown notes, embedding relevant screenshots.