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)
- Stellen Sie sicher, dass die MCP-Server
effectcraftundfilmcraftin der aktuellen Sitzung verfügbar sind (oder wechseln Sie sauber zu den CLIseffectcraft-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.effectcraftoder natives Binary, im Headless- oder Bridge-Modus).
- Falls sie fehlen, erfinden Sie keine Aufrufe: Konsultieren Sie references/mcp-and-commands.md für die genaue Konfiguration (Flatpak Linux
- Achtung Flatpak (Linux): Standardmäßig hat
ai.storyteller.effectcraftnur Zugriff aufxdg-documents,xdg-picturesundxdg-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 - 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
| Bereich | EffectCraft (.ecproj) | FilmCraft (.fcproj) |
|---|---|---|
| Hauptverwendung | Animierte 2D-Szenen (V01..Vnn), Liedtexte auf unabhängigen transparenten Layern (L01..Lnn), kinetische Titel, Partikel, 2D/3D-Compositing | Hauptschnitt mit mehreren Spuren (V1 Szenen + V2 RGBA-Texte + A1 Master-Audio), Frame-genaue Synchronisation, Überblendungen, globale Farbkorrektur, Doppelexport (mit Texten + Clean) |
| Erstellung | comp.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 Synchronisation | Genaue Referenzpunkte aus audio/lyrics_timing.json + Hören nach Gehör; optional keys.audioToKeyframes nur, wenn ein gemessener reaktiver Effekt gewünscht ist | markers.add für jeden Abschnitt, letzten Akzent und Schwarzschnitt; Frame-genaue Platzierung (frame: f0) |
| Gestaltung & Farbgebung | Layer-Stile, Masken, Bézier-Kurven, Leuchteffekte, Schlagschatten, Vorkompositionen (layer.precompose) | Lumetri Color (lumetri.applyPreset, lumetri.setLook, lumetri.applyMatch), sequence.colorSettings, sequence.applyVideoTransition |
| Audio | Kein 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 mitimage_sequence: true. - Für Alpha verboten:
H264,HevcundAv1unterstützen keinen Alphakanal (alpha: false).
- Empfohlen (einzelne Datei): QuickTime Apple ProRes 4444 (
- 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 sindhevcundav1möglicherweise nicht verfügbar.)
- Web/Ausstrahlung:
Auflösungs-, Bildraten- (FPS) und Farbraumabstimmung
- Von Anfang an festlegen ein eindeutiges Paar
(width, height, fps), das zwischen EffectCraft (comp.new) und FilmCraft (file.newSequence) geteilt wird, z. B.1920×1080mit30oder24fps. - 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. - Farbraum:
workingSpace: "rec709"in SDR in beiden Programmen (file.projectSettingsin EffectCraft,sequence.colorSettingsin FilmCraft;autoToneMap: truebei HDR/Log-Material). - Zeitumrechnung: EffectCraft arbeitet in Sekunden (
f64); FilmCraft verwendet Ticks (254016000000Ticks =1s) und akzeptiert auchframe/secondsintimeline.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
- Messen Sie die originale Spur immer mit 44,1 kHz (
hop = 441= exakt 10.000 ms) überaudio_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). - Ü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.
- 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: Grenzenstart_ms/end_ms, frame-genau ausgerichtet.phrases:start_ms,end_msunddisplay_end_ms(bei Bedarf um+250bis+600 msverlängert, damit das letzte Wort lesbar bleibt, auch wenn die Einstellung oder der Abschnitt wechselt).type: "lead"für den Hauptgesang undtype: "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
- 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), wenndisplay_end_mseinen Abschnittsschnitt überbrückt. - Dedizierte transparente Spur: Generieren Sie die Texte in separaten Kompositionen
L01..Lnn(unter Auslassung rein instrumentaler Abschnitte), die als ProRes 4444 RGBA gerendert und aufV2in FilmCraft abgelegt werden. - Text im Set auf
V1belassen: Schilder, Bildschirme, Kopien, Tafeln bleiben in den SzenenV01..Vnn. - Streng identischer Doppelexport: Exportieren Sie die Version mit Texten (
V2aktiviert), deaktivieren Sie dannV2(timeline.setTrack {"track": "V2", "enabled": false}), um die Clean-Version mit zu 100 % identischem Schnitt und Audio zu exportieren, und aktivieren SieV2vor dem endgültigen Speichern der.fcproj-Datei wieder.
D. Visuelle Aktionen während instrumentaler Passagen (Keine generischen Audiokurven)
- Verzichten Sie auf generische visuelle Krücken: Keine Audiokurven, keine Oszilloskop-Zickzacklinien, keine dekorativen schwebenden Kreise bei Intros, Soli oder Zwischenspielen.
- 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.
- Halten Sie die Einstellungen zwischen den Akzenten: Lassen Sie zwischen zwei starken Schlägen ein klares und stabiles Bild, damit die Aktion lesbar bleibt.
- 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
- 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. - 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. - 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)
- Erstellen Sie einen kurzen Schnittplan (Tabelle Zeit / Abschnitt / Ort & Bildausschnitt / gezeichnete visuelle Aktion / Textbehandlung).
- 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
- Bauen Sie die 2D-Szenen (
V01..Vnn) gemäß den Regeln für Ankerpunkte, neutrales Parenting und Stapelreihenfolge aus craft-2d-animation (mit Hilfe vonec_runtime.py). - Generieren Sie die transparenten Textkompositionen (
L01..Lnn, ohne Instrumentalpassagen) direkt ausaudio/lyrics_timing.jsonüberlyrics_overlay.py. - Schnelle Prüfung durch Screenshots (
render-frame --max-side 960) von Schlüsseleinstellungen (und--transparentfür Texte), um Überlappungen oder Ankerverschiebungen sofort vor dem Videorendering zu korrigieren. - 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.
- Vollständiges Low-Power-Rendering nach
./renders_vfx/überrender_ec_batch.sh(sequenziell 1 Rendering nach dem anderen, ProRes HQ RGB fürV*, ProRes 4444 RGBA fürL*, automatische Wiederaufnahme überffprobe). - Speichern Sie
projects/<clip>.ecproj.
Schritt 4 — Zusammenbau & Doppelexport in FilmCraft
- Bauen Sie die Rec.709-Sequenz über
assemble_filmcraft.py(oder über MCPfile.newProject,file.newSequence,media_import,timeline.place,markers.add) zusammen:A1: Originales Master-Audio intakt (volumeDb: 0.0)V1:V01..Vnn.movplatziert an ihrem genauen Frame (frame: f0)V2:L01..Lnn.mov(ProRes 4444 RGBA) platziert an denselben genauen Frames (audio: false)
- Überprüfen Sie die Sequenz (
inspect sequence) + rendern Sie einigeV1+V2-Composite-Frames undV1allein, um den Alpha-Ausschnitt und das Vorhandensein des diegetischen Texts in der Clean-Version zu bestätigen. - Exportieren Sie die Version mit Texten (
*_lyrics.mp4), deaktivieren SieV2, exportieren Sie die Clean-Version (*_clean.mp4), aktivieren Sie dannV2wieder und speichern Sieprojects/<clip>.fcproj.
Schritt 5 — Abschließendes obligatorisches Audit (Mit Ton + Ohne Ton)
- 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. - 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. - Präsentieren Sie die Lieferobjekte und listen Sie explizit die in
lyrics_timing.jsonmit"uncertain": truemarkierten Referenzpunkte auf.
5. Geteilte T3-Code-Tools & Abhängigkeiten
Die wiederverwendbaren Tools befinden sich in ~/.t3/shared/craft-video/:
| Tool | Pfad | Verwendung im Musikclip |
|---|---|---|
| 44,1-kHz-Audioanalyse & -Segmentierung | ~/.t3/shared/craft-video/audio_cues.py | Dauer-, Transienten- & Enddetektion (analyze), überlappende Hörsegmente (slice), Ausgabe von Markern |
| Lyrics-Overlay-Generator | ~/.t3/shared/craft-video/lyrics_overlay.py | Liest lyrics_timing.json, erzeugt EffectCraft-Kompositionen L* & validiert die JSON-Struktur |
| Batch-Rendering | ~/.t3/shared/craft-video/render_ec_batch.sh | Sequenzielles Rendering von V* & L* in ProRes, Wiederaufnahme bei Unterbrechung |
| FilmCraft-Assembler | ~/.t3/shared/craft-video/assemble_filmcraft.py | Erzeugt Sequenz, platziert Clips auf V1/V2/A1, fügt Marker hinzu, Prüfung (probe) |
| Gemeinsame 2D-Animationsregeln | ../craft-2d-animation/SKILL.md | Anker, Parenting, Stapelreihenfolge, Posenwechsel |
6. Wichtige Konventionen & Fallstricke
- Keine unbestimmten Rundungen: Alle Zeitwerte (ms, Frames, samples) müssen deterministisch aus der gemessenen Master-Audiodatei stammen. Verwenden Sie
audio_cues.py analyzemithop=441; jeder anderehop-Wert führt bei typischen Musikvideolängen zu inkonsistentem Timing. - 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". - Einzelner Referenzpunkt für den finalen Schwarzschnitt: Verwenden Sie den letzten starken Akzent (
last_accent_ms) auslyrics_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. - Clean-Version mit lesbarem diegetischem Text: Wenn
V01..VnnTexte 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-SpurenV2, nicht die Szenenebene. - 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. - 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. - Hörprüfung ist nicht verhandelbar: Das Skript
audio_cues.py analyzeliefert 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 inlyrics_timing.jsoneintragen. - 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
- 2D-Animationsregeln: craft-2d-animation
- MCP-Befehlsreferenz: references/mcp-and-commands.md
- Geteilte T3-Code-Tools:
~/.t3/shared/craft-video/