AI 紀錄片製作

第一次使用：先過環境關

圖片：預設使用者使用 GPT 出圖，AI 不呼叫圖片 API；啟用 image_mode=agent 時需明確批准。
環境：Python 3.10+、ffmpeg、ffprobe；contact_sheet.py 另需 Pillow；無 PyYAML 依賴。
H3：若尚未配置 MiniMax H3，請先參閱 references/00_setup.md：
- 開放平台註冊/實名/充值；
- 建立 API Key；
- 設定 MINIMAX_API_KEY 環境變數或金鑰檔案；
- 確認 base_url / 模型名稱 / 解析度對齊；
- 先執行一條 4 秒測試，再進行批次作業。
金鑰不寫入程式碼、不寫入日誌、不寫入 git。
若 H3 無法使用，就替換提供者或先製作 animatic，不要假裝可以生成。
未配置 H3，不進入 G5。

何時使用

使用者要製作 人物/主題短片，時長由 brief 決定；
30 秒、1 分鐘、3 分鐘都只是示例，非硬性範圍；
有真實人物、歷史資料、AI 情景再現；
需要從零走到可交付成片；
需要控制成本、保留來源、編寫 credits。

不適用

多人物的群像、採訪型長片；
商業廣告、純產品片；
純動畫、純虛擬製作；
需要真實拍攝的現場紀錄片。

時長不設硬性門檻；超長專案需要另加素材管理，但流程不變。

開工前必須問

成片時長、畫幅、幀率、語言、平台；
人物是誰、講哪一段、哪些事實不能錯；
預算上限、是否允許重試；
圖片由誰出（image_mode=human/agent）、影片使用什麼模型、剪輯使用什麼軟體；
旁白是真人還是 TTS；音樂是否單獨一軌；
是否有歷史照片/音樂授權；是否需要 AI 聲明；
交付格式與截止時間；
profile：short（約 15–60 秒）/ standard（約 2–5 分鐘）/ custom（依需求）；
model_routing：hybrid / gpt_only / codex_deepseek；
H3 是否已配置（Key/base_url/model/額度）；若未配置，先教學配置；
片頭卡：none / static；幾秒；是否計入目標時長；標題文字在 G2.5 才決定。

沒有 brief，不進入研究。

時長與 profile

時長由 project.yaml 的 duration_target_sec 決定，非寫死。

profile	示例時長	鏡頭數（示例）	段落（示例）	音樂（示例）
short	15–60s	8–18	1–2	1 段
standard	2–5min	24–60	3–5	3–5 段
custom	使用者決定	使用者決定	使用者決定	使用者決定

這些是估算，不是門禁；30 秒和 3 分鐘只是兩個常見例子。

G4 出圖交接

提示詞完成後，先提醒使用者出圖，再做並行工作：

發送 image_batch_request.md：鏡號、檔名、提示詞位置、數量、優先級；若啟用片頭卡，0-1_card.png 放進第一批；
明確地說：「現在可以開始生成圖片」；
使用者開始後，agent 做不依賴圖片/影片的工作：字幕、cue sheet、成本表、來源/credits、剪輯骨架、下一批 prompt QA；
不審圖、不生成影片、不做最終合成；
使用者回圖後，先審圖，不重新討論已鎖定的旁白/鏡頭；
片頭卡是靜態卡，不做 H3；文字逐字驗收，中文不穩定時改為後期疊字。

不要默默做別的事情讓使用者等待；出圖任務必須先交出去。詳見 references/13_parallel_work.md。

模型路由

預設 hybrid：

階段	模型	做什麼
G0–G3	Codex + DeepSeek	brief、研究、旁白、分鏡、提示詞
G4	GPT	出圖/審圖；`image_mode` 決定由誰出圖
G5–G8	Codex + DeepSeek	任務、成本、剪輯檔案、QC；看圖時臨時切換為 GPT

