vvai-pixel-mv · 픽셀 캐릭터 비트 MV은(는) 무엇을 하나요?
순서 고정: 스토리라인 → 스토리보드(사용자 확인 및 수정, 여러 번 가능) → 사용자 승인 → 출력. 사용자 승인 없는 스토리보드는 렌더링하지 않습니다.
전체 예시는 assets/examples/에 있습니다: 노래 하나의 스토리라인과 story.json, 7개 구간, 3개 캐릭터, 데스크탑 창 포함.
준비
PY: librosa, faster-whisper, numpy, Pillow가 설치된 Python 3.10 이상. 설치는 INSTALL.md 참조. 사용자의 CLAUDE.md나 메모리에 Python 경로가 명시되어 있으면 그 경로 사용; 없으면python으로 해당 패키지를 임포트할 수 있는지 확인하고, 안 되면 사용자에게 문의.MV:PY -X utf8 <본 스킬 경로>/scripts/pixel_mv.py- ffmpeg, Node 필요. 렌더링 기본값은
npx --yes [email protected]; CLI를 변경하려면 환경 변수HF_CLI설정, 여러 인자는|로 구분.
워크플로우
- 자료 수집. 오디오, 타임스탬프가 있는 가사(srt 또는 lrc), 노래 제목이 필수입니다.
- 선택 사항: 시작/종료 시간 잘라내기, 색상 프로필(base / neon / classic / retro), 강도(dj / standard / soft), 캐릭터 이미지.
- 스토리 질문: 사용자가 머릿속에 구체적인 스토리가 있는지? 없으면 3단계에서 제안.
- 가사 파일이 없으면 사용자에게 요청, 자동 전사로 추측하지 마세요. 전사로 사람 음성을 구분할 수 없는 구간은 먼저 사용자에게 물어보고, 인트로로 간주하지 마세요. (1화에서 실수로 벌스를 인트로로 처리한 사례 있음).
- 프로젝트 생성:
MV new <프로젝트 디렉토리> --audio <오디오> --lyrics <srt/lrc> --title <노래 제목> [--start 초 --end 초] [--look base] [--character 이미지]- 이 단계에서 오디오 자르기, 비트 및 에너지 피크 측정, 단어별 가사 정렬.
- 동시에 키워드 기반 장면 전환을 적용한 초안
story.json과스토리라인.md템플릿 생성. - 프로젝트는 사용자가 지정한 디렉토리에 저장; 사용자가 고정된 시리즈 디렉토리(CLAUDE.md나 메모리에 명시)를 가지고 있으면 해당 위치에 저장.
- 스토리라인 작성. 스토리텔링 방법에 따라
스토리라인.md작성: 한 문장 스토리, 캐릭터, 모티프, 막, 문장별. 사용자 확인. - story.json 작성. 스토리라인을 story.json으로 변환.
- 스토리보드 생성 및 사용자 확인.
MV board <프로젝트> --frames실행: 각 구간별 1-3장 이미지 캡처,스토리보드.md생성. 내용은 전체 개요, 구간별 캐릭터, 스토리 액션, 가사 줄 및 등장 방식, 장면 전환, 카메라, 비트 포인트.- SendUserFile을 사용하여
스토리보드.md와스토리보드/장면/의 콘택트 시트를 사용자에게 전송. - 사용자가 수정할 수 있는 부분을 알려주세요.
- 수정 반복. 사용자가 수정 요청하면 story.json을 수정하고
board다시 실행.- 버전 번호는 자동 증가, 이전 버전은
스토리보드/기록/에 저장. - 여러 번 반복 가능, 매번 새 스토리보드를 사용자에게 전송.
- 버전 번호는 자동 증가, 이전 버전은
- 승인 후 최종 출력.
- 사용자가 명확히 "출력해 줘"라고 하면
MV approve <프로젝트>실행, 이후MV render <프로젝트> --sample 12실행. - 애매한 응답("좋아", "알아서 해")은 승인으로 간주하지 않음.
render는 story.json의 지문을 확인, 승인 후 수정되면 거부.- 30MB 초과 시
_미리보기.mp4로 추가 압축하여 모바일용 제공.
- 사용자가 명확히 "출력해 줘"라고 하면
- 전달. 1프레임/초로 스티칭하여 직접 확인: 스토리가 이해되는지, 배경, 가사, 장면 전환, 제목이 모두 있는지, 길이가 원본 오디오와 일치하며 오디오 트랙이 있는지.
- 출력 후 사용자가 추가 수정 요청 시 6단계로 돌아가기: story.json 수정 → 새 스토리보드 → 재승인 → 재렌더링.
핵심 규칙
- 스토리가 효과보다 우선. 각 문장에는 최소 하나의 스토리 액션 또는 가사 인터랙션이 포함되어야 함; 스토리 액션은 키워드 시간에 정확히 배치; 장면 전환에는 스토리적 이유가 있어야 함. 자세한 내용은 스토리텔링 방법 참조.
- 장면 전환: 스토리 요구사항이 없을 경우 기본값은 "데스크탑 위주 + 이미지 삽입", 스토리보드 규칙 참조. 스토리가 있을 경우 막에 따라 진행, 깨달음이나 회상 같은 구간은 데스크탑 창 뷰 사용.
- 캐릭터:
- 기본 Claude 캐릭터가 "나" 역할.
- 다른 캐릭터는
cast로 선언(girl, rival, friend, ghost). - 사용자가 이미지를 제공하면
MV character <프로젝트> <이미지>실행, 16×16 픽셀 캐릭터로 변환.
- 비트 동기화:
- 캐릭터가 각 비트에 정확히 착지, 착지 시 압축, 발 밑 물결 퍼짐.
- 각 비트에 카메라 충격 및 색상 플래시, 강한 비트 시 RGB 분리.
- 전체 화면 흰색 플래시는 장면 전환 및 드롭에만 사용, 초당 3회 이하.
- 놀람 반응 패키지는 전체 영상에서 최대 2회, 진짜 반전에만 사용.
- 가사 본문:
- 화면 및 프로젝트 파일에만 나타남; 채팅 응답 및 스토리보드에는 문장 부호만 작성.
- 노래 저작권은 사용자 책임, 배포 전에 주의 문구 포함.
명령어 목록
| 명령어 | 기능 |
|---|---|
new | 프로젝트 생성: analyze + align + draft + story |
story | 스토리라인.md 템플릿 생성 (--force 재생성) |
check | story.json의 이름, 시간, 창이 엔진이 인식 가능한지 확인 |
board [--frames] | 스토리보드 생성(N번째 버전), 기록 저장 |
approve | 사용자 승인 버전 기록; 이후 render에서 허용 |
render [--sample 12] [--name 파일명] | 렌더링; --force는 승인 건너뛰기, 사용자 명시적 요청 시에만 사용 |
sync | story.json → assets/story.js 동기화(디버깅용; board와 render는 자동 동기화) |
upgrade | 이전 프로젝트를 현재 템플릿 엔진으로 업그레이드, 이전 파일은 .before-upgrade 백업 |
character | 캐릭터 이미지 → 픽셀 캐릭터 |
analyze / align / draft | new의 세부 단계, 개별 재실행용 |
템플릿 외 커스터마이징
템플릿 엔진 v2가 이미 다음을 지원하며, 인터랙션 카탈로그 참조:
- 27개 배경, 16가지 기본 동작;
- 23가지 스토리 액션;
- 7가지 가사 방식, 6가지 등장, 9가지 퇴장;
- 7가지 장면 전환;
- 데스크탑 창.
부족할 경우 해당 프로젝트의 assets/engine.js에 추가, 본 스킬의 템플릿은 수정하지 마세요. 1화 기법 참조 가능. 새로운 구간을 템플릿에 정착시키려면 먼저 사용자 확인. 정착 시 다음을 모두 수정:
- 템플릿
engine.js; pixel_mv.py의BEAT_NAMES등 목록 및 스토리보드용 한글명ZH_*;interactions.md.
배경 라이브러리
- 데이터는
assets/scene-library/scenes.json에 저장. - 배경 추가 시 두 곳 수정:
scenes.json에 키워드 및 인터랙션 등록, 템플릿engine.js의SCENES에 그리기 메서드 작성.