video-podcast-maker

推奨：Remotion のベストプラクティスを読み込む

Remotion のパターンライブラリをすべて利用するには、このスキルで remotion-best-practices（同梱されていません）を使うと便利です。これは任意です。利用できない場合は、以下の最低限のルールに従ってください。

• Pi：利用可能なスキルに記載されている remotion-best-practices から、読み込まれたスキルを確認してください。
• Claude Code：作業を進める前に、remotion-best-practices スキル／ツールを呼び出してください。

インストールされていませんか？remotion-dev/skills から入手してください（ドキュメント：remotion.dev/docs/ai/skills）。

remotion-best-practices がインストールされていない場合の最低限のルール：chromium を利用可能にすること、4K コンテンツは必ず <Scale4K> で囲むこと、linearTiming を指定した <TransitionSeries> を使用すること、音声をマスタークロックとして扱うこと。

Video Podcast Maker

トピックから 4K の Bilibili 向け横型ナレッジ動画を作成する自動パイプラインです。コーディングエージェント + TTS バックエンド + Remotion + FFmpeg。

目次

• セットアップ — 前提条件（ステップ 1 の前に実行してください）
• 実行モード — 自動と対話型 → references/workflow-script.md
• 既存動画の再生成 — 完成した動画を反復して改善する
• ワークフロー — 11 ステップのパイプライン + フェーズファイルの参照先 + 必須の停止ポイント
• 厳守ルール — 制作上の必須制約
• 音声マスタークロックと同期
• 動画ごとのレイアウト
• その他のリソース — 各 references/ ファイルを読み込むタイミング
• ユーザー設定
• トラブルシューティング

---

ブートストラップ

SKILL_DIR を、この SKILL.md が格納されているディレクトリに設定します。

• Pi：エージェントは、読み込まれたスキル一覧からスキルのパスを把握しています。コマンドを実行する前に、SKILL_DIR をそのディレクトリに設定してください。
• Claude Code：${CLAUDE_SKILL_DIR} が自動的に設定されます。

SKILL_DIR="${SKILL_DIR:-${CLAUDE_SKILL_DIR}}"

# Prerequisites (CLIs + backend env vars)
python3 "${SKILL_DIR}/scripts/check_prereqs.py"

更新はスキル CLI（npx skills update video-podcast-maker -g）を通じて行います。直接 git clone してインストールした場合は、README に従って git pull を実行してください。このスキルは更新チェックを行いません。

前提条件の確認に失敗した場合 — セットアップについては README.md を参照してください。チェックはバックエンドを認識し、TTS_BACKEND 環境変数 → user_prefs.json の global.tts.backend → デフォルトの edge の順に解決するため、アクティブなバックエンドが必要とする環境変数のみを検証します。

新しいプロジェクトで初めて動画を作成しますか？ すでに node_modules/ がインストールされている既存の Remotion プロジェクトを再利用することをおすすめします。新しいプロジェクトを作成すると、約 2.2 GB の npm パッケージと 90 MB の Chrome ヘッドレスシェルがダウンロードされます（プロジェクトごとに初回のみ）。ユーザーが以前の動画で使用したプロジェクトを持っている場合は、それを使用してください。新しいプロジェクトが必要な場合は、ステップ 1～4（トピックの調査とスクリプトの作成）の作業中に、バックグラウンドで npm install を実行してください。

すべてのレンダリングは videos/{name}/ に出力します — output.mp4、final_video.mp4、thumbnail_*.png はすべて、動画ごとのディレクトリに直接保存されます。out/ や dist/ ディレクトリへのレンダリングは絶対に行わないでください。--public-dir videos/{name}/ という規約により、すべてが自己完結した状態に保たれます。

TTS エンジン — ローカルバックエンドは 2 つあり、外部スキルは不要です。

• edge（デフォルト）— 無料で、キーは不要です。edge-tts を使用します。
• azure — AZURE_SPEECH_KEY と AZURE_SPEECH_REGION が必要です（Microsoft Speech SDK）。

それぞれが内部で音声を合成します（scripts/tts/backends/native.py）。発音の処理 （表示 → 読み上げ → 字幕用の表示への復元）と音素の適用が組み込まれています。 check_prereqs.py は、アクティブなバックエンドに必要な環境変数を検証します。

マルチプラットフォーム TTS を使いますか？ 9 つのバックエンドを提供していた従来の ttscn コンポーネントスキルは、このスキルの依存関係ではなくなりました。これらのプラットフォームを使いたい場合は、Agents365-ai/ttsCN を別途インストールして直接呼び出してください。このスキルに含まれるのは edge と azure のみです。

デザイン学習のショートカット：ユーザーが参考動画や画像を提供した場合、またはスタイルプロファイルの保存・一覧表示・削除を依頼した場合は、以下のワークフローを実行する代わりに references/design-learning.md を参照してください。

