streamingle-unity-utilities/CameraAI~/README.md

# Mingle Camera Work AI Unity Package

생성할 새 Unity Timeline에서 캐릭터 모션과 원본 음원을 60 FPS로 추출하고,
완전히 새로 만든 카메라를 비파괴 프리뷰 Timeline으로 불러옵니다. 생성 입력에
Cinemachine Track이나 기존 카메라 애니메이션은 필요하지 않으며, 존재해도
생성 입력으로 사용하지 않습니다.
축적된 작업자 데이터를 재구성하는 고품질 생성 엔진은
`CWCameraWorker.exe`로 실행됩니다. 워커에 Python 런타임과 라이브러리가
포함되므로 작업 PC에 Python을 별도로 설치하지 않아도 됩니다.
동일한 구간과 음원으로 후보 A/B를 녹화하고 Camera AI Review Portal에
반입할 provenance manifest도 생성합니다.

설치와 씬 요구사항은 저장소의 `docs/UNITY_COLLECTION.md`를 참고하세요.
워커 빌드와 배포 검증은 `docs/CLI_WORKER_PACKAGING.md`에 정리되어 있습니다.

Unity Package Manager의 `Add package from git URL`에는 다음 주소를 사용할 수
있습니다.

`https://kindnick-git.duckdns.org/mingle/streamingle-unity-utilities.git?path=/CameraAI~#v0.1.16`

배포 패키지에는 Windows x64용 `CWCameraWorker` 폴더 전체가 포함됩니다.
Python은 따로 설치하지 않아도 되지만, Git 패키지의 대용량 바이너리를 받으려면
Unity를 열기 전에 Git과 Git LFS를 설치해야 합니다. Worker는 단일 파일 EXE가
아니므로 `CWCameraWorker.exe`와 같은 폴더의 `_internal` 내용을 함께 유지해야
합니다.

카메라 생성에 필요한 준비된 참조 카메라·모션 데이터와 컷 모델은 패키지의
읽기 전용 `RuntimeData~`에 포함됩니다. 별도의 `CW-AI` 체크아웃은 필요하지
않습니다. 더 최신의 권한 제어 데이터가 있다면 `CWAI_ROOT` 환경 변수, Unity
프로젝트 옆의 `CW-AI` 폴더 또는 생성 창의
`고급 · 진단 > 참조 데이터 루트`에서 선택적으로 덮어쓸 수 있습니다.
상세 설치 절차는 `Documentation~/EXTERNAL_INSTALLATION.md`를 참고하세요.
참조 데이터는 읽기 전용이어도 됩니다. 반복 생성 캐시는 기본적으로 현재 Unity
프로젝트의 `Library/CWAI`에 저장되며, 필요하면 `CWAI_CACHE_ROOT` 환경 변수로
별도의 쓰기 가능한 위치를 지정할 수 있습니다.

메뉴:

- `Tools/Streamingle/AI 카메라 생성`
- `Tools/Streamingle/Timeline/Export Camera Dataset (60 FPS)`
- `Tools/Streamingle/Timeline/Create AI Camera Preview`
- `Tools/Streamingle/Timeline/Remove AI Camera Preview`
- `Tools/Streamingle/Timeline/Render AI Camera A-B`

## 카메라 생성

일반 작업자는 다음 세 단계만 사용하면 됩니다.

1. `Tools > Streamingle > AI 카메라 생성`을 엽니다.
2. 모션 트랙과 Audio Track만 들어 있는 `원본 Timeline`을 선택하고
   `새 카메라 생성하기`를 누릅니다. 입력 추출, 새 카메라 생성과 Timeline
   반영이 자동으로 이어집니다. 실행 중에는 현재 단계, 경과 시간과 예상
   남은 시간 범위가 표시됩니다.
3. 결과를 확인한 뒤 Timeline의 생성 카메라 clip 또는 Hierarchy의 카메라를
   선택하고 필요하면 `선택한 카메라만 다시 생성` 또는
   `완성본 씬으로 저장`을 누릅니다.

Timeline이 하나뿐이면 자동으로 선택됩니다. 특별한 연출 의도가 없다면
`연출 설정 (선택)`도 열 필요가 없습니다. 샷 거리, 움직임, 인물 구도와
강도를 직접 지정하려는 경우에만 펼칩니다.

경로, 워커 실행 파일, 내부 입력 ID, Seed, 캐시, 수동 가져오기와 로그는
`고급 설정 및 관리` 안에 있습니다. 기본 생성에서는 입력할 필요가 없습니다.

기본 화면에는 `데이터셋 곡`을 고르는 절차가 없습니다. 여기서 “입력”은 지금
선택한 새 Timeline 한 개이고, 고품질 워커가 내부적으로 참고하는 누적
작업자 카메라 데이터는 별도의 참조 라이브러리입니다. 새 Timeline을 그
라이브러리 안의 기존 곡과 연결하거나 기존 카메라를 정답으로 제공할 필요가
없습니다.

배포된 워커는 다음 명령을 제공합니다. Unity 생성 창은 `generate`와
`prepare-cache`를 호출하고, 설치·배포 확인에는 `version`과 `doctor`를
사용합니다.

```powershell
CWCameraWorker.exe version --json
CWCameraWorker.exe doctor
CWCameraWorker.exe prepare-cache --help
CWCameraWorker.exe generate --help
```

