DareDev256/fcp-mcp-server

Edición de Final Cut Pro mediante FCPXML

Antes de tocar nada

Siempre inspect y luego diagnose antes de edit. Las líneas de tiempo tienen estructura que no es obvia a partir del nombre de archivo, y una edición basada en una suposición errónea es costosa de deshacer.

1. inspect con la acción analyze_timeline para conocer forma, duración, resolución.
2. diagnose con la acción validate_timeline para detectar huecos, fotogramas flash, duplicados.
3. Lee el recurso preview://<path> para VER realmente la línea de tiempo antes de cambiar nada. Renderiza una línea de tiempo HTML autocontenida, incluyendo clips conectados en sus propias filas de carril, para que puedas ver el metraje secundario y las capas de audio, no solo la línea de tiempo principal.

Los siete grupos

Grupo	Úsalo para
inspect	Comprensión de solo lectura. Empieza aquí, siempre.
diagnose	Encontrar problemas: huecos, fotogramas flash, silencios, duplicados, beats.
edit	Cambiar clips: insertar, eliminar, recortar, dividir, reordenar, retemporizar, eliminar silencios.
mark	Marcadores y capítulos, incluyendo importación de SRT/VTT y beats.
generate	Construir nueva estructura: montajes preliminares, montajes, rollo A/B, plantillas y import_edl_json desde una lista de cortes de uso de video.
transcript	Transcribir localmente, luego editar o limpiar por lo que se DIJO. transcript_pack pone toda la grabación en una página — léela antes de planificar una edición de diálogos. Cada acción acepta backend: "elevenlabs" para etiquetas de hablante y eventos de audio; eso sube el material a ElevenLabs y necesita ELEVENLABS_API_KEY — el valor por defecto local nunca sale de la máquina.
deliver	Exportar a otros NLEs, reformatear, reenlazar, enviar a FCP.
preview	VER la edición: renderizado proxy, hoja de contactos y una tira de película + forma de onda leída del material fuente.
watch	Cerrar el ciclo: notar la exportación Cmd-E del operador y diferenciarla con la anterior.
index	La caché de análisis. index_status dice su antigüedad; index_build calienta cada fuente en una línea de tiempo; index_clear la elimina. Nada depende de ella.
scenes	Límites de plano a partir de los píxeles. detect_scenes lista cortes por clip en tiempo fuente y de línea de tiempo (PySceneDetect cuando se instala con [scenes], de lo contrario el filtro de escenas más grueso de ffmpeg); scenes_to_markers coloca un marcador en cada uno; scenes_split corta los clips allí. Los resultados se almacenan en caché en el índice.
organize	Registro masivo de bibliotecas y el libro mayor. organize_auto propone palabras clave por clip a partir de subtítulos almacenados en caché y la transcripción (apply=true las escribe). Selecciona clips por comodín clip_name, keyword y/o role, luego organize_keywords (añadir/quitar/reemplazar), organize_rate (favorito/rechazado/limpiar) u organize_roles — cada uno escribe una copia _organized. history lista cada operación registrada para la carpeta del archivo; undo mueve las últimas n salidas a la carpeta undone/ del diario (nunca elimina, se niega si un archivo ha cambiado desde entonces).
find	"¿Dónde está el fragmento donde…" como enrutador. find_shots clasifica momentos por lo que se dijo (transcripción), lo que se registró (nombres, palabras clave, notas, marcadores, eventos de audio) y, con el extra [find] y un modelo local descargado, por el aspecto de los fotogramas — la primera línea indica qué niveles respondieron y por qué uno no pudo. find_index calienta escenas y subtítulos e informa qué clips no tienen transcripción (nunca transcribe, nunca en línea). find_to_timeline ensambla los resultados en un carrete de selección _found con una puntuación de diversidad.

Cada llamada toma {"action": "...", "args": {...}}. Si pasas una acción que el grupo no posee, el error lista las válidas — léelo en lugar de adivinar.

