sound-skill (audio complète pour vidéo)

sound (version complète)

Chaîne d'outils complète pour sonoriser une vidéo, trois axes :

1. Sélection d'effets sonores — Recherche multi-sources, filtrage par signaux de retour humains, téléchargement, analyse.
2. BGM (musique de fond) — Deux voies : synthèse hors ligne de boucles sans couture, ou recherche de longs échantillons dans la bibliothèque.
3. Voix et mixage — Réduction de bruit / EQ / dé-esseur / compression, ducking side-chain, mixage statique, normalisation en deux passes.

Environnement : Python 3 + FFmpeg (ffmpeg / ffprobe dans le PATH). Bibliothèque standard uniquement, pas de paquets tiers, pas de clé API, pas de connexion.

Toutes les fonctionnalités de ce skill sont implémentées en open source dans ce dépôt (licence MIT) : toutes les commandes, règles, paramètres sont dans la documentation ci-dessous et dans references/, librement modifiables et distribuables.

Après installation, définissez les variables selon votre emplacement. Ci-dessous la syntaxe pour une installation dans le projet :

S=.claude/skills/sound/scripts/sfx.py       # Recherche / Téléchargement / Analyse
V=.claude/skills/sound/scripts/vocal.py     # Voix / Mixage
C=.claude/skills/sound/scripts/compose.py   # Synthèse BGM hors ligne

Pour une installation globale, remplacez .claude/skills/sound/ par ~/.claude/skills/sound/.

---

I. Sélection d'effets sonores

Flux de travail

1. Traduisez les actions visuelles en mots-clés anglais ("une carte qui entre" → short whoosh, "interrupteur basculé" → soft click).
2. all recherche sur toutes les sources ; si nécessaire, effectuez une recherche complémentaire sur une seule source ; --urls donne des liens d'écoute à l'utilisateur.
3. Évaluez d'abord si le son correspond à l'image, puis vérifiez la popularité ; donnez des candidats et une justification, ne confondez pas les chiffres avec "je l'ai écouté".
4. Selon l'usage, déterminez la licence, téléchargez, utilisez analyze pour vérifier la durée et la répartition de l'énergie.
5. Lors de la livraison, conservez l'URL source, l'auteur, la licence ; ajoutez les crédits pour les éléments non CC0.

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

