사운드 디자인 스킬은(는) 무엇을 하나요?

sound-design <command> ... --json (pip install -e .로 설치, Python >= 3.9, stdlib 전용). --json을 사용하면 표준 출력(stdout)은 정확히 하나의 JSON 문서(ASCII 전용)를 포함합니다. 프로빙, 커팅, 조인 및 라우드니스는 ffmpeg-skill을 통해 처리되며, --ffmpeg-skill DIR, $SOUND_DESIGN_FFMPEG_SKILL_DIR, $VIDEO_AGENT_FFMPEG_SKILL_DIR, ~/.claude/skills/ffmpeg-skill, ./vendor/ffmpeg-skill 또는 ../ffmpeg-skill 순서로 찾습니다. sound-design doctor --json은 각 엔진이 OK, MISSING 또는 INCOMPATIBLE인지, 컴퓨팅 장치와 GPU 메모리, 각 엔진 설치 방법을 알려줍니다. 절대 아무것도 다운로드하지 않습니다.

작업	명령어
60초 음악 배경	`sound-design generate-bgm --prompt "고요한 피아노 배경" --tags "ambient,70 bpm" --duration 60 -o bed.wav --seed 42 --json` (10-600 초)
15초 가사 비디오용 120 BPM 배경음악과 비트 그리드	`sound-design generate-bgm --prompt "경쾌한 팝" --duration 15 --bpm 120 --time-signature 4 -o pv.wav --json` (16초 = 8마디가 됩니다; `pv.beats.json`이 함께 생성됨)
동일, 가사 포함 / CPU 사용	`--lyrics lyrics.txt` / `--device cpu` 추가 (기본값은 기악, `--device auto`)
더 큰 4B XL 모델 사용 (옵트인, GPU 20 GB 이상 필요)	`sound-design generate-bgm --prompt "시네마틱 현악" --duration 60 -o bed.wav --model acestep-v15-xl-turbo --json` ("BGM 모델 선택" 참조)
음향 효과 (사용자 동의 후, 아래 참조)	`sound-design generate-sfx --prompt "나무 문이 닫힌다" --tags "실내" --duration 3 -o door.wav --seed 7 --acknowledge-ezaudio-training-data --json` (정수 초, 1-10)
사용자 파일을 라이브러리에 추가	`sound-design library-import track.wav --library ./sounds --licence CC-BY-4.0 --credit "Music: name" --kind bgm --tags piano --mood calm --loopable --json`
다운로드한 스톡 트랙과 라이선스 정보 추가	`sound-design library-import track.mp3 --library ./sounds --licence CC-BY-4.0 --title "Morning Light" --author "Aiko Tanaka" --licence-url https://creativecommons.org/licenses/by/4.0/ --licence-file LICENSE.txt --provider Freesound --kind bgm --json` (출처가 제공하는 경우 `--attribution "<line>"` 추가, 출처가 명시한 경우에만 `--content-id registered` 추가)
라이브러리 내용 확인 (라이선스 및 길이)	`sound-design library-index ./sounds --loudness --json`
60초에 맞게 조정된 라이브러리 트랙	`sound-design library-pick ./sounds --kind bgm --tags piano --duration 60 -o bed.wav --json` (트랙 이름 지정 시 `--file <path>` 추가, 루프용 `--crossfade 0.5` 추가)
배경음악의 8초 매끄러운 루프 (편집 시 루프용)	`sound-design loop-bed bed.wav -o loop.wav --duration 8 --search 1 --json` (소스는 최소 duration + crossfade 길이여야 함; 루프 지점은 `--search` 초 내에서 검색됨)
0.5초 지점의 컷에 피크가 맞춰진 1초 후잉(whoosh) 효과	`sound-design stinger whoosh.wav -o stinger.wav --duration 1 --peak-at 0.5 --type whoosh --json`
루프 파일의 이음새 확인	`sound-design seam-check loop-x10.wav --period 8 --json` (또는 `--seams 8,16`; 이음새 실패 시 종료 코드 1)
컷 및 강조 캡션에 효과 적용 (MIX용 큐 시트)	`sound-design sfx-cues --cuts 1.0,2.5,4.75 --emphasis 3.2 --library ./sounds --min-spacing 0.25 -o cues.json --json` (컷=whoosh, 강조=pop, 단 `--effect cut=<name>`으로 지정 가능; 생성된 효과의 경우 `--file ding=ding.wav`)
동일, 30초 내 파일 재사용 금지, 밝은 팝	`sound-design sfx-cues --cuts 1.0,12.0,25.0 --emphasis 3.2 --library ./sounds --min-reuse-spacing 30 --character pop=bright -o cues.json --json` (둘 다 옵트인; 아래 참조)
설치된 항목 확인	`sound-design doctor --json`, `sound-design engines --json`
이 스킬이 선언하는 내용	`sound-design contract --json` (별칭 `skill --json`)

