Musik-zu-Video – Ein musikgesteuerter, beat-synchronisierter Video-Workflow
Nutze diese Fähigkeit, um einen Musiktitel in ein beat-synchronisiertes HyperFrames-Video zu verwandeln. Du analysierst den Titel einmal, legst die Frames fest, füllst einen Frame-für-Frame-Plan und baust jeden Frame als Komposition. Die Eingabe ist ein Musiktitel plus optionale Bilder oder Videos vom Benutzer – es gibt keine Erzählung und keinen Website-Capture. Typografie und Vorlagen bilden die Basis (ein vollständiges Video benötigt keine Assets); alle vom Benutzer bereitgestellten Medien werden auf demselben Beat-Raster zugeschnitten.
Du bist der Orchestrator. Arbeite in videos/<projekt>/. 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). 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/<projekt-name>/.
Workflow: Schritt 0 Setup → hyperframes.json + assets/bgm.mp3; Schritt 1 Analyse → audiomap.json; Schritt 2 Skelett → STORYBOARD.md (Frames, Gruppen TBD); Schritt 3 Plan → vollständige STORYBOARD.md + frame.md; Schritt 4 Bau → compositions/frames/NN-*.html; Schritt 5 Montage → 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-/Roll-/Onset-/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. Die Entscheidung, welcher Fall vorliegt, ist daspacingjedes Frames (Schritt 2). - Ein Frame = eine Datei; Gruppen leben darin. Schritt 2 schneidet den Titel in Frames, und jeder Frame wird zu einer Kompositionsdatei
compositions/frames/NN-<frame_id>.html, die von einem Frame-Worker erstellt wird. Ein Frame kann in Gruppen unterteilt werden (jede eine Vorlage oder eine Kombination von Bewegungs-Primitiven). Zusätzliche Dichte geht innerhalb einer Gruppe, sodass die Frame-Anzahl unterschiedliche Behandlungen widerspiegelt, nicht 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.
Die Musik ist das Rückgrat – lege einen Titel fest, bevor du etwas anderes tust. Diese Fähigkeit ist für schnelle, energiegeladene BGM optimiert: Ein starkes Beat-Raster treibt die Schnitte (ruhige Titel funktionieren, aber richte dich nach Phrasen statt nach Beats). Wenn der Benutzer dir 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“, „aufmunterndes Corporate“) und erstelle einen Titel über /hyperframes-media (references/bgm.md – HeyGen-Abruf, wenn authentifiziert, sonst lokales Lyria / MusicGen; ElevenLabs oder ein anderer Generator funktioniert auch). Bevor du generierst, führe npx hyperframes auth status aus und gib seine Ausgabe wörtlich wieder (paraphrasiere oder schreibe sie nicht um) – sie zeigt an, ob die BGM von HeyGen oder lokalem MusicGen stammt und, falls nicht angemeldet, wie man sich anmeldet. Wenn nicht angemeldet, STOPP und warte, bis der Benutzer sich entscheidet – anmelden oder offline mit lokalem MusicGen fortfahren – bevor du den Titel generierst; schreibe keine Schlüssel in eine repo-spezifische .env. (Im autonomen Modus notiere den Status und fahre offline fort.) Siehe /hyperframes-media → Preflight für die kanonische Anleitung. In beiden Fällen landet der Titel unter assets/bgm.mp3. Stage alle vom Benutzer bereitgestellten Bilder oder Videos, damit Frames sie auf dem Beat-Raster einweben können; andernfalls trägt die Typografie das gesamte Video.
Initialisiere nur, wenn hyperframes.json fehlt. Benenne <projekt> aus der Aufgabenbeschreibung in Kebab-Schreibweise, z. B. midnight-drive-loop – niemals einen Zeitstempel. init überprüft die installierten Skills mit den neuesten auf GitHub und aktualisiert den globalen Satz, wenn welche veraltet sind.
npx hyperframes init "videos/<projekt>" --non-interactive --example=blank
mkdir -p "$PROJECT_DIR/assets" "$PROJECT_DIR/renders"
cp "<benutzer-musik>" "$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 <verz> --hyperframes "$PROJECT_DIR" --into public
Die Marke (Schriftart + Palette) wird in Schritt 3 ausgewählt, nicht hier. Wähle nicht im Voraus ein Genre oder einen Titeltyp aus – 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: Die 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 neu. Es liest den Titel 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 das zu beurteilen ist deine Entscheidung in Schritt 2.
Voraussetzungen: Python 3 mit librosa, numpy und soundfile. 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-Skelett (nur Struktur)
Ziel: Die Musik lesen und die Frames anlegen – das Skelett von STORYBOARD.md.
Lies references/frame-skeleton.md. Verwandle audiomap.json selbst in das Skelett von STORYBOARD.md – es gibt kein dazwischenliegendes JSON. Schneide den Titel in Frames an echten musikalischen Veränderungen (hard_stops, SURGE / DROP key_moments, die Kanten eines Rolls, ein Abschnitt ohne Onsets, ein großer Energiesprung), wobei jede Grenze an einen Audiomap-Anker gesnappt wird. 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 auf ruhige Musik aufgezwungenes Metronom ist), mood und ein einzeiliges feel (die einfache Musiksituation, die Schritt 3 mit einer Vorlage abgleicht). Klassifiziere und lege hier nur an: Lasse bei jedem Frame ### Gruppen als TBD (Schritt 3) und das Frontmatter style leer – keine Vorlagen, Kopien, Farben oder Schriftarten. Erwarte etwa 1–6 Frames.
Gate: Frames kacheln den Titel (erster bei 0, letzter bei duration_s); jeder trägt span_sec + pacing + mood + feel; jedes ### Gruppen ist TBD; kein Inhalt irgendwo.
Schritt 3: Den Plan füllen (benutzergesteuert)
Ziel: Das Skelett in ein freigegebenes, 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 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 die Stimmung des Titels 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 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 Primitiven-Katalog oder eine Asset-Behandlung, die
pacingbefolgt. 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 Titel 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 Preset-Kopie; validate-plan.mjs endet mit 0; der Benutzer hat den Plan freigegeben.
Schritt 4: Frames aus dem Plan bauen
Ziel: Jeden Frame als eigenständige Kompositionsdatei erstellen.
Erstelle compositions/frames/. Lies sub-agents/frame-worker.md und ../hyperframes-core/references/subagent-dispatch.md. Setze einen Frame-Worker pro Frame ein, wo möglich parallel (sonst in Wellen). Jeder Worker erhält genau einen Frame und diesen Kontext:
PROJECT_DIR: <absoluter Pfad>
frame_id: <NN-frame_id> # = der Frame-Dateiname, 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> Pacing: <beat_cut|phrase_flow>
Schreibe nach: PROJECT_DIR/compositions/frames/<frame_id>.html
Der Worker forkt die zitierten Materialien, konvertiert jeden Anker in frame-lokale Sekunden (local_t = track_t − span_sec[0]), gated 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 montierten Projekt, das noch nicht existiert, also würden sie auf den falschen Dateien berichten. Der Worker schreibt nur nach Vertrag und stoppt; du überprüfst nach der Montage (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: Montieren
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, mountet assets/bgm.mp3 auf Spur 11 und schneidet hart Frame → Frame (Frames kacheln den Titel lückenlos, also gibt es keinen Transition-Injektor).
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 montiere neu.
Gate: index.html existiert; Gesamtdauer == audiomap.audio.duration_sec.
Schritt 6: Verifizieren und rendern
Ziel: Das montierte Video verifizieren, die Benutzerfreigabe einholen und das finale MP4 rendern.
Führe die CLI auf dem montierten Projekt aus – das ist die korrekte Einheit (die Frame-Worker 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 Schnappschüsse 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 Fehlern mache die günstigste sichere Reparatur selbst: Bearbeite die fehlerhafte compositions/frames/NN-*.html. Ändere niemals die Dauer oder das Audio-Timing, um ein Sync-Problem zu verbergen. Sobald die Gates bestanden sind, pausiere für die Benutzerüberprüfung, dann rendere 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 | Fahre fort ab |
|---|---|
Nur assets/bgm.mp3 | Schritt 1 |
audiomap.json | Schritt 2 |
STORYBOARD.md (Skelett) | Schritt 3 |
STORYBOARD.md (vollst.) | Schritt 4 |
| Alle Frame-Dateien | Schritt 5 |
index.html | Schritt 6 |
Kurzreferenz
Formate: Querformat 1920x1080 standardmäßig; Hochformat 1080x1920; Quadrat 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-Montage), stage-assets.mjs (Stage für Benutzermedien), lib/storyboard.mjs (eingekaufter Parser). Alles andere ist die hyperframes-CLI.
| Lese | Wann |
|---|---|
references/frame-skeleton.md | Schritt 2: Musik lesen, Frames anlegen, 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 bauen |
references/montage.md | Schritt 3: Vom Benutzer bereitgestellte Medien einweben |
../hyperframes-creative/references/design-spec.md | Schritt 3: Marken-Preset auswählen |
sub-agents/frame-worker.md | Schritt 4: Frame-Worker dispatchieren |
../hyperframes-core/references/subagent-dispatch.md | Schritt 4: Sub-Agent-Dispatch-Richtlinien |
../hyperframes-core/references/sub-compositions.md + determinism-rules.md | Schritt 4: Frame-Vertrag für Worker |