FilmCraft

FilmCraft — operação do agente

O FilmCraft é um editor de vídeo nativo em Rust (classe Premiere Pro) cuja interface de agente é incorporada: cada ação é um comando com um id. Menus, atalhos, painéis, gestos na linha do tempo, a CLI, o canal de controle, o servidor MCP e a GUI dirigem o mesmo mecanismo. Verificado nas versões 0.10.0–0.13.0 no Windows e Linux.

Caminhos da máquina e ambiente

Plataforma	Binário	CLI	Diretório de dados padrão
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 (em ~/.local/bin ou PATH)	~/Library/Application Support/filmcraft

• Local do log: <data-dir>/Logs/filmcraft.log
• Porta de controle: apenas loopback (--control <porta> ou FILMCRAFT_CONTROL_PORT, ex. 9876 ou 7991 ou 50051)
• Comandos: 710 em 42 namespaces
• Efeitos: 130 efeitos de vídeo, 112 transições de vídeo, 3 transições de áudio

Modelo mental

• Um projeto (.fcproj, JSON) contém bins e itens: Movie, Audio, Image, Sequence, Multi-Camera Source Sequence. project_inspect retorna a árvore, activeSequence e a flag dirty. Uma sequência é ativa; os comandos agem sobre ela.
• Uma sequência possui arrays de faixas video[] e audio[], cada uma {id, name, items[], transitions[], muted, locked, ...}. Um clipe é {clip, item, name, start, duration, startFrame, durationFrames, sourceIn, sourceOut, speed, reverse, enabled, link, gainDb, effects[]} — todos os tempos em ticks.
• Colocar um filme cria dois clipes vinculados (vídeo + áudio) com ids diferentes e link apontando um para o outro. Selecionar um seleciona ambos por padrão.
• Tempo é em ticks inteiros, 254.016.000.000 por segundo (também 48000×5292). seconds e frame são ajustados à grade de quadros; frame e timecode (ex. "00:00:02:12", ou ; para drop-frame) mapeiam exatamente. Prefira frame quando precisar de um corte exato.
• Um comando é {"id": "timeline.razor", "params": {...}}. command_list encontra ids e documentação de parâmetros; command_run executa um (desfazível); command_batch executa vários. Tipos de parâmetros inválidos e comandos desconhecidos falham; nomes de parâmetros desconhecidos são ignorados silenciosamente (veja Armadilhas).
• Verifique relendo (sequence_inspect, project_inspect, captions.list, media.status, jobs.list) ou renderizando (render_frame, file.exportFrame). Um resultado null significa "executou", não "fez o que você quis".

Dois modos de conexão

Modo	Início	Usar para
Headless	filmcraft-cli mcp (--demo, --project p.fcproj, --data-dir d)	sem janela, construções em lote, exportações, scripts
Ponte do aplicativo	filmcraft --control 50051 + filmcraft-cli mcp --bridge 127.0.0.1:50051	a janela real: estado da UI, capturas de tela, cliques, teclas, arrastos, comandos exclusivos da GUI

Iniciando o FilmCraft a pedido do usuário ("起動して" / "start FilmCraft")

Quando o usuário pedir para iniciar ou lançar o FilmCraft (「FilmCraftを起動して」「立ち上げて」「開いて」「start FilmCraft」):

1. Verifique se já está em execução:
   • Windows: Get-Process filmcraft -ErrorAction SilentlyContinue
   • Linux / macOS: pgrep filmcraft
   • Se estiver em execução, verifique se a porta de controle está respondendo (filmcraft-cli --bridge 127.0.0.1:50051 inspect).
   • Se estiver em execução sem uma porta de controle, informe o usuário: "O FilmCraft está atualmente em execução sem uma porta de controle. Salve seu trabalho e reinicie-o, ou permita que eu feche e o reinicie com --control 50051."
