HyperFrames 스토리보드 하위 프리비즈 어댑터
어댑터 버전 0.4.0입니다. 입력 STORYBOARD_PREVIS_ADAPTER_V1, JSON 상태 검증 SCOPED_STATE_V2, 화면 ID PREVIS_RENDER_CONTENT_V2를 사용합니다. script-to-storyboard-prompts에서 전달된 마스터 스크립트를 편집 및 검토 가능한 3D 프리비즈로 컴파일하며, 원래 세그먼트 번호, 마스터 스크립트 및 예산 버전은 변경되지 않습니다. Three.js는 장면과 동작을 처리하고, HyperFrames는 프레임별로 내보냅니다.
시작하기
먼저 references/upstream-adapter.md를 읽어 사용자가 명확히 지정한 상위 프로젝트, 공식 세그먼트, 유효한 마스터 스크립트 버전 및 예산 버전을 찾습니다. 실제 본문, 장면 분석, 캐릭터/장면/소품 에셋 및 텍스트 형태의 시작/끝 상태를 읽습니다. 입력은 프로젝트 파일 또는 위치를 찾을 수 있는 세션 전달물일 수 있으며, 상위에서 별도의 스토리보드 디자인 테이블을 추가로 생성하도록 요구해서는 안 됩니다.
확인된 화면비, 전체 스타일, 세그먼트 최대 길이, 실제 계산된 런타임, 샷 순서, 캐릭터 키(센티미터), 조형 버전, 공간 방향, 원본 대사, 사운드 역할 및 공개 시점을 상속합니다. 이미 확인된 항목에 대해 다시 묻지 않으며, 이전 데모의 16:9/12초를 프로젝트 기본값으로 사용하지 않습니다. 렌더링 해상도와 fps가 지정되지 않은 경우 해당 화면비에 맞는 짝수 크기와 24fps를 선택하여 프리비즈 기술 매개변수로 기록합니다. 이로 인해 예산이 변경되거나 스토리가 추가되어서는 안 됩니다. 이번 어댑테이션에 영향을 미치는 누락된 항목만 집중적으로 질문합니다.
상위 7단계와 공식 세그먼트 범위는 계속 상위가 관리합니다. 이 어댑터는 권위 있는 상태를 읽고 <project>/previs/<formal_id>/<prompt_version>/에 자체 파일을 작성하며, 상위의 next_required, 커서, 오버라이드, 마스터 스크립트 또는 예산을 수정하지 않습니다. 사용자가 "계속"만 말하면 상위의 현재 목표를 실행합니다. 현재 요청에 프리비즈가 포함되거나 프리비즈 전달이 명시적으로 선택된 경우에만 개입합니다. 승인된 프리비즈 요청 내에서 읽기, 구축, 검사 및 내보내기를 연속적으로 완료할 수 있습니다.
상태 1.8/V3의 기존 텍스트 전달과 1.9/V4의 JSON 프로젝트를 지원합니다. JSON은 scripts/intake_storyboard.py를 사용하여 읽기 전용으로 추출합니다. 자유 텍스트/세션은 에이전트가 직접 읽고 정리하며, scripts/finalize_manual_intake.py를 사용하여 실제 증거를 봉인합니다. 이전 상태를 자동으로 마이그레이션하거나 추측하여 분석하지 않습니다. 다른 세그먼트를 정상적으로 진행해도 대상 세그먼트가 자동으로 무효화되지는 않습니다. 이 세그먼트 버전, 관련 에셋, 시작/끝 상태 또는 선택된 원본 텍스트가 변경되면 다시 어댑테이션합니다. 이전 버전 STATE_JSON 인테이크에 범위 검증 자료가 없는 경우 명시적으로 다시 추출하며, 자동 업그레이드하지 않습니다.
구도, 포지셔닝, 오클루전 및 타이밍을 확인하기에 충분한 가장 단순한 기하학적 형태를 사용합니다. 안정적인 색상 코드는 상위의 캐릭터에 해당하며, 환경은 관련 공간과 랜드마크만 유지합니다. 자세한 동작이 필요한 경우 사용 권한이 있는 모델을 연결합니다. 이미지 역할, 동작 역할 및 카메라 역할은 분리되어 있으며, 단순화된 프리비즈가 하위 모델이 픽셀 단위로 따르도록 강제할 수 있다고 약속하지 않습니다.
제작 및 수정
- 수신 및 매핑. 상위의
formal_id,prompt_version,budget_version, 에셋 ID, 샷 ID 및 시간 간격을 사용합니다. "샷 크기, 카메라 위치", "카메라 움직임 및 촬영 대상", "구도", "화면 내용"을 기하학적 스케일, 카메라, 시점 및 절대 시간 샘플로 변환합니다. 명확하지 않은 좌표는 실행 시 보충해야 할 항목으로 표시하며, 다시 연출하지 않습니다. 모든 샷과 동작 시간은 현재 공식 세그먼트의 0초를 기준으로 합니다. 단일 샷으로 구성된 단계는 여러 컷으로 나누지 않습니다. - 통합 공간 구축. 미터법, Y-up을 사용하고 방향을 명시합니다. 장면, 안정적인 캐릭터 ID, 소품 소속, 문 및 창문과 같은 동적 구조를 설정합니다. 캐릭터 외형은 명확한 색상 코드로 구분하며, 기하학적 스케일을 제공하여 화면만으로 비율을 추측하지 않도록 합니다.
- 결정론적 애니메이션 제작. 모든 프레임의 포즈, 위치, 카메라 및 문 상태는 반드시
t에 의해서만 결정되어야 합니다. 누적 변위, 고정되지 않은 난수 또는 이전 프레임의 상태를 사용하여 내보내기를 구동해서는 안 됩니다. 애니메이션 자료는AnimationMixer.setTime(t)또는 이와 동등한 절대 샘플링을 사용합니다. 브라우저 재생 타이머는 동일한renderAt(t)만 호출해야 합니다. - 검사 및 조정. 각 샷에 대해 마스터 스크립트, 컷 포인트 및 시작/끝 상태를 확인합니다. 화면 선택, 타임라인, 자유 관찰, 카메라/FOV 및 경로 키포인트 편집을 사용합니다. 템플릿은 현재 샷 궤적만 미리보기하며, 샷 수나 예산을 변경하지 않습니다. 확인된 샷/포지셔닝은 명시적으로 잠글 수 있습니다. 부분 실행 취소는 해당 대상의 가장 최근 보존된 수정만 되돌립니다. 공식적인 촬영 사실, 스토리, 런타임, 대사 또는 공개 시점의 변경이 발생하면 상위로 되돌려 수정해야 하며, 템플릿으로 기존 감독 의도를 대체할 수 없습니다. 편집 및 화면 피드백을 참조하세요.
- 검사 및 내보내기. 데이터 및 출처 검사, 에이전트 공간 샘플링, 실제 프레임별 내보내기를 수행하고 비디오 사양, 시작/끝 및 컷 포인트를 검사합니다. 명시된
framing.requiredActors에 대해서만 화면 내 등장 여부를 검사하며, 공간 경고는 화면을 확인해야 합니다. 프로그램이 경고 없음을 미디어 승인으로 대체하지 않습니다. 주석에는 실제 PNG, 세그먼트 내 타임코드, 객체 ID, 좌표 및 출처가 포함됩니다. 출처가 변경되면 만료로 표시하며, 처리됨과 승인됨은 분리합니다. - 어댑테이션 산출물 반환. 깨끗한 비디오, 소스 프로젝트, 출처 매핑, 원본 마스터 스크립트의 글자 그대로 사본, 참조 자료 부가 설명 및 실제 검사 영수증을 전달합니다. 상위 마스터 스크립트 또는 기존 모델 어댑테이션 초안은 계속 프롬프트의 출처로 사용되며, 템플릿에서 자동 생성된 짧은 프롬프트로 대체되지 않습니다. 영수증은 로컬 프리비즈 검사만을 나타냅니다. 최종 모델 제출 및 생성 능력은 해당 모델 어댑터가 처리합니다.
재사용 가능한 시작점
assets/starter/는 런타임 예제이며, 리뷰 페이지, 절대 시간 샘플링, 저장 및 내보내기를 포함합니다. 복도, 캐릭터, 소품, 세 개의 샷 및 문 열기 이벤트는 모두 데모 콘텐츠입니다. 상위를 수신할 때 실제 입력에 따라 기하학과 동작을 교체해야 하며, 이러한 스토리 요소를 자동으로 그대로 사용할 수 없습니다. 이미지가 없는 경우 유효한 텍스트 파일을 기반으로 색상 코드를 자리 표시자로 사용할 수 있으며, 공간과 타이밍만 검증한다는 점을 명확히 합니다.
node <skill-dir>/scripts/create_project.mjs <project-dir>
python -X utf8 <skill-dir>/scripts/intake_storyboard.py --state <상위 상태 JSON> --budget <상위 예산 JSON> --formal-id FORMAL_1 --out <project-dir>/upstream-intake.json
cd <project-dir>
npm install
npm run prepare-libs
전체 마스터 스크립트를 읽은 후, 실제 에셋, 샷 및 동작을 scene.json 및 장면 코드로 구현하고, assetBindings, sourceAssetIds 및 adaptationMap을 작성합니다. 그런 다음 다음 바인딩 및 검사를 실행하며, 바인딩을 건너뛰어 프로젝트가 데모 브랜치로 되돌아가지 않도록 해야 합니다:
npm run bind-upstream
npm run validate
npm run studio
sourceAssetIds.scenes/props는 이 세그먼트에서 실제로 사용되는 에셋 ID를 명시하며, 사용하지 않으면 []를 작성합니다. 캐릭터는 assetBindings를 통해 LOOK/STATE 버전과 키를 지정합니다. 수치, 버전 및 종속성 검사는 스토리, 대사 및 촬영 의미론적 검증을 대체하지 않습니다.
studio.html은 리뷰용이고, index.html은 깨끗한 내보내기용입니다. 캐릭터를 클릭하여 객체를 선택하고, 빈 공간을 클릭하여 화면 지점을 선택합니다. 단일 샷/키포인트 저장은 다른 초안을 포함하지 않습니다. 충돌은 명확하게 표시됩니다. 잠금은 서버 측에서 강제하며, 부분 실행 취소는 100개의 기록을 유지하고, 외부 변경으로 인한 충돌 시 덮어쓰기를 거부합니다. 캡처는 먼저 카메라 초안을 저장하거나 취소한 후, 공식 카메라로 전환하고, 선택 상자를 숨기고 비디오 프레임에 정렬합니다.
npm run lint
npm run spatial-check
npm run snapshot
npm run render
npm run handoff
npm run feedback
node scripts/bundle.mjs --project . --out <프로젝트 외부의 새 전달 패키지 디렉토리>
위 명령은 템플릿의 package.json에 정의되어 있습니다. 종속성은 검증된 HyperFrames 0.9.10 및 Three.js 0.187.0으로 고정됩니다. 새 환경에서 업데이트할 수 있지만, 먼저 현재 공식 API를 확인한 후 내보내기를 반복하여 검증해야 하며, 버전 번호만 변경해서는 안 됩니다.
필드는 장면 계약, 출처/수정은 상위 어댑터, 잠금/실행 취소/주석/공간 검사는 편집 및 화면 피드백을 참조하세요. 필요에 따라 렌더링 런타임, 반환 패키지 및 이동식 전달물을 읽으세요. 채택 및 보류된 외부 설계는 설계 근거를 참조하며, 외부 저장소를 제작의 선행 조건으로 간주할 필요는 없습니다.
전달 판단
- 내러티브 동작이 식별 가능해야 하며, 캐릭터/카메라/소품이 각 샷 간에 연속적인 근거를 가져야 합니다. 축선, 오클루전 및 관통에 대해 실제로 검사합니다. 의도적으로 축선을 넘는 경우 어떤 카메라가 방향을 설정했는지 설명합니다.
- 동일한 순간이 순차 재생, 직접 이동 및 역순 이동 후 동일한 상태를 제공해야 합니다. 최소 한 번의 비순차 샘플링(예:
8 → 2 → 8)을 검증합니다. - 원본 대사와 사운드 시간은 매핑과 영수증에 완전히 보존됩니다. 합성된 사운드, 구현된 입 모양 또는 복잡한 동작이 없는 경우 미검사 항목을 명시합니다. 에셋 프롬프트 전달됨, 이미지 존재, 이미지 읽음, 모델 바인딩됨을 각각 기록합니다.
- 동일한 공식 세그먼트는 기본적으로 독립적으로 내보냅니다. 장면 병합 또는 세그먼트 간 연결은 해당 요청이 있어야 하며, 오프셋 매핑을 별도로 저장합니다. 파일 경계가 자동으로 컷이 되지 않으며, 이전 세그먼트 이벤트를 반복하지 않고, 예산을 연장하거나 반올림하지 않습니다. 정수가 아닌 프레임 테일은 소스 클록과 최종 클록 매핑을 명시적으로 기록해야 합니다.
- 내보내기는 저장된 샷 데이터를 사용합니다. 첫 번째 프레임이 완전히 로드되었으며, 검은 프레임, 누락된 리소스, 실수로 화면에 들어간 리뷰 인터페이스 또는 컷 포인트 잔상이 없어야 합니다.
- 내보내기는 먼저 임시 저장하고 검사한 후 게시합니다. 실패 시 이전 성공 비디오를 보존합니다. 잠금, 기록 작성 및 주석은 화면 ID를 변경하지 않으며, 실제 카메라/경로/모델/코드 변경만이 이전 화면 증거를 만료시킵니다. 리뷰는 여전히 네 가지 관련 항목의 일관성을 요구합니다. 주석의 VERIFIED는 사용자가 별도의 증거를 등록했음을 의미할 뿐, 최종 모델 미디어 승인을 대체하지 않습니다.
- 모델 생성은 재질, 신체 부위 및 세부 사항을 재해석합니다. "반드시 보존해야 할 구도와 동작 의도"와 "자연스러운 연기와 질감 허용"을 명확히 작성하며, 픽셀 수준 또는 골격 수준의 제어를 약속하지 않습니다.
- 최종 보고서에는 실제 완료 및 실제 검증 범위를 명시합니다. 캐릭터 참조가 제공되지 않거나 하위 모델이 실행되지 않은 경우, 색상 블록 캐릭터를 캐릭터 일관성 검증으로 설명하지 않으며, 프리비즈 출력을 최종 생성 완성본으로 설명하지 않습니다.