chore: adiciona .gitignore e commit.command
This commit is contained in:
João Henrique
@@ -0,0 +1,114 @@
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user