Installation du plugin : Avant les commandes de configuration ou de mise à jour, suivez les règles d'exécution du plugin lorsque cette compétence se trouve à l'intérieur d'un plugin HyperFrames. Les installations autonomes conservent les instructions de mise à jour ci-dessous.
D'abord, maintenez 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 actualise cette compétence ainsi que les compétences de base du domaine dont elle dépend avant que vous ne les utilisiez.
Légendes incrustées
Un catalogue, choisi au départ (CATALOG.md — 35 identités ; les moteurs derrière sont des détails techniques). Standard (par défaut) construit un rail propre textuel (sous-titre en tiers inférieur portant la majeure partie du texte) + un incrusté culminant composé dans la scène derrière le sujet au moment clé. Cinématique est un incrusté 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 corporel × pièce maîtresse héroïque × effets avant × réaction de plaque, composée à partir de registres (themes/README.md) : ordnance terminal neonsign stardust stomp. La plupart des vidéos explicatives / voix-off sont Standard ; l'incrusté est le point culminant rare et mérité — incruster chaque mot est l'erreur courante ; Thème est réservé aux demandes de niveau VFX ("燃", "特效", "comme dans After Effects").
Prérequis d'exécution
Les installations de plugin utilisent la CLI groupée et épinglée au manifeste pour le matting, la transcription et le rendu ; aucune extraction de code source n'est nécessaire. Les utilitaires d'aperçu local et de mesure des légendes nécessitent également Sharp, Puppeteer (avec son navigateur Chromium) et GSAP. Installez ces éléments 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 verrou 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 la composition. L'ancien chien de garde HF_TIMEOUT_S n'est plus utilisé : un fichier partiel volumineux ne prouve pas que le rendu est terminé. Un argument explicite de vérification de construction ou HYPERFRAMES_ROOT sélectionne la CLI du contributeur au lieu du verrou du plugin. Annulez un rendu bloqué normalement via la CLI/le terminal ; l'utilitaire 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 (résumé)
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 restreinte nécessite le clip sondé, donc elle reste à l'étape 1 ci-dessous ; les questions de forme d'exécution de la couche ne s'appliquent pas (le métrage n'est pas touché, 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 de mode/catégorie)
hyperframes init(sautez si le répertoire du projet existe déjà avec la vidéo à l'intérieur —matte.cjs/transcribe.cjsadoptent n'importe quelle vidéo dans le 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 commande, rien oublié)- écrire un petit JSON de choix créatifs (lisez
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/panneau/poème/prise de contrôle ;anchorest le rail silencieux par défaut) - QA visuelle :
node scripts/preview-frames.cjs <projet>→ aperçus composites fidèles en ~2s/trame (pas de rendu). Vérifiez § QA visuelle avant de payer pour un rendu. render-and-composite.sh→ portes (timing / occlusion+héroïque / débordement / transfert) →final.mp4
Règles importantes que les gens oublient :
- rail (par défaut) + incrusté (promotion).
drop(remplissage, non affiché) /rail(sous-titre textuel en tiers inférieur, devant, porte la majeure partie du texte) /incrusté(un mot clé composé derrière le sujet). Le mode Standard fait les deux, incrustant uniquement le(s) point(s) culminant(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 autorisée — les beats 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 matting afin que le sujet+texte+plaque bougent comme un seul cadre) — les légendes sont la seule chose ajoutée ; le matting permet juste au sujet d'occulter la piste d'incrusté. Ne jamais étalonner/recoloriser/ajouter des lignes de balayage au métrage.
- Deux manuels : rail → references/rail.md (mince), artisanat d'incrusté → references/composition-craft.md (riche, uniquement incrusté). Parcourez selon les besoins.
Modèle de légende — rail + incrusté
Chaque phrase parlée est l'une des trois choses :
| 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 propre en tiers inférieur, devant, lisible. Un mot percutant peut obtenir un accent emphasis en ligne (couleur d'accent / pop de mot actif) — il reste sur le rail. |
| incrusté | un point culminant promu — le temps fort | un grand mot composé derrière le sujet (occlusion de matting), entrée + sortie conçues |
Le rail porte la majeure partie du texte ; l'incrusté 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 co-visibles, ≥ un temps de respiration entre les fenêtres héroïques (le compilateur avertit en dessous de 0,6 s). Un clip court → généralement 1–2 ; une longue explication → ~un par section. Parmi plusieurs héros, le plus grand créé est l'APEX (lui seul obtient le plein verrouillage incrusté + élévation ajustée à la largeur) ; les plus petits sont des pics MINEURS qui suivent leur colonne comme des lignes d'accentuation surdimensionnées (premier plan, mouvement amorti) — tous les beats n'ont pas besoin de la vitrine de matting, ce qui est exactement ce qui maintient 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, incrusté = le point culminant dans index.html). Les identités de flux de colonnes abandonnent le rail et font tout en style incrusté — recommandez-les uniquement pour les demandes d'ambiance plutôt que textuelles, jamais pour les vidéos explicatives / voix-off où les mots doivent être lus (CATALOG.md code cela par identité).
Étape 0 — choisir UNE identité du CATALOGUE
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 à partir de la ligne du catalogue. Ne jamais poser "Standard vs Cinématique vs Thème" comme question — ce sont des noms 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 de contiguïté 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 ("surprends-moi" / "décide pour moi"), choisissez vous-même dans votre liste restreinte et indiquez le pourquoi en une ligne au lieu de demander.
Procédure : sondez le clip → établissez une liste restreinte de 2–3 identités du catalogue → recommandez UNE avec un pourquoi en une ligne → l'utilisateur choisit (mode autonome : vous choisissez, en indiquant le pourquoi) → créez 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 créer. Ne prenez pas de valeur par défaut silencieusement.
(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 création de chaque backend.)
CATALOG.md est tout l'espace de réponse ici : ce flux de travail ne recherche pas dans le registre de composants HyperFrames. Les flux de travail de composition exécutent npx hyperframes catalog avant de créer un aspect 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 du registre — y compris les blocs caption-* — n'a rien à monter dedans. Un bloc de registre stylise le texte sur un canevas conçu ; cette compétence grave des légendes dans le métrage de quelqu'un via un matting. Lorsqu'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 sélection » dans CATALOG.md — elles sont au niveau de l'identité (par exemple "燃" sélectionne ordnance/stomp/terminal/loud et choisit CE QUI doit exploser), jamais au niveau de la catégorie. Incertain → anchor.
- Cinématique → écrivez
cinematic.jsonpour un modèle verrouillé, compilé parmake-cinematic.cjs. - Thème → lisez themes/README.md, créez
theme.json, exécutezscripts/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 classifiez la scène avant chaque mode.
ffprobe <video.mp4> # spécifications
ffmpeg -ss <t> -i <video.mp4> -vframes 1 echantillon.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 les talking-head)
- Moins de 3 secondes, pas de parole, ou visage jamais clairement visible —
transcribe.cjsavertit lorsque l'audio est quasi silencieux (Whisper hallucine des mots comme « Merci. » sur du 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 le métrage est livré intact (pas de recouvrement/retouche). Le texte incrusté apparaît souvent seulement au milieu du clip : échantillonnez une planche contact à 1 image par seconde (
ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" planche.png), ne vous fiez pas à 3 images ponctuelles. - La transcription est nulle — la parole non native/fortement accentuée peut être transcrite en charabia confiant. Lisez
transcript.jsonpour vérifier la cohérence avant de créer ; si cela ne ressemble pas à un langage, essayezWHISPER_MODEL=mediumune fois, sinon refusez (un rail textuel de mots fabriqués est pire que pas de légendes). - Mouvement rapide avec caméra à l'épaule chargée (scintillement du matting)
Sondages pré-vol (ne coûtent rien, évitent les pires échecs)
- Sondage de coupure de plan. Échantillonnez des images à 20 %, 50 %, 80 %. Si un sujet/scène différent apparaît, coupez 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ématiques sont crème+screenet VERROUILLÉS — utilisez ce sondage pour choisir une identité appropriée (scènes lumineuses →ink, ou le thèmeanchorà rail opaque), jamais pour en recoloriser une. - Recommandation d'identité par ton (vous recommandez ; l'utilisateur choisit — voir Étape 0 + CATALOG.md). explicatif / entretien / mots à lire absolument → identités de surface rail/panneau ; poétique / social / « cinématique » → identités de flux de colonnes selon le 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 restreinte 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> # matting ∥ 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éez un petit JSON ; voir ci-dessous selon le mode
Cinématique : créez cinematic.json → node scripts/make-cinematic.cjs <projet>
Thème : créez theme.json → bash scripts/render-theme.sh <projet> (compile + rend + effets plaque)
4. node scripts/preview-frames.cjs <projet> # ~2s/trame aperçus composites → § QA visuelle (AVANT le rendu)
5. bash scripts/render-and-composite.sh <projet> # portes → final.mp4 + instantané history/
(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 avant la 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 (incrusté pur)
- Lisez
safe-zones.jsond'abord. Les plans de narration vont danszones.hugLeft/hugRight— bandes propres JUXTAPOSÉES à la silhouette (le texte loin du corps se lit comme flottant, pas incrusté ; les coins éloignés sont le repli, pas le défaut). Le héros par défaut va dansheroAnchor/heroBands.best(centré SUR le sujet, ~30–55 % occulté).recommendation:"fg"déplace la NARRATION devant pour la lisibilité ; le héros reste incrusté chaque fois queheroBands.feasible— héros-premier-plan est le dernier recours. - L'ADN est l'identité que vous avez choisie à l'Étape 0