captjt/skill-tts

Synthèse vocale (Text-to-Speech)

Lancez le lanceur à l'emplacement ${CLAUDE_SKILL_DIR}/scripts/tts, soit scripts/tts dans le répertoire de cette compétence. Ci-dessous, il sera écrit tts. La première exécution télécharge un binaire d'environ 7 Mo et vérifie son SHA-256 avant de l'exécuter.

Exécutez chaque commande tts comme un appel Bash distinct. Ne l'enchaînez pas avec ;, && ou des pipes, afin qu'elle reste couverte par l'autorisation pré-approuvée de la compétence.

Il y a deux tâches :

• Voix off pour vidéos : tts render. Produit des fichiers ainsi qu'un manifeste de synchronisation pour le reste du pipeline vidéo.
• Lecture à voix haute : tts "texte". Joue via les haut-parleurs et revient immédiatement.

Voix off pour vidéos

1. Écrire un script

Placez un segment par scène ou prise de vue, et réutilisez les identifiants de scène de la vidéo pour que l'audio et les visuels s'alignent :

{
  "provider": "elevenlabs",
  "voice": "JBFqnCBsd6RMkjVDRZzb",
  "instructions": "narrateur chaleureux et confiant pour un produit",
  "pause": 0.5,
  "segments": [
    {"id": "01-intro",   "text": "Découvrez le nouveau tableau de bord Insights."},
    {"id": "02-filters", "text": "Filtrez n'importe quel graphique en un clic : par équipe, par service ou par version."},
    {"id": "03-alerts",  "text": "Définissez une alerte une fois, et nous vous prévenons dès qu'une métrique dévie.", "pause": 1.0},
    {"id": "04-outro",   "text": "Insights est disponible dès aujourd'hui, sur tous les forfaits."}
  ]
}

• Les champs de premier niveau (provider, voice, model, instructions, speed, pause) s'appliquent à chaque segment. Chaque segment peut surcharger voice, model, instructions, speed et pause, qui définissent le silence après lui dans la piste combinée.
• Gardez un seul fournisseur et une seule voix pour toute la vidéo afin qu'elle sonne comme un seul narrateur.
• Écrivez pour l'oreille : phrases courtes, nombres en toutes lettres ("quarante pour cent", "version deux"), pas de markdown. Si un nom de produit est mal prononcé, épelez-le phonétiquement dans text.
• Choisir un fournisseur et une voix. Si le script ne définit pas de fournisseur et que tts config show n'a pas de voiceover_provider, demandez à l'utilisateur quel fournisseur et quelle voix utiliser. Pour leur permettre de comparer, rendez de courts échantillons avec tts -o sample-NOM.wav -p FOURNISSEUR -v VOIX "Une ligne du script.". Proposez de sauvegarder leur choix avec tts config set voiceover_provider NOM et tts config set NOM.voice VOIX. Kokoro et system sont gratuits et locaux ; les autres sont payants. ElevenLabs, OpenAI avec instructions, et Gemini offrent le rendu le plus naturel.

2. Rendre

"${CLAUDE_SKILL_DIR}/scripts/tts" render script.json -o voix_off/

Ceci écrit :

• voix_off/<id>.wav pour chaque segment, avec le silence de début et de fin supprimé pour que les durées soient exactes.
• voix_off/voix_off.wav, tous les segments joints avec leurs pauses.
• voix_off/voix_off.srt, sous-titres.
• voix_off/manifest.json, qui est également affiché sur la sortie standard :

{"provider": "elevenlabs", "sample_rate": 24000, "channels": 1, "duration": 17.08,
 "combined": {"file": "/abs/voix_off/voix_off.wav", "duration": 17.08},
 "captions": "/abs/voix_off/voix_off.srt",
 "segments": [{"id": "01-intro", "file": "/abs/voix_off/01-intro.wav", "duration": 3.872,
                "start": 0, "end": 3.872, "text": "...", "voice": "...", "cached": false}, ...]}

Options de rendu :

• --format mp3|m4a définit le format de la piste combinée.
• --no-combine écrit uniquement les fichiers par segment.
• -p/-v/-i/-s définissent les valeurs par défaut que le script ne spécifie pas.
• --jobs N définit le parallélisme.

render utilise le modèle de la plus haute fidélité de chaque fournisseur, sauf si un modèle est défini : eleven_multilingual_v2 et gemini-3.8-flash-tts.

3. Utiliser les synchronisations

