cli-anything-shotcut

Was macht cli-anything-shotcut?

Eine zustandsbehaftete Kommandozeilen-Schnittstelle für die Videobearbeitung, basierend auf dem MLT-XML-Format. Entwickelt für KI-Agenten und Power-User, die Shotcut-Projekte ohne grafische Oberfläche erstellen und bearbeiten möchten.

Installation

Diese CLI wird als Teil des Pakets cli-anything-shotcut installiert:

pip install cli-anything-shotcut

Voraussetzungen:

• Python 3.10+
• melt (MLT CLI) — erforderlich für Rendern und Wiedergabe
• ffmpeg / ffprobe — erforderlich für Medienanalyse
• shotcut muss auf dem System installiert sein

Verwendung

Grundlegende Befehle

# Hilfe anzeigen
cli-anything-shotcut --help

# Interaktiven REPL-Modus starten
cli-anything-shotcut

# Ein neues Projekt erstellen
cli-anything-shotcut project new -o project.json

# Mit JSON-Ausgabe (für Agenten)
cli-anything-shotcut --json project info -p project.json

REPL-Modus

Wenn ohne Unterbefehl aufgerufen, startet die CLI eine interaktive REPL-Sitzung mit Unterstützung für Rückgängig/Wiederholen:

cli-anything-shotcut
# oder mit einem Projekt:
cli-anything-shotcut --project my_project.mlt

REPL-Befehle

Workflow: Zuerst immer media import, um eine clip_id zu erhalten, dann add-clip verwenden, um den Clip auf der Timeline zu platzieren.

Projekt & Sitzung:

• new [profile] — Neues Projekt erstellen (Standard: hd1080p30)
• open <path> — .mlt-Datei öffnen
• save [path] — Projekt speichern
• info — Projektinformationen anzeigen
• xml — Roh-MLT-XML ausgeben
• status — Sitzungsstatus anzeigen
• undo / redo — Operationsverlauf navigieren

Medien (Zwei-Schritt-Modell):

• media import <file> [--caption name] — Datei in den Projekt-Bin importieren, gibt clip_id zurück (z. B. clip0)
• media — Alle importierten Medien auflisten
• probe <file> — Eine Mediendatei analysieren

Timeline:

• add-track <video|audio> [name] — Eine Spur hinzufügen
• tracks — Alle Spuren auflisten
• show — Visuelle Timeline-Übersicht
• add-clip <clip_id> <track> [in] [out] [--at time] — Importierten Clip auf Spur platzieren
• clips <track> — Clips auf einer Spur auflisten
• remove-clip <track> <clip> — Einen Clip entfernen
• trim <track> <clip> [--in tc] [--out tc] — Clip trimmen
• split <track> <clip> <at> — Clip an einem Timecode teilen

Filter:

• list-filters [video|audio] — Verfügbare Filter durchsuchen
• filter-info <name> — Filterdetails anzeigen
• add-filter <name> [--track n] [--clip n] [key=val ...] — Filter zu Clip, Spur oder global hinzufügen
• filters [--track n] [--clip n] — Aktive Filter auflisten
• remove-filter <idx> [--track n] [--clip n] — Filter nach Index entfernen
• set-filter <idx> <param> <value> [--track n] [--clip n] — Filterparameter setzen
• volume-envelope [--track n] [--clip n] TIME=LEVEL ... — Keyframe-basierte Lautstärkenhüllkurve (z. B. 00:00:00.000=1.0 00:00:03.000=0.35)
• duck [--track n] [--clip n] START..END ... — Ducking-Hüllkurve (z. B. 00:00:06.000..00:00:09.000)

Export:

• presets — Export-Voreinstellungen auflisten
• render <output> [--preset name] — In Videodatei rendern

Befehlssgruppen

Projekt

Projektverwaltung: neu, öffnen, speichern, info.

Befehl	Beschreibung
new	Ein neues leeres Projekt erstellen
open	Eine vorhandene .mlt-Projektdatei öffnen
save	Das aktuelle Projekt speichern
info	Detaillierte Projektinformationen anzeigen
profiles	Verfügbare Videoprofile auflisten
xml	Das rohe MLT-XML des aktuellen Projekts ausgeben

Timeline

Timeline-Operationen: Spuren, Clips, Trimmen.

