clip-builder

Clip builder

세 가지 구성 요소로 짧은 비디오를 만듭니다: 화면(scene)을 렌더링하는 HTML 페이지, clip.json에 있는 스크립트 라인 목록(cues), 그리고 페이지를 프레임별로 캡처하여 MP4로 인코딩하는 명령줄 도구입니다.

scene 페이지는 draw(s)를 정의하는데, 이 함수는 시간 s에만 기반하여 페이지를 해당 시점의 상태로 설정합니다. 캡처는 각 프레임(초 0, 1/30, ...)마다 이 함수를 호출하고 스크린샷을 찍습니다. 결과적으로 출력물이 기계 속도에 의존하지 않고, 어떤 프레임이든 독립적으로 렌더링하여 검토할 수 있으며, 클립의 특정 부분을 --from과 --to 옵션으로 재캡처할 수 있습니다.

CLI는 이 스킬 디렉토리의 scripts/clip.mjs입니다. 이 문서에서 clip은 node "<skill dir>/scripts/clip.mjs"를 의미하며, <skill dir>은 이 파일이 포함된 디렉토리의 절대 경로입니다. (Claude Code에서는 ${CLAUDE_SKILL_DIR}로 대체됩니다. 다른 에이전트에서는 이 파일이 읽힌 디렉토리를 사용하세요.) clip.json이 포함된 클립의 프로젝트 디렉토리에서 명령을 실행하세요. clip help는 모든 명령과 옵션을 나열합니다.

요구 사항

Node 20 이상, ffmpeg, 그리고 Chromium이 포함된 Playwright가 필요합니다. clip doctor가 이를 확인하고 누락된 항목에 대한 설치 명령을 출력합니다. Playwright는 이 스킬 디렉토리가 아니라 클립이 빌드되는 디렉토리에 설치하세요 (npm install --save-dev playwright, 그 다음 npx playwright install chromium). 나레이션과 생성된 음악은 선택 사항입니다. 비용이 들거나 API 키가 필요한 유일한 단계입니다.

샌드박스 명령어(Codex의 기본값): clip stills, clip capture 및 clip serve는 127.0.0.1에서 HTTP 서버를 시작하며, 처음 두 개는 Chromium도 시작합니다. 명령 샌드박스가 둘 다 차단합니다. 그러면 명령은 상태 1과 함께 샌드박스 이름을 명시하는 메시지를 출력하며 종료됩니다. 이 세 명령을 샌드박스 외부에서 실행할 수 있도록 승인을 요청하고 그 이유를 설명하세요. 다른 캡처 방법으로 대체하지 마십시오. 다른 명령은 서버나 브라우저가 필요하지 않으므로 샌드박스 내에서 실행됩니다. tts --generate와 music --generate는 추가로 네트워크 액세스가 필요합니다.

개요

시작하기 전에 다음을 설정하세요. 누락된 것만 질문하세요. 사용자가 지정하지 않은 항목은 기본값을 사용하고 한 줄로 명시하세요.

• 목적과 대상: 프로모션, 제품 데모, 직원 교육 방법, 수업. 이것이 속도를 결정합니다. 프로모션 클립은 빠르게 진행되고, 교육 클립은 각 단계를 따라갈 시간을 남깁니다.
• 길이. 기본값: 프로모션/데모의 경우 2045초, 교육의 경우 60120초.
• 결과물 위치(프레임 결정). 기본값: wide 1920×1080, 소셜 피드용 tall 1080×1350. references/delivery.md 참조.
• 시각적 접근 방식: 새 그래픽 또는 앱 화면. 앱의 경우: 어떤 화면인지, 색상, 글꼴 및 간격의 소스로 앱의 소스 코드나 디자인 시스템을 사용할 수 있는지 여부.
• 사운드. 기본값: 자막 포함 무음. 무료이며 대부분의 피드 비디오는 음소거 상태로 재생됩니다. 나레이션과 음악은 각각 선택 사항입니다.
• 스크립트. 사용자에게 스크립트가 있으면 사용하세요. 그렇지 않으면 초안을 작성하고 scene을 만들기 전에 승인을 받으세요.

