LooperSalty/filmcraft

FilmCraft — edición impulsada por Claude

Instalación en este PC

Elemento	Ubicación
App + CLI (portátil 0.13.0)	%LOCALAPPDATA%\Programs\FilmCraft\ (filmcraft.exe, filmcraft-cli.exe, datos en data\)
Lanzador (canal de control 127.0.0.1:9876 + token)	{{DEPOT}}\filmcraft-mcp\launcher\FilmCraftClaude.exe (acceso directo en escritorio «FilmCraft»)
Token del canal de control	%LOCALAPPDATA%\FilmCraft-Claude\control.token (nunca mostrarlo ni copiarlo a otro lugar)
MCP compañero (Python, uv)	{{DEPOT}}\filmcraft-mcp\server\
Código fuente FilmCraft (docs)	{{DEPOT}}\filmcraft\docs\ (agents.md, control-protocol.md, captions.md, graphics.md)

Inicio (siempre en este orden)

1. filmcraft_status (MCP filmcraft-assist). Si running=false → filmcraft_launch (con files = proyecto .fcproj o medios si es necesario).
2. Cargar las herramientas MCP si son diferidas: ToolSearch +filmcraft (ambos servidores).
3. Nunca montar el trabajo del usuario en el proyecto demo: command_run file.newProject {name} luego file.saveAs {path} en la carpeta del proyecto, o file.open {path}.

Los dos MCP

Necesidad	Herramienta
Estado / iniciar la app	filmcraft_status, filmcraft_launch (assist)
Leer el proyecto, los ids	doc_inspect, project_inspect, sequence_inspect (filmcraft)
Acción	command_run {id, params}, command_batch {steps, stop_on_error}, media_import (filmcraft)
Buscar un comando	command_list {filter} o grep en references/commands.md
Ver el resultado	render_frame {seconds}, ui_screenshot {panel?} (filmcraft); contact_sheet (assist) luego Read de la imagen
Analizar un clip antes de editar	media_probe → media_conform si VFR (assist)
Transcripción palabra por palabra (ES)	transcribe_media (assist) — nunca transcript.generate (whisper-base, débil en español)
Sincronizar con la música	music_beats {add_markers, every, offset_seconds} (assist)
Control de calidad final	export_qc {path, platform} (assist)

Fuera del MCP, el CLI también funciona en Bash (sin cabeza, sin ventana): filmcraft-cli --project p.fcproj --save exec <id> key=value, filmcraft-cli --project p.fcproj export out.mp4 --preset "YouTube 1080p Full HD".

Ciclo de trabajo

1. Inspeccionar (sequence_inspect) → obtener los ids de clips/elementos. Los ids cambian después de un razor: volver a inspeccionar.
2. Accionar con objetivos explícitos (clips: [id], item: id) en lugar de la selección.
3. Verificar mirando: render_frame en los puntos clave, scopes.read para la corrección de color, contact_sheet para el ritmo.
4. Si está mal: command_run edit.undo. Guardar a menudo: file.save.

Reglas que evitan errores

• Tiempo: ticks (254 016 000 000 / s). La mayoría de los comandos aceptan seconds, frame o timecode → preferir seconds. markers.add y sequence.addEdit quieren time en ticks.
• Secuencia = formato de salida: file.newSequence {name, width, height, fps, sampleRate: 48000} configurada para la difusión (16:9 1920×1080, 9:16 1080×1920, 1:1 1080×1080), cadencia = la de los clips conformados.
• Tics de lenguaje en español: transcript.removeFillers tiene una lista inglesa por defecto → siempre pasar fillers (devuelta por transcribe_media).
• Exportaciones largas: file.exportMedia {…, wait: true}. Siempre terminar con export_qc luego contact_sheet sobre el archivo exportado.
• El ffmpeg del PATH es una versión de 2013: usar las herramientas assist (ffmpeg 8 WinGet) o %LOCALAPPDATA%\Microsoft\WinGet\Links\ffmpeg.exe.
• Comando rechazado «not available right now»: falta una condición (secuencia abierta, clip del tipo correcto, objetivo). Leer command_list {filter: "<id>"} → campo enabled.

Recetas

Recetas detalladas con los parámetros exactos: references/recipes.md.

• A. Tutorial / cara a cámara: probe → conform → transcripción → cortar muletillas y espacios → voz limpia → subtítulos → corrección de color → exportación -14 LUFS → QC.
• B. Short vertical 9:16: secuencia 1080×1920, recorte, subtítulos grandes y cortos, preajuste «Social Vertical 1080×1920».
• C. Edición con música: music_beats → marcadores de compás → cortes en marcadores → ducking.
• D. Corrección de color: Lumetri (parámetros reales en references/effects.md, efecto lumetri), emparejamiento de planos lumetri.applyMatch, control scopes.read.
• E. Mezcla: Essential Sound (diálogo/música), ducking, limitador true peak en Master.
• F. Exportación + QC: preajustes en references/export-presets.md, loudnessLufs, captionSidecar, burnCaptions.

Referencias

• references/recipes.md — paso a paso de las recetas A–F con cargas JSON.
• references/commands.md — los 710 comandos por familia (grep: `timeline., `captions., `lumetri., `essentialSound., `export., `transcript.).
• references/effects.md — 303 efectos/transiciones con ids de parámetros, límites y opciones (grep `lumetri`, `hard_limiter`, `cross_dissolve`).
• references/export-presets.md — 39 preajustes de exportación.
• scripts/gen_reference.py — regenera las tres referencias después de una actualización de FilmCraft: python -I scripts/gen_reference.py.

Actualización de FilmCraft

Descargar filmcraft-<ver>-windows-x64-portable.zip desde github.com/storytold/filmcraft/releases (verificar SHA256SUMS.txt), cerrar FilmCraft, reemplazar filmcraft.exe y filmcraft-cli.exe en %LOCALAPPDATA%\Programs\FilmCraft\ (mantener data\ y portable.txt), y luego ejecutar scripts/gen_reference.py.