kajisho5/sound-design-skill

¿Qué hace sound-design-skill?

Ejecuta sound-design <comando> ... --json (instalado con pip install -e ., Python >= 3.9, solo stdlib). Con --json, stdout contiene exactamente un documento JSON, solo ASCII. El sondeo, corte, unión y sonoridad se realizan a través de ffmpeg-skill, que se encuentra mediante --ffmpeg-skill DIR, $SOUND_DESIGN_FFMPEG_SKILL_DIR, $VIDEO_AGENT_FFMPEG_SKILL_DIR, ~/.claude/skills/ffmpeg-skill, ./vendor/ffmpeg-skill o ../ffmpeg-skill. sound-design doctor --json indica qué motores están OK, FALTAN o SON INCOMPATIBLES, el dispositivo de cómputo y la memoria de GPU, y cómo instalar cada motor; nunca descarga nada.

Tarea	Comando
Una pista musical de 60 s	sound-design generate-bgm --prompt "cama de piano tranquila" --tags "ambient,70 bpm" --duration 60 -o bed.wav --seed 42 --json (10-600 s)
Una pista a 120 BPM para un vídeo lírico de 15 s, con su rejilla de tiempos	sound-design generate-bgm --prompt "pop alegre" --duration 15 --bpm 120 --time-signature 4 -o pv.wav --json (se convierte en 16 s = 8 compases; pv.beats.json junto a él)
Lo mismo, con letra / en la CPU	añade --lyrics lyrics.txt / --device cpu (por defecto instrumental, --device auto)
Una pista del modelo 4B XL más grande (opt-in, una GPU con >= 20 GB)	sound-design generate-bgm --prompt "cuerdas cinematográficas" --duration 60 -o bed.wav --model acestep-v15-xl-turbo --json (ver "Elegir el modelo BGM")
Un efecto de sonido (después de que el usuario haya aceptado, ver más abajo)	sound-design generate-sfx --prompt "una puerta de madera se cierra" --tags "interior" --duration 3 -o door.wav --seed 7 --acknowledge-ezaudio-training-data --json (segundos enteros, 1-10)
Añadir un archivo propio del usuario a una biblioteca	sound-design library-import track.wav --library ./sounds --licence CC-BY-4.0 --credit "Música: nombre" --kind bgm --tags piano --mood calm --loopable --json
Añadir una pista de stock descargada con sus registros de licencia	sound-design library-import track.mp3 --library ./sounds --licence CC-BY-4.0 --title "Luz de la Mañana" --author "Aiko Tanaka" --licence-url https://creativecommons.org/licenses/by/4.0/ --licence-file LICENSE.txt --provider Freesound --kind bgm --json (añade --attribution "<línea>" cuando la fuente proporcione una, --content-id registered solo cuando la fuente lo indique)
Qué hay en una biblioteca, con licencias y duraciones	sound-design library-index ./sounds --loudness --json
Una pista de biblioteca ajustada a 60 s	sound-design library-pick ./sounds --kind bgm --tags piano --duration 60 -o bed.wav --json (añade --file <ruta> para nombrar la pista, --crossfade 0.5 para bucles)
Un bucle sin costuras de 8 s de una pista (para bucles en una edición)	sound-design loop-bed bed.wav -o loop.wav --duration 8 --search 1 --json (la fuente debe tener al menos la duración + crossfade; el punto de bucle se busca dentro de --search s)
Un whoosh de 1 s cuyo pico aterriza en el corte a 0.5 s	sound-design stinger whoosh.wav -o stinger.wav --duration 1 --peak-at 0.5 --type whoosh --json
Comprobar las uniones de un archivo en bucle	sound-design seam-check loop-x10.wav --period 8 --json (o --seams 8,16; sale con 1 cuando una unión falla)
Efectos en los cortes y leyendas de énfasis (una hoja de señales para MIX)	sound-design sfx-cues --cuts 1.0,2.5,4.75 --emphasis 3.2 --library ./sounds --min-spacing 0.25 -o cues.json --json (corte = whoosh, énfasis = pop a menos que --effect cut=<nombre>; --file ding=ding.wav para un efecto generado)
Lo mismo, sin que se repita ningún archivo en 30 s, y pops brillantes	sound-design sfx-cues --cuts 1.0,12.0,25.0 --emphasis 3.2 --library ./sounds --min-reuse-spacing 30 --character pop=bright -o cues.json --json (ambos opt-in; ver más abajo)
Qué está instalado	sound-design doctor --json, sound-design engines --json
Lo que declara esta habilidad	sound-design contract --json (alias skill --json)