Befehl	Beschreibung
show	Die Timeline-Übersicht anzeigen
tracks	Alle Spuren auflisten
add-track	Eine neue Spur zur Timeline hinzufügen
remove-track	Eine Spur nach Index entfernen
add-clip	Einen importierten Clip per clip_id zu einer Spur hinzufügen; unterstützt --at für absolute Platzierung
remove-clip	Einen Clip von einer Spur entfernen
move-clip	Einen Clip zwischen Spuren oder Positionen verschieben
trim	Die In/Out-Punkte eines Clips trimmen
split	Einen Clip am angegebenen Timecode in zwei teilen
clips	Alle Clips auf einer Spur auflisten
add-blank	Eine Lücke zu einer Spur hinzufügen
set-name	Den Anzeigenamen einer Spur setzen
mute	Eine Spur stummschalten oder die Stummschaltung aufheben
hide	Eine Videospur ein- oder ausblenden

Filtergruppe

Filteroperationen: hinzufügen, entfernen, Effekte konfigurieren.

Befehl	Beschreibung
list-available	Alle verfügbaren Filter auflisten
info	Detaillierte Informationen über einen Filter und seine Parameter anzeigen
add	Einen Filter zu einem Clip, einer Spur oder global hinzufügen
remove	Einen Filter nach Index entfernen
set	Einen Parameter an einem Filter setzen
list	Aktive Filter auf einem Ziel auflisten
volume-envelope	Eine neue Keyframe-basierte Lautstärkenhüllkurve auf einer Spur oder einem Clip erstellen oder ersetzen
duck	Eine praktische Ducking-Hüllkurve über einem oder mehreren Zeitfenstern erstellen

Medien

Medienoperationen: analysieren, auflisten, Dateien prüfen.

Befehl	Beschreibung
import	Eine Mediendatei in den Projekt-Bin importieren
probe	Die Eigenschaften einer Mediendatei analysieren
list	Alle Medienclips im aktuellen Projekt auflisten
check	Alle Mediendateien auf Existenz prüfen
thumbnail	Ein Vorschaubild aus einer Videodatei generieren

Export

Export-/Renderoperationen.

Befehl	Beschreibung
presets	Verfügbare Export-Voreinstellungen auflisten
preset-info	Details einer Export-Voreinstellung anzeigen
render	Das Projekt in eine Videodatei rendern

Übergangsgruppe

Übergangsoperationen: Überblendung, Wischblende und andere Übergänge.

Befehl	Beschreibung
list-available	Alle verfügbaren Übergangstypen auflisten
info	Detaillierte Informationen über einen Übergangstyp anzeigen
add	Einen Übergang zwischen zwei Spuren hinzufügen
remove	Einen Übergang nach Index entfernen
set	Einen Parameter an einem Übergang setzen
list	Alle Übergänge auf der Timeline auflisten

Composite-Gruppe

Compositing: Überblendungsmodi, Bild-in-Bild, Deckkraft.

Befehl	Beschreibung
blend-modes	Alle verfügbaren Überblendungsmodi auflisten
set-blend	Den Überblendungsmodus für eine Spur setzen
get-blend	Den aktuellen Überblendungsmodus einer Spur abrufen
set-opacity	Die Deckkraft einer Spur setzen (0.0-1.0)
pip	Die Bild-in-Bild-Position für einen Clip setzen

Sitzung

Sitzungsverwaltung: Status, Rückgängig, Wiederholen.

Befehl	Beschreibung
status	Aktuellen Sitzungsstatus anzeigen
undo	Die letzte Operation rückgängig machen
redo	Die letzte rückgängig gemachte Operation wiederholen
save	Sitzungsstatus auf Datenträger speichern
list	Alle gespeicherten Sitzungen auflisten

Vorschau

Vorschaupakete und Live-Vorschau-Sitzungen für iterative Bearbeitungsprüfungen.

Befehl	Beschreibung
preview recipes	Vorschau-Rezepte auflisten
preview capture	Ein niedrig aufgelöstes Vorschaupaket rendern
preview latest	Das neueste vorhandene Paket zurückgeben
preview live start	Eine Live-Vorschau-Sitzung starten und das erste Paket veröffentlichen
preview live push	Ein neues Paket in die Live-Sitzung veröffentlichen
preview live status	Aktuellen Live-Sitzungsstatus abfragen, ohne zu rendern
preview live stop	Die Live-Sitzung beenden, ohne Artefakte zu löschen

Typischer Inhalt eines quick-Pakets:

• preview.mp4
• mehrere Stichproben-Bilder
• Mittelpunkt hero.png
• summary.json mit Projektdaten

Poll-Modus wird unterstützt:

cli-anything-shotcut --json --project edit.mlt preview live start --recipe quick --mode poll --source-poll-ms 500

preview live status --json enthält Sitzungsreferenzen und eine kompakte trajectory_summary, damit Agenten preisgünstig die letzten wenigen Veröffentlichungen verstehen können.

Anzeiger-Befehle:

