kajisho5/sound-design-skill

Que fait sound-design-skill ?

Exécutez sound-design <commande> ... --json (installé par pip install -e ., Python >= 3.9, stdlib uniquement). Avec --json, stdout contient exactement un document JSON, ASCII uniquement. Les opérations de sondage, coupe, jointure et volume passent par ffmpeg-skill, trouvé via --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 indique quels moteurs sont OK, MANQUANT ou INCOMPATIBLE, le périphérique de calcul et la mémoire GPU, et comment installer chaque moteur ; il ne télécharge jamais rien.

Tâche	Commande
Un tapis sonore de 60 s	sound-design generate-bgm --prompt "calme lit piano" --tags "ambient,70 bpm" --duration 60 -o lit.wav --seed 42 --json (10-600 s)
Un tapis à 120 BPM pour une vidéo lyrique de 15 s, avec sa grille de temps	sound-design generate-bgm --prompt "pop entraînante" --duration 15 --bpm 120 --time-signature 4 -o pv.wav --json (devient 16 s = 8 mesures ; pv.beats.json à côté)
Même chose, avec paroles / sur le CPU	ajoutez --lyrics paroles.txt / --device cpu (par défaut instrumental, --device auto)
Un tapis issu du modèle 4B XL plus grand (opt-in, GPU avec >= 20 Go)	sound-design generate-bgm --prompt "cordes cinématiques" --duration 60 -o lit.wav --model acestep-v15-xl-turbo --json (voir "Choix du modèle BGM")
Un effet sonore (après accord de l'utilisateur, voir ci-dessous)	sound-design generate-sfx --prompt "une porte en bois se ferme" --tags "intérieur" --duration 3 -o porte.wav --seed 7 --acknowledge-ezaudio-training-data --json (secondes entières, 1-10)
Ajouter le propre fichier de l'utilisateur à une bibliothèque	sound-design library-import piste.wav --library ./sons --licence CC-BY-4.0 --credit "Musique: nom" --kind bgm --tags piano --mood calme --loopable --json
Ajouter une piste de stock téléchargée avec ses enregistrements de licence	sound-design library-import piste.mp3 --library ./sons --licence CC-BY-4.0 --title "Lumière du matin" --author "Aiko Tanaka" --licence-url https://creativecommons.org/licenses/by/4.0/ --licence-file LICENCE.txt --provider Freesound --kind bgm --json (ajoutez --attribution "<ligne>" quand la source en donne une, --content-id registered uniquement quand la source le dit)
Ce qu'il y a dans une bibliothèque, avec licences et durées	sound-design library-index ./sons --loudness --json
Une piste de bibliothèque adaptée à 60 s	sound-design library-pick ./sons --kind bgm --tags piano --duration 60 -o lit.wav --json (ajoutez --file <chemin> pour nommer la piste, --crossfade 0.5 pour les boucles)
Une boucle transparente de 8 s d'un tapis (pour les boucles dans un montage)	sound-design loop-bed lit.wav -o boucle.wav --duration 8 --search 1 --json (la source doit faire au moins la durée + le crossfade ; le point de boucle est recherché dans les --search s)
Un whoosh de 1 s dont le pic tombe sur la coupe à 0.5 s	sound-design stinger whoosh.wav -o stinger.wav --duration 1 --peak-at 0.5 --type whoosh --json
Vérifier les jonctions d'un fichier bouclé	sound-design seam-check boucle-x10.wav --period 8 --json (ou --seams 8,16 ; sort avec code 1 quand une jonction échoue)
Effets sur les coupes et les légendes d'emphase (une feuille de repères pour MIX)	sound-design sfx-cues --cuts 1.0,2.5,4.75 --emphasis 3.2 --library ./sons --min-spacing 0.25 -o repères.json --json (coupe = whoosh, emphase = pop sauf --effect cut=<nom> ; --file ding=ding.wav pour un effet généré)
Même chose, aucun fichier rejoué en 30 s, et pops lumineux	sound-design sfx-cues --cuts 1.0,12.0,25.0 --emphasis 3.2 --library ./sons --min-reuse-spacing 30 --character pop=brillant -o repères.json --json (les deux sont opt-in ; voir ci-dessous)
Ce qui est installé	sound-design doctor --json, sound-design engines --json
Ce que cette compétence déclare	sound-design contract --json (alias skill --json)

Chaque opération prend --timeout S et --ffmpeg-skill DIR ; celles qui écrivent un fichier prennent --overwrite (une sortie existante est refusée sans cela) ; les générateurs prennent aussi --seed (tiré et enregistré quand omis) et --offline. La sortie est un nouveau .wav ; l'entrée n'est jamais modifiée, et une sortie apparaît en entier ou pas du tout, après que ffmpeg-skill probe l'a vérifiée.

Quand l'utiliser

• L'utilisateur a de la musique ou des effets avec une licence connue (packs achetés, pistes commandées, CC0 / CC BY) : mode bibliothèque en premier. library-import chaque fichier avec sa licence, puis library-pick pour chaque scène. Aucun moteur ne s'exécute et rien n'est généré par IA (ai_generated: false).
• Rien de pertinent dans la bibliothèque : generate-bgm (ACE-Step) ou generate-sfx (EzAudio), si doctor montre le moteur OK.
• Ensuite toujours remettre le WAV et sa provenance à audio-production-skill MIX, qui le place, le baisse sous la parole et règle le volume. Cette compétence ne mixe pas, ne baisse pas et ne normalise pas.

Boucles et stingers

• loop-bed et stinger n'exécutent aucun moteur. Ils prennent un WAV que vous avez déjà (un résultat de generate-bgm, generate-sfx ou library-pick, ou un fichier de l'utilisateur), l'éditent via ffmpeg-skill uniquement, et mesurent le résultat ; sa licence et son moteur restent dans la provenance de la source, donc transmettez les deux.
• La fin d'une boucle rejoint son début sans clic : répétez-la bout à bout, sans crossfade. Le résultat signale la longueur de boucle trouvée (loop.length, dans les --search de --duration), à quel point le matériel crossfadé est similaire (loop.similarity ; un avertissement en dessous de 0.5) et l'enroulement mesuré (seam). Un nombre entier de mesures boucle le mieux.
• Un stinger a exactement --duration et ses 10 ms les plus fortes sont à moins de 10 ms de --peak-at (au moins 20 ms de chaque extrémité), sinon rien n'est écrit. Dites à MIX de le démarrer --peak-at secondes avant la coupe.
• seam-check est la propre vérification de boucle de cette compétence : clic (±1 ms), niveau et spectre par bande d'octave de 1 s de chaque côté. qc-skill n'a pas encore de vérification de jonction de boucle.