Cada operación acepta --timeout S y --ffmpeg-skill DIR; aquellas que escriben un archivo aceptan --overwrite (se rechaza una salida existente sin ella); los generadores también aceptan --seed (generado y registrado cuando se omite) y --offline. La salida es un nuevo .wav; la entrada nunca se modifica, y una salida aparece completa o no aparece, después de que ffmpeg-skill probe la haya comprobado.

Cuándo usarlo

• El usuario tiene música o efectos con una licencia conocida (paquetes comprados, pistas encargadas, CC0 / CC BY): modo biblioteca primero. library-import cada archivo con su licencia, luego library-pick para cada escena. No se ejecuta ningún motor y no se genera nada por IA (ai_generated: false).
• Nada adecuado en la biblioteca: generate-bgm (ACE-Step) o generate-sfx (EzAudio), si doctor muestra el motor OK.
• Luego siempre entrega el WAV y su provenance a audio-production-skill MIX, que lo coloca, lo atenúa bajo el habla y ajusta la sonoridad. Esta habilidad no mezcla, no atenúa ni normaliza.

Bucles y transiciones

• loop-bed y stinger no ejecutan ningún motor. Toman un WAV que ya tienes (un resultado de generate-bgm, generate-sfx o library-pick, o un archivo del usuario), lo editan solo a través de ffmpeg-skill, y miden el resultado; su licencia y motor permanecen en la procedencia de la fuente, así que pásalos ambos.
• El final de un bucle se une con su inicio sin clic: repítelo de extremo a extremo, sin crossfade. El resultado informa de la longitud del bucle encontrada (loop.length, dentro de --search de --duration), cuán similar es el material con crossfade (loop.similarity; una advertencia por debajo de 0.5) y la envolvente medida (seam). Un número entero de compases se repite mejor.
• Un stinger tiene exactamente la duración --duration y sus 10 ms más fuertes están dentro de 10 ms de --peak-at (al menos a 20 ms de cualquier extremo), de lo contrario no se escribe nada. Dile a MIX que lo inicie --peak-at segundos antes del corte.
• seam-check es la comprobación de bucle propia de esta habilidad: clic (±1 ms), nivel y espectro de banda de octava de 1 s en cada lado. qc-skill aún no tiene una comprobación de unión de bucle.

Hojas de señales de efectos de sonido

• sfx-cues no coloca nada y no decide nada: los tiempos los proporciona quien llama (de la lista de cortes de la edición y las leyendas de énfasis), una señal por tiempo. Un tiempo más cercano que --min-spacing a la última señal mantenida se descarta (listado bajo dropped con el motivo), nunca se mueve. Nunca inventes tiempos de énfasis para ello.
• Cada señal indica qué archivo (file, from: biblioteca o un WAV nombrado, source: su entrada bajo sources con la licencia), dónde comienza (start; file_offset cuando comenzaría antes de 0), su gain_db para alcanzar --level dBFS, y si su pico (whoosh, rise, ...) o su inicio (pop, ding, ...) se sitúa en el tiempo. Los efectos de biblioteca necesitan una licencia declarada, elegidos como library-pick por el nombre del efecto como etiqueta. Entrega la hoja a audio-production-skill MIX con las licencias de las fuentes.
• El mismo archivo de nuevo (opt-in, desactivado por defecto). --min-reuse-spacing S: un evento cuyo efecto reproduciría el mismo archivo (mismo SHA-256) que una señal mantenida menos de S s antes toma el siguiente archivo de biblioteca para ese efecto en orden de clasificación (el primero clasificado cuando esté libre; nunca aleatorio). Sin otro archivo elegible, o para un efecto --file, el evento se descarta (dropped[].by: min_reuse_spacing), nunca se mueve y nunca se le da otro efecto. substitutions y substituted de cada señal indican qué archivo reemplazó a cuál. La comprobación de --min-spacing ocurre primero; un evento descartado no cuenta para ninguna regla. Sugerido: 30 s para una edición de cabezas parlantes; más corto para ediciones de cortes rápidos, ya que con N archivos un efecto tiene como máximo N señales en cualquier S s; déjalo desactivado cuando se desee un sonido de firma único. Informa al usuario cuando se descarten señales.
• Carácter (opt-in). --character pop=bright (o el "character": ["bright"] de un evento, que lo reemplaza) mantiene solo los archivos de biblioteca para ese efecto cuyas etiquetas o estado de ánimo contengan cada palabra. Coincide con lo que la biblioteca ya dice; nunca infiere ni añade una etiqueta, y ningún archivo coincidente es INPUT_NOT_FOUND: importa o etiqueta el archivo, nunca adivines. Palabras a usar en library-import --tags / --mood y aquí: bright, dark, warm, metallic, soft, hard, punchy, subtle, short, long, high, low, rising, falling, airy, playful (otras palabras también coinciden).

