Musik-zu-Video — Ein beat-synchronisierter HyperFrames-Videoworkflow
Nutze diesen Skill, um einen Musiktitel in ein beat-synchronisiertes HyperFrames-Video zu verwandeln. Du analysierst den Track einmal, legst die Frames fest, füllst einen Frame-Plan aus und baust jeden Frame als Komposition. Die Eingabe ist ein Musiktitel plus optionale Benutzerbilder oder -videos – es gibt keine Erzählung und keinen Website-Capture. Typografie und Vorlagen sind der Grundbaustein (ein komplettes Video braucht keine Assets); alle vom Benutzer bereitgestellten Medien werden auf demselben Beat-Raster geschnitten.
Du bist der Orchestrator. Arbeite in videos/<project>/. Führe die Schritte der Reihe nach aus und bestehe jedes Gate, bevor du fortfährst. Zwei Schritte benötigen den Benutzer: Schritt 3 (Planfreigabe) und Schritt 6 (Render-Freigabe). Erledige jeden Schritt selbst, außer Schritt 4, wo du einen Sub-Agenten pro Frame einsetzt. Bewahre Design- und Bewegungsregeln außerhalb dieser Datei auf – sie leben in references/ und im frame-worker Sub-Agenten.
SKILL_DIR = dieses Skill-Verzeichnis. PROJECT_DIR = videos/<projekt-name>/.
Workflow: Schritt 0 Einrichtung → hyperframes.json + assets/bgm.mp3; Schritt 1 Analyse → audiomap.json; Schritt 2 Gerüst → STORYBOARD.md (Frames, Gruppen TBD); Schritt 3 Plan → vervollständige STORYBOARD.md + frame.md; Schritt 4 Bau → compositions/frames/NN-*.html; Schritt 5 Zusammenbau → index.html; Schritt 6 Render → renders/video.mp4.
Zwei Ideen, die alles prägen
- Ein Analysator, und du vertraust ihm.
analyze-beatgrid.pyist der einzige Beat-Analysator – miss Beats nie mit einem anderen Tool oder nach Gehör neu. Seine Energie-/Dichte-/Rolls-/Onsets-/Silence-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 auferlegt hat. Orientiere dich deshalb an Phrasen und Energie und schneide niemals hart darauf. Die Entscheidung, welcher Fall vorliegt, ist daspacingjedes Frames (Schritt 2). - Ein Frame = eine Datei; Gruppen leben darin. Schritt 2 unterteilt den Track in Frames, und jeder Frame wird zu einer Kompositionsdatei
compositions/frames/NN-<frame_id>.html, die von einem einzigen frame-worker erstellt wird. Ein Frame kann in Gruppen unterteilt werden (jede eine Vorlage oder eine Kombination aus Bewegungsprimitiven). Zusätzliche Dichte kommt innerhalb einer Gruppe unter, so dass die Frame-Anzahl unterschiedliche Behandlungen abbildet, nicht Beats – ein schneller Track erhöht nicht die Anzahl der Sub-Agenten.
Schritt 0: Einrichtung, BGM und Eingaben
Ziel: Lege die Musikquelle fest, erstelle das HyperFrames-Projekt und notiere alle vom Benutzer bereitgestellten Medien.
Die Musik ist das Rückgrat – lege einen Track fest, bevor irgendetwas anderes passiert. Dieser Skill ist optimiert für schnelle, energiegeladene Hintergrundmusik (BGM): Ein starkes Beat-Raster treibt die Schnitte (ruhige Tracks funktionieren, aber orientiere dich eher an Phrasen als am Beat). Wenn dir der Benutzer Audio gegeben hat – eine Musikdatei oder ein Video, aus dem du das Audio extrahieren sollst – verwende es. Wenn nicht, generiere eines: Wähle die Stimmung aus der Beschreibung des Benutzers (z. B. „treibender Synthwave“, „Trap-Beat“, „fröhlich, geschäftlich“) und erstelle einen Track via /hyperframes-media (references/bgm.md – HeyGen-Abruf, wenn authentifiziert, sonst lokales Lyria / MusicGen; ElevenLabs oder ein anderer Generator funktioniert auch). Führe vor der Generierung npx hyperframes auth status aus und gib seine Ausgabe wörtlich wieder (keine Paraphrase oder Umschreibung) – es zeigt, ob das BGM von HeyGen oder lokalem MusicGen stammt und, falls nicht eingeloggt, wie man sich einloggt. Falls nicht eingeloggt, STOPPEN und warten, bis der Benutzer wählt – einloggen oder offline mit lokalem MusicGen fortfahren – bevor der Track generiert wird; schreibe keine Schlüssel in eine repo-spezifische .env-Datei. (Im autonomen Modus den Status notieren und offline fortfahren.) Siehe /hyperframes-media → Preflight für die kanonische Anleitung. In beiden Fällen landet der Track bei assets/bgm.mp3. Bereite alle vom Benutzer bereitgestellten Bilder oder Videos so vor, dass Frames sie auf dem Beat-Raster einweben können; andernfalls trägt die Typografie das gesamte Video.
Initialisiere nur, wenn hyperframes.json fehlt. Benenne <project> aus dem Briefing in kebab-case, z. B. midnight-drive-loop – niemals ein Zeitstempel. init überprüft die installierten Skills mit den neuesten auf GitHub und aktualisiert den globalen Satz, wenn einer nicht auf dem neuesten Stand ist.
npx hyperframes init "videos/<project>" --non-interactive --example=blank
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 dir der Benutzer 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 ausgewählt, nicht hier. Wähle nicht vorab ein Genre oder eine Track-Art – 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: Erstelle die eine kanonische Timing-Analyse, 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 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 ergibt 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: Lies die Musik und lege die Frames fest – 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 an echten musikalischen Veränderungen (hard_stops, SURGE / DROP key_moments, die Kanten eines Rolls, eine Strecke ohne Onsets, einen großen Energiesprung) in Frames 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 auferlegt wurde), mood und eine einzeilige feel (die klare Musiksituation, mit der Schritt 3 eine Vorlage abgleicht). Klassifiziere und layoutiere hier nur: Lasse die ### Groups jedes Frames auf TBD (Step 3) und das Frontmatter style leer – keine Vorlagen, kein Copy, keine Farben 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: Plan ausfüllen (benutzergesteuert)
Ziel: Verwandle das Gerüst in ein freigegebenes, vollständiges STORYBOARD.md.
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 erledige 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(stimme mit der Stimmung des Tracks überein; 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 Farbpalette) daraus. - Fülle jeden Frame. Entscheide dich für 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
pacingbefolgt. 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: Dauerabweichung, Frames kacheln den Track nicht, fehlende src); Warnungen sind nach bestem Wissen und Gewissen zu behandeln. Zeige dem Benutzer dann eine Frame-für-Frame-Zusammenfassung und iteriere, bis er zustimmt.
Gate: frame.md ist eine wörtliche Kopie des Presets; validate-plan.mjs beendet mit 0; der Benutzer hat den Plan genehmigt.
Schritt 4: Frames aus dem Plan erstellen
Ziel: Erstelle jeden Frame als eigenständige Kompositionsdatei.
Erstelle compositions/frames/. Lies sub-agents/frame-worker.md und ../hyperframes-core/references/subagent-dispatch.md. Verteile einen frame-worker pro Frame, parallel wo möglich (sonst in Wellen). Jeder Arbeiter bekommt genau einen Frame und diesen Kontext:
PROJECT_DIR: <abs. Pfad>
frame_id: <NN-frame_id> # = der Dateiname des Frames, 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); bereitgestellte Assets/ (Asset-Gruppen)
Verträge: ../hyperframes-core/references/sub-compositions.md + determinism-rules.md
Leinwand: <B>×<H> Pace: <beat_cut|phrase_flow>
Schreibe nach: PROJECT_DIR/compositions/frames/<frame_id>.html
Der Arbeiter forkt die genannten Materialien, wandelt jeden Anker in lokale Sekunden des Frames um (local_t = track_t − span_sec[0]), verriegelt seine Gruppen mit 0ms-Schnitten und schreibt eine suchsichere Frame-Datei. Der Arbeiter führt niemals die hyperframes CLI aus – diese Befehle arbeiten auf dem zusammengebauten Projekt, das noch nicht existiert, also würden sie über die falschen Dateien berichten. Der Arbeiter schreibt nur den Vertrag und stoppt; du überprüfst nach dem Zusammenbau (Schritt 6). Wenn jeder Arbeiter zurückkehrt, 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: Zusammenbau
Ziel: Verdrahte die erstellten Frames + BGM in die abspielbare index.html.
assemble-index.mjs ist deterministisch – kein Sub-Agent, keine Beurteilung. Es referenziert jede Frame-Datei an ihrem kumulativen data-start, mountet 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 alle gemeldeten ✗ – eine fehlende oder leere Frame-Datei bedeutet, dass dieser Arbeiter eine unvollständige Datei geschrieben hat; verteile ihn erneut (Schritt 4) und baue neu zusammen.
Gate: index.html existiert; Gesamtdauer == audiomap.audio.duration_sec.
Schritt 6: Verifizieren und rendern
Ziel: Verifiziere das zusammengebaute Video, hole die Benutzerfreigabe ein und rendere das endgültige MP4.
Führe die CLI auf dem zusammengebauten Projekt aus – das ist die korrekte Einheit (die Frame-Arbeiter konnten sie nicht ausführen). lint prüft die Struktur, validate führt Headless Chrome aus (fängt JS-Fehler und fehlende Assets ab), inspect erstellt Momentaufnahmen von Frames.
( cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes validate . && npx hyperframes inspect . )
Überprüfe bei t=0, jedem Frame-Start, dem stärksten DROP / SURGE, jedem hard_stops[].t und dem letzten Frame. Bei einem Fehler führe selbst die günstigste sichere Reparatur durch: bearbeite die betreffende compositions/frames/NN-*.html. Ändere niemals die Dauer oder das Audio-Timing, um ein Synchronisationsproblem zu verbergen. Sobald die Gates bestanden sind, halte für die Benutzerüberprüfung inne, rendere dann nur nach Freigabe:
( cd "$PROJECT_DIR" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )
Gate: lint / validate / inspect bestanden; der Benutzer hat freigegeben; renders/video.mp4 existiert mit Audio, Dauer == audiomap.audio.duration_sec. Die finale Antwort gibt den MP4-Pfad und die Dauer an.
Fortsetzungstabelle
| Du hast | Fortsetzen ab |
|---|---|
Nur assets/bgm.mp3 | Schritt 1 |
audiomap.json | Schritt 2 |
STORYBOARD.md (Gerüst) | Schritt 3 |
STORYBOARD.md (vollst.) | Schritt 4 |
| Alle Frame-Dateien | Schritt 5 |
index.html | Schritt 6 |
Kurzreferenz
Formate: Querformat 1920x1080 standardmäßig; Hochformat 1080x1920; quadratisch 1080x1080. Setze die Leinwand einmal im Storyboard-Frontmatter (canvas: { w, h, fps }).
Skripte unter scripts/: analyze-beatgrid.py (der eine Analysator), validate-plan.mjs (Planprüfung), assemble-index.mjs (Index-Zusammenbau), stage-assets.mjs (Benutzermedien bereitstellen), lib/storyboard.mjs (eingekaufter Parser). Alles andere ist die hyperframes CLI.
| Lesen | Wann |
|---|---|
references/frame-skeleton.md | Schritt 2: Musik lesen, Frames anordnen, Pacing setzen |
references/planning.md · storyboard-format.md | Schritt 3: Marke wählen, jeden Frame füllen, Plan schreiben |
references/template-catalog.md | Schritt 3: Vorlage pro Gruppe wählen |
references/motion-primitive-catalog.md | Schritt 3: Freie Komposition aus Primitiven |
references/montage.md | Schritt 3: Nur bei mitgebrachten Assets lesen |
sub-agents/frame-worker.md | Schritt 4: Frame-Arbeiter dispatch |
../hyperframes-creative/references/design-spec.md | Schritt 3: Marke (frame.md) aus Preset-Tabelle |
../hyperframes-core/references/subagent-dispatch.md | Schritt 4: Register, Kontext, Verträge lesen |
../hyperframes-core/references/sub-compositions.md · determinism-rules.md | Schritt 4: Vertrag für jeden Frame-Arbeiter |