cli-anything-shotcut

Que fait cli-anything-shotcut ?

Une interface en ligne de commande avec état pour le montage vidéo, basée sur le format MLT XML. Conçue pour les agents IA et les utilisateurs avancés qui souhaitent créer et éditer des projets Shotcut sans interface graphique.

Installation

Cette CLI est installée dans le cadre du package cli-anything-shotcut :

pip install cli-anything-shotcut

Prérequis :

• Python 3.10+
• melt (CLI MLT) — nécessaire pour le rendu et la lecture
• ffmpeg / ffprobe — nécessaires pour l'analyse des fichiers médias
• shotcut doit être installé sur votre système

Utilisation

Commandes de base

# Afficher l'aide
cli-anything-shotcut --help

# Lancer le mode REPL interactif
cli-anything-shotcut

# Créer un nouveau projet
cli-anything-shotcut project new -o project.json

# Exécuter avec sortie JSON (pour les agents)
cli-anything-shotcut --json project info -p project.json

Mode REPL

Lorsqu'elle est invoquée sans sous-commande, la CLI entre dans une session REPL interactive avec support de l'annulation/rétablissement :

cli-anything-shotcut
# ou avec un projet :
cli-anything-shotcut --project my_project.mlt

Commandes REPL

Flux de travail : Importez toujours les médias en premier avec media import pour obtenir un clip_id, puis utilisez add-clip pour le placer sur la timeline.

Projet et session :

• new [profile] — Créer un nouveau projet (par défaut : hd1080p30)
• open <path> — Ouvrir un fichier .mlt
• save [path] — Enregistrer le projet
• info — Afficher les informations du projet
• xml — Afficher le code XML MLT brut
• status — Afficher l'état de la session
• undo / redo — Naviguer dans l'historique des opérations

Médias (modèle en deux étapes) :

• media import <file> [--caption nom] — Importer un fichier dans le bac du projet, retourne un clip_id (ex. clip0)
• media — Lister tous les médias importés
• probe <file> — Analyser un fichier média

Timeline :

• add-track <video|audio> [nom] — Ajouter une piste
• tracks — Lister toutes les pistes
• show — Aperçu visuel de la timeline
• add-clip <clip_id> <track> [in] [out] [--at time] — Placer un clip importé sur une piste
• clips <track> — Lister les clips d'une piste
• remove-clip <track> <clip> — Supprimer un clip
• trim <track> <clip> [--in tc] [--out tc] — Rogner un clip
• split <track> <clip> <at> — Diviser un clip à un timecode donné

Filtres :

• list-filters [video|audio] — Parcourir les filtres disponibles
• filter-info <nom> — Afficher les détails d'un filtre
• add-filter <nom> [--track n] [--clip n] [key=val ...] — Ajouter un filtre à un clip, une piste ou globalement
• filters [--track n] [--clip n] — Lister les filtres actifs
• remove-filter <idx> [--track n] [--clip n] — Supprimer un filtre par son index
• set-filter <idx> <param> <valeur> [--track n] [--clip n] — Définir un paramètre de filtre
• volume-envelope [--track n] [--clip n] TIME=NIVEAU ... — Enveloppe de volume avec images clés (ex. 00:00:00.000=1.0 00:00:03.000=0.35)
• duck [--track n] [--clip n] DEBUT..FIN ... — Enveloppe de ducking (ex. 00:00:06.000..00:00:09.000)

Export :

• presets — Lister les préréglages d'export
• render <sortie> [--preset nom] — Effectuer le rendu vers un fichier vidéo

Groupes de commandes

Projet

Gestion de projet : nouveau, ouvrir, enregistrer, informations.

Commande	Description
new	Créer un nouveau projet vierge
open	Ouvrir un fichier projet .mlt existant
save	Enregistrer le projet en cours
info	Afficher les informations détaillées du projet
profiles	Lister les profils vidéo disponibles
xml	Afficher le code XML MLT brut du projet en cours

Timeline

Opérations sur la timeline : pistes, clips, rognage.

Commande	Description
show	Afficher l'aperçu de la timeline
tracks	Lister toutes les pistes
add-track	Ajouter une nouvelle piste à la timeline
remove-track	Supprimer une piste par son index
add-clip	Ajouter un clip importé à une piste via son clip_id ; prend en charge --at pour un placement absolu
remove-clip	Supprimer un clip d'une piste
move-clip	Déplacer un clip entre pistes ou positions
trim	Rogner les points d'entrée/sortie d'un clip
split	Diviser un clip en deux au timecode donné
clips	Lister tous les clips d'une piste
add-blank	Ajouter un espace vide à une piste
set-name	Définir le nom d'affichage d'une piste
mute	Couper ou rétablir le son d'une piste
hide	Masquer ou afficher une piste vidéo

Groupe Filtres

Opérations sur les filtres : ajout, suppression, configuration des effets.

Commande	Description
list-available	Lister tous les filtres disponibles
info	Afficher des informations détaillées sur un filtre et ses paramètres
add	Ajouter un filtre à un clip, une piste ou globalement
remove	Supprimer un filtre par son index
set	Définir un paramètre sur un filtre
list	Lister les filtres actifs sur une cible
volume-envelope	Créer ou remplacer une enveloppe de volume avec images clés sur une piste ou un clip
duck	Construire une enveloppe de ducking pratique sur une ou plusieurs fenêtres temporelles

Médias

Opérations sur les médias : analyse, liste, vérification des fichiers.

