sonido-skill（completo）

sonido（completo）

Cadena de herramientas completa para poner sonido a vídeos, tres líneas de capacidad:

1. Selección de efectos — búsqueda multicanal, filtrado por señales de feedback humano, descarga, medición.
2. BGM (música de fondo) — dos rutas: síntesis offline de música cíclica sin interrupciones, o recuperación de pistas largas desde bibliotecas para fondo.
3. Voz y mezcla — reducción de ruido/EQ/de-esser/compresión, ducking sidechain, mezcla estática, normalización de sonoridad de dos pasos.

Entorno solo requiere Python 3 + FFmpeg (ffmpeg / ffprobe en PATH). Librería estándar pura, sin paquetes externos, sin API keys, sin inicio de sesión.

Todas las capacidades de este skill se implementan de código abierto en este repositorio (licencia MIT): todos los comandos, reglas y parámetros están en la documentación a continuación y en references/, se pueden modificar y distribuir libremente.

Tras la instalación, configura las variables según la ubicación real; aquí se usa la escritura de instalación dentro del proyecto:

S=.claude/skills/sound/scripts/sfx.py       # búsqueda / descarga / análisis
V=.claude/skills/sound/scripts/vocal.py     # voz / mezcla
C=.claude/skills/sound/scripts/compose.py   # síntesis offline de BGM

Para instalación global, cambia .claude/skills/sound/ por ~/.claude/skills/sound/.

---

1. Selección de efectos de sonido

Flujo de trabajo

1. Convierte las acciones de la escena en palabras clave en inglés ("tarjeta volando" → short whoosh, "interruptor" → soft click).
2. all busca candidatos en múltiples fuentes; si es necesario, busca en una sola fuente; --urls da al usuario enlaces de prueba.
3. Primero juzga si coincide con la escena, luego mira la popularidad; da candidatos y base de recomendación, no trates los números como "lo he escuchado".
4. Determina la licencia según el uso, descarga, usa analyze para verificar duración y distribución de energía.
5. Al entregar, conserva la URL de origen, autor y licencia; para los que no son CC0, completa el crédito.

