Compétence Génération Vocale

Générer de l'audio parlé pour le projet actuel (narration, voix off de démonstration produit, invites IVR, lectures d'accessibilité). Utilise par défaut gpt-4o-mini-tts-2025-12-15 et les voix intégrées, et préfère l'interface de ligne de commande fournie pour des exécutions déterministes et reproductibles.

Quand l'utiliser

Générer un seul clip parlé à partir de texte
Générer un lot d'invites (plusieurs lignes, plusieurs fichiers)

Arbre de décision (simple vs lot)

Si l'utilisateur fournit plusieurs lignes/invites ou souhaite plusieurs résultats -> lot
Sinon -> simple

Flux de travail

Décider de l'intention : simple vs lot (voir l'arbre de décision ci-dessus).
Recueillir les entrées à l'avance : texte exact (littéral), voix souhaitée, style de livraison, format et contraintes.
Si lot : rédiger un JSONL temporaire sous tmp/ (un travail par ligne), exécuter une fois, puis supprimer le JSONL.
Augmenter les instructions en une spécification courte étiquetée sans réécrire le texte d'entrée.
Exécuter l'interface de ligne de commande fournie (scripts/text_to_speech.py) avec des valeurs par défaut sensées (voir references/cli.md).
Pour les clips importants, valider : l'intelligibilité, le rythme, la prononciation et le respect des contraintes.
Itérer avec un seul changement ciblé (voix, vitesse ou instructions), puis revérifier.
Enregistrer/retourner les résultats finaux et noter le texte final + instructions + drapeaux utilisés.

Conventions temp et résultats

Utiliser tmp/speech/ pour les fichiers intermédiaires (par exemple les lots JSONL) ; supprimer une fois terminé.
Écrire les artefacts finaux sous output/speech/ lors de travaux dans ce repo.
Utiliser --out ou --out-dir pour contrôler les chemins de résultats ; garder les noms de fichiers stables et descriptifs.

Dépendances (installer si manquantes)

Préférer uv pour la gestion des dépendances.

Paquets Python :

uv pip install openai

Si uv n'est pas disponible :

python3 -m pip install openai

Environnement

OPENAI_API_KEY doit être défini pour les appels API en direct.

Si la clé est manquante, donner à l'utilisateur ces étapes :

Créer une clé API dans l'interface utilisateur de la plateforme OpenAI : https://platform.openai.com/api-keys
Définir OPENAI_API_KEY comme variable d'environnement dans leur système.
Proposer de les guider dans la définition de la variable d'environnement pour leur OS/shell si nécessaire.

Ne jamais demander à l'utilisateur de coller la clé complète dans le chat. Lui demander de la définir localement et de confirmer quand il est prêt.

Si l'installation n'est pas possible dans cet environnement, dire à l'utilisateur quelle dépendance est manquante et comment l'installer localement.

Valeurs par défaut et règles

Utiliser gpt-4o-mini-tts-2025-12-15 sauf si l'utilisateur demande un autre modèle.
Voix par défaut : cedar. Si l'utilisateur souhaite un ton plus clair, préférer marin.
Voix intégrées uniquement. Les voix personnalisées sont hors de portée pour cette compétence.
Les instructions sont supportées pour les modèles GPT-4o mini TTS, mais pas pour tts-1 ou tts-1-hd.
La longueur d'entrée doit être <= 4096 caractères par demande. Diviser le texte plus long en chunks.
Imposer 50 demandes/minute. L'interface de ligne de commande plafonne --rpm à 50.
Exiger OPENAI_API_KEY avant tout appel API en direct.
Fournir une divulgation claire aux utilisateurs finaux que la voix est générée par IA.
Utiliser le kit de développement logiciel OpenAI Python (openai package) pour tous les appels API ; ne pas utiliser HTTP brut.
Préférer l'interface de ligne de commande fournie (scripts/text_to_speech.py) à l'écriture de nouveaux scripts ponctuels.
Ne jamais modifier scripts/text_to_speech.py. Si quelque chose manque, demander à l'utilisateur avant de faire quoi que ce soit d'autre.

Augmentation des instructions

