e1dred/filmcraft

Que fait filmcraft ?

Mises à jour : si ce dossier contient un fichier .installed-from (écrit lorsqu'il a été copié depuis le dépôt), exécutez git ls-remote https://gitlab.com/e1dred/agent-skills.git HEAD une fois par session. Prenez le hash sur la ligne de sortie qui se termine exactement par HEAD ; s'il diffère de celui du fichier, informez l'utilisateur qu'une version plus récente existe et proposez de la mettre à jour (voir « Mise à jour » dans https://gitlab.com/e1dred/agent-skills/-/blob/main/INSTALL.md, qui peut fusionner les modifications locales) ; ne jamais mettre à jour sans demander. Comparez les hash après avoir supprimé les espaces. Pas de fichier, un clone ou un lien symbolique, ou pas de réseau (sortie vide ou erreur de git ls-remote) : passez silencieusement.

Notes de terrain issues des premières tâches sans interface graphique, dernièrement testé avec FilmCraft 0.17.1 (Linux AppImage). FilmCraft est un éditeur vidéo de type Premiere en Rust, en alpha. Chaque élément de menu et chaque bouton est une commande du moteur ; la CLI, le serveur MCP et le canal de contrôle de l'application exécutent les mêmes commandes. Si filmcraft-cli --version est plus récent, revérifiez tout ce qui est dit ici avant de s'y fier.

Configuration

• CLI : extrayez-la de l'AppImage (filmcraft.appimage --appimage-extract, copiez usr/bin/filmcraft-cli dans un endroit stable) ; autonome, pas de fenêtre. N'exécutez jamais --version sur l'AppImage elle-même.
• Sans interface (headless) : filmcraft-cli --project p.fcproj exec <id> key=valeur … ; les scripts sont en JSON lines et conservent une session : filmcraft-cli --project p.fcproj run script.jsonl [--save] avec des lignes {"id":"…","params":{…}}, ou filmcraft-cli run autonome après file.newProject. Sous-commandes : commands, describe, inspect, import, export, render, probe.
• Application live : filmcraft --control 9876 (ou FILMCRAFT_CONTROL_PORT) ; l'écouteur a besoin de FILMCRAFT_CONTROL_TOKEN (64 caractères hexadécimaux) dans l'environnement — sans lui, il reste fermé. Pont avec filmcraft-cli mcp --bridge 127.0.0.1:9876.
• MCP : filmcraft-cli mcp (sans interface) ou --bridge (live).

Où trouver les informations

Lisez le fichier qui correspond à la tâche ; chacun liste les sections qu'il contient. Utilisez grep -n sur reference/ pour trouver un identifiant de commande.

Fichier dans reference/	À lire pour	Sections
projects-and-timeline.md	Projets, import de médias, séquences, tête de lecture, rasoir et rognure, marqueurs, sauvegarde, transitions, effets vidéo et images clés, arrêts sur image, notes de projet	Projets et médias ; Séquences ; Coupe et rognure ; Marqueurs et sauvegarde ; Transitions ; Effets vidéo et images clés ; Arrêts sur image, sélection et notes de projet ; Autres outils d'édition
titles-and-graphics.md	Calques de texte et formes, taille/ajustement sur petits cadres, lecture des calques, texte vertical et images importées	Titres ; Dimensionnement et ajustement ; Propriétés des calques ; Autres outils de calque
audio-mixer.md	Pistes du mixeur, valeurs, sous-mixages, inserts et envois ; gain du clip et son essentiel	Mixeur ; Audio du clip
captions.md	Pistes de sous-titres, ajout/édition/déplacement de sous-titres, import et export SRT	Pistes de sous-titres et SRT
export.md	Présélections d'exportation et formats, file d'exportation, export MP4/GIF, images fixes, exportations d'échange, sondage	Présélections ; Exportation ; Présélections et file d'exportation ; Images fixes ; Sondage
command-catalogue.md	Tous les autres identifiants de commande par famille (clip, timeline, sequence, trim, graphics, edit, file, project, multicam, source, prefs, shortcuts, …), chacun marqué vérifié (chemin JSON ancien → nouveau), a renvoyé un résultat, s'est exécuté, ou a refusé avec la raison ; la configuration qui déverrouille les commandes dépendantes de la sélection	Une section par famille
live-app.md	Piloter l'application en cours d'exécution via --bridge : les outils ui_*, ce qui ne fonctionne qu'en live, l'exécution sur un écran caché	Connexion ; Ce que l'application live ajoute
newer-commands.md	Ce que chaque version a ajouté ou modifié	0.17.0 ; 0.17.1
log.md	Journal daté de ce qui a été testé et quand	Journal

Essentiels de la CLI (vérifiés)

filmcraft-cli commands --json                    # 716 commandes : id, label, menu, params, enabled
filmcraft-cli describe file.import               # documentation des paramètres pour une commande
filmcraft-cli --project p.fcproj inspect         # {project:{…}, sequence:{…}} en 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                     # type, durée (ticks), détails flux vidéo/audio

• Un script JSONL conserve l'état : file.newProject → file.import {"paths":["clip.mp4"]} → {"items":[1]} → file.newSequenceFromClip {"items":[1]} → {"clips":[6,7],"sequence":4} → … → file.saveAs {"path":"p.fcproj"}.
• Passez --project à chaque appel CLI ultérieur : sans lui, chaque invocation est une session vierge.

Pièges

• Les temps sont en ticks, pas en images : la séquence rapporte 762 048 000 000 pour 3 s (254 016 000 000 ticks/s) ; playhead.set accepte seconds, frame, time ou timecode et s'aligne sur l'image la plus proche (1,5 s → image 37).
• Un calque de texte à la taille par défaut déborde d'un petit cadre. graphics.newText a une taille par défaut de 100 px : sur une séquence 320×180, « Hello FilmCraft » à size:48 mesurait 334,7 px de large depuis x=40 et était coupé au bord droit. Ajustez-le en définissant size (~32 → 223 px de large ; vérifié dans un rendu). Le texte paragraphe avec box:[w,h] renvoie à la ligne, mais la boîte COUPE les lignes qui ne tiennent pas dans sa hauteur : box:[240,60] à taille 40 n'affichait que « Hello » (la deuxième ligne était coupée), donc faites la boîte assez haute pour chaque ligne (environ 1,3 × taille par ligne).
• Les ripple edits échouent sur une piste verrouillée en synchro : timeline.trim avec mode:"ripple" a répondu « cette édition briserait la synchro : V2 est verrouillée en synchro et a un clip sur le chemin » lorsqu'un titre était sur V2. Verrouillez/déverrouillez l'autre piste d'abord ou coupez sans ripple.
• probe --image-sequence n'accepte que les images fixes numérotées ; sur une vidéo, il génère une erreur.
• effects.addKeyframe sans interface avec un mediaTime brut n'a rien fait ({added:false, mediaTime:0} ; 0.17.0), mais dans l'application live {clip, effect:"opacity", param:"opacity", seconds:1.5, value:40} en a ajouté une (images clés 5 → 6 ; le temps s'aligne sur une image : 624699432000). Sans interface, déplacez la tête de lecture et utilisez effects.toggleAnimation, ou graphics.set {…,"keyframe":true} pour les propriétés de titre.
• mixer.addInsert nécessite un véritable identifiant d'effet audio (hard_limiter, de effects.list {"kind":"Audio"}), pas un libellé comme volume ; mixer.addSend nécessite la ref du sous-mixage de mixer.addSubmix dans la même exécution.
• Les commandes graphics.* ont besoin d'un titre dans la même session : exécutez graphics.newText d'abord dans le même script, puis graphics.alignFrame.*, nudge*, fontSize*, leading* fonctionnent sans interface (lisez graphics.list {clip} → layers[0]). Sans titre, elles répondent « pas de clip graphique ». graphics.deleteLayer n'a été accepté qu'en live (pas de retour de lecture).
• La sélection ne survit pas à une sauvegarde/réouverture : mettez project.select {items:[id]} / timeline.select dans le même script que la commande qui en a besoin (« sélectionnez un élément dans le panneau Projet », « aucun clip sélectionné »).
• L'exportation FCPXML peut perdre un titre : file.exportInterchange {"format":"fcpxml"} a signalé le clip graphique « non pris en charge » tout en écrivant le fichier ; lisez le rapport avant de vous fier à une exportation d'échange.
• --demo ouvre le projet de démonstration intégré : il inspecte et rend (une image 1920×1080 à 1 s), exporté correctement seulement dans la mesure testée ; les médias manquants sont exportés sous forme d'images de remplacement à moins que --allow-offline ne les accepte.
• file.exportMedia attend son fichier sauf si "wait":false ; la CLI export attend toujours.

Vérifier avant de rapporter

inspect sequence (début/fin des clips en images, pistes, transitions, effets), probe pour la durée et les codecs du fichier exporté, et render une image aux moments intéressants pour regarder. Comptage d'images : 3 s à 25 ips = 75 images ; un ripple trim de -10 images a donné 65.