Commande	Description
import	Importer un fichier média dans le bac du projet
probe	Analyser les propriétés d'un fichier média
list	Lister tous les clips médias du projet en cours
check	Vérifier l'existence de tous les fichiers médias
thumbnail	Générer une miniature à partir d'un fichier vidéo

Export

Opérations d'export/rendu.

Commande	Description
presets	Lister les préréglages d'export disponibles
preset-info	Afficher les détails d'un préréglage d'export
render	Effectuer le rendu du projet vers un fichier vidéo

Groupe Transitions

Opérations sur les transitions : fondu, wipe et autres transitions.

Commande	Description
list-available	Lister tous les types de transitions disponibles
info	Afficher des informations détaillées sur un type de transition
add	Ajouter une transition entre deux pistes
remove	Supprimer une transition par son index
set	Définir un paramètre sur une transition
list	Lister toutes les transitions de la timeline

Groupe Composition

Composition : modes de fusion, incrustation, opacité.

Commande	Description
blend-modes	Lister tous les modes de fusion disponibles
set-blend	Définir le mode de fusion d'une piste
get-blend	Obtenir le mode de fusion actuel d'une piste
set-opacity	Définir l'opacité d'une piste (0.0-1.0)
pip	Définir la position d'incrustation (picture-in-picture) pour un clip

Session

Gestion de session : état, annulation, rétablissement.

Commande	Description
status	Afficher l'état de la session en cours
undo	Annuler la dernière opération
redo	Rétablir la dernière opération annulée
save	Enregistrer l'état de la session sur le disque
list	Lister toutes les sessions enregistrées

Preview

Bundles de preview et sessions de preview en direct pour une révision itérative du montage.

Commande	Description
preview recipes	Lister les recettes de preview
preview capture	Effectuer le rendu d'un bundle de preview basse résolution
preview latest	Retourner le dernier bundle existant
preview live start	Démarrer une session de preview en direct et publier le premier bundle
preview live push	Publier un nouveau bundle dans la session en direct
preview live status	Interroger l'état de la session en direct sans effectuer de rendu
preview live stop	Arrêter la session en direct sans supprimer les artefacts

Contenu typique d'un bundle quick :

• preview.mp4
• plusieurs images échantillonnées
• image centrale hero.png
• summary.json avec les faits du projet

Le mode d'interrogation (poll) est pris en charge :

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

preview live status --json inclut les références de session et un trajectory_summary compact afin que les agents puissent comprendre facilement les dernières publications.

Commandes de visualisation :

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

Exemples

Créer un nouveau projet

Créer un nouveau fichier projet Shotcut.

cli-anything-shotcut project new -o myproject.json
# Ou avec une sortie JSON pour une utilisation programmatique
cli-anything-shotcut --json project new -o myproject.json

Session REPL interactive

Démarrer une session interactive avec support de l'annulation/rétablissement.

cli-anything-shotcut
# Entrer les commandes de manière interactive
# Utiliser 'help' pour voir les commandes disponibles
# Utiliser 'undo' et 'redo' pour naviguer dans l'historique

Exporter un projet

Exporter le projet vers un format de sortie final.

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

Reconstruction déterministe de la timeline

Pour les reconstructions, privilégier le placement absolu plutôt que l'insertion par ajout uniquement :

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 insère automatiquement des espaces vides lorsque le temps cible tombe dans une zone vide.
• La CLI rejette les chevauchements avec un clip existant.
• Privilégier des valeurs explicites --in et --out afin que le placement absolu ultérieur reste sans ambiguïté.

Automatisation audio

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

La CLI maintient l'état de la session avec :

• Annulation/Rétablissement (Undo/Redo) : Jusqu'à 50 niveaux d'historique
• Persistance du projet : Enregistrer/charger l'état du projet au format JSON
• Suivi de session : Suivi des modifications et des changements

Formats de sortie

Toutes les commandes prennent en charge deux modes de sortie :

• Lisible par l'humain (par défaut) : Tableaux, couleurs, texte formaté
• Lisible par machine (drapeau --json) : JSON structuré pour la consommation par les agents

# Sortie humaine
cli-anything-shotcut project info -p project.json

# Sortie JSON pour les agents
cli-anything-shotcut --json project info -p project.json

Pour les agents IA

Lorsque vous utilisez cette CLI de manière programmatique :

1. Utilisez toujours le drapeau --json pour une sortie analysable
2. Vérifiez les codes de retour - 0 pour succès, non nul pour erreur
3. Analysez stderr pour les messages d'erreur en cas d'échec
4. Utilisez des chemins absolus pour toutes les opérations sur fichiers
5. Vérifiez que les sorties existent après les opérations d'export
6. Privilégiez timeline add-clip --at lors de la recréation d'un montage connu
7. Revoyez les rendus finaux après les changements de volume avec images clés ou de ducking
8. Utilisez preview capture ou preview live ... pour valider visuellement le rythme, les coupes et les effets de filtre
9. Lisez les chemins d'artefacts retournés comme hero.png et preview.mp4 ; les charges utiles JSON référencent des fichiers sur le disque
10. Utilisez preview live status --json avant de lire l'intégralité du fichier trajectory.json
11. Utilisez cli-hub previews ... uniquement pour inspecter/ouvrir des bundles ou des sessions en direct existants

Plus d'informations

• Documentation complète : Voir README.md dans le package
• Couverture des tests : Voir TEST.md dans le package
• Méthodologie : Voir HARNESS.md dans le plugin cli-anything

Version

1.0.0