Plan-to-video (Plan vers vidéo)

Plan vers vidéo

Transforme un plan écrit en une vidéo explicative narrée (environ 60 à 90 s pour un post social, 2 à 2,5 min pour un vrai plan avec plusieurs décisions) : l'accroche, le problème, la proposition, le mécanisme, puis une image par décision ouverte (question plus 2 à 4 options) et une demande de clôture.

Cette compétence ne réimplémente pas HyperFrames. Elle décide du brief, de la forme narrative et de la configuration, puis exécute le workflow installé /faceless-explainer étape par étape, en ajoutant des correctifs aux points où le pipeline par défaut a tendance à échouer. Lis /hyperframes et /faceless-explainer comme ils l'indiquent ; ce fichier te dit quoi répondre et quoi corriger.

Première exécution sur une machine : lis references/setup.md et exécute sa vérification préalable. Il installe les compétences HyperFrames et une voix locale si elles manquent.

Configuration

Résous ces éléments une fois au début et réutilise-les dans chaque commande. Demande à l'utilisateur seulement si une valeur ne peut pas être trouvée.

Nom	Comment résoudre	Défaut
VIDEOS_DIR	$PLAN_TO_VIDEO_DIR si défini	./videos sous le répertoire de travail actuel (convention faceless-explainer)
FE_DIR	le dossier contenant le fichier faceless-explainer/SKILL.md installé	voir references/setup.md pour la recherche
MEDIA_DIR	le dossier contenant le fichier media-use/SKILL.md installé	même recherche
HYPERFRAMES_PYTHON	variable d'environnement si définie, sinon l'environnement virtuel de references/setup.md	~/.hyperframes-venv/bin/python
VOICE	la demande de l'utilisateur, sinon la voix mémorisée, sinon	Kokoro am_michael (hors ligne)

1. Brief (confirmer brièvement, ne pas interroger)

Lis d'abord la source (le document du plan, la note de recherche, la discussion). Propose ensuite ces valeurs par défaut en un seul message court et ne demande que ce que la source ne peut pas répondre. Un « oui » rapide vaut mieux qu'un questionnaire.

Champ	Défaut	Pourquoi
angle	listicle (une des valeurs de la route : concept, how-to, listicle, narrative)	un plan est « pourquoi c'est important, comment ça marche, N décisions »
storyboard arc	concept-explainer with listicle	texte libre dans STORYBOARD.md, pas une énumération du brief
aspect	1920x1080	regardé sur un ordinateur portable ou lors d'un appel ; les cartes d'options ont besoin de largeur
length	2 à 2,5 min pour un vrai plan avec plusieurs décisions ; environ 60 à 90 s pour un post social. Limite absolue 180 s	le point idéal de faceless-explainer est de 30 à 90 s ; un plan avec de nombreuses décisions dure plus longtemps. Environ 10 s par décision plus l'intro et la conclusion
language / voice	la langue de la source ; Kokoro am_michael pour l'anglais	local et gratuit. Les voix Kokoro non anglaises nécessitent espeak-ng
flow / storyboard	automation / no (autonome)	proposer la révision du storyboard lorsque le plan est à enjeux élevés
look	la marque propre du projet quand la vidéo concerne un dépôt, sinon un préréglage approprié	la vidéo doit ressembler à ce qu'elle explique
music	none	MusicGen local nécessite torch ; la musique HeyGen nécessite une connexion
project	$VIDEOS_DIR/<sujet-en-kebab>/	un dossier par vidéo

