elevenlabs-fx

ElevenLabs + AudioFX

ElevenLabs cria a matéria-prima (um efeito sonoro a partir de um prompt, uma voz a partir de texto, uma música); AudioFX a ajusta à cena (telefone, rádio, subaquático, reverb, um impacto no corte). sfx é node {{AUDIOFX_DIR}}/bin/sfx.mjs (veja a skill de design de som para o catálogo completo de efeitos).

1. Verifique a conexão

sfx doctor

A última linha informa se uma chave ElevenLabs foi encontrada e onde (nunca imprime a chave). O CLI e o estúdio procuram por ELEVENLABS_API_KEY no ambiente, depois em .env na pasta atual, no repositório AudioFX e em ~/.audiofx/.env.

Se não houver chave, diga ao usuário como conectar. Nunca peça para colar a chave no chat, nem a escreva em um arquivo você mesmo:

1. Crie uma chave de API em https://elevenlabs.io/app/settings/api-keys (qualquer plano; o nível gratuito funciona para efeitos sonoros e vozes predefinidas).
2. Ou execute npx -y @elevenlabs/cli@latest onboard init no projeto (ele escreve um .env), ou adicione ELEVENLABS_API_KEY=... em ~/.audiofx/.env manualmente.
3. Execute sfx doctor novamente. Nenhuma reinicialização necessária.

Outras formas de conectar (opcional)

• MCP Hospedado, para que o Claude possa chamar ferramentas ElevenLabs diretamente. No Claude (web ou desktop): Configurações → Conectores → adicione um conector personalizado com https://api.elevenlabs.io/v1/mcp e faça login. No Claude Code: claude mcp add --transport http elevenlabs https://api.elevenlabs.io/v1/mcp, depois /mcp para autenticar. A versão de diretório do conector é restrita e pode não oferecer música.
• Skills oficiais com conhecimento da API ElevenLabs (TTS, efeitos sonoros, música, agentes): npx skills add elevenlabs/skills.

sfx generate é o caminho mais direto para trabalho com vídeo: gera, salva uma cópia para reuso e aplica efeitos em um comando, sem necessidade de MCP.

2. Gere e processe em um único passo

sfx generate <sfx|voice|music> "<prompt>" <output> [passo...]

Tipo	O que chama	Opções
sfx	Efeitos sonoros (eleven_text_to_sound_v3)	--duration 0.5–30 (padrão: o modelo decide), --loop, --influence 0–1 (padrão 0.3)
voice	Texto para fala (eleven_v4)	--voice <id> (padrão George, uma voz predefinida), --model <id>
music	Música	--duration 3–600, --instrumental

• A cadeia é validada antes de gastar créditos, então um erro de digitação em um passo falha de graça.
• Cada geração também é salva como ~/.audiofx/generated/<tipo>-<prompt>-<tempo>.mp3 com um .json do prompt. Ela aparece primeiro na biblioteca do estúdio ("Gerado"), para que o usuário possa tentar outros efeitos sem pagar duas vezes. Reutilize com sfx apply em vez de gerar novamente.
• Sem passos, a geração bruta é escrita na saída (mp3 copiado; outros formatos convertidos para 48 kHz).
• 402 paid_plan_required em uma voz significa uma voz da Biblioteca de Vozes: use um id de voz predefinida ou peça ao usuário para atualizar. 429 significa limite de taxa: espere e tente novamente uma vez.

3. Receitas

Uma voz TTS através de um telefone, rádio ou dispositivo

sfx generate voice "Ei, sou eu. Estou lá fora, abre a porta." call.wav voice-clean "telephone:noise=0.1"
sfx generate voice "Aqui quem fala é o capitão." captain.wav "speaker:model=pa" "reverb:space=hall,mix=0.2"
sfx generate voice "Unidade quatro, responda." radio.wav "walkie-talkie:drive=12"

Vozes TTS são limpas e próximas: um tratamento as faz pertencer à cena. Para uma narração que deve ficar à frente, use apenas voice-clean e loudness, ou trailer-voice para uma leitura épica.

Uma música gerada que fica submersa em um momento

A câmera mergulha aos 12 s e emerge aos 18 s:

sfx generate music "Indie pop animado, guitarras brilhantes, 120 bpm" song.wav "underwater:depth=0.8@12-18" --duration 30 --instrumental --fade 0.35

Outros tratamentos baseados em momento em uma música: "am-radio@0-8" --fade 1.2 (toca de um rádio, depois se abre), "filter-sweep:fromFreq=300,toFreq=18000,start=10,duration=2" (crescendo para uma queda aos 12 s), "tape-stop:at=20,length=0.9" (parada cômica).

Um efeito sonoro sobreposto em um corte

Gere o efeito, depois misture-o no áudio do vídeo no corte (aqui 6,0 s) com o efeito layer:

sfx generate sfx "Porta pesada de madeira bate em corredor de pedra" 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 mede onde está o ataque do som gerado e o posiciona no corte, para que o silêncio inicial na geração não o atrase. Efeitos sonoros gerados também aparecem na aba Amostras do estúdio, onde o usuário pode experimentá-los em um momento ouvindo. Para um impacto, crescendo ou whoosh sintetizado, os efeitos de cinema na skill de design de som são mais rápidos e gratuitos; para amostras gravadas de uma biblioteca de sons, veja "Amostras reais como camadas" lá.

Um ambiente contínuo

sfx generate sfx "Chuva leve em uma janela, trânsito distante da cidade, sem trovão" rain.wav "muffled:thickness=0.4" --duration 20 --loop

--loop faz o final encontrar o início, para que o ambiente possa se repetir sob uma cena longa (-stream_loop no ffmpeg, ou <Loop> no Remotion).

Reutilizando o que o usuário já gerou

Áudio que o usuário fez no aplicativo ElevenLabs, ou com o MCP, é apenas um arquivo: sfx apply <arquivo> <saída> <passos...>. Links que o MCP hospedado retorna (em elevenlabsusercontent.com) expiram após cerca de duas horas, então baixe o arquivo primeiro, depois processe a cópia local.

Instruções para prompts de efeitos sonoros

• Descreva a fonte, a ação, o material e o espaço: "garrafa de vidro quebra em piso de concreto, sala pequena" é melhor que "vidro quebrando".
• Um evento por geração. Sobreponha várias gerações em vez de pedir uma cena inteira.
• Peça o que você processará de qualquer forma em uma versão neutra: gere um "telefone tocando" limpo e adicione speaker:model=phone ou distance com AudioFX, para que o mesmo arquivo sirva para várias cenas.
• Efeitos curtos (impactos, cliques, whooshes) funcionam melhor com --duration 1–3; ambientes e sons contínuos com --loop e 10–30 s.
• --influence próximo de 1 segue o prompt literalmente; valores mais baixos deixam o modelo preencher.

Custo e cuidado

• Cada chamada sfx generate gasta os créditos ElevenLabs do usuário. Gere uma vez, reutilize o arquivo salvo e mude os efeitos com sfx apply ou no estúdio.
• Não faça loops de gerações para "escolher a melhor" sem perguntar: ofereça duas ou três variações e deixe o usuário escolher ouvindo no sfx studio.
• Vozes geradas não devem imitar uma pessoa real sem o seu consentimento.