powerpoint

PowerPoint スキル

python-pptx ライブラリを使って、PowerPoint（.pptx）プレゼンテーションを作成、確認、編集できます。5 つのヘルパースクリプトで、JSON 仕様に基づくデッキの作成、構造化された読み取り、既存デッキの編集、テンプレートを使ったブランドデッキの作成、スライドのレンダリングに対応します。すべてオフラインで実行でき、PowerPoint のインストールは不要です。

使用する場面

• ユーザーからスライドデッキ、レポート用プレゼンテーション、またはピッチデッキの作成を依頼された場合。
• 共有された .pptx からテキスト、ノート、表、グラフデータ、画像を抽出する場合。
• 既存のデッキを更新する場合：テキストの置換、グラフデータの更新または差し替え、ロゴの交換、スライドの複製／削除／並べ替え、背景、フッター、ハイパーリンク、発表者ノートの設定など。
• 会社の .pptx テンプレートを使って、ブランドに沿ったデッキを作成する必要がある場合。
• .ppt（旧形式のバイナリ）ファイルには使用しないでください。LibreOffice が利用可能な場合は、まず soffice --convert-to pptx old.ppt で変換してください。

前提条件

• python-pptx がインストールされた Python 3.10 以降 （pip install python-pptx）。
• オプション：スライドの PNG レンダリングと PDF エクスポートには、LibreOffice（soffice）と poppler（pdftoppm または pdftocairo）が必要です。 pptx_render.py は shutil.which で両方を検出し、見つからない場合は適切に処理を続けます（{"rendered": false, "missing": [...]} を報告して終了コード 0 を返します）。作成／読み取り／編集の各操作は、これらがなくても実行できます。
• terminal で利用可能か確認します： python -c "import pptx; print(pptx.__version__)" と which soffice pdftoppm。

実行方法

すべてのスクリプトは scripts/ にあり、--help を受け付け、標準出力に JSON を出力し、失敗時は 0 以外の終了コードを返します。terminal で実行してください：

python scripts/pptx_create.py deck.json out.pptx
python scripts/pptx_read.py deck.pptx --outline      # full JSON outline
python scripts/pptx_read.py deck.pptx --notes        # speaker notes
python scripts/pptx_read.py deck.pptx --images ./img # export pictures
python scripts/pptx_edit.py deck.pptx --replace-text "Old Corp" "New Corp"
python scripts/pptx_edit.py deck.pptx --chart-data update.json
python scripts/pptx_edit.py deck.pptx --duplicate-slide 2
python scripts/pptx_edit.py deck.pptx --remove-slide 3 --move-slide 2 0
python scripts/pptx_from_template.py brand.pptx out.pptx --values vals.json
python scripts/pptx_render.py deck.pptx --outdir ./render  # slide PNGs

write_file で JSON 仕様を作成し、read_file でスクリプトの出力と生成された JSON を確認します。

クイックリファレンス

タスク	コマンド
仕様から新しいデッキを作成	pptx_create.py spec.json out.pptx
16:9 と 4:3 の切り替え	仕様内で "slide_size": "16:9" または "4:3" を指定
アウトラインを JSON で取得	pptx_read.py deck.pptx --outline
画像をエクスポート	pptx_read.py deck.pptx --images DIR
テキストを置換	pptx_edit.py deck.pptx --replace-text OLD NEW
グラフデータを置換	pptx_edit.py deck.pptx --chart-data spec.json
1 つの系列にパッチを適用	同じフラグを使用し、"ops" を含む仕様を指定（下記を参照）
画像を交換	pptx_edit.py deck.pptx --swap-image N NAME new.png
スライドを複製	pptx_edit.py deck.pptx --duplicate-slide N
スライドを削除	pptx_edit.py deck.pptx --remove-slide N
スライドを並べ替え	pptx_edit.py deck.pptx --move-slide FROM TO
スライドの背景	pptx_edit.py deck.pptx --set-background N RRGGBB
テキストにハイパーリンクを設定	pptx_edit.py deck.pptx --hyperlink N TEXT URL
スライド番号を有効化	pptx_edit.py deck.pptx --enable-slide-number N
フッターテキスト	pptx_edit.py deck.pptx --set-footer N TEXT
ノートを設定	pptx_edit.py deck.pptx --set-notes N TEXT
ノートを追記	pptx_edit.py deck.pptx --append-notes N TEXT
テンプレートに値を入力	pptx_from_template.py tpl.pptx out.pptx --values v.json
スライドを PNG にレンダリング	pptx_render.py deck.pptx --outdir DIR