워크플로우

1. 도구 확인: clip doctor.
2. 프로젝트 생성: clip init <dir> --template graphics 또는 --template app-ui. 이 명령은 clip.json, 작동하는 예제가 있는 scene/ 디렉토리, 그리고 audio/를 생성합니다. 두 템플릿 모두 수정 없이 렌더링됩니다.
3. clip.json에 큐(cues)를 작성합니다. 각 비트(beat)는 하나의 대사와 하나의 시각적 상태를 가진 클립의 한 구간입니다. 먼저 스크립트를 작성하세요: scene은 스크립트에 맞춰 시간이 조정되며, 녹음 후의 모든 문구 변경은 또 다른 유료 요청입니다. references/narration.md는 음성용 대사 작성 방법을 다룹니다.
4. scene 구축: scene/index.html과 scene/scene.js를 편집하세요. 먼저 references/scenes.md를 읽으세요. 이 문서에는 scene을 결정론적으로 유지하는 제약 조건(Math.random() 금지, 시계/타이머 금지, CSS 애니메이션 금지, 모든 상태가 s에서 계산됨)이 나열되어 있습니다. 앱 화면의 경우 references/app-ui.md도 읽으세요.
5. 스틸(stills) 검토: clip stills는 선택한 초의 프레임과 연락처 시트(contact sheet)를 out/review/에 씁니다. 연락처 시트를 이미지로 열어 검사하세요. 텍스트가 읽기 쉬운지, 겹치는 부분이 없는지, 각 비트가 캡션이 표시되는 동안 화면에 표시되는지 확인하세요. 모든 프레임 크기(--frame tall)에 대해 반복하세요. 대부분의 반복 작업은 이 단계에서 수행하세요: 스틸은 빠르고 비용이 들지 않습니다. clip serve는 사용자에게 라이브 미리보기를 제공합니다.
6. 드래프트(draft) 캡처: clip capture --draft는 2/3 크기로 렌더링하여 움직임과 페이싱을 확인합니다. 사용자에게 파일 경로를 알려주고 시청하도록 요청하세요.
7. 요청된 경우 사운드 추가: 나레이션: references/narration.md. 음악 및 믹스: references/sound.md. 먼저 플래그 없이 clip tts를 실행하세요. 계획된 요청과 문자 수를 나열합니다. 사용자의 승인을 받은 다음 clip tts --generate를 실행하세요. 새 녹음 후에는 clip timing을 실행하세요. 이 명령은 큐와 캡션 시간을 배치하고, 구성된 경우 scene을 나레이션에 맞춰 늘립니다. 그런 다음 스틸을 다시 검토하세요.
8. 최종 캡처: 각 프레임에 대해 clip capture --final, 사운드가 있으면 clip mix, 업로드용 작은 복사본을 위해 clip web <file> 순서로 실행하세요.
9. 확인 및 보고: 최종본의 스틸을 검토하고, 믹스 보고서의 음량(loudness)을 읽고, clip scan out을 실행하세요. 생성된 항목, 파일 경로, 확인된 사항과 확인되지 않은 사항을 보고하세요.

무음 클립은 7단계를 건너뜁니다. 캡션은 각 큐의 at과 until 값에서 가져오며, clip timing이 페이지에 이를 작성합니다.

안전 규칙

클립 작업에는 사용자의 돈, API 키 및 공개된 신원이 관련됩니다.