모든 명령은 --timeout S와 --ffmpeg-skill DIR을 받습니다; 파일을 쓰는 명령은 --overwrite를 받습니다 (기존 출력이 있으면 이 옵션 없이 거부됨); 생성기(generator)는 또한 --seed (생략 시 랜덤 생성 및 기록)와 --offline을 받습니다. 출력은 새로운 .wav 파일입니다; 입력은 절대 수정되지 않으며, 출력은 ffmpeg-skill probe가 확인한 후에야 전체 또는 전혀 생성되지 않습니다.

사용 시기

사용자에게 알려진 라이선스가 있는 음악 또는 효과가 있는 경우 (구매한 팩, 의뢰 제작 트랙, CC0 / CC BY): 라이브러리 모드를 먼저 사용합니다. 각 파일을 라이선스와 함께 library-import 한 후, 각 장면에 대해 library-pick을 사용합니다. 엔진이 실행되지 않으며 AI 생성(ai_generated: false)이 아닙니다.
라이브러리에 적합한 항목이 없는 경우: doctor에서 엔진이 OK 상태임을 보여주면 generate-bgm (ACE-Step) 또는 generate-sfx (EzAudio)를 사용합니다.
그런 다음 항상 WAV 파일과 그 provenance를 audio-production-skill MIX에 전달합니다. MIX는 이를 배치하고, 음성 아래에서 덕킹하며, 라우드니스를 설정합니다. 이 스킬은 믹싱, 덕킹 또는 노멀라이제이션을 수행하지 않습니다.

루프 및 스팅어

loop-bed 및 stinger는 엔진을 실행하지 않습니다. 이미 가지고 있는 WAV(generate-bgm, generate-sfx 또는 library-pick 결과, 또는 사용자 파일)를 가져와 ffmpeg-skill만을 통해 편집하고 결과를 측정합니다; 라이선스와 엔진은 소스의 자체 provenance에 남아 있으므로 둘 다 전달하십시오.
루프의 끝은 시작 부분으로 이어지며 클릭이 없습니다: 크로스페이드 없이 끝에서 끝으로 반복합니다. 결과는 찾은 루프 길이(loop.length, --duration의 --search 이내), 크로스페이드된 자료의 유사도(loop.similarity, 0.5 미만이면 경고) 및 측정된 랩(seam)을 보고합니다. 정수 마디의 루프가 가장 잘 맞습니다.
스팅어는 정확히 --duration 길이이며, 가장 큰 10ms는 --peak-at의 10ms 이내(양 끝에서 최소 20ms)에 있어야 합니다. 그렇지 않으면 아무것도 쓰지 않습니다. MIX에 컷 --peak-at 초 전에 시작하도록 지시하십시오.
seam-check는 이 스킬 자체의 루프 확인입니다: 클릭(±1ms), 레벨, 각 면의 1초 옥타브 밴드 스펙트럼을 확인합니다. qc-skill에는 아직 루프 이음새 확인 기능이 없습니다.

