cinematic-3d-video

시네마틱 3D 비디오

Claude는 직접 비디오 픽셀을 생성할 수 없지만, 3D 장면을 코드로 작성하고, 프레임별로 렌더링한 후 인코딩할 수 있습니다. 이 스킬이 그 파이프라인입니다.

scene (HTML + Three.js)  -- window.seek(t) -->  scripts/render.mjs  -->  headless Chrome screenshots  -->  ffmpeg  -->  MP4

render.mjs는 실제 시간 대신 가상 시계를 사용합니다. 결과는 모든 기기에서 동일하며, 무거운 장면이 끊기지 않고(단지 더 느리게 렌더링될 뿐) 실행됩니다. 이러한 이유로 장면은 시간의 순수 함수여야 합니다("장면 규칙" 참조).

1. 먼저 도구 확인

node -v        # 22 이상 (render.mjs는 내장 WebSocket 사용)
ffmpeg -version

Chrome, Edge 또는 Chromium이 설치되어 있어야 합니다(자동으로 찾음; CHROME_PATH로 재정의 가능). Three.js는 장면에서 CDN을 통해 로드되므로, Three.js를 자체 포함(vendor)하지 않는 한 렌더링하는 기계는 인터넷에 연결되어야 합니다(references/troubleshooting.md 참조). 도구가 누락된 경우 사용자에게 정확히 무엇을 설치해야 하는지 알리고 해결 방법을 추측하지 마세요. Blender는 포토리얼 경로에만 필요합니다.

새 기계에서 한 번 의존성 없는 스모크 테스트를 실행하세요. Chrome, WebGL, ffmpeg가 모두 작동함을 증명하므로 이후 문제는 설정이 아닌 장면에 있음을 확인할 수 있습니다:

node <skill-dir>/scripts/render.mjs <skill-dir>/templates/smoke-test.html --out smoke.mp4 --duration 2 --width 640 --height 360

2. 워크플로우

1. 간단히 요약: 주제, 분위기, 길이, 화면 비율, 텍스트, 오디오를 한두 문장으로 정리하세요. 사용자가 명확하지 않을 경우 기본값을 선택하고 선택한 사항을 알리세요: 1920x1080, 30fps, 8-12초, 어두운 배경, 하나의 주 오브젝트, 하나의 카메라 이동, 하나의 제목. 세로(TikTok/Reels/Shorts)는 1080x1920입니다. 시작하기 전에 한 개 이상의 짧은 질문은 거의 가치가 없습니다. 첫 번째 렌더링이 최고의 질문입니다.
2. 스타터에서 시작하세요.templates/starter/를 작업 디렉토리로 복사(cp -r)하고 index.html을 편집하세요. 렌더러, 톤 매핑, 스튜디오 반사, 블룸, 그림자, 시드 입자, 카메라 경로, HTML 타이틀 오버레이, 타임라인 훅이 이미 포함되어 있습니다. 히어로 오브젝트, 팔레트, 카메라 경로, 텍스트를 바꾸고 기본 구조는 유지하세요.
3. 비디오 렌더링 전에 스틸 프레임 확인하세요. 가장 바쁜 순간의 몇몇 프레임을 전체 크기로 렌더링하고 열어보세요:

   node <skill-dir>/scripts/render.mjs my-video/index.html --stills 0,2,4,6,7.5 --out my-video/stills
   

   여기서 구도, 노출, 색상, 텍스트 가독성을 수정하세요. 스틸은 1-2초 걸리지만, 전체 렌더링은 몇 분이 걸립니다.
4. 한 번 렌더링하세요. 설정을 선택한 후 전체 비디오를 렌더링하세요:

   node <skill-dir>/scripts/render.mjs my-video/index.html --out my-video/video.mp4 --width 1920 --height 1080 --fps 30 --scale 2
   

   --scale 2는 2배 해상도로 렌더링 후 다운샘플링하여 깜빡임 가장자리를 제거합니다(최종 렌더링에만 가치 있음). 긴 렌더링은 백그라운드에서 실행하고 진행 상황을 주기적으로 확인하여, 사용자가 조용한 터미널을 응시하지 않도록 하세요.
5. 파일 자체를 확인하세요.ffprobe로 지속 시간, 크기, fps를 확인하고; MP4에서 두세 프레임을 추출하여 보세요(ffmpeg -ss 3 -i video.mp4 -frames:v 1 check.png). 그런 다음 MP4와 장면 폴더를 사용자에게 전달하여 조정할 수 있도록 하세요.
6. 수정은 장면을 변경하고 다시 렌더링합니다. 한 순간을 반복할 때는 --start/--end를 사용하여 범위만 다시 렌더링하세요.

