storyboard-table

# Storyboard Table（影视级剧本拆解 · 分镜表制作） 把剧本或剧情描述按影视工业标准拆解成镜头（景别、运镜、画面、台词、音效、秒数、页数），交付可直接投入前期筹备的专业分镜表 Excel（可选铅笔线稿风分镜草图嵌表）。 ## 何时使用 - 用户给一段剧情 / 剧本，要求「拆成镜头」「做个分镜表」「剧本拆解」 - 用户给了一堆镜头要点 / 素材，要求「整理成专业分镜表」 - 用户明确要 分镜表 / 镜头表 / storyboard / 场记表 这类产出 ## 使用流程（v3 交互式，四步走） > 拿到需求后**先问再做**，一步一步确认。用户赶时间说「直接做」才跳过提问，用合理默认值。 ### Step 1 · 问项目类型（决定列结构） 问：**剧集（短剧 / 中剧 / 长剧）还是影片（电影 / 微电影 / 短片）？** | 类型 | 列结构差异 | |------|-----------| | 剧集（短剧/中剧/长剧） | 含 `ep`(**集**) + `scene`(**场**) 两列，均自动竖向合并 | | 影片（电影/微电影/短片） | 只有 `scene`(**场**) 列，无 `ep` | 两种类型都含：`daynight`(**日/夜**)、`inout`(**内/外**)、`set`(**场景**) 等氛围/场景列（见 schema 标准列）。 短剧（竖屏/快节奏）拆镜时：镜头更短（1-3 秒为主）、景别以近景/特写为主、前 3 镜必须出钩子。 ### Step 2 · 导演风格匹配（先定「怎么拍」，再画图） > 顺序铁律：**必须先确认导演参照，再生成任何分镜草图**——草图是导演视觉意图的呈现，导演没定，图不能动笔。 1. 识别用户内容：题材（古装/年代/悬疑/偶像/科幻…）、基调（冷峻/热血/唯美…）、媒介（剧/影）。 2. 读 `references/director-styles.md`（内置导演风格速查库，按地区×题材索引）， 匹配 **2-3 位候选导演**，向用户展示：每人代表作 + 一句风格速记。 3. **用户确认一位，或自定义修改**（如「朴赞郁的构图 + 奉俊昊的节奏」）。 4. 把选中风格注入拆镜参数：运镜偏好、景别节奏、镜头时长倾向、光线氛围 （例如选王家卫 → 多抽帧慢镜+局部特写+霓虹夜；选正午阳光 → 端正构图+自然光+稳重节奏）。 5. 在表格 `meta` 里记录：`"导演参照": "王家卫《花样年华》"`。 ### Step 3 · 问是否产出分镜图（按导演视觉特征画黑白手绘稿） 问：**需要生成黑白分镜草图吗？（每张约消耗 5-10 生图积分）** - **要**：对关键镜头（每场 1-2 个代表镜头，或用户指定）用 ImageGen 生成黑白草图， 把图片路径填入该镜头的 `image` 字段，脚本自动嵌入 Excel「分镜图」列。 生成前先从 Step 2 选定导演的风格里**提炼视觉关键词**（构图/机位/光线）注入 prompt。 - **不要**：省略 `image` 列。 生图 prompt 模板（v4 · 铅线稿风格 + 美术锁定版，同一批镜头套用）： ``` film storyboard panel, clean graphite pencil line drawing on white paper, thin precise outline linework, light cross-hatching for shadows only, large areas left white, {国家/时代美术锁定（如剧本非中式，必须显式写，见要点 5）}, {景别} shot: {画面内容（英文，含该国美术元素）}, in the visual style of {导演参照}: {导演视觉关键词（英文）}, {构图/机位}, {光线}, cinematic composition, storyboard conceptual art, no heavy tonal shading, no ink wash, no grey fill, monochrome line work only, no color, no text ``` 导演视觉关键词提炼方法（从 director-styles.md 的风格速记翻译）： | 导演参照 | 注入的视觉关键词示例 | |----------|---------------------| | 王家卫 | tight claustrophobic framing, rain-slicked neon reflections, oblique angles, smoke haze | | 正午阳光 | symmetrical balanced composition, natural daylight, eye-level shots | | 朴赞郁 | precise geometric framing, strong verticals, mirror symmetry, cold hard light | | 维伦纽瓦 | monumental negative space, silhouettes against vast landscape, misty atmosphere | | 杜琪峰 | wide static tableaux, low-key chiaroscuro, figures in deep shadow | 要点： 1. 固定关键词不丢：`black and white storyboard sketch / film storyboard panel / monochrome / hand-drawn / no color / no text` 2. 景别写明（extreme wide / medium close-up / over-the-shoulder 等），与表内「景别」列一致 3. **导演视觉关键词必须来自 Step 2 用户确认的导演参照**——同一项目所有草图用同一套关键词，风格才统一 4. 光线氛围翻译进去：chiaroscuro（明暗对比）、low-key（低调光）、backlit（逆光）、available light（自然光） 5. **美术方向必须单独显式锁定（雪魄项目教训）**：导演风格词只管摄影/构图/光线，**不管故事发生地的美术**。剧本若发生在韩国/日本/西方等非中式背景，必须在 prompt 里加 `Joseon-dynasty Korean setting, Korean traditional architecture and landscape, Korean traditional costume (hanbok)` 这类国家+时代+建筑+服装锁定，并把画面内的地标/服装/道具替换成对应国家元素（如 韩国剧本→镜浦湖/镜浦亭/dopo 袍/gat 笠帽/giwa 瓦顶廊桥/河回面具/韩纸），否则模型默认画成中式 6. **ImageGen 文件名撞名坑（雪魄项目教训）**：生成文件名是秒级时间戳（`..._YYYY-MM-DDTHH-MM-SS.png`），**并行调用同一秒完成会互相覆盖**（output_dir 也隔离不了）。务必单张顺序生成，每张完成后**立即重命名**为 `{镜号}.png` 再生成下一张；大批量可派后台 agent 顺序执行，但 agent 可能中途停摆，需检查实际文件数并手工补齐 7. **草图笔触固定为铅线稿风（用户 2026-08-30 确认固定，所有项目默认）**：分镜草图一律是「铅笔线稿」——clean graphite pencil line drawing / thin precise outline / light hatching / large areas left white / no heavy tonal shading / no ink wash / no grey fill。**此风格与导演参照完全解耦，换任何导演都不改笔触**。不要默认用 `rough pencil and charcoal` 或 `ink-wash monochrome`，那会变成炭笔水墨调子图。只有用户明确要求炭笔/水墨/厚涂时才切换 8. **导演风格只负责构图/光线/气氛，不负责笔触材质**：导演参照（如张艺谋《影》）只取「对称构图/大色块/戏曲化调度/雾气」这类**摄影语言**注入——即「导演影响的是怎么拍，不是用什么笔画」；**不能**把导演风格里的材质词（水墨/炭笔）带进笔触——否则画面会全部糊成灰块；线稿风格靠模板前段的 pencil line drawing 锁定，两条线互不干扰 ### Step 4 · 列配置与空列约定 - AI 自动填：集、场、日/夜、内/外、场景、镜号、景别、摄法、分镜图、页数、画面内容、秒数、台词、音效、角色出场列。 - **AI 依据剧本 + 导演参照判断填写**：`vfx`(**视效**)、`extra`(**特约**)、`mass`(**群众**)、`props`(**道具**)—— 剧本提到的直接填；没明写的按场景合理推断（如 街市→群众「路人若干」、茶馆→道具「茶壶 茶碗 八仙桌」；武打/爆炸/雨雪→视效）； 实在没有就留空，不硬编。 - **只留「备注」一列给用户手填**（`note`，AI 一律留空）。 - 列顺序（v8）：… 景别 → 摄法 → **分镜图 → 页数 → 画面内容 → 秒数** → **角色列组 → 台词** → 特约 → 群众 → 道具 → **音效 → 备注**；**视效**列在**场景**之后。 - **合计行（最后一行）**：数值列各自合计、对在自己的列下——页数列下是总页数，秒数列下是总秒数；无累计列。 - **页数（0.1 页十进制粒度，按场写）**：1 页 ≈ 1 分钟成片（对白场 1:1，动作场 ×1.5~2）。 值直接写小数：`0.1`（最细粒度，≈6 秒）、`0.2`、`0.3`…`1.2`、`1.5`、`2` 分别代表 0.1 页 / 1.2 页 / 2 页； 有剧本量页面占比，无剧本按预估秒数换算（6 秒 ≈ 0.1 页）。也兼容传统 1/8 分数写法（`"1/8"`=0.125 页），脚本都能算。 **页数只写在每场第一镜的行上，该场其余镜头行留空**——脚本会按「场」自动竖向合并单元格，一场显示一个页数值（无颜色数据条）， 合计行自然每场只计一次、不会重复累加。 - **角色每人一列（✓ 标记出场）**：JSON 顶层写 `"roles": ["陈","影"]`，行内 `"roles": ["陈"]` 标该镜出场角色； 脚本自动把每个角色展开为独立一列（位于台词之前，窄列、✓ 加粗蓝字）。 角色名用缩写：主角取姓名关键字（陈默→`陈`）；缩写对照写 `meta.角色缩写`， 如 `"角色缩写": "陈=陈默(男主) / 影=神秘人"`。空镜（无人物）不勾。 ## 两种输入工作流 ### 工作流 A：AI 自动拆镜头（输入 = 剧情 / 剧本） 1. 先走上面 Step 1-4 交互确认。 2. 读 `references/storyboard-schema.md`，掌握标准列、景别与运镜术语。 3. 按「场 → 镜头」粒度拆分：每镜至少含 景别、摄法、画面内容；有对白补台词，有声音设计补音效，按 1/8 页计法估页数。 4. 场次号用**纯数字**（`场=7`、`场=8`），一场内多镜头在镜号上编 `7A / 7B / 7C`；转场单列一行（`场=转`，`镜号=T`）。 转场行的**内/外列标方向**：前一景是内、后一景是外 → 写`内外`；前一景是外、后一景是内 → 写`外内`（例：场7外→场8内，转场行写`外内`）。 5. **场景列用「大景-具体位置」层级写法**：大景是地名/建筑（颐和园），`-` 后写该景的具体哪里（门口、长廊、正殿）， 如 `颐和园-门口`、`旧屋-里屋`；同一大景的不同位置要分别标注（玄关/里屋），方便置景与统筹按大景归组。 ### 工作流 B：整理用户提供素材（输入 = 镜头列表 / 要点） 1. 对齐到标准列（缺列补空，不臆造内容）；「备注」列同样留给用户。 2. 统一术语：把「近一点」规范成「近景」，把「镜头跟着走」规范成「跟移」等（参考 schema 术语表）。 3. 补全可推断字段，无法推断的留空并提示用户。 ## 产出：专业分镜表 Excel（.xlsx） ``` python scripts/make_storyboard.py data.json -o 分镜表.xlsx [--html] [--img-h 160] ``` - 本机可用 managed python（已含 openpyxl + Pillow），或任何装有 openpyxl 的 Python 3.9+ - 脚本会在 openpyxl 缺失时自动安装；支持 CSV 输入与 stdin（用 `-` 代替路径）。 - `--html` 同时导出可打印 HTML；`--img-h` 控制分镜图列图片高度（默认 150px）。 ### 输入数据格式（JSON，v3） ```json { "title": "《雨夜来客》顺场分镜表", "meta": { "集次": "S01E03", "编导": "佚名", "版本": "v6", "角色缩写": "陈=陈默(男主) / 影=神秘人", "导演参照": "辛爽《漫长的季节》", "页数口径": "0.1页粒度，1页≈1分钟" }, "roles": ["陈", "影"], "columns": ["ep","scene","daynight","inout","set","vfx","shot","size","camera","image","duration","action","sec","dialogue","extra","mass","props","sound","note"], "rows": [ {"ep":"3","scene":7,"daynight":"夜","inout":"外","set":"旧巷口","vfx":"","shot":"7A","size":"大远景","camera":"固定", "image":"shots/shot_7A.png","duration":0.1,"roles":[], "action":"雨夜，旧巷口，一盏路灯忽明忽暗。","sec":3.5,"dialogue":"","extra":"","mass":"","props":"","sound":"雨声、风声","note":""} ] } ``` - `columns` 用字段 key，脚本自动映射中文表头（完整映射见 schema）。 - `roles`：每个角色自动展开为独立一列（✓ 出场标记），无需写进 columns。 - `image` 值为存在的图片路径（相对/绝对均可）时自动嵌入；不存在则按普通文本写入。 - 影片类项目去掉 `ep` 列即可。 ## 表格排版规范（脚本内置，无需人工处理） 标题合并居中、表头深蓝白字、细边框、自动换行、冻结标题与表头、隔行底色、 集/场列竖向合并（浅蓝底）、景别六色配色（远蓝/全绿/中黄/近橙/特写红/黑场灰）、 日/夜氛围色、角色每人一列（✓ 加粗蓝字）、页数列分数兼容+按场合并（无数据条）、 表头筛选、A4 横版按宽缩放打印、合计行最后一行「合计 · N 个镜头」，页数/秒数各自合计对在自己列下。分镜图列按 `--img-h` 自适应行高。 ## 资源 - `references/storyboard-schema.md` — 标准列定义（v3）、景别/运镜术语、角色缩写规范、示例数据 - `references/director-styles.md` — 内置导演风格速查库（地区×题材索引，Step 2 用） - `scripts/make_storyboard.py` — JSON/CSV → 专业分镜表 .xlsx（可选 HTML、嵌分镜图）生成器 ## 交付前必须自审查漏补缺 生成最终 `.xlsx` 后、`present_files` 之前，必须主动跑一遍全面审查，不能等用户来发现： 1. **镜号连续性**：每场镜头编号 A/B/C… 无跳号、无重复。 2. **关键字段非空**：日/夜、内/外、场景、镜号、景别、摄法、秒数、画面内容、音效不得为空；备注除外。 3. **数值合计**：秒数合计、页数合计与合计行一致；页数只写每场第一镜并自动合并。 4. **角色列**：有出场人物的镜头必须至少有一个角色 ✓；纯黑场/无人物镜（如香火暖点、石壁显字、片名字卡）可留空但需确认。 5. **台词完整性**：剧本里出现的对白必须在台词列或画面内容中出现，可用程序做关键词核对。 6. **视效/道具编码**：O1-O8、R1-R7 引用有效，不得出现剧本未定义的特效码。 7. **图片文件与锚定**：所有 image 字段指向的文件真实存在；打开 `.xlsx` 检查 `len(ws._images)` 与预期一致、无错位。 8. **美术方向抽检**：对非中式背景（如韩国/日本/西方），抽样打开几张草图检查是否出现错误国别的建筑、服装、道具，发现偏了立即用更强提示词重画。 ## 注意事项 - 不臆造用户未提供的内容；特约/群众/道具/视效按剧本+导演参照合理推断填写，只有「备注」列永远留给用户手填。 - 页数按 1/8 页计法仅为估算（1页≈1分钟为经验值），正式拍摄以现场为准。 - 生图有积分成本，先告知用户再批量生成；关键镜头优先，不必每镜都生成。 - 如需更细列（角度/光线），在 `columns` 中追加即可，脚本与映射表已支持。