ShortVideoGenerator/tools/blender/README.md

# 저장소 안의 Blender 렌더 실행기

필수 제작 입력은 기존대로 주제·언어다. 아래 인자는 담당자가 작성한 요청을 실제 실행하기 위한 내부 값이다. 이미 설치된 Blender와 기존 Remotion 패키지에 들어 있는 FFmpeg·ffprobe를 지정한다. 설치·전역 설정 변경·외부 서비스 연결은 하지 않는다. Python 실행 환경에 기존 `jsonschema`가 있어야 하며 `bpy`는 Blender 내부에서 실행한다.

## 원본 검사

저장소 루트에서 실행한다. 파일 경로는 저장소 상대 경로다. 실행파일 경로는 명령에만 넣고 제작 JSON에 기록하지 않는다.

```powershell
C:/Users/baram/anaconda3/python.exe -B -X utf8 tools/blender/run.py inspect --blender 'C:/Program Files/Blender Foundation/Blender 5.2/blender.exe' --source projects/<제작물>/stages/08-scenes/r2/sample.blend --scene Droplet --require-object Droplet
```

원본을 실제 열어 SHA-256·Blender 버전·Scene·카메라·객체 이름과 외부 의존성을 확인한다. 필요한 객체 대신 컬렉션 이름을 지정할 수 있다. 외부 .blend 링크·포장되지 않은 이미지/글꼴·외부 미디어/볼륨·외부 캐시/영상 시퀀스는 거부한다. 외부 파일 없이 재현할 수 있는 모델과 키프레임이 대상이다. 생성 예정 원본은 `verified=false`로 시작하고, 실제 검사 뒤에 받은 `scene_file`을 담당자가 결과에 반영한다. 검사 전에 검증 메타데이터를 요구하는 순환 조건을 만들지 않는다.

## 대표 렌더와 정식 제작

대표 렌더는 총괄이 새 08 초안의 현재 포인터를 설정한 뒤 실행한다. topic/story의 기존 유효 승인은 필요하지만 새 scenes 승인은 아직 필요하지 않다. 08의 `preview.scene_file`과 `preview.render_profile`을 먼저 작성한다. 대표 컷 1–3개만 지정할 수 있으며 한 영상은 5초 이하다. 전체 장면은 08 본문에 설계하되 대표 렌더는 제한된 품질 검토 근거다.

```powershell
C:/Users/baram/anaconda3/python.exe -B -X utf8 tools/blender/run.py render --mode preview --project projects/<제작물>/project.json --artifact projects/<제작물>/stages/08-scenes/r2/artifact.json --output-revision 2 --source projects/<제작물>/stages/08-scenes/r2/sample.blend --scene Droplet --require-object Droplet --cut-id c01 --frame 0 --blender 'C:/Program Files/Blender Foundation/Blender 5.2/blender.exe' --ffmpeg '<기존 ffmpeg.exe>' --ffprobe '<기존 ffprobe.exe>'
```

이미지는 `--frame N`, 영상은 `--start N --end M`을 사용한다. 논리 0은 Blender 1이며 영상은 `[N,M)`다. 컷 끝점 PNG와 MP4의 마지막 프레임은 다르다. 이번 물 영상의 전체 논리 끝점은 5528이지만, 최종 MP4는 0–5527의 5528프레임이다. 인접 cut의 같은 논리 시각도 Scene 이름을 별도로 지정한다.

정식 제작은 `--mode production`과 1.1·visual_engine=Blender인 현재 진행 기록 및 10/11/12 요청을 사용한다. 기존 1.0 선행 단계는 보존·참조한다. 현재 topic/story/scenes 승인·feedback·승인 버전, 유효한 선행 입력, 실제 단위/통합 WAV·컷·선행 .blend/PNG/MP4를 확인한다. pending/changes_requested/stale 또는 옛 08/09 승인으로 새 제작을 시작할 수 없다. 원본 해시 변경·Scene/객체 누락·실측과 다른 프레임·다른 제작물 파일·이전 시각 제작 버전의 파일·누락 참조·프로필 불일치도 거부한다. 08/10/11의 원본과 결과 미디어는 해당 artifact 자신의 버전 폴더 아래에 있어야 한다. 기존 WAV의 media/06-tts/r1 경로는 유지할 수 있다.

