e1dred/filmcraft

O que filmcraft faz?

Atualizações: se esta pasta tiver um arquivo .installed-from (escrito quando foi copiado do repositório), execute git ls-remote https://gitlab.com/e1dred/agent-skills.git HEAD uma vez por sessão. Pegue o hash na linha de saída que termina exatamente com HEAD; se diferir do arquivo, informe ao usuário que uma versão mais recente existe e ofereça-se para atualizá-la (consulte "Atualizando" em https://gitlab.com/e1dred/agent-skills/-/blob/main/INSTALL.md, que pode mesclar edições locais); nunca atualize sem perguntar. Compare os hashes após remover espaços em branco. Se não houver arquivo, um clone ou link simbólico, ou nenhuma rede (saída vazia ou um erro de git ls-remote): ignore silenciosamente.

Notas de campo das primeiras tarefas headless, testado pela última vez no FilmCraft 0.17.1 (Linux AppImage). O FilmCraft é um editor de vídeo no estilo Premiere em Rust, em fase alfa inicial. Cada item de menu e botão é um comando do mecanismo; a CLI, o servidor MCP e o canal de controle do aplicativo executam os mesmos comandos. Se filmcraft-cli --version for mais recente, verifique novamente qualquer coisa aqui antes de confiar.

Configuração

• CLI: extraia-o do AppImage (filmcraft.appimage --appimage-extract, copie usr/bin/filmcraft-cli para algum local estável); autossuficiente, sem janela. Nunca execute --version no próprio AppImage.
• Headless: filmcraft-cli --project p.fcproj exec <id> key=value …; scripts são linhas JSON e mantêm uma sessão: filmcraft-cli --project p.fcproj run script.jsonl [--save] com linhas {"id":"…","params":{…}}, ou filmcraft-cli run autônomo após file.newProject. Subcomandos: commands, describe, inspect, import, export, render, probe.
• Aplicativo ao vivo: filmcraft --control 9876 (ou FILMCRAFT_CONTROL_PORT); o ouvinte precisa de FILMCRAFT_CONTROL_TOKEN (64 caracteres hexadecimais) no ambiente — sem ele, permanece fechado. Faça a ponte com filmcraft-cli mcp --bridge 127.0.0.1:9876.
• MCP: filmcraft-cli mcp (headless) ou --bridge (ao vivo).

Onde as coisas estão

Leia o arquivo que corresponde à tarefa; cada um lista as seções que contém. Use grep -n em reference/ para encontrar um id de comando.

Arquivo em reference/	Leia para	Seções
projects-and-timeline.md	Projetos, importação de mídia, sequências, playhead, razor e trim, marcadores, salvar, transições, efeitos de vídeo e keyframes, frame holds, notas do projeto	Projetos e mídia; Sequências; Corte e trim; Marcadores e salvar; Transições; Efeitos de vídeo e keyframes; Frame holds, seleção e notas do projeto; Outras ferramentas de edição
titles-and-graphics.md	Camadas de texto e forma, tamanho/ajuste em quadros pequenos, leitura de camadas, texto vertical e imagens importadas	Títulos; Dimensionamento e ajuste; Propriedades da camada; Outras ferramentas de camada
audio-mixer.md	Strips do mixer, valores, submixes, inserts e sends; ganho do clipe e Essential Sound	Mixer; Áudio do clipe
captions.md	Trilhas de legenda, adicionar/editar/mover legendas, importação e exportação SRT	Trilhas de legenda e SRT
export.md	Predefinições e formatos de exportação, fila de exportação, exportação MP4/GIF, imagens estáticas, exportações de intercâmbio, sondagem	Predefinições; Exportação; Predefinições e fila de exportação; Imagens estáticas; Sondagem
command-catalogue.md	Cada outro id de comando por família (clip, timeline, sequence, trim, graphics, edit, file, project, multicam, source, prefs, shortcuts, …), cada um marcado como verificado (caminho JSON antigo → novo), retornou um resultado, executou ou recusou com o motivo; a configuração que desbloqueia comandos dependentes de seleção	Uma seção por família
live-app.md	Conduzir o aplicativo em execução via --bridge: as ferramentas ui_*, o que funciona apenas ao vivo, executá-lo em uma tela oculta	Conectando; O que o aplicativo ao vivo adiciona
newer-commands.md	O que cada versão adicionou ou alterou	0.17.0; 0.17.1
log.md	Registro datado do que foi testado e quando	Registro

