pptx2video

編集済みの PPTX を動画に変換

これは、スタンドアロンの汎用 PowerPoint-to-video パッケージです。paper2video、ResearchStudio-Reel、または ppt-master へのランタイム依存はなく、完全な CLI とレンダラーは、インストール可能な pptx2video Python パッケージに含まれています。研究論文や、以前に納品された video.pptx に限定されません。視覚ソースとして、任意のローカル PPTX を使用してください。正確なナレーションとマーカーのタイミングには、正式な Author Notes を優先してください。正式な Notes がない場合は、Shape Alt Text から同じブロック文法を読み取ってください。レンダリング済みのバンドル成果物は再利用しないでください。ブロック単位の TTS キャッシュエントリを再利用しても安全なのは、完全な合成 ID が一致する場合に限られます。

エントリーポイント

/pptx2video <input.pptx> を、このスキルの直接呼び出しとして扱ってください。通常のレンダリングには、インストール済みの公開 CLI を使用してください。

pptx2video render <input.pptx> <new-output-directory> --resolution 1080p

ネイティブのアニメーション対象を追従するには、--animation-pointer cursor|laser を追加してください。これは Spotlight とは独立しており、デフォルトは none です。

非公開の Paper2Video スクリプトや ResearchStudio スクリプトをインポートまたは実行しないでください。CLI を利用できない場合は、続行する前に公開リポジトリからランタイムをインストールしてください。

python -m pip install \
  'pptx2video[svg] @ git+https://github.com/ai-nuts/pptx2video.git'
python -m playwright install chromium
pptx2video doctor --svg

作成規約

正確に制御するには、ハンドルがトップレベルの図形またはグループと一致する Notes ブロックを記述してください。

## [latency-card] latency-card
A new latency card appears. [[Spotlight] It reports lower latency.]

Alt Text では、先頭の # 文字を2つとも含め、同じ単一ブロックの文法を使用します。] の後のセマンティックテキストは省略可能で、読み上げられません。

## [latency-card] latency-card
A new latency card appears. [[Spotlight] It reports lower latency.]

ベースラインハッシュ、生成順序の来歴、セマンティックプロファイルは PPTX の図形 OOXML 内に格納されます。] の後に表示されるセマンティックテキストは、簡潔なプロファイルです。PPTX の生成またはプロトコルへの書き戻しでは、詳細なプロファイルも保持されます。競合表示では、格納された値を読み取り、レガシーデッキには決定論的なフォールバックを使用するため、LLM は呼び出されません。ネイティブの効果、対象、トリガー、遅延のデータは PowerPoint の p:timing ツリーに保持されます。これらは Notes または Alt Text には表示されません。以前の [handle] と Script:、[ID] handle、詳細な [Paper2Video] ブロックも引き続き読み取り可能で、次回の書き戻し時にこの統一形式へ移行されます。Author Notes は簡潔に保ってください。非表示の来歴に関する規約については、references/editable_pptx.md を参照してください。

安定したハンドルによって対象が直接解決されます。既定では、正常に解決された正規の Notes ブロックは、現在の相対順序をアンカーとして維持します。Notes にないナレーション対象のみが、現在のキャンバス上の位置関係に基づき、これらのアンカーの間に挿入されます。--narration-order-policy author-notes オプションは、明示的な互換性エイリアスとして保持され、同じアンカーと挿入によるナレーション順序を生成します。Animation Pane の順序は、ネイティブアニメーションの行順序と各効果のタイミングを個別に制御します。レンダリングされた動画では、各 Pane フェーズは、ナレーション対象のブロックの直前に出力専用の先行時間として配置され、次のフェーズは、先行ブロックの読み上げが終わるまで待機します。正規のスクリプトマーカーは Spotlight のみです。その位置によって、Edge の単語境界の時刻または範囲が決まります。以前の開始マーカーも移行用に引き続き読み取り可能ですが、ネイティブアニメーションを置き換えたり、作成したり、順序変更したりすることはありません。

