Légendes incrustées
Un catalogue, sélectionné en amont (CATALOG.md — 17 identités ; les trois moteurs derrière sont des détails de backend). Standard (par défaut) construit un rail propre et textuel (sous-titre inférieur transportant la plupart du texte) + un point culminant incrusté composité dans la scène derrière le sujet au sommet. 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 corporel × pièce maîtresse héroïque × effet avant × réaction de plaque, composée à partir de registres (themes/README.md) : ordnance terminal neonsign stardust stomp. La plupart des explications / voix off est Standard ; l'incrustation est le sommet rare et mérité — incruster chaque mot est l'erreur courante ; Thème est pour les demandes de qualité VFX ("炸", "特效", "comme AE").
Flux opérationnel (TL;DR)
Le texte artisanal 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é de CATALOG.md (17 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 n'importe quelle vidéo dans le répertoire en tant que source.mp4) →bash scripts/prepare.sh <projet>(matte ∥ transcription ∥ enveloppe audio en parallèle, puis safe-zones v2 avec palette scène/optique/éclairage — une commande, rien oublié)- rédiger un petit JSON de choix créatifs (lire
safe-zones.jsond'abord) : Cinématique →plan.json→fill-timings.cjs→fit-fonts.cjs→make-composition.cjs; Thème →theme.json→make-theme.cjs(paradigmes rail/panneau/poème/prise en charge ;anchorest le rail silencieux par défaut) - QA visuelle :
node scripts/preview-frames.cjs <projet>→ aperçus composites fidèles en ~2s/image (pas de rendu). Consultez § 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(bourrage, non affiché) /rail(sous-titre textuel inférieur, devant, porte la plupart du texte) /incrustation(un mot sommet composité 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 INTACTE (Standard/Cinématique ; le budget PLATE du mode Thème est la seule exception sanctionnée — réactions de battement enregistrées (charge-dim, coup, secousse, grain) définies par ADN du thème et appliquées APRÈS le composite matte pour que le sujet+texte+plaque bougent comme une seule image) — les légendes sont la seule chose ajoutée ; le matte permet juste au sujet d'occlure la piste incrustée. Ne jamais étalonner/habiller/ligner la séquence.
- Deux règles : rail → references/rail.md (mince), artisanat d'incrustation → references/composition-craft.md (riche, incrustation uniquement). Parcourir selon les besoins.
Modèle de légende — rail + incrustation
Chaque phrase parlée est l'une des trois choses :
| | Quoi | Comment c'est affiché |
| --------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | drop | bourrage — euh/euh, bégaiements, auto-corrections | non affiché | | rail | le défaut — contenu parlé ordinaire (textuel) | sous-titre inférieur propre, devant, lisible. Un mot fort peut obtenir une surbrillance emphase en ligne (couleur d'accent / pop de mot actif) — il reste sur le rail. | | incrustation | un sommet promu — le battement principal | un grand mot composité derrière le sujet (occlusion matte), entrée + sortie conçues |
Le rail porte la plupart du texte ; l'incrustation est le sommet 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 battement d'air entre les fenêtres héroïques (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éroïques, le plus grand rédigé est l'APEX (lui seul obtient le verrouillage complet incrusté + élévation de largeur) ; les plus petits sont des sommets MINEURS qui chevauchent leur colonne comme des lignes d'emphase surdimensionnées (avant-plan, mouvement atténué) — ce n'est pas chaque battement qui a besoin de la vitrine matte, 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 rail construisent exactement cela (rail = rail.html, incrustation = le point culminant dans index.html). Les identités de flux colonne abandonnent le rail et font tout style incrustation — les recommander uniquement pour les demandes d'ambiance plutôt que textuelles, jamais pour les explications / voix off où les mots doivent être lus (CATALOG.md encode cela par identité).
Étape 0 — choisir UNE identité du CATALOGUE
Un frontal, trois moteurs derrière. L'utilisateur choisit une IDENTITÉ de CATALOG.md (17 entrées : 12 classiques + 5 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 "Standard vs Cinématique vs Thème" comme question — ce sont des noms de backend (un produit a une seule UX même avec plusieurs moteurs). Le catalogue encode tout ce dont le routage a besoin : surface de lecture, voix, recommander-pour, besoins scéniques, notes d'adjacence pour les paires vraiment proches (loud↔ordnance, neon↔neonsign, cream↔stardust).
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 → rédiger le fichier de cette identité. Les identités sont verrouillées par moteur (pas de combinaisons croisées ; en ouvrir une est un evenement de validation — voir dna/README.md).
Toujours présenter votre recommandation et laisser l'utilisateur choisir avant de rédiger. Ne pas se rabattre silencieusement sur une valeur par défaut.
(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 rédaction de chaque backend.)
Heuristique de recommandation : utiliser les "Heuristiques de présélection" dans CATALOG.md — elles sont au niveau de l'identité (par ex. "炸" présélectionne ordnance/stomp/terminal/loud et choisit par CE qui doit exploser), jamais au niveau de la catégorie. Incertain → anchor.
- Cinématique → écrire
plan.jsonpour un modèle verrouillé, compilé parmake-composition.cjs. - Thème → lire themes/README.md, rédiger
theme.json, exécuterscripts/render-theme.sh(compile + rend + réaction de plaque → final_fx.mp4).
Porte de décision — À EXÉCUTER EN PREMIER
Sonder la vidéo et classer 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%
Lire les échantillons. Refuser si :
- Plusieurs intervenants / coupes dures (diviser & rendre chaque plan, ou refuser)
- Pas de sujet humain (cette compétence est pour la tête parlante)
- Moins de 3 secondes, aucun discours, ou visage jamais clairement visible —
transcribe.cjsavertit lorsque l'audio est presque silencieux (Whisper hallucine des mots comme "Merci." sur le silence) ; y prêter attention et refuser plutôt que de légender des mots fabriqués - La source a déjà des légendes / sous-titres / graphiques de texte lourds incrustés — ajouter un deuxième système de légendes entre en conflit et les séquences sont livrées intactes (pas de recouvrement/remplacement). Le texte incrusté apparaît souvent seulement au milieu du clip : échantillonner une planche contact à 1 ips (
ffmpeg -i in.mp4 -vf "fps=1,scale=160:-1,tile=10x5" sheet.png), ne pas se fier à 3 images ponctuelles. - La transcription est défectueuse — un discours non natif / avec un fort accent peut se transcrire en un charabia confiant. Lire
transcript.jsonavant de rédiger ; s'il ne se comprend pas comme une langue, essayerWHISPER_MODEL=mediumune fois, sinon refuser (un rail textuel de mots fabriqués est pire qu'aucune légende). - Mouvement à main levée rapide et chargé (scintillement du matte)
Sondages pré-vol (ne coûtent rien, évitent les pires échecs)
- Sondage de coupe de plan. Échantillonner les images à 20 %, 50 %, 80 %. Si un sujet/scène différent apparaît, rogner le clip avant la coupe.
- Sondage de lettre-boîte / pilier-boîte. Barres noires sur la première image ? Calculer le rectangle de contenu sûr et contraindre le placement des légendes à l'intérieur.
- Sondage de luminance. Échantillonner la luminance moyenne de la région des légendes —
sous 60→ le texte clair se lit tel quel,60-180→ ajouter le cache de glyphe,180+→ texte opaque + cache (jamais de texte clair nu). Les modèles cinématiques sont crème+écranet VERROUILLÉS — utiliser ce sondage pour choisir une identité adaptée (scènes lumineuses →ink, ou le thèmeanchorà rail opaque), jamais pour 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 colonne par registre ; "炸 / 特效 / VFX" / mondes nommés → identités thématiques. En cas d'incertitude →
anchor(les mots se lisent, la scène sûre) — mais présenter une présélection et laisser l'utilisateur choisir.
Pipeline — 5 étapes
1. hyperframes init <projet> --non-interactive --video <video.mp4>
2. bash scripts/prepare.sh <projet> # matte ∥ transcription (parallèle) → safe-zones. Une seule 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 plan.json → node scripts/fill-timings.cjs → fit-fonts.cjs → make-composition.cjs
Thème : rédiger theme.json → bash scripts/render-theme.sh <projet> (compile + rend + effets 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 + instantané history/
(Mode Thème : IGNORER 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 certaines sont obsolètes.
L'étape 3 diffère selon le mode :
Étape 3 — Mode Cinématique (incrustation pure)
- Lire
safe-zones.jsond'abord. Les plans de narration vont danszones.hugLeft/hugRight— bandes propres JOINTES à la silhouette (le texte loin du corps se lit comme flottant, pas incrusté ; les coins éloignés sont le repli, pas le défaut). L'héroïque par défaut va dansheroAnchor/heroBands.best(centré SUR le sujet, ~30–55 % occulté).recommendation:"fg"déplace la NARRATION devant pour la lisibilité ; l'héroïque reste incrustée tant queheroBands.feasible— héroïque-avant-plan est le dernier recours. - L'ADN est l'identité que vous avez choisie à l'Étape 0 (CATALOG.md) — ne pas rouvrir le choix ici. Le vérifier par rapport à la scène (luminance de bande héroïque brillante > 150 veut
ink; les conseils de choix complets se trouvent dans le catalogue, couvrant tous les dix incl. neon / glitch / chrome / velocity). Indiquer votre choix + pourquoi ; l'utilisateur décide. L'ADN verrouille le type/palette/mélange/mouvement + le trio héroïque ; les safe-zones v2 (palette/optics/lighting) le paramètrent pour CETTE scène automatiquement. - Rédiger
<projet>/cinematic.json—"dna": "<nom>"+ BLOCS de pensée, pas de groupes bruts : chaque bloc = lignes de mots (groupés 2–5 aux limites de proposition) + le plan dans lequel il s'empile +csspar ligne (taille/poids/style seulement — pas de positions) + au plus UNE ligne marquée"hero": true(le mot promu ;"text"pour la forme d'affichage). Schéma : en-tête descripts/make-cinematic.cjs. - Compiler :
node scripts/make-cinematic.cjs <projet>— abaisse les blocs → plan.json → index.html. Généré pour vous : timings séquencés par transcription, accumulation dans le bloc, page-flip entre les blocs, le VERROUILLAGE HÉROÏQUE (le pré-contexte d'un bloc héroïque, le HÉROS et le post-contexte s'empilent comme UNE composition liée centrée sur le sujet — ordre de lecture haut→bas = ordre parlé par construction ; le contexte flotte DEVANT tandis que le héros s'incruste DERRIÈRE = le sandwich de profondeur ; une règle de masse maintient le héros dominant son contexte), la division apex/héroïque mineur, l'ordre de lecture par construction, le repli avant-plan par safe-zones. Ensuite, les portes s'exécutent comme d'habitude. (La rédaction manuelle de plan.json reste possible pour les conceptions que les blocs ne peuvent pas exprimer — puis exécuterfill-timings.cjs+fit-fonts.cjs+make-composition.cjsvous-même.)
Étape 3 — Mode Thème (constitution thématique)
Lire themes/README.md EN PREMIER — registres de paradigme/pièce maîtresse, liens, règles strictes et le schéma exact de theme.json.
- Choisir un ADN de thème par registre de contenu (chaque
themes/<nom>.jsonavoice+when). Indiquer votre choix + pourquoi ; l'utilisateur décide. - Rédiger
<projet>/theme.json—dna,lines(textuel, ordre de transcription ; 1–5 mots chacun — pourtakeoverchaque ligne est une CARTE),minors(mots d'emphase),hero:{match}(le mot/expression culminante ; le laisser HORS delinespour les pièces maîtresses incrustées, le garder DANS pour les pièces maîtresses en ligne et redaction panneau+). - Rendre :
bash scripts/render-theme.sh <projet>— compile (porte de complétude textuelle au moment de la compilation), rend les deux couches, composite, applique la réaction de plaque →final_fx.mp4. Utiliserpreview-frames.cjsentre la compilation et le rendu pour une QA visuelle.
QA visuelle — aperçu AVANT de rendre
node scripts/preview-frames.cjs <projet> [t…] composite des images d'aperçu fidèles en ~2s chacune
(couches de légendes capturées d'écran à l'instant de recherche + image vidéo réelle + occlusion matte + superposition rail = à quoi
ressemblera le composite final à ce moment). Échantillons par défaut = chaque fenêtre de groupe/point culminant.
Un rendu complet coûte des minutes — ne jamais l'utiliser pour découvrir des problèmes de disposition.
Vérifier les aperçus (<projet>/preview/sheet.png) par rapport à