# 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"](#onde-paramos-e-proximos-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:

1. **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.
2. **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.
3. 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/`.
4. **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`).
5. **Registrar** qualquer correção/erro recorrente em
   `Engine/docs/05_EXPERIENCIAS.md` e rodar `./Engine/run_after_fix.sh`.