Talking Head Video Pipeline

Talking Head Video Pipeline

Turn raw or rough-cut talking-head footage into an approved working cut, editable captions, a motion-packaged preview, and a verified final export. Treat this file as the router and shared contract. Read only the routed internal workflow and references needed for the current stage.

Beginner Promise

Assume the user has never edited with Codex.

• Ask one short question at a time only when an answer cannot be inferred safely.
• Prefer a working default over presenting many technical choices.
• Explain the next visible result, not the renderer internals.
• Introduce rough cutting, transcription providers, or API setup only when raw footage actually needs that branch.
• Explain paid and local choices plainly, recommend one when useful, and never force it.
• End every stage with exact output paths and the next phrase the user can say.
• Resume existing work instead of restarting it.

Non-Negotiable Rules

1. Source is immutable. Never overwrite or destructively edit the supplied source media.
2. Main audio is the clock. Do not retime, reorder, resample, or replace it unless the user explicitly approves a rough-cut strategy. After approval, the derived working_video becomes the downstream clock while the original remains immutable.
3. Evidence stays readable. Never cover screenshot body text, product UI, faces, or user-marked safe zones. Do not blur evidence assets.
4. Preview before final. Build an official preview and wait for approval unless the user explicitly requests direct export.
5. Original-quality final. Do not present an upscaled low-resolution preview as a true high-resolution final. Use the original source as the final base whenever possible.
6. Do not interrupt progress. If a render is advancing, wait and report progress. Change pipelines only after a real error or explicit approval.
7. No private data in the skill. Project-local paths, media names, brand rules, screenshots, customer details, and API keys stay in the user's project.
8. Learn only from explicit feedback. Do not infer permanent style rules from silence or one unconfirmed draft.
9. Typography is part of correctness. Declare and verify font family, real weight, caption line policy, baseline alignment, and longest-label fit before approval.
10. Public defaults stay brand-neutral. Store creator palettes, recurring card systems, and private visual rules only in the local profile.
11. Public install exposes one Skill. Keep stage modules under references/workflows/; do not add nested SKILL.md files that package managers may register separately.
12. Install operations are recoverable. Back up an existing installation before replacement and archive uninstall targets instead of performing recursive force deletion.
13. Optional providers stay optional. The curated default shot pack is native HyperFrames + GSAP. Never clone, install, update, or require ShotCraft, Remotion, or another provider without explicit user consent. Native recipes must remain a complete fallback.

Read references/quality-gates.md before preview or export work.

Route Table

Mode Detection

Before routing:

1. Identify the user's video project directory, not this skill repository.
2. Look for .naive-video-state.json.
3. If absent and the task is more than a one-off caption text edit, load the init workflow.
4. If present, read it plus EDIT_PLAN.md, DESIGN.md, and VIDEO_LESSONS.md only when relevant. Use working_video when present; otherwise use main_video.
5. Run python3 tools/video_doctor.py --project <project_dir> when state and files disagree.

Use these stages:

textCopy code
initialized -> captions_ready -> design_ready -> preview_ready
-> approved -> rendering -> final_ready

Never mark a later stage until its quality gate passes.

Default Pipeline

When the user asks for the complete workflow:

1. Inspect source media with ffprobe.
2. Initialize project state and safe output directories.
3. Ask whether the footage is already rough-cut only when that status is unclear. If it is raw, load the optional rough-cut workflow and require strategy approval.
4. Produce or validate caption files from working_video when present, otherwise main_video.
5. Ask whether screenshots, recordings, product images, charts, or demos must appear. Let the user choose semantic placement, exact seconds/spoken-sentence anchors, or a hybrid; explain that exact anchors are more precise.
6. Normalize word-level timing when available and split the speech into viewer-facing logic groups. Do not fake word precision from whole-caption starts.
7. Collect or infer a style profile and safe zones. Offer optional screenshot-reference matching to beginners.
8. Write an edit plan and semantic motion plan with every requested insert, logic-group link, and time range.
9. For new projects, automatically map a few safe semantic nodes to the curated ShotCraft-inspired native pack unless the user chooses skip. Preserve existing approved projects, the native recipe, and offline fallback.
10. For first-use, new-style, or reasoning-heavy work, render representative static keyframes and resolve composition problems before a full dynamic preview.
11. Build a HyperFrames + GSAP preview using a browser-friendly proxy if needed.
12. Run preview quality gates and provide the official preview URL.
13. Wait for approval unless explicitly told to skip.
14. Render overlays or final composition using the approved working video and its audio clock.
15. Verify file existence, duration, resolution, frame rate, and audio.
16. Record only confirmed feedback as project-local lessons.
17. After delivery, run a factual retrospective and promote only explicit, privacy-safe rules.

