EffectCraft

EffectCraft — opération agent

EffectCraft est un compositeur de motion-design / VFX natif en Rust (classe AfterEffects) dont l'interface agent est intégrée : chaque action est une commandeavec un identifiant. L'interface graphique, les menus, la CLI, le canal decontrôle et le serveur MCP pilotent tous le même moteur. Validé contre laversion 0.17.0 sur Windows.

Chemins machine et environnement

Plateforme	Binaire	CLI	Répertoire de données par défaut
Windows	C:\Program Files\EffectCraft\effectcraft.exe	C:\Program Files\EffectCraft\effectcraft-cli.exe	%LOCALAPPDATA%\EffectCraft (cache disque)
Linux	/usr/bin/effectcraft	/usr/bin/effectcraft-cli	~/.local/share/effectcraft

• Port de contrôle : --control <port> ou EFFECTCRAFT_CONTROL_PORT (pas de jeton — le pont accepte les connexions de boucle locale simples, contrairement à FilmCraft)
• Commandes : 734 dans 55 espaces de noms (439 activées dans un contexte headless frais ; le reste nécessite une sélection / comp active / mode outil)
• Effets : 307 dans le registre (list_effects) ; 149 familles de polices (list_fonts)

Modèle mental

• Un projet (.ecproj) contient des éléments : Composition, Folder, Solid,Footage. get_project renvoie l'arborescence des éléments, le drapeau de modification et la comp active. Une comp est active ; la plupart des commandes agissent sur elle.
• Une comp est {width, height, frameRate, duration, startTime, background,renderer: classic3D|advanced3D}. Les temps sont en secondes (flottants, pas de ticks — pas de calcul de ticks ici, contrairement à FilmCraft).
• Un calque est Texte, Forme, Solide, Null, Composition (précomp), Ajustement,Lumière ou Caméra. Les calques s'empilent, 1 = haut. Adressez les calques par id, #n (index de pile) ou name.
• Chaque calque a une arborescence de propriétés : Transform (anchor, position, scale,rotation, opacity), plus effects, masks, contents de texte ou de forme. Les chemins de propriétés acceptent transform.position et Transform/Position — mais un position nu (sans groupe) est rejeté.
• Animation = images clés sur les propriétés (prop.addKey) ou expressions(prop.setExpression, JavaScript AE). prop.get {time} renvoie la valeur interpolée, la liste des clés et le drapeau animated.
• Les paramètres sont validés strictement : un nom de paramètre inconnu fait échouer la commande avec la liste des clés acceptées ; de même pour un ID de commande inconnu. C'est l'opposé des paramètres silencieusement ignorés de FilmCraft — lisez l'erreur, corrigez l'appel, ne réessayez pas à l'aveugle.
• Vérifiez en relisant (get_state, get_project, get_comp,get_layer, get_property) ou en rendant (render_frame — un PNG capture les positions erronées, les calques invisibles et les effets manquants qu'aucune relecture ne montre).

Deux modes de connexion

Mode	Démarrage	Utiliser pour
Headless	effectcraft-cli mcp --demo (--project p.ecproj, --empty, --autosave)	pas de fenêtre, constructions par lots, rendus, scripts
Pont applicatif	effectcraft --control 50052 + effectcraft-cli mcp --bridge 50052	la vraie fenêtre : état de l'interface utilisateur, captures d'écran, clics, touches, commandes GUI uniquement

Chaque invocation CLI est sa propre session. L'état construit dans une run disparaît lorsque le processus se termine — terminez par file.saveAs + --save-as, ou faites tout (construction → rendu) en une seule invocation render/run.

Lancer EffectCraft sur demande de l'utilisateur ("起動して" / "start EffectCraft")

1. Vérifier s'il est déjà en cours d'exécution : Get-Process effectcraft / pgrep effectcraft.Si c'est le cas, testez le port : effectcraft-cli --bridge 50052 info.S'il est exécuté sans port de contrôle, demandez à l'utilisateur de le redémarrer avec--control (le travail non enregistré serait autrement perdu).
2. Lancer avec --control <port> (par défaut 50052) :
   • Windows — utilisez scripts/launch.ps1 pour que la fenêtre apparaisse sur le bureau visible au lieu d'une session en arrière-plan : powershell -File scripts/launch.ps1 -Port 50052
   • Linux : ./scripts/launch.sh 50052
3. Vérifier : attendez 1 à 3 s, puis effectcraft-cli --bridge 50052 info — il affiche la version, les nombres de commandes/effets et le projet ouvert.

Les outils MCP

Le mode headless expose 27 outils ; le pont ajoute 9 outils d'interface utilisateur (ui_inspect,ui_elements, ui_click, ui_drag, ui_key, ui_set, ui_type,screenshot, control) plus script_ui pour les boîtes de dialogue ScriptUI = 36.

Outil	Objectif
command_list / list_commands	chaque commande (--filter, --enabled)
command_run / execute_command	exécuter une {id, params} (annulable)
command_batch / batch	plusieurs commandes, une seule étape d'annulation (batch)
describe_command	schéma d'une commande
doc_inspect / get_project	arborescence du projet + comp active en un seul appel
get_comp	une comp : paramètres, calques, zone de travail
get_layer	arborescence complète des propriétés d'un calque
get_property / set_property	lire / écrire une propriété (définir les clés lors de l'animation)
add_keyframe	images clés pour une propriété (active le chronomètre)
add_effect / list_effects	appliquer un effet (+params en un appel) / le registre des 307 effets
list_fonts	149 familles de polices utilisables par les calques de texte
run_script	ExtendScript de style After Effects (app.project, comps, calques)
render_frame / render_preview	PNG de la comp (active) à time
open_project / save_project	ouvrir (path, demo:true, empty:true) / enregistrer (+ Enregistrer sous)
undo / redo / history	historique d'annulation ramifié
get_state	comp active, heure actuelle, sélection, lecture
script_ui	piloter les boîtes de dialogue/palettes ScriptUI des scripts ouverts

Ressources : effectcraft://document et effectcraft://commands.

Flux de travail standard

1. Sonder. get_state + get_project ; headless démarre vide sauf si--demo/--project. ui_inspect d'abord en mode pont.
2. Construire. comp.new {name,width,height,frameRate,duration} →layer.newText/newShape/newSolid/newNull (paramètres de style en ligne) →file.import {paths} pour les séquences → placement de style layer.addItem.
3. Animer. prop.addKey {layer,path,time,value} par clé ;keys.setEase, keys.interpolation, prop.setExpression.
4. Styliser. effect.apply {effect:"Gaussian Blur", layers:[id]} +chemins de paramètres sous effects/#1/... ; masques (mask.new), animateurs de texte,traits de dégradé de forme.
5. Vérifier. get_property à des moments significatifs ; render_frame à ces momentset regarder les PNG (la position, l'assouplissement et le flou sont tous visibles).
6. Rendre. render --out file.mp4 --format h264 (CLI), ourenderQueue.add + renderQueue.render ; render-frame --transparent pourRGBA ; render --template t.ectemplate --values v.json pour les travaux de modèle.
7. Enregistrer. file.saveAs {path} (ou CLI --save-as) ; relisezget_project — le drapeau de modification s'efface après l'enregistrement.

Trouver des commandes

command_list {filter:"mask"} correspond à l'id, au libellé et au menu. Depuis un shell :effectcraft-cli commands --filter mask, et describe_command/describepour le schéma d'une commande. Les 734 ids avec la documentation des paramètres sont dansreferences/catalog/commands.md ; le JSON vérifié étape par étape est dansreferences/recipes.md.

Commencez par : comp.new, comp.settings, comp.open, layer.newText,layer.newShape, layer.newSolid, layer.newNull, layer.select,layer.moveLater, layer.setTransform, layer.setText, prop.get,prop.set, prop.addKey, keys.setEase, keys.interpolation,prop.setExpression, effect.apply, mask.new, time.set,file.import, file.saveAs, renderQueue.add, renderQueue.render,app.quit.

Pièges qui font perdre du temps

1. Validation stricte partout. Paramètre inconnu → invalid parameters …accepted: name, width, … avec la liste complète des clés ; id de commande inconnu →unknown command. Les erreurs sont la documentation — mais un paramètre valide avecune valeur de type erronée peut toujours mal se comporter, donc relisez l'état.
2. Temps du calque vs temps de la comp. Les commandes d'écriture (prop.addKey, keys.set,prop.set) prennent time en secondes de calque par défaut(timeBase:"layer"|"comp" permet de basculer) ; prop.get lit time en secondes de comp.Avec un calque commençant à 0, ils coïncident ; après layer.move, ils ne coïncident plus. Mauvaise base = les clés sont décalées silencieusement du début du calque.
3. De nombreuses commandes nécessitent une sélection. prop.set, effect.apply,keys.easyEase affichent enabled:false sans rien de sélectionné (headless démarrevide). Passez des paramètres explicites layer/layers, ou layer.select d'abord.
4. comp.new renvoie {comp: id} et en fait la comp active (vérifié :deux appels comp.new, un calque de texte atterrit dans le second). Basculez aveccomp.open {comp: id|name} et confirmez via get_state — les commandes etles rendus qui ciblent "la comp active" échouent avec no active compositionsur un projet --empty frais avant le premier comp.new.
5. Les chemins de propriétés doivent inclure le groupe : transform.position /Transform/Position fonctionnent, position nu génère une erreur no property.Trouvez les chemins exacts avec props <comp> <layer> --flat ou get_layer.
6. Les paramètres d'effet sont des chemins sous l'effet, par exempleeffects/#1/Blurriness (index = ordre d'application). effect.applyrenvoie paths:["effects/#1"] — utilisez-les.
7. Chaque invocation CLI est une session fraîche (voir ci-dessus). Les sessions MCP conserventl'état jusqu'à la sortie du serveur.
8. render écrit le --out relatif dans le répertoire de travail du processus ;passez toujours un chemin absolu pour une sortie prévisible.
9. Les calques de texte prennent tout le style à la création (layer.newText{size,fill,tracking,…} — des dizaines de paramètres). La restylisation ultérieure passe parles propriétés de source/document de texte ; vérifiez get_layer pour les chemins exacts.
10. Surface GUI uniquement : ui_*, screenshot, control, script_ui n'existentque sur le pont ; window.*, view.* et help.* ont surtout besoin de l'interface graphique.
11. mcp --autosave persiste les modifications headless non enregistrées à la sortie ; sans cela, ellessont perdues (attendu pour les exécutions jetables, surprenant pour un travail réel).

Carte de référence

Fichier	Contenu
references/recipes.md	JSON vérifié : construction, texte, forme, images clés, assouplissement, expressions, effets, masques, rendu, exportation, GUI
references/catalog/commands.md	les 734 commandes regroupées par espace de noms avec documentation des paramètres
references/mcp-and-control.md	les 27+9 outils, formes d'erreur, ressources, détails du pont
references/cli.md	sous-commandes effectcraft-cli, formats de rendu, modèles, bench
references/bugs-and-workarounds.md	défauts reproduits avec des reproductions minimales
references/maintenance.md	revérifier la version, vider les commandes, actualiser cette compétence
scripts/probe.sh / .ps1	poignée de main MCP + nombre d'outils + version
scripts/dump-commands.sh / .ps1	régénérer le catalogue de commandes
scripts/launch.sh / .ps1	démarrer l'interface graphique avec un port de contrôle (bureau visible)
scripts/smoke-test.sh / .ps1	construire → image clé → rendre → valider

Communauté : https://discord.gg/artcraft · https://getartcraft.com/apps/effectcraft.