# ShortVideoGenerator

Codex에서 혼자 사용하는 Shorts·TikTok·Reels 제작 프로젝트입니다. 주제와 언어를 받아 이야기, 음성 요청, 장면, 이미지 요청, 영상·합성 요청과 검수를 14단계로 연결합니다. 에이전트 8개와 스킬 15개, 입출력 양식·스키마를 제공합니다.

## 시작하기

이 저장소를 작업 폴더로 연 Codex 세션에서 다음처럼 요청합니다.

```text
$short-video-workflow
주제: 비가 온 뒤 물웅덩이는 어디로 사라질까
언어: 한국어
```

필수 제작 입력은 주제와 언어 두 개입니다. 이야기의 각도를 먼저 제안하고 사용자 검토를 기다립니다. 화면은 세로 9:16, 최종 영상은 3분 이내, 실제 음성에 따른 컷은 각각 5초 이내입니다. [기준 이미지](references/1.png)의 깔끔한 그림체를 사용합니다. 쉬운 표현을 사용하되 시청자를 어린이로 제한하지 않습니다.

현재 제공하는 것은 제작 지침과 요청·결과 양식입니다. TTS·이미지 API·영상 생성·합성을 실행하는 프로그램은 이후 연결합니다. 음성은 기존 conda qwen3-tts 환경의 Qwen3-TTS, 이미지는 gpt-image-2.5-sunburst를 사용하도록 지정했습니다. 영상 생성·합성 엔진은 별도 작업에서 선택합니다.

Codex는 프로젝트의 `.codex/agents/`와 `.agents/skills/`에서 지침을 찾습니다. 파일 파싱 검증과 실제 세션의 탐색은 다릅니다. 목록에 보이지 않으면 프로젝트 루트에서 새 세션을 열어 확인합니다. 사용자 전역 설정을 바꾸거나 추가 설치하지 않습니다. 형식·위치는 [공식 에이전트 안내](https://learn.chatgpt.com/docs/agent-configuration/subagents#custom-agents)와 [스킬 안내](https://learn.chatgpt.com/docs/build-skills#where-to-save-skills)를 따릅니다.

## 제작과 검토

| 단계 | 내용 | 담당 |
|---|---|---|
| 01–02 | 주제·각도 선택, 자료 조사 | topic-researcher |
| 03–04 | 쉬운 대본과 제목 | story-writer |
| 05–06 | 발화 단위와 Qwen3-TTS 요청·실제 결과 확인 | narration-designer |
| 07–09 | 실측 컷, 장면 연결, 인물·배경 | scene-director |
| 10–11 | 기준 이미지와 컷별 시작·끝 이미지 | visual-designer |
| 12–13 | 움직임과 합성·음성·자막 맞춤 | video-editor |
| 14 | 실제 완성본 검수 | video-reviewer |
| 전체 | 배정·진행·승인·재개·수정 | video-coordinator |

사용자 검토는 네 곳입니다.

1. 주제·각도 확정 후 자료 조사로 진행합니다.
2. 조사 근거·대본·제목 확정 후 TTS 분할로 진행합니다.
3. 실제 음성에 따른 컷·장면·반복 요소 확정 후 기준 이미지를 준비합니다.
4. 실제 완성본과 검수 보고를 확인한 뒤 제작을 완료합니다.

실제 응답이 있어야 승인입니다. 담당자의 추천이나 사용자 응답 없음은 승인으로 기록하지 않습니다. 기존의 같은 유효 승인 버전으로 재개할 때는 다시 승인받지 않습니다.

## 결과를 읽고 제출하기

각 제작은 `projects/<project_id>/project.json`과 `stages/<stage_id>/r<revision>/artifact.json`, 같은 폴더의 review.md를 사용합니다. 데이터 경로는 저장소 루트 기준입니다. 이전 버전을 보존하고 총괄만 현재 포인터·상태·승인을 바꿉니다.

- [공통 전달 계약](docs/workflow-contracts.md): 필드, 단계별 완료·보류 기준, 실측 시간, 승인과 수정
- [내용·구성 지침](docs/short-video-guide.md): 대본·제목·화면 설계와 검토 메모
- [참고 영상 분석](references/shorts/analysis.md): 네 영상의 구성·내용·좋은 점과 적용상 주의
- [양식](templates/), [진행 스키마](contracts/project.schema.json), [결과 스키마](contracts/artifact.schema.json)
- [연결 예제](examples/water-cycle/README.md): 텍스트 단계와 외부 결과가 없는 경우의 전달

외부 결과를 제출하려면 해당 단계의 `request` ID에 맞는 `result`를 채우고 실제 파일을 같은 제작의 media 폴더에 둡니다. 음성은 WAV, 이미지는 PNG, 영상은 MP4, 최종 자막은 SRT가 기본입니다. 실제 파일·형식·길이·크기를 확인한 경우만 media.verified=true로 기록합니다. TTS의 실제 사용 모델·화자와 통합 음성 구간도 제출합니다.

요청서만 있으면 result=null이며 실제 배정된 외부 단계는 awaiting_input으로 기다립니다. 부분 결과는 보존하지만 완료는 아닙니다. 시간 초과·지원하지 않는 언어·파일 부재·실측 불일치는 관련 단계로 돌아가 해결합니다.

## 재개와 개별 작업

```text
$short-video-workflow
기존 제작 <project_id>의 미해결 작업부터 이어 주세요.
```

특정 작업은 `$short-video-script`, `$short-video-scenes`, `$short-video-review`처럼 해당 스킬을 호출할 수 있습니다. 기존 제작·사용할 버전을 지정하며 필수 선행 결과와 검토를 건너뛰지 않습니다. 전체 스킬 이름은 `.agents/skills/`의 폴더 이름입니다.

수정은 새 버전을 만듭니다. 제목만 수정하면 관련 검토와 최종 합성·검수를 다시 확인하고, 변경과 관계없는 기존 음성·이미지를 유지합니다. 대본·음성·언어가 바뀌면 실제로 영향을 받는 결과를 확인해 갱신합니다.

## 확인된 범위

JSON·TOML·스킬 형식, 상대 경로, 단계·역할 연결, 예제의 승인·미디어 부재·수정·시간 문제를 확인합니다. 실제 Codex 세션의 자동 탐색과 TTS·이미지·영상 생성 성공은 파일 형식 검사만으로 확인할 수 없습니다. 검증 명령과 결과는 `docs/tracking/verification.md`에 기록합니다.