納品するすべての PPTX では、既定ですべてのスライドに、人が編集できる番号付きクリックグループが設定されます。With Previous ではない各 Pane 行を、それぞれのトップレベル mainSeq グループの On Click リーダーにしてください。連続する With Previous 行はそのリーダーとまとめ、キャンバス上のバッジを共有させてください。PowerPoint はこのトポロジーからバッジを導出します。バッジは保存されたアニメーション ID ではありません。効果の対象、プリセット、継続時間、遅延、Pane の開始時刻と終了時刻、行順序、同時グループが同一に保たれる場合に限り、書き換えを受け入れてください。スケジュールを維持できない場合は、処理を中止してください。ソースの自動クリックグループのトポロジーを変更せずに保つ必要がある場合に限り、--click-group-policy preserve を使用してください。

正規の Notes を使用しない PPT ネイティブのワークフローでは、同じ文法を使用して図形の Alt Text に明示的なスクリプトを記述し、効果にはネイティブの Animation Pane を使用してください。

## [latency-card] latency-card
A new latency card appears and reports lower latency.

効果名を変更する場合や、プロトコルの競合を解決する場合は、references/animations.md を参照してください。

権限と競合の規則

次の優先順位を適用してください：

1. 明示的に選択されたユーザーの script.json が、そのレンダリングのナレーションを管理します。
2. 正規の作成者ノートが順序の基準となります。ナレーションについては、ノートと代替テキストを、シェイプの OOXML に保存された最後にシステムと同期したスクリプトハッシュと比較します。一方だけが変更されている場合は、変更された側を優先します。両方が異なる内容に変更されている場合は、ノートを優先し、権限レポートに競合を記録します。
3. 正規の代替テキストブロックは、ノートがない場合、またはそのナレーションのみが保存済みのベースラインと異なる場合に、ナレーションを提供します。アニメーション対象が新たに追加され、プロトコル導入前のプレーンな代替テキストのみがある場合、そのテキストを初期スクリプトとして一度使用し、統一ブロック文法に正規化します。
4. ナレーションの順序は、デフォルトで増分的な geometry 挿入によって決まります。正常に解決された正規のノートブロックはすべてアンカーとなり、ノート内の相対的な順序を維持します。ノートにないナレーション対象のみを、これらのアンカーの前後に挿入します。垂直方向の重なりが 35 パーセント以上ある場合、水平バンドとしてまとめ、上から下へ読み進めます。各バンド内では、水平方向の重なりが 50 パーセント以上あるものを垂直レーンとしてまとめ、左から右へ読み進めます。右へ進む前に、各レーンを上から下まで読み進めます。既存のアンカー付きシェイプを移動しても、確立済みのナレーション順序は変わりません。順序を変更する必要がある場合は、そのノートブロックを移動してください。ジオメトリのない無音の対象は、決定性を保つため末尾に配置します。互換性のために明示的な author-notes ポリシーも引き続き利用でき、ノートアンカーにジオメトリ挿入を組み合わせた同じ順序を使用します。どちらのポリシーも、新たに挿入されたナレーションブロックに使用可能なトップレベルのジオメトリがない場合は、安全側に倒して処理を失敗させます。 ノート、代替テキスト、明示的な script.json、または要求された変更要素の再生成を解決した後、TTS または出力バンドルの作成を行う前に、決定的な開始順序を 2 種類算出します。1 つはスライド全体の純粋なバンド／レーンジオメトリ順序、もう 1 つはネイティブのアニメーションウィンドウ順序です。それぞれの順序で、対象となるすべての要素に番号を振り直します。ノートアンカーに基づくナレーション順序をジオメトリ順序として提示してはいけません。競合があるのは、新たに挿入された、ノートに存在しないナレーション対象の開始要素が相対的に逆転している場合に限られます。この候補のフィルタリングによって、確立済みのノートアンカーがジオメトリに基づいて並べ替えられることはありません。無音の装飾、強調のみの対象、同時実行グループは無視します。そのような競合があるスライドのみを含む animation_order_authority.json を出力し、正確なアニメーションウィンドウの行移動手順を記載します。競合のないスライドは何も出力せず、判断も不要です。
5. 通常のネイティブアニメーションの種類、行の順序、On Click、With Previous、After Previous、時間、遅延については、アニメーションウィンドウのみが正となります。動画スケジューラーは、ナレーションの解除ゲートをアニメーションウィンドウのフェーズ間に追加しながら、各アニメーションのローカルな関係を維持します。スクリプトでネイティブ効果を補足できるのは Spotlight のみです。
6. シェイプの OOXML には、スクリプトハッシュと並べて orderSource と正規の orderIndex を保存します。競合のないレンダリングでは、確立済みのノートアンカーに author_notes、新たに挿入されたブロックに geometry を書き込み、そのうえで有効な順序に連続したインデックスを振り直します。アニメーションウィンドウの選択を確定すると、該当する競合スライドの有効な開始順序に animation_pane を書き込みます。
7. 表示されるすべてのピクセルとジオメトリは、PowerPoint のキャンバスを正とします。

