07 — Estudo (SUSPENSO): Detectar o Projeto Ativo no Final Cut Pro

Status: SUSPENSO (2026-08-14). Estudo retomável. Ver seção "Onde parámos e próximos passos" ao fundo.

Objetivo

Descobrir se é possível detectar, de forma programática, qual projeto/timeline está aberto e em edição no Final Cut Pro — não apenas enumerar os projetos — para que as ferramentas do MCP possam operar sobre o projeto ativo.

Contexto atual do repositório: fcpxml/live.py já implementa list_fcp_libraries (enumerar bibliotecas → eventos → projetos) e push_to_fcp (import via Open Document). O que falta é saber qual projeto o usuário está vendo/editando.

Fatos verificados na máquina (2026-08-14)

FCP está em execução, mas o executável não está em /Applications: localizado em /Volumes/Merongo/Applications/Final Cut Pro Creator Studio.app. Aplicativo aparece como "Final Cut Pro Creator Studio" mas o bundle id é com.apple.FinalCut (processo Final Cut Pro).
Ambiente: osascript funciona (permissão de automação concedida para o host).

Superfície oficial: AppleScript (`ProEditor.sdef`)

O dicionário oficial fica em: /Volumes/Merongo/Applications/Final Cut Pro Creator Studio.app/Contents/Resources/ProEditor.sdef

Observações estruturais do .sdef:

Top-level = somente libraries → events → projects/sequences.
NÃO existe propriedade active project, front project ou active sequence no dicionário. A única leitura possível é get (100% read-only).
O sdef inclui a suite padrão (CocoaStandard.sdef), o que traz document.

Testes de terminal (resultados reais)

Comando (via `osascript`)	Resultado
`get name of front document`	`Biblioteca Padrão` — retorna a biblioteca em primeiro plano (class `document` que corresponde a um `library`; o id casa com um `library`).
`get class of front document`	`document`
`get name of front window`	`Final Cut Pro` (apenas o nome da janela do app, não o projeto)
`front project`	erro (`Não é possível obter project 1`)
`active document`	erro de sintaxe (`active` não é palavra-chave)
`events of front document`	erro `-1728` (eventos ficam em `library`, não em `document`)
`get name of every project`	erro `-1728` (projetos não são top-level)

Conclusão da superfície oficial

✅ Dá para detectar a biblioteca em primeiro plano via front document (equivalente a libraries de maior prioridade na lista).
❌ NÃO dá para detectar o projeto ativo (a timeline em edição) apenas pelo AppleScript oficial.

Superfície não-oficial: CommandPost

CommandPost instalado: v1.4.13 em /Applications/CommandPost.app (versão 1, gratuita; NÃO é a v2 que requer LateNite). LateNite não está instalado.

Na v1.4.13 não estava rodando e a porta WebSocket 27480 estava fechada (essa porta é do servidor WebSocket da v2). Logo, a integração via WS na porta 27480 não se aplica a esta instalação.
O app é baseado em Hammerspoon e tem um comando AppleScript próprio: execute lua code (declarado em /Applications/CommandPost.app/Contents/Resources/CommandPost.sdef). Isso permite rodar Lua dentro do ambiente do CommandPost (que tem acesso à árvore Accessibility/AX do FCP e à API cp.*).
O CommandPost usa Accessibility (AX) scripting para ler o FCP. A API interna (cp.apple.finalcutpro) é extensa e profunda; os caminhos para "documento ativo" não são uma propriedade direta e limpa — são derivados da árvore AX (ex.: título da janela da timeline).

Superfície não-oficial: AX direto (System Events)

Testado: ler títulos das janelas do processo "Final Cut Pro" via System Events:

tell application "System Events" to tell process "Final Cut Pro" to get title of every window

Resultado: erro -25211 — "osascript é um acesso assistivo não permitido" (o host não tem permissão de Accessibility/Assistive Access).
Isso é uma permissão de sistema (System Settings → Privacy & Security → Accessibility) que precisa ser concedida ao processo host.
A princípio o título da janela da timeline do FCP contém o nome do projeto, o que tornaria essa a via mais simples — desde que a permissão AX exista.

Mapa de decisão (resumo)

Via	Detecta projeto ativo?	Permissão extra	Robustez
AppleScript oficial (`front document`)	Só a biblioteca, não o projeto	Automação (já ok)	Alta (sanctioned)
CommandPost `execute lua code`	Sim (via AX/`cp.*`)	CommandPost rodando + AX do CommandPost	Média (frágil a updates do FCP)
AX direto (`System Events` título da janela)	Sim (título da timeline tem o projeto)	Accessibility no host	Média-alta
CommandPost v2 WS porta 27480	Sim	CommandPost v2 + LateNite (~US$10)	— (não aplicável aqui, é v1)

Onde paramos e próximos passos

Estado: investigação inicial feita; nenhum código foi escrito/alterado. Nenhum arquivo do repositório foi modificado; nada foi commitado.

Próximos passos sugeridos ao retomar:

Decidir a via — provavelmente a mais promissora e de menor custo é a AX direta via System Events (ler o título da janela da timeline), pois dispensa CommandPost. Requer apenas conceder Accessibility ao host.
Conceder permissão de Accessibility ao terminal/host em System Settings → Privacy & Security → Accessibility, e re-testar:
```
tell application "System Events" to tell process "Final Cut Pro" to get title of every window
```
Confirmar que o título da timeline contém o nome do projeto ativo.
Se AX direto for inviável, testar CommandPost execute lua code: iniciar o CommandPost, e via osascript executar Lua que consulta a árvore AX do FCP (ex.: a janela PrimaryWindow / a timeline) para extrair o título. A API interna relevante vive em extensions/cp/apple/finalcutpro/.
Projetar o tool MCP (ex.: get_fcp_active_project / detect_fcp_project), seguindo o padrão de handle_* em server.py e a documentação de boas práticas (Engine/docs/06_BOAS_PRATICAS.md).
Registrar qualquer correção/erro recorrente em Engine/docs/05_EXPERIENCIAS.md e rodar ./Engine/run_after_fix.sh.

6.3 KiB Raw Blame History