novel-storyboard

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

novel-storyboard

给 AI 短剧出分镜——管线里第一个直接面对视频模型的层。前提刻在骨子里：镜头是生成出来的，多切一镜的成本几乎为零，所以这里不心疼镜头数量，上限只有一个：视频模型单段生成的时长（默认 15 秒）。

核心机制：镜头认领节拍。 每个镜头声明它覆盖剧本某场的哪几个连续节拍（

sceneIndex

beats: [起, 止]

），镜头不许跨场次——换景必换镜。这让分镜和剧本的关系变成可机械对账的：

交付	解决什么
节拍认领	每个节拍被恰好一个镜头认领、顺序不乱——剧本改了重跑 validate，失效的镜头当场点名
单镜头 ≤ 15 秒	AI 视频单段生成上限，长对话在这里被强制拆镜（ `params.maxShotSeconds` 按模型改）
台词装得下	认领节拍的台词秒数 ≤ 镜头秒数——逐镜检查，不是拍脑袋
分镜图提示词 + 镜头正文	分镜图提示词（ `frame` ，中文，直呼角色名）给图像模型配合设定图出图；镜头正文（ `shot` ，中文，通用身份）写这几秒发生什么。景别是枚举，中文景别词必须写进分镜图提示词
H3 视频提示词（每段一条）	MiniMax H3 的 I2VA 结构：固定对齐指令 + integrated_multimodal_description + overall_soundscape + non_diegetic_music。认领节拍的台词逐字进 `<d>[Chinese] …</d>` 块——对白、声景、配乐一段提示词全带上
Seedance 视频提示词（每段一条，程序拼）	跟 H3 并列。由脚本按官方结构拼：参考图声明、段级走位、逐镜量化字段、台词 `{}` 、音效 `<>` 、配乐 `（）` 、编号约束。模型只写每切的 `shot` ，不写秒数、编号和图片引用
构图量化字段	每段 `blocking` （谁在左谁在右、间距），每镜焦距／机位／构图／视线落点／焦点／稳定性——不出分镜图时，它们就是构图的全部来源
生成批次单	同场景 + 同光照的镜头归一批，共用同一张环境参考图——AI 版的顺场表，脚本自动汇总
配音对齐单	每句台词对到镜号——TTS 音频贴到哪一段视频，脚本自动汇总

{baseDir}

= 本文件所在目录。脚本

{baseDir}/scripts/novel-storyboard.mjs

，零依赖，

node

直接跑。

边界（不做的事）：不写戏不改台词（

novel-script

的活）、不出场景/角色/道具设定图（

novel-art

novel-characters

的活）、不做视频生成与剪辑合成。口型/唇形同步暂不管——那是生成管线的事。

**Storyboard generation for AI short dramas — the first layer in the pipeline that directly interfaces with video models. Core premise baked in: shots are generated, and the cost of adding an extra cut is nearly zero, so there's no need to skimp on the number of shots. There's only one upper limit: the single-segment generation duration of the video model (default 15 seconds).

Core mechanism: shots are assigned to beats. Each shot declares which consecutive beats of a script scene it covers (

sceneIndex

beats: [start, end]

), and shots cannot span scenes — a scene change always requires a new shot. This makes the relationship between storyboard and script mechanically verifiable:

Deliverable	What it solves
Beat assignment	Each beat is assigned to exactly one shot, in correct order — re-run validate when the script changes, and invalid shots are flagged immediately
Single shot ≤ 15 seconds	Upper limit for single-segment AI video generation; long dialogues are forcibly split into shots here ( `params.maxShotSeconds` can be adjusted per model)
Dialogue fits within shot duration	The duration of dialogue from assigned beats ≤ shot duration — checked per shot, no guesswork
Storyboard frame prompts + shot descriptions	Storyboard frame prompts ( `frame` , in Chinese, using character names directly) are for image models to generate frames with reference art; shot descriptions ( `shot` , in Chinese, using generic identities) describe what happens in these few seconds. Shot sizes are enumerated, and Chinese shot size terms must be included in storyboard frame prompts
H3 video prompts (one per segment)	MiniMax H3's I2VA structure: fixed alignment instructions + integrated_multimodal_description + overall_soundscape + non_diegetic_music. Dialogue from assigned beats is placed character by character into `<d>[Chinese] …</d>` blocks — dialogue, soundscape, and score are all included in one segment prompt
Seedance video prompts (one per segment, assembled programmatically)	Parallel to H3. Assembled by scripts according to the official structure: reference image declarations, segment-level blocking, per-shot quantitative fields, dialogue `{}` , sound effects `<>` , score `（）` , numbering constraints. The model only writes the `shot` content for each cut, no durations, numbers, or image references
Composition quantitative fields	Per-segment `blocking` (who is on left/right, spacing), per-shot focal length / camera position / composition / gaze target / focus / stability — when no storyboard frames are generated, these are the sole source of composition
Generation batch sheet	Shots with the same scene + same lighting are grouped into one batch, sharing the same environment reference image — the AI version of a continuity sheet, automatically compiled by scripts
Dubbing alignment sheet	Each line of dialogue is mapped to a shot number — which video segment TTS audio should be attached to, automatically compiled by scripts

