Communitygithub.com

yazzang-homelab/motion-studio

비트 그리드에 맞춰 영화를 스코어링합니다: 트랙을 측정하거나(beats.mjs) 합성하고(score.mjs), 영화에서 SFX를 큐잉하고, 음성을 추가하며, 정확한 길이로 -14 LUFS / -1 dBTP에 믹싱합니다. '음악 추가', '비트에 동기화', 'SFX', '라우드니스'에 사용하세요.

motion-studio란 무엇인가요?

이 Motion Studio 스킬은 코드로 그려진 클립이 실제 영화처럼 느껴지도록 사운드 디자인을 자동화합니다. 사용자가 제공한 오디오 트랙의 BPM, 비트, 다운비트, 히트를 측정하거나(beats.mjs) 네 가지 스타일(펄스, 피아노, 미니멀, 시네마틱) 중 하나로 완전히 새로운 음악을 합성합니다(score.mjs). 영화 제작자(공장)와 장면 그리기 함수 모두에서 그리드 API(ctx.grid 및 c.grid)를 통해 비트 그리드를 노출하므로, 장면 전환은 다운비트에, SFX는 비트에, 악센트는 측정된 히트에 맞춰 정확히 배치할 수 있습니다. 또한, 큐 시스템은 영화 정의 내에서 시각적 이벤트와 함께 선언되므로, 싱크가 절대 어긋나지 않습니다(cues: (grid) => ...). 사전 녹음된 샘플을 지원하며, 선택적으로 ElevenLabs 음성을 합성하고, 두 패스 라우드니스 노멀라이제이션 및 오버샘플링된 리미터를 사용하여 통합 -14 LUFS 및 -1 dBTP 트루 피크를 목표로 최종 믹스를 만듭니다. 또한, 리믹스 감지(측정된 그리드 vs 합성 그리드) 및 싱크 정밀도 분석을 위한 메트릭 분석을 포함합니다.

지원 대상✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/yazzang-homelab/motion-studio/tree/HEAD/skills/sound-design

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

사운드 디자인 (코스 스텝 09)

사운드는 코드로 그려진 클립이 영화처럼 느껴지기 시작하는 지점입니다. 하나의 타임라인이 세 개의 레인을 구동합니다: 다운비트는 장면 전환을, 비트는 SFX를, 측정된 온셋 피크는 악센트를 정확히 배치합니다. 두 가지 경로가 있습니다: 사용자가 트랙을 제공하면 측정하여 변경하지 않고 사용하고, 그렇지 않으면 픽처와 동일한 그리드에 원본 음악을 합성합니다.

영화 프로젝트 루트에서 작업하세요. 인수는 한 번만 표시됩니다:

믹싱 세부 사항은 ${CLAUDE_SKILL_DIR}/references/mixing.md (references/mixing.md)에 있습니다.

1. 음악: 측정 또는 합성

상황명령어결과
사용자가 트랙을 제공함npm run beats -- audio/track.wav (ffmpeg가 디코딩하는 모든 형식)측정된 bpm, beats, downbeats, hits를 가진 audio/beats.json
템포가 모호함 (절반 또는 두 배)npm run beats -- audio/track.wav --bpm-hint 120힌트 쪽으로 치우친 템포 검색 (30 ~ 300). 힌트가 없으면 JS 엔진이 70 ~ 180 BPM을 검색하므로 60 BPM 트랙은 120으로 읽힘; 힌트가 있으면 검색 범위가 넓어짐 (45, 60, 65, 200, 250 힌트는 실제 템포를 찾음)
Python / librosa 없음npm run beats -- audio/track.wav --engine js내장 JS 분석 (스펙트럴 플럭스, 자기상관, 비트 트래킹). --engine auto(기본값)는 자체적으로 대체되며, MOTION_PYTHON이 깨진 인터프리터를 가리킬 때도 마찬가지임 (MOTION_PYTHON=... is not usable을 기록하고 계속 진행); --engine librosa는 해당 메시지와 함께 중단됨
트랙 없음: 합성npm run score -- --style pulse --bpm 120 --dur 12audio/music.wav + 분석용 audio/beats.json (source grid)

