hongliangzheng11/lyric-video-skill

Lyric-Video-Standard-Pipeline

Ein bereits validierter, festgelegter Stil. Der Benutzer muss lediglich eine Audiodatei und den Künstlernamen angeben. Der gesamte Rest wird nach dieser Standardvorgabe ausgeführt – kein Neuentwurf des visuellen Stils. Offizielle Songtexte sind optional: werden sie bereitgestellt, wird der schnelle Pfad 3A verwendet (keine Textspekulation); ansonsten wird der Rekonstruktionspfad 3B verwendet. Die Zeitachsen beider Pfade müssen auf Messungen basieren.

Eingabe / Ausgabe

Eingabe	Beschreibung
Audio	Erforderlich. Beliebiges MP3/WAV/FLAC, beliebige Länge
Künstlername	Erforderlich. Wird für den Vorspann, das permanente Wasserzeichen und den Abspann verwendet
Offizielle Songtexte (optional)	Wenn der Benutzer offizielle Texte hat, werden diese bevorzugt: keine Textspekulation, die Zeitachse wird dennoch vollständig durch gemessene Rescans ermittelt (siehe 3A). Andernfalls erfolgt die Rekonstruktion mit Whisper (3B)
Songtitel (optional)	Standardmäßig wird der Dateiname verwendet; Artist - Title.mp3 entfernt automatisch das Künstler-Präfix
Themenzeile (optional)	Eine chinesische Zeile unter dem Vorspann-Titel, standardmäßig nicht angezeigt

Ausgabe: <project>/renders/video.mp4 + renders/contact-sheet.jpg + transcript.json + NOTES.md.

Festgelegte Spezifikationen (nicht eigenmächtig änderbar)

