add_notes_pptx_com.py の技術ドキュメント

プログラムの動作

add_notes_pptx_com.py は、PowerPointプレゼンテーションファイル（.pptx）の各スライドに、指定されたテキストファイルから読み込んだノート（発表者ノート）を自動的に挿入するPythonスクリプトです。WindowsのCOM（Component Object Model）オートメーション機能を利用してPowerPointアプリケーションを直接操作します。

このプログラムの主な機能は以下の通りです。

ノートテキストの解析: 特定の形式で記述されたテキストファイルから、各スライドに対応するノートの内容を抽出します。
PowerPointの操作: win32com.client ライブラリを通じてPowerPointアプリケーションを起動し、指定されたプレゼンテーションファイルを開きます。
ノートの挿入: 解析したノート内容を、対応するスライドのノートページにあるノートテキストボックスに挿入または上書きします。
プレゼンテーションの保存: ノートが挿入されたプレゼンテーションを指定されたファイル名で保存します。出力ファイル名が指定されない場合は、元のファイルが上書きされます。

このプログラムは、大量のスライドにわたる発表者ノートを手動で追加する手間を省き、プレゼンテーションの準備プロセスを効率化することを目的としています。

原理

本プログラムは、WindowsのCOM (Component Object Model) オートメーション技術を利用してMicrosoft PowerPointアプリケーションをプログラム的に制御します。

ノートテキストの解析: 入力されたテキストファイルは行ごとに読み込まれ、正規表現 r"#Slide\s+(\d+)" を用いて #Slide n の形式を検出します。ここで n はスライド番号を示します。このマーカーを検出するたびに、それまでの行を現在のスライドのノートとしてまとめ、スライド番号とノートテキストのペアを辞書形式で保持します。
PowerPoint COMオブジェクトの取得: win32com.client.Dispatch("PowerPoint.Application") を呼び出すことで、PowerPointアプリケーションのCOMオブジェクトを取得します。これにより、PowerPointの各機能（プレゼンテーションの開閉、スライドへのアクセスなど）をPythonコードから実行できるようになります。
プレゼンテーションの開示: 取得したCOMオブジェクトの Presentations.Open() メソッドを使って、ターゲットとなるPowerPointファイルを開きます。
ノートの挿入: 開かれたプレゼンテーション内の各スライドを順に処理します。
- 現在のスライド番号に対応するノートテキストが解析済み辞書に存在するか確認します。
- ノートが存在する場合、そのスライドの NotesPage (ノートページ) オブジェクトにアクセスします。
- NotesPage 内の Shapes コレクションを反復処理し、ノートを挿入すべきテキストボックスを特定します。PowerPoint COM APIにおいて、ノートテキストボックスは shp.Type == 14 (ppShapePlaceholder) かつ shp.PlaceholderFormat.Type == 2 (ppPlaceholderBody) という条件で識別されます。
- 特定したテキストボックスの TextFrame.TextRange.Text プロパティに、解析済みのノートテキストを設定します。
プレゼンテーションの保存と終了: 全てのノート挿入処理が完了した後、pres.SaveAs() メソッドを使用してプレゼンテーションを保存します。指定された出力パスがない場合は、元のファイルが上書きされます。最後に、pres.Close() でプレゼンテーションを閉じ、ppt.Quit() でPowerPointアプリケーションを終了します。

必要な非標準ライブラリとインストール方法

このプログラムは、win32com.client ライブラリを使用しています。これは pywin32 パッケージの一部であり、Windows環境でのみ動作します。

インストールは以下の pip コマンドで実行できます。

pip install pywin32

必要な入力ファイル

PowerPointプレゼンテーションファイル (.pptx):
- プログラムの第1引数として指定します。
- 既存のPowerPointファイルで、ノートを挿入したい対象となります。
ノートテキストファイル (.txt):
- プログラムの第2引数として指定します。
- このファイルはUTF-8エンコーディングで、以下のような特定の形式で記述されている必要があります。
```
#Slide 1
これはスライド1の発表者ノートです。
複数行にわたる内容も記述できます。

#Slide 2
スライド2のノート。
重要なポイントをここに書きます。

#Slide 3
このスライドにはノートがありません。
（実際にはこの行がスライド3のノートとなる）

#Slide 5
スライド4はスキップして、スライド5のノートです。
```
- #Slide n という行で、その後のテキストがスライド番号 n のノートとして扱われます。
- #Slide マーカーが次に現れるまで、またはファイルの終わりまでが1つのスライドのノート内容となります。
- 指定されたスライド番号が存在しない場合、そのノートは無視されます。
- ノートが全く記述されていないスライドは、変更されません。

生成される出力ファイル

PowerPointプレゼンテーションファイル (.pptx):
- ノートが挿入されたPowerPointプレゼンテーションファイルが生成されます。
- プログラムの第3引数 [output.pptx] が指定された場合、そのファイル名で保存されます。
- 第3引数が省略された場合、入力として与えられた元の .pptx ファイルが上書きされます。

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

基本的な使用方法は以下の通りです。

python add_notes_pptx_com.py <PowerPointファイル> <ノートテキストファイル> [出力PowerPointファイル]

<PowerPointファイル>: ノートを挿入する対象の .pptx ファイルのパス。
<ノートテキストファイル>: スライドノートが記述された .txt ファイルのパス。
[出力PowerPointファイル]: （オプション）ノートが挿入されたプレゼンテーションを保存する新しい .pptx ファイルのパス。省略された場合、<PowerPointファイル> が上書きされます。

コマンドラインでの具体的な使用例

以下のファイルが存在すると仮定します。

my_presentation.pptx (既存のPowerPointファイル)
narration_text.txt (以下の内容のノートテキストファイル)

narration_text.txt の内容:

#Slide 1
これはプレゼンテーションの最初のスライドのノートです。
重要な導入部分をここに記述します。

#Slide 2
スライド2には詳細な解説が必要です。
ポイント1: XXXX
ポイント2: YYYY

例1: 新しいファイルにノートを挿入して保存する場合

元の my_presentation.pptx を変更せず、presentation_with_notes.pptx という新しいファイルにノートを挿入して保存します。

python add_notes_pptx_com.py my_presentation.pptx narration_text.txt presentation_with_notes.pptx

実行結果:

スライド 1: ノートを挿入しました。
スライド 2: ノートを挿入しました。
スライド 3: ノートなし。
スライド 4: ノートなし。
スライド 5: ノートなし。
(実際の出力は、my_presentation.pptxのスライド数に応じて変動します)

✅ ノート挿入完了: C:\path\to\your\directory\presentation_with_notes.pptx

例2: 元のファイルに直接ノートを上書きする場合

出力ファイル名を指定しないため、my_presentation.pptx が直接変更され、ノートが挿入されます。

python add_notes_pptx_com.py my_presentation.pptx narration_text.txt

実行結果:

スライド 1: ノートを挿入しました。
スライド 2: ノートを挿入しました。
スライド 3: ノートなし。
スライド 4: ノートなし。
スライド 5: ノートなし。
(実際の出力は、my_presentation.pptxのスライド数に応じて変動します)

✅ ノート挿入完了: C:\path\to\your\directory\my_presentation.pptx