Plugin-Installationen: Führe vor Einrichtungs- oder Aktualisierungsbefehlen die Plugin-Ausführungsregeln aus, wenn diese Fähigkeit innerhalb eines HyperFrames-Plugins verwendet wird. Bei eigenständigen Installationen befolge die untenstehenden Aktualisierungshinweise.
Zuerst: Halte diese Fähigkeit frisch – bestätige mit dem Benutzer vor der Ausführung:
npx hyperframes skills update music-to-video. Ein schneller No-op, wenn alles aktuell ist; andernfalls wird diese Fähigkeit zusammen mit den Kern-Domain-Fähigkeiten, von denen sie abhängt, aktualisiert, bevor du dich auf sie verlässt.
music-to-video – Ein musikbasiertes, beat-synchronisiertes Video-Workflow
Nutze diese Fähigkeit, um einen Musiktitel in ein beat-synchronisiertes HyperFrames-Video zu verwandeln. Du analysierst den Track einmalig, legst die Frames fest, erstellst einen pro-Frame-Plan und baust jedes Frame als Komposition. Die Eingabe ist ein Musiktitel plus optionale Benutzerbilder oder -videos – es gibt keine Erzählung und keinen Webseiten-Capture. Typografie und Vorlagen bilden die Grundlage (ein vollständiges Video benötigt keine Assets); jegliche vom Benutzer bereitgestellten Medien werden auf dasselbe Beat-Raster geschnitten.
Du bist der Orchestrator. Arbeite in videos/<projekt>/>. Führe die Schritte in der Reihenfolge aus und passiere jedes Gate, bevor du fortfährst. Zwei Schritte benötigen den Benutzer: Schritt 3 (Plangenehmigung) und Schritt 6 (Render-Genehmigung) – beide sind Checkpoint-Gates gemäß ../hyperframes/references/brief-contract.md (lies es vor Schritt 0): Im autonomen Modus poste die Schritt-3-Zusammenfassung als Hinweis und fahre fort; die Schritt-6-Render-Genehmigung wird weiterhin als die eine beibehaltene Frage gestellt. Führe jeden Schritt selbst aus, außer Schritt 4, bei dem du einen Sub-Agent pro Frame einsetzt. Halte Design- und Bewegungsregeln aus dieser Datei fern – sie befinden sich in references/ und dem frame-worker-Sub-Agent.
SKILL_DIR = dieses Fähigkeitsverzeichnis. PROJECT_DIR = videos/<projektname>/>.
Workflow: Schritt 0 Setup → hyperframes.json + assets/bgm.mp3; Schritt 1 Analyse → audiomap.json; Schritt 2 Gerüst → STORYBOARD.md (Frames, Gruppen TBD); Schritt 3 Plan → vollständige STORYBOARD.md + frame.md; Schritt 4 Bau → compositions/frames/NN-*.html; Schritt 5 Zusammenbau → index.html; Schritt 6 Rendern → renders/video.mp4.
Zwei Grundideen, die alles prägen
- Ein Analyzer, dem du vertraust.
analyze-beatgrid.pyist der einzige Beat-Analyzer – vermesse Beats niemals mit einem anderen Tool oder nach Gehör neu. Seine Energie-/ Dichte-/ Rolls-/ Einsätze-/ Stille-Ergebnisse sind immer zuverlässig. Seinbpmundbeats_secsind nur dann zuverlässig, wenn die Musik wirklich rhythmisch ist; bei ruhiger Musik ist das Raster ein Metronom, das der Tracker aufgezwungen hat, also orientiere dich stattdessen an Phrasen und Energie und schneide niemals hart darauf. Zu entscheiden, welcher Fall vorliegt, ist daspacingjedes Frames (Schritt 2). - Ein Frame = eine Datei; Gruppen leben darin. Schritt 2 schneidet den Track in Frames, und jedes Frame wird zu einer Kompositionsdatei
compositions/frames/NN-<frame_id>.html, gebaut von einem frame-worker. Ein Frame kann in Gruppen unterteilt werden (jede eine Vorlage oder eine Kombination von Bewegungsprimitiven). Zusätzliche Dichte geht innerhalb einer Gruppe, sodass die Frame-Anzahl unterschiedliche Behandlungen zählt, nicht Beats – ein schneller Track erhöht nicht die Anzahl der Sub-Agenten.
Schritt 0: Setup, BGM und Eingaben
Ziel: Die Musikquelle etablieren, das HyperFrames-Projekt erstellen und etwaige vom Benutzer bereitgestellte Medien notieren.
Der Brief beginnt auf der Absichtsebene. Öffnungsregel, in der Reihenfolge: (1) BRIEF.md existiert → lies es und frage nichts, was es beantwortet – sein flow/storyboard leiten den Modus ab (Brief-Vertrag § 1). (2) Kein BRIEF.md, aber das Projekt existiert → setze fort mit dem, was auf der Festplatte ist; befrage niemals erneut. (3) Eine frische Erstellungsanfrage, die direkt hier ankam → lies /hyperframes und führe seine Absichtsebene aus (references/intent-interview.md): es bestätigt die Muss-Anforderungen dieser Route (die Musikquelle, Ziel → Seitenverhältnis – ../hyperframes/references/routes/music-to-video.md) und kündigt an, was aufgeschoben wird – Marke und Genre werden absichtlich in Schritt 3 gewählt. Schreibe BRIEF.md sofort nach der Initialisierung (niemals davor – init verweigert ein nicht leeres Verzeichnis) und notiere die präferenzbasierten Antworten (brief-format.md). Bearbeitungsanfragen überspringen all dies.
Die Musik ist das Rückgrat – etabliere einen Track vor allem anderen. Diese Fähigkeit ist optimiert für schnelle, energiegeladene BGM: ein starkes Beat-Raster treibt die Schnitte (ruhige Tracks funktionieren, aber orientiere dich eher an Phrasen als am Beat). Wenn der Benutzer Audio zur Verfügung gestellt hat – eine Musikdatei oder ein Video zur Audioextraktion – verwende es. Andernfalls wähle die Stimmung aus der Anfrage und generiere einen Track über /media-use (audio/references/bgm.md). Führe vor der ersten authentifizierten Provider-Aktion npx hyperframes auth status aus und gib seine Ausgabe wörtlich wieder. Wenn abgemeldet, wende einen Zweig an:
- Kollaborativ: Warte auf Anmeldung oder eine explizite Entscheidung, offline mit dem lokalen Provider fortzufahren.
- Autonom: Gib den Status an und fahre mit dem verfügbaren lokalen Provider fort.
Wenn kein Offline-Provider die erforderliche Musikfähigkeit erfüllen kann, zeige den Blockierer an. Schreibe niemals Schlüssel in ein pro-Repo .env. Auth-Besitz und Offline-Fallbacks befinden sich in /media-use references/setup-providers.md § Providers. Der resultierende Track landet unter assets/bgm.mp3. Stufe bereitgestellte Bilder oder Videos ein, damit Frames sie auf dem Beat-Raster verwenden können; andernfalls trägt die Typografie das Video.
Lyric-Videos: Für Texte, die synchron zum Gesang sind, erhalte Wort-/Zeilentiming durch Transkribieren des Tracks über /media-use oder frage den Benutzer nach dem Liedtext und platziere Zeilen auf dem Beat-Raster.
Initialisiere nur, wenn hyperframes.json fehlt. Benenne <projekt> aus dem Brief in Kebab-Schreibweise, z. B. midnight-drive-loop – niemals einen Zeitstempel. init überprüft die installierten Fähigkeiten gegen die neuesten auf GitHub und aktualisiert den globalen Satz, wenn welche veraltet sind.
npx hyperframes init "videos/<projekt>" --non-interactive --example=blank --skill=music-to-video
mkdir -p "$PROJECT_DIR/assets" "$PROJECT_DIR/renders"
cp "<benutzermusik>" "$PROJECT_DIR/assets/bgm.mp3" # zuerst aus einem Video extrahieren, falls nötig
# nur wenn der Benutzer dir Bilder/Videos gegeben hat:
node <SKILL_DIR>/scripts/stage-assets.mjs --from <verz> --hyperframes "$PROJECT_DIR" --into public
Die Marke (Schriftart + Palette) wird in Schritt 3 gewählt, nicht hier. Wähle kein Genre oder eine Track-Art im Voraus – Assets sind nur eine optionale Zutat, und das Genre ergibt sich aus den Entscheidungen pro Frame.
Gate: hyperframes.json + assets/bgm.mp3 existieren; Seitenverhältnis / Länge / fps und (falls vorhanden) das Asset-Inventar sind notiert.
Schritt 1: Musik analysieren
Ziel: Die eine kanonische Zeitanalyse erstellen, auf der das gesamte Video basiert.
analyze-beatgrid.py ist der einzige Beat-Analyzer – vermesse Beats niemals mit einem anderen Tool oder nach Gehör neu. Er liest den Track einmal und schreibt audiomap.json: Energiephasen (Level / Dichte / Gefühl), Einsätze + onset_rate, Rolls, Stille, hard_stops, key_moments, Phrasen, Tempo / Raster und audio.duration_sec. Er ist deterministisch – dieselbe Datei ergibt immer dieselbe Karte. Die meisten Felder sind bei jeder Musik zuverlässig; bpm und beats_sec sind nur dann zuverlässig, wenn die Musik wirklich rhythmisch ist, und dies zu beurteilen ist die Entscheidung, die du in Schritt 2 triffst.
Voraussetzungen: Python 3 mit librosa, numpy und soundfile verfügbar. Wenn der Import fehlschlägt, installiere sie in der aktiven Python-Umgebung, bevor du den Analyzer ausführst:
python3 -m pip install librosa numpy soundfile
python3 <SKILL_DIR>/scripts/analyze-beatgrid.py "$PROJECT_DIR/assets/bgm.mp3" \
-o "$PROJECT_DIR/audiomap.json" --print
Gate: audiomap.json existiert; audio.duration_sec ist bekannt.
Schritt 2: Frame-Gerüst (nur Struktur)
Ziel: Die Musik lesen und die Frames anordnen – das Gerüst von STORYBOARD.md.
Lies references/frame-skeleton.md. Verwandle audiomap.json selbst in das Gerüst von STORYBOARD.md – es gibt kein dazwischenliegendes JSON. Schneide den Track in Frames an echten musikalischen Änderungen (hard_stops, SURGE / DROP key_moments, die Ränder eines Rolls, ein Abschnitt ohne Einsätze, ein großer Energiesprung) und raste jede Grenze an einem audiomap-Anker ein. Setze für jedes Frame span_sec, pacing (das Urteil aus dem Vertrauensaufruf von Schritt 1 – beat_cut, wenn das Raster real ist, phrase_flow, wenn es ein aufgezwungenes Metronom auf ruhiger Musik ist), mood und ein einzeiliges feel (die reine Musiksituation, mit der Schritt 3 eine Vorlage abgleicht). Klassifiziere und lege hier nur an: Lasse jedes ### Gruppen des Frames als TBD (Schritt 3) und die Frontmatter style leer – keine Vorlagen, Texte, Farben oder Schriftarten. Erwarte ~1–6 Frames.
Gate: Frames kacheln den Track (erstes bei 0, letztes bei duration_s); jedes trägt span_sec + pacing + mood + feel; jedes ### Gruppen ist TBD; nirgendwo Inhalt.
Schritt 3: Plan ausfüllen (benutzergesperrt)
Ziel: Das Gerüst in eine genehmigte, vollständige STORYBOARD.md verwandeln.
Lies references/planning.md, storyboard-format.md, template-catalog.md, motion-primitive-catalog.md und montage.md (nur wenn der Benutzer Assets bereitgestellt hat). Bearbeite dieselbe Datei an Ort und Stelle und tue zwei Dinge:
- Wähle die Marke. Wähle eine Voreinstellung aus
../hyperframes-creative/frame-presets/mithilfe der Tabelle in../hyperframes-creative/references/design-spec.md(passe sie an die Stimmung des Tracks an; nur ihre Schriftarten und Farben sind wichtig – Vorlagen besitzen die Komposition). Kopiere sie unverändert inframe.mdund fülle die Frontmatterstyle(Schriftart + eine ≤4–6-Farbpalette) daraus. - Fülle jedes Frame. Entscheide über seine Gruppen und gib jeder eine Behandlung: eine passende Vorlage aus dem Katalog (mit gebundenen Parametern und echten audiomap-Ankern), eine freie Komposition aus dem Primitivenkatalog oder eine Asset-Behandlung, die
pacingbefolgt. Bevor du einen benannten Look frei komponierst, durchsuche den Live-Katalog danach: für jeden Look, Effekt, jede Behandlung oder jeden Übergang, den der Benutzer angefragt hat – „CRT scanlines“, „glitch“, „film grain“, „shimmer sweep“ – führenpx hyperframes catalog --query "<der Look, auf Englisch>" --jsonaus und lies die obersten Ergebnisse.template-catalog.mdundmotion-primitive-catalog.mdlisten nur die eigenen lokalen Materialien dieser Fähigkeit auf; die Suche bewertet das gesamte gehostete Register (~400 Blöcke und Komponenten) und benötigt nichts installiertes – kein Projekt, kein vorherigesadd, kein Konto. Komponiere einen Look nur frei, nachdem eine Suche danach nichts Passendes ergeben hat. Schreibe den Text. Du besitzt WAS (Vorlage / Primitiven + Inhalt + Anker); der frame-worker besitzt WIE – schreibe niemals Millisekunden-Tweens in das Storyboard.
node <SKILL_DIR>/scripts/validate-plan.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--audiomap "$PROJECT_DIR/audiomap.json" --templates <SKILL_DIR>/references/templates
Behebe jedes ✗ (harte Fehler: Dauerinkonsistenz, Frames kacheln den Track nicht, fehlendes src); Warnungen sind nach bestem Wissen und Gewissen. Präsentiere dann die Frame-für-Frame-Zusammenfassung im Chat als Vorschlag (../hyperframes/references/review-loop.md § 1) und iteriere auf die Antworten des Benutzers, bis er genehmigt; für storyboard: yes schreibe es auch als storyboard.html (../hyperframes-creative/references/storyboard-recipe.md § 3), damit der Benutzer es öffnen kann. Im autonomen Modus ist dies ein Checkpoint-Gate: poste die Zusammenfassung als Hinweis und fahre fort (der validate-plan.mjs-Durchlauf ist ein Qualitätsgate und blockiert weiterhin).
Gate: frame.md ist eine wörtliche Kopie einer Voreinstellung; validate-plan.mjs beendet mit 0; der Benutzer hat den Plan genehmigt (autonom: die Zusammenfassung wurde als Hinweis gepostet).
Schritt 4: Frames aus dem Plan bauen
Ziel: Jedes Frame als eigenständige Kompositionsdatei erstellen.
Erstelle compositions/frames/. Lies sub-agents/frame-worker.md und ../hyperframes/references/subagent-dispatch.md. Setze einen frame-worker pro Frame ein, parallel wo möglich (ansonsten in Wellen). Jeder Worker erhält genau ein Frame und diesen Kontext:
PROJECT_DIR: <absoluter Pfad>
frame_id: <NN-frame_id> # = der Frame-Dateiname ohne Erweiterung, z. B. 02-f2; die Kompositions-ID
Dein Block: der `## Frame N — <frame_id>`-Block in PROJECT_DIR/STORYBOARD.md
audiomap: PROJECT_DIR/audiomap.json
frame.md: PROJECT_DIR/frame.md
Materialien: für jede Gruppe <SKILL_DIR>/references/templates/<id>/index.html (Vorlagen) und
<SKILL_DIR>/references/motion-primitives/<id>/ (frei); gestufte assets/ (Asset-Gruppen)
Verträge: ../hyperframes-core/references/sub-compositions.md + determinism-rules.md
Leinwand: <b>×<h> Pacing: <beat_cut|phrase_flow>
Schreibe nach: PROJECT_DIR/compositions/frames/<frame_id>.html
Der Worker verzweigt die zitierten Materialien, konvertiert alle Anker in frame-lokale Sekunden (local_t = track_t − span_sec[0]), setzt seine Gruppen mit 0ms-Schnitten und schreibt eine seek-sichere Frame-Datei. Der Worker führt niemals die hyperframes CLI aus – diese Befehle arbeiten am zusammengebauten Projekt, das noch nicht existiert, also würden sie über die falschen Dateien berichten. Der Worker schreibt nur gemäß Vertrag und stoppt; du überprüfst nach dem Zusammenbau (Schritt 6). Sobald jeder Worker zurückkehrt, kannst du bestätigen, dass seine Datei auf der Festplatte gelandet ist.
Gate: Jedes Frame hat seine compositions/frames/NN-*.html auf der Festplatte.
Schritt 5: Zusammenbau
Ziel: Die gebauten Frames + BGM in die abspielbare index.html verdrahten.
assemble-index.mjs ist deterministisch – kein Sub-Agent, keine Beurteilung. Es referenziert jede Frame-Datei an ihrer kumulativen data-start, montiert assets/bgm.mp3 auf Spur 11 und führt harte Schnitte von Frame zu Frame durch (Frames kacheln den Track lückenlos, also gibt es keinen Übergangsinjektor).
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--hyperframes "$PROJECT_DIR" --audiomap "$PROJECT_DIR/audiomap.json"
Behebe jedes ✗, das es meldet – eine fehlende oder leere Frame-Datei bedeutet, dass dieser Worker eine unvollständige Datei geschrieben hat; setze ihn erneut ein (Schritt 4) und baue erneut zusammen.
Gate: index.html existiert; Gesamtdauer == audiomap.audio.duration_sec.
Schritt 6: Überprüfen und rendern
Ziel: Das zusammengebaute Video überprüfen, Benutzergenehmigung einholen und das finale MP4 rendern.
Führe die CLI auf dem zusammengebauten Projekt aus – das ist die korrekte Einheit (die Worker pro Frame konnten sie nicht ausführen). check führt einen deterministischen Gültigkeitscheck durch; sammle die Ausgabe und melde sie. Wenn der Benutzer genehmigt hat oder im autonomen Modus (dies ist das eine beibehaltene Gate), rendere das Video:
npx hyperframes render "$PROJECT_DIR" -o "$PROJECT_DIR/renders/video.mp4"
Gate: renders/video.mp4 existiert und ist abspielbar.
Fehlerbehebung & häufige Fehler
analyze-beatgrid.pyschlägt fehl: Überprüfe, ob Python-Abhängigkeiten installiert sind. Führepython3 -m pip install librosa numpy soundfileim aktiven Environment aus.hyperframes initschlägt fehl: Stelle sicher, dass das Projektverzeichnis leer ist und keinehyperframes.jsonexistiert.- Worker-Datei fehlt oder ist leer: Der Worker hat möglicherweise eine unvollständige Datei geschrieben. Setze den Worker für dieses Frame erneut ein.
assemble-index.mjsmeldet✗: Überprüfe die Protokolle. Eine fehlende Frame-Datei bedeutet, dass du den Worker erneut einsetzen musst. Ein Dauerinkonsistenz-Fehler weist auf ein Problem im Storyboard hin; validiere es erneut mitvalidate-plan.mjs.- CLI-Befehle im Worker: Der Worker führt niemals die
hyperframesCLI aus, da das zusammengebaute Projekt noch nicht existiert. Wenn ein Worker dies dennoch versucht, ist das ein Fehler – wende dich an den HyperFrames-Support.
Referenzen
../hyperframes/references/brief-contract.md../hyperframes/references/subagent-dispatch.md../hyperframes-core/references/sub-compositions.md../hyperframes-core/references/determinism-rules.mdreferences/frame-skeleton.mdreferences/planning.mdreferences/storyboard-format.mdreferences/template-catalog.mdreferences/motion-primitive-catalog.mdreferences/montage.mdsub-agents/frame-worker.md../hyperframes-creative/references/design-spec.md../hyperframes-creative/references/storyboard-recipe.md