登録済みのネイティブ開始プリセット 22 種類すべてに、明示的な MP4 戦略があります。複雑なプリセットには、名前付きの決定的な近似処理を使用し、暗黙のうちにフェードへ変換することはありません。未知の開始プリセットの組み合わせ、およびサポート対象の開始／強調の仕様範囲外にあるネイティブアニメーションクラスは、明示的にエラーとします。 Notes と Alt Text の両方が異なる内容に変更された場合は、Notes が優先され、出力される PPTX の Alt Text が更新されます。レガシーなスクリプトの入口マーカーがネイティブ行と競合する場合は、ネイティブ行が優先され、競合レポートに無視されたマーカーが記録されます。ネイティブ行がない場合、レガシーな入口マーカーはアニメーションを作り出すのではなく、無視されます。図形が削除されている場合は、古くなった Notes ブロックを削除し、removed_stale_notes に記録してください。位置や残っているアニメーションウィンドウの行を使って、別の図形に再割り当てしてはいけません。曖昧なライブハンドルは引き続きフェイルクローズします。

1 つのコマンドでレンダリング

公開ランタイムをインストールし、コア依存関係と SVG 依存関係の両方を確認してからレンダリングします。

python -m pip install \
  'pptx2video[svg] @ git+https://github.com/ai-nuts/pptx2video.git'
python -m playwright install chromium
pptx2video doctor --svg

次に、ローカル CLI を呼び出します。

pptx2video render \
  path/to/edited.pptx \
  path/to/new_video_bundle \
  --resolution 1080p

--narration-order-policy geometry は、デフォルトの増分ポリシーです。現在の正規の Notes ブロックの順序を維持し、Notes にないナレーション対象の配置にのみジオメトリを使用します。--narration-order-policy author-notes は、互換性のために明示的に選択できます。

デフォルトの --click-group-policy normalize は、最初のスライドだけでなく、すべてのスライドを処理します。連続する各フェーズに番号付きバッジを 1 つ付与しつつ、With Previous の行は同じ番号のグループにまとめます。preserve は、これを明示的に無効にする設定です。

