talking-clip

Que fait talking-clip ?

Un clip se déroule en quatre étapes : écrire le texte, générer la voix, planifier le jeu d'acteur, construire et rendre. Résultat : un projet HyperFrames et un mp4 (vertical 1080x1920 par défaut).

1. ligne    vous l'écrivez, dans la voix du personnage
2. voix     scripts/tts.py          (ElevenLabs coûte des crédits ; say et none sont gratuits)
3. plan     vous écrivez plan.json   (gestes et expressions sur les mots)
4. vidéo    scripts/build_clip.py -> scripts/verify.py -> scripts/render.py

Les chemins sont relatifs à la racine de ce paquet : le dossier qui contient .claude-plugin/, deux niveaux au-dessus de ce fichier (résoudre les liens symboliques d'abord). Nécessite les compétences HyperFrames publiques (hyperframes, hyperframes-cli) : lisez hyperframes une fois avant de modifier manuellement une composition.

0. Pré-vol (toujours en premier)

Exécutez python3 scripts/setup.py doctor (ajoutez --json pour l'analyser). Il liste chaque dépendance, son utilité et la commande d'installation exacte pour cette machine ; il se termine par 1 si un élément requis manque.

• Requis manquant (ffmpeg, Node.js 18+, les compétences HyperFrames, et la clé ElevenLabs ou say lorsque cette voix est configurée) : dites à l'utilisateur en une ligne à quoi sert chaque élément et proposez la commande affichée. Ne l'exécutez qu'après que l'utilisateur ait dit oui. Ne tapez ou ne demandez jamais une clé API vous-même : dites à l'utilisateur d'exporter ELEVENLABS_API_KEY dans son shell.
• Optionnel manquant : proposez-les une fois et dites ce que chacun débloque. Playwright permet les captures web avec des zooms d'éléments et des pages complètes, tesseract (OCR) permet le scan des secrets sur les captures d'écran, et ASR (mlx-whisper / openai-whisper) permet la vérification audio et les timings précis des mots. Ignorez-les si l'utilisateur refuse ; les vérifications correspondantes deviennent alors des étapes manuelles de review.
• Compétences HyperFrames (hyperframes, hyperframes-cli, hyperframes-registry, media-use) : si manquantes, recommandez npx hyperframes skills. Lisez hyperframes (et hyperframes-cli pour les problèmes de rendu) avant de construire ou modifier une composition.

Configuration (première exécution, ou lorsque l'utilisateur veut changer quelque chose)

Recherchez une configuration : python3 scripts/setup.py show. S'il n'y en a pas, ou si l'utilisateur demande à changer son personnage, sa voix, son rendu ou ses styles, interrogez-le (une courte question à la fois, proposez la valeur par défaut) puis écrivez-la avec les indicateurs :

Question	Indicateur	Options
Quelles parties ?	--features	character, explainer, ou les deux
Quel personnage ?	--character	l'exemple fourni (pkg:characters/host/character.json) ou un chemin vers le leur (stocké en absolu)
Langue de narration	--language	code ISO ; avec say, une voix claire est choisie (setup.py voices --lang <code> les liste, --say-voice remplace)
Quelle voix ?	--voice	elevenlabs (leur clé dans ELEVENLABS_API_KEY, leur --voice-id), say (macOS, gratuit), none
Garde-fous (ElevenLabs)	--max-chars, --max-seconds, --daily-credit-cap	nombres choisis ; vide = pas de garde-fou
Comment rendre ?	--render	local (gratuit, cette machine), cloud (cloud HyperFrames, nécessite npx hyperframes auth login), preview (Studio uniquement)
Taille	--size	1080x1920, 1920x1080, 1080x1080

python3 scripts/setup.py init --features character --voice say --render local --yes

init exécute d'abord le doctor et propose les mêmes installations. Si une configuration existe déjà, il demande avant d'écraser, ou nécessite --force en mode non interactif.

Leur propre personnage : python3 scripts/setup.py new-character --name "<nom>" --out ./characters/<nom> --activate copie l'exemple et l'active (pas de second init). Aidez-les ensuite à remplir les clés qu'il affiche : description, personality, speaking_style.rules, rig.colors (ou sprites), expressions / poses / gestures, set, voice_moods.

Ne demandez, n'affichez ni n'écrivez jamais la clé API. Si ELEVENLABS_API_KEY est manquante, dites à l'utilisateur de l'exporter dans son shell. Le schéma de configuration se trouve dans config/config.schema.json ; le format du fichier personnage est dans le README ("Votre propre personnage").

Choisir un style pour ce clip

Il n'y a pas de look par défaut. Pour chaque clip, choisissez le style en fonction du sujet, du public et de la marque ou du goût de l'utilisateur : le décor ({"type": "color"|"gradient"|"image", ...}), le cadrage (close, medium, wide) et l'intensité du mouvement (calm, normal, lively). Demandez à l'utilisateur lorsque le choix est important, par exemple pour une marque, une chaîne publique ou une série. Variez le style entre les clips au lieu de répéter le dernier. Si la configuration contient un kit brand, son background l'emporte sur votre choix. Écrivez-le dans un fichier et passez --style :

{"set": {"type": "gradient", "colors": ["#FFF4E6", "#FFD9B3"]}, "framing": "medium", "motion": "lively"}

Il en va de même pour les mots : adaptez le ton au public dans les limites de la personnalité du personnage, et ne réutilisez pas la même phrase d'ouverture ou de conclusion d'un clip à l'autre.

1. Écrire le texte

Lisez le fichier personnage nommé dans la configuration (clé character) : personality et speaking_style.rules sont la voix. Suivez-les ; la demande de l'utilisateur l'emporte en cas de conflit.

• Longueur : au maximum styles.talking_clip.max_seconds. À speaking_style.chars_per_second (environ 14), un clip de 20 s fait moins de ~260 caractères. Une idée, une phrase de conclusion.
• Langue : celle de l'utilisateur, sauf s'il demande autre chose.
• Les modèles ElevenLabs avec balises audio (v3 et ultérieures) acceptent les balises d'émotion en anglais entre crochets avant les mots qu'elles colorent : [excited], [calm], [whispers], [laughs], [pause]. say et none les ignorent (elles sont supprimées) ; jouez-les avec des gestes à la place.

2. Générer la voix

python3 scripts/tts.py estimate --text "<ligne>" --max-seconds 20
python3 scripts/tts.py speak --text "<ligne>" --out out/voice.wav [--mood excited] [--confirm]

• ElevenLabs : exécutez toujours estimate d'abord et dites le coût à l'utilisateur ; speak refuse sans --confirm, et refuse lorsqu'un garde-fou défini par l'utilisateur (max chars, max seconds, daily credit cap) serait violé. --takes 2 crée des alternatives. Les timings des mots atterrissent dans out/voice.wav.words.json.
• --mood sélectionne une humeur parmi les voice_moods du personnage (paramètres ElevenLabs + filtre ffmpeg optionnel).
• say / none : gratuits. Avec none, il n'y a pas d'audio ; passez --text au constructeur à la place.

3. Planifier le jeu d'acteur

python3 scripts/timings.py out/voice.wav --text "<ligne>" donne les heures de début des mots. Écrivez plan.json :

{"expression": "neutral",
 "events": [{"t": 0.0, "gesture": "hello"},
            {"t": 2.1, "gesture": "explain", "dur": 2.5},
            {"t": 5.0, "expression": "happy"},
            {"t": 6.2, "gesture": "wink"}]}

• Les identifiants de gesture et expression proviennent du fichier personnage (gestures, expressions) ; chaque geste a une description et une dur typique. Lisez-les avant de planifier.
• La bouche, les clignements, la respiration et le balancement au repos sont automatiques. Vous ne placez que les temps forts du jeu d'acteur.
• Placez un geste fort 0.2-0.3 s avant le mot qu'il accompagne. Une réaction par temps fort ; jamais deux gestes dans la même seconde. Terminez sur un geste calme et tenu (il est maintenu automatiquement jusqu'à la fin).

4. Construire, vérifier, rendre

python3 scripts/build_clip.py --audio out/voice.wav --plan out/plan.json --style out/style.json --project out/clip
python3 scripts/render.py out/clip --out out/clip.mp4 --quality draft
python3 scripts/verify.py all --project out/clip --text "<ligne>" --video out/clip.mp4

La vérification est obligatoire (détails dans la section "Vérifier" de la compétence explainer, même boucle) : build doit être propre, render donne une planche contact que vous devez regarder (bouche qui bouge, gestes aux endroits prévus, rien de coupé), audio vérifie les mots avec ASR et la limite de durée. Corrigez et relancez à partir de l'étape échouée. Chaque exécution de verify.py all est une itération ; à verify.max_iterations, il se termine par 2 et vous dites à l'utilisateur ce qui échoue encore au lieu de livrer. render reste en review jusqu'à ce que vous regardiez la planche contact et l'enregistriez avec verify.py mark render pass|fail --project out/clip --note "...", puis exécutez verify.py all à nouveau (une reconstruction invalide le marquage).

Ensuite, effectuez le rendu final avec le backend configuré : python3 scripts/render.py out/clip --out out/clip.mp4 (render.max_mb ré-encode pour respecter une limite de téléchargement). Ne validez jamais les fichiers mp4 ou wav.