ElevenLabs TTS vers MP3

Que fait ElevenLabs TTS vers MP3 ?

Convertit le texte d'un script en voix off MP3 via l'API Text-to-Speech d'ElevenLabs.

Valeurs par défaut

• ID vocal : K7ewtjKRNtwwt3lKQ6M0 (voix de marque Hoang — verrouillée) — remplaçable via la variable d'environnement ELEVENLABS_VOICE_ID ou --voice_id
• Modèle : eleven_v3 (le plus expressif, prend en charge les balises audio comme [excited], [whisper], [laugh] ; idéal pour le contenu narratif) — remplaçable via --model_id. Alternatives : eleven_multilingual_v2 (haute qualité, plus lent), eleven_turbo_v2_5 (rapide, légèrement plat), eleven_flash_v2_5 (le plus rapide)
• Format de sortie : mp3_44100_128 (44,1 kHz / 128 kbps) — remplaçable via --output_format
• Paramètres vocaux : stability=0.5, similarity_boost=0.75, style=0, use_speaker_boost=true (valeurs par défaut ElevenLabs)
• Table de prononciation : chargée automatiquement depuis assets/vn-pronunciation-map.json — désactivable avec --no-pronounce-map, ou pointer vers un autre fichier avec --pronounce-map path.json
• Limite de caractères : 5000 par requête (limite stricte ElevenLabs). Texte > 5000 caractères → le script se termine avec une erreur et demande à l'utilisateur de diviser manuellement.

Utilisation rapide

Depuis un fichier

uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
  --file path/to/script.txt \
  -o workspace/content/YYYY-MM-DD/voiceover.mp3

Depuis un texte en ligne

uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
  "Xin chào các bạn, hôm nay mình chia sẻ về AI Agent" \
  -o workspace/assets/elevenlabs/sample.mp3

Voix / modèle personnalisé

uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
  --file script.txt \
  --voice_id K7ewtjKRNtwwt3lKQ6M0 \
  --model_id eleven_turbo_v2_5 \
  -o output.mp3

Ajuster l'expressivité de la voix

uv run .claude/skills/mkt-elevenlabs-tts-to-mp3/scripts/text_to_mp3.py \
  --file script.txt \
  --stability 0.4 \
  --similarity_boost 0.8 \
  --style 0.2 \
  -o output.mp3

Paramètres vocaux — quand les ajuster

Paramètre	Plage	Effet
stability	0.0–1.0	Plus élevé = plus monotone/prévisible ; plus bas = plus émotionnel/variable. 0,5 est le point idéal pour la narration. Descendre à 0,3–0,4 pour des accroches décontractées ; monter à 0,7+ pour des explications formelles.
similarity_boost	0.0–1.0	Degré de fidélité au clonage de la voix de référence. 0,75 par défaut. Augmenter vers 0,9 si la voix semble "décalée" par rapport à l'originale.
style	0.0–1.0	Exagération du style. 0 par défaut. Ajoute de la latence quand > 0. Utile (0,1–0,3) pour du contenu expressif.
use_speaker_boost	bool	Affine la similarité du locuteur. Gardez true pour la cohérence de la voix de marque.

Table de prononciation (correction des mots anglais)

Les modèles multilingues d'ElevenLabs essaient de lire tout le texte dans la langue dominante. Dans un script vietnamien, les mots anglais comme doc, chat, git sont prononcés comme des syllabes vietnamiennes et sonnent faux. Pour corriger cela sans éditer manuellement chaque script, la compétence charge automatiquement une table de substitution insensible à la casse (mot entier) depuis assets/vn-pronunciation-map.json et l'applique avant d'envoyer le texte à l'API.

Mappage par défaut :

{
  "doc": "đóc",
  "chat": "chát",
  "git": "gít"
}

Comment ça marche : chaque clé est recherchée sans tenir compte de la casse avec des limites \b...\b, puis remplacée par la valeur phonétique vietnamienne. Le modèle voit "đóc" au lieu de "doc" et le prononce proche de /dɒk/. Cela n'affecte que l'audio — votre script source reste propre.

