kajisho5/sound-design-skill

O que sound-design-skill faz?

Execute sound-design <comando> ... --json (instalado por pip install -e ., Python >= 3.9, apenas stdlib). Com --json, a saída padrão contém exatamente um documento JSON, somente ASCII. Sondagem, corte, junção e loudness passam pelo ffmpeg-skill, encontrado através de --ffmpeg-skill DIR, $SOUND_DESIGN_FFMPEG_SKILL_DIR, $VIDEO_AGENT_FFMPEG_SKILL_DIR, ~/.claude/skills/ffmpeg-skill, ./vendor/ffmpeg-skill ou ../ffmpeg-skill. sound-design doctor --json informa quais engines estão OK, AUSENTE ou INCOMPATÍVEL, o dispositivo de computação e a memória da GPU, e como instalar cada engine; nunca baixa nada.

Tarefa	Comando
Uma trilha de 60 s	sound-design generate-bgm --prompt "calm piano bed" --tags "ambient,70 bpm" --duration 60 -o bed.wav --seed 42 --json (10-600 s)
Uma trilha a 120 BPM para um lyric video de 15 s, com sua grade de batidas	sound-design generate-bgm --prompt "upbeat pop" --duration 15 --bpm 120 --time-signature 4 -o pv.wav --json (torna-se 16 s = 8 compassos; pv.beats.json ao lado)
O mesmo, com letras / na CPU	adicione --lyrics lyrics.txt / --device cpu (padrão instrumental, --device auto)
Uma trilha do modelo XL 4B maior (opt-in, GPU com >= 20 GB)	sound-design generate-bgm --prompt "cinematic strings" --duration 60 -o bed.wav --model acestep-v15-xl-turbo --json (veja "Escolhendo o modelo BGM")
Um efeito sonoro (após o usuário concordar, veja abaixo)	sound-design generate-sfx --prompt "a wooden door closes" --tags "indoor" --duration 3 -o door.wav --seed 7 --acknowledge-ezaudio-training-data --json (segundos inteiros, 1-10)
Adicionar o próprio arquivo do usuário a uma biblioteca	sound-design library-import track.wav --library ./sounds --licence CC-BY-4.0 --credit "Music: name" --kind bgm --tags piano --mood calm --loopable --json
Adicionar uma faixa baixada com seus registros de licença	sound-design library-import track.mp3 --library ./sounds --licence CC-BY-4.0 --title "Morning Light" --author "Aiko Tanaka" --licence-url https://creativecommons.org/licenses/by/4.0/ --licence-file LICENSE.txt --provider Freesound --kind bgm --json (adicione --attribution "<linha>" quando a fonte fornecer uma, --content-id registered apenas quando a fonte assim o disser)
O que há em uma biblioteca, com licenças e durações	sound-design library-index ./sounds --loudness --json
Uma faixa da biblioteca ajustada para 60 s	sound-design library-pick ./sounds --kind bgm --tags piano --duration 60 -o bed.wav --json (adicione --file <caminho> para nomear a faixa, --crossfade 0.5 para loops)
Um loop contínuo de 8 s de uma trilha (para loops em uma edição)	sound-design loop-bed bed.wav -o loop.wav --duration 8 --search 1 --json (fonte com pelo menos duração + crossfade; o ponto de loop é pesquisado dentro de --search s)
Um whoosh de 1 s cujo pico cai no corte em 0.5 s	sound-design stinger whoosh.wav -o stinger.wav --duration 1 --peak-at 0.5 --type whoosh --json
Verificar as emendas de um arquivo em loop	sound-design seam-check loop-x10.wav --period 8 --json (ou --seams 8,16; sai com código 1 quando uma emenda falha)
Efeitos nos cortes e legendas de ênfase (uma folha de sugestões 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, ênfase = pop a menos que --effect cut=<nome>; --file ding=ding.wav para um efeito gerado)
Mesmo, sem reutilizar arquivo em 30 s, e pops brilhantes	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; veja abaixo)
O que está instalado	sound-design doctor --json, sound-design engines --json
O que este skill declara	sound-design contract --json (alias skill --json)

Cada operação aceita --timeout S e --ffmpeg-skill DIR; aquelas que escrevem um arquivo aceitam --overwrite (uma saída existente é recusada sem ele); os geradores também aceitam --seed (sorteado e registrado quando omitido) e --offline. A saída é um novo .wav; a entrada nunca é modificada, e uma saída aparece completa ou não aparece, após o ffmpeg-skill probe tê-la verificado.

