video-engine を実務で限界まで使い倒すためのカスタマイズ知識を網羅的に補足します。
settings.yaml 全項目リファレンス
動画全体の挙動を支配する settings.yaml に定義されている、実在する全29個の設定項目を完全網羅。
画像をどのような手段で調達するかを指定します。選択肢は "manual"（手動生成）、"api"（画像APIで自動生成）、"external"（外部ツールでの生成・手動停止）の3つです。
変更すべきケース： OpenAI APIキーを使用し、ChatGPTを立ち上げずに画像を自動生成させたい場合は "api"、外部の高度な生成ツールで画像を作りつつ、動画の自動組み立て時（automation=full_auto）でも画像工程だけは一旦手動で止めたい場合は "external" を指定します。
使用する映像素材の定義を設定します。選択肢は "image_only"（静止画のみ）と "with_video"（動画アセットの混在）です。
変更すべきケース： 静止画のズームスライドだけでなく、生成AIで作った動画クリップや実機動画を差し挟んだマルチマテリアルな構成にする場合は "with_video" に変更します。
動画素材の生成ソースを指定します。選択肢は "ffmpeg_motion"、"video_api"（未整備）、"both" です。
変更すべきケース： 通常は既定値のまま運用します。モーションスクリプトの連携範囲を拡張する際の設定値となります。
動画生成工程の自動進行レベルを設定します。選択肢は "semi_auto"（半自動・工程ごとに人間がチェックする）と "full_auto"（全自動・1回で動画完成まで進む）です。
変更すべきケース： 台本やシーンごとのプロンプト設計を人間が徹底的にチェックして手動で次の工程へ進める場合は "semi_auto" のままとし、画像の自動API生成とアセンブラを連動させ、1本のコマンドで一気に最終動画まで出力させたい場合は "full_auto" に変更します。
ナレーション音声の合成に用いるTTSモデルを指定します。現在は "gemini_3_1" （Gemini 3.1 TTS）に対応しています。
変更すべきケース： 既定値のままで非常に高品質かつ自然な日本語音声合成を利用することができます。
ナレーション音声および組み立てられる動画全体の最終再生速度（倍速）を設定します（単位なし数値）。等速でアセンブルされた後に一括倍速処理が実行されます。
変更すべきケース： 動画を標準速度でじっくり解説させたい場合は 1.0 に、ショート動画向けに極限までテンポを高め、離脱を防ぐ構成にする場合は 1.5〜1.8 の範囲で調整します。
書き出される動画のフレームレート（1秒あたりのコマ数）を指定します。
変更すべきケース： 等速ズームパンの滑らかさやテロップのカクつきを抑えるためには 60 推奨ですが、マシンスペックが低くレンダリング速度を少しでも稼ぎたい場合は 30 に下げます。
生成されるすべての動画プロジェクトの成果物と各種アセットを一括保存するローカルフォルダの絶対パスです。
変更すべきケース： 自身の開発環境やプロジェクト管理用ディレクトリパスに必ず書き換えてください。※Windowsパス内の区切り文字は必ず / または \ に変更してください。
動画の構成、台本演出、およびビジュアルプロンプトの基礎スタイルを選択します。
変更すべきケース： AIやテクノロジーの解説動画なら "tech_explainer"、最新ニュースの切り出しなら "breaking_ai_news"、画面デモなら "practical_demo" 等、目指す動画ジャンルに応じて設定値リストから選択します。
生成される画像の統一的な画風（プリセットIDまたは自由な画風の指示テキスト）を指定します。空文字の場合はデフォルトのテック風デザインになります。
変更すべきケース： 劇画風（"gekiga"）や、水彩アニメ風（"ghibli_water"）、シネマティック（"cinematic"）など、チャンネル固有の世界観で統一されたイラスト・画像を安定して生成したい場合に指定します。
画像を生成する際、ユーザーがチャットでアップロードしたキャラクターなどの「参照画像（容姿）」をプロンプトで優先・継承させるかどうかの設定です。
変更すべきケース： 特定の語り手キャラクターなどを固定せず、一般的な風景やシステム的な図解スライド画像のみで動画を構成したい場合は false に変更します。
画像生成の工程へ進む際、参照画像が提供されていることを「必須条件」にするかどうかのフラグです。
変更すべきケース： 参照画像の準備なしで、テキストプロンプトのみからスピーディーに画像を直接生成させる場合は false に変更します。
GPT Image 2へ1回で同時指示できる画像の最大同時生成バッチ枚数です（総枚数の制限ではありません）。
変更すべきケース： チャットGPTの送信制限やコンテキストオーバーを回避するため、画像の同時指示数を抑える場合に数値を調整します。
テロップ焼き込みに使用するTrueTypeフォント（ttf）ファイルのパス（相対パス）です。
変更すべきケース： チャンネルのトンマナに合わせて、明朝体や丸ゴシックといった異なるフォントでテロップを出力したい場合に、そのフォントファイルを配置し、パスを指定します。
動画レンダラーに渡すフォントの論理ファミリー名（システム上のフォント登録名）です。
変更すべきケース： caption_font_file で登録したフォントファイルの正式なファミリー名を設定する必要がある場合、その文字列表記に合わせます。
書き出す完成動画に、BGMアセットを自動でバックグラウンド合成するかどうかの切り替えです。
変更すべきケース： ナレーション（ボイス）のみで出力し、後段の別の編集作業でBGMを乗せたい場合は false に変更します。
自動合成する既定のBGM音声ファイルのパス（相対パス）です。
変更すべきケース： 自身の動画ジャンルやチャンネルコンセプトに沿った独自のBGM音源（mp3/wav）を自動合成させたい場合に書き換えます。
BGMの合成音量比率（ナレーションを邪魔しないレベルの係数）です。既定の 0.05 は音量比率として約-26dBを意味します。
変更すべきケース： 使用するBGM音源の元音量が大きすぎたり、ナレーションを聞き取りやすくしたい場合は 0.02 等に下げ、BGMをもっと前に出したい場合は 0.08 程度に調整します。
テロップレンダラーのエンジン方式を指定します。現在は安定動作に最適化された "drawtext_textfile" が使用されます。
変更すべきケース： 通常は既定値のまま使用します。
縦型動画（9:16、1080×1920）の画面幅を基準とした、テロップの基本フォントサイズ（ピクセル指定、pxなどの単位は付けない）です。
変更すべきケース： スマホ画面内で字幕を目立たせるために文字サイズをさらに大きくしたい場合は 120 などに引き上げ、より小さく控えめでスマートなテロップにしたい場合は 80 程度に縮小します。
視認性を高めるためにテロップ文字の背面に適用される黒い縁取り（フチ）の太さ（ピクセル指定、pxなし）です。
変更すべきケース： 明るい白背景のスライド画像の上でも字幕の視認性を極めて強固に維持したい場合は 10 に引き上げ、すっきりとした細縁デザインにしたい場合は 4〜5 に下げます。
画面下端からテロップ表示位置までの縦方向の距離（ピクセル指定、pxなし）です。
変更すべきケース： TikTokやYouTubeショートの「アカウント名や投稿者コメント」との被りを避けるためにテロップ位置を引き上げたい場合は 200 以上に、中央に寄せるダイナミックな配置にする場合は数値を大きく調整します。
テロップが1行に収まる全角換算の目安文字数です。これを超える場合は自動改行プロトコルが作動します。
変更すべきケース： 画面の狭い縦型動画で、絶対に左右端へのはみ出しや泣き別れを防止する安全マージンを取る場合は 12〜13 に制限します。
静止画をズームさせたりパンさせたりするカメラアニメーション効果（Ken Burns）を適用するかどうかのフラグです。
変更すべきケース： カメラのズームイン・アウトなどの動きを完全に排除し、静止画スライドとしてきっちりピタッと静止させたい場合は false に変更します。
適用するモーションのスタイルです。現在は "ken_burns" 方式が使用されます。
変更すべきケース： 既定値のまま使用します。
映像シーンの切り替え時のトランジション（切り替え効果）を指定します。選択肢は "crossfade" または "none"（カット編集）です。
変更すべきケース： シーン切り替えをフワッとさせず、パッと切り替えてリズムを出したい場合は "none" に変更します。※タイムラインの圧縮が生じ後半がずれていく xfade フィルターの使用は禁止されています。
切り替えトランジションのフェード秒数を指定します（単位なし数値）。
変更すべきケース： シーンがパッと切り替わる感触に近づけるためにフェードを短くしたい場合は 0.1 程度に、柔らかく重なる演出にする場合は 0.4 秒程度に引き上げます。
音声が発話される前に、テロップを画面上に先行して表示させておく時間（秒数）を指定します。
変更すべきケース： 倍速再生（speed: 1.5など）で最終動画が圧縮された際に、体感されるテロップ表示の遅延を防ぐために 0.3 等に変更します。これにより実効0.2秒テロップが先行し、滑らかで自然な読了感になります。
シーン構成表の「演出意図」に書かれた文脈（ズーム・スライド・パン等）を自動判定し、意味と連動したカメラワークを適用する機能です。
変更すべきケース： 演出の自動連動を行わず、単純な機械的ローテーションによるカメラワークのみを適用する場合は false に変更します。
ジャンル別Config設定例
実在するキーと正しいデータ型（数値は単位なし、文字列は指定プリセット）を適用した、そのままコピーして使える実運用設定例です。
OpenAI APIを連動させて画像を自動生成し、BGMをしっかり乗せつつ、1.5倍速による超高密度なテンポ感で一気にアセンブルして出力する自動化構成です。
# 完全自動テックAIニュース構成
image_engine: "api"
automation: "full_auto"
bgm_enabled: true
video_style: "breaking_ai_news"
speed: 1.5
fps: 60
bgm_volume: 0.05
image_motion_enabled: true
semantic_motion_enabled: true
caption_font_file: "fonts/NotoSansJP-Black.ttf"
caption_font_name: "Noto Sans JP Black"
bgm_asset_file: "assets/bgm/tech_short_bgm_128bpm.mp3"
telop_font_size: 104
telop_border_width: 8
telop_bottom_px: 150
telop_max_line: 15
image_transition: "crossfade"
image_transition_duration: 0.25
telop_lead_sec: 0.3デモ画面やスライド画像を人間が厳密に確認・配置（画像は手動）し、ナレーションをはっきり聞かせるためにBGMを排除。倍速によるズレを防ぐため、テロップを0.3秒先行させる設定です。
# 実機デモ・解説構成
image_engine: "manual"
automation: "semi_auto"
bgm_enabled: false
video_style: "practical_demo"
speed: 1.2
fps: 60
telop_lead_sec: 0.3
image_motion_enabled: true
semantic_motion_enabled: true
caption_font_file: "fonts/NotoSansJP-Black.ttf"
caption_font_name: "Noto Sans JP Black"
telop_font_size: 96
telop_border_width: 7
telop_bottom_px: 160
telop_max_line: 14
image_transition: "crossfade"
image_transition_duration: 0.2
reference_enabled: false
reference_required: false動画全体のビジュアルを「劇画風」に固定し、画像工程は外部ツールで別途作成。動き（モーション）を完全に排除して美しい静止画と小さなテロップで伝えるコンセプト構成です。
# 劇画タッチミニマル構成
image_engine: "external"
automation: "semi_auto"
video_style: "minimal_caption"
art_style: "gekiga"
bgm_enabled: true
bgm_volume: 0.02
image_motion_enabled: false
semantic_motion_enabled: false
fps: 30
speed: 1.0
caption_font_file: "fonts/NotoSansJP-Black.ttf"
caption_font_name: "Noto Sans JP Black"
bgm_asset_file: "assets/bgm/tech_short_bgm_128bpm.mp3"
telop_font_size: 80
telop_border_width: 5
telop_bottom_px: 130
telop_max_line: 16
image_transition: "none"
reference_enabled: true
reference_required: trueよくあるエラーと対処
スキル SETUP.md および KNOWN_MISTAKES.md の実例に基づいて検証された、環境構築や実運用で必ず役に立つトラブル対処法です。
【症状】 Remotionによる組み立て（STEP 8）でエラーが発生し、レンダリング処理が異常停止する。
【原因】 自身のPC環境のNode.jsのバージョンが、Remotionの要件を満たしていない。
1. ターミナルで
node --version を実行し、現在のバージョンを確認します。2.
SETUP.md の動作要件に基づき、Node.js LTS v20以上 をPCへ必ず再インストールしてください。3. バージョン更新後、
remotion/ フォルダ内で npm install を再実行して動作確認を行います。【症状】 起動時（STEP 0）や実行中で「ディレクトリの検出エラー」や「パースエラー」が発生しエージェントが停止する。
【原因】 Windowsのフォルダパスをコピーした際、settings.yaml 内の projects_root の区切り文字にバックスラッシュ \ 1本をそのまま直書きしたことで、YAMLの構文解析で「エスケープ文字エラー」として処理されてしまう。
settings.yaml をエディタで開き、パスの区切りをすべてフォワードスラッシュ（例: "D:/Okihiro Forge/02_Workspace/_Video_Content_Production/_Projects"）にするか、またはバックスラッシュ2本（例: "D:\\Okihiro Forge\\..."）に完全に置換して再保存します。【症状】 動画の冒頭はぴったり合っているのに、後半に進むほどテロップが音声より遅れていき、最後は最大1.75秒もずれて崩壊する。
【原因】 画像トランジションに xfade フィルターを使用すると、重なり（オーバーラップ）の発生により全体のタイムライン尺が fade_duration × (画像数 - 1) 秒分だけ収縮します。テロップ表示時間（SRT）は元のタイムスタンプのままのため、後半ほど累積的なズレが拡大していた（KNOWN_MISTAKES #1 発生事象）。
settings.yaml にて、必ず image_transition: "crossfade"（または "none"）を使用してください。この設定によりタイムラインの無駄な圧縮を防ぎ、元のSRTタイミングがそのまま寸分の狂いもなく完全に音声と同期されます。xfade は使用禁止です。【症状】 ナレーション音声合成（STEP 5）や画像自動生成（STEP 3）で API Key の無効エラーが表示されて進まない。
【原因】 APIキーが正しく環境へ渡されていない、またはチャットログへの漏洩防止ルールに反した記述をしている。
絶対にチャット上にAPIキーをそのまま貼り付けないでください。スキルフォルダ配下の
secrets/api_keys_gemini.txt （Geminiキー）または secrets/api_keys_openai.txt （OpenAIキー）の所定ファイル内に、APIキー文字列のみを1行で記述し、エディタで保存してください。エージェントはこれらを安全に自動読み込みして認証を行います。セットアップ〜呼び出しの典型的な会話例
SETUP.md および SKILL.md の STEP 0 に定義された、ペルソナヒアリングからMODE選択までの完璧な初期動作シーケンスです。
・Python仮想環境（.venv）を確認：OK
・ライブラリ依存関係：OK
・Remotion npmパッケージ：OK
・Gemini APIキー（secrets/api_keys_gemini.txt）：読み込み完了
チャンネルの恒久ペルソナ設定を行います。今回の動画の個別タイトルではなく、このチャンネル全体の基本方針となります。二度聞きを避けるため、1問ずつ質問させていただきます。
Q1. チャンネルの「ジャンル傾向」を教えてください。（例: AIツール紹介、Google AI活用、生成AIニュース解説など）
Q2. 動画の主な「ターゲット層」を教えてください。（例: 生成AIを仕事で使いこなしたいビジネスパーソン、Google AIユーザーなど）
Q3. チャンネルの「語りスタイル」を教えてください。（例: フレンドリー、実務寄り、やさしく解説など）
Q4. ナレーションの「一人称」と「語尾」を教えてください。（例: 僕/ですます、うち/ですます、私/である調 など）
Q5. 動画の「基本尺」を教えてください。（例: 30秒、45秒、60秒など）
config/persona.yaml に保存しました。次回以降は保存データから自動で読み込むため、この質問はスキップされます。現在のシステム設定構成とモード選択メニューを表示します。
【現在のシステム構成】
・画像エンジン: manual
・素材タイプ: image_only
・動画ソース: ffmpeg_motion
・自動化: semi_auto
・音声: gemini_3_1
・速度: 1.5
・保存先: D:/Okihiro Forge/02_Workspace/_Video_Content_Production/_Projects
・動画スタイル: tech_explainer
・画風: （空＝指定なし）
・参照画像優先: true
・参照画像必須: true
・画像バッチ上限: 10
・字幕フォント: fonts/NotoSansJP-Black.ttf
・BGM合成: true
・BGMファイル: assets/bgm/tech_short_bgm_128bpm.mp3
・BGM音量: 0.05
実行するモードを番号で選択してください。
1 台本を作る / 2 映像素材を作る / 3 音声と組み立て / 4 全部通し
D:/Okihiro Forge/02_Workspace/_Video_Content_Production/_Projects に設定しました。STEP 1（台本生成）に移ります。今回の動画の「題材」または「切り口」を教えてください。