Mintii-Labs/ozor-skills

Ozor 문서-비디오 변환

Ozor.ai에서 문서를 비디오로 변환하는 종단간 프로세스입니다. 실제 파일(PDF, PPTX, DOCX 등)을 받아 Ozor 측에서 분석하여 구조화된 계획을 생성하고, 사용자가 계획을 승인/편집한 후 슬라이드 시각적 요소를 유지하면서 비디오를 생성하고 내보냅니다.

사용 시기

입력이 문서/파일일 때 이 스킬을 사용하세요. 신호:

• 사용자가 PDF, PPTX, DOCX, Keynote 내보내기, 슬라이드 데크, 제안서, 백서, 보고서, 원페이지를 첨부하거나 참조함
• "이 데크를 비디오로 만들어 줘"
• "이 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단계 — 계획을 사용자에게 제시하고 중지

이것은 중요한 단계입니다. 생성을 건너뛰지 마세요. 사용자에게 계획의 간결한 렌더링을 보여줍니다:

📋 "<문서 이름>"의 Ozor 계획

**형식:** 16:9 (또는 9:16)
**예상 시간:** ~X초
**장면 수:** N

(1) <장면 제목> — <한 줄 내레이션/시각적 요소>
(2) <장면 제목> — <한 줄 내레이션/시각적 요소>
...

이 상태로 생성할까요, 아니면 변경할 부분이 있나요? 다음을 할 수 있습니다:
- 장면 편집 ("scene 2를 ...로 변경")
- 장면 재정렬/삭제/추가
- 톤, 길이 또는 형식 변경
- 승인 및 생성

그런 다음 사용자가 승인하거나 편집을 요청할 때까지 기다리세요. 스스로 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단계 — 결과 표시

🎬 "<문서 이름>"의 비디오 준비 완료

**공유:** <shareUrl>
**편집기:** <editorUrl>
**다운로드:** <downloadUrl>

**임베드:**
```html
<iframe ...></iframe>

같은 계획으로 9:16 소셜 컷을 원하시면 다시 생성할 수 있습니다.

## `analyze_document`에 전달할 힌트

사용자가 언급했거나 문서에서 명확한 경우 다음 중 하나를 전달하세요:

- `targetDuration` — 예: `"60s"`, `"90s"`. 제안서/데크의 기본값 ~60초, 원페이지의 기본값 ~30초.
- `format` — `"16:9"` (기본값) 또는 소셜용 `"9:16"`.
- `audience` — 투자자, 고객, 개발자, 내부 팀, ...
- `tone` — 자신감, 따뜻함, 기술적, 활기찬, ...
- `focus` — 선택 사항으로, "4페이지의 지표에 집중" 또는 "팀 슬라이드 건너뛰기"와 같은 한 줄 메모.

## 문서 유형별 조정

| 문서 | 기본 시간 | 형식 | 톤 | 초점 |
|----------|------------------|--------|------|-------|
| 피치 데크 | 60–90초 | 16:9 | 자신감 | 문제 → 해결책 → 트랙션 → CTA |
| 제안서 (DOCX) | 60초 | 16:9 | 전문적 | 결과 + 가격 + 다음 단계 |
| 백서/보고서 | 60–90초 | 16:9 | 권위적 | 3가지 주요 발견, CTA에서 전체 문서 링크 |
| 영업 원페이지 | 30–45초 | 16:9 | 강렬함 | 훅 → 3가지 혜택 → CTA |
| 릴리스 노트 | 30–45초 | 16:9 | 활기찬 | 기능당 하나의 장면 |
| 교육/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를 조정하고 계획을 관리하는 것이지, 콘텐츠를 다시 작성하는 것이 아닙니다.