高度な使い方と内部構造

このセクションでは、差分ビルドシステム、ステータスファイルの直接操作、トラブルシューティングなど、パワーユーザー向けの機能を解説します。

差分ビルドシステム

動画生成には時間がかかり、TTS API のコストもかかります。そのため、slidemovie は 差分ビルド（インクリメンタルビルド） を行うように設計されています。

仕組み

ツールはソースディレクトリに status.json というファイルを保持します。このファイルには以下が記録されています：

  • 各スライドの Markdown コンテンツ（原稿）のハッシュ値
  • PowerPoint ファイルのハッシュ値
  • 生成された音声・動画ファイルのハッシュ値
  • 使用された設定（解像度、FPS）

ロジック

slidemovie -v を実行したとき：

  1. PPTX の確認: PPTX ファイルが前回実行時から変更されていなければ、画像の再変換をスキップします。
  2. 音声の確認: 各スライドについて、現在の ::: notes のテキストと記録されたハッシュを比較します。
    • 一致: 既存の WAV ファイルを再利用します。
    • 不一致: そのスライドについてのみ、AI API を呼び出して音声を再生成します。
  3. 動画の確認: 画像と音声に変更がなければ、そのスライドの MP4 生成をスキップします。

これにより、例えばスライド #10 の誤字を修正して再ビルドする場合でも、スライド #1〜#9 の TTS コストを払うことなく、数秒で動画全体を再生成できます。

状態ファイル (status.json) の管理

status.json は単なるキャッシュではなく、生成挙動を細かく制御するために編集することも可能です。

スライドごとのカスタムプロンプト

config.json の prompt は TTS エンジン全体へのシステム指示を設定しますが、status.json を編集することで、特定のスライドだけに個別の追加指示を与えることができます。

  1. ツールを一度実行して、初期の status.json を生成させます。
  2. status.json を開き、"slides" オブジェクトの中から対象のスライドを探します。
  3. "audio" セクション内の "additional_prompt" フィールドを見つけます。
  4. 追加したい指示を文字列として入力します。

status.json の記述例:

"myproject-05": {
  "title": "導入",
  "audio": {
    "status": "generated",
    "wav_file": "myproject-05.wav",
    "additional_prompt": "この文は興奮した口調で話してください。"
  }
}
  • 効果: このスライドの音声を再生成する際、TTS エンジンには 全体プロンプト + 追加プロンプト + スライドの原稿 が送信されます。
  • 再生成のトリガー: additional_prompt を編集した後、再生成をトリガーする必要があります。最も簡単な方法は、status.json 内の "status" の値を "generated" から別の値（例: "missing" や "update"）に変更することです。

サブプロジェクト（フォルダ管理）

シリーズ動画（例：オンラインコース）を作成する場合、--sub オプションを使うと便利です。

ディレクトリ構成:

MyCourse/               <-- 親プロジェクトルート
├── config.json         <-- 共通設定
├── Section01/          <-- サブプロジェクト 1
│   ├── Section01.md
│   └── Section01.pptx
└── Section02/          <-- サブプロジェクト 2
    ├── Section02.md
    └── Section02.pptx

コマンド:

# セクション 1 をビルド
slidemovie MyCourse --sub Section01 -v

# セクション 2 をビルド
slidemovie MyCourse --sub Section02 -v

出力ファイルは、出力ディレクトリ内で整理されて保存されます： movie/MyCourse/Section01/Section01.mp4

トラブルシューティング

“Movie class is not defined”

  • パッケージが正しくインストールされているか確認してください。
  • Python スクリプトから呼び出している場合、import slidemovie がされているか確認してください。

音ズレが発生する / 音声と映像が合わない

  • 原因: PowerPoint でスライドを削除したり、順番を入れ替えたりしていませんか？
  • 修正: slidemovie はスライドの「数」と「順番」が一致していることを前提としています。
    1. 生成された movie/{project}/slide_*.png ファイルを確認してください。
    2. Markdown のスライド数と、PPTX のスライド数が一致しているか確認してください。
    3. 同期が崩れてしまった場合、最も安全な方法は movie/{project} フォルダを削除して、再度 -v を実行して再ビルドすることです。

“build_config inconsistency detected”

  • 原因: プロジェクトを一度実行した後に、config.json で screen_size や video_fps を変更しました。
  • 修正: 一つのプロジェクト内で異なる解像度を混在させることはできません。
    1. ソースディレクトリ内の status.json を削除してください。
    2. 出力ディレクトリ movie/{project} を削除してください。
    3. 再ビルドを実行してください。

デバッグモード

ツールがクラッシュしたり、予期しない挙動をする場合は、--debug を付けて実行してください：

slidemovie myproject -v --debug

これにより、以下のような詳細情報が表示されます：

  • どのファイルがスキップされたか
  • FFmpeg コマンドの出力結果