music-to-video – Ein auf Musik basierender, beatsynchronisierter Video-Workflow
Verwenden Sie diesen Skill, um einen Musiktitel in ein beatsynchronisiertes HyperFrames-Video zu verwandeln. Sie analysieren den Titel einmal, legen die Frames fest, füllen einen Frame-für-Frame-Plan und erstellen jeden Frame als Komposition. Die Eingabe ist ein Musiktitel plus optionale Benutzerbilder oder -videos – es gibt keine Erzählung und keinen Webseiten-Capture. Typografie und Vorlagen sind die Basis (ein vollständiges Video benötigt keine Assets); alle Medien, die der Benutzer bereitstellt, werden im gleichen Beat-Raster eingefügt.
Sie sind der Orchestrator. Arbeiten Sie in videos/<project>/. Führen Sie die Schritte der Reihe nach aus und passieren Sie jedes Gate, bevor Sie fortfahren. Zwei Schritte erfordern den Benutzer: Schritt 3 (Planfreigabe) und Schritt 6 (Renderfreigabe). Führen Sie jeden Schritt selbst aus, außer Schritt 4, bei dem Sie einen Sub-Agenten pro Frame einsetzen. Halten Sie 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/<project-name>/.
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ändiges STORYBOARD.md + frame.md; Schritt 4 Bau → compositions/frames/NN-*.html; Schritt 5 Montage → index.html; Schritt 6 Rendern → renders/video.mp4.
Zwei Ideen, die alles prägen
- Ein Analyzer, und Sie vertrauen ihm.
analyze-beatgrid.pyist der einzige Beat-Analyzer – messen Sie Beats nie mit einem anderen Tool oder nach Gehör neu. Seine Energie-/Dichte-/Rolls-/Onsets-/Silences-Werte 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. Orientieren Sie sich daher an Phrasen und Energie und schneiden Sie nie hart nach ihm. Die Entscheidung, in welchem Fall Sie sich befinden, 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 (jeweils eine Vorlage oder eine Motion-Primitives-Kombination). Zusätzliche Dichte geht innerhalb einer Gruppe, sodass die Frame-Anzahl unterschiedlichen Behandlungen folgt, nicht Beats – ein schneller Titel bläht die Anzahl der Sub-Agenten nicht auf.
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 Titel fest, bevor Sie etwas anderes tun. Dieser Skill ist für schnelle, energiegeladene BGM optimiert: Ein starkes Beat-Raster treibt die Schnitte (ruhige Titel funktionieren, aber das Tempo wird eher durch Phrasen als durch Beats bestimmt). Wenn der Benutzer Ihnen Audio gegeben hat – eine Musikdatei oder ein Video, aus dem Sie das Audio extrahieren sollen – 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öhliche Unternehmensmusik“) und erstellen Sie einen Titel über /hyperframes-media (references/bgm.md – HeyGen-Abruf, wenn berechtigt, 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 dessen Ausgabe wörtlich wieder (nicht paraphrasieren oder umschreiben) – sie zeigt an, ob BGM von HeyGen oder lokalem MusicGen stammt und, wenn nicht angemeldet, wie Sie sich anmelden können. Wenn nicht angemeldet, STOPPEN Sie und warten Sie, bis der Benutzer wählt – anmelden oder offline mit lokalem MusicGen fortfahren – bevor Sie den Titel 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. So oder so landet der Titel unter assets/bgm.mp3. Stagen Sie alle vom Benutzer bereitgestellten Bilder oder Videos, damit Frames sie im Beat-Raster einweben können; andernfalls trägt die Typografie das gesamte Video.
Initialisieren Sie nur, wenn hyperframes.json fehlt. Benennen Sie <project> aus dem Briefing in Kebab-Schreibweise, z. B. midnight-drive-loop – niemals einen Zeitstempel. init überprüft die installierten Skills auf dem neuesten Stand gegenüber GitHub und aktualisiert den globalen Satz, wenn einer veraltet 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" # ggf. zuerst aus einem Video extrahieren
# nur wenn der Benutzer Ihnen 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ählen Sie nicht im Voraus ein Genre oder einen Titeltyp – Assets sind nur eine optionale Zutat, und das Genre ergibt sich aus den Entscheidungen für jeden Frame.
Gate: hyperframes.json + assets/bgm.mp3 existieren; Seitenverhältnis / Länge / fps und (falls vorhanden) der Asset-Bestand sind notiert.
Schritt 1: Die Musik analysieren
Ziel: Die eine kanonische Zeitanalyse erstellen, auf der das gesamte Video aufbaut.
analyze-beatgrid.py ist der einzige Beat-Analyzer – messen Sie 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 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 diese in die aktive Python-Umgebung, bevor Sie den Analyzer 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 anlegen – das Skelett von STORYBOARD.md.
Lesen Sie references/frame-skeleton.md. Erstellen Sie selbst aus audiomap.json das Skelett von STORYBOARD.md – es gibt kein Zwischen-JSON. Schneiden Sie den Titel an echten musikalischen Änderungen (hard_stops, SURGE/DROP key_moments, die Kanten eines Rolls, ein Abschnitt ohne Onsets, ein großer Energiesprung) in Frames und rasten Sie jeden Rand an einem Audiomap-Anker ein. Für jeden Frame setzen Sie span_sec, pacing (das Urteil aus Schritt 1s Vertrauensaufruf – beat_cut, wenn das Raster echt ist, phrase_flow, wenn es ein Metronom ist, das ruhiger Musik aufgezwungen wurde), mood und ein einzeiliges feel (die einfache Musiksituation, gegen die Schritt 3 eine Vorlage matched). Klassifizieren und legen Sie hier nur an: Lassen Sie die ### Gruppen jedes Frames als TBD (Schritt 3) und das Frontmatter style leer – keine Vorlagen, Texte, Farben oder Schriftarten. Erwarten Sie ~1–6 Frames.
Gate: Frames kacheln den Titel (erster bei 0, letzter bei duration_s); jeder trägt span_sec + pacing + mood + feel; jede ### Gruppen ist TBD; kein Inhalt irgendwo.
Schritt 3: Den Plan füllen (benutzergesteuert)
Ziel: Das Skelett in ein genehmigtes, vollständiges STORYBOARD.md verwandeln.
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 tun Sie zwei Dinge:
- Wählen Sie die Marke. Wählen Sie ein Preset aus
../hyperframes-creative/frame-presets/mithilfe der Tabelle in../hyperframes-creative/references/design-spec.md(passend zur Stimmung des Titels; nur die Schriftarten und Farben sind wichtig – Vorlagen besitzen die Komposition). Kopieren Sie es unverändert inframe.mdund füllen Sie das Frontmatterstyle(Schriftart + eine ≤4–6 Swatch-Palette) daraus. - Füllen Sie jeden Frame. Entscheiden Sie 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 Primitiv-Katalog oder eine Asset-Behandlung, die
pacinggehorcht. Schreiben Sie den Text. Sie besitzen WAS (Vorlage / Primitive + 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: Dauerabweichung, Frames kacheln den Titel nicht, fehlende src); Warnungen sind nach bestem Wissen und Gewissen zu behandeln. Zeigen Sie dem Benutzer dann eine Frame-für-Frame-Zusammenfassung und iterieren Sie, bis dieser sie genehmigt.
Gate: frame.md ist eine wörtliche Preset-Kopie; 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 bauen.
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, 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
Ihr Block: der Abschnitt `## 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); gestagte assets/ (Asset-Gruppen)
Verträge: ../hyperframes-core/references/sub-compositions.md + determinism-rules.md
Leinwand: <w>×<h> Taktung: <beat_cut|phrase_flow>
Schreiben 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]), fügt seine Gruppen mit 0ms-Schnitten ein 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 die falschen Dateien berichten. Der Worker schreibt nur gemäß Vertrag und stoppt; Sie verifizieren nach der Montage (Schritt 6). Wenn jeder Worker zurückkommt, können Sie bestätigen, dass seine Datei auf der Festplatte gelandet ist.
Gate: Jeder Frame hat seine compositions/frames/NN-*.html auf der Festplatte.
Schritt 5: Montage
Ziel: Die gebauten 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, mountet assets/bgm.mp3 auf Spur 11 und schneidet hart Frame → Frame (Frames kacheln den Titel lückenlos, also gibt es keinen Übergang-Injektor).
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--hyperframes "$PROJECT_DIR" --audiomap "$PROJECT_DIR/audiomap.json"
Beheben Sie jedes ✗, das es meldet – eine fehlende oder leere Frame-Datei bedeutet, dass dieser Worker eine Teil-Datei geschrieben hat; setzen Sie ihn erneut ein (Schritt 4) und montieren Sie neu.
Gate: index.html existiert; Gesamtdauer == audiomap.audio.duration_sec.
Schritt 6: Verifizieren und rendern
Ziel: Das montierte Video verifizieren, Benutzerfreigabe einholen und das endgültige MP4 rendern.
Führen Sie 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), inspect erstellt Schnappschüsse der Frames.
( cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes validate . && npx hyperframes inspect . )
Inspizieren Sie bei t=0, jedem Frame-Start, dem stärksten DROP / SURGE, jedem hard_stops[].t und dem letzten Frame. Bei Fehlern führen Sie die günstigste sichere Reparatur selbst durch: Bearbeiten Sie die betreffende compositions/frames/NN-*.html. Ändern Sie niemals Dauer oder Audio-Timing, um ein Sync-Problem zu verbergen. Sobald die Gates bestanden sind, pausieren Sie für die Benutzerüberprüfung und rendern Sie 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 | Fahren Sie fort 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. Setzen Sie die Leinwand einmal im Storyboard-Frontmatter (canvas: { w, h, fps }).
Skripte unter scripts/: analyze-beatgrid.py (der eine Analyzer), validate-plan.mjs (Planprüfung), assemble-index.mjs (Index-Montage), stage-assets.mjs (Benutzermedien stagen), lib/storyboard.mjs (gekapselter Parser). Alles andere ist die hyperframes-CLI.
| Lesen | Wann |
|---|---|
references/frame-skeleton.md | Schritt 2: die Musik lesen, Frames anlegen, Taktung setzen |
references/planning.md · storyboard-format.md | Schritt 3: Marke wählen, jeden Frame füllen, Plan schreiben |
references/template-catalog.md | Schritt 3: pro Gruppe eine Vorlage wählen |
references/motion-primitive-catalog.md | Schritt 3: freie Motion-Primitives pro Gruppe |
references/montage.md | Schritt 3: Benutzer-Assets in den Plan einweben |
sub-agents/frame-worker.md | Schritt 4: Frame-Worker dispatchieren |
references/sub-compositions.md · determinism-rules.md | Schritt 4: Verträge für Frame-Dateien |