e1dred/filmcraft

Was macht filmcraft?

Aktualisierungen: Wenn dieser Ordner eine Datei .installed-from enthält (die beim Kopieren aus dem Repository geschrieben wurde), führen Sie git ls-remote https://gitlab.com/e1dred/agent-skills.git HEAD einmal pro Sitzung aus. Nehmen Sie den Hash aus der Zeile, die genau auf HEAD endet; unterscheidet er sich vom Dateiinhalt, teilen Sie dem Benutzer mit, dass eine neuere Version existiert, und bieten Sie an, sie zu aktualisieren (siehe "Aktualisieren" unter https://gitlab.com/e1dred/agent-skills/-/blob/main/INSTALL.md, das lokale Änderungen zusammenführen kann); aktualisieren Sie niemals ohne Rückfrage. Vergleichen Sie die Hashes nach dem Entfernen von Leerzeichen. Bei fehlender Datei, einem Klon oder Symlink oder fehlender Netzwerkverbindung (leere Ausgabe oder Fehler von git ls-remote): stillschweigend überspringen.

Feldnotizen aus ersten Headless-Aufgaben, zuletzt getestet mit FilmCraft 0.17.1 (Linux AppImage). FilmCraft ist ein früher Alpha-Videoeditor im Premiere-Stil in Rust. Jeder Menüpunkt und jede Schaltfläche ist ein Engine-Befehl; die CLI, der MCP-Server und der Steuerkanal der App führen dieselben Befehle aus. Wenn filmcraft-cli --version neuer ist, überprüfen Sie alles hier erneut, bevor Sie sich darauf verlassen.

Einrichtung

• CLI: Entpacken Sie sie aus dem AppImage (filmcraft.appimage --appimage-extract, kopieren Sie usr/bin/filmcraft-cli an einen stabilen Ort); in sich geschlossen, kein Fenster. Führen Sie --version niemals auf dem AppImage selbst aus.
• Headless: filmcraft-cli --project p.fcproj exec <id> key=value …; Skripte sind JSON-Zeilen und behalten eine Sitzung bei: filmcraft-cli --project p.fcproj run script.jsonl [--save] mit Zeilen {"id":"…","params":{…}}, oder eigenständig filmcraft-cli run nach file.newProject. Unterbefehle: commands, describe, inspect, import, export, render, probe.
• Live-App: filmcraft --control 9876 (oder FILMCRAFT_CONTROL_PORT); der Listener benötigt FILMCRAFT_CONTROL_TOKEN (64 Hexadezimalzeichen) in der Umgebung – ohne bleibt er geschlossen. Brücke mit filmcraft-cli mcp --bridge 127.0.0.1:9876.
• MCP: filmcraft-cli mcp (Headless) oder --bridge (Live).

Wo was zu finden ist

Lesen Sie die Datei, die zur Aufgabe passt; jede listet die enthaltenen Abschnitte auf. Verwenden Sie grep -n auf reference/, um eine Befehls-ID zu finden.

Datei in reference/	Lesen für	Abschnitte
projects-and-timeline.md	Projekte, Medienimport, Sequenzen, Abspielkopf, Rasiermesser und Trimmen, Marker, Speichern, Übergänge, Videoeffekte und Keyframes, Standbilder, Projektnotizen	Projekte und Medien; Sequenzen; Schneiden und Trimmen; Marker und Speichern; Übergänge; Videoeffekte und Keyframes; Standbilder, Auswahl und Projektnotizen; Andere Bearbeitungswerkzeuge
titles-and-graphics.md	Text- und Formebenen, Größe/Anpassung an kleine Frames, Zurücklesen von Ebenen, vertikaler Text und importierte Bilder	Titel; Größenanpassung und Anpassung; Ebeneneigenschaften; Andere Ebenenwerkzeuge
audio-mixer.md	Mixer-Kanäle, Werte, Submixe, Einschleifwege und Sendewege; Clip-Verstärkung und Essential Sound	Mixer; Clip-Audio
captions.md	Untertitelspuren, Hinzufügen/Bearbeiten/Verschieben von Untertiteln, SRT-Import und -Export	Untertitelspuren und SRT
export.md	Export-Voreinstellungen und -Formate, die Export-Warteschlange, MP4/GIF-Export, Einzelbild-Exporte, Austausch-Exporte, Analyse	Voreinstellungen; Exportieren; Voreinstellungen und die Export-Warteschlange; Standbilder; Analyse
command-catalogue.md	Jede andere Befehls-ID nach Familie (Clip, Timeline, Sequenz, Trimmen, Grafiken, Bearbeiten, Datei, Projekt, Multicam, Quelle, Einstellungen, Tastenkürzel, …), jede als verifiziert markiert (JSON-Pfad alt → neu), ein Ergebnis zurückgegeben, ausgeführt oder mit Grund verweigert; die Einrichtung, die auswahlabhängige Befehle freischaltet	Ein Abschnitt pro Familie
live-app.md	Steuerung der laufenden App über --bridge: die ui_*-Werkzeuge, was nur live funktioniert, Ausführung auf einem versteckten Bildschirm	Verbindung; Was die Live-App hinzufügt
newer-commands.md	Was jede Version hinzugefügt oder geändert hat	0.17.0; 0.17.1
log.md	Datiertes Protokoll, was wann getestet wurde	Protokoll

