紀錄片製作
使用者提供一個主題。你交付一部完成的影片:out/<slug>.mp4(1920x1080,H.264/AAC),以及 .srt 字幕檔、CREDITS.md 致謝清單、腳本與來源。使用者無需自行安裝、研究、寫稿或渲染任何東西。只有在決策確實屬於使用者時才停下:例如需要付費的生成、需要權限才能下載的項目,或無法驗證的事實主張。
SKILL_DIR 是此資料夾。DOC 代表 python3 "$SKILL_DIR/scripts/doc.py"。
1. 撰寫前先設定框架
最多問兩個問題,且只有在這些問題會改變影片時才問:長度(預設 3 分鐘)和角度(影片論證的主張,而不只是主題)。其他一切由你決定。
紀錄片是用畫面來論證,不是摘要。選定一個觀眾看完後能複述的主張——例如「燈塔看守人不是輸給了技術,而是輸給了一張電子表格」——並刪除一切無助於支持這個主張的內容。
永遠不要只拍攝一串事實。要拍攝一個變化:某事曾經是真的,然後不再是真的,以及這帶來了什麼代價。
2. 設定環境(僅首次執行)
DOC doctor
需要 python3 和支援 libx264 的 ffmpeg。Termux:pkg install ffmpeg。macOS:brew install ffmpeg。若只有 ffmpeg 缺失,請安裝後重新執行。在 doctor 顯示「Ready」之前,不要寫入其他東西。
DOC new <project> --title "最後的燈塔看守人" --subtitle "1985 -- 1997"
這會建立 project.json、shots.json、research.md、script.md,以及 work/img、work/audio、out 目錄。
3. 研究
使用網路搜尋。目標是找到四到六個可靠來源:原始文件、檔案庫、大學或政府機構頁面、有信譽的新聞報導、一本書。要讀到足以解釋其中的機制,而不只是結果。
儲存到 research.md:
# 研究
## 論點
影片論證的一句話。
## 事實(每個都有來源)
- 1841:<事實> -- <來源網址>
- <年份>:<事實> -- <來源網址>
## 有爭議/未知的
- <來源之間的分歧點以及影片將如何措辭>
## 視覺素材
- <檔案庫、收藏、可能為公共領域的圖片搜尋>
旁白中的每一句話都必須能追溯到這裡的一行。如果兩個來源有分歧,你要麼在畫面上說明,要麼放棄這個事實。絕對不要虛構任何數字、日期、引言或軼事。 缺少一個事實是劇情問題;偽造一個事實則是欺詐。
4. 撰寫腳本
在撰寫前先閱讀 references/script-craft.md。簡而言之:
- 每分鐘 155 個字。 3 分鐘 = 約 460 字。按幕次分配預算,而不是憑感覺。
- 四個段落: 之前的世界(鉤子)、機制(變化如何發生)、代價(對人們造成的影響)、迴響(回到鉤子,但已有所改變)。
- 一句話一個想法。 一行一個呼吸。沒有句子超過 22 個字。
- 具體勝於抽象。 「他每晚爬 117 階樓梯兩次」比「這份工作很辛苦」更好。
- 故事用現在式,結論用過去式。
- 旁白承載論證;字幕承載證據(姓名、日期、地點)。永遠不要在音軌上說出字幕已經證明的內容。
將腳本以幕次為單位寫在 script.md 中,每一行一個句子,因為 shots.json 中的行必須完全對應:
## 第一幕 — 之前的世界
兩百年來,總得有人保持清醒,船隻才能找到海岸。
...
然後在一次訊息中向使用者展示整個腳本——大約 30 行——然後繼續。除非他們要求審閱,否則不要等待批准。
5. 鏡頭列表
閱讀 references/shot-list.md 了解所有欄位和一個完整範例,然後撰寫 shots.json:
{"shots": [
{"id": "s01", "kind": "card", "text": "最後的燈塔看守人",
"sub": "一個在十二年內消失的工作", "hold": 4.0},
{"id": "s02", "line": "兩百年來,總得有人保持清醒。",
"img": "work/img/cape-byron-1891.jpg", "motion": "zoom-in",
"caption": "拜倫角燈塔,1891"}
]}
重要的規則:
line是旁白,必須與腳本完全一致,且按順序排列。 持續時間來自音頻,所以更改任何一行都會影響剪輯。- 每個鏡頭 3.5 至 6 秒。 靜止畫面的時間需要比你想的更長。除刻意閃現外,不得少於 2.5 秒。
- 一個影像,一個想法。 如果一個鏡頭需要兩個影像,就把它分成兩個鏡頭。
- 移動攝影機,而不是世界。
zoom-in用於親密感,zoom-out用於後果,pan-*用於風景和文件,static用於人臉和文字。 - 標題卡是章節分隔。 在 3 分鐘的影片中使用 2-4 張:標題、一個日期或數字、以及一張結尾卡。標題卡沒有旁白。
caption是畫面角落的證據行:地點、年份、來源。保持在 6 個字以內。
6. 靜止畫面
優先使用真實的檔案素材。這是紀錄片和幻燈片之間的區別。
DOC archive <project> --query "拜倫角燈塔 1900" --n 3
這會搜尋 Wikimedia Commons,將可用的圖片下載到 work/img/,並寫入 sources.json 和 CREDITS.md,包含作者和授權資訊。預設只保留公有領域、CC0 和 CC BY / BY-SA 的圖片,因為發布的影片通常需要商業使用。加上 --license pd 可嚴格限定公有領域,--license any 則可看到所有內容(然後你自己檢查每個授權)。
如果檔案庫沒有合適的素材,按優先順序:
- 其他開放收藏 — 美國國會圖書館、史密森尼開放取用、NASA、Internet Archive、Europeana。在從新網站下載前詢問使用者,並在
CREDITS.md中記錄授權和 URL。 - 使用任何可用的影像工具生成圖片,並參考
references/image-prompts.md。在CREDITS.md中將生成的幀標記為 AI 生成的重建,並加上說明,讓觀眾永遠不會被誤導以為是照片。 - 排版與物件鏡頭 — 文件、地圖、航海日誌頁面、抽象圖版。誠實且成本低廉。
絕對不要將 AI 生成的圖片呈現為檔案資料。這單單一條線就構成了這個格式的全部倫理。
7. 配音
DOC tts <project>
當 ELEVENLABS_API_KEY 設定時使用 ElevenLabs(效果最佳),否則使用離線語音(espeak-ng、Android termux-tts-speak、macOS say)。一次錄製完成。要為聽覺而寫:句子簡短,避免繞口令,數字按照發音方式拼寫。
如果完全沒有語音,影片仍然會使用估計的時間來渲染——請告知使用者,並交付 .srt 字幕檔,以便使用者之後自行錄製旁白。保持 line 不變,這樣重新錄製可以直接套用。
錄音品質勝過模型品質:在安靜房間裡用手機錄音,對大多數紀錄片來說比合成語音更好。提供這個選項。
8. 構建與觀看
DOC build <project> --draft # 迭代時快速渲染
DOC build <project> --subs # 最終版本,字幕嵌入畫面
DOC sheet <project> # 12 格聯絡表
每次都要查看 out/contact.jpg。 檢查:
- 沒有重要內容被字幕蓋住,也沒有字幕超出畫面;
- 剪輯點落在句子結尾,且沒有鏡頭停留在圖片的空白或無關部分;
- 色調一致,人臉沒有被壓縮,文字圖像可讀;
- 結尾標題卡在旁白結束後出現,而不是重疊在上面。
透過編輯 shots.json(圖片、運鏡、字幕、順序)並重新構建來修正。內部剪輯片段會根據鏡頭 ID 進行快取,因此只會重新渲染有變更的鏡頭。
速度。 渲染是 CPU 密集型的。在 1080p 下,一部三分鐘的影片在大約筆電上需要約一分鐘,在手機上需要 10-20 分鐘。始終使用 --draft(半解析度、快速預設)進行迭代,最後再做一次完整渲染。build 會逐步印出每個鏡頭,因此你可以在渲染明顯錯誤時停止它。
9. 音樂
在加入音樂前先詢問使用者。建議一個來源,檢查授權,將檔案放在 public/music/bed.mp3,然後:
DOC build <project> --music public/music/bed.mp3
它會循環播放,音量約在 14%,並在語音出現時自動降低。沉默也是一個正當的選擇,而且對於嚴肅的影片來說通常是更好的選擇。
10. 交付
提供使用者:
- MP4 檔案;
.srt字幕檔(在 YouTube 上也很有用);CREDITS.md— 每張靜止畫面的作者、授權、連結;- 腳本、一段關於影片角度的說明,以及 3-5 個來源連結;
- 直接說明哪些是檔案資料、哪些是生成的,以及哪些因為缺乏證據而被刪除。
然後提供一個後續步驟:更長的剪輯、不同的開頭、第二幕,或將同一部影片製作成垂直的 60 秒版本。
良好的判斷力
- 影片是論證,不是素材。 如果畫面很美但主張模糊,就重寫。
- 刪除第三個例子。 兩個證明模式;三個就是列表。
- 來源要顯示在畫面上,而不只是在說明中。 附有年份和地點的說明,是讓觀眾相信其餘內容的關鍵。
- 說出你不知道的事。 「沒有人同意這個數字」比一個自信但錯誤的說法更有力。
- 尊重逝者。 真實的人物、真實的事件:不要有虛構的對話,不要將重演呈現為真實記錄,不要為指名道姓的個人生成臉孔。
- 長度是一種承諾。 如果素材只夠支撐 90 秒,就交付 90 秒。
檔案
scripts/doc.py— 整個流程(DOC -h查看所有標誌)。references/script-craft.md— 如何撰寫聽起來像電影的旁白。references/shot-list.md— 完整的shots.json結構和範例。references/sourcing.md— 檔案庫、授權規則、歸屬格式。references/image-prompts.md— 用於生成能與檔案素材搭配的靜止畫面的提示詞。examples/last-lightkeeper/— 一個完成的 3 鏡頭範例(腳本 + 鏡頭)。