Script et voix
La voix est l'horloge de la vidéo. Chaque battement de l'animation est ancré à un mot de la
narration (T[clip] + w(clip, "mot") dans build.py), donc le script et ses clips précèdent
l'animation, et modifier une phrase régénère un seul clip et re-calibre tout ce qui le suit. Dans la
production d'où viennent ces compétences, changer tout le moteur TTS a re-calibré une vidéo terminée sans
éditions manuelles grâce à cette conception. Animer d'abord et adapter la voix après implique
d'étirer l'audio ou de décaler les battements à la main à chaque modification.
Écrivez uniquement sous <video_dir>/audio/ (plus la section script de BRIEF.md). Chaque phrase doit
être soutenue par TRUTH.md et respecter CLAIMS.md ; si une phrase nécessaire n'a pas de source,
demandez qu'elle soit vérifiée ou supprimez-la.
Scripts, appelés comme dans docs/contracts.md :
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
S="$PVS_HOME/skills/script-and-voice/scripts"
"$PVS_HOME/bin/pvs-py" "$S/check_script.py" <video_dir> # lint lines.tsv
"$PVS_HOME/bin/pvs-py" "$S/tts.py" <video_dir> [--only N3,N4] [--provider say] [--force] [--restore]
"$PVS_HOME/bin/pvs-py" "$S/pronounce_check.py" <video_dir> [--only N3] # la RAS a-t-elle entendu les mots de marque ?
"$PVS_HOME/bin/pvs-py" "$S/make_sfx.py" <video_dir> [--list] # sfx.tsv, ou liste de la bibliothèque
1. Le script est une table de moments
Un enregistrement du produit est une référence, pas une ligne temporelle : les temps d'attente réels et les changements d'écran n'ont pas leur place dans la vidéo. Écrivez le script comme des moments, chacun avec ce qui se passe à l'écran, la phrase (ou le silence) et sa durée. Un moment dure aussi longtemps que la plus longue de son action et de sa phrase. Comprimez les attentes réelles : quarante secondes de chargement deviennent environ deux secondes d'un état de réflexion.
Ajoutez la table à BRIEF.md sous ## Script, dans l'ordre des chapitres :
| Moment | À l'écran | Ligne | Texte (ou silence) | Tient |
|---|---|---|---|---|
| Ouverture | Nom du produit sur l'app floue | N1 | Voici Acme Tasks, la liste de tâches qui planifie votre journée. | 0,8 s après |
| Attente | Le plan est en cours d'élaboration | (silence) | 2,0 s |
Choisissez ensuite le modèle pour le format de la vidéo et suivez sa structure : lisez
references/script-templates.md (pitch, visite, page de doc, tutoriel, boucle silencieuse).
Comment écrire les lignes, et pourquoi :
- Expliquez les fonctionnalités importantes ; ne les listez pas. Dites ce qu'une fonction fait pour le spectateur pendant que l'interface utilisateur l'exécute. Dans la production d'où viennent ces compétences, 9 versions sur 26 ont été faites parce qu'une vidéo nommait une fonction sans l'expliquer. COVERAGE.md indique quelles fonctionnalités doivent être expliquées à l'écran : chaque ligne marquée « doit expliquer » nécessite au moins une ligne qui l'explique.
- Expliquez chaque étape à quelqu'un qui n'a jamais vu le produit. Qui est le personnage, ce qu'il demande, ce que fait chaque étape. Une ouverture rapide et non expliquée a été rejetée en révision.
- Une idée par phrase et une phrase par clip. Une phrase modifiée ne coûte alors qu'un clip.
- Nommez ce que le curseur touche au moment où il le touche. Les battements s'ancrent sur ces mots, donc le nom à l'écran et le mot dans le clip doivent être les mêmes.
- Utilisez le vrai libellé de l'interface utilisateur, même si le relecteur utilise un autre mot. La vidéo correspond alors à ce que le spectateur verra dans le produit.
- Écrivez les nombres et les heures en toutes lettres (« dix heures », « trente minutes plus tard »). Les moteurs TTS lisent les chiffres de manière incohérente et la comparaison parole-texte compare les mots, pas les chiffres.
- Laissez de l'air autour des attentes. Environ trois secondes avant qu'un téléphone sonne, « environ une minute » au lieu d'un nombre précis que personne ne peut vérifier.
- Terminez sur une phrase complète, lue un peu plus lentement. Un fragment de slogan comme dernière ligne a semblé coupé en révision ; une phrase complète avec le positionnement de CLAIMS.md ne l'a pas fait.
- Gardez la personne cohérente dans une vidéo : première personne comme l'utilisateur fictif (« D'abord, je connecte mon calendrier. ») ou troisième personne à son sujet. Utilisez uniquement la distribution fictive de product.yaml, avec le même nom dans chaque vidéo.
- Le positionnement vient de CLAIMS.md, pas des documents source : un document source peut contenir une phrase que l'équipe a bannie, et la règle l'emporte.
2. lines.tsv
audio/lines.tsv, séparé par tabulations, en-tête id role speed text, un clip par ligne dans
l'ordre de lecture, les lignes # sont des commentaires. Format complet et comment build.py lit le
résultat : references/audio-formats.md.
- id :
N1,N2,N7bpour la narration ; d'autres lettres pour les personnages (A1pour un agent,C1pour un client). Insérer une ligne entre N7 et N8 commeN7blaisse tous les autres id, et chaque ancrage qui les utilise, stables. - role : une clé de
voice.rolesdans product.yaml (narrator,agent,customer, ou une variante de lecture telle quenarrator_close, voir section 3). Le rôle, pas l'id, choisit la voix. - speed : 1.0 par défaut, de 0.7 à 1.2. Utilisez 0.9 à 0.96 pour les lignes d'ouverture et de fermeture.
- text : exactement comme il apparaît à l'écran et dans les sous-titres, avec l'orthographe canonique des noms de produits. N'écrivez jamais de respelling ici ; la prononciation vit dans product.yaml.
Avant de modifier les lignes d'une version livrée, copiez lines.tsv en lines-v<N>.tsv et
timings.json en timings-v<N>.json, afin que la version précédente puisse être reconstruite.
Exécutez check_script.py après chaque modification. Il échoue en cas d'ids en double, de rôles
inconnus, de vitesses hors plage, de clips de plus de 40 mots, de termes bannis, d'expressions
"never_say", de noms hérités et de respellings dans le script, et avertit pour les clips longs,
les chiffres et les tirets. Corrigez chaque erreur avant de vocaliser : une phrase bannie qui
atteint le TTS coûte une prise, et une qui atteint un rendu coûte une version.
3. Casting
Lisez references/casting-and-pronunciation.md avant de proposer des voix. En résumé :
- Proposez d'abord des voix réalistes. La voix par défaut du produit et les modèles les moins chers ont été jugés « très faux » en révision ; le modèle le plus naturel disponible en vaut la peine pour les personnages.
- Auditionnez en contexte : deux vraies lignes consécutives par rôle, trois à six candidats par rôle.
- Proposez chaque choix pour véto comme une question fermée avec un défaut recommandé (« Narrateur : voix B, chaleureuse et posée. On garde ? »). Les listes ouvertes d'options sont restées sans réponse pendant des jours.
- Décidez du traitement par rôle :
treatment: phonepour quelqu'un en appel,treatment: roompour une réunion enregistrée, rien pour le narrateur. - Une lecture par ligne (plus stable, plus lente, moins de style) est une variante de rôle qui pointe vers la même voix avec d'autres réglages, de sorte que le choix est dans la configuration et survit à une ré-exécution.
voice.provider: say (ou --provider say) utilise la voix macOS gratuite et whisper pour les
synchronisations de mots. Utilisez-la pour les brouillons, les tests et le travail de timing avant
qu'une clé n'existe ; livrez avec la vraie voix.
4. Générer les clips
"$PVS_HOME/bin/pvs-py" "$S/tts.py" <video_dir>
Pour chaque ligne, il respelle les mots de marque uniquement pour le TTS, conserve la prise non
retouchée dans audio/raw/ (la prise précédente passe dans audio/raw/prev/), coupe le silence,
rééchantillonne en 48 kHz mono, applique le traitement du rôle, normalise selon voice.clip_lufs
(ffmpeg loudnorm, deux passes ; pics sous -1,5 dBTP), fond les deux bords, et fusionne l'entrée du
clip dans audio/timings.json.
Pourquoi chaque étape de traitement existe :
- Les prises brutes sont toujours archivées et toujours la source. Un client précédent normalisait à partir d'un fichier brut obsolète après un rendu complet ; ici, un clip est toujours reconstruit à partir de la prise qui l'a produit.
- La queue est coupée au maximum 0,6 s après le dernier mot, avec un fondu. Une prise TTS peut se terminer par un clic ou le début d'une autre phrase ; un tel clic a été livré comme un « coupe étrange » dans l'audio.
- Tous les clips au même volume. Une voix de personnage sortait 6 dB plus fort que le narrateur avant normalisation.
- Les lignes inchangées sont ignorées (hachage du texte, de la voix et des réglages dans
audio/raw/cache.json), donc une exécution complète après modification d'une ligne appelle le fournisseur une fois. Si seulclip_lufsou le traitement a changé, les clips sont reconstruits à partir des prises archivées gratuitement.--forcedemande une nouvelle prise quand même.
La clé est lue par le script depuis l'environnement ou PVS_HOME/.env et jamais affichée. Ne lisez
jamais .env vous-même et ne demandez jamais la clé dans le chat : si elle manque, dites à
l'utilisateur d'ajouter la ligne lui-même dans .env, ou passez à say.
Exécutez pronounce_check.py après toute nouvelle prise. Il transcrit chaque clip sans inciter
le RAS, signale les mots de marque et de distribution non reconnus, les noms hérités qui ont été
entendus, et les voyelles qui ont dérivé (section 5). Un signal signifie écouter, pas régénérer :
les RAS confondent des mots de marque qui ont été bien prononcés.
5. Prononciation
Le script et l'écran gardent l'orthographe réelle. product.pronounce modifie uniquement ce qui
est envoyé au TTS, et tts.py réassocie les timings, donc timings.json contient le mot affiché
à l'écran dans w et le respelling dans say ({"w": "Acme", "say": "AK-mee", ...}). Les
ancres dans build.py utilisent le mot affiché à l'écran.
product:
pronounce:
Acme: AK-mee # respelling simple
Acme Tasks: {say: AK-mee Tasks, vowel: ae, confusable: ey} # avec vérification de la première voyelle
Lorsqu'un relecteur dit que le nom sonne faux, essayez trois ou quatre respellings sur une ligne,
mesurez-les avec la vérification de voyelle, gardez celui qui réussit, puis vérifiez toutes les
autres lignes contenant le mot : les fournisseurs varient par prise. Détails et table des voyelles :
references/casting-and-pronunciation.md.
6. Prises
- Au maximum deux prises par ligne sauf si l'utilisateur dit autrement ; les quotas de fournisseur sont généralement partagés entre une équipe. Dites combien de caractères une exécution complète coûtera avant de l'exécuter.
- Régénérez uniquement la ligne qui en a besoin :
tts.py <video_dir> --only N7 --force. - Si la nouvelle prise est pire,
--only N7 --restorela remplace avec ses timings. - Pour une note de ton (« trop enthousiaste », « ça ressemble à une demi-phrase »), faites deux ou trois variantes comme variantes de rôle ou changements de vitesse, et laissez le relecteur les comparer en contexte avec la ligne précédente.
- Modifier une ligne, dans l'ordre : copiez les fichiers de version, modifiez la ligne,
check_script.py,tts.py --only <id>,pronounce_check.py --only <id>, puis le compositeur reconstruit ; tout ce qui suit ce clip se déplace tout seul.
7. Effets sonores
Utilisez uniquement des sons enregistrés, issus de la bibliothèque fournie avec HyperFrames
(make_sfx.py --list). La frappe synthétisée sonnait « comme une paille, pas un clavier » et un
whoosh synthétisé comme « bruit blanc » en révision, donc les whooshes et les crescendos sont
refusés par le script, et rien ne passe sous la narration comme musique sauf si le brief le
demande. La production d'où viennent ces compétences a été livrée sans fond musical et sans
ducking, et personne ne l'a regretté.
- Frappe :
typing_track(text, start, cps)construit une piste à partir de frappes individuelles découpées d'un enregistrement réel, avec un appui plus fort sur les espaces et un rythme basé sur une graine, de sorte qu'elle est déterministe et que le même texte sonne toujours de la même manière. Faites-la durer exactement aussi longtemps que le battement qui montre le texte (dur=), et laissez les mots tapés atterrir sur les mots prononcés. - Clics et pops :
library_sfx("click", start)sur l'image où le curseur appuie. audio/sfx/CREDITS.mdliste chaque fichier de bibliothèque utilisé et porte la licence de la bibliothèque.- Niveaux suggérés : narration 1.0, personnages 1.0, clics 0.35 (0.22 lors du relâchement d'un glisser), frappe 0.45, pops 0.12 à 0.3. Deux clips sur la même piste audio ne doivent jamais se chevaucher : commencez un clip au moins 0,02 s après la fin du précédent, ou déplacez-le sur une autre piste.
build.py importe les fonctions ; make_sfx.py <video_dir> avec un audio/sfx.tsv pré-construit
les mêmes fichiers depuis la ligne de commande (format dans le docstring du script).
8. Transfert au compositeur
Livrez, sous <video_dir>/audio/ : lines.tsv, clips/<id>.wav, timings.json, et sfx/
avec CREDITS.md. Dites au compositeur à quels mots chaque battement doit s'ancrer (le nom que
le curseur touche, le mot sur lequel la frappe atterrit) et les attentes de la table de moments.
Ne modifiez jamais timings.json à la main : il est régénéré à partir des clips, et une
modification manuelle est perdue lors de la prochaine exécution.
Faites un rapport à l'utilisateur : les lignes vocalisées, la durée de chaque clip, les indicateurs de prononciation et ce que vous avez entendu, les voix utilisées (avec le défaut recommandé pour tout ce qui est encore ouvert), et les caractères fournisseur dépensés.