Reformater les directives de l'utilisateur en une spécification courte étiquetée. Rendre explicites uniquement les détails implicites ; ne pas inventer de nouvelles exigences.

Clarification rapide (augmentation vs invention) :

Si l'utilisateur dit « narration pour une démo », vous pouvez ajouter des contraintes de livraison implicites (clair, rythme régulier, ton amical).
Ne pas introduire un nouveau personnage, accent ou style émotionnel que l'utilisateur n'a pas demandé.

Modèle (inclure uniquement les lignes pertinentes) :

Voice Affect: <caractère et texture générale de la voix>
Tone: <attitude, formalité, chaleur>
Pacing: <lent, régulier, rapide>
Emotion: <émotions clés à transmettre>
Pronunciation: <mots à énoncer ou à mettre l'accent>
Pauses: <où ajouter des pauses intentionnelles>
Emphasis: <mots ou phrases clés à souligner>
Delivery: <notes sur la cadence ou le rythme>

Règles d'augmentation :

Garder court ; ajouter uniquement des détails que l'utilisateur a déjà implicitement fournis ou fournis ailleurs.
Ne pas réécrire le texte d'entrée.
Si un détail critique est manquant et bloque le succès, poser une question ; sinon procéder.

Exemples

Exemple simple (narration)

Texte d'entrée : "Welcome to the demo. Today we'll show how it works."
Instructions :
Voice Affect: Warm and composed.
Tone: Friendly and confident.
Pacing: Steady and moderate.
Emphasis: Stress "demo" and "show".

Exemple lot (invites IVR)

{"input":"Thank you for calling. Please hold.","voice":"cedar","response_format":"mp3","out":"hold.mp3"}
{"input":"For sales, press 1. For support, press 2.","voice":"marin","instructions":"Tone: Clear and neutral. Pacing: Slow.","response_format":"wav"}

Meilleures pratiques d'instruction (liste courte)

Structurer les directives comme : affect -> ton -> rythme -> émotion -> prononciation/pauses -> emphase.
Garder 4 à 8 lignes courtes ; éviter les directives conflictuelles.
Pour les noms/acronymes, ajouter des indices de prononciation (par exemple, « enunciate A-I ») ou fournir une transcription phonétique dans le texte.
Pour les éditions/itérations, répéter les invariants (par exemple, « garder le rythme régulier ») pour réduire la dérive.
Itérer avec des suites à changement unique.

Plus de principes : references/prompting.md. Spécifications à copier/coller : references/sample-prompts.md.

Conseils par cas d'utilisation

Utiliser ces modules quand la demande concerne un style de livraison spécifique. Ils fournissent des valeurs par défaut et des modèles ciblés.

Narration / explainer : references/narration.md
Démo produit / voix off : references/voiceover.md
IVR / invites téléphoniques : references/ivr.md
Lectures d'accessibilité : references/accessibility.md

Notes sur l'interface de ligne de commande et l'environnement

Commandes de l'interface de ligne de commande + exemples : references/cli.md
Référence rapide des paramètres API : references/audio-api.md
Modèles d'instruction + exemples : references/voice-directions.md
Si les approbations réseau / paramètres sandbox posent problème : references/codex-network.md

Carte de référence

references/cli.md : comment exécuter la génération vocale/lots via scripts/text_to_speech.py (commandes, drapeaux, recettes).
references/audio-api.md : paramètres API, limites, liste des voix.
references/voice-directions.md : modèles d'instruction et exemples.
references/prompting.md : meilleures pratiques d'instruction (structure, contraintes, modèles d'itération).
references/sample-prompts.md : recettes d'instruction à copier/coller (exemples uniquement ; pas de théorie supplémentaire).
references/narration.md : modèles + valeurs par défaut pour narration et explainers.
references/voiceover.md : modèles + valeurs par défaut pour voix off de démos produit.
references/ivr.md : modèles + valeurs par défaut pour invites IVR/téléphoniques.
references/accessibility.md : modèles + valeurs par défaut pour lectures d'accessibilité.
references/codex-network.md : dépannage environnement/sandbox/approbations réseau.