Quando usar

• O usuário tem músicas ou efeitos com licença conhecida (pacotes comprados, faixas comissionadas, CC0 / CC BY): modo biblioteca primeiro. library-import cada arquivo com sua licença, depois library-pick para cada cena. Nenhum engine é executado e nada é gerado por IA (ai_generated: false).
• Nada adequado na biblioteca: generate-bgm (ACE-Step) ou generate-sfx (EzAudio), se doctor mostrar o engine OK.
• Então sempre entregue o WAV e sua provenance ao audio-production-skill MIX, que o posiciona, o atenua sob a fala e define o loudness. Este skill não mixa, atenua ou normaliza.

Loops e stingers

• loop-bed e stinger não executam nenhum engine. Eles pegam um WAV que você já possui (resultado de generate-bgm, generate-sfx ou library-pick, ou o arquivo do usuário), editam-no apenas através do ffmpeg-skill e medem o resultado; sua licença e engine permanecem na proveniência da fonte, portanto, passe ambos adiante.
• O final de um loop se conecta ao seu início sem clique: repita-o de ponta a ponta, sem crossfade. O resultado informa o comprimento do loop que encontrou (loop.length, dentro de --search de --duration), o quão semelhante é o material com crossfade (loop.similarity; um aviso abaixo de 0.5) e a emenda medida (seam). Um número inteiro de compassos forma o melhor loop.
• Um stinger tem exatamente a duração --duration e seus 10 ms mais altos estão dentro de 10 ms de --peak-at (pelo menos 20 ms de qualquer extremidade), caso contrário nada é escrito. Diga ao MIX para iniciá-lo --peak-at segundos antes do corte.
• seam-check é a própria verificação de loop deste skill: clique (±1 ms), nível e espectro de banda de oitava de 1 s de cada lado. O qc-skill ainda não possui verificação de emenda de loop.

Folhas de sugestões de efeitos sonoros

• sfx-cues não posiciona nada e não decide nada: os tempos são do chamador (da lista de cortes da edição e das legendas de ênfase), uma sugestão por tempo. Um tempo mais próximo que --min-spacing da última sugestão mantida é descartado (listado em dropped com o motivo), nunca movido. Nunca invente tempos de ênfase para ele.
• Cada sugestão indica qual arquivo (file, from: biblioteca ou um WAV nomeado, source: sua entrada em sources com a licença), onde começa (start; file_offset quando começaria antes de 0), seu gain_db para atingir o nível --level dBFS, e se seu pico (whoosh, rise, ...) ou seu início (pop, ding, ...) está sobre o tempo. Efeitos da biblioteca precisam de uma licença declarada, escolhidos como library-pick pelo nome do efeito como uma tag. Entregue a folha ao audio-production-skill MIX com as licenças das fontes.
• O mesmo arquivo novamente (opt-in, desligado por padrão). --min-reuse-spacing S: um evento cujo efeito reproduziria o mesmo arquivo (mesmo SHA-256) como uma sugestão mantida há menos de S s atrás pega o próximo arquivo da biblioteca para aquele efeito em ordem de classificação (o primeiro classificado sempre que estiver livre; nunca aleatório). Sem outro arquivo elegível, ou para um efeito --file, o evento é descartado (dropped[].by: min_reuse_spacing), nunca movido e nunca recebe outro efeito. substitutions e substituted de cada sugestão indicam qual arquivo substituiu qual. A verificação --min-spacing vem primeiro; um evento descartado não conta para nenhuma regra. Sugerido: 30 s para uma edição de cabeça falante; mais curto para edições de cortes rápidos, já que com N arquivos um efeito tem no máximo N sugestões em qualquer S s; deixe desligado quando um som de assinatura é desejado. Informe o usuário quando as sugestões forem descartadas.
• Caráter (opt-in). --character pop=bright (ou o "character": ["bright"] de um evento, que o substitui) mantém apenas os arquivos da biblioteca para aquele efeito cujas tags ou humor contenham cada palavra. Ele corresponde ao que a biblioteca já diz; nunca infere ou adiciona uma tag, e nenhum arquivo correspondente é INPUT_NOT_FOUND: importe ou marque o arquivo, nunca adivinhe. Palavras a serem usadas em library-import --tags / --mood e aqui: bright, dark, warm, metallic, soft, hard, punchy, subtle, short, long, high, low, rising, falling, airy, playful (outras palavras também correspondem).

