Musik-zu-Video – Ein auf Musik basierender, beat-synchronisierter Video-Workflow
Nutzen Sie diese Fähigkeit, um einen Musiktitel in ein beat-synchronisiertes HyperFrames-Video zu verwandeln. Sie analysieren den Track einmal, legen die Frames fest, füllen einen Frame-für-Frame-Plan und bauen 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 die Basis (ein komplettes Video benötigt keine Assets); alle vom Benutzer bereitgestellten Medien werden auf demselben Beat-Raster zugeschnitten.
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 (Renderfreigabe). Führen Sie jeden Schritt selbst aus, außer Schritt 4, wo Sie einen Sub-Agenten pro Frame einsetzen. Halten Sie Design- und Bewegungsregeln außerhalb dieser Datei – sie leben in references/ und dem frame-worker Sub-Agenten.
SKILL_DIR = dieses Skill-Verzeichnis. PROJECT_DIR = videos/<projektname>/.
Workflow: Schritt 0 Setup → hyperframes.json + assets/bgm.mp3; Schritt 1 Analyse → audiomap.json; Schritt 2 Skeleton → STORYBOARD.md (Frames, Gruppen TBD); Schritt 3 Plan → vollständige STORYBOARD.md + frame.md; Schritt 4 Build → compositions/frames/NN-*.html; Schritt 5 Assemble → index.html; Schritt 6 Render → renders/video.mp4.
Zwei Ideen, die alles prägen
- Ein Analyzer, und man vertraut ihm.
analyze-beatgrid.pyist der einzige Beat-Analyzer – messen Sie Beats nie mit einem anderen Tool oder nach Gehör nach. Seine Energie-/Dichte-/Rolls-/Onsets-/Silences-Werte sind immer zuverlässig. Seinebpmundbeats_secsind nur dann zuverlässig, wenn die Musik wirklich rhythmisch ist; bei ruhiger Musik ist das Raster ein Metronom, das der Tracker aufgezwungen hat. Richten Sie sich stattdessen nach Phrasen und Energie und schneiden Sie nie hart darauf. Die Entscheidung, in welchem Fall Sie sich befinden, ist daspacingjedes Frames (Schritt 2). - Ein Frame = eine Datei; Gruppen leben darin. Schritt 2 schneidet 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: Setup, Hintergrundmusik und Eingaben
Ziel: Musikkquelle etablieren, das HyperFrames-Projekt erstellen und alle vom Benutzer bereitgestellten Medien notieren.
Die Musik ist das Rückgrat – stellen Sie einen Track fest, bevor Sie etwas anderes tun. Diese Fähigkeit ist optimiert für schnelle, energiegeladene Hintergrundmusik: Ein starkes Beat-Raster treibt die Schnitte an (ruhige Tracks funktionieren auch, aber takten Sie nach Phrasen statt nach Beats). Wenn der Benutzer Ihnen Audio gegeben hat – eine Musikdatei oder ein Video, aus dem Sie das Audio extrahieren – verwenden Sie es. Wenn nicht, generieren Sie eines: Wählen Sie die Stimmung aus der Beschreibung des Benutzers (z. B. „treibender Synthwave“, „Trap-Beat“, „aufgewecktes Corporate“) und produzieren Sie einen Track über /hyperframes-media (references/bgm.md – HeyGen-Abruf bei Anmeldung, 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) – es zeigt an, ob die Hintergrundmusik von HeyGen oder lokalem MusicGen stammt und, falls nicht angemeldet, wie man sich anmeldet. Wenn nicht angemeldet, STOPPEN und warten Sie, bis der Benutzer wählt – anmelden oder offline mit lokalem MusicGen fortfahren – bevor Sie den Track generieren; schreiben Sie keine Schlüssel in eine 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 Track 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 dem Briefing in Kebab-Schreibweise, z. B. midnight-drive-loop – niemals ein Zeitstempel. init prüft die installierten Skills gegen die neuesten auf GitHub und aktualisiert das globale Set, 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 Ihnen Bilder/Videos gegeben 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 aus – Assets sind nur eine optionale Zutat, und das Genre ergibt sich aus den Frame-Entscheidungen.
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 Timing-Analyse erstellen, auf der das gesamte Video basiert.
analyze-beatgrid.py ist der einzige Beat-Analyzer – messen Sie Beats nie mit einem anderen Tool oder nach Gehör nach. 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 das 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 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-Skeleton (nur Struktur)
Ziel: Die Musik lesen und die Frames anlegen – das Skeleton von STORYBOARD.md.
Lesen Sie references/frame-skeleton.md. Wandeln Sie audiomap.json selbst in das Skeleton von STORYBOARD.md um – es gibt kein Zwischen-JSON. Schneiden Sie den Track in Frames an echten musikalischen Änderungen (hard_stops, SURGE / DROP key_moments, die Ränder eines Rolls, ein Abschnitt ohne Onsets, ein großer Energiesprung), wobei jede Grenze an einem Audiomap-Anker einrastet. Setzen Sie für jeden Frame span_sec, pacing (das Urteil aus Schritt 1 – beat_cut, wenn das Raster echt ist, phrase_flow, wenn es ein auf ruhige Musik aufgezwungenes Metronom ist), stimmung und eine einzeilige feel (die reine Musiksituation, die Schritt 3 mit einer Vorlage abgleicht). Nur klassifizieren und anlegen: Lassen Sie für jeden Frame ### Gruppen als TBD (Schritt 3) und das Frontmatter Style leer – keine Vorlagen, Texte, Farben oder Schriftarten. Erwarten Sie ~1–6 Frames.
Gate: Frames decken den Track ab (erster bei 0, letzter bei duration_s); jeder hat span_sec + pacing + stimmung + feel; jedes ### Gruppen ist TBD; kein Inhalt irgendwo.
Schritt 3: Plan füllen (benutzergesteuert)
Ziel: Das Skeleton 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/anhand 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 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 Primitivkatalog oder eine Asset-Behandlung, die
pacingbefolgt. Schreiben Sie den Text. Sie besitzen WAS (Vorlage / Primitiven + 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 decken den Track nicht ab, 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 zustimmt.
Gate: frame.md ist eine wörtliche Preset-Kopie; validate-plan.mjs endet 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, 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 `## 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> Taktung: <beat_cut|phrase_flow>
Schreiben nach: PROJECT_DIR/compositions/frames/<frame_id>.html
Der Worker fork die zitierten Materialien, wandelt jeden Anker in framelokale Sekunden um (local_t = track_t − span_sec[0]), grenzt seine Gruppen mit 0ms-Schnitten ab und schreibt eine suchsichere Frame-Datei. Der Worker führt niemals die hyperframes CLI aus – diese Befehle operieren auf dem assemblierten Projekt, das noch nicht existiert, also würden sie über die falschen Dateien berichten. Der Worker schreibt nur gemäß Vertrag und stoppt; Sie überprüfen 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 sein compositions/frames/NN-*.html auf der Festplatte.
Schritt 5: Montieren
Ziel: Die gebauten Frames + Hintergrundmusik in die abspielbare index.html verdrahten.
assemble-index.mjs ist deterministisch – kein Sub-Agent, keine Beurteilung. Es referenziert jede Frame-Datei an ihrer kumulativen data-start, mountet assets/bgm.mp3 auf Track 11 und schneidet hart Frame → Frame (Frames decken den Track lückenlos ab, 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 gemeldeten ✗ – eine fehlende oder leere Frame-Datei bedeutet, dass der Worker eine partielle 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 finale MP4 rendern.
Führen Sie die CLI auf dem montierten Projekt aus – das ist die korrekte Einheit (die Per-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 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, der stärksten DROP / SURGE, jedem hard_stops[].t und dem letzten Frame. Beheben Sie bei Fehlern selbst den günstigsten sicheren Fix: Bearbeiten Sie das betreffende compositions/frames/NN-*.html. Ändern Sie niemals die Dauer oder das Audio-Timing, um ein Sync-Problem zu verstecken. Wenn die Gates bestanden sind, pausieren Sie für die Benutzerüberprüfung, dann rendern Sie nur nach Freigabe:
( cd "$PROJECT_DIR" && npx hyperframes render . --skill=musik-zu-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 finale Antwort gibt den MP4-Pfad und die Dauer an.
| Fortsetzungstabelle | |
|---|---|
| Sie haben | Weiter bei |
assets/bgm.mp3 nur | Schritt 1 |
audiomap.json | Schritt 2 |
STORYBOARD.md (Skeleton) | 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 (eigener Parser). Alles andere ist die hyperframes CLI.
| Lesen | Wann |
|---|---|
references/frame-skeleton.md | Schritt 2: 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: Vorlage pro Gruppe wählen |
references/motion-primitive-catalog.md | Schritt 3: Bewegungspritive pro Gruppe auswählen |
references/montage.md | Schritt 3: Asset-Benutzer-Gruppen behandeln |
sub-agents/frame-worker.md | Schritt 4: Frame-Worker dispatchieren |