Communitygithub.com

ドキュメンタリービデオスキル

あらゆるテーマを、完全な短編ドキュメンタリー作品に仕上げます。調査、事実確認済みナレーションスクリプト、音声、ソース付きアーカイブ静止画、字幕、クレジット、BGM、そしてffmpegでレンダリングされたグレーディング済みMP4まで、エンドツーエンドで生成します。

ドキュメンタリービデオスキル とは?

このAIエージェントスキルは、ユーザーが指定したトピックをもとに、調査から公開まで完全自動で短編ドキュメンタリー映画を制作します。ユーザーはソフトウェアのインストールや編集作業を一切行う必要がなく、「〇〇についてのドキュメンタリーを作って」と頼むだけで、ナレーション、アーカイブ静止画、BGM、字幕、クレジットを含む1920x1080のMP4動画が出力されます。スキルはまずトピックをフレーミングし、長さ(デフォルト3分)と主張(テーマではなく、映画が何を論じるか)を決めます。次にウェブ検索で4~6の信頼できる情報源を調査し、事実ごとに出典を明記したresearch.mdを作成します。スクリプトは155語/分のナレーション速度、4幕構成、1文1行の厳格なルールに従い、script.mdに書き出されます。shots.jsonでショットリスト(静止画と動き、キャプション)を定義した後、DOCコマンドで音声生成(ElevenLabs対応)、静止画ソーシング(Wikimedia Commons優先、AI生成画像も利用可能だが倫理的ガイドラインあり)、そしてffmpegによるレンダリングを行います。最終的にMP4、SRT字幕、CREDITS.md、スクリプトをユーザーに納品します。このスキルは、Claude CodeやCodexなどのAIエージェントが、ドキュメンタリー、ミニドキュメンタリー、ビデオエッセイ、歴史・科学ショート、アーカイブ形式の映画、ナレーション付き解説動画を依頼されたときに最適です。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/0xAkashic/documentary-video-skill/tree/HEAD

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

ドキュメンタリービデオ

ユーザーがトピックを与えると、完成した動画を納品します:out/<slug>.mp4(1920×1080、H.264/AAC)、さらに.srt、CREDITS.md、スクリプト、ソースファイルも含まれます。ユーザーは自らインストール、調査、執筆、レンダリングを行う必要は一切ありません。本当にユーザーの判断が必要な場合(有料の生成、ダウンロードに許可が必要、事実確認できない主張)でなければ、作業を続けてください。

SKILL_DIRはこのフォルダです。DOCはpython3 "$SKILL_DIR/scripts/doc.py"を意味します。

1. 書く前にフレームを決める

最大で2つの質問をしますが、それは映画を変える場合に限ります:長さ(デフォルト3分)と視点(主題ではなく、映画が何を論じるか)。それ以外はすべてあなたが決めます。

ドキュメンタリーとは、写真で裏打ちされた議論であり、単なる要約ではありません。視聴者が見終わった後に繰り返せる主張を一つ選びなさい——「灯台守はテクノロジーに負けたのではなく、スプレッドシートに負けたのだ」——そして、その主張に貢献しないものはすべて削る。

事実のリストを映像化してはいけません。変化を映像化しなさい:何かが真実だった、そしてそれが真実でなくなった、その代償は何だったか。

2. セットアップ(初回のみ)

DOC doctor

python3 と ffmpeg(libx264付き)が必要です。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. 調査

ウェブ検索を使用します。4~6の信頼できる情報源を目指しましょう:一次資料、アーカイブ、大学や政府機関のページ、信頼できるジャーナリズム、書籍1冊。結果だけでなく、メカニズムを説明できるだけの情報を読み込みましょう。

research.md に保存します:

# 調査

## テーゼ
映画が論じる一文。

## 事実(それぞれに出典を)
- 1841年:<事実> -- <ソースURL>
- <年>:<事実> -- <ソースURL>

## 論争中・不明
- <情報源間で意見が分かれている点と、映画でどのように表現するか>

## ビジュアル素材
- <アーカイブ、コレクション、パブリックドメインの画像検索候補>

ナレーションのすべての文は、ここに記された行に遡ることができなければなりません。2つの情報源が矛盾する場合は、画面上でその旨を伝えるか、その事実をカットしてください。数字、日付、引用、逸話を捏造してはいけません。 不足している事実はプロットの問題ですが、偽の事実は詐欺です。

4. スクリプトを書く

書き始める前に references/script-craft.md を読んでください。要点は以下の通りです:

  • 毎分155語。 3分で約460語。雰囲気ではなく幕ごとに予算を組む。
  • 4つの動き: 以前の世界(フック)、メカニズム(変化の仕組み)、代償(人々への影響)、反響(変化したフックへの回帰)。
  • 一文一意見。 一行一呼吸。一文は22語を超えない。
  • 抽象より具体。 「彼は一晩に117段の階段を2回登った」は「仕事は過酷だった」よりはるかに優れている。
  • 物語は現在形、評価は過去形。
  • ナレーションが議論を運び、キャプションが証拠(名前、日付、場所)を伝える。 キャプションですでに証明されていることをサウンドトラックで語ってはいけない。

