Mintii-Labs/ozor-skills

Ozor ドキュメントからビデオへ

Ozor.ai 上でのエンドツーエンドのドキュメント to ビデオ変換。実際のファイル（PDF、PPTX、DOCX など）を受け取り、Ozor 側で分析して構造化プランを作成し、ユーザーに承認・編集を促した上で、ビデオを生成・エクスポートします。スライドのビジュアルはそのまま保持されます。

使用するタイミング

このスキルは、入力がドキュメント/ファイルの場合に使用します。以下のようなケースが該当します：

• ユーザーが PDF、PPTX、DOCX、Keynote 書き出し、スライドデッキ、提案書、ホワイトペーパー、レポート、1 ページ資料を添付または参照した場合
• 「このデッキをビデオにして」
• 「この PDF からビデオを作って」
• 「私のピッチ/提案書/レポートからビデオを」

以下の場合はこのスキルを使用しないでください：

• 入力が短いクリエイティブなテキストブリーフの場合 → ozor-generate
• 入力が URL やランディングページの場合 → ozor-url-to-video
• ユーザーが書かれた Ozor プロンプトのみを希望する場合 → ozor-doc-to-video（プロンプトのみのスキル）
• ユーザーが既存のビデオを管理したい場合 → ozor-video-library

必要な MCP ツール

• mcp__ozor__analyze_document — ドキュメントを分析し、planId と構造化プランを返します
• mcp__ozor__prepare_document_upload — 公開 URL のないローカルファイル用に、curl でアップロード可能な URL を取得します（一般的なケース）
• mcp__ozor__get_plan — 最新のプランの状態を取得します
• mcp__ozor__update_plan — 生成前にユーザーの編集をプランに適用します
• mcp__ozor__generate_from_plan — 承認されたプランからビデオのビルドを開始し、projectId を返します
• mcp__ozor__export_video — レンダリングを開始します（projectId を videoId として使用します）
• mcp__ozor__wait_for_export — レンダリングが完了するまでブロックします
• mcp__ozor__get_embed_code — <iframe> HTML を返します

Ozor MCP が接続されていない場合は、ユーザーにその旨を伝えて停止してください。自分でコンテンツを抽出して generate_video にフォールバックしないでください。スライドのビジュアルが失われ、2000 文字のプロンプト制限を超える可能性があります。ドキュメントにはプランベースのフローが必須です。

ワークフロー

ステップ 1 — ドキュメントを Ozor に送る

優先順位に従って最適なソースを選択します：

1. 公開 URL → url をそのまま analyze_document に渡します。サイズ制限なし、トークン消費なし。利用可能なら最適です。
2. ローカルファイル（一般的なケース） → mcp__ozor__prepare_document_upload を呼び出し、返された curl コマンドを実行してバイトデータを直接 Ozor のストレージにプッシュします。バイトデータはツール呼び出しを経由しないため、最大約 50MB のファイルが扱えます。ユーザーが会話にアップロードした数 MB の PDF/PPTX/DOCX に使用します。
3. analyze_document の fileBase64 + fileName — 小さなファイル（数百 KB 程度）にのみ使用します。大きなデッキではトークンを消費するため避けてください。

prepare_document_upload がツールリストにない場合、このサーバーではアップロードが無効になっています。URL または小さな base64 にフォールバックしてください。

ステップ 2 — ドキュメントを分析する

Ozor がファイルを入手したら、次のように呼び出します：

mcp__ozor__analyze_document({
  url | uploadId | fileBase64+fileName,
  ...オプションのヒント: targetDuration, format (16:9 / 9:16), audience, tone
})

これにより { planId, plan } が返されます。プランには、提案されたシーン、ナレーション、ビジュアルノート、およびどのスライド/ページがどのシーンにマッピングされるかが含まれます。

ステップ 3 — プランをユーザーに提示して STOP

これは重要なステップです。 生成にスキップしないでください。プランを簡潔にユーザーに表示します：

📋 Ozor プラン for "<ドキュメント名>"

**フォーマット:** 16:9（または 9:16）
**推定時間:** ~X 秒
**シーン数:** N

(1) <シーンタイトル> — <1行ナレーション/ビジュアル>
(2) <シーンタイトル> — <1行ナレーション/ビジュアル>
...

これをそのまま生成しますか？それとも変更しますか？以下の操作が可能です：
- シーンを編集（"change scene 2 to ..."）
- シーンの並べ替え/削除/追加
- トーン、長さ、フォーマットの変更
- 承認して生成

その後、ユーザーが承認または編集を要求するまで 待機 します。generate_from_plan を自分の判断で呼び出さないでください。プランはコストとクリエイティブな管理のためのチェックポイントです。

ステップ 4 — 編集を適用する（必要な場合）

ユーザーが変更を要求した場合、編集内容を指定して mcp__ozor__update_plan({ planId, ... }) を呼び出します。get_plan で再取得し、更新されたプランを再表示します。ユーザーが承認するまでこのループを繰り返します。

