
This project tackles automated video captioning with a focus on efficiency, accuracy, and production-grade robustness. Single-pass inference is utilized where instead of one API call per caption style, the pipeline extracts frames once and sends them to Fireworks AI (Minimax-M3, with automatic Qwen3p7-plus VLM fallback) exactly once, receiving structured JSON with both video-understanding metadata (subjects, setting, camera motion, apparent emotion) and all four captions simultaneously, ensuring fewer API calls, one network round-trip instead of a waterfall, and video context transmitted only once. For hybrid frame extraction, extract_frames.py combines three evenly-spaced anchor frames for temporal coverage with FPS-scaled histogram-based scene-change detection, adapting sampling density correctly across frame rates from 12fps to 60fps. Production hardening guarantees the pipeline never crashes a batch on one bad task: malformed JSON triggers an automatic repair-prompt retry before self-correcting via programmatic sentence-truncation and falling back to a safe default caption; every dictionary access uses safe defaults; exponential backoff with Retry-After handling covers transient API errors; and output verification enforces word limits, single-sentence structure, and clean text before a caption is accepted. Under anti-hallucination guarantees, the prompt forbids inventing objects, people, locations, or actions not visible in frames, mapping uncertain elements as "unknown." All four styles must describe the same underlying facts where only tone varies, and humorous captions must ground their joke in a specific visible object or action rather than generic filler. Finally, batch orchestration via run_all.py processes tasks concurrently via ThreadPoolExecutor, validates every requested style is present and non-empty, and exits with a status code reflecting overall batch success.
13 Jul 2026