Communitygithub.com

craft-music-video

Zeigt einem Agenten, wie man ein Musikvideo plant, erstellt oder schneidet, sodass das konkrete Ergebnis eine Bewegung ist, die der Agent Einstellung für Einstellung verteidigen kann. Das Verfahren durchläuft Craft Music Video (`FilmCraft` + `EffectCraft`), 0. Pré-requis MCP et Sandbox (à vérifier avant de démarrer), 1. Répartition des rôles : EffectCraft vs FilmCraft. Verwenden Sie es, wenn eine neue Aufgabe dieses Handwerk erfordert.

Was ist craft-music-video?

Diese Skill-Anleitung beschreibt einen vollständigen Workflow zur Erstellung professioneller Musikvideos, der die beiden KI-gesteuerten Tools EffectCraft (für 2D-Animationen, Motion Graphics, VFX und eigenständige transparente Texteinblendungen) und FilmCraft (für den Hauptschnitt, Mehrspur-Arrangement, Audio-Synchronisation, Farbkorrektur und Doppelexport) kombiniert. Der Prozess beginnt mit der Überprüfung der MCP-Server und Sandbox-Konfiguration, gefolgt von einer klaren Rollenverteilung zwischen den beiden Tools. Kern des Workflows ist eine detaillierte, hörgenaue Audioanalyse bei 44,1 kHz, um Takt, Abschnitte und Gesangslinien präzise zu erfassen und in einer editierbaren JSON-Datei (`audio/lyrics_timing.json`) zu speichern. Die Erstellung der Szenen und Texteinblendungen erfolgt in EffectCraft unter Einhaltung der Regeln für 2D-Animation (aus der referenzierten `craft-2d-animation`), während der Zusammenschnitt, die Alpha-Compositing und der obligatorische Doppelexport (mit/ohne Liedtexte) in FilmCraft stattfinden. Die Skill-Arbeitsanleitung betont die ausschließliche Verwendung von verlustfreien, Alpha-fähigen Videoformaten wie Apple ProRes 4444 für transparente Overlays, die Einhaltung eines gemeinsamen Farbraums (Rec. 709) und einer einheitlichen Bildrate und Auflösung. Neben der detaillierten Schritt-für-Schritt-Anleitung enthält die Skill-Dokumentation wichtige technische Konventionen, Abhängigkeiten zu geteilten T3-Code-Tools und strenge Qualitätskontrollen, die sowohl eine visuelle als auch auditive Prüfung der finalen Exporte sicherstellen.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/NelaBDV/craft-video-kit/tree/HEAD/skills/craft-music-video

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Craft Music Video (FilmCraft + EffectCraft)

Wiederverwendbarer Workflow zur Produktion von Musikvideos, die auf einer Audiospur synchronisiert sind, durch Kombination von EffectCraft (2D-Szenen, Motion Graphics, VFX, unabhängiger Alpha-Layer für Liedtexte) und FilmCraft (Hauptschnitt mit mehreren Spuren, rhythmische Synchronisation, Audio-Mixing/Mastering, globale Farbkorrektur, Doppelexport Master + Clean).

Gemeinsame 2D-Animationsmethoden (Bildausschnitte, Posenwechsel mit Antizipation, Ankerpunkte für Figuren/Kameras, Fallstricke beim Parenting in EffectCraft, Stapelreihenfolge und Lesbarkeit von Text): Befolgen Sie craft-2d-animation.

Vollständige MCP-Referenz, verifizierte Motor-Befehle und Flatpak-Konfigurationen: references/mcp-and-commands.md.


