Turn the script and visual facts into shots with shot duties, spatial continuity, and freezable starting points 剧集/<EP>/分镜.md.
Each shot uses a second-level heading ## SHOT-..., and under the same shot use ### 冻结关键帧提示词 to write the starting-frame body text;
when needed, add ### 收尾关键帧提示词 to write the ending body text.
Quick Start
用 $short-drama-storyboard 完成 EP001 的正式分镜和每镜冻结关键帧
Entry
The current script plus the necessary visual facts is enough to enter directly. Asset image prompts and the storyboard are sibling branches and do not wait on each other. Only when a key scene truly has multiple viable directing options should options be compared in the context; for ordinary scenes, design directly.
Creator-readable explanations follow the project language; the copyable body text of frozen keyframes follows
short-drama.json#/format/prompt_language. When there is no short-drama.json , the body text uses enby default.
Before allocating shot durations, read
short-drama.json#/creator_authority/production_profile/choices/native_duration_seconds. If a target model is declared but
there is no native duration, fill in this one choice first; if no target model is declared either, design by narrative rhythm as usual and do not guess vendor limits.
When also reading short-drama.json#/creator_authority/rhythm_profile:status as accepted , shot length follows
Where shot length comes from derived from sound events and target_avg_shot_seconds ,
the proportion of close-up-type shots in the whole series is no less than close_shot_share_min; when the profile is missing or not accepted, do not check these values.
Before the frozen keyframes are finished, who will appear in this frame has not yet been decided. So all three bases are backfilled after the keyframes, reading the finished image, not the shot intent.
The user not manually naming reference images does not mean choosing text-to-video. After freezing the keyframes, first judge the consistency needs based on the characters, locations, key props, and starting composition visible in this shot, then check the real images already in the project. Only images that are currently readable and whose content and purpose can be verified can be automatically bound; when a filename looks like a certain character but the content has not been verified, it is still treated as not ready.
When there is not a single one in the project, the creator has three paths; state all three clearly at once and then let him choose, do not give only "generate a reference image first" and
"switch to text-to-video": put the images already at hand into the project and bind them as REF-...; generate images in your own tools, and for this round first use
PLAN-... to write out the image-attachment plan; or explicitly switch to text-to-video. Using this suite's production skill to generate images is only one way to do the first path,
and requires an out-of-project adapter and credentials; it is not the only entry point.
Before starting the storyboard, read the current content of 剧集/<EP>/剧本.md . When the creator says "the script has been confirmed for adoption", that refers to that file,
not an earlier draft in the conversation; when the two are inconsistent, the file prevails, and state the difference.
Workflow
-
Read the accepted target model's native duration range, then confirm which shots carry each scene's action, dialogue, sound, on-screen text, and turning point.
-
Determine when the audience knows what, who to align with, how space reveals it, and which visible action the turn lands on. When the script or Brief uses relative time such as "first half / second half / first third / last N seconds" to define when something first appears, is released, or is prohibited, first convert it into explicit time boundaries using the accepted episode length before storyboarding; for example, a "first appearance in the second half" of a 60-second piece must not be earlier than 30 seconds.
-
For each shot, write clearly its sole responsibility, source, duration, shot size/camera position, camera movement, starting point, sole main action, ending point, and sound; use
起点 → 唯一动作 → 终点to directly explain how the characters, both hands, and held objects complete the state transition of this shot. Leave the three bases for step 6. For "camera movement", choose shot by shot according to the purpose of this shot, write the behavior and rationale; for a static shot also write the rationale, see choose camera movement shot by shot. When there is dialogue, VO, or OS, first estimate the full vocalization time according to the original text and the character's way of speaking, then arrange actions, pauses, and end reactions that must not overlap; write the basis for the timing estimate in brief in this shot's "sound". For specific methods, see dialogue timing estimate. For dialogue scenes, first follow default dialogue coverage to place cut points; shot length is not converted according to script word count. -
Lock the characters' orientation, position, line of sight, held objects, entrances and exits, screen direction, and necessary states; when there is already an upstream continuous relationship that constrains the action space, project the relationship into this shot's starting point and ending point.
-
A frozen keyframe projects only the shot's starting point; delete text, actions, poses, or prop states that appear only at the ending point. When the shot's responsibility lands on the final beat, separately write
### 收尾关键帧提示词projectionending point—the other end of the same frame, with completely symmetric rules: delete what exists only at the starting point and is no longer present at the ending point. It is optional; for how to write it and trade-offs, see pairing start and end。 -
After the keyframe is finalized, first read from the finalized text the characters, locations, and props in this frame that need to maintain identity, styling, or geography, then use the same list to fill all three bases at once:
- visual basis: write each item in the list as an entry reference to 《视觉设定.md》; this is a required field;
- image prompt item: if the list already has a suitable
IMG-...entry, write it in; if not, leave "none"; - input reference image: according to the list, search for matching images in the user-provided input,
剧集/<EP>/制作成果/and other visible media already pointed to by the document; if matched, write intoREF-.... If none are matched, write "none (reference images to be supplemented: <this shot's missing starting frame, characters, locations, props>)"; if only some are matched, after the existingREF-...append "; reference images to be supplemented: <still missing images>", using only、between gaps. When the creator says the images will be prepared by themselves elsewhere, write this list asPLAN-...slots, and this shot is then ready; only when the creator explicitly says no images are to be used, write "none (creator has explicitly chosen text-to-video)".
The three bases read the same frame, so they must not contradict each other: characters or props named in the keyframe must appear in the visual basis.
-
An entire-episode request completes the entire episode, and at the end reports once on coverage, pacing, and genuinely undecided choices.
shot requirements
-
Each shot has a unique responsibility, a clear source, visible start and end states, and a reasonable duration. "Source" begins with a scene ID that actually exists in "Script.md"; after the ID, a necessary short quotation may follow; for shots spanning scenes, use
、to write multiple entries;creator_markdown_check.pywill verify that every ID resolves. -
The "Source" short quotation should correspond to the action or sound this shot carries. When the main text mentions an off-screen character, you may write in the visual basis
;画外:<类别>「<名称>」; this only declares that they are not in frame and cannot replace the fulfillment of a necessary action. Actions that need to be seen should be carried by another shot, or an explanation should be given for why they are omitted. -
Every scene in the script must be carried by shots. If you truly decide not to shoot a certain scene, write a line at the beginning of the main text of "Storyboard.md"
- 未拍场次:<场景 ID>(理由:……), and connect multiple items with;. SHT-01 always allows omission with a reason, but omissions and missed shots look exactly the same in the final document, so the reason must be written down rather than left in conversation. -
When a native duration has been declared, each shot still has its own unique responsibility, start and end boundaries, and frozen keyframes as usual, and the shot length is first determined by narrative need. For shots shorter than the minimum seconds, propose to the creator to put several adjacent shots from the same scene into a multi-shot container and declare it in the delivery file; when the target dialect requires it, every cut of the container must have an accepted keyframe image, and whether and how it can be packed is determined by the dialect of
$short-drama-video-prompts. When the creator has not declared a multi-shot container, or the dialect does not support it, the shot falls within the minimum seconds and holds the endpoint after the action completes. Actions longer than the upper limit are split into shots at visible state closure points, and each resulting shot still has its own unique responsibility and credible boundary. -
"Unique action" writes the visible state chain from this shot's starting point to its endpoint; when handoffs, changes of hand, placement, or retrieval are involved, write the contact person, contact method, and object landing point in the same chain, and do not let legal endpoints be connected by off-screen teleportation.
-
A cut must bring a change in information, power, emotion, space, or rhythm; delete synonymous repeated shots.
-
Relative time words constrain the moment an event is first visible or audible, and it is not released early just because a preceding action has already completed; the storyboard timeline directly writes that boundary, and does not treat narrative order such as "later" or "after the handoff" as a substitute for numerical time.
-
The same action does not repeat across shots, and at the peak, any declaredimpact repetitionis excepted; the endpoint should be able to become the next shot's credible starting point.
-
The readability of key information takes priority over decorative camera movement, and vertical-screen composition prioritizes keeping the subject and reactions visible.
-
For complex group scenes, first lock the spatial anchor and screen direction, then decide on changes in shot size.
-
In addition to each person's posture, the start and end boundaries must also clearly state the body-object-space relationships this shot depends on. When the relationship does not change within the shot, both ends retain it; when it truly needs to change, the process and endpoint must have script basis.
-
Frozen keyframes only write what can be seen at that instant; text, fingers, reflections, and occlusions must be generatable.
-
When close-up keyframes are generated with a location board attached, the image is often stretched into a medium-long shot; write the specific framing in the main text (where the frame cuts, where the face is in the frame, camera distance), and if the generated image is still too wide, do not attach the location board for this shot and write the background into the main text.
-
The keyframes of an episode must look like they belong to the same film: each body text must use the same phrasing for art style (if it's realistic, say realistic; don't mix in terms like "manga drama" or "illustration" that would pull some images toward an illustration-style face), and each scene must use the same phrasing for light and color temperature; when generating, first produce one medium-to-long shot of that scene as the tone-setting image and accept it, then use it as the last reference for the remaining shots, taking only the color tone, lighting, and texture, not the composition.
-
The continuity locks in "Visual Settings.md" must be written verbatim into the body text of the frozen keyframes on the shots where they take effect; a lock face must not be omitted on the grounds that "the reference image will convey it."
-
If an inspection finds an omission, fix the document directly; do not generate a coverage table to prove you checked. The "visual basis" in a shot block is that shot's basis field, not the coverage table referred to here.
Visual basis and images
IMG-...is theprompt entry IDin "Image Prompts.md", and does not mean the image has been generated, provided, or is usable.- When "Image Prompts.md" already exists and this shot needs an entry from it, write "Image prompt item": the ID must match a visible second-level heading in that document, and also write the Chinese name and the identity, styling, geography, composition, or other boundaries it controls. The ID is only used for lookup; do not let the English slug carry meaning.
- When there is no "Image Prompts.md" or no suitable entry, write "Image prompt item: none", then in Chinese point to the character, location, or prop item in "Visual Settings.md" and its control scope. This is a normal direct entry point; do not fabricate an ID just to continue storyboarding, and do not invent another stage.
- "Visual basis" is a field that must be written for every shot: after the frozen keyframes are finalized, cross-check against the actual image; visible characters, locations, and props that need to maintain identity, styling, or geographymustbe written item by item as
《视觉设定.md》·<人物|造型|地点|道具>「<名称>」(控制:<范围>), with multiple items connected by;, and the names must be found as identical headings in "Visual Settings.md". Small-scale or background characters are still in scope as long as their identity needs to be recognized; off-screen voices and unrecognizable partial areas do not count; when this shot truly has no such items, write "Visual basis: none". - When the body text of a keyframe contains the name of an item, but it truly is not in the frame for this shot (the owner has already left, the name appears only in on-screen text, or it is homographic with some word),
append at the end of "visual basis"
;画外:<类别>「<名称>」. This is an accurate record, not writing an absent person as present. - When the name of an item is simply unreliable in the body text (
道具「手机」will collide with "phone store",人物「小雨」will collide with "it's drizzling"), write画面代称:无for that item in "Visual Settings.md", and mechanical checking will no longer look for it by name; whether this shot actually depicts it is still answered truthfully by "visual basis". - All three bases describe the same frame of the image, not this shot's asset roster. Under "control", write only the scope this frame can bear: a close-up of the back of a hand does not say "this episode's styling", and a shot showing only a screen and one finger does not say "physique". A binding from the previous shot does not carry over to the next shot just because "the character is still in this scene".
- Characters, locations, or props named in the body text of a keyframe (the item names in "Visual Settings.md" or the "on-screen aliases" it declares) must appear in this shot's "visual basis";
creator_markdown_check.pywill mechanically check this item. It only catcheswhat is namedthat category: when the body text only describes without naming ("a boy in a hooded jacket"), the machine says nothing, and who is in the image still has to be read out by this step itself; you cannot wait for an error report. - Visible objects that must remain consistent in this shot but do not yet have an entry in 《视觉设定.md》 (especially common for props appearing across shots) cannot be treated as not needing consistency just because "they can't be written into the visual basis". A pen and a coat that appear in all four shots are the same kind of problem. Do two things: pin it down in the main text with exactly the same description in every shot, and name it in the report at the end of this round, recommending
$short-drama-assetsadd an entry. Do not add 《视觉设定.md》 entries on your own, and do not stuff it into "visual basis" to pass it off as an existing entry. - "Input reference image" is a separate, distinct axis: an actual image already provided by the creator, or confirmed as produced and currently readable, referenced with a stable
IMG-...slot different fromREF-.... Each slot must simultaneously give the explicit order, the project-relative path separated only by/, the Chinese name, "purpose", "controls", and "must not control" scope; when there is none, you must distinguish between "reference image pending" and "creator has explicitly chosen text-to-video"; when only part is ready, keep the existingREF-...and append "; reference image pending: ...". Do not write prompt entries, images not yet generated, or descriptions from the conversation asREF-...——REF-...means "the file is currently in the project". Images that the creator will mount themselves at generation time go under thePLAN-...below: it likewise does not claim the file exists, it just makes clear which images to mount for this shot. - Each
REF-...must follow the single format verbatim:REF-<slot>(顺序:<n>)· <项目相对路径>《<中文名称>》(用途:<用途>;控制:<范围>;不得控制:<范围>). Note the full-width colon after "order:" and the middle dot·before the path; do not use/in place of the field separator. For multiple images, connect them only with the Chinese semicolon;, and when some images are missing, append;待补参考图:<缺口>after the last complete slot, separating the gaps with、. After writing, read it back once against this format before delivering. 用途can only be one of身份、造型状态、地理、构图、尺度、效果、起始帧、结束帧、风格; for what each one can control, see$short-drama《参考角色》. For this shot's starting frame image write用途:起始帧, for character images write用途:身份or造型状态, for scene images write用途:地理, and for prop state images write according to the one item it determines. If one image serves two purposes, split it into two slots; a shot has at most one起始帧and one结束帧, and when writing结束帧there must also be起始帧. Downstream video prompts rely on用途to make clear "which storyboard starting frame this shot sends, and which character/prop/scene images", so a slot missing用途does not count as ready.- When this shot does not yet have a starting frame image, there are two paths. The creator produces it with this kit:
用途:起始帧that one is generated by$short-drama-produceusing this shot's frozen keyframe main text, with the job'ssourcewritten as剧集/<EP>/分镜.md、source_entrywritten as this shot'sSHOT-..., the output lands in剧集/<EP>/制作成果/images/, and after obtaining the real file, bind it asREF-.... The creator produces it in their own tool: copy the frozen keyframe main text over to generate the image, then put the file into the project and bind it asREF-..., or write it in this round asPLAN-SHOT-START(顺序:<n>)· <本镜 SHOT-...>《本镜冻结关键帧》(用途:起始帧;……). If neither path is taken, it still remains only an item under "reference image pending". - When the creator generates images outside the project and the images do not enter the project, use the
PLAN-...slot: the syntax is verbatim identical toREF-..., only replacing the project-relative path withIMG-...orSHOT-...entry ID,IMG-...The Chinese name must be consistent with the title of "图片提示词.md". It states that "this image was mounted by the creator in this order during generation"; it does not claim that a file exists in the project, so it is not "to be added", nor can it be used for production. Once the real file enters the project, rewrite it asREF-.... The two types of slots can be mixed,顺序uniformly and consecutively numbered. - Automatic binding does not mean cramming all images into one shot. Select only the images that are visible in this shot and whose identity, styling, geography, key prop state, or initial composition truly need to be stabilized; for each image, write clearly its purpose, what it can control, and what it must not control.
- The two axes can be combined independently: when there is a valid image prompt item, the input reference image can still be "to be added" or a text-to-video option explicitly chosen by the creator; when the creator provides a real reference image, the image prompt item can also be "none".
On-demand knowledge
By default, read only this SKILL, the current script, and the necessary visual facts. When encountering the corresponding issue, open only one:
- Stage boundaries and rule grading:Stage contract
- Shot responsibilities, reasons for cutting, shot length derivation, dialogue coverage, and boundaries:Shot craft
- The shot grammar needed for actual production:Production shot grammar
- Comparison of directing options for key scenes:Scene visual plan
- Check whether all the original text is carried by visuals:Coverage Audition
- Multiple people, groups, and complex spatial staging:Staging manual
- Who is illuminated, and how to write it so it can be executed:Design of light
- Frozen moment, center of attention, and readability:Keyframe craft
- Shared art style vocabulary for comic drama/2D comic forms:Comic drama keyframe word list
- A complete example from script facts to keyframes:Script to keyframes
- Shot splitting, shot merging, and stable shot IDs:Shot revision identity
- Continuity check before completion:Review and examples
Revision
Keep unaffected shot IDs. When splitting shots, merging shots, or changing shot responsibilities, explain which downstream video prompts need to be refreshed, but do not automatically rewrite files the user did not name.
Completion
Every part of the original text within the named scope has been realized in shots, each shot's responsibility is not duplicated, space and state are continuous, the start and end boundaries are producible, and the keyframes can be frozen.
Each shot's "source" resolves to a real scene in "剧本.md", every scene in the script is carried by shots or has been recorded in "unshot scenes",
and the visible characters, locations, and props in each shot's keyframes are all in this shot's "visual basis"; that is completion. Visible objects needed by the visuals but not yet having entries in "视觉设定.md"
should be named one by one in the report at the end. When this request modifies both
"图片提示词.md" and "分镜.md", refresh the references of affected shots in that round; do not create a separate override table.
Video prompts, production, and review start only when the user names them.
After the five creation documents are complete, you may switch to $short-drama to perform a mechanical check of the cross-document structure; content quality is still reviewed by the creator.
Installation and maintenance
Run only during installation, upgrade, or troubleshooting python3 scripts/selftest.py。