music-to-video – Ein Arbeitsablauf für ein musikgestütztes, beat-synchronisiertes Video
Verwenden Sie diese Fertigkeit, um einen Musiktitel in ein beat-synchronisiertes HyperFrames-Video zu verwandeln. Sie analysieren den Titel einmal, legen die Frames fest, füllen einen Pro-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 Website-Screenshot. Typografie und Vorlagen sind die Grundlage (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 (Planungsgenehmigung) und Schritt 6 (Render-Genehmigung). Führen Sie jeden Schritt selbst aus, außer Schritt 4, wo Sie einen Sub-Agenten pro Frame einsetzen. Halten Sie Design- und Bewegungsregeln aus dieser Datei heraus – sie befinden sich in references/ und dem frame-worker-Sub-Agenten.
SKILL_DIR = dieses Fertigkeitsverzeichnis. PROJECT_DIR = videos/<projektname>/.
Arbeitsablauf: Schritt 0 Einrichtung → hyperframes.json + assets/bgm.mp3; Schritt 1 Analyse → audiomap.json; Schritt 2 Grundgerüst → STORYBOARD.md (Frames, Gruppen TBD); Schritt 3 Plan → vollständige STORYBOARD.md + frame.md; Schritt 4 Bau → compositions/frames/NN-*.html; Schritt 5 Zusammenbau → index.html; Schritt 6 Rendern → renders/video.mp4.
Zwei Ideen, die alles bestimmen
- Ein Analyse-Tool, und Sie vertrauen ihm.
analyze-beatgrid.pyist der einzige Beat-Analysator – messen Sie Beats niemals mit einem anderen Tool oder nach Gehör neu. Seine Energie-/Dichte-/Rolls-/Onsets-/Stille-Werte sind immer zuverlässig. Seinebpmundbeats_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 stattdessen an Phrasen und Energie und schneiden Sie nie hart darauf. Die Entscheidung, welcher Fall vorliegt, wird in jedem Frame durch daspacing(Schritt 2) getroffen. - 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 Kombination aus Bewegungs-Primitiven). Zusätzliche Dichte geht innerhalb einer Gruppe, sodass die Frame-Anzahl unterschiedliche Behandlungen zählt, nicht Beats – ein schneller Titel erhöht nicht die Anzahl der Sub-Agenten.
Schritt 0: Einrichtung, Hintergrundmusik 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. Diese Fertigkeit ist optimiert für schnelle, energiegeladene Hintergrundmusik: Ein starkes Beat-Raster treibt die Schnitte an (ruhige Titel funktionieren auch, aber richten Sie sich eher nach Phrasen als nach dem Beat). 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öhlich Corporate“) und erstellen Sie einen Titel über /hyperframes-media (references/bgm.md – HeyGen Retrieval, wenn berechtigt, sonst lokales Lyria / MusicGen; ElevenLabs oder ein anderer Generator funktioniert auch). Führen Sie vor der Generierung npx hyperframes auth status aus und geben Sie dessen Ausgabe wörtlich wieder (nicht umschreiben oder neu formulieren) – sie zeigt, ob die Hintergrundmusik 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 Titel generieren; schreiben Sie keine Schlüssel in ein Repo-spezifisches .env. (Im autonomen Modus notieren Sie den Status und fahren offline fort.) Siehe /hyperframes-media → Preflight für die kanonische Anleitung. In beiden Fällen landet der Titel unter assets/bgm.mp3. Stagen Sie 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.
Initialisieren Sie nur, wenn hyperframes.json fehlt. Benennen Sie <projekt> aus der Aufgabenstellung im Kebab-Case, z. B. midnight-drive-loop – niemals einen Zeitstempel. init überprüft die installierten Fertigkeiten auf dem neuesten Stand von 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 "<benutzermusik>" "$PROJECT_DIR/assets/bgm.mp3" # bei Bedarf zuerst aus einem Video extrahieren
# nur wenn der Benutzer Bilder/Videos bereitgestellt 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ählen Sie 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: 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 niemals 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 sie in die aktive 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-Grundgerüst (nur Struktur)
Ziel: Lesen Sie die Musik und legen Sie die Frames fest – das Grundgerüst von STORYBOARD.md.
Lesen Sie references/frame-skeleton.md. Wandeln Sie audiomap.json selbst in das Grundgerüst von STORYBOARD.md um – es gibt kein Zwischen-JSON. Schneiden Sie den Titel in Frames an echten musikalischen Veränderungen (hard_stops, SURGE / DROP key_moments, die Ränder eines Rolls, ein Abschnitt ohne Onsets, ein großer Energiesprung) 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 ein aufgezwungenes Metronom auf ruhiger Musik ist), mood und ein einzeiliges feel (die einfache Musiksituation, die Schritt 3 mit einer Vorlage abgleicht). Hier nur klassifizieren und anordnen: Lassen Sie jedes ### Gruppen des Frames als TBD (Schritt 3) und das Frontmatter style leer – keine Vorlagen, Texte, Farben oder Schriftarten. Erwarten Sie ~1–6 Frames.
Gate: Frames decken den Titel ab (erster bei 0, letzter bei duration_s); jeder trägt span_sec + pacing + mood + feel; jedes ### Gruppen ist TBD; keinerlei Inhalt vorhanden.
Schritt 3: Plan ausfüllen (benutzergesteuert)
Ziel: Das Grundgerüst in eine genehmigte, vollständige 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/mit der Tabelle in../hyperframes-creative/references/design-spec.md(passen Sie die Stimmung des Titels an; nur seine Schriftarten und Farben sind wichtig – Vorlagen besitzen die Komposition). Kopieren Sie es unverändert inframe.mdund füllen Sie das Frontmatterstyle(Schriftart + eine Palette mit ≤4–6 Farbwerten) 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: Dauer-Diskrepanz, Frames decken den Titel nicht ab, fehlendes src); Warnungen sind nach bestem Wissen und Gewissen zu beheben. Zeigen Sie dem Benutzer dann eine framebasierte Zusammenfassung und iterieren Sie, bis er zustimmt.
Gate: frame.md ist eine wörtliche Preset-Kopie; validate-plan.mjs gibt 0 aus; 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, 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
Ihr 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); gestagte 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 forkt die zitierten Materialien, konvertiert jeden Anker in frame-lokale Sekunden (local_t = track_t − span_sec[0]), gliedert 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 zusammengebauten Projekt, das noch nicht existiert, und würden daher die falschen Dateien melden. Der Worker schreibt nur in 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 liegt.
Gate: Jeder Frame hat seine compositions/frames/NN-*.html auf der Festplatte.
Schritt 5: Zusammenbau
Ziel: Die gebauten Frames + Hintergrundmusik in die abspielbare index.html einbinden.
assemble-index.mjs ist deterministisch – kein Subagent, keine Beurteilung. Es referenziert jede Frame-Datei bei ihrem kumulativen data-start, mountet assets/bgm.mp3 auf Track 11 und macht harte Schnitte von Frame zu Frame (Frames decken den Titel lückenlos ab, daher gibt es keinen Transition Injector).
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--hyperframes "$PROJECT_DIR" --audiomap "$PROJECT_DIR/audiomap.json"
Beheben Sie jedes ✗, das gemeldet wird – eine fehlende oder leere Frame-Datei bedeutet, dass der Worker eine unvollständige Datei geschrieben hat; setzen Sie ihn erneut ein (Schritt 4) und bauen Sie erneut zusammen.
Gate: index.html existiert; Gesamtdauer == audiomap.audio.duration_sec.
Schritt 6: Überprüfen und rendern
Ziel: Das zusammengebaute Video überprüfen, die Benutzerzustimmung einholen und das endgültige MP4 rendern.
Führen Sie die CLI auf dem zusammengebauten Projekt aus – das ist die korrekte Einheit (die Frame-Worker konnten sie nicht ausführen). lint überprüft die Struktur, validate führt Headless Chrome aus (fängt JS-Fehler und fehlende Assets ab), inspect macht 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 Fehlern machen Sie die günstigste sichere Reparatur selbst: Bearbeiten Sie die fehlerhafte compositions/frames/NN-*.html. Ändern Sie niemals die Dauer oder das Audio-Timing, um ein Sync-Problem zu verbergen. Sobald die Gates passiert sind, pausieren Sie für die Benutzerüberprüfung, dann 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 | Fortsetzen ab |
|---|---|
nur assets/bgm.mp3 | Schritt 1 |
audiomap.json | Schritt 2 |
STORYBOARD.md (Grundgerüst) | 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; Quadratisch 1080x1080. Setzen Sie 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 (Indexzusammenbau), stage-assets.mjs (Benutzermedien stagen), lib/storyboard.mjs (integrierter 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 für eine Gruppe |
references/montage.md | Schritt 3 (nur bei Benutzer-Assets): Montage-Struktur |
sub-agents/frame-worker.md | Schritt 4: Regeln zum Erstellen jeder Frame-Datei |