sfx-library

Biblioteca de Efeitos Sonoros

834 arquivos / 63 categorias / ~1 GB. Um único ponto de entrada: o script sfx localizado no mesmo diretório que este arquivo SKILL.md. O script determina automaticamente o seu próprio caminho, portanto pode ser chamado de qualquer lugar usando o caminho completo — os exemplos abaixo são escritos de forma abreviada como sfx.

Passo 0 — verificar se os dados já existem

O repositório contém apenas código e catálogo; os arquivos de áudio ficam em data/ (não commitados).

sfx status

Se exibir "Chua co du lieu", obtenha os dados — uma única vez, ~1 GB, avise o usuário antes de baixar:

sfx setup

setup segue automaticamente a ordem de prioridade correta, não altere a sequência:

1. Google Drive primeiro — baixa um arquivo .zip (~880 MB, cerca de 1 minuto), verifica o sha256 e extrai.
2. URL disponível no catálogo é o fallback — usado apenas quando o Drive falha (404, arquivo não compartilhado publicamente, limite de downloads excedido, sha256 diferente). Nesse caso, setup muda para baixar cada arquivo individualmente pela URL em catalog/source/*.json (sequencial, ~18 minutos) e verifica o sha256 com catalog/meta.json.

Requer apenas python3 (≥ 3.8), sem necessidade de instalar mais nada. Se for interrompido no meio, execute novamente sfx setup — ele continuará de onde parou, sem baixar tudo de novo. O fallback é lento: execute em segundo plano e informe o usuário sobre o tempo de espera.

Chame sfx setup --source diretamente (pulando o Drive) apenas se o usuário solicitar.

Se setup exibir "Ca hai nguon deu that bai", execute sfx doctor e avise o usuário — não tente encontrar fontes alternativas de áudio.

Encontrar SFX — o único comando que você precisa lembrar

sfx find "<palavra-chave>"

Digitar em português com acentos, sem acentos, ou em inglês produz os mesmos resultados — os acentos são removidos antes da comparação, e cada categoria já possui um conjunto de palavras-chave bilíngue.

sfx find "transição"          # por intenção
sfx find "notificação" --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

O resultado exibe a duração (em segundos) — a informação mais importante ao encaixar SFX na linha do tempo.

Flag	Uso
--max-dur N / --min-dur N	restringir duração conforme o espaço na timeline
--group <grupo>	navegar por toda uma intenção (veja a tabela de grupos abaixo)
--category <slug>	quando a categoria exata já é conhecida
--ext wav	obter apenas wav (ou mp3)
--paths	exibir apenas caminhos, um arquivo por linha — ideal para passar para outro comando
--json	saída para leitura por máquina, incluindo duration, sha256, score
--abs	caminhos absolutos — use ao chamar sfx de outro diretório
-n N / --all	número de resultados (padrão: 20)

Consultas com múltiplas palavras usam AND por padrão; se nenhum arquivo corresponder a todas as palavras, a consulta é automaticamente expandida para OR e isso é informado claramente no stderr.

Se não tiver certeza do que usar → sfx list exibe todas as categorias com "quando usar" e palavras-chave.

10 grupos por intenção

Escolha o grupo primeiro, depois refine — é mais rápido do que adivinhar o nome da categoria.

Grupo	Uso	Categorias típicas
transition	conectar duas cenas	fast-whoosh swoosh-swish whip zoom reverse
impact	marcar um ponto, mostrar dados	hit boom impacts slam bass
ui	texto aparecendo, cliques em botões, digitação	pop click typing ui-mini tick shine
alert	notificações, lembretes	notification ding bell alarm
tension	criar suspense antes do clímax	riser builder braam tension trailer
ambience	fundo contínuo para uma cena	ambience environment
foley	objetos reais	paper doors footsteps liquid draw camera-shutter
comedy	humor	comedy-cartoon memes
scifi	tecnologia, fantasia	technology glitch laser magic data
horror	terror	horror jumpscare

Ouvir antes de escolher

O nome do slug não é suficiente para saber como o arquivo soa. whoosh-fast-05 e whoosh-fast-06 podem ser completamente diferentes em termos de nuance.

afplay "$(sfx find whoosh --paths --abs -n 1)"     # macOS; Linux: ffplay -nodisp -autoexit

Se não for possível ouvir (execução headless), apresente 2–3 opções com duração para o usuário escolher — não decida sozinho e afirme que é adequado.

Inserir SFX no vídeo

sfx mix video.mp4 -o com-som.mp4 \
    2.4:fast-whoosh/whoosh-fast-05.wav \
    5.0:ding/[email protected]

Cada cue é <segundos>:<caminho>[@volume]. O caminho é relativo a data/sfx/, ou apenas o nome do arquivo se não houver conflito. Volume padrão 0.6. Requer ffmpeg.

• O áudio existente no vídeo é mantido e mixado junto, não substituído — executar sfx mix após adicionar narração é seguro.
• Usa amix=normalize=0 + alimiter: adicionar cues não reduz o volume original e evita distorção quando várias fontes se sobrepõem.
• --dry-run exibe o comando ffmpeg caso precise ser usado em outro script.

Vídeo gerado a partir de HTML (gravação de tela com Playwright/Puppeteer/Remotion): tags <audio> ou new Audio().play() na página só funcionam quando visualizadas no navegador — ele não vai para o arquivo MP4 gravado. Insira SFX na etapa ffmpeg usando sfx mix, obtendo os marcadores de tempo da animação da timeline.

Três fatores que determinam se um vídeo soa profissional:

1. O SFX deve ser mais curto que o espaço na timeline — filtre com --max-dur desde o início em vez de cortar depois.
2. Posicione o SFX exatamente no frame do movimento, não no início da cena — um whoosh deve soar exatamente quando o objeto começa a se mover.
3. Não sobreponha SFX à fala. Se houver narração, reduza para @0.3 ou use a categoria ui-mini.

Três erros comuns

1. Não commite data/ — ~1 GB, já está no gitignore, recupere com sfx setup.
2. Não modifique arquivos em data/sfx/. Eles são os originais; corte/normalize o volume e salve em outro lugar.
3. Não chame sfx download diretamente para obter os dados pela primeira vez. Ele baixa 834 arquivos individuais, é lento e é o caminho de fallback. Sempre use sfx setup para tentar o Google Drive primeiro.

Verifique se suspeitar de problemas: sfx doctor (ferramentas + fonte de dados), sfx verify --hash (recalcula sha256 de cada arquivo).

Manutenção da biblioteca (adicionar categoria, reempacotar, alterar link do Drive): consulte README.md.