제공된 트랙의 경우, studio.json audio.music을 해당 경로(예: "audio/track.wav")로 설정하고 bpm을 측정된 값으로 설정하세요. 그런 다음 평범하게 npm run score를 실행하지 마십시오: 이 명령어는 audio.music에 쓰고(트랙을 덮어씀) beats.json을 합성 그리드로 대체합니다. npm run build는 안전한데, score.mjs --if-missing을 호출하여 제공되거나 대체된 트랙을 유지하기 때문입니다(해시가 audio/music.meta.json과 일치하지 않음). 사용자가 트랙을 사용할 권리(라이선스 또는 소유권)가 있는지 확인하고 docs/production.json 노트에 기록하세요.

Score 옵션 (node tools/score.mjs):

플래그값참고
--stylepulse (킥 4/4, 박수, 하이햇, 서브 베이스, 플럭 아르페지오) · piano (펠트 피아노, 드문 퍼커션) · minimal (틱, 클릭, 소프트 킥; UI 영화) · cinematic (태고 같은 히트, 보우 오스티나토, 다운비트 붐)어떤 스타일에도 정적 제네릭 패드는 없음
--bpm, --dur숫자studio.json의 기본값
--key, --modeA, F#, Bb ... (뒤에 m은 단조 의미), minor / major단조 i-VI-III-VII, 장조 I-V-vi-IV
--drop BAR마디 인덱스기본값은 길이의 약 40%, 라이저가 드롭으로 이어짐
--loop플래그매끄러운 루프: 인트로나 엔딩 없음, 드롭 없음, 테일이 시작 부분으로 감김; studio.json loop의 기본값. 정수 마디 수의 지속 시간을 사용하거나, 도구가 이음새가 다운비트를 놓친다고 경고함
--seed N정수동일한 시드, 동일한 바이트
--if-missing플래그npm run build에서 사용: 제공된 트랙이거나 설정이 여전히 audio/music.meta.json과 일치하는 기존 WAV를 유지하고; score.mjs가 만들었지만 duration, bpm, style, key, mode, seed, loop 또는 drop bar가 변경된 경우(WAV, beats.json, 사이드카) 재생성하고, 변경된 사항을 말함(JSON에서 regenerated)

모든 실행은 또한 audio/music.meta.json(해결된 설정 및 WAV의 sha256)을 기록합니다. 이것이 --if-missing이 사용자가 제공하거나 대체한 트랙에서 만든 점수를 식별하는 방법이며, 이 점수는 절대 건드리지 않습니다.

선택적 studio.json audio 키는 플래그가 없을 때(플래그가 우선함) 동일한 옵션을 채웁니다: style (템플릿은 "pulse"를 제공), key, mode, seed; voiceId는 voice.mjs의 기본 ElevenLabs 음성입니다. 예: "audio": { "style": "cinematic", "key": "D", "mode": "minor", "seed": 7 }.

네 가지 스타일은 pulse, piano, minimal 및 cinematic입니다. 편곡은 드문 마디로 시작하여, 빌드업하고, 다운비트에서 드롭하고, 영화가 끝나기 최소 0.5초 전에 끝나는 마지막 다운비트에 마지막 히트를 안착시킨 후 디케이 테일로 끝납니다; --loop를 사용하면 대신 자기 자신으로 접히는 꾸준한 그루브입니다. 길이는 정확히 영화 길이입니다.

beats.json 참고: 결과는 audio/.cache/에 오디오의 sha256으로 캐시되므로 동일한 오디오에 대한 재실행은 즉시 이루어집니다(--no-cache로 강제 실행). Librosa는 콜드 스타트가 있습니다: 새로운 Python 환경에서 첫 번째 실행은 약 1분이 걸리고(numba 컴파일), 이후 실행은 빠릅니다. 그 1분을 멈춤으로 읽지 마십시오; --engine js는 Python을 건너뜁니다. 다운비트는 저대역 온셋에서 네 가지 비트 위상을 점수화하여 선택하는데, 이는 곡이 픽업으로 시작할 때 "매 4번째 비트"가 한 비트씩 어긋나기 때문입니다. 무음은 경고와 함께 빈 비트 목록을 제공합니다; 페이지는 그런 다음 BPM 그리드로 대체됩니다.

