FilmCraft

FilmCraft — operación del agente

FilmCraft es un editor de video nativo en Rust (clase Premiere Pro) cuya interfaz de agente está integrada: cada acción es un comando con un id. Menús, atajos, paneles, gestos de línea de tiempo, la CLI, el canal de control, el servidor MCP y la GUI impulsan un mismo motor. Verificado contra 0.10.0–0.13.0 en Windows y Linux.

Rutas de máquina y entorno

Plataforma	Binario	CLI	Directorio de datos por defecto
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 (en ~/.local/bin o PATH)	~/Library/Application Support/filmcraft

• Ubicación del log: <data-dir>/Logs/filmcraft.log
• Puerto de control: solo loopback (--control <port> o FILMCRAFT_CONTROL_PORT, ej. 9876 o 7991 o 50051)
• Comandos: 710 en 42 namespaces
• Efectos: 130 efectos de video, 112 transiciones de video, 3 transiciones de audio

Modelo mental

• Un proyecto (.fcproj, JSON) contiene bins e ítems: Movie, Audio, Image, Sequence, Multi-Camera Source Sequence. project_inspect devuelve el árbol, activeSequence y la bandera dirty. Una secuencia está activa; los comandos actúan sobre ella.
• Una secuencia tiene arrays de pistas video[] y audio[], cada una {id, name, items[], transitions[], muted, locked, ...}. Un clip es {clip, item, name, start, duration, startFrame, durationFrames, sourceIn, sourceOut, speed, reverse, enabled, link, gainDb, effects[]} — todos los tiempos en ticks.
• Colocar una película crea dos clips enlazados (video + audio) con diferentes ids y link apuntando uno al otro. Seleccionar uno selecciona ambos por defecto.
• El tiempo es en ticks enteros, 254,016,000,000 por segundo (también 48000×5292). seconds y frame se ajustan a la cuadrícula de fotogramas; frame y timecode (ej. "00:00:02:12", o ; para drop-frame) mapean exactamente. Prefiere frame cuando necesites un corte exacto.
• Un comando es {"id": "timeline.razor", "params": {...}}. command_list encuentra ids y documentación de parámetros; command_run ejecuta uno (deshacible); command_batch ejecuta varios. Los tipos de parámetros inválidos y los comandos desconocidos fallan; los nombres de parámetros desconocidos se ignoran silenciosamente (ver Trampas).
• Verifica leyendo de vuelta (sequence_inspect, project_inspect, captions.list, media.status, jobs.list) o renderizando (render_frame, file.exportFrame). Un resultado null significa "se ejecutó", no "hizo lo que querías".

Dos modos de conexión

Modo	Inicio	Usar para
Headless	filmcraft-cli mcp (--demo, --project p.fcproj, --data-dir d)	sin ventana, builds batch, exportaciones, scripts
Puente de app	filmcraft --control 50051 + filmcraft-cli mcp --bridge 127.0.0.1:50051	la ventana real: estado de UI, screenshots, clics, teclas, arrastres, comandos solo-GUI

Iniciando FilmCraft a petición del usuario ("起動して" / "start FilmCraft")

Cuando el usuario pida iniciar o lanzar FilmCraft (「FilmCraftを起動して」「立ち上げて」「開いて」「start FilmCraft»):

1. Verificar si ya está en ejecución:
   • Windows: Get-Process filmcraft -ErrorAction SilentlyContinue
   • Linux / macOS: pgrep filmcraft
   • Si está en ejecución, verificar si el puerto de control responde (filmcraft-cli --bridge 127.0.0.1:50051 inspect).
   • Si está en ejecución sin un puerto de control, informar al usuario: "FilmCraft se está ejecutando actualmente sin un puerto de control. Por favor, guarda tu trabajo y reinícialo, o permíteme cerrarlo y reiniciarlo con --control 50051."
