Evidence video factory

Evidence Video Factory

Build one reviewable video from verified project evidence. Optimize for truthful value, editorial motion, exact Chinese text, and repeatable rendering.

Workflow

0. Prove the hero claim before writing

Identify the one thing viewers should remember about the creator, not only the topic. Write a Story Contract containing:

• viewerProblem: the audience pain or desire;
• creatorOwnedAsset: what the user actually built, changed, or uniquely operated;
• heroClaim: the single main promise of the video;
• transformation: concrete input -> operation -> output;
• measuredLeverage: scale, runtime, cost, success rate, or before/after improvement;
• viewerOutcome: what the audience can now do or understand;
• memoryTarget: the sentence a viewer should use to describe the creator afterward;
• distributionTarget: the primary platform and audience context;
• nativeAspectRatio: the platform-native layout, not a later crop;
• heroEvidenceIds: evidence that proves the main promise.

If the hero claim contains a time, cost, count, success rate, or comparison, create a fresh benchmark record before scripting. Record start/end timestamps, exact input, mode, output count, failures, cost, and artifact hashes. A marketing draft, estimate, file timestamp, or dry-run is not benchmark evidence.

If the asset is a Skill, verify the exact invocation path shown in the video. Distinguish a genuinely executable Skill from an agent manually following a SKILL.md. Do not call an unmeasured or partially manual flow “three minutes” or “one click.”

1. Freeze the story before production

Inspect the project, evidence, real outputs, and user intent. Write script-review.md containing:

• the Story Contract and benchmark status;
• one hero claim plus supporting and boundary claims;
• 3 title options;
• 3 cover-text options paired with those titles;
• the first 5-second hook;
• complete narration;
• claim-to-evidence table;
• scene outline;
• disclosure and scope boundaries;
• estimated duration.

Stop after this file. Do not synthesize speech, build scenes, or render until the user explicitly approves the copy. Treat revision requests as a return to this stage.

Lead with the user's leverage, not implementation trivia. Prefer a structure such as:

fast creation → large real task → structured result → how it changes the user's workflow → evidence boundary.

Run three editorial tests before approval:

1. Creator Asset test: Can a viewer tell what the user built or uniquely did?
2. First-eight-second test: Do title, cover, spoken hook, and first visual communicate the same hero claim?
3. Memory test: After one viewing, will the viewer remember the creator, or only the tool / AI / researched subject?

For a creator-owned Skill, the first eight seconds should normally include the asset, scale, and result; include speed only when benchmarked. Do not demote the creator-owned asset to a secondary purpose when the account exists to share workflows and Skills.

2. Freeze canonical inputs

After approval, create one episode.json as the timeline SSOT and one Evidence Manifest. Keep approved narration and visible captions canonical; never replace them with ASR text.

Run:

python3 scripts/validate_episode.py --strict-story episode.json

Block on a missing Story Contract, an unproven timed claim, creator-asset keywords missing from the first eight seconds, replacement characters, invalid timing, overlapping captions, missing evidence IDs, or scene duration mismatch.

3. Generate and align narration

• Default Chinese documentary voice: MiniMax Chinese (Mandarin)_Radio_Host with speech-2.8-hd.
• For a personal workflow/Skill account, prefer the creator's real voice for the first eight seconds and fixed outro; TTS may carry the body. Ownership is harder to remember when the entire video sounds anonymous.
• Provide short voice samples only when the user has not approved a voice.
• Request native subtitles from MiniMax.
• Use Whisper word timestamps only as timing coordinates.
• Map approved canonical phrases onto those coordinates; do not surface Whisper's recognized words.
• Drive captions, scene boundaries, emphasis, and transitions from the same timeline.

4. Build the visual system

Use Remotion as the default renderer. Reuse a persistent studio instead of scaffolding per episode.

• Use deterministic HTML/React/SVG for text, data, UI, charts, and claims.
• Use generative polish only for text-free lighting, depth, texture, or editorial backgrounds.
• Do not use generated text, fake UI, stock B-roll filler, or a digital avatar by default.
• Convert long HTML reports to a few static chapter captures once; animate those images. Do not render a live iframe on every frame unless interaction is essential.
• Prefer spatial aggregation, camera push, shared-element motion, masked wipes, and meaningful state changes over slide-by-slide presentation.
• Keep one engine and one approved version. Do not A/B render engines unless the user explicitly requests a technical comparison.

Read references/quality-gates.md before rendering.

When the video is part of the user's recurring AI workflow / Skill account, also use visual-director-gate before approving the visual direction. This gate does not force a fixed template; it scores first-frame memory, information hierarchy, UI focus, motion purpose, caption discipline, evidence/privacy, and progress over the prior episode.

5. Render cheaply before rendering finally

Use this order:

1. TypeScript check.
2. One still per scene plus every transition boundary.
3. 540p proxy with draft encoding.
4. Visual Director Gate review using first-frame, scene sheet, caption sheet, raw key frames, and previous-episode baseline when available.
5. User/editorial review when visual direction changed materially.
6. One 1080p final render.
7. Two-pass loudness normalization and standard color tagging.
8. Blocking QC.

Never rerender 1080p to diagnose a problem visible in a still or proxy.

Before the 540p proxy, render one silent first-frame/cover comparison. It must communicate the creator asset and result without narration. Reject a visually attractive frame that only communicates the topic.

After the 540p proxy, create or update a visual-gate-report.md. Do not proceed to final render if the Visual Director Gate score is below 82, or if any blocking rule is triggered.

6. Run the final gate

python3 skills/evidence-video-factory/scripts/qc_video.py output/final.mp4 --width 1920 --height 1080 --fps 30

Also extract a frame at the midpoint of every caption and visually inspect the contact sheets. A technical pass does not override visible garbling, clipped text, wrong HTML anchors, or semantic audio-picture mismatch.

Deliver the MP4, QC report, contact sheets, approved script, Evidence Manifest, and hashes. Do not publish automatically.

7. Prepare publishing and learning

Prepare, but do not automatically publish:

• selected title and cover text;
• platform-native aspect ratio and a separately reviewed cover image;
• description and disclosure;
• pinned comment;
• published URL / post ID field;
• a 2-hour, 24-hour, and 7-day metric sheet.

Track views, 2/3/5-second hold where available, average watch time, completion, likes, comments, saves, shares, profile visits, and follows. Also classify comments by what viewers remembered: topic, tool, creator-owned asset, result, or reproduction request.

After publishing, compare the remembered message with memoryTarget. A technically successful video is an editorial miss if viewers remember only the researched subject or AI tool and not what the creator built.

Track production time in a production-run.json by phase: story contract, benchmark, script approval, TTS/alignment, visual build, proxy review, final render, QC, and publishing package. Optimize repeated phases, not editorial judgment. After three episodes, extract repeated scene components and one-command proxy/contact-sheet/QC orchestration; do not build a generic template from a single episode.

Storage

Place active episodes, audio, captures, renders, dependencies, models, and browser caches in project-configured storage with enough space. Keep generated media out of the Skill installation directory.

Exit criteria

Finish only when:

• the Story Contract has one approved hero claim;
• the creator-owned asset appears in the first eight seconds;
• every numeric leverage claim has benchmark evidence;
• approved copy is unchanged;
• every visible claim maps to evidence;
• canonical text has no replacement character;
• every caption midpoint matches the spoken meaning and scene;
• the Visual Director Gate passes, or the user explicitly accepts the visual tradeoff;
• the final file passes codec, color, loudness, peak, black-frame, and decode gates;
• the review bundle is complete;
• the publishing package and metric checkpoints are prepared;
• no publication action occurred.