Zum HyperFrames Registry beitragen
Führe den Benutzer von der Idee bis zum gemergten PR für einen neuen Registry-Block oder eine Komponente.
Arbeitsablauf
1. Klären → 2. Gerüst bauen → 3. Erstellen → 4. Validieren → 5. Vorschau → 6. Einreichen
Schritt 1: Klären
Frage, was sie bauen möchten. Das Registry hat zwei Arten von Einträgen:
- Block (
registry/blocks/, Typhyperframes:block) – eine vollständige eigenständige Komposition mit festen Abmessungen und Dauer. Caption-Stile, VFX-Effekte, Titelcards, Lower Thirds. - Komponente (
registry/components/, Typhyperframes:component) – ein wiederverwendbares Snippet ohne feste Abmessungen oder Dauer. CSS-Effekte, Textbehandlungen, Overlays, die sich jeder Kompositionsgröße anpassen.
Frage dann:
- Ein-Satz-Beschreibung des Effekts
- Visuelle Referenz (URL, Screenshot oder Beschreibung)
- Wer verwendet dies und wann?
Schritt 2: Gerüst bauen
Erstelle die Registry-Struktur:
Für Blöcke:
registry/blocks/{block-name}/
{block-name}.html
registry-item.json
Für Komponenten:
registry/components/{component-name}/
{component-name}.html
registry-item.json
Namenskonvention:
| Elementname | ID-Präfix | Beispiel-IDs |
|---|---|---|
cap-hormozi | hz | hz-cg-0, hz-cw-3 |
cap-typewriter | tw | tw-cg-0, tw-ch-0-5 |
vfx-chrome | vc | vc-canvas |
Verwende ein 2-3-Buchstaben-Präfix. ALLE Element-IDs müssen dieses Präfix verwenden, um Kollisionen in Unterkompositionen zu vermeiden.
registry-item.json für Blöcke:
{
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
"name": "{block-name}",
"type": "hyperframes:block",
"title": "{Menschlicher Titel}",
"description": "{ein Satz}",
"dimensions": { "width": 1920, "height": 1080 }, // anpassen: 1080x1920 für Hochformat/Soziales
"duration": 10, // für deine Komposition anpassen
"tags": ["{Kategorie}", "{Unterkategorie}"],
"files": [
{
"path": "{block-name}.html",
"target": "compositions/{block-name}.html",
"type": "hyperframes:composition"
}
]
}
registry-item.json für Komponenten (keine dimensions oder duration):
{
"$schema": "https://hyperframes.heygen.com/schema/registry-item.json",
"name": "{component-name}",
"type": "hyperframes:component",
"title": "{Menschlicher Titel}",
"description": "{ein Satz}",
"tags": ["{Kategorie}"],
"files": [
{
"path": "{component-name}.html",
"target": "compositions/components/{component-name}.html",
"type": "hyperframes:snippet"
}
]
}
Schritt 3: Erstellen
Wende die richtige Vorlage basierend auf dem Typ an. Siehe templates.md für Copy-Paste-Starter.
Caption-Blöcke
Unverhandelbare Caption-Regeln:
- Schriftart: Mindestens 96px für proportionale Schriftarten. 64-72px akzeptabel für Monospace (breitere Zeichen benötigen weniger Größe).
- Lesbarkeit:
-webkit-text-stroke: 2-3pxODER mehrschichtigestext-shadow - Überlauf: Rufe
window.__hyperframes.fitTextFontSize()für jede Gruppe auf - Karaoke: Hebe das aktive Wort mittels
tl.to(wordEl, { color/scale }, WORDS[wi].start)hervor - Hard Kill:
tl.set(groupEl, { opacity: 0, visibility: "hidden" }, g.end)bei JEDER Gruppe - Verwende niemals
tl.from(el, { opacity: 0 })an derselben Position wietl.set(el, { opacity: 1 })– das from überschreibt das set. Verwende stattdessentl.to.
Animation pro Zeichen (Schreibmaschine, Scramble):
- Wickele jedes Zeichen in ein
<span>mit der ID{prefix}-ch-{group}-{char} - Staffelung mittels
tl.setzu berechneten Intervallen basierend auf Wort-Zeitstempeln - Cursor/dekorative Elemente: Verwende
tl.setin Intervallen – NICHT CSS-Animation (nicht suchbar)
Positionierungsvarianten:
- Zentriert:
display: flex; align-items: center; justify-content: center; - Lower Third:
position: absolute; bottom: 100px; left: 0; width: 100%; text-align: center; - Linksbündig:
position: absolute; bottom: 100px; left: 120px; text-align: left;
VFX-Blöcke (Three.js)
- Verwende
[email protected]vom CDN (globales Skript) tl.eventCallback("onUpdate", renderScene); renderScene();– KEIN requestAnimationFrame- State-Proxy-Muster: GSAP animiert einfaches JS-Objekt, Render-Funktion liest es
- Seeded PRNG (
mulberry32) für Zufälligkeit
Alle Typen
data-composition-idMUSS mitwindow.__timelines["id"]übereinstimmen- Alle Element-IDs mit Block-Abkürzung versehen
gsap.timeline({ paused: true })– immer pausiert- Kein
Math.random(), keinDate.now()
Schritt 4: Validieren
hyperframes lint # 0 Fehler erforderlich
hyperframes validate --no-contrast # 0 Konsolenfehler erforderlich
Schritt 5: Vorschau
# Vorschauvideo rendern
hyperframes render -o preview.mp4
# Schnappschuss für visuelle QA
hyperframes snapshot --at "1.0,3.0,5.0,7.0"
# Auf hyperframes.dev zur Überprüfung veröffentlichen
npx hyperframes publish
Katalogvorschaubild – Die Katalogkarte verwendet ein PNG unter docs/images/catalog/{art}/{name}.png (wobei {art} blocks oder components ist). Generiere es aus einem Schnappschuss, dann:
- HeyGen-interne Mitwirkende: Führe
scripts/upload-docs-images.shaus (benötigt AWS-Profilengineering-767398024897) - Externe Mitwirkende: Füge das Vorschau-MP4 an deine PR-Beschreibung an. Ein Maintainer generiert und lädt das Katalogbild vor dem Mergen hoch.
Schritt 6: Einreichen
Alle Schritte sind erforderlich. Das Fehlen eines einzigen erzeugt einen defekten Katalogeintrag.
{art} ist blocks oder components, je nachdem, was du in Schritt 1 gebaut hast.
# 1. Branch erstellen
git checkout -b feat/registry-{name}
# 2. HTML formatieren
npx oxfmt registry/{art}/{name}/*.html
# 3. registry/registry.json aktualisieren – Eintrag zum "items"-Array hinzufügen:
# { "name": "{name}", "type": "hyperframes:block" } (oder "hyperframes:component")
# 4. Katalog-Dokumentationsseite generieren
npx tsx scripts/generate-catalog-pages.ts
# 5. Auf hyperframes.dev veröffentlichen, damit Reviewer eine Vorschau sehen können
npx hyperframes publish
# 6. Alles stagen
git add registry/{art}/{name}/ registry/registry.json docs/catalog/
# 7. Commit
.git commit -m "feat(registry): {name} — {ein Satz}"
# 8. Pushen und PR mit hyperframes.dev-Link öffnen
git push origin feat/registry-{name}
gh pr create --title "feat(registry): {name}" --body "preview: {hyperframes.dev-url}"
Wenn du kein GitHub-Konto hast: Du brauchst eines, um einen PR zu öffnen. Melde dich unter https://github.com/signup an und führe dann gh auth login aus.
Qualitätskontrolle
-
hyperframes lint→ 0 Fehler -
hyperframes validate→ 0 Konsolenfehler -
npx oxfmt --checkerfolgreich -
registry/registry.jsonmit neuem Eintrag aktualisiert -
scripts/generate-catalog-pages.tsausgeführt (Dokumentationsseite generiert) -
npx hyperframes publishausgeführt (Projekt-URL beansprucht) - Vorschau-MP4 an PR angehängt (extern) oder Katalog-PNG hochgeladen (intern)
- Alle IDs eindeutig und mit Präfix versehen