DareDev256/fcp-mcp-server

Édition Final Cut Pro via FCPXML

Avant de toucher à quoi que ce soit

Effectuez toujours inspect puis diagnose avant edit. Les timelines portent une structure qui n'est pas évidente à partir d'un nom de fichier, et une édition basée sur une hypothèse erronée est coûteuse à annuler.

1. inspect avec l'action analyze_timeline pour la forme, la durée, la résolution.
2. diagnose avec l'action validate_timeline pour les trous, les images noires, les doublons.
3. Lisez la ressource preview://<path> pour VRAIMENT VOIR la timeline avant d'y changer quoi que ce soit. Elle génère une timeline HTML autonome, incluant les clips connectés sur leurs propres voies, afin que vous puissiez voir les couches B-roll et audio, pas seulement l'histoire principale.

Les sept groupes

Groupe	Utilisation
inspect	Compréhension en lecture seule. Commencez ici, toujours.
diagnose	Trouver les problèmes : trous, images noires, silence, doublons, beats.
edit	Modifier les clips : insérer, supprimer, rogner, diviser, réordonner, retimer, supprimer le silence.
mark	Marqueurs et chapitres, y compris l'import SRT/VTT et de beats.
generate	Construire de nouvelles structures : coupes brutes, montages, A/B roll, templates, et import_edl_json à partir d'une liste de coupes d'utilisation vidéo.
transcript	Transcrire localement, puis éditer ou nettoyer en fonction de ce qui a été DIT. transcript_pack regroupe l'ensemble du tournage sur une seule page — lisez-la avant de planifier un montage dialogué. Chaque action prend backend: "elevenlabs" pour les étiquettes de locuteurs et les événements audio ; cela télécharge le média vers ElevenLabs et nécessite ELEVENLABS_API_KEY — le local par défaut ne quitte jamais la machine.
deliver	Exporter vers d'autres NLE, reformater, relier, pousser dans FCP.
preview	VOIR l'édition : rendu proxy, planche contact, et une pellicule+forme d'onde lue depuis le média source.
watch	Boucler le round-trip : remarquer l'export Cmd-E de l'opérateur et le comparer avec le précédent.
index	Le cache d'analyse. index_status indique son âge ; index_build réchauffe chaque source d'une timeline ; index_clear le supprime. Rien n'en dépend.
scenes	Limites de plans à partir des pixels. detect_scenes liste les coupes par clip en temps source et timeline (PySceneDetect quand installé via [scenes], sinon le filtre plus grossier de ffmpeg) ; scenes_to_markers dépose un marqueur sur chacune ; scenes_split coupe les clips à ces points. Les résultats sont mis en cache dans l'index.
organize	Journalisation en masse de la bibliothèque et le registre. organize_auto propose des mots-clés par clip à partir des légendes mises en cache et de la transcription (apply=true les écrit). Sélectionnez les clips par glob clip_name, keyword et/ou role, puis organize_keywords (ajouter/supprimer/remplacer), organize_rate (favori/rejeté/effacer) ou organize_roles — chacun écrit une copie _organized. history liste chaque opération enregistrée pour le dossier du fichier ; undo déplace les n dernières sorties dans le dossier undone/ du journal (ne supprime jamais, refuse si un fichier a changé depuis).
find	« Où est le passage où… » en tant que routeur. find_shots classe les moments par ce qui a été dit (transcription), ce qui a été journalisé (noms, mots-clés, notes, marqueurs, événements audio) et, avec l'extra [find] et un modèle local téléchargé, par l'apparence des images — la première ligne nomme quels niveaux ont répondu et pourquoi l'un n'a pas pu. find_index réchauffe les scènes et les légendes et rapporte quels clips n'ont pas de transcription (ne transcrit jamais, jamais en ligne). find_to_timeline assemble les résultats en une bobine de sélection _found avec un score de diversité.

Chaque appel prend {"action": "...", "args": {...}}. Si vous passez une action que le groupe ne possède pas, l'erreur liste les actions valides — lisez-la plutôt que de deviner.

Faits FCPXML qui vous mordront

