music-to-video – Ein musikbasierter, beat-synchronisierter Video-Workflow
Verwenden Sie diesen Skill, um einen Musiktitel in ein beat-synchronisiertes HyperFrames-Video zu verwandeln. Sie analysieren den Track einmalig, legen die Frames fest, füllen einen Plan pro Frame und bauen jeden Frame als Komposition. 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 keine Assets); alle vom Benutzer bereitgestellten Medien werden auf demselben Beat-Raster eingefügt.
Sie sind der Orchestrator. Arbeiten Sie in videos/<projekt>/. Führen Sie die Schritte der Reihe nach aus und passieren Sie jedes Gate, bevor Sie fortfahren. Zwei Schritte benötigen den Benutzer: Schritt 3 (Planfreigabe) und Schritt 6 (Render-Freigabe). Führen Sie alle Schritte selbst aus, außer Schritt 4, bei dem Sie einen Sub-Agenten pro Frame einsetzen. Bewahren Sie Design- und Bewegungsregeln außerhalb dieser Datei auf – sie leben in references/ und dem Sub-Agenten frame-worker.
SKILL_DIR = dieses Skill-Verzeichnis. PROJECT_DIR = videos/<projektname>/.
Workflow: Schritt 0 Einrichtung → 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 Build → compositions/frames/NN-*.html; Schritt 5 Zusammenbau → index.html; Schritt 6 Render → renders/video.mp4.
Zwei Ideen, die alles prägen
- Ein Analysator, und Sie vertrauen ihm.
analyze-beatgrid.pyist der einzige Beat-Analysator – messen Sie Beats nie mit einem anderen Tool oder nach Gehör neu. Seine Energie / Dichte / Rolls / Onsets / Stille sind immer zuverlässig. Seinbpmundbeats_secsind nur zuverlässig, wenn die Musik wirklich rhythmisch ist; bei ruhiger Musik ist das Raster ein Metronom, das der Tracker aufgezwungen hat. Richten Sie sich also stattdessen nach Phrasen und Energie und schneiden Sie nie hart danach. Die Entscheidung, in welchem Fall Sie sich befinden, ist daspacingjedes Frames (Schritt 2). - Ein Frame = eine Datei; Gruppen leben darin. Schritt 2 zerlegt den Track 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 (jeweils eine Vorlage oder eine Kombination von Bewegungsprimitiven). Zusätzliche Dichte geht innerhalb einer Gruppe, sodass die Frame-Anzahl unterschiedliche Behandlungen verfolgt, nicht Beats – ein schneller Track erhöht nicht die Anzahl der Sub-Agenten.
Schritt 0: Einrichtung, BGM und Eingaben
Ziel: Die Musikquelle festlegen, das HyperFrames-Projekt erstellen und alle vom Benutzer bereitgestellten Medien notieren.
Die Musik ist das Rückgrat – legen Sie einen Track fest, bevor Sie irgendetwas anderes tun. Dieser Skill ist für schnelles, energiegeladenes BGM optimiert: Ein starkes Beat-Raster treibt die Schnitte an (ruhige Tracks funktionieren auch, aber das Tempo richtet sich eher nach der Phrase als nach dem Beat). Wenn der Benutzer Ihnen Audio gegeben hat – eine Musikdatei oder ein Video, aus dem Audio extrahiert werden soll – verwenden Sie es. Wenn nicht, generieren Sie eines: Wählen Sie die Stimmung aus der Beschreibung des Benutzers (z. B. "treibender Synthwave", "Trap-Beat", "fröhliches Corporate") und erstellen Sie einen Track über /hyperframes-media (references/bgm.md – HeyGen-Abruf, wenn Anmeldeinformationen vorhanden sind, sonst lokales Lyria / MusicGen; ElevenLabs oder ein anderer Generator funktioniert auch). Führen Sie vor dem Generieren npx hyperframes auth status aus und geben Sie seine Ausgabe wörtlich wieder (paraphrasieren oder umschreiben Sie sie nicht) – sie zeigt an, ob BGM von HeyGen oder lokalem MusicGen stammt und, falls nicht angemeldet, wie man sich anmeldet. Wenn nicht angemeldet, STOPPEN Sie und warten Sie auf die Entscheidung des Benutzers – anmelden oder offline mit lokalem MusicGen fortfahren – bevor Sie den Track generieren; schreiben Sie keine Schlüssel in ein pro-Repo .env. (Im autonomen Modus notieren Sie den Status und fahren offline fort.) Siehe /hyperframes-media → Preflight für die kanonische Anleitung. In jedem Fall landet der Track unter assets/bgm.mp3. Stufen Sie alle vom Benutzer bereitgestellten Bilder oder Videos bereit, damit Frames sie auf dem Beat-Raster einweben können; andernfalls trägt die Typografie das gesamte Video.
Initialisieren Sie nur, wenn hyperframes.json fehlt. Benennen Sie <projekt> aus dem Briefing in Kebab-Schreibweise, z. B. midnight-drive-loop – niemals ein Zeitstempel. init überprüft die installierten Skills gegen die neuesten auf GitHub und aktualisiert den globalen Satz, wenn einer veraltet ist.
npx hyperframes init "videos/<projekt>" --non-interactive --example=blank
mkdir -p "$PROJECT_DIR/assets" "$PROJECT_DIR/renders"
cp "<benutzermusik>" "$PROJECT_DIR/assets/bgm.mp3" # ggf. zuerst aus einem Video extrahieren
# nur wenn der Benutzer Bilder/Videos bereitgestellt hat:
node <SKILL_DIR>/scripts/stage-assets.mjs --from <verzeichnis> --hyperframes "$PROJECT_DIR" --into public
Die Marke (Schriftart + Palette) wird in Schritt 3 ausgewählt, nicht hier. Wählen Sie nicht vorab ein Genre oder einen Track-Typ – 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 aufbaut.
analyze-beatgrid.py ist der einzige Beat-Analysator – messen Sie 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 Sie in Schritt 2 treffen.
Voraussetzungen: Python 3 mit librosa, numpy und soundfile. Wenn der Import fehlschlägt, installieren Sie sie in der aktiven Python-Umgebung, bevor Sie den Analysator ausführen:
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 anordnen – das Skelett von STORYBOARD.md.
Lesen Sie references/frame-skeleton.md. Wandeln Sie audiomap.json selbst in das Skelett von STORYBOARD.md um – es gibt kein dazwischenliegendes JSON. Zerlegen Sie den Track bei tatsächlichen musikalischen Änderungen (hard_stops, SURGE / DROP key_moments, die Ränder eines Rolls, ein Abschnitt ohne Onsets, ein großer Energiesprung) in Frames und rasten Sie jede Grenze an einem Audiomap-Anker ein. Setzen Sie für jeden Frame span_sec, pacing (das Urteil aus Schritt 1 über das Vertrauen – beat_cut, wenn das Raster echt ist, phrase_flow, wenn es sich um ein Metronom handelt, das ruhiger Musik aufgezwungen wurde), mood und ein einzeiliges feel (die reine Musiksituation, die Schritt 3 mit einer Vorlage abgleicht). Nur klassifizieren und anordnen: Lassen Sie jedes ### Gruppen des Frames als TBD (Schritt 3) und das Frontmatter style leer – keine Vorlagen, kein Text, keine Farbe, keine Schriftarten. Erwarten Sie ~1–6 Frames.
Gate: Frames kacheln den Track (erster bei 0, letzter bei duration_s); jeder trägt span_sec + pacing + mood + feel; jedes ### Gruppen ist TBD; kein Inhalt irgendwo.
Schritt 3: Plan ausfüllen (benutzergesteuert)
Ziel: Das Skelett in eine genehmigte, vollständige STORYBOARD.md umwandeln.
Lesen Sie references/planning.md, storyboard-format.md, template-catalog.md, motion-primitive-catalog.md und montage.md (nur wenn der Benutzer Assets bereitgestellt hat). Bearbeiten Sie dieselbe Datei direkt und erledigen Sie zwei Dinge:
- Marke auswählen. Wählen Sie ein Voreinstellung aus
../hyperframes-creative/frame-presets/mithilfe der Tabelle in../hyperframes-creative/references/design-spec.md(passen Sie die Stimmung des Tracks an; nur seine Schriftarten und Farben sind wichtig – Vorlagen besitzen die Komposition). Kopieren Sie sie unverändert inframe.mdund füllen Sie das Frontmatterstyle(Schriftart + eine Palette mit ≤4–6 Farbtönen) daraus aus. - Jeden Frame füllen. Entscheiden Sie sich für seine Gruppen und geben Sie jeder eine Behandlung: eine passende Vorlage aus dem Katalog (mit gebundenen Parametern und echten Audiomap-Ankern), eine freie Komposition aus dem Primitive-Katalog oder eine Asset-Behandlung, die
pacingbefolgt. Schreiben Sie den Text. Sie besitzen WAS (Vorlage / Primitives + Inhalt + Anker); der frame-worker besitzt WIE – schreiben Sie 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
Beheben Sie jedes ✗ (harte Fehler: Dauerinkonsistenz, Frames, die den Track nicht kacheln, fehlendes src); Warnungen sind nach bestem Wissen und Gewissen. Zeigen Sie dem Benutzer dann eine Frame-für-Frame-Zusammenfassung und iterieren Sie, bis er sie genehmigt.
Gate: frame.md ist eine wörtliche Kopie der Voreinstellung; validate-plan.mjs beendet mit 0; der Benutzer hat den Plan genehmigt.
Schritt 4: Frames aus dem Plan bauen
Ziel: Jeden Frame als eigenständige Kompositionsdatei erstellen.
Erstellen Sie compositions/frames/. Lesen Sie sub-agents/frame-worker.md und ../hyperframes-core/references/subagent-dispatch.md. Setzen Sie 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 ohne Erweiterung, z. B. 02-f2; die Kompositions-ID
Ihr 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>
Schreiben nach: PROJECT_DIR/compositions/frames/<frame_id>.html
Der Worker verzweigt die zitierten Materialien, wandelt jeden Anker in framespezifische Sekunden um (lokal_t = track_t − span_sec[0]), gated seine Gruppen mit 0ms-Schnitten und schreibt eine suchsichere Frame-Datei. Der Worker führt niemals das hyperframes CLI aus – diese Befehle arbeiten am zusammengebauten Projekt, das noch nicht existiert, sodass sie über die falschen Dateien berichten würden. Der Worker schreibt nur an den Vertrag und stoppt; Sie überprüfen nach dem Zusammenbau (Schritt 6). Wenn jeder Worker zurückkommt, können Sie bestätigen, dass seine Datei auf der Festplatte gelandet ist.
Gate: Jeder Frame hat sein 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, kein Urteil. Es referenziert jede Frame-Datei bei ihrer kumulativen data-start, mountet assets/bgm.mp3 auf Spur 11 und schneidet hart von Frame zu Frame (Frames kacheln den Track lückenlos, daher gibt es keinen Übergangsinjektor).
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--hyperframes "$PROJECT_DIR" --audiomap "$PROJECT_DIR/audiomap.json"
Beheben Sie alle ✗, die es meldet – eine fehlende oder leere Frame-Datei bedeutet, dass dieser Worker eine unvollständige Datei geschrieben hat; setzen Sie ihn erneut ein (Schritt 4) und bauen Sie neu zusammen.
Gate: index.html existiert; Gesamtdauer == audiomap.audio.duration_sec.
Schritt 6: Überprüfen und rendern
Ziel: Das zusammengebaute Video überprüfen, die Zustimmung des Benutzers einholen und das endgültige MP4 rendern.
Führen Sie das CLI am zusammengebauten Projekt aus – das ist die korrekte Einheit (die Arbeiter pro Frame konnten es nicht ausführen). lint prüft die Struktur, validate führt headless Chrome aus (fängt JS-Fehler und fehlende Assets), inspect erstellt Schnappschüsse von Frames.
( cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes validate . && npx hyperframes inspect . )
Überprüfen Sie bei t=0, jedem Frame-Start, dem stärksten DROP / SURGE, jedem hard_stops[].t und dem letzten Frame. Bei einem Fehler führen Sie die günstigste sichere Reparatur selbst durch: Bearbeiten Sie die betreffende compositions/frames/NN-*.html. Ändern Sie niemals die Dauer oder das Audio-Timing, um ein Sync-Problem zu verbergen. Nachdem die Gates bestanden sind, pausieren Sie für die Benutzerüberprüfung und rendern Sie dann nur nach Genehmigung:
( 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 genehmigt; renders/video.mp4 existiert mit Audio, Dauer == audiomap.audio.duration_sec. Die endgültige Antwort gibt den MP4-Pfad und die Dauer an.
Fortsetzungstabelle
| Sie haben | Fortsetzen ab |
|---|---|
nur assets/bgm.mp3 | Schritt 1 |
audiomap.json | Schritt 2 |
STORYBOARD.md (Skelett) | Schritt 3 |
STORYBOARD.md (vollständig) | Schritt 4 |
| alle Frame-Dateien | Schritt 5 |
index.html | Schritt 6 |
Kurzreferenz
Formate: Querformat 1920x1080 standardmäßig; Hochformat 1080x1920; Quadrat 1080x1080. Legen Sie die Leinwand einmal im Storyboard-Frontmatter fest (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 (verkaufter Parser). Alles andere ist das hyperframes CLI.
| Lesen | Wann |
|---|---|
references/frame-skeleton.md | Schritt 2: Musik lesen, Frames anordnen, Pacing festlegen |
references/planning.md · storyboard-format.md | Schritt 3: Marke auswählen, jeden Frame füllen, Plan schreiben |
references/template-catalog.md | Schritt 3: Vorlage pro Gruppe auswählen |
references/motion-primitive-catalog.md | Schritt 3: Frei komponieren / Primitiven mischen |
references/montage.md | Schritt 3: Asset-Gruppen einfügen (falls der Benutzer Assets bereitgestellt hat) |
sub-agents/frame-worker.md | Schritt 4: Wie ein frame-worker seinen einen Frame baut |
../hyperframes-core/references/sub-compositions.md | Schritt 4: Vertrag zwischen Orchestrator und frame-worker |
../hyperframes-core/references/subagent-dispatch.md | Schritt 4: Wie der Orchestrator frame-worker aufruft |
../hyperframes-creative/references/design-spec.md | Schritt 3: Voreinstellungstabelle für Marken |