sfx-library

Bibliothèque d’effets sonores

834 fichiers / 63 catégories / ~1 Go. Un seul point d’entrée : le script sfx situé dans le même dossier que ce fichier SKILL.md. Le script détermine lui-même son propre chemin, il peut donc être appelé depuis n’importe où en utilisant le chemin complet — les exemples ci-dessous l’écrivent simplement sfx.

Étape 0 — vérification des données

Le dépôt ne contient que le code et le catalogue ; les fichiers audio se trouvent dans data/ (non commités).

sfx status

Si le message "Chua co du lieu" apparaît, il faut récupérer les données — une seule fois, ~1 Go, prévenez l’utilisateur avant de télécharger :

sfx setup

setup suit un ordre de priorité strict, ne pas inverser :

1. Google Drive en premier — télécharge un fichier .zip (~880 Mo, environ 1 minute), vérifie le sha256 puis décompresse.
2. Les URL présentes dans le catalogue sont la sauvegarde — uniquement si Drive échoue (404, fichier non partagé publiquement, limite de téléchargement dépassée, sha256 erroné). Dans ce cas, setup bascule automatiquement sur le téléchargement de chaque fichier via les URL dans catalog/source/*.json (séquentiel, ~18 minutes) et vérifie le sha256 avec catalog/meta.json.

Nécessite uniquement python3 (≥ 3.8), aucune autre installation requise. Si le téléchargement est interrompu, relancez sfx setup — il reprend là où il s’est arrêté, sans recommencer. L’étape de secours est lente : lancez-la en arrière-plan et informez l’utilisateur du temps d’attente.

N’appelez sfx setup --source (en contournant Drive) que si l’utilisateur le demande explicitement.

Si setup signale "Ca hai nguon deu that bai" (les deux sources ont échoué), exécutez sfx doctor et informez l’utilisateur — ne cherchez pas d’autres sources audio alternatives.

Recherche de SFX — la seule commande à retenir

sfx find "<mot-clé>"

Saisissez le texte en français avec ou sans accents, ou en anglais, vous obtiendrez les mêmes résultats — les accents sont supprimés avant la comparaison, et chaque catégorie dispose d’un ensemble de mots-clés bilingues prêts à l’emploi.

sfx find "transition"          # par intention
sfx find "notification" --max-dur 2
sfx find whoosh --group transition
sfx find --group impact --max-dur 1.5
sfx find riser --min-dur 3 --max-dur 5

Les résultats incluent la durée (en secondes) — l’information la plus importante pour faire correspondre un SFX à la timeline.

Option	Quand l’utiliser
--max-dur N / --min-dur N	pour contraindre la durée selon l’emplacement dans la timeline
--group <groupe>	pour parcourir toute une intention (voir le tableau des groupes ci-dessous)
--category <slug>	lorsque la catégorie exacte est déjà connue
--ext wav	pour ne récupérer que des wav (ou mp3)
--paths	pour n’afficher que les chemins, un par ligne — utilisable directement dans d’autres commandes
--json	sortie lisible par machine, incluant duration, sha256, score
--abs	chemins absolus — à utiliser lorsqu’on appelle sfx depuis un autre répertoire
-n N / --all	nombre de résultats (par défaut 20)

Une requête avec plusieurs mots est par défaut en AND ; si aucun fichier ne correspond à tous les mots, elle passe automatiquement en OR et l’indique clairement sur stderr.

Si vous ne savez pas quoi utiliser → sfx list affiche toutes les catégories avec leur "quand l’utiliser" et leurs mots-clés.

10 groupes par intention

Choisissez d’abord le groupe, puis filtrez — c’est plus rapide que de deviner le nom de la catégorie.

Groupe	Utilisation	Catégories typiques
transition	relier deux scènes	fast-whoosh swoosh-swish whip zoom reverse
impact	marquer une idée, afficher des données	hit boom impacts slam bass
ui	apparition de texte, clics, frappes	pop click typing ui-mini tick shine
alert	notifications, rappels	notification ding bell alarm
tension	montée en puissance avant le climax	riser builder braam tension trailer
ambience	fond sonore continu	ambience environment
foley	objets réels	paper doors footsteps liquid draw camera-shutter
comedy	humour	comedy-cartoon memes
scifi	technologie, fantastique	technology glitch laser magic data
horror	horreur	horror jumpscare

Écouter avant de choisir

Le nom du slug ne suffit pas pour deviner à quoi ressemble un fichier. whoosh-fast-05 et whoosh-fast-06 peuvent être radicalement différents en termes de texture.

afplay "$(sfx find whoosh --paths --abs -n 1)"     # macOS ; Linux : ffplay -nodisp -autoexit

Si l’écoute est impossible (exécution headless), proposez 2–3 options avec leur durée à l’utilisateur pour qu’il choisisse, ne décidez pas seul et n’affirmez pas que le choix est pertinent.

Intégration d’un SFX dans une vidéo

sfx mix video.mp4 -o video-avec-son.mp4 \
    2.4:fast-whoosh/whoosh-fast-05.wav \
    5.0:ding/[email protected]

Chaque cue est de la forme <seconde>:<chemin>[@volume]. Le chemin est relatif à data/sfx/, ou vous pouvez simplement donner le nom du fichier s’il n’y a pas de conflit. Le volume par défaut est 0.6. Nécessite ffmpeg.

• L’audio existant dans la vidéo est conservé et mixé, il n’est pas écrasé — il est donc sûr d’exécuter sfx mix après avoir ajouté une voix-off.
• Utilise amix=normalize=0 + alimiter : l’ajout d’un cue ne réduit pas le volume original, et il n’y a pas d’écrêtage lorsque plusieurs sources se superposent.
• --dry-run affiche la commande ffmpeg, utile pour l’intégration dans un autre script.

Vidéo générée à partir de HTML (capture d’écran avec Playwright/Puppeteer/Remotion) : les balises <audio> ou new Audio().play() dans la page ne sont audibles que lorsqu’on les consulte dans un navigateur — elles ne sont pas incluses dans le fichier MP4 enregistré. Ajoutez les SFX à l’étape ffmpeg avec sfx mix, en utilisant les repères temporels de l’animation de la timeline.

Trois éléments qui déterminent si une vidéo sonne professionnellement :

1. Le SFX doit être plus court que l’emplacement dans la timeline — filtrez avec --max-dur dès le début plutôt que de couper après.
2. Placez le SFX exactement à l’image du mouvement, pas au début de la scène — un whoosh doit démarrer au moment précis où l’objet commence à bouger.
3. Ne superposez pas de SFX sur les dialogues. S’il y a une voix-off, réduisez à @0.3 ou utilisez la catégorie ui-mini.

Trois erreurs courantes

1. Ne commitez pas data/ — ~1 Go, déjà dans gitignore, récupérable avec sfx setup.
2. Ne modifiez pas les fichiers dans data/sfx/. Ce sont les originaux ; pour couper ou normaliser le volume, exportez les résultats ailleurs.
3. N’appelez pas directement sfx download pour la première récupération des données. Cela télécharge les 834 fichiers un par un, c’est lent et c’est une solution de secours. Utilisez toujours sfx setup pour que Google Drive soit essayé en premier.

Vérification en cas de problème : sfx doctor (outils + source de données), sfx verify --hash (recalcule le sha256 de chaque fichier).

Maintenance de la bibliothèque (ajout de catégorie, reconditionnement, changement de lien Drive) : voir README.md.