먼저, 이 스킬을 최신 상태로 유지하세요 — 실행 전 사용자에게 확인:
npx hyperframes skills update music-to-video. 모든 것이 최신 상태면 빠른 no-op입니다. 그렇지 않으면 이 스킬과 의존하는 핵심 도메인 스킬을 갱신합니다.
music-to-video — 음악 기반 비트 싱크 비디오 워크플로
이 스킬은 음악 트랙을 비트에 맞춘 HyperFrames 비디오로 변환합니다. 한 번 트랙을 분석하고, 프레임을 배치하며, 프레임별 계획을 작성하고, 각 프레임을 구성으로 빌드합니다. 입력은 음악 트랙과 선택적 사용자 이미지/비디오이며, 내레이션이나 웹사이트 캡처는 없습니다. 타이포그래피와 템플릿이 기본입니다(완전한 비디오에 별도 에셋 불필요). 사용자가 제공한 미디어는 동일한 비트 그리드 위에 자르기됩니다.
당신은 오케스트레이터입니다. videos/<project>/ 디렉토리에서 작업합니다. 단계를 순서대로 실행하고 각 게이트를 통과한 후에 다음 단계로 넘어가세요. 두 단계에서 사용자 필요: Step 3(계획 승인)과 Step 6(렌더 승인) — 이는 ../hyperframes/references/brief-contract.md(Step 0 전에 읽으세요)에 정의된 체크포인트 게이트입니다. 자율 모드에서는 요약을 공지로 게시하고 기다리지 않고 진행합니다. Step 4를 제외한 모든 단계를 직접 수행하고, Step 4에서는 프레임당 하나의 서브 에이전트를 파견합니다. 디자인 및 모션 규칙은 이 파일 외부(references/ 및 frame-worker 서브 에이전트)에 보관합니다.
SKILL_DIR = 이 스킬 디렉토리. PROJECT_DIR = videos/<project-name>/.
워크플로: Step 0 설정 → hyperframes.json + assets/bgm.mp3; Step 1 분석 → audiomap.json; Step 2 스켈레톤 → STORYBOARD.md(프레임, 그룹 TBD); Step 3 계획 → 완전한 STORYBOARD.md + frame.md; Step 4 빌드 → compositions/frames/NN-*.html; Step 5 어셈블 → index.html; Step 6 렌더 → renders/video.mp4.
모든 것을 결정하는 두 가지 아이디어
- 하나의 분석기, 그리고 이를 신뢰하세요.
analyze-beatgrid.py가 유일한 비트 분석기입니다 — 다른 도구나 귀로 비트를 다시 측정하지 마세요. 에너지/밀도/롤/온셋/침묵은 항상 신뢰할 수 있습니다.bpm과beats_sec은 음악이 진정한 리듬감을 가질 때만 신뢰할 수 있습니다. 조용한 음악에서는 그리드가 임시로 부과된 메트로놈이므로, 대신 프레이즈와 에너지로 페이싱하고 절대 하드 컷하지 마세요. 어느 경우인지 결정하는 것은 각 프레임의pacing(Step 2)입니다. - 하나의 프레임 = 하나의 파일; 그룹은 내부에 있습니다. Step 2는 트랙을 프레임으로 자르고, 각 프레임은 하나의
compositions/frames/NN-<frame_id>.html파일이 됩니다(하나의 frame-worker로 빌드). 프레임은 그룹(템플릿 또는 모션 프리미티브 조합)으로 세분화될 수 있습니다. 추가 밀도는 그룹 내부에 위치하므로, 프레임 수는 비트가 아닌 개별 처리 수를 추적합니다 — 빠른 트랙에서도 서브 에이전트 수가 폭발하지 않습니다.
Step 0: 설정, BGM, 입력
목표: 음악 소스 설정, HyperFrames 프로젝트 생성, 사용자 제공 미디어 기록.
브리프는 의도 레이어에서 시작합니다. 다음 규칙을 순서대로 적용: (1) BRIEF.md 존재 → 읽고 답변된 내용은 묻지 않음. flow/storyboard가 모드를 결정합니다(브리프 계약 § 1). (2) BRIEF.md 없지만 프로젝트 존재 → 디스크 상태에서 재개; 재질문 금지. (3) 현재 요청이 직접 여기로 온 신규 생성 요청 → /hyperframes를 읽고 의도 레이어 실행(references/intent-interview.md): 이 루트의 필수 사항(음악 소스, 목적지 → 종횡비)을 확인하고, 위임된 사항(브랜드와 장르는 Step 3에서 선택)을 공지합니다. init 직후 BRIEF.md 작성(절대 그 전에 하지 마세요 — init은 비어 있지 않은 디렉토리를 거부함). 수정 요청은 모두 생략.
음악이 핵심입니다 — 다른 것보다 먼저 하나의 트랙을 설정하세요. 이 스킬은 빠르고 에너지가 높은 BGM에 최적화되어 있습니다: 강한 비트 그리드가 컷을 주도합니다(조용한 트랙도 작동하지만 프레이즈 단위로 페이싱). 사용자가 오디오(음악 파일 또는 오디오 추출 가능한 비디오)를 제공했다면 사용하세요. 그렇지 않으면 요청에서 무드를 선택하고 /media-use를 통해 트랙 생성(references/bgm.md 참조). 첫 번째 인증된 제공자 작업 전에 npx hyperframes auth status를 실행하고 결과를 그대로 전달. 로그아웃 상태라면 두 가지 분기:
- 협업: 로그인 또는 로컬 제공자로 오프라인 계속할지 명시적 선택 대기.
- 자율: 상태를 알리고 사용 가능한 로컬 제공자로 계속 진행.
오프라인 제공자가 필요한 음악 기능을 충족할 수 없으면 장벽을 표면화. 절대 저장소별 .env에 키를 기록하지 마세요. 인증 소유권 및 오프라인 대체는 /media-use references/setup-providers.md § Providers에 있음. 결과 트랙은 assets/bgm.mp3에 저장. 제공된 이미지/비디오를 준비하여 프레임이 비트 그리드에서 사용할 수 있게 하고, 그렇지 않으면 타이포그래피가 비디오를 대체.
리릭 비디오: 보컬에 동기화된 가사가 필요하면 /media-use를 통해 트랙을 전사하여 단어/라인 타임을 얻거나, 사용자에게 가사 텍스트를 요청하여 비트 그리드에 배치.
hyperframes.json이 없을 때만 초기화. 프로젝트 이름 <project>는 브리프에서 kebab-case로 작성(예: 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
브랜드(폰트 + 팔레트)는 Step 3에서 선택, 여기서는 안 됨. 장르나 트랙 유형을 미리 선택하지 마세요 — 에셋은 선택적 재료일 뿐이며, 장르는 프레임별 선택에서 자연스럽게 나타납니다.
게이트: hyperframes.json + assets/bgm.mp3 존재; 종횡비/길이/fps 및 (있는 경우) 에셋 목록 기록 완료.
Step 1: 음악 분석
목표: 전체 비디오의 기반이 되는 유일한 타이밍 분석 결과 생성.
analyze-beatgrid.py가 유일한 비트 분석기 — 다른 도구나 귀로 비트를 다시 측정하지 마세요. 트랙을 한 번 읽고 audiomap.json을 작성: 에너지 단계(레벨/밀도/느낌), 온셋 + onset_rate, 롤, 침묵, hard_stops, key_moments, 프레이즈, 템포/그리드, audio.duration_sec. 결정론적 — 같은 파일은 항상 같은 맵을 제공. 대부분 필드는 모든 음악에서 신뢰 가능; bpm과 beats_sec은 음악이 진정한 리듬감을 가질 때만 신뢰 가능, 이 판단은 Step 2에서 결정.
전제 조건: Python 3와 librosa, numpy, soundfile 필요. import 실패 시 분석기 실행 전 활성 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 확인.
Step 2: 프레임 스켈레톤 (구조만)
목표: 음악을 읽고 프레임 배치 — STORYBOARD.md의 스켈레톤.
references/frame-skeleton.md를 읽으세요. audiomap.json을 STORYBOARD.md의 스켈레톤으로 직접 변환 — 중간 JSON 없음. 실제 음악 변화(hard_stops, SURGE/DROP key_moments, 롤의 경계, 온셋이 없는 구간, 큰 에너지 점프)에서 트랙을 프레임으로 자르고, 모든 경계를 audiomap 앵커에 스냅. 각 프레임에 대해 span_sec, pacing(Step 1의 신뢰 판단 결과 — 그리드가 실제면 beat_cut, 조용한 음악에 부과된 메트로놈이면 phrase_flow), mood, 한 줄 feel(Step 3에서 템플릿과 일치시키는 음악 상황) 설정. 여기서는 분류와 배치만 수행: 각 프레임의 ### Groups는 TBD (Step 3)으로 남기고, frontmatter style은 비워 두기 — 템플릿, 카피, 색상, 폰트 없음. 약 1~6개 프레임 예상.
게이트: 프레임이 트랙을 완전히 덮음(첫 번째 0부터 마지막 duration_s까지); 각각 span_sec + pacing + mood + feel 포함; 모든 ### Groups는 TBD; 콘텐츠 없음.
Step 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에 수정 없이 복사하고 frontmatterstyle(폰트 + ≤4–6 스와치 팔레트)을 채움. - 각 프레임 채우기. 그룹을 결정하고 각각에 하나의 처리를 할당: 카탈로그에서 일치하는 템플릿(바운드 파라미터와 실제 audiomap 앵커 포함), 프리미티브 카탈로그의 자유 구성, 또는
pacing을 따르는 에셋 처리. 명명된 룩을 자유 구성하기 전에 라이브 카탈로그에서 검색: 사용자가 요청한 모든 룩, 효과, 처리, 전환(예: "CRT 스캔라인", "글리치", "필름 그레인", "샤이머 스윕")에 대해npx hyperframes catalog --query "<룩, 일반 영어로>" --json을 실행하고 상위 결과 읽기.template-catalog.md와motion-primitive-catalog.md는 이 스킬의 로컬 자료만 나열; 검색은 전체 호스티드 레지스트리(~400 블록 및 컴포넌트)를 순위화하며, 설치 필요 없음 — 프로젝트, 이전add, 계정 불필요. 검색 결과 적합한 것이 없을 때만 자유 구성. 카피 작성. WHAT(템플릿/프리미티브 + 콘텐츠 + 앵커)을 소유; HOW는 frame-worker가 소유 — 절대 스토리보드에 밀리초 트윈 작성 금지.
node <SKILL_DIR>/scripts/validate-plan.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--audiomap "$PROJECT_DIR/audiomap.json" --templates <SKILL_DIR>/references/templates
모든 ✗ 수정(심각한 오류: 기간 불일치, 프레임이 트랙을 덮지 않음, src 누락); 경고는 최선의 노력. 그런 다음 프레임별 요약을 제안으로 채팅에 게시(../hyperframes/references/review-loop.md § 1)하고 사용자 답변에 따라 승인될 때까지 반복; storyboard: yes의 경우 storyboard.html로도 작성(../hyperframes-creative/references/storyboard-recipe.md § 3)하여 사용자가 열 수 있도록. 자율 모드에서는 이는 체크포인트 게이트: 요약을 공지로 게시하고 진행(validate-plan.mjs 통과는 품질 게이트이며 여전히 차단).
게이트: frame.md가 그대로의 프리셋 복사본; validate-plan.mjs가 0으로 종료; 사용자가 계획 승인(자율: 요약이 공지로 게시됨).
Step 4: 계획에서 프레임 빌드
목표: 각 프레임을 독립적인 구성 파일로 빌드.
compositions/frames/ 생성. sub-agents/frame-worker.md와 ../hyperframes/references/subagent-dispatch.md 읽기. 프레임당 하나의 frame-worker를 가능하면 병렬로(또는 물결 모양) 파견. 각 워커는 정확히 하나의 프레임과 다음 컨텍스트를 받음:
PROJECT_DIR: <절대 경로>
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를 실행하지 않음 — 해당 명령은 어셈블된 프로젝트에서 작동하며 아직 존재하지 않으므로 잘못된 파일을 보고할 것. 워커는 계약에 따라 파일을 작성하고 중지; 어셈블 후 확인(Step 6). 각 워커가 반환될 때 파일이 디스크에 있는지 확인.
게이트: 모든 프레임이 compositions/frames/NN-*.html 파일로 디스크에 존재.
Step 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"
보고된 ✗ 수정 — 누락되거나 빈 프레임 파일은 워커가 부분 파일을 작성했음을 의미; 재파견(Step 4) 후 재어셈블.
게이트: index.html 존재; 총 길이 == audiomap.audio.duration_sec.
Step 6: 확인 및 렌더
목표: 어셈블된 비디오 확인, 사용자 승인 획득, 최종 MP4 렌더링.
어셈블된 프로젝트에서 CLI 실행 — 이것이 올바른 단위(프레임별 워커는 실행 불가). check는 구조 린트와 헤드리스 브라우저 런타임, 레이아웃, 모션, 대비 게이트를 한 번에 수행; --snapshots는 리뷰 프레임도 출력.
( cd "$PROJECT_DIR" && npx hyperframes check . --snapshots )
t=0, 각 프레임 시작, 가장 강한 DROP/SURGE, 모든 hard_stops[].t에서 검사...