embedded-captions — couche mute-feed

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.

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 du domaine central dont elle dépend avant de les utiliser.

Sous-titres intégrés

Un seul catalogue, choisi en premier (CATALOG.md — 35 identités ; les moteurs derrière sont des détails backend). Standard (par défaut) construit un bandeau propre et textuel (sous-titre en tiers inférieur contenant la plupart du texte) + un point culminant intégré composé dans la scène derrière le sujet au moment fort. Cinématique est purement intégré — pas de bandeau, chaque sous-titre est composé derrière le sujet (typographie héroïque, accumulation, occlusion comme 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 plaque, composée à partir de registres (themes/README.md) : ordnance terminal neonsign stardust stomp. La plupart des vidéos explicatives / voix-off utilisent le mode Standard ; le mode intégré est le point culminant rare et mérité — intégrer chaque mot est l'erreur courante ; le mode Thème est réservé aux demandes de niveau effets visuels ("炸", "特效", "comme dans After Effects").

---

Prérequis d'exécution

Les installations via plugin utilisent l'interface en ligne de commande fournie et épinglée au manifeste pour le matage, la transcription et le rendu ; aucune extraction du code source n'est nécessaire. Les aides à la prévisualisation locale et à la mesure des sous-titres nécessitent également Sharp, Puppeteer (avec son navigateur Chromium) et GSAP. Installez-les dans le projet de sous-titres, pas à l'intérieur du plugin en lecture seule :

npm install --prefix <project> --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 matage et la transcription peuvent télécharger leurs propres modèles lors de la première utilisation.

Le rendu attend que l'interface en ligne de commande se termine avec succès avant la composition. 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 vérification de la construction ou HYPERFRAMES_ROOT sélectionne l'interface en ligne de commande du contributeur au lieu de l'épingle du plugin. Annulez un rendu bloqué normalement via l'interface en ligne de commande/le terminal ; l'aide au sous-titrage ne tue pas de force 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 a besoin du clip sondé, elle reste donc à l'étape 1 ci-dessous ; les questions de forme d'exécution de la couche ne s'appliquent pas (les images sont intactes, 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 création 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 :

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 sur le mode/catégorie)
2. hyperframes init (sautez-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 comme source.mp4) → bash scripts/prepare.sh <project> (matage ∥ transcription ∥ enveloppe audio en parallèle, puis zones de sécurité v2 avec palette de scène/optique/éclairage — une commande, rien oublié)
3. rédiger un petit JSON de choix créatifs (lire d'abord safe-zones.json) : Cinématique → plan.json → fill-timings.cjs → fit-fonts.cjs → make-composition.cjs ; Thème → theme.json → make-theme.cjs (paradigmes bandeau/panneau/poème/prise de contrôle ; anchor est le bandeau discret par défaut)
4. Assurance qualité visuelle : node scripts/preview-frames.cjs <project> → prévisualisations composites fidèles en ~2s/image (pas de rendu). Vérifiez la section Assurance qualité visuelle avant de payer un rendu.
5. render-and-composite.sh → portes (timing / occlusion+héroïque / débordement / transfert) → final.mp4

Règles importantes que les gens oublient :

• bandeau (par défaut) + intégré (promotion). drop (remplissage, non affiché) / bandeau (sous-titre textuel en tiers inférieur, devant, contient la plupart du texte) / intégré (un mot clé composé derrière le sujet). Le mode Standard fait les deux, n'intégrant que le(s) point(s) culminant(s). Voir la section Modèle de sous-titres.
• La vidéo est livrée INTACTE (Standard/Cinématique ; le budget PLATE du mode Thème est la seule exception autorisée — les réactions de battements enregistrées (charge-dim, coup, secousse, grain) définies par l'ADN du thème et appliquées APRÈS la composition du matage afin que le sujet+texte+plaque bougent comme une seule image) — les sous-titres sont la seule chose ajoutée ; le matage permet juste au sujet d'occlure la piste intégrée. Ne jamais étalonner/recolorer/ligner la vidéo.
• Deux recueils de règles : bandeau → references/rail.md (mince), création intégrée → references/composition-craft.md (riche, intégré uniquement). Parcourez selon les besoins.

---

Modèle de sous-titres — bandeau + intégré

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

	Quoi	Comment c'est affiché
drop	remplissage — euh/um, bégaiements, autocorrections	non affiché
bandeau	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 bandeau.
intégré	un point culminant promu — le battement principal	un grand mot composé derrière le sujet (occlusion du matage), entrée + sortie conçues

Le bandeau contient la plupart du texte ; l'intégré est le point culminant rare et mérité. La rareté est par battement/bloc, pas par clip : ≤1 héroïque par bloc (pensée), jamais deux co-visibles, ≥ un temps de pause 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 vidéo explicative → ~un par section. Parmi plusieurs héroïques, le plus grand créé est l'APEX (lui seul obtient le bloc intégré complet + agrandissement à la largeur) ; les plus petits sont des pointes MINEURES qui montent sur leur colonne comme des lignes de surlignage agrandies (premier plan, mouvement amorti) — tous les battements n'ont pas besoin de la vitrine du matage, ce qui est exactement ce qui fait de l'apex un événement. Intégrer chaque mot est toujours l'erreur courante.

Les identités de surface en bandeau construisent exactement cela (bandeau = rail.html, intégré = le point culminant dans index.html). Les identités à flux de colonnes abandonnent le bandeau et font tout en style intégré — recommandez-les uniquement pour les demandes d'ambiance plutôt que de texte, jamais pour les vidéos explicatives / voix-off où les mots doivent être lus (CATALOG.md encode cela par identité).

---

Étape 0 — choisir UNE identité du CATALOGUE

Un seul 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 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, 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 propre liste restreinte et indiquez le pourquoi en une ligne au lieu de demander.

Procédure : sonder le clip → établir une liste restreinte de 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) → créer 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 décision 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 docs du moteur ci-dessous décrivent le contrat de création de chaque backend.)

CATALOG.md est l'espace de réponse complet 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 créer un rendu nommé ; celui-ci ne doit pas le faire. Ses moteurs sont des compilateurs verrouillés qui consomment cinematic.json / theme.json et produisent eux-mêmes la composition, donc un élément du registre — les blocs caption-* inclus — n'a rien à monter. Un bloc de registre style le texte sur un canevas conçu ; cette compétence grave des sous-titres dans les images de quelqu'un via un matage. 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 "炸" présélectionne ordnance/stomp/terminal/loud et choisit en fonction de CE qui devrait exploser), jamais au niveau de la catégorie. En cas de doute → anchor.

• Cinématique → écrivez plan.json pour un modèle verrouillé, compilé par make-composition.cjs.
• Thème → lisez themes/README.md, créez theme.json, exécutez 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 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 / coupures nettes (divisez et effectuez le rendu de chaque plan, ou refusez)
• Aucun sujet humain (cette compétence est pour les plans de parole)
• Moins de 3 secondes, aucune parole, ou le visage n'est jamais clairement visible — transcribe.cjs avertit lorsque l'audio est quasi silencieux (Whisper hallucine des mots comme "Thank you." sur le silence) ; tenez-en compte et refusez plutôt que de sous-titrer des mots fabriqués
• La source contient déjà des sous-titres incrustés / du texte graphique lourd — l'ajout d'un deuxième système de sous-titres entre en conflit et les images sont livrées intactes (pas de masquage/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 aberrante — la parole non native / fortement accentuée peut être transcrite en un charabia confiant. Relisez transcript.json avant de créer ; si cela ne s'analyse pas comme une langue, essayez WHISPER_MODEL=medium une fois, sinon refusez (un bandeau textuel de mots fabriqués est pire que pas de sous-titres).
• Plan porté à la main agité avec mouvement rapide (le matage scintille)

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

1. 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.
2. Sondage de letterbox / pillarbox. Des barres noires sur la première image ? Calculez le rectangle de contenu sûr et contraignez le placement des sous-titres à l'intérieur.
3. Sondage de luminance. Échantillonnez la luminance moyenne de la région des sous-titres — 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é adaptée (scènes lumineuses → ink, ou le thème anchor à bandeau opaque), jamais pour recolorer une.
4. Recommandation d'identité par ton (vous recommandez ; l'utilisateur choisit — voir Étape 0 + CATALOG.md). explicatif / interview / mots à lire impérativement → identités de surface en bandeau/panneau ; poétique / social / "cinématique" → identités à 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 restreinte et laissez l'utilisateur choisir.

---

Pipeline — 5 étapes

1. hyperframes init <project> --non-interactive --video <video.mp4> --skill=embedded-captions
2. bash scripts/prepare.sh <project>       # matage ∥ transcription (parallèle) → zones de sécurité. Une commande.
                                           #   → frames_fg/ transcript.json safe-zones.json
3. [ÉTAPE DE L'AGENT — la seule étape créative] créez un petit JSON ; voir ci-dessous par mode
   Cinématique : créez plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
   Thème :     créez theme.json → bash scripts/render-theme.sh <project>   (compile + rend + effets de plaque)
4. node scripts/preview-frames.cjs <project>   # ~2s/image prévisualisations composites → § Assurance qualité visuelle (AVANT le rendu)
5. bash scripts/render-and-composite.sh <project>  # portes → final.mp4 + historique/ instantané
   (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 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 l'une d'entre elles est obsolète.

L'étape 3 diffère selon le mode :

Étape 3 — Mode cinématique (intégré pur)

1. Lisez safe-zones.json d'abord. Les plans de narration vont dans zones.hugLeft/hugRight — des bandes propres CONTIGUËS à la silhouette (le texte loin du corps donne l'impression de flotter, pas d'être intégré ; les coins éloignés sont la solution de repli, pas la valeur par défaut). L'héroïque par défaut va dans heroAnchor/heroBands.best (centré SUR le sujet, ~30–55 % occulté). recommendation:"fg" déplace la NARRATION devant pour la lisibilité ; l'héroïque reste intégré chaque fois que heroBands.feasible — l'héroïque au premier plan est le dernier recours.
2. L'ADN est l'identité que vous avez