sous-titres-incrustes

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 dans un plugin HyperFrames. Les installations autonomes conservent 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, cela rafraîchit cette compétence ainsi que les compétences de domaine centrales dont elle dépend avant de les utiliser.

Sous-titres incrustés

Un catalogue, choisi en amont (CATALOG.md — 35 identités ; les moteurs derrière sont des détails d'implémentation). Standard (défaut) construit un rail textuel propre (sous-titre en tiers inférieur portant la majeure partie du texte) + un incrusté culminant composité dans la scène derrière le sujet au moment fort. Cinématique est un incrusté pur — pas de rail, chaque légende compositée derrière le sujet (typographie héroïque, accumulation, occlusion en tant qu'effet). Thème est une constitution thématique complète — 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'incrusté est le moment fort rare et mérité — incruster chaque mot est l'erreur courante ; le Thème est pour les demandes de niveau VFX ("炸", "特效", "comme After Effects").

---

Prérequis d'exécution

Les installations via plugin utilisent la CLI groupée et verrouillée par le manifeste pour l'incrustation, la transcription et le rendu ; aucune extraction de code source n'est nécessaire. Les assistants 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. L'incrustation 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 gros fichier partiel ne prouve pas que le rendu est terminé. Un argument build-checkout explicite ou HYPERFRAMES_ROOT sélectionne la CLI du contributeur au lieu du verrouillage du plugin. Annulez un rendu bloqué normalement via la CLI/terminal ; l'assistant 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 (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 n'est pas modifié, 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 savoir-faire 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 :

1. 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)
2. hyperframes init (ignorez-le si le répertoire du projet existe déjà avec la vidéo à l'intérieur — matte.cjs/transcribe.cjs adoptent toute vidéo dans le répertoire en tant que source.mp4) → bash scripts/prepare.sh <projet> (matte ∥ transcribe ∥ enveloppe audio en parallèle, puis zones de sécurité v2 avec palette de scène/optique/éclairage — une commande, rien d'oublié)
3. 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)
4. 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 pour un rendu.
5. render-and-composite.sh → barrières (timing / occlusion+pièce maîtresse / débordement / transfert) → final.mp4

Règles importantes que les gens oublient :

• rail (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é composité derrière le sujet). Le mode Standard fait les deux, n'incrustant que le(s) moment(s) fort(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 sanctionnée — les battements de réaction verrouillés par registre (charge-dim, punch, shake, grain) définis par l'ADN du thème et appliqués APRÈS la composition du matte afin que le sujet+texte+plaque bougent comme un seul cadre) — les légendes sont la seule chose ajoutée ; le matte permet simplement au sujet d'occlure la piste incrustée. Ne jamais étalonner/recolorer/ajouter des lignes de balayage au métrage.
• Deux recueils de règles : rail → references/rail.md (mince), art de l'incrustation → references/composition-craft.md (riche, incrusté uniquement). Parcourez selon les besoins.

---

Modèle de légende — rail + incrusté

Chaque phrase parlée est l'une de ces trois choses :

	Quoi	Comment c'est affiché
drop	remplissage — euh/hem, 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.
incrusté	un moment fort promu — le battement principal	un grand mot composité derrière le sujet (occlusion du matte), entrée + sortie conçues

Le rail porte la majeure partie du texte ; l'incrusté est le moment fort rare et mérité. La rareté est par battement/bloc, pas par clip : ≤1 pièce maîtresse par bloc (pensée), jamais deux visibles en même temps, ≥ un battement d'air entre les fenêtres de pièce maîtresse (le compilateur avertit en dessous de 0,6 s). Un clip court → généralement 1–2 ; une longue explication → ~une par section. Parmi plusieurs pièces maîtresses, la plus grande rédigée est l'APEX (elle seule obtient le verrouillage complet de l'incrusté + l'ajustement à la largeur) ; les plus petites sont des pics MINEURS qui chevauchent leur colonne en tant que lignes d'emphase surdimensionnées (premier plan, mouvement amorti) — ce n'est pas chaque battement qui a besoin de la vitrine du matte, ce qui est exactement ce qui fait de l'apex 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 à flux de colonnes abandonnent le rail et font tout en style incrusté — recommandez-les uniquement pour les demandes d'ambiance sur 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 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 rédaction sont dérivés par recherche à partir de la ligne du catalogue. Ne posez jamais "Standard vs Cinématique vs Thème" comme une question — ce sont des noms internes (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 proximité 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 parmi votre shortlist vous-même et énoncez le pourquoi en une ligne au lieu de demander.