Datos de FCPXML que te morderán

• El tiempo es racional, nunca flotante. 3600/2400s son 1.5 segundos. Nunca hagas matemáticas de punto flotante en timecodes y nunca lo redondees por tu cuenta.
• offset es la posición en la línea de tiempo. start es el punto de entrada en la fuente. Son números diferentes y confundirlos desplaza una edición en silencio.
• Los clips de biblioteca y los clips de línea de tiempo son elementos diferentes. <asset-clip> vive en la biblioteca, <clip> vive en la línea de tiempo.
• Los marcadores son hijos de los clips, no hermanos.
• <spine> es la línea de tiempo principal. Los clips conectados cuelgan de los clips del spine por carril: positivo es arriba (video), negativo es abajo (audio).
• Los paquetes .fcpxmld son directorios, que envuelven Info.fcpxml más datos auxiliares. Los archivos auxiliares deben conservarse al guardar o los datos de seguimiento de objetos y Cinematic se destruyen.
• Los nombres de clips duplicados son comunes. Prefiere operaciones basadas en elementos sobre búsquedas por nombre cuando una herramienta ofrezca ambas.

Eliminación de silencios: elige la correcta

Hay dos pares de detección y corrección, y no son intercambiables. Ambos siguen la misma división que cualquier otro par de detección/corrección en este servidor: el detector vive en diagnose, el corrector vive en edit.

• detect_media_silence (diagnose) → remove_media_silence (edit) lee el audio fuente real con ffmpeg. Preciso, más lento, necesita ffmpeg instalado.
• detect_silence_candidates (diagnose) → remove_silence_candidates (edit) usa solo heurísticas de línea de tiempo. Rápido, sin ffmpeg, y adivina.

Usa las versiones de material cuando la corrección importe. Di cuál usaste.

Orden de trabajo que suele mantenerse

1. inspect → diagnose → leer el recurso preview://.
2. transcript con la acción transcript_pack si la edición está basada en diálogos — una página con todo lo dicho, para que el plan se haga a partir de las palabras en lugar de los nombres de clip.
3. generate para el ensamblaje, edit para el refinamiento, mark para los capítulos.
4. preview con la acción preview_check en el rango que cambiaste, antes de ofrecer la edición como terminada. Esto es lo que hace que la edición no sea ciega. El recurso preview:// y preview_timeline ambos se basan en el XML — muestran lo que se ESCRIBIÓ, por lo que no pueden distinguir un corte corregido de uno roto. preview_check lee el material. No sustituyas uno por el otro, y no lo omitas porque la llamada a la herramienta reportó éxito.
5. deliver, ya sea exportando o push_to_fcp a la aplicación en ejecución.
6. watch con la acción watch_start una vez por sesión, luego watch_pull después de que el operador exporte. Final Cut Pro NO tiene exportación programática — Apple nunca lanzó una — por lo que el ciclo solo se cierra cuando presionan Cmd-E. Dilo claramente en lugar de esperar en silencio.

No hagas

• No edites sin una pasada de diagnóstico. Los fotogramas flash y los huecos se acumulan.
• No asumas que ffmpeg o Whisper están instalados. Ambos degradan gracefulmente y devuelven nada en lugar de un error, así que verifica la respuesta.
• No leas un resumen de preview_render más allá de la palabra NO VERIFICADO. Significa que no se pudo leer la duración del archivo renderizado, por lo que nada de ese renderizado ha sido confirmado.
• No ignores una línea Sustituido:. El proxy renderiza las transiciones como cortes directos, por lo que una disolución en la línea de tiempo NO es lo que estás viendo.
• No afirmes que una edición ha llegado a Final Cut Pro a menos que se haya llamado a push_to_fcp y haya reportado éxito. Escribir un archivo .fcpxml no es lo mismo que importarlo.
• No confíes en el mensaje de éxito de una herramienta como prueba de que la línea de tiempo se ve correcta. Lee preview:// y mira.