# 02 — Módulos do Engine (`fcpxml/`)

Guia módulo a módulo do núcleo Python. Tamanho em linhas, responsabilidade e as
funções/classes públicas de cada um. APIs públicas são reexportadas em
`fcpxml/__init__.py` (fonte da verdade para o `__all__`).

## Versão atual
`__version__ = "0.6.35"` — ver `fcpxml/__init__.py`.

---

| Módulo | Linhas | Papel |
|--------|-------:|-------|
| `models.py` | 930 | Data classes e enums (tempo, clips, markers, QC) |
| `parser.py` | 367 | FCPXML → objetos Python |
| `writer.py` | 3154 | Edição e escrita de FCPXML (o maior) |
| `rough_cut.py` | 798 | Geração de timelines novas |
| `dtd.py` | 112 | Validação contra DTDs oficiais |
| `safe_xml.py` | 113 | Wrappers `defusedxml` + `serialize_xml()` |
| `media_intel.py` | 173 | Silêncio (ffmpeg) e beats (librosa) |
| `transcribe.py` | 184 | Transcrição Whisper + edição por transcrição |
| `model_manager.py` | 298 | Gestão de modelos Whisper (cache/catálogo) |
| `export.py` | 226 | Export DaVinci Resolve v1.9 + FCP7 XMEML v5 |
| `diff.py` | 269 | Comparação de timelines |
| `live.py` | 273 | Modo Live — push_to_fcp / list_fcp_libraries |
| `templates.py` | 387 | Templates de timeline |
| `__init__.py` | 139 | Reexporta API pública |

---

## `models.py` — modelos e enums
Single source of truth para estrutura de dados. NUNCA mexa aqui sem rodar
`test_models.py`.

- **Tempo:** `TimeValue` (fração racional), `Timecode`.
- **Clips:** `Clip`, `VideoClip`, `AudioClip`, `ConnectedClip` (lane),
  `CompoundClip`, `Transition`.
- **Contêineres:** `Timeline`, `Project`, `Keyword`.
- **Markers:** `Marker`, `MarkerType`, `MarkerColor`, `MARKER_XML_TAGS`.
  `MarkerType` é o dono da serialização (`from_string`/`from_xml_element`/`xml_attrs`).
  Match estrito do atributo `completed` (`'0'`/`'1'`, sem padding).
- **QC:** `SilenceCandidate`, `FlashFrame`, `GapInfo`, `DuplicateGroup`,
  `ValidationIssue`, `ValidationResult`.
- **Geração:** `SegmentSpec`, `PacingConfig`, `PacingStyle`, `RoughCutResult`.

## `parser.py` — leitura
- `parse_fcpxml(path)` → `Project`.
- `FCPXMLParser` — lê spine, connected clips (lanes), secondary storylines, roles.

## `writer.py` — o coração (3154 linhas)
Duas classes principais:

- **`FCPXMLModifier`** — edita documento existente de forma index-based
  (dicts de `clips`/`resources`/`formats`), imune a ambiguidade de nomes duplicados.
  Métodos: `insert_clip`, `add_marker`, `trim_clip`, `delete_clip`, `split_clip`,
  `change_speed`, `cut_clip_ranges` (usado pela remoção de silêncio), etc.
- **`FCPXMLWriter`** — gera FCPXML novo a partir de objetos Python.

Helpers de nível de arquivo: `modify_fcpxml`, `add_marker_to_file`,
`trim_clip_in_file`, `build_marker_element`, `write_fcpxml`, `validate_fcpxml`,
`list_effects`, `FCP_EFFECTS`.

## `rough_cut.py` — geração
- `RoughCutGenerator`, `generate_rough_cut`, `generate_segmented_rough_cut`.

## `media_intel.py` — inteligência de mídia (v0.10)
- Silêncio via `ffmpeg silencedetect` (subprocess limitado), `remove_silence_candidates`,
  mapeamento source→timeline.
- Beats via `librosa` (import lazy, extra `[intelligence]`).
- Degrada para `None` quando `ffmpeg` ausente.

## `transcribe.py` — Whisper local
- `transcribe(media_path, model_size, language)` → dict com `words` (spans).
- `ALLOWED_MODELS` — allowlist de nomes de modelo (também usado por `model_manager`).
- Edição por transcrição: remove filler words, aparar por transcrição.

## `model_manager.py` — gestão de modelos
Catálogo `models.json` + cache no HF hub. Config em `~/.fcp-mcp-server/config.json`.
Funções: `get/save_models_dir`, `list_installed_models`, `download_model`,
`delete_model`, `get/load_selected_model`, `save_selected_model`, `load_catalog`.
Permite cancelamento de download via `threading.Event`. Segue convenções:
allowlist, lazy imports, degradação graciosa.

## `export.py` — cross-NLE
- `DaVinciExporter` — FCPXML v1.9 p/ DaVinci Resolve.
- Export FCP7 XMEML v5.

## `diff.py` — comparação
- `compare_timelines`, `TimelineDiff`, `ClipDiff`, `MarkerDiff`.
- Detecta added/removed/moved/trimmed clips & markers.

## `live.py` — FCP ao vivo (macOS)
- `push_to_fcp(path, library, options)` — Apple event *Open Document* + `<import-options>`.
  Requer `.fcpbundle` p/ zero-click real.
- `list_fcp_libraries()` — AppleScript read-only.

## `templates.py`
- `Template`, `TemplateSlot`, `ClipSpec`, `BUILTIN_TEMPLATES`, `apply_template`,
  `list_templates`. Estruturas prontas: intro/outro, lower thirds, music video.

## `safe_xml.py`
Wrappers `defusedxml` centralizados + `serialize_xml()`. Todo parse/escrita passa aqui.

## `dtd.py`
Valida output contra DTDs oficiais no bundle do FCP (via `xmllint`; exige o caminho
do DTD percent-encoded por causa dos espaços em "Final Cut Pro.app").

---

## Como adicionar um módulo novo
1. Criar `fcpxml/<seu_modulo>.py` — função pura, sem conhecer MCP.
2. Reexportar classes/funções em `fcpxml/__init__.py` (`__all__`).
3. Cobrir em `tests/test_<seu_modulo>.py`.
4. Rodar `./Engine/run_after_fix.sh`.