Edição do Final Cut Pro via FCPXML

O que Edição do Final Cut Pro via FCPXML faz?

Antes de tocar em qualquer coisa

Sempre inspect (inspecione) e depois diagnose (diagnostique) antes de edit (editar). As timelines carregam estruturas que não são óbvias a partir de um nome de arquivo, e uma edição baseada em uma suposição errada é cara de desfazer.

1. inspect com a ação analyze_timeline para forma, duração, resolução.
2. diagnose com a ação validate_timeline para gaps (lacunas), flash frames (quadros flash), duplicatas.
3. Leia o recurso preview://<path> para VER a timeline de fato antes de mudar qualquer coisa. Ele renderiza uma timeline HTML autocontida, incluindo clipes conectados em suas próprias linhas, para que você possa ver o B-roll e as camadas de áudio, não apenas a história principal.

Os sete grupos

Grupo	Use para
inspect	Compreensão somente leitura. Comece aqui, sempre.
diagnose	Encontrar problemas: gaps, flash frames, silêncio, duplicatas, batidas.
edit	Modificar clipes: inserir, deletar, aparar, dividir, reordenar, retemporizar, remover silêncio.
mark	Marcadores e capítulos, incluindo importação de SRT/VTT e batidas.
generate	Construir nova estrutura: cortes brutos, montagens, rolagem A/B, modelos e import_edl_json a partir de uma lista de cortes de uso de vídeo.
transcript	Transcrever localmente, depois editar ou limpar pelo que foi DITO. transcript_pack coloca toda a gravação em uma página — leia antes de planejar uma edição de diálogo. Cada ação aceita backend: "elevenlabs" para rótulos de locutor e eventos de áudio; isso envia a mídia para o ElevenLabs e precisa de ELEVENLABS_API_KEY — o padrão local nunca sai da máquina.
deliver	Exportar para outros NLEs, reformatar, religar, enviar para o FCP.
preview	VEJA a edição: renderização de proxy, folha de contato e uma tira de filme + forma de onda lida da mídia de origem.
watch	Fechar o ciclo: notar o Cmd-E de exportação do operador e compará-lo com o anterior.
index	O cache de análise. index_status diz a idade dele; index_build aquece cada origem em uma timeline; index_clear o descarta. Nada depende dele.
scenes	Limites de cena a partir dos pixels. detect_scenes lista cortes por clipe em tempo de origem e de timeline (PySceneDetect quando instalado via [scenes], senão o filtro de cena mais grosseiro do ffmpeg); scenes_to_markers coloca um marcador em cada um; scenes_split corta os clipes ali. Os resultados são armazenados em cache no índice.
organize	Registro em lote da biblioteca e o livro-razão. organize_auto propõe palavras-chave por clipe a partir de legendas em cache e da transcrição (apply=true as escreve). Selecione clipes por glob de clip_name, keyword e/ou role, depois organize_keywords (adicionar/remover/substituir), organize_rate (favorito/rejeitado/limpar) ou organize_roles — cada um escreve uma cópia _organized. history lista cada operação registrada para a pasta do arquivo; undo move as últimas n saídas para a pasta undone/ do diário (nunca deleta, recusa se um arquivo mudou desde então).
find	"Onde está o trecho onde…" como um roteador. find_shots classifica momentos pelo que foi dito (transcrição), pelo que foi registrado (nomes, palavras-chave, notas, marcadores, eventos de áudio) e, com o extra [find] e um modelo local baixado, pela aparência dos quadros — a primeira linha nomeia quais camadas responderam e por que uma não pôde. find_index aquece cenas e legendas e relata quais clipes não têm transcrição (nunca transcreve, nunca fica online). find_to_timeline monta os resultados em um rolo de seleções _found com uma pontuação de diversidade.

Toda chamada recebe {"action": "...", "args": {...}}. Se você passar uma ação que o grupo não possui, o erro lista as válidas — leia-o em vez de adivinhar.

