Installation du plugin : Avant les commandes de configuration ou de mise à jour de la fraîcheur, suivez les règles d'exécution du plugin lorsque cette compétence se trouve dans un plugin HyperFrames. Pour une installation autonome, conservez les instructions de mise à jour ci-dessous.

Tout d'abord, 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 du domaine principal dont elle dépend, avant que vous ne vous appuyiez dessus.

Légendes incrustées

Un catalogue, choisi au préalable (CATALOG.md — 35 identités ; les moteurs derrière sont des détails techniques). Standard (par défaut) construit un rail de sous-titres propre (barre inférieure portant la majeure partie du texte) + un point culminant incrusté composé dans la scène derrière le sujet au moment fort. Cinématique est une incrustation pure — pas de rail, chaque légende est composée derrière le sujet (typographie héroïque, accumulation, occlusion comme effet). Thème est une constitution complète thématique — paradigme du corps × pièce maîtresse héroïque × effets avant × réaction de la plaque, composée à partir de registres (themes/README.md) : ordnance terminal neonsign stardust stomp. La plupart des vidéos explicatives / voix off sont en mode Standard ; l'incrustation est le sommet rare et mérité — incruster chaque mot est l'erreur courante ; le mode 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 intégrée et épinglée au manifeste pour le détourage, la transcription et le rendu ; aucune extraction du code source n'est nécessaire. Les aides à l'aperçu local et à la mesure des légendes nécessitent également Sharp, Puppeteer (avec son 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 de verrouillage du projet. Si ces dépendances existent déjà, utilisez leurs versions verrouillées au lieu de les remplacer. 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 watchdog shell HF_TIMEOUT_S n'est plus utilisé : un fichier partiel volumineux ne prouve pas que le rendu est terminé. Un argument explicite de checkout de construction ou HYPERFRAMES_ROOT sélectionne la CLI du contributeur au lieu de l'épingle du plugin. Annulez un rendu bloqué normalement via la CLI/terminal ; l'outil d'aide aux 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 (quel clip) et annonce le choix d'identité comme une question différée — la liste de sélection a besoin du clip sondé, donc elle reste à l'étape 1 ci-dessous ; les questions de forme d'exécution de la couche ne s'appliquent pas (les images ne sont pas modifiées, il n'y a pas de storyboard à examiner). Un BRIEF.md, lorsqu'il est présent, contient l'entrée confirmée et les é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 é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 de mode/catégorie)
hyperframes init (ignorer si le répertoire du projet existe déjà avec la vidéo à l'intérieur — matte.cjs/transcribe.cjs adoptent n'importe quelle vidéo dans le répertoire 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 d'abord) : Cinématique → cinematic.json → make-cinematic.cjs (dérive plan.json et le compile) ; Thème → theme.json → make-theme.cjs (paradigmes rail/panneau/poème/prise de contrôle ; anchor est 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érifiez § QA visuelle avant de payer un rendu.
render-and-composite.sh → portes (timing / occlusion+héro / débordement / relais) → final.mp4

Règles importantes souvent négligées :

rail (défaut) + incrustation (promotion). drop (bourrage, non affiché) / rail (sous-titre textuel en bas, devant, porte la majeure partie du texte) / embed (un mot clé composé derrière le sujet). Le mode Standard fait les deux, n'incrustant que le(s) sommet(s). Voir § Modèle de légende.
La vidéo est livrée NON MODIFIÉE (Standard/Cinématique ; le budget PLATE du mode Thème est la seule exception autorisée — les battements de réaction contrôlés par registre (assombrissement de charge, coup, secousse, grain) définis par l'ADN du thème et appliqués APRÈS la composition du détourage pour que le sujet+texte+plaque bougent comme un seul cadre) — les légendes sont la seule chose ajoutée ; le détourage permet juste au sujet d'occulter la piste incrustée. Ne jamais étalonner/recolorer/ajouter de lignes de balayage aux images.
Deux recueils de règles : rail → references/rail.md (mince), fabrication d'incrustation → references/composition-craft.md (riche, réservé à l'incrustation). Parcourez selon le besoin.

Modèle de légende — rail + incrustation

Chaque phrase parlée est l'une des trois choses suivantes :

	Quoi	Comment c'est affiché
drop	remplissage — euh/hein, bégaiements, auto-corrections	non affiché
rail	le défaut — contenu parlé ordinaire (textuel)	sous-titre en bas, devant, lisible. Un mot fort peut obtenir une mise en évidence `emphasis` en ligne (couleur d'accent / pop de mot actif) — il reste sur le rail.
embed	un sommet promu — le battement principal	un grand mot composé derrière le sujet (occlusion du détourage), entrée + sortie conçues

Le rail porte la majeure partie du texte ; l'incrustation est le sommet rare et mérité. La rareté est par battement/bloc, pas par clip : ≤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). Un clip court → généralement 1–2 ; une longue explication → ~un par section. Parmi plusieurs héros, le plus grand rédigé est l'APEX (lui seul reçoit l'incrustation complète de verrouillage + l'élévateur de largeur) ; les plus petits sont des sommets MINEURS qui chevauchent leur colonne comme des lignes d'accentuation surdimensionnées (avant-plan, mouvement amorti) — ce n'est pas à chaque battement qu'il faut la mise en valeur du détourage, ce qui permet précisément à l'apex de rester un événement. Incruster chaque mot reste l'erreur courante.

Les identités de surface de rail construisent exactement cela (rail = rail.html, incrustation = le point culminant dans index.html). Les identités de flux de colonnes abandonnent le rail et transforment tout en style incrustation — 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 l'encode par identité).

Étape 0 — choisir UNE identité dans le CATALOG

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 rédaction sont dérivés par recherche à partir de 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 expérience utilisateur même avec plusieurs moteurs). Le catalogue encode tout ce dont le routage 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 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 liste de 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) → rédiger le fichier de cette identité. Les identités sont verrouillées sur le 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 le routage. Les documents du moteur ci-dessous décrivent le contrat de rédaction de chaque backend.)

CATALOG.md est l'espace de réponse complet 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 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 — y compris les blocs caption-* — n'a rien dans quoi se monter. Un bloc de registre stylise le texte sur un canevas conçu ; cette compétence grave les légendes dans les images de quelqu'un via un détourage. 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 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 cinematic.json pour un modèle verrouillé, compilé par make-cinematic.cjs.
Thème → lire themes/README.md, rédiger 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

Sondez 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 rendez chaque plan, ou refusez)
Pas de sujet humain (cette compétence est pour le talking-head)
Moins de 3 secondes, aucune parole, ou visage jamais clairement visible — transcribe.cjs pré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/éléments graphiques textuels incrustés — l'ajout d'un deuxième système de légendes entre en conflit et les images sont livrées non modifiées (pas de recouvrement/de repeinture). 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 inutilisable — la parole non native/fortement accentuée peut être transcrite en charabia confiant. Lisez transcript.json avant de rédiger ; si cela ne s'analyse pas comme une langue, essayez WHISPER_MODEL=medium une fois, sinon refusez (un rail textuel de mots fabriqués est pire que pas de légendes).
Mouvement à main levé agité (le détourage scintille)

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

Sondage de coupure de plan. Échantillonnez les images à 20 %, 50 %, 80 %. Si un sujet/scène différent apparaît, recadrez le clip avant la coupure.
Sondage de boîte aux lettres / pilier. Barres noires sur la première image ? Calculez le rectangle de contenu sûr et contraignez le placement des légendes à l'intérieur de celui-ci.
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ématiques sont crème+écran et VERROUILLÉS — utilisez ce sondage 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). explicative / interview / mots à lire absolument → identités de surface de rail/panneau ; poétique / social / « cinématographique » → identités de flux de 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 liste de sélection 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] rédigez un petit JSON ; voir ci-dessous selon le mode
   Cinématique : rédigez cinematic.json → node scripts/make-cinematic.cjs <projet>
   Thème :     rédigez 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 : IGNOREZ les étapes 3b/5 — render-theme.sh exécute déjà la compilation + rendu-et-composition
    + _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 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 (incrustation pure)

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

courtneymgabrus-star/Video

Qu'est-ce que Video ?

Demander à votre IA préférée

Documentation