sound (완전판)
비디오에 사운드를 입히는 완전한 도구 체인, 세 가지 기능 라인:
- 효과음 선정 — 다중 소스 검색, 인간 피드백 신호 기반 필터링, 다운로드, 측정.
- BGM (배경 음악) — 두 가지 경로: 오프라인 합성으로 무한 반복 음악 생성, 또는 소재 라이브러리에서 장시간 오디오 검색.
- 보컬 및 믹싱 — 노이즈 제거/EQ/디에서/컴프레션, 사이드체인 덕킹, 정적 믹싱, 이중 패스 음량 노멀라이제이션.
환경은 Python 3 + FFmpeg (ffmpeg / ffprobe가 PATH에 있어야 함)만 필요합니다. 순수 표준 라이브러리, 타사 패키지, API 키, 로그인 불필요.
이 스킬의 모든 기능은 이 저장소에서 오픈소스로 구현되었습니다 (MIT 라이선스): 모든 명령, 규칙, 매개변수는 아래 문서와 references/에 있으며 자유롭게 수정 및 배포할 수 있습니다.
설치 후 실제 위치에 따라 변수를 설정합니다. 아래는 프로젝트 내 설치를 기준으로 한 표기입니다:
S=.claude/skills/sound/scripts/sfx.py # 검색 / 다운로드 / 분석
V=.claude/skills/sound/scripts/vocal.py # 보컬 / 믹싱
C=.claude/skills/sound/scripts/compose.py # 오프라인 BGM 합성
전역 설치 시 .claude/skills/sound/를 ~/.claude/skills/sound/로 바꿉니다.
1. 효과음 선정
워크플로우
- 화면 동작을 영어 키워드로 변환합니다 ("카드 날아들기" →
short whoosh, "스위치 전환" →soft click). all로 여러 소스에서 후보를 검색하고, 필요시 단일 소스로 추가 검색합니다.--urls는 사용자에게 청취 링크를 제공합니다.- 먼저 화면과의 부합 여부를 판단한 다음 인기도를 확인합니다. 후보와 추천 근거를 제시하고, 숫자를 "내가 들어봤다"로 오해하지 마세요.
- 용도에 따라 라이선스를 결정하고 다운로드한 후
analyze로 길이와 에너지 분포를 확인합니다. - 전달 시 출처 URL, 저자, 라이선스를 보존합니다. CC0가 아닌 경우 저작자 표시를 추가합니다.
python3 $S all "short whoosh" --license cc0 -n 10 --urls
python3 $S freesound "paper slide" --license by -n 5 --sort short
python3 $S commons "bell" -n 5 --json
python3 $S mixkit "whoosh" -n 5
python3 $S kenney "impact" -n 5
python3 $S get sfx/ fs:167563 wm:131079817 mk:1489
python3 $S analyze sfx/*.mp3 --loudness --silence --json
선정 규칙 (인간 피드백 신호 활용)
- 평점 수 > 평균 평점:
★4.4(380)이★4.9(6)보다 더 강력한 증거입니다. - 업로더 설명이 청취 결과와 가장 일치: "built-in mic" / "made with my mouth"는 저음질을 의미합니다. 녹음기(Zoom, Sound Devices)를 명시하고 명확한 음원("cork from a wine bottle")을 언급하면 통제 가능함을 의미합니다. 설명의 음원이 화면과 맞지 않으면 아무리 인기 있어도 폐기합니다.
- 인기도가 부합을 의미하지는 않음: 가장 많이 다운로드된 "thud"가 3초짜리 영화 저음 폭음일 수 있습니다. 반드시 길이를 확인하고
analyze로 에너지가 어디에 있는지, 꼬리가 얼마나 긴지 확인한 후 잘라낼지 결정합니다. - 먼저 후보를 제시하고 다운로드: 사용자가 청취를 원하면
--urls를 추가하세요. 미리 결정하지 마세요. - 사용 가능한 신호는 소스에 따라 다름: Freesound는 다운로드 수와 평점 수가 있습니다. Commons는 실제 길이와 라이선스가 있습니다. Mixkit은 길이는 있지만 인기도는 없습니다. Kenney는 전체 팩 자료입니다. 누락된 필드를 0점으로 취급하지 마세요.
라이선스 규칙 (엄격한 등급, 완화 금지)
| 매개변수 | 허용 | 일반 용도 |
|---|---|---|
--license cc0 | CC0 / PDM만 | 상업용, 저작자 표시 불필요 |
--license by | CC0 / PDM / BY / BY-SA | 저작자 표시 가능 (BY-NC, BY-NC-SA, BY-ND 제외됨) |
--license any | 모두, 그러나 결과에 라이선스 표시 | 후보만 보고 싶을 때 |
- BY-NC는 상업용으로 절대 사용 금지, 스크립트가
cc0/by에서 이미 제외했습니다.any에서는 직접 판단해야 합니다. - Mixkit은 자체 "Mixkit Free License"(실제로 상업용 및 저작자 표시 불필요)를 사용하지만 CC0/BY 태그 체계에 속하지 않으므로
cc0/by에서 제외됩니다. 필요시 명시적으로--license any를 사용하고 전달물에 라이선스 이름을 명시하세요. - CC0가 아닌 소재는
get이 저자와 라이선스 정보를 출력합니다. 이것은 단서일 뿐이며, 전달 시 출처와 라이선스 원문을 보존해야 합니다. - Kenney는 모두 CC0이지만 전체 zip 패키지로 다운로드되며, 단일 효과음이 아니므로 직접 압축을 풀어 파일을 선택해야 합니다.
음원 분담
| 소스 | 강점 | 한계 |
|---|---|---|
| Freesound | 다운로드 수/평점 수가 유일함 | 미리보기 MP3만 다운로드 가능, 원본 파일 아님; 단일 연결 약 80 KB/s |
| Wikimedia Commons | 실제 길이 + 라이선스 필드 완전, 환경 녹음/종소리/장시간 오디오 | 파일 설명 기반 매칭, 키워드가 이상하면 검색 안 됨; 인기도 없음 |
| Mixkit | 상업용 저작자 표시 불필요, UI 효과음 품질 안정적 | 페이지 구조 파싱 필요; 인기도 없음; 길이는 정수 초 단위 |
| Kenney | CC0 게임/UI 효과음 패키지 | 전체 zip 패키지, 개별 길이 없음 |
자세한 가져오기 방식과 라이선스 태그 매핑은 references/sources.md를 참조하세요.
2. BGM: 합성 또는 배경
먼저 사용자가 원하는 것이 "음악이 있는 것"인지 "감정에 맞는 곡을 배치하는 것"인지 판단합니다:
| 시나리오 | 경로 | 명령 |
|---|---|---|
| 무한 반복 가능, 종속성 없음, 감정 제어 가능, 저작권 위험 없음 | 오프라인 합성 | compose.py |
| 실제 악기/보컬/환경 분위기 필요 | 검색 배경 | sfx.py music |
| 짧은 BGM을 가지고 화면을 채우고 싶음 | 반복/자르기 | vocal.py loop / trim |
오프라인 합성 (첫 번째 선택, 실제로 "BGM 합성"에 해당)
python3 $C bgm.wav --style ambient --duration 30 --bpm 90 --key Am
python3 $C bgm.wav --style lofi --duration 30 --bpm 85 --key C
python3 $C bgm.wav --style upbeat --duration 30 --bpm 120 --key G
ambient: 느린 패드(베이스 화음), 드럼 없음, 해설/제품 시연에 적합.lofi: 디튠 코러스 + 느슨한 kick/hat + 테이프 노이즈.upbeat: 밝고 짧은 화음 + 4비트 베이스 드럼 + 베이스 라인.- 출력은 44.1 kHz / 16-bit / 스테레오 WAV, 시작과 끝 위상 정렬 + 화음 링 크로스페이드로 무한 반복 가능.
- 길이는 가장 가까운 정수 마디로 맞춰집니다 (예: 30s @ 90 BPM 실제 29.333s). 정확한 초가 필요하면 4박자로 나누어 떨어지는 BPM(예: 120)을 사용하세요.
- 스크립트는 **바로 붙여넣을 수 있는
--bgm-gain권장값(dB 단위)**을 출력하며,vocal.py매개변수와 일치하므로 바로 사용할 수 있습니다. --seed는 동일한 매개변수로 완전히 동일한 출력을 보장하여 버전 관리에 용이합니다.
검색 배경
python3 $S music "ambient" --duration long --max-seconds 600 -n 8 --urls --json
python3 $S get bgm/ wm:123456
python3 $V trim bgm/xxx.ogg bed.wav --start 0 --end 30
music은 Commons의filetype:audio검색을 사용합니다.--duration long은 기본적으로 30초 이상이며, 알 수 없는 길이는 기본적으로 제외됩니다 (허용하려면--allow-unknown추가).- Commons는 종종 시간 단위의 현장 녹음/오디오북을 반환하므로, 배경으로 사용할 때는 반드시
--max-seconds 600을 추가해야 합니다. 그렇지 않으면 수백 MB를 다운로드할 수 있습니다. - 긴 오디오는 다운로드 후 일반적으로
trim으로 한 부분을 잘라내거나,loop로 짧은 부분을 화면 길이에 맞춰 채웁니다.
3. 보컬 정리 및 믹싱
표준 체인
# 1. 보컬: 노이즈 제거 → 하이패스 → (디에서) → 컴프레션 → 이중 패스 음량 노멀라이제이션 → 페이드 인/아웃
python3 $V clean voice.wav clean.wav --deesser
# 기본 목표 -16 LUFS; 노멀라이제이션을 원하지 않으면 --no-loudnorm 추가
# 2. BGM을 화면 길이에 맞춤 (둘 중 하나 선택)
python3 $V loop bgm.wav bed.wav --duration 30 # 짧은 소재를 채우고, 이음새 진정한 크로스페이드
python3 $V trim bgm.wav bed.wav --start 0 --end 30
# 3. 믹싱: 말하는 동안 자동으로 BGM 낮춤 (사이드체인 덕킹)
python3 $V duck clean.wav bed.wav mixed.wav --bgm-gain -12 --threshold -30 --ratio 8
# 보컬 없음/순수 분위기일 경우 정적 믹싱으로 변경
python3 $V mix bed.wav clean.wav mixed.wav --bgm-gain -18
# 4. 최종 음량 확인 / 노멀라이제이션
python3 $V report mixed.wav
python3 $V loudnorm mixed.wav final.wav --target-lufs -16
매개변수 규칙
| 매개변수 | 기본값 | 변경 시기 |
|---|---|---|
--bgm-gain | duck -12 / mix -18 dB | compose.py가 출력한 권장값 사용. BGM이 보컬을 덮으면 3~6 dB 더 낮춤 |
--threshold | -30 dB | 사이드체인 임계값은 레벨 임계값이며 음성 감지가 아님. 보컬이 매우 작으면 -36으로, BGM이 매우 크면 높임 |
--ratio | 8 | 덕킹이 너무 뚜렷하거나 호흡감이 강하면 4로 낮춤 |
--target-lufs | -16 LUFS | 나레이션/비디오는 -16, 순수 음악 스트리밍은 -14, 팟캐스트는 -16까지 가능 |
--true-peak | -1.5 dBTP | 플랫폼에 명확한 상한이 있으면 해당 상한으로 변경 |
--fade | duck 0.3 / clean 0.05 초 | 도입/종료, 반복 이음새 |
- 단위 혼동 금지:
I는 LUFS (통합 음량),TP는 dBTP (실제 피크),LRA는 LU (음량 범위).mean_volume은 dBFS 평균 레벨이며,report에서 명확히 표시되므로 LUFS로 착각해서는 안 됩니다. duck/mix두 경로 모두apad(무음 채움)를 추가하고duration=longest를 사용하므로, BGM이 보컬보다 짧아도 잘리지 않습니다.--duration으로 완성된 길이를 지정할 수 있습니다.clean의 두 번 loudnorm 측정은 전체 전처리 체인 이후에 실행되며, 측정 단계의 I/TP/LRA가 두 번째 단계와 완전히 일치합니다. 페이드 인/아웃은 loudnorm 이전에 위치하여 측정 신호와 노멀라이제이션 입력이 동일하도록 보장합니다. 그렇지 않으면measured_*가 일치하지 않습니다.loudnorm내부 측정 규격은ebur128과 약 1 LU 정도 차이가 날 수 있습니다. 스크립트는 완성 후 폐쇄 루프 검증을 수행하고 추가 게인을 보정하며, 요약에 '폐쇄 루프 보정 ±X.X dB'를 출력합니다. 이는 정확한 목표 달성을 위한 필수 단계이므로 삭제하지 마세요.- 매우 짧거나 거의 무음인 소재는 유효한 LUFS를 측정할 수 없는 경우 자동으로 단일 패스 loudnorm으로 대체되며, 출력에 '단일 패스'라고 명시됩니다. 이 경우 폐쇄 루프는 자동으로 건너뛰며, 무음에 게인을 과도하게 추가하지 않습니다.
필터 체인 원문, 이중 패스 loudnorm 원리 및 조정 표는 references/mixing.md를 참조하세요.
4. 자주 사용하는 레시피
A. 30초 제품 시연 (완전 오프라인, 소재 불필요)
python3 $C bgm.wav --style ambient --duration 30 --bpm 120 --key Am
python3 $V clean voice.wav clean.wav --deesser
python3 $V duck clean.wav bgm.wav mixed.wav --bgm-gain -13
python3 $V loudnorm mixed.wav final.wav --target-lufs -16
python3 $S all "soft whoosh" --license cc0 -n 6 --urls
B. 기존 더빙에 실제 분위기 배경 추가
python3 $S music "rain ambience" --duration long --max-seconds 600 --license by -n 6 --urls
python3 $S get bgm/ wm:xxx
python3 $V trim bgm/xxx bed.wav --start 10 --end 40
python3 $V clean voice.wav clean.wav
python3 $V duck clean.wav bed.wav mixed.wav --bgm-gain -18
C. 전환 효과음 하나만 필요, 상업용 가능해야 함
python3 $S all "paper slide" --license cc0 -n 8 --sort short --urls
python3 $S get sfx/ fs:xxx
python3 $S analyze sfx/*.mp3 --loudness --silence --json
D. 화면에 맞춘 볼륨 엔벨로프 (Remotion 렌더링)
완성 마스터링은 위의 FFmpeg 체인을 사용합니다. 프레임별 페이드 인/아웃/비트 맞춤 볼륨 변경은 Remotion 렌더링 단계에서 수행합니다. references/remotion-audio.md를 참조하세요.