Changelog → Markenvideo
Eingabe: Ein Changelog .md (Themen + Elemente, wie der wöchentliche HyperFrames-Digest).
Ausgabe: Ein lint-sauberes, seam-gate-grünes HyperFrames-Projekt in
projects/active/weekly-changelog-<bereich>/. Nur rendern, wenn danach gefragt wird.
Zuerst laden, nicht verhandelbar: motion-doctrine (+ cut-the-curve,
oversized-cursor falls ein Cursor erscheint, seam-craft) und captions-overlay.
Dieser Skill liefert die changelog-spezifische Pipeline; die Doktrin liefert das
Bewegungsgesetz.
Der oberste Grundsatz: Visualisieren, nicht auflisten
Jedes Thema wird durch einen animierten Mock der tatsächlichen Benutzeroberfläche oder eines
originalgetreuen Analogons veranschaulicht, das die Änderung im Erlebnis darstellt – niemals Textaufzählungen.
Leite jedes Thema/jedes Element durch references/visualization-registry.md, BEVOR du das Skript schreibst; die Registrierung entscheidet über UI-Neuerstellung / UI-Analogon / Terminal / Checkliste. Text-Checkliste ist der letzte Ausweg und nur für wirklich nicht-visuelle Elemente reserviert (Zuverlässigkeits-Fixlisten).
Pipeline
0 · Projekt aus den Ressourcen DIESES Skills bootstrappen – nicht verhandelbar
Mach das, bevor du irgendein Kompositions-HTML schreibst. Wenn du es überspringst, entsteht immer ein Video, das wie ein ähnliches Projekt aussieht, das du zuvor gebaut hast, NICHT die Marke dieses Skills – das ist mit Abstand die häufigste Art, wie dieser Skill von der Marke abweicht. Die Ressourcen, Schriftarten und das Grundgerüst des Skills sind der Skill; die SKILL.md-Aufforderung ist ein Router.
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
Dann lies references/build-spec.md vollständig durch (nicht überflogen) – es definiert die Marken-Token (TT Norms Pro + ABC Solar Display + TT Norms Mono, Creme #f5f6f4, rationiertes Grün #5ef17c, Glaskarten mit grün getönten Rändern, Kicker/Sec-Chip-Pillenform, 32px Untertitel-Schiene bei top: 990), die jede Szene vom Grundgerüst erbt.
Erst DANN beginne mit den Schritten 1-6 unten. Die Schritte 1-4 (parsen, routen, skripten, VO) planen, was in das Grundgerüst kommt; Schritt 5 füllt Platzhalter (<RANGE>, <TOTAL>, <CUT_N>, <DUR_N>, Szeneninhalte) innerhalb der bereits kopierten project/index.html – du überschreibst NICHT das Chrom, die Schriftarten, die Palette oder das Layout-Gehäuse des Grundgerüsts.
Wenn du dich dabei ertappst, dass du zu cp auf einer vorherigen index.html greifst, oder eigene @font-face-Deklarationen schreibst, oder einen WebGL-Shader-Hintergrund entwirfst anstatt das codierte BG-Pattern-MP4 von oben zu verwenden: STOPP. Lösche die aktuelle index.html und starte neu mit dem cp des Master-Skeleton-Gerüsts. Den Szeneninhalt auf dem richtigen Gerüst neu aufzubauen ist billiger, als die Marke nachträglich in das falsche Gerüst einzupassen.
1 · Parsen + redaktioneller Schnitt
- Extrahiere: Wochenbereich, Überschriftenstatistiken (Releases, Commits), Themen, Elemente.
- Budget: 45-60s insgesamt. Titel ≤2s, Outro ≤3,5s, 4 Themen ≈ 9-12s pro Thema.
- Pro Thema EINE Heldenvisualisierung + maximal 3 gesprochene Elemente behalten. Alles andere existiert nur als "vollständiger Digest"-Verweis im Outro. Schneiden ist die Aufgabe: Ein Changelog mit 30 Elementen ergibt immer noch ≤14 gesprochene Punkte.
- Ordne Themen nach Story: Highlight-Feature → Produktoberfläche → Leistung → Zuverlässigkeit (der Digest hat diese Reihenfolge normalerweise bereits).
2 · Visualisierungs-Routing
Wähle für jedes Thema die Oberfläche aus references/visualization-registry.md und schreibe eine Zeile: thema → oberfläche → die 2-4 aufeinanderfolgenden Aktionen, die der Mock ausführt, jede verknüpft mit einem Skriptsatz. Wenn keine Registrierungsoberfläche passt und kein originalgetreues Analogon existiert, wird es eine Checklistenszene – erfinde keine falsche UI für etwas, das wir nicht ehrlich darstellen können.
3 · Zweischichtiges Skript (gesprochen vs. Anzeige)
Schreibe das Skript als Token-Zeilen gemäß references/script-voice.md:
konversationeller Ton, jedes technische Fachwort, das eine spoken-phonetische Form aus references/lexicon.json trägt, während display die Standardschreibweise beibehält. Die Untertitel zeigen display; das VO liest spoken. Jeder Begriff, der nicht im Lexikon ist: STOPP und frage den Benutzer, wie es ausgesprochen wird, und füge es dann zum Lexikon hinzu.
Speichere als script-tokens.json im Projekt.
4 · VO – Annie (HeyGen, festgepinnt)
# spoken-layer Text nur; words JSON = Ground-Truth-Zeitstempel des GESPROCHENEN Textes
# Repo-nativer Pfad: Der Changelog-Video-Skill läuft vom HyperFrames-Repo-Root aus,
# also verwendet er direkt den getrackten HyperFrames-Media TTS-Helfer (kein `npx hyperframes`
# skills install`-Schritt). Wenn du den Skill in ein anderes Repo kopiert hast, tausche
# deinen eigenen Pfad zum media-use / hyperframes-media heygen-tts.mjs aus.
node skills/hyperframes-media/scripts/heygen-tts.mjs ./vo-spoken.txt \
-o voiceover.mp3 --words vo-words.json \
--voice 330290724a1b470fb63153f34d4c0183 # Annie – lebensecht (nicht ersetzen)
Erfordert heygen CLI ≥0.3.0 authentifiziert (heygen auth login --oauth).
Dann gleiche die gesprochenen Zeitstempel mit den Anzeige-Token ab:
node <SKILL_DIR>/scripts/align-captions.mjs \
--tokens script-tokens.json --words vo-words.json --out captions.json
captions.json ist der Untertitel-Schienen-Eingabe (Anzeigeschreibweise, gesprochenes Timing).
Der Aligner gibt MISMATCH-Warnungen aus – löse jede einzelne, bevor du baust (meistens ein Lexikon, das der TTS als mehrere Wörter rendert). Das Audio ist die Uhr: Alle Beat-Zeiten stammen aus vo-words.json; eine VO-Regenerierung öffnet jede Naht neu.
Wortzeiten sind eine harte Gate. Bevor du zu Schritt 5 übergehst, verifiziere,
dass vo-words.json nicht leer ist und ein words: [...]-Array mit start/end
pro Wort hat. Wenn es leer ist (0 Bytes) oder das Array fehlt – ein bekannter Fehlermodus,
wenn der TTS-Anbieter Audio, aber keine Zeitstempel-Nutzlast zurückgibt – FAHRE NICHT ohne sie fort.
Fallback: Erstelle ein Forced-Alignment des produzierten Audios gegen das Anzeigeskript mit lokalem Whisper:
uvx --from openai-whisper whisper voiceover.mp3 \
--model base.en --language en --word_timestamps True \
--output_format json --output_dir .
# dann führe align-captions.mjs mit --words voiceover.json aus (gleiche Form)
Whisper hört TTS-Renderings falsch ("gee-sap" → "gsap", "heyjen" → "hey Jen",
usw.) – Untertitel verwenden trotzdem die ANZEIGE-Schreibweise aus script-tokens.json;
Whisper liefert nur die Zeitstempel. align-captions.mjs übernimmt die Zusammenführung.
Dieser Fallback ist der Unterschied zwischen einem Build mit Untertiteln und einem
stumm ohne Untertitel.
5 · Bauen
Befolge references/build-spec.md genau: Marken-Token + Schriftarten (gebündelt in
<SKILL_DIR>/assets/), die animierte Hintergrundcodierung, Szenengerüst,
Chrom, Untertitel-Schiene, ein rationiertes Grün-Moment pro Szene. Dann die Doktrin-
Reihenfolge: ledger.json (alle normalen Nähte cut-the-curve LEFT) → seam-stamp →
interne Beats auf VO-Worte → seam-gate verify.
Untertitel sind nicht optional. Das Master-Skeleton liefert eine Untertitel-Schienen-IIFE,
die ein LINES-Array liest – dieses Array leer zu lassen ist ein ausgelieferter Bug, keine
Stilwahl. Befülle es aus captions.json, bevor du mit Schritt 6 fortfährst:
// Ersetze "const LINES = /* … */ []" in der Untertitel-Schienen-IIFE:
const LINES = /* Inhalt von captions.json */ [
{ id: 0, end: 2.74, w: [["This", 0.0], ["week,", 0.30], …] },
…
];
Wenn align-captions.mjs übersprungen wurde oder LINES [] ist, wird die Frame-Prüfung in Schritt 6 fehlschlagen – überdecke es nicht, indem du #cap-line aus dem Gerüst entfernst.
6 · Gates (alle grün, bevor du präsentierst)
bun run --cwd packages/cli hyperframes check(oder die installiertehyperframes-CLI aus dem repo-lokalenskills/hyperframes-cli/-Skill) – 0 Fehler (Kontrast: dunkler Text ≥ .66 Alpha). Verwende NICHTnpx hyperframes@latest; die getrackte repo-lokale CLI ist die Quelle der Wahrheit für den Kompositionsvertrag, den dieser Skill produziert.seam-gate.mjs verify– 0 Fehlschläge.- Starte den Vorschau-Server neu (er cacht das Bundle), überprüfe 3-4 Beats stichprobenartig
über
__player.seekauf der rohen Kompositionsseite. - RENDERE NICHT, es sei denn, der Benutzer fragt danach. Nach einem angeforderten Render überprüfe
Frames vom MP4 (
ffmpeg -ss <t> … -frames:v 1): Untertitel vorhanden, Hintergrundvideo nicht schwarz, keine winzigen/eingefrorenen Frames. - Anwesenheits-Gate für Untertitel – harter Fehlschlag. Prüfe 3-4 Frames, verteilt über das
gesprochene Fenster des VO (z.B.
t=3,t=15,t=30,t=42für ein 48s VO) und bestätige, dass die Untertitel-Schiene beitop: 990auf jedem sichtbaren Text rendert. Wenn einem Frame in einem gesprochenen Intervall Untertitel fehlen, wird der Build ohne Untertitel versendet – behandle es als rotes Gate und überprüfe dieLINES-Befüllung aus Schritt 5 erneut. Genau das ist beim Build vom 13.-20. Juli v4 schiefgelaufen.
Projektstruktur
projects/active/weekly-changelog-<bereich>/
├── index.html # Einzeldokument-Master (Szenen als Folien, gestempelte Nähte)
├── ledger.json # Vektor-Ledger (seam-stamp-Eingabe)
├── script-tokens.json # Zweischichtiges Skript (Quelle der Wahrheit für VO + Untertitel)
├── vo-spoken.txt # Generiert: gesprochene Schicht, eine Zeile
├── voiceover.mp3 + vo-words.json + captions.json
├── bgm.mp3 # Kopie aus <SKILL_DIR>/assets/bgm.mp3 (der Haus-Track), es sei denn, der Benutzer liefert einen
└── assets/fonts/ + assets/bg-pattern-<dauer>s.mp4
Anti-Patterns
| Nicht | Stattdessen |
|---|---|
| Aufzählungspunkt-Folien für UI-Änderungen | Die Oberfläche simulieren, die die Änderung darstellt |
| Gefälschte UI für nicht darstellbare Elemente | Ehrliche Checklisten-Szene |
| Einfaches "JSON"/"CLI" im TTS-Text | Lexikon-Gesprochene-Formen; Anzeige bleibt standard |
| Phonetische Schreibweisen in Untertiteln | Untertitel rendern immer die Anzeigeschicht |
| Erraten der Aussprache eines unbekannten Begriffs | Fragen, dann Lexikon erweitern |
| Jedes Changelog-Element sprechen | ≤3 pro Thema; der Digest-Link trägt den Rest |
| Grün-Akzente überall | Ein grüner Moment pro Szene (#5ef17c) |
| Beginnen von einer vorherigen index.html | Schritt 0 – examples/master-skeleton.html aus diesem Skill immer in project/index.html kopieren |
Handgefertigtes @font-face / WebGL-Shader / eigenes BGM | Schritt 0 – assets/ dieses Skills wortwörtlich kopieren; die Ressourcen des Skills SIND die Marke |
| Lieferung ohne CloudFront-Invalidierung | Führe aws cloudfront create-invalidation auf Distribution E2BSLVSZ7FG3U0 für den genauen Pfad nach jedem S3-Ersatz aus – CDN cached sonst die alte Datei |
Lieferung mit leerem LINES-Array im Gerüst | Schritt 4 muss ein befülltes captions.json produzieren; Schritt 5 muss es in die IIFE einfügen; Schritt 6 Gate 5 muss Untertitel auf gerenderten Frames bestätigen. Leeres LINES = ungetitelte Lieferung = Wiederholung des Durchlaufs |
Kein vo-words.json → Untertitel überspringen und trotzdem liefern | Fallback auf Whisper Forced Alignment des produzierten Audios; Untertitel sind nicht optional |