Installation du plugin : Avant les commandes de configuration ou de mise à jour, suivez les règles d'exécution du plugin lorsque ce skill se trouve dans un plugin HyperFrames. Les installations autonomes conservent les instructions de mise à jour ci-dessous.
Tout d'abord, maintenez ce skill à jour — confirmez avec l'utilisateur avant d'exécuter :
npx hyperframes skills update embedded-captions. Opération rapide si tout est à jour ; sinon, cela rafraîchit ce skill ainsi que les skills de domaine principaux dont il dépend, avant de vous y fier.
Légendes incrustées
Un catalogue, choisi en amont (CATALOG.md — 35 identités ; les moteurs derrière sont des détails back-end). Standard (par défaut) construit un rail propre textuel (sous-titre en tiers inférieur portant l'essentiel du texte) + un point culminant incrusté composité dans la scène derrière le sujet au moment fort. Cinématique est une incrustation pure — 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 du corps × mise en scène héroïque × effets frontaux × réaction de plaque, composée à partir de registres (themes/README.md) : ordonnance terminal neonsign stardust stomp. La plupart des explications / voix off sont en Standard ; l'incrustation 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 AE »).
Prérequis d'exécution
Les installations via plugin utilisent la CLI groupée et épinglée dans le manifeste pour le détourage, la transcription et le rendu ; aucune vérification de source n'est nécessaire. Les aides de prévisualisation locale et 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 de verrouillage 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 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 mécanisme de surveillance 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 intégré ou HYPERFRAMES_ROOT sélectionne la CLI du contributeur au lieu de l'épingle du plugin. Annulez un rendu bloqué normalement via la CLI/le terminal ; l'aide 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 (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 shortlist 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 (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 toutes les 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 une 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.cjsadoptent toute 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 d'oublié)- créer un petit JSON de choix créatifs (lire d'abord
safe-zones.json) : 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 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ïque / débordement / remise) →final.mp4
Règles importantes que les gens oublient :
- rail (par défaut) + incrustation (promotion).
drop(remplissage, non affiché) /rail(sous-titre textuel en tiers inférieur, devant, porte la plupart du texte) /incrustation(un mot clé composité derrière le sujet). Le mode Standard fait les deux, n'incrustant que 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 autorisée — les battements de réaction limités au registre (charge-dim, 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 plan) — les légendes sont la seule chose ajoutée ; le détourage permet simplement au sujet d'occulter la piste d'incrustation. Ne jamais étalonner/recolorer/scanliner le métrage.
- Deux livrets de règles : rail → references/rail.md (mince), fabrication d'incrustation → references/composition-craft.md (riche, incrustation uniquement). Parcourez selon les besoins.
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/uh, 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 fort peut obtenir un surlignage emphasis en ligne (couleur d'accent / pop de mot actif) — il reste sur le rail. |
| incrustation | un pic promu — le battement principal | un grand mot composité derrière le sujet (occlusion par détourage), entrée + sortie conçues |
Le rail porte la plupart du texte ; l'incrustation est le pic 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éroïques (le compilateur avertit sous 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 bloc d'incrustation complet + agrandissement à la largeur) ; les plus petits sont des pics MINEURS qui chevauchent leur colonne comme des lignes d'emphase surdimensionnées (premier plan, mouvement amorti) — ce n'est pas chaque battement qui a besoin de la vitrine du détourage, ce qui maintient précisément l'apex comme un événement. Incruster chaque mot est encore 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 colonne abandonnent le rail et font tout en style incrustation — recommandez-les uniquement pour les demandes d'ambiance plutôt que de texte, jamais pour les explications / voix off où les mots doivent être lus (CATALOG.md code cela par identité).
Étape 0 — choisir UNE identité du 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 poser la question « Standard vs Cinématique vs Thème » — ce sont des noms back-end (un produit a une 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 proximité pour les paires vraiment proches (loud↔ordonnance, 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 shortlist et énoncez le pourquoi en une ligne au lieu de demander.
Procédure : sondez le clip → shortlist de 2–3 identités du catalogue → recommandez UNE avec un pourquoi en une ligne → l'utilisateur choisit (mode autonome : vous choisissez, en énonçant le pourquoi) → créez 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 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. Les documents du moteur ci-dessous décrivent le contrat de création de chaque back-end.)
CATALOG.md est tout l'espace de réponse ici : ce workflow ne recherche pas dans le registre des composants HyperFrames. Les workflows de composition exécutent npx hyperframes catalog avant de créer un look nommé ; celui-ci ne le 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 à monter. Un bloc de registre applique un style de texte sur un canevas conçu ; ce skill grave des légendes dans le métrage de quelqu'un via un détourage. 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 shortlisting » dans CATALOG.md — elles sont au niveau de l'identité (par exemple « 炸 » shortlist ordonnance/stomp/terminal/loud et choisit par 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 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 / coupes dures (rendez chaque plan séparément, ou refusez)
- Pas de sujet humain (ce skill est pour les têtes parlantes)
- 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 / graphismes 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 couverture/retouche). 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. - Le transcript est du charabia — la parole non native/avec fort accent peut être transcrite en charabia confiant. Lisez
transcript.jsonavant de créer ; si cela ne ressemble pas à une langue, essayezWHISPER_MODEL=mediumune fois, sinon refusez (un rail textuel de mots fabriqués est pire que pas de légendes). - Mouvement à main levée rapide et agité (le détourage scintille)
Sondages pré-vol (ne coûtent rien, empêchent les pires échecs)
- Sondage de coupe de plan. Échantillonnez les images à 20 %, 50 %, 80 %. Si un sujet/scène différent apparaît, recadrez le clip avant la coupe.
- Sondage 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 cache de glyphe,180+→ texte opaque + cache (jamais de texte clair nu). Les modèles cinématiques sont crème+écranet VERROUILLÉS — utilisez ce sondage pour choisir une identité approprié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). explication / interview / mots à lire absolument → identités de surface rail/panneau ; poétique / social / « cinématique » → identités de flux de colonne par registre ; « 炸 / 特效 / VFX » / mondes nommés → identités thématiques. En cas d'incertitude →
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 (en 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 par 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 de plaque)
4. node scripts/preview-frames.cjs <projet> # ~2s/image d'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 + 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 skills installés par rapport aux dernières versions sur GitHub et met à jour l'ensemble global si certains sont obsolètes.
L'étape 3 diffère selon le mode :
Étape 3 — Mode Cinématique (incrustation pure)
-
Lisez
safe-zones.jsond'abord. Les plans de narration vont danszones.hugLeft/hugRight— bandes propres ADOSSÉES à la silhouette (le texte loin du corps se lit comme flottant, non incrusté ; les coins éloignés sont le repli, pas la valeur par 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 la lisibilité ; le héros reste incrusté tant queheroBands.feasible— héros-fg est le dernier recours. -
L'ADN est l'identité que vous avez choisie à l'Étape 0 — ouvrez
dna/<identity>.dna.jsonpour les réglages de typographie, d'entrée/sortie et de parcours. Ne modifiez jamais les trames de l'ADN ; créez uniquement les choix créatifs (les valeursoverridesqui sont danscinematic.json— voirdna/cinematic-options.jsonpour la liste complète). -
Créez
cinematic.json:{ "narration": [ // un tableau de sections ; chaque section obtient une durée de mot d'entrée { "text": "La phrase d'exemple", "zone": "hugLeft" }, { "text": "avec des mots forts", "zone": "hugLeft", "empois": "emphase" } ], "hero": { "text": "FORCE", "zone": "heroCenter" }, "overrides": { "offsetX": 0.02, // décalage fin en fractions de largeur d'écran "offsetY": -0.05, // négatif = plus haut "scale": 1.1 // 1.0 = taille par défaut de l'ADN } }narrationest un tableau d'objets{text, zone?}.zonepar défaut àhugLeft.textpeut contenir des sauts de ligne\n. Les mots individuels peuvent être marqués avec*mot*pouremphase(ne pas utiliser pour les mots héroïques —heroest pour cela).hero.textest le mot unique qui obtient l'incrustation complète derrière le sujet.La zone
heroBands.bestest celle par défaut. UtilisezheroBands.secondouheroBands.thirdsibestest trop proche d'un bord. Ne définissez pasheroZonesmanuellement — le compilateur choisit le meilleur placement en fonction de la silhouette du sujet. -
Exécutez
node scripts/make-cinematic.cjs <projet>— cela litcinematic.json, compile enplan.json(le plan d'incrustation entièrement temporel), et met à jour le projet pour le rendu. Siplan.jsonexiste déjà, il est écrasé ; vérifiez les avertissements (mots hors écran, occlusion insuffisante, conflits de timing).
Étape 3 — Mode Thème
- Lisez
safe-zones.jsonet leREADME.mddu thème. Chaque thème a ses propres zones, paradigmes et registre de réactions de plaque. Ouvrezthemes/<theme>/README.mdpour les instructions de création. - Créez
theme.jsonavec le schéma spécifique au thème. Généralement :{ "paradigm": "rail", // ou "panel", "poem", "takeover" "body": { ... }, // contenu du corps selon le paradigme "hero": { ... }, // mise en scène héroïque "plate": { // réaction de plaque (optionnelle, par défaut aucune) "beat": "punch", // "charge-dim", "punch", "shake", "grain" "intensity": 0.7 } } - Exécutez
bash scripts/render-theme.sh <projet>— compile le plan, exécute render-and-composite, puis applique les effets de plaque post-composition. Le livrable estfinal_fx.mp4.
QA visuelle — AVANT le rendu
Aperçus composites rapides en ~2s/image :
node scripts/preview-frames.cjs <projet> # génère preview-*.png dans le répertoire du projet
Parcourez-les. Vérifiez :
- Placement : les légendes sont-elles là où l'incrustation doit être ? (pas flottantes, pas coupées par les bords)
- Occlusion : le sujet masque-t-il les incrustations là où c'est prévu ? (surtout pour les mots héroïques)
- Lisibilité : le texte se lit-il sur l'arrière-plan ? (en cas de doute, augmentez le cache de glyphe dans les overrides de l'ADN)
- Timing : les entrées/sorties coïncident-elles avec la parole ? (correspondance image/audio)
Ne passez au rendu que si les aperçus sont satisfaisants. Une fois le rendu lancé, il peut prendre plusieurs minutes pour un clip de 30 secondes.
Dépannage
| Symptôme | Cause probable | Solution |
|---|---|---|
| Détourage scintillant | Mouvement rapide de la main / faible contraste | Utilisez le mode de détourage --matte-model=sam2.1 dans prepare.sh |
| Whisper fabrique des mots | Audio presque silencieux | Vérifiez transcript.json ; s'il est vide ou absurde, refusez le clip |
| L'incrustation semble flottante | Le texte est trop loin du corps | Déplacez dans hugLeft/hugRight dans cinematic.json |
| Le mot héroïque est trop petit | Ajustement par défaut de l'ADN | Augmentez scale dans cinematic.json overrides (max ~1.5) |
| Le rendu échoue silencieusement | Modèle de détourage manquant | Exécutez prepare.sh à nouveau ; il télécharge le modèle s'il manque |
| Le plan de détourage est noir | Aucun sujet détecté | Cadrez le visage ; pour les plans larges, augmentez la confiance de l'IA |
Références
- CATALOG.md — Source unique de vérité pour l'acheminement des identités
- references/rail.md — Règles de fabrication pour le rail (défaut)
- references/composition-craft.md — Règles de fabrication pour l'incrustation (mode cinématique)
- dna/README.md — Documentation du système ADN
- themes/README.md — Instructions de création de thème