2. Inicie com --control <porta> (padrão: 50051) e FILMCRAFT_CONTROL_TOKEN de 64 caracteres:
   • Windows (PowerShell) — use scripts/launch.ps1 para garantir uma janela de desktop visível em WinSta0\Default:

     powershell -File scripts/launch.ps1 -Port 50051
     

     (Isso automaticamente define/persiste FILMCRAFT_CONTROL_TOKEN, configura a porta e inicia uma tarefa interativa para que a GUI fique visível para o usuário logado, em vez de oculta na sessão de fundo).
   • Linux:

     ./scripts/launch.sh 50051
     

   • macOS:

     ./scripts/launch.sh 50051
     

3. Verifique a conexão:
   • Aguarde 1–3 segundos, depois execute filmcraft-cli --bridge 127.0.0.1:50051 inspect.
   • Assim que responder, informe que o FilmCraft está ativo, ouvindo na porta 50051 e pronto para edições ao vivo na linha do tempo e comandos colaborativos.

As 17 ferramentas MCP

Ferramenta	Propósito
command_list	todos os comandos (filter, enabled_only)
command_run	executa um {id, params}
command_batch	executa {steps:[{id,params}], stop_on_error} → {completed, failed, results}
doc_inspect	árvore do projeto + sequência ativa em uma chamada
project_inspect	árvore, itens, sequência ativa, dirty
sequence_inspect	sequência ativa: configurações, faixas, clipes, transições, marcadores
media_import	importa arquivos por caminho absoluto (paths, bin, image_sequence)
render_frame	PNG em seconds (ou playhead), max_side
render_preview	igual a render_frame (ponte: monitor do Programa)
ui_inspect	estado da janela/UI (ferramenta, espaço de trabalho, seleção, diálogo, reprodução, contagem de elementos)
ui_elements	elementos na tela com id, label e rect (prefix)
ui_click	clicar por id ou x,y (button, count, modifiers)
ui_drag	pressionar–mover–soltar entre pontos ou ids de elemento (steps)
ui_key	tecla ou atalho (Space, Cmd+Z, Shift+Delete)
ui_type	digitar no campo focado
ui_screenshot	PNG da janela ou de um panel
ui_control	qualquer método de controle: ui.set, ui.menu.list, ui.playback, …

Recursos: filmcraft://document (48 KB JSON: projeto + sequência) e filmcraft://commands (192 KB catálogo). Sem prompts.

Fluxo de trabalho padrão

1. Sondar. project_inspect / doc_inspect; headless inicia vazio a menos que --demo ou --project. ui_inspect primeiro no modo bridge.
2. Construir. file.newProject → file.import (caminhos absolutos) ou 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. Leia sequence_inspect/captions.list; render_frame em um momento revelador e veja o PNG (isso detecta clipes errados, quadros pretos e transições ausentes que nenhuma leitura de retorno mostra).
6. Exportar. file.exportMedia com wait:true (verifique offlineMedia e o arquivo escrito); file.exportInterchange para ida e volta em NLE.
7. Salvar. file.saveAs (cria diretórios? não — o pai deve existir); então releia project_inspect.dirty (false após salvar).

Encontrando comandos

command_list {filter:"razor"} encontra id, label, menu e parâmetros. filmcraft-cli commands razor, describe <id> e filmcraft-cli inspect fazem o mesmo a partir da shell. Todos os 701 ids com sua documentação de parâmetros estão em references/commands.md; JSON verificado passo a passo está em references/recipes.md.

Comece com: 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.

Armadilhas que custam tempo

