video-podcast-maker

必須：最初に Remotion Best Practices を読み込んでください

このスキルは 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> を使用すること、そして音声をマスタークロックとして扱うこと。

ビデオポッドキャストメーカー

トピックから 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"

更新はプラグインマーケットプレイス（/plugin update）を通じて行います。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 headless shell がダウンロードされます（プロジェクトごとに初回のみ）。ユーザーが前回の動画で使ったプロジェクトを持っている場合は、それを使用してください。新規プロジェクトが必要な場合は、ステップ 1～4（トピックの調査とスクリプトの作成）の間に、バックグラウンドで npm install を実行してください。

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

TTS エンジン — 11 種類すべてのバックエンド（TTS_BACKEND=edge|azure|cosyvoice|doubao|tencent|baidu|minimax|xunfei|elevenlabs|openai|google）は、ttscn コンポーネントスキルを通じて音声を合成します。このスキルは必須です。~/.claude/skills/ttscn にインストールするか、ルートディレクトリを TTSCN_HOME に指定してください（Agents365-ai/ttsCN）。各バックエンドで必要なのは、それぞれの API キーのみです（Edge では不要）。check_prereqs.py がインストール状況と API キーの両方を検証します。

Pi ユーザー向け： ttscn は Pi に同梱されていません。Agents365-ai/ttsCN を Pi スキルとしてインストールする（skills/ttscn/ の構成が自動検出されます）か、TTSCN_HOME を設定してください。check_prereqs.py が TTS の前にインストール状況を検証します。

デザイン学習のショートカット：ユーザーが参考動画／画像を提示した場合、またはスタイルプロファイルの保存／一覧表示／削除を依頼した場合は、以下のワークフローを実行する代わりに 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 を参照してください。