0. MCP- und Sandbox-Voraussetzungen (vor dem Start zu überprüfen)

  1. Stellen Sie sicher, dass die MCP-Server effectcraft und filmcraft in der aktuellen Sitzung verfügbar sind (oder wechseln Sie sauber zu den CLIs effectcraft-cli / filmcraft-cli).
    • Falls sie fehlen, erfinden Sie keine Aufrufe: Konsultieren Sie references/mcp-and-commands.md für die genaue Konfiguration (Flatpak Linux ai.storyteller.filmcraft / ai.storyteller.effectcraft oder natives Binary, im Headless- oder Bridge-Modus).
  2. Achtung Flatpak (Linux): Standardmäßig hat ai.storyteller.effectcraft nur Zugriff auf xdg-documents, xdg-pictures und xdg-videos. Wenn das Projekt woanders liegt (z. B. ~/.t3/projects/...), übergeben Sie --filesystem=<Projektstamm> oder konfigurieren Sie den Override: flatpak override --user --filesystem=home ai.storyteller.effectcraft
  3. GUI vs. Headless-Konflikt: Öffnen Sie niemals dieselbe .ecproj- oder .fcproj-Datei gleichzeitig in der grafischen Anwendung und im MCP/CLI-Headless-Modus. Verwenden Sie --bridge, um ein geöffnetes Fenster zu steuern.

1. Rollenverteilung: EffectCraft vs. FilmCraft

BereichEffectCraft (.ecproj)FilmCraft (.fcproj)
HauptverwendungAnimierte 2D-Szenen (V01..Vnn), Liedtexte auf unabhängigen transparenten Layern (L01..Lnn), kinetische Titel, Partikel, 2D/3D-CompositingHauptschnitt mit mehreren Spuren (V1 Szenen + V2 RGBA-Texte + A1 Master-Audio), Frame-genaue Synchronisation, Überblendungen, globale Farbkorrektur, Doppelexport (mit Texten + Clean)
Erstellungcomp.new, layer.newText, layer.newShape, layer.newSolid, layer.newAdjustment, add_effect, JSX-Skripte (ec_runtime.py)file.newSequence, timeline.place, timeline.setTrack, timeline.razor, timeline.trim, timeline.move, clip.speedDuration
Musikalische SynchronisationGenaue Referenzpunkte aus audio/lyrics_timing.json + Hören nach Gehör; optional keys.audioToKeyframes nur, wenn ein gemessener reaktiver Effekt gewünscht istmarkers.add für jeden Abschnitt, letzten Akzent und Schwarzschnitt; Frame-genaue Platzierung (frame: f0)
Gestaltung & FarbgebungLayer-Stile, Masken, Bézier-Kurven, Leuchteffekte, Schlagschatten, Vorkompositionen (layer.precompose)Lumetri Color (lumetri.applyPreset, lumetri.setLook, lumetri.applyMatch), sequence.colorSettings, sequence.applyVideoTransition
AudioKein Audio bei Zwischenrendern (--audio off)Original-Masterspur auf A1 (standardmäßig auf 0.0 dB belassen, um das Original-Master zu erhalten; essentialSound.* oder sequence.normalizeMixTrack nur auf Anfrage)

2. Pipeline für Dateiaustausch & Technische Konsistenz

Projektordner-Konvention

<Projektstamm>/
├── audio/           # Masterspur (WAV/FLAC/MP3) + lyrics_timing.json (einzige editierbare Quelle)
├── footage/         # Videomaterial, Fotos, ggf. Logos
├── renders_vfx/     # EffectCraft-Zwischenrenditen: V01..Vnn.mov (RGB) + L01..Lnn.mov (RGBA)
├── previews/        # PNG-Screenshots (render-frame) + kurze MP4-Vorschauen mit Ton (z. B. Refrain, Solo)
├── projects/        # .ecproj- und .fcproj-Dateien
├── scripts/         # Clipspezifische Generatoren (wichtig: geteilte T3-Code-Tools)
└── exports/         # Finale 1080p-Lieferobjekte: *_lyrics.mp4 und *_clean.mp4

Kompatible Austauschformate

  • Texte & Overlays mit Transparenz (V2) von EffectCraft → FilmCraft:
    • Empfohlen (einzelne Datei): QuickTime Apple ProRes 4444 (.mov), format: "prores", proresProfile: "4444", channels: "rgba", audio: "off".
    • Verlustfreie Alternative: PNG- oder OpenEXR-Sequenz (channels: "rgba"), importiert in FilmCraft mit image_sequence: true.
    • Für Alpha verboten: H264, Hevc und Av1 unterstützen keinen Alphakanal (alpha: false).
  • Undurchsichtige visuelle Szenen (V1) von EffectCraft:
    • format: "prores", proresProfile: "hq", channels: "rgb", audio: "off".
  • Finale Lieferung von FilmCraft:
    • Web/Ausstrahlung: format: "h264" (.mp4, Preset "High Quality 1080p HD").
    • Master-Archiv: format: "prores". (Hinweis: Unter Linux ohne Hardware-Encoder sind hevc und av1 möglicherweise nicht verfügbar.)

