e1dred/filmcraft

¿Qué hace filmcraft?

Actualizaciones: si esta carpeta tiene un archivo .installed-from (escrito cuando se copió desde el repositorio), ejecuta git ls-remote https://gitlab.com/e1dred/agent-skills.git HEAD una vez por sesión. Toma el hash de la línea de salida que termina exactamente en HEAD; si difiere del contenido del archivo, informa al usuario que existe una versión más reciente y ofrécete a actualizarla (consulta "Actualizando" en https://gitlab.com/e1dred/agent-skills/-/blob/main/INSTALL.md, que puede fusionar ediciones locales); nunca actualices sin preguntar. Compara los hash después de eliminar espacios en blanco. Si no hay archivo, hay un clon o enlace simbólico, o no hay red (salida vacía o error de git ls-remote): omite silenciosamente.

Notas de campo de las primeras tareas headless, probadas por última vez en FilmCraft 0.17.1 (Linux AppImage). FilmCraft es un editor de video en alfa temprana, al estilo Premiere, escrito en Rust. Cada elemento de menú y botón es un comando del motor; la CLI, el servidor MCP y el canal de control de la aplicación ejecutan los mismos comandos. Si filmcraft-cli --version es más reciente, verifica nuevamente cualquier información aquí antes de confiar en ella.

Configuración

• CLI: extráelo del AppImage (filmcraft.appimage --appimage-extract, copia usr/bin/filmcraft-cli a una ubicación estable); es autónomo, sin ventana. Nunca ejecutes --version sobre el AppImage en sí.
• Headless: filmcraft-cli --project p.fcproj exec <id> clave=valor …; los scripts son líneas JSON y mantienen una sesión: filmcraft-cli --project p.fcproj run script.jsonl [--save] con líneas {"id":"…","params":{…}}, o filmcraft-cli run independiente después de file.newProject. Subcomandos: commands, describe, inspect, import, export, render, probe.
• Aplicación en vivo: filmcraft --control 9876 (o FILMCRAFT_CONTROL_PORT); el listener necesita FILMCRAFT_CONTROL_TOKEN (64 caracteres hexadecimales) en el entorno — sin él permanece cerrado. Puentea con filmcraft-cli mcp --bridge 127.0.0.1:9876.
• MCP: filmcraft-cli mcp (headless) o --bridge (en vivo).

Dónde está cada cosa

Lee el archivo que coincida con la tarea; cada uno enumera las secciones que contiene. Usa grep -n en reference/ para encontrar un id de comando.

Archivo en reference/	Léelo para	Secciones
projects-and-timeline.md	Proyectos, importación de medios, secuencias, cabezal de reproducción, cuchilla y recorte, marcadores, guardado, transiciones, efectos de video y fotogramas clave, congelación de fotogramas, notas de proyecto	Proyectos y medios; Secuencias; Corte y recorte; Marcadores y guardado; Transiciones; Efectos de video y fotogramas clave; Congelación de fotogramas, selección y notas de proyecto; Otras herramientas de edición
titles-and-graphics.md	Capas de texto y formas, tamaño/ajuste en fotogramas pequeños, lectura de capas, texto vertical e imágenes importadas	Títulos; Tamaño y ajuste; Propiedades de capa; Otras herramientas de capa
audio-mixer.md	Tiras de mezclador, valores, submezclas, inserciones y envíos; ganancia de clip y Sonido Esencial	Mezclador; Audio de clip
captions.md	Pistas de subtítulos, agregar/editar/mover subtítulos, importación y exportación SRT	Pistas de subtítulos y SRT
export.md	Ajustes preestablecidos y formatos de exportación, la cola de exportación, exportación MP4/GIF, fotogramas fijos, exportaciones de intercambio, sondas	Ajustes preestablecidos; Exportación; Ajustes preestablecidos y cola de exportación; Fotogramas; Sondas
command-catalogue.md	Cada otro id de comando por familia (clip, timeline, sequence, trim, graphics, edit, file, project, multicam, source, prefs, shortcuts, …), cada uno marcado como verificado (ruta JSON antigua → nueva), devolvió un resultado, se ejecutó, o se rechazó con el motivo; la configuración que desbloquea comandos dependientes de selección	Una sección por familia
live-app.md	Conducir la aplicación en ejecución a través de --bridge: las herramientas ui_*, lo que solo funciona en vivo, ejecutarlo en una pantalla oculta	Conexión; Lo que la aplicación en vivo agrega
newer-commands.md	Lo que cada versión agregó o cambió	0.17.0; 0.17.1
log.md	Registro fechado de lo que se probó y cuándo	Registro