음향 효과 큐 시트

sfx-cues는 아무것도 배치하거나 결정하지 않습니다: 시간은 호출자(편집의 컷 리스트 및 강조 캡션에서 가져옴)가 제공하며, 시간당 하나의 큐가 생성됩니다. 마지막으로 유지된 큐보다 --min-spacing보다 가까운 시간은 드롭되고 (이유와 함께 dropped 아래에 나열됨), 절대 이동되지 않습니다. 강조 시간을 임의로 생성하지 마십시오.
각 큐는 어떤 파일(file, from: 라이브러리 또는 명명된 WAV, source: 라이선스를 포함한 sources 아래의 항목), 시작 위치(start, 0 이전에 시작하면 file_offset), --level dBFS에 도달하기 위한 gain_db, 그리고 시간에 맞추어지는 것이 피크(whoosh, rise 등)인지 시작점(pop, ding 등)인지를 명시합니다. 라이브러리 효과는 선언된 라이선스가 필요하며, 효과 이름을 태그로 사용하여 library-pick처럼 선택됩니다. 시트를 소스의 라이선스와 함께 audio-production-skill MIX에 전달하십시오.
동일한 파일 재사용 (옵트인, 기본 꺼짐). --min-reuse-spacing S: 효과가 S초 미만 전에 유지된 큐와 동일한 파일(동일한 SHA-256)을 재생하려는 경우, 해당 효과에 대해 순위 순서로 다음 라이브러리 파일을 사용합니다(첫 번째 순위 파일이 사용 가능할 때마다 사용, 절대 랜덤하지 않음). 자격이 되는 다른 파일이 없거나 --file 효과의 경우, 이벤트는 드롭됩니다(dropped[].by: min_reuse_spacing), 절대 이동되지 않으며 다른 효과가 주어지지 않습니다. substitutions와 각 큐의 substituted는 어떤 파일이 무엇을 대체했는지 나타냅니다. --min-spacing 확인이 먼저 수행되며, 드롭된 이벤트는 두 규칙 모두에 대해 계산되지 않습니다. 제안: 말하는 사람 편집(head edit)의 경우 30초; 빠른 컷 편집의 경우 더 짧게, N개의 파일이 있는 경우 S초 내에 효과당 최대 N개의 큐를 가질 수 있기 때문입니다; 하나의 시그니처 사운드가 필요할 때는 끄십시오. 큐가 드롭된 경우 사용자에게 알리십시오.
캐릭터 (옵트인). --character pop=bright (또는 이벤트의 "character": ["bright"], 후자가 전자를 대체함)는 해당 효과에 대해 태그나 무드가 모든 단어를 포함하는 라이브러리 파일만 유지합니다. 라이브러리가 이미 말하는 것을 매칭합니다. 절대 태그를 추론하거나 추가하지 않으며, 일치하는 파일이 없으면 INPUT_NOT_FOUND입니다: 파일을 가져오거나 태그를 지정하고, 절대 추측하지 마십시오. library-import --tags / --mood 및 여기에서 사용할 단어: bright, dark, warm, metallic, soft, hard, punchy, subtle, short, long, high, low, rising, falling, airy, playful (다른 단어도 일치합니다).

EzAudio 실행 전 사용자에게 묻기

EzAudio (generate-sfx)는 YouTube 오디오(AudioSet, VGGSound, AudioCaps)로 훈련되었으며, 소유자가 훈련용으로 라이선스하지 않았습니다. 소유자의 결정에 따라 사용자는 실행 전에 이 사실을 알려야 합니다. --acknowledge-ezaudio-training-data 없이 generate-sfx는 아무것도 실행하기 전에 CONFIRMATION_REQUIRED (종료 코드 8)로 중단됩니다. 메시지는 주의 사항을 영어와 일본어로 제공합니다. 사용자에게 해당 메시지를 보여주고, 사용자가 동의한 후에만 플래그를 전달하십시오. 절대 자체적으로 추가하지 마십시오. contract --json (generate-sfx 도구) 및 doctor --json (checks.operations.sfx)은 confirmation_required: true를 전달하므로 오케스트레이터가 먼저 물을 수 있습니다. 확인은 provenance에 기록되며, 모든 SFX 결과는 훈련 데이터 경고를 반복합니다: 이를 전달하십시오.

