Skill de génération vocale

Générez de l'audio parlé pour le projet actuel (narration, voix-off de démo produit, messages IVR, lectures accessibles). Par défaut gpt-4o-mini-tts-2025-12-15 et voix intégrées, avec préférence pour le CLI fourni afin d'obtenir des exécutions déterministes et reproductibles.

Quand l'utiliser

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

Arbre de décision (unique vs lot)

Si l'utilisateur fournit plusieurs lignes/prompts ou souhaite de nombreuses sorties -> lot
Sinon -> unique

Flux de travail

Déterminez l'intention : unique vs lot (voir l'arbre de décision ci-dessus).
Collectez les entrées à l'avance : texte exact (verbatim), voix souhaitée, style de livraison, format et toute contrainte.
Si lot : écrivez un JSONL temporaire sous tmp/ (une tâche par ligne), exécutez une fois, puis supprimez le JSONL.
Augmentez les instructions en une spécification courte et étiquetée sans réécrire le texte d'entrée.
Exécutez le CLI fourni (scripts/text_to_speech.py) avec des valeurs par défaut sensées (voir references/cli.md).
Pour les clips importants, validez : intelligibilité, cadence, prononciation et respect des contraintes.
Itérez avec un seul changement ciblé (voix, vitesse ou instructions), puis revérifiez.
Enregistrez/retournez les sorties finales et notez le texte final + instructions + flags utilisés.

Conventions temp et sortie

Utilisez tmp/speech/ pour les fichiers intermédiaires (par exemple, les lots JSONL) ; supprimez-les une fois terminé.
Écrivez les artefacts finaux sous output/speech/ quand vous travaillez dans ce repo.
Utilisez --out ou --out-dir pour contrôler les chemins de sortie ; gardez les noms de fichiers stables et descriptifs.

Dépendances (installer si manquant)

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

Packages 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, donnez à l'utilisateur ces étapes :

Créez une clé API dans l'interface OpenAI platform : https://platform.openai.com/api-keys
Définissez OPENAI_API_KEY comme variable d'environnement dans leur système.
Proposez de les guider à travers la configuration de la variable d'environnement pour leur OS/shell si nécessaire.

Ne demandez jamais à l'utilisateur de coller la clé complète dans le chat. Demandez-lui de la définir localement et confirmez quand il est prêt.

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

Valeurs par défaut et règles

Utilisez 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 lumineux, préférez marin.
Voix intégrées uniquement. Les voix personnalisées ne sont pas incluses dans ce skill.
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 requête. Divisez le texte plus long en blocs.
Imposez 50 requêtes/minute. Le CLI plafonne --rpm à 50.
Exigez OPENAI_API_KEY avant tout appel API en direct.
Fournissez une divulgation claire aux utilisateurs finaux que la voix est générée par IA.
Utilisez le SDK Python OpenAI (package openai) pour tous les appels API ; n'utilisez pas le HTTP brut.
Préférez le CLI fourni (scripts/text_to_speech.py) plutôt que d'écrire de nouveaux scripts ponctuels.
Ne modifiez jamais scripts/text_to_speech.py. Si quelque chose manque, demandez à l'utilisateur avant de faire quoi que ce soit d'autre.

Augmentation d'instructions

Reformatez la direction de l'utilisateur en une spécification courte et étiquetée. Ne rendez explicites que les détails implicites ; n'inventez pas 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, cadence régulière, ton amical).
N'introduisez pas une nouvelle persona, accent ou style émotionnel que l'utilisateur n'a pas demandé.

Modèle (inclure uniquement les lignes pertinentes) :

Voice Affect: <caractère global et texture 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 de cadence ou de rythme>

Règles d'augmentation :

Gardez-le court ; ajoutez uniquement les détails que l'utilisateur a déjà implicitement fournis ou mentionnés ailleurs.
Ne réécrivez pas le texte d'entrée.
Si un détail critique manque et bloque le succès, posez une question ; sinon, procédez.

Exemples

Exemple unique (narration)

Texte d'entrée : "Bienvenue à la démo. Aujourd'hui, nous allons vous montrer comment cela fonctionne."
Instructions :
Voice Affect: Chaleureux et composé.
Tone: Amical et confiant.
Pacing: Régulier et modéré.
Emphasis: Insistez sur « démo » et « montrer ».

Exemple de lot (messages IVR)

{"input":"Merci d'avoir appelé. Veuillez patienter.","voice":"cedar","response_format":"mp3","out":"hold.mp3"}
{"input":"Pour les ventes, appuyez sur 1. Pour le support, appuyez sur 2.","voice":"marin","instructions":"Tone: Clair et neutre. Pacing: Lent.","response_format":"wav"}

Bonnes pratiques d'instructioning (courte liste)

Structurez les directions comme suit : affect -> tone -> pacing -> emotion -> pronunciation/pauses -> emphasis.
Gardez 4 à 8 lignes courtes ; évitez les conseils contradictoires.
Pour les noms/acronymes, ajoutez des indices de prononciation (par exemple, « enunciate A-I ») ou fournissez une orthographe phonétique dans le texte.
Pour les modifications/itérations, répétez les invariants (par exemple, « gardez une cadence régulière ») pour réduire la dérive.
Itérez avec des suivi à changement unique.

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

Conseils par cas d'usage

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

Narration / explication : references/narration.md
Démo produit / voix-off : references/voiceover.md
IVR / messages téléphoniques : references/ivr.md
Lectures accessibles : references/accessibility.md

Notes CLI et environnement

Commandes CLI + exemples : references/cli.md
Référence rapide des paramètres API : references/audio-api.md
Modèles d'instructions + exemples : references/voice-directions.md
Si les approbations réseau / paramètres de 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, flags, recettes).
references/audio-api.md: paramètres API, limites, liste des voix.
references/voice-directions.md: modèles d'instructions et exemples.
references/prompting.md: bonnes pratiques d'instructioning (structure, contraintes, modèles d'itération).
references/sample-prompts.md: recettes d'instructions à copier/coller (exemples uniquement ; pas de théorie supplémentaire).
references/narration.md: modèles + valeurs par défaut pour narration et explications.
references/voiceover.md: modèles + valeurs par défaut pour voix-off de démo produit.
references/ivr.md: modèles + valeurs par défaut pour messages IVR/téléphoniques.
references/accessibility.md: modèles + valeurs par défaut pour lectures accessibles.
references/codex-network.md: dépannage environnement/sandbox/approbations réseau.