手順

1. デッキを作成する

JSON 仕様を作成し（完全な形式は pptx_create.py --help を参照）、pptx_create.py を実行します。スライドごとに設定できる項目は次のとおりです：layout（title、 title_content、section、two_content、title_only、blank）、title、 subtitle、bullets（文字列、または level 0-4、size pt、 bold、italic、font、color hex、ハイパーリンク用の link URL を含む辞書）、background（単色の hex）、footer（テキスト。レイアウトのフッタープレースホルダーを有効化）、slide_number（true。レイアウトのスライド番号プレースホルダーを有効化）、images（パスとインチ単位の left/top/width/height）、tables（rows はリストのリスト）、shapes（rectangle、rounded_rectangle、oval、diamond、right_arrow、chevron。fill hex と任意の text を指定）、charts（bar、bar_h、line、pie。categories と series を指定）、notes（発表者ノート）。

2. スライドを読み取る

pptx_read.py deck.pptx --outline は、スライドサイズ、レイアウト一覧、 各スライドのレイアウト名、すべての図形テキスト、表のセル、画像一覧 （ファイル名／拡張子／バイト数）、グラフのカテゴリ／系列／値、発表者ノートを返します。 --images DIR を使うと、埋め込み画像をファイルに書き出せます。内容を確認したい場合は、 書き出した画像に対して vision_analyze を実行してください。

3. スライドを編集する

pptx_edit.py は複数の操作を1回で実行します。元のファイルを保持するには --output を使います。テキスト置換では、スライドの図形、表のセル、ノートを検索します。 画像の差し替えでは、画像のリレーションシップ ID を変更するため、位置とサイズは そのまま保持されます。スライドの削除ではリレーションシップと <p:sldId> エントリが削除され、並べ替えでは <p:sldIdLst> 内の <p:sldId> 要素が移動します （python-pptx にはどちらの操作にも公開 API がないため、スクリプトが XML レベルで 処理します）。--duplicate-slide N は、スライド N の独立したディープコピーを末尾に追加します。 図形の XML と画像／メディア／ハイパーリンクのリレーションシップが複製され、rId が 再割り当てされるため、コピーを編集しても元のスライドには影響しません。グラフを含む スライドは拒否されます（「注意点」を参照）。--set-notes／--append-notes は発表者 ノートを編集します。--set-background、--hyperlink、--enable-slide-number、 --set-footer は、スライドの仕上げに使用します。

グラフの更新には、--chart-data で JSON 仕様を渡します。すべて置き換える場合： {"slide": 0, "chart": 0, "categories": [...], "series": {...}}。細かく編集する場合は、 代わりに "ops" を渡します。これは次の形式のリストです。 {"op": "update_series", "name": ..., "values": [...]}、 add_series、remove_series、rename_category（from／to または index）、および set_title。python-pptx ではグラフのデータセット全体を 置き換える（replace_data）ことしかできないため、操作は既存データの読み込み → 変更 → 置き換えとして実装されています。部分ごとの UX はラッパーであり、 カテゴリと数値系列として表現できないグラフデータは、往復処理によって正規化されます。

4. テンプレートから作成する

pptx_from_template.py はブランド用の .pptx を開き、スライド／表／ノート全体にわたって 値 JSON の各 {{token}} を置換します。また、テンプレート独自のレイアウト （レイアウト名またはインデックス）を使う新しいスライドを追加でき、マスターのフォントと色を 引き継げます。ヒント：スライドがゼロのテンプレートから始めるには、後から pptx_edit.py --remove-slide を使って既存のスライドを削除してください。

5. 見た目を確認する