라이브러리 모드의 라이선스

library-import는 누락, 비어 있거나 플레이스홀더 라이선스(unknown, n/a 등)를 LICENCE_REQUIRED (종료 코드 2)와 함께 거부합니다. 사용자에게 라이선스를 물으십시오. 절대 임의로 채우지 마십시오.
라이선스는 선언된 그대로 기록되며, verified: false입니다. 이 스킬은 라이선스를 확인하거나 정리하지 않습니다: "CC-BY-4.0으로 선언됨"이라고 말하고, 절대 "확인됨"이라고 말하지 마십시오.
library-index는 선언된 라이선스가 없는 파일을 licence: "unknown"으로 보고하며, library-pick은 절대 이를 사용하지 않습니다 (이유와 함께 excluded 아래에 나열됨).
경고를 전달하십시오: 비상업적 조건, 트리밍되거나 루프된 파일에 대한 수정 금지 조건, 크레딧 없는 CC BY 라이선스, 가져온 이후 변경된 파일. 게시된 모든 것에 크레딧을 유지하십시오.
스톡 트랙. 사용자가 다운로드한 것을 출처가 명시한 대로 가져옵니다: --licence, --licence-url 및/또는 --licence-file (licences/에 복사됨), --title, --author, --provider, --attribution, --content-id. 스킬은 아무것도 다운로드하지 않습니다; doctor는 스톡 소스를 나열하지만 (API 키 없이 MISSING, API 없이 MANUAL) 절대 호출하지 않습니다. 영수증(library-pick 결과 및 provenance의 licence.attribution, handoff.credit_line)은 크레딧 라인을 전달합니다: 선언된 것, 그다음 크레딧, CC BY의 경우 선언된 부분만으로 구성된 것 (경고: 확인). 비디오 설명이나 크레딧에 넣으십시오. --content-id registered로 선언된 트랙은 경고됩니다: 업로드 시 클레임이 발생할 수 있으므로 게시 전에 사용자에게 알리십시오.
맞춤: 0.1초 또는 1% 이내에서 파일이 전체적으로 사용됩니다; 더 긴 파일은 트리밍됩니다(페이드 없음: MIX가 페이드 처리); 더 짧은 파일은 --loopable로 가져온 경우에만 크로스페이드와 함께 루프되고, 그렇지 않으면 제외됩니다. 동일한 라이브러리와 쿼리는 항상 동일한 파일을 제공합니다.

사용자에게 알릴 제한 사항

실험적(EXPERIMENTAL). audio.bgm_generate, audio.sfx_generate 및 audio.library_import는 수명 주기가 EXPERIMENTAL입니다. 실제 ACE-Step 및 EzAudio의 시드 결정론과 지속 시간 정확도는 아직 측정되지 않았습니다 (테스트는 동일한 API를 가진 가짜 엔진을 사용합니다). 결과가 생성된 것이며 들어봐야 한다고 말하십시오.
템포. --bpm을 사용하면 길이가 가장 가까운 정수 마디가 됩니다 (경고 메시지 표시됨), 따라서 배경음악이 마디 라인에서 끝나고, 비트 그리드 (모든 비트, 다운비트, 마디 라인)는 <name>.beats.json으로 기록되고 tempo_map으로 반환됩니다. 그리드는 첫 번째 비트가 0초에 있는 요청된 그리드입니다 (measured: false): ACE-Step에 템포가 요청되었지만, 템포를 얼마나 잘 유지하는지는 측정되지 않았습니다. 그리드를 전달하십시오. 측정되었다고 말하지 마십시오.
ACE-Step은 DiT만 실행합니다 (Qwen3 기본 라이선스가 확인될 때까지 언어 모델은 꺼져 있음). 따라서 프롬프트는 구조가 아닌 스타일을 안내합니다.
warnings의 모든 항목을 읽고 전달하십시오.