Fatos do FCPXML que vão te morder

• O tempo é racional, nunca float. 3600/2400s é 1,5 segundos. Nunca faça matemática de float em timecode e nunca o arredonde você mesmo.
• offset é a posição na timeline. start é o ponto de entrada na origem. São números diferentes e confundi-los desloca uma edição silenciosamente.
• Clipes de biblioteca e clipes de timeline são elementos diferentes. <asset-clip> vive na biblioteca, <clip> vive na timeline.
• Marcadores são filhos de clipes, não irmãos.
• O <spine> é a história principal. Clipes conectados penduram nos clipes do spine por faixa: positivo é acima (vídeo), negativo é abaixo (áudio).
• Pacotes .fcpxmld são diretórios, envolvendo Info.fcpxml mais dados auxiliares. Os auxiliares devem ser preservados ao salvar, ou os dados de rastreamento de objetos e Cinematic serão destruídos.
• Nomes de clipe duplicados são comuns. Prefira operações baseadas em elemento em vez de buscas por nome quando uma ferramenta oferecer ambas.

Remoção de silêncio: escolha a correta

Existem dois pares de detecção-e-correção, e eles não são intercambiáveis. Ambos seguem a mesma divisão de todos os outros pares de detecção/correção neste servidor: o detector vive em diagnose, o corretor vive em edit.

• detect_media_silence (diagnose) → remove_media_silence (edit) lê o áudio de origem real com ffmpeg. Preciso, mais lento, precisa do ffmpeg instalado.
• detect_silence_candidates (diagnose) → remove_silence_candidates (edit) usa apenas heurísticas de timeline. Rápido, sem ffmpeg, e ele chuta.

Use as versões de mídia quando a correção for importante. Diga qual você usou.

Ordem de trabalho que tende a funcionar

1. inspect → diagnose → leia o recurso preview://.
2. transcript com a ação transcript_pack se a edição for orientada a diálogo — uma página de tudo que foi dito, para que o plano seja feito a partir das palavras em vez dos nomes dos clipes.
3. generate para a montagem, edit para o refinamento, mark para capítulos.
4. preview com a ação preview_check sobre o intervalo que você alterou, antes de oferecer a edição como concluída. É isso que torna a edição não cega. O recurso preview:// e preview_timeline ambos se baseiam no XML — eles mostram o que foi ESCRITO, então não podem distinguir um corte corrigido de um quebrado. preview_check lê a mídia. Não substitua um pelo outro, e não pule isso porque a chamada de ferramenta relatou sucesso.
5. deliver, seja exportando ou usando push_to_fcp para o aplicativo em execução.
6. watch com a ação watch_start uma vez por sessão, depois watch_pull após o operador exportar. O Final Cut Pro NÃO tem exportação programática — a Apple nunca lançou uma — então o ciclo só se fecha quando eles pressionam Cmd-E. Diga isso claramente em vez de esperar em silêncio.

Não faça

• Não edite sem uma passada de diagnóstico. Flash frames e gaps se acumulam.
• Não presuma que ffmpeg ou Whisper estão instalados. Ambos degradam graciosamente e retornam nada em vez de erro, então verifique a resposta.
• Não leia um resumo de preview_render além da palavra UNVERIFIED (NÃO VERIFICADO). Isso significa que a duração do arquivo renderizado não pôde ser lida de volta, então nada sobre aquela renderização foi confirmado.
• Não ignore uma linha Substituted: (Substituído:). O proxy renderiza transições como cortes secos, então uma dissolução na timeline NÃO é o que você está vendo.
• Não afirme que uma edição chegou ao Final Cut Pro a menos que push_to_fcp tenha sido chamado e relatado sucesso. Escrever um arquivo .fcpxml não é o mesmo que importá-lo.
• Não confie na mensagem de sucesso de uma ferramenta como prova de que a timeline está correta. Leia preview:// e olhe.