Demande, au maximum : qui va la regarder (cela détermine le niveau technique du texte), et si une option recommandée doit être marquée sur chaque décision (la bordure « penchée » de l'accent).

Règle pour l'option recommandée : marque l'option que la source recommande. Quand aucune option unique ne gagne, ne marque rien ; quand la décision est « prendre en charge plusieurs », marque chaque option qui fait partie de cette réponse. Quand la source ne le dit pas, recommande les valeurs par défaut de cette compétence (les valeurs dans le tableau ci-dessus) au lieu d'inventer une préférence.

BRIEF.md est écrit à l'Étape 0, après npx hyperframes init (init refuse un dossier non vide), dans la forme que /hyperframes references/brief-format.md décrit, avec ce que l'utilisateur a dit et ce que tu as déduit séparés.

2. Forme narrative

Arc par défaut, adapter à la source :

1. Accroche avec un chiffre réel de la source (« N sur M éléments sont X »). Chaque chiffre doit provenir d'une ligne de la source ; n'invente jamais de statistiques, de prix ou de quantités. Si la source n'a pas de chiffre, ouvre sur le problème concret à la place.
2. Le problème en 2 ou 3 causes nommées, avec des exemples réels de la source.
3. La thèse ou la proposition à l'image 3 (valeur avant la preuve).
4. Le mécanisme dans une image de diagramme.
5. Un jalon (« Cinq décisions avant de le construire ») comme une courte pause.
6. Une image par question ouverte ou étape, toutes sur le même fond de question (references/question-stage.md). Chaque image montre la question et ses 2 à 4 options ; les options apparaissent au fur et à mesure que la voix les nomme.
7. Une demande de clôture qui rappelle le jalon (« Répondez à ces cinq questions et la première étape sera livrée cette semaine »).

Écris la voix off comme de courtes phrases indicatrices (6 à 25 mots par image) afin que chaque option ait un mot sur lequel se révéler. Si une décision est déjà répondue dans la source, montre la réponse choisie dans l'accent au lieu de demander.

3. Exécuter le workflow, avec ces correctifs

Suis les Étape 0 à 6 de /faceless-explainer dans l'ordre. À chaque étape, applique le correctif correspondant de references/gotchas.md. Ceux qui posent problème si on les saute :

• Étape 0 : init à l'intérieur du parent de $VIDEOS_DIR pour que le projet atterrisse dans $VIDEOS_DIR/<sujet>, puis écris BRIEF.md. Être déconnecté de HeyGen n'est pas un problème : la voix tourne sur Kokoro localement.
• Étape 2 design : pour un dépôt, mets ses couleurs et polices dans capture/extracted/tokens.json et place les vrais fichiers .woff2 dans assets/fonts/ avant build-frame.mjs (il écrit ensuite le bloc @font-face lui-même). Obtiens les polices à partir des fichiers du site de la marque, d'un téléchargement Google Fonts ou d'un package de polices dans node_modules. Si la marque est sombre et le préréglage clair, inverse les rôles dans frame.md, remplace les glyphes du préréglage que la police intégrée peut manquer, et échange un préréglage d'accent qui appartient à une autre marque contre celui de l'utilisateur (references/gotchas.md, Étape 2).
• Étape 3.1 audio : passe HYPERFRAMES_PYTHON sur chaque commande audio sauf si le python3 par défaut importe déjà kokoro_onnx.
• Temporisations : laisse l'audio se terminer et exécute audio.mjs sync-durations avant d'écrire les fenêtres de Scène de l'Étape 4, puis cadence chaque révélation à partir des temporisations réelles des mots dans audio_meta.json. (faceless-explainer exécute sync-durations à l'Étape 5 ; le déplacer plus tôt est délibéré.)
• Marge de respiration : sync-durations définit chaque image à sa durée vocale exacte, donc la dernière image et le jalon se terminent brusquement. Juste après la synchronisation, modifie - duration: dans STORYBOARD.md : image finale +2 à 3 s, jalon et autres images de pause +1 s. Fais-le avant de construire les paquets pour que les travailleurs animent contre les fenêtres rembourrées.
• Mots des sous-titres : les sous-titres proviennent d'une transcription de l'audio, pas de SCRIPT.md, donc les noms de produits sont mal compris. Avant que les sous-titres ne soient construits, compare la liste de mots dans audio_meta.json (voices[].words[].text) avec SCRIPT.md et corrige les mots mal compris sur place, en conservant leurs temporisations.
• Avant l'envoi de l'Étape 5 : donne à chaque travailleur les noms de fichiers de polices exacts mis en place à l'Étape 2. Les paquets omettent le bloc ## Video direction du storyboard et les temporisations complètes des mots, donc colle les deux dans le contexte d'envoi de chaque travailleur. Donne aux images du fond de question le cahier des charges partagé textuellement. Interdis les emoji.
• Étape 5 : un travailleur par image, en parallèle si ton agent prend en charge les sous-agents (un modèle plus rapide convient pour les travailleurs), chacun avec _role.md, son paquet et le contexte d'envoi.
• Après les travailleurs : normalise les chemins des ressources, corrige les avertissements de lint qui sont de véritables bugs de recherche, exécute check, fais un instantané, regarde la feuille de contact.

4. Passages qualité (tous avant le rendu)

• npx hyperframes lint avec 0 erreurs. Les avertissements studio_missing_editable_id sont cosmétiques ; gsap_repeated_fromto_without_baseline est un vrai bug, corrige-le (references/gotchas.md, Étape 6).
• npx hyperframes check passe.
• npx hyperframes snapshot --at <milieu de chaque image> et regarde réellement la feuille de contact : texte sombre sur fond sombre, polices manquantes (secours serif), cartes tronquées et emoji tofu apparaissent tous là.
• Si l'utilisateur a un style maison (par exemple « pas de tirets cadratins »), vérifie chaque chaîne : les lignes - voiceover:, les lignes SCRIPT.md, le texte dans compositions/frames/*.html, et les titres aussi. Écris les titres avec deux-points (## Image 1 : Accroche, ## Ligne 1 : Accroche (Image 1)) ; l'analyseur syntaxique du storyboard et du script l'accepte, donc aucun tiret n'est jamais nécessaire.

5. Révision, rendu, remise

L'Étape 6 de faceless-explainer conserve une question même en mode autonome : ouvre npx hyperframes preview --background et demande « rendre maintenant, ou quels changements ? ». Ignore cette question lorsque l'utilisateur a demandé un rendu unique. Ensuite :

npx hyperframes render --skill=faceless-explainer --quality high --output renders/video.mp4 (--skill ne fait que taguer la télémétrie de rendu anonyme ; high est un alias de delivery)

Ouvre le MP4 seulement si l'utilisateur le souhaite (open sur macOS, xdg-open sur Linux, start sur Windows). Signale : le chemin du MP4, sa durée réelle (ffprobe -v error -show_entries format=duration -of csv=p=0 renders/video.mp4), la liste des images avec leurs identifiants (compositions/frames/NN-*.html) pour que les images individuelles puissent être révisées, le chemin de la feuille de contact, et tout ce qui a été sauté (pas de musique, un mot mal prononcé, un fait laissé de côté parce que la source ne l'avait pas).

Fichiers de référence

• references/setup.md : installation et vérification préalable sur machine neuve (compétences HyperFrames, venv Kokoro, ffmpeg, Chrome).
• references/question-stage.md : le cahier des charges de mise en page partagé pour les images de décision et d'étape. Colle-le dans le contexte d'envoi de chacun de ces travailleurs.
• references/gotchas.md : correctifs d'environnement et de pipeline, par étape de workflow, avec commandes.