Pythonスクリプト `add_notes_pptx.py` の解析結果を以下に示します。

---

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

このPythonプログラムは、PowerPointファイル（.pptx）のノート機能を拡張するためのツールです。大きく分けて2つのモードで動作します。

1.  **`add` モード（デフォルト）**:
    *   各スライドのノートページに記述されたテキストを読み込みます。
    *   そのノートテキストを、スライドの下部に半透明のテキストボックス（いわゆる「字幕」のような表示）として追加します。
    *   追加される字幕ボックスのフォント、文字色、背景色、透明度、位置、サイズなどをコマンドライン引数で細かく設定できます。
    *   これにより、プレゼンテーション中にノートの内容を視覚的に表示させたい場合に便利です。

2.  **`replace` モード**:
    *   スライド内のテキストに含まれる `{{key}}` 形式のプレースホルダーを、指定された値で置換します。
    *   置換する値は、以下の2つのソースから取得されます。
        *   コマンドライン引数 `--replace` で指定されたTOML風の `key=value` ファイル。
        *   各スライドのノートテキスト（これは `{{supertitle}}` というキーとして扱われ、上記ファイルで `supertitle` が指定されていてもスライドノートの内容が優先されます）。
    *   この置換処理は、元のテキストの書式やアニメーションを壊さない「部分置換」として行われます。
    *   グループ化された図形内や表のセル内のテキストも置換対象となります。
    *   テンプレートとなるPowerPointファイルに汎用的なプレースホルダーを配置しておき、外部ファイルやスライドノートの内容に基づいて自動的に個別のプレゼンテーションを生成する用途に適しています。

**共通の動作**:
*   `argparse` を用いてコマンドライン引数を解析します。
*   `win32com.client` を使用してMicrosoft PowerPointアプリケーションをCOM経由で操作します。このため、本プログラムは**Windows環境にPowerPointがインストールされている**ことを前提とします。
*   処理結果は新しいPowerPointファイルとして保存され、元のファイルは変更されません。

---

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

**必要な非標準ライブラリ**:
*   `pywin32`: Microsoft OfficeアプリケーションなどのCOMオブジェクトをPythonから操作するためのライブラリです。

**インストールコマンド**:

```bash
pip install pywin32
```

**インストール方法**:

1.  コマンドプロンプト（またはPowerShell、ターミナル）を開きます。
2.  上記の `pip install pywin32` コマンドを実行してライブラリをインストールします。
3.  インストール後、COMオブジェクトの登録が正しく行われるか確認します。通常は自動的に処理されますが、もし実行時にPowerPoint COMオブジェクトが見つからないといったエラーが発生する場合は、以下のコマンドを実行してCOMオブジェクトの登録を明示的に行うことが推奨されます。
    ```bash
    python -m win32com.client.makepy
    # または
    python Scripts/pywin32_postinstall.py -install
    ```
    (`Scripts` ディレクトリの場所はPythonのインストール状況（例: 仮想環境、Anaconda）によって異なる場合があります。)

---

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

1.  **入力PowerPointファイル (`.pptx`)**:
    *   このプログラムが処理を行う対象となるPowerPointプレゼンテーションファイルです。
    *   必須の引数です。
    *   `add` モードでは、このファイルの各スライドのノートテキストが利用されます。
    *   `replace` モードでは、このファイルの各スライド内のテキストにある `{{key}}` 形式のプレースホルダーが置換対象となります。

2.  **置換用のTOML風 `key=value` ファイル** (`--replace` または `-R` オプション使用時、`mode=replace` の場合):
    *   オプションのファイルです。
    *   `replace` モードでのみ使用されます。
    *   ファイル内には `key = value` の形式で、プレースホルダー置換用のキーと値のペアを記述します。
    *   行頭/行末の空白、`#` で始まるコメント行、`"` または `'` で囲まれた値（クォートは自動的に剥がされます）に対応しています。
    *   例:
        ```
        # コメント
        title = "プロジェクト進捗報告"
        presenter = "鈴木 太郎"
        date = '2023年10月27日'
        version=1.0.5
        ```

---

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

1.  **出力PowerPointファイル (`.pptx`)**:
    *   プログラムの処理結果が適用された新しいPowerPointプレゼンテーションファイルが生成されます。
    *   元の入力ファイルは変更されません。
    *   **デフォルトのファイル名**:
        *   `add` モードの場合: `[入力ファイル名]-note-added.pptx`
        *   `replace` モードの場合: `[入力ファイル名]-replaced.pptx`
    *   `-o` または `--outfile` オプションを使って、任意の出力ファイル名を指定できます。

---

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

#### ヘルプの表示

```bash
python add_notes_pptx.py --help
```

#### 1. `add` モード（ノートを字幕として追加）

*   **基本的な使用例**:
    `my_presentation.pptx` のノートを字幕として追加し、`my_presentation-note-added.pptx` として保存します。
    ```bash
    python add_notes_pptx.py my_presentation.pptx --mode add
    ```

*   **出力ファイル名を指定し、字幕の見た目をカスタマイズする例**:
    出力ファイルを `presentation_with_subs.pptx` とし、字幕ボックスの左右余白、高さ、フォント、文字色（白）、背景色（濃い青）、透明度を設定します。
    ```bash
    python add_notes_pptx.py my_presentation.pptx -o presentation_with_subs.pptx --mode add \
      --box_margin 70 --box_height 70 --font_name "游ゴシック" --font_size 14 \
      --font_color "FFFFFF" --bgcolor "003366" --bgalpha 0.75
    ```

#### 2. `replace` モード（プレースホルダー置換）

*   **基本的な使用例**:
    `template.pptx` 内の `{{key}}` 形式のプレースホルダーを、`replace_data.txt` の内容で置換し、`template-replaced.pptx` として保存します。

    **`replace_data.txt` の内容例**:
    ```
    # プロジェクト情報
    project_title = "新規事業計画"
    presenter_name = "佐藤 健"
    date = "2023/11/01"
    ```
    **コマンド**:
    ```bash
    python add_notes_pptx.py template.pptx --mode replace -R replace_data.txt
    ```

*   **出力ファイル名を指定し、スライドノートを `{{supertitle}}` として利用する例**:
    `report_template.pptx` のプレースホルダーを `report_data.txt` の内容と、各スライドのノートテキスト（`{{supertitle}}` として利用可能）で置換し、`final_report.pptx` として保存します。
    ```bash
    python add_notes_pptx.py report_template.pptx -o final_report.pptx --mode replace -R report_data.txt
    ```

    **補足**: `replace` モードでは、各スライドのノートテキストが自動的に `{{supertitle}}` キーの値として利用可能です。例えば、スライドのノートに「このスライドのテーマ」と書かれている場合、スライド内の `{{supertitle}}` は「このスライドのテーマ」に置換されます。これは `-R` で指定するファイル内の `supertitle` キーよりも優先されます。