---

実行モード

ワークフローの開始時に、自動モード（デフォルト）と対話モードを判定してください。自動モードをデフォルトにする判断表と、リクエストごとの上書き設定については、references/workflow-script.md を参照してください。

---

既存の動画を再生成する

videos/{name}/ がすでに存在し、ユーザーが完成済みまたは作成中の動画を修正している場合は、そのディレクトリを再利用してください。新しいプロジェクトや、新しい videos/{newname}/ を作成してはいけません。

実際に変更した内容に対して、必要最小限の手順のみを再実行してください。

変更内容	再実行する手順	再利用するもの（やり直さない）
ナレーションスクリプト（podcast.txt）	ステップ 7（TTS）→ ステップ 8 プレビュー → レンダリング＋ミックス	トピックの調査＋セクション設計
映像のみ（コンポーネント、レイアウト、色）	ステップ 8 プレビュー → レンダリング＋ミックス	音声（podcast_audio.wav / timing.json）
BGM のみ	BGM を再ミックス	output.mp4（再レンダリング不要）
字幕のみ	ステップ 10.1 仕上げ	output.mp4 / video_with_bgm.mp4

視聴者が見るもの、または聞くものに影響する変更を再実行する場合は、必ずステップ 8 の確認に戻ってください。変更を適用し、Studio のホットリロードを待ってから、新たに明示的な「render 4K」の指示を待ちます。以前の確認は引き継がれません。スクリプトを変更すると、それ以降のタイムスタンプがすべて変わるため、必ず TTS で timing.json を再生成してください。手作業で編集してはいけません。再実行後は、必ず次の項目を再確認してください。

python3 ${SKILL_DIR}/scripts/verify_output.py videos/{name}/

---

ワークフロー

完成済みの動画を調整しますか？ すでに videos/{name}/ が存在する場合は、ステップ 1 から始めず、上記の既存動画の再生成を参照して、必要最小限の再実行を行ってください。

ステップ 1 の開始時に、エージェントのタスクトラッカーに各ステップのタスクを 1 つずつ作成してください。開始時に in_progress、完了時に completed に設定してください。videos/{name}/ 内のファイルが永続的な記録になります。中断した場合は、ディレクトリを確認して再開する箇所を判断してください。

#	ステップ	出力	フェーズファイル
1	トピックの方向性を決める	topic_definition.md	workflow-script.md
2	トピックを調査する	topic_research.md	workflow-script.md
3	5～7 セクションを設計する	（メモリ内）	workflow-script.md
4	ナレーション台本を作成する	podcast.txt	workflow-script.md
4.5	発音の事前確認（zh-CN）	phonemes.json	workflow-script.md
5	アセットを計画して解決する	assets/manifest.json	workflow-assets.md
6	サムネイルを生成する（16:9 + 4:3）	thumbnail_*.png	workflow-production.md
7	TTS 音声を生成する	podcast_audio.wav, timing.json	workflow-production.md
8	Remotion のコンポジション + Studio プレビュー	—	workflow-production.md
9	4K でレンダリングし、BGM をミックスする	output.mp4, video_with_bgm.mp4	workflow-production.md
10	公開情報 + 出力の検証	publish_info.md, final_video.mp4	workflow-publish.md
11	縦型ショート動画を生成する（任意）	shorts/	workflow-publish.md

必須の停止ポイント（上記の太字の行）：

• ステップ 8 — Studio でのレビュー。 npx remotion studio を必ず起動し、レンダリング前にユーザーからのフィードバックを待ってください。ユーザーが明示的に（「render 4K」／「render final」と）確認するまで、4K でのレンダリングは絶対に行わないでください。調整依頼を含む返信は確認ではありません。変更を適用して Studio をホットリロードし、再度確認を求めてください。調整を行うたびに、ステップ 9 の前に改めて確認を得る必要があります。
• ステップ 10 — verify_output.py。 動画の完成を宣言する前に、必ず合格させてください。終了コード 0 は合格、終了コード 2 は警告が残っていても公開可能です。一般的な不足項目は自動修正されます（final_video.mp4 がない場合は作成されます）。プラットフォーム対応表に照らして、公開情報（タイトル、説明、タグ、チャプター）を検証します。公開情報はステップ 5.5 と 10.2 で生成してください。機械可読な出力を追加するには --format json を指定してください。

レンダリング前の監査（推奨） — ステップ 8 の前に実施してください：

python3 ${SKILL_DIR}/scripts/audit_beat_sync.py <Video.tsx> <timing.json>

ナレーションから 1.5 秒を超えてずれているビートにフラグを付けます。

自動モード：ビジュアルのセルフレビュー。 Studio をユーザーが確認しない自動モードで実行する場合は、レンダリング確認を求める前に、重要なフレームの静止画を 3～5 枚レンダリングしてください：