1. Parâmetros de comando são tolerantes — chaves desconhecidas e alguns tipos errados são descartados silenciosamente. timeline.trim {seconds:-1} retorna {"delta":0} (a chave é delta); timeline.place {seconds:"2"} coloca em 0; fps:"fast" cai para 23.976. Alguns comandos validam (graphics.set, markers.add), então nunca confie em um erro para pegar um parâmetro ruim. Leia a documentação do parâmetro e então leia o estado de volta.
2. file.newSequence muda a sequência ativa e retorna {sequence: id}. sequence.open espera {item: id} — passar sequence ou um id de clipe causa erro. Após qualquer open/new, releia sequence_inspect.
3. Transições não estão no clipe. Elas vivem em sequence_inspect.video[i].transitions[] como {id, effect, from, to, start, duration, align, reverse, params}. sequence.removeTransition {transitions:[id]}; sequence.setTransition edita duração/alinhamento/parâmetros.
4. Legendas não estão em sequence_inspect. Use captions.list; as cues carregam id, start, end, text. captions.newTrack cai silenciosamente para Subtitle para qualquer string de formato desconhecida.
5. Nunca passe um diretório para file.exportMedia. Isso trava indefinidamente (reproduzido duas vezes, >3 min, sem saída). Use um caminho de arquivo completo.
6. O formato vence a extensão. format:"gif" com out.mp4 escreve out.mp4.gif; ProRes com out.mp4 escreve out.mp4.mov. O path do resultado é autoritativo.
7. timeline.place com duration maior que a origem mantém o último quadro pelo resto do clipe, sem aviso. Apare com a mídia em mente.
8. range:"inOut" sem marcadores exporta a sequência inteira, silenciosamente. range:"custom" + startSeconds/endSeconds é o subintervalo confiável.
9. jobs.list é um comando, não uma ferramenta. command_run {id:"jobs.list"}; jobs.cancel {job} remove o arquivo parcial. wait:false exporta retorna {job, path, poll, cancel}.
10. O material de demonstração é sintético. Exportações de intercâmbio (FCPXML/AAF/OMF) da mídia de demonstração perdem clipes; com mídia real em disco eles fazem ida e volta (veja references/formats-and-roundtrip.md).
11. edit.clear (Backspace) deixa uma lacuna; edit.rippleDelete a fecha. sequence.lift/extract precisam de marcas de entrada/saída na sequência, não uma seleção.
12. lumetri.applyPreset anexa um novo efeito Lumetri cada vez, em vez de substituir a aparência anterior. Remova o efeito antigo ou defina os parâmetros diretamente.
13. Comandos exclusivos da GUI são invisíveis para command_list: window.workspace. {editing,assembly,color,effects,audio}, window.workspace.reset, window.toggleFullScreen, app.about. Eles existem apenas na bridge.
14. Exportação HEVC não está disponível aqui ("no encoder registered"). H.264, ProRes, DNxHR, MJPEG, MXF, sequências de imagens e áudio funcionam.
15. prefs.set em uma sessão headless tem escopo de sessão — não persistiu entre duas sessões --data-dir. Use a GUI para preferências duráveis.
16. Os argumentos das ferramentas MCP são estritos (chave desconhecida → JSON-RPC -32602; tipo errado → isError com uma mensagem de desserialização), mas command_run.params é passado adiante intocado.

Mapa de referência

Arquivo	Conteúdo
references/recipes.md	JSON verificado para construir, cortar, efeitos, cor, legendas, gráficos, proxies, multicâmera, TTS, exportar, GUI
references/commands.md	todos os 701 comandos, agrupados por namespace, com documentação de parâmetros
references/mcp-and-control.md	detalhes do MCP, formatos de erro, recursos, métodos de controle, comandos exclusivos da GUI
references/cli.md	subcomandos do filmcraft-cli, flags, códigos de saída, mídia offline, trabalhos headless
references/formats-and-roundtrip.md	matriz de exportação + validação independente, ida e volta de intercâmbio
references/bugs-and-workarounds.md	cada defeito reproduzido com uma reprodução mínima
references/maintenance.md	reverifique a versão, despeje comandos, atualize esta skill
scripts/probe.sh	handshake MCP + contagem de ferramentas + versão
scripts/dump-commands.sh	regenerar o catálogo de comandos
scripts/smoke-test.sh	construir → renderizar → exportar → validação independente

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