Auflösungs-, Bildraten- (FPS) und Farbraumabstimmung

  1. Von Anfang an festlegen ein eindeutiges Paar (width, height, fps), das zwischen EffectCraft (comp.new) und FilmCraft (file.newSequence) geteilt wird, z. B. 1920×1080 mit 30 oder 24 fps.
  2. Frame-genaue Abschnitte: Berechnen Sie jede Abschnittsgrenze als ganze Anzahl von Frames (f0 / fps .. f1 / fps), sodass die Summe der Abschnitte genau die tatsächliche Länge der Audiospur abdeckt, ohne Drift oder Lücken.
  3. Farbraum: workingSpace: "rec709" in SDR in beiden Programmen (file.projectSettings in EffectCraft, sequence.colorSettings in FilmCraft; autoToneMap: true bei HDR/Log-Material).
  4. Zeitumrechnung: EffectCraft arbeitet in Sekunden (f64); FilmCraft verwendet Ticks (254016000000 Ticks = 1 s) und akzeptiert auch frame / seconds in timeline.place.

3. Zentrale musikalische Methode (Synchronisation nach Gehör, editierbares Timing, unabhängige Texte & Instrumentalpassagen)

A. Synchronisation nach Gehör und genaue Messung des Endes auf der Master-Audiospur

  1. Messen Sie die originale Spur immer mit 44,1 kHz (hop = 441 = exakt 10.000 ms) über audio_cues.py analyze (verwenden Sie niemals einen gerundeten Schritt von 22,05 kHz, der über 3 Minuten zu einer Drift von mehreren hundert Millisekunden führt).
  2. Überprüfen Sie das genaue Ende auf der MP3/WAV-Datei, bevor Sie den Schnitt verriegeln: Identifizieren Sie den letzten starken Akzent, den letzten Schlagzeug-/Instrumentenschlag (z. B. Schwarzschnitt) und das tatsächliche Ende des Nachhalls bis zur endgültigen Stille.
  3. Hören Sie sich die Spur abschnittsweise an: Schneiden Sie das Stück in überlappende Segmente (z. B. 18 s mit 2 s Überlappung) und dann kurze Auszüge um Übergänge, Refrains, Chöre und Phrasenenden herum (audio_cues.py slice) und hören Sie sie sich an, um das genaue BPM und jeden Gesangseinsatz nach Gehör festzulegen.

B. Einzelne editierbare Timing-Datei (audio/lyrics_timing.json) und unsichere Referenzpunkte

Zentralisieren Sie das gesamte Timing der Texte in einer einzigen manuell editierbaren JSON-Datei (audio/lyrics_timing.json), die vom EffectCraft-Generator gelesen wird:

  • meta: Audiodatei, Audio-/Videolänge in ms, fps, bpm, first_drum_hit_ms, last_accent_ms, black_cut_ms.
  • sections: Grenzen start_ms / end_ms, frame-genau ausgerichtet.
  • phrases:
    • start_ms, end_ms und display_end_ms (bei Bedarf um +250 bis +600 ms verlängert, damit das letzte Wort lesbar bleibt, auch wenn die Einstellung oder der Abschnitt wechselt).
    • type: "lead" für den Hauptgesang und type: "echo" in separaten Einträgen für Begleitgesang, Antworten und Ad-libs.
    • words (Aufteilung in Wörter/Gruppen) nur dort, wo eine Animation oder ein visueller Akzent dies erfordert; ansonsten die gesamte Phrase sauber anzeigen.
    • "uncertain": true + "review_note": "..." bei allen mehrdeutigen Referenzpunkten (Begleitgesang, Echos, überlagerte Vokalisen, kurze Schreie), damit der Benutzer sie leicht manuell nachjustieren kann, ohne den Code zu ändern.

