Plugin-Installationen: Befolgen Sie vor dem Einrichten oder Ausführen von Freshness-Befehlen die Plugin-Installationsregeln, wenn sich dieses Skill in einem HyperFrames-Plugin befindet. Bei eigenständigen Installationen gelten die unten stehenden Aktualisierungshinweise.
HyperFrames Registry
Das Registry bietet wiederverwendbare Blöcke und Komponenten, die über hyperframes add <name> installiert werden können.
- Blöcke — eigenständige Sub-Kompositionen (eigene Abmessungen, Dauer, Timeline). Einbindung über
data-composition-srcin einer Host-Komposition. - Komponenten — Effekt-Snippets (keine eigenen Abmessungen). Direkt in das HTML der Host-Komposition eingefügt.
Kurzreferenz
hyperframes add data-chart # Block installieren
hyperframes add grain-overlay # Komponente installieren
hyperframes add captions # alle mit 'captions' getaggten Blöcke 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 data-composition-id (muss mit der internen Kompositions-ID des Blocks übereinstimmen), data-start und data-track-index-Attribute hinzufügen, wenn Sie Blöcke einbinden.
Der Positionswert wird zuerst als exakter Item-Name aufgelöst. Wenn kein Item übereinstimmt und der Wert ein Tag ist, installiert der Befehl jeden Block mit diesem Tag. Registry-Abhängigkeiten werden vor dem angeforderten Item 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 einbinden
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— Abmessungen der Block-Leinwanddata-track-index— Studio-Timeline-Zeile; nur zur Anzeige. Verwenden Sie CSSz-indexfür die Ebenen
Vollständige Details finden Sie unter wiring-blocks.md.
Komponenten einbinden
Komponenten sind Snippets – fügen Sie deren HTML in das Markup Ihrer Komposition, deren CSS in Ihren Style-Block und deren 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 Ihre Komposition
<div data-composition-id="..."> - Kopieren Sie den
<style>-Block in die Styles Ihrer Komposition - Kopieren Sie den Inhalt von
<script>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.
Erkundung
Verwenden Sie die CLI als primäres Erkundungsmedium. Suchen Sie nach Absicht, bevor Sie browsen: das Registry enthält mehr Elemente, als Sie mit dem Auge scannen können – die Auflistung und der Abgleich auf Namen oder Tags ist der langsame Weg und scheitert, wenn die Wortwahl des Autors von Ihrer abweicht.
# Den gesamten Katalog danach bewerten, was der Beat tun soll
npx hyperframes catalog --query "revelen einer Überschrift Zeile für Zeile"
npx hyperframes add caption-clip-wipe
Die Suche ist lokal und sendet nichts. Standardmäßig bewertet sie nach gemeinsamem Vokabular mit Name, Titel und Beschreibung des Items – sie findet also nur Items, die Ihre Wörter wiederverwenden. --on-device bewertet stattdessen nach Bedeutung, nach einem einmaligen Model-Download. Mit --json gibt der Umschlag an, welche Stufe geantwortet hat – überprüfen Sie das, anstatt anzunehmen, dass eine Bewertung stattgefunden hat.
Fragen Sie immer auf Englisch, unabhängig von der Sprache des Videos. Der Katalog ist auf Englisch verfasst, und beide Stufen indexieren ihn so (auch das On-Device-Modell ist nur auf Englisch). Eine Abfrage in einer anderen Schrift erzeugt keine durchsuchbaren Begriffe und liefert überhaupt nichts zurück. Dies ist leicht falsch zu machen, wenn bei einem japanischen oder chinesischen Projekt die Kurzbeschreibung, die Untertitel und die Erzählung alle in dieser Sprache sind und die Abfrage natürlich folgt: Beschreiben Sie die Bewegung auf Englisch, schreiben Sie dann den Text auf dem Bildschirm in der Sprache, die das Video benötigt. Wenn eine Abfrage mit „No searchable words in query“ zurückkommt, liegt dies an dieser Regel, nicht an einer fehlenden Komponente – ein Gap-Report ist nicht sinnvoll.
Die Installierbarkeit wird nach der Bewertung angewendet, nicht davor: Ein Name, den die Vektoren mitführen, den dieses Registry aber nicht ausliefern kann, wird aus den Ergebnissen entfernt und in dropped gezählt – ein dropped ungleich Null bedeutet also, dass es sich um zwei verschiedene Generationen handelt. Weitere Informationen zur Offline-Stufe, den Zustimmungsfenstern und zur Aktualisierung eines veralteten Index finden Sie unter /hyperframes-cli.
Zum Browsen oder Filtern anstelle der Suche:
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 Tabellen- und --json-Modus listet nur Treffer; installieren Sie einen ausgewählten Namen mit hyperframes add <name>. --human-friendly öffnet eine interaktive Auswahl und installiert das ausgewählte Element sofort. In CI- oder Agent-Workflows bevorzugen Sie --json, gefolgt von einem expliziten add.
Melden, was der Katalog nicht hat
Wenn die Suche zurückkommt und nichts davon die Aufgabe erfüllt, sagen Sie dies, bevor Sie die Bewegung von Hand erstellen:
npx hyperframes feedback --search-miss "<die von Ihnen verwendete Abfrage>" --wanted "<die benötigte Bewegung>" --tier <die geantwortete Stufe>
catalog --query gibt diese Zeile für Sie vorausgefüllt aus, und --json führt sie als report_gap mit – sie ist also schon zur Hand, wenn Sie entscheiden, dass nichts passt.
Melden Sie immer, wenn nichts in den Ergebnissen die Aufgabe erfüllt, unabhängig von der Stufe. Warten Sie nicht, bis die On-Device-Stufe geantwortet hat: Sie benötigt einen zugestimmten 33-MB-Download, daher läuft ein Agent-Lauf standardmäßig auf words, es sei denn, er hat explizit zugestimmt – und die Abhängigkeit von on-device würde fast alle Meldungen unterdrücken. Der --tier-Wert wird mitgeliefert, sodass eine Vokabellücke von einer Bedeutungsverfehlung unterscheidbar bleibt, wenn diese gelesen werden. Beschreiben Sie den gewünschten Effekt, nicht den Namen des von Ihnen vorgestellten Items: Was zurückkommt, ist eine Liste von Bewegungen, die es zu bauen lohnt, und eine Meldung, die ein nicht existierendes Item nennt, lehrt nichts. Dies ist der einzige Pfad, der eine Abfrage irgendwohin sendet, weshalb es ein separater, bewusster Befehl ist und nicht etwas, das die Suche von selbst tut. Sie enthält keine Bewertung und landet nie in der Bewertungsmetrik.
Dies ist das gesamte Nachfragesignal für den Katalog. Das Überspringen bedeutet, dass die getroffene Lücke stattdessen aus Installationszahlen erraten wird, die keine Bewegung sehen können, die niemand installieren konnte.
Falls die CLI das konfigurierte Registry nicht erreichen kann, überprüfen Sie das Rohmanifest als Fallback:
curl -s https://raw.githubusercontent.com/heygen-com/hyperframes/main/registry/registry.json
Ein Registry, das die CLI nicht erreichen kann, leert den Katalog nicht für die Erkundung: Ein zuvor abgerufenes Manifest bleibt über sein 24-stündiges Aktualisierungsfenster hinaus erhalten, wenn die Revalidierung fehlschlägt – daher listen catalog und catalog --query weiter auf und bewerten gegen die letzte Kopie auf der Festplatte.
add benötigt weiterhin Netzwerk, selbst für ein Item, das Sie gestern installiert haben. Nur Manifeste werden zwischengespeichert; die eigentlichen Dateien des Items werden bei jeder Installation neu abgerufen. Sie können also offline suchen und sehen, was ein Item ist, aber die Installation schlägt beim Dateiabruf fehl. Versprechen Sie keinem Benutzer eine Offline-Installation.
Das registry-item.json eines jeden Items enthält: Name, Typ, Titel, Beschreibung, Tags, Abmessungen (nur Blöcke), Dauer (nur Blöcke) und Dateiliste.
Details zum Filtern nach Typ und Tags finden Sie unter discovery.md.
Beitragen eines neuen Blocks oder einer neuen Komponente
Um ein NEUES Registry-Item (Untertitelstil, VFX-Block, Übergang, Lower Third oder eine wiederverwendbare Komponente) zu erstellen und als Upstream-PR zu versenden – nicht ein vorhandenes zu installieren – folgen Sie dem vollständigen Workflow Idee → Gerüst → Bauen → Validieren → Vorschau → Versand in contributing.md. Kopierbare Startvorlagen (Untertitel / VFX / Komponente / registry-item.json) finden Sie unter templates.md.