Feuilles de repères d'effets sonores

• sfx-cues ne place rien et ne décide rien : les temps proviennent de l'appelant (de la liste des coupes du montage et des légendes d'emphase), un repère par temps. Un temps plus proche que --min-spacing du dernier repère conservé est supprimé (listé sous dropped avec la raison), jamais déplacé. N'inventez jamais de temps d'emphase pour cela.
• Chaque repère indique quel fichier (file, from : bibliothèque ou un WAV nommé, source : son entrée sous sources avec la licence), où il commence (start ; file_offset quand il commencerait avant 0), son gain_db pour atteindre --level dBFS, et si son pic (whoosh, montée, ...) ou son attaque (pop, ding, ...) se situe sur le temps. Les effets de bibliothèque ont besoin d'une licence déclarée, choisis comme library-pick par le nom de l'effet comme tag. Remettez la feuille à audio-production-skill MIX avec les licences des sources.
• Le même fichier à nouveau (opt-in, désactivé par défaut). --min-reuse-spacing S : un événement dont l'effet jouerait le même fichier (même SHA-256) qu'un repère conservé moins de S s plus tôt prend le fichier de bibliothèque suivant pour cet effet dans l'ordre de classement (le premier classé quand il est libre ; jamais aléatoire). Sans autre fichier éligible, ou pour un effet --file, l'événement est supprimé (dropped[].by: min_reuse_spacing), jamais déplacé et jamais doté d'un autre effet. substitutions et le substituted de chaque repère indiquent quel fichier a remplacé lequel. La vérification --min-spacing vient en premier ; un événement supprimé ne compte pour aucune règle. Suggéré : 30 s pour un montage de tête parlante ; plus court pour les montages à coupes rapides, car avec N fichiers un effet a au plus N repères dans n'importe quel S s ; laissez-le désactivé quand un son signature est souhaité. Informez l'utilisateur lorsque des repères ont été supprimés.
• Caractère (opt-in). --character pop=brillant (ou le "character": ["brillant"] d'un événement, qui le remplace) conserve uniquement les fichiers de bibliothèque pour cet effet dont les tags ou l'humeur portent chaque mot. Cela correspond à ce que la bibliothèque dit déjà ; cela n'infère ni n'ajoute jamais de tag, et aucun fichier correspondant n'est INPUT_NOT_FOUND : importez ou taguez le fichier, ne devinez jamais. Mots à utiliser dans library-import --tags / --mood et ici : brillant, sombre, chaud, métallique, doux, dur, percutant, subtil, court, long, aigu, grave, montant, descendant, aérien, enjoué (d'autres mots correspondent aussi).