Pergunte ao usuário antes do EzAudio

O EzAudio (generate-sfx) foi treinado em áudio do YouTube (AudioSet, VGGSound, AudioCaps) não licenciado para treinamento por seus proprietários. Por decisão do proprietário, o usuário é informado disso antes de sua execução. Sem --acknowledge-ezaudio-training-data, generate-sfx para com CONFIRMATION_REQUIRED (código de saída 8) antes de fazer qualquer coisa; a mensagem fornece a ressalva em inglês e japonês. Mostre essa mensagem ao usuário e passe a flag somente após ele concordar; nunca a adicione por conta própria. contract --json (a ferramenta generate-sfx) e doctor --json (checks.operations.sfx) carregam confirmation_required: true para que um orquestrador possa perguntar primeiro. O reconhecimento é registrado na proveniência, e todo resultado SFX repete o aviso de dados de treinamento: passe-o adiante.

Licenças no modo biblioteca

• library-import recusa uma licença ausente, vazia ou place holder (unknown, n/a, ...) com LICENCE_REQUIRED (código de saída 2). Pergunte ao usuário pela licença; nunca preencha uma.
• Uma licença é registrada exatamente como declarada, com verified: false. Este skill não verifica ou limpa licenças: diga "declarada como CC-BY-4.0", nunca "verificada".
• library-index relata um arquivo sem licença declarada como licence: "unknown", e library-pick nunca o utiliza (ele é listado em excluded com o motivo).
• Passe adiante os avisos: um termo não comercial, um termo sem derivações em um arquivo cortado ou em loop, uma licença CC BY sem crédito, um arquivo alterado desde sua importação. Mantenha o crédito com qualquer coisa publicada.
• Faixas de banco de imagens. Importe o que o usuário baixou com o que a fonte indica: --licence, --licence-url e/ou --licence-file (copiado para licences/), --title, --author, --provider, --attribution, --content-id. O skill não baixa nada; doctor lista fontes de banco de imagens (MISSING sem chave de API, MANUAL sem API), mas nunca as chama. O recibo (licence.attribution no resultado library-pick e proveniência, handoff.credit_line) carrega a linha de crédito: a declarada, senão o crédito, senão para CC BY uma composta apenas das partes declaradas (avisado: verifique-a). Coloque-a na descrição ou créditos do vídeo. Uma faixa declarada --content-id registered é avisada: o upload pode receber uma reivindicação, então informe o usuário antes de publicar.
• Ajuste: dentro de max(0.1 s, 1%) o arquivo é usado inteiro; um arquivo mais longo é cortado (sem fade: o MIX faz fade); um arquivo mais curto é colocado em loop com um crossfade apenas quando foi importado com --loopable, senão é excluído. A mesma biblioteca e consulta sempre fornecem o mesmo arquivo.

Limites a informar ao usuário

• EXPERIMENTAL. audio.bgm_generate, audio.sfx_generate e audio.library_import têm ciclo de vida EXPERIMENTAL. O determinismo da semente e a precisão da duração dos ACE-Step e EzAudio reais ainda não foram medidos (os testes usam engines falsos com a mesma API). Diga que o resultado é gerado e deve ser ouvido.
• A música gerada não é verificada quanto à semelhança com gravações existentes; verificações de reconhecimento musical e direitos autorais não são função deste skill. A declaração de uso comercial do ACE-Step é uma afirmação do fornecedor.
• Tempo. Com --bpm, o comprimento se torna o número inteiro mais próximo de compassos (um aviso informa isso), de modo que a trilha termina em uma linha de compasso, e a grade de batidas (cada batida, tempos fortes, linhas de compasso) é escrita como <nome>.beats.json e retornada como tempo_map. A grade é a solicitada com a primeira batida em 0 s (measured: false): o ACE-Step recebeu a solicitação de tempo, mas o quão bem ele o mantém não é medido. Passe a grade adiante; não a chame de medida.
• O ACE-Step executa apenas DiT (seu modelo de linguagem está desligado até que as licenças base do Qwen3 sejam verificadas), então os prompts orientam o estilo, não a estrutura.
• Leia e passe adiante cada entrada de warnings.

Engines (opcionais)

