LooperSalty/filmcraft

FilmCraft — montagem dirigida por Claude

Instalação neste PC

Elemento	Localização
App + CLI (portátil 0.13.0)	%LOCALAPPDATA%\Programs\FilmCraft\ (filmcraft.exe, filmcraft-cli.exe, dados em data\)
Lançador (canal de controle 127.0.0.1:9876 + token)	{{DEPOT}}\filmcraft-mcp\launcher\FilmCraftClaude.exe (atalho na área de trabalho "FilmCraft")
Token do canal de controle	%LOCALAPPDATA%\FilmCraft-Claude\control.token (nunca exibir nem copiar para outro lugar)
MCP companheiro (Python, uv)	{{DEPOT}}\filmcraft-mcp\server\
Fonte FilmCraft (documentos)	{{DEPOT}}\filmcraft\docs\ (agents.md, control-protocol.md, captions.md, graphics.md)

Inicialização (sempre nesta ordem)

1. filmcraft_status (MCP filmcraft-assist). Se running=false → filmcraft_launch (com files = projeto .fcproj ou mídias se necessário).
2. Carregar as ferramentas MCP se estiverem atrasadas: ToolSearch +filmcraft (os dois servidores).
3. Nunca montar o trabalho do usuário no projeto demo: command_run file.newProject {name} depois file.saveAs {path} na pasta do projeto, ou file.open {path}.

Os dois MCPs

Necessidade	Ferramenta
Estado / iniciar o app	filmcraft_status, filmcraft_launch (assist)
Ler o projeto, os ids	doc_inspect, project_inspect, sequence_inspect (filmcraft)
Agir	command_run {id, params}, command_batch {steps, stop_on_error}, media_import (filmcraft)
Encontrar um comando	command_list {filter} ou grep em references/commands.md
Ver o resultado	render_frame {seconds}, ui_screenshot {panel?} (filmcraft) ; contact_sheet (assist) depois Read da imagem
Analisar um take antes da edição	media_probe → media_conform se VFR (assist)
Transcrição palavra por palavra (PT)	transcribe_media (assist) — nunca transcript.generate (whisper-base, fraco em português)
Sincronizar com música	music_beats {add_markers, every, offset_seconds} (assist)
Controle de qualidade final	export_qc {path, platform} (assist)

Fora do MCP, a CLI também funciona em Bash (headless, sem janela): filmcraft-cli --project p.fcproj --save exec <id> key=value, filmcraft-cli --project p.fcproj export out.mp4 --preset "YouTube 1080p Full HD".

Loop de trabalho

1. Inspecionar (sequence_inspect) → obter os ids de clipes/elementos. Os ids mudam após um razor: reinspccionar.
2. Agir com alvos explícitos (clips: [id], item: id) em vez da seleção.
3. Verificar olhando: render_frame nos pontos-chave, scopes.read para colorização, contact_sheet para ritmo.
4. Se estiver errado: command_run edit.undo. Salvar com frequência: file.save.

Regras que evitam erros

• Tempo: ticks (254 016 000 000 / s). A maioria dos comandos aceita seconds, frame ou timecode → preferir seconds. markers.add e sequence.addEdit querem time em ticks.
• Sequência = formato de saída: file.newSequence {name, width, height, fps, sampleRate: 48000} configurada para difusão (16:9 1920×1080, 9:16 1080×1920, 1:1 1080×1080), taxa de quadros = a dos takes conformados.
• Palavras de preenchimento em português: transcript.removeFillers tem uma lista inglesa padrão → sempre passar fillers (retornado por transcribe_media).
• Exportações longas: file.exportMedia {…, wait: true}. Sempre finalizar com export_qc depois contact_sheet no arquivo exportado.
• O ffmpeg do PATH é uma versão de 2013: usar as ferramentas assist (ffmpeg 8 WinGet) ou %LOCALAPPDATA%\Microsoft\WinGet\Links\ffmpeg.exe.
• Comando recusado "not available right now": falta uma condição (sequência aberta, clipe do tipo certo, alvo). Ler command_list {filter: "<id>"} → campo enabled.

Receitas

Receitas detalhadas com os parâmetros exatos: references/recipes.md.

• A. Tutorial / câmera na cara: probe → conform → transcrição → cortar "ehs" e espaços → voz limpa → legendas → colorização → export -14 LUFS → QC.
• B. Short vertical 9:16: sequência 1080×1920, recorte, legendas grandes e curtas, predefinição "Social Vertical 1080×1920".
• C. Edição com música: music_beats → marcadores de compasso → cortes nos marcadores → ducking.
• D. Colorização: Lumetri (parâmetros reais em references/effects.md, efeito lumetri), correspondência de planos lumetri.applyMatch, controle scopes.read.
• E. Mixagem: Essential Sound (diálogo/música), ducking, limitador true peak no Mix.
• F. Export + QC: predefinições em references/export-presets.md, loudnessLufs, captionSidecar, burnCaptions.

Referências

• references/recipes.md — passo a passo das receitas A–F com cargas JSON.
• references/commands.md — os 710 comandos por família (grep: `timeline., `captions., `lumetri., `essentialSound., `export., `transcript.).
• references/effects.md — 303 efeitos/transições com ids de parâmetros, limites e opções (grep `lumetri`, `hard_limiter`, `cross_dissolve`).
• references/export-presets.md — 39 predefinições de exportação.
• scripts/gen_reference.py — regenera as três referências após uma atualização do FilmCraft: python -I scripts/gen_reference.py.

Atualização do FilmCraft

Baixar filmcraft-<ver>-windows-x64-portable.zip de github.com/storytold/filmcraft/releases (verificar SHA256SUMS.txt), fechar FilmCraft, substituir filmcraft.exe e filmcraft-cli.exe em %LOCALAPPDATA%\Programs\FilmCraft\ (manter data\ e portable.txt), depois executar novamente scripts/gen_reference.py.