cli-hub previews inspect /path/to/bundle-or-session
cli-hub previews html /path/to/bundle-or-session -o page.html
cli-hub previews watch /path/to/session --open
cli-hub previews open /path/to/bundle-or-session

Beispiele

Ein neues Projekt erstellen

Erstellen Sie eine neue Shotcut-Projektdatei.

cli-anything-shotcut project new -o myproject.json
# Oder mit JSON-Ausgabe für programmatische Nutzung
cli-anything-shotcut --json project new -o myproject.json

Interaktive REPL-Sitzung

Starten Sie eine interaktive Sitzung mit Unterstützung für Rückgängig/Wiederholen.

cli-anything-shotcut
# Geben Sie Befehle interaktiv ein
# Verwenden Sie 'help', um verfügbare Befehle zu sehen
# Verwenden Sie 'undo' und 'redo' für die Verlaufsnavigation

Projekt exportieren

Exportieren Sie das Projekt in ein endgültiges Ausgabeformat.

cli-anything-shotcut --project myproject.json export render output.mp4 --overwrite

Deterministische Timeline-Rekonstruktion

Für Wiederaufbauten bevorzugen Sie die absolute Platzierung gegenüber einem append-only Clip-Einfügen:

cli-anything-shotcut --project myproject.mlt media import intro.mp4
cli-anything-shotcut --project myproject.mlt timeline add-clip clip0 \
  --track 1 --in 00:00:00.000 --out 00:00:04.000 --at 00:00:00.000

cli-anything-shotcut --project myproject.mlt media import broll.mp4
cli-anything-shotcut --project myproject.mlt timeline add-clip clip1 \
  --track 1 --in 00:00:10.000 --out 00:00:16.000 --at 00:00:08.000

• --at fügt automatisch Lücken ein, wenn die Zielzeit auf leeren Raum fällt.
• Die CLI lehnt Überlappungen mit einem vorhandenen Clip ab.
• Bevorzugen Sie explizite --in- und --out-Werte, damit spätere absolute Platzierungen eindeutig bleiben.

Audio-Automation

cli-anything-shotcut --project myproject.mlt filter volume-envelope \
  --track 2 \
  --point 00:00:00.000=1.0 \
  --point 00:00:03.000=0.35 \
  --point 00:00:05.000=1.0

cli-anything-shotcut --project myproject.mlt filter duck \
  --track 2 \
  --window 00:00:06.000..00:00:09.000 \
  --window 00:00:15.000..00:00:18.000 \
  --normal 1.0 --duck 0.25

Die CLI verwaltet den Sitzungsstatus mit:

• Rückgängig/Wiederholen: Bis zu 50 Ebenen Verlauf
• Projektpersistenz: Speichern/Laden des Projektstatus als JSON
• Sitzungsverfolgung: Änderungen und Modifikationen nachverfolgen

Ausgabeformate

Alle Befehle unterstützen zwei Ausgabemodi:

• Menschenlesbar (Standard): Tabellen, Farben, formatierter Text
• Maschinenlesbar (--json-Flag): Strukturiertes JSON für die Verarbeitung durch Agenten

# Menschliche Ausgabe
cli-anything-shotcut project info -p project.json

# JSON-Ausgabe für Agenten
cli-anything-shotcut --json project info -p project.json

Für KI-Agenten

Bei programmatischer Nutzung dieser CLI:

1. Verwenden Sie immer das --json-Flag für analysierbare Ausgaben
2. Prüfen Sie Rückgabecodes – 0 für Erfolg, ungleich 0 für Fehler
3. Analysieren Sie stderr für Fehlermeldungen im Fehlerfall
4. Verwenden Sie absolute Pfade für alle Dateioperationen
5. Überprüfen Sie die Existenz von Ausgaben nach Exportoperationen
6. Bevorzugen Sie timeline add-clip --at beim Wiederherstellen eines bekannten Schnitts
7. Prüfen Sie finale Render nach Schlüsselbild-basierter Lautstärke- oder Ducking-Änderungen
8. Verwenden Sie preview capture oder preview live ..., um Tempo, Schnitte und Filtereffekte visuell zu validieren
9. Lesen Sie zurückgegebene Artefaktpfade wie hero.png und preview.mp4; JSON-Payloads referenzieren Dateien auf der Festplatte
10. Verwenden Sie preview live status --json, bevor Sie die vollständige trajectory.json lesen
11. Verwenden Sie cli-hub previews ... nur, um vorhandene Pakete oder Live-Sitzungen zu inspizieren/zu öffnen

Weitere Informationen

• Vollständige Dokumentation: Siehe README.md im Paket
• Testabdeckung: Siehe TEST.md im Paket
• Methodik: Siehe HARNESS.md im cli-anything-plugin

Version

1.0.0