chalk-roster
火柴人與粉筆風動畫短片常因帽子顏色在中途改變、道具瞬移、或鉤子（hook）在第十二秒才出現而崩潰。chalk-roster 是一個預渲染連續性檢查閘門：一次鎖定角色與風格，撰寫時間節拍，執行檢查，然後才投入生成算力。
使用時機
- 無臉 / 火柴人 / 線稿 / 粉筆風動畫短片，且擁有重複出現的角色陣容
- 多場景解說影片，需確保相同剪影在不同鏡頭中保持可辨識性
- 系列作品，需讓風格在每集之間留下一致指紋
- 任何原本打算直接跳入逐鏡頭提示的計畫
不要將此工具用於：真人影片剪接時間調整、音樂對齊剪輯、混音拆解、真人照片動作擺拍、或聊天貼圖包——那些是其他任務。
核心概念
- 角色清單卡（已凍結）：頻道 + 風格鎖定 + 角色成員，需附上固定標記與禁止清單。
- 節拍表：依序排列的鏡頭，包含時長、出場角色、動作（禁止閒置）、道具對應表、可選的轉場記錄、配音字數與鉤子標記。
- 檢查閘門：
chalkroster.py check→ SHIP / FIX / HOLD。
判定結果
| 判定 | 意義 | 是否生成片段？ |
|---|---|---|
SHIP | 連續性乾淨 | 是 |
FIX | 軟性問題（配音密度、移動方向、禁止用詞） | 修正節拍，再重新檢查 |
HOLD | 硬性錯誤（未知角色、道具跳躍、無鉤子、風格不完整） | 不要生成 |
操作步驟
- 複製
templates/roster.json→roster.json。填寫style（畫面比例、線條粗細、頭部填充、肢體規則、背景規則、強調色上限）與cast（id、標記≥1、禁止項目）。 - 複製
templates/beats.json→beats.json。每行一個鏡頭；標記早期鉤子；列出道具持有者；在transfers中記錄每一次交接，並設transfer: true。 - 語法檢查：
python3 scripts/chalkroster.py lint roster.json beats.json - 閘門檢查：
python3 scripts/chalkroster.py check roster.json beats.json - 僅在
SHIP狀態下：將每個鏡頭展開成生成提示，對每個出現的角色逐字重複其凍結的標記。 - 若為
FIX/HOLD：修復列出的問題；絕不「近似」某個標記變更，除非有明確的轉場事件。
角色清單格式
{
"channel": {"name": "chalk-bytes", "lock_style_across_episodes": true},
"vo_lang": "en",
"style": {
"aspect_ratio": "9:16",
"line_weight": "medium",
"head_fill": "hollow",
"limb_rule": "two-arms-two-legs",
"bg_rule": "flat-black",
"max_accent_colors": 3,
"accent_colors": ["vivid red", "electric blue", "warm gold"],
"fingerprint": "hollow-head/medium-line/flat-black/3-accent"
},
"cast": [
{
"id": "guide",
"role": "narrator-avatar",
"silhouette": "tall-thin",
"markers": ["red beanie", "yellow shirt"],
"forbid": ["photoreal face", "extra arms"]
}
]
}
節拍格式
每個鏡頭需要 duration_s、action，通常還需 cast。道具以 prop → holder_id|null 的對應表表示。變更持有者或標記需要明確的轉場記錄。
配音密度範圍（字/秒）：英文 1.8–2.9，中文 3.2–5.2。鉤子必須在 hook_deadline_s（預設 5）之內發生。
範例
- 乾淨的 30 秒影集：
examples/cache-lie-roster.json+examples/cache-lie-beats.json→SHIP。 - 道具瞬移：以相同角色清單檢查
examples/broken-prop-jump-beats.json→HOLD，直到記錄轉場為止。 - 內建示範：
python3 scripts/chalkroster.py demo
小技巧
- 標記使用普通文字（如“紅色毛帽”），而非色碼或解剖學描述。
- 剪影改變 = 新的角色 id，而非悄然修改標記。
- 強調色數量 ≤
max_accent_colors；以日常用語命名。 - 系列模式：設定
channel.lock_style_across_episodes並讓style.fingerprint在各集保持一致。 - 閒置的粉筆角色會使檢查失敗——每個鏡頭都需要具體的
action。