• Longueurs des scènes : chaque scène doit durer au moins la duration de son segment. Ajoutez un temps de respiration, ou prolongez la scène pour correspondre.
• Placer l'audio : placez le fichier de chaque segment au début de sa scène, ou utilisez voix_off.wav comme piste unique avec start/end comme décalages.
• Muxage avec ffmpeg :
  • Piste entière : ffmpeg -i video.mp4 -i voix_off/voix_off.wav -map 0:v -map 1:a -c:v copy -c:a aac -shortest out.mp4
  • Un segment à 4.47 s : ajoutez l'entrée -i voix_off/02-filters.wav, puis -filter_complex "[1]adelay=4470:all=1[a]" -map 0:v -map "[a]".

4. Itérer

Modifiez le script et exécutez la même commande à nouveau. Les segments dont le texte, la voix, le modèle, le style et la vitesse n'ont pas changé sont réutilisés depuis le dernier rendu ("cached": true). Seuls les segments modifiés sont re-rendus et facturés. Utilisez --force pour tout re-rendre. Si certains segments échouent, les autres sont conservés, et une réexécution ne tente que les échecs.

Lecture à voix haute

"${CLAUDE_SKILL_DIR}/scripts/tts" "La compilation a réussi et les 214 tests sont verts."
"${CLAUDE_SKILL_DIR}/scripts/tts" <<'EOF'
Texte plus long, ou tout ce qui contient des guillemets, passe par l'entrée standard.
EOF

Ceci revient une fois que l'audio commence à jouer, et la lecture continue en arrière-plan. Une nouvelle parole interrompt la parole en cours ; -q la met en file d'attente, et tts stop coupe tout.

Autres options :

• -p fournisseur, -v voix, -i "style", -s vitesse.
• -w attend la fin de la lecture.
• -o FICHIER [--json] écrit un fichier au lieu de jouer. --json affiche sa durée et son chemin.

Lors de la lecture :

• Résumez ; ne récitez pas. Utilisez deux à quatre phrases parlées, sauf si on vous demande de lire le texte intégral.
• Décrivez le code en mots au lieu de le lire. Le markdown et les blocs de code sont automatiquement supprimés.
• Gardez les notifications courtes et utilisez -q pour une série d'entre elles.

Fournisseurs, coût et confidentialité

• Utilisez les valeurs par défaut configurées (tts config show). Passez -p uniquement lorsque l'utilisateur ou le script nomme un fournisseur.
• system et kokoro restent sur cette machine et sont gratuits. Les autres fournisseurs envoient le texte à cette entreprise et facturent le compte de l'utilisateur. Ne changez jamais le fournisseur par défaut sans demander.
• N'envoyez jamais de secrets, d'informations d'identification ou de données privées à un fournisseur cloud.
• Les fournisseurs payants refusent plus de 20 000 nouveaux caractères par commande. Raccourcissez le texte, ou passez --max-chars N si l'utilisateur veut tout.

Configuration et dépannage

• tts doctor affiche la sortie audio, le fournisseur par défaut et quels fournisseurs sont prêts.
• tts providers et tts voices -p NOM [filtre] listent les fournisseurs et les voix.
• tts config set CLE VALEUR définit les valeurs par défaut. Les clés sont provider, voiceover_provider, max_chars, et NOM.voice|model|speed|instructions|base_url.
• Clé API manquante : dites à l'utilisateur de définir la variable d'environnement (par ex. ELEVENLABS_API_KEY) ou d'exécuter tts auth set elevenlabs dans son propre terminal. Ne demandez jamais à l'utilisateur de coller une clé dans le chat, et ne mettez jamais une clé sur une ligne de commande.
• Fournisseurs cloud non testés : openai, gemini, cartesia et deepgram n'ont pas encore été testés avec leurs API en direct. Seuls system, kokoro et elevenlabs l'ont été. Si l'un d'eux échoue avec une erreur concernant la requête elle-même (champ inconnu, paramètre invalide ou réponse inattendue), il s'agit probablement d'un bogue dans cette compétence, pas de quelque chose que l'utilisateur a fait. Montrez à l'utilisateur l'erreur exacte, suggérez de la signaler sur github.com/captjt/skill-tts/issues, et proposez kokoro ou system comme solution de secours. Ne continuez pas à réessayer avec des paramètres devinés. Les erreurs d'authentification (401/403) et de quota (429) sont à corriger par l'utilisateur comme d'habitude.
• Kokoro inaccessible : démarrez-le avec docker run -d --name kokoro -p 8880:8880 ghcr.io/remsky/kokoro-fastapi-cpu:v0.9.0.
• Aucun périphérique audio (SSH, conteneurs) : utilisez render ou -o ; ils n'ont pas besoin de haut-parleurs.

Les voix, modèles et options pour chaque fournisseur se trouvent dans references/providers.md.