HyperFrames Registry
Das Registry bietet wiederverwendbare Blöcke und Komponenten, die über hyperframes add <name> installiert werden können.
- Blöcke — eigenständige Subkompositionen (eigene Abmessungen, Dauer, Timeline). Werden über
data-composition-srcin eine Host-Komposition eingebunden. - Komponenten — Effekt-Snippets (keine eigenen Abmessungen). Werden direkt in das HTML der Host-Komposition eingefügt.
Kurzreferenz
hyperframes add data-chart # einen Block installieren
hyperframes add grain-overlay # eine Komponente installieren
hyperframes add captions # jeden Block mit dem Tag 'captions' installieren
hyperframes add shimmer-sweep --dir . # auf ein bestimmtes Projekt abzielen
hyperframes add data-chart --json # Maschinenlesbare Ausgabe
hyperframes add data-chart --no-clipboard # Zwischenablage überspringen (CI/Headless)
Nach der Installation gibt die CLI aus, welche Dateien geschrieben wurden und ein Snippet zum Einfügen in Ihre Host-Komposition. Das Snippet ist ein Ausgangspunkt – Sie müssen die Attribute data-composition-id (muss mit der internen Kompositions-ID des Blocks übereinstimmen), data-start und data-track-index hinzufügen, wenn Sie Blöcke verdrahten.
Der Positionswert wird zuerst als genauer Elementname aufgelöst. Wenn kein Element übereinstimmt und der Wert ein Tag ist, installiert der Befehl jeden Block mit diesem Tag. Registry-Abhängigkeiten werden vor dem angeforderten Element installiert. hyperframes add funktioniert nur für Blöcke und Komponenten; für Beispiele verwenden Sie stattdessen hyperframes init <dir> --example <name>.
Installationsorte
Blöcke werden standardmäßig in compositions/<name>.html installiert. Komponenten werden standardmäßig in compositions/components/<name>.html installiert.
Diese Pfade sind in hyperframes.json konfigurierbar:
{
"registry": "https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry",
"paths": {
"blocks": "compositions",
"components": "compositions/components",
"assets": "assets"
}
}
Vollständige Details finden Sie unter install-locations.md.
Blöcke verdrahten
Blöcke sind eigenständige Kompositionen – binden Sie sie über data-composition-src in Ihre Host-index.html ein:
<div
data-composition-id="data-chart"
data-composition-src="compositions/data-chart.html"
data-start="2"
data-duration="15"
data-track-index="1"
data-width="1920"
data-height="1080"
></div>
Wichtige Attribute:
data-composition-src— Pfad zur Block-HTML-Dateidata-composition-id— muss mit der internen ID des Blocks übereinstimmendata-start— wann der Block in der Host-Timeline erscheint (Sekunden)data-duration— wie lange der Block abgespielt wirddata-width/data-height— Block-Leinwandabmessungendata-track-index— Ebenenreihenfolge (höher = weiter vorne)
Vollständige Details finden Sie unter wiring-blocks.md.
Komponenten verdrahten
Komponenten sind Snippets – fügen Sie ihr HTML in das Markup Ihrer Komposition, ihr CSS in den Style-Block und ihr JS in Ihr Skript ein (falls vorhanden):
- Lesen Sie die installierte Datei (z.B.
compositions/components/grain-overlay.html) - Kopieren Sie die HTML-Elemente in das
<div data-composition-id="...">Ihrer Komposition - Kopieren Sie den
<style>-Block in die Styles Ihrer Komposition - Kopieren Sie jeglichen
<script>-Inhalt in das Skript Ihrer Komposition (vor Ihrem Timeline-Code) - Wenn die Komponente eine GSAP-Timeline-Integration bereitstellt (siehe Kommentarblock im Snippet), fügen Sie diese Aufrufe zu Ihrer Timeline hinzu
Vollständige Details finden Sie unter wiring-components.md.
Discovery
Verwenden Sie die CLI als primäre Oberfläche für die Entdeckung:
npx hyperframes catalog
npx hyperframes catalog --type block
npx hyperframes catalog --type component
npx hyperframes catalog --type block --tag social
npx hyperframes catalog --json
npx hyperframes catalog --human-friendly
Der normale Tabellenmodus und der --json-Modus listen nur Übereinstimmungen auf; installieren Sie einen ausgewählten Namen mit hyperframes add <name>. --human-friendly öffnet einen interaktiven Auswähler und installiert das ausgewählte Element sofort. In CI- oder Agent-Workflows bevorzugen Sie --json gefolgt von einem expliziten add.
Falls die CLI das konfigurierte Registry nicht erreichen kann, überprüfen Sie das rohe Manifest als Fallback:
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
Die registry-item.json jedes Elements enthält: name, type, title, description, tags, dimensions (nur Blöcke), duration (nur Blöcke) und file list.
Details zum Filtern nach Typ und Tags finden Sie unter discovery.md.
Beitrag eines neuen Blocks oder einer neuen Komponente
Um ein NEUES Registry-Element (Bildunterschriften-Stil, VFX-Block, Übergang, unteres Drittel oder eine wiederverwendbare Komponente) zu erstellen und als Upstream-PR bereitzustellen – nicht ein vorhandenes zu installieren – folgen Sie dem vollständigen Workflow Idee → Gerüst → Bauen → Validieren → Vorschau → Versand in contributing.md. Kopierfertige Startervorlagen (Bildunterschrift / VFX / Komponente / registry-item.json) finden Sie in templates.md.