sfx-library

Biblioteca de Efectos de Sonido

834 archivos / 63 categorías / ~1 GB. Un único punto de entrada: el script sfx ubicado en el mismo directorio que este archivo SKILL.md. El script determina automáticamente su propia ruta, por lo que puede llamarse desde cualquier lugar usando la ruta completa; los ejemplos a continuación usan la forma abreviada sfx.

Paso 0 — Verificar si ya existen los datos

El repositorio solo contiene código y el catálogo; los archivos de audio están en data/ (no se incluyen en el commit).

sfx status

Si indica "Chua co du lieu" (Sin datos), descargue los datos — una sola vez, ~1 GB, informe al usuario antes de descargar:

sfx setup

setup sigue estrictamente el orden de prioridad, no lo altere:

1. Google Drive primero — descarga un archivo .zip (~880 MB, aproximadamente 1 minuto), verifica el checksum sha256 y luego lo descomprime.
2. URLs existentes en el catálogo como respaldo — solo se usan si Drive falla (404, archivo no compartido públicamente, límite de descarga excedido, sha256 incorrecto). En ese caso, setup cambia automáticamente a descargar archivo por archivo desde las URLs en catalog/source/*.json (secuencial, ~18 minutos) y verifica sha256 contra catalog/meta.json.

Solo requiere python3 (≥ 3.8), no necesita instalar nada más. Si la descarga se interrumpe, ejecute sfx setup nuevamente — continuará la descarga sin empezar desde cero. El paso de respaldo es lento: ejecútelo en segundo plano e informe al usuario el tiempo estimado.

Solo llame directamente sfx setup --source (omitiendo Drive) si el usuario lo solicita explícitamente.

Si setup informa "Ca hai nguon deu that bai" (Ambas fuentes fallaron), ejecute sfx doctor y notifique al usuario — no busque fuentes alternativas de audio por su cuenta.

Buscar SFX — El único comando que necesita recordar

sfx find "<palabra clave>"

Escriba en español con acentos, sin acentos, o en inglés y obtendrá los mismos resultados — los acentos se eliminan antes de comparar, y cada categoría tiene un conjunto de palabras clave bilingüe.

sfx find "transición"          # por intención
sfx find "notificación" --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

Los resultados incluyen la duración (segundos) — la información más importante para ajustar SFX en la línea de tiempo.

Opción	Úselo cuando
--max-dur N / --min-dur N	necesite restringir la duración al espacio en la línea de tiempo
--group <grupo>	quiera explorar toda una intención (ver tabla de grupos abajo)
--category <slug>	ya sepa la categoría exacta
--ext wav	quiera solo archivos wav (o mp3)
--paths	solo imprima las rutas, una por línea — para pasarlas directamente a otro comando
--json	salida para máquinas, incluye duration, sha256, score
--abs	rutas absolutas — úselo cuando llame a sfx desde otro directorio
-n N / --all	número de resultados (por defecto 20)

Varias palabras en la consulta usan AND por defecto; si ningún archivo coincide con todas, se amplía automáticamente a OR y se notifica en stderr.

Si no está seguro de qué usar → sfx list muestra todas las categorías con su "cuándo usarla" y palabras clave.

10 grupos por intención

Primero seleccione el grupo, luego filtre — es más rápido que adivinar el nombre de la categoría.

Grupo	Úselo para	Categorías típicas
transition	unir dos escenas	fast-whoosh swoosh-swish whip zoom reverse
impact	enfatizar una idea, mostrar datos	hit boom impacts slam bass
ui	aparición de texto, clics, tecleo	pop click typing ui-mini tick shine
alert	notificaciones, recordatorios	notification ding bell alarm
tension	generar suspense antes del clímax	riser builder braam tension trailer
ambience	fondo continuo de una escena	ambience environment
foley	objetos reales	paper doors footsteps liquid draw camera-shutter
comedy	humor	comedy-cartoon memes
scifi	tecnología, fantasía	technology glitch laser magic data
horror	terror	horror jumpscare

Escuchar antes de elegir

El nombre del slug no es suficiente para saber cómo suena el archivo. whoosh-fast-05 y whoosh-fast-06 pueden ser completamente diferentes en tono.

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

Si no se puede escuchar (entorno sin interfaz gráfica), presente 2–3 opciones con su duración para que el usuario elija, no decida por su cuenta afirmando que es adecuado.

Mezclar SFX en video

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

Cada marca de tiempo tiene el formato <segundos>:<ruta>[@volumen]. La ruta es relativa a data/sfx/, o simplemente el nombre del archivo si no hay ambigüedad. El volumen por defecto es 0.6. Requiere ffmpeg.

• El audio existente en el video se conserva y se mezcla, no se sobrescribe — ejecutar sfx mix después de haber añadido la locución es seguro.
• Utiliza amix=normalize=0 + alimiter: añadir marcas no reduce el volumen original y evita distorsiones cuando varias fuentes se superponen.
• --dry-run imprime el comando ffmpeg si necesita integrarlo en otro script.

Video generado desde HTML (grabación de pantalla con Playwright/Puppeteer/Remotion): las etiquetas <audio> o new Audio().play() solo suenan al ver en el navegador — no se incluyen en el archivo MP4 grabado. Añada SFX en el paso de ffmpeg usando sfx mix, obteniendo los tiempos de la línea de tiempo de la animación.

Tres factores que determinan si un video suena profesional:

1. El SFX debe ser más corto que el espacio en la línea de tiempo — filtre con --max-dur desde el principio en lugar de recortar después.
2. Coloque el SFX exactamente en el fotograma del movimiento, no al inicio de la escena — el whoosh debe sonar justo cuando el objeto comienza a moverse.
3. No superponga SFX sobre el diálogo. Si hay locución, reduzca a @0.3 o use la categoría ui-mini.

Tres errores comunes

1. No incluya data/ en el commit — ~1 GB, ya está en gitignore, recupere con sfx setup.
2. No modifique los archivos en data/sfx/. Son los originales; si necesita cortar o normalizar volumen, exporte a otro directorio.
3. No ejecute sfx download directamente para la primera descarga. Descarga 834 archivos individuales, es lento y es solo una ruta de respaldo. Siempre ejecute sfx setup para que Google Drive se intente primero.

Para verificar si hay problemas: sfx doctor (herramientas + origen de datos), sfx verify --hash (recalcula sha256 de cada archivo).

Para mantenimiento de la biblioteca (agregar categorías, reempaquetar, cambiar enlace de Drive): vea README.md.