Règles de sélection (en s'inspirant des signaux de retour humains)

• Nombre d'évaluations > note moyenne : ★4.4(380) est une preuve plus forte que ★4.9(6).
• Description de l'auteur la plus proche de l'écoute : "built-in mic" / "made with my mouth" indique une faible fidélité ; mentionner un enregistreur (Zoom, Sound Devices) et une source claire ("cork from a wine bottle") indique un son contrôlé. Si la source décrite ne correspond pas à l'image, même populaire, ne l'utilisez pas.
• La popularité n'implique pas l'adéquation : un "thud" très téléchargé peut être un grondement de film de 3 secondes. Vérifiez la durée, utilisez analyze pour voir où se trouve l'énergie et la longueur de la queue, puis décidez de couper ou non.
• Proposez d'abord des candidats, puis téléchargez : si l'utilisateur veut écouter, ajoutez --urls ; ne décidez pas à sa place.
• Signaux disponibles selon la source : Freesound a le nombre de téléchargements et d'évaluations ; Commons a la durée réelle et la licence ; Mixkit a la durée mais pas de popularité ; Kenney est un pack complet. Ne traitez pas les champs manquants comme des notes de 0.

Règles de licence (strictes, pas de relâchement)

Paramètre	Autorisé	Usage typique
--license cc0	Uniquement CC0 / PDM	Usage commercial, pas de crédit
--license by	CC0 / PDM / BY / BY-SA	Crédit acceptable (exclut BY-NC, BY-NC-SA, BY-ND)
--license any	Tout, mais les résultats indiquent la licence	Pour voir les candidats d'abord

• BY-NC jamais pour un usage commercial, les scripts l'excluent déjà avec cc0/by ; avec any, jugez vous-même.
• Mixkit utilise sa propre "Mixkit Free License" (utilisable commercialement sans crédit), mais n'appartient pas aux catégories CC0/BY, donc avec cc0/by elle sera exclue. Utilisez explicitement --license any et mentionnez le nom de la licence dans le livrable.
• Pour les éléments non CC0, get imprime l'auteur et un rappel de licence ; ce n'est qu'un indice, conservez la source et le texte de licence original dans le livrable.
• Kenney est entièrement CC0, mais le téléchargement est un zip complet, pas un fichier unique ; à décompresser et sélectionner.

Répartition des sources

Source	Points forts	Limitations
Freesound	Seul à avoir téléchargements/évaluations	Télécharge seulement l'aperçu MP3, pas le fichier original ; ~80 Ko/s par connexion
Wikimedia Commons	Durée réelle + licence complète, enregistrements d'ambiance/cloches/longs fichiers	Correspondance par description, les mots-clés bizarres peuvent ne rien trouver ; pas de popularité
Mixkit	Utilisable commercialement sans crédit, qualité stable pour interfaces	Structure de page à analyser ; pas de popularité ; durée indiquée en secondes entières
Kenney	Packs d'effets sonores CC0 pour jeux/interfaces	Zip complet, pas de durée individuelle

Détails de scraping et mappage des licences dans references/sources.md.

---

II. BGM : Synthèse ou fond sonore

D'abord, déterminez si l'utilisateur veut "de la musique" ou "un morceau qui correspond à l'ambiance" :

Scénario	Voie	Commande
Veut une boucle, zéro dépendance, ambiance contrôlée, sans risque de copyright	Synthèse hors ligne	compose.py
Veut des instruments réels/voix/ambiance	Recherche de fond	sfx.py music
A déjà un court BGM à étendre sur toute la durée	Boucle/coupe	vocal.py loop / trim

Synthèse hors ligne (recommandée, la vraie "synthèse 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 : nappes lentes (accords de fond), sans batterie, idéal pour commentaires/démos ; lofi : chorus désaccordé + kick/hat relâché + bruit de fond de bande ; upbeat : accords courts et brillants + grosse caisse quatre temps + ligne de basse.
• Sortie : 44,1 kHz / 16-bit / stéréo WAV, phase alignée début-fin + crossfade d'accords en anneau, boucle sans couture.
• La durée sera arrondie à la mesure entière la plus proche (ex. 30 s à 90 BPM donne en réalité 29,333 s) ; pour une durée exacte, utilisez un BPM divisible par 4 (ex. 120).
• Le script imprime une valeur suggérée de --bgm-gain (en dB) directement copiable, compatible avec les paramètres de vocal.py.
• --seed garantit une sortie identique avec les mêmes paramètres, utile pour la gestion de versions.

Recherche de fond

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 utilise la recherche filetype:audio de Commons, --duration long par défaut ≥30 secondes, durée inconnue exclue par défaut (utilisez --allow-unknown pour autoriser).
• Commons renvoie souvent des enregistrements d'ambiance/livres audio de plusieurs heures ; ajoutez impérativement --max-seconds 600 pour le fond, sinon des centaines de Mo seront téléchargés.
• Après téléchargement, il faut généralement trim pour extraire une section, ou loop pour étendre une courte section sur toute la durée de la vidéo.

---

III. Nettoyage vocal et mixage

Chaîne standard

# 1. Voix : Réduction de bruit → passe-haut → (dé-esseur) → compression → normalisation en deux passes → fondu
python3 $V clean voice.wav clean.wav --deesser
#    Cible -16 LUFS par défaut ; ajoutez --no-loudnorm pour désactiver la normalisation

# 2. BGM aligné sur la durée de la vidéo (choisir l'une des deux)
python3 $V loop  bgm.wav  bed.wav  --duration 30     # Court élément étendu, vrai crossfade à la jointure
python3 $V trim  bgm.wav  bed.wav  --start 0 --end 30

# 3. Mixage : baisse automatique du BGM quand on parle (ducking side-chain)
python3 $V duck clean.wav bed.wav mixed.wav --bgm-gain -12 --threshold -30 --ratio 8
#    Sans voix / ambiance pure : utilisez le mixage statique
python3 $V mix  bed.wav clean.wav mixed.wav --bgm-gain -18

# 4. Vérification / normalisation du volume final
python3 $V report mixed.wav
python3 $V loudnorm mixed.wav final.wav --target-lufs -16

Règles des paramètres

Paramètre	Défaut	Quand ajuster
--bgm-gain	duck -12 / mix -18 dB	Utilisez la valeur suggérée par compose.py ; si le BGM couvre la voix, baissez encore de 3 à 6 dB
--threshold	-30 dB	Le seuil du side-chain est un seuil de niveau, pas une détection de parole ; si la voix est très douce, passez à -36 ; si le BGM est fort, augmentez
--ratio	8	Si le ducking est trop marqué / perceptible, baissez à 4
--target-lufs	-16 LUFS	Pour discours/vidéo : -16 ; pour musique en streaming pur : -14 ; podcast : peut aller à -16
--true-peak	-1,5 dBTP	Modifiez selon la plateforme si elle a une limite claire
--fade	duck 0,3 / clean 0,05 s	Pour les débuts/fins de séquence, les jointures de boucle

• Ne mélangez pas les unités : I est en LUFS (loudness intégrée), TP en dBTP (pic vrai), LRA en LU (gamme de loudness) ; mean_volume est le niveau moyen en dBFS, clairement indiqué dans report, ne l'utilisez pas comme LUFS.
• duck / mix ajoutent tous deux apad (silence de remplissage) avec duration=longest, le BGM plus court que la voix ne sera pas coupé ; --duration permet de spécifier la durée finale.
• Les deux passes de loudnorm dans clean sont exécutées après toute la chaîne de pré-traitement, et les valeurs I/TP/LRA de la passe de mesure sont identiques à celles de la seconde passe ; les fondus sont placés avant loudnorm pour garantir que le signal mesuré est le même que l'entrée normalisée, sinon measured_* ne correspondra pas.
• La mesure interne de loudnorm peut différer d'environ 1 LU par rapport à ebur128 ; le script effectue une vérification en boucle fermée après le rendu et applique un gain correctif, imprimant « Correction en boucle fermée ±X.X dB » dans le résumé ; c'est une étape nécessaire pour atteindre la cible avec précision, ne la supprimez pas.
• Pour les éléments très courts / quasi-silencieux où aucun LUFS valide ne peut être mesuré, le script passe automatiquement à une seule passe de loudnorm et indique clairement « Une seule passe » dans la sortie ; la boucle fermée est alors automatiquement ignorée, sans ajouter de gain sur le silence.

Texte original de la chaîne de filtres, principe de la normalisation en deux passes et tableau de paramètres dans references/mixing.md.

---

IV. Recettes courantes

A. Démo produit de 30 secondes (100 % hors ligne, zéro échantillon)

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. Ajouter une ambiance réelle à une voix off existante

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. Juste un son de transition, utilisable commercialement

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. Enveloppe de volume suivant l'image (rendu Remotion)

Le mastering final utilise la chaîne FFmpeg ci-dessus ; les fondus image par image / ajustements de volume au tempo sont effectués pendant le rendu Remotion, voir references/remotion-audio.md.

---