2. 그리드 위의 픽처

영화는 그리드를 ctx.grid (공장) 및 c.grid (장면 그리기)로 받습니다. audio/beats.json이 존재할 때 측정되고, 그렇지 않으면 studio.json bpm에서 균일합니다.

호출반환값
grid.beat(n)비트 n의 시간 (분수 n 허용: beat(4.5)는 8분음표만큼 늦음)
grid.bar(n)다운비트 n의 시간 (마디 시작)
grid.index(t) / grid.nearest(t)t에서의 비트 인덱스 / 가장 가까운 비트의 시간
grid.beatsIn(a, b) / grid.barsIn(a, b)[a, b) 내의 비트 또는 마디 시간
grid.isOnBeat(t, tol = 0.02)t가 비트에서 tol 초 이내인지 여부
grid.hits측정된 악센트 피크(초 단위): 고정, 정렬, 중복 제거, [0, duration) 내; 트랙에 없으면 []
grid.hitsIn(a, b)[a, b) 내의 히트, beatsIn과 동일한 윈도우

규칙: 장면 전환 및 상태 변경은 다운비트(grid.bar(n))에서; UI 액션, 팝 및 클릭은 비트에서; 트랙이 제공될 때 큰 악센트는 측정된 히트에서 수행하십시오. 모든 시간을 그리드에서 파생시키십시오; 그리드가 제공할 수 있는 시간을 직접 입력하지 마십시오. 그렇지 않으면 트랙이나 템포가 변경될 때 픽처가 표류합니다. 측정된 트랙의 경우 grid.bar(0)는 첫 번째 측정된 다운비트이며, 이는 0초 이후(픽업 또는 인트로)에 있을 수 있으므로 마디로 작성된 스팬은 함께 이동합니다.

측정된 히트(온셋 피크, audio/beats.json의 hits)는 공장(ctx.grid)과 모든 장면 그리기(c.grid)에서 grid.hits 및 grid.hitsIn(a, b)로 영화에 도달합니다. 트랙에 추적된 비트가 없어도 사용할 수 있습니다. 직접 audio/beats.json을 가져오지 마십시오; 그리드가 이미 이를 전달합니다:

// 공장의 큐에서: 8초에서 10초 사이의 측정된 악센트
cues: (grid) => [...grid.hitsIn(8, 10).map((t) => ({ t, type: 'snap', gain: 0.5 }))],

합성된 점수는 메인 악센트만 hits에 기록합니다(예: 드롭 및 최종 히트).

3. 큐는 영화에서 나온다

큐를 그들이 속한 픽처 옆, 공장의 cues(그리드의 배열 또는 함수)에 선언하십시오:

export default defineFilm((ctx) => ({
  scenes: [/* ... */],
  cues: (grid) => [
    ...[0, 1, 2, 3, 4].map((n) => ({ t: grid.bar(n), type: 'thump' })),       // 다운비트에서 장면 변경
    { t: grid.bar(1), type: 'whoosh', gain: 0.6 },                             // 장면 2로 전환: 피크가 컷에 안착
    { t: grid.beat(6), type: 'click', pan: 0.2 },                              // 비트에서 커서 누르기
    ...[0, 1, 2, 3, 4, 5, 6, 7].map((i) => ({ t: grid.beat(8) + i * 0.06, type: 'pop', gain: 0.5, pitch: 1 + i * 0.03 })),
    { t: grid.bar(4), type: 'riser' },                                         // 라이저가 큐에서 시작 ...
    { t: grid.bar(5), type: 'hit' },                                           // ... 다음 히트/텀프/스냅에 도착
  ],
}));

큐 필드: t (초), type, gain (1), pan (-1 ~ 1, 0), pitch (재생 속도 배율, 1). sfx를 type으로, vol을 gain으로 대체 가능합니다. 음수 또는 무한 시간의 큐는 삭제됩니다. 타입 (SFX_TYPES): click tick pop thump whoosh swoosh riser hit chime type glitch snap.

