version unknown

lanshu-create-ai-presenter-video

cclank@cclank⭐ 3.0k stars· last commit 1mo ago· 2 open issues

>-

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

7.3/10
Verified
Oct 12, 2026

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐⭐ 3.0k on GitHubGitHub ↗

Very popular

🟢ProSkills ScoreAI Verified
7.3/10
📍

Not yet listed on ClawHub or SkillsMP

// README

lanshu-create-ai-presenter-video

English | 简体中文

Agent Skills Harness Neutral Provider Neutral Routes: Presenter | Styled Explainer Styles: 12 Rendered with HyperFrames Validate Skill License: MIT Release Python 3.9+ FFmpeg Required Node.js for the styled route GitHub stars X @LufzzLiz Author: 岚叔 Lanshu

Turn a topic or script into a verified, publish-ready explainer video — presented by a digital human from one authorized portrait, or acted out on screen in one of twelve explainer styles — driven by the coding agent you already use.

lanshu-create-ai-presenter-video is an Agent Skill that takes an AI agent through the full production of an explainer video. On the presenter route that means script, narration, presenter generation, lip-sync, captions and keyword motion graphics, editing, rendering, and quality assurance. On the styled route the narration is performed scene by scene in one of twelve styles (nine visual, three narrative), from a word-timed story to a rendered film. Every stage is gated by evidence on disk, and nothing is delivered until the output passes decode and loudness checks.

Highlights

  • Harness-neutral. A standard SKILL.md that loads in Claude Code, Codex, Gemini CLI, Cursor, OpenCode, GitHub Copilot, and other Agent Skills clients. Any agent that can read files and run shell commands can follow it directly.
  • Provider-neutral. On the presenter route, voice, presenter video, lip-sync, and speech recognition are selected by capability at run time; each job records the provider, model, parameters, and task IDs it actually used. The styled route voices with MiniMax (word timestamps come from the voice engine) or takes narration you voiced or recorded elsewhere.
  • Twelve performed explainer styles. Nine visual styles — editorial, tech HUD, notebook, paper pop-up, pop comic, 3D one-take, drafting sheet, chalkboard, and clay town — plus three narrative styles: derivation, casefile, and life-scene sitcom. Each has a reusable kit, starter, and example project.
  • Audio-locked timeline. The approved narration is the master clock for presenter motion, captions, cuts, and final duration, which keeps lip-sync and scene boundaries aligned.
  • Evidence-gated workflow. Eight production states, from intake to verified, computed from artifacts instead of declared by hand.
  • Cost guardrails. Pilot-first generation, an explicit billing statement before the first paid call, retry ceilings, and task-ID recovery to avoid duplicate charges.
  • Verified delivery. Master and share encodes are fully decoded and loudness-checked before any file is published.

Two routes

RouteThe videoYou providePaid generationFormat
PresenterA digital human presents; captions and keyword graphics support itTopic or script + authorized portraitVoice + presenter videoAny; 9:16 by default
Styled explainerNo presenter: every narrated phrase is acted out on screen in one of twelve styles (nine visual, three narrative)Topic or script (or your own recorded narration)Voice only (none with your own narration)16:9

The agent infers the route from your request or asks once, with the style gallery. All styles share one contract — word-timed captions, chapter chips, a performed closing line, a one-frame recap. Nine are visual styles that differ in how ideas are acted out: editorial paper, tech HUD, notebook and pen, paper pop-up book, pop comic, 3D one-take, drafting sheet, chalkboard, and a clay town. Below is the same moment of the bundled KV cache explainer in all nine:

The same moment of the KV cache explainer in nine styles

Three are narrative styles, where the look comes with a way of telling and the script can draw on its suggested arc: 推演 (derive it on one canvas, formulas and geometry bound by colour), 案卷 (investigate it on an evidence board, from the anomaly to the closed case) and 小剧场 (a life-scene sitcom: a misconception, a bill or a queue that shows the cause, one sentence that maps the analogy to the real term). Below is the same KV cache topic told the three ways:

The KV cache topic told in the three narrative styles

A new topic becomes a playable draft in any style in a few commands — narration, word timing, captions, chapters, closing line, recap, and sound are generated; the agent then performs each line's scene. See explainer/STYLES.md to choose a style and references/styled-explainer.md for the workflow — including an optional method for bringing your digital human into a styled film.

What you provide

InputRequiredNotes
Topic or finished scriptYesA topic becomes a 45–75 second script; a supplied script keeps its natural length.
Presenter imagePresenter routesOne clear adult presenter, with confirmed rights to use the image. Not needed for the styled explainer.
Voice sampleNoUsed only with explicit cloning authorization; otherwise a stock voice is selected and recorded.
Supporting mediaNoScreen recordings, images, B-roll, or brand assets, used where they prove or clarify a spoken point.
Delivery preferencesNoPlatform, duration, aspect ratio, style, watermark, music, and call to action.

How it works

Presenter route:

Topic or script + authorized portrait
        │
        ▼
Lock script and full narration ──► narration becomes the master clock
        │
        ▼
Low-cost presenter pilot
        │
        ▼
Presenter generation (split at real pauses when a provider caps duration)
        │
        ▼
Audio-driven edit: captions, keyword graphics, cover, close
        │
        ▼
Technical and visual QA
        │
        ▼
Master, share copy, contact sheet, and delivery report

Styled route:

Topic or script ──► choose a style (menu + galleries, or drafts in the nine visual styles)
        │
        ▼
Script written for the style ──► voice with word timestamps (or your own narration)
        │
        ▼
Draft film from the style's starter: captions, chapters, closing line, recap, sound
        │
        ▼
Storyboard ──► every line performed on screen, on it

// HOW IT'S BUILT

// FILES

