video-script

1. Positioning

When only changing the promotional title, cover, on-screen text, or backfilling external copy, directly read references/promotional-copy.md, and handle the specified text layer according to the current short film's reason to watch and payoff positions, without redoing the planning/narration chain described below. Regular narration writing does not thereby add platform research or packaging tasks.

This skill is responsible for: creative direction, visual/sound plan, narration writing, and verification. The Agent is not a JSON filler, but must play these roles in turn:

1. Director
2. Story editor
3. Picture editor
4. Sound/narration editor
5. First-time viewer

The Agent first records concise decisions, then writes timeline artifacts.validate.py is responsible for mechanically verifying the understanding index, and never rewrites the Agent's script: paragraph order, count, timing, text, pauses, and extended metadata are preserved as-is; it only writes back the measured overlaps_speechbased on existing sound evidence. Problems such as text not fitting the time window or paragraphs not sorted by time are returned to the Agent as errors to fix.

The following scripts/... are all relative to this skill directory. If the executor starts from the repository root, prefix the script path with this skill's absolute directory.

1.1 Creative control mode

First determine this round's mode based on user requirements and work_dir ; it is not the full|cut|dub rendering mode:

• CREATE: first-time creation. Compare at least two genuinely viable story/editing hypotheses before choosing.
• DIRECTED: the user has specified the structure, shots, lines, or expression. Implement faithfully, and do not invent alternatives just to satisfy a "creative process."
• REVISION: the user is revising by watching an existing version. The latest feedback is the current source of truth; unspecified parts are frozen by default.

In REVISION, first clarify this round's change items and frozen items, then edit the corresponding layer: expression, spoken rhythm, and subtitle feedback updates style_card.json; shots, in/out points, performance, and sound division of labor update visual_audio_board.json; update recap_story_plan.jsononly when the audience promise, POV, main line, or beat changes. Deleted shots, original sound, or copy must also be removed from related plans; do not keep outdated anchors. Do not turn a viewing-based revision back into a CREATE.

2. Remote calls and data egress

This skill has only one script that goes online:review.py(the advisory semantic review in §7.1). Everything else runs locally:validate.py and its lint and de-AI-flavor checks only read and write files in work_dir , and send no network requests; planning and scriptwriting are completed by the Agent directly reading and writing work_dir .

review.py What is sent to whom:

• MiMo's OpenAI-compatible chat interface <MIMO_API_URL>/chat/completions, authenticated with MIMO_API_KEY , model MIMO_MODEL(default mimo-v2.5). When MIMO_API_URL is not set, pay-as-you-go keys are sent to https://api.xiaomimimo.com/v1，tp- Token Plan keys starting with are sent to MIMO_TOKEN_PLAN_CLUSTER the selected token-plan cluster (default https://token-plan-cn.xiaomimimo.com/v1）。
• When MIMO_API_KEY is not set, exit directly without constructing or sending any request.

review.py What is sent (text only; no video, frame images, or audio files):

