ai-presenter-video

1---2name: ai-presenter-video3description: "Make a verified AI presenter video from script + image."4version: 1.0.05author: cclank (https://github.com/cclank/lanshu-create-ai-presenter-video), ported by Hermes Agent6license: MIT7platforms: [linux, macos]8required_commands: [ffmpeg, ffprobe, python3]9metadata:10  hermes:11    tags: [video, presenter, avatar, lipsync, tts, captions, creative]12    category: creative13    homepage: https://github.com/cclank/lanshu-create-ai-presenter-video14    related_skills: [hyperframes, kanban-video-orchestrator, comfyui]15---16 17# AI Presenter Video18 19Turn a topic (or finished script) plus ONE authorized adult presenter image20into a complete, publish-ready presenter-led video: locked narration, avatar21generation with lip-sync QA, captions, deterministic editing, loudness-normalized22master/share encodes, and machine + visual acceptance reports.23 24Use this skill for new presenter videos AND for continuing, revising,25captioning, lip-sync-repairing, or re-exporting an existing presenter-video26job. The workflow is provider-neutral: pick generation capabilities from what27is actually available in the session (FAL video/image models via28`image_generate` and the video-gen plugin, TTS via `text_to_speech`, ASR via29the whisper/STT tooling, ffmpeg for everything deterministic).30 31> Ported from cclank/lanshu-create-ai-presenter-video (MIT). Upstream body32> kept substantively verbatim in `references/`; Hermes adaptations live in33> this hub file. Scripts are deterministic (no network, no credentials).34 35## Hermes adaptations (read first)36 37- **Skill dir resolution** — upstream hardcoded its own agent's skills path.38  In Hermes the loader expands `${HERMES_SKILL_DIR}` to this skill's installed39  directory, so every command below uses that token directly:40 41  ```bash42  SKILL_DIR="${HERMES_SKILL_DIR}"43  ```44 45  Shell variables do not persist between tool calls — re-paste the assignment46  (or the expanded path) in each terminal call that uses it.47- **Capability mapping** — where the references say "a voice generation48  capability", use `text_to_speech` (OpenAI/Edge/ElevenLabs per user config);49  "presenter/avatar generation" → FAL image-to-video families (Kling, Wan,50  MiniMax H3 etc.) through the configured video tooling, or an avatar/lipsync51  endpoint the user has access to; "word-timestamp ASR" → whisper via the STT52  tooling or `faster-whisper` in a venv; "deterministic compositor" → ffmpeg53  filtergraphs, or the `hyperframes` skill when installed (the editing54  reference has a HyperFrames section that maps directly onto it).55- **Visual QA** — do the "normal-speed visual review" steps with56  `vision_analyze` on the generated contact sheet plus sampled frames57  (identity, mouth timing, hands, blinking, continuity). Numeric checks come58  from the scripts' ffprobe output.59- **Paid-generation consent** — remote avatar/TTS generation is billable.60  Follow the upstream operating rules: before the first paid call state the61  uploaded assets, requested seconds, known cost, pilot size, and retry62  ceiling, and get the user's explicit go-ahead. Never upload the presenter63  image to a remote provider before `remote_upload_approved` is true in64  `job.json`.65- **Consent flags live under `input`** — `rights_confirmed`,66  `adult_presenter_confirmed`, `remote_upload_approved`, and67  `voice_clone_approved` sit inside the `input` object of `job.json` (init68  flags set them; hand-editing must target `input.*`, not the job root).69  `manual_input_review.*` sits at the root. `preflight.py` distinguishes70  `errors` (block everything) from `remote_blockers` (block only remote71  generation) — local script/audio work may proceed while remote is blocked.72 73## Workflow74 751. **Start or resume a job.** New job:76 77   ```bash78   python3 "$SKILL_DIR/scripts/init_job.py" \79     --job-dir ~/Videos/my-presenter-video \80     --presenter-image /path/to/presenter.png \81     --topic "explain context engineering in one minute" \82     --duration 60 --aspect 9:16 \83     --rights-confirmed --adult-presenter-confirmed84   ```85 86   Use `--script` for an existing script file; other flags: `--voice-sample`,87   `--supporting-media`, `--width`, `--height`, `--fps`, `--watermark`,88   `--cta`. For an existing job, read `job.json` + QA reports and resume from89   the earliest unfinished state — never regenerate accepted work.90 912. **Manual input review.** Actually look at the presenter image92   (`vision_analyze`) and listen to any voice sample; record findings by93   setting the `manual_input_review` booleans in `job.json`, e.g.:94 95   ```bash96   python3 - <<'PY'97   import json98   p = "~/Videos/my-presenter-video/job.json"  # expand ~ or use an absolute path99   import os; p = os.path.expanduser(p)100   j = json.load(open(p))101   j["manual_input_review"].update(image_viewed=True, single_clear_face=True,102                                   image_has_no_unwanted_text=True)103   json.dump(j, open(p, "w"), indent=2)104   PY105   ```106 107   Then gate:108 109   ```bash110   python3 "$SKILL_DIR/scripts/preflight.py" ~/Videos/my-presenter-video/job.json111   ```112 113   Proceed only when `ok: true`; do remote generation only when114   `remote_ready: true`. Note: preflight also updates `job.json` in place115   (records the report path) — re-read it after running rather than editing116   a stale copy.117 1183. **Lock content and audio** — read `references/generation.md`. Script →119   full narration via `text_to_speech` → ASR-verify the narration against the120   script → record real durations. The locked audio is the master clock for121   everything downstream.122 1234. **Plan and generate the presenter** — read `references/generation.md`.124   Short low-cost pilot first; full run only after the pilot passes identity125   and mouth-timing review.126 1275. **Edit** — read `references/editing.md`. Deterministic timeline driven by128   the locked audio; captions and keyword callouts only after audio and media129   are final.130 1316. **Verify and deliver** — read `references/qa-recovery.md`, render, then:132 133   ```bash134   bash "$SKILL_DIR/scripts/finalize_delivery.sh" \135     ~/Videos/my-presenter-video/renders/rendered.mp4 \136     ~/Videos/my-presenter-video/outputs my-video137   ```138 139   The finalizer preserves aspect ratio, runs two-pass loudness normalization140   (program ≈ −16 LUFS), produces master + share encodes, decode-verifies141   both, writes a delivery report JSON, and emits a nine-frame contact sheet.142   Inspect the contact sheet with `vision_analyze` before claiming completion.143 144## Operating rules (non-negotiable)145 146- Confirm image rights, adult status, remote-upload approval, and147  voice-cloning authorization before the relevant remote action.148- Never infer or clone a real person's voice from an image; use an authorized149  sample or a stock TTS voice.150- Lock the complete narration before presenter generation, caption timing, or151  final scene boundaries.152- Mute video sources in the final composition; only the approved narration153  and intentional mix tracks carry audio.154- Preserve provider request bodies and task IDs (minus credentials/expiring155  URLs). Poll interrupted work before resubmitting — avoid double billing.156- Stop after three rejected paid candidates and summarize the failure mode.157- Do not claim completion until the final files fully decode and the contact158  sheet or full playback has been reviewed.159 160## Defaults for minimal input161 1629:16, 1080×1920, 30fps; topic-derived videos target 45–75s; stock voice when163no authorized sample; presenter-led layout with hook → 2–4 beats → close;164no music/CTA unless requested; language inferred from the request.165 166## Reference routing167 168- `references/generation.md` — intake, content, voice, capability selection,169  presenter prompts, paid generation, provider changes.170- `references/editing.md` — timeline contract, openings/closes, captions,171  keyword-callout presets, HyperFrames composition, exports.172- `references/qa-recovery.md` — technical acceptance, visual acceptance, and173  recovery for lip-sync/identity/hands/exposure/freeze/caption/audio faults.174 175## Pitfalls176 177- `preflight.py` requires ffprobe; on a bare box install ffmpeg first.178- The consent booleans set by init flags land under `input.*`; editing them179  at the job-json root silently does nothing (preflight keeps blocking).180- `finalize_delivery.sh` needs bash + jq + awk and a fully decodable input —181  a truncated render fails the decode check by design, not by accident.182- Long avatar clips drift: prefer one continuous presenter source sliced on183  the audio timeline over many regenerated chapter clips (identity drift184  across regenerations is the #1 visual-QA failure).185- FAL i2v endpoints cap duration (typically 5–15s); plan chapter-level186  presenter segments accordingly and reuse the pilot's seed/params for187  consistency where the endpoint supports it.188 189## Verification190 191Validated hands-on (Aug 2026): `init_job.py` → `job.json` with correct state192machine; `preflight.py` correctly blocked on unreviewed inputs, flipped to193`ok: true` after review booleans, and kept `remote_ready: false` until194`input.remote_upload_approved`; `finalize_delivery.sh` on a synthetic 5s1951080×1920 render produced decode-verified master (631kbit/s) + share encodes,196delivery-report JSON, and a 9-frame contact sheet, exit 0.197