`version --json`은 워커의 CLI 계약 버전을 확인하고, `doctor`는 배포 파일과
필수 데이터 경로를 진단합니다. `prepare-cache`는 반복 생성용
준비 캐시를 구성하며, `generate`는 전체 생성과 선택 샷 재생성을 처리합니다.

전체 결과는 카메라별 CinemachineCamera, Animator, Animation Track과 `.anim`으로
1:1 분리됩니다. 각 카메라의 Transform/Track Offset과 커브를 다른 샷에 영향을
주지 않고 조정할 수 있습니다. 선택 샷 재생성은 기존 clip GUID와 컷 경계를
유지하고 나머지 샷을 보존합니다. `Balanced` 또는 `Editable` 키 단순화를
선택하면 위치·Quaternion·렌즈 오차 한도 안에서 키가 축약됩니다.

예상 시간은 Timeline 길이와 준비·후보 캐시 상태를 기준으로 범위로 표시합니다.
같은 PC에서 완료된 전체 생성과 선택 샷 생성 시간을 별도로 누적해 이후 예측을
보정합니다. 준비 캐시 생성 시간은 실제 카메라 생성 기록에 섞지 않습니다.

처음 실행하는 PC에서는 `고품질 생성 준비 캐시 만들기 / 갱신`을
한 번 실행합니다. 준비 모델 seed와 후보 seed는 분리되어 있으므로 이후
선택 샷 재생성에서 seed가 바뀌어도 같은 무결성 검증 캐시를 재사용합니다.

`Seed`는 안전 검사를 통과하고 최종 화면에서 서로 구별되는 카메라
후보 중 하나를 결정론적으로 선택합니다. 같은 Seed와 입력은 같은 결과를
재현하며, 안전한 구별 후보가 둘 이상이면 인접 Seed는 다른 후보를 선택합니다.
후보는 최고 안전 후보와의 선택 점수 차이가 허용 범위 안인 경우에만 사용되어,
다양성을 위해 구도 품질을 과도하게 낮추지 않습니다.
다음 샷의 계획 문맥은 최고 안전 후보로 고정되므로, 앞 샷에서 Seed로 고른
후보가 뒤 샷의 후보 풀을 바꾸어 다시 같은 카메라로 수렴하지 않습니다.
명시한 `static` 연출은 유지되고, 안전한 구별 후보가 하나뿐인 샷은 Seed를
바꿔도 같을 수 있습니다. 기존 결과를 다시 적용하는 기능은 새 후보를 생성하지
않으므로 Seed를 사용하지 않습니다.

`metadata.json`의 샷별 `variationSeed`, `variationPoolSize`,
`variationIndex`, `variationApplied`, `variationQualityEligibleCandidateCount`,
`variationSelectedScoreDeltaFromBest`, `sequenceContinuationPolicy`와 전체 요약
`seedVariationPolicy`,
`seedVariationAppliedShotCount`, `seedVariationPoolSizeMinMedianMax`로 Seed가
실제로 적용된 범위와 후보 풀이 하나뿐이었던 예외를 확인할 수 있습니다.

생성된 회전은 AnimationClip에 굽고 런타임 LookAt이나 Tracking Target을
사용하지 않습니다. 캐릭터 관절 envelope와 의미 기반 구도를 검증하며,
안전한 후보가 없으면 결과 생성을 중단합니다. 사용자가 `static` 또는
움직임 강도 0을 명시했을 때는 정지 의도를 유지합니다.

가져오기, 제거, 전체/선택 샷 재생성은 모두 같은 원본 Director scope만
사용합니다. 씬에 사용할 수 있는 `Timeline` Director가 하나뿐이면 자동으로
선택됩니다.

`현재 씬을 AI Camera Final 복사본으로 저장`은 preview Timeline과 생성된 `.anim`
파일을 Final 전용 asset 폴더로 복제하고, 복사된 씬이 그 복제본을 참조하게 합니다.
따라서 이후 작업 씬에서 preview를 제거하거나 재생성해도 Final 씬의 참조가 끊기지
않습니다.

샷별 JSON 예시는 `Samples~/CameraDirections/camera_directives.example.json`
에 있습니다.

## A/B 렌더

1. 씬과 Timeline을 저장합니다.
2. 두 생성 결과 디렉터리의 `metadata.json`, `world_camera.f32`,
   `time.f64`, 선택적인 `shots.json`이 완전한지 확인합니다.
3. A/B 렌더 창에서 두 디렉터리와 `[startFrame, endFrameExclusive)`
   구간을 선택합니다.
4. 렌더러는 두 후보의 sample rate, frame count, `time.f64`, song ID,
   evaluation group, aspect ratio가 같은지 먼저 검증합니다.
5. 후보마다 원본 씬을 다시 열고 Preview Timeline을 만든 뒤, 기존
   RecorderTrack은 mute하고 MainCamera와 Timeline audio를 녹화합니다.
6. 완료 폴더의 `manifest.json`과 두 영상을 웹 포털에 함께 반입합니다.

작업 상태는 `Library/CWAI/ABRender/active_job.json`에 저장되어 Play Mode
domain reload 뒤에도 이어집니다. 실패·취소 시 원본 scene setup을
복구하며, 원본 Timeline과 생성 카메라 파일은 수정하지 않습니다.

UniCLI 공개 진입점:

- `AICameraABRenderRunner.StartABRenderForCli(...)`
- `AICameraABRenderRunner.GetABRenderStatusForCli(jobId)`
- `AICameraABRenderRunner.CancelABRenderForCli(jobId)`