음악→비디오 — 하나의 음악 기반, 비트 동기화 비디오 워크플로
이 스킬은 음악 트랙을 비트에 동기화된 HyperFrames 비디오로 변환합니다. 트랙을 한 번 분석하고, 프레임을 배치하며, 각 프레임에 대한 계획을 채우고, 각 프레임을 컴포지션으로 빌드합니다. 입력은 음악 트랙과 사용자가 제공한 선택적 이미지 또는 비디오입니다. 내레이션이나 웹사이트 캡처는 없습니다. 타이포그래피와 템플릿이 기본 바탕입니다(완전한 비디오를 위해 별도의 에셋이 필요하지 않음). 사용자가 제공한 미디어는 동일한 비트 그리드에서 편집됩니다.
당신은 오케스트레이터입니다. videos/<project>/ 디렉토리에서 작업합니다. 단계를 순서대로 실행하고 각 게이트를 통과한 후 다음 단계로 넘어가세요. 두 단계는 사용자와의 상호작용이 필요합니다: 3단계(계획 승인)와 6단계(렌더링 승인). 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 프로젝트를 생성하며, 사용자가 제공한 미디어를 기록합니다.
음악이 중추입니다. 다른 모든 것보다 먼저 하나의 트랙을 설정하십시오. 이 스킬은 빠르고 에너지 넘치는 BGM에 최적화되어 있습니다. 강한 비트 그리드가 컷을 주도합니다(잔잔한 트랙도 작동하지만, 비트보다는 구절에 따라 진행하십시오). 사용자가 오디오(음악 파일 또는 비디오에서 추출할 오디오)를 제공했다면 그것을 사용하십시오. 그렇지 않으면 하나를 생성하십시오. 사용자의 설명에서 분위기를 선택하고(예: "드라이빙 신스웨이브", "트랩 비트", "밝은 기업 음악") /hyperframes-media (references/bgm.md — HeyGen 검색(자격 증명이 있는 경우), 로컬 Lyria/MusicGen; ElevenLabs 또는 다른 생성기도 작동)를 통해 트랙을 생성하십시오. 생성하기 전에 npx hyperframes auth status를 실행하고 출력물을 그대로 전달하십시오(의역하거나 다시 작성하지 마십시오) — BGM이 HeyGen에서 오는지 로컬 MusicGen에서 오는지, 그리고 로그인되어 있지 않으면 로그인 방법을 보여줍니다. 로그인되어 있지 않으면 중단하고 사용자가 선택할 때까지 기다리십시오 — 로그인하거나 로컬 MusicGen으로 오프라인에서 계속하십시오 — 트랙을 생성하기 전에; 저장소별 .env에 키를 작성하지 마십시오. (자율 모드에서는 상태를 기록하고 오프라인에서 계속하십시오.) /hyperframes-media → Preflight에서 표준 지침을 확인하십시오. 어느 쪽이든 트랙은 assets/bgm.mp3에 저장됩니다. 사용자가 제공한 이미지나 비디오를 준비하여 프레임이 비트 그리드에 통합할 수 있도록 하십시오. 그렇지 않으면 타이포그래피가 전체 비디오를 구성합니다.
hyperframes.json이 누락된 경우에만 초기화합니다. <project> 이름은 브리핑에서 케밥 표기법으로 지정하십시오(예: midnight-drive-loop). 타임스탬프를 사용하지 마십시오. init는 설치된 스킬을 GitHub의 최신 스킬과 비교하여 오래된 것이 있으면 전역 세트를 업데이트합니다.
npx hyperframes init "videos/<project>" --non-interactive --example=blank
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단계에서 내리는 결정입니다.
전제 조건: librosa, numpy, soundfile이 설치된 Python 3. 가져오기에 실패하면 분석기를 실행하기 전에 활성 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, 롤의 가장자리, 온셋이 없는 구간, 큰 에너지 점프)에서 트랙을 프레임으로 자르고, 모든 경계를 오디오맵 앵커에 맞추십시오. 각 프레임에 대해 span_sec, pacing(1단계의 신뢰 호출에 따른 판결 — 그리드가 실제일 때 beat_cut, 잔잔한 음악에 부과된 메트로놈일 때 phrase_flow), mood, 한 줄짜리 feel(3단계에서 템플릿과 일치시키는 일반 음악 상황)을 설정하십시오. 여기서는 분류하고 배치만 하십시오. 각 프레임의 ### Groups는 TBD (3단계)로 남겨두고, frontmatter 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에 복사하고, frontmatterstyle(글꼴 + ≤4–6 스와치 팔레트)을 채우십시오. - 모든 프레임을 채우십시오. 그룹을 결정하고 각각에 처리를 제공하십시오: 카탈로그의 일치하는 템플릿(바인딩된 매개변수와 실제 오디오맵 앵커 포함), 프리미티브 카탈로그의 자유 구성, 또는
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)를 수정하십시오. 경고는 최선의 노력입니다. 그런 다음 사용자에게 프레임별 요약을 보여주고 승인할 때까지 반복하십시오.
게이트: 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를 실행하십시오. 이것이 올바른 단위입니다(프레임별 작업자는 실행할 수 없었습니다). lint는 구조를 확인하고, validate는 헤드리스 Chrome을 실행하며(JS 오류 및 누락된 에셋을 포착), inspect는 프레임을 스냅샷합니다.
( cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes validate . && npx hyperframes inspect . )
t=0, 각 프레임 시작, 가장 강한 DROP/SURGE, 모든 hard_stops[].t, 마지막 프레임에서 검사하십시오. 실패 시 가장 저렴하고 안전한 수정을 직접 수행하십시오: 문제가 있는 compositions/frames/NN-*.html을 편집하십시오. 동기화 문제를 숨기기 위해 지속 시간이나 오디오 타이밍을 변경하지 마십시오. 게이트가 통과하면 사용자 검토를 위해 일시 중지한 다음 승인 시에만 렌더링하십시오:
( cd "$PROJECT_DIR" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )
게이트: lint / validate / inspect가 통과했습니다. 사용자가 승인했습니다. renders/video.mp4가 오디오와 함께 존재하며 지속 시간 == audiomap.audio.duration_sec입니다. 최종 응답은 MP4 경로와 지속 시간을 명시합니다.
재개 테이블
| 보유한 파일 | 다음 단계부터 계속 |
|---|---|
assets/bgm.mp3만 | 1단계 |
audiomap.json | 2단계 |
STORYBOARD.md (뼈대) | 3단계 |
STORYBOARD.md (완료) | 4단계 |
| 모든 프레임 파일 | 5단계 |
index.html | 6단계 |
빠른 참조
형식: 기본값은 가로 1920x1080입니다. 세로 1080x1920. 정사각형 1080x1080. 스토리보드 frontmatter에서 캔버스를 한 번 설정하십시오(canvas: { w, h, fps }).
스크립트는 scripts/ 아래에 있습니다: analyze-beatgrid.py(하나의 분석기), validate-plan.mjs(계획 검사), assemble-index.mjs(인덱스 조립), stage-assets.mjs(사용자 미디어 준비), lib/storyboard.mjs(벤더된 파서). 그 외 모든 것은 hyperframes CLI입니다.
| 읽을 문서 | 언제 |
|---|---|
references/frame-skeleton.md | 2단계: 음악 읽기, 프레임 배치, 페이싱 설정 |
references/planning.md · storyboard-format.md | 3단계: 브랜드 선택, 각 프레임 채우기, 계획 작성 |
references/template-catalog.md | 3단계: 그룹당 템플릿 선택 |
references/motion-primitive-catalog.md | 3단계: 자유형 모션 프리미티브 선택 |
references/montage.md | 3단계: 사용자 제공 에셋이 있는 경우에만 |
references/design-spec.md | 3단계: 프리셋 표에서 브랜드(글꼴 + 색상) 선택 |
sub-agents/frame-worker.md | 4단계: frame-worker 파견 |
../hyperframes-core/references/subagent-dispatch.md | 4단계: 서브 에이전트 파견 규칙 |
../hyperframes-core/references/sub-compositions.md | 4단계: 서브 컴포지션 계약 |
../hyperframes-core/references/determinism-rules.md | 4단계: 결정론적 프레임 빌드 규칙 |