vvv (Viral Video Visualizer)
the_problem
Making short video with AI is cheap per attempt and expensive in aggregate. Every wrong prompt is a paid call, a character whose face changes between scenes ruins a story, and a product video that shows something unlike the real product is a misleading offer. The failures that cost the most are the ones that look like success.
what_it_does
- Video intelligence: scene detection, keyframe extraction, local transcription and visual analysis, choosing representative frames instead of sending every frame to a model.
- Story intelligence: an original story built from the reference’s structure (hook, open loops, twist, payoff), with character and visual bibles fixing what must not change between scenes.
- Two prompts per scene: the image prompt defines the visual state, the animation prompt what changes over time.
- Measured assembly: returned clips are decoded and timed, narration is transcribed back against the script and checked for voice drift, and the cut is joined with levels matched.
- A Brazilian TikTok Shop lane: product videos gated by product, claim and compliance checks, and a client for TikTok Shop’s Affiliate Creator API, run by the operator or on a schedule.
- A pre-publish gate that measures the final video, labels each finding verified or attested, and never posts by itself.
stack
backend
Python 3.11+ · Go 1.25 · Typer · Pydantic 2 · SQLAlchemy 2 · PostgreSQL 16
infra
GitHub Actions · Terraform
other
OpenCV · faster-whisper · Anthropic SDK · Model Context Protocol · pytest · GitHub Spec Kit
measured
- Specifications
- 37specs/, 2026-07-03 to 2026-09-27
- Machine-readable contracts
- 28schemas/, one JSON Schema per persisted shape
- Test functions
- 1782tests/, Python, 2026-09-27; 21 more in Go
- CLI commands
- 71src/h3v/cli.py, 2026-09-27
- Lint gate
- 9.9 / 10pylint fail-under, enforced in CI
how_it_was_built
Spec-driven: 37 specifications, each a spec, a plan and its tasks. The pipeline layer orchestrates, one module per command following read, check, write; the domain packages beside it make no I/O decisions; every persisted shape has a JSON Schema contract.
`record` does not take a reported result on faith. A clip reported as completed is decoded first: a file that is not a readable video becomes missing, and one that is has its measured duration recorded in place of the claimed one. The rule exists because the first render plan logged a PNG as a finished video, and an exists-check believed it.
A native Go launcher opens the interactive harness in milliseconds and runs the scheduled publishing worker, which holds a single-instance lock and never fires a job late; every other command passes through to the Python CLI.
known_limitations
- No end-to-end command, on purpose: three stages make paid model calls, so the chain is driven stage by stage.
- The storytelling account is posted by hand, after the gate reports ready.
- The TikTok Shop publishing path is built and tested against a fake client; no live post has been recorded yet.
- A remote result with no local file is stored as reported, not as measured.
- Local only, from a private repository; not offered to the public.
tracked coding time
127 hrs 15 mins Source: WakaTime · tracked 2026-03-17 to 2026-09-22