2. Iniciar con --control <port> (por defecto: 50051) y un FILMCRAFT_CONTROL_TOKEN de 64 caracteres:
   • Windows (PowerShell) — usar scripts/launch.ps1 para asegurar una ventana de escritorio visible en WinSta0\Default:

     powershell -File scripts/launch.ps1 -Port 50051
     

     (Esto establece/persiste automáticamente FILMCRAFT_CONTROL_TOKEN, configura el puerto, y lanza una tarea interactiva para que la GUI sea visible para el usuario conectado, no oculta en una sesión de fondo).
   • Linux:

     ./scripts/launch.sh 50051
     

   • macOS:

     ./scripts/launch.sh 50051
     

3. Verificar la conexión:
   • Esperar 1–3 segundos, luego ejecutar filmcraft-cli --bridge 127.0.0.1:50051 inspect.
   • Una vez que responda, informar que FilmCraft está activo, escuchando en el puerto 50051, y listo para ediciones en vivo de la línea de tiempo y comandos colaborativos.

Las 17 herramientas MCP

Herramienta	Propósito
command_list	cada comando (filter, enabled_only)
command_run	ejecuta uno {id, params}
command_batch	ejecuta {steps:[{id,params}], stop_on_error} → {completed, failed, results}
doc_inspect	árbol del proyecto + secuencia activa en una llamada
project_inspect	árbol, ítems, secuencia activa, dirty
sequence_inspect	secuencia activa: ajustes, pistas, clips, transiciones, marcadores
media_import	importa archivos por ruta absoluta (paths, bin, image_sequence)
render_frame	PNG en seconds (o playhead), max_side
render_preview	igual que render_frame (puente: monitor del Programa)
ui_inspect	estado de ventana/UI (herramienta, espacio de trabajo, selección, diálogo, reproducción, número de elementos)
ui_elements	elementos en pantalla con id, label y rect (prefix)
ui_click	clic por id o x,y (button, count, modifiers)
ui_drag	presionar–mover–soltar entre puntos o ids de elementos (steps)
ui_key	tecla o atajo (Space, Cmd+Z, Shift+Delete)
ui_type	escribir en el campo enfocado
ui_screenshot	PNG de la ventana o de un panel
ui_control	cualquier método de control: ui.set, ui.menu.list, ui.playback, …

Recursos: filmcraft://document (48 KB JSON: proyecto + secuencia) y filmcraft://commands (192 KB catálogo). Sin prompts.

Flujo de trabajo estándar

1. Sondear. project_inspect / doc_inspect; headless comienza vacío a menos que se use --demo o --project. ui_inspect primero en modo puente.
2. Construir. file.newProject → file.import (rutas absolutas) o file.importDemoFootage → file.newSequence → timeline.place.
3. Cortar. playhead.set + timeline.razor, timeline.trim, timeline.slip, timeline.move, edit.clear / edit.rippleDelete.
4. Estilizar. effects.apply + effects.setParam; sequence.applyVideoTransition; lumetri.applyPreset; graphics.newText; markers.add; captions.add.
5. Verificar. Leer sequence_inspect/captions.list; render_frame en un momento revelador y mirar el PNG (esto detecta clips incorrectos, fotogramas negros y transiciones faltantes que ninguna lectura de vuelta muestra).
6. Exportar. file.exportMedia con wait:true (comprobar offlineMedia y el archivo escrito); file.exportInterchange para ida y vuelta con NLE.
7. Guardar. file.saveAs (¿crea directorios? no — el padre debe existir); luego releer project_inspect.dirty (false después de guardar).

Encontrando comandos

command_list {filter:"razor"} coincide con id, etiqueta, menú y parámetros. filmcraft-cli commands razor, describe <id> y filmcraft-cli inspect hacen lo mismo desde una shell. Los 701 ids con su documentación de parámetros están en references/commands.md; los JSON paso a paso verificados están en references/recipes.md.

Empieza con: 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.

Trampas que cuestan tiempo

