JavaScript, Canvas, Web Audio로 외부 에셋 없이 프로시저럴 영상 만들기

procedural-film이 하는 일

procedural-film은 주제를 약 30초 분량의 세로형 영상으로 변환하는 에이전트 스킬입니다. 이미지, 동영상 또는 오디오 파일을 조합하는 대신, 각 영상은 HTML 캔버스에서 바닐라 JavaScript로 시각 요소를 그리고 Web Audio API로 사운드트랙을 합성합니다.

완성된 프로젝트는 독립 실행형 HTML 플레이어와 MP4 내보내기 파일을 생성할 수 있습니다. 시각 요소와 사운드가 코드로 생성되므로 영상에는 미디어 에셋이 전혀 포함되지 않습니다.

저장소에는 examples/butterfly-life에 완전한 참조 제작물이 포함되어 있습니다. 이 제작물은 17개 장면으로 제왕나비의 생애 주기를 묘사하고, 120 bpm에서 32초 동안 재생되며, 초당 24프레임의 1080x1920 세로형 프레임을 사용합니다.

주요 기능

• 절차적 시각 요소: 모든 픽셀은 바닐라 JavaScript와 Canvas로 그립니다.
• 합성 오디오: 모든 사운드는 Web Audio를 통해 생성됩니다.
• 에셋 없는 배포: 영상은 별도의 미디어 파일에 의존하지 않습니다.
• 세로형 출력: 참조 워크플로는 휴대전화에 적합한 1080x1920 형식을 대상으로 합니다.
• 다양한 결과물: 파이프라인은 독립 실행형 HTML 플레이어와 MP4 내보내기 파일을 생성합니다.
• 에이전트 기반 제작: 병렬 하위 에이전트가 개별 장면을 작성하고, 크리틱 웨이브가 각 장면을 검토할 수 있습니다.
• 내장 검증: 예제에는 렌더링 전에 실행되는 6개 항목 품질 게이트가 포함되어 있습니다.

저장소 구조 이해하기

저장소는 재사용 가능한 스킬과 실제 작업 예제로 나뉩니다.

• skills/procedural-film/에는 에이전트 스킬이 들어 있습니다.
• skills/procedural-film/SKILL.md는 전체 제작 파이프라인을 정의합니다.
• skills/procedural-film/foundation/에는 새 영상마다 복사되는 엔진과 도구가 들어 있습니다.
• skills/procedural-film/templates/에는 4개의 기획 문서 템플릿이 들어 있습니다.
• skills/procedural-film/reference/에는 장면 유형 색인, 장면 및 음악 가이드, 참조 프레임이 들어 있습니다.
• examples/butterfly-life/에는 나비 영상의 기획 문서, 소스 코드, 도구, HTML 플레이어, 휴대전화용 MP4가 들어 있습니다.

사전 요구 사항

스킬을 사용하기 전에 다음 소프트웨어를 설치하세요.

• Node.js 20 이상
• 시스템 PATH에서 사용할 수 있는 ffmpeg
• Playwright용 Chromium
• Claude Code와 같이 스킬 및 병렬 하위 에이전트를 지원하는 에이전트

Node.js와 ffmpeg를 사용할 수 있는지 확인하세요.

node --version
ffmpeg -version

procedural-film 스킬 설치

1. 저장소 복제

git clone https://github.com/kuhnhomeuk-cell/procedural-film.git

2. 에이전트에 스킬 연결

복제한 저장소가 있는 디렉터리에서 Claude Code의 스킬 폴더에 심볼릭 링크를 만드세요.

ln -s "$PWD/procedural-film/skills/procedural-film" ~/.claude/skills/procedural-film

심볼릭 링크를 사용하면 examples/butterfly-life/의 실제 작업 예제를 스킬 옆에서 계속 사용할 수 있습니다. 다른 호환 에이전트를 사용한다면 동일한 스킬 디렉터리를 해당 에이전트의 스킬 폴더에 연결하세요.

3. 예제 도구의 종속성 설치

npm install --prefix examples/butterfly-life/tools

4. Playwright용 Chromium 설치

npx --prefix examples/butterfly-life/tools playwright install chromium

주제로 영상 만들기

스킬을 연결한 후 에이전트에게 주제에 관한 절차적 영상을 만들어 달라고 요청하세요. 예를 들면 다음과 같습니다.

꿀벌의 생애에 관한 절차적 영상을 만들어 줘.

에이전트는 skills/procedural-film/SKILL.md의 파이프라인을 따릅니다. 제작 과정은 의도적으로 상당한 규모로 구성되어 있습니다. 장면당 하나의 에이전트가 1,000줄을 넘을 수 있는 장면 파일을 작성하고, 이후 크리틱 웨이브가 모든 장면을 검토합니다.

