Installation du plugin : Avant les commandes de configuration ou de fraîcheur, suivez les règles d'installation du plugin lorsque cette compétence se trouve dans un plugin HyperFrames. Les installations autonomes conservent les instructions de mise à jour ci-dessous.

Avant tout, maintenez cette compétence à jour — confirmez avec l'utilisateur avant d'exécuter : npx hyperframes skills update embedded-captions. Une opération rapide qui ne fait rien si tout est à jour ; sinon, elle met à jour cette compétence ainsi que les compétences du domaine de base dont elle 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 des détails d'implémentation). Standard (par défaut) construit un rail propre et textuel (sous-titre en bas qui porte la majeure partie du texte) + un point culminant embed composité dans la scène derrière le sujet au moment clé. Cinématique est purement embed — pas de rail, chaque légende compositée derrière le sujet (typographie héroïque, accumulation, occlusion comme effet). Thème est une constitution thématique complète — paradigme de corps × morceau héroïque × effet 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 utilisent le mode Standard ; l'embed est le pic 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").

Prérequis d'exécution

Les installations via plugin utilisent une CLI groupée et épinglée au manifeste pour le détourage, la transcription et le rendu ; aucun checkout de code source n'est nécessaire. Les outils d'aperçu local et de mesure des légendes nécessitent également Sharp, Puppeteer (avec son navigateur Chromium) et GSAP. Installez-les dans le projet de sous-titrage, pas dans le plugin en lecture seule :

npm install --prefix <projet> --save-dev --save-exact [email protected] [email protected] [email protected]

Conservez le fichier lock du projet. Si ces dépendances existent déjà, utilisez leurs versions verrouillées plutôt que de les écraser. Bash et FFmpeg/ffprobe doivent être dans le PATH. Le détourage et la transcription peuvent télécharger leurs propres modèles lors de la première utilisation.

Le rendu attend que la CLI se termine avec succès avant de composer. L'ancien chien de garde shell HF_TIMEOUT_S n'est plus utilisé : un fichier volumineux partiel ne prouve pas que le rendu est terminé. Un argument de checkout explicite ou HYPERFRAMES_ROOT sélectionne la CLI du contributeur au lieu de l'épingle du plugin. Annulez un rendu bloqué normalement via le CLI/terminal ; l'outil de légendes ne force pas l'arrêt ni ne récupère un rendu à partir d'un instantané de processus.

Flux opérationnel (TL;DR)

Acheminé via /hyperframes, la couche d'intention confirme uniquement l'entrée (quelle vidéo) et annonce le choix d'identité comme une question différée — la shortlist a besoin de la vidéo inspectée, donc elle reste à l'étape 1 ci-dessous ; les questions de mise en forme de la couche ne s'appliquent pas (le métrage est intact, il n'y a pas de storyboard à réviser). Un BRIEF.md, s'il est présent, contient l'entrée confirmée et d'éventuelles notes de l'utilisateur — lisez-le d'abord.

Le texte de fabrication ci-dessous est long ; le pipeline lui-même est court — et tout ce qui est déterministe est calculé ou compilé, jamais rédigé à la main :

Porte de décision (refuser les mauvaises vidéos) → 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 dossier du projet existe déjà avec la vidéo à l'intérieur — matte.cjs/transcribe.cjs adoptent toute vidéo présente comme source.mp4) → bash scripts/prepare.sh <projet> (détourage ∥ transcription ∥ enveloppe audio en parallèle, puis zones de sécurité v2 avec palette de scène/optique/éclairage — une commande, rien oublié)
rédiger un petit JSON de choix créatifs (lire safe-zones.json en premier) : Cinématique → cinematic.json → make-cinematic.cjs (dérive plan.json et le compile) ; Thème → theme.json → make-theme.cjs (paradigmes rail/panel/poème/takeover ; anchor est le rail silencieux par défaut)
QA visuelle : node scripts/preview-frames.cjs <projet> → aperçus composites fidèles en ~2s/image (pas de rendu). Vérifiez § QA visuelle avant de payer un rendu.
render-and-composite.sh → portes (timing / occlusion+héro / débordement / remise) → final.mp4

Règles importantes souvent oubliées :

