Changelog → Markenvideo
Eingabe: eine changelog.md-Datei (Themen + Einträge, z. B. der wöchentliche HyperFrames-Digest).
Ausgabe: ein lint-sauberes, seam-gate-grünes HyperFrames-Projekt in
projects/active/weekly-changelog-<range>/. Rendern nur auf Anfrage.
Zuerst laden, nicht verhandelbar: motion-doctrine (+ cut-the-curve,
oversized-cursor falls ein Cursor erscheint, seam-craft) und captions-overlay.
Diese Fähigkeit stellt die changelog-spezifische Pipeline bereit; die Doktrin liefert
das Bewegungsgesetz.
Die oberste Direktive: visualisieren, nicht auflisten
Jedes Thema wird durch einen animierten Mock der tatsächlichen Benutzeroberfläche oder ein
treues Analogon illustriert, das die Änderung im Erlebnis nachbildet – niemals Textaufzählungen.
Jedes Thema/jeden Eintrag VOR dem Schreiben des Skripts durch references/visualization-registry.md
leiten; die Registry entscheidet über ui-recreate / ui-analog / terminal / checkliste.
Text-Checkliste ist der LETZTE Ausweg, reserviert für wirklich nicht-visuelle Einträge
(zuverlässigkeitsbezogene Fehlerbehebungslisten).
Pipeline
0 · Bootstrapping des Projekts AUS DEN RESSOURCEN DIESER FÄHIGKEIT – nicht verhandelbar
Tun Sie dies, bevor Sie Composition-HTML schreiben. Das Überspringen führt immer zu einem Video, das wie ein ähnliches Projekt aussieht, das Sie zuvor gebaut haben, NICHT wie die Marke dieser Fähigkeit – das ist der mit Abstand häufigste Weg, wie diese Fähigkeit von der Marke abweicht. Die Ressourcen, Schriftarten und das Gerüst dieser Fähigkeit SIND die Fähigkeit; die SKILL.md-Anweisung 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
Lesen Sie dann references/build-spec.md vollständig durch (nicht überfliegen) – es definiert die Marken-Token (TT Norms Pro + ABC Solar Display + TT Norms Mono, Cremefarbe #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 Gerüst erbt.
Erst DANN beginnen Sie mit den Schritten 1-6 unten. Die Schritte 1-4 (Parsen, Routing, Skript, Sprecher) planen, was in das Gerüst kommt; Schritt 5 füllt Platzhalter (<RANGE>, <TOTAL>, <CUT_N>, <DUR_N>, Szeneninhalte) innerhalb der bereits kopierten project/index.html – Sie überschreiben NICHT das Chrome, die Schriftarten, die Palette oder das Layout-Shell des Gerüsts.
Wenn Sie dabei ertappen, dass Sie nach einem cp auf das index.html eines früheren Videos greifen, eigene @font-face-Deklarationen schreiben oder einen WebGL-Shader-Hintergrund entwerfen, anstatt das codierte bg-pattern-MP4 von oben zu verwenden: STOPPEN Sie. Löschen Sie das aktuelle index.html und beginnen Sie neu beim cp des master-skeleton-Gerüsts. Den Szeneninhalt auf dem richtigen Gerüst neu aufzubauen, ist günstiger, als nachträglich die Marke in das falsche Gerüst einzubauen.
1 · Parsen + redaktioneller Schnitt
- Extrahieren: Wochenbereich, Überschriftsstatistiken (Releases, Commits), Themen, Einträge.
- Budget: 45-60s gesamt. Titel ≤2s, Abspann ≤3.5s, 4 Themen ≈ 9-12s pro Thema.
- Pro Thema BEHALTEN Sie EINE Heldenvisualisierung + maximal 3 gesprochene Einträge. Alles andere existiert nur als Verweis auf den „vollständigen Digest“ im Abspann. Schneiden ist die Aufgabe: ein Changelog mit 30 Einträgen ergibt immer noch ≤14 gesprochene Beats.
- Themen nach Geschichte ordnen: Vorzeigefunktion → Produktoberfläche → Leistung → Zuverlässigkeit (der Digest ist normalerweise bereits so aufgebaut).
2 · Visualisierungs-Routing
Wählen Sie für jedes Thema die Oberfläche aus references/visualization-registry.md
und schreiben Sie eine Zeile: thema → oberfläche → die 2-4 sequenziellen Aktionen, die der Mock ausführt, jede verknüpft mit einem Skriptsatz. Wenn keine Registry-Oberfläche passt und kein
treues Analogon existiert, handelt es sich um eine Checklisten-Szene – erfinden Sie keine gefälschte Benutzeroberfläche für etwas, das wir nicht ehrlich darstellen können.
3 · Zweischichtiges Skript (gesprochen vs. Anzeige)
Schreiben Sie das Skript als Token-Zeilen gemäß references/script-voice.md:
konversationeller Register, jeder technische Begriff trägt eine spoken-Phonetikform
aus references/lexicon.json, während display die Standardschreibweise beibehält.
Untertitel zeigen display; die Sprecherstimme liest spoken. Jeder Begriff, der nicht im Lexikon ist:
STOPPEN und den Benutzer fragen, wie er ausgesprochen wird, dann zum Lexikon hinzufügen.
Speichern Sie als script-tokens.json im Projekt.
4 · Sprecher – Annie (HeyGen, fixiert)
# Nur Text der gesprochenen Ebene; words JSON = Ground-Truth-Zeitstempel des GESPROCHENEN Texts
# Repo-eigener Pfad: Der Changelog-Video-Skill wird vom HyperFrames-Repo-Root aus ausgeführt,
# verwendet also direkt den getrackten hyperframes-media TTS-Helfer (kein `npx hyperframes
# skills` Installationsschritt). Wenn Sie den Skill in ein anderes Repo kopiert haben, tauschen Sie
# Ihren 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 – naturgetreu (nicht ersetzen)
Erfordert heygen CLI ≥0.3.0, authentifiziert (heygen auth login --oauth).
Dann die gesprochenen Zeitstempel zurück auf die Anzeige-Token abgleichen:
node <SKILL_DIR>/scripts/align-captions.mjs \
--tokens script-tokens.json --words vo-words.json --out captions.json
captions.json ist die Eingabe für die Untertitelschiene (Anzeige-Schreibweise, gesprochenes Timing).
Der Aligner gibt MISMATCH-Warnungen aus – jede einzelne auflösen, bevor weitergebaut wird
(meistens ein Lexikonbegriff, den der TTS als mehrere Wörter rendert). Der Ton
ist die Uhr: alle Beat-Zeiten stammen aus vo-words.json; eine erneute Sprechergenerierung öffnet
jede Naht neu.
Wort-Zeitstempel sind eine harte Hürde. Bevor Sie zu Schritt 5 übergehen, stellen Sie sicher,
dass vo-words.json nicht leer ist und ein words: [...]-Array mit start/end
pro Wort enthält. Wenn es leer (0 Byte) ist oder das Array fehlt – ein bekannter Fehlermodus,
wenn der TTS-Anbieter Audio, aber keine Zeitstempel-Nutzlast zurückgibt – FAHREN Sie NICHT ohne
sie fort. Rückfall: Erzwingen Sie die Ausrichtung des produzierten Audios gegen das Anzeigeskript
mithilfe von lokalem Whisper:
uvx --from openai-whisper whisper voiceover.mp3 \
--model base.en --language en --word_timestamps True \
--output_format json --output_dir .
# dann align-captions.mjs ausführen mit --words voiceover.json (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 kümmert sich um die Zusammenführung.
Dieser Rückfall ist der Unterschied zwischen einem Build mit Untertiteln und einem
stillen Build ohne Untertitel.
5 · Bauen
Folgen Sie genau references/build-spec.md: Marken-Token + Schriftarten (gebündelt in
<SKILL_DIR>/assets/), die codierte animierte Hintergrund-Enkodierung, Szenengerüst,
Chrome, Untertitelschiene, ein rationierter grüner Moment pro Szene. Dann die Doktrin-Reihenfolge:
ledger.json (alle gewöhnlichen Nähte geschnitten-the-curve LINKS) → Seam-Stempel →
interne Beats auf VO-Wörtern → Seam-Gate-Überprüfung.
Untertitel sind nicht optional. Das Master-Skelett enthält eine Caption-Rail-IIFE,
die ein LINES-Array liest – dieses Array leer zu lassen, ist ein ausgelieferter Fehler, keine
Stilwahl. Befüllen Sie es aus captions.json, bevor Sie zu Schritt 6 übergehen:
// Ersetzen von "const LINES = /* … */ []" in der Caption-Rail-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 – überdecken Sie das nicht, indem Sie #cap-line aus dem
Gerüst entfernen.
6 · Hürden (alle grün, bevor präsentiert wird)
node packages/cli/bin/hyperframes.mjs check --caption-zone "x0=0;y0=.90;x1=1;y1=1;severity=error;seek=.02,.06,.10,.14,.18,.22,.26,.30,.34,.38,.42,.46,.50,.54,.58,.62,.66,.70,.74,.78,.82,.86,.90,.94,.98"(oder die installiertehyperframes-CLI aus dem Repo-lokalenskills/hyperframes-cli/Skill) — 0 Fehler (Kontrast: gedimmter Text ≥ .66 Alpha; Szeneninhalt bleibt oberhalb der Untertitelschiene). NICHT zunpx hyperframes@latestgreifen; die getrackte, Repo-lokale CLI ist die Quelle der Wahrheit für den Kompositionsvertrag, den dieser Skill produziert.seam-gate.mjs verify— 0 Fehler.- Starten Sie den Vorschau-Server neu (er cacht das Bundle), überprüfen Sie 3-4 Beats
stichprobenartig über
__player.seekauf der rohen Kompositionsseite. - NICHT rendern, es sei denn, der Benutzer fragt. Nach einem angeforderten Render überprüfen Sie
Frames aus dem MP4 (
ffmpeg -ss <t> … -frames:v 1): Untertitel vorhanden, Hintergrundvideo nicht schwarz, keine winzigen/eingefrorenen Frames. - Untertitel-Präsenz-Hürde – harter Fehler. Überprüfen Sie stichprobenartig 3-4 Frames, die über das
gesprochene Fenster der VO verteilt sind (z. B.
t=3,t=15,t=30,t=42für eine 48s VO) und bestätigen Sie, dass die Untertitelschiene beitop: 990auf jedem sichtbaren Text rendert. Wenn irgendein Frame in einem gesprochenen Intervall keine Untertitel hat, wird der Build ohne Untertitel ausgeliefert – behandeln Sie es als rote Hürde und überprüfen Sie erneut die Befüllung vonLINESin Schritt 5. Genau das ist beim Build vom 13.-20. Juli v4 schiefgelaufen.
Projektlayout
projects/active/weekly-changelog-<range>/
├── index.html # Single-Doc-Master (Szenen als Folien, gestempelte Nähte)
├── ledger.json # Vektor-Ledger (Seam-Stamp-Eingabe)
├── script-tokens.json # Zweischicht-Skript (Quelle der Wahrheit für VO + Untertitel)
├── vo-spoken.txt # generiert: gesprochene Ebene, 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ählungspunkte-Folien für UI-Änderungen | Die Oberfläche nachbilden, die die Änderung vorführt |
| Gefälschte UI für nicht darstellbare Einträge | Ehrliche Checklisten-Szene |
| Einfache „JSON"/"CLI" im TTS-Text | Lexikon-Gesprochene-Formen; Anzeige bleibt Standard |
| Phonetische Schreibweisen in Untertiteln | Untertitel rendern immer die Anzeige-Ebene |
| Erraten der Aussprache eines unbekannten Begriffs | Fragen, dann das Lexikon erweitern |
| Jeden Changelog-Eintrag sprechen | ≤3 pro Thema; der Digest-Link trägt den Rest |
| Grüne Akzente überall | Ein grüner Moment pro Szene (#5ef17c) |
| Beginnen mit dem index.html eines früheren Videos | Schritt 0 – examples/master-skeleton.html aus dieser Fähigkeit in project/index.html kopieren, immer |
Handgefertigte @font-face / WebGL-Shader / eigener BGM | Schritt 0 – die assets/ dieser Fähigkeit unverändert kopieren; die Ressourcen der Fähigkeit SIND die Marke |
| Lieferung ohne CloudFront-Invalidierung | aws cloudfront create-invalidation für die Distribution E2BSLVSZ7FG3U0 für den genauen Pfad nach jedem S3-Ersatz ausführen – der CDN cached sonst die alte Datei |
Auslieferung 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 Hürde 5 muss Untertitel auf gerenderten Frames bestätigen. Ein leeres LINES = Auslieferung ohne Untertitel = Wiederholung des Durchlaufs |
Kein vo-words.json → Untertitel überspringen und trotzdem ausliefern | Auf Whisper-Zwangszuordnung des produzierten Audios zurückfallen; Untertitel sind nicht optional |