デフォルトの --animation-order-policy auto は、stdin が TTY の場合にのみ対話形式になります。競合があるスライドに限ってスライドインデックスの昇順でプロンプトを表示し、次の競合スライドを表示する前に各判断を待ちます。たとえば、スライド 4 を表示する前にスライド 2 を解決します。非対話形式または API での使用時に競合が検出されると、レポートが書き込まれ、出力ディレクトリを作成する前にコード 3 で終了します。 Codex または別のスキルが会話内でそのレポートを提示する場合は、競合スライドを一度に 1 枚だけ表示し、次を表示する前にユーザーの選択を待ってください。レポートの決定論的なテキストまたは ASCII キャンバスを使用し、各要素の中心だけでなく OOXML のバウンディングボックスを描画してください。また、等幅フォントの文字セルの縦横比を考慮したうえで、PPTX キャンバスの実際の縦横比に近づけた 3 つのビューを縦に並べて表示してください。キャンバスが切り取られないよう、検出したターミナル幅に合わせてすべての寸法を調整してください。3 つのビューすべてで同じ輪郭線を使用してください。Geometry Order では各ボックス内にジオメトリ順位の番号だけを、Animation Pane Order では同じボックス内に Pane 順位の番号だけを、Element Identity Map では A、B、C などの安定した識別文字だけを表示してください。G1/P2 のように複数のラベルを組み合わせて表示しないでください。識別文字は安定した shape_id の自然順に従い、どちらの順序系列とも独立しているため、順序の意味は持ちません。各キャンバスに、正確に LEGEND というタイトルのキーと意味の凡例を設けてください。Geometry Order の横には、各ジオメトリ順位の番号をその要素の意味の説明に対応付けて表示してください。Animation Pane Order の横には、各 Pane 順位の番号をその要素の意味の説明に対応付けて表示してください。Element Identity Map の横には、各識別文字をその要素の意味の説明に対応付けて表示し、ユーザーが C -> A -> D -> B のように任意の順序を指定できるようにしてください。ターミナルの幅が広い場合は、各凡例を対応するキャンバスの右側に配置してください。幅が狭い場合は、次のビューを表示する前に、各キャンバスの直下に凡例を配置してください。選択された同じプロファイルを 3 つすべての凡例に適用してください。既定では concise を使い、保存済みの detailed プロファイルを使う場合は --semantic-profile detailed を指定してください。幅が 26 列未満の場合はバウンディングボックスのプロットを省略しますが、ラベル付きのテキストビュー 3 つは残し、それぞれに数値順位または識別文字と意味の対応付けを表示してください。1 行だけの細長い要素は、幅広で薄い形状として視認できるようにしてください。競合表示時に、いずれかの順序、識別マップ、レイアウト、意味の説明を推測するために LLM を使わないでください。また、競合スライドをすべて一度に列挙しないでください。Pane の選択は選択された競合スライドのみに適用され、そのスライドの対象となるナレーション付き開始ブロックを Pane 順にシリアライズし、配信する Notes と OOXML の来歴情報を同期させます。他の競合スライドにはそれぞれの決定が維持され、競合のないスライドには Notes アンカーと挿入ジオメトリの来歴情報が維持されます。いずれかのスライドでユーザーが reading-order を選択した場合は、停止してレポートに記載された正確な Pane 移動手順を提示してください。配信された PPTX とスケジュールが異なる動画を黙ってレンダリングしてはいけません。

ユーザーが選択した Identity 順は、決定論的な identity_order.v1 を使って解析してください。Identity Map が A から G までの競合ページでは、CABGDEF は正確に C -> A -> B -> G -> D -> E -> F を意味します。大文字と小文字を区別せずに入力を受け付け、大文字に正規化してください。現在のページに表示されている識別文字の完全な順列を必須とし、欠落、重複、不明、空、または無効なラベルは拒否してください。すべてのラベルが 1 文字である場合は、区切り文字のない入力も有効です。ページが Z を越えて AA まで続く場合は、A,B,...,AA のような区切り文字を必須としてください。TTY では、表示中のページの順序を直接受け付けてください。API または非 TTY での使用では、競合ページが 1 つの場合は --animation-order-sequence CABGDEF を受け付け、すべての競合ページを指定する場合は --animation-order-sequence SLIDE=ORDER をページごとに繰り返して受け付けてください。指定された順序が現在の Pane と完全に一致する場合は、明示的な Pane 確認として記録し、レンダリングしてください。一致しない場合は、その Identity 順と shape-ID 順を決定レポートに保存し、ソース PPTX の Pane を修正するために処理を停止してください。配信された PPTX と一致しない順序をレンダリングしてはいけません。

インストール方法と任意のパスの使用方法については、references/cli.md を参照してください。ユーザーが編集した外部スクリプトで PPTX のナレーションを上書きする場合に限り、--script-json path/to/edited-script.json を追加してください。このコマンドは次の処理を行う必要があります：