엔진 (선택 사항)

명령	엔진	설치
`generate-bgm`	ACE-Step 1.5 (MIT 코드 및 가중치; 기본 2B turbo, `--model`로 4B XL turbo), 자체 체크아웃 및 `.venv` 내 Python 3.11-3.12	`doctor`가 정확한 라인을 출력합니다; `SOUND_DESIGN_ACESTEP_PYTHON` 설정 (및 `SOUND_DESIGN_ACESTEP_CHECKPOINTS`, 그렇지 않으면 Hugging Face 캐시 사용)
`generate-sfx`	EzAudio-XL (MIT 코드 및 가중치, Flan-T5-XL Apache-2.0), 자체 체크아웃 및 `.venv` 내	`doctor`가 정확한 라인을 출력합니다; `SOUND_DESIGN_EZAUDIO_PYTHON` 및 `SOUND_DESIGN_EZAUDIO_DIR` (체크아웃 `ckpts/` 포함) 설정; Hugging Face 캐시 내 Flan-T5-XL
라이브러리 모드	없음	ffmpeg-skill 외에 설치할 항목 없음

BGM 모델 선택

generate-bgm은 --model (요청 키 model)이 다른 것을 지정하지 않는 한 ACE-Step의 2B turbo 모델 acestep-v15-turbo를 실행합니다. 4GB 미만의 GPU 메모리가 필요하며 CPU에서도 실행됩니다 (느리게). --model acestep-v15-xl-turbo는 XL turbo 모델을 선택합니다: 4B DiT, 기본값과 마찬가지로 MIT이며, 출력의 상업적 사용이 자체 모델 카드에 명시되어 있습니다. doctor --json, checks.operations.bgm.models에서 선택합니다. 각 모델은 ready, 해당 파일, vram 및 install을 가집니다:

GPU 메모리. XL은 최소 20GB의 GPU가 필요합니다. 이 스킬은 CPU 오프로드나 양자화 없이 실행하기 때문입니다. 자체 모델 카드에는 12GB (오프로드 및 INT8 포함), 16GB (오프로드 포함), 20GB (오프로드 없음), 24GB (4B LM 포함)가 나열되어 있습니다. 20GB 미만이거나 GPU가 없는 경우, generate-bgm --model acestep-v15-xl-turbo는 아무것도 실행하기 전에 INSUFFICIENT_VRAM (종료 코드 3)으로 중단됩니다. 사용자에게 알리고 기본 모델을 제공하십시오 (error.details.default_model): --model을 제거하십시오. Apple Silicon은 CPU와 공유하는 통합 메모리를 계산합니다. GPU 메모리를 측정할 수 없는 경우 (ROCm, Intel XPU), 배경음악이 만들어지고 확인되지 않았다는 경고가 표시됩니다. Intel GPU는 xpu-smi를 통해서만 인식됩니다; 이것이 없는 Intel GPU에서는 --device xpu를 전달하십시오.
다운로드. 디스크에 약 20GB 더 추가되며, 기본 모델과 동일한 체크포인트 디렉토리 (SOUND_DESIGN_ACESTEP_CHECKPOINTS; Hugging Face 캐시 스냅샷은 XL에서 작동하지 않음)에 저장됩니다. 없으면 MODEL_NOT_FOUND 및 error.details.install과 함께 호출이 중단되며, 예를 들어 uv run acestep-download --model acestep-v15-xl-turbo --di와 같은 설치 라인을 제공합니다.

사운드 디자인 스킬