gart/code/Engine/docs/02_MODULES.md

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.