Zuerst: Halte diesen Skill frisch – bestätige mit dem Benutzer, bevor du ausführst:
npx hyperframes skills update music-to-video. Ein schneller No-Op, wenn alles aktuell ist; sonst wird dieser Skill plus die Kern-Skills, von denen er abhängt, aktualisiert, bevor du dich darauf verlässt.
music-to-video – ein musikbasierter, beat-synchronisierter Video-Workflow
Nutze diesen Skill, um einen Musiktrack in ein beat-synchronisiertes HyperFrames-Video zu verwandeln. Du analysierst den Track einmal, legst die Frames fest, füllst einen frame-basierten Plan aus und erstellst jeden Frame als Komposition. Die Eingabe ist ein Musiktrack plus optionale Benutzerbilder oder -videos – es gibt keine Erzählung und keinen Website-Screenshot. Typografie und Vorlagen bilden die Basis (ein vollständiges Video benötigt keine externen Assets); alle vom Benutzer bereitgestellten Medien werden auf dasselbe Beat-Raster geschnitten.
Du bist der Orchestrator. Arbeite in videos/<project>/. Führe die Schritte in der Reihenfolge aus und passiere jedes Gate, bevor du fortfährst. Zwei Schritte benötigen den Benutzer: Schritt 3 (Planfreigabe) und Schritt 6 (Renderfreigabe) – beides sind Checkpoint-Gates gemäß ../hyperframes/references/brief-contract.md (lies es vor Schritt 0): Im autonomen Modus postest du die Zusammenfassung als Hinweis und fährst fort, anstatt zu warten. Führe jeden Schritt selbst aus, außer Schritt 4, wo du einen Sub-Agenten pro Frame entsendest. Design- und Bewegungsregeln bleiben außerhalb dieser Datei – sie leben in references/ und dem frame-worker Sub-Agenten.
SKILL_DIR = dieses Skill-Verzeichnis. PROJECT_DIR = videos/<project-name>/.
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 Erstellung → compositions/frames/NN-*.html; Schritt 5 Assemblierung → index.html; Schritt 6 Rendering → renders/video.mp4.
Zwei Ideen, die alles bestimmen
- Ein Analyzer, und du vertraust ihm.
analyze-beatgrid.pyist der einzige Beat-Analyzer – miss Beats niemals mit einem anderen Tool oder nach Gehör neu. 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, also richte dich stattdessen nach Phrasen und Energie und schneide nie hart darauf. Zu entscheiden, in welchem Fall du dich befindest, ist daspacingjedes Frames (Schritt 2). - Ein Frame = eine Datei; Gruppen leben darin. Schritt 2 teilt den Track in Frames, und jeder Frame wird zu einer Kompositionsdatei
compositions/frames/NN-<frame_id>.html, erstellt von einem frame-worker. Ein Frame kann in Gruppen unterteilt werden (jede eine Vorlage oder eine Kombination aus Bewegungsprimitiven). Zusätzliche Dichte geht innerhalb einer Gruppe, also zählt die Frame-Anzahl die unterschiedlichen Behandlungen, nicht die Beats – ein schneller Track sprengt nicht die Anzahl der Sub-Agenten.
Schritt 0: Setup, BGM und Eingaben
Ziel: Die Musikquelle festlegen, das HyperFrames-Projekt erstellen und alle vom Benutzer bereitgestellten Medien notieren.
Der Brief beginnt auf der Intentionsebene. Öffnungsregel, in der 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 erneut. (3) Eine frische Erstellungsanfrage, die direkt hier angekommen ist → lies /hyperframes und führe seine Intentionsebene 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 bleibt – Marke und Genre werden absichtlich erst in Schritt 3 gewählt. Schreibe BRIEF.md sofort nach der Initialisierung (niemals davor – init verweigert ein nicht leeres Verzeichnis) und zeichne die präferenzgestützten Antworten auf (brief-format.md). Bearbeitungsanfragen überspringen all dies.
Die Musik ist das Rückgrat – lege einen Track fest, bevor du irgendetwas anderes tust. Dieser Skill ist optimiert für schnelle, energiegeladene BGM: ein starkes Beat-Raster treibt die Schnitte (ruhige Tracks funktionieren auch, aber richte dich nach Phrasen statt nach Beats). Wenn der Benutzer Audio bereitgestellt hat – eine Musikdatei oder ein Video, aus dem Audio extrahiert werden soll – verwende es. Wähle andernfalls die Stimmung aus der Anfrage und generiere einen Track über /media-use (references/bgm.md). Vor der ersten authentifizierten Provider-Aktion führe npx hyperframes auth status aus und gib die Ausgabe wörtlich weiter. 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-Fallback leben in /media-use references/setup-providers.md § Providers. Der resultierende Track landet unter assets/bgm.mp3. Stufe bereitgestellte Bilder oder Videos so ein, dass Frames sie auf dem Beat-Raster verwenden können; andernfalls trägt Typografie das Video.
Lyric-Videos: Für Lyrics, die auf den Gesang synchronisiert sind, erhalte Wort-/Zeilen-Timing durch Transkription des Tracks über /media-use, oder frage den Benutzer nach dem Lyric-Text und platziere Zeilen auf dem Beat-Raster.
Initialisiere nur, wenn hyperframes.json fehlt. Benenne <project> aus dem Brief in Kebab-Schreibweise, z. B. midnight-drive-loop – niemals ein Zeitstempel. init prüft die installierten Skills gegen die neuesten auf GitHub und aktualisiert das globale Set, wenn eines veraltet ist.
npx hyperframes init "videos/<project>" --non-interactive --example=blank --skill=music-to-video
mkdir -p "$PROJECT_DIR/assets" "$PROJECT_DIR/renders"
cp "<user-music>" "$PROJECT_DIR/assets/bgm.mp3" # extrahiere zuerst aus einem Video, falls nötig
# nur wenn der Benutzer dir Bilder/Videos gegeben hat:
node <SKILL_DIR>/scripts/stage-assets.mjs --from <dir> --hyperframes "$PROJECT_DIR" --into public
Die Marke (Schriftart + Palette) wird in Schritt 3 gewählt, nicht hier. Wähle kein Genre oder einen Track-Typ im Voraus – Assets sind nur eine optionale Zutat, und das Genre ergibt sich aus den Frame-bezogenen Entscheidungen.
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-Analyzer – miss Beats niemals mit einem anderen Tool oder nach Gehör neu. Es liest den Track einmal und schreibt audiomap.json: Energiephasen (Level / 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. Wenn der Import fehlschlägt, installiere sie in die aktive 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. Wandle audiomap.json selbst in das Gerüst von STORYBOARD.md um – es gibt kein dazwischenliegendes JSON. Schneide den Track an echten musikalischen Veränderungen in Frames (hard_stops, SURGE / DROP key_moments, die Ränder eines Rolls, ein Abschnitt ohne Onsets, ein großer Energiesprung) und raste jede Grenze an einem Audiomap-Anker ein. Setze für jeden Frame span_sec, pacing (das Urteil aus dem Vertrauensaufruf 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, gegen die Schritt 3 eine Vorlage abgleicht). Klassifiziere und lege hier nur an: lasse die ### Groups jedes Frames als TBD (Step 3) und das Frontmatter style leer – keine Vorlagen, kein Text, keine Farbe oder Schriftarten. Erwarte ~1–6 Frames.
Gate: Frames kacheln den Track (erster bei 0, letzter bei duration_s); jeder trägt span_sec + pacing + mood + feel; jedes ### Groups ist TBD; kein Inhalt irgendwo.
Schritt 3: Den Plan ausfüllen (benutzergesteuert)
Ziel: Das Gerüst in eine genehmigte, vollständige STORYBOARD.md umwandeln.
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 tue zwei Dinge:
- Wähle die Marke. Wähle ein Preset aus
../hyperframes-creative/frame-presets/mit der Tabelle in../hyperframes-creative/references/design-spec.md(passe es an die Stimmung des Tracks an; nur seine Schriftarten und Farben sind wichtig – Vorlagen besitzen die Komposition). Kopiere es unverändert inframe.mdund fülle das Frontmatterstyle(Schriftart + eine ≤4–6-Swatch-Palette) daraus. - Fülle jeden Frame. Entscheide 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 Primitiv-Katalog oder eine Asset-Behandlung, die
pacinggehorcht. 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", "Filmkorn", "Schimmer-Wisch" – führenpx hyperframes catalog --query "<der Look, auf Englisch>" --jsonaus und lies die Top-Ergebnisse.template-catalog.mdundmotion-primitive-catalog.mdlisten nur die lokalen Materialien dieses Skills; die Suche durchsucht das gesamte gehostete Register (~400 Blöcke und Komponenten) und benötigt nichts installiert – kein Projekt, kein vorherigesadd, kein Konto. Komponiere einen Look frei, erst nachdem eine Suche danach nichts Passendes ergeben hat. Schreibe den Text. Du besitzt WAS (Vorlage / Primitive + 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: Dauerabweichung, Frames, die den Track nicht kacheln, eine fehlende 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; 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 trotzdem).
Gate: frame.md ist eine wörtliche Preset-Kopie; 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 erstellen
Ziel: Jeden Frame als eigenständige Kompositionsdatei erstellen.
Erstelle compositions/frames/. Lies sub-agents/frame-worker.md und ../hyperframes/references/subagent-dispatch.md. Entsende einen frame-worker pro Frame, parallel wo möglich (sonst in Wellen). Jeder Worker bekommt genau einen Frame und diesen Kontext:
PROJECT_DIR: <abs path>
frame_id: <NN-frame_id> # = der Frame-Datei-Stamm, 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: <w>×<h> Pacing: <beat_cut|phrase_flow>
Schreibe nach: PROJECT_DIR/compositions/frames/<frame_id>.html
Der Worker forkt die zitierten Materialien, wandelt jeden Anker in frames-lokale Sekunden um (local_t = track_t − span_sec[0]), steuert seine Gruppen mit 0ms-Schnitten und schreibt eine suchsichere Frame-Datei. Der Worker führt niemals die hyperframes CLI aus – diese Befehle operieren auf dem assemblierten Projekt, das noch nicht existiert, also würden sie auf die falschen Dateien verweisen. Der Worker schreibt nur an den Vertrag und stoppt; du überprüfst nach der Assemblierung (Schritt 6). Wenn jeder Worker zurückkommt, kannst du bestätigen, dass seine Datei auf der Festplatte gelandet ist.
Gate: Jeder Frame hat seine compositions/frames/NN-*.html auf der Festplatte.
Schritt 5: Assemblierung
Ziel: Die erstellten Frames + BGM in die abspielbare index.html einbinden.
assemble-index.mjs ist deterministisch – kein Sub-Agent, keine Beurteilung. Es referenziert jede Frame-Datei an ihrem kumulativen data-start, montiert assets/bgm.mp3 auf Spur 11 und schneidet hart Frame → Frame (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 partielle Datei geschrieben hat; entsende ihn erneut (Schritt 4) und assembliere neu.
Gate: index.html existiert; Gesamtdauer == audiomap.audio.duration_sec.
Schritt 6: Überprüfen und rendern
Ziel: Das assemblierte Video überprüfen, Benutzerfreigabe einholen und das finale MP4 rendern.
Führe die CLI auf dem assemblierten Projekt aus – das ist die korrekte Einheit (die frame-basierten Worker konnten sie nicht ausführen). check führt strukturelles Linting und den Headless-Browser-Runtime-, Layout-, Bewegungs- und Kontrast-Gate in einem Durchlauf aus; --snapshots emittiert auch die Review-Frames.
( cd "$PROJECT_DIR" && npx hyperframes check . --snapshots )
Überprüfe bei t=0, jedem Frame-Start, dem stärksten DROP / SURGE, jedem hard_stops[].t,
… [für die Übersetzung gekürzt]