Procédure : sonder le clip → shortlister 2–3 identités du catalogue → recommander UNE avec un pourquoi en une ligne → l'utilisateur choisit (mode autonome : vous choisissez, en énonçant le pourquoi) → rédiger le fichier de cette identité. Les identités sont verrouillées au 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 un défaut silencieux.

(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 rédaction 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 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 la composition eux-mêmes, donc un élément du registre — les blocs caption-* inclus — n'a rien dans quoi se monter. Un bloc de registre stylise du texte sur un canevas conçu ; cette compétence grave des légendes dans la vidéo 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 shortlisting" dans CATALOG.md — elles sont au niveau de l'identité (par exemple "炸" shortliste ordnance/stomp/terminal/loud et choisit par CE QUI devrait exploser), jamais au niveau de la catégorie. Incertain → 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 + rendu + 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 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 franches (rendre chaque plan séparément, ou refuser)
• Pas de sujet humain (cette compétence est pour les plans poitrine)
• Moins de 3 secondes, pas de parole, ou visage jamais clairement visible — transcribe.cjs prévient lorsque l'audio est quasi 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 sous-titres / légendes / graphismes de texte lourds incrustés — ajouter un deuxième système de légendes entre en conflit et le métrage est livré non modifié (pas de recouvrement/retouche). Le texte incrusté apparaît souvent seulement au milieu du clip : é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 défectueuse — la parole non native/fortement accentuée peut se transcrire en charabia confiant. Lisez transcript.json avant de rédiger ; 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).
• Mouvement panoramique agité avec mouvement rapide (scintillement du matte)

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

1. Sondage de coupure de plan. Échantillonnez des images à 20 %, 50 %, 80 %. Si un sujet/scène différent apparaît, recadrez le clip avant la coupure.
2. Sondage de boîte aux lettres / piliers. Des barres noires sur la première image ? Calculez le rectangle de contenu sûr et contraignez le placement des légendes à l'intérieur.
3. Sondage de luminance. Échantillonnez la luminance moyenne de la région des légendes — moins de 60 → le texte clair se lit tel quel, 60-180 → ajoutez l'écran de glyphe, 180+ → texte opaque + écran (jamais de texte clair nu). Les modèles cinématiques sont crème+screen 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.
4. Recommandation d'identité par ton (vous recommandez ; l'utilisateur choisit — voir Étape 0 + CATALOG.md). explicatif / interview / mots à lire absolument → identités de surface rail/panneau ; poétique / social / "cinématographique" → identités à flux de colonnes 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>       # matte ∥ transcribe (parallèle) → zones de sécurité. 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 + 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>  # barrières → final.mp4 + historique/ instantané
   (Mode Thème : IGNORER les étapes 3b/5 — render-theme.sh exécute déjà compile + 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 (incrusté pur)

1. Lire safe-zones.json en premier. Les plans de narration vont dans zones.hugLeft/hugRight — bandes propres ABOUTISSANT à la silhouette (le texte loin du corps se lit comme flottant, pas incrusté ; les coins éloignés sont le plan de repli, pas le défaut). La pièce maîtresse par défaut va vers heroAnchor/heroBands.best (centré SUR le sujet, ~30–55 % occulté). recommendation:"fg" déplace la NARRATION devant pour la lisibilité ; la pièce maîtresse reste incrustée chaque fois que heroBands.feasible — pièce maîtresse au premier plan est le dernier recours.
2. L'ADN est l'identité que vous avez choisie à l'étape 0 — lisez dna/<identité>.md pour la typographie exacte, l'échelle, le placement du point d'ancrage, etc. La plupart de l'ADN est compilé directement dans le plan ; vous ne le modifiez pas, vous le choisissez.
3. Créer cinematic.json — un petit fichier (10 à 20 lignes) avec transcript.json comme référence, en mappant chaque phrase à une classification drop / rail / hero. Seules les pièces maîtresses (hero) obtiennent une entrée d'incrusté ; le rail est compilé à partir du reste. Chaque pièce maîtresse peut avoir un style optionnel (par ex. "heavy" pour une emphase plus large/mixtape). Le compilateur make-cinematic.cjs lit cela, vérifie safe-zones.json pour les placements valides, et émet plan.json (le script de composition complet) et compile l'incrusté en index.html.
   • Exemple :

     {
       "heroes": [
         { "phraseIndex": 3, "style": "default" },
         { "phraseIndex": 7, "style": "heavy" }
       ]
     }
     

     -> phraseIndex fait référence à l'index 0 dans la liste phrases de transcript.json. Si vous souhaitez que le texte de la pièce maîtresse soit différent du parlé textuel (par ex. un slogan), incluez un champ customText.
4. Exécuter la compilation : node scripts/make-cinematic.cjs <projet> — cela produit plan.json et index.html dans le répertoire du projet.

Étape 3 — Mode thème

1. Lire themes/README.md d'abord pour le paradigme de composition complet (séquence d'effets, réaction de plaque, options de paradigme). Chaque thème a des éléments verrouillés (son ADN, son budget de plaque) et des choix ouverts (paradigme, niveau d'effet).
2. Choisir un paradigme parmi ceux définis pour ce thème : rail (sous-titres de style panneau) / panel (plusieurs panneaux à l'écran, comme des cartes de titre) / poem (paroles centrales, centré sur l'esthétique) / takeover (plein écran, réaction de plaque complète). Le défaut du thème est codé dans son ADN.
3. Créer theme.json — un petit fichier (20-30 lignes) qui mappe les phrases aux classifications (drop/rail/hero) et définit les paramètres du thème (réaction de plaque activée/désactivée, intensité, etc.). Exemple :

   {
     "theme": "ordnance",
     "paradigm": "poem",
     "phrases": [
       { "index": 0, "type": "rail" },
       { "index": 1, "type": "hero", "customText": "BOOM" },
       { "index": 2, "type": "drop" }
     ],
     "plateReaction": true,
     "plateIntensity": 0.7
   }
   

4. Exécuter le rendu : bash scripts/render-theme.sh <projet> — cela compile le plan, exécute render-and-composite.sh, puis _postfx.sh pour ajouter les réactions de plaque. Le livrable est final_fx.mp4.

---

QA visuelle — avant de payer pour un rendu

node scripts/preview-frames.cjs <projet>  # ~2s/image

Cela génère des images composites dans frames_preview/ (non vidéo, mais fidèle au rendu final sauf pour l'anticrénelage de la résolution finale). Vérifiez :

• Occultation : la pièce maîtresse est-elle suffisamment occultée par la silhouette du sujet ? Si le texte traverse un espace, ajustez la position dans safe-zones.json ou changez l'emplacement de la pièce maîtresse.
• Lisibilité : le rail est-il lisible sur l'arrière-plan de la scène ? Si le contraste est faible, l'étape de prétraitement prepare.sh aura dû ajouter un écran ; sinon, exécutez à nouveau avec les invites de contraste.
• Timing : la pièce maîtresse apparaît-elle au bon moment ? Le compilateur utilise les horodatages de transcript.json ; s'ils sont décalés (parole rapide), ajustez-les manuellement dans transcript.json ou exécutez à nouveau la transcription.
• Débordement : le texte de la pièce maîtresse déborde-t-il du cadre sûr ? Le compilateur le réduit automatiquement, mais les très longs mots peuvent encore dépasser ; choisissez un mot plus court comme pièce maîtresse.
• Réaction de plaque (mode Thème uniquement) : la charge/le punch/la secousse sont-ils trop forts ? Réduisez plateIntensity dans theme.json et réexécutez.

Corrigez les problèmes en modifiant cinematic.json / theme.json (pas de réexécution complète du pipeline) et réexécutez les preview-frames jusqu'à ce que cela soit acceptable.

---

Rendu final

bash scripts/render-and-composite.sh <projet>

Cela exécute un rendu pleine résolution, applique toutes les compositions (rail + incrusté + effets de plaque en mode Thème) et produit final.mp4 (ou final_fx.mp4 en mode Thème). Le rendu est non interactif ; surveillez les journaux pour les erreurs (espace disque insuffisant, chemin ffmpeg introuvable, etc.).

---

Références

• CATALOG.md — catalogue complet des 35 identités, heuristiques de recommandation
• references/rail.md — règles de rail (sous-titres textuels)
• references/composition-craft.md — art de l'incrustation cinématographique
• themes/README.md — documentation du système de thèmes, définitions de paradigmes
• dna/ — ADN de chaque identité (typographie, échelle, placement)