Communitygithub.com

紀錄片製作技能

將任何主題從頭到尾製作成一部短片紀錄片:研究、事實查核的旁白腳本、配音、有來源的歷史靜態影像、字幕、致謝、背景音樂,並使用 ffmpeg 渲染成 MP4 檔案。每當有人要求製作紀錄片、迷你紀錄片、視頻論文、歷史或科學短片、檔案風格影片、解說影片,或說「做一個關於...的影片」且希望有真實來源而非簡報時,請使用此技能。

紀錄片製作技能 是什麼?

此AI代理人技能可將使用者的任何主題,從頭到尾自動化產出一部完整的短片紀錄片,最終交付一個 MP4 檔案(1920x1080, H.264/AAC),以及字幕檔 (SRT)、致謝清單、腳本和來源。其核心運作流程包含:先以不超過兩個問題與使用者確認影片長度與論述角度,接著進行主題研究(目標4-6個可靠來源),撰寫分幕腳本(每分鐘155字、四個段落結構、每句不超過22字),編排鏡頭列表,並從 Wikimedia Commons 等開放檔案庫取得真實歷史靜態影像。若無合適素材,則可生成 AI 重建影像或使用文件、地圖等圖形素材,但嚴禁將 AI 生成的圖片偽裝成真實檔案。系統支援多種語音合成(優先使用 ElevenLabs),並可加入背景音樂。最終所有素材會透過 FFmpeg 渲染成影片,並提供迭代用的草稿模式以加快開發速度。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/0xAkashic/documentary-video-skill/tree/HEAD

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

紀錄片製作

使用者提供一個主題。你交付一部完成的影片: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 則可看到所有內容(然後你自己檢查每個授權)。

如果檔案庫沒有合適的素材,按優先順序:

  1. 其他開放收藏 — 美國國會圖書館、史密森尼開放取用、NASA、Internet Archive、Europeana。在從新網站下載前詢問使用者,並在 CREDITS.md 中記錄授權和 URL。
  2. 使用任何可用的影像工具生成圖片,並參考 references/image-prompts.md。在 CREDITS.md 中將生成的幀標記為 AI 生成的重建,並加上說明,讓觀眾永遠不會被誤導以為是照片。
  3. 排版與物件鏡頭 — 文件、地圖、航海日誌頁面、抽象圖版。誠實且成本低廉。

絕對不要將 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 鏡頭範例(腳本 + 鏡頭)。

相關技能