/minara-music — 스크립트에서 음악 + 사운드 효과 생성
비디오의 초 단위 스크립트를 음악 큐 시트(cues.json)로 변환한 후, BGM과 화면 동기화 사운드 효과를 로컬에서 합성합니다. 합성은 순수 로컬 numpy로 이루어지며, 출력은 결정론적입니다(동일한 큐 + 시드는 항상 동일한 오디오를 생성). 외부 서비스를 호출하지 않으며 비용이 들지 않습니다.
출처: Minara V2 런칭 영화의 스코어링 접근 방식을 일반화하여 재사용 가능한 스크립트로 만든 것입니다. examples/v2-launch.json이 해당 영화의 큐 시트입니다.
워크플로 (순서대로)
- 스크립트 읽기: minara-video(또는 스토리보드/내레이션 타임라인 시트)에서 초 단위 스크립트를 가져옵니다. 스크립트에 "사운드 분위기" 또는 "음악" 열이 있으면 따르고, 없으면 화면 분위기로 판단합니다.
- 큐 시트 작성: 프로젝트의
audio-src/cues.json에 다음을 작성합니다:duration(= 최종 비디오 길이),bpm(기본값 120),key(기본값A minor; 밝거나 축하하는 곡은C major사용 가능),seed.sections: 스크립트를 음악 섹션으로 자르고, 각 섹션에 하나의energy를 선택하고,note를 사용하여 일치하는 화면을 설명합니다(쉬운 상호 참조를 위해).sfx: 스크립트의 각 보이는 동작(탭, 타이핑, 주문 완료, 알림 팝업, 전환, 잠금 착륙)에 대해 스크립트에 제공된 초 단위로 시간이 지정된 하나의 사운드 효과를 추가합니다.
- 렌더링 전에 운영자에게 시트를 먼저 보여주기: 마크다운 테이블로 "시간 범위 / 에너지 / 일치하는 화면" 및 "SFX 시간 / 유형 / 일치하는 동작"을 나열하고, 운영자가 확인(OK)을 말할 때까지 기다립니다. 운영자는 코드가 아닌 시트를 편집합니다.
- 렌더링:
python3 ~/.claude/skills/minara-music/scripts/make_music.py <project>/audio-src/cues.json -o <project>/assets [--vo <project>/assets/vo.wav] - 자체 점검: 스크립트가 각 섹션을 출력합니다. 그런 다음 섹션별로 음량을 측정하여 클라이맥스가 가장 크고, 브레이크다운/아웃트로가 명확히 줄어들며, 덕킹이 제대로 작동하는지 확인합니다. 청취 문제(너무 복잡함, 사운드 효과가 주의를 빼앗는 경우)가 있으면
level/gain을 조정하고 재렌더링합니다. 각 렌더링은 몇 초가 소요됩니다. - 전달:
bgm.wav(또는bgm-duck.wav)의 경로를 제공하고,open -R을 사용하여preview-mix.wav를 강조 표시하여 운영자가 들을 수 있도록 합니다. HyperFrames에서는 오디오 트랙으로 추가하고, 내레이션은 별도 트랙에 둡니다.
출력
| 파일 | 내용 |
|---|---|
bgm.wav | 음악 + 사운드 효과, 48kHz 스테레오, -1dBFS 피크, 시작 부분 0.4초 페이드인, 끝 부분 3.2초 페이드아웃 |
bgm-duck.wav | 내레이션이 있을 때 생성됨: 음성이 있는 곳에서 음악이 duck_db(기본값 -8dB)만큼 낮아짐; 사운드 효과는 덕킹되지 않음 |
preview-mix.wav | 내레이션이 있을 때 생성됨: 음악 + 내레이션이 혼합된 파일로, 청취용이며 최종 비디오용이 아님 |
에너지 섹션 유형
| 에너지 | 사운드 | 사용처 |
|---|---|---|
silent | 음악 없음 | 완전한 침묵이 필요한 일시 중지 |
intro | 낮은 드론 + 부드러운 패드 | 오프닝, 로고, 데이터 수렴 |
light | 패드 + 가벼운 아르페지오 + 드문 비트 | 모바일 상호작용, 가벼운 기능 데모 |
build | 모든 비트에 베이스와 킥 추가, 섹션 끝에 자동 라이저 | 주요 순간으로 이어지는 점진적 빌드업 |
full | 전체 드럼 키트 + 클랩 + 베이스 + 아르페지오 | 핵심 기능(백테스팅, 실시간 전환, 자동화) 지속적 시연 |
breakdown | 드럼과 베이스 제거, 패드와 부드러운 아르페지오만 남김; 마지막 마디에 킥 복귀 | 장면 전환, "숨 쉴" 필요가 있는 보안/개인정보 섹션 |
climax | 가장 풍부함: 전체 드럼 키트 + 리드 멜로디 + 섹션 시작 부분의 크래쉬; 이전 섹션이 build가 아니면 자동으로 라이저 추가 | 제품 이름 / 런칭 클레임 등장 |
outro | 토닉 코드 + 브랜드 벨로 해결, 전체 믹스와 함께 페이드아웃 | 엔드 카드, CTA |
각 섹션은 볼륨을 미세 조정하기 위해 "level": 0.5–1.3을 사용할 수 있습니다. 코드는 글로벌 바(단조: i–VI–III–VII, 장조: I–V–vi–IV)를 따르므로 섹션 간에 깨지지 않습니다.
사운드 효과 유형 (SFX)
| 유형 | 사운드 | 일반적인 동작 | 선택적 매개변수 |
|---|---|---|---|
tap | 짧은 클릭 | 버튼 탭, 선택 | gain |
typing | 연속 타이핑 틱 | 입력 필드에 타이핑 | chars, cps (초당 문자 수, 화면 타이핑 속도와 일치) |
success | 두 개의 상승하는 벨 톤 | 주문 완료, 전략 실행 | gain |
notify | 세 음 알림 | 알림 또는 미리 알림 팝업 | gain |
bell | 단일 벨 톤 | 아바타/로고 등장 | note (MIDI, 기본값 81) |
blips | 위로 상승하는 짧은 톤 | 백테스트 진행, 데이터 로딩 | count, step (초), note |
sparkle | 반짝이는 그레인 + 숨결 소음 | 입자 수렴, 오프닝 | dur |
riser | 상승하는 노이즈 | 수동으로 추가된 전환 빌드업 | dur |
whoosh | 역방향 스윕 | 창 축소, 푸시/풀 전환 | dur |
thud | 낮은 잠금 소리 | 잠금, 확인, 무거운 착륙 | gain |
crash | 심벌즈 | 추가 악센트 | gain |
모든 사운드 효과는 gain을 사용하여 볼륨을 조정할 수 있습니다.
규칙
- 사운드 효과는 보이는 동작만 따릅니다: 화면에 일치하는 동작이 없으면 사운드 효과를 추가하지 마십시오. 이는 "텍스트를 함부로 추가하지 마라"와 같습니다.
- 스크립트에서 타이밍을 복사하고 추정하지 마십시오: SFX
t는 초 단위 스크립트/애니메이션 타임라인의 실제 초를 사용합니다. 타이핑의cps는 애니메이션의 타이핑 속도를 사용합니다. - 스크립트의 길이나 순서가 변경되면 먼저
cues.json을 업데이트하고 재렌더링하십시오. 오디오를 수동으로 늘리지 마십시오. - 외부 AI 음악 서비스나 웹에서 다운로드한 트랙을 사용하지 마십시오. 상업적으로 라이선스된 음악이 필요한 경우 운영자가 파일을 제공합니다.