음향 효과 라이브러리
834개 파일 / 63개 카테고리 / 약 1GB. 단일 진입점: sfx 스크립트가 이 SKILL.md 파일과 같은 디렉터리에 있습니다. 스크립트는 자신의 경로를 자동으로 확인하므로 전체 경로로 어디서든 호출할 수 있습니다. 아래 예제에서는 간단히 sfx로 표기합니다.
0단계 — 데이터가 있는지 확인
리포지토리에는 코드와 카탈로그만 포함되어 있습니다. 오디오 파일은 data/ 디렉터리에 있으며, 커밋되지 않습니다.
sfx status
"Chua co du lieu"(데이터 없음)라고 표시되면 데이터를 가져옵니다 — 한 번만, 약 1GB, 다운로드 전에 사용자에게 알립니다:
sfx setup
setup은 다음 순서를 엄격히 따르며 순서를 바꾸지 마십시오:
- Google Drive 우선 — 하나의
.zip파일(약 880MB, 약 1분 소요)을 다운로드하고, sha256을 확인한 후 압축을 풉니다. - 카탈로그에 있는 URL은 백업용입니다 — Drive가 실패한 경우에만 사용합니다(404, 파일이 공개 공유되지 않음, 다운로드 한도 초과, sha256 불일치). 이 경우
setup은 자동으로catalog/source/*.json의 URL로 전환하여 각 파일을 순차적으로 다운로드(약 18분 소요)하고catalog/meta.json의 sha256과 대조합니다.
python3(≥ 3.8)만 필요하며, 추가 설치가 필요하지 않습니다. 중간에 중단되면 sfx setup을 다시 실행하십시오 — 처음부터 다시 다운로드하지 않고 이어서 다운로드합니다. 백업 단계는 느리므로 백그라운드에서 실행하고 사용자에게 예상 시간을 알려주십시오.
사용자가 명시적으로 요청한 경우에만 sfx setup --source를 직접 호출하십시오(Drive 건너뛰기).
setup이 "Ca hai nguon deu that bai"(두 소스 모두 실패)라고 보고하면 sfx doctor를 실행하고 사용자에게 알리십시오 — 다른 오디오 소스를 직접 찾아 대체하지 마십시오.
SFX 찾기 — 기억해야 할 유일한 명령어
sfx find "<검색어>"
한국어(받침 유무 관계없이) 또는 영어로 입력해도 동일한 결과가 나옵니다 — 비교 전에 발음 기호가 제거되며, 각 카테고리에는 미리 준비된 이중 언어 키워드 세트가 있습니다.
sfx find "전환" # 의도 기반 검색
sfx find "알림" --max-dur 2
sfx find whoosh --group transition
sfx find --group impact --max-dur 1.5
sfx find riser --min-dur 3 --max-dur 5
결과에는 길이(초) 가 함께 표시됩니다 — 타임라인에 SFX를 맞출 때 가장 중요한 정보입니다.
| 플래그 | 사용 시기 |
|---|---|
--max-dur N / --min-dur N | 타임라인의 슬롯에 맞게 길이 제한 |
--group <그룹> | 전체 의도 그룹 검색 (아래 그룹 표 참조) |
--category <slug> | 정확한 카테고리를 이미 알고 있을 때 |
--ext wav | wav(또는 mp3)만 가져오기 |
--paths | 파일 경로만 한 줄에 하나씩 출력 — 다른 명령어에 바로 전달 |
--json | 기계 판독 가능 출력, duration, sha256, score 포함 |
--abs | 절대 경로 — 다른 디렉터리에서 sfx를 호출할 때 사용 |
-n N / --all | 결과 개수 (기본값 20) |
여러 단어 쿼리는 기본적으로 AND 연산입니다. 모든 단어와 일치하는 파일이 없으면 자동으로 OR로 전환되며 stderr에 명확히 표시됩니다.
무엇을 사용해야 할지 모르겠다면 → sfx list를 입력하면 전체 카테고리와 "언제 사용하는지" 및 키워드가 출력됩니다.
10가지 의도 기반 그룹
먼저 그룹을 선택한 다음 필터링하십시오 — 카테고리 이름을 추측하는 것보다 빠릅니다.
| 그룹 | 용도 | 대표 카테고리 |
|---|---|---|
transition | 두 장면 연결 | fast-whoosh swoosh-swish whip zoom reverse |
impact | 요점 강조, 데이터 표시 | hit boom impacts slam bass |
ui | 텍스트 표시, 버튼 클릭, 키보드 입력 | pop click typing ui-mini tick shine |
alert | 알림, 리마인더 | notification ding bell alarm |
tension | 클라이맥스 전 긴장감 고조 | riser builder braam tension trailer |
ambience | 장면 아래 깔리는 배경음 | ambience environment |
foley | 실제 물체 소리 | paper doors footsteps liquid draw camera-shutter |
comedy | 유머 | comedy-cartoon memes |
scifi | 기술, 판타지 | technology glitch laser magic data |
horror | 공포 | horror jumpscare |
선택 전에 미리 듣기
슬러그 이름만으로는 파일 소리를 추측하기에 충분하지 않습니다. whoosh-fast-05와 whoosh-fast-06은 느낌이 완전히 다를 수 있습니다.
afplay "$(sfx find whoosh --paths --abs -n 1)" # macOS; Linux: ffplay -nodisp -autoexit
소리를 들을 수 없는 경우(헤드리스 실행)에는 길이와 함께 2~3개의 옵션을 사용자에게 제시하여 선택하게 하고, 직접 결정하여 "적합하다"고 확정하지 마십시오.
SFX를 동영상에 합성하기
sfx mix video.mp4 -o 효과음-추가됨.mp4 \
2.4:fast-whoosh/whoosh-fast-05.wav \
5.0:ding/[email protected]
각 큐는 <초>:<경로>[@볼륨] 형식입니다. 경로는 data/sfx/를 기준으로 하거나, 중복되지 않으면 파일 이름만 적어도 됩니다. 볼륨 기본값은 0.6입니다. ffmpeg가 필요합니다.
- 동영상에 이미 있는 소리는 유지되며 함께 믹싱됩니다, 덮어쓰지 않습니다 —
sfx mix는 보이스오버를 합성한 후에 실행해도 안전합니다. amix=normalize=0+alimiter사용: 큐를 추가해도 원래 소리가 작아지지 않으며, 여러 소스가 겹쳐도 음량이 깨지지 않습니다.--dry-run은 다른 스크립트에 통합해야 할 경우 ffmpeg 명령어를 출력합니다.
HTML에서 제작된 동영상(Playwright/Puppeteer/Remotion 화면 녹화): 페이지 내 <audio> 태그나 new Audio().play()는 브라우저에서 볼 때만 소리가 납니다 — 녹화된 MP4 파일에는 포함되지 않습니다. sfx mix를 사용하여 ffmpeg 단계에서 SFX를 합성하고, 타임라인 애니메이션에서 시간 지점을 가져오십시오.
동영상의 전문적인 사운드를 결정하는 세 가지 요소:
- SFX는 타임라인 슬롯보다 짧아야 합니다 — 나중에 자르는 대신 처음부터
--max-dur로 필터링하십시오. - SFX를 장면 시작이 아닌 움직임의 정확한 프레임에 배치하십시오 — whoosh는 물체가 움직이기 시작하는 정확한 순간에 재생되어야 합니다.
- SFX를 대사 위에 겹치지 마십시오. 보이스오버가 있는 경우
@0.3으로 낮추거나ui-mini카테고리를 사용하십시오.
자주 하는 실수 세 가지
data/를 커밋하지 마십시오 — 약 1GB, gitignore에 포함되어 있으며sfx setup으로 다시 가져옵니다.data/sfx/내의 파일을 수정하지 마십시오. 원본 파일입니다. 자르거나 볼륨을 정규화해야 한다면 다른 위치로 내보내십시오.- 처음 데이터를 가져올 때
sfx download를 직접 호출하지 마십시오. 834개의 개별 파일을 다운로드하며 느리고 백업 경로입니다. 항상sfx setup을 호출하여 Google Drive를 먼저 시도하십시오.
문제가 의심될 때 확인: sfx doctor (도구 + 데이터 소스), sfx verify --hash (각 파일의 sha256 재확인).
라이브러리 유지 관리(카테고리 추가, 재패키징, Drive 링크 변경): README.md를 참조하십시오.