1. 信頼できる Notes がある場合は、そこから統一 Alt Text ブロックを正規化します。
2. 新しいアニメーション対象のハンドルと統一 Alt Text ブロックを生成します。
3. ソースに Alt Text またはネイティブ行しかない場合は、正規の Notes を補完します。
4. ユーザースクリプト、Notes、Alt Text の順に優先してナレーションを抽出し、スクリプトの信頼性とは独立して、選択したナレーション順序ポリシーを適用します。
5. 変更検出とプロトコルへの書き戻し後、すべてのスライドで番号付きクリックグループを正規化します。レンダラーの Pane クロックが変更されていないことを確認し、assets/meta/reports/click_group_normalization.json に書き込みます。
6. ナレーションブロックごとに Edge TTS と単語タイミングを生成し、完全一致するキャッシュ項目のみを再利用します。出力の組み立て時には、各ナレーションブロックの前に対応する Animation Pane フェーズを無音として挿入し、Edge の各単語境界を同じ量だけずらしてから、ブロックを連結してスライド音声を作成します。ネイティブ要素のみで構成される無音スライドには、決定的な無音音声を生成します。メタデータでは各論理セクション ID を保持し、manifest.json を使ってポータブルな物理 MP3 を解決します。
7. ナレーションに合わせてシリアライズされたスケジュールを構築します。ナレーション付きの開始アニメーションは最初の発話語より前に完了し、次の Pane フェーズは直前のナレーションブロックが終了してから開始します。ネイティブの同時実行グループは保持します。
8. すべての字幕キューを、実際の Edge TTS の最初と最後の単語境界に合わせます。最終レンダリングでは比例タイミングを使用しないでください。
9. PPTX のピクセル、アニメーション、音声、スポットライト、下部帯の字幕をレンダリングします。フレームソース、アテンションオーバーレイ、ffmpeg、パフォーマンス、デバッグの詳細は references/render_video.md を参照してください。
10. timeline.json、字幕アラインメントの証拠、マッピングレポート、厳格な QA 証拠を書き出します。

最終レンダリングでは --prebuilt-audio-dir を指定しないでください。--no-qa を指定しないでください。

永続的な TTS キャッシュは、ブロックごとのコンテンツアドレス方式です。無効化キーは、正規化されたナレーションの SHA-256、音声、速度、ピッチ、プロバイダー、プロバイダーのバージョン、キャッシュスキーマのバージョンを含む正規 JSON ID の SHA-256 です。タイミング対応レンダリングでは、音声、メタデータ、単語境界の証拠がすべてそれぞれのハッシュとキャッシュキーに一致する場合に限り、キャッシュを使用します。ブロックを 1 つ編集した場合は、そのブロックのみを再生成します。合成設定またはプロバイダーのバージョンを変更すると、影響を受けるすべてのキーが無効になります。アニメーションの先行無音と末尾のパディングは、キャッシュのマテリアライズ後に適用され、未加工のキャッシュエントリーに混入することはありません。

変更を考慮した再レンダリングでは、通常のユーザーは既存のナレーションを保持するか、変更された要素だけを再生成するかを選択します。後者には、以前の PPTX ベースラインと OpenAI API キーが必要です。

pptx2video render edited.pptx new-bundle \
  --baseline-pptx previous-video.pptx \
  --narration-mode regenerate

再生成されたスクリプトは、納品する PPTX の Author Notes と統一 Alt Text ブロックの両方に書き戻されます。script.json は通常の編集画面ではなく、Advanced 用のオーバーライドとして扱います。

通常のアニメーション付き PPTX

デッキに正規の Notes と Alt Text がまだ含まれていない場合は、既存のナレーションスクリプトからコピーを初期作成し、そのコピーを編集します。

pptx2video bootstrap path/to/animated-source.pptx \
  --script-json path/to/script.json \
  --output path/to/editable-video.pptx \
  --report path/to/bootstrap-report.json

完了ゲート

以下の成果物が揃っていることを確認します。

new_video_bundle/
  video.mp4
  video_no_subtitles.mp4
  video.pptx
  manifest.json
  assets/audio/
  assets/captions/
  assets/meta/timeline.json
  assets/meta/reports/author_notes_authority.json
  assets/meta/reports/animation_order_authority.json
  assets/meta/reports/click_group_normalization.json
  assets/meta/reports/subtitle_timing_alignment.json
  assets/meta/reports/video_qa_report.json

字幕タイミングレポートの status: word_aligned を確認してから、video_qa_report.json の passed: true、error: 0、warning: 0 を確認します。厳格なレンダラーが 0 で終了するまで、完了を宣言しないでください。

macOS でのローカル利用

references/macos.md を参照してください。同じ Python パッケージをインストールし、Playwright Chromium をインストールして、pptx2video doctor --svg でネイティブ依存関係と SVG 依存関係を確認したうえで、Terminal または外部ランチャーからスタンドアロン CLI を実行します。