에이전트 세션이 오래 실행되고 많은 리소스를 사용할 수 있도록 계획하세요. README에는 완성된 영상 하나가 에이전트 사용량 요금제의 상당 부분을 소모할 수 있다고 안내되어 있습니다.

나비 참조 영상 다시 빌드하기

포함된 예제를 다시 빌드하면 Node.js, ffmpeg, Playwright, Chromium이 올바르게 구성되었는지 가장 쉽게 확인할 수 있습니다.

1. 검증 게이트 실행

node examples/butterfly-life/tools/check.cjs

check.cjs 스크립트는 프로젝트의 6개 항목 게이트를 실행합니다. 검증에 성공하면 상태 코드 0으로 종료됩니다.

2. MP4 렌더링

node examples/butterfly-life/tools/render.cjs

렌더러는 결과 동영상을 다음 위치에 기록합니다.

examples/butterfly-life/exports/butterfly-life.mp4

3. 독립 실행형 HTML 플레이어 다시 빌드

node examples/butterfly-life/tools/build.cjs

이 명령은 HTML 플레이어를 다시 빌드합니다. 기존 인터랙티브 플레이어는 examples/butterfly-life/dist/butterfly-life.html에 있으며 다운로드하거나 브라우저에서 열 수 있습니다.

실용적인 개발 워크플로

1. 명확하게 정의된 주제로 시작하고, 에이전트에게 해당 주제에 관한 절차적 영화를 제작하도록 요청합니다.
2. 에이전트와 병렬 하위 에이전트가 기획 문서와 장면 파일을 생성하도록 합니다.
3. 초기 생성 후 멈추지 말고 비평 단계에서 여러 차례 샷을 검토하도록 합니다.
4. 렌더링 전에 프로젝트의 유효성 검사를 실행합니다.
5. 보고된 문제를 해결한 다음, 검사가 성공적으로 종료될 때까지 다시 실행합니다.
6. MP4를 렌더링하고 독립 실행형 HTML 플레이어를 다시 빌드합니다.
7. 브라우저에서 플레이어를 열고 최종 세로형 영화를 검토합니다.

고급 팁

참조 영화를 제작 목표로 활용하기

예상되는 프로젝트 구조와 출력 품질을 익힐 때 examples/butterfly-life를 살펴보세요. 이 예제의 기획 문서, 소스, 도구, 렌더링된 플레이어, 내보낸 휴대폰용 동영상은 이 스킬이 제작하도록 설계된 결과물을 보여줍니다.

스타일을 변경하기 전에 지원 참조 자료 읽기

reference/ 디렉터리에는 샷 유형 색인, 장면 가이드, 음악 가이드, 시각적 참조 프레임이 포함되어 있습니다. 이러한 자료는 에이전트 파이프라인이 내리는 결정의 맥락을 제공합니다.

최종 렌더링 전에 매번 유효성 검사하기

render.cjs를 실행하기 전에 check.cjs를 실행합니다. 최종 MP4를 생성하려면 6개 검사 게이트가 성공적인 종료 코드를 반환해야 합니다.

시간과 에이전트 사용량을 계획하기

이 파이프라인은 빠른 출력보다 상세한 장면 생성과 반복적인 비평을 우선합니다. 개별 샷 파일에는 1,000줄이 넘는 내용이 포함될 수 있으므로, 이 작업 흐름이 짧은 한 번의 프롬프트 생성 작업처럼 완료될 것이라고 가정하지 마세요.

스킬은 복사하지 말고 연결 상태로 유지하기

심볼릭 링크를 사용하면 스킬이 클론한 저장소와 연결된 상태로 유지되고 butterfly 예제에 편리하게 접근할 수 있습니다. 또한 저장소 구조와 분리된 별도의 복사 설치본이 만들어지는 것을 방지합니다.

결론

procedural-film은 JavaScript 드로잉과 합성 오디오만으로 세로형 영화를 제작할 수 있는 에이전트 기반 방식을 제공합니다. 스킬을 연결하고 필요한 도구를 설치한 후에는 주제를 지정해 영화 제작을 요청하고, 생성된 장면의 유효성을 검사하고, MP4를 내보내고, 기존 미디어 자산을 번들로 포함하지 않은 독립 실행형 HTML 플레이어를 빌드할 수 있습니다.

이 프로젝트는 MIT 라이선스로 제공됩니다. 시각적·편집적 접근 방식은 Kevin Ngo의 The life of a fruit fly를 모델로 하며, 자세한 내용은 examples/butterfly-life/docs/reference-analysis.md에 기록되어 있습니다.