h0wzy

vvv (Viral Video Visualizer)

old viralvideogen

own product functional, not deployed

2026-07-03 → 2026-09-27 · 338 commits

ShowcaseThe designed summary: what it does, the rule behind it, and the two accounts it serves.
open showcase →

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

← back to all works