C. Texte auf einem unabhängigen Layer (V2 RGBA) & Doppelexport Master / Clean

  1. Keine permanenten schwarzen Balken: Platzieren Sie jede Phrase im freien Raum der Einstellung (siehe craft-2d-animation §5), mit weichem Schlagschatten, Sicherheitsabständen und automatischer Kontinuität (isContIn / isContOut), wenn display_end_ms einen Abschnittsschnitt überbrückt.
  2. Dedizierte transparente Spur: Generieren Sie die Texte in separaten Kompositionen L01..Lnn (unter Auslassung rein instrumentaler Abschnitte), die als ProRes 4444 RGBA gerendert und auf V2 in FilmCraft abgelegt werden.
  3. Text im Set auf V1 belassen: Schilder, Bildschirme, Kopien, Tafeln bleiben in den Szenen V01..Vnn.
  4. Streng identischer Doppelexport: Exportieren Sie die Version mit Texten (V2 aktiviert), deaktivieren Sie dann V2 (timeline.setTrack {"track": "V2", "enabled": false}), um die Clean-Version mit zu 100 % identischem Schnitt und Audio zu exportieren, und aktivieren Sie V2 vor dem endgültigen Speichern der .fcproj-Datei wieder.

D. Visuelle Aktionen während instrumentaler Passagen (Keine generischen Audiokurven)

  1. Verzichten Sie auf generische visuelle Krücken: Keine Audiokurven, keine Oszilloskop-Zickzacklinien, keine dekorativen schwebenden Kreise bei Intros, Soli oder Zwischenspielen.
  2. Choreografieren Sie gezeichnete Aktionen auf nach Gehör ausgewählten Akzenten: Eine Tür knallt zu, eine Reihe von Deckenleuchten schaltet sich nacheinander ein, ein Set entfaltet sich in Karton/3D-Papier auf Riffs, ein Objekt gleitet oder eine Figur wechselt die Pose mit Antizipation und Halten.
  3. Halten Sie die Einstellungen zwischen den Akzenten: Lassen Sie zwischen zwei starken Schlägen ein klares und stabiles Bild, damit die Aktion lesbar bleibt.
  4. Wenden Sie die gemeinsamen 2D-Regeln an: Abwechslungsreiche Bildausschnitte (Total / OTS / Profil / Nahaufnahme), vollständige Silhouetten, Hierarchie neutraler Ankerpunkte vor Transformation (siehe craft-2d-animation).

4. Schritt-für-Schritt-Workflow

Schritt 1 — Audioanalyse nach Gehör & Timing-Skelett

  1. Untersuchen Sie das Master (audio_cues.py analyze) mit 44,1 kHz, um die genaue Dauer, 10-ms-Transienten und die Details des Trackendes zu erhalten.
  2. Extrahieren Sie Hörsegmente (audio_cues.py slice) und hören Sie sie an, um das genaue BPM, die frame-genauen Abschnittsgrenzen, Phrasen, Echos und den finalen Schnitt zu bestimmen.
  3. Initialisieren und füllen Sie audio/lyrics_timing.json, markieren Sie zweifelhafte Referenzpunkte mit "uncertain": true + "review_note" und validieren Sie das JSON (lyrics_overlay.py --validate).

Schritt 2 — Aufteilung / Kurzes Storyboard (vor großen Renderings)

  1. Erstellen Sie einen kurzen Schnittplan (Tabelle Zeit / Abschnitt / Ort & Bildausschnitt / gezeichnete visuelle Aktion / Textbehandlung).
  2. Präsentieren Sie dem Benutzer die Aufteilung (und die Akzentwahl für instrumentale Passagen), bevor Sie vollständige Renderings starten.