文字和檔案使用 DeepSeek，像素和視覺使用 GPT；
image_mode=human：使用者透過 GPT 出圖；image_mode=agent：Codex + 影像工具出圖（需明確批准）；
切換前撰寫 image_handoff.md，專案檔案是交接憑證；
詳見 references/10_model_routing.md。

9 個階段與 G0–G8 門禁

階段	產出	門禁
G0 Brief	`project_brief.md`	時長、預算、權利、平台鎖定
研究/史實核查	`fact_check.csv`、`research.md`	G1 事實鎖定
腳本/旁白	`script.md`、`vo.csv`、`vo_text_review.md`、`voice_audition.md`、`vo_lock.md`、`vo_review.md`	G2 旁白鎖定（文案 + 音色 + 版本）
分鏡/時間線	`beats.csv`、`shots.csv`、`segments.csv`、`timeline.csv`、`animatic.mp4`、`v0_review.md`	G3 節拍認領 + 鏡頭表 + v0 確認
首幀（依 image_mode）	`首幀/`、`image_review.md`、`image_handoff.md`、`image_batch_request.md`	G4 首幀鎖定
影片生成	`h3_package/`、`clips/`、`tasks.json`、`cost.csv`	G5 影片鎖定
粗剪/字幕	`cut/`、`subtitles.srt`	G6 畫面鎖定
配樂/音效	`music/`、`cue_sheet.csv`	G7 聲音鎖定
終檢/交付	`final.mp4`、`final_qc.md`、`credits.md`	G8 交付

規則：上一關沒過，不進入下一關，不花錢。

片頭卡

只在 G0 詢問「要不要、幾秒、是否計入目標時長」；標題文字在 G2.5 才決定。

G0：opening_card: none|static；opening_seconds；opening_in_target；
G2.5：主標題/副標題/字體風格；opening_card.md 逐字確認；
G3：作為 0-1 靜態鏡頭寫入 shots.csv（static=yes，無旁白），segments.csv 寫一行 CARD（static=yes）；
G4：放進第一批出圖，檔名 首幀/0-1_card.png；文字和圖片一起出時逐字驗收；
G5：不做 H3；export_h3.py 跳過 static=yes，H3 任務表不排它；
G6：在剪輯中靜態保持；可做 1–2% 緩慢推近；
片頭卡時長從目標時長中扣除，或明確加至總長度，G0 就決定。

片頭卡是「立項時的時長決策」，不是「出圖時的裝飾選項」。

旁白審核順序

文案評審：將 vo.csv 全文、時間碼、事實備註給使用者看；使用者確認後再做聲音；
音色試聽：同一句生成 2–3 個候選，使用者選擇 A/B/C 或自己錄製；
整條 scratch：依照選定音色生成完整旁白；
v0 animatic：才做靜幀 + 旁白；
任何一步沒確認，不進入下一步。

旁白先行

這是本技能的核心順序：

先定旁白，再定鏡頭、首幀、影片；
一句旁白配 2–3 個畫面是常態；
一鏡一句是特殊情況（短促反應、口號、單鏡蒙太奇），非預設；
旁白獨立成 vo.csv，不要按鏡頭切碎；
不要按鏡頭生成 TTS；按照句子/段落生成，整段放一條音軌；
每句一個資訊；每 1–2 句至少一個硬資訊（年份/人名/數字/動作/因果）；
詩性意象必須有具體錨點、一條鏈、能夠落地；「大門/種子」可以是 motif，不是自動錯誤；無錨點的口號才是空詞；先講清因果，再談詩意；
寫完先執行 narration_lint.py，再讀一遍定稿；
剪輯時使用 J-cut/L-cut：畫面切，旁白不斷；
句與句之間留 0.3–1.0 秒氣口；5 秒旁白不要硬貼 5 秒畫面；氣口最好由一個無旁白的短鏡頭承載，不要塞在有旁白的鏡頭內部；
氣口只放在旁白句與句之間；切點要落在氣口裡，不能落在有旁白的句子內部；
旁白鎖定後不直接修改舊版；先執行 vo_diff.py，只修改受影響的檔案；
一段旁白可以跨多個鏡頭；普通鏡頭最多一段旁白；long_take=yes 的長鏡頭可以包含多段旁白，但每段必須完整在鏡頭內；
相鄰旁白的氣口視窗必須包含至少一個鏡頭切點；句子起止可以落在鏡頭內部，不要求與切點齊平；有區間時氣口取大；
排完 shots.csv / timeline.csv 後先輸出 v0 animatic（靜幀/黑幀 + 旁白），明確提醒使用者聽句間氣口；確認後再輸首幀/影片；
先給文案看，再定音色，再做 v0：沒有使用者對文案和音色的確認，不生成 TTS/animatic。