Op	Engine	Instalação
generate-bgm	ACE-Step 1.5 (código e pesos MIT; 2B turbo por padrão, 4B XL turbo com --model), Python 3.11-3.12 em seu próprio checkout e .venv	doctor imprime a linha exata; defina SOUND_DESIGN_ACESTEP_PYTHON (e SOUND_DESIGN_ACESTEP_CHECKPOINTS, senão o cache do Hugging Face)
generate-sfx	EzAudio-XL (código e pesos MIT, Flan-T5-XL Apache-2.0) em seu próprio checkout e .venv	doctor imprime a linha exata; defina SOUND_DESIGN_EZAUDIO_PYTHON e SOUND_DESIGN_EZAUDIO_DIR (checkout com ckpts/); Flan-T5-XL no cache do Hugging Face
modo biblioteca	nenhum	nada para instalar além do ffmpeg-skill

Escolhendo o modelo BGM

generate-bgm executa o modelo turbo 2B do ACE-Step, acestep-v15-turbo, a menos que --model diga o contrário (chave de solicitação model). Ele precisa de menos de 4 GB de memória GPU e também funciona na CPU (lentamente). --model acestep-v15-xl-turbo seleciona o modelo turbo XL: um DiT 4B, MIT como o padrão, com uso comercial da saída declarado em seu próprio cartão de modelo. Escolha-o a partir de doctor --json, checks.operations.bgm.models, onde cada modelo tem ready, seus arquivos, vram e install:

• Memória GPU. O XL precisa de uma GPU com pelo menos 20 GB, porque este skill o executa sem CPU offload ou quantização. Seu cartão de modelo lista 12 GB (com offload e INT8), 16 GB (com offload), 20 GB (sem offload) e 24 GB (com o LM 4B). Abaixo de 20 GB, ou sem GPU, generate-bgm --model acestep-v15-xl-turbo para antes de qualquer execução com INSUFFICIENT_VRAM (código de saída 3). Informe o usuário e ofereça o modelo padrão (error.details.default_model): remova --model. Apple Silicon conta sua memória unificada, que a CPU compartilha. Quando a memória GPU não pode ser medida (ROCm, Intel XPU), a trilha é feita e um aviso diz que não foi verificada. Uma GPU Intel só é notada através de xpu-smi; em uma sem ele, passe --device xpu.
• Download. Cerca de 20 GB adicionais em disco, no mesmo diretório de checkpoints do modelo principal (SOUND_DESIGN_ACESTEP_CHECKPOINTS; um snapshot do cache do Hugging Face não funciona para XL). Sem ele, a chamada para com MODEL_NOT_FOUND e error.details.install fornece a linha, por exemplo uv run acestep-download --model acestep-v15-xl-turbo --dir /caminho/para/checkpoints.
• Sem modelo XL. Quando doctor mostra MODEL_MISSING ou INSUFFICIENT_VRAM, o comportamento é como se --model nunca tivesse sido passado: o modelo turbo 2B é usado.

Proveniência e entrega

Todo resultado carrega a proveniência como um metadado WAV (iXML ou bext) e como provenance no JSON de saída:

{
  "engine": "acestep-v15-turbo | ezaudio-xl | library",
  "source": "...",
  "seed": 42,
  "prompt": "...",
  "duration": 60.0,
  "licence": "CC-BY-4.0 | CC0-1.0 | ...",
  "ai_generated": true | false,
  "confirmation_required": false,
  "acknowledged": true | false,
  "attribution": "...",
  "warnings": []
}

Passe a proveniência junto com o arquivo WAV para o estágio MIX. Nunca perca a informação de licença ou o aviso de dados de treinamento.

Fluxo de trabalho típico

1. O usuário pede música de fundo ou efeitos sonoros.
2. Verifique a biblioteca com library-index; se houver algo adequado, use library-pick.
3. Caso contrário, verifique os engines com doctor.
4. Se o engine BGM estiver OK, gere com generate-bgm; informe o usuário sobre a natureza experimental.
5. Se for SFX, avise sobre o EzAudio, pergunte ao usuário e, se ele concordar, gere com generate-sfx.
6. Crie loops ou stingers conforme necessário com loop-bed ou stinger.
7. Entregue o WAV e a proveniência ao audio-production-skill MIX.

Nota: Este skill não faz mixagem, ducking ou normalização de loudness. Isso é responsabilidade do MIX.