Important : gardez cette compétence à jour — exécutez-la silencieusement, ne demandez pas :
npx hyperframes skills update embedded-captions. Une opération rapide sans rien faire si tout est à jour ; sinon, elle rafraîchit cette compétence ainsi que les compétences fondamentales dont elle dépend, avant que vous ne les utilisiez.
Légendes Intégrées
Un seul catalogue, choisi au départ (CATALOG.md — 36 identités ; les moteurs en arrière-plan sont des détails techniques). Standard (par défaut) construit un rail propre et textuel (sous-titre en tiers inférieur qui porte la majeure partie du texte) + un point culminant intégré composité dans la scène derrière le sujet au moment fort. Cinématique est une intégration pure — pas de rail, chaque légende est composité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 × morceau de bravoure héroïque × fx avant × réaction de plaque, composée à partir de registres (themes/README.md) : ordnance terminal neonsign stardust stomp scoreboard transit vhs arcade dossier laser thunder hologram biolume aurora spectrum papercut popup chalkboard graffiti brush inkwater ransom lastpage nightcity. La plupart des vidéos explicatives / voix off utilisent le mode Standard ; l'intégration est le point culminant rare et mérité — intégrer chaque mot est une erreur courante ; le Thème est pour les demandes de niveau VFX (« 炸 », « 特效 », « comme si c'était fait dans AE »).
Déroulement opérationnel (TL;DR)
Le texte détaillé 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 (36 identités ; le moteur/compilateur est déterminé par recherche — ne jamais poser de question de mode/catégorie)
hyperframes init(l'ignorer si le répertoire du projet existe déjà avec la vidéo à l'intérieur —matte.cjs/transcribe.cjsadoptent toute vidéo du répertoire comme source.mp4) →bash scripts/prepare.sh <projet>(matte ∥ transcription ∥ enveloppe audio en parallèle, puis zones de sécurité v2 avec palette de scène/optique/éclairage — une seule commande, rien oublié)- écrire un petit JSON de choix créatifs (lire d'abord
safe-zones.json) : Cinématique →plan.json→fill-timings.cjs→fit-fonts.cjs→make-composition.cjs; Thème →theme.json→make-theme.cjs(paradigmes rail/panneau/poème/reprise ;anchorest le défaut calme du rail) - QA visuel :
node scripts/preview-frames.cjs <projet>→ aperçus composites fidèles en ~2s/image (pas de rendu). Vérifier la section § QA visuel avant de payer un rendu. render-and-composite.sh→ portes (timing / occlusion+héros / débordement / remise) →final.mp4
Règles importantes souvent négligées :
- rail (défaut) + intégration (promotion).
drop(remplissage, non affiché) /rail(sous-titre textuel en tiers inférieur, devant, porte la majorité du texte) /integrate(un mot clé composité derrière le sujet). Le mode Standard fait les deux, n'intégrant que le(s) point(s) culminant(s). Voir § Modèle de légende. - La vidéo est livrée INTACTE (Standard/Cinématique ; le budget PLAQUE du mode Thème est la seule exception autorisée — les beats de réaction pilotés par registre (assombrissement, coup, secousse, grain) définis par l'ADN de chaque thème et appliqués APRÈS le composite du matte pour que le sujet+texte+plaque bougent comme un seul plan). Les légendes sont la seule chose ajoutée ; le matte permet juste au sujet d'occlure la piste intégrée. Ne jamais étalonner/recolorer/ajouter de lignes de balayage à la vidéo.
- Deux manuels : rail → references/rail.md (court), l'art de l'intégration → references/composition-craft.md (riche, intégration uniquement). Parcourir selon les besoins.
Modèle de légende — rail + intégration
Chaque phrase parlée est d'un de ces trois types :
| Quoi | Comment c'est affiché | |
|---|---|---|
| drop | remplissage — euh/euh, bégaiements, auto-corrections | non affiché |
| rail | le défaut — contenu parlé ordinaire (textuel) | sous-titre propre en tiers inférieur, devant, lisible. Un mot percutant peut obtenir une surbrillance emphasis en ligne (couleur d'accent / effet actif) — il reste sur le rail. |
| integrate | un point culminant promu — le moment clé | un grand mot composité derrière le sujet (occlusion par matte), entrée + sortie conçues |
Le rail porte la majeure partie du texte ; l'intégration est le point culminant rare et mérité. La rareté est par beat/bloc, pas par clip : ≤1 héros par bloc (pensée), jamais deux visibles en même temps, ≥ un beat d'air entre les fenêtres de héros (le compilateur prévient en dessous de 0,6s). Un court clip → généralement 1–2 ; une longue vidéo explicative → environ un par section. Parmi plusieurs héros, le plus grand est l'APEX (lui seul obtient l'intégration complète en verrouillage + levée ajustée à la largeur) ; les plus petits sont des pics MINEURS qui chevauchent leur colonne comme des lignes de texte d'accentuation surdimensionnées (au premier plan, mouvement atténué) — tous les beats n'ont pas besoin de la mise en valeur par matte, ce qui maintient précisément l'apex comme un événement. Intégrer chaque mot reste l'erreur courante.
Les identités à surface de rail construisent exactement cela (rail = rail.html, intégration = le point culminant dans index.html). Les identités à flux en colonne abandonnent le rail et mettent tout en style intégration — les recommander uniquement pour des demandes d'ambiance plutôt que de texte, jamais pour des vidéos explicatives / voix off où les mots doivent être lisibles (CATALOG.md code cela par identité).
Étape 0 — choisir UNE identité dans le CATALOGUE
Une interface, trois moteurs en arrière-plan. L'utilisateur choisit une IDENTITÉ dans CATALOG.md (36 entrées : 10 classiques + 26 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 présenter « Standard vs Cinématique vs Thème » comme une question — ce sont des noms internes (un produit a une seule expérience utilisateur même avec plusieurs moteurs). Le catalogue code tout ce dont l'acheminement a besoin : surface de lecture, voix, recommandation, besoins de scène, notes d'adjacence pour les paires vraiment proches (loud↔ordnance, neon↔neonsign, cream↔stardust).
Le choix de l'identité est une porte de préférence (../hyperframes-core/references/brief-contract.md § 1) :
en mode autonome (« surprends-moi » / « décide pour moi »), choisissez vous-même dans votre présélection
et indiquez le pourquoi en une ligne au lieu de demander.
Procédure : sonder le clip → présélectionner 2–3 identités du catalogue → recommander UNE avec un pourquoi en une ligne → l'utilisateur choisit (mode autonome : vous choisissez, en indiquant 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).
Présentez toujours votre recommandation et laissez l'utilisateur choisir avant de créer. Ne prenez pas de défaut silencieux.
(La table complète des identités se trouve dans CATALOG.md — source unique de vérité pour l'acheminement. La documentation du moteur ci-dessous décrit le contrat de création de chaque backend.)
Heuristique de recommandation : utiliser les « Heuristiques de présélection » dans CATALOG.md — elles sont au niveau de l'identité (par exemple « 炸 » présélectionne ordnance/stomp/terminal/loud et choisit par CE QUI doit exploser), jamais au niveau de la catégorie. En cas de doute → anchor.
- Cinématique → é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(compilation + rendu + 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 les deux modes.
ffprobe <video.mp4> # specs
ffmpeg -ss <t> -i <video.mp4> -vframes 1 echantillon.png # à 20/50/80%
Lire les échantillons. Refuser si :
- Plusieurs intervenants / coupures franches (diviser et rendre chaque plan, ou refuser)
- Pas de sujet humain (cette compétence est pour le talking-head)
- Moins de 3 secondes, pas de parole, ou visage jamais clairement visible —
transcribe.cjsprévient quand l'audio est quasi silencieux (Whisper hallucine des mots comme « Merci. » sur le silence) ; l'écouter et refuser plutôt que de légender des mots fabriqués - La source a déjà des sous-titres / légendes / graphiques textuels incrustés — ajouter un deuxième système de légendes entre en conflit et la vidéo est livrée intacte (pas de recouvrement/inpainting). Le texte incrusté apparaît souvent seulement au milieu du clip : échantillonner une planche contact à 1 ips (
ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png), ne pas se fier à 3 images ponctuelles. - La transcription est inutilisable — la parole non native / fortement accentuée peut être transcrite en charabia avec assurance. Lire
transcript.jsonavant de créer ; si cela ne ressemble pas à une langue, essayerWHISPER_MODEL=mediumune fois, sinon refuser (un rail textuel de mots fabriqués est pire que pas de légendes). - Mouvements rapides instables (le matte scintille)
Vérifications préliminaires (ne coûtent rien, évitent les pires échecs)
- Vérification des coupures de plan. Échantillonner des images à 20%, 50%, 80%. Si un sujet/scène différent apparaît, couper le clip avant la coupure.
- Vérification des barres noires (letterbox / pillarbox). Barres noires sur la première image ? Calculer le rectangle de contenu sûr et contraindre le placement des légendes à l'intérieur.
- Vérification de la luminance. Échantillonner la luminance moyenne de la région des légendes —
sous 60→ le texte clair se lit tel quel,60-180→ ajouter le voile de glyphe,180+→ texte opaque + voile (jamais de texte clair nu). Les modèles cinématiques sont cream+screenet VERROUILLÉS — utiliser cette vérification pour choisir une identité adaptée (scènes lumineuses →ink, ou le thèmeanchorà rail opaque), jamais pour en recolorer une. - Recommandation d'identité par ton (vous recommandez ; l'utilisateur choisit — voir Étape 0 + CATALOG.md). Vidéo explicative / interview / mots à lire absolument → identités à surface rail/panneau ; poétique / social / « cinématique » → identités à flux en colonne par registre ; « 炸 / 特效 / VFX » / mondes nommés → identités thématiques. En cas de doute →
anchor(les mots se lisent, la scène est sûre) — mais présenter une présélection et laisser l'utilisateur choisir.
Pipeline — 5 étapes
1. hyperframes init <projet> --non-interactive --video <video.mp4>
2. bash scripts/prepare.sh <projet> # matte ∥ transcription (parallèle) → safe-zones. Une seule 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ématique : 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> (compilation + rendu + fx plaque)
4. node scripts/preview-frames.cjs <projet> # ~2s/image d'aperçus composites → § QA visuel (AVANT le rendu)
5. bash scripts/render-and-composite.sh <projet> # portes → final.mp4 + snapshot dans history/
(Mode Thème : IGNORER les étapes 3b/5 — render-theme.sh exécute déjà compilation + rendu-et-composite
+ _postfx.sh ; le livrable est final_fx.mp4, final.mp4 est avant réaction de plaque)
L'étape 1 (init) vérifie les compétences installées par rapport aux dernières versions sur GitHub et met à jour l'ensemble global si l'une d'elles est obsolète.
L'étape 3 diffère selon le mode :
Étape 3 — Mode Cinématique (intégration pure)
- Lire d'abord
safe-zones.json. Les plans de narration vont danszones.hugLeft/hugRight— bandes propres COLLÉES à la silhouette (le texte loin du corps donne l'impression de flotter, pas d'être intégré ; les coins éloignés sont le repli, pas le défaut). Le héros par défaut estheroAnchor/heroBands.best(centré SUR le sujet, ~30–55% occulté).recommendation:"fg"déplace la NARRATION devant pour plus de lisibilité ; le héros reste intégré chaque fois queheroBands.feasible— héros-fg est la dernière option. - L'ADN est l'identité que vous avez choisie à l'Étape 0 (CATALOG.md) — ne pas rouvrir le choix ici. Vérifier sa cohérence avec la scène (une luminance élevée de la bande héroïque > 150 nécessite
ink; les conseils complets de sélection se trouvent dans le catalogue, couvrant les dix incluant neon / glitch / chrome / velocity). Indiquer votre choix + pourquoi ; l'utilisateur décide. L'ADN verrouille le type/la palette/le mélange/le mouvement + l'acte en trois temps du héros ; safe-zones v2 (palette/optics/lighting) le paramètre pour CETTE scène automatiquement. - Créer
<projet>/cinematic.json—"dna": "<nom>"+ BLOCS de pensée, pas de groupes bruts : chaque bloc = lignes de mots (regroupés 2–5 aux limites de proposition) + 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 dans le bloc, changement de page entre les blocs, le VERROUILLAGE du héros (le pré-contexte d'un bloc héros, le HÉROS et le post-contexte s'empilent comme UNE composition liée centrée sur le sujet — l'ordre de lecture haut→bas = ordre parlé par construction ; le contexte flotte DEVANT 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), la division apex/pics mineurs, ordre de lecture par construction, repli fg selon safe-zones. Ensuite, les portes s'exécutent comme d'habitude. (La création manuelle de plan.json reste possible pour des conceptions que les blocs ne peuvent pas exprimer — puis exécuterfill-timings.cjs+fit-fonts.cjs+make-composition.cjsvous-même.)
Étape 3 — Mode Thème (constitution thématique)
Lire themes/README.md EN PREMIER — registres de paradigmes/morceaux de bravoure, liens, règles strictes et le schéma exact de theme.json.
- Choisir un ADN de thème selon le registre du contenu (chaque
themes/<nom>.jsonavoice+when). Indiquer votre choix + pourquoi ; l'utilisateur décide. - Créer
<projet>/theme.json—dna,lines(textuel, ordre de transcription ; 1–5 mots chacun — pourtakeover, chaque ligne est une CARTE),minors(mots d'accentuation),hero:{match}(le mot/la phrase culminante ; le laisser HORS delinespour les morceaux de bravoure intégrés, le garder DANSlinespour les morceaux de bravoure en ligne et panneau+redaction). - Rendre :
bash scripts/render-theme.sh <projet>— compile (porte de complétude textuelle au moment de la compilation), rend les deux couches, composite, applique la réaction de plaque →final_fx.mp4. Utiliserpreview-frames.cjspour les contrôles de timing et de chevauchement avant.
Étape 3 — Mode Standard (rail + intégration)
- Lire
safe-zones.json. Les emplacements de rail sont en bas (zoneshugBottompar défaut ;railUnderpour une marge supplémentaire). Les emplacements d'intégration sont centrés (sur-corpsheroBands.best; descentefgsi la bande n'est pas faisable). - L'ADN est l'identité choisie dans le catalogue (Étape 0) —
anchorpar défaut. - Créer
<projet>/standard.jsonconformément au schéma en haut descripts/make-rail.cjs:dna,blocks: [{lines, hero?}],adapt: {contrast, safe}. - Compiler :
node scripts/make-rail.cjs <projet>— produitrail.html+index.html. Ensuite exécutermake-composition.cjs(via les scripts du pipeline) pour le composite final.
QA visuel (AVANT le rendu)
node scripts/preview-frames.cjs <projet> produit ~20 images composites (pas de rendu) pour vérifier :
- Les mots intégrés entrent-ils par le chemin prévu ? (Les habillages de bord frappent-ils le visage ?)
- Les mots du rail sont-ils tronqués ? (Ajuster
railMaxChars) - La réaction de plaque domine-t-elle le mot ? (Reculer la parade de réaction de quelques images)
- La palette s'harmonise-t-elle avec la scène ? — Le mode Thème a son propre contrôle de palette à l'étape 2 ; Standard/Cinématique s'appuient sur l'ADN de l'identité — si cream est trop clair pour une scène lumineuse, changer d'identité (ink, anchor) plutôt que de lutter contre la palette verrouillée. L'outil de prévisualisation montre la palette extraite par zone afin que vous puissiez comparer avec la palette de l'identité choisie.
Les défauts courants pris ici : occlusion trop large (ajuster heroKernel), héros flottant trop haut (forcer fg), police trop petite (l'heuristique de fit-fonts donne la taille maximale pour les lignes de rail — autoriser 2 lignes pour les mots longs au lieu d'une troncature à 1 ligne).
Portes de remise
render-and-composite.sh exécute quatre portes avant d'écrire final.mp4 :
- Timing — chaque fenêtre de héros ≥ 0.6s d'intervalle entre les bords
- Occlusion+héros — le pic de couverture du matte dans la zone du héros est ≥ 30% (sinon le héros flotte nu)
- Débordement — aucune ligne de légende ne dépasse les marges de sécurité de la scène
- Remise — le répertoire de travail est nettoyé (mais
history/conserve un instantané pour les révisions)
Chaque porte qui échoue écrit un fichier .gate-failure dans le répertoire du projet avec la raison et s'arrête. L'agent doit corriger le problème et relancer.
Utilisation de l'API / autonome
Idéal pour une adoption par npx hyperframes --skill embedded-captions plan.json ou pour qu'un agent appelle createAgentText.cjs avec un rapport de transcription — voir le contrat d'interface dans scripts/README.md.
Les déclencheurs de l'utilisateur final : « ajoute des sous-titres à cette vidéo », « légendes intégrées », « sous-titres cinématiques », « motion graphics au texte », « fais un effet », « 炸 », « 特效字幕 », « comme dans AE », ou toute identité nommée du catalogue (anchor, neon, glitch, chrome, etc.).
En mode complètement autonome, l'agent sonde le clip, choisit la meilleure identité dans le catalogue, crée le fichier de création, compile et rend — une seule commande. La vérification humaine se fait au stade des aperçus QA.