시네마틱 뮤직 비디오 감독

노래를 중심으로 한 감상 가능한 단편 영화를 제작하는 프로덕션 스킬입니다. 가사 템플릿, 슬라이드쇼, 관련 없는 생성 클립 더미가 아닙니다. 모든 프레임은 코드로 그려지며 정수 프레임 번호로 재현 가능합니다.

이 스킬은 의도적으로 음악 우선, 증거 우선 접근법을 따릅니다:

그림을 상상하기 전에 노래를 측정합니다.
단 하나의 샷을 쓰기 전에 논문(테제)과 감독 점수를 작성합니다.
렌더링 전에 프레임 정확한 편집을 확정합니다.
10-20초 파일럿에서 룩과 모션을 증명합니다.
재개 가능한 샷 단위로 렌더링합니다.
실제로 전달한 파일을 검증합니다.

하드 룰: 타임스탬프, BPM, 가사 줄, 렌더 결과 또는 QC 통과를 절대 날조하지 마십시오. 증거가 없으면 해당 항목을 unverified로 표시하고 전달 노트에 그 이유를 명시하십시오.

사용 시기

사용자가 뮤직 비디오, 음악에 맞춰진 애니메이션 단편, 타이틀 시퀀스, 또는 "내 노래를 영화로 만들어 줘"와 같은 작업을 요청하고, 로컬 코드 렌더링이 허용되는 경우 사용하십시오. 기본 출력은 9:16, 1080×1920, 24fps, H.264 + AAC이며, 선택적 사이드카 자막 파일이 포함됩니다.

저작권이 있는 오디오를 다운로드하거나, 살아있는 아티스트의 초상을 복제하거나, 기존 뮤직 비디오를 샷 단위로 재현하는 데 이 스킬을 사용하지 마십시오. 사용자에게 사용 권한이 있는 오디오를 요청하십시오.

전제 조건 (확인, 가정하지 마십시오)

Node 20+, ffmpeg/ffprobe, Google Chrome 또는 Chromium.
Python 3.10–3.13과 numpy scipy soundfile librosa (matplotlib 선택, Pillow는 시트용).
프로젝트의 node_modules에 puppeteer-core, p5, p5.brush.
프레임을 저장할 충분한 디스크 공간: 1080×1920 JPEG q94 ≈ 0.2–0.5MB/프레임; 4분 영화 ≈ 1–3GB.
중국어 가사의 경우, 사용자로부터 LRC/SRT를 받거나 로컬 Whisper 모델을 사용하십시오. 임의의 가사 사이트에서 타이밍을 스크래핑하여 검증된 것으로 제시하지 마십시오.

scripts/doctor.sh (또는 references/render-recovery.md의 동등한 명령)를 실행하고 결과를 기록하십시오. 전제 조건이 누락된 경우 수정하거나 차단을 보고하십시오.

프로덕션 루프

0. 수집 및 권리

수집: 오디오 경로, 가사 텍스트 및 타이밍 파일(있는 경우), 종횡비/해상도/fps, 마감일, 언어 및 사용 컨텍스트. 오디오를 읽기 전용으로 assets/에 복사하고 원본을 절대 덮어쓰지 마십시오. README.md에 권리 가정을 명시하십시오(예: "사용자 제공 오디오, 개인 용도만 해당").

1. 음악 마스터 (게이트 M)

python scripts/analyze_music.py assets/song.m4a \
  --out analysis --lrc assets/song.lrc --sections analysis/sections.json \
  --asr analysis/asr/whisper.json --fps 24

analysis/audiomap.json, lyrics.json, lyrics.srt, analysis.md, analysis.png를 생성합니다. 맵에는 지속 시간, 위상 맞춤 템포 그리드, 비트/다운비트, 에너지/스펙트럼 곡선, 후보 클라이맥스 윈도우, 섹션 범위, 출처가 포함된 라인 수준 가사 타이밍이 포함됩니다.