• Le temps est rationnel, jamais décimal. 3600/2400s correspond à 1,5 seconde. Ne faites jamais de calculs décimaux sur le timecode et ne l'arrondissez jamais vous-même.
• offset est la position dans la timeline. start est l'entrée source. Ce sont des nombres différents et les confondre décale une édition en silence.
• Les clips de bibliothèque et les clips de timeline sont des éléments différents. <asset-clip> vit dans la bibliothèque, <clip> vit sur la timeline.
• Les marqueurs sont des enfants des clips, pas des frères.
• Le <spine> est l'histoire principale. Les clips connectés sont suspendus aux clips du spine par voie : positif est au-dessus (vidéo), négatif en dessous (audio).
• Les bundles .fcpxmld sont des répertoires, contenant Info.fcpxml plus des données annexes. Les annexes doivent être conservées lors de la sauvegarde, sinon les données de suivi d'objet et Cinematic sont détruites.
• Les noms de clips en double sont courants. Préférez les opérations basées sur les éléments aux recherches par nom quand un outil offre les deux.

Suppression de silence : choisissez la bonne

Il existe deux paires détection-puis-correction, et elles ne sont pas interchangeables. Les deux suivent la même division que toute autre paire détection/correction de ce serveur : le détecteur vit dans diagnose, le correcteur vit dans edit.

• detect_media_silence (diagnose) → remove_media_silence (edit) lit l'audio source réel avec ffmpeg. Précis, plus lent, nécessite ffmpeg installé.
• detect_silence_candidates (diagnose) → remove_silence_candidates (edit) utilise uniquement des heuristiques de timeline. Rapide, pas de ffmpeg, et il devine.

Utilisez les versions média quand la justesse compte. Dites laquelle vous avez utilisée.

Ordre de travail qui a tendance à tenir

1. inspect → diagnose → lire la ressource preview://.
2. transcript avec l'action transcript_pack si l'édition est axée sur le dialogue — une page de tout ce qui a été dit, pour que le plan soit fait à partir des mots plutôt que des noms de clips.
3. generate pour l'assemblage, edit pour le raffinement, mark pour les chapitres.
4. preview avec l'action preview_check sur la plage que vous avez modifiée, avant de proposer l'édition comme terminée. C'est ce qui rend l'édition non aveugle. La ressource preview:// et preview_timeline puisent toutes deux dans le XML — elles montrent ce qui a été ÉCRIT, elles ne peuvent donc pas distinguer un montage correct d'un montage cassé. preview_check lit le média. Ne substituez pas l'un à l'autre, et ne l'ignorez pas parce que l'appel d'outil a rapporté un succès.
5. deliver, soit en exportant, soit en utilisant push_to_fcp dans l'application en cours.
6. watch avec l'action watch_start une fois par session, puis watch_pull après que l'opérateur exporte. Final Cut Pro n'a AUCUN export programmatique — Apple n'en a jamais livré — donc la boucle ne se ferme que lorsqu'ils appuient sur Cmd-E. Dites-le clairement plutôt que d'attendre en silence.

Ne faites pas

• N'éditez pas sans une passe de diagnostic. Les images noires et les trous s'accumulent.
• Ne supposez pas que ffmpeg ou Whisper sont installés. Les deux dégradent gracieusement et ne renvoient rien plutôt qu'une erreur, vérifiez donc la réponse.
• Ne lisez pas un résumé preview_render après le mot NON VÉRIFIÉ. Cela signifie que la durée du fichier rendu n'a pas pu être relue, donc rien sur ce rendu n'a été confirmé.
• N'ignorez pas une ligne Substituted:. Le proxy rend les transitions comme des coupes franches, donc un fondu dans la timeline N'est PAS ce que vous regardez.
• Ne prétendez pas qu'une édition a atterri dans Final Cut Pro à moins que push_to_fcp n'ait été appelé et n'ait rapporté un succès. Écrire un fichier .fcpxml n'est pas la même chose que l'importer.
• Ne faites pas confiance au propre message de succès d'un outil comme preuve que la timeline est correcte. Lisez preview:// et regardez.