npx remotion still src/remotion/index.ts <CompositionId> videos/{name}/_review_001.png --public-dir videos/{name}/ --frame=<midpoint_frame>

フレームは、ヒーロータイトル（全体の約 10% 地点）、情報量の多いセクションの中間地点、アウトロから選んでください。静止画を画像として読み込み、実際のレンダリング出力に対してdesign-guide.mdとvisual-taste.mdのチェックリストを確認してください。4K レンダリングの前に、はみ出し、コントラスト、レイアウトのリグレッションを見つけてください。レビュー後に _review_*.png を削除してください。

検証チェックポイント

ステップの後	確認内容
7（TTS）	podcast_audio.wav が再生できる · timing.json がすべてのセクションをカバーしている · SRT が UTF-8 である
9（レンダリング）	output.mp4 が 3840×2160 である · 音声と映像が同期している · 黒いフレームがない
10（検証）	verify_output.py の終了コードが 0（または警告を確認済みの場合は 2）である

---

厳守事項

ルール	要件
単一プロジェクト	ユーザーの Remotion プロジェクト内の videos/{name}/ にすべての動画を配置します。動画ごとに新しいプロジェクトを作成してはいけません。
4K 出力	3840×2160（または縦型の 2160×3840）。1920×1080 のデザイン領域を scale(2) で囲みます。
音声同期	音声（podcast_audio.wav + podcast_audio.srt）をマスタークロックとします。timing.json は実際の TTS 出力から必ず生成し、手作業で推定してはいけません。レンダリング前に、最終動画の長さが音声と ±0.5 秒以内で一致している必要があります。音声マスタークロックと同期を参照してください。
サムネイル	16:9（1920×1080）と 4:3（1200×900）の両方を必ず生成してください。design-guide.mdを参照してください。
レンダリング前に Studio で確認	確認のために remotion studio を必ず起動してください。ユーザーが明示的に確認するまで、4K でレンダリングしてはいけません。調整のフィードバックは確認ではありません。反映してホットリロードした後、再度確認を求めてください。
--public-dir	Remotion コマンドではすべて --public-dir videos/{name}/ を使用します。すべての出力ファイル（output.mp4、final_video.mp4、サムネイル）は videos/{name}/ に直接配置し、out/ や dist/ ディレクトリに配置してはいけません。

テキストサイズ、コンテンツ幅、安全領域、アニメーションの安全性に関するビジュアルの最低要件は、references/design-guide.mdに記載されています。Step 8 の前に必ず読み込んでください。

音声マスタークロックと同期

基本ルール

1. 音声をマスタークロックとします。 すべてのスライドの開始時刻、字幕、チャプター、アニメーションのビートは、podcast_audio.wav と podcast_audio.srt から導きます。
2. テキストの推定ではなく、TTS からタイミングを生成します。 パイプライン：podcast.txt → generate_tts.py → podcast_audio.wav + podcast_audio.srt + timing.json → コンポジション → レンダリング。
3. 音声が生成される前に timing.json を手作業で作成してはいけません。 すでにスライドを調整済みの場合は、align_timing_from_srt.py を実行し、実際の SRT に合わせてください。
4. TransitionSeries のオーバーラップを補正します。 TransitionSeries は sum(section.duration_frames) - (N-1) * transitionFrames フレームをレンダリングします。レンダリング後の長さを timing.total_frames と一致させるため、各セクションを比例して拡大します。オーバーラップ分のフレームをすべて最初のセクションに詰め込んではいけません。修正済みのパターンは templates/Video.tsx にあります。

必須の同期チェックポイント

タイミング	確認項目
Step 7（TTS）の後	timing.json.total_duration が podcast_audio.wav と ±0.5 秒以内で一致している
レンダリング前	Video.tsx がオーバーラップ分を考慮してすべてのセクションを拡大している
レンダリング後	final_video.mp4 の長さが podcast_audio.wav と ±0.5 秒以内で一致している
Step 10（検証）	verify_output.py が終了コード 0 で終了し、音声／タイミングの結果が緑色で表示される

チェックポイントにひとつでも不合格があれば、そこで停止してください。公開してはいけません。

出力仕様

パラメーター	横型（16:9）	縦型（9:16）
解像度	3840×2160（4K）	2160×3840（4K）
フレームレート	30 fps	30 fps
エンコード	H.264、16Mbps	H.264、16Mbps
音声	AAC、192kbps	AAC、192kbps
長さ	1～15 分	60～90 秒（ハイライト）

動画ごとのレイアウト