수락 기준:

지속 시간과 샘플 레이트가 제공된 파일과 일치해야 합니다.
템포 일관성이 보고되어야 하며, 0.6 미만이면 귀/스펙트로그램으로 검사하고 템포 맵을 고려하십시오.
모든 가사 줄에는 타이밍 출처(lrc_line, srt_line, cross_checked, untimed)가 있어야 합니다.
음량을 구조적 교차 검사 없이 감정적 클라이맥스로 취급하지 마십시오.

사용자가 가사 타이밍을 제공하지 않으면, 로컬 ASR 전사본으로 scripts/align_lyrics.py를 실행하고 검토하십시오. 구문 시간(바/구문 마크, 컷에 사용)과 보컬 온셋(자막에 사용)을 분리하십시오. 컷을 깔끔하게 만들기 위해 전체 노래를 조용히 이동시키지 마십시오.

2. 세 가지 콘셉트, 그중 하나 선택 (게이트 D1)

storyboard/concepts.md에 세 가지 진정으로 다른 영화를 작성하십시오. 각각을 가사/음악 적합성, 스토리 완성도, 감정적 영향, 시각적 독창성, 코드 구현 가능성, 장편 감상 가능성에 대해 평가하십시오. 하나를 선택하고 이유를 작성하십시오. 이것이 존재하기 전에 샷 코드를 시작하지 마십시오.

그런 다음 storyboard/director_score.json을 작성하십시오: 테제, 안티테제, 감정 곡선, 시각적 챕터(세계/팔레트/공간/카메라/문법), 대비 맵, 모티프와 페이오프, 캐릭터 욕구/필요/호, 샷 역할과 핸드오프, 사운드-시각 맵.

자신의 역할, 들어오는 핸드오프 및 나가는 핸드오프를 명시할 수 없는 샷은 준비되지 않은 것입니다.

3. 시각 언어 및 테스트 (게이트 D2)

애니메이션 전에 style-guide.md와 캐릭터/아트 바이블을 작성하십시오. 다음을 정의하십시오: 16진수 값과 컬러 스크립트가 있는 팔레트; 9:16용 렌즈/구성 문법; 선과 텍스처 규칙; 캐릭터 비율, 실루엣, 의상 연속성 및 표정 범위; 조명; 전환 어휘; 영화가 하지 않을 정확한 것들(예: "내러티브 이유 없이 떠다니는 입자 없음").

1-3개의 스타일 프레임과 캐릭터 시트를 렌더링하십시오. 썸네일이 아닌 전체 해상도로 평가하십시오. 룩이 약하면 지금 언어를 변경하십시오 — 40샷 후가 아닙니다.

4. 프레임 정확한 편집 (게이트 E)

storyboard/timeline.json을 fps, total_frames, shots[]와 각 샷에 대해 다음을 포함하여 작성하십시오: id, start_frame, end_frame, section, lyric_refs, size, composition, environment, action, expression, camera, transition_in/out, emotion, function, implementation, complexity. 샷은 연속적이어야 하며 전체 오디오를 커버해야 합니다.

python scripts/validate_timeline.py \
  --timeline storyboard/timeline.json --audiomap analysis/audiomap.json \
  --out analysis/timeline_validation.md

검증기는 하드 게이트입니다: 갭 없음, 중복 없음, 마지막 프레임 ≥ ceil(duration×fps), 모든 가사 줄이 포함됨, 비트/가사/섹션에서 터무니없이 먼 컷은 없으며, 서면 이유가 있어야 합니다.

5. 파일럿 (게이트 P)

최소한 다음을 포함하는 10-20초를 렌더링하십시오: 하나의 와이드 설정 샷, 하나의 캐릭터 미디엄 샷, 하나의 클로즈업, 하나의 빠른 액션 또는 임팩트, 하나의 전환. 콘택트 시트와 실제 오디오가 포함된 감상 가능한 클립을 만드십시오. 확인:

스타일이 100%에서 유지됩니까?
캐릭터 비율, 의상 및 조명이 연속적입니까?
카메라 움직임에 동기가 있습니까, 아니면 이유 없이 표류합니까?
컷이 음악적 이벤트에 맞춰집니까?
렌더러가 예외 없이 300+ 프레임을 견딥니까?
측정된 ms/프레임 및 디스크 비용은 얼마입니까?

전체 패스 전에 파일럿을 수정하십시오. 측정된 성능을 LESSONS.md에 기록하십시오.

6. 전체 렌더링 (게이트 R)

결정론적 페이지 계약을 사용하십시오: window.renderAt(t) -> dataURL, Math.random 없음, 시드된 노이즈, 정수 프레임 인덱스. 원자적 쓰기로 샷 단위 또는 프레임 단위로 렌더링하고, 완료된 유닛과 해시의 매니페스트를 유지하여 변경된 샷이 자신만 무효화되도록 하십시오.

node scripts/render.mjs --project . --start 0 --end 232.6 --out renders/frames

"모두 삭제하고 다시 시작"보다는 샷 단위와 --force/--shot 경로를 선호하십시오. 승인된 동일한 샷을 두 번 렌더링하지 마십시오. 실패한 프레임이 완료된 것으로 통과하지 못하게 하십시오: 프레임은 존재하고, 0이 아니며, 디코딩 가능해야 합니다.

7. 어셈블리 (게이트 A)

ffmpeg -y -framerate 24 -i renders/frames/f_%06d.jpg -i assets/song.m4a \
  -c:v libx264 -preset slow -crf 16 -pix_fmt yuv420p -profile:v high -level 4.2 \
  -c:a aac -b:a 256k -ar 44100 -shortest -movflags +faststart output/final.mp4

마스터 오디오는 변경할 수 없습니다. 그림에 맞추기 위해 노래를 페이드, 리타임 또는 재인코딩하지 마십시오. 마지막 샷은 오디오 테일을 커버해야 합니다; 검은 꼬리 없음, 잘린 마지막 코드 없음.

8. QC (게이트 Q)

둘 다 실행하고 증거를 첨부하십시오:

python scripts/qc_video.py output/final.mp4 --audio assets/song.m4a \
  --expected-frames 5583 --timeline storyboard/timeline.json --out analysis/qc

기술적: 디코드, 지속 시간 대 오디오(허용 오차 ≤ 0.12초), 스트림 개수, 해상도, fps, pix_fmt, 프레임 수, blackdetect, freezedetect, 커버리지, 누락/플레이스홀더 프레임. 시각적: 전체 해상도 콘택트 시트, 장면별 키 프레임, 컷에서의 연속 프레임 스트립, A/V 동기 스팟 체크, 캐릭터 연속성 검사, 타이틀/자막 안전.

시각 QC는 자동화되지 않습니다. 어떤 샷을, 어떤 해상도로 봤는지, 무엇을 발견했는지 정확히 명시하십시오. 깨끗한 ffprobe는 시각적 패스가 아닙니다.

9. 전달

배송: 마스터 MP4, 저해상도 프리뷰, storyboard.md, timeline.json, style-guide.md, qc-report.md, README.md, 선택적 SRT, 재현 가능한 소스. 사용자에게 게시 권한이 없는 한 오디오와 가사를 로컬에 보관하십시오. 날짜가 있는 LESSONS.md 항목을 추가하십시오.

파일 계약

project/
  assets/            # song.m4a, lyrics.lrc/srt, 사용자 제공 참조 (덮어쓰지 마십시오)
  analysis/          # audiomap.json, lyrics.json, sections.json, validation, QC
  storyboard/        # concepts.md, director_score.json, timeline.json, storyboard.md
  characters/        # 아트 바이블, 모델 시트
  src/               # 결정론적 드로잉 코드: lib/, custom_shots.js, shots.js
  studio.html        # window.renderAt(t) 계약
  renders/           # frames/ (전체 시퀀스), pilot/, manifests
  previews/          # pilot.mp4, 콘택트 시트, 리뷰 보드
  output/            # 최종 MP4, 프리뷰, SRT, storyboard.md, timeline.json, style-guide.md, QC