• 유료 요청은 명시적인 사용자 승인이 필요합니다. 제공업체가 나레이션과 음악 비용을 청구합니다. CLI는 --generate 없이는 아무것도 보내지 않습니다. 사용자가 특정 테이크를 승인한 후에만 해당 플래그를 전달하세요. 한 테이크에 대한 승인이 다음 테이크를 포함하지 않습니다. 요청 시 드라이런 출력(라인 및 문자 수)을 표시하세요. 요청이 중단되면 영수증은 attempted 상태로 유지됩니다. 사용자가 제공업체의 사용 기록을 확인할 때까지 재시도하지 마세요. 요청이 이미 청구되었을 수 있기 때문입니다.
• API 키는 환경 변수에서만 가져옵니다. CLI는 ELEVENLABS_API_KEY 또는 OPENAI_API_KEY만 읽고 다른 소스는 읽지 않습니다. 사용자의 비밀 저장소에서 단일 명령을 위해 키를 인라인으로 전달하세요(references/keys-and-paid-calls.md에 명령어가 있습니다). 사용자에게 대화에 키를 붙여넣도록 요청하지 말고, 키를 출력(echo, env, cat)하거나 파일에 쓰지 마세요. 키가 설정되었는지 확인하려면 길이를 확인하세요. clip doctor가 이를 수행합니다.
• 파일을 전달하고 게시하지 마세요. 클립을 게시하거나 업로드하는 것은 사용자가 요청하지 않는 한 사용자의 행동입니다.
• 사용자가 사용할 권리가 있는 자료만 사용하세요. 음악, 글꼴, 로고 및 영상에는 라이선스 또는 사용자의 소유권이 필요합니다. 사용자가 소유하거나 표시할 권한이 있는 앱만 표시하고, 다른 회사의 제품으로 목업(mock-up) 스타일을 지정하지 마세요. 두 제공업체의 약관은 상업적 사용과 생성된 음성의 공개를 다룹니다. 나레이션 클립이 게시되기 전에 사용자에게 이를 알리세요.
• 개인 데이터를 화면과 파일에 포함시키지 마세요. 앱 화면에는 가상의 이름과 숫자를 사용하세요. 실제로 제시되는 수치와 인용문은 실제여야 하며, 예시는 예시임을 식별할 수 있어야 합니다. 공유하기 전에 clip scan을 모든 것에 대해 실행하세요. API 키, 로컬 사용자 이름 및 경로, 이메일 주소, 사용자의 개인 용어 목록, 미디어 파일에 포함된 메타데이터를 확인합니다.

편집 지침

• 클립당 하나의 주제를 다루세요. 두 가지를 다루는 스크립트는 분할하세요.
• 처음 몇 초 안에 나레이션 또는 첫 번째 캡션을 시작하세요.
• 비트(beat)당 하나의 큐를 사용하고, 해당 라인이 말해지는 동안 비트의 화면을 유지하세요.
• 항상 캡션을 포함하세요. 대부분의 피드 비디오는 음소거 상태로 재생됩니다.
• 긴 프레임은 휴대폰 크기로 검토하세요. 이러한 이유로 긴 프레임에서는 scene 단위가 더 큽니다.
• 상태 변경을 표시하거나 주의를 끌기 위해 움직임을 사용하세요. 지속적인 움직임은 피하세요.
• 마지막 카드를 최소 2.5초 동안 유지하세요.
• 교육용: 시청자가 수행하면서 따라갈 수 있는 속도로 동작을 보여준 다음 그 결과를 보여주세요. 화면에 단계 번호를 매기고 시작 부분에서 시청자가 무엇을 할 수 있게 될지 명시하세요.

명령어

명령어	기능
clip doctor	Node, ffmpeg 및 Playwright를 확인하고 설정된 키를 보고합니다 (길이만)
clip init <dir> --template graphics|app-ui	작동하는 예제로 프로젝트를 생성합니다
clip serve	라이브 미리보기를 제공합니다. URL에 ?t=5를 추가하면 5초에서 멈춥니다
clip stills [--at 2,5,9] [--frame tall] [--final]	검토용 스틸과 연락처 시트를 렌더링합니다
clip capture [--frame wide] [--draft] [--final] [--from s --to s] [--web]	모든 프레임을 렌더링하고 MP4로 인코딩합니다
clip capture --mode clock --url … --seconds N [--actions file.mjs]	실행 중인 앱을 캡처합니다 (실험적, references/app-ui.md 참조)
clip tts [--generate]	녹음할 나레이션을 나열합니다. --generate를 사용하면 녹음합니다 (유료)
clip music [--generate]	생성된 배경 음악에 대해 동일합니다 (유료)
clip timing	큐와 캡션 시간을 계산합니다. scene/timing.json과 .srt 파일을 씁니다
clip mix	표준 음량으로 사운드트랙을 빌드하고 각 캡처된 비디오에 먹싱합니다
clip web <video>	업로드용 작은 복사본을 씁니다
clip scan <dir> [--terms-file words.txt]	파일이 공유되기 전에 개인 데이터를 보고합니다
clip strip <media file>	모든 포함된 메타데이터를 제거한 복사본을 씁니다