Comandos essenciais da CLI (verificados)

filmcraft-cli commands --json                    # 716 comandos: id, label, menu, params, enabled
filmcraft-cli describe file.import               # documentação de parâmetros para um 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, duração (ticks), detalhes do stream de vídeo/áudio

• Um script JSONL mantém estado: file.newProject → file.import {"paths":["clip.mp4"]} → {"items":[1]} → file.newSequenceFromClip {"items":[1]} → {"clips":[6,7],"sequence":4} → … → file.saveAs {"path":"p.fcproj"}.
• Passe --project em cada chamada CLI posterior: sem ele, cada invocação é uma nova sessão.

Armadilhas

• Os tempos são em ticks, não em quadros: a sequência relata 762.048.000.000 para 3 s (254.016.000.000 ticks/s); playhead.set aceita seconds, frame, time ou timecode e snap para o quadro mais próximo (1,5 s → quadro 37).
• Uma camada de texto no tamanho padrão transborda em um quadro pequeno. graphics.newText padroniza para 100 px: em uma sequência de 320×180, "Hello FilmCraft" com size:48 desenhou 334,7 px de largura a partir de x=40 e foi cortada na borda direita. Ajuste definindo size (~32 → 223 px de largura; verificado em um render). Texto de parágrafo com box:[w,h] quebra linhas, mas a caixa CORTA linhas que não cabem em sua altura: box:[240,60] com tamanho 40 mostrou apenas "Hello" (a segunda linha foi cortada); portanto, faça a caixa alta o suficiente para cada linha (cerca de 1,3 × tamanho por linha).
• Edições ripple falham em uma trilha sync-locked: timeline.trim com mode:"ripple" respondeu "esta edição quebraria a sincronia: V2 está sync-locked e tem um clipe no caminho" quando um título estava em V2. Bloqueie/desbloqueie a outra trilha primeiro ou corte sem ripple.
• probe --image-sequence aceita apenas imagens estáticas numeradas; em um filme, ele gera erro.
• effects.addKeyframe headless com um mediaTime bruto não fez nada ({added:false, mediaTime:0}; 0.17.0), mas no aplicativo ao vivo {clip, effect:"opacity", param:"opacity", seconds:1.5, value:40} adicionou um (keyframes 5 → 6; o tempo snap para um quadro: 624699432000). Headless, mova o playhead e use effects.toggleAnimation, ou graphics.set {"…","keyframe":true} para propriedades de título.
• mixer.addInsert precisa de um id de efeito de áudio real (hard_limiter, de effects.list {"kind":"Audio"}), não de um rótulo como volume; mixer.addSend precisa da ref do submix de mixer.addSubmix na mesma execução.
• Os comandos graphics.* precisam de um título na mesma sessão: execute graphics.newText primeiro no mesmo script, depois graphics.alignFrame.*, nudge*, fontSize*, leading* funcionam headless (leia graphics.list {clip} → layers[0]). Sem um, eles respondem "no graphic clip". graphics.deleteLayer foi aceito apenas ao vivo (sem leitura).
• A seleção não sobrevive a salvar/reabrir: coloque project.select {items:[id]} / timeline.select no mesmo script do comando que precisa dela ("select an item in the Project panel", "no clips selected").
• A exportação FCPXML pode perder um título: file.exportInterchange {"format":"fcpxml"} relatou o clipe gráfico "not supported" enquanto ainda escrevia o arquivo; leia o relatório antes de confiar em uma exportação de intercâmbio.
• --demo abre o projeto de demonstração integrado: ele inspeciona e renderiza (um quadro 1920×1080 em 1 s), exportou bem apenas até onde foi testado; mídia ausente é exportada como quadros placeholder a menos que --allow-offline os aceite.
• file.exportMedia aguarda seu arquivo a menos que "wait":false; a CLI export sempre aguarda.

Verifique antes de relatar

inspect sequence (inícios/fins de clipe em quadros, trilhas, transições, efeitos), probe para a duração e codecs do arquivo exportado, e render um quadro nos momentos interessantes para inspecionar. Contagem de quadros: 3 s a 25 fps = 75 quadros; um ripple trim de -10 quadros resultou em 65.