先有旁白，再有畫面；不是先有 40 個鏡頭，再往每鏡裡塞一句話。

檔案契約

`shots.csv`

id,story_segment,scene_id,duration,shot_size,camera,scene,action,expression,vo_ids,anchor,first_frame,video,status,cost,notes,long_take,static

story_segment 是敘事段號，不是 H3 生成段；生成段在 segments.csv 的 generation_id；
scene_id 是場景編號，必須和 segments.csv 對得上；
duration 以秒為單位，支援小數；
status 只用 todo/image_ready/video_running/video_ok/conditional/retake/final；
vo_ids 可為空；普通鏡頭最多一個 vo_id；long_take=yes 的長鏡頭可以寫 V01|V02；
long_take=yes：一個連續長鏡頭，允許 2 段以上旁白，但每段必須完整在鏡頭內；
static=yes：靜態片頭/插入卡，不做 H3；必須有 first_frame，segments.csv 使用 static=yes 段；
這是畫面真相來源；旁白在 vo.csv，兩者透過 vo_ids 關聯。

`vo.csv`

vo_id,start,end,text,shot_ids,notes
V01,0.0,4.2,"一句完整旁白","1-1|1-2","4.2s；句後0.8s氣口"
V02,5.0,6.2,"下一句","1-3","1.2s；句尾0.8s"

start/end 是絕對秒數；
一句旁白可以跨 2–3 個鏡頭；
一鏡一句僅在特殊情況下使用；
句與句之間留 0.3–1.0 秒氣口；
一個 shot_id 只能屬於一個 cue；一個 cue 可以覆蓋多個 shot；
字幕從 vo.csv 生成，不跟鏡頭綁定。

`beats.csv`

beat_id,story_segment,kind,shot_id,vo_id,text,notes
B01,1,action,1-1,V01,櫃台後算題,
B02,1,action,2-1,V02,把論文裝進信封,

節拍是故事最小單位，不是音樂節拍；
每個節拍恰好被一個 shot_id 認領；
每個非 static 鏡頭至少一個節拍；static=yes 的片頭卡可以沒有 beat；每段旁白至少一個節拍；
一個旁白可以跨多個節拍，在每行重複同一個 vo_id；
節拍順序必須跟鏡頭順序一致；漏拍、重複、亂序由 validate.py 攔截。

`segments.csv`

generation_id,scene_id,cut_order,shot_id,start,end,duration,keyframe,static,notes
S01,1,1,1-1,0,5,5,首幀/1-1_first.png,no,單切段
S02,1,1,1-2,5,9,4,首幀/1-2_first.png,no,段內第 1 切
S02,1,2,1-3,9,15,6,首幀/1-3_first.png,no,段內第 2 切

generation_id = 一次 H3 生成；一段 ≤15 秒，不跨場；
scene_id 必須等於 shots.csv 同鏡的 scene_id；換場必須換段；
cut_order = 段內第幾切，從 1 連續；
keyframe = 這一一切的構圖錨圖；第 1 切釘在 0.00 秒，後續釘在切點；
static=yes = 靜態卡，不進入 H3；必須單一切；export_h3.py 會跳過；
每個 shot 只能出現在一個 generation 裡；
每一刀的 start/end/duration 必須等於 shots.csv 的累計起止；全片必須無斷檔、無重疊；
validate.py 攔截越界、錯位、斷檔、重複。