script.md に幕ごとに、一文一行で書きます。shots.json の行はこれと完全に一致する必要があるからです。

## 幕I -- 以前の世界
200年の間、誰かが起きていなければならなかった。そうすることで船が岸を見つけられた。
...

その後、スクリプト全体(おおよそ30行)を1回のメッセージでユーザーに表示し、続行します。ユーザーがレビューを希望した場合を除き、承認を待ってはいけません。

5. ショットリスト

すべてのフィールドと完全な例について references/shot-list.md を読んだ後、shots.json を書きます:

{"shots": [
  {"id": "s01", "kind": "card", "text": "最後の灯台守",
   "sub": "12年で消えた仕事", "hold": 4.0},
  {"id": "s02", "line": "200年の間、誰かが起きていなければならなかった。",
   "img": "work/img/cape-byron-1891.jpg", "motion": "zoom-in",
   "caption": "ケープ・バイロン、1891年"}
]}

重要なルール:

  • line はナレーションであり、スクリプトからそのまま、順序通りに。 尺は音声から決まるため、行を変更すると編集が変わります。
  • 1ショット3.5~6秒。 静止画は思っているより長く必要です。意図的なフラッシュ以外は2.5秒未満にしないでください。
  • 1画像、1アイデア。 ショットに2つの画像が必要なら、それは2つのショットです。
  • カメラを動かし、世界を動かさない。 zoom-in は親密さ、zoom-out は結果、pan-* は風景や文書、static は顔やテキストに使用します。
  • カードは章の区切り。 3分の作品で2~4枚使用:タイトル、日付や数字1つ、そして最後に着地するカード。カードにはナレーションがありません。
  • caption は画面上の小さな証拠行です:場所、年、ソース。6語以内に収めます。

6. 静止画

実際のアーカイブ素材を優先します。それがドキュメンタリーとスライドショーの違いです。

DOC archive <project> --query "Cape Byron lighthouse 1900" --n 3

これによりWikimedia Commonsを検索し、使用可能な画像を work/img/ にダウンロードし、sources.json と著者・ライセンス情報を含む CREDITS.md を書き出します。デフォルトでは、公開された動画には通常商用利用が必要なため、パブリックドメイン、CC0、CC BY/BY-SAのみを保持します。厳密なパブリックドメインの場合は --license pd、すべてを表示する場合は --license any を追加します(その後、各自でライセンスを確認してください)。

アーカイブに何も見つからなかった場合、優先順位は以下の通りです:

  1. その他のオープンコレクション -- アメリカ議会図書館、スミソニアン・オープンアクセス、NASA、インターネットアーカイブ、Europeana。新しいサイトからダウンロードする前にユーザーに確認し、ライセンスとURLを CREDITS.md に記録します。
  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の場合、3分の動画はラップトップで約1分、電話で10~20分かかります。常に --draft(半分の解像度、高速プリセット)で反復し、最後に1回だけフルパスを行います。build は各ショットを処理中に表示するため、明らかに間違っているレンダリングは停止できます。

9. 音楽

音楽を追加する前にユーザーに確認します。ソースを提案し、ライセンスを確認し、ファイルを public/music/bed.mp3 に配置してから、以下を実行します:

DOC build <project> --music public/music/bed.mp3

ループ再生され、音量は約14%で、音声の下に自動的にダッキングされます。無音も正当な選択肢であり、シリアスな映画では多くの場合、それがより良い選択です。

10. 納品

ユーザーに以下を提供します:

  • MP4ファイル。
  • .srtファイル(YouTubeでも有用)。
  • CREDITS.md -- すべての静止画、著者、ライセンス、リンク。
  • スクリプト、視点に関する1段落、および3~5のソースリンク。
  • 何がアーカイブ素材で、何が生成されたもので、何が証拠不足でカットされたかについての率直なメモ。

その後、次のステップを1つ提案します:長いカット、異なるオープニング、第2幕、または同じ動画の縦型60秒カット。

適切な判断

  • 映画は映像ではなく議論である。 画像が美しくても主張が曖昧なら、書き直せ。
  • 3つ目の例はカットせよ。 2つでパターンが証明される。3つはリストだ。
  • ソースは説明文だけでなく画面上に表示せよ。 年と場所が書かれたキャプションこそが、視聴者に残りを信頼させる。
  • わからないことは「わからない」と言え。 「その数については誰も意見が一致しない」というのは、自信満々の間違いより強い一文だ。
  • 故人を敬え。 実在の人物、実在の出来事:捏造された会話、記録として提示する再現、名前のある個人に対する生成された顔を禁止する。
  • 長さは約束である。 素材が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ショットの例(スクリプト+ショットリスト)。

関連スキル