project-root/                           # Remotion project root
├── src/remotion/                       # Remotion source (Root.tsx, compositions, index.ts)
├── videos/{video-name}/                # Per-video directory
│   ├── topic_definition.md             # Step 1
│   ├── topic_research.md               # Step 2
│   ├── podcast.txt                     # Step 4: narration script
│   ├── phonemes.json                   # Step 4.5: zh-CN pronunciation overrides
│   ├── assets/manifest.json            # Step 5: per-section asset registry
│   ├── publish_info.md                 # Step 10: title/description/tags
│   ├── podcast_audio.wav               # Step 7: TTS audio
│   ├── podcast_audio.srt               # Step 7: subtitles
│   ├── timing.json                     # Step 7: timeline (drives animations)
│   ├── thumbnail_*.png                 # Step 6
│   ├── output.mp4                      # Step 9: 4K render
│   ├── video_with_bgm.mp4              # Step 9: with BGM
│   ├── final_video.mp4                 # Step 10: final output
│   └── bgm.mp3                         # Background music
└── remotion.config.ts

動画ごとの --public-dir

Remotion コマンドではすべて --public-dir videos/{name}/ を使用します。各動画のアセットはそれぞれのディレクトリに保持されるため、並列レンダリングが可能です。

npx remotion studio src/remotion/index.ts --public-dir videos/{name}/
npx remotion render ... videos/{name}/output.mp4 --public-dir videos/{name}/ --video-bitrate 16M
npx remotion still ... videos/{name}/thumbnail.png --public-dir videos/{name}/

命名規則

• 動画名 {video-name}：小文字の英語をハイフンで区切ります（例：reference-manager-comparison）
• セクション名 {section}：小文字の英語をアンダースコアで区切り、[SECTION:xxx] に一致させます
• サムネイル（16:9 と 4:3 の両方が必須）：thumbnail_remotion_16x9.png + thumbnail_remotion_4x3.png（AI 生成の場合は _ai_ 接頭辞を使用）

---

追加リソース

必要に応じて読み込みます — 一度にすべて読み込まないでください：

ファイル	読み込むタイミング
references/workflow-script.md	ステップ 1〜4（トピック → スクリプト）＋実行モード（自動と対話型）
references/natural-narration.md	ステップ 4 のスクリプト執筆前に読み込んでください — 音声ナレーションの不自然さを避けるためのルール（使用禁止リスト、構成上の注意点、チェックリスト）
references/script-polish.md	ステップ 4 の草稿を書いた後に読み込んでください — 英語・中国語の修正前後のパターン 24 件、根拠の境界、品質評価基準を含む詳細な編集ツールキット
references/workflow-assets.md	ステップ 5、またはユーザーが画像・クリップを提供する場合、もしくはストックメディア／AI メディアを希望する場合
references/workflow-assets.md	コンポーネントライブラリを超えるデータチャート／インフォグラフィックのアニメーションが必要なセクション（Hyperframes による透明オーバーレイ）
references/workflow-production.md	ステップ 5.5〜9.5（公開情報の草稿 → サムネイル → TTS → Remotion → レンダリング → BGM ミキシング）
references/workflow-publish.md	ステップ 10〜11（公開情報、確認、ショート動画）
references/platform-matrix.md	プラットフォーム固有の動作（サムネイル、チャプター、アウトロ、公開情報、ショート動画）
references/design-guide.md	ステップ 8 の前に必ず読み込んでください — ビジュアルの最低基準、タイポグラフィ、アニメーションの安全性
references/visual-taste.md	ステップ 8 の前に design-guide と併せて読み込んでください — デザインの調整項目、デフォルト設定を避けるルール、ビジュアルモード、セクションのリズム
references/design-learning.md	ユーザーが参考動画／画像を提供する場合、またはスタイルプロファイルを管理する場合
references/troubleshooting.md	Azure の音声／スタイルを選ぶ場合、またはかすれた音声や不具合のある音声をデバッグする場合
references/troubleshooting.md	エラー発生時、スクリプト／CLI の調査時、またはユーザーが設定／BGM について質問した場合
templates/presets/kinetic-typography/	太字のテキストを主役にするプリセット（意見／議論／宣言の動画）

すべてのスクリプトには 1 つのディスパッチャーからアクセスできます — python3 ${SKILL_DIR}/scripts/cli.py --help から始めてください。すべてのルートとエンベロープエラーコードについては、references/troubleshooting.md を参照してください。

---

ユーザー設定

変更可能な状態（user_prefs.json、phonemes.json）は ~/.video-podcast-maker/ に保存されるため、スキルの更新で影響を受けません。初回実行時にスキルディレクトリから自動的に移行されます。「show preferences」を実行すると表示でき、「set X Y」を実行すると変更できます。コマンドの全一覧については、references/troubleshooting.md を参照してください。

---

トラブルシューティング

エラー、BGM のオプション、設定の学習、デザイン学習の問題については、references/troubleshooting.md を参照してください。