novel-storyboard

Storyboard the AI short dramashot—the first layer in the pipeline that faces the video model directly.The premise is ingrained: shots are generated, and the cost of one more cut is almost zero, so there is no reluctance to use more shots here; the only limit is the duration of a single segment generation by the video model (15 seconds by default).

Core mechanism: shots claim beats. Each shot declares which consecutive beats of a scene in the script it covers (sceneIndex + beats: [起, 止]), and shots may not cross scenes—a change of setting must mean a change of shot. This makes the relationship between the storyboard and the script mechanically reconcilable:

Deliverable	What it solves
Beat claiming	Each beat is claimed by exactly one shot, in order—if the script changes, rerun validate and the invalidated shots are called out on the spot
Single shot ≤ 15 seconds	The upper limit for a single AI video generation; long dialogue is forcibly split into shots here (`params.maxShotSeconds` change according to the model)
Dialogue fits	The seconds of dialogue claiming a beat ≤ the seconds of the shot—checked shot by shot, not guessed
Shot image prompt + shot body	Shot image prompt (`frame`, Chinese, directly names characters) works with the setting images for the image model to generate images; shot body (`shot`, Chinese, generic identity) writes what happens in these few seconds. Shot size is an enum, and the Chinese shot size term must be written into the shot image prompt
H3 video prompt (one per segment)	MiniMax H3's I2VA structure: fixed alignment instruction + integrated_multimodal_description + overall_soundscape + non_diegetic_music.The dialogue of the claimed beats goes verbatim into the `<d>[Chinese] …</d>` block—dialogue, soundscape, and music are all carried in one prompt
Seedance video prompt (one per segment, assembled by script)	Parallel to H3. Assembled by script according to the official structure: reference image declarations, segment-level blocking, per-shot quantified fields, dialogue `{}`, sound effects `<>`, music `（）`, numbering constraints. The model only writes the `shot`of each cut, not seconds, numbering, or image references
Composition quantified fields	Each segment `blocking`(who is on the left, who is on the right, spacing), each shot's focal length / camera position / composition / eyeline landing point / focus / stability—when no shot image is produced, these are the entire 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 summarized by script
Voice alignment sheet	Each line of dialogue is mapped to a shot number—which segment of video the TTS audio is attached to, automatically summarized by script

{baseDir} = the directory containing this file. Script {baseDir}/scripts/novel-storyboard.mjs, zero dependencies,node run directly.

