コマンドラインインターフェース (CLI) リファレンス

slidemovie コマンドは、すべての操作の入り口となります。

基本的な構文

slidemovie [プロジェクト名] [オプション]

位置引数

  • PROJECT_NAME (必須)
    • プロジェクトの識別子（名前）です。
    • ツールはソースディレクトリ内の {PROJECT_NAME}.md を探します。
    • サブプロジェクトモード (--sub) を使用する場合、この引数は 親フォルダ名 （出力の分類用）を指定します。

オプション

モード制御フラグ (少なくとも1つは必須)

  • -p, --pptx
    • 動作: ソースとなる Markdown ファイルを PowerPoint (.pptx) ファイルに変換します。
    • 用途: 初期ドラフトの作成、またはスライドテキストの更新。
    • 注意: 既存の PPTX ファイルがある場合、上書きされます（デザイン済みファイルがある場合は注意が必要です）。
  • -v, --video
    • 動作: 完全な動画をビルドします。
    • 処理ステップ:
      1. Markdown のノートから音声 (TTS) を生成。
      2. PPTX ファイルから画像をエクスポート（--pdf 指定時は PDF ファイルから）。
      3. 音声と画像を結合してスライドごとのクリップを作成。
      4. すべてのクリップを結合して最終的な動画ファイルを作成。
    • 用途: 最終的な動画制作。
    • 注意: スライド画像は screen_size に正規化されます。ソースのアスペクト比が異なる場合、アスペクト比を保って内接縮小し、不足分を image_pad_color で均等な余白（レターボックス／ピラーボックス）として付与します。
  • --pdf
    • 動作: 画像のソースとして PowerPoint ファイルの代わりに PDF ファイル（{PROJECT_NAME}.pdf）を使用します。
    • 用途: スライドが既に PDF として用意されている場合（他ツールからの書き出しなど）。-v と併用して PDF から直接動画をビルドします。
    • 注意: --video 実行時の画像生成にのみ影響します。--pptx（-p）のドラフト作成には影響しません。Markdown ノートからの音声生成は従来どおりです。

パス・プロジェクト構造

  • -s DIR, --source-dir DIR
    • デフォルト: . (カレントディレクトリ)
    • 説明: ソースファイル (.md, .pptx) が存在するディレクトリを指定します。
    • 例: slidemovie myproject -s ./docs (./docs/myproject.md を探しに行きます)
  • --sub SUB_NAME
    • 説明: 階層構造（サブプロジェクト）モード を有効にします。
    • 挙動:
      • PROJECT_NAME は出力先の親フォルダ名として使用されます。
      • SUB_NAME が 子 フォルダ（サブプロジェクト）になります。
      • 入力ソース: {Child}/{Child}.md
      • 出力動画: movie/{Parent}/{Child}/{Child}.mp4
    • 例: slidemovie Season1 --sub Episode1
  • -o DIR, --output-root DIR
    • デフォルト: ./movie (ソースディレクトリからの相対パス)
    • 説明: 生成されたすべての動画成果物を出力するルートディレクトリを指定します。
    • 注意: 設定ファイルの output_root でも指定可能です。指定したディレクトリが存在しない場合、output_root が明示的に指定されていればエラーとなり、未指定の場合はデフォルトのディレクトリを自動的に作成します。
  • -f NAME, --filename NAME
    • デフォルト: プロジェクトIDと同じ。
    • 説明: 最終的に出力される .mp4 ファイルの名前（拡張子なし）を指定します。

TTS 設定の上書き (一時的)

これらのオプションは、config.json の設定を 今回の実行に限り 上書きします。

  • --tts-provider NAME: 例: google, openai, azure, voicevox
  • --tts-model NAME: 例: gpt-4o-mini-tts, gemini-3.1-flash-tts-preview（azure・voicevox では不要）
  • --tts-voice NAME: 例: cedar, charon。voicevox の場合は整数の話者 style ID（例: 3）
  • --tts-voicevox-url URL: VOICEVOX エンジンの URL（デフォルト http://127.0.0.1:50021）。--tts-provider voicevox のときのみ使用
  • --prompt TEXT: TTS生成時のシステムプロンプトを上書きし、プロンプトの使用を有効にします (tts_use_prompt=True)。
  • --no-prompt: システムプロンプトの使用を無効にします (tts_use_prompt=False)。
  • --prompt-separator STR: スタイルプロンプトと読み上げ本文の間に挿入する区切り文字列。例: "\n\n## 原稿\n"（プロンプトと原稿の区切り を参照）。デフォルトは空文字列。
  • --chunk-size N: TTS の 1 チャンクあたりの最大文字数。指定すると長文ナレーションの自動分割が有効になります（長文ナレーション を参照）。
  • --split-chars STR: 分割候補となる文字列（デフォルト: 。．.!！?？ と改行）。
  • --chunk-overflow {extend,error}: --chunk-size 以内に分割候補が見つからない場合の挙動。extend は次の候補まで読み進め、error はエラーで停止します。

デバッグ

  • --debug
    • 詳細なログ出力を有効にします (INFO/DEBUG レベル)。
    • スキップされたタスクや内部処理の詳細を表示します。
    • FFmpeg のログレベルを info に設定します。

実行例

1. 基本的なドラフト生成:

slidemovie tutorial -p

2. 特定のフォルダにあるプロジェクトを動画化:

slidemovie tutorial -s ./content -v

3. サブプロジェクトを OpenAI の音声でビルド:

slidemovie Course101 --sub Lesson01 -v --tts-provider openai --tts-model gpt-4o-mini-tts --no-prompt --tts-voice alloy

4. VOICEVOX でビルド（ローカルエンジンを起動しておくこと）:

slidemovie tutorial -v --tts-provider voicevox --tts-voice 3 --no-prompt