Demander à l'utilisateur avant EzAudio

EzAudio (generate-sfx) a été entraîné sur de l'audio YouTube (AudioSet, VGGSound, AudioCaps) non sous licence pour l'entraînement par ses propriétaires. Par décision du propriétaire, l'utilisateur en est informé avant son exécution. Sans --acknowledge-ezaudio-training-data, generate-sfx s'arrête avec CONFIRMATION_REQUIRED (code de sortie 8) avant de faire quoi que ce soit ; le message donne la mise en garde en anglais et en japonais. Montrez ce message à l'utilisateur et passez le drapeau seulement après son accord ; ne l'ajoutez jamais de votre propre chef. contract --json (l'outil generate-sfx) et doctor --json (checks.operations.sfx) portent confirmation_required: true afin qu'un orchestrateur puisse demander d'abord. L'accusé de réception est enregistré dans la provenance, et chaque résultat SFX répète l'avertissement sur les données d'entraînement : transmettez-le.

Licences en mode bibliothèque

• library-import refuse une licence manquante, vide ou de substitution (inconnue, n/d, ...) avec LICENCE_REQUIRED (code de sortie 2). Demandez la licence à l'utilisateur ; n'en remplissez jamais une.
• Une licence est enregistrée exactement comme déclarée, avec verified: false. Cette compétence ne vérifie ni ne valide les licences : dites "déclarée comme CC-BY-4.0", jamais "validée".
• library-index signale un fichier sans licence déclarée comme licence: "inconnue", et library-pick ne l'utilise jamais (il est listé sous excluded avec la raison).
• Transmettez les avertissements : une clause non commerciale, une clause sans dérivés sur un fichier coupé ou bouclé, une licence CC BY sans crédit, un fichier modifié depuis son import. Conservez le crédit avec tout ce qui est publié.
• Pistes de stock. Importez ce que l'utilisateur a téléchargé avec ce que la source déclare : --licence, --licence-url et/ou --licence-file (copié dans licences/), --title, --author, --provider, --attribution, --content-id. La compétence ne télécharge rien ; doctor liste les sources de stock (MANQUANT sans clé API, MANUEL sans API) mais ne les appelle jamais. Le reçu (licence.attribution dans le résultat de library-pick et la provenance, handoff.credit_line) porte la ligne de crédit : celle déclarée, sinon le crédit, sinon pour CC BY une composée uniquement à partir des parties déclarées (averti : vérifiez-la). Mettez-la dans la description ou les crédits de la vidéo. Une piste déclarée --content-id registered est signalée : le téléchargement peut faire l'objet d'une revendication, alors informez l'utilisateur avant publication.
• Ajustement : dans la limite de max(0.1 s, 1 %), le fichier est utilisé en entier ; un fichier plus long est coupé (pas de fondu : MIX fondue) ; un fichier plus court est bouclé avec un crossfade uniquement s'il a été importé avec --loopable, sinon il est exclu. La même bibliothèque et la même requête donnent toujours le même fichier.

Limites à communiquer à l'utilisateur

• EXPÉRIMENTAL. audio.bgm_generate, audio.sfx_generate et audio.library_import ont un cycle de vie EXPÉRIMENTAL. La déterminisme de la seed et la précision de la durée des vrais ACE-Step et EzAudio ne sont pas encore mesurés (les tests utilisent des moteurs factices avec la même API). Dites que le résultat est généré et doit être écouté.
• La musique générée n'est pas vérifiée pour sa similarité avec des enregistrements existants ; la reconnaissance musicale et les vérifications de droits d'auteur ne relèvent pas de cette compétence. La déclaration d'utilisation commerciale d'ACE-Step est une affirmation du fournisseur.
• Tempo. Avec --bpm, la longueur devient le nombre entier de mesures le plus proche (un avertissement le dit), donc le tapis se termine sur une barre de mesure, et la grille de temps (chaque temps, temps forts, barres de mesure) est écrite sous <nom>.beats.json et renvoyée comme tempo_map. La grille est celle demandée avec le premier temps à 0 s (measured: false) : ACE-Step a été sollicité pour le tempo, mais la qualité avec laquelle il le maintient n'est pas mesurée. Transmettez la grille ; ne l'appelez pas mesurée.
• ACE-Step exécute DiT uniquement (son modèle de langage est désactivé jusqu'à ce que les licences de base Qwen3 soient vérifiées), donc les prompts orientent le style, pas la structure.
• Lisez et transmettez chaque entrée des warnings.

Moteurs (optionnels)

Opération	Moteur	Installation
generate-bgm	ACE-Step 1.5 (code et poids MIT ; 2B turbo par défaut, 4B XL turbo avec --model), Python 3.11-3.12 dans son propre checkout et .venv	doctor affiche la ligne exacte ; définissez SOUND_DESIGN_ACESTEP_PYTHON (et SOUND_DESIGN_ACESTEP_CHECKPOINTS, sinon le cache Hugging Face)
generate-sfx	EzAudio-XL (code et poids MIT, Flan-T5-XL Apache-2.0) dans son propre checkout et .venv	doctor affiche la ligne exacte ; définissez SOUND_DESIGN_EZAUDIO_PYTHON et SOUND_DESIGN_EZAUDIO_DIR (checkout avec ckpts/) ; Flan-T5-XL dans le cache Hugging Face
mode bibliothèque	aucun	rien à installer au-delà de ffmpeg-skill

Choix du modèle BGM

generate-bgm exécute le modèle turbo 2B d'ACE-Step, acestep-v15-turbo, sauf si --model dit autrement (clé de requête model). Il nécessite moins de 4 Go de mémoire GPU et fonctionne aussi sur le CPU (lentement). --model acestep-v15-xl-turbo sélectionne le modèle turbo XL : un DiT 4B, MIT comme le défaut, avec une utilisation commerciale de la sortie déclarée sur sa propre fiche modèle. Choisissez-le depuis doctor --json, checks.operations.bgm.models, où chaque modèle a ready, ses fichiers, vram et install :

• Mémoire GPU. XL nécessite un GPU avec au moins 20 Go, car cette compétence l'exécute sans déchargement CPU ni quantification. Sa fiche modèle liste 12 Go (avec déchargement et INT8), 16 Go (avec déchargement), 20 Go (sans déchargement) et 24 Go (avec le LM 4B). En dessous de 20 Go, ou sans GPU, generate-bgm --model acestep-v15-xl-turbo s'arrête avant toute exécution avec INSUFFICIENT_VRAM (code de sortie 3). Informez l'utilisateur et proposez le modèle par défaut (error.details.default_model) : supprimez --model. Apple Silicon compte sa mémoire unifiée, que le CPU partage. Lorsque la mémoire GPU ne peut pas être mesurée (ROCm, Intel XPU), le tapis est créé et un avertissement indique qu'elle n'a pas été vérifiée. Un GPU Intel n'est remarqué que via xpu-smi ; sur un GPU sans cela, passez --device xpu.
• Téléchargement. Environ 20 Go supplémentaires sur le disque, dans le même répertoire de points de contrôle que le modèle principal (SOUND_DESIGN_ACESTEP_CHECKPOINTS ; un instantané du cache Hugging Face ne fonctionne pas pour XL). Sans cela, l'appel s'arrête avec MODEL_NOT_FOUND et error.details.install donne la ligne, par exemple uv run acestep-download --model acestep-v15-xl-turbo --dir .... Téléchargez-le et réessayez.

Exemples de code / intégration

Génération et bouclage

# Générer un tapis
sound-design generate-bgm --prompt "ambiance calme" --duration 30 -o calme.wav --json
# Créer une boucle de 8 s
sound-design loop-bed calme.wav -o calme_loop.wav --duration 8 --json

Importation et sélection depuis la bibliothèque

# Importer avec licence
sound-design library-import ma_piste.wav --library ./ma_biblio --licence CC0-1.0 --kind bgm --tags calme --json
# Sélectionner pour 60 s
sound-design library-pick ./ma_biblio --kind bgm --duration 60 -o sortie.wav --json

Feuille de repères SFX

sound-design sfx-cues --cuts 1.0,3.5 --emphasis 2.0 --library ./ma_biblio --min-spacing 0.5 -o repères.json --json

Son généré

# BGM
sound-design generate-bgm --prompt "jazz doux" --duration 45 -o jazz.wav --json
# SFX (après confirmation de l'utilisateur)
sound-design generate-sfx --prompt "un verre se brise" --duration 2 -o verre.wav --acknowledge-ezaudio-training-data --json

Notes supplémentaires sur les dépendances

• Python >= 3.9 requis ; recommandé Python 3.11-3.12 pour les moteurs ACE-Step et EzAudio.
• ffmpeg-skill nécessaire pour les opérations sur le son ; vérifiez qu'il est accessible.
• GPU : recommandé 4 Go+ pour ACE-Step 2B, 20 Go+ pour ACE-Step 4B XL. EzAudio-XL peut fonctionner sur GPU avec >= 8 Go.
• Stockage : les modèles peuvent occuper jusqu'à 30 Go (modèle XL inclus).

Cette compétence est conçue pour être intégrée à des pipelines d'agents IA, où elle fournit des sorties structurées (JSON) avec provenance, adaptées à une orchestration automatique.