3. 장면 규칙 (그리고 이유)

• 애니메이션되는 모든 것은 t(초 단위)의 순수 함수여야 하며, update(t) 내부에 설정됩니다. Math.random()(시드 rng() 사용), Date.now(), clock.getDelta(), 프레임 간 상태 누적을 사용하지 마세요. 렌더러는 seek을 어떤 순서로든 호출할 수 있으며, 브라우저에서의 미리보기가 비디오와 정확히 일치해야 합니다.
• 페이지 계약은 window.seek(t)(동기적으로 그리기), window.__duration(초) 및 에셋이 로드되면 window.__ready = true입니다. lib/stage.js의 installTimeline()이 이 세 가지를 모두 수행합니다. 자세한 내용은 references/contract.md를 참조하세요.
• 1.0 이상의 HDR 색상은 빛나게 합니다. 블룸은 임계값보다 밝은 픽셀만 캡처하므로, 발광 부분은 new THREE.Color(hex).multiplyScalar(3..6)을 사용하고, 일반 표면은 임계값 아래로 유지하세요.
• 텍스트는 캔버스 위의 HTML/CSS입니다(스크린샷에는 페이지가 포함됨). 어떤 해상도에서도 선명하며, 폰트 파일이 필요 없고, update(t) 내부에서 일반 스타일 변경으로 애니메이션됩니다.
• 에셋을 로드할 때는 __ready를 설정하기 전에 await를 사용하세요(GLTF 모델, 텍스처, 폰트). 에셋이 도착하기 전에 렌더링된 프레임은 비디오에서 영구적인 결함이 됩니다.
• 하나의 조명 스토리를 유지하세요: 키 라이트, 하나 또는 두 개의 컬러 림 라이트, 이미지 기반 반사. 반사 재질(금속, 유리, 클리어코트)을 어둡고 약간 반사하는 바닥 위에 배치하면 "웹 데모"가 아닌 "3D 애니메이션"으로 읽힙니다. references/cinematography.md에는 카메라 이동, 속도 조절, 이징, 조명 및 색상에 대한 레시피가 있습니다.

4. 여러 장면, 오디오, 다른 형식

• 다중 장면 비디오: 각 장면을 동일한 크기, fps 및 인코더 설정으로 별도의 MP4로 렌더링한 후, 재인코딩 없이 연결하세요: list.txt에 file 'a.mp4' 라인을 작성하고 ffmpeg -f concat -safe 0 -i list.txt -c copy out.mp4를 실행하세요. 크로스페이드는 장면의 자체 타임라인 안에 배치(한 장면의 마지막 1초와 다음 장면의 첫 1초가 모두 검정/색상으로 페이드)하는 것이 완성된 파일을 블렌딩하는 것보다 낫습니다. 후자는 모든 것을 두 번 인코딩합니다.
• 오디오: --audio track.mp3는 오디오를 믹싱하고 비디오에 맞게 자릅니다. 나중에 사운드만 변경하려면: ffmpeg -i video.mp4 -i new.mp3 -map 0:v -map 1:a -c:v copy -shortest out.mp4.
• GIF / WebM / 작은 복사본: 완성된 MP4를 ffmpeg로 재인코딩하고, 형식 변경을 위해 다시 렌더링하지 마세요.
• 하나의 장면 변경은 해당 장면 파일을 다시 렌더링하고(크로스페이드가 포함된 경우에만 다음 파일도 다시 렌더링)합니다.

5. Blender를 사용해야 하는 경우

실시간 엔진이 제대로 흉내낼 수 없는 작업(경로 추적 유리 및 코스틱스, 볼륨 조명, 서브서피스 스킨, 유체/천/연기 시뮬레이션, 완전 포토리얼 제품 샷)이 필요할 때만 Blender(references/blender.md, templates/blender/render_blender.py)를 사용하세요. Blender는 프레임당 훨씬 느리고 Blender 4+가 설치되어 있어야 합니다. 그 외의 경우 Three.js가 훨씬 짧은 시간에 좋은 결과를 내고 더 빠르게 반복할 수 있습니다.

참조 파일

파일	읽어야 할 때
references/contract.md	처음부터 장면 작성, 모델/텍스처 로드, 또는 "__ready를 설정하지 않음" 디버깅 시
references/cinematography.md	결과를 좋게 만들기 위해: 카메라, 조명, 재질, 이징, 속도, 색상, 텍스트, 입자
references/troubleshooting.md	검은 프레임, 느린 렌더링, CDN/오프라인 설정, Windows/macOS/Linux 특이사항, 비정상 크기
references/blender.md	포토리얼 또는 시뮬레이션 작업 시
scripts/render.mjs	모든 옵션: node scripts/render.mjs --help