FilmCraft

FilmCraft — opération agent

FilmCraft est un éditeur vidéo natif Rust (classe Premiere Pro) dont l'interface agent est intégrée : chaque action est une commande avec un identifiant. Menus, raccourcis, panneaux, gestes de timeline, la CLI, le canal de contrôle, le serveur MCP et l'interface graphique pilote un même moteur. Validé sur 0.10.0–0.13.0 sous Windows et Linux.

Chemins machine et environnement

Plateforme	Binaire	CLI	Répertoire de données par défaut
Windows	C:\Program Files\FilmCraft\filmcraft.exe	C:\Program Files\FilmCraft\filmcraft-cli.exe	%LOCALAPPDATA%\FilmCraft
Linux	/usr/bin/filmcraft	/usr/bin/filmcraft-cli	~/.local/share/filmcraft
macOS	/Applications/FilmCraft.app/Contents/MacOS/filmcraft	filmcraft-cli (dans ~/.local/bin ou PATH)	~/Library/Application Support/filmcraft

• Emplacement des logs : <data-dir>/Logs/filmcraft.log
• Port de contrôle : loopback uniquement (--control <port> ou FILMCRAFT_CONTROL_PORT, par ex. 9876 ou 7991 ou 50051)
• Commandes : 710 dans 42 espaces de noms
• Effets : 130 effets vidéo, 112 transitions vidéo, 3 transitions audio

Modèle mental

• Un projet (.fcproj, JSON) contient des bacs et des éléments : Movie, Audio, Image, Sequence, Multi-Camera Source Sequence. project_inspect renvoie l'arborescence, activeSequence et le drapeau dirty. Une séquence est active ; les commandes agissent sur elle.
• Une séquence a des tableaux de pistes video[] et audio[], chacun {id, name, items[], transitions[], muted, locked, ...}. Un clip est {clip, item, name, start, duration, startFrame, durationFrames, sourceIn, sourceOut, speed, reverse, enabled, link, gainDb, effects[]} — tous les temps en ticks.
• Placer un film crée deux clips liés (vidéo + audio) avec des identifiants différents et link pointant l'un vers l'autre. Sélectionner l'un sélectionne les deux par défaut.
• Le temps est en ticks entiers, 254 016 000 000 par seconde (soit 48000×5292). seconds et frame sont ajustés à la grille d'images ; frame et timecode (par ex. "00:00:02:12", ou ; pour drop-frame) correspondent exactement. Préférez frame lorsque vous avez besoin d'une coupe précise.
• Une commande est {"id": "timeline.razor", "params": {...}}. command_list trouve les identifiants et la documentation des paramètres ; command_run en exécute une (annulable) ; command_batch en exécute plusieurs. Les types de paramètres invalides et les commandes inconnues échouent ; les noms de paramètres inconnus sont ignorés silencieusement (voir Pièges).
• Vérifiez en relisant (sequence_inspect, project_inspect, captions.list, media.status, jobs.list) ou en rendant (render_frame, file.exportFrame). Un résultat null signifie « exécuté », pas « fait ce que vous vouliez ».

Deux modes de connexion

Mode	Démarrage	Utilisation pour
Headless	filmcraft-cli mcp (--demo, --project p.fcproj, --data-dir d)	pas de fenêtre, constructions par lots, exports, scripts
Pont d'application	filmcraft --control 50051 + filmcraft-cli mcp --bridge 127.0.0.1:50051	la vraie fenêtre : état de l'interface, captures d'écran, clics, touches, glissés, commandes GUI uniquement

Lancer FilmCraft à la demande de l'utilisateur (「起動して」 / « lance FilmCraft »)

Quand l'utilisateur demande de démarrer ou lancer FilmCraft (「FilmCraftを起動して」「立ち上げて」「開いて」「start FilmCraft」) :

1. Vérifier s'il est déjà en cours d'exécution :
   • Windows : Get-Process filmcraft -ErrorAction SilentlyContinue
   • Linux / macOS : pgrep filmcraft
   • S'il tourne, vérifier si le port de contrôle répond (filmcraft-cli --bridge 127.0.0.1:50051 inspect).
   • S'il tourne sans port de contrôle, informer l'utilisateur : « FilmCraft est actuellement en cours d'exécution sans port de contrôle. Veuillez enregistrer votre travail et le redémarrer, ou autorisez-moi à le fermer et le relancer avec --control 50051. »