Boundaries (things not done): does not write drama or change dialogue (novel-script 's job), does not produce scene/character/prop setting images (novel-art / novel-characters live-action), and does not do video generation or editing/compositing. Lip sync is out of scope for now—that is the generation pipeline's concern.

Step 0 — Define inputs and scope

script.json is a hard prerequisite—storyboards are meaningless without a script; both validate/render must be given --script. For the rest of the upstream, use them if present:

--outline / --cast: prompt name prohibition check + C01 shown as a person name in the report
--art: S01 shown as a scene name in the report + batch sheet embeds the scene setting image
--shots <卡片目录>：Optionalmount the shot-recipes shot recipe card library (pointing to shot-recipes/references/cards, only accepts a directory, not an exported JSON), enabling the 18th shot-recipe gate. If shot-recipes is not installed, do not provide it—this skill is self-contained and does not depend on it

How many episodes to cut at a time: follow the script's batches (split as far as the script is written), default one batch ≤ 3 episodes.

Decide the aspect ratio first: storyboard.json top-level aspectRatio is the formal contract jointly observed by storyboards and downstream image generation; only accepts 16:9 or 9:16. When there are no special requirements, use 16:9; for vertical short dramas explicitly write 9:16。

Step 1 — seed working draft

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

Deterministic expansion: each scene's beat list (number, action/dialogue, seconds per beat, speaker) goes into seedScenes, which is the working draft when cutting shots; at the same time write --aspect into the top-level aspectRatio, defaulting to 16:9。The seconds per beat are calculated, do not let the model re-estimate them. Leave shots empty; cutting shots is the model's job.

Step 2 — Segment and cut shots episode by episode

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

{baseDir}/references/storyboard-pass.md and {baseDir}/references/schema.md(read them and follow them)
That episode's seedScenes working draft + scene cards (art.json's anchors and lighting prompts) + character cards (cast.json's appearance key points)

Process:First segment by story unit(each segment 9–15 seconds, not crossing scenes),within a segment cut 2–5 second shots(dialogue shot-reverse-shot, insert close-ups for key actions, the three-piece entrance set—the shot-cutting grammar is all in storyboard-pass.md), for each cut write one storyboard image prompt (Chinese, address characters by name), one shot body shot(Chinese, generic identity) and six composition fields; for each segment write blocking、soundscape, and if there is music also write music. All storyboard images and downstream generated images must maintain the same aspect ratio specified by the top-level aspectRatio .

Each segment's shot body follows {baseDir}/references/shot-writing.md when writing(protocol-agnostic: one camera move per shot, actions must be completable, dialogue verbatim, layered audio, no art style). Whichever video service it is sent to, then apply that protocol's syntax: for MiniMax H3 see {baseDir}/references/h3-prompt.md, for Seedance see {baseDir}/references/seedance-prompt.md。

Write one per segment h3Prompt, following {baseDir}/references/h3-prompt.md (an internalized version of the official methodology,not dependent on any external skill). The official convention defaults to English (promptLang can switch to Chinese),each shot on its own line. Key points: the first line aligns the instruction and [Shot k] cut point timesderived from the storyboard seconds, not a single character may drift(validate reconciles verbatim); claimed dialogueverbatiminto <d>[Chinese] …</d>; write each cut's camera movement terms on their own line; put the soundscape and music into the latter two fields —the soundscape is also an action instruction; when the visuals change, the soundscape changes with them。

Seedance prompts don't need to be written：render the report's prompt panel and the export --protocol seedance are both assembled on the fly from the fields above. The visual style is appended by the caller at submission time, and global constraints are given via --constraints <文件> .

After cutting, delete seedScenes .

Step 3 — Validation ⛔ must not be skipped

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

The 18 quality gates are all code: full beat coverage (at the storyboard level, exactly once, in order, continuous), segment 0 < total seconds ≤ 15,each cut 2–5 seconds, dialogue fits into the storyboard shots, each episode's total duration within ±15% of the script target, ≤ 3 people in the same frame (if exceeded, a breakdown explanation is required), segment numbers in E01-01 format consecutively numbered, Chinese shot-size terms present in the storyboard image prompts, camera movement uses the H3 vocabulary and is in its own [Shot k] paragraph,H3 alignment instructions derived from the storyboard structure checked word by word + cut timing checked one by one、claimed dialogue goes word by word into the <d> block、prompt language matches promptLang(checked both ways: Chinese written as English and English mixed into Chinese are both blocked), storyboard image prompt Chinese is non-empty,video prompts contain no character names(the H3 body is not language-specific; Seedance shot bodies are all checked; storyboard image prompts may name them directly and are allowed through),composition quantification fields are complete、Seedance shot body is compliant(Chinese is non-empty, and no time, shot numbers, image references, or protocol symbols are written), scenes/characters/props are reconciled against the script,shot recipes are reconciled(optional gate, see below).

The structural check also validates the optional aspectRatio: only accepts 16:9 or 9:16. It belongs to the storyboard.json contract check and does not count as an additional quality gate.

Fix each violation one by one, rerun after fixing, until it passes.

The 18th shot-recipe(optionally mounted): only checked if --shots is provided; if not provided, explicitly state it is skipped. On a cut you can write an optional recipe(recipe card id,cut level not segment level，multi-panel recipes are expressed by consecutive shots with the same id, not an array), and the gate checks three things — the id is in the card library, each of the card's must_phrases appears in that cut's frame (after lowercasing both sides includes), and when the card's cuts lower bound ≥ 2, the number of consecutive shots with the same id must not be below that lower bound. The card'ssuggested shot size and camera movement have no gate, and only flag deviations in the report's "Recipe" column and at the end of checkup : a recipe is vocabulary, not law; once something optional becomes strict, no one will mount it.

Step 4 — Output and reporting

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

The report interface language is specified by --lang zh|en (priority --lang > JSON top-level lang field > default Chinese) — it only switches interface labels and is independent of promptLang(H3 prompt language). The main storyboard image and sub-storyboard strip are laid out according to the top-level aspectRatio ; the old data's _meta.orientation and the frame-end aspect ratio label are only for compatibility. Userender to find the storyboard image via --frames <目录> (<目录>/<段号>/f<切序>.png, default current directory), and use --images <目录> to find the batch sheet's scene setting images (<目录>/<场景 slug>-sheet.png, default ./images), both can point to any path—this skill does not produce these files, and after the downstream finishes generating images, rerunning render once will embed them into the report.export --frames <目录> will copy the storyboard images it can find into the production package, so you don't have to manually put them in the package. The report includes: KPI band, storyboard rhythm band (thick separators = segment boundaries, strip width = proportion of storyboard duration, color depth = shot size distance, click to jump to segment card), per-episode storyboard table (main storyboard image + sub-storyboard strip + per-cut storyboard rows + storyboard image/H3 prompt copy buttons), generation batch sheet, voice alignment sheet, quality gates, export JSON. The Markdown version includes the complete H3 prompt for each segment, ready to copy and use directly.

Say it clearly in one reporting sentence: how many episodes and shots, total duration vs target, how many generation batches, report path; state plainly any gates that did not pass.

Do not say "images have been generated"—this step no longer exists; what is delivered is the prompts and the image attachment list.

Final delivery:

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

The relay of five skills (the pipeline closes the loop here)

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

Storyboarding is the consumer side: seed consumes script.json, storyboard image generation (downstream) consumes the setting images from art and characters as references, H3 prompts are sent directly to the video model as orders, and the voice alignment sheet connects to the TTS output of the script dialogue script. The reports for each of the five JSON files all have export buttons, and after editing they can all be fed back into their respective render/validate.

Boundaries

The report interface has built-in Chinese and English (--lang, default Chinese); the prompt language is controlled separately by promptLang (default English)
The seconds arethe generation duration given to the video model, not an estimate—change the segment upper limit according to your model params.maxSegmentSeconds, and change the cut rhythm interval min/maxCutSeconds
Lip sync/mouth shape sync is not handled for now—that is the generation pipeline's concern
Storyboard images do not aim to be perfect in one pass—they are composition anchors for the video model; it is enough if the composition is right and the assets are right, and fine-tuning is left to regeneration

Gate failures accumulate

validate and checkup each time append the gate results tothe current directory's .gates.jsonl; run stats to summarize:

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

Answer three things:which gate rings most often(the rule the model most often ignores; what should be changed is the wording),which gate has never rung(it may be a dead gate, or the rule may have been internalized),what the failure details look like(for the kind of problem that keeps recurring but has no gate, only human review can help).

If you don't want to remember, add --no-log; if it cannot be written, it is silently skipped and does not affect validation.

Self-test

node {baseDir}/scripts/selftest.mjs

336 assertions, no model calls, no quota spent. Each of the 18 quality gates has a breaking test case. Run this first after modifying scripts.

Built-in sample

{baseDir}/examples/渡口-storyboard.json: the complete storyboard for Episode 1 of "The Ferry Crossing"—10 segments and 34 cuts claim all 35 beats of the script, averaging 3.5 seconds per cut, totaling 119 seconds / target 120 seconds, 2 generation batches, with each segment carrying a complete H3 video prompt (multi-image alignment + cut point timestamps all reconciled and passed). It serves as a quality benchmark and also as a self-test fixture.

novel-storyboard

About this skill