• Hochkant 1080 × 1920, 30 fps, Gesamtlänge gleich der tatsächlichen Audio-Länge (kein Zuschneiden, Strecken oder Geschwindigkeitsänderung).
• Audio verwendet die Originaldatei, der Renderer sorgt für einheitliche Verstärkung (data-volume="0.9").
• Hintergrund: Rein schwarz bis tiefes Blauviolett, zwei versetzte Lichtflecken überblenden langsam; keine Vollbild-CSS-Filter verwenden (hinterlassen sichtbare Kachel-Nähte).
• Hauptelement: Nur ein transparentes Glaselement, 8 abgerundete geometrische Formen (Kugel/waagerechtes Ellipsoid/senkrechtes Ellipsoid/abgerundetes Rechteck/Raute/Dreieck/Fünfeck/Sechseck), wird beim Auftreffen auf den Bildschirmrand um 11% entlang der Normalen gestaucht → formt sich innerhalb von 0,94 s in eine andere Form um → prallt ab und driftet weiter. Einzelne Zeitachse über das gesamte Lied, kein Zurücksetzen beim Textwechsel.
• Unterer Rand: Kleine Tierbande (Katze/Bär/Pinguin/Fuchs) mit 4,5417 s nahtloser Schleife, bündig am unteren Rand 1080×526, Ebene über dem Hintergrund-Licht, unter dem Glaselement, mix-blend-mode: screen.
• Untertitel: Ganzer Block mit optischem Zentrum bei der vertikalen Bildmitte y≈960; Englisch/Original oben (Inter, Schriftgröße automatisch an Zeilenbreite angepasst), Chinesisch unten (SimSun, warmes Braun #DDA97D), gleiche Gruppe blendet ein und aus.
• Signatur einheitlich mit Künstlernamen, keine Abschnittsbezeichnungen wie VERSE / CHORUS / BRIDGE im Bild.

Detailparameter, Farben, Schriftgrößen und Fallstricke finden Sie in references/style-spec.md.

Ablauf

Sei HF = HyperFrames-Installationsverzeichnis (standardmäßig G:\hyperframes), PY = Python mit faster-whisper (standardmäßig C:\Users\Admin\.workbuddy-ai\binaries\python\envs\hf\Scripts\python.exe), SK = Verzeichnis dieses Skills.

1. Projekt erstellen

"$PY" "$SK/scripts/new_project.py" "<Audio-Pfad>" "<Künstlername>" [--title "Songtitel"] [--tagline "Eine chinesische Zeile"] [--root G:/hyperframes/videos]

Gibt den absoluten Pfad des Projekts aus; unbedingt notieren. Es erstellt: ein eindeutiges Verzeichnis → kopiert die Audiodatei → konvertiert in 16 kHz Mono-WAV → führt das offizielle analyze-beatgrid.py aus, um audiomap.json zu generieren → kopiert das Tierbanden-Spritesheet und GSAP → schreibt project.json.

Vorhandene Projektverzeichnisse werden niemals überschrieben; für Änderungen an bereits ausgelieferten Werken muss ein neues Projekt erstellt werden.

2. Transkription

"$PY" "$SK/scripts/transcribe.py" "<Projekt>" --model medium.en --lang en

CPU int8 benötigt für ein 3–4-minütiges Lied etwa 3–6 Minuten. Bei nicht-englischen Liedern --lang durch die entsprechende Sprache ersetzen, --model ohne .en. Ausgabe: whisper_raw.json (Segment- + Wort-Zeitstempel).

Bei gemischtsprachigen Liedern (Englisch+Japanisch, Englisch+Koreanisch usw.) transcribe.py NICHT verwenden: --lang fixiert eine Sprache, die andere Sprache wird gewaltsam als die erste Sprache transkribiert – das Ergebnis liest sich glatt, ist aber komplett falsch, gefährlicher als Nicht-Auflösung. Stattdessen fensterweise automatische Spracherkennung verwenden:

"$PY" "$SK/scripts/transcribe_mixed.py" "<Projekt>" --model "C:/Users/Admin/.cache/whisper-manual/large-v3-turbo"

Es dekodiert in Fenstern von 14 s / Schrittweite 10 s, jedes Fenster erkennt seine eigene Sprache, behält nur die Kern-Wörter des Fensters (Überlappungsbereich wird verworfen, keine Duplikate), druckt eine Sprachkarte und schreibt whisper_mixed.json. Zuerst die Sprachkarte ansehen: Die Stellen, an denen die Sprache wechselt, sind in der Regel die Abschnittsgrenzen. Hinweis: .en-Modelle (medium.en / small.en) sind reine Englisch-Modelle, können physisch kein Japanisch ausgeben; gemischtsprachige Lieder müssen ein mehrsprachiges Modell verwenden.

Bei Pfad 3A (mit offiziellen Texten) ist dieser Schritt optional: Die Zeitachse basiert auf Prompt-Rescans, dennoch wird empfohlen, bei gemischtsprachigen Liedern zuerst transcribe_mixed.py laufen zu lassen, um die Sprachkarte zu sehen, um für jedes Fenster --lang en oder --lang ja zu bestimmen.

3. Lyrik-Quelldatei schreiben (dieser Schritt muss selbst durchgeführt werden)

Zuerst entscheiden, welcher Pfad gewählt wird, dann <project>/lyrics_source.json schreiben.

3A Benutzer hat offizielle Songtexte bereitgestellt (bevorzugter Pfad)

• Text der offiziellen Songtexte unverändert übernehmen: en-Slot ist der offizielle Originaltext (englische Sätze auf Englisch, japanische Sätze auf Japanisch, Kanji/Kana wie geschrieben), zh Satz für Satz übersetzen.
• Zeitachse nicht über eine vollständige Transkription ermitteln: Offizielle Songtexte als initial_prompt für fensterweise Rescans verwenden, um Wort-Zeitstempel zu erhalten (siehe 3.5), jede Zeile mit explizitem start/end versehen, align_lyrics.py verwendet den manuellen Kanal, um Zeilen zu verankern.
• Offizielle Songtexte stimmen nicht mit dem Rescan-Ergebnis überein → Immer die offiziellen Songtexte verwenden, die Unterschiede in NOTES.md auflisten und den Benutzer um Bestätigung bitten. Häufige drei Fälle: Standardwortform vs. Schreibfehler (不甲斐ない / 不甲埋ない), ähnlich klingende Wörter (束の間の / 明日の間の), stimmlose Konsonanten (smiling / falling).
• Zwei Zeilen in offiziellen Songtexten, die in einem Atemzug gesungen und jeweils unter 1 s lang sind → Untertitel werden zu einer Zeile zusammengelegt (Text unverändert, nur nebeneinander), die Zusammenlegungstabelle in NOTES.md festhalten.
• Lautmalerische/improvisierte Passagen, die nicht in den offiziellen Songtexten stehen ("Yeah,", Summen, Pfeifen) → Keine Untertitel, nicht selbst erfinden.
• Struktur wie folgt schreiben:

{
  "audio": "Artist - Title.mp3",
  "models": ["large-v3-turbo — prompted window re-scans, official lyrics as initial_prompt"],
  "lines": [
    {"en": "Oh my god, they're coming again", "zh": "哦天哪，他们又来了", "start": 6.36, "end": 9.10, "lang": "en", "conf": "high"}
  ]
}

3B Keine offiziellen Songtexte (Rekonstruktionspfad)

whisper_raw.json (oder bei gemischtsprachigen Liedern whisper_mixed.json) lesen und daraus die Lyrik-Quelldatei schreiben:

{
  "audio": "Artist - Title.mp3",
  "models": ["faster-whisper medium.en — full track, word timestamps"],
  "lines": [
    {"en": "Sometimes I lay under the moon", "zh": "有时我躺卧在月光之下"},
    {"en": "And thank God I'm breathing", "zh": "感谢上天让我仍在呼吸"}
  ]
}

Gemeinsame Anforderungen beider Pfade:

• Zeile = ein tatsächlich gesungener Satz, nach offizieller Satzgliederung; zu lange Sätze von Whisper müssen getrennt werden.
• Englische Schreibweise nach offiziellen Songtexten korrigieren ('Cause / I've usw. mit Apostroph), Whisper-Tippfehler nicht übernehmen.
• Chinesisch Satz für Satz übersetzen, Tonfall an das Lied anpassen, keine Sätze auslassen, nicht zusammenlegen, keine Platzhaltertexte.
• Wiederholte Refrains müssen jedes Mal ausgeschrieben werden (kein "dito").
• Wenn ein Satz von der Begleitung übertönt wird und die automatische Ausrichtung deutlich abweicht, explizite Zeiten hinzufügen (nach Anhören der Audiodatei ausfüllen): {"en": "...", "zh": "...", "start": 13.22, "end": 16.80}.
• Chinesische Lieder/Instrumentalmusik: Bei chinesischen Liedern en mit dem Originaltext füllen, zh als leeren String lassen, im Bild wird nur eine Zeile angezeigt; Instrumentalmusik ist nicht geeignet für dieses Skill.
• Gemischtsprachige Lieder: Der en-Slot enthält den Originaltext der tatsächlichen Sprache dieses Satzes (englische Sätze auf Englisch, japanische Sätze auf Japanisch, Kanji/Kana wie geschrieben), zh enthält die chinesische Übersetzung. Das Bild zeigt standardmäßig "Original + Chinesisch" in zwei Zeilen; gemischte Anordnung zerstört das Layout nicht; die englische Zeile der Vorlage enthält bereits Yu Gothic UI / Yu Gothic / Meiryo als Fallback, sodass Kana und Kanji korrekt dargestellt werden.

3.5 Prompt-Rescans: Kernmethode für Zeitachsen-Präzision

Die vollständige Transkription ist bei schnellen Liedern, gemischtem Gesang oder schnellen Textpassagen oft ungenau. Die Verwendung bekannter Songtexte als initial_prompt für fensterweise Rescans ist die Methode mit der höchsten Genauigkeit – Die Prompt-Qualität bestimmt direkt die Rescan-Genauigkeit: Offizielle Songtexte > Vermutete Songtexte > Kein Prompt. Kann in rescan_all.sh für den gesamten Track in einem Batch geschrieben werden:

"$PY" "$SK/scripts/rescan.py" "<Projekt>" --from 6.0 --to 20.0 \
    --model "C:/Users/Admin/.cache/whisper-manual/large-v3-turbo" \
    --lang en --prompt "<Offizieller Text dieses Fensters>"

Wichtige Punkte:

• Gesamten Track in Fenster von 20–26 s schneiden, Überlappung zwischen Fenstern ca. 0,5 s, jedes Fenster erneut analysieren; large-v3-turbo CPU int8 benötigt pro Fenster ca. 5–10 s.
• Bei gemischtsprachigen Liedern jedes Fenster sowohl auf en als auch ja analysieren: Nur wo beide Pfade übereinstimmen, wird der Wort-Zeitstempel verwendet; Wörter, die nur in einem Pfad erscheinen, werden mit dem anderen Pfad überprüft.
• Für Sätze mit unklarem oder verspätetem Start ein schmales Fenster von 2 s zur Nachjustierung hinzufügen (--from 37.2 --to 39.2 nur für den Start eines Satzes); der Start eines Abschnittsfensters kann durch die Endung des vorherigen Satzes verfälscht werden.
• Halluzinationen behandeln: Gelegentlich gibt ein Rescan denselben gesamten Satz 15+ Mal aus → Dieses Fenster verwerfen, einen anderen Sprachkanal oder ein kleineres Fenster verwenden, nur den sauberen einmaligen Zeitstempel verwenden, Halluzinationen nicht in die Lyrik-Quelldatei übernehmen.
• Jeder Rescan speichert rescan_<from>-<to>.json und druckt die Start-/Endzeit jedes Wortes im Fenster. Dies ist eine zweite Dekodierung, keine Schätzung; die Zahlen werden direkt in die start/end-Felder von lyrics_source.json geschrieben.
• Passagen, die von der Begleitung übertönt, zu ooh verarbeitet, zu einem großen Block zusammengefasst oder wiederholte Sätze, die verschluckt wurden, werden ebenfalls zuerst mit dieser Methode behandelt, bevor Überschreibungswerte gesetzt werden; der Austausch des Modells (small.en / medium.en) kann ebenfalls wirksam sein.

4. Ausrichtung + Generierung

"$PY" "$SK/scripts/align_lyrics.py" "<Projekt>"
"$PY" "$SK/scripts/motion.py" "<Projekt>"
"$PY" "$SK/scripts/gen_storyboard.py" "<Projekt>"
"$PY" "$SK/scripts/build_frame.py" "<Projekt>"
"$PY" "$SK/scripts/make_index.py" "<Projekt>"

align_lyrics.py druckt eine zeilenweise Zeittabelle und führt zwei harte Überprüfungen durch:

• Ein Satz am Anfang/Ende passt überhaupt nicht → Fehler mit Abbruch, Auflistung der betroffenen Sätze (es wird nicht mit geschätzten Zeiten kaschiert).
• Ein Satz in der Mitte passt nicht, oder zwei Sätze haben denselben Startzeitpunkt, oder ein Satz wird auf unter 0,5 s komprimiert → REVIEW wird gedruckt und Exit-Code 2 ausgegeben.

Bei einem dieser Fälle zu Schritt 3.5 zurückgehen, Überschreibungswerte hinzufügen, bis die Ausgabe OK: every line anchored to a real sung timestamp lautet. Diesen Schritt nicht überspringen, um zu rendern. Bei Pfad 3A haben alle Zeilen explizite start/end-Werte (manueller Kanal), sollten alle verankert und 0-Gap-gefüllt sein; bei Pfad 3B basiert es auf Wortabgleich; für nicht passende Zeilen werden die Zeiten gemäß Schritt 3.5 hinzugefügt.

Der Zufallsstartwert von motion.py wird durch "Künstlername+Songtitel" bestimmt – jedes Mal, wenn dasselbe Lied erneut ausgeführt wird, ist der Pfad vollständig identisch; verschiedene Lieder haben verschiedene Pfade.

5. Validierung

cd "<Projekt>"
node "$HF/packages/cli/bin/hyperframes.mjs" check .
node "$HF/packages/cli/bin/hyperframes.mjs" snapshot . --at "3,20,60,120" --no-end -o build/shots

Muss erreichen: lint / runtime / layout / motion 0 Fehler, contrast alle bestehen WCAG AA. Dann tatsächlich die Screenshots ansehen: Ist das Glaselement vollständig? Sind die Songtexte zentriert? Ist die Tierbande unten? Gibt es zusätzliche Blasen oder Abschnittsbezeichnungen? composition_file_too_large ist ein Stilhinweis für Einzelframes mit mehr als 300 Zeilen und ist akzeptabel (bei einem Einzelzeitachsen-Design zwangsläufig).

6. Rendern + Abnahme

node "$HF/packages/cli/bin/hyperframes.mjs" render . --skill=music-to-video -q delivery -o renders/video.mp4 --fps 30
"$PY" "$SK/scripts/verify.py" "<Projekt>"

verify.py überprüft Auflösung/Bildrate/Längenabweichung (Abweichung von mehr als einem Frame führt zu Fehler) und erstellt ein Kontaktblatt. Das Kontaktblatt muss angesehen werden, um sicherzustellen, dass Anfang, Strophe, Refrain, Wiederholungen und Ende visuell dargestellt sind und die Untertitel keine Lücken oder Verschiebungen aufweisen.

Abschließend NOTES.md schreiben (Spezifikationen, Zeitachsen-Quelle, Reproduktionsbefehle, Validierungsaufzeichnungen) und das fertige Video sowie das Kontaktblatt an den Benutzer übergeben.

Harte Regeln

• Keine Berechnung von Songtext-Zeiten mit BPM/Taktgitter; Zeitstempel dürfen nur aus Whisper-Messungen (einschließlich Prompt-Rescans) oder manueller Überprüfung durch Anhören stammen.
• Vom Benutzer bereitgestellte offizielle Songtexte haben Vorrang vor jeglichen Modell-Rekonstruktionsergebnissen; bei Konflikten die offiziellen Songtexte verwenden und die Unterschiede in NOTES.md auflisten, um den Benutzer um Bestätigung zu bitten.
• Änderungen an Auflösung, Bildrate, Länge, Signatur oder Untertitelposition sind nicht erlaubt, nur weil „es besser aussieht".
• Ohne Validierung keine Behauptung der Audio-Video-Synchronisation; jedes Lied muss stichprobenartig überprüft werden.
• Fehlende Materialien, nicht verfügbare Werkzeuge, Spezifikationskonflikte → klar melden, keine geschätzten Daten als Ergebnisse ausgeben.
• Bereits ausgelieferte Projekte und ihre Quelldateien gelten als schreibgeschützt; für Änderungen muss ein neues Verzeichnis erstellt werden.

Umgebungsabhängigkeiten

• HyperFrames: node <HF>/packages/cli/bin/hyperframes.mjs (enthält skills/music-to-video/scripts/analyze-beatgrid.py).
• Python: faster-whisper, librosa, soundfile, numpy, scipy, pillow. Falls nicht vorhanden: python -m venv <env> && <env>/Scripts/pip install faster-whisper librosa soundfile numpy scipy pillow.
• Whisper-Modelle: Direkte Modellnamen werden automatisch heruntergeladen; es kann auch auf ein lokales Verzeichnis verwiesen werden (auf diesem Rechner üblich: C:\Users\Admin\.cache\whisper-manual\medium.en; für Prompt-Rescans bevorzugt: C:\Users\Admin\.cache\whisper-manual\large-v3-turbo, CPU int8 für gesamtes Lied ca. 48 s, pro Fenster 5–10 s).
• ffmpeg / ffprobe müssen im PATH sein.

Bekannte Fallstricke

• <video> für die Tierbanden-Ebene nicht verwenden: Bei hyperframes render unter Windows kann das Verzeichnis mit den extrahierten Frames nach der Verlinkung in das Build-Verzeichnis nicht gelesen werden (ENOENT ... __hyperframes_video_frames/*/frame_00001.jpg). Spritesheet verwenden.
• Vollbild-CSS filter: hue-rotate() hinterlässt im Rendering vertikale Nähte; stattdessen zwei überblendende Lichtflecken verwenden.
• Template-HTML mit data-composition-id darf nicht im Projektstammverzeichnis abgelegt werden (löst multiple_root_compositions aus); in build/ ablegen.
• Chinesische Schriftarten müssen explizit mit @font-face und local("SimSun") deklariert werden, sonst meldet der Linter font_family_without_font_face.
• Rescan-Halluzinationen: Einige Fenster geben denselben gesamten Satz 15+ Mal aus (z. B. "永遠の行方はどこにある?" × 15) → Dieses Fenster verwerfen, einen anderen, sich überschneidenden en-Kanal oder ein kleineres Fenster verwenden, Halluzinations-Zeitstempel nicht in die Lyrik-Quelldatei übernehmen.
• Inkonsistenz zwischen offiziellen Songtexten und Rescan: Offizielle Songtexte verwenden und in NOTES.md eine Vergleichstabelle zur Bestätigung durch den Benutzer aufführen, nicht eigenmächtig den offiziellen Text ändern.
• Schnelle, zusammengelegte Zeilen: Zwei Zeilen in offiziellen Songtexten, die in einem Atemzug gesungen und jeweils unter 1 s lang sind, werden im Untertitel zu einer Zeile zusammengelegt (Text unverändert, nur nebeneinander), die Zusammenlegungstabelle in NOTES.md festhalten.
• Fehler beim Laden von Schriftarten im Headless-Modus (Yu Gothic UI meldet FAILED während der Screenshot-Erstellung): Kein Grund zur Sorge: src: local() wird vom Browser meistens gefunden, da die Schriftart im System installiert ist; die nächste Schriftart im Fallback wird verwendet; zuerst die Screenshots ansehen, dann entscheiden, ob eine Behandlung erforderlich ist.