앵커 의미: t는 샘플이 시작되는 위치가 아니라 사운드가 안착하는 순간입니다. node tools/sfx.mjs --list는 각 음성을 길이와 앵커와 함께 인쇄합니다.

타입t에 안착하는 것용도
click, tick, pop, thump, hit, chime, type, snap과도 현상 (사운드는 몇 밀리초 먼저 시작됨)시각적 이벤트: 누르기, 진입, 잠금
glitch첫 번째 조각: t에서 시작디지털 브레이크, 나타나는 프레임에
whoosh, swoosh통과 피크 (사운드 내 0.31초 및 0.20초), 따라서 스윕이 t 전에 빌드업그것이 전달하는 컷 또는 움직임에 배치
riser아무것도 안착하지 않음: t에서 시작하여 0.4초에서 4초 후의 다음 hit, thump 또는 snap 큐로 팽창하여 해당 임팩트에 도착; 범위 내에 그러한 큐가 없으면 1.6초 지속임팩트보다 한 마디 또는 한 비트 앞에 배치하고, 절대 임팩트 위에 배치하지 마십시오

hit과 동시에 있는 라이저는 착륙 큐를 찾지 못하고(0.35초 이상 늦은 큐가 필요함) 임팩트로 이어지지 않고 1.6초 더 실행됩니다. 라이저 큐를 더 일찍, grid.bar(n)의 히트에 대해 grid.bar(n - 1)에 배치하십시오.

위의 타일 예제와 같은 계단식 팝은 의도적인 오프비트 큐입니다; 동기화 메트릭이 이를 나열하지만, 각각이 시각적 이벤트에 위치하는 한 괜찮습니다.

4. SFX

npm run sfx                         # 영화를 헤드리스로 열고, __studio.cues()를 읽고, audio/cues.json + audio/sfx.wav를 씁니다
node tools/sfx.mjs --dump-cues      # audio/cues.json만 씁니다 (합성 전 시간 확인)
node tools/sfx.mjs --cues my.json   # 영화 대신 손으로 편집한 큐 파일에서 합성합니다

모든 음성은 결정론적으로 합성되며(큐 타입, 시간 및 동일한 타입의 큐 중 순위, 그리고 --seed에서 파생된 큐별 시드, 따라서 다른 큐를 추가, 제거 또는 재정렬해도 이 큐의 사운드는 변경되지 않음), 등전력으로 패닝되고, 플로트 버스에서 합산되며, -1 dBFS로 제한되고, 파일은 정확히 영화 길이입니다(빈 큐는 해당 길이의 무음을 제공함; 루프 영화에서는 끝을 지난 테일이 시작 부분으로 접힘). 대신 녹음된 샘플을 사용하려면 프로젝트에 audio/samples/<type>.wav (.flac, .mp3, .ogg도 가능)를 넣으십시오: 해당 타입의 합성된 음성을 대체합니다(--samples none 또는 --no-samples는 한 번 실행 동안 폴더를 무시함). 파일의 가장 큰 피크가 앵커이며, 샘플링된 라이저는 이 피크가 도착 시간에 안착하도록 시간이 맞춰집니다. 샘플에는 상업적 사용 라이선스가 필요합니다: 자신의 녹음, CC0, 또는 게시된 영화에 대해 보유한 라이선스. 저작자 표시 전용 라이선스(CC BY)는 포스트에 크레딧이 필요합니다; 비상업용 및 "개인용" 팩은 제외됩니다. 출처와 라이선스를 docs/production.json 노트에 기록하십시오.

