Plugin-Installation: Führe vor dem Setup oder den Aktualisierungsbefehlen die Plugin-Installationsregeln aus, wenn sich dieser Skill innerhalb eines HyperFrames-Plugins befindet. Bei eigenständigen Installationen gelten die unten stehenden Aktualisierungshinweise.
Zuerst diesen Skill frisch halten – mit dem Benutzer abstimmen, bevor du ausführst:
npx hyperframes skills update music-to-video. Ein schneller No-Op, wenn alles aktuell ist; andernfalls wird dieser Skill zusammen mit den Kern-Skills, von denen er abhängt, aktualisiert, bevor du dich auf sie verlässt.
music-to-video – ein musikgesteuerter, taktsynchroner Video-Workflow
Nutze diesen Skill, um aus einem Musiktitel ein taktsynchrones HyperFrames-Video zu erstellen. Du analysierst den Titel einmalig, legst die Frames fest, erstellst einen Plan pro Frame und baust jedes Frame als Komposition auf. Die Eingabe ist ein Musiktitel plus optionale Benutzerbilder oder -videos – es gibt keine Erzählung und keinen Website-Screenshot. Typografie und Vorlagen sind die Basis (ein vollständiges Video benötigt null eigene Medien); alle vom Benutzer bereitgestellten Medien werden auf dasselbe Takt-Raster geschnitten.
Du bist der Orchestrator. Arbeite in videos/<projekt>/. Führe die Schritte in der Reihenfolge aus und bestehe jedes Gate, bevor du fortfährst. Zwei Schritte benötigen den Benutzer: Schritt 3 (Planfreigabe) und Schritt 6 (Renderfreigabe) – beides Checkpoint-Gates gemäß ../hyperframes/references/brief-contract.md (lies es vor Schritt 0): Im autonomen Modus poste die Zusammenfassung als Hinweis und fahre fort, anstatt zu warten. Führe jeden Schritt selbst aus, außer Schritt 4, bei dem du einen Sub-Agenten pro Frame einsetzt. Halte Design- und Bewegungsregeln aus dieser Datei heraus – sie leben in references/ und dem frame-worker-Sub-Agenten.
SKILL_DIR = dieses Skill-Verzeichnis. 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 Ideen, die alles bestimmen
- Ein Analysator, und du vertraust ihm.
analyze-beatgrid.pyist der einzige Beat-Analysator – miss Beats nie mit einem anderen Tool oder nach Gehör. Seine Energie-/Dichte-/Rolls-/Onsets-/Stille-Werte 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 – richte dich stattdessen nach Phrasen und Energie und schneide niemals hart danach. Zu entscheiden, in welchem Fall du dich befindest, ist die Aufgabe despacing-Felds jedes Frames (Schritt 2). - Ein Frame = eine Datei; Gruppen leben darin. Schritt 2 unterteilt den Titel in Frames, und jedes Frame wird zu einer Kompositionsdatei
compositions/frames/NN-<frame-id>.html, die von einem eigenen Frame-Worker erstellt wird. Ein Frame kann sich in Gruppen unterteilen (jede eine Vorlage oder eine Kombination von Bewegungs-Primitiven). Zusätzliche Dichte kommt innerhalb einer Gruppe, sodass die Frame-Anzahl die Anzahl unterschiedlicher Behandlungen widerspiegelt, nicht die Anzahl der Beats – ein schneller Titel lässt die Anzahl der Sub-Agenten nicht explodieren.
Schritt 0: Setup, BGM und Eingaben
Ziel: Die Musikquelle festlegen, das HyperFrames-Projekt erstellen und alle vom Benutzer bereitgestellten Medien notieren.
Das Briefing beginnt auf der Absichtsebene. Öffnungsregel, in dieser Reihenfolge: (1) BRIEF.md existiert → lies es und frage nichts, was es bereits beantwortet – sein flow/storyboard leiten den Modus ab (Brief-Contract § 1). (2) Kein BRIEF.md, aber das Projekt existiert → setze vom aktuellen Stand auf der Festplatte fort; befrage nie neu. (3) Eine neue Erstellungsanfrage, die direkt hier angekommen ist → lies /hyperframes und führe seine Absichtsebene aus (references/intent-interview.md): es bestätigt die Muss-Kriterien 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äferenzgestützten Antworten (brief-format.md). Bearbeitungsanfragen überspringen all dies.
Die Musik ist das Rückgrat – etabliere einen Titel vor allem anderen. Dieser Skill ist optimiert für schnelle, energiegeladene BGM: ein starkes Beat-Raster treibt die Schnitte (ruhige Titel funktionieren auch, aber richte dich nach Phrasen statt nach Beats). Hat der Benutzer Audio bereitgestellt – eine Musikdatei oder ein Video, aus dem Audio extrahiert werden soll – verwende es. Wähle andernfalls die Stimmung aus der Anfrage und generiere einen Titel über /media-use (references/bgm.md). Führe vor der ersten authentifizierten Provider-Aktion npx hyperframes auth status aus und gib dessen Ausgabe wortwörtlich weiter. Wenn abgemeldet, wende eine der beiden Varianten an:
- Kollaborativ: Warte auf die 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 Blockadegrund an. Schreibe niemals Schlüssel in eine Pro-repo .env-Datei. Auth-Eigentum und Offline-Fallbacks leben in /media-use references/setup-providers.md § Provider. Der resultierende Titel landet unter assets/bgm.mp3. Bühne bereitgestellte Bilder oder Videos, damit Frames sie auf dem Takt-Raster verwenden können; andernfalls trägt die Typografie das Video.
Lyric-Videos: für Texte, die mit dem Gesang synchronisiert sind, ermittle Wort-/Zeilen-Timing, indem du den Titel über /media-use transkribierst, oder frage den Benutzer nach dem Text und platziere die Zeilen auf dem Takt-Raster.
Initialisiere nur, wenn hyperframes.json fehlt. Benenne <projekt> aus dem Briefing in Kebab-Schreibweise, z. B. midnight-drive-loop – niemals einen Zeitstempel. init prüft die installierten Skills gegen die neuesten auf GitHub und aktualisiert die globale Menge, 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" # bei Bedarf zuerst aus einem Video extrahieren
# nur wenn der Benutzer dir Bilder/Videos gegeben hat:
node <SKILL_DIR>/scripts/stage-assets.mjs --from <verzeichnis> --hyperframes "$PROJECT_DIR" --into public
Die Marke (Schriftart + Palette) wird in Schritt 3 gewählt, nicht hier. Wähle nicht vorab ein Genre oder einen Titeltyp – 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 Timing-Analyse erstellen, auf der das gesamte Video aufbaut.
analyze-beatgrid.py ist der einzige Beat-Analysator – miss Beats nie mit einem anderen Tool oder nach Gehör. Es liest den Titel einmal und schreibt audiomap.json: Energiephasen (Pegel / Dichte / Gefühl), Onsets + onset_rate, Rolls, Stille, hard_stops, key_moments, Phrasen, Tempo/Raster und audio.duration_sec. Es ist deterministisch – dieselbe Datei liefert immer dieselbe Karte. Die meisten Felder sind bei jeder Musik zuverlässig; bpm und beats_sec sind nur 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 die aktive Python-Umgebung, bevor du den Analysator 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 anlegen – das Gerüst von STORYBOARD.md.
Lies references/frame-skeleton.md. Erstelle selbst aus audiomap.json das Gerüst von STORYBOARD.md – es gibt kein zwischengeschaltetes JSON. Schneide den Titel in Frames an echten musikalischen Veränderungen (hard_stops, SURGE / DROP key_moments, die Ränder eines Rolls, eine Strecke ohne Onsets, einen großen Energiesprung) und raste jede Grenze an einem Audiomap-Anker ein. Setze für jedes Frame span_sec, pacing (das Urteil aus dem Vertrauensentscheid von Schritt 1 – beat_cut, wenn das Raster echt ist, phrase_flow, wenn es ein Metronom ist, das ruhiger Musik aufgezwungen wurde), mood und eine einzeilige feel (die reine Musiksituation, die Schritt 3 mit einer Vorlage abgleicht). Klassifiziere und lege hier nur an: Lasse die ### Gruppen jedes Frames als TBD (Schritt 3) und das Frontmatter style leer – keine Vorlagen, kein Text, keine Farbe, keine Schriftarten. Erwarte ~1–6 Frames.
Gate: Frames decken den Titel ab (erstes bei 0, letztes bei duration_s); jedes hat span_sec + pacing + mood + feel; jedes ### Gruppen ist TBD; nirgendwo Inhalt.
Schritt 3: Plan ausfüllen (benutzergesteuert)
Ziel: Das Gerüst in ein genehmigtes, vollständiges 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 direkt und mache 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 Titels an; nur ihre Schriftarten und Farben sind wichtig – Vorlagen besitzen die Komposition). Kopiere sie unverändert inframe.mdund fülle das Frontmatterstyle(Schriftart + eine Palette mit ≤4–6 Farbtönen) daraus. - Fülle jedes Frame aus. Entscheide seine Gruppen und weise jeder eine Behandlung zu: eine passende Vorlage aus dem Katalog (mit gebundenen Parametern und echten Audiomap-Ankern), eine freie Komposition aus dem Primitiven-Katalog oder eine Asset-Behandlung, die
pacinggehorcht. Bevor du eine benannte Optik frei komponierst, durchsuche den Live-Katalog danach: für jede Optik, jeden Effekt, jede Behandlung oder jeden Übergang, den der Benutzer gewünscht hat – „CRT-Scanlines“, „Glitch“, „Filmkorn“, „Schimmer-Sweep“ – führenpx hyperframes catalog --query "<die Optik, auf Deutsch>" --jsonaus und lies die Top-Ergebnisse.template-catalog.mdundmotion-primitive-catalog.mdlisten nur die lokalen Materialien dieses Skills; die Suche bewertet das gesamte gehostete Register (~400 Blöcke und Komponenten) und benötigt nichts installiert – kein Projekt, kein vorherigesadd, kein Konto. Komponiere eine Optik nur frei, nachdem eine Suche danach nichts Passendes ergeben hat. Schreibe den Text. Du bestimmst WAS (Vorlage / Primitive + Inhalt + Anker); der Frame-Worker bestimmt 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 decken den Titel nicht ab, fehlendes src); Warnungen sind nach bestem Wissen und Gewissen zu behandeln. 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 zustimmt; bei 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äts-Gate und blockiert immer noch).
Gate: frame.md ist eine wörtliche Kopie der Voreinstellung; validate-plan.mjs endet mit Exit-Code 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 bauen.
Erstelle compositions/frames/. Lies sub-agents/frame-worker.md und ../hyperframes/references/subagent-dispatch.md. Weise einen Frame-Worker pro Frame zu, möglichst parallel (sonst 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 Endung, z. B. 02-f2; die Kompositions-ID
Dein Block: der Block `## Frame N — <frame_id>` 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); bereitgestellte Assets/ (Asset-Gruppen)
Verträge: ../hyperframes-core/references/sub-compositions.md + determinism-rules.md
Leinwand: <b>×<h> Tempo: <beat_cut|phrase_flow>
Schreibe nach: PROJECT_DIR/compositions/frames/<frame_id>.html
Der Worker kopiert die referenzierten Materialien, konvertiert jeden Anker in frame-lokale Sekunden (local_t = track_t − span_sec[0]), schaltet seine Gruppen mit 0ms-Schnitten und schreibt eine suchsichere 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 die falschen Dateien melden. Der Worker schreibt nur in den Vertrag und stoppt; du überprüfst nach dem Zusammenbau (Schritt 6). Sobald ein Worker zurückkommt, 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 ihrem kumulativen data-start, bindet assets/bgm.mp3 auf Spur 11 und setzt harte Schnitte von Frame zu Frame (Frames decken den Titel lückenlos ab, also gibt es keinen Übergangs-Injektor).
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--hyperframes "$PROJECT_DIR" --audiomap "$PROJECT_DIR/audiomap.json"
Behebe jedes von ihm gemeldete ✗ – eine fehlende oder leere Frame-Datei bedeutet, dass dieser Worker eine unvollständige Datei geschrieben hat; weise ihn erneut zu (Schritt 4) und baue erneut zusammen.
Gate: index.html existiert; Gesamtdauer == audiomap.audio.duration_sec.
Schritt 6: Verifizieren und rendern
Ziel: Das zusammengebaute Video verifizieren, die Benutzerfreigabe einholen und das endgültige MP4 rendern.
Führe die CLI am zusammengebauten Projekt aus – das ist die korrekte Einheit (die Frame-Worker konnten sie nicht ausführen). check führt einen strukturellen Lint und den Headless-Browser-Runtime-, Layout- und Bewegungsabgleich durch – dasselbe wie der Validator in Schritt 3, aber live im Browser. Wenn etwas fehlschlägt, korrigiere das Problem und baue erneut zusammen (Schritt 5).
cd "$PROJECT_DIR"
npx hyperframes check --headless
Wenn alle Prüfungen bestanden sind, präsentiere die Zusammenfassung (Rahmenanzahl, Dauer, Auflösung) und frage den Benutzer, ob er rendern möchte. Bei Genehmigung:
cd "$PROJECT_DIR"
npx hyperframes render renders/video.mp4 --headless
Gate: Benutzer genehmigt das Rendern; renders/video.mp4 existiert.
Referenzen
references/brief-contract.mdreferences/frame-skeleton.mdreferences/planning.mdreferences/storyboard-format.mdreferences/template-catalog.mdreferences/motion-primitive-catalog.mdreferences/montage.mdreferences/bgm.mdsub-agents/frame-worker.md../hyperframes/references/subagent-dispatch.md../hyperframes-creative/references/design-spec.md