Project Files

The init workflow creates this minimal project memory without touching source media:

textCopy code
<project_dir>/
├── .naive-video-state.json
├── EDIT_PLAN.md
├── DESIGN.md
├── CONTENT_LOGIC.json       # viewer-facing reasoning groups and timed beats
├── STYLE_REFERENCE.md       # created only when a reference image is used
├── MOTION_PLAN.json         # created when semantic motion is planned
├── VIDEO_LESSONS.md
├── VIDEO_RETRO.md
├── edit/
│   ├── rough-cut.mp4            # optional; original media is never overwritten
│   ├── rough-cut-edl.json       # optional decision record
│   ├── script-aligned.srt
│   ├── caption-table.csv
│   └── transcripts/
├── preview/
├── final/
└── qa/
    └── KEYFRAME_REVIEW.md   # static-composition review before dynamic preview

State is operational metadata, not a media database. Keep it small and never store transcript bodies, private screenshots, or secrets in it. See references/state-management.md.

Style Defaults

If the user wants speed and gives no reference:

• Preserve the source aspect ratio.
• Use a clean, readable card system with one configurable accent color.
• Use bold captions with restrained keyword emphasis.
• Use GSAP transforms and opacity for motion.
• Place cards in verified empty space.
• Reduce motion density while screenshots or demos are visible.
• Keep readable text level and baseline-aligned; animate the containing component instead of skewing labels.
• Choose an explicit caption maximum line count and wrap policy.

Ask for an accent color only if brand consistency matters. Otherwise use the neutral preset and make it easy to change later. Beginners may optionally provide a screenshot and choose low, medium, or high reference strength; explain that the skill copies visual language, never the source brand or content. Motion density is restrained, balanced, or energetic. See references/style-onboarding.md.

Detailed GSAP recipes and semantic mappings live in references/motion-recipes.md. Runtime and plugin selection live in references/gsap-runtime.md. Screenshot extraction and anti-copy rules live in references/style-reference-workflow.md. Asset timing choices live in references/asset-onboarding.md. Load them only for the matching design branch.

ShotCraft discovery and adaptation rules live in references/shotcraft-integration.md; the native beginner pack lives in references/shotcraft-default-pack.md. Load them for new automatic projects, named cards, or cinematic shot requests. Never install a provider silently.

Word-level timing, viewer-facing logic groups, and accumulation/exit behavior live in references/content-logic-workflow.md. Load it after captions and before semantic design.

Typography, component geometry, glass notifications, and seek-safe focus/type/split adaptation live in references/visual-quality-rules.md. Load it for every design or preview task.

Self-Iteration Contract

Self-iteration means improving the current user's workflow without leaking it into public defaults.

Classify feedback into one scope:

• project: applies only to this video.
• profile: applies to this user's future videos; write it only after explicit confirmation.
• product: a privacy-safe, general reliability improvement; propose it to the skill maintainer separately.

Record profile feedback in VIDEO_LESSONS.md with the user's words, the confirmed rule, and the affected stage. Never copy media paths or private evidence into this repository. See references/self-iteration.md.

Use the retro workflow after delivery to separate failures, environment issues, and taste feedback before promoting any rule. New projects import active private-profile rules into VIDEO_LESSONS.md so the editor can actually apply them.

Recovery Rules

• If preview stops responding, check the process and port before rebuilding.
• If a browser cannot decode HEVC/Main10 smoothly, make an H.264 proxy for preview only.
• If a render session is running, poll it; do not terminate it merely because it is slow.
• If partial frames exist, compare expected and actual frame counts before resuming or restarting.
• Move damaged partial outputs to a project-local quarantine only after confirming they are not the sole valid result.
• Keep logs outside command pipes that can terminate long jobs.

Privacy Before Publishing

Run:

bashCopy code
bash scripts/doctor.sh --privacy-scan .
python3 tools/validate_skill.py .

Block publication if either command reports personal absolute paths, secrets, private media names, invalid frontmatter, multiple skill manifests, missing internal workflows, unsafe install commands, or broken templates.