Curateur du dictionnaire — écoutez d'abord, ajoutez ensuite :

• Exécutez la compétence sur un court script de test contenant le mot candidat
• Si le modèle le lit déjà correctement, ne l'ajoutez pas (le surapprentissage cassera les choses)
• Attention aux collisions : ajouter "code" réécrirait aussi le Code dans Claude Code (nom de marque) → ne faites jamais cela
• Pour les noms de marque qui nécessitent une protection, laissez-les complètement de côté

Surcharge / désactivation :

# Utiliser une table personnalisée pour un projet spécifique
uv run scripts/text_to_mp3.py --file s.txt --pronounce-map workspace/.../map.json -o out.mp3

# Ignorer entièrement la substitution
uv run scripts/text_to_mp3.py --file s.txt --no-pronounce-map -o out.mp3

Le script imprime chaque substitution appliquée sur stderr (par ex. 'doc' -> 'đóc' (4x)) pour que vous puissiez vérifier ce qui a changé.

Flux de travail

1. Charger ELEVENLABS_API_KEY depuis le .env du projet
2. Lire le texte depuis --file ou l'argument positionnel, supprimer les espaces
3. Appliquer la table de prononciation (sauf si --no-pronounce-map) — remplacement insensible à la casse de mots entiers
4. Valider len(text) <= 5000
5. POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id}?output_format=mp3_44100_128
   • En-tête : xi-api-key: <key>, Content-Type: application/json, Accept: audio/mpeg
   • Corps :

     {
       "text": "...",
       "model_id": "eleven_v3",
       "voice_settings": {
         "stability": 0.5,
         "similarity_boost": 0.75,
         "style": 0,
         "use_speaker_boost": true
       }
     }
     

6. Diffuser les octets audio directement vers le MP3 de sortie (pas de transcodage nécessaire — le serveur renvoie du MP3)
7. Afficher output_path, size_mb, char_count, voice_id, model_id

Convention de sortie

• Court/test : workspace/assets/elevenlabs/<nom>.mp3
• Production vidéo : workspace/content/YYYY-MM-DD/video-short/<projet>/voiceover.mp3

Prérequis

• ELEVENLABS_API_KEY dans le .env du projet (authentification par en-tête : xi-api-key)
• ELEVENLABS_VOICE_ID optionnel dans .env pour verrouiller une voix par défaut différente
• Dépendances Python gérées via les métadonnées en ligne PEP 723 (installées automatiquement par uv run) : requests, python-dotenv
• Pas besoin de ffmpeg — ElevenLabs renvoie directement du MP3

Pourquoi pas de découpage en morceaux

ElevenLabs limite les requêtes à 5000 caractères. La compétence échoue rapidement au-dessus de cette limite au lieu de diviser automatiquement car :

• Une voix off unique doit être un morceau cohérent — une division en milieu de script provoque des sauts de prosodie aux points de concaténation
• Le contenu de l'utilisateur (accroches, scripts courts, segments vidéo) tient généralement bien en dessous de 5000 caractères
• Si l'utilisateur a vraiment besoin d'un audio plus long, il doit diviser le script sémantiquement (sauts de paragraphe) et appeler cette compétence pour chaque morceau, puis concaténer avec ffmpeg dans son propre pipeline

Référence API

• Point d'accès : POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id}
• Authentification : en-tête xi-api-key: <api_key>
• Catalogue des modèles : https://elevenlabs.io/docs/models
• Catalogue vocal (parcourir / obtenir les ID vocaux) : https://elevenlabs.io/app/voice-library
• Documentation API : https://elevenlabs.io/docs/api-reference/text-to-speech/convert
• Limites de taux : dépendent du niveau d'abonnement — voir https://elevenlabs.io/pricing
• Formats de sortie : mp3_44100_128 (par défaut), mp3_44100_192 (qualité supérieure, payant uniquement), pcm_44100, ulaw_8000 (téléphonie)