• narration.json the timings and text of all narration paragraphs.
• Textual evidence for understanding the index: within the time ranges selected near the beginning, middle, end, long gaps, and each narration time window,vlm_analysis.json scene descriptions and frame_facts text, as well as dialogue transcripts (use asr_clean.json when available, otherwise asr_result.json）。
• background_research.json synopsis, characters, relationships, and plotline excerpts.
• When present, attach packaging_plan.json、recap_story_plan.json、visual_audio_board.json、style_card.json(first 3000 characters of each excerpt) and original_subtitles.json original audio subtitle text.
• When the content is long, split into chunks, one request per chunk; write the returned feedback only to the local narration_review.json / narration_review.md。

When it runs and how to disable it:

• When using this skill on its own,review.py it runs only when the user or Agent explicitly executes it; if it is not executed, nothing is sent out. When the user does not want the script to leave the local machine, do not run it; instead, after manual review, directly run validate.py。
• The end-to-end orchestration by default automatically calls this review once before TTS, and a failure does not block; to disable it, use the orchestration entry point's --no-review-narration or the environment variable REVIEW_NARRATION=0. If strict review is also enabled (--require-narration-review or REQUIRE_NARRATION_REVIEW=1), the review must run, and the disable switch has no effect.
• The review is advisory: it only writes a report and never rewrites narration.json; whether to modify is decided by the Agent or the user.

3. Read the materials and confirm the status

First read:

• work_dir/agent_narration_brief.md: scenes, durations, quiet windows, and word-count budget.
• asr_writing_chunks.json: writing chunks for long dialogue.
• timeline_fusion.json: determine whether a given segment has dialogue or a silent slot.
• vlm_analysis.json / asr_result.json: verify the specific visuals and original audio evidence; when asr_clean.json is available, its text takes precedence (lint, review, editing, and synthesis all read it).
• The contact sheet listed at the top of the brief: do not rely only on scene summaries; reactions, blocking, stillness, and the specific moments before and after lines are often more important.
• production_reference.json(only when work_dir contains it): transferable methods and pacing values extracted from another finished film; for usage, see §4.

full mode uses the original film's time. In the first stage of cut mode, write only clip_plan.json；edited_source.mp4 is produced, and only in the second stage write according to the output time narration.json。

Before writing any creative output, directly read work_dir to determine the current stage:

• recap_run_manifest.json: confirm edit_mode, the source video, and this round's settings.
• full mode: when there is no narration.json , proceed to scriptwriting; when it exists, review first and then verify.
• cut first stage: there is not yet clip_plan_validated.json / edited_source.mp4, write only clip_plan.json。
• cut second stage: both exist; verify the mapping according to clip_plan_validated.json.clips[] in source_start/end and output_start/end , then write the narration for the output time.

It must be confirmed that the narration does not cross incorrect edit boundaries and does not fall into deleted intervals. The entire judgment relies only on work_dir outputs.

4. Formulate the creative plan

First read references/creative-editing-playbook.md, then write or update the working outputs according to the creative control mode:

1. recap_story_plan.json: director's intent, at least two editing hypotheses in CREATE, the chosen POV / main line, and beats defined by "change". DIRECTED / REVISION does not force new hypotheses to be added.
2. visual_audio_board.json: each beat's visual task, specific performance/reaction, in-point/out-point,audio_owner, original audio anchors, and narration_job。
3. style_card.json(when applicable): the voice, spoken rhythm, subtitle reading stance, and explicit taboos currently approved by the user. After receiving expression or subtitle feedback, update the original file rather than only changing the final copy.

Record only decisions, evidence anchors, abandoned alternatives, and brief reasons; do not write lengthy thought processes.

If work_dir has production_reference.json, read it before formulating a plan. It comes from another finished piece and contains only transferable methods and measured pacing, not facts about this piece, and cannot be used as evidence for this piece's visuals, story, or dialogue. Priority: user instructions > this piece's evidence > reference. CREATE may treat its structure as a candidate hypothesis and compare it with hypotheses arising from the material; DIRECTED / REVISION does not apply it by default.targets is a reference value, not a quota: when it conflicts with this piece's audio_owner, full dialogue, or performance, the material prevails. You may write the optional field recap_story_plan.json in reference_methods: [{"id": "m1", "decision": "adopt|adapt|skip", "note": "…"}]. If this file does not exist, skip this paragraph.

4.1 Director's Judgment

Lock:

• Audience Promise
• POV
• Dramatic Question
• Starting and Ending Emotions
• Concealment and Revelation
• Ending Aftertaste

4.2 Story Editing

CREATE compares two genuinely viable structures and chooses one; DIRECTED / REVISION follows the user-specified or already-confirmed structure unless the latest feedback explicitly changes the story direction. Each beat changes at least one of: knowledge, power, goal, relationship, emotion, or risk. If deleting it would cause no loss to causality, character, or emotion, that beat usually should not be kept.

4.3 Picture Editing

Choose specific moments, not just events. Compare:

• Speaker and Listener
• Action and Reaction
• Early In and Late In
• Early Out and Staying Half a Second Longer

Enter late and exit early without damaging comprehension, while preserving irreplaceable performance, pauses, mistakes, action sounds, and full dialogue.

4.4 Division of Labor Between Sound and Narration

First specify audio_owner, then write. Narration may only take on the following narration_job：

• context
• causal_link
• foreshadow
• interpretation
• transition
• none

When picture, original sound, or silence is already sufficient, use none, and do not default to laying on narration.

4.5 cut Mode Phase One

In cut mode, first write the original-film-time recap_story_plan.json based on visual_audio_board.json and clip_plan.json; at this point do not write narration.json：

{
  "target_duration": "10m",
  "clips": [
    {
      "start": 12.0,
      "end": 38.0,
      "reason": "b01 | hook | knowledge: unknown→threat | POV=主角 | 保留倾听反应 | 入点=问题已问出 | 出点=沉默落地"
    }
  ]
}

reason Use uniformly:

beat_id | function | change | POV | preferred moment | 入点 | 出点

The order of clips must form one complete storyline, not a random montage of highlights. You may use 0–1 cold open, then return to a setup → turn → escalation → payoff with clear causality. Clip length is subject to the specific moment; do not use a uniform seconds-based template. The film's ending must preserve complete dialogue or action. The source judgment and handling rules for dense scene-change candidates are defined by the editing phase; follow the same rules when writing the plan, and do not create artificial flash cuts.

5. Writing Narration

In full mode, write directly according to original-film time; in cut phase two, first review edited_source.mp4 and the post-cut storyboard, then supplement visual_audio_board.json as output time and reconfirm audio_owner / narration_job, then write according to output time:

[
  {
    "start": 5.0,
    "end": 12.0,
    "narration": "解说文本。",
    "pause_after_ms": 250,
    "overlaps_speech": true,
    "emotion": "紧张"
  }
]

Field Description:

Field	Meaning
start / end	In full mode, this is original-film time; in cut phase two, it is output time. Blocks no more than 1.6 seconds apart from the previous block belong to the same paragraph; assemble will make it play immediately after the actual end of the previous block (0.35 seconds apart), at most start up to 1.2 seconds early, and the advanced segment will not enter the original dialogue; the paragraph's first block starts from start if the previous block is overtime, then it is postponed to after the previous block's end plus the pause
narration	Narration Text
pause_after_ms	Pause after the segment, default 250ms
overlaps_speech	Whether it overlaps with the original dialogue; the continuous bed window is usually true, while only a true silent slot is false
emotion	The MiMo TTS emotion/tone tag for the entire narration block

5.1 Writing Rules

1. First there is narration_job, then there is a sentence: if there is no clear task, do not write; narration is not the default audio track.
2. Write along a continuous line of thought: when narration owns a beat, use one or a small number of complete sentences to accomplish “premise → triggering action → change/meaning,” and synthesize them in a single TTS pass. Periods obey the flow of speech and breathing, not subtitle line breaks; do not fix the number of sentences, and do not “pause after every sentence.”
3. 7:3 is not a quota: it serves only as a rough first-draft reference for avoiding wall-to-wall narration when material judgment is insufficient. The actual ratio obeys audio_owner; strong dialogue, action sound, or silence can fully own a beat.
4. Audiovisual relay: if narration leads into original sound, the end of the block should make the audience want to listen; the next block after the original sound ends should carry forward the change it caused.
5. Control quantity by effective speech rate: use 字数 / brief 头部 speech budget to estimate the reading seconds, and add about 0.45 seconds of TTS head and tail silence to each block. The word count marked for each window in the brief does not deduct this silence; a short window of 2–3 seconds should be written one or two characters fewer than that; when it does not fit, cut or split the narrative task instead of speeding up and piling on words.
6. Do not speak without looking at the image: narration only adds context, causality, expectation, evidence-supported explanation, or crossings.
7. Characters and evidence first: prioritize known character names; relationships, motives, subtext, and outcomes must point to visual / ASR / research / user context, and background material must not be disguised as a fact of the current image.
8. Write for the ear: use concrete nouns and verbs; sentences should be complete and audibly conversational; avoid subtitle-ese, half-sentences, vague elevation, and dashes. TTS text should first ensure continuous listening; subtitles are then split according to reading width, and the reading script must not be chopped up in reverse.
9. Avoid template-like correction: “not A, but B” is used only when there truly is a judgment the audience might believe and the material needs to correct. It is not a forbidden sentence, but one must not manufacture fake insight by first negating and then affirming; prioritize directly writing the character’s actions, causality, and consequences.

5.2 Narration Structure

• Hook: raise a question or stake that the main body will truly fulfill; do not use irrelevant retention talk.
• Main line: advance around the chosen POV and main line; do not start over in every scene.
• Progression: subsequent beats must raise the risk, change relationships, or provide new information.
• Suspense gap: only foreshadow consequences that will really be paid off later.
• Ending: answer or intentionally transform the opening question, leaving a clear aftertaste.
• Connection: the narration block and the adjacent original sound belong to the same beat; the former sets it up, the latter presents it, and the next block carries it forward.

5.3 Original Sound Blank Subtitles

Optionally write original_subtitles.json, using the final output time:

[{"start": 15.0, "end": 17.0, "text": "原声台词"}]

Write only the lines actually audible in the blank; correct ASR typos and names, and keep each line to roughly one line; do not write sentences that are covered by narration or have been cut. When omitted, the synthesis stage will use a conservative ASR mapping as a fallback, and in the final cut use 「」 to distinguish original dialogue from narration.

6. Creative self-review

Before calling the LLM review, do the followingcounterfactual checks：

1. Remove each beat: if causality, character, emotion, or promise loses nothing, delete it.
2. Compare speaker/action with listener/reaction: keep the moment that better fits the POV and emotion.
3. Mute the narration: the visuals and original sound should still carry visible action, character behavior, and key emotions.
4. Listen to audio only: the narration should form an understandable main thread, not serve as on-screen subtitles.
5. Replace narration with original sound or silence: if the scene is stronger on its own, give up ownership of the voice.
6. Check whether the opening question is real and whether the ending answers or transforms it.
7. Check whether adjacent short sentences can be combined into one continuous thought; subtitle line breaks must not become a reason for TTS sentence splitting.

Record and prioritize fixing only the 1–3 highest-return issues; fix structure first, then polish sentences.

REVISION must also confirm item by item: the issues named by the user have changed, unnamed frozen items have not changed unexpectedly, and related style_card.json / visual_audio_board.json contain no old shots or old expressions. Unless the user requests an alternate version, do not expand into new directions.

7. Review and validation

7.1 Advisory semantic review

python3 scripts/review.py --work-dir <work_dir>   # 会联网：外发内容与关闭方式见 §2

The review automatically identifies the cut mode and, when a validated edit plan exists, checks against the output timeline;--timeline source can force the use of the original film time. Turn on narration_review.md, handle erroritem by item, especially category=hallucination。

Repeat revision and review until:

• verdict is PASS and there is no error; or
• Make an explicit override for issues that remain.

Append override decisions to work_dir/narration_review_override.md：

### 覆盖记录 — <date>
- 问题：segment 4 / category=hallucination
- 评审意见：“他早已知情”缺少画面/对白依据
- 决定：KEEP — 该事实来自用户提供的当前集背景，而非未来剧情
- 签署：<agent/human>

review.py itself only writes a report, and the default invocation policy is advisory and fail-open; if the caller explicitly enables strict review, factual contradictions, incomplete sentences, parse failures, or review unavailability can block before TTS. Override records are used only for auditing,review.py / validate.py does not read it.

7.2 Deterministic hard validation

python3 scripts/validate.py --work-dir <work_dir> --mode full
# cut 输出时间线由编排器使用 --mode cut_output

The command writes out narration_lint.json. full and cut_output use the same voice attribution algorithm (original dialogue intervals minus quiet windows) to write back overlaps_speech, and all other fields are preserved as-is, without truncation, merging, punctuation addition, or reordering. Recommended character count is calculated by first subtracting 0.45 seconds of TTS head/tail silence from the time window; in full mode, if a segment's character count exceeds 1.25 times the recommended count, report over_budget error, and state the time window,budget_chars、limit_chars、actual_chars and over_chars: shorten the text or relax/move the time window; do not expect TTS to shorten the script for you. When there is an error, the command exits nonzero and lists block by block "segment N" (the Nth block in narration.json, counting from 1;narration_lint.json 's index still counts from 0), the error code, key numbers, and how to fix it. After fixing all errors, run repeatedly until validation is clean, then continue with TTS and synthesis.

When the title or subject is clear but plot context is missing, first follow this skill's references/research-guide.md to write background_research.json. If the understanding material is thin, the quantities in the brief can only be treated as upper limits: better to write less and write truthfully than to restate the visuals just to fill a quota.

8. Capability boundaries

• Does not run ASR / VLM, does not synthesize TTS, does not render video; only consumes the video understanding index.
• The only remote call is review.py 's MiMo text review (see §2);validate.py and lint only run locally.
• Platform research is only used for explicit promotional tasks; it does not replace the current in-video facts, nor does it change the commentary and editing by default.