Pythonプログラム `add_notes_voice_pptx.py` を解析し、以下の項目について記述します。

---

### プログラム解析: `add_notes_voice_pptx.py`

#### 1) プログラムの動作

このプログラムは、PowerPointプレゼンテーション（PPTXファイル）のスライドノートからテキストを抽出し、そのテキストを音声合成（TTS: Text-to-Speech）によって音声ファイルに変換します。最終的に、生成された音声ファイルを元のプレゼンテーションのスライドに自動再生されるメディアオブジェクトとしてリンクします。

**主な機能:**
*   **PPTXノートからのテキスト抽出**: 指定されたPPTXファイル内の各スライドに記述されたノートの内容を読み取ります。
*   **外部テキストファイルからのノート追加/上書き (オプション)**: スライド番号と対応するテキストが記述された外部ファイルを読み込み、PPTXの一時ファイルにノート内容として書き込むことができます。これにより、元のPPTXにノートがない場合でも音声生成が可能です。
*   **音声合成 (Text-to-Speech)**: 以下のいずれかのTTSエンジンを使用して、ノートのテキストを音声ファイルに変換します。
    *   **pyttsx3**: Windowsに組み込まれているTTSエンジン（例: Microsoft Haruka Desktop）。オフラインで動作し、音声名と読み上げ速度（WPM）を指定できます。
    *   **AquesTalkPlayer**: 外部のAquesTalkPlayer.exe（株式会社AHS提供）を実行して音声ファイルを生成します。プリセット名と読み上げ速度を指定できます。
    *   **OpenAI TTS**: OpenAIのAPI（tts-1モデルなど）を利用して音声を生成します。APIキーとインターネット接続が必要です。ボイス名と追加指示を指定できます。
*   **音声ファイルのPPTXへのリンク**: 生成された音声ファイル（.wav または .mp3）を各スライドに埋め込み（リンク形式）、スライドショー開始時に自動的に再生されるように設定します。アイコンはスライドの右下隅に配置されます。
*   **利用可能な音声の一覧表示**: 各TTSエンジンで利用可能な音声名（またはプリセット名/ボイス名）をコマンドラインで一覧表示するモードがあります。
*   **Windows/PowerPoint依存**: 本プログラムは `win32com.client` を使用してPowerPointをCOMオブジェクトとして操作するため、Windows OSにPowerPointがインストールされている環境でしか動作しません。

**ワークフロー:**
1.  **引数解析**: コマンドライン引数から、実行モード、入力PPTX、出力PPTX、使用するTTSエンジンなどの設定を読み込みます。
2.  **モード選択**:
    *   `list` モード: 選択されたTTSエンジンの利用可能な音声名を一覧表示して終了します。
    *   `conv` モード: 以下の手順を実行します。
        *   **ノートの準備**: `--narration_txt` が指定されていれば、そのファイルからノートを読み込み、一時的なPPTXファイルにノートを書き込みます。指定されていなければ、`--input_path` のPPTXから既存のノートを読み取ります。
        *   **音声生成**: 準備されたノートテキストを基に、選択されたTTSエンジンで音声ファイルを生成し、指定されたディレクトリに保存します。
        *   **PPTX更新**: `--input_path` をコピーして `--output_path` を作成し、そこに生成された音声ファイルを自動再生設定付きでリンクします。
        *   **クリーンアップ**: 一時ファイルがあれば削除します。

#### 2) 必要な非標準ライブラリとインストールコマンドとインストール方法

本プログラムは以下の非標準ライブラリに依存しています。

1.  **`pyttsx3`**:
    *   機能: PythonからTTSエンジンを操作するためのライブラリ。Windows標準の音声合成エンジンを使用します。
    *   インストールコマンド:
        ```bash
        pip install pyttsx3
        ```
2.  **`pywin32`**:
    *   機能: `win32com.client` モジュールを提供し、PythonからWindows COMオブジェクト（PowerPointなど）を操作できるようにします。
    *   インストールコマンド:
        ```bash
        pip install pywin32
        ```
    *   **インストール後**: `pywin32` インストール後にCOMオブジェクトが正しく登録されるよう、以下のコマンドを実行することが推奨されます。
        ```bash
        python -m win32com.client.makepy -install
        # または
        python -m post_install -install
        ```