| 대상 | 지정할 요청 항목 |
|---|---|
| 10 기준 렌더 | `--reference-id 기준ID --frame 논리프레임 --require-object 실제객체명` |
| 11 컷 끝점 PNG | `--frame-id 프레임ID --frame 요청frame_index` |
| 12 컷 영상 | `--cut-id 컷ID --start 요청start_frame --end 요청end_frame` |

10 원본은 같은 새 단계 버전 아래에 있어야 한다. 11은 request.scene_path, 12는 검증된 11 result.scene_file을 그대로 사용한다. 11/12 Scene은 요청의 이름과 같아야 한다. cut 연결은 양쪽 Scene 이름을 구별한다. continuous 연결은 같은 Scene·논리 프레임을 쓰며, 완료된 11 결과의 두 경계 ID는 같은 실제 PNG 경로를 공유한다. CLI는 출력 경로를 자동으로 공유하지 않으므로 담당자가 동일 경계의 한 렌더를 양쪽 ID에 참조한다.

렌더 엔진·장치·fps·해상도·샘플·seed는 해당 요청의 RenderProfile에서 읽고 실제 적용 값을 대조한다. EEVEE는 GPU, Cycles는 CPU/GPU다. 이 Blender의 EEVEE에는 임의 seed 설정 API가 없으므로 기본 seed=0만 허용하며 다른 seed는 실패한다. Cycles에서는 실제 seed를 적용한다. Cycles GPU는 기존 OPTIX 장치를 실제 확인하고 미지원이면 실패한다. 이 경로의 GPU 성공은 따로 검사해야 한다. 요청에 고정된 설정을 조용히 다른 엔진으로 바꾸지 않는다. H.264를 위해 해상도는 짝수이고 9:16이어야 한다.

## 결과와 실패 기록

렌더는 해당 artifact.json과 같은 버전 폴더의 `render-attempts/<식별값>-<유일ID>/`에만 PNG·MP4·로그·검사 결과를 쓴다. 식별값은 원본 전체 SHA-256·프로필·Scene·프레임·Blender 내부 스크립트 해시를 포함한다. 이전 결과나 캐시를 재사용하지 않는다. 새 시도는 이전 시도를 덮어쓰지 않으며 실패/부분 파일도 보존한다.

`evidence.json`에는 실제 검사한 scene_file·render_profile·scene_name·logical_frames·media와 `visual_review="not_checked"`가 있다. PNG/MP4를 실제 probe·전체 디코드하고 해상도·코덱·프레임 수·fps·길이를 확인한 뒤에만 media.verified=true를 쓴다. PNG는 실제 PNG, MP4는 단일 무음 H.264 트랙이다. 실패 시 failure.json에 이유를 남기며 성공 증거를 만들지 않는다.

이 증거는 전체 단계 완료·사용자 승인·미적 품질 평가를 뜻하지 않는다. 실행기는 artifact.json과 project.json을 수정하지 않는다. 담당자가 실제 결과를 자기 새 버전 결과에 반영하고 총괄이 완료·검토 상태를 확인한다. 08 대표 결과로 10–12를 완료 처리하지 않는다.

## 검증

```powershell
C:/Users/baram/anaconda3/python.exe -B -X utf8 tools/blender/test_runner.py
C:/Users/baram/anaconda3/python.exe -B -X utf8 contracts/check.py
C:/Users/baram/anaconda3/python.exe -B -X utf8 tools/blender/smoke.py --engine BLENDER_EEVEE --blender 'C:/Program Files/Blender Foundation/Blender 5.2/blender.exe' --ffmpeg 'C:/git/ShortVideoGenerator/projects/water-hydrogen-bond-surface-tension/renderer/node_modules/@remotion/compositor-win32-x64-msvc/ffmpeg.exe' --ffprobe 'C:/git/ShortVideoGenerator/projects/water-hydrogen-bond-surface-tension/renderer/node_modules/@remotion/compositor-win32-x64-msvc/ffprobe.exe'
```

`smoke.py`는 사용자 영상과 별개로 .cache에 작은 움직이는 구·두 Scene·모의 승인 기록을 만든다. 90×160·10fps·1초로 실제 .blend 재열기·PNG/MP4 전체 디코드·움직임·다른 Scene의 같은 논리 시각·승인된 10/11/12 요청 실행·누락 Scene/객체·외부 의존성·실제 Scene 범위 실패를 확인한다. `--engine CYCLES`는 CPU 경로다. 제작물·기존 실제 승인 기록은 변경하지 않으며, 이것을 사용자의 물 영상 제작 성공이나 시각 품질 승인으로 보고하지 않는다.