5. 음성 (선택 사항, ElevenLabs)

  1. 키는 .env에 ELEVENLABS_API_KEY=...로 넣습니다 (프롬프트, 커밋하는 파일 또는 스크린샷에 절대 넣지 마십시오). 이름으로 참조하십시오: "ElevenLabs 키는 .env의 ELEVENLABS_API_KEY입니다".
  2. audio/voice.json을 작성하십시오: [{ "t": 0.5, "text": "Driftnote를 만나보세요." }, { "t": 4.0, "text": "스스로 파일링하는 노트." }] (선택적 줄별 voiceId). 줄을 다운비트에 배치하고 픽처가 이를 위한 공간을 남겨두십시오.
  3. node tools/voice.mjs --dry-run은 계획과 문자 수를 인쇄합니다(네트워크 없음, 비용 없음). 예산이 중요한 경우 사용자에게 보여주십시오. 이전 줄과 동일한 텍스트, 음성 ID 및 모델을 가진 줄은 한 번 합성되고 한 번 청구됩니다(드라이 런은 이를 repeat으로 표시함; billableChars는 고유 문자만 계산함).
  4. node tools/voice.mjs --voice-id <id>는 합성하고(줄별로 audio/.cache/에 캐시됨), 각 줄을 해당 t에 배치하고 정확한 영화 길이로 audio/voice.wav를 씁니다.
  5. voice.mjs가 파일을 쓴 후 studio.json audio.voice를 "audio/voice.wav"로 설정하십시오(voice.mjs는 알림을 인쇄하지만 studio.json을 편집하지는 않음). audio.voice가 null인 동안 믹스는 음성을 무시합니다; 설정되면 mix.mjs는 음성 아래에서 음악을 덕킹합니다(duck: true). audio.voiceId는 자체 voiceId가 없는 줄의 기본 음성입니다.

6. 믹스 및 검증

npm run mix                                   # 모든 형식: out/score.wav + out/<fmt>/final.mp4 + out/final.mp4
node tools/critique.mjs --format 9x16 --video out/9x16/final.mp4    # out/review/9x16/video/의 증거

mix는 40~80초가 걸립니다: 영화가 길거나 머신이 바쁠 때는 백그라운드에서 시작하고 로그를 폴링하십시오(절대 약 2분 이상 포그라운드에서 기다리지 마십시오).

믹싱 전에, mix.mjs는 모든 스템을 디코딩하고 측정합니다. 영화보다 0.25초 이상 짧거나, 비어 있거나, 무음인(피크가 -80 dBFS 미만) 음악, 음성 또는 sfx 스템은 refusing to mix: ... stem problem(s) do not fit the N s film으로 믹스를 중단하고 아무것도 쓰지 않습니다: 이전 길이의 오래된 music.wav가 무음 테일로 믹스되곤 했습니다. 스템을 재생성하십시오(npm run score, npm run sfx, npm run voice); 짧아야 하는 보이스오버 또는 징글의 경우 --allow-short-stems를 전달하십시오(누락된 부분은 무음). 무음 sfx 스템은 경고만 하는데, 큐가 없는 영화는 무음을 렌더링하기 때문입니다; 영화보다 긴 스템은 끝이 페이드 없이 잘린다고 경고합니다. JSON 결과는 stemInfo(스템당 디코딩된 길이 및 피크)를 전달합니다.

목표: 통합 -14 LUFS +-0.5, 트루 피크가 -1 dBTP 이하, 오디오 길이가 비디오 길이와 같음(절대 -shortest 아님). --lufs (또는 audio.lufs)는 -70 ~ -5여야 하고, --tp (또는 audio.truePeak)는 -20 ~ 0이어야 합니다; -9 dBTP 미만에서는 리미터 경로가 천장을 적용하고, 낮은 천장에서 라우드니스에 도달할 수 없는 피크가 많은 믹스는 충돌 대신 master misses the target 경고로 끝납니다. mix.mjs는 두 패스 loudnorm을 사용하고 마스터가 목표 공차의 절반 이내(기본적으로 +-0.25 LU)에 있을 때만 선형 결과를 유지합니다; 그렇지 않으면 +-0.1 LU를 목표로 하는 오버샘플링된 리미터와 함께 게인으로 대체한 다음 믹스된 AAC를 다시 측정합니다. 숫자가 벗어났을 때 references/mixing.md의 보고 표는 무엇을 변경해야 하는지 알려줍니다.

동기화 확인: metrics check, 리믹스 감지, 싱크 정밀도 분석.

