docs: varredura geral, documentação por função e regra de atualização
A documentação descrevia um sistema que não existe mais: 62/73 ferramentas
(são 74), writer.py e models.py como arquivos (viraram pacotes), 1032 testes
(são 1454), models_api.py descrito como "API FastAPI" (é ponte JSON) e o app
SwiftUI ausente por completo — 5.500 linhas que o usuário opera todo dia sem
uma linha de documentação.
Cada arquivo passa a ter uma função específica, com cabeçalho de escopo
dizendo o que cobre e o que NÃO cobre (com a seta para quem cobre). O objetivo
é ler só o necessário: doc fora do assunto custa tempo e processamento sem
entregar nada.
01 arquitetura camadas, duas portas de entrada, regras transversais
02 módulos mapa do engine, incluindo o pipeline de voz
03 server/tools as 74 tools, helpers e como criar uma nova
08 app macOS NOVO — build por swiftc, telas, ponte, etapa 5
09 manutenção NOVO — por onde começar, o que está aberto, sintoma→arquivo
CLAUDE.md ganha a seção "Documentação (MANDATORY)": tabela de roteamento
(qual arquivo abrir para cada tarefa) e a regra de que toda alteração de
código atualiza a doc no mesmo commit, com o mapa de o-que-mexeu → o-que-
atualizar. Doc velha engana mais que doc ausente.
O índice do 05_EXPERIENCIAS subiu para o topo: consultar "isso já quebrou
antes?" custava carregar 1.281 linhas antes de chegar na tabela.
Dívidas levantadas na varredura e registradas em 09 §2: etapa 6 ainda ignora
o phrase_review.json, offset de ~400ms do Whisper, MacApp sem teste, admin/
fora do lint, confirmações visuais pendentes no FCP, submódulo WHISPERX sujo.
Também corrigidos dois links quebrados no Engine/README que apontavam um
nível acima do certo.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
João Henrique
co-authored by
Claude Opus 5
Claude Opus 5
parent
ffaebb3f72
commit
dcdd73edb5
@@ -9,25 +9,91 @@ normalmente; a regra é sobre a comunicação com o usuário.
|
||||
|
||||
## What This Is
|
||||
|
||||
MCP server that reads/writes Final Cut Pro XML (FCPXML) files. 73 tools for timeline analysis, batch editing, QC, generation, multi-track support, media relink, NLE export, transcript-based editing (local Whisper), and LIVE FCP control (push_to_fcp / list_fcp_libraries via Apple events). Reads FCPXML 1.8–1.14 (incl. `.fcpxmld` bundles with sidecar preservation), writes 1.13 by default. Dual-mode (XML + Live) direction: `code/docs/CAPABILITY-AUDIT-2026-06.md`.
|
||||
MCP server that reads/writes Final Cut Pro XML (FCPXML) files. 74 tools for timeline analysis, batch editing, QC, generation, multi-track support, media relink, NLE export, transcript-based editing (local Whisper), and LIVE FCP control (push_to_fcp / list_fcp_libraries via Apple events). Reads FCPXML 1.8–1.14 (incl. `.fcpxmld` bundles with sidecar preservation), writes 1.13 by default. Dual-mode (XML + Live) direction: `code/docs/CAPABILITY-AUDIT-2026-06.md`.
|
||||
|
||||
## Architecture
|
||||
|
||||
Toda a estrutura do projeto fica em `code/`. A pasta `admin/` fica na raiz (fora de `code/`).
|
||||
|
||||
```
|
||||
code/server.py — MCP server entry point. All 62 tool definitions, handlers, resources, prompts.
|
||||
Dispatch dict pattern: TOOL_HANDLERS maps tool names → async handler functions.
|
||||
Há **duas portas de entrada** para o mesmo engine: o MCP (Claude decide a
|
||||
edição) e a ponte JSON (o app macOS opera). Nenhuma das duas tem lógica de
|
||||
timeline — as duas delegam a `fcpxml/`.
|
||||
|
||||
code/fcpxml/parser.py — Reads FCPXML → Python objects (Timeline, Clip, ConnectedClip, Marker, etc.)
|
||||
code/fcpxml/writer.py — Writes modifications back to FCPXML. Handles markers, trimming, gaps, transitions.
|
||||
code/fcpxml/rough_cut.py — Generates new timelines from source clips (rough cuts, montages, A/B rolls).
|
||||
code/fcpxml/diff.py — Timeline comparison engine. Detects added/removed/moved/trimmed clips & markers.
|
||||
code/fcpxml/export.py — DaVinci Resolve FCPXML v1.9 export + FCP7 XMEML v5 export for cross-NLE workflows.
|
||||
code/fcpxml/models.py — Data classes: TimeValue, Timecode, Clip, ConnectedClip, CompoundClip, Timeline, etc.
|
||||
code/fcpxml/media_intel.py — Real media analysis. Audio silence detection + beat detection.
|
||||
code/fcpxml/dtd.py — Validates output against Apple's official DTDs.
|
||||
```
|
||||
code/server.py — MCP entry point (592 linhas). Só dispatch: TOOL_HANDLERS.
|
||||
code/server_tools/ — Os handlers das 74 tools, um módulo por categoria.
|
||||
code/server_tools/_shared/ — Helpers compartilhados (paths, project, formatting,
|
||||
captions, detection, media).
|
||||
|
||||
code/fcpxml/parser.py — Reads FCPXML → Python objects (Timeline, Clip, Marker…)
|
||||
code/fcpxml/writer/ — PACOTE. Edição/escrita de FCPXML. FCPXMLModifier é
|
||||
montado por mixins, um por assunto (markers, trim,
|
||||
speed, titles, cut, silence…). Ver writer/modifier.py.
|
||||
code/fcpxml/models/ — PACOTE. Data classes por família: timing, timeline,
|
||||
enums, subtitles, qc, planning.
|
||||
code/fcpxml/rough_cut.py — Generates new timelines (rough cuts, montages, A/B rolls).
|
||||
code/fcpxml/diff.py — Timeline comparison engine.
|
||||
code/fcpxml/export.py — DaVinci Resolve v1.9 + FCP7 XMEML v5 export.
|
||||
code/fcpxml/media_intel.py — Silence detection + beat detection.
|
||||
code/fcpxml/dtd.py — Validates output against Apple's official DTDs.
|
||||
code/fcpxml/voice_*.py — Pipeline de voz: features → emphasis → voice_timeline
|
||||
→ voice_actions → phrase_review. Ver Engine/docs/02.
|
||||
|
||||
admin/models_api.py — Ponte JSON com o app: docstring de comandos + dispatch.
|
||||
admin/api/ — Os 37 comandos, um módulo por assunto.
|
||||
code/MacApp/Sources/ — App SwiftUI. Compilado por swiftc (sem Xcode/SPM).
|
||||
```
|
||||
|
||||
Os dois `__init__.py` de pacote (`writer/`, `models/`) reexportam tudo, então
|
||||
`from .writer import FCPXMLModifier` e `from .models import TimeValue` seguem
|
||||
valendo em todo o projeto.
|
||||
|
||||
## Documentação (MANDATORY)
|
||||
|
||||
A documentação viva fica em `code/Engine/docs/`. Cada arquivo tem **uma função
|
||||
específica** — leia só o que a tarefa exige, não o conjunto. Carregar
|
||||
documentação que não é do assunto custa tempo e processamento sem entregar nada.
|
||||
|
||||
### Qual arquivo abrir
|
||||
|
||||
| Sua tarefa | Abra | Não precisa de |
|
||||
|-----------|------|----------------|
|
||||
| Entender como o sistema é dividido | `01_ARCHITECTURE.md` | o resto |
|
||||
| Achar onde mora uma função do engine | `02_MODULES.md` | 01, 03 |
|
||||
| Criar/alterar uma ferramenta MCP | `03_SERVER_TOOLS.md` | 08 |
|
||||
| Entender ou rodar os testes | `04_TESTS_AND_WORKFLOW.md` | — |
|
||||
| "Isso já quebrou antes?" | `05_EXPERIENCIAS.md` — **só o índice no topo** | as entradas que não são a sua |
|
||||
| Checklist antes de fechar | `06_BOAS_PRATICAS.md` | — |
|
||||
| Mexer no app / no Assistente | `08_APP_MACOS.md` | 02, 03 |
|
||||
| Escolher o que fazer, ver o que está aberto | `09_MANUTENCAO.md` | — |
|
||||
|
||||
Quando não souber por onde começar: `09_MANUTENCAO.md`. Ele roteia para o resto.
|
||||
|
||||
### Regra de atualização (obrigatória)
|
||||
|
||||
**Toda alteração de código atualiza a documentação no mesmo commit.** Doc velha
|
||||
engana mais do que doc ausente — quem lê confia nela e erra com confiança.
|
||||
|
||||
| Você alterou | Atualize |
|
||||
|--------------|----------|
|
||||
| Estrutura de pastas, camadas ou dependências | `01_ARCHITECTURE.md` |
|
||||
| Criou/moveu/dividiu módulo em `fcpxml/` | `02_MODULES.md` (tabela + linhas) |
|
||||
| Criou/removeu ferramenta MCP | `03_SERVER_TOOLS.md` + contagem no `CLAUDE.md` |
|
||||
| Comando da ponte | docstring de `admin/models_api.py` + `08_APP_MACOS.md` |
|
||||
| Tela ou fluxo do app | `08_APP_MACOS.md` |
|
||||
| Resolveu ou abriu uma dívida | `09_MANUTENCAO.md` §2 |
|
||||
| Bateu num problema estrutural ou erro recorrente | `05_EXPERIENCIAS.md` + **índice no topo** |
|
||||
|
||||
Se um número (tools, testes, linhas) mudou, corrija onde ele aparece. Se um
|
||||
documento divergir do código, **o código está certo** — conserte o documento.
|
||||
|
||||
### Ao escrever documentação
|
||||
|
||||
- **Um assunto por arquivo.** Se um doc começar a cobrir dois, divida.
|
||||
- **Diga o que não está ali** e para onde ir — economiza a leitura seguinte.
|
||||
- **Fatos verificados**, não suposições: rode o comando e use o número real.
|
||||
- **Registre o porquê**, não só o quê. O "o quê" está no código; o "por quê"
|
||||
se perde, e é o que evita alguém desfazer uma decisão por engano.
|
||||
|
||||
## Key Patterns
|
||||
|
||||
@@ -88,7 +154,7 @@ CI runs both on every push to main. If either fails, the commit gets an X on Git
|
||||
|
||||
## Testing
|
||||
|
||||
1342 tests across 34 files. `test_models.py` covers TimeValue arithmetic, Timecode parsing/formatting, Clip properties, validation models, and Timeline helpers. `test_writer.py` covers insert_clip, add_marker (all types), trim_clip, delete_clip, split_clip, and change_speed operations. `test_server.py` covers MCP tool handlers, parsers, and dispatch. `test_rough_cut.py` covers RoughCutGenerator. `test_features_v05.py` covers connected clips, roles, timeline diff, reformat, silence detection, export, and backward compatibility. `test_marker_pipeline.py` covers build_marker_element shared builder, batch auto-modes, clip index duplicate-name behavior, and write_fcpxml output format. `test_refactored_helpers.py` covers _index_elements, _iter_spine_clips, _find_spine_clip_at_seconds, _resolve_clip_duration, _make_asset_clip, _format_batch_result, and serialize_xml edge cases. `test_transcribe.py` covers phrase/filler span matching, range merge/invert algebra, whisper graceful degradation, and transcript-driven handler cuts against cached transcripts. `test_media_intel.py` covers silencedetect stderr parsing, source-to-timeline mapping, parameter bounds, and real-WAV ffmpeg integration (skips without ffmpeg; CI installs it). Tests use `examples/sample.fcpxml` as fixture data and inline XML fixtures. Tests create temp files and clean up after.
|
||||
1454 tests across 42 files, all under `code/tests/`. Um teste fora dessa pasta não roda (`testpaths = ["tests"]`) — se você criar um em outro lugar, confirme que a contagem total subiu. Cobertura por área: `test_models.py` (TimeValue/Timecode/Clip/Timeline), `test_writer.py` (insert/marker/trim/delete/split/speed), `test_server.py` (handlers e dispatch), `test_rough_cut.py`, `test_features_v05.py` (connected clips, roles, diff, reformat, silêncio, export), `test_marker_pipeline.py`, `test_refactored_helpers.py`, `test_transcribe.py`, `test_media_intel.py` (pula sem ffmpeg; o CI instala), `test_phrase_review.py` (revisão de frases da etapa 5) e `test_models_api.py` (comandos da ponte). Fixtures: `examples/sample.fcpxml` e XML inline. Os testes criam temporários e limpam depois.
|
||||
|
||||
## FCPXML Gotchas
|
||||
|
||||
|
||||
Reference in New Issue
Block a user