1. Los parámetros de comandos son permisivos — las claves desconocidas y algunos tipos incorrectos se descartan silenciosamente. timeline.trim {seconds:-1} devuelve {"delta":0} (la clave es delta); timeline.place {seconds:"2"} coloca en 0; fps:"fast" retrocede a 23.976. Algunos comandos sí validan (graphics.set, markers.add), así que nunca confíes en un error para detectar un parámetro malo. Lee la documentación del parámetro, luego lee el estado de vuelta.
2. file.newSequence cambia la secuencia activa y devuelve {sequence: id}. sequence.open requiere {item: id} — pasar sequence o un id de clip da error. Después de cualquier open/new, vuelve a leer sequence_inspect.
3. Las transiciones no están en el clip. Viven en sequence_inspect.video[i].transitions[] como {id, effect, from, to, start, duration, align, reverse, params}. sequence.removeTransition {transitions:[id]}; sequence.setTransition edita duración/align/params.
4. Los subtítulos no están en sequence_inspect. Usa captions.list; las señales llevan id, start, end, text. captions.newTrack retrocede silenciosamente a Subtitle para cualquier string de formato desconocido.
5. Nunca pasar un directorio a file.exportMedia. Se cuelga indefinidamente (reproducido dos veces, >3 min, sin salida). Usa una ruta de archivo completa.
6. El formato prevalece sobre la extensión. format:"gif" con out.mp4 escribe out.mp4.gif; ProRes con out.mp4 escribe out.mp4.mov. La ruta del resultado es la autorizada.
7. timeline.place con duration mayor que el origen mantiene el último fotograma durante el resto del clip, sin advertencia. Recorta teniendo en cuenta el material.
8. range:"inOut" sin marcas exporta toda la secuencia, silenciosamente. range:"custom" + startSeconds/endSeconds es el sub-rango fiable.
9. jobs.list es un comando, no una herramienta. command_run {id:"jobs.list"}; jobs.cancel {job} elimina el archivo parcial. Las exportaciones con wait:false devuelven {job, path, poll, cancel}.
10. El metraje de demostración es sintético. Las exportaciones de intercambio (FCPXML/AAF/OMF) de material demo pierden clips; con material real en disco hacen ida y vuelta (ver references/formats-and-roundtrip.md).
11. edit.clear (Backspace) deja un hueco; edit.rippleDelete lo cierra. sequence.lift/extract necesitan marcas de entrada/salida en la secuencia, no una selección.
12. lumetri.applyPreset añade un nuevo efecto Lumetri cada vez en lugar de reemplazar el look anterior. Elimina el efecto antiguo o establece los parámetros directamente.
13. Los comandos solo-GUI son invisibles para command_list: window.workspace. {editing,assembly,color,effects,audio}, window.workspace.reset, window.toggleFullScreen, app.about. Solo existen en el puente.
14. La exportación HEVC no está disponible aquí ("no encoder registered"). H.264, ProRes, DNxHR, MJPEG, MXF, secuencias de imágenes y audio funcionan.
15. prefs.set en una sesión headless tiene ámbito de sesión — no persistió entre dos sesiones --data-dir. Usa la GUI para preferencias duraderas.
16. Los argumentos de la herramienta MCP son estrictos (clave desconocida → JSON-RPC -32602; tipo incorrecto → isError con un mensaje de deserialización), pero command_run.params se pasa sin modificaciones.

Mapa de referencias

Archivo	Contenido
references/recipes.md	JSON verificado para construir, cortar, efectos, color, subtítulos, gráficos, proxies, multicámara, TTS, exportación, GUI
references/commands.md	los 701 comandos, agrupados por namespace, con documentación de parámetros
references/mcp-and-control.md	Detalles MCP, formas de error, recursos, métodos de control, comandos solo-GUI
references/cli.md	subcomandos de filmcraft-cli, flags, códigos de salida, medios offline, trabajos headless
references/formats-and-roundtrip.md	matriz de exportación + validación independiente, ida y vuelta de intercambio
references/bugs-and-workarounds.md	cada defecto reproducido con una reproducción mínima
references/maintenance.md	re-verificar la versión, volcar comandos, refrescar este skill
scripts/probe.sh	handshake MCP + conteo de herramientas + versión
scripts/dump-commands.sh	regenerar el catálogo de comandos
scripts/smoke-test.sh	construir → renderizar → exportar → validación independiente

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