`h3_prompts.csv`

shot_id,prompt,soundscape,notes
1-1,"保持首幀；筆尖緩慢移動，燈焰輕晃。","紙筆聲、遠處風聲。",

export_h3.py 按 segments.csv 分組，把每個切的 prompt 拼成一段多圖對齊提示詞；
輸出 h3_package/<generation_id>/prompt.md + manifest.json；
不呼叫 API；生成仍由 H3 任務表執行。

旁白版本

vo_versions/vo_v1.csv
vo_v1_scratch.wav
vo_lock.md

鎖定前先試讀/TTS，量測真實時長；
鎖定後只新增版本，不直接修改舊版；
修改旁白先執行 vo_diff.py，再按影響範圍修改；
詳見 references/12_change_control.md。

`project.json`

init_project.py 生成的機器配置：profile/model_routing/image_mode/duration_target_sec/shot_target/fps/resolution/providers。
project.yaml 是給人讀的版本；腳本讀取 project.json。

`tasks.json`

[{"generation_id":"S01","provider":"minimax_h3","model":"MiniMax-H3","resolution":"768P","duration":9,"status":"todo","prompt":"h3_package/S01/prompt.md","first_frames":["首幀_h3/1-1_first.png"],"cost_cny":0.0}]

generation_id 對應 segments.csv 的生成段；
duration 必須是 4–15 的整數；
prompt / first_frames 是投產包路徑；
失敗任務不計費；重試單獨列出；
舊的逐鏡任務可使用 id，但 h3_tasks.json 一律使用 generation_id。

交付包

final.mp4
subtitles.srt
vo.wav
vo.csv
music/A-E.wav + cue_sheet.csv
credits.md
source_list.csv
fact_check.csv
final_qc.md

硬規則

圖片預設由使用者透過 GPT 生成，AI 不呼叫圖片 API；僅當 image_mode=agent 且使用者明確批准時才允許影像工具；
影片預設一版制，不能用才補一版；
生成的影片只允許環境音/人聲，不允許配樂/BGM；
768P 原始素材可能是 1344×768（7:4），最終版交付 1920×1080；
首幀必須是 16:9，否則圖生影片比例會跑掉；
歷史照片標註來源，AI 畫面標註「情景再現」；
字幕 16–20 字/行、最多 2 行、左右 ≥100px；
音樂每段留 1.5–2 秒 handle，低谷不是靜音；
成本按照任務日誌計算，不靠記憶；
交付前使用 ffprobe 覆核解析度/幀率/音訊；
先定旁白，再定鏡頭；預設一句旁白跨 2–3 鏡，一鏡一句是特殊情況；
旁白不要鋪滿畫面；5 秒旁白配 5 秒畫面會趕，句間留 0.3–1.0 秒氣口；
旁白可以有詩意，但詩意必須有實物/動作錨點；解釋段才要求每句一個硬資訊；不要把兩套標準混用；
旁白鎖定後，禁止因為改一句旁白重寫整個專案；先執行 vo_diff.py，再只修改受影響的檔案；
G4 提示詞完成後，先提醒使用者出圖；使用者開始出圖後，才做不依賴圖片/影片的並行工作；
一段旁白可跨多個鏡頭；普通鏡頭最多一段旁白；long_take=yes 的長鏡頭可包含多段旁白，但必須全部在鏡頭內；
氣口視窗必須包含鏡頭切點；不要要求句子起止貼著切點；氣口有區間時取大；
v0 animatic 輸出完成後，先提醒使用者檢查句間氣口；確認前不輸出首幀、不生成影片；
音色必須在試聽 2–3 個候選後由使用者選定；不能預設使用某個 TTS；
旁白預設「清楚但不直白」：先講清人物/事件/因果，再用具體物象和短句留白；允許加 1–2 句，但每句要有新資訊或新畫面，不用形容詞湊時長；
beats.csv 的每個節拍必須恰好被一個鏡頭認領；每個鏡頭、每段旁白都要有節拍覆蓋；漏拍/重複/亂序由 validate.py 攔截；
segments.csv 一段 ≤15 秒；段內切序連續、每一切一張關鍵幀、每個 shot 只出現一次；每一切的起止必須等於 shots.csv 的累計時間；H3 多圖對齊使用 export_h3.py 輸出投產包；
片頭卡：G0 定時長，G2.5 定文字，G3 寫入 0-1 static=yes，G4 出圖，G5 不做 H3。