Pregunta al usuario antes de EzAudio

EzAudio (generate-sfx) fue entrenado con audio de YouTube (AudioSet, VGGSound, AudioCaps) no licenciado para entrenamiento por sus propietarios. Por decisión del propietario, se informa al usuario antes de que se ejecute. Sin --acknowledge-ezaudio-training-data, generate-sfx se detiene con CONFIRMATION_REQUIRED (código de salida 8) antes de hacer nada; el mensaje da la advertencia en inglés y japonés. Muestra ese mensaje al usuario y pasa la bandera solo después de que acepte; nunca la añadas por tu cuenta. contract --json (la herramienta generate-sfx) y doctor --json (checks.operations.sfx) llevan confirmation_required: true para que un orquestador pueda preguntar primero. El reconocimiento se registra en la procedencia, y cada resultado de SFX repite la advertencia de datos de entrenamiento: pásala.

Licencias en modo biblioteca

• library-import rechaza una licencia faltante, vacía o de marcador de posición (unknown, n/a, ...) con LICENCE_REQUIRED (código de salida 2). Pregunta al usuario por la licencia; nunca la rellenes.
• Una licencia se registra exactamente como se declara, con verified: false. Esta habilidad no verifica ni aclara licencias: di "declarada como CC-BY-4.0", nunca "aclarada".
• library-index informa de un archivo sin licencia declarada como licence: "unknown", y library-pick nunca lo usa (se lista bajo excluded con el motivo).
• Pasa las advertencias: un término no comercial, un término sin derivados en un archivo recortado o en bucle, una licencia CC BY sin crédito, un archivo modificado desde su importación. Mantén el crédito con cualquier cosa publicada.
• Pistas de stock. Importa lo que el usuario descargó con lo que la fuente indique: --licence, --licence-url y/o --licence-file (copiado en licences/), --title, --author, --provider, --attribution, --content-id. La habilidad no descarga nada; doctor lista las fuentes de stock (MISSING sin clave API, MANUAL sin API) pero nunca las llama. El recibo (licence.attribution en el resultado de library-pick y la procedencia, handoff.credit_line) lleva la línea de crédito: la declarada, o si no, el crédito, o para CC BY una compuesta solo a partir de partes declaradas (se advierte: verifícala). Ponla en la descripción o los créditos del vídeo. Se advierte sobre una pista declarada --content-id registered: la subida puede recibir un reclamo, así que informa al usuario antes de publicar.
• Ajuste: dentro de max(0.1 s, 1 %) el archivo se usa completo; un archivo más largo se recorta (sin fundido: MIX funde); un archivo más corto se repite en bucle con un crossfade solo cuando se importó con --loopable, de lo contrario se excluye. La misma biblioteca y consulta siempre dan el mismo archivo.

Límites que informar al usuario