출력은 out/으로 이동하며, <name>-<take>-<frame>.mp4 형식으로 명명되고, -draft, -part(--from/--to로 캡처된 범위), -sound 및 -web 접미사가 해당하는 경우 추가됩니다. 이전 버전을 새 버전 옆에 유지하려면 clip.json에서 "take"를 증가시키세요 (a, b, c, ...).

참조 파일

현재 단계에 필요한 파일을 읽으세요.

파일	읽을 시기
references/scenes.md	scene을 작성하거나 변경할 때: 페이지 계약, 도우미 라이브러리, 단위, 긴 프레임, 글꼴 및 캡처를 결정론적으로 유지하는 제약 조건
references/app-ui.md	클립이 앱 화면을 보여줄 때: 디자인 토큰에서 재구축, 포인터, 타이핑, 카메라 이동 및 실행 중인 앱 캡처
references/narration.md	라인 작성, 제공업체 및 음성 선택, 발음, 한 라인 재녹음, scene을 나레이션에 맞추기, 캡션
references/sound.md	음악 및 믹스: 레벨, 덕킹(ducking), 트랙을 클립에 맞추기, 음량, 믹스 수정
references/keys-and-paid-calls.md	유료 요청 전: 키를 안전하게 전달하는 방법, 전송되는 내용, 영수증, 중단된 요청
references/project-file.md	clip.json의 모든 필드
references/delivery.md	프레임 크기, 최종 렌더링, 전달 전 확인 사항, 보고할 내용
references/cookbook.md	요청이 일반적인 작업과 일치할 때: 무음 클립, 디자인 토큰의 앱 화면, 여러 종횡비, 단계별 교육 클립, JSON의 막대 차트, 각 제공업체의 나레이션, 라인 재녹음, 배경 음악, 사용자 정의 글꼴 및 로고, 실행 중인 앱, 최종 확인. 또한 draw() 스니펫

문제 해결

증상	가능한 원인
"This looks like a command sandbox", listen EPERM 또는 브라우저 시작 실패	에이전트의 샌드박스가 HTTP 서버 또는 브라우저를 차단하고 있습니다. 사용자의 승인을 받아 stills, capture 및 serve를 샌드박스 외부에서 실행하세요
"The page never set window.ready"	scene의 스크립트 오류 (메시지에 페이지의 오류가 나열됨) 또는 페이지가 키트의 clip()을 호출하지 않음
동일한 scene의 두 캡처가 다름	scene의 일부 상태가 s에서 계산되지 않음: Math.random(), Date, CSS 애니메이션 또는 전환, <video>, 타이머
다른 기기에서 텍스트가 다른 글꼴로 렌더링됨	scene이 시스템 글꼴을 사용합니다. 글꼴 파일을 scene 디렉토리에 넣으세요 (references/scenes.md)
화면이 나레이션보다 앞서거나 뒤쳐짐	새 녹음 후에 clip timing이 실행되지 않았거나, 그 전에 비디오가 캡처되었습니다. clip mix는 첫 번째 경우 실행을 거부하고 두 번째 경우 경고합니다
tts 목록에 attempted가 표시됨	이전 요청이 완료되지 않았습니다. --retry-attempted를 사용하기 전에 제공업체의 사용 기록을 확인하세요
단어 사이에서 음악 레벨이 오르락내리락함	"mix": { "master": "limit" } 설정 (references/sound.md)