elevenlabs-fx

ElevenLabs + AudioFX

ElevenLabs는 원재료(프롬프트 기반 음향 효과, 텍스트 기반 음성, 음악)를 만들고, AudioFX는 이를 장면에 맞게 변형합니다(전화기, 라디오, 수중, 리버브, 컷에 맞춘 효과음). sfx는 node {{AUDIOFX_DIR}}/bin/sfx.mjs입니다(전체 효과 목록은 사운드 디자인 스킬 참고).

1. 연결 확인

sfx doctor

마지막 줄에는 ElevenLabs 키가 발견되었는지와 그 위치가 표시됩니다(키 자체는 절대 출력되지 않음). CLI와 스튜디오는 환경 변수 ELEVENLABS_API_KEY를 먼저 찾고, 그다음 현재 폴더, AudioFX 저장소, ~/.audiofx/.env의 .env 파일을 찾습니다.

키가 없으면 사용자에게 연결 방법을 알려주세요. 사용자에게 채팅에 키를 붙여넣도록 요청하거나, 스스로 파일에 키를 작성하지 마십시오.

1. https://elevenlabs.io/app/settings/api-keys 에서 API 키 생성 (모든 요금제 가능; 무료 플랜도 음향 효과 및 프리메이드 음성에 사용 가능).
2. 프로젝트에서 npx -y @elevenlabs/cli@latest onboard init 실행 (.env 파일을 생성함) 또는 사용자가 직접 ~/.audiofx/.env에 ELEVENLABS_API_KEY=...를 추가.
3. sfx doctor를 다시 실행합니다. 재시작은 필요하지 않습니다.

기타 연결 방법 (선택 사항)

• 호스티드 MCP: Claude가 ElevenLabs 도구를 직접 호출할 수 있게 합니다. Claude(웹 또는 데스크톱): 설정 → 커넥터 → 사용자 지정 커넥터 추가: https://api.elevenlabs.io/v1/mcp, 로그인. Claude Code: claude mcp add --transport http elevenlabs https://api.elevenlabs.io/v1/mcp, 이후 /mcp로 인증. 디렉토리 버전의 커넥터는 제한적이며 음악 기능을 제공하지 않을 수 있습니다.
• 공식 스킬 (ElevenLabs API 활용, TTS, 음향 효과, 음악, 에이전트): npx skills add elevenlabs/skills.

sfx generate는 비디오 작업에 가장 직접적인 경로입니다. 생성, 재사용을 위한 복사본 저장, 효과 적용을 한 명령어로 처리하며 MCP가 필요 없습니다.

2. 생성 및 한 번에 처리

sfx generate <sfx|voice|music> "<프롬프트>" <출력파일> [단계...]

종류	호출하는 기능	옵션
sfx	음향 효과 (eleven_text_to_sound_v3)	--duration 0.5–30 (기본값: 모델 결정), --loop, --influence 0–1 (기본값 0.3)
voice	텍스트 음성 변환 (eleven_v4)	--voice <id> (기본값 George, 프리메이드 음성), --model <id>
music	음악	--duration 3–600, --instrumental

• 체인은 크레딧이 사용되기 전에 검증되므로, 단계에 오타가 있으면 무료로 실패합니다.
• 모든 생성물은 ~/.audiofx/generated/<종류>-<프롬프트>-<시간>.mp3로 저장되며 프롬프트 정보가 담긴 .json 파일도 함께 저장됩니다. 스튜디오 라이브러리("Generated")에 가장 먼저 표시되므로, 사용자는 비용을 두 번 지불하지 않고 다른 효과를 시험해 볼 수 있습니다. 다시 생성하지 않고 sfx apply를 사용하여 재사용하세요.
• 단계 없이 실행하면 원시 생성물이 출력 파일로 직접 기록됩니다(mp3 복사, 다른 형식은 48kHz로 변환).
• 음성에서 402 paid_plan_required 오류는 Voice Library 음성을 의미합니다. 프리메이드 음성 ID를 사용하거나 사용자에게 업그레이드를 요청하세요. 429는 속도 제한입니다. 잠시 기다렸다가 한 번 재시도하세요.

3. 레시피

TTS 음성을 전화기, 라디오 또는 장치를 통해 재생

sfx generate voice "Hey, it's me. I'm outside, open the door." call.wav voice-clean "telephone:noise=0.1"
sfx generate voice "This is your captain speaking." captain.wav "speaker:model=pa" "reverb:space=hall,mix=0.2"
sfx generate voice "Unit four, respond." radio.wav "walkie-talkie:drive=12"