rail (par défaut) + embed (promotion). drop (remplissage, non affiché) / rail (sous-titre textuel en bas, devant, porte la majeure partie du texte) / embed (un mot clé composité 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 INCHANGÉE (Standard/Cinématique ; le budget PLATE du mode Thème est la seule exception sanctionnée — les beats de réaction enregistrés (charge-dim, punch, shake, grain) définis par l'ADN du thème et appliqués APRÈS le composite de détourage pour que sujet+texte+plaque bougent comme un seul cadre) — seules les légendes sont ajoutées ; le détourage permet simplement au sujet d'occlure la piste embed. Ne jamais étalonner/recolorer/ajouter de lignes de balayage au métrage.
Deux livres de règles : rail → references/rail.md (fin), fabrication embed → references/composition-craft.md (riche, embed uniquement). Parcourez 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/hum, bégaiements, auto-corrections	non affiché
rail	le défaut — contenu parlé ordinaire (textuel)	sous-titre propre en bas, devant, lisible. Un mot fort peut obtenir un `emphasis` (couleur d'accent / pop de mot actif) — il reste sur le rail.
embed	un sommet promu — le beat principal	un grand mot composité derrière le sujet (occlusion de détourage), entrée + sortie conçues

Le rail porte la majeure partie du texte ; l'embed est le pic rare et mérité. La rareté est par beat/bloc, pas par vidéo : ≤1 héros par bloc (pensée), jamais deux co-visibles, ≥ un battement d'air entre les fenêtres héros (le compilateur avertit en dessous de 0.6s). Une vidéo courte → généralement 1–2 ; une longue explication → environ un par section. Parmi plusieurs héros, le plus grand créé est l'APEX (lui seul obtient le lockup embed complet + soulèvement de largeur) ; les plus petits sont des pics MINEURS qui chevauchent leur colonne comme des lignes d'accentuation surdimensionnées (avant-plan, mouvement amorti) — ce n'est pas chaque beat qui a besoin de la vitrine de détourage, c'est exactement ce qui fait de l'apex un événement. Intégrer chaque mot reste l'erreur courante.

Les identités de surface de rail construisent exactement cela (rail = rail.html, embed = le point culminant dans index.html). Les identités de flux en colonnes suppriment le rail et rendent tout en style embed — recommandez-les uniquement pour les demandes d'ambiance plutôt que de texte textuel, jamais pour les explications / voix off où les mots doivent être lus (CATALOG.md code cela par identité).

Étape 0 — choisir UNE identité dans le CATALOGUE

Un front-end, 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 à partir de la ligne du catalogue. Ne jamais présenter "Standard vs Cinématique vs Thème" comme une question — ce sont des noms de backend (un produit a une seule UX même avec plusieurs moteurs). Le catalogue code tout ce dont l'acheminement 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 ("surprenez-moi" / "décidez pour moi"), choisissez vous-même dans votre shortlist et indiquez le pourquoi en une ligne au lieu de demander.

Procédure : inspecter la vidéo → shortlister 2–3 identités du catalogue → recommander UNE avec un argument d'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 faites pas de choix silencieux par défaut.

(Le tableau complet des identités se trouve dans CATALOG.md — source unique de vérité pour l'acheminement. La documentation des moteurs ci-dessous décrit le contrat de création de chaque backend.)

CATALOG.md est tout l'espace de réponses ici : ce workflow ne recherche pas dans 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 émettent eux-mêmes la composition, donc un élément du registre — les blocs caption-* inclus — n'a rien à monter. Un bloc de registre stylise le texte sur un canevas conçu ; cette compétence grave des légendes dans une vidéo via un détourage. Quand aucune identité ne correspond à la demande, dites-le et choisissez la plus proche, plutôt que de chercher en dehors du catalogue.

Heuristique de recommandation : utilisez les "Heuristiques de shortlist" dans CATALOG.md — elles sont au niveau de l'identité (par exemple "炸" shortliste ordnance/stomp/terminal/loud et choisit selon CE qui doit exploser), jamais au niveau de la catégorie. En cas de doute → anchor.

Cinématique → écrire cinematic.json pour un modèle verrouillé, compilé par make-cinematic.cjs.
Thème → lire themes/README.md, créer theme.json, exécuter scripts/render-theme.sh (compile + rend + réaction de plaque → final_fx.mp4).

Porte de décision — À EXÉCUTER EN PREMIER

Inspectez la vidéo et classez 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%

Lisez les échantillons. Refusez si :

Plusieurs intervenants / coupures franches (divisez et traitez chaque plan, ou refusez)
Pas de sujet humain (cette compétence est pour des têtes parlantes)
Moins de 3 secondes, pas de discours, ou visage jamais clairement visible — transcribe.cjs prévient quand l'audio est quasi-silencieux (Whisper hallucine des mots comme "Merci." sur le silence) ; tenez-en compte et refusez plutôt que de sous-titrer des mots fabriqués
La source a déjà des légendes/sous-titres incrustés ou des graphiques de texte lourds — ajouter un second système de légendes entre en conflit et le métrage est livré intact (pas de recouvrement/retouche). Le texte incrusté apparaît souvent seulement au milieu de la vidéo : échantillonnez une planche contact à 1ips (ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png), ne vous fiez pas à 3 images ponctuelles.
La transcription est incompréhensible — un discours non natif / avec un fort accent peut être transcrit en charabia confiant. Lisez transcript.json pour vérifier la cohérence avant de créer ; si cela ne ressemble pas à une langue, essayez WHISPER_MODEL=medium une fois, sinon refusez (un rail textuel de mots fabriqués est pire que pas de légendes).
Caméra à l'épaule mouvementée avec mouvement rapide (le détourage scintille)

Sondes pré-vol (ne coûtent rien, évitent les pires échecs)

Son de coupure de plan. Échantillonnez les images à 20%, 50%, 80%. Si un sujet/scène différent apparaît, recadrez la vidéo avant la coupure.
Son 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.
Son 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 cache de glyphe, 180+ → texte opaque + cache (jamais de texte clair nu). Les modèles cinématiques sont crème+screen et VERROUILLÉS — utilisez cette sonde pour choisir une identité appropriée (scènes lumineuses → ink, ou le thème anchor à rail opaque), jamais pour en recolorer une.
Recommandation d'identité par ton (vous recommandez ; l'utilisateur choisit — voir Étape 0 + CATALOG.md). Explication / interview / mots à lire absolument → identités de surface rail/panel ; poétique / social / "cinématographique" → identités de flux en colonnes 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é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>       # détourage ∥ 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 selon le mode
   Cinématique : créer cinematic.json → node scripts/make-cinematic.cjs <projet>
   Thème :      créer theme.json → bash scripts/render-theme.sh <projet>   (compile + rend + effets de plaque)
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 + historique/ instantané
   (Mode Thème : SAUTEZ les étapes 3b/5 — render-theme.sh exécute déjà compile + render-and-composite
    + _postfx.sh ; le livrable est final_fx.mp4, final.mp4 est sans réaction de plaque)

L'étape 1 init vérifie les compétences installées par rapport aux dernières sur GitHub et met à jour l'ensemble global si certaines sont obsolètes.

L'étape 3 diffère selon le mode :

Étape 3 — Mode Cinématique (embed pur)

Lisez safe-zones.json en premier. Les plans de narration vont dans zones.hugLeft/hugRight — bandes propres ADOSSÉES à la silhouette (le texte loin du corps donne l'impression de flotter, pas d'être intégré ; les coins éloignés sont le recours, pas la valeur par défaut). Le héros par défaut est heroAnchor/heroBands.best (centré SUR le sujet, ~30–55% occulté). recommendation:"fg" déplace la NARRATION devant pour la lisibilité ; le héros reste intégré quand heroBands.feasible — héros-avant-plan est le dernier recours.
L'ADN est l'identité que vous avez choisie à l'Étape 0

… [tronqué pour la traduction]

Étape 3 — Mode Thème

… [section non fournie dans l'original]

QA visuelle — avant le rendu

node scripts/preview-frames.cjs <projet> génère des aperçus composites rapides. Vérifiez :

Occlusion : les mots embed sont-ils correctement cachés derrière le sujet ?
Placement : le rail et l'embed sont-ils dans les zones de sécurité ?
Lisibilité : le texte se détache-t-il suffisamment de l'arrière-plan ?

Si la QA échoue, ajustez le JSON créatif et relancez l'étape 3 ou 4, pas le rendu complet.

Références

CATALOG.md — 35 identités visuelles
references/rail.md — règles de rail
references/composition-craft.md — règles de composition embed
themes/README.md — enregistrement des thèmes
dna/README.md — validation des identités

kinyias/hyperframes-templates

Qu'est-ce que hyperframes-templates ?

Demander à votre IA préférée

Documentation