• EXPERIMENTAL. audio.bgm_generate, audio.sfx_generate y audio.library_import tienen ciclo de vida EXPERIMENTAL. El determinismo de la semilla y la precisión de la duración del ACE-Step y EzAudio reales aún no se han medido (las pruebas usan motores falsos con la misma API). Di que el resultado se genera y debe escucharse.
• La música generada no se verifica por similitud con grabaciones existentes; el reconocimiento musical y las comprobaciones de derechos de autor no son trabajo de esta habilidad. La declaración de uso comercial de ACE-Step es una afirmación del proveedor.
• Tempo. Con --bpm la longitud se convierte en el número entero de compases más cercano (una advertencia lo indica), por lo que la pista termina en una línea de compás, y la rejilla de tiempos (cada tiempo, tiempos fuertes, líneas de compás) se escribe como <nombre>.beats.json y se devuelve como tempo_map. La rejilla es la solicitada con el primer tiempo en 0 s (measured: false): se pidió el tempo a ACE-Step, pero qué tan bien lo mantiene no se mide. Pasa la rejilla; no la llames medida.
• ACE-Step ejecuta solo DiT (su modelo de lenguaje está desactivado hasta que se verifiquen las licencias base de Qwen3), por lo que los prompts guían el estilo, no la estructura.
• Lee y pasa cada entrada de warnings.

Motores (opcionales)

Operación	Motor	Instalación
generate-bgm	ACE-Step 1.5 (código y pesos MIT; 2B turbo por defecto, 4B XL turbo con --model), Python 3.11-3.12 en su propio checkout y .venv	doctor imprime la línea exacta; configura SOUND_DESIGN_ACESTEP_PYTHON (y SOUND_DESIGN_ACESTEP_CHECKPOINTS, si no, la caché de Hugging Face)
generate-sfx	EzAudio-XL (código y pesos MIT, Flan-T5-XL Apache-2.0) en su propio checkout y .venv	doctor imprime la línea exacta; configura SOUND_DESIGN_EZAUDIO_PYTHON y SOUND_DESIGN_EZAUDIO_DIR (checkout con ckpts/); Flan-T5-XL en la caché de Hugging Face
modo biblioteca	ninguno	nada que instalar más allá de ffmpeg-skill

Elegir el modelo BGM

generate-bgm ejecuta el modelo turbo 2B de ACE-Step, acestep-v15-turbo, a menos que --model indique lo contrario (clave de solicitud model). Necesita menos de 4 GB de memoria de GPU y también se ejecuta en la CPU (lentamente). --model acestep-v15-xl-turbo selecciona el modelo turbo XL: un DiT de 4B, MIT como el predeterminado, con uso comercial del resultado indicado en su propia tarjeta de modelo. Elígelo de doctor --json, checks.operations.bgm.models, donde cada modelo tiene ready, sus archivos, vram e install:

• Memoria de GPU. XL necesita una GPU con al menos 20 GB, porque esta habilidad lo ejecuta sin descarga en CPU ni cuantización. Su tarjeta de modelo lista 12 GB (con descarga e INT8), 16 GB (con descarga), 20 GB (sin descarga) y 24 GB (con el LM de 4B). Por debajo de 20 GB, o sin GPU, generate-bgm --model acestep-v15-xl-turbo se detiene antes de ejecutar nada con INSUFFICIENT_VRAM (código de salida 3). Informa al usuario y ofrece el modelo predeterminado (error.details.default_model): elimina --model. Apple Silicon cuenta su memoria unificada, que la CPU comparte. Cuando la memoria de GPU no se puede medir (ROCm, Intel XPU), la pista se crea y una advertencia dice que no se verificó. Una GPU Intel solo se detecta a través de xpu-smi; en una sin ella, pasa --device xpu.
• Descarga. Aproximadamente 20 GB más en disco, en el mismo directorio de puntos de control que el modelo principal (SOUND_DESIGN_ACESTEP_CHECKPOINTS; una instantánea de la caché de Hugging Face no funciona para XL). Sin ella, la llamada se detiene con MODEL_NOT_FOUND y error.details.install da la línea, por ejemplo `uv run acestep-download --model acestep-v15-xl-turbo --di