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:

Same basename + .srt, excluding _英文.srt / _English.srt.
Same basename + .ass (parse [Events] → Dialogue lines, strip ASS override tags like {\\fn...}).
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)

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

2026-07-08-video-note-extractor-design.md 2.0 KB History Raw