pptx_render.py deck.pptx --outdir ./render は、soffice --headless でスライドを PDF に 変換し、pdftoppm（または pdftocairo）でスライドごとに1つの PNG に分割します。 出力 JSON には PNG のパスが記載されます。各画像を vision_analyze で確認してください。 いずれかのツールが見つからない場合、スクリプトは {"rendered": false, "missing": [...]} と案内を出して 0 で終了します。その場合は、 pptx_read.py の JSON アウトラインを代わりに使用してください。これで内容と構造は 確認できますが、見た目は確認できません。

PDF に変換する

LibreOffice がインストールされている場合は、完成したスライドを直接 PDF にエクスポートできます。

soffice --headless --convert-to pdf --outdir ./out deck.pptx

出力先は ./out/deck.pdf です。ホストにインストールされていないフォントは 代替フォントに置き換えられるため、PDF を納品する前にレンダリングして確認してください（手順 5）。 オフラインで .pptx から PDF に変換する純粋な Python の方法はありません。soffice がない場合は、 近似で済ませず、その旨を伝えてください。

注意点

• 実行の分割：PowerPoint は、スペルチェックや編集の境界で段落テキストをランに分割します。--replace-text はまず、書式が同一の隣接するランを結合するため、そのようなランにまたがる一致は書式を完全に保持したまま置換されます。一致が 実際に書式の異なる ランにまたがる場合に限り、段落は最初のランの書式で書き換えられます。置換後に該当するスライドを確認してください。
• グラフを含むスライドは複製できません：各グラフのリレーションシップには個別の XLSX ブックパーツが埋め込まれています。このグラフを確実に複製することはサポートされていないため、--duplicate-slide はデッキを破損させる代わりに、グラフを含むスライドの複製を適切に拒否します。代わりに、新しいスライドでグラフを作成してください。外部ハイパーリンクと画像／メディアの rel は引き継がれ、レイアウトとノートの rel は新しく作成されます。
• グラフ操作はラッパーです：python-pptx はデータセット全体を置き換えます。「ops」は既存のプロットデータを replace_data 経由で往復させます。グラフの 種類 は変更できません。
• 並べ替えは XML レベルで行われます：python-pptx には、サポートされている並べ替え API がありません。--move-slide は <p:sldIdLst> を直接操作します。通常のデッキでは安全ですが、実行後にデッキを読み直して確認してください。
• デッキ間でのスライドのコピーはサポートされていません — 複製は、レイアウトとマスターが共有されている同一デッキ内でのみ機能します。
• フッター／スライド番号を有効にすると、スライドのレイアウトからプレースホルダーがコピーされます。これらのプレースホルダーがないレイアウトでは、--set-footer は明確なメッセージを表示して失敗します（代わりにテキストボックスを追加してください）。
• ハイパーリンクはラン全体に適用されます。--hyperlink は、そのスライドで指定したテキストを含むすべてのランにリンクを設定します。
• python-pptx のデフォルトのテンプレートは 4:3 です。作成スクリプトは、仕様で指定されていない限り 16:9 に設定します。カスタムテンプレートは独自のサイズを維持します。
• レイアウトのインデックスはテンプレートによって異なります。ブランドテンプレートでは、まずレイアウト名を一覧表示してください：pptx_read.py template.pptx --outline（layouts_available）。
• 空白のレイアウトでは slide.shapes.title は None です。作成スクリプトでは処理されますが、アドホックな python-pptx コードを書く際は注意してください。
• 仕様ファイルを書き込む際は、必ず encoding="utf-8" を指定してください。{{city}} のようなトークンには、非 ASCII の値が設定される場合があります。

検証

1. 作成または編集を行った後は、pptx_read.py OUT.pptx --outline を実行し、スライド数、テキスト、表、ノート、グラフの値が意図どおりであることを確認します。
2. --images DIR を実行し、その後ファイルサイズを確認することで、画像が埋め込まれていることを確認できます。
3. pptx_render.py deck.pptx --outdir ./render ですべてのスライドをレンダリングし、vision_analyze ですべての PNG を確認します。これにより、アウトラインでは検出できない図形の重なり、テキストの欠落、色の問題を見つけられます。レンダリングツールが見つからない場合はスクリプトが通知します。その場合はアウトラインを確認してください。
4. 同梱のテストスイートが完全な仕様です：python -m pytest tests/ -q（python-pptx と pytest が必要です）。