Schritt 3 — Erstellung der Szenen (V01..Vnn) und Texte (L01..Lnn) in EffectCraft

  1. Bauen Sie die 2D-Szenen (V01..Vnn) gemäß den Regeln für Ankerpunkte, neutrales Parenting und Stapelreihenfolge aus craft-2d-animation (mit Hilfe von ec_runtime.py).
  2. Generieren Sie die transparenten Textkompositionen (L01..Lnn, ohne Instrumentalpassagen) direkt aus audio/lyrics_timing.json über lyrics_overlay.py.
  3. Schnelle Prüfung durch Screenshots (render-frame --max-side 960) von Schlüsseleinstellungen (und --transparent für Texte), um Überlappungen oder Ankerverschiebungen sofort vor dem Videorendering zu korrigieren.
  4. Kurze MP4-Vorschauen mit Ton (z. B. 1 Refrain + 1 Solo): Rendern Sie nur diese 1–2 Abschnitte, muxen Sie sie mit dem genauen Ausschnitt des Master-Audios, sehen und hören Sie sie an, um bei Bedarf Echo-Einsätze, das Halten des letzten Wortes zwischen Einstellungen und die Lesbarkeit des Solos nachzujustieren.
  5. Vollständiges Low-Power-Rendering nach ./renders_vfx/ über render_ec_batch.sh (sequenziell 1 Rendering nach dem anderen, ProRes HQ RGB für V*, ProRes 4444 RGBA für L*, automatische Wiederaufnahme über ffprobe).
  6. Speichern Sie projects/<clip>.ecproj.

Schritt 4 — Zusammenbau & Doppelexport in FilmCraft

  1. Bauen Sie die Rec.709-Sequenz über assemble_filmcraft.py (oder über MCP file.newProject, file.newSequence, media_import, timeline.place, markers.add) zusammen:
    • A1: Originales Master-Audio intakt (volumeDb: 0.0)
    • V1: V01..Vnn.mov platziert an ihrem genauen Frame (frame: f0)
    • V2: L01..Lnn.mov (ProRes 4444 RGBA) platziert an denselben genauen Frames (audio: false)
  2. Überprüfen Sie die Sequenz (inspect sequence) + rendern Sie einige V1+V2-Composite-Frames und V1 allein, um den Alpha-Ausschnitt und das Vorhandensein des diegetischen Texts in der Clean-Version zu bestätigen.
  3. Exportieren Sie die Version mit Texten (*_lyrics.mp4), deaktivieren Sie V2, exportieren Sie die Clean-Version (*_clean.mp4), aktivieren Sie dann V2 wieder und speichern Sie projects/<clip>.fcproj.

Schritt 5 — Abschließendes obligatorisches Audit (Mit Ton + Ohne Ton)

  1. Prüfung MIT Ton am Export *_lyrics.mp4: Überprüfen Sie die Phrasenenden, Refrain-Schnitte, Echo-Einsätze, den genauen Schwarzschnitt und das saubere Ende der originalen Audiospur.
  2. Prüfung OHNE Ton (stumm) an den instrumentalen Passagen (Solo, Zwischenspiel) des Exports *_clean.mp4: Stellen Sie sicher, dass das Ziel der Figur und der visuelle Fortschritt zu 100 % ohne Audio verständlich sind, ohne verbleibende Audiokurven und mit intaktem Text im Set.
  3. Präsentieren Sie die Lieferobjekte und listen Sie explizit die in lyrics_timing.json mit "uncertain": true markierten Referenzpunkte auf.

5. Geteilte T3-Code-Tools & Abhängigkeiten

Die wiederverwendbaren Tools befinden sich in ~/.t3/shared/craft-video/:

ToolPfadVerwendung im Musikclip
44,1-kHz-Audioanalyse & -Segmentierung~/.t3/shared/craft-video/audio_cues.pyDauer-, Transienten- & Enddetektion (analyze), überlappende Hörsegmente (slice), Ausgabe von Markern
Lyrics-Overlay-Generator~/.t3/shared/craft-video/lyrics_overlay.pyLiest lyrics_timing.json, erzeugt EffectCraft-Kompositionen L* & validiert die JSON-Struktur
Batch-Rendering~/.t3/shared/craft-video/render_ec_batch.shSequenzielles Rendering von V* & L* in ProRes, Wiederaufnahme bei Unterbrechung
FilmCraft-Assembler~/.t3/shared/craft-video/assemble_filmcraft.pyErzeugt Sequenz, platziert Clips auf V1/V2/A1, fügt Marker hinzu, Prüfung (probe)
Gemeinsame 2D-Animationsregeln../craft-2d-animation/SKILL.mdAnker, Parenting, Stapelreihenfolge, Posenwechsel