python3 $S all "short whoosh" --license cc0 -n 10 --urls
python3 $S freesound "paper slide" --license by -n 5 --sort short
python3 $S commons "bell" -n 5 --json
python3 $S mixkit "whoosh" -n 5
python3 $S kenney "impact" -n 5
python3 $S get sfx/ fs:167563 wm:131079817 mk:1489
python3 $S analyze sfx/*.mp3 --loudness --silence --json

Reglas de selección (herencia de señales de feedback humano)

• Número de votantes > puntuación media: ★4.4(380) es evidencia más fuerte que ★4.9(6).
• Descripción del subidor lo más cercana a la escucha: la aparición de "built-in mic" / "made with my mouth" indica baja fidelidad; nombrar grabadoras (Zoom, Sound Devices) y fuentes de sonido claras ("cork from a wine bottle") indica control. Si la fuente en la descripción no coincide con la escena, descartar aunque sea popular.
• Popularidad no implica adecuación: el "thud" más descargado puede ser un rugido grave de cine de 3 segundos. Debes mirar la duración, usa analyze para ver dónde cae la energía y cuánto dura la cola, luego decide si recortar.
• Primero da candidatos, luego descarga: si el usuario quiere escuchar, añade --urls, no decidas por él directamente.
• Las señales disponibles varían según la fuente: Freesound tiene número de descargas y votantes; Commons tiene duración real y licencia; Mixkit tiene duración pero no popularidad; Kenney son paquetes completos. No trates campos faltantes como 0 puntos.

Reglas de licencia (estrictas por niveles, no relajar)

Parámetro	Permitido	Uso típico
--license cc0	Solo CC0 / PDM	Comercial, sin querer gestionar créditos
--license by	CC0 / PDM / BY / BY-SA	Acepta crédito (ya excluye BY-NC, BY-NC-SA, BY-ND)
--license any	Todos, pero los resultados aún marcan licencia	Solo quiere ver candidatos primero

• BY-NC no se usa para fines comerciales, el script ya lo ha excluido en cc0/by; en any debes juzgarlo tú mismo.
• Mixkit usa su propia "Mixkit Free License” (comercial sin crédito), pero no pertenece al sistema de etiquetas CC0/BY, por lo que se excluye en cc0/by; cuando lo necesites, usa explícitamente --license any y especifica el nombre de la licencia en el entregable.
• Para material no CC0, get imprimirá el autor y un aviso de licencia; esto es solo una pista, al entregar debes conservar la fuente y el texto original de la licencia.
• Kenney es todo CC0, pero la descarga es un zip del paquete completo, no un efecto individual; debes descomprimirlo y seleccionar los archivos.

Distribución de fuentes

Fuente	Fortaleza	Limitación
Freesound	Única con número de descargas/votantes	Solo descarga MP3 de previsualización, no archivo original; una conexión ~80 KB/s
Wikimedia Commons	Duración real + campos de licencia completos, grabaciones ambientales/campanas/audio largo	Coincidencia por descripción de archivo; palabras clave extrañas no se encuentran; sin popularidad
Mixkit	Comercial sin crédito, efectos de interfaz de calidad estable	Análisis de estructura de página; sin popularidad; duración en segundos enteros
Kenney	Paquetes CC0 de juegos/interfaz	Zip del paquete completo, sin duración individual

Para detalles sobre el método de captura y correspondencia de etiquetas de licencia, ver references/sources.md.

---

2. BGM: síntesis o fondo

Primero determina si el usuario quiere "música” o "componer una pieza que coincida con la emoción":

Escenario	Ruta	Comando
Quiere cíclica, sin dependencias, emoción controlable, sin riesgo de derechos de autor	Síntesis offline	compose.py
Quiere instrumentos reales/voz/ambiente	Recuperación de fondo	sfx.py music
Ya tiene BGM corta y quiere llenar la escena	Bucle/corte	vocal.py loop / trim

Síntesis offline (primera opción, realmente corresponde a "síntesis de BGM")

python3 $C bgm.wav --style ambient --duration 30 --bpm 90 --key Am
python3 $C bgm.wav --style lofi    --duration 30 --bpm 85 --key C
python3 $C bgm.wav --style upbeat  --duration 30 --bpm 120 --key G

• ambient: pad lento (acordes de fondo), sin batería, ideal para narración/demostración de producto; lofi: chorus desafinado + kick/hat relajado + ruido de cinta; upbeat: acordes cortos brillantes + bombo en cuatro tiempos + línea de bajo.
• Salida WAV estéreo 44.1 kHz / 16-bit, alineación de fase de inicio y fin + crossfade circular de acordes, se puede repetir sin interrupciones.
• La duración se alinea al compás entero más cercano (ej. 30s @ 90 BPM son realmente 29.333s); para segundos exactos, usa BPM divisible por 4 (ej. 120).
• El script imprime un valor sugerido de --bgm-gain (en dB) directamente pegable, coherente con los parámetros de vocal.py, úsalo directamente.
• --seed garantiza que la misma salida sea completamente idéntica, para gestión de versiones.

Recuperación de fondo

python3 $S music "ambient" --duration long --max-seconds 600 -n 8 --urls --json
python3 $S get bgm/ wm:123456
python3 $V trim bgm/xxx.ogg bed.wav --start 0 --end 30

• music busca en Commons con filetype:audio, --duration long por defecto ≥30 segundos, duración desconocida se excluye por defecto (para permitir, añade --allow-unknown).
• Commons a menudo devuelve grabaciones de campo/audiolibros de horas; al usarlas como fondo asegúrate de añadir --max-seconds 600, de lo contrario descargarás cientos de MB.
• Después de descargar audio largo, generalmente hay que trim un segmento, o loop para llenar la longitud de la escena con un segmento corto.

---

3. Limpieza de voz y mezcla

Cadena estándar

# 1. Voz: reducción de ruido → paso alto → (de-esser) → compresión → normalización de sonoridad de dos pasos → fundido de entrada/salida
python3 $V clean voice.wav clean.wav --deesser
#    Por defecto objetivo -16 LUFS; para no normalizar, añade --no-loudnorm

# 2. Alinear BGM a la longitud de la escena (elegir una)
python3 $V loop  bgm.wav  bed.wav  --duration 30     # material corto llena, crossfade real en la unión
python3 $V trim  bgm.wav  bed.wav  --start 0 --end 30

# 3. Mezcla: cuando hay voz, baja automáticamente la BGM (ducking sidechain)
python3 $V duck clean.wav bed.wav mixed.wav --bgm-gain -12 --threshold -30 --ratio 8
#    Sin voz / solo ambiente, cambia a mezcla estática
python3 $V mix  bed.wav clean.wav mixed.wav --bgm-gain -18

# 4. Revisión / normalización de sonoridad final
python3 $V report mixed.wav
python3 $V loudnorm mixed.wav final.wav --target-lufs -16

Reglas de parámetros

Parámetro	Por defecto	Cuándo ajustar
--bgm-gain	duck -12 / mix -18 dB	Usa el valor sugerido por compose.py; si la BGM tapa la voz, baja otros 3~6 dB
--threshold	-30 dB	El umbral del sidechain es umbral de nivel, no detección de voz; cuando la voz es muy baja, ajústalo a -36; cuando la BGM es muy alta, súbelo
--ratio	8	Si el ducking es demasiado obvio/la respiración es fuerte, baja a 4
--target-lufs	-16 LUFS	Para locución/vídeo usa -16; para transmisión de música pura usa -14; para podcast puede ser -16
--true-peak	-1.5 dBTP	Si la plataforma tiene un límite claro, cámbialo según la plataforma
--fade	duck 0.3 / clean 0.05 segundos	Para inicio/final de clip, uniones de bucle

• No mezcles dimensiones: I es LUFS (sonoridad integrada), TP es dBTP (pico verdadero), LRA es LU (rango de sonoridad); mean_volume es nivel promedio en dBFS, en report se etiqueta claramente, no lo tomes como LUFS.
• Tanto duck como mix añaden apad (silencio de relleno) y usan duration=longest, la BGM más corta que la voz no se corta; --duration puede especificar la longitud del producto final.
• Las dos pasadas de loudnorm en clean se ejecutan después de toda la cadena previa, y la I/TP/LRA de la pasada de medición es completamente consistente con la segunda pasada; el fundido se coloca antes de loudnorm, asegurando que la señal medida y la entrada normalizada sean la misma; de lo contrario, measured_* no coincidirá.
• El margen de medición interno de loudnorm puede diferir de ebur128 en aproximadamente 1 LU; el script realiza una revisión cerrada y añade una ganancia de compensación después del producto final, e imprime en el resumen "Revisión cerrada ±X.X dB"; este es un paso necesario para alcanzar la precisión, no lo elimines.
• Para material muy corto/casi silencioso donde no se puede medir LUFS válido, se degrada automáticamente a una sola pasada de loudnorm y se escribe claramente en la salida "Una pasada"; en este caso, la revisión cerrada se omite automáticamente, no añade ganancia en silencio.

Para el texto original de la cadena de filtros, el principio de dos pasadas de loudnorm y la tabla de ajuste de parámetros, ver references/mixing.md.

---

4. Recetas comunes

A. Demostración de producto de 30 segundos (totalmente offline, sin material)

python3 $C bgm.wav --style ambient --duration 30 --bpm 120 --key Am
python3 $V clean voice.wav clean.wav --deesser
python3 $V duck clean.wav bgm.wav mixed.wav --bgm-gain -13
python3 $V loudnorm mixed.wav final.wav --target-lufs -16
python3 $S all "soft whoosh" --license cc0 -n 6 --urls

B. Añadir fondo ambiental real a una locución existente

python3 $S music "rain ambience" --duration long --max-seconds 600 --license by -n 6 --urls
python3 $S get bgm/ wm:xxx
python3 $V trim bgm/xxx bed.wav --start 10 --end 40
python3 $V clean voice.wav clean.wav
python3 $V duck clean.wav bed.wav mixed.wav --bgm-gain -18

C. Solo un efecto de transición, y que sea comercializable

python3 $S all "paper slide" --license cc0 -n 8 --sort short --urls
python3 $S get sfx/ fs:xxx
python3 $S analyze sfx/*.mp3 --loudness --silence --json

D. Envolvente de volumen que sigue la escena (renderizado con Remotion)

El máster final usa la cadena FFmpeg anterior; los fundidos cuadro a cuadro / volumen de golpe se hacen durante el renderizado de Remotion, ver references/remotion-audio.md.

---