CLI esencial (verificado)

filmcraft-cli commands --json                    # 716 comandos: id, etiqueta, menú, parámetros, habilitado
filmcraft-cli describe file.import               # documentación de parámetros para un comando
filmcraft-cli --project p.fcproj inspect         # {project:{…}, sequence:{…}} como 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                     # tipo, duración (ticks), detalles de flujo de video/audio

• Un script JSONL mantiene el estado: file.newProject → file.import {"paths":["clip.mp4"]} → {"items":[1]} → file.newSequenceFromClip {"items":[1]} → {"clips":[6,7],"sequence":4} → … → file.saveAs {"path":"p.fcproj"}.
• Pasa --project en cada llamada CLI posterior: sin él, cada invocación es una sesión nueva.

Trampas

• Los tiempos son ticks, no fotogramas: la secuencia informa 762,048,000,000 para 3 s (254,016,000,000 ticks/s); playhead.set acepta seconds, frame, time o timecode y ajusta al fotograma más cercano (1.5 s → fotograma 37).
• Una capa de texto con el tamaño predeterminado desborda un fotograma pequeño. graphics.newText tiene un tamaño predeterminado de 100 px: en una secuencia de 320×180, "Hola FilmCraft" con size:48 dibujó 334.7 px de ancho desde x=40 y se cortó en el borde derecho. Ajústalo estableciendo size (~32 → 223 px de ancho; verificado en un renderizado). El texto de párrafo con box:[w,h] se ajusta, pero la caja RECORTA las líneas que no caben en su altura: box:[240,60] con tamaño 40 mostró solo "Hola" (la segunda línea se cortó), por lo que la caja debe ser lo suficientemente alta para cada línea (aproximadamente 1.3 × tamaño por línea).
• Las ediciones ripple fallan en una pista bloqueada por sync: timeline.trim con mode:"ripple" respondió "esta edición rompería la sincronización: V2 está bloqueada por sync y tiene un clip en el camino" cuando un título estaba en V2. Bloquea/desbloquea la otra pista primero o recorta sin ripple.
• probe --image-sequence solo acepta fotogramas numerados; en una película da error.
• effects.addKeyframe headless con un mediaTime sin procesar no hizo nada ({added:false, mediaTime:0}; 0.17.0), pero en la aplicación en vivo {clip, effect:"opacity", param:"opacity", seconds:1.5, value:40} agregó uno (fotogramas clave 5 → 6; el tiempo se ajusta a un fotograma: 624699432000). Headless, mueve el cabezal de reproducción y usa effects.toggleAnimation, o graphics.set {…,"keyframe":true} para propiedades de título.
• mixer.addInsert necesita un id de efecto de audio real (hard_limiter, de effects.list {"kind":"Audio"}), no una etiqueta como volume; mixer.addSend necesita la ref de la submezcla de mixer.addSubmix en la misma ejecución.
• Los comandos graphics.* necesitan un título en la misma sesión: ejecuta graphics.newText primero en el mismo script, luego graphics.alignFrame.*, nudge*, fontSize*, leading* funcionan headless (lee graphics.list {clip} → layers[0]). Sin uno, responden "sin clip gráfico". graphics.deleteLayer solo se aceptó en vivo (sin lectura de retorno).
• La selección no sobrevive a un guardado/reapertura: coloca project.select {items:[id]} / timeline.select en el mismo script que el comando que lo necesita ("selecciona un elemento en el panel Proyecto", "no hay clips seleccionados").
• La exportación FCPXML puede omitir un título: file.exportInterchange {"format":"fcpxml"} informó que el clip gráfico "no es compatible" mientras seguía escribiendo el archivo; lee el informe antes de confiar en una exportación de intercambio.
• --demo abre el proyecto de demostración integrado: inspecciona y renderiza (un fotograma de 1920×1080 a 1 s), se exportó bien solo hasta donde se probó; los medios faltantes se exportan como fotogramas de reemplazo a menos que --allow-offline los acepte.
• file.exportMedia espera su archivo a menos que "wait":false; la CLI export siempre espera.

Verifica antes de informar

inspect sequence (inicios/finales de clips en fotogramas, pistas, transiciones, efectos), probe para la duración y códecs del archivo exportado, y render un fotograma en los momentos de interés para examinarlo. Conteo de fotogramas: 3 s a 25 fps = 75 fotogramas; un recorte ripple de -10 fotogramas dio 65.