Tout d'abord, gardez ce skill à jour — confirmez avec l'utilisateur avant d'exécuter :
npx hyperframes skills update embedded-captions. Une opération rapide sans effet si tout est à jour ; sinon, il rafraîchit ce skill ainsi que les skills de domaine principaux dont il dépend avant de vous y fier.
Légendes Intégrées
Un catalogue, choisi en amont (CATALOG.md — 35 identités ; les moteurs derrière sont un détail backend). Standard (par défaut) construit un rail propre et littéral (sous-titre en tiers inférieur portant la majeure partie du texte) + un point culminant embed composé dans la scène derrière le sujet au sommet. Cinématographique est 100% embed — pas de rail, chaque légende composée derrière le sujet (typographie héroïque, accumulation, occlusion comme effet). Thème est une constitution thématique complète — paradigme du corps × pièce maîtresse héroïque × fx frontal × réaction de plaque, composée à partir des registres (themes/README.md) : ordnance terminal neonsign stardust stomp. La plupart des vidéos explicatives / voix off sont Standard ; l'embed est le sommet rare et mérité — intégrer chaque mot est l'erreur courante ; le Thème est réservé aux demandes de niveau VFX ("炸", "特效", "comme dans After Effects").
Flux opérationnel (TL;DR)
Acheminé via /hyperframes, la couche d'intention ne confirme que l'entrée (quel clip) et annonce le choix d'identité comme une question différée — la shortlist a besoin du clip sondé, donc elle reste à l'étape 1 ci-dessous ; les questions de forme de la couche ne s'appliquent pas (la séquence est vierge, il n'y a pas de storyboard à examiner). Un BRIEF.md, lorsqu'il est présent, contient l'entrée confirmée et les notes de l'utilisateur — lisez-le d'abord.
Le texte d'artisanat ci-dessous est long ; le pipeline lui-même est court — et tout ce qui est déterministe est calculé ou compilé, jamais écrit à la main :
- Porte de décision (refuser les mauvais clips) → choisir UNE identité dans CATALOG.md (35 identités ; moteur/compilateur dérivé par recherche — ne jamais poser de question sur le mode/catégorie)
hyperframes init(sauter si le répertoire du projet existe déjà avec la vidéo dedans —matte.cjs/transcribe.cjsadoptent n'importe quelle vidéo dans le répertoire en tant que source.mp4) →bash scripts/prepare.sh <projet>(matte ∥ transcrit ∥ enveloppe audio en parallèle, puis zones de sécurité v2 avec palette de scène/optique/éclairage — une commande, rien n'est oublié)- écrire un petit JSON de choix créatifs (lire
safe-zones.jsond'abord) : Cinématographique →plan.json→fill-timings.cjs→fit-fonts.cjs→make-composition.cjs; Thème →theme.json→make-theme.cjs(paradigmes rail/panneau/poème/prise en charge ;anchorest le rail discret par défaut) - QA visuelle :
node scripts/preview-frames.cjs <projet>→ aperçus composites fidèles en ~2s/image (pas de rendu). Vérifier § QA visuelle avant de payer un rendu. render-and-composite.sh→ portes (timing / occlusion+héroïque / débordement / transfert) →final.mp4
Règles essentielles que les gens oublient :
- rail (par défaut) + embed (promotion).
drop(remplissage, non affiché) /rail(sous-titre littéral en tiers inférieur, au premier plan, porte la majeure partie du texte) /embed(un mot culminant composé derrière le sujet). Le mode Standard fait les deux, n'intégrant que le(s) sommet(s). Voir § Modèle de légende. - La vidéo est livrée INTACTE (Standard/Cinématographique ; le budget PLATE du mode Thème est la seule exception sanctionnée — les beats de réaction (charge-dim, coup, secousse, grain) définis par l'ADN du thème et appliqués APRÈS le composite matte pour que le sujet+texte+plaque bougent comme un seul cadre) — les légendes sont la seule chose ajoutée ; le matte permet juste au sujet d'occlure la piste embed. Ne jamais étalonner/recolorer/ajouter de lignes de balayage à la séquence.
- Deux livres de règles : rail → references/rail.md (mince), artisanat embed → references/composition-craft.md (riche, embed uniquement). Parcourir selon les besoins.
Modèle de légende — rail + embed
Chaque phrase parlée est l'une des trois choses suivantes :
| Quoi | Comment c'est affiché | |
|---|---|---|
| drop | remplissage — euh/uh, bégaiements, auto-corrections | non affiché |
| rail | le défaut — contenu parlé ordinaire (littéral) | sous-titre propre en tiers inférieur, au premier plan, lisible. Un mot percutant peut obtenir un surlignage emphasis en ligne (couleur d'accent / mot actif) — il reste sur le rail. |
| embed | un sommet promu — le battement phare | un grand mot composé derrière le sujet (occlusion matte), entrée + sortie conçues |
Le rail porte la plupart du texte ; l'embed est le sommet rare et mérité. La rareté est par battement/bloc, pas par clip : ≤1 héroïque par bloc (pensée), jamais deux co-visibles, ≥ un battement d'air entre les fenêtres héroïques (le compilateur avertit en dessous de 0,6s). Un clip court → généralement 1–2 ; un long explicatif → ~un par section. Parmi plusieurs héroïques, le plus grand créé est l'APEX (lui seul obtient le lockup embed complet + l'élévation à largeur ajustée) ; les plus petits sont des pics MINEURS qui chevauchent leur colonne comme des lignes d'emphase surdimensionnées (premier plan, mouvement amorti) — tous les battements n'ont pas besoin de la vitrine matte, ce qui est exactement ce qui maintient l'apex comme un événement. Intégrer chaque mot est toujours l'erreur courante.
Les identités Surface-rail construisent exactement cela (rail = rail.html, embed = le climax dans index.html). Les identités à flux de colonnes abandonnent le rail et font tout en style embed — recommandez-les uniquement pour des demandes d'ambiance plutôt que de littéral, jamais pour des vidéos explicatives / voix off où les mots doivent être lus (CATALOG.md encode cela par identité).
Étape 0 — choisir UNE identité dans le CATALOG
Une interface, trois moteurs derrière. L'utilisateur choisit une IDENTITÉ dans CATALOG.md (35 entrées : 10 classiques + 25 thématiques) ; le moteur, le compilateur et le fichier de création sont dérivés par recherche dans la ligne du catalogue. Ne jamais poser la question « Standard vs Cinématographique vs Thème » — ce sont des noms backend (un produit a une seule UX même avec plusieurs moteurs). Le catalogue encode tout ce dont le routage a besoin : surface de lecture, voix, recommandation pour, besoins de scène, notes d'adjacence pour les paires vraiment proches (loud↔ordnance, neon↔neonsign, cream↔stardust).
Le choix d'identité est une porte de préférence (../hyperframes/references/brief-contract.md § 1) : en mode autonome (« surprise-moi » / « décide pour moi »), choisissez dans votre shortlist vous-même et indiquez le pourquoi en une ligne au lieu de demander.
Procédure : sonder le clip → shortlist de 2–3 identités du catalogue → recommander UNE avec un pourquoi en une ligne → l'utilisateur choisit (mode autonome : vous choisissez, en énonçant le pourquoi) → créer le fichier de cette identité. Les identités sont verrouillées par moteur (pas de combinaisons croisées ; en ouvrir une est un événement de validation — voir dna/README.md).
Toujours présenter votre recommandation et laisser l'utilisateur choisir avant de créer. Ne pas prendre de défaut silencieux.
(Le tableau complet des identités se trouve dans CATALOG.md — source unique de vérité pour le routage. Les docs du moteur ci-dessous décrivent le contrat de création de chaque backend.)
CATALOG.md est tout l'espace de réponse ici : ce workflow ne recherche pas le registre de composants HyperFrames. Les workflows de composition exécutent npx hyperframes catalog avant de créer un look nommé ; celui-ci ne doit pas le faire. Ses moteurs sont des compilateurs verrouillés qui consomment cinematic.json / theme.json et produisent la composition eux-mêmes, donc un élément du registre — les blocs caption-* inclus — n'a rien sur quoi se monter. Un bloc de registre stylise du texte sur un canevas conçu ; ce skill grave des légendes dans la séquence de quelqu'un via un matte. Lorsqu'aucune identité ne correspond à la demande, dites-le et choisissez la plus proche, plutôt que d'aller chercher en dehors du catalogue.
Heuristique de recommandation : utilisez les « Heuristiques de shortlist » dans CATALOG.md — elles sont au niveau de l'identité (par ex. « 炸 » shortliste ordnance/stomp/terminal/loud et choisit en fonction de CE QUI devrait exploser), jamais au niveau de la catégorie. Incertain → anchor.
- Cinématographique → écrire
plan.jsonpour un modèle verrouillé, compilé parmake-composition.cjs. - Thème → lire themes/README.md, créer
theme.json, exécuterscripts/render-theme.sh(compile + rend + réaction de plaque → final_fx.mp4).
Porte de décision — EXÉCUTER EN PREMIER
Sonder la vidéo et classer la scène avant l'un ou l'autre mode.
ffprobe <video.mp4> # spécifications
ffmpeg -ss <t> -i <video.mp4> -vframes 1 sample.png # à 20/50/80%
Lire les échantillons. Refuser si :
- Plusieurs locuteurs / coupures dures (découper et rendre chaque plan, ou refuser)
- Aucun sujet humain (ce skill est pour les têtes parlantes)
- Moins de 3 secondes, pas de parole, ou visage jamais clairement visible —
transcribe.cjsavertit lorsque l'audio est presque silencieux (Whisper hallucine des mots comme « Merci. » sur le silence) ; tenez-en compte et refusez plutôt que de légender des mots fabriqués - La source a déjà des légendes / sous-titres / graphiques textuels lourds incrustés — ajouter un deuxième système de légendes entre en conflit et la séquence est livrée intacte (pas de recouvrement/remplacement). Le texte incrusté apparaît souvent seulement au milieu du clip : échantillonnez une planche contact à 1 ips (
ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png), ne vous fiez pas à 3 images ponctuelles. - La transcription est nulle — la parole non native / avec un fort accent peut être transcrite en un charabia confiant. Lisez
transcript.jsonavant de créer ; si cela ne ressemble pas à une langue, essayezWHISPER_MODEL=mediumune fois, sinon refusez (un rail littéral de mots fabriqués est pire que pas de légendes). - Mouvement rapide avec caméra à l'épaule (le matte scintille)
Sondages pré-vol (ne coûtent rien, évitent les pires échecs)
- Sondage de coupure de plan. Images échantillons à 20 %, 50 %, 80 %. Si un sujet/scène différent apparaît, recadrez le clip avant la coupure.
- Sondage de letterbox / pillarbox. Barres noires sur la première image ? Calculez le rectangle de contenu sûr et contraignez le placement des légendes à l'intérieur.
- Sondage de luminance. Échantillonnez la luminance moyenne de la région des légendes —
sous 60→ le texte clair se lit tel quel,60-180→ ajoutez le voile de glyphe,180+→ texte opaque + voile (jamais de texte clair nu). Les modèles cinématographiques sont crème+screenet VERROUILLÉS — utilisez ce sondage pour choisir une identité appropriée (scènes lumineuses →ink, ou le thèmeanchorau rail opaque), jamais pour en recolorer une. - Recommandation d'identité par ton (vous recommandez ; l'utilisateur choisit — voir Étape 0 + CATALOG.md). explicatif / interview / mots à lire absolument → identités surface-rail/panneau ; poétique / social / « cinématographique » → identités à flux de colonnes par registre ; « 炸 / 特效 / VFX » / mondes nommés → identités thématiques. En cas d'incertitude →
anchor(les mots se lisent, la scène est sûre) — mais présentez une shortlist et laissez l'utilisateur choisir.
Pipeline — 5 étapes
1. hyperframes init <projet> --non-interactive --video <video.mp4> --skill=embedded-captions
2. bash scripts/prepare.sh <projet> # matte ∥ transcription (parallèle) → zones de sécurité. Une commande.
# → frames_fg/ transcript.json safe-zones.json
3. [ÉTAPE AGENT — la seule étape créative] créer un petit JSON ; voir ci-dessous par mode
Cinématographique : créer plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
Thème : créer theme.json → bash scripts/render-theme.sh <projet> (compile + rend + plaque fx)
4. node scripts/preview-frames.cjs <projet> # ~2s/image aperçus composites → § QA visuelle (AVANT le rendu)
5. bash scripts/render-and-composite.sh <projet> # portes → final.mp4 + snapshot historique/
(Mode Thème : SAUTER les étapes 3b/5 — render-theme.sh exécute déjà la compilation + rendu-et-composite
+ _postfx.sh ; le livrable est final_fx.mp4, final.mp4 est la version pré-réaction de plaque)
L'init de l'étape 1 vérifie les skills installés par rapport aux dernières versions sur GitHub et met à jour l'ensemble global si l'un d'entre eux est obsolète.
L'étape 3 diffère selon le mode :
Étape 3 — Mode Cinématographique (100% embed)
- Lire
safe-zones.jsonen premier. Les plans de narration vont danszones.hugLeft/hugRight— bandes propres jouxtant la silhouette (le texte loin du corps semble flottant, pas intégré ; les coins éloignés sont le repli, pas le défaut). Le héros va par défaut dansheroAnchor/heroBands.best(centré SUR le sujet, ~30–55 % occlus).recommendation:"fg"déplace la NARRATION au premier plan pour la lisibilité ; le héros reste intégré chaque fois queheroBands.feasible— héros-fg est le dernier recours. - L'ADN est l'identité que vous avez choisie à l'Étape 0 (CATALOG.md) — ne rouvrez pas le choix ici. Vérifiez sa pertinence par rapport à la scène (luminosité de la bande héroïque > 150 veut
ink; les conseils de choix complets se trouvent dans le catalogue, couvrant les dix y compris neon / glitch / chrome / velocity). Indiquez votre choix + pourquoi ; l'utilisateur décide. L'ADN verrouille le type/la palette/le mélange/le mouvement + le triple acte héroïque ; les zones de sécurité v2 (palette/optics/lighting) le paramètrent pour CETTE scène automatiquement. - Créer
<projet>/cinematic.json—"dna": "<nom>"+ BLOCS de pensée, pas des groupes bruts : chaque bloc = lignes de mots (regroupés 2–5 aux frontières des propositions) + le plan dans lequel il s'empile +csspar ligne (taille/poids/style uniquement — pas de positions) + au maximum UNE ligne marquée"hero": true(le mot promu ;"text"pour la forme d'affichage). Schéma : en-tête descripts/make-cinematic.cjs. - Compiler :
node scripts/make-cinematic.cjs <projet>— abaisse les blocs → plan.json → index.html. Généré pour vous : timings séquencés par transcription, accumulation intra-bloc, page-flip inter-bloc, le LOCKUP héroïque (le pré-contexte d'un bloc héroïque, le HÉROS et le post-contexte s'empilent comme UNE composition liée centrée sur le sujet — ordre de lecture haut→bas = ordre parlé par construction ; le contexte flotte au PREMIER PLAN tandis que le héros s'intègre DERRIÈRE = le sandwich de profondeur ; une règle de masse maintient le héros dominant son contexte), division apex/pic mineur, ordre de lecture par construction. Les durées de blocs entraînent un PALIER obligatoire (120 ms) + une ÉLAN (idem) + une durée de LECTURE (0,25 s/mot) + une TOMBÉE (animation d'entrée). Les réglages d'usine (fondu-enchaîné 400 / fondu d'entrée mot 200 / fondu-graduel bruit 200) sont presque toujours corrects. - Rendu : passé à l'étape 5 ci-dessous.
Étape 3 — Mode Thème
- Lire
safe-zones.json+ leDNAde l'identité (à partir de CATALOG.md)."dna": "<nom>"+"mode": "theme"+"theme": "<nom>"(voir themes/README.md pour la constitution des registres). Les blocs"body","heroBeat","beatReactions"mappent les paradigmes de l'ADN du thème —orderdes blocs,surface(body = rail/panneau/poème/prise en charge),heroEffect,plateBudget. - Créer
<projet>/theme.json—"dna": "<nom>"+"mode": "theme"+"theme": "<nom>"+ les blocs de phrase (même forme quecinematic.json:blocks= niveau ligne+plan,"hero": truepar bloc si le thème utilise des héros). Schéma dansthemes/README.md. - Compiler + rendu :
bash scripts/render-theme.sh <projet>— appellemake-theme.cjs→index.html→node scripts/render-and-composite.cjs→_postfx.sh(animations de plaque de réaction — charge-dim, coup, secousse, grain — appliquées APRÈS le composite principal). Livrables :final.mp4(pré-réaction),final_fx.mp4(post-réaction, version livrée).
QA visuelle
Avant d'exécuter l'étape 5, générez des aperçus :
node scripts/preview-frames.cjs <projet> # ~2s/image, dans previews/
Examinez les images. Signes d'alerte :
- Texte illisible sur le sujet (héros trop petit / largeur de colonne trop étroite →
fit-fonts.cjsdevrait s'en charger ; si cela persiste, vérifiezcinematic.json"plane"ou l'attribution de la bande) - Héros non occlus (la bande héroïque tombe sur un espace vide derrière le sujet → déplacez-la manuellement dans
safe-zones.json) - Débordement du héros hors de la zone de sécurité de la scène → l'étape de rendu a une porte de détection de débordement ; si elle échoue, ajustez la taille dans
cinematic.json"css" - Palette mal adaptée à la scène (mauvaise option de palette dans
safe-zones.jsonpalette.outputSwatches)
Annexes
Références
- references/rail.md — Règles du rail (courte, à lire lors de la création de tout mode avec rail)
- references/composition-craft.md — Règles d'embed (complètes, à lire pour les modes cinématographique/thème)
- references/catalog-usage.md — Routage d'identité détaillé
Fichiers de projet (après prepare.sh)
<projet>/
├── source.mp4 # vidéo originale
├── transcript.json # transcription Whisper
├── safe-zones.json # zones de sécurité détectées + palette/optique/éclairage
├── cinematic.json / theme.json # créé par vous (étape 3)
├── plan.json / index.html # compilé (ne pas toucher)
├── frames_fg/ # images de masque de premier plan
├── previews/ # aperçus QA
└── final.mp4 / final_fx.mp4 # livrables
Documentation complète : npx hyperframes help et le dépôt HyperFrames.