3.  **`openai`**:
    *   機能: OpenAIのAPIにアクセスするためのライブラリ。OpenAI TTSエンジンを使用する場合に必要です。
    *   インストールコマンド:
        ```bash
        pip install openai
        ```
    *   **設定**: OpenAI APIを使用するには、環境変数 `OPENAI_API_KEY` にAPIキーを設定する必要があります。
        *   Windowsの場合 (コマンドプロンプト): `set OPENAI_API_KEY="your_api_key_here"`
        *   Linux/macOSの場合 (Bash/Zsh): `export OPENAI_API_KEY="your_api_key_here"`
        または、Pythonコード内で `openai.api_key = "your_api_key_here"` のように設定することも可能です。
4.  **`pydub`**:
    *   機能: 音声ファイルを操作するためのライブラリ。このプログラムの現在の実装では直接使用されていませんが、`try-except` ブロックに含まれているため、将来的な拡張や特定の音声フォーマット変換が必要になった場合に備えてインストールしておくことが推奨されます。
    *   インストールコマンド:
        ```bash
        pip install pydub
        ```
    *   **注意**: `pydub` でMP3などの多くのフォーマットを扱うには、別途 [FFmpeg](https://ffmpeg.org/download.html) をダウンロードし、その実行ファイルがシステムPATHに通っている必要があります。

#### 3) 必要な入力ファイル

**すべてのモード共通:**
*   なし（`list` モードの場合）

**`conv` モードの場合:**
1.  **`--input_path` (-i)**:
    *   元のPowerPointプレゼンテーションファイル (`.pptx` または `.ppt`) のパス。必須。
    *   例: `my_presentation.pptx`
2.  **`--narration_txt` (-t)**: (オプション)
    *   スライドごとのノート内容を記述したテキストファイル。
    *   このファイルが存在する場合、指定されたPPTXの一時ファイルにノートとして書き込まれてから音声が生成されます。
    *   ファイル形式は以下の通りです。
        ```
        # Slide 1
        これはスライド1のノートです。
        複数行にわたるテキストも記述できます。

        # Slide 2
        スライド2の重要なポイントです。
        ```
    *   例: `narration_notes.txt`
3.  **`--aqt_path`**: (AquesTalkPlayer を `--tts aquestalkplayer` で使用する場合のみ必須)
    *   AquesTalkPlayerの実行ファイル (`AquesTalkPlayer.exe`) へのパス。
    *   例: `C:\Program Files (x86)\AquesTalkPlayer\AquesTalkPlayer.exe`

#### 4) 実行後に生成される出力ファイル

1.  **音声ファイル**:
    *   **場所**: `--audio_dir` 引数で指定されたディレクトリ（デフォルト: `audio_output/`）内に生成されます。
    *   **ファイル名**: `slide<スライド番号>.wav` (pyttsx3, AquesTalkPlayer の場合) または `slide<スライド番号>.mp3` (OpenAI の場合)。
    *   例: `audio_output/slide1.wav`, `audio_output/slide2.mp3`
2.  **出力PPTXファイル**:
    *   **場所**: `--output_path` 引数で指定されたパスに生成されます。
    *   **内容**: `--input_path` のPPTXをコピーし、生成された音声ファイルが各スライドに自動再生設定でリンクされています。
    *   例: `my_presentation_with_voice.pptx`
3.  **一時PPTXファイル**: (`--narration_txt` が指定された場合のみ)
    *   **ファイル名**: `temp_notes_added.pptx`
    *   **内容**: `--input_path` をコピーし、`--narration_txt` の内容がノートとして書き込まれた一時ファイル。
    *   **処理**: プログラム終了時に自動的に削除されます。

#### 5) コマンドラインでの使用例 (Usage)

`add_notes_voice_pptx.py` を実行する際のコマンドラインでの使用例をいくつか示します。

**A. 利用可能な音声の一覧表示 (`list` モード)**

1.  **pyttsx3 で利用可能な音声を表示:**
    ```bash
    python add_notes_voice_pptx.py --mode list --tts pyttsx3
    ```
2.  **AquesTalkPlayer で利用可能なプリセットを表示:**
    ```bash
    python add_notes_voice_pptx.py --mode list --tts aquestalkplayer
    ```
3.  **OpenAI で利用可能なボイスを表示:**
    ```bash
    python add_notes_voice_pptx.py --mode list --tts openai
    ```

**B. PPTXに音声ファイルをリンク (`conv` モード)**

`input.pptx` を元に、`narration.txt` のノートを適用し、`output_with_voice.pptx` を生成する例を基本とします。音声ファイルは `audio_output` ディレクトリに保存されます。

**`narration.txt` の例:**
```
# Slide 1
はじめに、このプレゼンテーションの目的について説明します。

# Slide 2
次に、主要な機能と利点について詳しく見ていきましょう。
```

1.  **`pyttsx3` を使用して音声を追加 (デフォルト設定):**
    *   Windows標準のHaruka音声、デフォルト速度で生成。
    ```bash
    python add_notes_voice_pptx.py --mode conv ^
        --input_path input.pptx ^
        --narration_txt narration.txt ^
        --output_path output_with_voice_pyttsx3.pptx ^
        --audio_dir audio_output_pyttsx3 ^
        --tts pyttsx3
    ```

2.  **`pyttsx3` を使用して音声を追加 (音声と速度を指定):**
    *   Microsoft David音声、速度180WPMで生成。
    ```bash
    python add_notes_voice_pptx.py --mode conv ^
        --input_path input.pptx ^
        --narration_txt narration.txt ^
        --output_path output_with_voice_pyttsx3_david.pptx ^
        --audio_dir audio_output_pyttsx3_david ^
        --tts pyttsx3 ^
        --voice "Microsoft David Desktop" ^
        --speak_rate 180
    ```

3.  **`AquesTalkPlayer` を使用して音声を追加:**
    *   `AquesTalkPlayer.exe` へのパスとプリセット名を指定。
    ```bash
    python add_notes_voice_pptx.py --mode conv ^
        --input_path input.pptx ^
        --narration_txt narration.txt ^
        --output_path output_with_voice_aqt.pptx ^
        --audio_dir audio_output_aqt ^
        --tts aquestalkplayer ^
        --aqt_path "C:\Program Files (x86)\AquesTalkPlayer\AquesTalkPlayer.exe" ^
        --aqt_preset "まりさ" ^
        --speak_rate 150
    ```

4.  **`OpenAI` を使用して音声を追加:**
    *   OpenAI APIキーが環境変数 `OPENAI_API_KEY` に設定されている必要があります。
    ```bash
    python add_notes_voice_pptx.py --mode conv ^
        --input_path input.pptx ^
        --narration_txt narration.txt ^
        --output_path output_with_voice_openai.pptx ^
        --audio_dir audio_output_openai ^
        --tts openai ^
        --openai_voice "nova" ^
        --openai_inst "落ち着いたトーンで話してください。"
    ```

5.  **既存のPPTXノートから直接音声を生成 (外部テキストファイルなし):**
    *   `input_with_notes.pptx` に既にノートが記述されている場合。
    ```bash
    python add_notes_voice_pptx.py --mode conv ^
        --input_path input_with_notes.pptx ^
        --output_path output_from_existing_notes.pptx ^
        --audio_dir audio_output_existing ^
        --tts pyttsx3
    ```

**注:**
*   Windowsのコマンドプロンプトやバッチファイルでは、行末の `^` はコマンドの継続を示します。Bash/Zshなどでは `\` を使用します。
*   ファイルパスにスペースが含まれる場合は、パス全体を二重引用符で囲んでください (例: `"C:\My Documents\input.pptx"`)。
*   OpenAI TTSを使用する場合、`OPENAI_API_KEY` が正しく設定されていることを確認してください。