Seek 엔진 (코스 07단계)
여기서 필름은 비디오가 아니라 프로그램입니다. 페이지가 임의의 시간 t에 대해 정확한 프레임을 그리고, 렌더러는 시간을 따라가며 각 프레임을 캡처하여 ffmpeg로 전달합니다. 시계(clock)에 의존하는 것이 없으므로 모든 실행에서 동일한 렌더 결과가 나오며, 수정은 한 줄 편집 후 재렌더링만 하면 됩니다. 이것은 경로 A이며, Opus가 기본적으로 선택하는 경로입니다. 사용자가 Remotion 또는 HyperFrames를 언급하지 않는 한 이 경로를 사용하세요 (언급하는 경우 references/route-b.md를 읽으세요).
모든 명령은 필름 프로젝트 루트(studio.json이 있는 폴더)에서 실행하세요. 루트가 없으면 먼저 /motion-studio:studio-init을 실행하세요. 이 스킬의 파일은 ${CLAUDE_SKILL_DIR}에 있으며, 아래의 상대 링크는 그곳을 가리킵니다 (${CLAUDE_SKILL_DIR}/references/determinism.md, ${CLAUDE_SKILL_DIR}/references/route-b.md).
1. 두 가지 구성 요소
| 구성 요소 | 파일 | 역할 |
|---|---|---|
| 페이지(Page) | index.html, film/film.js, lib/runtime.js (+ lib/*.js) | boot(film)이 studio.json, audio/beats.json(선택 사항) 및 번들된 폰트를 로드한 후 window.seek(t)와 window.__studio를 노출합니다 |
| 드라이버(Driver) | tools/render.mjs (+ tools/studio.mjs) | 프로젝트를 http://127.0.0.1:<random>에서 서빙하고, 헤드리스 브라우저(Windows: Playwright의 헤드리스 쉘, 설치된 Chrome이나 Edge는 사용하지 않음; macOS 및 Linux: Chrome, Edge, 그 다음 번들된 브라우저 순)를 실행하며, N개의 워커 페이지를 열고, 프레임을 순서대로 캡처하여 하나의 H.264 스트림으로 인코딩합니다 |
페이지는 항상 http로 서빙됩니다. file://은 fetch('studio.json'), ES 모듈 및 # 또는 %가 포함된 경로를 깨뜨립니다.
2. 렌더 계약
| 멤버 | 계약 |
|---|---|
?format=9x16&scale=1&render=1 | 드라이버가 보내는 쿼리; format의 기본값은 studio.primaryFormat, scale은 0.1–1 |
window.seek(t, blur?) | 시간 t의 동기식 페인트; 루프 필름은 loopT로 감싸고, 나머지는 [0, duration]으로 제한; true 반환. 선택적 두 번째 인수 { frameT, sub, subs }는 이 페인트가 frameT를 중심으로 한 출력 프레임의 subs개 서브프레임 중 sub번째 서브프레임임을 나타냄 (페이지 캡처는 모든 스크린샷에 대해 이를 보냄) |
__studio.ready | Promise; 설정, 비트 그리드, 폰트(loadFonts는 모든 페이스를 확인), setup()이 완료된 후 resolve |
__studio.error | 부팅 실패 시 문자열 스택 (드라이버가 출력) |
__studio.meta | { title, duration, fps, format, width, height, logicalWidth, logicalHeight, scale, bpm, loop, capture } |
__studio.frame({ t, sub, shutter, fps, wrap }) | 프레임 t의 PNG 데이터 URL; sub > 1이면 페이지 내에서 중심이 같은 서브프레임을 누적(모션 블러); wrap: false는 루프 필름에서도 원시 시간을 [0, duration]으로 제한하여 페인트 |
__studio.hash(t, { wrap, sub, shutter, fps }) | paint(t) 후 원시 픽셀의 sha256 (결정론 검사); hash({ t, wrap: false })도 허용. hash(0) 대 hash(duration, { wrap: false })는 루프-클로저 불변량 |
__studio.pixels(t, w) | 작은 RGBA 썸네일을 base64로 (비평 지표); 루프 필름에서는 항상 감쌈 |
__studio.cues() / shots() / grid | SFX 큐, 샷 윈도우, 비트 그리드를 JSON으로 (sfx.mjs, stills.mjs --shots, critique.mjs에서 읽음). shots()는 시간 순서이며, overlays는 제외하고 씬만 나열; grid는 hits를 포함 |
__studio.textUse() / coverage(family, weight, style, chars) / textTrack | 비평의 글리프 검사. 로드 전에 window.__TEXT_TRACK__ = true (또는 ?texttrack=1)를 설정하면 lib/draw.js에서 text(), kinetic() 및 textWidth()가 폰트별로 그리는 문자를 기록; textUse()는 지금까지 페인트된 프레임에 대해 [{ family, weight, style, chars }]를 resolve (seek()을 먼저 실행); coverage()는 하나의 페이스에 대해 { missing, checked }를 resolve. 기본적으로 꺼져 있으며, 픽셀을 변경하지 않음; text()와 kinetic()은 등록되지 않은 패밀리에 대해 예외를 던지지 않음 |
모션 블러 프레임이 생성되는 동안 씬이 c에서 보는 내용: c.t는 페인트 중인 시간(서브프레임 시간, 따라서 모션 블러가 자동으로 적용됨), c.frameT는 출력 프레임의 중심 시간(모든 서브프레임에 동일), c.frame은 출력 프레임 인덱스 floor(frameT x fps)(모든 서브프레임에 동일), c.sub / c.subs는 서브프레임 인덱스와 개수입니다. 프레임 인덱스 기반 노이즈는 c.frame을 사용하고 (grain(g, W, H, c.frame)은 스틸, 미리보기 및 최종 결과에서 동일하게 보임), "on twos"는 stepTime(c.frameLt, 12)를 사용합니다. 자세한 내용은 플러그인의 docs/ARCHITECTURE.md 섹션 5.2를 참고하세요.
필름 코드는 references/determinism.md의 규칙을 따릅니다. 요약: 모든 값은 t의 함수입니다. 요소별로 rngFor(name, i)를 사용한 시드 기반 무작위성; Math.random, Date, performance.now, 타이머, requestAnimationFrame, CSS 전환 또는 프레임 간에 유지되는 상태 금지; 폰트와 에셋은 로컬 파일. npm run lint가 이를 검사하며, 플러그인 훅은 film/, lib/ 및 index.html에 대한 각 편집을 린트합니다.
3. 명령어
| 목표 | 명령어 |
|---|---|
라이브 미리보기 (스크러브, Space, 화살표, [/] 샷, F 포맷, G 안전 가이드) | npm run preview |
| 환경 검사 (Node, Playwright, 브라우저, ffmpeg, 폰트, 키 존재 여부) | npm run doctor |
| Windows 기본 브라우저 설치 (Playwright의 헤드리스 쉘, 약 115MB) | npx playwright install chromium-headless-shell (npm run setup:browser) |
| 빠른 페이싱 체크 (절반 스케일, 30fps, 블러 없음) | npm run animatic (out/animatic/<fmt>/silent.mp4 생성) |
| 기본 포맷 렌더 | npm run render |
| 시간 범위 렌더 (체크 용) | node tools/render.mjs --from 4 --to 6 --draft --out out/check (out/check/<fmt>/clip_4.00-6.00.mp4 생성) |
| 모든 포맷 렌더 | npm run render:all |
| 최종 렌더, 모든 포맷 (비평 게이트 통과 시까지 차단됨; 12초 데모의 경우 약 4분 소요, 백그라운드에서 실행) | npm run render:final |
| 긴 형식, 재개 가능한 세그먼트 | node tools/render.mjs --format all --final --chunk 10 |
| 프레임별 해시 매니페스트 | node tools/render.mjs --hash (frames.sha256 생성; 범위는 clip_<from>-<to>.sha256 생성) |
포맷별 출력: out/<fmt>/silent.mp4, out/<fmt>/poster.png (studio.poster 위치 또는 0.35 x duration), out/<fmt>/render.json (fps, 프레임 수, 워커, 브라우저 버전, 캡처, 인코딩 설정, 시간). mix.mjs는 정확한 오디오 길이를 위해 render.json을 읽습니다. 모든 것은 out/<fmt>/.staging/에 빌드되고 하나의 단위로 발행됩니다: 이전 파일을 먼저 옮기고, 새 파일을 silent.mp4를 마지막으로 이동시키며, 실패 시 이전 파일을 복원합니다. 다른 프로그램이 출력 파일을 열고 있으면(예: 비디오 플레이어, Windows의 이미지 뷰어), 렌더는 최대 30초(MOTION_PUBLISH_WAIT_MS) 동안 기다리고, 시작 시 어떤 파일이 열려 있는지 경고하며, 그렇지 않으면 cannot replace <file>: EBUSY ...로 중단되고 완료된 렌더는 out/<fmt>/.staging/에 유지됩니다 (이전 출력은 그대로 유지됨). 해당 프로그램을 닫고 .staging/에서 파일을 복사하거나, 다시 렌더하세요. --no-poster가 있는 전체 렌더는 이전 poster.png를 제거하고, --hash가 없으면 이전 frames.sha256을 제거하므로, 어떤 출력도 이전 컷을 설명하지 않습니다.
범위 렌더는 --from/--to가 프레임을 일부만 포함할 때만 부분적이며, clip_<from>-<to>.mp4를 자체 .json 및 .sha256과 함께 생성하고, silent.mp4를 절대 대체하지 않으며, --final이 될 수 없습니다. 전체 필름을 포함하는 범위(또는 끝을 넘는 --to)는 전체 렌더입니다. 체크 렌더는 --out out/check 아래에 유지하여 out/<fmt>/에는 실제 필름만 들어 있도록 하세요.
4. 캡처 모드
| 모드 | 설정 방법 | 프레임 생성 방식 | 용도 |
|---|---|---|---|
canvas (기본값) | 설정 없음 | __studio.frame이 sub개의 서브프레임을 t + ((j + 0.5) / sub - 0.5) * shutter / fps에서 페인트하고, 페이지에서 픽셀을 합산하여 하나의 PNG 반환 | <canvas id="stage">에 그려지는 모든 것 |
page | 팩토리가 capture: 'page' 반환 또는 studio.json에 "capture": "page" 설정 | seek(t) 후 page.screenshot을 서브프레임별로 수행; ffmpeg tmix + select가 각 그룹을 블렌딩 | DOM 필름 (t로부터 업데이트된 스타일 요소) |
shutter 0.5는 180도 셔터: 블러가 프레임 간격의 절반에 걸쳐집니다. 빠른 휩과 팬은 --sub 4에서 고스트 복사본을 보일 수 있습니다. 해당 필름의 경우 --sub 8로 높이세요. 페이지 캡처는 더 느리고(서브프레임당 하나의 스크린샷), DOM 렌더링 차이를 상속받으므로 캔버스를 선호합니다.
5. 성능 조정
페인트 수 = 프레임 수 x 서브프레임 수. 60fps에서 --sub 4인 12초 필름은 포맷당 2,880회 페인트입니다.
| 플래그 | 기본값 | 효과 | 사용 시기 |
|---|---|---|---|
--workers N | min(4, max(1, floor(cpus / 3))) | 하나의 브라우저에 있는 병렬 페이지가 하나의 정렬된 인코더에 공급 | 큰 장비에서는 높이고; RAM이 부족하면 낮춤 |
--scale s | 1 | 캔버스 = even(round(W x s)); 0.5 = 픽셀의 1/4 | 초안, 긴 필름의 스틸 |
--sub N | studio.subframes (4) | 프레임당 서브프레임 수 | --sub 1은 초안용; 빠른 모션은 8 |
--fps N | studio.fps (60) | 출력 프레임 속도 | 애니메틱은 30 |
--draft | 꺼짐 | encode.previewPreset + CRF 23 | 최종이 아닌 모든 렌더 |
--crf N / --preset p | 16 / slow | x264 품질 / 속도 | 최종 렌더용으로 남겨둠 |
--chunk S | 꺼짐 | 재개 가능한 out/<fmt>/.parts/seg_<a>_<b>.mp4, 이후 -c copy로 연결 | 약 30초 이상의 필름, 세 가지 포맷의 최종 렌더, 야간 실행 (중단 시 다시 시작하지 않고 재개) |
--no-poster | 포스터 켜짐 | 포스터 스틸 건너뜀 | 일괄 체크 |
참조 랩탑에서 측정 (12-스레드 i7-1255U, 설치된 Chrome, 1080x1920, 60fps, 4 서브프레임, 4 워커; Windows 기본값은 이제 헤드리스 쉘이며, 프레임당 속도는 재측정되지 않았고, 실시간 안티바이러스가 있는 머신에서 도구 실행당 시작 시간이 15~25초 추가됨, 측정됨):
| 설정 | 출력 프레임당 시간 | 60fps에서 15초 동안 시간 |
|---|---|---|
| 코스의 서브프레임당 스크린샷 루프 (캡처 전용, 200개의 호, 텍스트 및 그라데이션이 있는 합성 장면) | 약 1,575ms | 약 24분 |
| 4개 페이지에서의 페이지 내 누적 (동일한 합성 장면, 캡처 전용, 픽셀 동일) | 약 148ms | 약 2.2분 |
| 이 렌더러의 템플릿 12초 데모 필름에 대한 종단 간, 최종 x264 인코딩 | 9x16에서 123ms, 1x1에서 75ms, 16x9에서 118ms | 9x16에서 1.8분 (12초 필름의 세 가지 포맷에 대해 약 4분) |
처음 두 행은 설계를 선택하게 한 캡처 전용 벤치마크입니다. 마지막 행은 실제 필름의 비용이며, 예상치로 인용할 수치입니다 (장면 복잡성과 머신에 로드된 다른 프로그램에 따라 증가하며, 세 가지 포맷에 대해 최대 약 5분까지). x264 -preset slow는 해당 크기에서 약 18fps로 인코딩하므로 캡처가 병목입니다. 진행 상황, fps 및 ETA가 필름-초당 한 번씩 stderr에 출력됩니다. 최종 렌더는 백그라운드에서 시작하고 로그를 폴링하세요. 포그라운드에서 기다리지 마세요.
6. 결정론 증명
npm run critique는 결정론 검사를 실행합니다: 모든 샷 경계와 큐를 걸치는 시간(플러스 및 마이너스 1프레임)에서__studio.hash를 수행하고, 패스 A는 순서대로, 패스 B는 섞어서, 패스 C는 리로드 후에 수행합니다.out/review/<fmt>/metrics.json은 일치하지 않는 모든t를 나열합니다.- 범위 렌더 후, 동일한 범위에 대해 두 번의 해시 렌더로 결정론을 증명합니다. 병렬 처리도 다루도록 워커 수를 변경하세요:
node tools/render.mjs --from 0 --to 2 --hash --draft --no-poster --json --workers 1 --out out/check/a및node tools/render.mjs --from 0 --to 2 --hash --draft --no-poster --json --workers 4 --out out/check/b. 범위는 절대silent.mp4를 건드리지 않습니다. 각 실행은out/check/<a|b>/<fmt>/clip_0.00-2.00.mp4와.json및.sha256(프레임당 한 줄:index t sha256)을 생성하고,--json줄은 해시 열을 개행 문자로 연결한 sha256인framesDigest를 보고합니다. 모든 포맷에서 동일한framesDigest값은 동일한 프레임을 의미합니다. 다르면 두.sha256파일을 비교하세요:git diff --no-index --quiet out/check/a/<fmt>/clip_0.00-2.00.sha256 out/check/b/<fmt>/clip_0.00-2.00.sha256은 일치 시 0으로 종료하고git diff --no-index는 다른 첫 프레임을 보여줍니다. Windows나 Linux에 존재하지 않는md5는 절대 사용하지 마세요. - mp4를 해시하지 마세요: x264 출력은 스레드 수에 따라 변경되므로 mp4 해시는 머신마다 다릅니다.
framesDigest는 인코더에 들어가는 프레임 PNG를 다루며, 이것이 결정론의 핵심입니다.
약속은 동일한 머신과 브라우저 빌드(render.json에 기록됨)에서 비트 동일한 프레임입니다. 머신이 다르면 폰트가 다르게 래스터화됩니다(DirectWrite, CoreText, FreeType). 시각적으로 비교하세요.
7. 문제 해결
| 증상 | 원인 | 수정 |
|---|---|---|
Executable doesn't exist ... chromium_headless_shell 또는 could not launch a browser: no safe browser found. (Windows) | Playwright의 헤드리스 쉘이 다운로드되지 않음 (npm install이 가져오지 않음) | npx playwright install chromium-headless-shell. macOS 및 Linux에서는 설치된 Chrome 또는 Edge도 작동; Windows에서는 설치된 브라우저는 보호된 옵트인(studio.json "browser": "chrome", MOTION_BROWSER=chrome)이며, 각 새 프로필 시작이 실패한 Windows 로그온으로 계산되기 때문 |
Windows 계정 잠김, 보안 로그 이벤트 4625 (chrome.exe), 또는 refusing to start chrome: N launches ... | 설치된 Chrome 또는 Edge가 새 프로필로 시작됨 (빈 암호 테스트 = 실패한 로그온) | 위와 같이 헤드리스 쉘로 전환하고 MOTION_BROWSER / MOTION_CHROME_PATH 설정 해제; 확인 명령과 이유는 ${CLAUDE_SKILL_DIR}/../studio-init/references/troubleshooting.md, "Windows account gets locked out while rendering or testing" 참고 |
ffmpeg not found | PATH에 없거나 ffmpeg-static 누락 | npm i -D ffmpeg-static 또는 FFMPEG_PATH 설정; npm run doctor가 OS별 명령 출력 |
Windows에서 자체 스크립트의 spawn EINVAL | 셸 없이 npm/npx .cmd 심 스폰 | spawn('npm.cmd', args, { shell: true }) 사용; 도구는 이미 이렇게 함 |
font missing: 700 64px "X" 또는 준비 시간 초과 | 패밀리가 번들되지 않았거나 철자가 틀림 | npm run fonts -- add "X:400,700"; studio.json brand.fonts의 이름 사용 |
| 빈 또는 부분 프레임, 로그의 페이지 오류 | 씬 드로우 내 예외 | 드라이버가 __studio.error와 콘솔 오류를 출력; 해당 시간에서 npm run preview로 재현 |