{baseDir}

= the directory where this file is located. The script

{baseDir}/scripts/novel-storyboard.mjs

has zero dependencies and runs directly with

node

Boundaries (what it doesn't do): No scriptwriting or dialogue editing (that's

novel-script

's job), no scene/character/prop concept art generation (that's

novel-art

novel-characters

' job), no video generation or editing/compositing. Lip sync is not handled for now — that's the generation pipeline's responsibility.

Step 0 — 定输入与范围

Step 0 — Define Inputs and Scope

script.json 是硬前提——分镜离开剧本没有意义，validate/render 都必须给

--script

。其余上游按有则用：

```
--outline
```
/
```
--cast
```
：提示词禁人名检查 + 报告里 C01 显示成人名
```
--art
```
：报告里 S01 显示成场景名 + 批次单嵌场景设定图
```
--shots <卡片目录>
```
：可选挂载 shot-recipes 的镜头配方卡库（指向
```
shot-recipes/references/cards
```
，只接受目录不接受导出的 JSON），开第 18 道
```
shot-recipe
```
门。没装 shot-recipes 就别给——本 skill 自包含，不依赖它

一次切几集：跟剧本的批次走（剧本写到哪就分到哪），默认一批 ≤ 3 集。

script.json
is a hard prerequisite — storyboards have no meaning without a script, and

--script

must be provided for both validate/render. Other upstream inputs are used if available:

```
--outline
```
/
```
--cast
```
: Enables character name prohibition check in prompts + displays C01 codes as character names in reports
```
--art
```
: Displays S01 codes as scene names in reports + embeds scene concept art in batch sheets
```
--shots <card directory>
```
: Optional mounts the shot-recipes shot formula card library (points to
```
shot-recipes/references/cards
```
, only accepts directories, not exported JSON), enabling the 18th
```
shot-recipe
```
gate. Don't provide this if shot-recipes isn't installed — this skill is self-contained and doesn't depend on it.

How many episodes per batch: Follows the script's batch (divides up to wherever the script is written), default batch size ≤ 3 episodes.

Step 1 — seed 工作底稿

Step 1 — Seed Working Draft

bash

node {baseDir}/scripts/novel-storyboard.mjs seed <script.json> --eps 1-3 > <workdir>/storyboard.json

确定性展开：每场的节拍清单（编号、动作/台词、每拍秒数、说话人）进

seedScenes

，这就是切镜时的工作底稿。每拍几秒是算出来的，不要让模型重新估。 shots 留空，切镜才是模型的活。

bash

node {baseDir}/scripts/novel-storyboard.mjs seed <script.json> --eps 1-3 > <workdir>/storyboard.json

Deterministic expansion: the beat list for each scene (number, action/dialogue, seconds per beat, speaker) is loaded into

seedScenes

, which serves as the working draft for shot cutting. The duration of each beat is calculated, don't let the model re-estimate it.

shots

are left empty — shot cutting is the model's job.

Step 2 — 逐集分段切镜

Step 2 — Segment and Cut Shots Per Episode

每集一份任务，能并发就并发。每份任务拿到：

{baseDir}/references/storyboard-pass.md

和

{baseDir}/references/schema.md

（读它们，照着做）

该集的 seedScenes 底稿 + 场景卡（art.json 的锚点与光照提示词）+ 角色卡（cast.json 的形象要点）

流程：先按剧情单元分段（每段 9–15 秒、不跨场），段内切 2–5 秒的分镜（对话正反打、关键动作插入特写、进场三件套——切镜语法都在 storyboard-pass.md），每切写一条分镜图提示词（中文，直呼角色名）、一段镜头正文

shot

（中文，通用身份）和六个构图字段；每段写

blocking

、

soundscape

，有配乐再写

music

。

每段的镜头正文照
{baseDir}/references/shot-writing.md
写（协议无关：一切一个运镜、动作要做得完、台词逐字、声音分层、不写画风）。发给哪个视频服务，就再套哪份协议语法：MiniMax H3 见

{baseDir}/references/h3-prompt.md

，Seedance 见

{baseDir}/references/seedance-prompt.md

。

每段写一条
h3Prompt
，照

{baseDir}/references/h3-prompt.md

写（官方方法论的内化版，不依赖任何外部 skill）。官方口径默认英文（

promptLang

可切中文），每个镜头独立一行。要点：首行对齐指令和

[Shot k]

切点时刻由分镜秒数推导，一个字符都不许漂（validate 逐字对账）；认领台词逐字进

<d>[Chinese] …</d>

；每切的运镜词写进自己那一行；声景与配乐分进后两个字段——声景也是动作指令，画面改了声景一起改。

Seedance 提示词不用写：

render

报告的提示词面板和

export --protocol seedance

都会从上面这些字段现拼。视觉风格由调用方提交时附加，全局约束用

--constraints <文件>

给。

切完把

seedScenes

删掉。

One task per episode, run concurrently if possible. Each task receives:

{baseDir}/references/storyboard-pass.md

and

{baseDir}/references/schema.md

(read them and follow the instructions)

The episode's
```
seedScenes
```
draft + scene cards (anchor points and lighting prompts from
```
art.json
```
) + character cards (appearance key points from
```
cast.json
```
)

Process: First segment by plot units (each segment 9–15 seconds, no scene crossing), then cut 2–5 second shots within segments (dialogue shot/reverse shot, close-ups inserted for key actions, three-part entry — all shot cutting grammar is in

storyboard-pass.md

). For each cut, write one storyboard frame prompt (in Chinese, using character names directly), one shot description

shot

(in Chinese, generic identities), and six composition fields; for each segment, write

blocking

soundscape

, and

music

if there's a score.

Shot descriptions for each segment should be written according to
{baseDir}/references/shot-writing.md
(protocol-agnostic: one camera movement per cut, actions must be completable, dialogue word-for-word, layered sound, no art style description). Apply the corresponding protocol syntax based on which video service you're sending to: MiniMax H3 see

{baseDir}/references/h3-prompt.md

, Seedance see

{baseDir}/references/seedance-prompt.md

Write one
h3Prompt
per segment, written according to

{baseDir}/references/h3-prompt.md

(internalized version of official methodology, no external skill dependencies). Official default is English (

promptLang

can be switched to Chinese), each shot on its own line. Key points: the first line's alignment instructions and

[Shot k]

cut timings are derived from storyboard durations, not a single character may deviate (validate checks character by character); assigned dialogue is placed word for word into

<d>[Chinese] …</d>

; camera movement terms for each cut are written on their own line; soundscape and score are placed into the latter two fields — soundscape is also an action instruction, so if the画面 changes, the soundscape changes too.

Seedance prompts don't need to be written manually: the prompt panel in

render

reports and

export --protocol seedance

will assemble them on the fly from the above fields. Visual style is attached by the caller when submitting, and global constraints are provided via

--constraints <file>

Delete

seedScenes

after cutting is complete.

Step 3 — 校验 ⛔ 不能跳

Step 3 — Validation ⛔ Cannot Skip

bash

node {baseDir}/scripts/novel-storyboard.mjs validate <storyboard.json> \
  --script <script.json> --outline <outline.json> --cast <cast.json> \
  [--shots </path/to/cards>]

18 道质量门全是代码：节拍全覆盖（分镜级，恰好一次、按顺序、连续）、段 0 < 总秒 ≤ 15、每切 2–5 秒、台词装得进分镜、每集总时长在剧本目标 ±15% 内、同框 ≤ 3 人（超了必须带拆解说明）、段号 E01-01 格式连号、中文景别词在分镜图提示词里、运镜用 H3 词表且在自己的 [Shot k] 段落里、H3 对齐指令由分镜结构推导逐字对账 + 切点时刻逐个对、认领台词逐字进
<d>
块、提示词语言与 promptLang 一致（双向查：中文写成英文、英文混进中文都拦）、分镜图提示词中文非空、视频提示词不含角色名（H3 正文不分语言、Seedance 镜头正文都查；分镜图提示词直呼其名放行）、构图量化字段齐全、Seedance 镜头正文合规（中文非空，不写时间、镜头编号、图片引用和协议符号）、场次/人物/道具对账剧本、镜头配方对账（可选门，见下）。

有违规逐条修，改完重跑，直到通过。

第 18 道
shot-recipe
（可选挂载）：给了

--shots

才查，不给就明说跳过。cut 上可以写一个可选的

recipe

（配方卡 id，cut 级不是 segment 级，多格配方靠连续同 id 的分镜表达，不是数组），门查三条——id 在卡库里、卡片的每条

must_phrases

出现在该切的

frame

里（两边小写化后

includes

）、卡片

cuts

下限 ≥ 2 时连续同 id 的分镜数不得低于该下限。卡片的建议景别与运镜不设门，只在报告的「配方」列和

checkup

末尾提示偏离：配方是语汇不是法条，可选挂载的东西一旦变严就没人挂。

bash

node {baseDir}/scripts/novel-storyboard.mjs validate <storyboard.json> \
  --script <script.json> --outline <outline.json> --cast <cast.json> \
  [--shots </path/to/cards>]

All 18 quality gates are code-enforced: full beat coverage (shot-level, exactly once, in order, consecutive), segment total duration 0 < total seconds ≤ 15, each cut 2–5 seconds, dialogue fits within shot, total episode duration within ±15% of script target, ≤ 3 people in the same frame (exceeding requires a breakdown explanation), segment numbers in consecutive E01-01 format, Chinese shot size terms present in storyboard frame prompts, camera movements use H3 vocabulary and are within their own [Shot k] section, H3 alignment instructions derived from storyboard structure and verified character by character + cut timings checked individually, assigned dialogue placed word for word into
<d>
blocks, prompt language matches
promptLang
(bidirectional check: blocks Chinese written as English and English mixed with Chinese), storyboard frame prompts are non-empty Chinese text, video prompts contain no character names (checked for both H3 body text regardless of language and Seedance shot descriptions; storyboard frame prompts using direct names are allowed), composition quantitative fields are complete, Seedance shot descriptions are compliant (non-empty Chinese, no durations, shot numbers, image references, or protocol symbols), scene/character/prop reconciliation with script, shot recipe reconciliation (optional gate, see below).

Fix violations one by one, re-run after changes, until all pass.

18th
shot-recipe
gate (optional mount): Only checked if

--shots

is provided, otherwise explicitly skipped. An optional

recipe

can be written on a cut (recipe card ID, cut-level, not segment-level, multi-frame recipes are expressed by consecutive shots with the same ID, not an array). The gate checks three things — ID exists in the card library, each

must_phrases

from the card appears in the cut's

frame

(case-insensitive

includes

after lowercasing both), and when the card's

cuts

lower limit ≥ 2, the number of consecutive shots with the same ID must not be lower than that limit. The card's suggested shot sizes and camera movements are not gated, only deviations are noted in the report's "Recipe" column and at the end of

checkup

: recipes are vocabulary, not laws — optional mounts would never be used if they become too strict.

Step 4 — 输出与汇报

Step 4 — Output and Reporting

bash

cd <输出目录>
node {baseDir}/scripts/novel-storyboard.mjs render <剧名>-storyboard.json --md \
  --script <script.json> --outline <outline.json> --art <art.json> > <剧名>-storyboard.md
node {baseDir}/scripts/novel-storyboard.mjs render <剧名>-storyboard.json --html \
  --script <script.json> --outline <outline.json> --art <art.json> > storyboard-report.html

报告界面语言用

--lang zh|en

指定（优先级

--lang

> JSON 顶层

lang

字段 > 默认中文）——只切界面标签，与

promptLang

（H3 提示词语言）互相独立。

render

用

--frames <目录>

找分镜图（

<目录>/<段号>/f<切序>.png

，默认当前目录）、用

--images <目录>

找批次单的场景设定图（

<目录>/<场景 slug>-sheet.png

，默认

./images

），两个都可以指到任意路径——本 skill 不产生这些文件，下游出完图重跑一次 render 就能嵌进报告。

export --frames <目录>

会把找得到的分镜图拷进投产包，不用手动往包里放。报告含：KPI 带、分镜节奏带（粗分隔 = 段边界、片宽 = 分镜时长占比、颜色深浅 = 景别远近、点击跳段卡）、分集分镜表（主分镜图 + 子分镜条 + 逐切分镜行 + 分镜图/H3 提示词复制按钮）、生成批次单、配音对齐单、质量门、导出 JSON。Markdown 版每段附完整 H3 提示词，直接复制可用。

汇报一句话说清：几集几镜、总时长 vs 目标、几个生成批次、报告路径；没过的门明说。

不要说「已出图」——这一步不存在了，交付的是提示词和挂图清单。

最终落地：

<输出目录>/
├── <剧名>-storyboard.json
├── <剧名>-storyboard.md
├── storyboard-report.html         ← 双击就能开
├── manifest.json                  ← export 生成
└── E01-01/                        ← 一段一个文件夹 = 一次 H3 生成的全部材料
    ├── f1.png                     ← 主分镜图（下游出完放这儿）
    ├── f2.png …                   ← 子分镜图
    └── prompt.md                  ← H3 提示词（export 生成）

bash

cd <output-directory>
node {baseDir}/scripts/novel-storyboard.mjs render <drama-name>-storyboard.json --md \
  --script <script.json> --outline <outline.json> --art <art.json> > <drama-name>-storyboard.md
node {baseDir}/scripts/novel-storyboard.mjs render <drama-name>-storyboard.json --html \
  --script <script.json> --outline <outline.json> --art <art.json> > storyboard-report.html

Report interface language is specified with

--lang zh|en

(priority:

--lang

> top-level

lang

field in JSON > default Chinese) — this only affects interface labels and is independent of

promptLang

(H3 prompt language).

render

uses

--frames <directory>

to locate storyboard frames (

<directory>/<segment-number>/f<cut-order>.png

, default current directory), and

--images <directory>

to locate scene concept art for batch sheets (

<directory>/<scene-slug>-sheet.png

, default

./images

). Both can point to any path — this skill does not generate these files; re-run render after downstream image generation to embed them in the report.

export --frames <directory>

will copy found storyboard frames into the production package, no manual placement needed. The report includes: KPI bar, storyboard rhythm bar (thick dividers = segment boundaries, bar width = shot duration proportion, color depth = shot size distance, click to jump to segment card), episode-by-episode storyboard table (main storyboard frame + sub-shot bars + per-cut shot rows + copy buttons for storyboard frame/H3 prompts), generation batch sheet, dubbing alignment sheet, quality gates, exportable JSON. The Markdown version includes full H3 prompts per segment, ready to copy directly.

Report in one sentence: number of episodes and shots, total duration vs target, number of generation batches, report path; explicitly mention any failed gates.

Don't say "images have been generated" — this step doesn't exist; deliverables are prompts and reference image lists.

Final output structure:

<output-directory>/
├── <drama-name>-storyboard.json
├── <drama-name>-storyboard.md
├── storyboard-report.html         ← Double-click to open
├── manifest.json                  ← Generated by export
└── E01-01/                        ← One folder per segment = all materials for one H3 generation
    ├── f1.png                     ← Main storyboard frame (place here after downstream generation)
    ├── f2.png …                   ← Sub storyboard frames
    └── prompt.md                  ← H3 prompt (generated by export)

五个 skill 的接力（管线到此闭环）

Five-Skill Relay (Pipeline Closed Loop Here)

novel-outline    → outline.json    （什么：结构与分集）
novel-characters → cast.json       （谁：角色设定图）
novel-art        → art.json        （哪里：场景/道具设定图）
novel-script     → script.json     （戏：场次、节拍、台词）
novel-storyboard → storyboard.json （怎么拍：镜头、首帧、批次）

分镜是消费端：seed 吃 script.json，分镜图出图（在下游）吃 art 和 characters 的设定图当参考，H3 提示词直接下单给视频模型，配音对齐单接 script 台词本的 TTS 产物。五份 JSON 各自的报告都带导出按钮，改完都能喂回各自的 render/validate。

novel-outline    → outline.json    (What: structure and episode division)
novel-characters → cast.json       (Who: character concept art)
novel-art        → art.json        (Where: scene/prop concept art)
novel-script     → script.json     (Drama: scenes, beats, dialogue)
novel-storyboard → storyboard.json (How to shoot: shots, first frames, batches)

Storyboarding is the consumer end: seed consumes

script.json

, storyboard frame generation (downstream) consumes art and characters concept art as references, H3 prompts are sent directly to the video model, and the dubbing alignment sheet connects to TTS output from the script's dialogue book. Each of the five JSON files has export buttons in its respective report, and after modifications, they can be fed back into their respective render/validate processes.

边界

Boundaries

报告界面内置中英（
```
--lang
```
，默认中文）；提示词语言由
```
promptLang
```
单独控制（默认英文）
秒数是下给视频模型的生成时长不是估算——段上限按你的模型改
```
params.maxSegmentSeconds
```
，切的节奏区间改
```
min/maxCutSeconds
```
口型/唇形同步暂不管——那是生成管线的事
分镜图不追求一次到位——它是给视频模型的构图锚，构图对、资产对就够，微调交给重生成

Report interface has built-in Chinese/English support (
```
--lang
```
, default Chinese); prompt language is controlled separately by
```
promptLang
```
(default English)
Durations are generation durations sent to the video model, not estimates — adjust segment upper limit with
```
params.maxSegmentSeconds
```
per your model, adjust cut rhythm range with
```
min/maxCutSeconds
```
Lip sync is not handled for now — that's the generation pipeline's responsibility
Storyboard frames don't need to be perfect on the first try — they are composition anchors for the video model; as long as composition and assets are correct, fine-tuning is left to regeneration

门失败会累积

Gate Failures Accumulate

validate

与

checkup

每次都把门的结果追加到当前目录的

.gates.jsonl

；跑

stats

汇总：

bash

node {baseDir}/scripts/novel-storyboard.mjs stats

回答三件事：哪道门最常响（那条规则模型最常无视，该改的是措辞）、哪道门从没响过（可能是死门，也可能规则已被内化）、失败详情长什么样（反复出现却没有门的那类问题，只能靠人看）。

不想记加

--no-log

；写不进去静默跳过，不影响校验。

validate

and

checkup

append gate results to

.gates.jsonl

in the current directory every time; run

stats

to summarize:

bash

node {baseDir}/scripts/novel-storyboard.mjs stats

It answers three questions: Which gate triggers most often (the rule the model most often ignores, wording should be adjusted), Which gate never triggers (may be a dead gate, or the rule has been internalized), What do failure details look like (problems that recur but have no gate can only be reviewed manually).

Add

--no-log

to disable logging; silent skip if writing fails, no impact on validation.

自测

Self-Test

bash

node {baseDir}/scripts/selftest.mjs

323 项断言，不调模型、不花额度。18 道质量门每一道都有击穿用例。改完脚本先跑这个。

bash

node {baseDir}/scripts/selftest.mjs

323 assertions, no model calls, no quota usage. Each of the 18 quality gates has failure test cases. Run this first after modifying the script.

自带样例

Built-in Example

{baseDir}/examples/渡口-storyboard.json

：《渡口》第 1 集完整分镜——10 段 34 切认领剧本全部 35 拍，平均 3.5 秒一切，共 119 秒 / 目标 120 秒，2 个生成批次，每段带完整的 H3 视频提示词（多图对齐 + 切点时刻全部对账通过）。当质量基准，也是自测夹具。

{baseDir}/examples/渡口-storyboard.json

: Complete storyboard for Episode 1 of Ferry Crossing — 10 segments, 34 cuts, covering all 35 beats of the script, average 3.5 seconds per cut, total 119 seconds / 120 second target, 2 generation batches, each segment with full H3 video prompts (multi-image alignment + all cut timings verified and passed). Serves as a quality benchmark and self-test fixture.