2. Lancer avec --control <port> (par défaut : 50051) et un FILMCRAFT_CONTROL_TOKEN de 64 caractères :
   • Windows (PowerShell) — utiliser scripts/launch.ps1 pour garantir une fenêtre de bureau visible sur WinSta0\Default :

     powershell -File scripts/launch.ps1 -Port 50051
     

     (Cela définit/persiste automatiquement FILMCRAFT_CONTROL_TOKEN, configure le port et lance une tâche interactive pour que l'interface soit visible par l'utilisateur connecté plutôt que cachée dans une session d'arrière-plan).
   • Linux :

     ./scripts/launch.sh 50051
     

   • macOS :

     ./scripts/launch.sh 50051
     

3. Vérifier la connexion :
   • Attendre 1 à 3 secondes, puis exécuter filmcraft-cli --bridge 127.0.0.1:50051 inspect.
   • Une fois qu'il répond, signaler que FilmCraft est actif, écoute sur le port 50051, et prêt pour les modifications en direct de la timeline et les commandes collaboratives.

Les 17 outils MCP

Outil	Objectif
command_list	chaque commande (filter, enabled_only)
command_run	exécuter une {id, params}
command_batch	exécuter {steps:[{id,params}], stop_on_error} → {completed, failed, results}
doc_inspect	arborescence du projet + séquence active en un appel
project_inspect	arborescence, éléments, séquence active, dirty
sequence_inspect	séquence active : paramètres, pistes, clips, transitions, marqueurs
media_import	importer des fichiers par chemin absolu (paths, bin, image_sequence)
render_frame	PNG à seconds (ou tête de lecture), max_side
render_preview	identique à render_frame (pont : moniteur Programme)
ui_inspect	état de la fenêtre/interface (outil, espace de travail, sélection, dialogue, lecture, nombre d'éléments)
ui_elements	éléments à l'écran avec identifiant, libellé et rectangle (prefix)
ui_click	cliquer par id ou x,y (button, count, modifiers)
ui_drag	appuyer–déplacer–relâcher entre points ou identifiants d'éléments (steps)
ui_key	touche ou raccourci (Space, Cmd+Z, Shift+Delete)
ui_type	taper dans le champ focalisé
ui_screenshot	PNG de la fenêtre ou d'un panel
ui_control	toute méthode de contrôle : ui.set, ui.menu.list, ui.playback, …

Ressources : filmcraft://document (JSON 48 Ko : projet + séquence) et filmcraft://commands (catalogue de 192 Ko). Pas de prompts.

Flux de travail standard

1. Sonder. project_inspect / doc_inspect ; headless démarre vide sauf --demo ou --project. ui_inspect en premier en mode pont.
2. Construire. file.newProject → file.import (chemins absolus) ou file.importDemoFootage → file.newSequence → timeline.place.
3. Couper. playhead.set + timeline.razor, timeline.trim, timeline.slip, timeline.move, edit.clear / edit.rippleDelete.
4. Styliser. effects.apply + effects.setParam ; sequence.applyVideoTransition ; lumetri.applyPreset ; graphics.newText ; markers.add ; captions.add.
5. Vérifier. Lire sequence_inspect/captions.list ; render_frame à un instant significatif et regarder le PNG (cela détecte les mauvais clips, les images noires et les transitions manquantes qu'aucune relecture ne montre).
6. Exporter. file.exportMedia avec wait:true (vérifier offlineMedia et le fichier écrit) ; file.exportInterchange pour les allers-retours NLE.
7. Enregistrer. file.saveAs (crée les répertoires ? non — le parent doit exister) ; puis relire project_inspect.dirty (false après enregistrement).

Trouver les commandes

command_list {filter:"razor"} correspond à l'identifiant, au libellé, au menu et aux paramètres. filmcraft-cli commands razor, describe <id> et filmcraft-cli inspect font de même depuis un shell. Les 701 identifiants avec leur documentation de paramètres sont dans references/commands.md ; le JSON vérifié étape par étape est dans references/recipes.md.

Commencez par : file.newProject, file.import, file.newSequence, timeline.place, timeline.razor, timeline.trim, timeline.slip, timeline.move, timeline.select, edit.clear, edit.rippleDelete, edit.undo, effects.apply, effects.setParam, sequence.applyVideoTransition, sequence.setTransition, markers.add, captions.newTrack, captions.add, graphics.newText, file.exportMedia, file.exportInterchange, file.exportFrame, file.saveAs.

Pièges qui font perdre du temps

1. Les paramètres de commande sont tolérants — les clés inconnues et certains types erronés sont silencieusement ignorés. timeline.trim {seconds:-1} renvoie {"delta":0} (la clé est delta) ; timeline.place {seconds:"2"} place à 0 ; fps:"fast" revient à 23.976. Certaines commandes valident (graphics.set, markers.add), donc ne comptez jamais sur une erreur pour détecter un mauvais paramètre. Lisez la doc du paramètre, puis relisez l'état.
2. file.newSequence bascule la séquence active et renvoie {sequence: id}. sequence.open attend {item: id} — passer sequence ou un identifiant de clip produit une erreur. Après toute ouverture/création, relisez sequence_inspect.
3. Les transitions ne sont pas sur le clip. Elles se trouvent dans sequence_inspect.video[i].transitions[] sous la forme {id, effect, from, to, start, duration, align, reverse, params}. sequence.removeTransition {transitions:[id]} ; sequence.setTransition modifie la durée/l'alignement/les params.
4. Les légendes ne sont pas dans sequence_inspect. Utilisez captions.list ; les sous-titres portent id, start, end, text. captions.newTrack revient silencieusement à Subtitle pour toute chaîne de format inconnue.
5. Ne passez jamais un répertoire à file.exportMedia. Il se bloque indéfiniment (reproduit deux fois, >3 min, aucune sortie). Utilisez un chemin de fichier complet.
6. Le format l'emporte sur l'extension. format:"gif" avec out.mp4 écrit out.mp4.gif ; ProRes avec out.mp4 écrit out.mp4.mov. Le path du résultat est faisant autorité.
7. timeline.place avec une duration plus longue que la source maintient la dernière image pour le reste du clip, sans avertissement. Coupez avec le média en tête.
8. range:"inOut" sans marques exporte toute la séquence, silencieusement. range:"custom" + startSeconds/endSeconds est la sous-plage fiable.
9. jobs.list est une commande, pas un outil. command_run {id:"jobs.list"} ; jobs.cancel {job} supprime le fichier partiel. wait:false exports renvoient {job, path, poll, cancel}.
10. Les rushes de démonstration sont synthétiques. Les exports d'échange (FCPXML/AAF/OMF) des médias de démonstration perdent des clips ; avec de vrais médias sur disque, ils font un aller-retour (voir references/formats-and-roundtrip.md).
11. edit.clear (Retour arrière) laisse un trou ; edit.rippleDelete le referme. sequence.lift/extract nécessitent des marques d'entrée/sortie de séquence, pas une sélection.
12. lumetri.applyPreset ajoute un nouvel effet Lumetri à chaque fois au lieu de remplacer l'effet précédent. Supprimez l'ancien effet ou définissez les paramètres directement.
13. Les commandes GUI uniquement sont invisibles pour command_list : window.workspace. {editing,assembly,color,effects,audio}, window.workspace.reset, window.toggleFullScreen, app.about. Elles n'existent que sur le pont.
14. L'export HEVC n'est pas disponible ici ("aucun encodeur enregistré"). H.264, ProRes, DNxHR, MJPEG, MXF, séquences d'images et audio fonctionnent tous.
15. prefs.set dans une session headless est limité à la session — il n'a pas persisté entre deux sessions --data-dir. Utilisez l'interface graphique pour les préférences durables.
16. Les arguments des outils MCP sont stricts (clé inconnue → JSON-RPC -32602 ; mauvais type → isError avec un message de désérialisation), mais command_run.params est transmis tel quel.

Carte de référence

Fichier	Contenu
references/recipes.md	JSON vérifié pour construction, coupe, effets, couleur, légendes, graphiques, proxies, multicam, TTS, export, GUI
references/commands.md	toutes les 701 commandes, groupées par espace de noms, avec documentation des paramètres
references/mcp-and-control.md	détails MCP, formes d'erreur, ressources, méthodes de contrôle, commandes GUI uniquement
references/cli.md	sous-commandes filmcraft-cli, flags, codes de sortie, médias hors ligne, tâches headless
references/formats-and-roundtrip.md	matrice d'export + validation indépendante, allers-retours d'échange
references/bugs-and-workarounds.md	chaque défaut reproduit avec une reproduction minimale
references/maintenance.md	revérifier la version, vider les commandes, actualiser cette compétence
scripts/probe.sh	poignée de main MCP + nombre d'outils + version
scripts/dump-commands.sh	régénérer le catalogue de commandes
scripts/smoke-test.sh	construire → rendre → exporter → validation indépendante

Communauté : https://discord.gg/artcraft · https://getartcraft.com/apps/filmcraft · https://github.com/storytold/filmcraft.