ShortVideoGenerator/docs/architecture.md

# 구성과 데이터 흐름

ShortVideoGenerator는 개인용 Codex 작업 지침으로 구성된다. 역할 TOML, 작업별 SKILL.md, JSON 양식·스키마를 함께 사용하고 승인된 로컬 실행 경로에 미디어 제작을 맡긴다. 서비스·데이터베이스는 두지 않는다.

`.codex/agents/`의 8개 역할은 `.agents/skills/`의 담당 작업을 사용한다. 스킬은 `templates/`의 빈 양식과 `contracts/`의 전달 구조를 읽고, 제작별 `projects/<project_id>/`에 결과 버전과 사람용 검토를 남긴다. 총괄만 공유 진행 기록을 관리한다. 참고 자료는 이야기 구성·그림체의 입력이고 다른 제작의 상태·승인을 가져오는 저장소가 아니다.

주제와 언어 요청은 총괄→주제·조사→작가→내레이션→장면→비주얼→영상·편집→검수 순으로 전달된다. 주제, 대본·제목, 장면, 완성본의 사용자 검토가 다음 구간을 연다. 검토를 기다리는 동안 경계를 넘는 새 후속 작업을 실행하지 않는다.

음성 요청은 기존 conda qwen3-tts 환경의 Qwen3-TTS로, 새 모델·기준·컷 이미지·영상 요청은 Blender로 전달한다. 기존 1.0 이미지 모델 계약과 실제 결과는 보존하고 새 1.1과 함께 읽는다. 모델·화자·지원 언어·결과 파일은 실제 제작 환경에서 확인해야 하며 설치 여부가 추론 성공을 뜻하지 않는다.

영상·합성 경계에는 시작/끝 이미지·움직임·컷 길이 또는 클립·음성·자막의 요청과 실제 결과 파일 정보가 오간다. 1.1은 Blender의 .blend 원본·RenderProfile·Scene 이름·논리 프레임을 명시하고 PNG·MP4 결과를 별도로 기록한다. 합성은 승인된 기존 Remotion + FFmpeg 경로를 재사용한다. 실행파일의 외부 경로·인증정보는 전달 계약에 기록하지 않는다. 외부 결과가 없으면 진행이 멈추며 예상이나 모의 데이터를 실제 결과로 승격하지 않는다.

대표적인 재개 요청은 기존 입력·포인터·승인·파일을 읽고 가장 앞선 미해결 단계에 배정된다. 결과가 갱신되면 실제 inputs 관계로 종속 결과를 다시 확인한다. 제목만 수정한 경우 새 제목은 합성과 검수에 전달되며 기존 음성·이미지는 유지된다.

08의 제한된 대표 화면·짧은 움직임 제작만 scenes 승인 전 품질 검토를 위해 허용한다. 이 자료는 정식 10–12 완료가 아니다. 새 08·09의 scenes 승인 후 전체 모델·끝점·클립을 제작한다. 주제별 모델·장면은 해당 제작의 근거로 작성하며 다른 주제의 3D 자산을 자동 생성한다고 보장하지 않는다.