@oh-story/dsh 0.1.10 → 0.1.11

package/lib/video-recap/README.en.md

@@ -1,142 +1,312 @@
-# video-recap-skills
+<!-- Last synced with README.md: 2026-09-20 -->
+
+<p align="center">
+  <img src="https://zenstory.ai/brand/zenstory-ai-mark.svg" alt="" width="76" height="76">
+</p>
+
+<h1 align="center">Video Recap Skills</h1>
+
+<p align="center">
+  <b>Turn one or several videos into a Chinese-narration recap: six skills inside the coding agent you already use, ffmpeg locally, one Xiaomi MiMo key remotely, and an optional JianYing/CapCut draft to keep editing by hand.</b>
+</p>
+
+<p align="center">
+  <a href="https://zenstory.ai/video-recap"><b>Project page</b></a>
+  &nbsp;·&nbsp;
+  <a href="#install"><b>Install</b></a>
+  &nbsp;·&nbsp;
+  <a href="#see-what-it-produces"><b>See what it produces</b></a>
+  &nbsp;·&nbsp;
+  <a href="README.md"><b>中文</b></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/zenstory-ai/video-recap-skills/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/zenstory-ai/video-recap-skills?style=flat-square&color=22D3EE&logo=github&logoColor=white&label=Stars"></a>
+  <a href="https://github.com/zenstory-ai/video-recap-skills/releases/latest"><img alt="Release" src="https://img.shields.io/github/v/release/zenstory-ai/video-recap-skills?style=flat-square&color=081431&label=Release"></a>
+  <img alt="Skills 6" src="https://img.shields.io/badge/Skills-6-081431?style=flat-square">
+  <a href="https://www.python.org/"><img alt="Python 3.10%2B" src="https://img.shields.io/badge/Python-3.10%2B-3776AB?style=flat-square&logo=python&logoColor=white"></a>
+  <a href="https://github.com/zenstory-ai/video-recap-skills/actions/workflows/skill-validate.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/zenstory-ai/video-recap-skills/skill-validate.yml?style=flat-square&label=CI"></a>
+  <a href="https://platform.xiaomimimo.com"><img alt="AI Xiaomi%20MiMo" src="https://img.shields.io/badge/AI-Xiaomi%20MiMo-34A853?style=flat-square"></a>
+  <a href="./LICENSE"><img alt="License MIT" src="https://img.shields.io/badge/License-MIT-1F6FEB?style=flat-square"></a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/zenstory-ai/video-recap-skills/issues"><img alt="GitHub Issues" src="https://img.shields.io/badge/GitHub%20Issues-181717?style=for-the-badge&logo=github&logoColor=white"></a>
+</p>
+
+<video src="https://github.com/user-attachments/assets/f3c2df0c-6869-4f5b-8f4c-cce70b58b667" controls muted playsinline width="100%"></video>
+
+The 59-second landscape recap above, *Guohuo (这一秒过火)*, is the final delivery after selecting from four episodes of a short drama, cutting, scripting, voicing, mixing, packaging, and several rounds of viewing feedback. Every creative artifact behind it (story plan, sound ownership, narration, timeline, QC reports, revision log, Remotion overlay source) lives in [examples/guohuo-60s/](examples/guohuo-60s/), and every excerpt below is copied from those files.
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-Plugin-purple)
-![Powered by Xiaomi MiMo](https://img.shields.io/badge/AI-Xiaomi%20MiMo-green)
-![Fish Audio TTS](https://img.shields.io/badge/TTS-Fish%20Audio-blue)
+## What it is
 
-[中文](README.md) · English
+Six skills install into Claude Code, Codex CLI, OpenCode, or OpenClaw. You give the video paths and the recap you want in plain language; the agent understands picture and dialogue, decides the story and audiovisual plan, cuts, writes, voices, mixes, and subtitles. Supported inputs: `.mp4 / .mov / .mkv / .webm`.
 
-**In Claude Code, Codex CLI, OpenCode, or OpenClaw, one natural-language request turns a video into a Chinese-narration recap.** It needs only Python, `ffmpeg`, and one Xiaomi MiMo API key locally; TTS can optionally use Fish Audio. No GPU or model downloads are required, and it runs on macOS / Linux / Windows.
+- **One key, ffmpeg locally.** ASR, VLM, and TTS all go through [Xiaomi MiMo](https://platform.xiaomimimo.com); the local runtime is Python's standard library plus `ffmpeg`, with no GPU, no `pip install`, and no model downloads. Voiceover can switch to Fish Audio, which replaces only that stage.
+- **The editorial decision comes before the sound allocation.** The agent compares edit hypotheses first, writes the viewer promise, POV, dramatic question, and change-based beats into `recap_story_plan.json`, then assigns each beat a picture job and an audio owner: narration is voiced as a block only when it has a defined job, and strong dialogue, action sound, or silence may own an entire beat.
+- **Cut first, narrate second, so the timeline is aligned by construction.** Cut mode renders the shortened video first and writes narration against that output timeline; feed several videos at once and pick ranges by `source_id` to cut one story spine; each video's analysis is saved to a filesystem material library for reuse.
+- **Keep editing after the render.** The multi-track `timeline.json` exports to a JianYing draft with editable source clips, narration, BGM, subtitles, and image overlays; drop in an accurate subtitle file and it becomes the preferred source for original-dialogue captions.
+- **Every step leaves a record you can check.** Narration lint, assembly QC, delivery QC, and the revision log are machine-readable files; the optional MiMo adviser only suggests, and a missing key, rate limit, or timeout never blocks the render.
 
-## Demo
+## Install
 
-<video src="https://github.com/user-attachments/assets/f3c2df0c-6869-4f5b-8f4c-cce70b58b667" width="640" controls></video>
+Prerequisites: Python 3.10 or newer, `ffmpeg` with libass on `PATH` (subtitles are burned in by default), and one [Xiaomi MiMo](https://platform.xiaomimimo.com) API key.
 
-[Explore the complete 60-second *Guohuo (这一秒过火)* Skill project, Remotion overlay source, and content audit](examples/guohuo-60s/)
+```bash
+brew install ffmpeg                        # macOS; apt on Debian/Ubuntu, choco / scoop / winget on Windows
+export MIMO_API_KEY=your-mimo-key          # Windows PowerShell: $env:MIMO_API_KEY="your-mimo-key"
+export MIMO_TOKEN_PLAN_CLUSTER=cn          # tp-* Token Plan keys only: cn | sgp | ams
+```
 
-The case study covers the core cut, picture/audio lock, packaging exploration, viewing feedback, scoped conform/re-cut, and frozen-set verification. It also demonstrates multi-episode selects, source-audio/narration ownership, Fish Audio voiceover with TTS-aligned captions, and repairing distracting joins by restoring continuous source motion. No copyrighted episode footage, audio, or rendered video is stored in the repository.
+MiMo needs no subscription; `sk-*` keys bill pay-as-you-go. One complete video measured for this project cost about CNY 1.3, varying with length and request volume.
 
-Beyond the rendered MP4, you can export a **剪映/JianYing draft** to keep editing by hand, with original clips, narration, BGM, and subtitles:
+Inside Claude Code:
 
-<img alt="Exported 剪映 draft: original clips, narration, BGM, and subtitles" src="docs/jianying-export.png" width="100%">
+```text
+/plugin marketplace add zenstory-ai/video-recap-skills
+/plugin install video-recap-skills@video-recap
+```
 
-## What it is
+Or just ask (any agent that can import a GitHub repository):
 
-```mermaid
-flowchart LR
-    video(["Video"]) --> understand["① Understand<br/>scenes · ASR · VLM"]
-    research["Story research · optional"] -.-> understand
-    understand --> script["② Direct · Edit · Script<br/>agent"] --> voiceover["③ Voiceover<br/>MiMo / Fish Audio"] --> assemble["④ Assemble<br/>mux · subtitles"] --> output(["Recap"])
-    understand -. cut mode · cut first .-> cut["Cut<br/>render first"] -.-> script
-    classDef io fill:#4f86c6,stroke:#3a6298,color:#fff;
-    classDef stage fill:#eef6ff,stroke:#4f86c6,color:#1f2937;
-    classDef opt fill:#f3f4f6,stroke:#9ca3af,color:#475569;
-    class video,output io;
-    class understand,script,voiceover,assemble stage;
-    class research,cut opt;
+```text
+Install this plugin: https://github.com/zenstory-ai/video-recap-skills
 ```
 
-## Why use it
-
-- **One key, runs anywhere.** ASR, VLM, and TTS all go through [Xiaomi MiMo](https://platform.xiaomimimo.com); the local runtime uses only Python's standard library and `ffmpeg`, with no `pip install`.
-- **Optional Fish Audio TTS.** Select `--tts-provider fish-audio` to use Fish Audio. Its current `s2.1-pro-free` model is useful for development, evaluation, and non-SLA workloads while the existing MiMo path remains the default.
-- **Research when it matters.** When the title/story context is known or the brief notes the material is thin, put character relationships and plot background in `background_research.json` so the VLM knows who's who.
-- **Make the editorial decision before allocating sound.** The agent first compares edit hypotheses and locks the POV, story spine, exact picture moments, and original-audio anchors. Narration is voiced as a block only when it has a defined job; strong dialogue, action sound, or silence may own an entire beat. A 7:3 split is only a rough fallback, never a quota.
-- **Cut first, frames aligned.** Cut mode renders the shortened video first, then writes narration against that output timeline, so picture and voice stay in sync.
-- **Multi-video cut, reusable analysis.** Feed several videos at once, pick ranges by `source_id`, and render one recap; each video's analysis is saved to a filesystem material library you can `grep` and reuse next time.
-- **Keep editing in 剪映.** Optionally export a schema-driven draft with editable original clips, narration, BGM, subtitles, and local image overlays. Video/audio/images are bundled under `Resources/local` with a material index, so a clone or moved draft stays usable. ffmpeg remains the canonical render.
-- **Optional MiMo adviser, never a gatekeeper.** On request, MiMo can review the project before assembly or after rendering. Missing keys, rate limits, timeouts, and malformed model output are warnings only, never blockers or automatic edits.
+<details>
+<summary><strong>Codex CLI, OpenCode, OpenClaw</strong></summary>
 
-## Installation
+**Codex CLI**
 
-### 1. Shared prerequisites
+```bash
+codex plugin marketplace add zenstory-ai/video-recap-skills
+codex plugin add video-recap-skills@video-recap
+```
 
-- Python 3.10+
-- `ffmpeg` on `PATH`; subtitle burn-in is enabled by default and requires libass / the `subtitles` filter
-- One [Xiaomi MiMo](https://platform.xiaomimimo.com) API key for ASR, VLM, and the default TTS path
+**OpenCode**: the [official Agent Skills documentation](https://opencode.ai/docs/skills/) puts project skills under `.opencode/skills/<name>/SKILL.md`. Clone the repository and start OpenCode from that directory:
 
 ```bash
-brew install ffmpeg                         # macOS
-sudo apt install ffmpeg                    # Debian / Ubuntu
-choco install ffmpeg                       # Windows; scoop or winget also work
+git clone https://github.com/zenstory-ai/video-recap-skills.git
+cd video-recap-skills
+mkdir -p .opencode
+ln -s ../skills .opencode/skills             # on Windows, copy skills\* into .opencode\skills\
+opencode debug skill                         # should list all 6 skills
+```
+
+**OpenClaw**: after cloning, import the Claude plugin bundle:
 
-export MIMO_API_KEY=your-mimo-key          # macOS / Linux
-export MIMO_TOKEN_PLAN_CLUSTER=cn          # optional for tp-* keys: cn | sgp | ams
+```bash
+openclaw plugins install ./video-recap-skills
+openclaw skills list
 ```
 
-In Windows PowerShell, use `$env:MIMO_API_KEY="your-mimo-key"`. MiMo does not require a subscription: `sk-*` keys can use pay-as-you-go billing. In one complete-video run measured for this project, usage cost about CNY 1.3; actual cost varies with video length and request volume. Pay-as-you-go keys default to `https://api.xiaomimimo.com/v1`.
+Register the checkout through one discovery path only; duplicates cause name collisions or repeated triggers.
 
-To use the currently free Fish Audio TTS path:
+</details>
+
+<details>
+<summary><strong>Optional: voice with Fish Audio</strong></summary>
 
 ```bash
 export TTS_PROVIDER=fish-audio
 export FISH_API_KEY=your-fish-key
-export FISH_TTS_REFERENCE_ID=your-voice-model-id  # optional; overrides the built-in “娱乐扒妹” voice
+export FISH_TTS_REFERENCE_ID=your-voice-model-id  # optional; the built-in "娱乐扒妹" narration voice is the default
 ```
 
-The default Fish model is `s2.1-pro-free`, with the built-in “娱乐扒妹” narration voice (reference ID `5653cea4ac83480aaf2bf45406556185`). Set `FISH_TTS_REFERENCE_ID` to override it. [Fish Audio currently states](https://fish.audio/blog/s2-1-pro-free-api/?articleLocale=en) that free access runs through **2026-08-31**, subject to its Fair Use Policy and without an SLA; check its current policy after that date. See the [config playbook](skills/video-recap/references/config-playbook.md) for model, voice, loudness, subtitle, and per-capability settings.
-
-### 2. Choose an agent host
+The default model is `s2.1-pro-free` with the built-in "娱乐扒妹" voice (reference ID `5653cea4ac83480aaf2bf45406556185`); billing follows Fish Audio's own terms. ASR and VLM still use MiMo, and local reference-voice cloning (`--voice-ref`) is available on the MiMo path only.
 
-#### Claude Code
+</details>
 
-Run inside Claude Code:
+Once installed, ask the agent to check the environment:
 
 ```text
-/plugin marketplace add zenstory-ai/video-recap-skills
-/plugin install video-recap-skills@video-recap
+Check the video-recap environment and tell me whether Python, ffmpeg/libass, and MiMo are ready.
 ```
 
-Or simply ask:
+> Changes are in [CHANGELOG.md](CHANGELOG.md) and [Releases](https://github.com/zenstory-ai/video-recap-skills/releases). The repository moved from `worldwonderer/video-recap-skills` to `zenstory-ai/video-recap-skills`; if you installed from the old address, point at the new one.
 
-```text
-Install this plugin: https://github.com/zenstory-ai/video-recap-skills
+## See what it produces
+
+Every excerpt below is copied from a file in [examples/guohuo-60s/](examples/guohuo-60s/); cuts are marked with "…". The inputs were episodes 2, 3, 6, and 21 of *Guohuo*; the repository holds the structured artifacts only, never the episode audio or video. The files are in Chinese and are quoted as-is, with a translation after each.
+
+### The story plan states the viewer promise first, then what changes in each beat
+
+Before a single cut, the agent writes [`recap_story_plan.json`](examples/guohuo-60s/recap_story_plan.json). The director's intent answers four questions: what is promised, whose point of view, what question the audience watches with, and what is withheld until the end:
+
+```json
+"director_intent": {
+  "viewer_promise": "60秒看懂死而复生的白月光为什么让男主一秒破防，并用三个名场面把关系推到婚服送嫁。",
+  "pov": "跟随慕容清峄的认知与反应，让观众和他一起从震惊、发疯走到确认她仍会护他。",
+  "dramatic_question": "她既然装作陌生人，为什么眼神、亲吻和保护都在暴露旧情？",
+  "emotional_start": "荒诞吃瓜式震惊",
+  "emotional_end": "抓马又上头的未完待续",
+  "ending_aftertaste": "明明相爱却要嫁给哥哥的强悬念",
+  "withhold_reveal": "前8秒先揭示准大嫂身份；中段以洗手台和护夫逐步证明旧情；最后才亮婚服。"
+},
 ```
 
-#### Codex CLI
+Translated: the promise is "in 60 seconds, understand why the lover who came back from the dead breaks the hero in one second, and push the relationship to the wedding-dress send-off through three iconic scenes"; the POV follows Murong Qingyi's realisation; the dramatic question is "if she is pretending to be a stranger, why do her eyes, the kiss, and her protecting him all betray the old love?"; the reveal order is "the sister-in-law identity in the first 8 seconds, the washstand and the shielding in the middle, the wedding dress last".
+
+Each beat records not a scene summary but what changes, which question the audience carries in and out, the exact moment that must be kept, and where the evidence comes from (1 of 10 beats):
+
+```json
+{
+  "beat_id": "b03",
+  "source_id": "episode-03",
+  "source_start": 1292.0,
+  "source_end": 1305.5,
+  "function": "escalation",
+  "event": "男主堵住女主说出日日夜夜想她与挫骨扬灰",
+  "change": "power: 女主回避→男主逼问",
+  "audience_question_in": "男主会忍吗",
+  "audience_question_out": "狠话里全是想念",
+  "character_focus": "慕容清峄",
+  "must_keep_moment": "完整原声“我日日夜夜地想你…挫骨扬灰”",
+  "evidence": ["asr", "vlm", "hard_subtitle"]
+},
+```
 
-```bash
-codex plugin marketplace add zenstory-ai/video-recap-skills
-codex plugin add video-recap-skills@video-recap
+Translated: the event is "he corners her and says he thinks of her day and night and wants to grind her bones to dust"; the change is "power: she evades → he interrogates"; the audience goes in asking "will he hold back?" and comes out with "every harsh word is longing"; the moment that must be kept is the complete original line, evidenced by ASR, VLM, and the burned-in subtitle.
+
+In [`clip_plan.json`](examples/guohuo-60s/clip_plan.json) this beat becomes one range with a reason; cut mode renders the cut from it first and writes narration afterwards.
+
+### Narration yields to original dialogue, and the owner of each beat is written down
+
+[`visual_audio_board.json`](examples/guohuo-60s/visual_audio_board.json) assigns an `audio_owner` to every beat. The beat above is owned by the original dialogue, its narration job is `none`, and its playback speed is locked at 1.0 (1 of 10 beats):
+
+```json
+{
+  "beat_id": "b03",
+  "source_id": "episode-03",
+  "source_start": 1292.0,
+  "source_end": 1305.24,
+  "output_start": 9.206666,
+  "output_end": 22.446666,
+  "picture_job": "performance",
+  "preferred_moment": "完整原声“我日日夜夜地想你…挫骨扬灰”",
+  "entry_reason": "尽量晚进到信息/动作将发生前",
+  "exit_reason": "台词、动作或反应完整落地后立即离开",
+  "audio_owner": "original_dialogue",
+  "original_audio_anchor": "完整原声“我日日夜夜地想你…挫骨扬灰”",
+  "narration_job": "none",
+  "handoff": "旁白先补关系，原声/动作发生时完全让位；下一拍承接人物反应。",
+  "playback_speed": 1.0
+},
 ```
 
-For a local checkout, replace the marketplace source in the first command with its directory. This flow was smoke-tested with an isolated `CODEX_HOME` on Codex CLI `0.144.1`.
+Translated: enter "as late as possible, just before the information or action lands"; exit "as soon as the line, action, or reaction has fully landed"; handoff "narration fills in the relationship first, then yields completely while the original sound or action plays; the next beat picks up the character's reaction".
+
+So [`narration.json`](examples/guohuo-60s/narration.json) has only 7 narration blocks in the whole piece. The second stops at 10.2 s and the third does not enter until 23.047 s; the 13 seconds between belong entirely to that line:
+
+```json
+{
+  "start": 5.773,
+  "end": 10.2,
+  "narration": "她改名方牧兰，嘴上装作不认识，一个眼神就把三年前的旧情全招了。",
+  "pause_after_ms": 80,
+  "overlaps_speech": true,
+  "emotion": "调侃"
+},
+{
+  "start": 23.047,
+  "end": 26.5,
+  "narration": "天呐，狠话还没落地，下一秒两个人直接亲上了。",
+  "pause_after_ms": 50,
+  "overlaps_speech": true,
+  "emotion": "吃瓜、上头"
+},
+```
 
-#### OpenCode
+Translated: "She renamed herself Fang Mulan and pretends not to know him, but one look confesses the whole affair from three years ago." / "Oh no, the threat hasn't even landed and the next second they're kissing."
 
-The official [OpenCode Agent Skills documentation](https://opencode.ai/docs/skills/) defines project skills under `.opencode/skills/<name>/SKILL.md`. Clone the repository and start OpenCode from that directory:
+The three protected lines, proofread by the agent, go into [`original_subtitles.json`](examples/guohuo-60s/original_subtitles.json) and are burned as 「」 captions in the gaps:
 
-```bash
-git clone https://github.com/zenstory-ai/video-recap-skills.git
-cd video-recap-skills
-mkdir -p .opencode
-ln -s ../skills .opencode/skills             # macOS / Linux
-opencode debug skill
+```json
+[
+  { "start": 4.133, "end": 5.053, "text": "大嫂。" },
+  { "start": 11.127, "end": 21.027, "text": "我好想你，日日夜夜地想你，想把你抽筋扒皮，挫骨扬灰。" },
+  { "start": 35.673, "end": 37.473, "text": "有我在，你别怕。" }
+]
 ```
 
-On Windows, copy `skills\*` into `.opencode\skills\`. This PR was run-verified on OpenCode `1.14.32`: `opencode debug skill` discovered all 6 skills. Use `video-recap` for normal end-to-end production, `video-script` for planning or writing only, and the other four skills as tool stages.
+Translated: "Sister-in-law." / "I missed you so much, day and night, I wanted to skin you alive and grind your bones to dust." / "I'm here. Don't be afraid."
+
+At assembly, the original-audio track in [`timeline.json`](examples/guohuo-60s/timeline.json) is ducked under each narration block and restored after it; this timeline is what the JianYing export reads.
+
+### After viewing: what changed, what was frozen, and how it was verified
+
+The case went through four revision rounds, each written into [`revision-log.json`](examples/guohuo-60s/revision-log.json) as three lists: what to change, what stays frozen, how to verify. The last round unfreezes picture only:
+
+```json
+{
+  "baseline": "final_picture_conform",
+  "scope": "picture_conform",
+  "change_set": [
+    "remove the visible tail-frame pause near 42.08 seconds",
+    "restore continuous source movement around 46.24 seconds"
+  ],
+  "frozen_set": [
+    "story and narration",
+    "all audio",
+    "caption timing and typography",
+    "title and accent graphics"
+  ],
+  "verification": [
+    "normal-speed full watch",
+    "join playback around both change points",
+    "freeze detection as supporting evidence",
+    "audio stream-copy verification",
+    "full decode"
+  ]
+}
+```
 
-#### OpenClaw
+[`edit-map.json`](examples/guohuo-60s/edit-map.json) records how the jump near 46 s was repaired: not with a dissolve or a flash frame, but by restoring the 2001–2004 s stretch of the same continuous movement that had been cut out:
+
+```json
+{
+  "name": "wedding_corridor_continuous_motion",
+  "beat_ids": ["b07", "b08"],
+  "output_frames": [1052, 1288],
+  "output_seconds": [42.08, 51.52],
+  "asset_id": "episode-21",
+  "source_seconds": [1996.0, 2010.32],
+  "speed": 1.516949153,
+  "repair": "Restored the omitted 2001-2004 source interval instead of hiding the jump with a transition."
+},
+```
 
-After cloning, import the Claude plugin bundle and check the discovered skills:
+The mechanical pre-delivery checks are in [`assembly_qc.json`](examples/guohuo-60s/assembly_qc.json) (loudness, subtitle overflow, release gate) and [`delivery-qc.json`](examples/guohuo-60s/delivery-qc.json):
 
-```bash
-openclaw plugins install ./video-recap-skills
-openclaw skills list
+```json
+"checks": {
+  "full_decode": true,
+  "audio_stream_matches_master": true,
+  "vmaf_mean": 93.844938,
+  "ssim_all": 0.989302,
+  "psnr_average_db": 45.415972
+}
 ```
 
-Do not register the same checkout through multiple discovery paths; duplicate registration can cause name collisions or repeated triggers.
+And [`content-qc.md`](examples/guohuo-60s/content-qc.md) checks every narration claim against the footage and public sources, and states the interpretive boundary of each colloquial line (1 of 9 rows):
 
-After installation, ask the agent to check the environment:
-
-```text
-Check the video-recap environment and tell me whether Python, ffmpeg/libass, and MiMo are ready.
+```markdown
+| “这一下伪装露馅，男主全懂了” | 挡击动作和“有我在”原声连续证明她仍在意男主 | [爱奇艺官方角色片花](https://www.iqiyi.com/v_r8e40v8g54.html)确认二人重逢后身份错位、爱恨拉扯 | **解释成立，但需限定语义**：“全懂”指看懂她仍在意他，不指此刻才第一次认出她是任素素 |
 ```
 
-## Usage
+Translated: claim "the disguise slips and the hero understands everything"; footage evidence: the shielding action and the "I'm here" line together prove she still cares; web evidence: iQIYI's official character trailer confirms the mistaken identity and push-pull after the reunion; verdict: **the interpretation holds, with a semantic limit**: "understands everything" means he sees she still cares, not that this is the first moment he recognises her as Ren Susu.
 
-Give the agent the video paths, desired result, and any useful story context. Users do not need to run the repository's Python scripts directly.
+### Keep editing in JianYing
+
+Add "export a JianYing draft" to the request and `timeline.json` is written as an editable multi-track draft: source clips, per-segment narration, BGM, subtitles, and image overlays each on their own track, with media bundled under `Resources/local` so the draft still opens on another machine. The `recap_<name>.mp4` that `ffmpeg` renders is the final piece; the draft is for you to keep working on.
+
+<img alt="Exported JianYing draft: source clips, narration, BGM, and subtitles" src="docs/jianying-export.jpg" width="100%">
+
+Export contents and limits: [JianYing draft export and cost](docs/capcut-jianying-draft-export.md) (Chinese).
+
+## Your first request
+
+Copy one and adjust it. Give the video path, the recap you want, and any useful story context; you never run the repository's Python scripts by hand.
 
 **Full-video recap:**
 
@@ -144,114 +314,155 @@ Give the agent the video paths, desired result, and any useful story context. Us
 Make a Chinese-narration recap of /path/to/video.mp4. It is episode 1 of 庆余年, the lead is 范闲, and subtitles should be burned in.
 ```
 
-**Cut a long video into a shorter recap:**
+**Cut a long video or several episodes into one short recap:**
 
 ```text
-Turn /path/to/long.mp4 into a roughly ten-minute recap while preserving key original dialogue and character reactions.
+Use /path/to/ep1.mp4 and /path/to/ep2.mp4 to make one ten-minute recap with a shared story spine, keeping key original dialogue and character reactions, not two separate summaries.
 ```
 
-**Build one story from multiple videos:**
+**Text-only handoff first, no voiceover and no render** (replace the 〈placeholders〉):
 
-```text
-Use /path/to/ep1.mp4 and /path/to/ep2.mp4 to make one ten-minute recap with a shared story spine, not two separate summaries.
+> I have permission to use 〈local video〉 and am supplying checked picture and dialogue records for it. Propose only the sound handoff for this material: which full dialogue line, action sound or pause to preserve, where narration is needed, and which record supports each choice. List missing evidence rather than inventing motives or unseen events. Return beat notes and necessary narration drafts without calling TTS or rendering.
+
+The agent handles understanding, story and audiovisual planning, cutting, scripting, voiceover, and assembly. In cut mode it first chooses the footage, renders the shortened video, and only then writes narration on the output timeline; the internal pauses and resumes are the agent's job too.
+
+## Workflow and the six skills
+
+```mermaid
+flowchart LR
+    video(["Video"]) --> understand["① Understand<br/>scenes · ASR · VLM"]
+    research["Story research · optional"] -.-> understand
+    understand --> script["② Direct · Edit · Script<br/>agent"] --> voiceover["③ Voiceover<br/>MiMo / Fish Audio"] --> assemble["④ Assemble<br/>mix · subtitles"] --> output(["Recap"])
+    understand -. cut mode · cut first .-> cut["Cut<br/>render first"] -.-> script
+    classDef io fill:#4f86c6,stroke:#3a6298,color:#fff;
+    classDef stage fill:#eef6ff,stroke:#4f86c6,color:#1f2937;
+    classDef opt fill:#f3f4f6,stroke:#9ca3af,color:#475569;
+    class video,output io;
+    class understand,script,voiceover,assemble stage;
+    class research,cut opt;
 ```
 
-The agent handles understanding, story and audiovisual planning, editing, narration, voiceover, and assembly. In cut mode it first chooses footage, renders the shortened video, and only then writes narration on the output timeline; the agent also handles the internal pauses and resume steps.
+The six skills hand off through the JSON / MP4 artifacts in `work_dir`:
+
+| Skill | Responsibility | In → Out |
+|---|---|---|
+| [`video-recap`](skills/video-recap/) | Orchestrator and environment doctor; the one to use for everyday end-to-end production | `video` → `recap_<name>.mp4` |
+| [`video-understanding`](skills/video-understanding/) | Scene detection · frame extraction · ASR (`mimo-v2.5-asr`) · VLM (`mimo-v2.5`) · timeline fusion · creative brief | `video` → `scenes / asr_result / vlm_analysis / silence_periods / timeline_fusion / agent_narration_brief.md` |
+| [`video-script`](skills/video-script/) | Directing / story / picture / sound plan, narration writing, advisory review and lint; call it alone for planning or writing only | `brief + index` → `recap_story_plan.json + visual_audio_board.json + [clip_plan.json] + narration.json` |
+| [`video-cut`](skills/video-cut/) | Clip plan → rendered cut; cut first, narrate second on the output timeline | `clip_plan.json + video` → `edited_source.mp4` |
+| [`video-voiceover`](skills/video-voiceover/) | Synthesise narration audio (MiMo `mimo-v2.5-tts` / Fish Audio `s2.1-pro-free`) | `narration.json` → `tts_segments/ + tts_meta.json` |
+| [`video-assemble`](skills/video-assemble/) | Mix · duck original audio · render subtitles · multi-track timeline · optional JianYing export | `video + tts_meta` → `recap_<name>.mp4 + subtitles.srt/.ass + timeline.json` |
+
+The recap is always written to `recap_<name>.mp4` alongside `subtitles.srt/.ass`; all intermediate artifacts live in `work_dir/`, with the field contracts in the [data schema](skills/video-recap/references/data-schema.md).
 
-## Common advanced requests
+## Advanced requests
 
-**Reuse previously analyzed material:**
+**Reuse previously analysed material:**
 
 ```text
 Analyze /path/to/ep1.mp4 and save reusable understanding artifacts under /path/to/.video-materials. Prefer that material library in later projects.
 ```
 
-The library contains JSON, Markdown, and an index only. It does not copy raw media, create a database, or use embeddings; the agent searches it directly on the filesystem.
+The library holds JSON, Markdown, and an index only; it copies no media, builds no database, and uses no embeddings. The agent simply `grep`s the filesystem.
 
-**Add advisory quality review and export a JianYing draft:**
+**Run an advisory MiMo review before and after assembly, and export a JianYing draft:**
 
 ```text
 Make a recap of /path/to/video.mp4, run MiMo quality review before assembly and after rendering, and export an editable JianYing draft.
 ```
 
-MiMo review is always advisory: at most one request per selected stage, fail-open, and never an automatic edit or render blocker.
+MiMo review makes at most one request per stage, only suggests, and never blocks the render if it fails.
 
-**Align new subtitles with the source's burned-in subtitle band:**
+**Align recap subtitles with the source's burned-in subtitle band:**
 
 ```text
 Detect the source subtitle band in /path/to/video.mp4 and let me confirm the preview before rendering recap subtitles in the same region.
 ```
 
-The measurement preview is stored under `.subtitle_measure/`. It currently requires square-pixel video and bottom-aligned source subtitles. This capability is adapted from [ops120/video-recap-skills-plus](https://github.com/ops120/video-recap-skills-plus).
+The preview is stored under `.subtitle_measure/`; it currently requires square-pixel video and bottom-aligned source subtitles.
 
-**Clone an authorized reference voice:**
+**Voice with an authorised reference voice:**
 
 ```text
 Use the voice from /path/to/voice-ref.wav for the recap of /path/to/video.mp4. I have the voice owner's authorization.
 ```
 
-The reference audio is sent to MiMo for synthesis and its content fingerprint participates in cache validation. Use voice cloning only with the voice owner's authorization.
+The reference audio is sent to MiMo for synthesis; use it only with the voice owner's authorisation.
+
+**Dub an English video into Chinese while keeping the speaker's voice:**
+
+```text
+Dub /path/to/english.mp4 into Chinese, keeping the original speaker's voice.
+```
+
+This replaces the original speech rather than overlaying commentary; the current version supports one speaker and full-track replacement without background-music separation.
 
-**Use the currently free Fish Audio voiceover path:**
+**Reuse subtitle style, voice, BGM and frame across a series:**
 
 ```text
-Use Fish Audio for the Chinese narration of /path/to/video.mp4 with the built-in “娱乐扒妹” voice.
+Use /path/to/library as the resource library: register this BGM, this font and this frame image, draft a subtitle-style
+template for 1080x1920 for me to adopt, then render this series with /path/to/series/recap_project.json binding them.
 ```
 
-The agent passes `--tts-provider fish-audio` to the orchestrator. `FISH_API_KEY` is required; the built-in “娱乐扒妹” voice is used unless `FISH_TTS_REFERENCE_ID` overrides it. Local `--voice-ref` cloning remains specific to MiMo.
+Resources, templates and sample films are JSON records in your own directory; licence and "adopted" status are only ever set by you. A binding that conflicts with an explicit setting, or a template whose canvas differs from the output, stops the run before voicing. Each render gets a `resource_lock.json` listing what it actually used and whether the licences are clear. Format: [resource library, templates and samples](skills/video-recap/references/resource-library.md).
 
-**Dub an English video into Chinese while preserving the voice:**
+**Browse projects, runs and the library in a local page (read-only):**
 
 ```text
-Dub /path/to/english.mp4 into Chinese, keeping the original speaker's voice.
+Open the local dashboard for /path/to/projects so I can see run progress, finished videos and the library.
 ```
 
-This replaces the original speech instead of overlaying commentary. The current version supports one speaker and full-track replacement without background-music separation.
+The dashboard is read-only and listens on loopback only; wherever something needs doing it gives you one sentence to paste back into the conversation.
 
-## Architecture
+<img alt="Dashboard film view: player with picture, narration, BGM and subtitle tracks" src="docs/dashboard-film.png" width="100%">
 
-| Skill | Does | In → Out (the `work_dir` contract) |
-|---|---|---|
-| **video-understanding** | scene detect · frame extract · ASR (`mimo-v2.5-asr`) · VLM (`mimo-v2.5`) · fuse timeline · build brief | `video` → `scenes / asr_result / vlm_analysis / silence_periods / timeline_fusion / agent_narration_brief.md` |
-| **video-script** | directing/story/picture/audio plan + narration + advisory review + lint/validate | `brief + index` → `recap_story_plan.json + visual_audio_board.json + [clip_plan.json] + narration.json` |
-| **video-cut** | clip plan → render the cut (cut-first/narrate-second; narration is written on the output timeline, no remap) | `clip_plan.json + video` → `edited_source.mp4` |
-| **video-voiceover** | synthesize narration audio (MiMo `mimo-v2.5-tts` / Fish Audio `s2.1-pro-free`) | `narration.json` → `tts_segments/ + tts_meta.json` |
-| **video-assemble** | mux · duck original audio · render subtitles · multi-track timeline (optional 剪映 export) | `video + tts_meta` → `recap_<name>.mp4 + subtitles.srt/.ass + timeline.json` |
-| **video-recap** | orchestration and environment diagnostics | `video` → `recap_<name>.mp4` |
+<img alt="Dashboard template view: canvas schematics for packaging and subtitle style, parameter table with provenance" src="docs/dashboard-templates.png" width="100%">
+
+**Bring your own original-dialogue subtitles for accurate 「」 captions:** put `user_subtitles.json` (`[{"start": s, "end": s, "text": "line"}]` on the output timeline; wrap it as `{"timeline": "source", "lines": [...]}` for source-timeline subs mapped through the clip plan) or `user_subtitles.srt` / `.ass` (source timeline) into `work_dir`. Priority: your file › the agent-proofread `original_subtitles.json` › ASR fallback.
+
+## FAQ
 
-## Output
+### My video has no narration, or even no dialogue. Can it still get a new narration track?
 
-- `recap_<name>.mp4`: the final recap, written to a stable name; subtitles are burned in by default and also written as `subtitles.srt` and `subtitles.ass`
-- `work_dir/narration.json`: the narration script (`narration_lint.json` timing diagnostics, `narration_review.md` review notes)
-- `work_dir/recap_story_plan.json` · `visual_audio_board.json`: agent-authored story, picture, and audio decisions for resume/advisory review; not a render gate
-- `work_dir/agent_narration_brief.md`: timing and scene brief for the agent
-- `work_dir/vlm_analysis.json` · `asr_result.json` · `silence_periods.json` · `timeline_fusion.json`: understanding artifacts
-- `work_dir/clip_plan.json` · `edited_source.mp4` · `recap_phase.json`: cut-mode artifacts (narration is written on the output timeline; `recap_phase.json` records cut/narrate progress for deterministic resume)
-- `work_dir/multi_source_manifest.json` · `work_dir/sources/<source_id>/`: multi-video cut source manifest and per-source analysis artifacts
-- `<material-library-dir>/materials/<material_id>/material.json|material.md` · `materials_index.jsonl`: optional grep-friendly material library for reusing analyzed sources
-- `work_dir/timeline.json` · `work_dir/assembly_manifest.json` · `tts_segments/` · `tts_meta.json`: multi-track timeline, slim render record, and TTS audio
-- `work_dir/mimo_qc.json`: optional aggregated pre-assemble/post-render MiMo advice; never a gate
+Yes. Understanding relies on the VLM reading the picture and does not require existing narration; when there is no dialogue either, have the agent skip ASR (`--skip-asr`) and narrate from the picture. This was asked in [issue #79](https://github.com/zenstory-ai/video-recap-skills/issues/79).
 
-## Bring your own original-dialogue subtitles (optional, more accurate)
+### A long video hit a 429 or was interrupted halfway. Do I start over?
 
-During the original-audio gaps between narration blocks, the original dialogue is burned as a subtitle (wrapped in `「」` to set it apart from narration). By default that text is agent-proofread with an ASR fallback — but ASR timing is coarse and can drift from the audio. For accurate timing, drop a subtitle file into `work_dir`; it becomes the **preferred source**:
+No. VLM scene analysis resumes from where it stopped and recovers from rate limits; once `narration.json` is written, repeating the same command continues, cut mode records cut/narrate progress in `recap_phase.json`, and a resume only continues a work directory for the same source video and parameters.
 
-- `work_dir/user_subtitles.json`: `[{"start": s, "end": s, "text": "line"}]` on the **output** timeline, used as-is; or wrap it as `{"timeline": "source", "lines": [...]}` to give **source**-timeline subs that are auto-mapped onto the cut via the clip plan.
-- `work_dir/user_subtitles.srt` / `.ass`: parsed as **source**-timeline by default and mapped onto the cut.
+### The VLM can't tell who is who and the narration is all "a man in black"?
 
-Priority: **your file › the agent-proofread `original_subtitles.json` › ASR fallback**. When the source is accurate, each line is clipped precisely into its gap instead of being placed by a coarse midpoint estimate.
+When the title or plot is known, have the agent research first and write `background_research.json`; character names and relationships are folded into the VLM context. See the [research guide](skills/video-understanding/references/research-guide.md) (Chinese).
 
-## References
+## Further reading
 
-- Per-skill contracts: each `skills/<skill>/SKILL.md` (the writing rules are in video-script's SKILL.md)
-- [Data schema](skills/video-recap/references/data-schema.md) · [Config playbook](skills/video-recap/references/config-playbook.md) · [Multi-track timeline / 剪映 export](skills/video-recap/references/timeline-and-jianying.md)
-- [Background research guide](skills/video-recap/references/research-guide.md) · [VLM prompt templates](skills/video-understanding/references/prompt-templates.md)
+- [Video-to-narration workflow](https://zenstory.ai/video-recap/video-to-narration) — establish picture, dialogue, and supplied background before treating a claim as a source-video fact
+- [Original sound and narration](https://zenstory.ai/video-recap/original-audio-and-narration) — assign each beat's sound task first, then write the narration
+- [JianYing / CapCut draft export](https://zenstory.ai/video-recap/capcut-draft) — export independently from a real `timeline.json`
+- [JianYing draft export and cost](docs/capcut-jianying-draft-export.md) — in-repo document (Chinese): what is in the draft, and how self-hosting bills differ from SaaS
+- [Production boundaries and acceptance](docs/production-boundaries.md) — in-repo document (Chinese): which delivery rules belong in the shared library and which belong to a single project; the three kinds of acceptance cannot stand in for one another
+- [Guohuo case runbook](examples/guohuo-60s/skill-runbook.md) · [decision chain from content lock to final](examples/guohuo-60s/iteration-notes.md) (both in Chinese)
+- Per-skill contracts in each `skills/<skill>/SKILL.md`; [data schema](skills/video-recap/references/data-schema.md) · [config playbook](skills/video-recap/references/config-playbook.md) · [multi-track timeline / JianYing export](docs/timeline-and-jianying.md) · [creative editing playbook](skills/video-script/references/creative-editing-playbook.md)
 
 ## Acknowledgements
 
-- [linux.do](https://linux.do)
-- The 剪映 draft protocol references [pyJianYingDraft](https://github.com/GuanYixuan/pyJianYingDraft), [capcut-mate](https://github.com/Hommy-master/capcut-mate), and [duo-video](https://github.com/duoec/duo-video).
+- [LINUX DO - The New Ideal Community](https://linux.do) — community support
+- The JianYing draft protocol references [pyJianYingDraft](https://github.com/GuanYixuan/pyJianYingDraft), [capcut-mate](https://github.com/Hommy-master/capcut-mate), and [duo-video](https://github.com/duoec/duo-video)
+- Subtitle-band detection adapted from [ops120/video-recap-skills-plus](https://github.com/ops120/video-recap-skills-plus)
 
 ## License
 
 MIT, see [LICENSE](LICENSE).
+
+## Part of ZenStory AI
+
+This project is maintained by [ZenStory AI](https://zenstory.ai) — open-source, agent-native tools for creating, adapting and producing stories (GitHub org: [zenstory-ai](https://github.com/zenstory-ai)). Sibling projects:
+
+| Project | What it does |
+| --- | --- |
+| [oh-story-claudecode](https://github.com/zenstory-ai/oh-story-claudecode) | Web-fiction writing skill pack: chart scanning, deconstruction, drafting, de-AI-flavor, covers |
+| [drama-skills](https://github.com/zenstory-ai/drama-skills) | AI short-drama / motion-comic suite: scripts, assets, storyboards, image & video prompts, review |
+| [novel-to-game](https://github.com/zenstory-ai/novel-to-game) | Agent skills for source-grounded novel adaptation, target-runtime builds, and evidence-based QA |
+| [video-recap-skills](https://github.com/zenstory-ai/video-recap-skills) | Create Chinese-narration recaps from supported video files, with optional editable JianYing/CapCut draft export (this repo) |
+| [oh-story-dsh](https://github.com/zenstory-ai/oh-story-dsh) | Community DeepSeek Harness plugin with novel, short-drama, game and video-recap workbenches |
+| [zenstory](https://github.com/zenstory-ai/zenstory) | Chat-to-create AI novel-writing workbench ([app.zenstory.ai](https://app.zenstory.ai)) |