video-script

1. Positioning

When only changing the promo 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 viewing rationale and payoff position, without redoing the planning/commentary chain below. Ordinary commentary writing does not thereby add platform research or packaging tasks.

This skill covers: creative direction, picture/sound plan, commentary writing, and verification. The Agent is not a JSON filler but must successively play:

1. Director
2. Story Editor
3. Picture Editor
4. Sound/Commentary Editor
5. First-time Viewer

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

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

1.1 Creative Control Mode

First determine this round's mode based on the user's requirements and work_dir ; it is not full|cut|dub render 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 fabricate alternatives just to satisfy a "creative process."
• REVISION: The user is reviewing and revising an existing version. The latest feedback is the current source of truth; unspecified parts are frozen by default.

For REVISION, first clarify this round's modification items and frozen items, then edit the corresponding layer: expression, spoken rhythm, and subtitle feedback update style_card.json; shots, in/out points, performance, and sound division of labor update visual_audio_board.json; only update recap_story_plan.jsonwhen the audience promise, POV, mainline, or beats change. Deleted shots, original sound, or copy must also be removed from related plans; do not retain stale anchors. Do not redo a review-based revision as a CREATE.

2. Remote Calls and Data Transmission

Only one script in this skill accesses the network: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 without making any network requests; planning and scriptwriting are done by the Agent directly reading and writing work_dir .

review.py What is sent to whom:

• MiMo's OpenAI-compatible chat endpoint <MIMO_API_URL>/chat/completions, authenticated with MIMO_API_KEY , with model MIMO_MODEL(default mimo-v2.5). When MIMO_API_URL is not set, a pay-as-you-go key is sent to https://api.xiaomimimo.com/v1，tp- and a Token Plan key beginning with MIMO_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 time and text of all commentary paragraphs.
• Textual evidence for understanding the index: within the time segments selected near the beginning, middle, and end, long gaps, and each narration time window,vlm_analysis.json scene description and frame_facts text, as well as dialogue transcription (when asr_clean.json is available use it, otherwise asr_result.json）。
• background_research.json 's synopsis, characters, relationships, and storyline excerpts.
• when present, attach packaging_plan.json、recap_story_plan.json、visual_audio_board.json、style_card.json(first 3000 characters of each cut) and original_subtitles.json 's original audio subtitle text.
• when the content is long, split into chunks, one request per chunk; the returned comments are written back only to the local narration_review.json / narration_review.md。

when it runs, how to disable it:

• when using this skill on its own,review.py runs only when the user or Agent explicitly executes it; if it is not executed, there is no outbound transmission at all. 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 invokes this review once before TTS, and a failure does not block; the way to disable it is 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 is authoritative (lint, review, editing, and synthesis all read it).
• contact sheet listed at the top of the brief: do not rely only on the scene summary; the specific moments of reactions, blocking, stillness, and before and after lines are often more important.
• production_reference.json(only when work_dir is in): transferable methods and pacing values extracted from another finished piece, see §4 for usage.

full mode uses original footage time. In the first stage of cut mode, only write clip_plan.json；edited_source.mp4 after it is generated, only in the second stage write by output time narration.json。

before writing any creative artifact, 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 , enter scriptwriting; when it exists, review first and then validate.
• cut first stage: there is not yet clip_plan_validated.json / edited_source.mp4, only write clip_plan.json。
• cut second stage: both exist, according to clip_plan_validated.json.clips[] in source_start/end and output_start/end verify the mapping, then write the narration for the output time.

Must confirm that the narration does not cross incorrect edit boundaries and does not fall into deleted intervals. The entire determination relies only on work_dir artifacts.

4. Formulate the creative plan

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

1. recap_story_plan.json: director's intent, at least two editing hypotheses in CREATE, the selected POV / main line, and beats defined by "change." DIRECTED / REVISION do not force new hypotheses.
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 making a plan. It comes from another finished film and contains only transferable methods and measured pacing, not facts about this film, and cannot serve as evidence for this film's visuals, plot, or dialogue. Priority: user instructions > this film's evidence > reference. CREATE may treat its structure as a candidate hypothesis and compare it with hypotheses generated from the material; DIRECTED / REVISION does not apply it by default.targets are reference values, not quotas: when they conflict with this film's audio_owner, complete dialogue, or performance, the material takes precedence. 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 section.

4.1 Director's Judgment

Locks:

• Audience promise
• POV
• Dramatic question
• Starting and ending emotions
• Concealment and revelation
• Closing 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 must change at least one of the following: knowledge, power, goal, relationship, emotion, or risk. If deleting it causes no loss to causality, character, or emotion, that beat usually should not be kept.

4.3 Visual Editing

Choose specific moments, not just events. Compare:

• Speaker vs. listener
• Action vs. reaction
• Early in vs. late in
• Early out vs. holding half a second longer

Enter late and exit early without breaking comprehension, while preserving irreplaceable performance, pauses, mistakes, action sounds, and complete 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 visuals, original sound, or silence are already sufficient, use none, and do not default to laying on narration.

4.5 cut Mode Phase One

In cut mode, first based on recap_story_plan.json and visual_audio_board.json , write the original-film-time 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 clip order must form a complete storyline, not a disordered highlight reel. You may use 0–1 cold open, then return to a causally clear setup → turn → escalation → payoff. Clip length should follow the specific moment, not a uniform seconds-based template; the ending must preserve complete dialogue or action. The source judgment and handling rules for dense scene-change candidates are defined in 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 by original-film time; in cut phase two, first review edited_source.mp4 and the post-cut storyboard, supplement visual_audio_board.json 's output time and reconfirm audio_owner / narration_job, then write by output time:

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

Field descriptions:

Field	Meaning
start / end	In full mode this is original-film time; in cut phase two this 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 1.2 seconds early, and the early portion will not enter the original dialogue; the first block of a paragraph starts from start If the previous block runs overtime, it shifts to after the previous block's end plus a pause
narration	Narration text
pause_after_ms	Post-segment pause, default 250ms
overlaps_speech	Whether it overlaps with the original dialogue; consecutive underlay windows are usually true, and only true silent slots are false
emotion	MiMo TTS emotion/tone tag for the entire narration block

5.1 Writing Rules

1. First there is narration_job, then there are sentences: if there is no clear task, do not write; narration is not the default audio track.
2. Write by continuous thought: when narration owns a beat, use one or a few complete sentences to accomplish "premise → triggering action → change/meaning," and synthesize in a single TTS pass. Periods obey spoken thought 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 there is insufficient material. 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 volume by effective speech rate: use 字数 / brief 头部 speech budget to estimate the read-aloud seconds, and add about 0.45 seconds of TTS head/tail silence to each block. The word counts marked for each window in the brief do not deduct this silence, so 2–3 second short windows should be written with one or two fewer words than that; when it does not fit, cut or split the narrative task instead of speeding up and cramming in words.
6. Do not talk over the visuals: narration only adds context, causality, expectation, evidence-supported explanation, or cross-cutting.
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 facts in the current frame.
8. Write for the ear: use concrete nouns and verbs, with complete, spoken, listenable sentences; avoid subtitle-ese, half-sentences, vague elevation, and em dashes. TTS text should first ensure listening continuity, and subtitles should then be split by reading width; do not reverse this by chopping the read-aloud script into pieces.
9. Avoid templated correction: "not A, but B" is used only when there really is a judgment the audience might believe and the material needs to correct. It is not a banned phrase, but false insight must not be manufactured by first negating and then affirming; prioritize directly writing the character's action, causality, and consequence.

5.2 Narration Structure

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

5.3 Original-Sound Blank Subtitles

Optionally write original_subtitles.json, using the final-cut output timing:

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

Write only dialogue actually audible in the blank, correct ASR typos and personal names, and keep each entry to one line where possible; do not write sentences that are covered by narration or have already been cut. When omitted, the composition 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. Delete each beat: if there is no loss to causality, character, emotion, or promise, 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 audio should still carry visible action, character behavior, and key emotions.
4. Listen to the audio only: the narration should form an intelligible throughline, not screen subtitles.
5. Replace narration with original audio 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 be 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 the relevant style_card.json / visual_audio_board.json contains no old shots or old expressions. Unless the user requests an alternative 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’s time. Open narration_review.md, process item by item error, especially category=hallucination。

Repeat revisions and reviews until:

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

Append the override decision to work_dir/narration_review_override.md：

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

review.py itself only writes a report; 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 may block before TTS. Override records are for audit only,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 kept as-is: not truncated, not merged, not punctuated, not reordered. Recommended character counts are calculated after first subtracting 0.45 seconds of TTS lead-in/lead-out 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 in the report the time window,budget_chars、limit_chars、actual_chars and over_chars: shorten the text or loosen/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 the fix. After fixing all errors, run repeatedly until validation is clean, then continue with TTS and composition.

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 material is thin, the quantities in the brief can only be treated as upper limits: prefer writing less and writing truthfully rather than restating 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 run only locally.
• Platform research is used only for explicit promotional tasks; it does not replace the facts within the current video, nor does it change the commentary and editing by default.