327 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • SKILL.md15 KBef4c3cf5894dupstream ↗
    ---
    name: lanshu-create-ai-presenter-video
    description: >-
      Turn a topic or finished script into a complete, publish-ready explainer video — led by an AI presenter from an authorized adult presenter image, or performed with no presenter in one of twelve explainer styles (nine visual styles and three narrative ones). Not for promos, ads, or footage montages. Use for new presenter or styled explainer videos and for continuing, revising, captioning, lip-sync repairing, or re-exporting an existing job. Use it whenever the user asks for 数字人口播 / 数字人讲解, for a 讲解视频 / 动画讲解 / 科普视频, asks which styles or templates are available (有哪些风格 / 看看风格 / 风格模板), or names one of the styles: 留白, 信号/科技感, 手帐/手绘, 立体书/纸艺, 波普漫画, 一镜到底/3D, 图纸与注脚, 黑板报, 黏土小城, 推演/动态图解, 案卷/调查复盘, 小剧场/生活场景. Keep model and provider selection capability-based and record the actual choices per job.
    license: MIT
    compatibility: Works in any Agent Skills harness or shell-capable coding agent. Requires Python 3.9+, FFmpeg with ffprobe, bash, and jq; remote voice and presenter generation need network access and provider credentials. The styled explainer route also needs Node.js (npx) and rsync.
    ---
    
    # Lanshu Create AI Presenter Video
    
    Produce a verified explainer video from minimal inputs — led by a digital human, or performed in one of twelve explainer styles. The final narration is the master clock for presenter motion, captions, graphics, cuts, and delivery duration.
    
    ## Choose a route
    
    Every job takes one of two routes, recorded as `creative.route`. Infer it when the request is clear (cues below);
    otherwise ask once, with this table and the style gallery (`explainer/STYLES.md`; attach or link the images
    `explainer/gallery/nine-styles-kv-cache.jpg` and `explainer/gallery/three-narrative-styles-kv-cache.jpg`). Never fall back to `presenter` silently: it needs a portrait the user
    may not have.
    
    | Route | The video | The user provides | Paid generation | Format |
    |---|---|---|---|---|
    | `presenter` | A digital human presents; captions and keyword graphics support it | Topic or script + authorized presenter image | Voice + presenter video | Any; 9:16 by default |
    | `styled` | A performed explainer: every narrated phrase is acted out on screen in one of twelve styles (nine visual, three narrative), no presenter | Topic or script | Voice only | 16:9 |
    
    - A presenter image or the words 数字人 / presenter / 口播 / 真人出镜 point to `presenter`; 不要真人 / "no presenter" /
      "faceless", a named style, or 动画讲解 / 手绘 / 黑板 / 黏土 / 漫画 / 推导 / 复盘 / 小剧场 point to `styled`.
    - A vertical platform (抖音 / 视频号 / 小红书 / 竖屏 / 9:16) is a format request, not a route: `styled` is 16:9 only.
      If it comes with no portrait or with styled cues, ask (a 16:9 styled film vs a 9:16 presenter video) instead of
      switching routes.
    - Narration the user already recorded is the locked audio on either route. Never pass it as `--voice-sample` (that
      flag is for voice cloning). On `styled` use `story.py story --audio <file>` and ask for the matching script text
      (or transcribe it and have the user check it).
    - To re-style an earlier job, keep its script and locked audio (no new voice cost), build a new film from the same
      `story.json` in the new style, and re-approve the storyboard. Ask which job when it is not obvious.
    - This skill makes explainers. For 宣传片 / 广告 / 发布大片 / footage edits, say so, and offer a product explainer only
      if the user wants one.
    - For `styled` also choose `creative.explainer_style` (`v1-editorial` … `v12-sitcom`). Recommend two or three from the
      topic and audience (one reason each) using `explainer/STYLES.md`; when the user is unsure, build drafts in the nine
      visual styles (no extra paid calls once the audio is locked, or with `--dry`) and let them pick from a still grid.
      Settle the style before the script is locked: each style shapes how the narration is written and voiced
      (`explainer/STYLES.md`, "按风格写稿"). The three narrative styles (`v10-reasoning` 推演, `v11-casefile` 案卷,
      `v12-sitcom` 小剧场) go further: use the style's suggested arc when it helps the explanation, adapting chapters and
      order to the topic. The examples are starting points; keep room for other storytelling choices. To compare
      styles first, use `--dry` drafts of a first script, then adapt it to the chosen style.
    - `styled` follows [styled-explainer.md](references/styled-explainer.md) and reuses this skill's job directory, state
      machine, approvals, and delivery checks. The styles are designed to carry the explanation on their own; if a user
      also wants their digital human in a styled film, that file describes the method (time the film to the presenter's
      locked narration, give the presenter its own space) as an optional addition, not a separate route.
    
    How to ask, when the request leaves the choice open — one message, in the user's language:
    
    1. The two routes, one line each: what the video looks like, what the user must provide, what is paid, and the
       format (presenter: any ratio, 9:16 by default; styled: 16:9 only). Recommend one for this topic and say why (e.g. "no portrait yet, or a concept that needs to be shown → styled"; "personal brand,
       talking to camera → presenter").
    2. For `styled`, assume the user does not know the styles yet: show the whole menu — the two gallery images plus the
       twelve one-line entries of "风格菜单" in `explainer/STYLES.md` — and mark the two or three that fit this topic and
       audience, one reason each. Offer "build drafts in the nine visual styles and pick from a still grid" as the
       alternative. Do the same, without the route table, when the user only asks which styles there are.
    3. Proceed with the recommendation if the user agrees or does not mind; record the choice in `job.json`.
    
    ## Required outcome
    
    - Start from a topic or script and, for the presenter route, one authorized image containing one clear adult presenter.
    - Deliver a fully decoded master video, a smaller share copy, captions, production records, and separate machine and visual QA notes.
    - Keep the workflow portable across providers, models, aspect ratios, languages, and durations.
    
    ## Operating rules
    
    - Confirm image rights, adult status, remote-upload approval, and voice-cloning authorization before the relevant remote action.
    - Treat remote generation as potentially billable. Before the first paid call, state the uploaded assets, requested seconds or units, known cost, pilot size, retry ceiling, and expected output. Reuse an approval already given for that exact plan.
    - Never infer a real voice from an image. Use an authorized sample or record a selected stock voice.
    - Lock the complete narration before presenter generation, caption timing, or final scene boundaries.
    - Prefer one presenter image, one voice identity, one visual treatment, and one continuous presenter source.
    - Mute video sources in the final composition. Route only the approved external narration and intentional mix tracks.
    - Preserve provider request bodies and task IDs without credentials or expiring URLs. Poll interrupted work before considering resubmission.
    - Use numeric checks for technical faults and normal-speed visual review for identity, mouth timing, blinking, gestures, hands, lighting, and continuity.
    - Stop after three rejected paid candidates, or before a change that materially affects cost, privacy, voice, appearance, or provider.
    - Do not claim completion until the final files fully decode, the contact sheet or full playback has been reviewed, and `check_state.py` reports `verified`.
    
    ## Start or resume a job
    
    For a new job, read [generation.md](references/generation.md). Set `SKILL_DIR` to the directory that contains this file; its location depends on the harness. Then run:
    
    ```bash
    SKILL_DIR=/path/to/lanshu-create-ai-presenter-video
    
    python3 "$SKILL_DIR/scripts/init_job.py" \
      --job-dir ~/Videos/my-presenter-video \
      --presenter-image ~/Pictures/presenter.png \
      --topic "用一分钟讲清楚上下文工程"
    ```
    
    For the styled route add `--route styled --explainer-style v3-notebook` (no presenter image needed).
    
    Use `--script` for an existing script file. Optional flags include `--voice-sample`, `--supporting-media`, `--duration`, `--aspect`, `--width`, `--height`, `--fps`, `--watermark`, and `--cta`. The initializer copies every input into the job and records job-relative paths, so the job directory is self-contained; keep later artifact paths job-relative too.
    
    Inspect the actual source image and listen to any voice sample. Record the manual review and approvals in `job.json`, then run:
    
    ```bash
    python3 "$SKILL_DIR/scripts/preflight.py" ~/Videos/my-presenter-video/job.json
    ```
    
    For an existing job, read `job.json`, current artifacts, task IDs, and QA reports, then run `check_state.py` (below) to find the earliest unfinished state. Resume there without regenerating accepted work.
    
    ## Production state machine
    
    Advance a job only when its evidence exists:
    
    ```text
    intake
    → content_locked       passing preflight report, script, beat sheet
    → audio_locked         decodable final audio, ASR report
    → visual_plan_locked   timeline, storyboard, plan.status "approved"
    → presenter_generated  recorded main_presenter capability, selected video, visual review
    → composition_checked  composition report
    → rendered             decodable render with video and audio
    → verified             master, share, delivery report with passing output loudness
    ```
    
    On the `styled` route there is no presenter: `presenter_generated` is reached by the performed film instead
    (`artifacts.story`, `artifacts.film_project`, and the visual review).
    
    Never edit `state` by hand. Record artifacts in `job.json`, then let the checker compute the state:
    
    ```bash
    python3 "$SKILL_DIR/scripts/check_state.py" ~/Videos/my-presenter-video/job.json --write
    ```
    
    Without `--write` it only reports. It exits non-zero when the recorded state claims more than the evidence supports, and lists what the next state is missing.
    
    ### 1. Lock content and audio
    
    Read [generation.md](references/generation.md).
    
    1. Turn a topic into one spoken content spine, or polish a supplied script without changing factual meaning silently.
    2. Save the production script, beat sheet, pronunciations, and narration sections.
    3. Generate the complete approved narration with one voice configuration.
    4. Normalize sections consistently, run ASR on the final audio, and correct material omissions, additions, numbers, names, or repeated speech.
    5. Record real durations. These durations now define the timeline.
    
    ### 2. Plan and generate the presenter
    
    Choose a presenter-led, screen-demo, or mixed-explainer route. Use supporting media only when it proves or clarifies a spoken point.
    
    When the provider caps request or reference-audio duration below the narration length, plan the split from the locked audio's ASR timings instead of guessing:
    
    ```bash
    python3 "$SKILL_DIR/scripts/plan_segments.py" \
      --timings ~/Videos/my-presenter-video/qa/asr/sentences.json \
      --audio ~/Videos/my-presenter-video/assets/audio/final/narration.wav \
      --cap 15 --whole-seconds \
      --output ~/Videos/my-presenter-video/qa/requests/segment-plan.json
    ```
    
    Save the plan path in `plan.segment_plan`. Generate every segment from the same image, seed, framing, light, and motion constraints.
    
    Generate a short, low-cost pilot before a full run. Prioritize identity and mouth timing for the main track. Use one controlled gesture for an actionful opening or close. When body motion is accepted but mouth timing fails, preserve the motion plate and apply a dedicated lip-sync repair with the locked audio.
    
    Archive the prompt, parameters, provider/model/version, region, task ID, requested seconds, and acceptance notes.
    
    ### 3. Edit the video
    
    Read [editing.md](references/editing.md).
    
    Build a deterministic timeline driven by the locked audio. Keep authored start, duration, and source offset independent. Add captions and keyword callouts only after audio and selected media are final.
    
    When using HyperFrames, load the current `hyperframes`, `general-video`, and relevant domain instructions. Run the project check, inspect transition and emphasis frames, open the Studio preview, and wait for final visual approval before rendering.
    
    ### 4. Verify and deliver
    
    Read [qa-recovery.md](references/qa-recovery.md).
    
    Render at delivery quality, watch the complete video, and finalize it:
    
    ```bash
    bash "$SKILL_DIR/scripts/finalize_delivery.sh" \
      ~/Videos/my-presenter-video/renders/rendered.mp4 \
      ~/Videos/my-presenter-video/outputs \
      my-video
    ```
    
    The finalizer preserves the input aspect ratio, performs two-pass program loudness normalization, creates master/share encodes, fully decodes them, measures their delivered loudness, counts black and frozen-picture events, and produces a nine-frame contact sheet. It builds everything in a temporary directory and publishes nothing unless every check passes. The target defaults to `-16 LUFS`; set `PROGRAM_LUFS` (for example `PROGRAM_LUFS=-14`) when the destination requires another.
    
    Inspect the contact sheet, review any freeze events against intentional still shots, record the outputs and delivery report in `job.json`, and run `check_state.py --write` to reach `verified`.
    
    ## Default behavior for minimal input
    
    - Infer language from the request.
    - On the presenter route, use 9:16, 1080×1920, 30fps unless the intended platform suggests another format. The styled route is always 16:9, 1920×1080, 30fps.
    - Preserve a supplied script's natural duration; for a topic, target 45–75 seconds.
    - Use a suitable stock voice when no authorized voice sample exists.
    - On the presenter route, use a presenter-led layout with a designed hook, 2–4 useful beats, and a concise close; on the styled route, the style's starter sets the layout.
    - Omit music and promotional CTA unless requested or clearly justified.
    - Keep styling credible, contemporary, readable, and safe for the destination platform.
    
    ## Required job artifacts
    
    ```text
    job.json
    docs/{SCRIPT,BEAT_SHEET,TIMELINE,STORYBOARD}.md
    assets/source/
    assets/audio/{reference,raw,final}/
    assets/video/{candidates,selected,render}/
    assets/captions/
    qa/{requests,asr,contacts,reports}/
    renders/
    outputs/
    ```
    
    ## Reference routing
    
    - Read [styled-explainer.md](references/styled-explainer.md) whenever `creative.route` is `styled`; it maps every state above onto the explainer tools in `explainer/`. Choose styles with `explainer/STYLES.md`.
    - Read [generation.md](references/generation.md) for intake, content, voice, tool selection, presenter prompts, paid generation, or provider changes.
    - Read [editing.md](references/editing.md) for timeline construction, screen-demo layouts, openings, closes, captions, keyword callouts, previews, and exports.
    - Read [qa-recovery.md](references/qa-recovery.md) before accepting media or delivery, and whenever lip sync, identity, hands, exposure, freezes, captions, audio, or remote jobs fail.
    
  • explainer/examples/README.md1.4 KB72e6cc534cdeupstream ↗
    # Finished examples: the KV cache explainer in twelve styles
    
    Each folder is the performed KV cache film of one style (45 s for the nine visual styles; the three narrative styles
    `v10-reasoning`, `v11-casefile`, `v12-sitcom` tell the same topic in their own arc, from the stories
    `kv-cache-reasoning`, `kv-cache-casefile`, `kv-cache-sitcom`, 50–61 s) — the reference every `STARTER.md` idiom comes from.
    Only the authored files are committed (`index.html`, `tools/sfx.py`, `fonts.json`, project files); `lib/`, fonts, and
    audio are generated. To open one, copy it out of the skill and build it:
    
    ```bash
    X=<skill>/explainer; S=v3-notebook
    cp -R "$X/examples/kv-cache/$S" ./kv-$S
    bash "$X/tools/sync.sh" ./kv-$S $S kv-cache      # no narration audio is committed: a silent track is used
    python3 "$X/tools/fonts.py" ./kv-$S
    (cd ./kv-$S && python3 tools/sfx.py && npx --yes [email protected] preview)
    ```
    
    The three narrative styles sync with their own story: `kv-cache-reasoning` (V10), `kv-cache-casefile` (V11),
    `kv-cache-sitcom` (V12) in place of `kv-cache` above.
    
    V3, V8 and V11 build their sound from a page log first: `node lib/kit/events.mjs .` (V3, V11) or
    `node lib/kit/chalklog.mjs .` (V8) before `tools/sfx.py` (V11's example also has `bash tools/sfx.sh`, which runs both). To hear the voice, build the story with
    `tools/story.py` (MiniMax key, or `--audio` with your own recording) and sync again.
    
  • README.md20 KB3760bd81f2c7upstream ↗
    # lanshu-create-ai-presenter-video
    
    **English** | [简体中文](README.zh-CN.md)
    
    [![Agent Skills](https://img.shields.io/badge/Agent_Skills-SKILL.md-111827)](https://agentskills.io)
    ![Harness Neutral](https://img.shields.io/badge/Harness-Neutral-8B5CF6)
    ![Provider Neutral](https://img.shields.io/badge/Provider-Neutral-0EA5E9)
    ![Routes: Presenter | Styled](https://img.shields.io/badge/Routes-Presenter_%7C_Styled-0EA5E9)
    [![Explainer Styles: 12](https://img.shields.io/badge/Explainer_Styles-12-E8590C)](explainer/STYLES.md)
    [![Rendered with HyperFrames](https://img.shields.io/badge/Rendered_with-HyperFrames-2563EB)](https://hyperframes.heygen.com)
    <br>
    [![Validate Skill](https://github.com/cclank/lanshu-create-ai-presenter-video/actions/workflows/validate.yml/badge.svg)](https://github.com/cclank/lanshu-create-ai-presenter-video/actions/workflows/validate.yml)
    [![License: MIT](https://img.shields.io/badge/License-MIT-F4C430.svg)](LICENSE)
    [![Release](https://img.shields.io/github/v/release/cclank/lanshu-create-ai-presenter-video)](https://github.com/cclank/lanshu-create-ai-presenter-video/releases/latest)
    [![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)
    [![FFmpeg Required](https://img.shields.io/badge/FFmpeg-Required-007808?logo=ffmpeg&logoColor=white)](https://ffmpeg.org/)
    [![Node.js for the styled route](https://img.shields.io/badge/Node.js-styled_route-5FA04E?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
    [![GitHub stars](https://img.shields.io/github/stars/cclank/lanshu-create-ai-presenter-video?style=flat)](https://github.com/cclank/lanshu-create-ai-presenter-video/stargazers)
    <br>
    [![X @LufzzLiz](https://img.shields.io/badge/X-@LufzzLiz-000000?logo=x&logoColor=white)](https://x.com/LufzzLiz)
    [![Author: 岚叔 Lanshu](https://img.shields.io/badge/Author-%E5%B2%9A%E5%8F%94_Lanshu-C2410C)](https://x.com/LufzzLiz)
    
    > Turn a topic or script into a verified, publish-ready explainer video — presented by a digital human from one authorized portrait, or acted out on screen in one of twelve explainer styles — driven by the coding agent you already use.
    
    `lanshu-create-ai-presenter-video` is an [Agent Skill](https://agentskills.io) that takes an AI agent through the full production of an explainer video. On the **presenter route** that means script, narration, presenter generation, lip-sync, captions and keyword motion graphics, editing, rendering, and quality assurance. On the **styled route** the narration is performed scene by scene in one of twelve styles (nine visual, three narrative), from a word-timed story to a rendered film. Every stage is gated by evidence on disk, and nothing is delivered until the output passes decode and loudness checks.
    
    ## Highlights
    
    - **Harness-neutral.** A standard `SKILL.md` that loads in Claude Code, Codex, Gemini CLI, Cursor, OpenCode, GitHub Copilot, and other Agent Skills clients. Any agent that can read files and run shell commands can follow it directly.
    - **Provider-neutral.** On the presenter route, voice, presenter video, lip-sync, and speech recognition are selected by capability at run time; each job records the provider, model, parameters, and task IDs it actually used. The styled route voices with MiniMax (word timestamps come from the voice engine) or takes narration you voiced or recorded elsewhere.
    - **Twelve performed explainer styles.** Nine visual styles — editorial, tech HUD, notebook, paper pop-up, pop comic, 3D one-take, drafting sheet, chalkboard, and clay town — plus three narrative styles: derivation, casefile, and life-scene sitcom. Each has a reusable kit, starter, and example project.
    - **Audio-locked timeline.** The approved narration is the master clock for presenter motion, captions, cuts, and final duration, which keeps lip-sync and scene boundaries aligned.
    - **Evidence-gated workflow.** Eight production states, from `intake` to `verified`, computed from artifacts instead of declared by hand.
    - **Cost guardrails.** Pilot-first generation, an explicit billing statement before the first paid call, retry ceilings, and task-ID recovery to avoid duplicate charges.
    - **Verified delivery.** Master and share encodes are fully decoded and loudness-checked before any file is published.
    
    ## Two routes
    
    | Route | The video | You provide | Paid generation | Format |
    |---|---|---|---|---|
    | **Presenter** | A digital human presents; captions and keyword graphics support it | Topic or script + authorized portrait | Voice + presenter video | Any; 9:16 by default |
    | **Styled explainer** | No presenter: every narrated phrase is acted out on screen in one of twelve styles (nine visual, three narrative) | Topic or script (or your own recorded narration) | Voice only (none with your own narration) | 16:9 |
    
    The agent infers the route from your request or asks once, with the style gallery. All styles share one contract —
    word-timed captions, chapter chips, a performed closing line, a one-frame recap. Nine are visual styles that differ in
    how ideas are acted out: editorial paper, tech HUD, notebook and pen, paper pop-up book, pop comic, 3D one-take,
    drafting sheet, chalkboard, and a clay town. Below is the same moment of the bundled KV cache explainer in all nine:
    
    ![The same moment of the KV cache explainer in nine styles](explainer/gallery/nine-styles-kv-cache.jpg)
    
    Three are narrative styles, where the look comes with a way of telling and the script can draw on its suggested arc: **推演**
    (derive it on one canvas, formulas and geometry bound by colour), **案卷** (investigate it on an evidence board, from the
    anomaly to the closed case) and **小剧场** (a life-scene sitcom: a misconception, a bill or a queue that shows the cause,
    one sentence that maps the analogy to the real term). Below is the same KV cache topic told the three ways:
    
    ![The KV cache topic told in the three narrative styles](explainer/gallery/three-narrative-styles-kv-cache.jpg)
    
    A new topic becomes a playable draft in any style in a few commands — narration, word timing, captions, chapters,
    closing line, recap, and sound are generated; the agent then performs each line's scene. See
    [`explainer/STYLES.md`](explainer/STYLES.md) to choose a style and
    [`references/styled-explainer.md`](references/styled-explainer.md) for the workflow — including an optional method for
    bringing your digital human into a styled film.
    
    ## What you provide
    
    | Input | Required | Notes |
    |---|---|---|
    | Topic or finished script | Yes | A topic becomes a 45–75 second script; a supplied script keeps its natural length. |
    | Presenter image | Presenter routes | One clear adult presenter, with confirmed rights to use the image. Not needed for the styled explainer. |
    | Voice sample | No | Used only with explicit cloning authorization; otherwise a stock voice is selected and recorded. |
    | Supporting media | No | Screen recordings, images, B-roll, or brand assets, used where they prove or clarify a spoken point. |
    | Delivery preferences | No | Platform, duration, aspect ratio, style, watermark, music, and call to action. |
    
    ## How it works
    
    Presenter route:
    
    ```text
    Topic or script + authorized portrait
            │
            ▼
    Lock script and full narration ──► narration becomes the master clock
            │
            ▼
    Low-cost presenter pilot
            │
            ▼
    Presenter generation (split at real pauses when a provider caps duration)
            │
            ▼
    Audio-driven edit: captions, keyword graphics, cover, close
            │
            ▼
    Technical and visual QA
            │
            ▼
    Master, share copy, contact sheet, and delivery report
    ```
    
    Styled route:
    
    ```text
    Topic or script ──► choose a style (menu + galleries, or drafts in the nine visual styles)
            │
            ▼
    Script written for the style ──► voice with word timestamps (or your own narration)
            │
            ▼
    Draft film from the style's starter: captions, chapters, closing line, recap, sound
            │
            ▼
    Storyboard ──► every line performed on screen, on its words
            │
            ▼
    QA (check, stillness, cover) ──► render ──► master, share copy, subtitles, delivery report
    ```
    
    Each state requires evidence before a job may advance. `check_state.py` computes the state from the job's artifacts:
    
    | State | Evidence required |
    |---|---|
    | `intake` | Job created |
    | `content_locked` | Passing preflight report, script, beat sheet |
    | `audio_locked` | Decodable final narration, ASR report |
    | `visual_plan_locked` | Timeline, storyboard, approved plan |
    | `presenter_generated` | Recorded presenter capability, selected video, visual review |
    | `composition_checked` | Composition report |
    | `rendered` | Decodable render with video and audio |
    | `verified` | Master, share copy, and a delivery report with passing output loudness |
    
    On the styled route, `audio_locked` also needs a voiced `story.json` (a `--dry` draft never counts), and
    `presenter_generated` is reached by the performed film and its visual review instead of a presenter video.
    
    ## Requirements
    
    - An Agent Skills harness, or any coding agent that can read files and run shell commands.
    - Python 3.9+, FFmpeg with `ffprobe`, Bash, `jq`, `awk`, and `sed`.
    - For the presenter route: access to at least one voice synthesis, presenter video generation, and lip-sync capability — a cloud CLI, an API, or a local model — and optionally a deterministic timeline compositor such as HyperFrames for captions, motion graphics, and final rendering.
    - For the styled explainer: Node.js (HyperFrames runs with `npx`), `rsync`, Python with `numpy` (sound bed; point
      `PYTHON` at it), and a MiniMax API key (`MINIMAX_API_KEY`) for the voice and its word timestamps — or your own
      recorded narration.
    
    ## Installation
    
    The repository directory is the skill. Clone it into your harness's skills directory and keep the folder name `lanshu-create-ai-presenter-video`, which the Agent Skills specification requires to match the skill `name`.
    
    | Harness | Skills directory | Explicit invocation |
    |---|---|---|
    | Claude Code | `~/.claude/skills/` or project-level `.claude/skills/` | `/lanshu-create-ai-presenter-video` |
    | Codex | `~/.codex/skills/` | `$lanshu-create-ai-presenter-video` |
    | Other Agent Skills clients | See the client's documentation, linked from the [client list](https://agentskills.io/clients) | Client-specific |
    
    For example, with Claude Code:
    
    ```bash
    git clone https://github.com/cclank/lanshu-create-ai-presenter-video.git \
      ~/.claude/skills/lanshu-create-ai-presenter-video
    ```
    
    Run `git pull` in the installed directory to update. If you use several harnesses, clone once into each skills directory.
    
    Tagged versions and a ready-to-extract skill ZIP are available in [Releases](https://github.com/cclank/lanshu-create-ai-presenter-video/releases). See [CHANGELOG.md](CHANGELOG.md) for version history.
    
    **Agents without Agent Skills support.** Clone the repository anywhere, then start the session with:
    
    ```text
    Read /path/to/lanshu-create-ai-presenter-video/SKILL.md and follow its workflow exactly.
    ```
    
    ## Quick start
    
    Most harnesses select the skill automatically from its description, so you can describe the video you want:
    
    ```text
    Turn this script and portrait into a 30-second 16:9 presenter video with live captions.
    ```
    
    For a styled explainer you don't need to know the styles yet — ask, and the agent shows the twelve with pictures and
    recommends a few for your topic:
    
    ```text
    Make a 40-second explainer about RAG, no presenter. Which styles are there?
    ```
    
    Use the explicit invocation from the table above to guarantee selection. The skill works in the language of your request.
    
    The agent runs the bundled scripts itself. To set up a job manually, point `SKILL_DIR` at your installation:
    
    ```bash
    SKILL_DIR=~/.claude/skills/lanshu-create-ai-presenter-video
    
    python3 "$SKILL_DIR/scripts/init_job.py" \
      --job-dir ~/Videos/my-presenter-video \
      --presenter-image ~/Pictures/presenter.png \
      --topic "Context engineering in one minute" \
      --duration 60 \
      --aspect 9:16 \
      --rights-confirmed \
      --adult-presenter-confirmed
    ```
    
    Complete the manual review and upload approvals in `job.json`, then run preflight:
    
    ```bash
    python3 "$SKILL_DIR/scripts/preflight.py" ~/Videos/my-presenter-video/job.json
    ```
    
    After each stage, record its artifacts in `job.json` and let the checker compute the state:
    
    ```bash
    python3 "$SKILL_DIR/scripts/check_state.py" ~/Videos/my-presenter-video/job.json --write
    ```
    
    A styled explainer by hand, from a job directory (`X=$SKILL_DIR/explainer`):
    
    ```bash
    python3 "$SKILL_DIR/scripts/init_job.py" --job-dir . --route styled --explainer-style v8-chalkboard --topic "RAG in 40 seconds"
    python3 "$X/tools/story.py" story              # story/script.md → voice + word times → story/story.json
    bash "$X/tools/new_film.sh" v8-chalkboard story film   # a playable draft; perform each line in film/beats.js
    python3 "$X/tools/qa.py" film qa/film          # check, stillness, snapshots, cover
    bash "$X/tools/render.sh" film rag outputs     # master, share copy, subtitles
    ```
    
    ## Scripts
    
    | Script | Purpose |
    |---|---|
    | `init_job.py` | Creates a self-contained job directory, copies all inputs into it, and records job-relative paths. |
    | `preflight.py` | Validates inputs, manual review, and approvals; separates local errors from remote-generation blockers. |
    | `plan_segments.py` | Splits the locked narration at real ASR pauses when a provider caps request or reference-audio duration. |
    | `check_state.py` | Computes the evidence-backed production state and exits non-zero when the recorded state overclaims. |
    | `finalize_delivery.sh` | Builds master and share encodes, verifies full decode, delivered loudness, and black or frozen frames, then publishes them with a contact sheet and report. |
    
    ## Explainer tools
    
    Under `explainer/tools/`, used on the styled route:
    
    | Tool | Purpose |
    |---|---|
    | `story.py` | `script.md` → MiniMax voice per line with the engine's word timestamps → `story.json`; `--audio` for your own narration, `--dry` for a silent draft, `--check` for the plan and estimated length. |
    | `new_film.sh` / `new_topic.sh` | A playable film from a style's starter (or drafts in the nine visual styles at once). |
    | `docs.py` | Script, beat sheet, timeline, and a storyboard table from the story. |
    | `qa.py` | `hyperframes check`, snapshots at every chapter, stillness pairs, a cover frame, and a composition report. |
    | `render.sh` | Render, finalize with `finalize_delivery.sh`, write subtitles (SRT); `DRAFT=1` makes a 720p review copy for a phone. |
    | `srt.py`, `still_grid.py`, `fonts.py`, `sync.sh`, `stamp.py` | Subtitles, a 3×3 style comparison still, font subsets, and project plumbing. |
    
    ## Reference guides
    
    The agent loads each guide only when it reaches the matching stage, which keeps context usage low.
    
    | Guide | Covers |
    |---|---|
    | [`generation.md`](references/generation.md) | Intake, script and narration, capability selection, billing gates, segment planning, presenter prompts |
    | [`editing.md`](references/editing.md) | Timeline contract, segment seams, openings and closes, captions, keyword graphics, preview and export |
    | [`qa-recovery.md`](references/qa-recovery.md) | Acceptance gates and recovery playbooks for lip-sync, identity, seams, loudness, and remote tasks |
    | [`styled-explainer.md`](references/styled-explainer.md) | The styled explainer route: story pipeline, style starters, performing scenes, and an optional method for adding a digital human |
    | [`explainer/STYLES.md`](explainer/STYLES.md) | The style menu and gallery, common words → styles, and how to write the narration for each style |
    | [`explainer/KITS.md`](explainer/KITS.md) | The kit contract, the aesthetic baseline, the starters, and the tools |
    | [`explainer/GOTCHAS.md`](explainer/GOTCHAS.md) | HyperFrames pitfalls met while building the styles |
    
    ## Repository layout
    
    ```text
    lanshu-create-ai-presenter-video/
    ├── SKILL.md                 # Skill entry point: metadata and workflow
    ├── README.md
    ├── README.zh-CN.md
    ├── agents/
    │   └── openai.yaml          # Codex display metadata; other harnesses ignore it
    ├── assets/
    │   └── job.template.json    # Job manifest template
    ├── references/              # Stage guides loaded on demand
    ├── scripts/                 # Job setup, gates, segment planning, delivery
    ├── explainer/               # Styled explainer engine: core runtime, twelve style kits + starters, tools, examples
    │   ├── STYLES.md            # Style chooser with the gallery
    │   ├── KITS.md              # The kit contract and tools
    │   ├── kits/<style>/        # One look per style, and starter/ = the film minus the topic
    │   ├── stories/             # Example scripts (KV cache) and a draft test story
    │   ├── examples/kv-cache/   # The finished KV cache film in each style
    │   └── tools/               # story.py, new_film.sh, qa.py, render.sh, srt.py, …
    └── tests/
        ├── smoke.sh             # End-to-end test with synthetic media
        └── explainer_smoke.sh   # Styled route: intake, story, starter sync, state
    ```
    
    ## Defaults
    
    | Setting | Default |
    |---|---|
    | Format | 9:16, 1080×1920, 30 fps (styled explainer: 16:9, 1920×1080, 30 fps) |
    | Duration | 45–75 seconds from a topic; natural length for a supplied script |
    | Voice | Stock voice unless an authorized sample is provided; styled route: MiniMax `Chinese (Mandarin)_Reliable_Executive`, speed set per style |
    | Structure | Hook, 2–4 content beats, concise close |
    | Music and call to action | Off unless requested |
    | Loudness | −16 LUFS ±0.5 LU, true peak ≤ −1 dBTP; override with `PROGRAM_LUFS` |
    
    ## Safety and cost controls
    
    - Image rights and adult-presenter status are confirmed before any upload.
    - Voice cloning requires explicit authorization, and a voice is never inferred from an image.
    - Before the first paid call, the agent states the uploads, requested seconds, known price, pilot size, and retry ceiling.
    - When a provider caps duration, the quote uses the total requested seconds from the segment plan.
    - Interrupted remote tasks are polled by their saved task ID before any resubmission.
    - Work stops after three rejected paid candidates, with a summary of the recurring failure and remaining options.
    - On the styled route the only paid call is the voice — one call per line, cached, so an edit re-voices only that line; drafts in the nine visual styles cost nothing more.
    
    ## Privacy
    
    - The repository contains no API keys, access tokens, signed URLs, or user media.
    - Provider request records are stored without credentials or expiring URLs.
    - Preflight and delivery reports store file names or job-relative paths only, never absolute machine paths.
    - The styled explainer downloads font subsets from Google Fonts and jsDelivr (only the characters used); word timing
      comes from the voice provider's own timestamps, so no speech model is installed; snapshots are taken with
      `--describe false`, so frames stay local.
    
    ## Testing
    
    The smoke test drives a synthetic job from `intake` to `verified` without calling any remote service. It requires FFmpeg, `jq`, and Python 3.9+:
    
    ```bash
    bash tests/smoke.sh
    bash tests/explainer_smoke.sh   # styled explainer; also needs Node.js and rsync
    ```
    
    CI runs metadata validation, a portability check, syntax checks for the explainer engine, and both smoke tests on every push and pull request.
    
    ## Contributing
    
    Issues and pull requests are welcome. Reports from different harnesses and providers are especially valuable, as are improvements to the workflow, compatibility, and quality checks. To add another explainer style, follow the kit contract in [`explainer/KITS.md`](explainer/KITS.md) and the starter brief in [`explainer/STARTER-BRIEF.md`](explainer/STARTER-BRIEF.md).
    
    ## Author
    
    Created and maintained by **岚叔 (Lanshu)**. Follow on X for updates and new AI video workflows:
    
    [![Follow on X](https://img.shields.io/badge/Follow_on_X-@LufzzLiz-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.com/LufzzLiz)
    
    ## License
    
    Released under the [MIT License](LICENSE). Fonts, libraries, and services the explainer engine uses are listed in [`explainer/THIRD_PARTY.md`](explainer/THIRD_PARTY.md).
    
  • scripts/check_state.py9.4 KBa812334cfbf3upstream ↗
    #!/usr/bin/env python3
    """Report the production state a job's evidence supports, and optionally record it."""
    
    from __future__ import annotations
    
    import argparse
    import json
    import shutil
    import subprocess
    import sys
    from pathlib import Path
    from typing import Any, Callable
    
    
    STATES = (
        "intake",
        "content_locked",
        "audio_locked",
        "visual_plan_locked",
        "presenter_generated",
        "composition_checked",
        "rendered",
        "verified",
    )
    VIDEO_SUFFIXES = {".mp4", ".mov", ".m4v", ".mkv", ".webm"}
    
    
    class Evidence:
        def __init__(self, job: dict[str, Any], job_dir: Path) -> None:
            self.job = job
            self.job_dir = job_dir
    
        def section(self, name: str) -> dict[str, Any]:
            value = self.job.get(name)
            return value if isinstance(value, dict) else {}
    
        def resolve(self, value: str) -> Path:
            return (self.job_dir / Path(value).expanduser()).resolve()
    
        def file(self, section: str, key: str) -> tuple[Path | None, str | None]:
            value = str(self.section(section).get(key) or "").strip()
            if not value:
                return None, f"{section}.{key} is not recorded"
            path = self.resolve(value)
            if not path.is_file() or path.stat().st_size == 0:
                return None, f"{section}.{key} is missing or empty: {portable_name(value)}"
            return path, None
    
        def document(self, section: str, key: str) -> list[str]:
            _, problem = self.file(section, key)
            return [problem] if problem else []
    
        def media(self, section: str, key: str, video: bool, audio: bool) -> list[str]:
            path, problem = self.file(section, key)
            if problem:
                return [problem]
            kinds = stream_kinds(path)
            missing = [
                kind
                for kind, needed in (("video", video), ("audio", audio))
                if needed and kind not in kinds
            ]
            if missing:
                return [f"{section}.{key} has no decodable {' or '.join(missing)} stream"]
            return []
    
        def report(self, key: str, fallback: str = "") -> tuple[dict[str, Any] | None, list[str]]:
            value = str(self.section("qa").get(key) or fallback).strip()
            if not value:
                return None, [f"qa.{key} is not recorded"]
            path = self.resolve(value)
            try:
                data = json.loads(path.read_text(encoding="utf-8"))
            except (OSError, json.JSONDecodeError):
                return None, [f"qa.{key} is missing or not JSON: {portable_name(value)}"]
            return data, []
    
    
    def portable_name(value: str) -> str:
        path = Path(value).expanduser()
        return path.name if path.is_absolute() else path.as_posix()
    
    
    def stream_kinds(path: Path) -> set[str]:
        result = subprocess.run(
            ["ffprobe", "-v", "error", "-show_entries", "stream=codec_type", "-of", "json", str(path)],
            capture_output=True,
            text=True,
        )
        if result.returncode != 0:
            return set()
        try:
            streams = json.loads(result.stdout).get("streams", [])
        except json.JSONDecodeError:
            return set()
        return {stream.get("codec_type") for stream in streams}
    
    
    def content_locked(evidence: Evidence) -> list[str]:
        missing = []
        preflight, problems = evidence.report("preflight_report", "qa/reports/preflight.json")
        missing += problems
        if preflight is not None and preflight.get("ok") is not True:
            missing.append("preflight report is not ok; fix its errors and rerun preflight.py")
        missing += evidence.document("artifacts", "script")
        missing += evidence.document("artifacts", "beat_sheet")
        return missing
    
    
    def audio_locked(evidence: Evidence) -> list[str]:
        missing = evidence.media("artifacts", "final_audio", video=False, audio=True) + evidence.document(
            "qa", "asr_report"
        )
        if evidence.section("creative").get("route") == "styled":
            path, problem = evidence.file("artifacts", "story")
            if problem:
                missing.append(problem)
            else:
                try:
                    story = json.loads(path.read_text(encoding="utf-8"))
                except (OSError, json.JSONDecodeError):
                    story = {}
                    missing.append("artifacts.story is not a readable story.json")
                if story.get("draft"):
                    missing.append("artifacts.story is a --dry draft; voice it with story.py before locking audio")
        return missing
    
    
    def visual_plan_locked(evidence: Evidence) -> list[str]:
        missing = evidence.document("artifacts", "timeline") + evidence.document("artifacts", "storyboard")
        if evidence.section("plan").get("status") != "approved":
            missing.append('plan.status must be "approved"')
        return missing
    
    
    def styled_film_ready(evidence: Evidence) -> list[str]:
        """For the styled route (no presenter) this state means: the explainer film project exists and was reviewed."""
        missing = evidence.document("artifacts", "story")
        value = str(evidence.section("artifacts").get("film_project") or "").strip()
        if not value:
            missing.append("artifacts.film_project is not recorded (the explainer film's project directory)")
        elif not (evidence.resolve(value) / "index.html").is_file():
            missing.append(f"artifacts.film_project has no index.html: {portable_name(value)}")
        missing += evidence.document("qa", "manual_visual_review")
        return missing
    
    
    def presenter_generated(evidence: Evidence) -> list[str]:
        if evidence.section("creative").get("route") == "styled":
            return styled_film_ready(evidence)
        missing = []
        if not evidence.section("capabilities").get("main_presenter"):
            missing.append("capabilities.main_presenter must record the provider, model, and task IDs")
        selected = evidence.job_dir / "assets" / "video" / "selected"
        candidates = sorted(
            path
            for path in (selected.iterdir() if selected.is_dir() else [])
            if path.suffix.lower() in VIDEO_SUFFIXES
        )
        if not any("video" in stream_kinds(path) for path in candidates):
            missing.append("assets/video/selected has no decodable presenter video")
        missing += evidence.document("qa", "manual_visual_review")
        return missing
    
    
    def composition_checked(evidence: Evidence) -> list[str]:
        return evidence.document("qa", "composition_report")
    
    
    def rendered(evidence: Evidence) -> list[str]:
        return evidence.media("artifacts", "rendered", video=True, audio=True)
    
    
    def verified(evidence: Evidence) -> list[str]:
        missing = evidence.media("artifacts", "master", video=True, audio=True)
        missing += evidence.media("artifacts", "share", video=True, audio=True)
        delivery, problems = evidence.report("delivery_report")
        missing += problems
        if delivery is not None:
            if delivery.get("status") != "verified":
                missing.append('delivery report status is not "verified"')
            if delivery.get("loudness_passed") is not True:
                missing.append(
                    "delivery report has no passing output loudness; rerun finalize_delivery.sh"
                )
        return missing
    
    
    CHECKS: dict[str, Callable[[Evidence], list[str]]] = {
        "content_locked": content_locked,
        "audio_locked": audio_locked,
        "visual_plan_locked": visual_plan_locked,
        "presenter_generated": presenter_generated,
        "composition_checked": composition_checked,
        "rendered": rendered,
        "verified": verified,
    }
    
    
    def write_atomic(path: Path, text: str) -> None:
        temporary = path.with_suffix(path.suffix + ".tmp")
        temporary.write_text(text, encoding="utf-8")
        temporary.replace(path)
    
    
    def main() -> int:
        parser = argparse.ArgumentParser(description=__doc__)
        parser.add_argument("job", help="Path to job.json")
        parser.add_argument(
            "--write",
            action="store_true",
            help="Record the evidenced state in job.json, moving it back if evidence is missing",
        )
        args = parser.parse_args()
    
        if not shutil.which("ffprobe"):
            print("ERROR: ffprobe is required", file=sys.stderr)
            return 2
        job_path = Path(args.job).expanduser().resolve()
        try:
            job = json.loads(job_path.read_text(encoding="utf-8"))
        except (OSError, json.JSONDecodeError) as exc:
            print(f"ERROR: could not read job manifest {job_path.name}: {exc}", file=sys.stderr)
            return 2
    
        evidence = Evidence(job, job_path.parent)
        evidenced = STATES[0]
        blocking: dict[str, list[str]] = {}
        for state in STATES[1:]:
            missing = CHECKS[state](evidence)
            if missing:
                blocking[state] = missing
                break
            evidenced = state
    
        recorded = job.get("state")
        evidenced_index = STATES.index(evidenced)
        recorded_index = STATES.index(recorded) if recorded in STATES else None
        consistent = recorded_index is not None and recorded_index <= evidenced_index
    
        written = False
        if args.write and recorded != evidenced:
            job["state"] = evidenced
            write_atomic(job_path, json.dumps(job, ensure_ascii=False, indent=2) + "\n")
            written = True
    
        next_state = STATES[evidenced_index + 1] if evidenced_index + 1 < len(STATES) else None
        result = {
            "job": job_path.name,
            "recorded_state": recorded,
            "evidenced_state": evidenced,
            "consistent": consistent,
            "written": written,
            "next_state": next_state,
            "missing_for_next": blocking.get(next_state, []) if next_state else [],
        }
        print(json.dumps(result, ensure_ascii=False, indent=2))
        return 0 if consistent or written else 1
    
    
    if __name__ == "__main__":
        raise SystemExit(main())
    
  • scripts/finalize_delivery.sh9.5 KBe197cbf1c6cbupstream ↗
    #!/usr/bin/env bash
    
    set -euo pipefail
    
    usage() {
      printf 'Usage: %s rendered.mp4 output-dir output-stem\n' "$(basename "$0")" >&2
      printf 'Environment: PROGRAM_LUFS sets the integrated loudness target (default -16).\n' >&2
    }
    
    die() {
      printf 'ERROR: %s\n' "$*" >&2
      exit 1
    }
    
    [[ "$#" -eq 3 ]] || { usage; exit 64; }
    
    INPUT="$1"
    OUTPUT_DIR="$2"
    STEM="$3"
    
    TARGET_I="${PROGRAM_LUFS:--16}"
    TARGET_TP="-1.5"
    MAX_TP="-1.0"
    TOLERANCE_LU="0.5"
    
    [[ -f "$INPUT" && -s "$INPUT" ]] || die "input render is missing or empty: $INPUT"
    [[ "$STEM" =~ ^[A-Za-z0-9._-]+$ ]] || die "output stem contains unsupported characters: $STEM"
    [[ "$TARGET_I" =~ ^-[0-9]+([.][0-9]+)?$ ]] || die "PROGRAM_LUFS must be a negative number: $TARGET_I"
    awk -v target="$TARGET_I" 'BEGIN { exit !(target >= -40 && target <= -5) }' \
      || die "PROGRAM_LUFS must be between -40 and -5: $TARGET_I"
    
    for command in ffmpeg ffprobe jq mktemp awk sed tr; do
      command -v "$command" >/dev/null 2>&1 || die "required command unavailable: $command"
    done
    
    mkdir -p "$OUTPUT_DIR"
    OUTPUT_DIR="$(cd "$OUTPUT_DIR" && pwd -P)"
    INPUT="$(cd "$(dirname "$INPUT")" && pwd -P)/$(basename "$INPUT")"
    
    MASTER="$OUTPUT_DIR/${STEM}-master.mp4"
    SHARE="$OUTPUT_DIR/${STEM}-share.mp4"
    REPORT="$OUTPUT_DIR/${STEM}-delivery-report.json"
    CONTACT="$OUTPUT_DIR/${STEM}-contact-sheet.png"
    
    for output in "$MASTER" "$SHARE" "$REPORT" "$CONTACT"; do
      [[ ! -e "$output" ]] || die "refusing to overwrite existing output: $output"
    done
    
    TMP_ROOT="${TMPDIR:-/tmp}"
    if command -v cygpath >/dev/null 2>&1; then TMP_ROOT="$(cygpath -u "$TMP_ROOT")"; fi
    TMP_DIR="$(mktemp -d "${TMP_ROOT%/}/presenter-finalize.XXXXXX")"
    # A failed cleanup must not decide the exit status: under `set -e` a rejected rm would turn a
    # fully successful delivery into exit code 1. Clean up best-effort and stay quiet.
    trap 'rm -rf -- "$TMP_DIR" >/dev/null 2>&1 || true' EXIT INT TERM
    
    # Every output is built and verified here first; nothing reaches OUTPUT_DIR unless all checks pass.
    TMP_MASTER="$TMP_DIR/master.mp4"
    TMP_SHARE="$TMP_DIR/share.mp4"
    TMP_CONTACT="$TMP_DIR/contact.png"
    TMP_REPORT="$TMP_DIR/report.json"
    
    STREAM_JSON="$TMP_DIR/source-probe.json"
    ffprobe -v error -show_streams -show_format -of json "$INPUT" >"$STREAM_JSON"
    jq -e '.streams | any(.codec_type == "video") and any(.codec_type == "audio")' "$STREAM_JSON" >/dev/null \
      || die "input must contain decodable video and audio streams"
    
    WIDTH="$(jq -r '[.streams[] | select(.codec_type == "video")][0].width' "$STREAM_JSON" | tr -d '\r')"
    HEIGHT="$(jq -r '[.streams[] | select(.codec_type == "video")][0].height' "$STREAM_JSON" | tr -d '\r')"
    FPS="$(jq -r '[.streams[] | select(.codec_type == "video")][0].avg_frame_rate' "$STREAM_JSON" | tr -d '\r')"
    [[ "$FPS" != "0/0" && -n "$FPS" ]] || FPS="30"
    
    measure_loudness() {
      local source="$1"
      local name="$2"
      local log="$TMP_DIR/${name}-loudnorm.log"
      local json="$TMP_DIR/${name}-loudness.json"
    
      ffmpeg -hide_banner -nostdin -nostats -i "$source" \
        -map 0:a:0 -vn \
        -af "loudnorm=I=${TARGET_I}:TP=${TARGET_TP}:LRA=9:print_format=json" \
        -f null - >/dev/null 2>"$log"
      sed -n '/^{/,/^}/p' "$log" >"$json"
      jq -e . "$json" >/dev/null || die "could not parse loudness measurement for $name"
    }
    
    measure_loudness "$INPUT" source
    MEASURE_JSON="$TMP_DIR/source-loudness.json"
    jq -e '.input_i | test("^-?[0-9]+([.][0-9]+)?$") and (tonumber > -70)' "$MEASURE_JSON" >/dev/null \
      || die "input audio is silent or unmeasurable ($(jq -r .input_i "$MEASURE_JSON") LUFS); confirm the narration is routed into the render"
    
    MEASURED_I="$(jq -r .input_i "$MEASURE_JSON" | tr -d '\r')"
    MEASURED_TP="$(jq -r .input_tp "$MEASURE_JSON" | tr -d '\r')"
    MEASURED_LRA="$(jq -r .input_lra "$MEASURE_JSON" | tr -d '\r')"
    MEASURED_THRESH="$(jq -r .input_thresh "$MEASURE_JSON" | tr -d '\r')"
    OFFSET="$(jq -r .target_offset "$MEASURE_JSON" | tr -d '\r')"
    
    LOUDNORM="loudnorm=I=${TARGET_I}:TP=${TARGET_TP}:LRA=9:measured_I=${MEASURED_I}:measured_TP=${MEASURED_TP}:measured_LRA=${MEASURED_LRA}:measured_thresh=${MEASURED_THRESH}:offset=${OFFSET}:linear=true:print_format=summary"
    VIDEO_FILTER="scale=trunc(iw/2)*2:trunc(ih/2)*2:flags=lanczos,setsar=1,fps=${FPS},format=yuv420p"
    
    encode() {
      local crf="$1"
      local preset="$2"
      local audio_bitrate="$3"
      local destination="$4"
    
      ffmpeg -hide_banner -nostdin -loglevel warning -stats -i "$INPUT" \
        -map 0:v:0 -map 0:a:0 -sn -dn \
        -vf "$VIDEO_FILTER" -af "$LOUDNORM" \
        -c:v libx264 -preset "$preset" -crf "$crf" -profile:v high \
        -pix_fmt yuv420p -tag:v avc1 -fps_mode cfr \
        -color_primaries bt709 -color_trc bt709 -colorspace bt709 \
        -c:a aac -b:a "$audio_bitrate" -ar 48000 -ac 2 \
        -map_metadata -1 -map_chapters -1 -movflags +faststart \
        "$destination"
      [[ -s "$destination" ]] || die "encoder produced an empty output"
    }
    
    encode 16 slow 256k "$TMP_MASTER"
    encode 24 medium 160k "$TMP_SHARE"
    
    for file in "$TMP_MASTER" "$TMP_SHARE"; do
      ffmpeg -hide_banner -nostdin -v error -xerror -i "$file" \
        -map 0:v:0 -map 0:a:0 -f null - >/dev/null \
        || die "full decode failed: $(basename "$file")"
    done
    
    # Verify the delivered program, not just the source: compositors can duplicate mono into stereo.
    measure_loudness "$TMP_MASTER" master
    measure_loudness "$TMP_SHARE" share
    for name in master share; do
      jq -e --argjson target "$TARGET_I" --argjson tolerance "$TOLERANCE_LU" --argjson max_tp "$MAX_TP" \
        '((.input_i | tonumber) - $target) as $delta
         | (if $delta < 0 then -$delta else $delta end) <= $tolerance
           and (.input_tp | tonumber) <= $max_tp' \
        "$TMP_DIR/${name}-loudness.json" >/dev/null \
        || die "$name loudness out of tolerance: $(jq -r '"\(.input_i) LUFS, \(.input_tp) dBTP"' "$TMP_DIR/${name}-loudness.json") (target ${TARGET_I} ± ${TOLERANCE_LU} LU, true peak <= ${MAX_TP} dBTP)"
    done
    
    portable_probe() {
      local source="$1"
      local published_name="$2"
      local destination="$3"
    
      ffprobe -v error -show_streams -show_format -of json "$source" \
        | jq --arg name "$published_name" '.format.filename = $name' >"$destination"
    }
    
    # Keep shared reports portable and avoid exposing the developer machine path.
    jq --arg name "$(basename "$INPUT")" '.format.filename = $name' "$STREAM_JSON" >"$STREAM_JSON.portable"
    mv -- "$STREAM_JSON.portable" "$STREAM_JSON"
    portable_probe "$TMP_MASTER" "$(basename "$MASTER")" "$TMP_DIR/master-probe.json"
    portable_probe "$TMP_SHARE" "$(basename "$SHARE")" "$TMP_DIR/share-probe.json"
    
    ffmpeg -hide_banner -nostdin -i "$TMP_MASTER" \
      -vf 'blackdetect=d=0.10:pix_th=0.02,freezedetect=n=-60dB:d=0.40' -an -f null - \
      >/dev/null 2>"$TMP_DIR/picture-events.log"
    BLACK_EVENTS="$(grep -c 'black_start:' "$TMP_DIR/picture-events.log" || true)"
    FREEZE_EVENTS="$(grep -c 'freeze_start:' "$TMP_DIR/picture-events.log" || true)"
    
    DURATION="$(ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 "$TMP_MASTER" | tr -d '\r')"
    awk -v duration="$DURATION" 'BEGIN {
      p[1]=0.2; p[2]=duration*0.125; p[3]=duration*0.25; p[4]=duration*0.375;
      p[5]=duration*0.5; p[6]=duration*0.625; p[7]=duration*0.75;
      p[8]=duration*0.875; p[9]=duration-0.2;
      for(i=1;i<=9;i++) printf "%.6f\n", p[i]
    }' >"$TMP_DIR/timestamps.txt"
    
    if (( WIDTH > HEIGHT )); then
      CONTACT_FRAME_FILTER='scale=480:270:force_original_aspect_ratio=decrease:flags=lanczos,pad=480:270:(ow-iw)/2:(oh-ih)/2:color=black'
    elif (( HEIGHT > WIDTH )); then
      CONTACT_FRAME_FILTER='scale=270:480:force_original_aspect_ratio=decrease:flags=lanczos,pad=270:480:(ow-iw)/2:(oh-ih)/2:color=black'
    else
      CONTACT_FRAME_FILTER='scale=360:360:force_original_aspect_ratio=decrease:flags=lanczos,pad=360:360:(ow-iw)/2:(oh-ih)/2:color=black'
    fi
    
    index=0
    while IFS= read -r timestamp; do
      index=$((index + 1))
      printf -v frame '%s/frame-%02d.png' "$TMP_DIR" "$index"
      ffmpeg -hide_banner -nostdin -loglevel error -ss "$timestamp" -i "$TMP_MASTER" \
        -frames:v 1 -vf "$CONTACT_FRAME_FILTER" -update 1 "$frame"
    done <"$TMP_DIR/timestamps.txt"
    
    ffmpeg -hide_banner -nostdin -loglevel error -framerate 1 -start_number 1 \
      -i "$TMP_DIR/frame-%02d.png" -frames:v 1 \
      -vf 'tile=3x3:padding=12:margin=12:color=0x101218' -update 1 "$TMP_CONTACT"
    
    jq -n \
      --arg status verified \
      --arg input "$(basename "$INPUT")" \
      --arg master "$(basename "$MASTER")" \
      --arg share "$(basename "$SHARE")" \
      --arg contact "$(basename "$CONTACT")" \
      --arg duration "$DURATION" \
      --argjson target_i "$TARGET_I" \
      --argjson max_tp "$MAX_TP" \
      --argjson tolerance "$TOLERANCE_LU" \
      --argjson black_events "$BLACK_EVENTS" \
      --argjson freeze_events "$FREEZE_EVENTS" \
      --slurpfile measured "$MEASURE_JSON" \
      --slurpfile master_loudness "$TMP_DIR/master-loudness.json" \
      --slurpfile share_loudness "$TMP_DIR/share-loudness.json" \
      --slurpfile source_probe "$STREAM_JSON" \
      --slurpfile master_probe "$TMP_DIR/master-probe.json" \
      --slurpfile share_probe "$TMP_DIR/share-probe.json" \
      '{status:$status,input:$input,master:$master,share:$share,contact_sheet:$contact,duration_s:($duration|tonumber),loudness_target:{integrated_lufs:$target_i,tolerance_lu:$tolerance,max_true_peak_dbtp:$max_tp},loudness_passed:true,source_loudness:$measured[0],master_loudness:$master_loudness[0],share_loudness:$share_loudness[0],source_probe:$source_probe[0],master_probe:$master_probe[0],share_probe:$share_probe[0],full_decode_passed:true,black_frame_events:$black_events,freeze_events:$freeze_events}' \
      >"$TMP_REPORT"
    
    # Publish only after every check passed; the report goes last as the completion marker.
    mv -- "$TMP_MASTER" "$MASTER"
    mv -- "$TMP_SHARE" "$SHARE"
    mv -- "$TMP_CONTACT" "$CONTACT"
    mv -- "$TMP_REPORT" "$REPORT"
    
    printf 'Master: %s\nShare: %s\nReport: %s\nContact: %s\n' "$MASTER" "$SHARE" "$REPORT" "$CONTACT"
    
  • scripts/init_job.py7.8 KBcb7f77be265aupstream ↗
    #!/usr/bin/env python3
    """Create a non-overwriting presenter-video job from minimal inputs."""
    
    from __future__ import annotations
    
    import argparse
    import json
    import re
    import shutil
    import sys
    from pathlib import Path
    
    
    SKILL_DIR = Path(__file__).resolve().parent.parent
    TEMPLATE = SKILL_DIR / "assets" / "job.template.json"
    JOB_DIRECTORIES = (
        "docs",
        "assets/source",
        "assets/audio/reference",
        "assets/audio/raw",
        "assets/audio/final",
        "assets/video/candidates",
        "assets/video/selected",
        "assets/video/render",
        "assets/captions",
        "qa/requests",
        "qa/asr",
        "qa/contacts",
        "qa/reports",
        "renders",
        "outputs",
    )
    ASPECT_DEFAULTS = {
        "9:16": (1080, 1920),
        "16:9": (1920, 1080),
        "1:1": (1080, 1080),
        "4:5": (1080, 1350),
    }
    ROUTES = ("presenter", "styled")
    STYLES = (
        "v1-editorial",
        "v2-signal",
        "v3-notebook",
        "v4-paper",
        "v5-comic",
        "v6-cinematic",
        "v7-drafting",
        "v8-chalkboard",
        "v9-clay",
        "v10-reasoning",
        "v11-casefile",
        "v12-sitcom",
    )
    
    
    def existing_file(path_text: str, label: str) -> Path:
        path = Path(path_text).expanduser().resolve()
        if not path.is_file():
            raise ValueError(f"{label} does not exist or is not a file: {path}")
        return path
    
    
    def copy_into_job(source: Path, job_dir: Path, relative_dir: str) -> str:
        """Copy an input into the job and return its job-relative path."""
        destination_dir = job_dir / relative_dir
        destination = destination_dir / source.name
        counter = 2
        while destination.exists():
            destination = destination_dir / f"{source.stem}-{counter}{source.suffix}"
            counter += 1
        shutil.copy2(source, destination)
        return destination.relative_to(job_dir).as_posix()
    
    
    def slugify(value: str) -> str:
        slug = re.sub(r"[^a-z0-9]+", "-", value.lower()).strip("-")
        return slug or "presenter-video"
    
    
    def parse_args() -> argparse.Namespace:
        parser = argparse.ArgumentParser(description=__doc__)
        parser.add_argument("--job-dir", required=True)
        parser.add_argument(
            "--route",
            choices=ROUTES,
            default="presenter",
            help="presenter: digital-human video (default); styled: a performed explainer in one of the nine "
            "explainer styles, no presenter",
        )
        parser.add_argument(
            "--explainer-style",
            choices=STYLES,
            help="explainer style for the styled route (see explainer/STYLES.md)",
        )
        parser.add_argument("--presenter-image", help="required for the presenter route")
        source = parser.add_mutually_exclusive_group(required=True)
        source.add_argument("--topic")
        source.add_argument("--script", help="Existing local script file")
        parser.add_argument("--voice-sample")
        parser.add_argument("--supporting-media", action="append", default=[])
        parser.add_argument("--language", default="auto")
        parser.add_argument("--audience", default="general")
        parser.add_argument("--duration", type=float, default=60.0)
        parser.add_argument(
            "--aspect",
            choices=sorted(ASPECT_DEFAULTS),
            help="default 9:16 for the presenter route; the styled route is 16:9",
        )
        parser.add_argument("--width", type=int)
        parser.add_argument("--height", type=int)
        parser.add_argument("--fps", type=int, choices=(24, 25, 30, 50, 60), default=30)
        parser.add_argument("--style", default="credible contemporary presenter")
        parser.add_argument("--watermark", default="")
        parser.add_argument("--cta", default="")
        parser.add_argument("--rights-confirmed", action="store_true")
        parser.add_argument("--adult-presenter-confirmed", action="store_true")
        parser.add_argument("--remote-upload-approved", action="store_true")
        parser.add_argument("--voice-clone-approved", action="store_true")
        return parser.parse_args()
    
    
    def main() -> int:
        args = parse_args()
        styled = args.route == "styled"
        if not styled and not args.presenter_image:
            raise ValueError("--presenter-image is required for the presenter route")
        if styled and not args.explainer_style:
            raise ValueError(f"--explainer-style is required for --route styled (one of: {', '.join(STYLES)})")
        if styled and args.aspect not in (None, "16:9"):
            raise ValueError("the styled route renders 16:9 (1920x1080); omit --aspect or pass 16:9")
        if args.aspect is None:
            args.aspect = "16:9" if styled else "9:16"
        if not 5 <= args.duration <= 1800:
            raise ValueError("--duration must be between 5 and 1800 seconds")
        if (args.width is None) != (args.height is None):
            raise ValueError("--width and --height must be supplied together")
    
        width, height = ASPECT_DEFAULTS[args.aspect]
        if args.width is not None and args.height is not None:
            width, height = args.width, args.height
            if min(width, height) < 256 or max(width, height) > 7680:
                raise ValueError("custom dimensions must be between 256 and 7680 pixels")
    
        presenter_image = (
            existing_file(args.presenter_image, "presenter image") if args.presenter_image else None
        )
        script = existing_file(args.script, "script") if args.script else None
        voice_sample = (
            existing_file(args.voice_sample, "voice sample") if args.voice_sample else None
        )
        supporting_media = [
            existing_file(item, "supporting media") for item in args.supporting_media
        ]
    
        job_dir = Path(args.job_dir).expanduser().resolve()
        if job_dir.exists() and any(job_dir.iterdir()):
            raise ValueError(f"job directory must be absent or empty: {job_dir}")
        job_dir.mkdir(parents=True, exist_ok=True)
        for relative in JOB_DIRECTORIES:
            (job_dir / relative).mkdir(parents=True, exist_ok=True)
    
        # Copy inputs so the job stays self-contained and portable; originals stay untouched.
        manifest = json.loads(TEMPLATE.read_text(encoding="utf-8"))
        manifest["job_id"] = slugify(job_dir.name)
        manifest["input"]["topic"] = (args.topic or "").strip()
        manifest["input"]["script_path"] = (
            copy_into_job(script, job_dir, "assets/source") if script else ""
        )
        manifest["input"]["presenter_image"] = (
            copy_into_job(presenter_image, job_dir, "assets/source") if presenter_image else ""
        )
        manifest["input"]["voice_sample"] = (
            copy_into_job(voice_sample, job_dir, "assets/audio/reference")
            if voice_sample
            else ""
        )
        manifest["input"]["supporting_media"] = [
            copy_into_job(item, job_dir, "assets/source") for item in supporting_media
        ]
        manifest["input"]["rights_confirmed"] = args.rights_confirmed
        manifest["input"]["adult_presenter_confirmed"] = args.adult_presenter_confirmed
        manifest["input"]["remote_upload_approved"] = args.remote_upload_approved
        manifest["input"]["voice_clone_approved"] = args.voice_clone_approved
    
        creative = manifest["creative"]
        creative.update(
            {
                "language": args.language,
                "audience": args.audience,
                "duration_target_s": args.duration,
                "aspect": args.aspect,
                "width": width,
                "height": height,
                "fps": args.fps,
                "style": f"explainer style {args.explainer_style}" if styled else args.style,
                "route": args.route,
                "explainer_style": args.explainer_style or "",
                "watermark": args.watermark,
                "cta": args.cta,
            }
        )
    
        if styled:
            manifest["voice"]["rate"] = 1.1   # the styled route's story.py voices at speed 1.1 by default
        job_path = job_dir / "job.json"
        job_path.write_text(
            json.dumps(manifest, ensure_ascii=False, indent=2) + "\n",
            encoding="utf-8",
        )
        print(json.dumps({"job": str(job_path), "state": "intake"}, ensure_ascii=False))
        return 0
    
    
    if __name__ == "__main__":
        try:
            raise SystemExit(main())
        except ValueError as exc:
            print(f"ERROR: {exc}", file=sys.stderr)
            raise SystemExit(2)
    
  • scripts/plan_segments.py7.0 KBf89f86b3798fupstream ↗
    #!/usr/bin/env python3
    """Plan presenter generation segments that fit a provider duration cap.
    
    Cuts fall inside real pauses of the locked narration, so no segment starts or
    ends mid-word. Timings are ASR sentence or word spans normalized to a JSON list
    of {"start": seconds, "end": seconds, "text": "..."} objects.
    """
    
    from __future__ import annotations
    
    import argparse
    import json
    import math
    import subprocess
    import sys
    from pathlib import Path
    from typing import Any
    
    
    EPSILON = 1e-6
    
    
    def parse_args() -> argparse.Namespace:
        parser = argparse.ArgumentParser(description=__doc__)
        parser.add_argument("--timings", required=True, help="ASR spans as a JSON list")
        duration = parser.add_mutually_exclusive_group(required=True)
        duration.add_argument("--audio", help="Locked narration file (probed for duration)")
        duration.add_argument("--audio-duration", type=float, help="Narration seconds")
        parser.add_argument(
            "--cap",
            type=float,
            required=True,
            help="Longest segment the provider accepts; use the smallest of its video and reference-audio limits",
        )
        parser.add_argument("--min-gap", type=float, default=0.25, help="Shortest pause to cut in")
        parser.add_argument("--min-segment", type=float, default=2.0, help="Shortest segment to plan")
        parser.add_argument(
            "--whole-seconds",
            action="store_true",
            help="Provider requests and bills whole seconds; prefer integer cuts inside pauses",
        )
        parser.add_argument("--output", help="Also write the plan to this JSON file")
        return parser.parse_args()
    
    
    def probe_duration(path: Path) -> float:
        result = subprocess.run(
            [
                "ffprobe",
                "-v",
                "error",
                "-show_entries",
                "format=duration",
                "-of",
                "default=nw=1:nk=1",
                str(path),
            ],
            check=True,
            capture_output=True,
            text=True,
        )
        return float(result.stdout.strip())
    
    
    def load_spans(path: Path) -> list[tuple[float, float]]:
        data: Any = json.loads(path.read_text(encoding="utf-8"))
        if isinstance(data, dict):
            for key in ("sentences", "segments", "words"):
                if isinstance(data.get(key), list):
                    data = data[key]
                    break
        if not isinstance(data, list) or not data:
            raise ValueError("timings must be a non-empty JSON list of {start, end} spans")
        spans = []
        for item in data:
            try:
                start, end = float(item["start"]), float(item["end"])
            except (KeyError, TypeError, ValueError):
                raise ValueError(f"timing entry needs numeric start and end: {item!r}")
            if end < start:
                raise ValueError(f"timing entry ends before it starts: {item!r}")
            spans.append((start, end))
        return sorted(spans)
    
    
    def candidate_cuts(
        spans: list[tuple[float, float]], min_gap: float, whole_seconds: bool
    ) -> list[dict[str, Any]]:
        cuts = []
        speech_end = spans[0][1]
        for start, end in spans[1:]:
            # Overlapping word spans never form a pause.
            if start - speech_end >= min_gap:
                middle = (speech_end + start) / 2
                cut = round(middle, 3)
                if whole_seconds:
                    integers = range(math.ceil(speech_end), math.floor(start) + 1)
                    if integers:
                        cut = float(min(integers, key=lambda value: abs(value - middle)))
                cuts.append({"cut": cut, "pause": [speech_end, start]})
            speech_end = max(speech_end, end)
        return cuts
    
    
    def plan(
        spans: list[tuple[float, float]],
        total: float,
        cap: float,
        min_gap: float,
        min_segment: float,
        whole_seconds: bool,
    ) -> dict[str, Any]:
        if spans[-1][1] > total + 0.25:
            raise ValueError(
                f"timings end at {spans[-1][1]:.3f}s but the narration lasts {total:.3f}s; "
                "use timings from the locked audio"
            )
        limit = math.floor(cap + EPSILON) if whole_seconds else cap
        if limit < min_segment:
            raise ValueError("--cap must be at least --min-segment")
    
        cuts = candidate_cuts(spans, min_gap, whole_seconds)
        boundaries = [0.0]
        pauses: list[list[float] | None] = []
        while total - boundaries[-1] > limit + EPSILON:
            start = boundaries[-1]
            window = [
                cut
                for cut in cuts
                if start + min_segment <= cut["cut"] <= start + limit + EPSILON
                and total - cut["cut"] >= min_segment
            ]
            if not window:
                raise ValueError(
                    f"no pause of at least {min_gap}s between {start:.3f}s and "
                    f"{start + limit:.3f}s; supply word-level timings, lower --min-gap, "
                    "or rewrite the sentence"
                )
            # The latest usable pause keeps segments long, so the edit has fewer seams.
            chosen = window[-1]
            boundaries.append(chosen["cut"])
            pauses.append(chosen["pause"])
        boundaries.append(total)
        pauses.append(None)
    
        segments = []
        for index, (start, end) in enumerate(zip(boundaries, boundaries[1:]), start=1):
            duration = round(end - start, 3)
            requested = math.ceil(duration - EPSILON) if whole_seconds else duration
            segments.append(
                {
                    "index": index,
                    "audio_start_s": round(start, 3),
                    "audio_end_s": round(end, 3),
                    "requested_seconds": requested,
                    "authored_start_s": round(start, 3),
                    "authored_duration_s": duration,
                    "source_start_s": 0.0,
                    "ends_in_pause_s": pauses[index - 1],
                }
            )
    
        return {
            "audio_duration_s": round(total, 3),
            "cap_s": cap,
            "min_gap_s": min_gap,
            "whole_seconds": whole_seconds,
            "segments": segments,
            "seams_s": [round(value, 3) for value in boundaries[1:-1]],
            "total_requested_seconds": round(
                sum(segment["requested_seconds"] for segment in segments), 3
            ),
        }
    
    
    def main() -> int:
        args = parse_args()
        if args.cap <= 0 or args.min_gap < 0 or args.min_segment <= 0:
            raise ValueError("--cap and --min-segment must be positive; --min-gap cannot be negative")
        spans = load_spans(Path(args.timings).expanduser())
        total = (
            probe_duration(Path(args.audio).expanduser())
            if args.audio
            else float(args.audio_duration)
        )
        if total <= 0:
            raise ValueError("narration duration must be positive")
    
        result = plan(spans, total, args.cap, args.min_gap, args.min_segment, args.whole_seconds)
        text = json.dumps(result, ensure_ascii=False, indent=2) + "\n"
        if args.output:
            output = Path(args.output).expanduser()
            output.parent.mkdir(parents=True, exist_ok=True)
            output.write_text(text, encoding="utf-8")
        print(text, end="")
        return 0
    
    
    if __name__ == "__main__":
        try:
            raise SystemExit(main())
        except (ValueError, subprocess.CalledProcessError) as exc:
            print(f"ERROR: {exc}", file=sys.stderr)
            raise SystemExit(2)
    
  • scripts/preflight.py8.4 KBcdf4e3844bb6upstream ↗
    #!/usr/bin/env python3
    """Validate a presenter-video job and write a machine-readable preflight report."""
    
    from __future__ import annotations
    
    import argparse
    import json
    import shutil
    import subprocess
    import sys
    from pathlib import Path
    from typing import Any
    
    
    def probe(path: Path) -> dict[str, Any]:
        result = subprocess.run(
            [
                "ffprobe",
                "-v",
                "error",
                "-show_entries",
                "stream=index,codec_type,codec_name,width,height,pix_fmt,sample_rate,channels,r_frame_rate:format=duration,size,bit_rate",
                "-of",
                "json",
                str(path),
            ],
            check=True,
            capture_output=True,
            text=True,
        )
        return json.loads(result.stdout)
    
    
    def portable_name(value: str) -> str:
        """Show job-relative paths as written and absolute paths by file name only."""
        path = Path(value).expanduser()
        return path.name if path.is_absolute() else path.as_posix()
    
    
    def require_file(
        value: str, label: str, job_dir: Path, errors: list[str]
    ) -> Path | None:
        if not value:
            errors.append(f"missing {label}")
            return None
        path = (job_dir / Path(value).expanduser()).resolve()
        if not path.is_file():
            errors.append(f"{label} is not a file: {portable_name(value)}")
            return None
        return path
    
    
    def write_atomic(path: Path, text: str) -> None:
        temporary = path.with_suffix(path.suffix + ".tmp")
        temporary.write_text(text, encoding="utf-8")
        temporary.replace(path)
    
    
    def main() -> int:
        parser = argparse.ArgumentParser(description=__doc__)
        parser.add_argument("job", help="Path to job.json, e.g. ~/Videos/my-presenter-video/job.json")
        args = parser.parse_args()
        if not shutil.which("ffprobe"):
            print("ERROR: ffprobe is required", file=sys.stderr)
            return 2
    
        job_path = Path(args.job).expanduser().resolve()
        if not job_path.is_file():
            print(f"ERROR: job manifest does not exist: {job_path}", file=sys.stderr)
            return 2
        job = json.loads(job_path.read_text(encoding="utf-8"))
        job_dir = job_path.parent
        errors: list[str] = []
        remote_blockers: list[str] = []
        warnings: list[str] = []
        media: dict[str, Any] = {}
    
        input_data = job.get("input", {})
        topic = str(input_data.get("topic", "")).strip()
        script_text = str(input_data.get("script_path", "")).strip()
        if not topic and not script_text:
            errors.append("topic or script_path is required")
        if script_text:
            require_file(script_text, "script", job_dir, errors)
    
        creative = job.get("creative", {})
        route = str(creative.get("route") or "presenter")
        if route not in ("presenter", "styled"):
            errors.append(f"creative.route must be presenter or styled, not {route!r}")
        has_presenter = route != "styled"
        if route == "styled":
            style = str(creative.get("explainer_style") or "")
            kits = Path(__file__).resolve().parent.parent / "explainer" / "kits"
            if not style or not (kits / style / "starter").is_dir():
                errors.append(f"creative.explainer_style must name a style in explainer/kits, not {style!r}")
            if (int(creative.get("width") or 0), int(creative.get("height") or 0)) != (1920, 1080):
                errors.append("the styled route renders 1920x1080 (16:9)")
    
        image = (
            require_file(str(input_data.get("presenter_image", "")), "presenter image", job_dir, errors)
            if has_presenter
            else None
        )
        if image:
            try:
                media["presenter_image"] = probe(image)
                streams = [
                    stream
                    for stream in media["presenter_image"].get("streams", [])
                    if stream.get("codec_type") == "video"
                ]
                if not streams:
                    errors.append("presenter image has no decodable image/video stream")
                else:
                    width = int(streams[0].get("width") or 0)
                    height = int(streams[0].get("height") or 0)
                    if min(width, height) < 512:
                        warnings.append(f"presenter image is low resolution: {width}x{height}")
            except (subprocess.CalledProcessError, json.JSONDecodeError):
                errors.append(f"could not decode presenter image: {image.name}")
    
        voice_value = str(input_data.get("voice_sample", "")).strip()
        if voice_value:
            voice = require_file(voice_value, "voice sample", job_dir, errors)
            if voice:
                try:
                    media["voice_sample"] = probe(voice)
                    streams = [
                        stream
                        for stream in media["voice_sample"].get("streams", [])
                        if stream.get("codec_type") == "audio"
                    ]
                    if not streams:
                        errors.append("voice sample has no audio stream")
                    duration = float(media["voice_sample"].get("format", {}).get("duration") or 0)
                    if duration < 4:
                        warnings.append(f"voice sample is short: {duration:.3f}s")
                    if duration > 60:
                        warnings.append(f"voice sample is unusually long: {duration:.3f}s")
                except (subprocess.CalledProcessError, json.JSONDecodeError, ValueError):
                    errors.append(f"could not decode voice sample: {voice.name}")
            if not input_data.get("voice_clone_approved"):
                remote_blockers.append("voice_clone_approved must be true before voice cloning")
        else:
            warnings.append("no voice sample supplied; use and record a stock voice")
    
        supporting_reports = []
        for value in input_data.get("supporting_media", []):
            path = require_file(str(value), "supporting media", job_dir, errors)
            if path:
                try:
                    supporting_reports.append({"file": path.name, "probe": probe(path)})
                except (subprocess.CalledProcessError, json.JSONDecodeError):
                    errors.append(f"could not decode supporting media: {path.name}")
        media["supporting_media"] = supporting_reports
    
        if has_presenter and not input_data.get("rights_confirmed"):
            remote_blockers.append("rights_confirmed must be true before presenter synthesis")
        if has_presenter and not input_data.get("adult_presenter_confirmed"):
            remote_blockers.append("adult_presenter_confirmed must be true before presenter synthesis")
        if not input_data.get("remote_upload_approved"):
            remote_blockers.append(
                "remote_upload_approved must be true before remote generation"
                if has_presenter
                else "remote_upload_approved must be true before the script text is sent to a TTS provider "
                "(not needed when the user supplies the narration and story.py --audio is used)"
            )
    
    
        manual = job.get("manual_input_review", {})
        for key in ("image_viewed", "single_clear_face", "image_has_no_unwanted_text"):
            if has_presenter and not manual.get(key):
                errors.append(f"manual_input_review.{key} must be true")
        if voice_value:
            for key in ("voice_sample_listened", "single_clear_speaker"):
                if not manual.get(key):
                    errors.append(f"manual_input_review.{key} must be true")
    
        duration = float(creative.get("duration_target_s") or 0)
        if not 5 <= duration <= 1800:
            errors.append("creative.duration_target_s must be between 5 and 1800")
        width = int(creative.get("width") or 0)
        height = int(creative.get("height") or 0)
        if min(width, height) < 256 or max(width, height) > 7680:
            errors.append("creative width/height must be between 256 and 7680")
        if int(creative.get("fps") or 0) not in (24, 25, 30, 50, 60):
            errors.append("creative.fps must be one of 24, 25, 30, 50, or 60")
    
        report_path = job_dir / "qa" / "reports" / "preflight.json"
        report_path.parent.mkdir(parents=True, exist_ok=True)
        report = {
            "ok": not errors,
            "remote_ready": not errors and not remote_blockers,
            "job": job_path.name,
            "errors": errors,
            "remote_blockers": remote_blockers,
            "warnings": warnings,
            "media": media,
        }
        write_atomic(report_path, json.dumps(report, ensure_ascii=False, indent=2) + "\n")
        job.setdefault("qa", {})["preflight_report"] = "qa/reports/preflight.json"
        write_atomic(job_path, json.dumps(job, ensure_ascii=False, indent=2) + "\n")
        print(json.dumps(report, ensure_ascii=False, indent=2))
        return 0 if not errors else 1
    
    
    if __name__ == "__main__":
        raise SystemExit(main())
    
  • references/editing.md4.0 KB270613b33ff4upstream ↗
    # Editing
    
    Read this file for the visual plan, deterministic timeline, openings, closes, screen demos, captions, keyword callouts, covers, previews, and exports.
    
    ## Visual routes
    
    - **Presenter-led:** the presenter carries the explanation; add one concise visual idea per beat.
    - **Screen-demo:** preserve real UI readability; introduce the presenter large at chapter starts, then shrink the same continuous video into a verified safe region.
    - **Mixed explainer:** assign supporting media only where it proves or clarifies narration.
    
    Do not fabricate product evidence. Label conceptual visuals clearly.
    
    ## Timeline contract
    
    The locked narration defines duration and semantic boundaries. Every clip keeps three independent values:
    
    - authored start in the final video;
    - authored duration;
    - source-media start.
    
    When an opening changes length, shift authored starts while preserving presenter source offsets. Keep video sources muted and use approved external narration as the program clock. Prefer one continuous presenter source and source-time slices over regenerated chapter clips.
    
    When the presenter was generated in segments, place each one at its planned `authored_start_s` with source start `0` and authored duration equal to its audio slice. Independent segments leave small expression or pose differences at each seam. Mask every seam with a short opacity breath of about `0.2s`, a planned layout or shape change, or a cut to supporting media, and inspect frames at seam `±0.1s`.
    
    Use hard cuts at settled semantic pauses. Add transitions only when they clarify structure. Preserve a quiet tail so the last word, gesture, and mouth position finish naturally.
    
    ## Opening, body, and close
    
    - Establish the topic and payoff within the first few seconds.
    - Design the time-zero frame as a deliberate cover frame.
    - Keep opening copy away from eyes, mouth, and the hand-motion path.
    - Use the same visual system across the cover, chapters, captions, keywords, progress, and close.
    - End with a conclusion or one requested next step. Do not add promotional copy without a brief requirement.
    
    ## Captions
    
    Generate word timestamps from the final audio. Split into short semantic phrases, normally one readable line. A practical baseline is about `40ms` visual lead and `120ms` tail hold when neighboring phrases allow it.
    
    Keep captions clear of the face, UI, watermark, progress line, and platform controls. Highlight one meaningful term per phrase. Make entrances and exits quick enough to preserve reading stability.
    
    ## Presenter-side keyword presets
    
    Use keyword callouts to amplify selected spoken beats. Avoid repeating one identical card throughout the video.
    
    Rotate a small family of presets such as:
    
    - radial burst;
    - tilted ribbon or sticker;
    - hand-drawn circle or marker stroke;
    - large/small type contrast;
    - staggered word-chip cluster;
    - double-layer outline lockup.
    
    Bind each callout to a real spoken stress or ASR word anchor. Separate the entry timing of the kicker, main word, secondary word, marker, rays, and outline by a few frames. Let the callout settle briefly, then collapse before the next idea. Keep it inside a consistent presenter-side safe region and verify the complete motion path does not cover the face or hands.
    
    ## Composition and preview
    
    Use a deterministic compositor available in the environment. For HyperFrames:
    
    1. load the current HyperFrames workflow and domain instructions;
    2. give all timed media explicit start, duration, track, and source offset;
    3. run the required composition check with representative emphasis and transition samples;
    4. inspect time zero, chapter cuts, layout changes, keyword beats, captions, close, and final frame;
    5. open the final Studio preview and obtain approval before rendering;
    6. render at delivery quality only after approval.
    
    Measure the assembled stereo program after rendering. Mono narration duplicated into stereo can measure about 3 LU louder, so perform final program normalization from the rendered file. `finalize_delivery.sh` does this and verifies the delivered master and share loudness before publishing either file.
    
  • references/generation.md5.8 KB0c16dc7d3d77upstream ↗
    # Generation
    
    Read this file for intake, content, narration, capability selection, paid generation, presenter prompts, or provider changes.
    
    ## Inputs and authorization
    
    Required:
    
    - a topic or script;
    - one local presenter image with one clear adult face;
    - confirmed image rights before remote upload;
    - confirmed adult status from the user.
    
    Optional:
    
    - authorized voice sample;
    - screen recordings, B-roll, images, charts, brand assets, or source links;
    - audience, duration, language, aspect, style, watermark, music, CTA, provider preference, or previous episode.
    
    Inspect the real image. Record visible anchors only: framing, hair, glasses, clothing, accessories, hands, furniture, background geometry, camera height, crop, light, exposure, white balance, embedded text, logos, occlusion, multiple faces, and resolution. Do not infer sensitive traits.
    
    When a voice sample exists, listen for one speaker, audible speech duration, language, noise, echo, clipping, music, silence, and codec damage. Record whether cloning is authorized. Keep the original unchanged.
    
    ## Content and narration
    
    For a topic, use one clear spine:
    
    ```text
    hook → promise → 2–4 useful beats → synthesis → close
    ```
    
    For a supplied script, preserve factual meaning while improving breath, pronunciation, sentence length, and transitions. Flag material factual edits for approval.
    
    Generate the complete approved narration before visual work. Keep one voice identity and one synthesis configuration. Split only for operational limits or clean semantic sections. Preserve raw and normalized copies.
    
    Run ASR against final audio. Review names, numbers, English tokens, omitted words, repeated words, and tail speech. Use actual audio durations for every later cut.
    
    ## Capability routing
    
    Resolve capabilities at execution time:
    
    | Capability | Acceptance priority |
    |---|---|
    | Voice generation | authorization, identity, pronunciation, rate control, clean audio |
    | Main presenter | exact audio support, semantic lip sync, identity stability, required duration |
    | Short motion | stable face, one controllable gesture, fixed camera, economical retry |
    | Lip-sync repair | preserves accepted motion while replacing mouth timing with exact audio |
    | Word-timestamp ASR | accurate word start/end times and reviewable output |
    | Timeline compositor | explicit source offsets, frame-accurate seek, deterministic render |
    | Encoder and QA | local probe, loudness, decode, black-frame and contact-sheet support |
    
    Inspect current installed tools and official documentation when availability, duration, pricing, or request fields may have changed. Prefer a user-selected provider when it passes the gates. Otherwise choose the simplest available capability that does.
    
    Record the actual provider, model, version, region, parameters, price evidence date, task ID, and sanitized request body in `job.json`. Ask before a provider change that affects cost, privacy, voice, appearance, or quality.
    
    ## Billing and pilot gate
    
    Before the first remote or paid call, state:
    
    - files or data being uploaded;
    - capability and selected tool;
    - requested seconds or units;
    - known price or that the cost is unknown;
    - pilot duration and retry ceiling;
    - expected output and main risks.
    
    Generate the smallest useful pilot. Continue to a full run only after technical checks and visual review pass. Do not generate a long clip when the edit uses only a short range.
    
    ## Duration caps and segments
    
    Prefer one continuous audio-driven presenter source. When the provider caps request duration or reference-audio length below the narration length, split by the narration's real pauses:
    
    - Use the smallest of the provider's video-duration and reference-audio limits as the cap.
    - Normalize the final-audio ASR sentence or word timings to `[{"start": s, "end": s, "text": "..."}]` and run `scripts/plan_segments.py`. It cuts only inside pauses of at least `0.25s`, takes the latest usable pause so the edit has as few seams as possible, and keeps every segment at least `2s` long.
    - With `--whole-seconds`, it prefers an integer cut that lies inside a pause; otherwise it cuts at the pause midpoint and requests the rounded-up seconds. Do not move a cut onto an integer that falls inside speech to save a billed second.
    - Send each segment exactly its planned audio slice. Reuse the same image, seed, framing, wardrobe, light, and motion constraints for the pilot and every segment.
    - Quote `total_requested_seconds` from the plan in the billing statement. Record the plan in `plan.segment_plan` and task IDs keyed by range, such as `"00-10": "<task id>"`.
    - Generated clips often run a few frames longer than requested. Trim them through authored duration and source offset; never time-stretch a presenter clip.
    
    ## Presenter prompt structure
    
    Write prompts in this order:
    
    1. Bind the user image as the sole presenter and scene reference.
    2. List only visible identity, clothing, accessory, camera, framing, background, light, exposure, and white-balance anchors.
    3. Request realistic skin, hair, eye moisture, fabric, breathing, bilateral blinking, and restrained head motion.
    4. Supply exact dialogue through the tool's supported audio or dialogue field.
    5. Tie one physically plausible gesture to one phrase and approximate time.
    6. Reserve a settled, closed-mouth tail.
    7. Exclude identity, face, glasses, hair, wardrobe, skin tone, background, camera, lighting, finger, hand, dialogue, text, logo, watermark, and extra-person drift.
    
    For the main presenter, prioritize mouth timing and identity. Keep hands low or outside frame. For an opening or close, one small gesture may carry the hook or CTA. Keep hands below the collarbone, away from the face and lens, and end the movement before the tail hold.
    
    If the body performance is accepted but mouth timing is visibly late, preserve the motion plate and apply lip-sync repair with the exact locked audio and no duration extension.
    
  • references/qa-recovery.md4.6 KB69ecf65b66a5upstream ↗
    # QA and recovery
    
    Read this file before accepting generated media or delivery, and whenever a production fault appears.
    
    ## Acceptance gates
    
    ### Inputs
    
    - Topic or script exists.
    - Presenter image decodes and contains one reviewed adult face.
    - Image rights, adult confirmation, and remote-upload permission are recorded.
    - Any voice sample contains one authorized speaker.
    - Supporting media is probed and its provenance is recorded.
    
    ### Audio
    
    - Final ASR matches the intended script once, without material omissions or additions.
    - Sections have consistent loudness, commonly near `-17 LUFS`.
    - Assembled program loudness is commonly `-16 ± 0.5 LUFS` unless the destination specifies another target.
    - No clipped words, doubled tracks, echo, clicks, unexpected silence, or truncated tail.
    - Measure the final stereo file; section measurements alone are insufficient. The finalizer records `master_loudness` and `share_loudness` and refuses to publish outside `±0.5 LU` or above `-1.0 dBTP`.
    
    ### Presenter
    
    - Expected resolution, frame rate, duration, and decodable streams.
    - No black frames, long exact-frame freezes, progressive darkening, or duration extension.
    - Identity, face geometry, hair, glasses, clothing, accessories, background, crop, exposure, and white balance remain coherent.
    - Mouth follows names, numbers, English tokens, plosives, and phrase endings.
    - Blinks are sparse and bilateral; gestures occur once and settle; hands remain plausible and away from the face.
    - Tail ends with a settled face and resting mouth.
    - Segmented output keeps identity, framing, and light continuous at every seam `±0.1s`.
    
    ### Composition and delivery
    
    - No flash, duplicate presenter, source-time reset, missing overlay, overflow, face obstruction, caption collision, or unreadable UI.
    - Opening, callouts, captions, watermark, progress, and platform safe zones remain compatible.
    - Master and share files have the expected duration, dimensions, frame rate, codec, pixel format, and audio rate.
    - Both files fully decode.
    - Every `freeze_events` entry in the delivery report corresponds to an intentional still shot.
    - Contact sheet covers opening, chapters, emphasis graphics, close, and final frame.
    - Watch the complete video at normal speed before delivery.
    
    ## Recovery rules
    
    ### Interrupted remote task
    
    Poll the saved task ID and download a succeeded result. Resubmit only after a confirmed failure or cancellation.
    
    ### Voice identity or loudness changes
    
    Confirm one synthesis identity and configuration. Regenerate the mismatching section, normalize again, and rerun ASR. If the final render is louder than the source, confirm video is muted and apply whole-program two-pass loudness correction.
    
    ### Presenter changes between chapters
    
    Use one continuous audio-driven source with source-time slices. When splitting is unavoidable, lock identity, framing, parameters, light, and quiet edge holds.
    
    ### Body motion works but mouth is late
    
    Keep the accepted motion plate. Apply lip-sync repair with the exact locked audio and no duration extension. Check speech anchors at numbers, plosives, English tokens, and final syllables.
    
    ### Visible jump at a segment seam
    
    Confirm each segment used its planned audio slice and identical generation settings. Mask small expression or pose differences with a short opacity breath, a layout change, or supporting media. Regenerate only the affected segment when identity, framing, or light differs structurally.
    
    ### Finalizer rejects loudness
    
    Nothing was published. Confirm every video source is muted and narration is not routed twice, then re-render. When the destination requires another target, rerun with `PROGRAM_LUFS` set to it.
    
    ### Face, glasses, hands, or light drift
    
    Retry from the original image with reduced motion and explicit camera, exposure, and white-balance locks. Simplify the gesture and keep hands low. Structural face or finger faults require regeneration; grading cannot correct them.
    
    ### Frozen picture-in-picture
    
    Confirm the layout uses moving video, source offsets advance continuously, and no poster frame or identical-frame padding replaced the presenter.
    
    ### Captions or keyword graphics feel wrong
    
    Regenerate timings from the final audio. Split by meaning, shorten visible phrases, and adjust small lead/hold margins. Bind keyword motion to actual spoken anchors and verify its complete path against the face, hands, UI, and captions.
    
    ### Three rejected paid candidates
    
    Stop. Preserve candidates, prompts, task IDs, cost, and rejection notes. Summarize the recurring failure, remaining options, expected additional cost, and the single variable proposed for the next attempt.
    
  • references/styled-explainer.md13 KB9eb72669e072upstream ↗
    # Styled explainer route
    
    Read this file when the job's `creative.route` is `styled`: a performed explainer in one of twelve styles (nine visual
    styles and three narrative styles — 推演, 案卷, 小剧场 — whose look comes with a way of telling), with no presenter. The styles carry the explanation on their own — the work is in performing every line well. The engine
    lives in `explainer/`:
    `explainer/STYLES.md` to choose a style, `explainer/KITS.md` for the contract and tools, each style's
    `kits/<style>/starter/STARTER.md` for how to perform a beat, and `examples/kv-cache/<style>/` for a finished film.
    
    The input is a topic or script; the only paid generation is the voice. Films render 16:9 at 1920×1080 and end with a
    one-frame recap. For 9:16 vertical delivery use the presenter route. To bring a digital human into a styled film, see
    the last section — an optional method, not a separate route.
    
    ## Requirements
    
    - Node.js with `npx` (HyperFrames is run as `npx --yes [email protected]`, override with `HYPERFRAMES`), FFmpeg,
      `rsync`, Python 3.9+ with numpy for the sound bed (`PYTHON=…` to choose the interpreter), network access for
      Google Fonts and jsDelivr (font subsets).
    - Voice and word timing: the built-in path calls MiniMax T2A once per line (`MINIMAX_API_KEY`; `MINIMAX_BASE_URL` for the
      China endpoint) and takes each word's timestamp from the voice engine itself — no speech-recognition model to install.
      Narration the user voiced or recorded elsewhere works too (`story.py --audio`): lines are found at its pauses and word
      times are estimated (about 0.15 s), fine for captions and slightly looser for word-timed beats.
    
    ### Voice setup · 配音
    
    The default voice is MiniMax `Chinese (Mandarin)_Reliable_Executive` (a steady male voice) at speed 1.1; set `voice:`
    and `speed:` in `script.md` to change it — the user picks a system voice ID from the voice library in their MiniMax
    console. The international API is `https://api.minimax.io` (the default); mainland-China accounts use their console's
    endpoint via `MINIMAX_BASE_URL` (typically `https://api.minimaxi.com`). Write names, numbers and acronyms in the
    script as they should be read; after voicing, check how numbers, units and English were read: `story/audio/pronounce.txt` lists each line as the engine read it
    (e.g. 「2 GB」 read as 「二吉字节」 — rewrite the script as 「两 GB」 if that is wanted, and voice that line again).
    Narration the user recorded themselves needs no TTS at all: `story.py story --audio`.
    
    ## Job layout
    
    The usual job directory gains two folders:
    
    ```text
    story/      script.md → audio/narration.wav, audio/tts/ (per-line voice + word timestamps), audio/pronounce.txt, story.json
    film/       the HyperFrames project (from the style's starter); film/beats.js holds the performed scenes
    ```
    
    `X` below is `$SKILL_DIR/explainer`.
    
    ## Production, state by state
    
    ### intake
    
    ```bash
    python3 "$SKILL_DIR/scripts/init_job.py" --job-dir ~/Videos/kv-cache --route styled \
      --explainer-style v3-notebook --topic "讲清楚 KV cache"
    ```
    
    If the user has not chosen a style, show them `explainer/STYLES.md` (attach or link its two gallery images) and
    recommend two or three from the topic and audience, one reason each; or build drafts in the nine visual styles (below)
    and let them pick from a still grid. Settle the style before the script is locked — the script is written for it (next
    step); for a narrative style (V10–V12), adapt its suggested arc to the topic.
    
    ### content_locked
    
    Write `story/script.md` for the chosen style — tone, sentence length, `speed:` and the recap `length:` from the
    "按风格写稿" table in `explainer/STYLES.md` — with the content rules of [generation.md](generation.md): chapters (`## key | 章节标题`), one narration line per text line, `> beat notes` under each chapter
    (the starters show them in the draft), `## end` with `emphasis:` for the closing line, `## recap` points, and a
    `## facts` block — the only facts the film may put on screen. See `explainer/stories/kv-cache/script.md`.
    
    For a narrative style, these arcs are useful starting points; adapt chapter count and order to the explanation:
    V10 推演 a question → the figure built step by step → the pattern
    → the result and its cost; V11 案卷 the anomaly and suspects → evidence → the cause proven → the fix → the case closed
    (cause / fix / cost / lesson, facts sourced, illustrative numbers marked 「示意」); V12 小剧场 one life scene and one
    character: the misconception → a bill, a queue or an object comparison that shows the cause → the new way → the analogy
    mapped to the real term, closed in one sentence. The bundled `explainer/stories/kv-cache-reasoning`, `kv-cache-casefile`
    and `kv-cache-sitcom` are the same topic written in the three arcs. A sitcom's setting and characters can change
    with the topic; the demo's milk-tea shop is an example. Keep facts sourced and label illustrative numbers.
    
    ```bash
    python3 "$X/tools/story.py" story --check      # chapters, lines and the estimated length
    python3 "$X/tools/docs.py" story docs          # docs/SCRIPT.md and docs/BEAT_SHEET.md from script.md
    ```
    
    Record `artifacts.script = docs/SCRIPT.md` and `artifacts.beat_sheet = docs/BEAT_SHEET.md`. Show the user the script and
    the estimated length before anything is voiced; that is their approval of the content and of the voice cost.
    
    ### audio_locked
    
    `python3 "$X/tools/story.py" story` voices every line with MiniMax (cached per line, levelled to −18 LUFS so delivery
    loudness passes), or voice the script with any TTS — or use the user's own recording — and run
    `python3 "$X/tools/story.py" story --audio narration.wav` (the script text must match what is said).
    
    Read the printed word times against the audio; fix the script or voice before going on. Record
    `artifacts.final_audio = story/audio/narration.wav`, `artifacts.story = story/story.json`, and
    `qa.asr_report = story/story.json` (its per-word times are the ASR evidence).
    Read `story/audio/pronounce.txt` for misread numbers or terms. A `--dry` draft never locks the audio
    (`check_state.py` refuses it); `story.json` records `timing: engine | estimated | draft`.
    
    ### visual_plan_locked
    
    Build the draft film — it plays end to end with captions, chapter chip, closing line, recap and sound, and a
    「待演绎」 placeholder per line:
    
    ```bash
    bash "$X/tools/new_film.sh" <style> story film
    # to compare styles first:  DEST_ROOT=drafts JOBS=3 bash "$X/tools/new_topic.sh" story
    #                           python3 "$X/tools/still_grid.py" drafts 9.5,30 qa/contacts
    ```
    
    Run `python3 "$X/tools/docs.py" story docs` again: it adds `docs/TIMELINE.md` and a `docs/STORYBOARD.md` table with one
    row per line (time and words). Fill its "on screen" column: what is performed, on which word, using the style's idioms
    (`film/STARTER.md`) and the finished example. Make t = 0 a composed frame (the first scene already on screen, not an
    empty stage) — it is the first thing a feed shows. Send the user the storyboard and a phone-friendly draft
    (`DRAFT=1 bash "$X/tools/render.sh" film <name> qa`, about a minute) rather than a developer preview; after their
    approval of style and storyboard, set `plan.status` to `"approved"`.
    
    ### presenter_generated (here: the performed film)
    
    There is no presenter on this route; the state means the performed film exists. Replace the placeholders in
    `film/beats.js` with the storyboard's scenes, scene by scene, every beat time from `story.at()` / `story.phrase()` /
    `story.span()`. Rerun `python3 "$X/tools/fonts.py" film` and `(cd film && bash tools/sfx.sh)` after edits. Record
    `artifacts.film_project = film`, and write what you looked at and judged to a file (e.g. `qa/reports/visual-review.md`)
    and record its path as `qa.manual_visual_review` — the checker needs a file, not a sentence.
    
    ### composition_checked
    
    ```bash
    python3 "$X/tools/qa.py" film qa/film      # check + snapshots + stillness + cover.png → qa/film/composition.json
    ```
    
    It exits non-zero when `check` fails or a stillness pair is under 0.001 (a parked camera or frozen picture). Look at
    the snapshots in `qa/film/contacts/` (every chapter, the closing line, the recap). `composition_file_too_large` and
    `nested_structure_needs_subcomposition` warnings are expected for these single-file films. Record
    `qa.composition_report = qa/film/composition.json`. Get the user's approval before the final render, with a new
    `DRAFT=1` render (or the Studio preview, if they prefer it).
    
    ### rendered → verified
    
    ```bash
    bash "$X/tools/render.sh" film <name> outputs        # renders film/renders/<name>.mp4, then finalize_delivery.sh
    ```
    
    `render.sh` calls this skill's `finalize_delivery.sh` (loudness, full decode, contact sheet), writes
    `outputs/<name>.srt` (subtitles for Bilibili CC and other platforms) and `outputs/<name>-freeze.txt`; a performed
    explainer should have 0 freeze events. `SKIP_RENDER=1` repeats only the finalize step. Record
    `artifacts.rendered = film/renders/<name>.mp4`, `artifacts.master`, `artifacts.share`, `artifacts.caption_json` (or the
    SRT), `qa.delivery_report`, then `check_state.py --write` until `verified`. Hand the user the master, the share copy,
    the SRT, and `qa/film/cover.png` as the upload cover.
    
    Recording artifacts is plain JSON editing, e.g.
    `jq '.artifacts.film_project = "film"' job.json > job.tmp && mv job.tmp job.json`.
    
    ## Re-styling an earlier film
    
    Keep the job's `story/` (script and locked audio — no new voice cost). Build a second film from the same story in the
    new style (`new_film.sh <style> story film-<style>`), perform its `beats.js` from the storyboard, and get the
    storyboard re-approved; QA and delivery as above, with its own output name. The first film stays untouched.
    
    ## Performing the content
    
    - Act out every narrated phrase on screen, on its word: the thing named appears, moves, changes or is compared
      when it is said. A page that only reveals text reads as a slide.
    - One plain-language note per chapter; the real term next to every analogy.
    - Only facts from the script and the `## facts` block; label illustrative visuals as illustrative.
    - Keep the style's aesthetic baseline (`explainer/KITS.md` §2): readable sizes at 1080p, one accent with one meaning,
      no dead space, something meaningful in motion every second, the camera never parks.
    - Starters are drafts: never deliver a film whose `beats.js` still shows 「待演绎」 placeholders.
    
    ## Optional: bringing a digital human into a styled film
    
    The styles are designed without a presenter, and most topics do not need one. When a user wants their digital human
    in a styled film anyway (a personal channel, a familiar face for the hook), this method was tried on two finished
    films (V2 and V9, both passing `check`); use it as a recipe, not a default.
    
    1. **One clock.** Lock the narration the presenter route's way and generate the presenter from it (pilot, cost
       statement, evidence — [generation.md](generation.md)). Build the story from that exact audio:
       `story.py story --audio assets/audio/final/narration.wav`. The film is then timed to the words the presenter's
       mouth is already synced to; never re-voice one side only. Join a segmented presenter into one track first.
    2. **Give the presenter its own space — never cover the film.** Each style fills the frame with performed content;
       anything laid on top hides it (and fails the layout and contrast checks). Shrink the film instead: wrap every
       visual child of the composition root in CSS `translate` / `scale` (they compose with the style's own transforms)
       and place the presenter in the freed column.
    3. **Three states, morphing over ~0.6 s:** *on stage* for the hook and the closing line (film at about 70 % on one
       side, the presenter on a tall card beside it); *badge* while the film explains (film at about 86 %, the presenter as
       a small circle in the narrow column); *off* for the recap (film full size). Default keys from the story: on stage
       until the first line ends, badge until just before the closing line, on stage for it, off before the recap.
    4. **Belong to the style.** Frame the presenter with the style's tokens (`--kit-accent` border, `--kit-surface`
       behind), the face focused near the top third (`object-position: 50% 30%`), the video muted (the film's narration
       track is the presenter's audio).
    5. **Drive it from the film's clock.** Every frame is a pure function of t: update the presenter frame and the film
       transform inside the style's frame function (or a hook it calls each frame), and give the `<video>` its own
       `data-start` / `data-duration` so HyperFrames owns its playback.
    6. **Verify** as for any styled film (check 0 errors, stillness pairs), plus normal-speed playback of the hook and the
       closing line for lip-sync.
    
  • assets/job.template.json1.9 KB70625cdba946upstream ↗
    {
      "schema_version": 1,
      "job_id": "replace-me",
      "state": "intake",
      "mode": "automation",
      "input": {
        "topic": "",
        "script_path": "",
        "presenter_image": "",
        "voice_sample": "",
        "supporting_media": [],
        "rights_confirmed": false,
        "adult_presenter_confirmed": false,
        "remote_upload_approved": false,
        "voice_clone_approved": false
      },
      "creative": {
        "language": "auto",
        "audience": "general",
        "goal": "explain clearly",
        "route": "presenter",
        "explainer_style": "",
        "duration_target_s": 60,
        "aspect": "9:16",
        "width": 1080,
        "height": 1920,
        "fps": 30,
        "style": "credible contemporary presenter",
        "watermark": "",
        "cta": ""
      },
      "voice": {
        "strategy": "auto",
        "voice_id": "",
        "rate": 1.06,
        "segment_lufs": -17,
        "program_lufs": -16
      },
      "plan": {
        "status": "draft",
        "opening_target_s": 4,
        "closing_target_s": 5,
        "chapters": [],
        "requested_generation_seconds": 0,
        "segment_plan": "",
        "estimated_cost": null,
        "price_evidence_date": "",
        "pilot_approved": false,
        "paid_generation_approved": false,
        "retry_ceiling": 3
      },
      "capabilities": {
        "voice_generation": {},
        "main_presenter": {},
        "short_motion": {},
        "lipsync_repair": {},
        "word_timestamp_asr": {},
        "timeline_compositor": {},
        "encoder_qa": {}
      },
      "manual_input_review": {
        "image_viewed": false,
        "single_clear_face": false,
        "image_has_no_unwanted_text": false,
        "voice_sample_listened": false,
        "single_clear_speaker": false
      },
      "artifacts": {
        "script": "",
        "beat_sheet": "",
        "timeline": "",
        "storyboard": "",
        "story": "",
        "film_project": "",
        "final_audio": "",
        "caption_json": "",
        "rendered": "",
        "master": "",
        "share": ""
      },
      "qa": {
        "preflight_report": "",
        "asr_report": "",
        "composition_report": "",
        "delivery_report": "",
        "manual_visual_review": ""
      }
    }
    
  • .github/workflows/validate.yml2.0 KBd914976063bcupstream ↗
    name: Validate Skill
    
    on:
      push:
      pull_request:
    
    permissions:
      contents: read
    
    jobs:
      validate:
        runs-on: ubuntu-latest
        steps:
          - name: Check out repository
            uses: actions/checkout@v4
    
          - name: Set up Python
            uses: actions/setup-python@v5
            with:
              python-version: "3.9"
    
          - name: Validate metadata and source files
            run: |
              grep -q '^name: lanshu-create-ai-presenter-video$' SKILL.md
              grep -q 'lanshu-create-ai-presenter-video' agents/openai.yaml
              python3 -m py_compile scripts/*.py
              for script in scripts/*.py; do python3 "$script" --help >/dev/null; done
              bash -n scripts/finalize_delivery.sh
              bash -n tests/smoke.sh
              bash -n tests/explainer_smoke.sh
              python3 -m json.tool assets/job.template.json >/dev/null
    
          - name: Validate the explainer engine
            run: |
              find explainer -name '*.py' -print0 | xargs -0 python3 -m py_compile
              find explainer -name '*.sh' -print0 | xargs -0 -n1 bash -n
              find explainer \( -name '*.js' -o -name '*.mjs' \) -print0 | xargs -0 -n1 node --check
              for story in explainer/stories/*/story.json; do python3 -m json.tool "$story" >/dev/null; done
    
          - name: Check repository portability
            run: |
              if grep -R -n '/Users/' README.md README.zh-CN.md SKILL.md agents assets references scripts tests explainer; then
                echo 'Machine-specific home path found.' >&2
                exit 1
              fi
    
      smoke:
        runs-on: ubuntu-latest
        steps:
          - name: Check out repository
            uses: actions/checkout@v4
    
          - name: Set up Python
            uses: actions/setup-python@v5
            with:
              python-version: "3.9"
    
          - name: Install FFmpeg
            run: sudo apt-get update && sudo apt-get install -y --no-install-recommends ffmpeg
    
          - name: Run end-to-end smoke test
            run: bash tests/smoke.sh
    
          - name: Run styled explainer smoke test
            run: bash tests/explainer_smoke.sh
    
  • .gitignore360 B4f34128315f3upstream ↗
    __pycache__/
    *.py[cod]
    .DS_Store
    .idea/
    .vscode/
    .env
    .env.*
    !.env.example
    
    # Generated production jobs and media do not belong in the Skill repository.
    work/
    jobs/
    outputs/
    renders/
    *.mp4
    *.mov
    *.wav
    *.mp3
    _work/
    
    # Voice caches of the bundled stories (story.py regenerates them; only script.md, story.json, STORYBOARD.md are kept)
    explainer/stories/*/audio/
    
  • agents/openai.yaml443 B97079cd47c81upstream ↗
    interface:
      display_name: "岚叔 · 通用数字人与讲解视频制作"
      short_description: "从主题或文案制作并验收完整讲解视频:数字人口播,或十二种风格的动画讲解(九种画风 + 三种讲法)"
      default_prompt: "Use $lanshu-create-ai-presenter-video to turn my topic or script into a verified publish-ready explainer video: help me choose between a digital-human presenter and a styled explainer."
    
  • CHANGELOG.md2.2 KB998d26850c18upstream ↗
    # Changelog
    
    ## 1.0.0 — 2026-10-12
    
    First tagged release of the presenter and styled explainer workflow.
    
    ### Added
    
    - Twelve explainer styles: the original nine visual styles plus **推演 / Derivation** (`v10-reasoning`), **案卷 / Casefile** (`v11-casefile`), and **小剧场 / Sitcom** (`v12-sitcom`).
    - Reusable kits, starters, KV cache examples, and a separate gallery for the three narrative styles.
    - Optional narration pronunciation entries and pause markers, with regression coverage for engine word timestamps and plain narration.
    - A release version file and bilingual README links to releases and this changelog.
    
    ### Fixed
    
    - Windows / Git Bash temporary paths and native-tool CRLF output in smoke tests and delivery finalization, including portrait contact-sheet orientation ([#3](https://github.com/cclank/lanshu-create-ai-presenter-video/pull/3)).
    - Windows npm cache lookup and Chrome executable suffixes for the notebook and chalkboard sound readers ([#4](https://github.com/cclank/lanshu-create-ai-presenter-video/pull/4)). The notebook reader retains its existing Chrome sandbox default.
    - Edge cases in reusable starters, QA error reporting, and still-grid output directory creation.
    
    ### Validation
    
    - Offline presenter and styled smoke suites, all twelve starter sync/stamp checks, and four narration timing/pronunciation regressions.
    - Native macOS notebook/chalkboard cue extraction and simulated Windows CRLF, temporary-directory, cache, and executable-path checks.
    - Native Windows end-to-end execution remains unverified; the GitHub workflow runs on Ubuntu.
    
    ### Thanks
    
    Thanks to [@happysharegithub](https://github.com/happysharegithub) for the Windows compatibility contributions in #3 and #4.
    
    ### 中文说明
    
    本版将讲解风格扩展到十二种,新增推演、案卷、小剧场及其风格包、起步模板、KV cache 示例和独立预览图;加入可选读音配置与停顿标记。合并了 Windows 路径、换行和声音读取器的兼容修复,并保留笔记本读取器的 Chrome 沙箱默认设置。
    
    离线流程、十二种模板和四项配音时序回归检查通过。Windows 已完成条件模拟核验,完整实机流程仍待验证。
    
  • explainer/core/core.js11 KB935b37842f04upstream ↗
    /* explainer core — the style-agnostic runtime every style kit and every film shares.
     *
     * Load as a classic script (<script src="core/core.js">) before the film's own script; it defines
     * window.ExplainerCore. Nothing here knows about a topic or a look:
     *   - time helpers and eases (every frame is a pure function of time t)
     *   - track(): camera / value keyframes through monotone Hermite with Fritsch–Carlson limiting
     *   - Story: narration lines, word times, chapters, recap — loaded from a topic's story.json
     *   - Captions / Chapters: DOM builders whose look comes entirely from the style kit's CSS
     *   - place(): put an overlay element at a screen point with an anchor, opacity and scale
     */
    (function (g) {
      "use strict";
      const clamp01 = (x) => (x < 0 ? 0 : x > 1 ? 1 : x);
      const pr = (t, a, d) => clamp01((t - a) / d);
      const lerp = (a, b, u) => a + (b - a) * u;
      // fade in over fi after a, fade out over fo before b
      const env = (t, a, b, fi = 0.3, fo = 0.3) => Math.min(pr(t, a, fi), 1 - pr(t, b - fo, fo));
      const E = {
        linear: (u) => u,
        o2: (u) => 1 - (1 - u) * (1 - u),
        o3: (u) => 1 - Math.pow(1 - u, 3),
        o4: (u) => 1 - Math.pow(1 - u, 4),
        i3: (u) => u * u * u,
        i2: (u) => u * u,
        io2: (u) => (u < 0.5 ? 2 * u * u : 1 - Math.pow(-2 * u + 2, 2) / 2),
        io3: (u) => (u < 0.5 ? 4 * u * u * u : 1 - Math.pow(-2 * u + 2, 3) / 2),
        io4: (u) => (u < 0.5 ? 8 * u * u * u * u : 1 - Math.pow(-2 * u + 2, 4) / 2),
        back: (u) => { const c1 = 1.6, c3 = c1 + 1; return u <= 0 ? 0 : 1 + c3 * Math.pow(u - 1, 3) + c1 * Math.pow(u - 1, 2); },
      };
      // deterministic pseudo-random in [0,1)
      function hash(n) { const s = Math.sin(n * 127.1 + 311.7) * 43758.5453; return s - Math.floor(s); }
    
      // keys: [[t, v1, v2, ...], ...] sorted by t. Returns [v1, v2, ...] at time t, never overshooting a hold.
      function track(keys, t) {
        const n = keys.length;
        if (t <= keys[0][0]) return keys[0].slice(1);
        if (t >= keys[n - 1][0]) return keys[n - 1].slice(1);
        let i = 0;
        while (keys[i + 1][0] < t) i++;
        const k0 = keys[Math.max(0, i - 1)], k1 = keys[i], k2 = keys[i + 1], k3 = keys[Math.min(n - 1, i + 2)];
        const h = k2[0] - k1[0], u = (t - k1[0]) / h, u2 = u * u, u3 = u2 * u, out = [];
        for (let d = 1; d < k1.length; d++) {
          const s01 = i === 0 ? 0 : (k1[d] - k0[d]) / (k1[0] - k0[0]);
          const s12 = (k2[d] - k1[d]) / h;
          const s23 = i + 2 > n - 1 ? 0 : (k3[d] - k2[d]) / (k3[0] - k2[0]);
          let m1 = i === 0 || s01 * s12 <= 0 ? 0 : (s01 + s12) / 2;
          let m2 = i + 1 === n - 1 || s12 * s23 <= 0 ? 0 : (s12 + s23) / 2;
          if (s12 === 0) m1 = m2 = 0;
          else {
            const a = m1 / s12, b = m2 / s12, r = a * a + b * b;
            if (r > 9) { const tau = 3 / Math.sqrt(r); m1 = tau * a * s12; m2 = tau * b * s12; }
          }
          out.push((2 * u3 - 3 * u2 + 1) * k1[d] + (u3 - 2 * u2 + u) * h * m1 + (-2 * u3 + 3 * u2) * k2[d] + (u3 - u2) * h * m2);
        }
        return out;
      }
    
      /* Story: wraps a topic's story.json
       *   { title, duration, lines: [{i, text, start, end, words: [[unit, t], ...]}],
       *     chapters: [{n, title, start, end}], end: {words: [[unit, t, emphasis?], ...]}, recap: {...} }
       * at(line, unit, nth=1)  -> time the nth occurrence of `unit` is spoken in line `line` (1-based)
       * phrase(line, text)     -> time the first unit of `text` is spoken (text must appear in the line)
       * span(line, text)       -> { start, end }: when `text` starts, and when the unit after it starts (or the line ends)
       * idx(line, unit, nth=1) -> index of that unit in line.words;  word(line, k) -> time of the k-th unit
       * lineAt(t)              -> the line being spoken at t (or null between lines)
       * spoken(line)           -> the line's units without punctuation: [[unit, t], ...]
       * chapterOf(line)        -> the chapter object of a line (null for the closing line)
       */
      function Story(data) {
        this.data = data;
        this.title = data.title;
        this.duration = data.duration;
        this.lines = data.lines;
        this.chapters = data.chapters || [];
        this.recap = data.recap || null;
        this.end = data.end || null; // the closing line: { line, start, emphasis }
      }
      Story.prototype.line = function (i) { return this.lines[i - 1]; };
      Story.prototype.at = function (line, unit, nth = 1) {
        const L = this.line(line);
        let k = 0;
        for (const [u, t] of L.words) if (u === unit && ++k === nth) return t;
        throw new Error(`story.at: "${unit}" #${nth} not in line ${line}: ${L.text}`);
      };
      Story.prototype.phrase = function (line, text) {
        return this.span(line, text).start;
      };
      Story.prototype.span = function (line, text) {
        const L = this.line(line);
        const units = L.words.map((w) => w[0]), want = text.replace(/\s/g, "");
        for (let s = 0; s < units.length; s++) {
          let acc = "", e = s;
          for (; e < units.length && acc.length < want.length; e++) acc += units[e];
          if (acc === want) {
            let n = e;
            while (n < units.length && !/[A-Za-z\d㐀-鿿]/.test(units[n])) n++;
            return { start: L.words[s][1], end: n < units.length ? L.words[n][1] : L.end };
          }
        }
        throw new Error(`story.phrase: "${text}" not in line ${line}: ${L.text}`);
      };
      Story.prototype.idx = function (line, unit, nth = 1) {
        const L = this.line(line);
        let k = 0;
        for (let i = 0; i < L.words.length; i++) if (L.words[i][0] === unit && ++k === nth) return i;
        throw new Error(`story.idx: "${unit}" #${nth} not in line ${line}: ${L.text}`);
      };
      Story.prototype.word = function (line, k) { return this.line(line).words[k][1]; };
      Story.prototype.lineAt = function (t) {
        return this.lines.find((L) => t >= L.start && t < L.end) || null;
      };
      Story.prototype.spoken = function (line) {
        return this.line(line).words.filter((w) => /[A-Za-z\d㐀-鿿]/.test(w[0]));
      };
      // the chapter a line belongs to (story.py writes line.chapter; older stories fall back to the line's start time)
      Story.prototype.chapterOf = function (line) {
        const L = this.line(line);
        if (L.chapter) return this.chapters.find((c) => c.key === L.chapter) || null;
        return this.chapters.find((c) => L.start >= c.start - 0.25 && L.start < c.end) || null;
      };
      Story.prototype.chapterAt = function (t) {
        return this.chapters.find((c) => t >= c.start && t < c.end) || null;
      };
    
      /* Captions: one element per narration line, one span per unit. The kit's CSS styles
       *   .kit-cap (the line box), .kit-cap > span (a unit), and the custom property --lit (0..1) per span.
       * opts (all optional; the defaults keep the original behaviour):
       *   groups   [[firstLine, lastLine], ...] to show several short lines in one caption box
       *   lead, tail   seconds the box shows before its first word / after its last line ends (0.12 / 0.18)
       *   skipEnd  true: no box for story.end.line (when Kit.title performs the closing line)
       *   air      em of space where a Latin / number unit touches CJK (e.g. 0.2); spans also get .kit-air-l / .kit-air-r
       *   clamp    true: neighbouring boxes never overlap, even with long lead / tail (they hand over at the gap's middle) */
      function Captions(container, story, opts = {}) {
        const endLine = opts.skipEnd && story.end ? story.end.line : null;
        const groups = opts.groups || story.lines.filter((L) => L.i !== endLine).map((L) => [L.i, L.i]);
        this.boxes = groups.map(([a, b]) => {
          const el = document.createElement("div");
          el.className = "kit-cap";
          container.appendChild(el);
          const spans = [];
          for (let i = a; i <= b; i++) {
            story.line(i).words.forEach(([u, t], k, arr) => {
              const s = document.createElement("span");
              const next = arr[k + 1];
              // keep a space between two Latin/number units, never inside CJK
              const latin = /[A-Za-z\d]$/.test(u) && next && /^[A-Za-z\d]/.test(next[0]);
              s.textContent = latin ? u + " " : u;
              el.appendChild(s);
              spans.push({ s, t });
            });
          }
          if (opts.air) airLatin(spans.map((x) => x.s), opts.air);
          return { el, a: story.line(a).start, b: story.line(b).end, spans };
        });
        this.lead = opts.lead ?? 0.12;
        this.tail = opts.tail ?? 0.18;
        this.boxes.forEach((c, k) => {
          c.from = c.a - this.lead;
          c.to = c.b + this.tail;
          if (!opts.clamp) return;
          const prev = this.boxes[k - 1], next = this.boxes[k + 1];
          if (prev) c.from = Math.max(c.from, (prev.b + c.a) / 2);
          if (next) c.to = Math.min(c.to, (c.b + next.a) / 2);
        });
      }
      const CJK = /[㐀-鿿]/, LATIN = /[A-Za-z\d]/;
      function airLatin(spans, em) {
        spans.forEach((s, k) => {
          if (!LATIN.test(s.textContent)) return;
          const p = spans[k - 1], n = spans[k + 1];
          if (p && CJK.test(p.textContent.slice(-1))) { s.classList.add("kit-air-l"); s.style.marginLeft = em + "em"; }
          if (n && CJK.test(n.textContent.charAt(0))) { s.classList.add("kit-air-r"); s.style.marginRight = em + "em"; }
        });
      }
      Captions.prototype.render = function (t) {
        for (const c of this.boxes) {
          const o = env(t, c.from, c.to, 0.18, 0.2);
          c.el.style.opacity = o.toFixed(3);
          c.el.style.visibility = o > 0 ? "visible" : "hidden";
          if (o <= 0) continue;
          for (const w of c.spans) w.s.style.setProperty("--lit", E.o2(pr(t, w.t - 0.04, 0.16)).toFixed(3));
        }
      };
    
      /* Chapters: a single chip element with .kit-chap-n and .kit-chap-t children (kit CSS styles them).
       * opts.format: (n) => string for the number (default String(n); e.g. (n) => String(n).padStart(2, "0")) */
      function Chapters(el, story, opts = {}) {
        this.el = el;
        this.story = story;
        this.format = opts.format || String;
        el.classList.add("kit-chap");
        el.innerHTML = '<span class="kit-chap-n"></span><span class="kit-chap-t"></span>';
        this.n = el.firstChild;
        this.ti = el.lastChild;
      }
      Chapters.prototype.render = function (t) {
        const c = this.story.chapterAt(t);
        if (!c) { this.el.style.opacity = "0"; return; }
        const num = this.format(c.n);
        if (this.n.textContent !== num) this.n.textContent = num;
        if (this.ti.textContent !== c.title) this.ti.textContent = c.title;
        const o = Math.min(pr(t, c.start + 0.05, 0.35), 1 - pr(t, c.end - 0.25, 0.25));
        this.el.style.opacity = o.toFixed(3);
        this.el.style.setProperty("--in", E.o3(pr(t, c.start + 0.05, 0.45)).toFixed(3));
      };
    
      // put an absolutely positioned overlay at screen point (x, y); (ax, ay) is the element's anchor in 0..1.
      // opts.inherit: show with visibility "inherit" instead of "visible", so a hidden parent still hides the element
      function place(el, x, y, ax = 0.5, ay = 0.5, opacity = 1, scale = 1, opts) {
        if (opacity <= 0) { if (el.style.opacity !== "0") el.style.opacity = "0"; el.style.visibility = "hidden"; return; }
        el.style.visibility = opts && opts.inherit ? "inherit" : "visible";
        el.style.opacity = opacity.toFixed(3);
        el.style.transformOrigin = `${ax * 100}% ${ay * 100}%`;
        el.style.transform = `translate(${x.toFixed(1)}px, ${y.toFixed(1)}px) translate(${(-ax * 100).toFixed(1)}%, ${(-ay * 100).toFixed(1)}%) scale(${scale.toFixed(3)})`;
      }
    
      g.ExplainerCore = { version: 2, clamp01, pr, lerp, env, E, hash, track, Story, Captions, Chapters, place };
    })(window);
    
  • explainer/core/sfxlib.py9.1 KB8467b4af3035upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v1-editorial/fonts.json133 Bf9af6bcc8c90upstream ↗
    {
      "index.html": ["noto-serif-sc-900", "noto-serif-sc-500", "instrument-serif-400", "instrument-serif-400i", "ibm-plex-mono-400"]
    }
    
  • explainer/examples/kv-cache/v1-editorial/hyperframes.json355 B08fb6813f5d1upstream ↗
    {
      "$schema": "https://hyperframes.heygen.com/schema/hyperframes.json",
      "registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
      "paths": {
        "blocks": "compositions",
        "components": "compositions/components",
        "assets": "assets"
      },
      "media": {
        "autoProxy": true
      },
      "authoringSkill": "general-video"
    }
    
  • explainer/examples/kv-cache/v1-editorial/index.html48 KBd6b9d4d70547upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v1-editorial/meta.json114 B75ce9d2c3e1fupstream ↗
    {
      "id": "kv-cache-v1-editorial",
      "name": "kv-cache-v1-editorial",
      "createdAt": "2026-10-05T00:00:00.000Z"
    }
    
  • explainer/examples/kv-cache/v1-editorial/package.json306 B28a51ad8fe56upstream ↗
    {
      "name": "kv-cache-v1-editorial",
      "private": true,
      "type": "module",
      "scripts": {
        "dev": "npx --yes [email protected] preview",
        "check": "npx --yes [email protected] check",
        "render": "npx --yes [email protected] render",
        "publish": "npx --yes [email protected] publish"
      }
    }
    
  • explainer/examples/kv-cache/v1-editorial/tools/sfx.py7.6 KBe6b732490351upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v10-reasoning/beats.js30 KB12b88572ffa2upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v10-reasoning/fonts.json678 B5305c0ba1337upstream ↗
    {
      "extra": {
        "noto-sans-sc-500": {"family": "Noto Sans SC", "css": "Noto+Sans+SC:wght@500", "weight": 500},
        "noto-sans-sc-700": {"family": "Noto Sans SC", "css": "Noto+Sans+SC:wght@700", "weight": 700},
        "stix-two-500i": {"family": "STIX Two Text", "css": "STIX+Two+Text:ital,wght@1,500", "weight": 500, "style": "italic"},
        "stix-two-500": {"family": "STIX Two Text", "css": "STIX+Two+Text:wght@500", "weight": 500},
        "jetbrains-mono-500": {"family": "JetBrains Mono", "css": "JetBrains+Mono:wght@500", "weight": 500}
      },
      "index.html": ["noto-serif-sc-900", "noto-sans-sc-500", "noto-sans-sc-700", "stix-two-500i", "stix-two-500", "jetbrains-mono-500"]
    }
    
  • explainer/examples/kv-cache/v10-reasoning/hyperframes.json355 B08fb6813f5d1upstream ↗
    {
      "$schema": "https://hyperframes.heygen.com/schema/hyperframes.json",
      "registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
      "paths": {
        "blocks": "compositions",
        "components": "compositions/components",
        "assets": "assets"
      },
      "media": {
        "autoProxy": true
      },
      "authoringSkill": "general-video"
    }
    
  • explainer/examples/kv-cache/v10-reasoning/index.html30 KBa280f838d933upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v10-reasoning/meta.json116 B3207c1bb7f5cupstream ↗
    {
      "id": "kv-cache-v10-reasoning",
      "name": "kv-cache-v10-reasoning",
      "createdAt": "2026-10-08T00:00:00.000Z"
    }
    
  • explainer/examples/kv-cache/v10-reasoning/package.json307 Bd4cd38894c60upstream ↗
    {
      "name": "kv-cache-v10-reasoning",
      "private": true,
      "type": "module",
      "scripts": {
        "dev": "npx --yes [email protected] preview",
        "check": "npx --yes [email protected] check",
        "render": "npx --yes [email protected] render",
        "publish": "npx --yes [email protected] publish"
      }
    }
    
  • explainer/examples/kv-cache/v10-reasoning/STYLE.md2.1 KBe4a4a8b42a71upstream ↗
    # V10「推演」· KV cache
    
    同一套推演 kit(`kits/v10-reasoning`),讲 KV cache(`stories/kv-cache-reasoning`)。一张画布、四个推演站:每句话都在画布上
    “加一步几何”——项随话音写进公式、点一行一行长出来、向量转到位、点从三角形飞进缓存;讲完拉远,整个推演就是一张图,
    复习时每一步框住它自己的站。
    
    | 图形(画面) | 真名(配音) |
    | --- | --- |
    | 颜色绑定的式子 out = Σᵢ softmax(q · kᵢ) vᵢ,每一项在被说到时写进去,引线连到大白话标签 | 注意力:新 token 的 q 和前面每个 k 比,按比例取走 v |
    | 玫红 = 新的 / 正在推导的(q、对角线、新的一行);青 = k、缓存;琥珀 = v;朱红 = 浪费 / 代价 | 三种颜色贯穿全片(字幕里的 q、k、v 也同色) |
    | 二维向量盘:q 和每个 k 的夹角,投影 = 点积;越接近取得越多(二维示意) | q·k 打分,softmax 按比例 |
    | 点三角形:第 n 行 n 个点,对角线是新算的,左边带 ↻ 的是又算一遍;列线揭示“同一个 token 被算了一遍又一遍” | 不缓存:第 n 步重算 n 份,1+2+…+8 = 36 = 8 + 28 |
    | 每个对角点分出青 k、琥珀 v,飞进下面的缓存列;重复的点褪成虚线 | k、v 只算一次,存进缓存 |
    | 新 token 只算自己的 q、k、v(×1),k、v 写进最后一行;q 沿 k 列逐行比对,v 按匹配回流到 out | 之后只算新来的一个,再去缓存里查 |
    | 两张图:不缓存的点 (n, n) 落到 y = 1;显存线随长度线性上涨,斜率 0.5 MB/token,4096 处 = 2 GB | 每步从 n 份变 1 份;代价是显存(Llama 2 7B) |
    | 2 × 32 × 4096 × 2 B ≈ 0.5 MB,每一项引线到 k 和 v / 层 / 维 / FP16 | story.json facts:per_token_bytes、context_4k(单条请求) |
    
    示意值:例句「因为空气把蓝光散射得更多」、二维方向和权重(softmax(2·cos))只是示意,界面上都标了「示意」。
    声音:`tools/sfx.py`(起步模板的底 + 本片 beats 的点、飞行、扫描、落点;读 `lib/story.js` 的词时间)。
    
  • explainer/examples/kv-cache/v10-reasoning/tools/sfx.py13 KB838dca5ce90cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v10-reasoning/tools/sfx.sh374 B5ef3bf0819fdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v11-casefile/beats.js29 KBf06f5a496118upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v11-casefile/fonts.json340 B57215800dc27upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v11-casefile/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v11-casefile/index.html37 KB41affb281169upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v11-casefile/meta.json114 B788dabc7ca39upstream ↗
    {
      "id": "kv-cache-v11-casefile",
      "name": "kv-cache-v11-casefile",
      "createdAt": "2026-10-08T10:00:00.000Z"
    }
    
  • explainer/examples/kv-cache/v11-casefile/package.json306 B921b0b852acaupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v11-casefile/STYLE.md3.8 KB252ee27f6959upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v11-casefile/tools/sfx.py3.5 KB1e55d4e72e70upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v11-casefile/tools/sfx.sh991 Bf05129b8ff51upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v12-sitcom/beats.js38 KBe1a98312e3a6upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v12-sitcom/fonts.json327 Be2f90a6d84a2upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v12-sitcom/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v12-sitcom/index.html27 KB57737f77bcc0upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v12-sitcom/meta.json110 B9bcbf473e11eupstream ↗
    {
      "id": "kv-cache-v12-sitcom",
      "name": "kv-cache-v12-sitcom",
      "createdAt": "2026-10-08T12:00:00.000Z"
    }
    
  • explainer/examples/kv-cache/v12-sitcom/package.json304 Ba27cd2d52e65upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v12-sitcom/STYLE.md2.6 KB27639ee9cf20upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v12-sitcom/tools/sfx.py7.3 KBe3a07c551068upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v12-sitcom/tools/sfx.sh579 Bc04b5434999aupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v12-sitcom/tools/sfx_beats.py11 KB8755bf1f4057upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v2-signal/fonts.json203 Bb2dd64ca58d2upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v2-signal/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v2-signal/index.html81 KBf75b057fefabupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v2-signal/meta.json108 B35ed1f3de4a6upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v2-signal/package.json303 B960ae73e78a5upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v2-signal/tools/sfx.py9.5 KB88da217b0e55upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v3-notebook/fonts.json61 Bb81f75043ee9upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v3-notebook/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v3-notebook/index.html43 KBda30ab7b8f58upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v3-notebook/meta.json112 B546766a0d9ceupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v3-notebook/package.json305 B4c751ad74c7cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v3-notebook/tools/sfx.py1.0 KBbbc85e75a035upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v4-paper/fonts.json50 Bee5e3c86db73upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v4-paper/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v4-paper/index.html60 KBb1d952d02b44upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v4-paper/meta.json106 Be019671e02b1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v4-paper/package.json302 B29fcf6056c3eupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v4-paper/tools/sfx.py9.3 KB1663e35eeba5upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v5-comic/fonts.json287 Be19b25ebfdbaupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v5-comic/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v5-comic/index.html73 KBd3d549dce122upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v5-comic/meta.json106 B253d9f9839c0upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v5-comic/package.json302 Ba1b192f37202upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v5-comic/tools/sfx.py11 KBb7ac02ecedffupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v6-cinematic/fonts.json569 Beb19931b801fupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v6-cinematic/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v6-cinematic/index.html54 KBab9cd29337b0upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v6-cinematic/meta.json114 B3eb26ce16954upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v6-cinematic/package.json306 B8ce1d664c17bupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v6-cinematic/tools/sfx.py7.1 KB8a6a0019425aupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v7-drafting/fonts.json558 Bc9ac3b88c547upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v7-drafting/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v7-drafting/index.html62 KB40f4b16a94ccupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v7-drafting/meta.json111 B07f9fac13577upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v7-drafting/package.json304 B4b9ef83c56deupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v7-drafting/tools/sfx.py8.7 KBdfb5f60b1e8bupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v8-chalkboard/fonts.json169 Bd69eb7e3bdf8upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v8-chalkboard/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v8-chalkboard/index.html33 KB94b4924bddceupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v8-chalkboard/meta.json115 B73f50defa6f6upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v8-chalkboard/package.json306 B21d991c2e1d3upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v8-chalkboard/tools/sfx.py3.7 KB8b97c58a7bd0upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v9-clay/fonts.json418 B9c3fc83d05d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v9-clay/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v9-clay/index.html71 KB0d9427de1222upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v9-clay/meta.json104 B981037477ca8upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v9-clay/package.json301 Bd19f52cbd7ddupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v9-clay/STYLE.md1.6 KBd5b396ad365fupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/examples/kv-cache/v9-clay/tools/sfx.py8.2 KB1bbdd930953dupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/gallery/nine-styles-kv-cache.jpg240 KB4a8618e53c8dupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/gallery/three-narrative-styles-kv-cache.jpg148 KBcea17c118239upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/GOTCHAS.md4.8 KB361036ecb354upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/KITS.md18 KBc4d10e1d4472upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v1-editorial/kit.css14 KB6ccfb2ee34a1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v1-editorial/kit.js24 KBde1881557998upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v1-editorial/KIT.md11 KBd9dca00cc13eupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v1-editorial/paper-grain.svg437 B3fd7ac528894upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v1-editorial/starter/AGENTS.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v1-editorial/starter/beats.js1.7 KBc2bf30fcc902upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v1-editorial/starter/CLAUDE.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v1-editorial/starter/fonts.json133 Bf9af6bcc8c90upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v1-editorial/starter/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v1-editorial/starter/index.html32 KBeb22252d9664upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v1-editorial/starter/meta.json112 Bee7f666a6767upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v1-editorial/starter/package.json305 B2767699cc3f3upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v1-editorial/starter/STARTER.md6.9 KB571c8cce403bupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v1-editorial/starter/tools/sfx.py7.8 KB11f06f6869f2upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v1-editorial/starter/tools/sfx.sh456 B8e04e9797cf5upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v10-reasoning/kit.css15 KBf6b3544e742cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v10-reasoning/kit.js44 KB01200b98dcd6upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v10-reasoning/KIT.md11 KBa952cb27cc68upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v10-reasoning/starter/AGENTS.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v10-reasoning/starter/beats.js1.4 KBa898c34f741fupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v10-reasoning/starter/CLAUDE.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v10-reasoning/starter/fonts.json678 B5305c0ba1337upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v10-reasoning/starter/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v10-reasoning/starter/index.html30 KBcb51000cedbeupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v10-reasoning/starter/meta.json114 B8a95d2e58b54upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v10-reasoning/starter/package.json306 Bfa480a1a562eupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v10-reasoning/starter/STARTER.md8.5 KBae2f92af231cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v10-reasoning/starter/tools/sfx.py8.9 KB29cf873fb45bupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v10-reasoning/starter/tools/sfx.sh374 B5ef3bf0819fdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v11-casefile/casefile_sfx.py8.5 KB7fdad6a4993aupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v11-casefile/cork.svg1.2 KBf809626d11bbupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v11-casefile/events.mjs2.8 KB5ec92a2c1309upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v11-casefile/kit.css18 KBc9e8ff908e7dupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v11-casefile/kit.js58 KB464136291997upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v11-casefile/KIT.md11 KB4eb0ab452947upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v11-casefile/stamp-ink.svg539 B929db42e51c0upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v11-casefile/starter/AGENTS.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v11-casefile/starter/beats.js1.6 KBdf6166035229upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v11-casefile/starter/CLAUDE.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v11-casefile/starter/fonts.json340 B57215800dc27upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v11-casefile/starter/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v11-casefile/starter/index.html37 KBb044d130db21upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v11-casefile/starter/meta.json112 B835d251dc921upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v11-casefile/starter/package.json305 B58287d4e5423upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v11-casefile/starter/STARTER.md8.5 KBf6feab69f0d2upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v11-casefile/starter/tools/sfx.py3.5 KB1e55d4e72e70upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v11-casefile/starter/tools/sfx.sh991 Bf05129b8ff51upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v12-sitcom/kit.css27 KB0dda75e45a9aupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v12-sitcom/kit.js84 KB40db54f0e508upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v12-sitcom/KIT.md12 KB325c4a47a60eupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v12-sitcom/sitcom_sfx.py6.2 KBb9f2acc46852upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v12-sitcom/starter/AGENTS.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v12-sitcom/starter/beats.js1.8 KB8e2223796abdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v12-sitcom/starter/CLAUDE.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v12-sitcom/starter/fonts.json327 Be2f90a6d84a2upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v12-sitcom/starter/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v12-sitcom/starter/index.html26 KB667c92c37c6bupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v12-sitcom/starter/meta.json110 B9bcbf473e11eupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v12-sitcom/starter/package.json304 Ba27cd2d52e65upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v12-sitcom/starter/STARTER.md8.2 KB706b4bc5fe65upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v12-sitcom/starter/tools/sfx.py7.3 KBe3a07c551068upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v12-sitcom/starter/tools/sfx.sh579 Bc04b5434999aupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v12-sitcom/starter/tools/sfx_beats.py1.1 KB9c656e8559abupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v2-signal/kit.css14 KB3a6bca295e4cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v2-signal/kit.js28 KBd99e81fd95d0upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v2-signal/KIT.md11 KB4a56326b5a99upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v2-signal/sfx_signal.py3.6 KB1958c95b7431upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v2-signal/starter/AGENTS.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v2-signal/starter/beats.js1.3 KBfd8b5a6349e3upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v2-signal/starter/CLAUDE.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v2-signal/starter/fonts.json203 Bb2dd64ca58d2upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v2-signal/starter/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v2-signal/starter/index.html41 KBd1463f5eb4f9upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v2-signal/starter/meta.json106 B1755a3dfe7ccupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v2-signal/starter/package.json302 B43b1158c8f9eupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v2-signal/starter/STARTER.md7.5 KBaab45de1812dupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v2-signal/starter/tools/sfx.py7.6 KB9303a26b7b74upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v2-signal/starter/tools/sfx.sh445 B8370aaaca0a8upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v3-notebook/events.mjs3.1 KBed9a4656f0ffupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v3-notebook/fix-56de.woff2940 Bbad0a7973b6bupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v3-notebook/kit.css13 KB7360040cd11aupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v3-notebook/kit.js44 KBf347a1810454upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v3-notebook/KIT.md9.2 KB22b1c407aa09upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v3-notebook/notebook_sfx.py6.2 KB82b8dddf1949upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v3-notebook/paper-grain.svg437 B3fd7ac528894upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v3-notebook/starter/AGENTS.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v3-notebook/starter/beats.js1.5 KBa54a17db78d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v3-notebook/starter/CLAUDE.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v3-notebook/starter/fonts.json61 Bb81f75043ee9upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v3-notebook/starter/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v3-notebook/starter/index.html34 KB36a6d77db9e3upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v3-notebook/starter/meta.json110 Ba66749f6ab7dupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v3-notebook/starter/package.json304 Bdc1361806af1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v3-notebook/starter/STARTER.md7.0 KB882283a50786upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v3-notebook/starter/tools/sfx.py3.4 KB9c2fc909844dupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v3-notebook/starter/tools/sfx.sh882 B24227e1c0a17upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v4-paper/kit.css17 KB8c971b269623upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v4-paper/kit.js34 KBd53b6f9fc6caupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v4-paper/KIT.md11 KB346eb9a3ab20upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v4-paper/paper-grain.svg437 B3fd7ac528894upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v4-paper/paper_sfx.py5.0 KB9b0129406bd2upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v4-paper/starter/AGENTS.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v4-paper/starter/beats.js1.6 KBab34d4a01ce0upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v4-paper/starter/CLAUDE.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v4-paper/starter/fonts.json50 Bee5e3c86db73upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v4-paper/starter/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v4-paper/starter/index.html35 KBbbbb89fa6733upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v4-paper/starter/meta.json106 Be019671e02b1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v4-paper/starter/package.json302 B29fcf6056c3eupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v4-paper/starter/STARTER.md7.4 KB55dee1e0dd29upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v4-paper/starter/tools/sfx.py6.7 KB4e6f58510b9dupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v4-paper/starter/tools/sfx.sh555 B7efa0e43c7a5upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v4-paper/starter/tools/sfx_beats.py917 B87bac718d910upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v5-comic/kit.css17 KBde91a38c8c8cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v5-comic/kit.js31 KB26f5542a2f00upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v5-comic/KIT.md11 KBd5e38102c738upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v5-comic/starter/AGENTS.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v5-comic/starter/beats.js1.1 KB18f8ada321d3upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v5-comic/starter/CLAUDE.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v5-comic/starter/fonts.json287 Be19b25ebfdbaupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v5-comic/starter/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v5-comic/starter/index.html34 KBa04a1113b008upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v5-comic/starter/meta.json104 B6c5f6783a169upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v5-comic/starter/package.json301 Befd5f9ca63a1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v5-comic/starter/STARTER.md7.5 KBa8422ebb699bupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v5-comic/starter/tools/sfx.py11 KB21024495654cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v5-comic/starter/tools/sfx.sh383 B3cf4ea6eabbaupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v6-cinematic/grain.svg437 B3fd7ac528894upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v6-cinematic/kit.css13 KBf8cb2bbfeb18upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v6-cinematic/kit.js30 KB7a6ad13c4bacupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v6-cinematic/KIT.md8.1 KBcc8b7d48e269upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v6-cinematic/starter/AGENTS.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v6-cinematic/starter/beats.js1.1 KBcd1cc0d9131dupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v6-cinematic/starter/CLAUDE.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v6-cinematic/starter/fonts.json569 Beb19931b801fupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v6-cinematic/starter/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v6-cinematic/starter/index.html33 KBad3c3e361dc7upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v6-cinematic/starter/meta.json112 B27c6dc666101upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v6-cinematic/starter/package.json305 Bc671f9778ebbupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v6-cinematic/starter/STARTER.md6.9 KB9887ac35e849upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v6-cinematic/starter/tools/sfx.py4.5 KBdeac66d77a0fupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v6-cinematic/starter/tools/sfx.sh405 Bc0a49e036bc9upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v7-drafting/grain.svg437 B3fd7ac528894upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v7-drafting/kit.css17 KBd38e3e7bd9b6upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v7-drafting/kit.js32 KBce911c202b1eupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v7-drafting/KIT.md8.9 KB7b6de78cec72upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v7-drafting/starter/AGENTS.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v7-drafting/starter/beats.js1.2 KBf67b2a8de8a6upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v7-drafting/starter/CLAUDE.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v7-drafting/starter/fonts.json558 Bc9ac3b88c547upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v7-drafting/starter/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v7-drafting/starter/index.html43 KB58ed67e4bbd2upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v7-drafting/starter/meta.json110 B3fc65e2e363dupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v7-drafting/starter/package.json303 B771e643055a9upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v7-drafting/starter/STARTER.md7.6 KBe2ce5b702a19upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v7-drafting/starter/tools/sfx.py7.8 KB0a758f12439cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v7-drafting/starter/tools/sfx.sh382 B291b7588b9a0upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v8-chalkboard/chalk-mask.png310 KB76de27525b61upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v8-chalkboard/chalklog.mjs3.9 KB63b6d11bb5baupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v8-chalkboard/grain.svg437 B3fd7ac528894upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v8-chalkboard/kit.css6.3 KB6c70f8827e78upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v8-chalkboard/kit.js61 KB3dab607a83aeupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v8-chalkboard/KIT.md9.5 KB8aea1ca90b96upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v8-chalkboard/starter/AGENTS.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v8-chalkboard/starter/beats.js1.1 KBd8e7b91fd6c2upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v8-chalkboard/starter/CLAUDE.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v8-chalkboard/starter/fonts.json169 Bd69eb7e3bdf8upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v8-chalkboard/starter/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v8-chalkboard/starter/index.html34 KBee46af7ff387upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v8-chalkboard/starter/meta.json114 Be6aeae608f5eupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v8-chalkboard/starter/package.json305 B72585f05d801upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v8-chalkboard/starter/STARTER.md8.0 KB2cd44eabeba6upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v8-chalkboard/starter/tools/sfx.py4.4 KBd9cc7d4541c4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v8-chalkboard/starter/tools/sfx.sh799 B045d51754719upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v9-clay/kit.css15 KBff569ccb724bupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v9-clay/kit.js35 KB5b9dee728ad3upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v9-clay/KIT.md9.8 KB1a8fe10cccc1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v9-clay/starter/AGENTS.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v9-clay/starter/beats.js1.3 KBe6c09cfb4653upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v9-clay/starter/CLAUDE.md1.5 KB6e97b78072d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v9-clay/starter/fonts.json418 B9c3fc83d05d4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v9-clay/starter/hyperframes.json355 B08fb6813f5d1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v9-clay/starter/index.html38 KB930eb43e7129upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v9-clay/starter/meta.json102 B67990789916eupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v9-clay/starter/package.json300 B04ed92bebd92upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v9-clay/starter/STARTER.md7.9 KB222a850569a1upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v9-clay/starter/tools/plan.mjs1.7 KB6b8149e3b193upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v9-clay/starter/tools/sfx.py4.1 KBa50752bbe949upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/kits/v9-clay/starter/tools/sfx.sh385 B7c52ea5919efupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/STARTER-BRIEF.md5.7 KB54a2b57dfc86upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/stories/_test-dry/script.md972 B2c6ee1de8320upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/stories/_test-dry/story.json6.5 KB4842d37f8951upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/stories/kv-cache-casefile/script.md2.5 KBf9b4b6ba6d9eupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/stories/kv-cache-casefile/story.json13 KB9bafed469625upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/stories/kv-cache-reasoning/script.md2.3 KBf1df33cb431bupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/stories/kv-cache-reasoning/story.json12 KBe773ce47bcbaupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/stories/kv-cache-sitcom/script.md2.3 KBd0daf4471736upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/stories/kv-cache-sitcom/story.json12 KBe153d46d8550upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/stories/kv-cache/script.md2.4 KBf0adce0d6dc6upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/stories/kv-cache/story.json11 KBdcdcfc955ae7upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/stories/kv-cache/STORYBOARD.md6.3 KB342acb75085aupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/STYLES.md14 KB31f8ed8e5ed0upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/THIRD_PARTY.md1.4 KB9d06cc8201bcupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/tools/docs.py4.6 KBc0de91b5c9e2upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/tools/fonts.py7.0 KB8b790c7064c0upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/tools/grid.py3.3 KBd7c769d86db5upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/tools/new_film.sh3.0 KBad6b24ff8c4bupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/tools/new_topic.sh1.7 KBa1b1dc17cd2dupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/tools/qa.py5.7 KBff5d02ffa936upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/tools/render.sh2.4 KB99cb9133f61cupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/tools/srt.py3.4 KB147da7e91980upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/tools/stamp.py1.7 KBbcf827d34854upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/tools/still_grid.py3.5 KB06e1c35b38f0upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/tools/story.py24 KBc381a817cb6bupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • explainer/tools/sync.sh2.1 KB569a649fbabeupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • LICENSE1.0 KBf5be3d70a127upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • README.zh-CN.md20 KB5a8898be5698upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • tests/explainer_smoke.sh6.9 KB9077595c13f4upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • tests/smoke.sh7.8 KB22d58ae32f60upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • tests/story_timing.py3.5 KBedf60dedf116upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • VERSION6 B3eefcb9dd5b3upstream ↗
    1.0.0
    

Plain-text copy, no login: /skill-bundles/cclank-lanshu-create-ai-presenter-video.md

// REPO STATS

3.0k stars
2 open issues
Last commit: 1mo ago