Changelog → Vidéo de marque
Entrée : un fichier .md de changelog (thèmes + éléments, comme le digest hebdomadaire HyperFrames).
Sortie : un projet HyperFrames propre et validé par seam-gate dans
projects/active/weekly-changelog-<plage>/. Le rendu n'est effectué que sur demande.
À charger en premier, non-négociable : motion-doctrine (+ cut-the-curve,
oversized-cursor si un curseur apparaît, seam-craft) et captions-overlay.
Ce skill fournit le pipeline spécifique au changelog ; la doctrine fournit la
loi du mouvement.
La directive primordiale : visualiser, ne pas lister
Chaque thème est illustré par une maquette animée de l'interface utilisateur réelle ou d'un analogue fidèle qui met en scène le changement d'expérience — jamais de puces de texte. Acheminez chaque thème/élément via references/visualization-registry.md AVANT d'écrire le script ; le registre décide de la surface : ui-recreate / ui-analog / terminal / checklist. La checklist textuelle est le dernier recours, réservée aux éléments vraiment non visuels (listes de correctifs de fiabilité).
Pipeline
0 · Amorcer le projet à partir des actifs DE CE skill — non-négociable
Faites ceci avant d'écrire un quelconque HTML de composition. L'ignorer produit toujours une vidéo qui ressemble à un projet similaire que vous avez construit avant, PAS à la marque de ce skill — c'est la manière la plus courante de dévier de la marque. Les actifs, polices et échafaudage du skill sont le skill ; le prompt SKILL.md est un routeur.
mkdir -p project/assets/fonts
cp <SKILL_DIR>/assets/fonts/*.woff2 project/assets/fonts/
cp <SKILL_DIR>/assets/bgm.mp3 project/bgm.mp3
ffmpeg -y -stream_loop 15 -i <SKILL_DIR>/assets/bg-pattern.mp4 -t <TOTAL> \
-vf "scale=1080:1080,fps=30,eq=saturation=0.72,[email protected]:t=fill" \
-an -c:v libx264 -crf 20 -pix_fmt yuv420p project/assets/bg-pattern-<TOTAL>s.mp4
cp <SKILL_DIR>/examples/master-skeleton.html project/index.html
Ensuite, lisez references/build-spec.md en entier (pas en diagonale) — il définit les tokens de marque (TT Norms Pro + ABC Solar Display + TT Norms Mono, crème #f5f6f4, vert rationné #5ef17c, cartes en verre avec bordures teintées de vert, forme de pilule pour le kicker/sec-chip, rail de sous-titres de 32px à top: 990) que chaque scène hérite de l'échafaudage.
SEULEMENT ALORS commencer les étapes 1 à 6 ci-dessous. Les étapes 1 à 4 (parser, router, script, VO) planifient ce qui va dans l'échafaudage ; l'étape 5 remplit les espaces réservés (<RANGE>, <TOTAL>, <CUT_N>, <DUR_N>, corps des scènes) à l'intérieur du project/index.html déjà copié — vous NE réécrivez PAS l'habillage, les polices, la palette ou le shell de mise en page de l'échafaudage.
Si vous vous surprenez à utiliser cp sur le index.html d'une vidéo précédente, ou à écrire vos propres déclarations @font-face, ou à concevoir un arrière-plan de shader WebGL au lieu d'utiliser l'encodage bg-pattern MP4 ci-dessus : ARRÊTEZ. Supprimez le index.html actuel et recommencez par le cp de l'échafaudage master-skeleton. Reconstruire le contenu de la scène sur le bon échafaudage est moins coûteux que d'adapter après coup la marque au mauvais échafaudage.
1 · Parser + montage éditorial
- Extraire : la plage de la semaine, les statistiques principales (versions, commits), les thèmes, les éléments.
- Budget : 45-60s au total. Titre ≤2s, générique ≤3.5s, 4 thèmes ≈ 9-12s chacun.
- Par thème, garder UNE visualisation héroïque + au plus 3 éléments parlés. Tout le reste existe uniquement comme pointeur vers le "digest complet" dans le générique. Couper est le travail : un changelog avec 30 éléments donne toujours ≤14 temps parlés.
- Ordonner les thèmes par récit : fonctionnalité phare → surface produit → performance → fiabilité (le digest est généralement déjà dans cet ordre).
2 · Routage des visualisations
Pour chaque thème, choisir la surface dans references/visualization-registry.md et écrire une ligne : thème → surface → les 2-4 actions séquencées que la maquette effectue, chacune liée à une phrase du script. Si aucune surface du registre ne correspond et qu'aucun analogue fidèle n'existe, c'est une scène de checklist — n'inventez pas une fausse interface utilisateur pour quelque chose que nous ne pouvons pas représenter honnêtement.
3 · Script à deux couches (parlé vs affiché)
Écrire le script en lignes de tokens selon references/script-voice.md :
registre conversationnel, chaque terme technique portant une forme spoken
phonémique depuis references/lexicon.json tandis que display conserve
l'orthographe standard. Les sous-titres montrent display ; la VO lit
spoken. Tout terme absent du lexique : STOPPER et demander à l'utilisateur
comment il se prononce, puis l'ajouter au lexique.
Enregistrer sous script-tokens.json dans le projet.
4 · VO — Annie (HeyGen, épinglée)
# Texte de la couche parlée uniquement ; words JSON = horodatages de référence du TEXTE PARLÉ
# Chemin natif du dépôt : le skill changelog-video s'exécute depuis la racine du dépôt hyperframes,
# donc il utilise directement le helper TTS hyperframes-media suivi (pas d'étape d'installation
# `npx hyperframes skills`). Si vous avez copié le skill dans un autre dépôt, remplacez par
# votre propre chemin vers le helper media-use / hyperframes-media heygen-tts.mjs.
node skills/hyperframes-media/scripts/heygen-tts.mjs ./vo-spoken.txt \
-o voiceover.mp3 --words vo-words.json \
--voice 330290724a1b470fb63153f34d4c0183 # Annie — réaliste (ne pas substituer)
Nécessite l'outil CLI heygen ≥0.3.0 authentifié (heygen auth login --oauth).
Ensuite, aligner les horodatages parlés sur les tokens affichés :
node <SKILL_DIR>/scripts/align-captions.mjs \
--tokens script-tokens.json --words vo-words.json --out captions.json
captions.json est l'entrée du rail de sous-titres (orthographe affichée, timing parlé).
L'aligneur affiche les avertissements MISMATCH — les résoudre tous avant de construire
(généralement une orthographe du lexique que le TTS rend comme plusieurs mots). L'audio
est l'horloge : tous les temps des plans viennent de vo-words.json ; une regénération de
la VO rouvre toutes les coutures.
Les horodatages des mots sont une porte d'entrée stricte. Avant de passer à
l'étape 5, vérifiez que vo-words.json n'est pas vide et qu'il possède un tableau
words: [...] avec start/end par mot. S'il est vide (0 octet) ou que le tableau
manque — un mode de défaillance connu lorsque le fournisseur TTS retourne de l'audio
mais pas de charge utile d'horodatage — NE PAS CONTINUER sans eux. Solution de repli :
forced-aligner l'audio produit sur le script affiché en utilisant whisper local :
uvx --from openai-whisper whisper voiceover.mp3 \
--model base.en --language en --word_timestamps True \
--output_format json --output_dir .
# puis exécuter align-captions.mjs avec --words voiceover.json (même forme)
Whisper interprète mal les rendus TTS ("gee-sap" → "gsap", "heyjen" → "hey Jen",
etc.) — les sous-titres utilisent toujours l'orthographe D'AFFICHAGE de
script-tokens.json ; whisper ne fournit que les horodatages. align-captions.mjs
gère la jointure. Cette solution de repli est la différence entre une construction
sous-titrée et une construction silencieusement non sous-titrée.
5 · Construction
Suivez references/build-spec.md exactement : tokens de marque + polices (fournies
dans <SKILL_DIR>/assets/), l'encodage de l'arrière-plan animé, l'échafaudage de la
scène, l'habillage, le rail de sous-titres, un moment de vert rationné par scène.
Ensuite l'ordre de la doctrine : ledger.json (toutes les coutures ordinaires
cut-the-curve GAUCHE) → tampon de couture → temps internes sur les mots de la VO →
vérification seam-gate.
Les sous-titres ne sont pas optionnels. Le squelette principal embarque une
IIFE de rail de sous-titres qui lit un tableau LINES — laisser ce tableau vide
est un bogue livré, pas un choix de style. Le peupler à partir de captions.json
avant de passer à l'étape 6 :
// coller à la place de "const LINES = /* … */ []" dans l'IIFE du rail de sous-titres :
const LINES = /* contenu de captions.json */ [
{ id: 0, end: 2.74, w: [["Cette", 0.0], ["semaine,", 0.30], …] },
…
];
Si align-captions.mjs a été sauté ou que LINES est [], la vérification d'image
à l'étape 6 échouera — ne la contournez pas en supprimant #cap-line de l'échafaudage.
6 · Contrôles (tous verts avant de présenter)
bun run --cwd packages/cli hyperframes check(ou l'outil CLIhyperframesinstallé depuis le skill localskills/hyperframes-cli/) — 0 erreurs (contraste : texte sombre ≥ .66 alpha). N'UTILISEZ PASnpx hyperframes@latest; le CLI local suivi du dépôt est la source de vérité pour le contrat de composition que ce skill produit.seam-gate.mjs verify— 0 échec.- Redémarrer le serveur de prévisualisation (il met en cache le bundle),
vérifier 3-4 temps via
__player.seeksur la page de composition brute. - NE PAS faire le rendu sauf si l'utilisateur le demande. Après un rendu
demandé, vérifier les images du MP4 (
ffmpeg -ss <t> … -frames:v 1) : sous-titres présents, vidéo de fond non noire, pas d'images minuscules/fixes. - Contrôle de présence des sous-titres — échec strict. Échantillonner
3-4 images réparties sur la fenêtre parlée de la VO (par exemple
t=3,t=15,t=30,t=42pour une VO de 48s) et confirmer que le rail de sous-titres àtop: 990rend un texte visible sur chacune. Si une image dans un intervalle parlé manque de sous-titres, la construction est livrée non sous-titrée — traitez-la comme un contrôle rouge et revérifiez le peuplement deLINESà l'étape 5. C'est exactement ce qui n'a pas marché sur la version du 13-20 juillet.
Structure du projet
projects/active/weekly-changelog-<plage>/
├── index.html # document maître unique (scènes en diapositives, coutures tamponnées)
├── ledger.json # registre vectoriel (entrée du tampon de couture)
├── script-tokens.json # script à deux couches (source de vérité pour VO + sous-titres)
├── vo-spoken.txt # généré : couche parlée, une ligne
├── voiceover.mp3 + vo-words.json + captions.json
├── bgm.mp3 # copie depuis <SKILL_DIR>/assets/bgm.mp3 (le morceau maison) sauf si l'utilisateur en fournit un
└── assets/fonts/ + assets/bg-pattern-<dur>s.mp4
Anti-patrons
| Ne pas faire | Faire à la place |
|---|---|
| Diapositives à puces pour des changements d'interface | Maquetter la surface agissant le changement |
| Interface fictive pour des éléments non représentables | Scène de checklist honnête |
| "JSON"/"CLI" purs dans le texte TTS | Formes parlées du lexique ; l'affichage reste standard |
| Orthographes phonétiques dans les sous-titres | Les sous-titres rendent toujours la couche d'affichage |
| Deviner la prononciation d'un terme inconnu | Demander, puis enrichir le lexique |
| Parler de chaque élément du changelog | ≤3 par thème ; le lien du digest porte le reste |
| Accents verts partout | Un moment vert par scène (#5ef17c) |
Partir du index.html d'une vidéo précédente | Étape 0 — copier examples/master-skeleton.html de ce skill dans project/index.html, toujours |
@font-face / shader WebGL / BGM personnalisé fait main | Étape 0 — copier les assets/ de ce skill mot pour mot ; les actifs du skill SONT la marque |
| Livré sans invalidation CloudFront | Exécuter aws cloudfront create-invalidation sur la distribution E2BSLVSZ7FG3U0 pour le chemin exact après tout remplacement S3 — le CDN met en cache l'ancien fichier autrement |
Livrer avec le tableau LINES vide dans l'échafaudage | L'étape 4 doit produire un captions.json peuplé ; l'étape 5 doit le coller dans l'IIFE ; le contrôle 5 de l'étape 6 doit confirmer les sous-titres sur les images rendues. Un LINES vide = livraison non sous-titrée = refaire l'exécution |
Pas de vo-words.json → sauter les sous-titres et livrer quand même | Repliez-vous sur l'alignement forcé Whisper de l'audio produit ; les sous-titres ne sont pas optionnels |