// video_generation · interview-driven · the service ClearSpring sells

What is code versus what is LLM — the line is deliberate.

Built on HyperFrames (HeyGen, Apache 2.0) · Claude Agent SDK · Gemini TTS + image · FFmpeg · Kokoro fallback · per-client frame.md
The beat sheet is the swap point. Substitute a new one and re-run.
6 steps
a fixed pipeline — each step owned by code or by the LLM, never both

The pipeline has six steps, and the load-bearing design decision is which steps are code and which are LLM. The beat sheet (idea → scenes) is LLM — creative. Narration timing, QA, and render are code — deterministic. Composition HTML is LLM, guided by archetypes. The creative artifacts are substitutable; the machine is fixed.

That division is why re-rendering is byte-identical and why a new video is "write a beat sheet, re-run 2–6" — not "regenerate the whole thing and pray." The SonosKD video on this site took one focused session end-to-end through exactly this pipeline.

// the pipeline — what is code vs what is LLM
1. idea → beat_sheet.json        # LLM (creative)
2. beat_sheet → narration + manifest # CODE (deterministic timing)
3. beat_sheet + manifest → HTML  # LLM (guided by archetypes)
4. QA loop (lint/validate/inspect)# CODE (block on all three)
5. visual check (render, look, fix) # LLM (frames extracted, reviewed)
6. render to MP4              # CODE (headless Chrome + FFmpeg)
# swap the beat sheet → re-run 2–6. only the creative changes.

// structural decisions worth knowing

  • beat sheet as swap point
    The beat_sheet.json is the single substitutable creative artifact. A kitten-meeting-a-dog video and a baked-mac-and-cheese video run through the exact same steps — only the beat sheet and the composition HTML change. The pipeline is topic-agnostic by construction.
  • the outgoing-transition rule
    A hard-won GSAP lesson, now in the PLAYBOOK: outgoing scene transitions must use tl.to(), never tl.fromTo(). A fromTo(old, {opacity:1}, …) immediateRenders opacity:1 onto every later scene at construction time, blacking out earlier scenes. The first production render shipped scenes 1–3 as black frames for exactly this reason. The "prefer fromTo" rule applies to entrances; exits are the exception.
  • per-client brand as <code>frame.md</code>
    The recurring-value mechanism for the ClearSpring service is the per-client brand spec — palette hexes, font mappings, tone rules, a banned-vocabulary table, distilled into a frame.md. The video tool is sold as "your brand, as video," and the brand capture is a deliverable, not an assumption. Themes switch at render time via a composition variable, so one beat sheet = multiple brand treatments.
  • studio-review learning loop
    uv run studio-review compacts a session transcript deterministically and has a model write a debrief — friction, protocol adherence, proposed patches, durable lessons. Accepted lessons fold back into the protocol and PLAYBOOK. The tool improves itself across runs, with the same keep-or-revert discipline QLoop uses (lessons validated against prior runs).
  • duration gate before assets
    Narration is the cheapest stage to redo. A >15% overshoot vs the approved duration must be resolved before image assets — because assets and composition timing bind to the manifest. This gate caught a silent 75s→111s blowup on a real run. Fail cheap, fail early.
  • OK... go ahead and ask...
    Can I afford custom video ads,... and with one-day turnaround
// nextUniversal Agent →The desktop is the cockpit. The VPS is the brain.