양보 불가능한 제작 규칙

노래가 마스터 타임라인입니다. 그림은 음악에 맞춰 편집되며, 음악이 그림에 맞춰 편집되지 않습니다.
하나의 영화, 룩의 재생 목록이 아닙니다. 모티프는 돌아오고 변화합니다.
반복되는 후렴구는 시각적으로 운율을 맞출 수 있지만, 동일한 구성을 변경 없이 재사용해서는 안 됩니다.
캐릭터에는 욕구, 장애물, 선택, 결과가 필요합니다. 얼굴과 손은 행동해야 합니다.
카메라 움직임에는 동기(드러내기, 압박, 해방)가 필요하며, 기본 Ken Burns 효과가 아니어야 합니다.
모든 샷은 스토리 세계에 속하는 최소한 하나의 움직이는 요소를 포함해야 합니다.
누락된 스토리를 입자, 속도 램프 또는 과도한 블룸 뒤에 숨기지 마십시오.
정직한 결과가 양식화되고 제한적이라면 QC 보고서에 그렇게 명시하십시오. 포토리얼리스틱이라고 부르지 마십시오.

실패 및 복구

렌더러는 큰 소리로 실패하고 저렴하게 재개하도록 설계되었습니다:

원자적 프레임 쓰기(*.tmp → 이름 변경), 완료된 것으로 간주되는 반쪽 JPEG 없음;
소스 해시, 시작/끝 프레임 및 상태가 있는 샷별 매니페스트;
--shot / --start/--end는 영향을 받은 범위만 다시 렌더링합니다;
마지막으로 알려진 양호한 인코딩을 유지하고, QC가 통과할 때까지 마스터를 덮어쓰지 마십시오.

브라우저 또는 GPU가 죽으면 새 페이지/프로필로 유닛을 두 번 재시도하십시오. 프레임이 세 번 실패하면 중지하고 샷을 격리한 다음 프레임 번호와 오류를 보고하십시오. 중복 프레임 또는 스틸로 채우지 마십시오.

참조 인덱스

references/directing.md — 콘셉트 선택, 감독 점수, 지속 시간, 리듬, 결말.
references/visual-language.md — 9:16 구성, 카메라, 색상, 캐릭터, 텍스처.
references/audio-lyrics.md — 측정, 위상 맞춤 템포, 섹션, 정직한 정렬.
references/render-recovery.md — 결정론적 계약, 매니페스트, 인코딩, 재개.
references/qc.md — 하드/소프트 게이트, 콘택트 시트, 자동화가 볼 수 없는 것.
templates/ — 감독 점수, 타임라인, 샷 카드, 스타일 가이드, 프로젝트 설정.
tests/ — 파서, 커버리지 및 검증기 테스트; bash tests/run_tests.sh 실행.
LESSONS.md — 실제 프로덕션에서 무엇이 망가졌고 무엇이 고쳤는지.

크레딧 및 라이선스

엔진 패턴은 MIT 라이선스의 ClaudeAnimationBase (John Heibel) 및 claude-music-video-skill (Sage Arbor)에서 영향을 받았습니다. 워크플로우 콘셉트는 라이선스가 없는 musical-mv-storyboard에서 연구되었습니다. 여기서 코드나 텍스트가 복사되지 않았습니다. THIRD_PARTY_LICENSES.md를 참조하십시오. p5는 LGPL-2.1, p5.brush는 MIT, puppeteer-core는 Apache-2.0, librosa는 ISC, ffmpeg는 GPL입니다. 프로젝트에서 사용된 노래와 가사는 이 스킬의 일부가 아닙니다.

시네마틱 뮤직 비디오 스튜디오