6. Wichtige Konventionen & Fallstricke

  1. Keine unbestimmten Rundungen: Alle Zeitwerte (ms, Frames, samples) müssen deterministisch aus der gemessenen Master-Audiodatei stammen. Verwenden Sie audio_cues.py analyze mit hop=441; jeder andere hop-Wert führt bei typischen Musikvideolängen zu inkonsistentem Timing.
  2. Alpha nur in verlustfreien Codecs: Legen Sie Alphakanäle (Texte, Logos, Partikel-Overlays) ausschließlich in ProRes 4444, PNG oder OpenEXR an. Verlustbehaftete Codecs (h264, h265, av1) zerstören die Transparenz. Validieren Sie mit ffprobe -show_streams renders_vfx/L01.mov | grep "codec_name".
  3. Einzelner Referenzpunkt für den finalen Schwarzschnitt: Verwenden Sie den letzten starken Akzent (last_accent_ms) aus lyrics_timing.json, bestimmen Sie eine angemessene Ausklingzeit (Nachhall, letzter Atemzug), schneiden Sie auf Schwarz und setzen Sie das Sequenzende auf genau diesen Frame. Keine willkürliche Ausblendung (dissolve) auf dem letzten Bild.
  4. Clean-Version mit lesbarem diegetischem Text: Wenn V01..Vnn Texte im Set enthalten (Schilder, Bildschirme, Untertitel), stellen Sie sicher, dass diese in der Clean-Version (*_clean.mp4) vollständig sichtbar bleiben. Deaktivieren Sie nur die Overlay-Spuren V2, nicht die Szenenebene.
  5. Niemals von der Quelle trennen: Kopieren Sie keine Audio-/Videodateien in andere Ordner. Bearbeiten Sie die Originaldateien in ./audio/ und ./footage/ und rendern Sie Zwischenprodukte in ./renders_vfx/. Verwenden Sie relative Pfade in allen Konfigurationen.
  6. Planung vs. Ausführung: Präsentieren Sie immer zuerst das Storyboard (Schritt 2), bevor Sie mit dem Rendering beginnen. Ein einmal gerenderter Satz von Szenen (V01..Vnn) erfordert einen neuen Durchlauf, um das Timing zu ändern.
  7. Hörprüfung ist nicht verhandelbar: Das Skript audio_cues.py analyze liefert keine menschliche Hörprüfung. Der Agent muss Hörsegmente erzeugen und dem Benutzer zur Überprüfung vorlegen oder sie in einer Vorschau anhören und die Ergebnisse in lyrics_timing.json eintragen.
  8. Keine generischen visuellen Effekte: Füllen Sie instrumentale Passagen niemals mit statischen Wellenformen, Spektrumanalysatoren oder sich wiederholenden dekorativen Kreisen. Choreografieren Sie stattdessen gezeichnete Aktionen, die die Musikrichtung hervorheben (z. B. ein Kartenhaus, das auf dem Höhepunkt eines Gitarrensolos zusammenfällt).

7. Nützliche Befehle

# 1. Master-Audio analysieren (44,1 kHz, 10-ms-Präzision)
python3 ~/.t3/shared/craft-video/audio_cues.py analyze audio/song.wav --hop 441

# 2. Überlappende Hörsegmente extrahieren (18 s, 2 s Überlappung)
python3 ~/.t3/shared/craft-video/audio_cues.py slice audio/song.wav --duration 18 --overlap 2 --out previews/

# 3. Timing-JSON validieren
python3 ~/.t3/shared/craft-video/lyrics_overlay.py --validate audio/lyrics_timing.json

# 4. Alle V* & L* in ProRes rendern (sequenziell, automatische Wiederaufnahme)
bash ~/.t3/shared/craft-video/render_ec_batch.sh projects/clip.ecproj renders_vfx/

# 5. FilmCraft-Sequenz aus JSON zusammenbauen
python3 ~/.t3/shared/craft-video/assemble_filmcraft.py \
    --project projects/clip.fcproj \
    --json audio/lyrics_timing.json \
    --vfx renders_vfx/ \
    --audio audio/song.wav

Referenzen

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Verwandte Skills