7. 메트릭, 리믹스, 싱크

npm run metrics

메트릭은 metrics.json을 작성하며, 이는 audio/beats.json 그리드와 영화에서 렌더링된 큐 간의 정렬을 분석합니다:

  • 각 큐의 nearestBeat (가장 가까운 그리드 비트까지의 시간)
  • syncRatio (그리드 비트와 정렬된 큐의 비율)
  • offBeatCues (임계값을 벗어난 큐 목록)
  • remix (true인 경우) 소스가 grid인지 measure인지 및 BPM 차이를 나타냄

npm run remix는 동일한 오디오 파일을 사용하지만 새 그리드(예: BPM 변경 후)로 믹스를 재생성합니다. 이는 audio/music.wav를 다시 인코딩하지 않고 beats.json과 큐만 다시 계산합니다.

싱크 정밀도: --sync-precision 0.01 플래그를 sfx 또는 mix에 전달하여 큐를 지정된 공차(초)로 비트에 스냅합니다. 기본값은 0.02초입니다.


참조

자세한 내용은 references/mixing.md를 참조하십시오.


이 문서는 Motion Studio 사운드 디자인 스킬의 일부입니다.

Individual skills in this repo

This repo contains 11 individual skills — each has its own dedicated page.

yazzang-homelab/motion-studio

Make Claude watch its own frames: critique.mjs evidence, harsh 7-axis scores, timestamped P0/P1/P2 problems in docs/review_log.md, fix the 3 worst, re-check, pass the gate. Use for 'critique it', 'review the frames', 'is it good'.

yazzang-homelab/motion-studio

Plan long-form or overnight films: director's brief (PLAN FIRST or GO, budget, definition of done), ANIMATION_GUIDE + STORYBOARD, chapter subagents, gates, chunked render. Use for 'overnight film', 'music video', '2-minute film'.

yazzang-homelab/motion-studio

Make a launch video, app or product reel, explainer or motion ad from code, end to end: brand assets from a URL, beat-grid shot list, synced sound, critique loop, all formats. Default for new video requests; not footage edits.

yazzang-homelab/motion-studio

Brand-asset stage of a product film (motion-reel runs the whole film): capture real screenshots, logo, colors and fonts from a URL, never redraw UI; brand story beats; voice + mascot. Use to grab or fix a brand's assets.

yazzang-homelab/motion-studio

Turn a reference (a frame, a video or an image library) into docs/style_guide.md and a beat-grid shot list: measure cuts, palette and pace, take grammar not content, wait for OK. Use when the user supplies or names a look.

yazzang-homelab/motion-studio

Build, debug or speed up the seek(t) render engine: render contract, canvas vs page capture, workers/subframes/chunks, determinism fixes, Remotion or HyperFrames handoff. Use for 'render is slow', 'frames differ', 'use Remotion'.

yazzang-homelab/motion-studio

Ship every format from one timeline, then package it: layout() reframing (never crop), render all formats, per-format checks, deliver.mjs, a brand skill, a service offer. Use for 'export 9:16 and 16:9', 'deliver', 'make a skill'.

yazzang-homelab/motion-studio

The viral one-line 'showreel for a résumé' prompt: why it works (anatomy), the credited quote, and seeded variants that avoid look-alike reels; runs it as an engine test. Use for that prompt, its variations, or a showreel.

yazzang-homelab/motion-studio

Make motion feel physical with closed-form springs from lib/motion.js: presets, springFromFeel, track() for multi-target values, loopTrack loops, indicators, text swaps. Use for 'feels linear', 'add bounce', 'easing to springs'.

yazzang-homelab/motion-studio

Scaffold a motion-studio film project (seek(t) renderer, springs, beat grid, synthesized sound, critique tools), install it, set up the browser, run doctor. Use for 'set up the motion studio', 'new film project', 'init studio'.

yazzang-homelab/motion-studio

Write a six-part XML state spec for a one-shape UI morph film (inputs, direction, structure, build, gotchas, start): states on downbeats, cursor-driven changes, seamless loop, approval gate. Use for 'UI morph', 'state list'.

관련 스킬