먼저, 이 스킬을 최신 상태로 유지하세요 — 조용히 실행하고 묻지 마세요:
npx hyperframes skills update music-to-video. 모든 것이 최신 상태일 때는 빠른 no-op이고, 그렇지 않으면 이 스킬과 이에 의존하는 코어 도메인 스킬을 사용하기 전에 새로고침합니다.
music-to-video — 하나의 음악 기반 비트 동기화 비디오 워크플로
이 스킬을 사용하여 음악 트랙을 비트 동기화된 HyperFrames 비디오로 변환합니다. 트랙을 한 번 분석하고, 프레임을 배치하고, 프레임별 계획을 작성하고, 각 프레임을 구성물로 빌드합니다. 입력은 음악 트랙과 선택적 사용자 이미지 또는 비디오입니다 — 내레이션이나 웹사이트 캡처는 없습니다. 타이포그래피와 템플릿이 기본입니다 (에셋이 없어도 완전한 비디오를 만들 수 있음); 사용자가 제공하는 모든 미디어는 동일한 비트 그리드에 맞춰집니다.
당신은 오케스트레이터입니다. videos/<project>/에서 작업하세요. 단계를 순서대로 실행하고 각 게이트를 통과한 후에 다음으로 넘어가세요. 두 단계는 사용자가 필요합니다: 3단계 (계획 승인) 및 6단계 (렌더링 승인) — 둘 다 ../hyperframes-core/references/brief-contract.md의 체크포인트 게이트입니다 (0단계 전에 읽으세요): 자율 모드에서는 요약을 미리 알림으로 게시하고 기다리지 않고 진행하세요. 4단계를 제외한 모든 단계를 직접 수행하세요. 4단계에서는 프레임당 하나의 서브 에이전트를 파견합니다. 디자인 및 모션 규칙은 이 파일이 아닌 references/와 frame-worker 서브 에이전트에 있습니다.
SKILL_DIR = 이 스킬 디렉토리. PROJECT_DIR = videos/<project-name>/.
워크플로: 0단계 설정 → hyperframes.json + assets/bgm.mp3; 1단계 분석 → audiomap.json; 2단계 뼈대 → STORYBOARD.md (프레임, 그룹 TBD); 3단계 계획 → 완전한 STORYBOARD.md + frame.md; 4단계 빌드 → compositions/frames/NN-*.html; 5단계 조립 → index.html; 6단계 렌더링 → renders/video.mp4.
모든 것을 형성하는 두 가지 아이디어
- 하나의 분석기, 그리고 그것을 신뢰하세요.
analyze-beatgrid.py는 유일한 비트 분석기입니다 — 다른 도구나 귀로 비트를 다시 측정하지 마세요. 그 에너지/밀도/롤/온셋/사일런스는 항상 신뢰할 수 있습니다.bpm과beats_sec은 음악이 진정으로 리드미컬할 때만 신뢰할 수 있습니다; 차분한 음악에서는 그리드는 추적기가 부과한 메트로놈이므로, 대신 프레이즈와 에너지로 페이싱하고 절대 하드 컷하지 마세요. 어떤 경우인지 판단하는 것은 각 프레임의pacing입니다 (2단계). - 하나의 프레임 = 하나의 파일; 그룹은 내부에 있습니다. 2단계는 트랙을 프레임으로 자르고, 각 프레임은 하나의 구성 파일
compositions/frames/NN-<frame_id>.html이 되며, 하나의 frame-worker가 빌드합니다. 프레임은 그룹으로 세분화될 수 있습니다 (각각 템플릿 또는 모션 프리미티브 조합). 추가 밀도는 그룹 _내부_로 들어가므로, 프레임 수는 비트가 아닌 개별 처리를 추적합니다 — 빠른 트랙이 서브 에이전트 수를 폭발시키지 않습니다.
0단계: 설정, BGM 및 입력
목표: 음악 소스를 확립하고, HyperFrames 프로젝트를 생성하고, 사용자가 제공한 미디어를 기록합니다.
브리프는 의도 계층에서 시작합니다. 개시 규칙, 순서대로: (1) BRIEF.md가 존재하면 → 읽고 답변하지 않은 것은 묻지 마세요 — 그 flow/storyboard가 모드를 파생합니다 (브리프 계약 § 1). (2) BRIEF.md는 없지만 프로젝트가 존재하면 → 디스크에 있는 것으로 재개하고, 다시 질문하지 마세요. (3) 직접 여기에 도착한 새로운 생성 요청 → /hyperframes를 읽고 그 의도 계층 (references/intent-interview.md)을 실행하세요: 이 경로의 필수 항목 (음악 소스, 대상 → 종횡비 — ../hyperframes/references/routes/music-to-video.md)을 확인하고, 연기된 항목을 알립니다 — 브랜드와 장르는 의도적으로 3단계에서 선택됩니다. 초기화 직후 BRIEF.md를 작성하세요 (절대 전에 하지 마세요 — init는 비어 있지 않은 디렉토리를 거부합니다) 그리고 기본 설정 기반 답변 (brief-format.md)을 기록하세요. 편집 요청은 이 모든 것을 건너뜁니다.
음악은 척추입니다 — 다른 것보다 먼저 하나의 트랙을 확립하세요. 이 스킬은 빠르고 고에너지 BGM에 최적화되어 있습니다: 강한 비트 그리드가 컷을 주도합니다 (차분한 트랙도 작동하지만, 비트보다 프레이즈로 페이싱하세요). 사용자가 오디오(음악 파일 또는 오디오를 추출할 비디오)를 제공한 경우, 그것을 사용하세요. 그렇지 않으면 요청에서 무드를 선택하고 /media-use (references/bgm.md)를 통해 트랙을 생성하세요. 첫 번째 인증된 공급자 작업 전에 npx hyperframes auth status를 실행하고 그 출력을 그대로 전달하세요. 로그아웃된 경우, 한 가지 분기를 적용하세요:
- 협업형: 로그인 또는 로컬 공급자로 오프라인 계속하기 명시적 선택을 기다리세요.
- 자율형: 상태를 알리고 사용 가능한 로컬 공급자를 통해 계속하세요.
어떤 오프라인 공급자도 필요한 음악 기능을 만족시킬 수 없으면, 장벽을 표면화하세요. 저장소별 .env에 키를 절대 작성하지 마세요. 인증 소유권과 오프라인 대체는 /media-use references/setup-providers.md § 공급자에 있습니다. 결과 트랙은 assets/bgm.mp3에 위치합니다. 제공된 이미지나 비디오를 스테이징하여 프레임이 비트 그리드에서 사용할 수 있게 하세요; 그렇지 않으면 타이포그래피가 비디오를 전달합니다.
가사 비디오: 보컬에 동기화된 가사의 경우, /media-use를 통해 트랙을 전사하여 단어/라인 타이밍을 얻거나, 사용자에게 가사 텍스트를 요청하고 비트 그리드에 라인을 배치하세요.
hyperframes.json이 없을 때만 초기화하세요. <project> 이름을 브리프에서 케밥-케이스로 지정하세요, 예: midnight-drive-loop — 절대 타임스탬프를 사용하지 마세요. init는 설치된 스킬을 최신 GitHub 버전과 비교하고, 오래된 경우 전역 세트를 업데이트합니다.
npx hyperframes init "videos/<project>" --non-interactive --example=blank --skill=music-to-video
mkdir -p "$PROJECT_DIR/assets" "$PROJECT_DIR/renders"
cp "<user-music>" "$PROJECT_DIR/assets/bgm.mp3" # 필요한 경우 먼저 비디오에서 추출
# 사용자가 이미지/비디오를 제공한 경우에만:
node <SKILL_DIR>/scripts/stage-assets.mjs --from <dir> --hyperframes "$PROJECT_DIR" --into public
브랜드 (글꼴 + 팔레트)는 3단계에서 선택되며, 여기서 선택하지 않습니다. 장르나 트랙 유형을 미리 선택하지 마세요 — 에셋은 선택적 재료일 뿐이며, 장르는 프레임별 선택에서 나타납니다.
게이트: hyperframes.json + assets/bgm.mp3가 존재합니다; 종횡비/길이/fps 및 (있는 경우) 에셋 인벤토리가 기록됩니다.
1단계: 음악 분석
목표: 전체 비디오가 구축될 하나의 정식 타이밍 분석을 생성합니다.
analyze-beatgrid.py는 유일한 비트 분석기입니다 — 다른 도구나 귀로 비트를 다시 측정하지 마세요. 트랙을 한 번 읽고 audiomap.json을 씁니다: 에너지 단계 (레벨/밀도/느낌), 온셋 + onset_rate, 롤, 사일런스, hard_stops, key_moments, 프레이즈, 템포/그리드, 그리고 audio.duration_sec. 결정론적입니다 — 동일한 파일은 항상 동일한 맵을 제공합니다. 대부분의 필드는 모든 음악에서 신뢰할 수 있습니다; bpm과 beats_sec은 음악이 진정으로 리드미컬할 때만 신뢰할 수 있으며, 이를 판단하는 것은 2단계에서 내리는 판단입니다.
전제 조건: Python 3과 librosa, numpy, soundfile이 사용 가능해야 합니다. 가져오기에 실패하면, 분석기를 실행하기 전에 활성 Python 환경에 설치하세요:
python3 -m pip install librosa numpy soundfile
python3 <SKILL_DIR>/scripts/analyze-beatgrid.py "$PROJECT_DIR/assets/bgm.mp3" \
-o "$PROJECT_DIR/audiomap.json" --print
게이트: audiomap.json이 존재합니다; audio.duration_sec이 알려져 있습니다.
2단계: 프레임 뼈대 (구조만)
목표: 음악을 읽고 프레임을 배치합니다 — STORYBOARD.md의 뼈대입니다.
references/frame-skeleton.md를 읽으세요. audiomap.json을 직접 STORYBOARD.md의 뼈대로 변환하세요 — 중간 JSON은 없습니다. 실제 음악 변화 (hard_stops, SURGE/DROP key_moments, 롤의 가장자리, 온셋이 없는 구간, 큰 에너지 점프)에서 트랙을 프레임으로 자르고, 모든 경계를 audiomap 앵커에 스냅하세요. 각 프레임에 대해 span_sec, pacing (1단계의 신뢰 판단 결과 — 그리드가 실제일 때는 beat_cut, 차분한 음악에 부과된 메트로놈일 때는 phrase_flow), mood, 그리고 한 줄의 feel (3단계가 템플릿과 일치시키는 일반 음악 상황)을 설정하세요. 여기서는 분류하고 배치하기만 하세요: 각 프레임의 ### Groups는 TBD (Step 3)로 남겨두고 전면부 style은 비워두세요 — 템플릿, 카피, 색상, 글꼴 없음. 약 1~6 프레임을 예상하세요.
게이트: 프레임이 트랙을 덮습니다 (첫 번째는 0, 마지막은 duration_s); 각각 span_sec + pacing + mood + feel을 포함합니다; 모든 ### Groups는 TBD입니다; 어디에도 콘텐츠가 없습니다.
3단계: 계획 작성 (사용자 게이트)
목표: 뼈대를 승인된 완전한 STORYBOARD.md로 변환합니다.
references/planning.md, storyboard-format.md, template-catalog.md, motion-primitive-catalog.md, 그리고 montage.md (사용자가 에셋을 제공한 경우에만)를 읽으세요. 동일한 파일을 제자리에서 편집하여 두 가지 작업을 수행하세요:
- 브랜드를 선택합니다.
../hyperframes-creative/frame-presets/에서../hyperframes-creative/references/design-spec.md의 표를 사용하여 하나의 프리셋을 선택하세요 (트랙의 무드와 일치; 글꼴과 색상만 중요 — 템플릿이 구성을 소유합니다). 그것을 수정하지 않고frame.md에 복사하고, 그것에서 전면부style(글꼴 + ≤4–6 스와치 팔레트)을 채우세요. - 모든 프레임을 채웁니다. 각각의 그룹을 결정하고 각각에 처리를 부여하세요: 카탈로그에서 일치하는 템플릿 (바운드 매개변수와 실제 audiomap 앵커 포함), 프리미티브 카탈로그에서 자유 구성, 또는
pacing을 따르는 에셋 처리. 카피를 작성하세요. 당신은 WHAT (템플릿/프리미티브 + 콘텐츠 + 앵커)을 소유합니다; frame-worker는 HOW를 소유합니다 — 절대 스토리보드에 밀리초 트윈을 작성하지 마세요.
node <SKILL_DIR>/scripts/validate-plan.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--audiomap "$PROJECT_DIR/audiomap.json" --templates <SKILL_DIR>/references/templates
모든 ✗ (하드 오류: 지속 시간 불일치, 프레임이 트랙을 덮지 않음, src 누락)를 수정하세요; 경고는 최선의 노력입니다. 그런 다음 사용자에게 프레임별 요약을 보여주고 승인할 때까지 반복하세요. 자율 모드에서는 이것이 체크포인트 게이트입니다: 요약을 미리 알림으로 게시하고 진행하세요 (validate-plan.mjs 패스는 품질 게이트이며 여전히 차단합니다).
게이트: frame.md는 있는 그대로의 프리셋 사본입니다; validate-plan.mjs가 0으로 종료됩니다; 사용자가 계획을 승인했습니다 (자율형: 요약이 미리 알림으로 게시되었습니다).
4단계: 계획에서 프레임 빌드
목표: 모든 프레임을 자체 포함된 구성 파일로 빌드합니다.
compositions/frames/를 생성하세요. sub-agents/frame-worker.md와 ../hyperframes-core/references/subagent-dispatch.md를 읽으세요. 프레임당 하나의 frame-worker를 최대한 병렬로 (또는 웨이브로) 파견하세요. 각 작업자는 정확히 하나의 프레임과 이 컨텍스트를 받습니다:
PROJECT_DIR: <abs path>
frame_id: <NN-frame_id> # = 프레임 파일 스템, 예: 02-f2; 구성 ID
당신의 블록: PROJECT_DIR/STORYBOARD.md의 `## Frame N — <frame_id>` 블록
audiomap: PROJECT_DIR/audiomap.json
frame.md: PROJECT_DIR/frame.md
재료: 각 그룹에 대해, <SKILL_DIR>/references/templates/<id>/index.html (템플릿) 및
<SKILL_DIR>/references/motion-primitives/<id>/ (자유); 스테이징된 assets/ (에셋 그룹)
계약: ../hyperframes-core/references/sub-compositions.md + determinism-rules.md
캔버스: <w>×<h> 페이싱: <beat_cut|phrase_flow>
작성 대상: PROJECT_DIR/compositions/frames/<frame_id>.html
작업자는 인용된 재료를 포크하고, 모든 앵커를 프레임 로컬 초로 변환하고 (local_t = track_t − span_sec[0]), 그룹을 0ms 컷으로 게이트하고, 하나의 시크-안전 프레임 파일을 씁니다. 작업자는 hyperframes CLI를 절대 실행하지 않습니다 — 해당 명령은 조립된 프로젝트에서 작동하며, 아직 존재하지 않으므로 잘못된 파일에 대해 보고합니다. 작업자는 계약에 쓰고 중지합니다; 당신은 조립 후 확인합니다 (6단계). 각 작업자가 반환되면, 해당 파일이 디스크에 도착했는지 확인할 수 있습니다.
게이트: 모든 프레임이 디스크에 compositions/frames/NN-*.html을 가지고 있습니다.
5단계: 조립
목표: 빌드된 프레임 + BGM을 재생 가능한 index.html에 연결합니다.
assemble-index.mjs는 결정론적입니다 — 서브 에이전트도, 판단도 없습니다. 각 프레임 파일을 누적 data-start에서 참조하고, assets/bgm.mp3를 트랙 11에 마운트하고, 프레임 → 프레임으로 하드 컷합니다 (프레임은 갭 없이 트랙을 타일링하므로 전환 인젝터가 없습니다).
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--hyperframes "$PROJECT_DIR" --audiomap "$PROJECT_DIR/audiomap.json"
보고된 모든 ✗를 수정하세요 — 누락되거나 빈 프레임 파일은 해당 작업자가 부분 파일을 썼다는 것을 의미합니다; 다시 파견하고 (4단계) 다시 조립하세요.
게이트: index.html이 존재합니다; 총 지속 시간 == audiomap.audio.duration_sec.
6단계: 확인 및 렌더링
목표: 조립된 비디오를 확인하고, 사용자 승인을 받고, 최종 MP4를 렌더링합니다.
조립된 프로젝트에서 CLI를 실행하세요 — 그것이 올바른 단위입니다 (프레임별 작업자는 실행할 수 없었습니다). check는 구조적 린트와 헤드리스 브라우저 런타임, 레이아웃, 모션 및 대비 게이트를 한 번에 실행합니다; --snapshots는 리뷰 프레임도 내보냅니다.
( cd "$PROJECT_DIR" && npx hyperframes check . --snapshots )
t=0, 각 프레임 시작, 가장 강한 DROP/SURGE, 모든 hard_stops[].t, 그리고 마지막 프레임에서 검사하세요. 실패 시, 가장 저렴한 안전한 수정을 직접 하세요: 문제가 있는 compositions/frames/NN-*.html을 편집하세요. 동기화 문제를 숨기기 위해 지속 시간이나 오디오 타이밍을 변경하지 마세요. 게이트가 통과되면, 사용자 리뷰를 위해 일시 중지하고, 승인 후에만 렌더링하세요 (자율 모드: 한 가지 유지된 질문을 하세요 — "미리보기 먼저, 아니면 렌더링?" — 그런 다음 연락처 시트와 함께 MP4를 전달하세요):
( cd "$PROJECT_DIR" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )
게이트: check가 통과되었고 스냅샷이 검사되었습니다; 사용자가 승인했습니다 (자율형: 검사가 통과되었고 전달에 연락처 시트가 포함됨); renders/video.mp4가 오디오와 함께 존재하며, 지속 시간 == audiomap.audio.duration_sec. 최종 응답은 MP4 경로와 지속 시간을 명시합니다.
재개 테이블
| 가지고 있는 것 | 다음에서 계속 |
|---|---|
| 아무것도 없음, 새 프로젝트 | 0단계 |
BRIEF.md + hyperframes.json | 0단계 (에셋/오디오 확인) |
assets/bgm.mp3까지 있음 | 1단계 |
audiomap.json까지 있음 | 2단계 |
뼈대 STORYBOARD.md까지 있음 | 3단계 |
| 계획이 승인됨까지 있음 | 4단계 |
모든 compositions/frames/까지 있음 | 5단계 |
index.html까지 있음 | 6단계 |
renders/video.mp4까지 있음 | 완료 |
렌더링 실패 디버깅
렌더링이 실패하면 (npx hyperframes render ... 명령이 오류와 함께 실패), 다음을 시도하세요:
- 프레임 파일 확인.
compositions/frames/NN-*.html의 각 파일이 유효한 HTML이고,main진입점을 포함하며, 손상된 링크나 구문 오류가 없는지 확인하세요. 인라인 CSS/JS가 깨지지 않았는지 확인하세요. - 에셋 경로 확인. 템플릿이나 사용자 제공 에셋에 대한 모든 상대 경로가
index.html의 관점에서 올바른지 확인하세요. 프레임 내에서../../public/...와 같은 경로를 사용하는 것은index.html이PROJECT_DIR에 있고 프레임이compositions/frames/에 있기 때문에 올바르지 않을 수 있습니다.assemble-index.mjs가 경로를 재작성한다고 가정하지 마세요. - 하이퍼프레임 설치 확인.
npx hyperframes가 올바른 버전인지 확인하세요. 어떤 이유로 설치가 손상된 경우,npx hyperframes init ...를 다시 실행하세요. - 로그 확인. CLI 출력을 주의 깊게 읽으세요. 특정 오류가 있으면, 이 스킬을 수정하거나 다시 실행하기 전에 오류 메시지를 해결하세요.
- 프레임 재조립. 프레임 파일을 수정한 후,
assemble-index.mjs를 다시 실행하고 다시 렌더링하세요.assemble-index.mjs를 건너뛰지 마세요 — 손상된 상태를 감지합니다.
다음 단계를 시도해도 문제가 지속되면, 프레임 파일의 내용을 다시 확인하고 템플릿 참조가 완전하고 정확한지 확인하세요.