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, prêt pour le rendu, dans projects/active/weekly-changelog-<range>/. Ne rend le rendu que lorsque demandé.
À charger en premier, non négociable : motion-doctrine (+ cut-the-curve, oversized-cursor si un curseur apparaît, seam-craft) et captions-overlay. Cette compétence 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 joue 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 : 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 CETTE compétence — non négociable
Faites ceci avant d'écrire un quelconque HTML de composition. Omettre cette étape produit toujours une vidéo qui ressemble à un projet similaire que vous avez déjà construit, PAS à la marque de cette compétence — c'est la façon la plus courante de dévier de la marque. Les actifs, polices et squelette de la compétence sont la compétence ; 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 du début à la fin (pas en diagonale) — il définit les jetons 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 kicker/sec-chip, rail de sous-titres 32px à top: 990) que chaque scène hérite du squelette.
SEULEMENT ALORS commencez les étapes 1 à 6 ci-dessous. Les étapes 1 à 4 (analyse, routage, script, VO) planifient ce qui va dans le squelette ; l'étape 5 remplit les espaces réservés (<RANGE>, <TOTAL>, <CUT_N>, <DUR_N>, corps de scène) à l'intérieur du project/index.html déjà copié — vous NE réécrivez PAS le chrome, les polices, la palette ou la coque de mise en page du squelette.
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 shader WebGL au lieu d'utiliser la vidéo bg-pattern MP4 encodée ci-dessus : ARRÊTEZ. Supprimez le index.html actuel et recommencez à partir du cp du squelette master-skeleton. Reconstruire le contenu de la scène sur le bon squelette est moins coûteux que de rétro-adapter la marque dans un mauvais squelette.
1 · Analyse + coupe éditoriale
- Extraire : la plage de la semaine, les statistiques principales (versions, commits), les thèmes, les éléments.
- Budget : 45-60s au total. Titre ≤2s, outro ≤3.5s, 4 thèmes ≈ 9-12s chacun.
- Par thème, garder UNE visualisation héroïque + au maximum 3 éléments parlés. Tout le reste n'existe que comme pointeur "digest complet" dans l'outro. La coupe est le travail : un changelog avec 30 éléments donne toujours ≤14 temps parlés.
- Ordonner les thèmes par histoire : fonctionnalité phare → surface produit → performance → fiabilité (le digest est généralement déjà dans cet ordre).
2 · Routage de la visualisation
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, il s'agit d'une scène de checklist — n'inventez pas d'interface utilisateur factice pour quelque chose que nous ne pouvons pas représenter honnêtement.
3 · Script à deux couches (parlé vs affiché)
Écrire le script sous forme de lignes de jetons selon references/script-voice.md : registre conversationnel, chaque terme technique portant une forme phonétique spoken tirée de references/lexicon.json tandis que display conserve l'orthographe standard. Les sous-titres affichent display ; la VO lit spoken. Tout terme qui n'est pas dans le lexique : ARRÊTEZ et demandez à l'utilisateur comment il se prononce, puis ajoutez-le 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 = timestamps de référence du texte PARLÉ
# Chemin natif du dépôt : la compétence changelog-vidéo s'exécute depuis la racine du dépôt hyperframes,
# elle utilise donc l'assistant TTS hyperframes-media suivi directement (pas de `npx hyperframes
# skills` install step). Si vous avez copié la compétence dans un autre dépôt, remplacez par
# votre propre chemin vers l'assistant 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 — lifelike (ne pas substituer)
Nécessite heygen CLI ≥0.3.0 authentifié (heygen auth login --oauth).
Ensuite, aligner les timestamps parlés sur les jetons 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 imprime des avertissements MISMATCH — résolvez chacun 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 temps forts viennent de vo-words.json ; une régénération de la VO rouvre chaque couture.
Les timestamps des mots sont une porte stricte. Avant de passer à l'étape 5, vérifiez que vo-words.json n'est pas vide et contient un tableau words: [...] avec start/end pour chaque mot. S'il est vide (0 octet) ou ne contient pas le tableau — un mode de défaillance connu lorsque le fournisseur TTS renvoie l'audio mais pas de payload de timestamp — NE CONTINUEZ PAS sans eux. Solution de repli : aligner forcément 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écutez align-captions.mjs avec --words voiceover.json (même structure)
Whisper peut mal interpréter les rendus TTS ("gee-sap" → "gsap", "heyjen" → "hey Jen", etc.) — les sous-titres utilisent toujours l'orthographe AFFICHÉE de script-tokens.json ; whisper ne fournit que les timestamps. align-captions.mjs gère la jointure.
Cette solution de repli fait 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 : jetons de marque + polices (fournies dans <SKILL_DIR>/assets/), l'encodage du fond animé, le squelette de la scène, le chrome, le rail de sous-titres, un moment vert rationné par scène. Ensuite, l'ordre de la doctrine : ledger.json (toutes les coutures ordinaires cut-the-curve LEFT) → seam-stamp → temps forts internes sur les mots de la VO → vérification seam-gate.
Les sous-titres sont non optionnels. Le squelette master-skeleton inclut une IIFE de rail de sous-titres qui lit un tableau LINES — laisser ce tableau vide est un bogue expédié, pas un choix de style. Remplissez-le à partir de captions.json avant de passer à l'étape 6 :
// collez à 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: [["This", 0.0], ["week,", 0.30], …] },
…
];
Si align-captions.mjs a été sauté ou si LINES est [], la vérification de trame à l'étape 6 échouera — ne la contournez pas en supprimant #cap-line du squelette.
6 · Vérifications (toutes vertes avant de présenter)
bun run --cwd packages/cli hyperframes check(ou le CLIhyperframesinstallé à partir de la compétence localeskills/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 cette compétence produit.seam-gate.mjs verify— 0 échec.- Redémarrez le serveur de prévisualisation (il met en cache le bundle), vérifiez 3-4 temps forts via
__player.seeksur la page de composition brute. - Ne RENDEZ PAS à moins que l'utilisateur ne le demande. Après un rendu demandé, vérifiez les trames de la MP4 (
ffmpeg -ss <t> … -frames:v 1) : sous-titres présents, vidéo de fond non noire, pas de trames minuscules/gelées. - Vérification de présence des sous-titres — échec strict. Échantillonnez 3-4 trames 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 confirmez que le rail de sous-titres àtop: 990affiche du texte visible sur chacune. Si une trame dans un intervalle parlé manque de sous-titres, la construction expédie sans sous-titres — traitez-la comme une vérification rouge et revérifiez le remplissage deLINESà l'étape 5. C'est exactement ce qui n'a pas fonctionné sur la version v4 du 13-20 juillet.
Structure du projet
projects/active/weekly-changelog-<range>/
├── index.html # document maître unique (scènes sous forme de diapositives, coutures estampillées)
├── ledger.json # registre vectoriel (entrée seam-stamp)
├── script-tokens.json # script à deux couches (source de vérité pour la VO + les 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 | À la place |
|---|---|
| Diapositives à puces pour les changements d'interface | Maquetter la surface qui joue le changement |
| Interface utilisateur factice pour des éléments non représentables | Scène de checklist honnête |
| "JSON"/"CLI" brut 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 affichée |
| Deviner la prononciation d'un terme inconnu | Demander, puis développer 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 — copiez examples/master-skeleton.html de cette compétence dans project/index.html, toujours |
@font-face / shader WebGL / BGM personnalisé fait main | Étape 0 — copiez les assets/ de cette compétence mot pour mot ; les actifs de la compétence SONT la marque |
| Livraison sans invalidation CloudFront | Exécutez 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 sinon |
Expédier avec le tableau LINES vide dans le squelette | L'étape 4 doit produire un captions.json rempli ; l'étape 5 doit le coller dans l'IIFE ; l'étape 6, vérification 5, doit confirmer les sous-titres sur les trames rendues. LINES vide = expédition sans sous-titres = recommencez l'exécution |
Pas de vo-words.json → sauter les sous-titres et expédier quand même | Replier sur l'alignement forcé Whisper sur l'audio produit ; les sous-titres sont non optionnels |