Changelog → Markiertes Video
Eingabe: ein Changelog .md (Themen + Elemente, wie der wöchentliche HyperFrames-Digest).
Ausgabe: ein lint-sauberes, seam-gate-green HyperFrames-Projekt in
projects/active/weekly-changelog-<range>/. Nur rendern, wenn danach gefragt.
Zuerst laden, nicht verhandelbar: motion-doctrine (+ cut-the-curve,
oversized-cursor, falls ein Cursor erscheint, seam-craft) und captions-overlay.
Dieser Skill stellt die Changelog-spezifische Pipeline bereit; die Doctrine liefert
das Bewegungsgesetz.
Die oberste Direktive: visualisieren, nicht auflisten
Jedes Thema wird durch eine animierte Mock-Darstellung der tatsächlichen UI oder
eines originalgetreuen Analogons veranschaulicht, das die Änderung in der Erfahrung
nachspielt – niemals Textaufzählungen. Leite jedes Thema/Element durch
references/visualization-registry.md, BEVOR du das Skript schreibst; die Registry
entscheidet über ui-recreate / ui-analog / terminal / checkliste. Die Text-Checkliste
ist der letzte Ausweg, reserviert für wirklich nicht-visuelle Elemente (Zuverlässigkeitsfix-Listen).
Pipeline
0 · Bootstrap des Projekts aus den Assets dieses Skills – nicht verhandelbar
Mach das, bevor du irgendein Kompositions-HTML schreibst. Das Überspringen führt immer zu einem Video, das wie ein ähnliches Projekt aussieht, das du zuvor gebaut hast, NICHT wie die Marke dieses Skills – das ist der häufigste Weg, wie dieser Skill von der Marke abkommt. Die Assets, Schriftarten und das Grundgerüst des Skills sind der Skill; die SKILL.md-Eingabeaufforderung 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/Sek-Chip-Pillenform, 32px Caption-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 des Grundgerüsts.
Wenn du dich dabei ertappst, wie du nach cp eines früheren 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: HÖR AUF. Lösche das aktuelle index.html und
beginne erneut mit dem cp des master-skeleton-Grundgerüsts. Das
Neuerstellen von Szeneninhalten auf dem richtigen Grundgerüst ist
günstiger als das Nachrüsten der Marke in das falsche Grundgerüst.
1 · Parsen + redaktioneller Schnitt
- Extrahiere: Wochenbereich, Überschrift-Statistiken (Releases, Commits), Themen, Elemente.
- Budget: 45-60s insgesamt. Titel ≤2s, Outro ≤3,5s, 4 Themen ≈ 9-12s jedes.
- Pro Thema behalte EINE Heldenvisualisierung + maximal 3 gesprochene Elemente. Alles andere existiert nur als „vollständiger Digest“-Hinweis im Outro. Kürzen ist die Aufgabe: Ein Changelog mit 30 Elementen ergibt trotzdem ≤14 gesprochene Beats.
- Ordne die Themen nach Geschichte: Marquee-Feature → Produktoberfläche → Leistung → Zuverlässigkeit (der Digest ist normalerweise bereits so aufgebaut).
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 sequenziellen Aktionen, die der Mock ausführt, jede mit einem Skriptsatz verknüpft. Wenn keine
Registry-Oberfläche passt und kein originalgetreues Analogon existiert, ist
es eine Checklisten-Szene – erfinde keine gefälschte 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 trägt eine spoken
phonetische Form aus references/lexicon.json, während display die
Standard-Rechtschreibung beibehält. Untertitel zeigen display; der VO
liest spoken. Jeder Begriff, der nicht im Lexikon ist: ANHALTEN und den
Benutzer fragen, wie es ausgesprochen wird, dann zum Lexikon hinzufügen.
Speichere als script-tokens.json im Projekt.
4 · VO — Annie (HeyGen, festgelegt)
# Gesprochene Schicht nur Text; words JSON = Ground-Truth-Zeitstempel des GESPROCHENEN Textes
# Repo-eigener Pfad: Der Changelog-Video-Skill wird aus dem HyperFrames-Repo-Stammverzeichnis
# ausgeführt, daher verwendet er direkt den getrackten hyperframes-media TTS-Helfer (kein `npx hyperframes
# skills` Installationsschritt). Wenn du den Skill in ein anderes Repo kopiert hast, tausche
# deinen eigenen Pfad zum media-use / hyperframes-media heygen-tts.mjs ein.
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).
Richte dann die gesprochenen Zeitstempel zurück auf die Anzeige-Token aus:
node <SKILL_DIR>/scripts/align-captions.mjs \
--tokens script-tokens.json --words vo-words.json --out captions.json
captions.json ist die Caption-Schienen-Eingabe (Anzeige-Schreibweise,
gesprochenes Timing). Der Aligner gibt MISMATCH-Warnungen aus – löse jede
davon vor dem Bauen auf (normalerweise eine Lexikon-Schreibweise, die der
TTS als mehrere Wörter wiedergibt). Das Audio ist die Uhr: Alle
Beat-Zeiten stammen aus vo-words.json; eine VO-Neuerstellung öffnet
jede Naht neu.
Wort-Zeitstempel sind ein hartes Gate. Bevor du zu Schritt 5
übergehst, überprüfe, ob vo-words.json nicht leer ist und ein
words: [...]-Array mit start/end pro Wort hat. Wenn es leer
(0 Bytes) ist oder das Array fehlt – ein bekannter Fehlermodus, wenn
der TTS-Anbieter Audio, aber keine Zeitstempel-Nutzlast zurückgibt –
FAHRE NICHT ohne sie FORT. Fallback: Erzwinge die Ausrichtung des
produzierten Audios am Anzeige-Skript mit lokalem Whisper:
uvx --from openai-whisper whisper voiceover.mp3 \
--model base.en --language en --word_timestamps True \
--output_format json --output_dir .
# Führe dann align-captions.mjs mit --words voiceover.json (gleiche Form) aus
Whisper hört TTS-Wiedergaben falsch („gee-sap“ → „gsap“, „heyjen“ →
„hey Jen“ usw.) – Untertitel verwenden weiterhin 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 stillen
Build ohne Untertitel.
5 · Bauen
Befolge references/build-spec.md genau: Marken-Token + Schriftarten
(gebündelt in <SKILL_DIR>/assets/), der codierte animierte Hintergrund,
Szenengerüst, Chrom, Caption-Schiene, ein rationierter grüner Moment pro
Szene. Dann die Doctrine-Reihenfolge: ledger.json (alle normalen Nähte
cut-the-curve LINKS) → Nahtstempel → interne Beats auf VO-Wörtern →
Naht-Gate verifizieren.
Untertitel sind nicht optional. Das master-skeleton liefert eine
Caption-Schienen-IIFE, die ein LINES-Array liest – dieses Array leer
zu lassen, ist ein ausgelieferter Fehler, keine Stilwahl. Befülle es aus
captions.json, bevor du zu Schritt 6 übergehst:
// Füge anstelle von "const LINES = /* … */ []" in der Caption-Schienen-IIFE ein:
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 der Frame-Check in Schritt 6 fehlschlagen – überdecke dies nicht,
indem du #cap-line aus dem Grundgerüst entfernst.
6 · Gates (alle grün, bevor du präsentierst)
bun run --cwd packages/cli hyperframes check(oder die installiertehyperframesCLI aus dem repo-lokalenskills/hyperframes-cli/Skill) — 0 Fehler (Kontrast: dunkler Text ≥ .66 alpha). Greife NICHT zunpx 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 Fehler.- Starte den Preview-Server neu (er cacht das Bundle), überprüfe 3-4
Beats über
__player.seekauf der rohen Kompositionsseite. - Rendere NICHT, es sei denn, der Benutzer fragt danach. Überprüfe nach
einem angeforderten Render die Frames aus dem MP4 (
ffmpeg -ss <t> … -frames:v 1): Untertitel vorhanden, Hintergrundvideo nicht schwarz, keine winzigen/eingefrorenen Frames. - Caption-Anwesenheitsgate – harter Fehler. Nimm Stichproben von 3-4
Frames, die über das gesprochene Fenster des VO verteilt sind (z. B.
t=3,t=15,t=30,t=42für einen 48s VO) und bestätige, dass die Caption-Schiene beitop: 990auf jedem sichtbaren Text rendert. Wenn ein Frame in einem gesprochenen Intervall keine Untertitel hat, wird der Build ohne Untertitel ausgeliefert – behandle es als rotes Gate und überprüfe dieLINES-Befüllung von Schritt 5 erneut. Das ist genau das, was beim Jul 13-20 v4 Build schiefgelaufen ist.
Projektstruktur
projects/active/weekly-changelog-<range>/
├── index.html # Einzel-Dokument-Master (Szenen als Folien, gestempelte Nähte)
├── ledger.json # Vektor-Ledger (Nahtstempel-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 von <SKILL_DIR>/assets/bgm.mp3 (der Haus-Track), es sei denn, der Benutzer liefert einen
└── assets/fonts/ + assets/bg-pattern-<dur>s.mp4
Anti-Patterns
| Nicht tun | Stattdessen |
|---|---|
| Aufzählungspunkt-Folien für UI-Änderungen | Mocke die Oberfläche, die die Änderung nachspielt |
| 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 Anzeige-Schicht |
| Aussprache eines unbekannten Begriffs erraten | Fragen, dann das Lexikon erweitern |
| Jedes Changelog-Element sprechen | ≤3 pro Thema; der Digest-Link trägt den Rest |
| Grüne Akzente überall | Ein grüner Moment pro Szene (#5ef17c) |
Von einem früheren index.html starten | Schritt 0 — kopiere examples/master-skeleton.html aus diesem Skill in project/index.html, immer |
Handgefertigtes @font-face / WebGL-Shader / eigenes BGM | Schritt 0 — kopiere die assets/ dieses Skills wörtlich; die Assets des Skills SIND die Marke |
| Ohne CloudFront-Invalidierung ausgeliefert | Führe aws cloudfront create-invalidation für die Distribution E2BSLVSZ7FG3U0 auf dem genauen Pfad nach jedem S3-Ersatz aus – der CDN cached sonst die alte Datei |
Mit leerem LINES-Array im Grundgerüst ausgeliefert | 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. Ein leeres LINES = Lieferung ohne Untertitel = Wiederholung des Durchlaufs |
Kein vo-words.json → Untertitel überspringen und trotzdem ausliefern | Fallback auf Whisper-Forced-Alignment des produzierten Audios; Untertitel sind nicht optional |