CLI-Grundlagen (verifiziert)

filmcraft-cli commands --json                    # 716 Befehle: id, label, menu, params, enabled
filmcraft-cli describe file.import               # Parameterdokumentation für einen Befehl
filmcraft-cli --project p.fcproj inspect         # {project:{…}, sequence:{…}} als JSON
filmcraft-cli import clip.mp4 --project p.fcproj
filmcraft-cli --project p.fcproj export out.mp4 --scale 0.5 --quality 70
filmcraft-cli --project p.fcproj render --seconds 2 --out frame.png
filmcraft-cli probe clip.mp4                     # Art, Dauer (Ticks), Video/Audio-Stream-Details

• Ein JSONL-Skript behält den Zustand bei: file.newProject → file.import {"paths":["clip.mp4"]} → {"items":[1]} → file.newSequenceFromClip {"items":[1]} → {"clips":[6,7],"sequence":4} → … → file.saveAs {"path":"p.fcproj"}.
• Übergeben Sie --project bei jedem späteren CLI-Aufruf: Ohne diesen ist jeder Aufruf eine neue Sitzung.

Fallstricke

• Zeiten sind Ticks, keine Frames: Die Sequenz meldet 762.048.000.000 für 3 s (254.016.000.000 Ticks/s); playhead.set akzeptiert seconds, frame, time oder timecode und rastet auf den nächsten Frame ein (1,5 s → Frame 37).
• Eine Textebene in Standardgröße läuft auf einem kleinen Frame über. graphics.newText standardmäßig auf 100 px: Bei einer 320×180-Sequenz zeichnete "Hallo FilmCraft" mit size:48 334,7 px breit ab x=40 und wurde am rechten Rand abgeschnitten. Passen Sie es an, indem Sie size setzen (~32 → 223 px breit; in einem Render überprüft). Absatztext mit box:[w,h] umbricht, aber die Box SCHNEIDET Zeilen ab, die nicht in ihre Höhe passen: box:[240,60] bei Größe 40 zeigte nur "Hallo" (die zweite Zeile wurde abgeschnitten), machen Sie die Box also hoch genug für jede Zeile (etwa 1,3 × Größe pro Zeile).
• Ripple-Schnitte schlagen über eine synchronverriegelte Spur hinweg fehl: timeline.trim mit mode:"ripple" antwortete "this edit would break sync: V2 is sync-locked and has a clip in the way" wenn ein Titel auf V2 lag. Sperren/entsperren Sie die andere Spur zuerst oder trimmen Sie ohne Ripple.
• probe --image-sequence akzeptiert nur nummerierte Standbilder; bei einem Film gibt es einen Fehler.
• effects.addKeyframe headless mit einer rohen mediaTime tat nichts ({added:false, mediaTime:0}; 0.17.0), aber in der Live-App fügte {clip, effect:"opacity", param:"opacity", seconds:1.5, value:40} einen hinzu (Keyframes 5 → 6; die Zeit rastet auf einen Frame ein: 624699432000). Headless verschieben Sie den Abspielkopf und verwenden Sie effects.toggleAnimation, oder graphics.set {…,"keyframe":true} für Titelseigenschaften.
• mixer.addInsert benötigt eine echte Audioeffekt-ID (hard_limiter, von effects.list {"kind":"Audio"}), keine Bezeichnung wie volume; mixer.addSend benötigt die Submix-ref von mixer.addSubmix im selben Durchlauf.
• graphics.*-Befehle benötigen einen Titel in derselben Sitzung: führen Sie zuerst graphics.newText im selben Skript aus, dann funktionieren graphics.alignFrame.*, nudge*, fontSize*, leading* headless (lesen Sie graphics.list {clip} → layers[0]). Ohne einen antworten sie "no graphic clip". graphics.deleteLayer wurde nur live akzeptiert (kein Rücklesen).
• Die Auswahl überlebt kein Speichern/Neuöffnen: setzen Sie project.select {items:[id]} / timeline.select in dasselbe Skript wie den Befehl, der sie benötigt ("select an item in the Project panel", "no clips selected").
• FCPXML-Export kann einen Titel verlieren: file.exportInterchange {"format":"fcpxml"} meldete den Grafikclip "not supported", während die Datei noch geschrieben wurde; lesen Sie den Bericht, bevor Sie einem Austauschexport vertrauen.
• --demo öffnet das integrierte Demoprojekt: es inspiziert und rendert (einen 1920×1080-Frame bei 1 s), exportierte soweit getestet einwandfrei; fehlendes Medium wird als Platzhalter-Frames exportiert, es sei denn, --allow-offline akzeptiert sie.
• file.exportMedia wartet auf seine Datei, es sei denn, "wait":false; der CLI export wartet immer.

Vor dem Melden verifizieren

inspect sequence (Clip-Start/-Ende in Frames, Spuren, Übergänge, Effekte), probe für die Dauer und Codecs der exportierten Datei, und render einen Frame zu den interessanten Zeiten, um ihn anzusehen. Frame-Anzahl: 3 s bei 25 fps = 75 Frames; ein Ripple-Trim von -10 Frames ergab 65.