TTS 음성은 깨끗하고 가깝게 녹음됩니다. 효과 처리를 통해 장면에 어울리게 만들 수 있습니다. 앞쪽에 남아 있어야 하는 내레이션에는 voice-clean과 loudness만 사용하거나, 장엄한 읽기를 위해 trailer-voice를 사용하세요.

특정 순간에 물속으로 들어가는 음악 생성

카메라가 12초에 다이빙하고 18초에 수면 위로 나옵니다:

sfx generate music "Upbeat indie pop, bright guitars, 120 bpm" song.wav "underwater:depth=0.8@12-18" --duration 30 --instrumental --fade 0.35

음악에 적용할 수 있는 다른 순간 기반 효과: "am-radio@0-8" --fade 1.2 (라디오에서 재생되다가 열림), "filter-sweep:fromFreq=300,toFreq=18000,start=10,duration=2" (12초 드롭을 위한 빌드업), "tape-stop:at=20,length=0.9" (코믹한 정지).

컷에 맞춰 레이어링된 음향 효과

효과를 생성한 다음 layer 효과를 사용하여 비디오 오디오의 컷(여기서는 6.0초)에 믹싱합니다:

sfx generate sfx "Heavy wooden door slams in a stone hallway" door.wav "reverb:space=hall,mix=0.25" --duration 2
sfx apply mix.wav mix-door.wav "layer:file=door.wav,at=6,align=onset,level=-3"

align=onset은 생성된 사운드의 어택(attack) 지점을 측정하여 컷에 정확히 맞춥니다. 따라서 생성물에 앞부분 무음이 있어도 지연되지 않습니다. 생성된 음향 효과는 스튜디오의 Samples 탭에도 나타나며, 사용자는 귀로 직접 시점을 확인하며 적용할 수 있습니다. 합성된 효과음(hit, riser, whoosh)의 경우 사운드 디자인 스킬의 시네마 효과가 더 빠르고 무료입니다. 사운드 라이브러리의 녹음된 샘플이 필요하면 해당 스킬의 "Real samples as layers"를 참고하세요.

앰비언스 배경음

sfx generate sfx "Light rain on a window, distant city traffic, no thunder" rain.wav "muffled:thickness=0.4" --duration 20 --loop

--loop는 시작과 끝이 매끄럽게 연결되도록 하여 긴 장면 아래에서 반복 재생할 수 있게 합니다(ffmpeg의 -stream_loop 또는 Remotion의 <Loop> 사용).

사용자가 이미 생성한 오디오 재사용

사용자가 ElevenLabs 앱이나 MCP에서 만든 오디오는 단순한 파일입니다: sfx apply <파일> <출력파일> <단계...>. 호스티드 MCP가 반환하는 링크(예: elevenlabsusercontent.com)는 약 2시간 후에 만료되므로, 먼저 파일을 다운로드한 다음 로컬 복사본을 처리하세요.

음향 효과 프롬프팅

• 소리의 근원, 동작, 재질, 공간을 설명하세요: "glass bottle shatters on a concrete floor, small room"이 "glass breaking"보다 효과적입니다.
• 한 번 생성에 하나의 이벤트만 요청하세요. 전체 장면을 요청하는 대신 여러 생성을 레이어링하세요.
• 어차피 처리할 내용은 중립적인 버전으로 요청하세요: 깨끗한 "phone ringing"을 생성하고 AudioFX로 speaker:model=phone이나 distance를 추가하면 동일한 파일을 여러 장면에 사용할 수 있습니다.
• 짧은 효과음(hit, click, whoosh)은 --duration 1–3이 가장 적합합니다. 앰비언스와 배경음은 --loop와 10–30초를 사용하세요.
• --influence를 1에 가깝게 설정하면 프롬프트를 문자 그대로 따르고, 낮출수록 모델이 창의성을 발휘합니다.

비용 및 주의 사항

• 각 sfx generate 호출은 사용자의 ElevenLabs 크레딧을 소모합니다. 한 번 생성하고 저장된 파일을 재사용하며, sfx apply나 스튜디오에서 효과를 변경하세요.
• "최고의 것을 고르기" 위해 묻지 않고 생성을 반복하지 마세요. 두세 가지 변형을 제시하고 사용자가 sfx studio에서 귀로 선택하도록 하세요.
• 생성된 음성은 동의 없이 실제 인물을 모방해서는 안 됩니다.