코드 필름
여기서 필름이란 임의의 순간을 요청하면 그릴 수 있는 웹 페이지입니다 (window.renderAt(t)). 작은 하네스가 헤드리스 Chromium에서 GPU를 통해 모든 프레임을 요청하고, ffmpeg가 프레임과 사운드트랙을 결합합니다. 비디오로 촬영되거나 생성되는 것이 아니므로, 코드가 지정한 대로 어떤 해상도에서든 항상 정확한 그림을 얻을 수 있습니다.
이 폴더의 키트는 "Dial-A-Dev 98"(Builder Wars 주간 테마 "1998년 출시", 2026년 11월)에서 입증되었습니다: 44초, 1920x1080, 11개의 샷, 1,326 프레임을 약 45초 만에 렌더링했습니다. 해당 필름의 전체 소스는 examples/dial-a-dev-98/에 있습니다. 패턴은 github.com/Vincentwei1021/mg-styles-15(MIT)를 따르며, 이는 모션 디자인 스타일에 대한 좋은 입문서이기도 합니다.
필름 시작하기
bash ~/.claude/skills/code-film/new-film.sh ~/Work/<film-folder> # 키트를 복사하고 두 개의 로컬 패키지를 설치합니다.
cd ~/Work/<film-folder>
# 사운드를 위해서는 ElevenLabs 키가 필요합니다: 사용자가 직접 ./.env 파일에 ELEVENLABS_API_KEY=...를 저장합니다 (채팅에서 절대 묻지 마세요).
node harness/render.mjs film --stills 0,1,2 # PNG 스틸 -> film/out/stills/
bash tools/build.sh v1 # 큐 목록, 믹스, 렌더, X 인코딩 -> film/out/<filmName>_v1.mp4
필름은 제품 저장소 외부의 자체 폴더에 보관하세요. 글로벌하게 설치하기 전에 물어보세요.
작업 순서
- 브리프. 제품, 대상, 게시 위치, 길이, 화면 비율(16:9, 9:16, 1:1). Builder Wars의 경우
get_video_guide를 호출하고 그 규칙을 따르세요(이 파일보다 우선합니다). - 트리트먼트. 하나의 아이디어, 처음 0.5초 안에 훅, 점진적인 고조, 런타임의 약 60-75% 지점에 하나의 히어로 순간, 그리고 잘 구성된 마지막 프레임. 하나의 스타일을 선택하고 테스트 가능한 진술문으로 핵심 특징을 적어 두세요.
- 큐 시트 우선 작성 (
film/cues.json). 음성 대본을 라인으로 작성하고 예상 시간을 포함시킵니다. 샷은 고정된 초가 아니라 라인 및 발화 단어와 연결되므로, 새로운 음성 테이크가 전체 필름의 타이밍을 다시 조정합니다. - 모션보다 스틸 먼저. 가장 까다로운 두세 프레임의 룩을 만들고 전체 크기로 살펴보세요. 아직 포스터 가치가 없는 프레임은 애니메이션하지 마세요.
- 샷. 샷당 하나의 모듈(아래 계약 참조). 스틸과 작은 콘택트 시트로 각각 확인하세요.
- 음성. 오디션(기본 음성과 디자인된 세 가지 음성)을 보고, 모든 라인을 단어 타이밍과 함께 녹음한 다음, 큐 시트가 컷을 이동하도록 합니다:
node tools/vo.mjs --voice <id>, 그 다음--reuse --tempo 1.12로 읽기를 조입니다. - 음향 효과 및 음악.
audio/sfx.json과audio/music.json에 목록을 작성하고node tools/sfx.mjs --music으로 생성합니다. 각 샷은 자체 사운드 큐를 선언하므로 히트가 그림에 고정됩니다. - 빌드 (
tools/build.sh), 그런 다음 직접 콘택트 시트를 읽고 보이는 문제를 수정하세요. - 심사. 독립적인 에이전트에게
rubric.md, 파일 및 브리프를 제공하세요. 에이전트는 필름을 만들지 않았으며 점수를 매기고 정렬된 수정 사항을 반환합니다. 이를 적용하고 다시 빌드한 후에만 사용자에게 보여주세요. 시간이 허락하면 두 번 수행합니다. - 마무리 및 전달.
tools/finish.sh는 X용으로 인코딩하고 포스터와 콘택트 시트를 만듭니다. 대상의 자체 검사기를 실행하세요. 사용자가 게시합니다. 그들을 대신해 게시하지 마세요.
페이지 계약
window.FILM = { width, height, fps, duration, shots, lines, sfx },window.renderAt = async (t) => {...}, 그 다음window.__ready = true.- 모든 프레임은
t의 순수 함수입니다: 시드된 난수만 사용하고, 시계, CSS 전환, 또는 프레임 간 상태 전이가 없습니다. 하네스는 어떤 순서로든 여러 브라우저에서 동시에 프레임을 요청할 수 있습니다. - 샷은
{ name, samples(lt), render(lt, post, renderer), overlay(g, lt), look(lt), sfx: [...] }입니다:render는 선형 HDR을post.scene에 그립니다;overlay는 1920x1080 캔버스에 2D 자막을 그립니다(그렸으면 true 반환);samples는 해당 순간의 모션 블러 샘플 수입니다(정적일 때 3, 빠른 움직임 중 12-20);look는 포스트 설정(블룸, 플래시, 테이프 양, 글리치)을 반환합니다;sfx는{ t, s, g, a, len }목록입니다: 로컬 시간, 사운드 이름, 게인,a: 'peak'는 사운드의 가장 큰 순간을 큐에 맞추고, 선택적 컷 길이.
film/js/film.js는 샷 이름을 팩토리에 매핑하고 모든 샷 위에 표시되는 모든 것을 그립니다.- 룩 개발을 위한 쿼리 스위치:
?clean(테이프 패스 없음),?nocc(캡션 없음),?mb=1,?rs=0.5. render는 또한 패스 번호와 개수(render(lt, post, renderer, i, K))를 수신하며, 샷은shutter: 0을 설정할 수 있습니다. 모션 블러가 없으면 K 패스는 다른 용도로 자유롭게 사용할 수 있습니다: 피사계 심도를 위해 렌즈를 움직이거나, 부드러운 그림자를 위해 키 라이트를 움직이거나, 안티앨리어싱을 위해 픽셀 그리드를 움직입니다(스토리북의rig.js).look()은 테이프 패스 대신 깔끔한 마무리(색상 정확한 톤 커브, 그레인, 비네트)를 위해paper: true를 반환할 수 있습니다.film.js는loadFonts(첫 번째 프레임 전에 완료되어야 하는 모든 비동기 작업),buildCaptions및caption을 내보낼 수 있습니다.
이 머신 (2026-11-11 확인)
/usr/bin/chromium에 Chromium 155, RTX 4070 Ti SUPER. 하드웨어 WebGL2는--use-gl=angle --use-angle=gl-egl이 필요합니다(하네스가 전달하고 소프트웨어로 대체되는 경우 경고합니다). WebGPU는 소프트웨어로 대체됩니다: WebGL2를 사용하세요.- libx264 및 NVENC를 사용하는 ffmpeg 9; 콘택트 시트용 ImageMagick; venv 외부에 Blender나 numpy는 없습니다.
- 전체 1080p 렌더: 세 개의 워커로 프레임당 약 0.03초.
ElevenLabs 노트 (2026-11-11 확인)
- 키는 필름 폴더의
.env에 있습니다. 키에는user_read가 없을 수 있으므로, 요금제와 남은 크레딧을 읽을 수 없을 수 있습니다; 추측하기보다 그렇게 말하세요. - 사용 중인 요금제는 기껏해야
mp3_44100_128을 허용합니다(더 높은 형식은 Creator 요금제 필요). 음성 모델eleven_v4는 작동하며[excited]와 같은 오디오 태그를 사용합니다; 태그는 정렬에서 다시 돌아오며vo.mjs에 의해 제거됩니다. - 기본 음성은 강한 판매에는 느리게 읽습니다. 디자인된 음성(
eleven.mjs design, 그 다음voice-save.mjs는 하나의 음성 슬롯을 사용합니다)에--tempo 1.12를 추가하면 홈쇼핑 속도가 나왔습니다.speed설정은 타이밍을 거의 변경하지 못했습니다. - 음향 효과는 레벨이 매우 다양하며 하나는 무음으로 돌아왔습니다:
mix.mjs는 모든 파일을 피크 노멀라이즈하고, 거의 무음인 파일은 건너뛰고 그 사실을 알립니다. 더 평이한 프롬프트로 재생성하세요("큰 박수 한 번"은 설명된 클래퍼보드가 세 번 무음으로 돌아온 후에 효과가 있었습니다). - 이야기꾼 음성은 느리게 읽습니다: 기본 음성 George는 초당 2.25 단어를 측정했습니다.
--tempo 1.25는 초당 2.7 단어, 일반적인 말하기 속도로 만들었습니다. 길이는 단어 수가 아니라 녹음된 라인에서 결정하세요. - 생성된 음악은 명시된 길이보다 일찍 끝납니다.
mix.mjs는 레벨이 실제로 끝나는 위치를 찾아 필름의 끝과 맞춥니다. - 캐릭터 음성(예: 어린이 TV 마스코트)은 설명이 주는 속도로 읽습니다: 같은 텍스트가 "유아에게 천천히 말함"에서는 31초가 걸렸고 "활기차고 빠른 템포"에서는 24초가 걸렸습니다. 설명에 속도를 포함시키고, 두세 가지 설명을 디자인하고(각각 세 개의 미리 듣기),
tools/audition-stats.mjs(길이, 중앙 피치, 피치 범위)로 측정하고, 그 위에--tempo 1.3을 예상하세요. 유형을 설명하세요; 실제 캐릭터나 사람의 이름은 절대 지정하지 마세요. - 오디션에서 사용자가 선택한 음성은 같은 피치와 밝기를 측정하지만 필름에서는 더 높게 들릴 수 있습니다: 모델이 긴 오디션 구절보다 약 1.3배 빠르게 개별 라인을 읽고, 추가로
--tempo를 적용하면 음성이 더 높고 작게 들립니다.vo.mjs --reuse --tempo 1.38 --pitch -2는 같은 속도로 낮춥니다(타이밍은 변경되지 않으므로 기존 마스터를 다시 믹스하고finish.sh를 다시 실행하면 됩니다; 렌더링은 필요 없습니다). 사용자가 듣기 위해 0, -1, -2, -3 반음의 비교 클립을 만들고, 이후 음성 stem 레벨을 다시 확인하세요(mix.vo). voice-save.mjs <generated id> "<name>" "<description>"는 미리 듣기를 계정에 저장합니다(하나의 음성 슬롯). 새 내레이터를 녹음하기 전에 이전 내레이터의 테이크를 보관하세요(cp -r audio/vo audio/vo_<name>).- 무료 요금제는 상업적 게시에 대한 라이선스가 없습니다. 요금제를 알 수 없으면 사용자에게 알리세요.
잘못된 점, 다시는 그러지 않기 위해
사진 및 코드:
- 텍스트에서 단어의 위치를 기준으로 단어가 언제 발화되는지 추정하는 것은 최대 1초까지 틀립니다("98"은 "ninety-eight"로 발음됨). 녹음된 단어 타이밍(
mark(line, word))을 사용하세요. - three.js는 돌출된 텍스트를 명목 크기보다 더 크게 만듭니다. 단어를 대상 너비에 맞추세요; 숫자를 신뢰하지 마세요.
- 방향광으로 비춰진 평평한 거울은 균일하게 하얗게 됩니다. 디스크와 크롬에는 지점광이나 다양한 환경을 제공하여 하이라이트가 핫스팟이 되도록 하세요.
- 겹치는 기울어진 디스크는 교차합니다. 깊이로 겹쳐서 배열하고 기울기를 제한하세요.
- 흐릿한 바닥 반사는 배경의 반짝임을 점 격자로 만듭니다: 미러 패스에서 반짝임을 끄세요.
- 가짜 볼드 비트맵 텍스트(텍스트를 한 픽셀 간격으로 두 번 그리기)는 W와 M을 채웁니다.
ui98.js는 다음 획과의 간격이 열린 상태로 유지되는 곳에서만 획을 두껍게 합니다. - 상단 절반이 배경색에 가까운 로고는 사라집니다. 돌출된 글자에 어두운 키라인(
makeLetters의outline)을 지정하고 측면 벽을 검은색에 가깝게 유지하세요. - 테이프 노이즈는 인코딩 비용이 많이 듭니다. 무손실로 렌더링(
--lossless)한 다음 비트레이트 제한으로 한 번 인코딩하세요.
첫 번째 심사 라운드에서 완성했다고 생각한 필름에서 발견한 것(약 6/10 점수). 심사 전에 다음 사항을 확인하세요:
- 제품 이름은 약 2초 이내에 화면에 표시되어야 하며 프레임 0은 썸네일입니다. 첫 프레임부터 이름이 있는 하단 1/3 지점의 고정 요소가 두 문제를 모두 해결했습니다.
- 자막과 캡션이 가장 좋은 농담을 가렸습니다. 자막을 배치한 후 그 아래에 무엇이 있는지 확인하세요.
- 카메라가 푸시된 후 텍스트가 타이틀 안전 영역 밖으로 나갔습니다. 모든 푸시의 첫 번째 프레임이 아닌 마지막 프레임을 확인하세요.
- 모든 컷에서 동일한 흰색 플래시와 글리치는 템플릿처럼 보이며, 네 개의 샷에 대해 하나의 배경과 다섯 개의 동일한 별 폭발도 마찬가지입니다. 다양하게 변화를 주고 큰 플래시는 한두 번의 히트에만 사용하세요.
- 1080p에서는 괜찮아 보이는 캡션이 휴대폰에서는 너무 작습니다: 자체 대역 내에서 약 40px 높이의 글자.
- 결실을 맺지 못하는 전제. 필름이 "누군가 전화를 받지 않으면"이라고 말하므로, 누군가는 받아야 합니다.
- 말하는 단어 아래에 있는 사운드 히트는 들리지 않습니다. 히트를 단어 뒤로 옮기고 레벨을 높이세요.
두 번의 심사 라운드에서 종이 스토리북 필름에 대해 발견한 것(약 6/10, 그 다음 약 7/10). 다음 번에는 이것들을 먼저 확인하세요:
- 실제 제품 화면을 전체 프레임으로 보여주는 것은 화면 녹화처럼 보이며 세계관을 깨뜨립니다. 큰 글자와 함께 장면 안(세트의 노트북)에 두 개의 큰 크롭으로 유지하고, 16프레임 이상의 인월드 와이프로 변경하세요. 테두리를 잘라내어 화면 측면에 이음새가 없도록 하고 게임 내 화폐는 가짜라고 표시하세요.
- 숫자는 샷 간에 일치해야 합니다. "가짜 백만장자" 다음에 $9,100를 보여주는 보드는 히어로 라인을 무너뜨렸습니다.
- 히어로 샷이 1.4초 동안 정지했습니다. 모든 홀드 동안 무언가 움직이게 유지하고(동전 쏟아지기, 불빛 깜빡이기, 라인이 끝날 때 두 번째 폭발), 첫 프레임부터 넓게 프레이밍하세요.
- 희미한 배경음만 있는 1초 이상의 음성 공백은 데드 에어로 느껴집니다. 줄이거나 개그와 사운드를 넣으세요.
- 깨끗한 가장자리를 가진 평평한 모양은 그레인이 있어도 벡터 아트처럼 읽힙니다. 약간 흔들리는 컷 라인과 가장자리를 따라 더 밝은 종이 코어(스토리북
paper.js의piece())가 이를 수정했습니다. 표지판은 인쇄된 활자가 아니라 잘라낸 글자(cutSign)여야 합니다. - 떠 있는 모든 것은 눈에 보이는 지지대(줄기, 스프링, 탭)가 필요합니다. 광선은 불투명한 종이여야 합니다.
- 주요 동작이 휴대폰에서는 너무 작았습니다: 동전 뒤집기, 왕관 머리 바뀌기, 버튼 누르기. 동작을 확대하고 카메라를 안으로 푸시하세요.
- 팝업이 서로를 통과하고 페이지를 넘기는 동작을 통과했습니다. 실제 접힘 기하 구조는 독자 방향의 접힘이 스프레드가 닫히기 시작하는 즉시 뒤로 젖혀지도록 만듭니다. 이 접힘을 직립 상태로 유지하고, 모든 팝업이 스프레드가 거의 열릴 때까지 낮게 유지되도록 하며(
book.js의rise), 닫힌 책 안에 평평하게 놓이는 조각들을 숨기세요. - 문장이 끝나기 전에 페이지가 넘어가기 시작해서는 안 됩니다: 샷의
lead는 그 앞의gap보다 길어서는 안 됩니다. - 그림이 전달하는 펀치라인을 반복하는 캡션은 그것을 망칩니다. 라인의
cc는 시작 단어만 유지할 수 있습니다; 그러면 나머지 내용이 말해질 때 캡션이 사라집니다. - 첫 번째 프레임에서 끝: 책이 주소가 적힌 밴드와 함께 표지 위로 덮입니다. 또한 깔끔하게 반복됩니다.
사용자가 그 필름을 본 후 변경한 사항(v4 컷):
- 다른 캐릭터를 희생시키는 농담("Sam은 Kim을 싫어함", 폭풍우 구름)은 비열하게 읽혔습니다. 그는 농담이 히어로를 향하도록 요청했습니다: Sam이 눈물을 흘린 다음 첫 번째가 되는 것을 공상합니다("꿈꿔요, Sam, 꿈꿔요."). 개그는 히어로를 목표로 하세요.
- 제품에서 복사된 슬로건("가장 높은 월 소득이 승리")은 무엇을 얻는지 묻게 했고; 아무것도 없었습니다. 녹음하기 전에 대본의 모든 주장을 제품이 실제로 하는 일과 대조 확인하세요.
- 생각 구름이 프레임보다 높습니다: 카메라를 함께 올리고, 그것이 반영하는 것을 프레임 안에 유지하고(꿈 보드 아래 실제 보드), 페이지가 넘어가기 몇 프레임 전에 터뜨려서 높은 것이 페이지 위에 타지 않도록 하세요.
작업 분할:
- 먼저 한 세션에서 룩과 엔진을 구축하고(사용자가 승인하는 두세 프레임), 샷 계약 및 각 샷에 대한 브리프를 파일로 작성하세요(
SHOTS.md,BRIEFS.md). 그런 다음 샷을 새 에이전트에게 분산하여, 샷당 하나 또는 두 개씩,model: "opus"와 해당 파일을 브리프로 사용하여 배포하세요. 이를 위해 포크를 사용하지 마세요: 포크는 항상 세션 자체 모델과 노력으로 실행되며 더 저렴한 모델을 지정할 수 없습니다(스타일 필름에서 포크는 사용량의 55%를 차지했습니다). 각 에이전트는 자체 샷 파일만 소유합니다; 공유 캐릭터를 먼저 작성하세요; 샷 모듈을 하나씩 로드하여 편집 중에 파일이 깨져도 해당 샷만 비워집니다. 심사 수정 사항도 같은 방식으로, 샷 파일과 수정 목록이 제공된 새 에이전트에게 배포하고, 빌더를 재개하지 마세요; 엔진 파일은 주 세션에 유지하세요. - 각 라운드마다 새 에이전트에게 심사를 맡기고 두 번째 에이전트에게 첫 번째 에이전트의 노트를 읽지 말라고 지시하세요.
프로세스:
pkill -f <pattern>은 그것을 실행하는 셸과 일치합니다. 패턴을[p]attern으로 작성하세요.- 페이지 오류는 하네스를 대기 상태로 만듭니다. 45초 후에 포기하고 페이지 오류를 출력합니다; 디버깅 중에는
tail을 통해 파이프하지 마세요. 그렇지 않으면 오류가 마지막에만 도착합니다
...(번역을 위해 잘림)