ステップ 5 — プランから生成する

ユーザーが承認したら：

mcp__ozor__generate_from_plan({ planId })

これにより { projectId } が返されます。projectId を後続のすべての呼び出しで videoId として使用します。

応答に jobId が含まれている場合は、wait_for_job({ videoId: projectId, jobId }) でそれを待機します。それ以外の場合はエクスポートに進みます。

ステップ 6 — エクスポート

mcp__ozor__export_video({ videoId: projectId })
mcp__ozor__wait_for_export({ videoId: projectId })

shareUrl、editorUrl、downloadUrl が返されます。

ステップ 7 — 埋め込み

mcp__ozor__get_embed_code({ videoId: projectId })

ステップ 8 — 結果を表示

🎬 ビデオ準備完了 from "<ドキュメント名>"

**共有:** <shareUrl>
**エディター:** <editorUrl>
**ダウンロード:** <downloadUrl>

**埋め込み:**
```html
<iframe ...></iframe>

同じプランから 9:16 のソーシャルカットも必要ですか？再生成できます。

## `analyze_document` に渡すヒント

ユーザーが言及した場合、またはドキュメントから明らかな場合、以下のいずれかを渡します：

- `targetDuration` — 例：`"60s"`、`"90s"`。提案書/デッキのデフォルトは約 60 秒、1 ページ資料は約 30 秒。
- `format` — `"16:9"`（デフォルト）またはソーシャル用の `"9:16"`。
- `audience` — 投資家、顧客、開発者、社内チームなど。
- `tone` — 自信に満ちた、温かい、技術的な、エネルギッシュな、など。
- `focus` — オプション。1 行のメモ（例：「スライド 4 のメトリクスに重点を置く」「チームスライドをスキップ」）。

## ドキュメントタイプによる適応

| ドキュメント | デフォルト時間 | フォーマット | トーン | フォーカス |
|----------|------------------|--------|------|-------|
| ピッチデッキ | 60–90 秒 | 16:9 | 自信に満ちた | 問題 → 解決策 → 牽引力 → CTA |
| 提案書 (DOCX) | 60 秒 | 16:9 | プロフェッショナル | 成果 + 価格 + 次のステップ |
| ホワイトペーパー / レポート | 60–90 秒 | 16:9 | 権威のある | 3 つの主要な発見、CTA で全文へのリンク |
| セールス 1 ページ資料 | 30–45 秒 | 16:9 | インパクトのある | フック → 3 つのメリット → CTA |
| リリースノート | 30–45 秒 | 16:9 | エネルギッシュな | 機能ごとに 1 シーン |
| トレーニング / SOP | 90 秒以上 | 16:9 | 落ち着いて明確な | 番号付きステップ、7 シーンを超える場合はシリーズに分割 |

迷った場合は、最初の呼び出しでデフォルトを提案し、ユーザーがプランを見た後で上書きできるようにします。

## 生成後の反復

レンダリングされたビデオに変更が必要な場合：
- 小さなナレーション/コピーの微調整 → `update_plan` ＋ 再生成（プランから再実行されるため、ドキュメントの再分析は不要）
- 新しいシーン順序やトーン → 同じパス
- 新しいフォーカスやオーディエンス → より強いヒントを指定して `analyze_document` を再度呼び出す方が安価な場合がある

## エラーと復旧

- **ファイルが大きすぎて `analyze_document` が失敗する** → base64 の代わりに `prepare_document_upload` を使用します。
- **プランに欠落や誤ったコンテンツがある** → 再起動する代わりに、修正を指定して `update_plan` を呼び出します。
- **`generate_from_plan` が失敗する** → エラーは通常、特定のシーンを指しています。`update_plan` で修正し、再試行します。
- **エクスポートがハングする** → `wait_for_export` を再度呼び出しても安全です。続行されます。

## ルール

1. **常にプランファーストで進めること。** ドキュメントから抽出した手書きの散文を `generate_video` に渡さないでください。このスキルのポイントは、Ozor がスライドを直接参照することです。
2. **`generate_from_plan` の前に必ずプランをユーザーに表示し、承認を待つこと。** 生成はコストがかかるステップです。プランがチェックポイントです。
3. **ローカルファイルには `prepare_document_upload` ＋ curl を使用すること。** Base64 は小さなファイルのみに使用します。
4. **`generate_from_plan` 以降は、`projectId` をすべての場所で `videoId` として使用すること。** 同じ識別子です。
5. **すべての URL（共有、エディター、ダウンロード、埋め込み）を提示すること。**
6. **自分でドキュメントを要約しないこと。** Ozor の `analyze_document` がそれを実行し、ビジュアルを保持します。あなたの仕事は MCP をオーケストレーションし、プランをキュレーションすることであり、コンテンツを書き換えることではありません。