Installation des plugins : Avant d'exécuter les commandes de configuration ou de mise à jour, suivez les règles d'exécution des plugins lorsque cette compétence se trouve dans un plugin HyperFrames. Les installations autonomes conservent les instructions de mise à jour ci-dessous.
Avant tout, gardez cette compétence à 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, elle rafraîchit cette compétence ainsi que les compétences de base dont elle dépend avant de vous y fier.
Que fait Sous-titres incrustés (Embedded Captions) ?
Un catalogue, choisi au début (CATALOG.md — 35 identités ; les moteurs derrière sont des détails d'implémentation). Standard (par défaut) construit un rail propre (sous-titre en bas de l'écran) + un embed climax composé dans la scène derrière le sujet au moment fort. Cinématique est un embed pur — 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 × setpiece héroïque × fx avant × réaction de la plaque, composé à 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 pic rare et mérité — incruster 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 la CLI groupée et épinglée dans le manifeste pour le matting, la transcription et le rendu ; aucun checkout de code source n'est nécessaire. L'aperçu local et les outils de mesure des légendes nécessitent également Sharp, Puppeteer (avec son navigateur Chromium) et GSAP. Installez-les dans le projet de légendes, pas dans le plugin en lecture seule :
npm install --prefix <projet> --save-dev --save-exact [email protected] [email protected] [email protected]
Conservez le fichier lockfile du projet. Si ces dépendances existent déjà, utilisez leurs versions verrouillées au lieu de les écraser. Bash et FFmpeg/ffprobe doivent être dans le PATH. Le matting 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 watchdog HF_TIMEOUT_S n'est plus utilisé : un fichier partiel volumineux ne prouve pas que le rendu est terminé. Un argument explicite --built-checkout ou HYPERFRAMES_ROOT sélectionne la CLI du contributeur au lieu du verrouillage du plugin. Annulez un rendu bloqué normalement via la CLI/le terminal ; l'outil de légende 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 (quel clip) et annonce le choix de l'identité comme une question différée — la shortlist a besoin du clip sondé, donc elle reste à l'étape 1 ci-dessous ; les questions sur la forme du déroulement ne s'appliquent pas (le métrage est intact, 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 éventuelles 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 manuellement :
- Porte de décision (refuser les mauvais clips) → choisir UNE identité du CATALOG.md (35 identités ; moteur/compilateur dérivé par recherche — ne jamais poser de question de 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 comme source.mp4) →bash scripts/prepare.sh <projet>(matte ∥ transcribe ∥ envelope 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.jsond'abord) : Cinématique →cinematic.json→make-cinematic.cjs(dériveplan.jsonet le compile) ; Thème →theme.json→make-theme.cjs(paradigmes rail/panel/poem/takeover ;anchorest le rail calme par défaut) - QA visuel :
node scripts/preview-frames.cjs <projet>→ aperçus composites fidèles en ~2s/image (pas de rendu). Consultez § QA visuel avant de payer un rendu. render-and-composite.sh→ portes (timing / occlusion+hero / overflow / hand-off) →final.mp4
Règles importantes souvent oubliées :
- rail (par défaut) + embed (promotion).
drop(remplissage, non affiché) /rail(sous-titre textuel en bas de l'écran, devant, porte la plupart du texte) /embed(un mot clé composé derrière le sujet). Le mode Standard fait les deux, en incrustant uniquement le(s) pic(s). Voir § Modèle de légende. - La vidéo est livrée INTACTE (Standard/Cinématique ; Le budget PLATE du mode Thème est la seule exception sanctionnée — les beats de réaction définis par registre (charge-dim, punch, shake, grain) sont définis par l'ADN du thème et appliqués APRÈS la composition du matte de sorte que sujet+texte+plate bougent comme un seul cadre) — les légendes sont la seule chose ajoutée ; le matte permet simplement au sujet d'occlure la piste embed. Ne jamais étalonner/recoloriser/ajouter des scanlines au métrage.
- Deux règles : rail → references/rail.md (fin), artisanat 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/hem, bégaiements, autocorrections | non affiché |
| rail | le défaut — contenu parlé ordinaire (textuel) | sous-titre propre en bas de l'écran, devant, lisible. Un mot d'emphase peut obtenir un surlignage emphasis en ligne (couleur d'accent / pop de mot actif) — il reste sur le rail. |
| embed | un pic promu — le point fort du titre | un grand mot composé derrière le sujet (occlusion par matte), entrée + sortie conçues |
Le rail porte la plupart du texte ; l'embed est le pic rare et mérité. La rareté est par beat/bloc, pas par clip : ≤1 héros par bloc (pensée), jamais deux co-visibles, ≥ un beat d'air entre les fenêtres de héros (le compilateur prévient en dessous de 0.6s). Un clip court → généralement 1–2 ; une longue explication → ~un par section. Parmi plusieurs héros, le plus grand est l'APEX (lui seul obtient le lockup embed complet + élévation à largeur ajustée) ; les plus petits sont des pics MINEURS qui chevauchent leur colonne comme des lignes d'emphase surdimensionnées (fg, mouvement atténué) — tous les beats n'ont pas besoin de la vitrine matte, ce qui maintient précisément l'apex comme un événement. Incruster chaque mot est toujours l'erreur courante.
Les identités de surface de rail construisent exactement cela (rail = rail.html, embed = le climax dans index.html). Les identités à flux de colonnes suppriment le rail et font tout en style embed — recommandez-les uniquement pour les demandes d'ambiance plutôt que textuelles, jamais pour les explications / voix off où les mots doivent être lus (CATALOG.md encode cela par identité).
Étape 0 — choisir UNE identité du CATALOG
Un frontal, 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 paramètres sont dérivés par recherche dans la ligne du catalogue. Ne jamais poser la question «Standard vs Cinématique vs Thème» — ce sont des noms de backend (un produit a une seule UX même avec plusieurs moteurs). Le catalogue encode tout ce dont l'acheminement a besoin : surface de lecture, voix, recommandé pour, 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/references/brief-contract.md § 1) : en mode autonome («surprends-moi» / «décide pour moi»), choisissez parmi votre shortlist vous-même et donnez la raison en une ligne au lieu de demander.
Procédure : sonder le clip → court-circuiter 2–3 identités du catalogue → recommander UNE avec une raison en une ligne → l'utilisateur choisit (mode autonome : vous choisissez, en donnant la raison) → rédiger 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 rédiger. Ne prenez pas de valeur par défaut en silence.
(Le tableau complet 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 paramétrage de chaque backend.)
CATALOG.md est tout l'espace de réponse ici : ce workflow ne recherche pas dans le registre de composants HyperFrames. Les workflows de composition exécutent npx hyperframes catalog avant de rédiger un look nommé ; celui-ci ne doit pas. Ses moteurs sont des compilateurs verrouillés qui consomment cinematic.json / theme.json et émettent eux-mêmes la composition, donc un élément de registre — les blocs caption-* inclus — n'a rien dans quoi se monter. Un bloc de registre stylise du texte sur un canvas conçu ; cette compétence grave des légendes dans le métrage 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 court-circuit» dans CATALOG.md — elles sont au niveau de l'identité (par ex. «炸» court-circuite ordnance/stomp/terminal/loud et choisit selon CE qui doit exploser), jamais au niveau de la catégorie. Incertain → anchor.
- Cinématique → écrire
cinematic.jsonpour un template verrouillé, compilé parmake-cinematic.cjs. - Thème → lire themes/README.md, rédiger
theme.json, exécuterscripts/render-theme.sh(compile + rendu + réaction de plaque → final_fx.mp4).
Porte de décision — À EXÉCUTER EN PREMIER
Sondez la vidéo et classez la scène avant chaque mode.
ffprobe <video.mp4> # specs
ffmpeg -ss <t> -i <video.mp4> -vframes 1 sample.png # à 20/50/80%
Lisez les échantillons. Refusez si :
- Plusieurs intervenants / cut secs (splitter et rendre chaque plan, ou refuser)
- Pas de sujet humain (cette compétence est pour le plan poitrine)
- Moins de 3 secondes, pas de parole, ou visage jamais clairement visible —
transcribe.cjsprévient 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 incrustés / graphiques de texte lourds — ajouter un second système de légendes crée un conflit et le métrage est livré intact (pas de recouvrement/inpainting). Le texte incrusté apparaît souvent seulement au milieu du clip : échantillonnez une planche contact 1fps (
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 accent fort peut se transcrire en charabia confiant. Lisez
transcript.jsonpour le bon sens avant de rédiger ; si ça ne se décode pas comme une langue, essayezWHISPER_MODEL=mediumune fois, sinon refusez (un rail textuel de mots fabriqués est pire que pas de légendes). - Prise de vue mouvementée avec un mouvement rapide (scintillement du matte)
Sondages pré-vol (ne coûtent rien, évitent les pires échecs)
- Sondage de cut de plan. Échantillonnez des images à 20%, 50%, 80%. Si un sujet/scène différent apparaît, recadrez le clip avant le cut.
- 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 de légende —
en dessous de 60→ le texte clair se lit tel quel,60-180→ ajoutez le scrim de glyphe,180+→ texte opaque + scrim (jamais de texte clair nu). Les templates cinématiques sont crème+screenet VERROUILLÉS — utilisez ce sondage pour choisir une identité adaptée (scènes lumineuses →ink, ou le thèmeanchorà rail opaque), jamais pour recoloriser une identité. - 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ématique» → identités à flux de colonnes par registre ; «炸 / 特效 / VFX» / mondes nommés → identités thématiques. En cas d'incertitude →
anchor(les mots se lisent, scène 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 ∥ transcribe (parallèle) → safe-zones. Une commande.
# → frames_fg/ transcript.json safe-zones.json
3. [ÉTAPE AGENT — la seule étape créative] rédiger un petit JSON ; voir ci-dessous par mode
Cinématique : rédiger cinematic.json → node scripts/make-cinematic.cjs <projet>
Thème : rédiger theme.json → bash scripts/render-theme.sh <projet> (compile + rendu + fx de plaque)
4. node scripts/preview-frames.cjs <projet> # ~2s/image aperçus composites → § QA visuel (AVANT le rendu)
5. bash scripts/render-and-composite.sh <projet> # portes → final.mp4 + historiques/ snapshot
(Mode Thème : SAUTER 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 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 certaines sont obsolètes.
L'étape 3 diffère par mode :
Étape 3 — Mode Cinématique (embed pur)
- Lisez
safe-zones.jsonen premier. Les plans de narration vont danszones.hugLeft/hugRight— bandes propres en BORDURE de la silhouette (le texte loin du corps se lit comme flottant, pas incrusté ; les coins lointains sont le fallback, pas le défaut). Le héros par défaut estheroAnchor/heroBands.best(centré SUR le sujet, ~30–55% occlus).recommendation:"fg"déplace la NARRATION devant pour la lisibilité ; le héros reste incrusté chaque fois queheroBands.feasible— héros-fg est le dernier recours. - L'ADN est l'identité que vous avez choisie à l'Étape 0