Provider

config/providers.yaml 是說明文件；機器配置是 providers.json（由 init_project.py 生成，timeline.py 會進行校驗）。

預設：圖片=user_gpt，影片=minimax_h3，旁白=capcut_tts，配樂=local_midi_fluidsynth，剪輯=capcut，品質檢驗=ffmpeg。

圖片 provider 永遠是 human；此設定不隨配置改變。

命令

python scripts/init_project.py --root my-film --profile short --duration 30 --shots 10 --segments 2
python scripts/timeline.py --shots shots.csv --vo vo.csv --vo-out vo_report.csv --project project.json --min-gap 0.4
python scripts/timeline.py --shots shots.csv --vo vo.csv --max-density 0.85 --allow-single
python scripts/narration_lint.py --text vo.csv --style lyrical --max-chars 28
python scripts/validate.py --shots shots.csv --vo vo.csv --beats beats.csv --segments segments.csv --project project.json
python scripts/validate.py --shots shots.csv --vo vo.csv --beats beats.csv --segments segments.csv --project project.json --strict-files
python scripts/validate_tasks.py --tasks h3_tasks.json --segments segments.csv
python scripts/selftest.py
python scripts/export_h3.py --shots shots.csv --segments segments.csv --prompts h3_prompts.csv --out h3_package
python scripts/timeline.py --shots shots.csv --vo vo.csv --animatic animatic.mp4
python scripts/vo_gap_report.py --vo vo.csv --audio vo_scratch.wav --out vo_gap.md
python scripts/vo_diff.py --old vo_versions/vo_v1.csv --new vo.csv --out vo_diff.md
python scripts/vo2srt.py --vo vo.csv --out subtitles.srt --max-chars 18
python scripts/contact_sheet.py --clips clips --out review --frames 6
python scripts/cost_report.py --tasks tasks.json --out cost.csv --default-model MiniMax-H3

腳本：init_project.py、validate.py、selftest.py、export_h3.py、timeline.py、narration_lint.py、vo2srt.py、vo_gap_report.py、vo_diff.py、contact_sheet.py、cost_report.py。--animatic 缺少首幀時預設使用黑幀佔位，--animatic-missing error 可改為報錯。

validate.py 管理結構契約（schema / 節拍 / 段切 / 覆蓋）；G3 預設不檢查關鍵幀檔案，G5 使用 --strict-files 檢查。timeline.py --vo 管理時間（氣口 / 密度 / 長鏡頭）。兩者都要執行，不互相替代。

失敗處理

影片失敗：檢查任務狀態；失敗不計費；替換 H3-Max 或修改首幀，不盲目重跑；
人物變臉/多手：重新生成或改為側影/背影；
動作沒發生：重新生成，不要用剪輯硬補；
字幕溢出：修改樣式/斷行，不要縮到看不清；
音樂突兀：增加 pickup、expression ramp、handle，不要硬切；
導出比例錯誤：回到專案改為 1920×1080，不要拉寬。

參考

SOP.md：給人看的流程與檢查表
references/：階段細節（包含 00_setup.md、09_vo_spans.md、10_model_routing.md、11_narration.md、12_change_control.md、13_parallel_work.md、14_v0_animatic.md、15_beats_segments.md）
providers/：可替換工具
templates/：專案卡、鏡頭表、提示詞、評審表、cue sheet、credits、終檢

yinguozhang/ai-documentary-production

ai-documentary-production 是什麼？

在你喜歡的 AI 中提問

說明文件