KyaniteLabs/kinocut

Que fait kinocut ?

Utilisez Kinocut lorsqu'un agent a besoin d'une surface de montage vidéo structurée au lieu d'écrire des commandes FFmpeg à la main. Il expose des outils MCP, un client Python et une CLI pour le montage, l'analyse, les sous-titres, l'audio, les Hyperframes, le compositing par couches et les workflows de réutilisation locale.

Chemin par défaut (faites ceci en premier)

1. kino doctor puis kino --format json info <fichier>.
2. Pour une tâche non familière, appelez search_tools avec la tâche de l'utilisateur (par exemple, "supprimer les mots de remplissage" ou "garder le visage dans le cadre"), puis inspectez les entrées requises de l'outil retourné. Planifiez avec video_intent pour les intentions prises en charge (le goal= optionnel compile un fichier de coupe ; un objectif 360/bureau/table/x4 propose également un 360_assembly_plan). Vérifiez que la proposition satisfait réellement la demande avant de rendre.
3. Rendu (video_cutfile_render, video_edit, workflow, ou un outil moteur unique). Pour le 360 : video_review_decide approuve/rejette ce plan, puis rendez — ne rendez jamais un plan proposed. .insv est rejeté ; besoin d'un MP4 360 équirectangulaire. Guide : docs/360_ASSEMBLY.md.
4. video-quality-check / assert_quality. Les synchronisations repurpose et shorts-package échouent-fermé à un score de 80 sauf si ignoré/allow_fail.
5. Révision humaine visuelle/audio. Ne traitez jamais un reçu comme publié.

Profondeur (sauvetage, récupération, compositing, Hyperframes, son fin S12) : docs/TOOLS.md, docs/RESCUE.md, docs/WORKFLOWS.md. Liste blanche des workflows : probe, trim, resize, convert, crop, add_text, merge, composite_layers, burn_in.

Chargez le guide pertinent lorsque nécessaire. Utilisez des preuves de source pour les choix éditoriaux ; préservez les noms, les nombres, la négation et les qualifications. Signalez les preuves manquantes ou les actions non prises en charge au lieu d'inventer des affirmations de source, des horodatages ou des capacités. Un outil de planification propose une modification ; son existence ne signifie pas que le détecteur ou le modèle requis a été exécuté. Le code possède le timing, les transformations, la validation et l'exécution ; la révision humaine reste séparée du jugement du modèle.

Flux vidéo-code local Revideo (astuce de développement)

Utilisez revideo_materialize, revideo_install et revideo_render lorsque l'appelant a besoin d'un projet échelonné inspectable. Utilisez revideo_render_job pour les mêmes étapes supervisées en un seul appel. Une scène fournie est un TypeScript exécutable de confiance : inspectez-la avant utilisation et n'exécutez jamais de code de scène non fiable. L'installation des dépendances peut accéder à npm ; le rendu s'exécute localement contre le modèle épinglé de Kinocut. Le reçu de rendu lie les médias observés et les octets de sortie au digest exact du fichier de travail sur disque. .mp4, .webm et .mov sélectionnent les modes d'exportation épinglés MP4, WebM et ProRes 4444 et sont vérifiés avant publication. Vérifiez le reçu par rapport aux octets de sortie, exécutez video_quality_check et video_release_checkpoint, puis exigez une révision visuelle humaine.

Commencez ici

• Lisez ../../README.md pour l'installation et le contrat de sécurité.
• Exécutez kino doctor avant FFmpeg / Hyperframes / extensions AI.

Choisissez une surface

• MCP : meilleur pour Claude Code, Cursor, les clients de type Codex et autres hôtes d'agents. Configurez uvx --from kinocut kino.
• CLI : meilleur pour les modifications locales directes, les diagnostics rapides, composite-layers --dry-run, les travaux par lots et la sortie JSON compatible CI.
• Client Python : meilleur pour les pipelines reproductibles qui ont besoin de résultats structurés, de chemins de sortie et de reçus de plan de couche enregistrés.

Assemblage double caméra 360 (publié 1.14.0)

Utilisez lorsque la source est un MP4 360 équirectangulaire assemblé de n'importe quelle caméra (Insta360, Ricoh Theta, GoPro MAX, DJI Osmo 360, …) et que la demande est de deux caméras virtuelles sous forme de split / switch / PiP / unique.

1. video_intent(verb="reformat_vertical", goal="desk 360 split 9:16", source=ABS_PATH) ou Client.propose_360_assembly(...).
2. Montrez les caméras, la disposition et les images du storyboard. N'inventez pas de lacet/tangage.
3. video_review_decide / Client.decide_360_assembly avec approve ou reject.
4. Rendez uniquement un plan approuvé (Client.render_360_assembly ou video_review_decide + output_path).

Il n'y a pas d'outil MCP video_360_* ni de commande kino 360. La CLI intent et review-decide n'exécutent pas ce compilateur. Les hooks du réalisateur acceptent un proposant JSON injecté ; un nom de modèle configuré seul n'exécute pas un modèle. Les propositions cloud nécessitent allow_cloud ; les réalisateurs n'écrivent jamais de pixels.

Détourage de produit / objet (publié dans 1.15.1 ; actuel dans 1.15.3)

L'extension de détourage d'objet optionnelle est disponible dans la version publiée 1.15.3. Utilisez la commande existante hyperframes-remove-background / hyperframes_remove_background. Le modèle par défaut est les personnes. Pour les SKU de catalogue, les bijoux, les bouteilles, les chaussures, l'emballage ou tout ce qui n'est pas une personne :

1. hyperframes_remove_background(info=true) — liste les modèles, pas de téléchargement.
2. pip install "kinocut[object-matte]" puis model="birefnet-general".
3. Optionnel --mask-interval 3 sur la vidéo du produit. Superposition d'équipement optionnelle pour les restes de plateau tournant/support/trépied/balayage.
4. Composez sur une plaque de magasin avec composite-layers. Gardez chaque src dans le répertoire spec.

N'inventez pas video_product_matte ; ce n'est pas un nouvel outil MCP. Ne revenez pas au modèle de personnes lorsque l'extension d'objet est manquante. Guide : docs/PRODUCT_MATTE.md. Exemple : examples/product-matte/.

Sauvetage vidéo dédié

Utilisez video_rescue_*, rescue-* ou Client.rescue_* lorsque la demande est de réparer un clip local tout en préservant sa source, son histoire et sa chronologie.

Séquence requise :

1. Appelez le plan et enregistrez l'artefact du plan.
2. Présentez safe_repairs, recommendations, unavailable_repairs, blocked_repairs, aperçus, intentions de package, capacités et estimation à l'utilisateur.
3. Inspectez le plan avant le rendu. Obtenez ou déduisez une approbation explicite uniquement pour les ID dans safe_repairs ; omettre la liste des ID signifie que tous les ID sûrs dans le plan examiné.
4. Appelez le rendu avec exactement ces ID sûrs approuvés.
5. Inspectez le reçu de rendu, puis signalez les chemins de package, les side-cars indisponibles, l'intégrité, la vérification de contrôle, la confidentialité, la reprise et l'état de nettoyage.

Ne rendez jamais directement à partir d'un plan non examiné. N'ajoutez jamais d'ID de recommandation, d'ID indisponibles ou d'ID bloqués à l'approbation. N'utilisez jamais d'outils cloud, ne gravez pas de légendes de sauvetage, ne réécrivez pas la source ou ne traitez pas unavailable comme un échec automatique. Une annulation ou un échec de vérification ne doit pas être promu ou mis en quarantaine.

Inspection vidéo AI déterministe

Utilisez video_ingest, video_preflight et video_inspect_temporal (ou leurs équivalents CLI plats et Python) lorsque des images générées ont besoin de preuves avant une décision de montage. Ingérez en premier, puis adressez l'actif par son hachage retourné. Ne remplacez jamais cet ID d'actif par un chemin hôte ou construisez un AssetRecord à la frontière publique. L'inspection temporelle retourne le package complet d'images échantillonnées et de bandes de mouvement, des résultats déterministes et des capacités de fournisseur indisponibles explicites. L'absence de fournisseur est attendue et ne doit pas déclencher un téléchargement ou un repli réseau.

Révision et récupération vidéo AI supervisée

Utilisez video_verdict, video_acceptance_eval, video_body_swap et video_salvage (ou leurs équivalents CLI plats et Python) pour les décisions éditoriales exactes sur actif et la récupération de dérivés. Un verdict non approuvé peut capturer l'analyse de l'agent, mais une disposition approuvée doit lier une décision humaine active et exacte avec une exigence, un rôle et une preuve d'artefact explicites. L'évaluation d'acceptation est dérivée plutôt qu'une action d'approbation, et chaque sortie de récupération commence dans un nouvel emplacement de révision non approuvé.

N'inventez jamais un ID de décision, ne passez pas une approbation non stockée ou ne cherchez pas une route de force/outrepassement. L'échange de corps rejette la non-concordance de durée à moins que l'appelant ne choisisse une politique explicite. La récupération nécessite un projet privé existant, un actif source stocké, une politique de recette liée et un ID de spec d'acceptation exact.

L'évaluation d'acceptation prend les acceptance_spec_id et verdict_ids actifs stockés, jamais les objets de preuve construits par l'appelant. L'échange de corps public prend toujours project_dir en premier et les deux chemins source doivent résoudre en actifs actifs dans ce projet exact.

Lisez docs/AI_VIDEO_REVIEW_AND_SALVAGE.md avant d'opérer ce workflow. Traitez chaque dérivé comme un nouveau travail non approuvé et gardez la porte visuelle/audio humaine explicite avant la publication.

Planification post-sauvetage

Utilisez l'outil MCP video_* correspondant, la commande CLI plate ou la méthode Client lorsque la demande nécessite une recherche sémantique, des modifications de nettoyage ordinaires, des transformations conscientes du sujet, la restauration, la composition, la coordination créative ou la sortie à distance. Passez des preuves et des intentions compatibles JSON ; présentez le plan retourné et le diff avant toute étape de rendu séparée.

N'inventez jamais de descriptions de source, ne cachez pas l'incertitude, ne déduisez pas d'approbation d'un plan et ne traitez pas un exécuteur local manquant comme une permission d'utiliser un fournisseur cloud. Le travail à distance nécessite un manifeste de sortie séparé et une approbation. Un planificateur qui manque de preuves ou de capacités doit s'abstenir.

Compositing par couches

Utilisez composite-layers / video_composite_layers lorsque le montage est une pile ordonnée de couches d'image, vidéo ou solides, en particulier les tiers inférieurs, les variantes d'image dans l'image, les plaques de flou d'arrière-plan, les masques/détourages, ou les variantes de disposition spécifiques à une plateforme.

Préférez ce chemin plutôt que les graphiques de filtres FFmpeg bruts lorsqu'un agent a besoin de transformations, d'opacité, de fenêtres de début/durée, de sources alpha de masque/détourage, ou d'un reçu qui peut être examiné avant publication.

Flux de planification en premier :

1. Écrivez une spec JSON avec canvas, layers ordonnées et output explicite.
2. Exécutez kino composite-layers --spec layers.json --dry-run --save-layer-plan layer-plan.json.
3. Inspectez le plan de couche pour les hachages source, le hachage du graphique de filtre, les transformations, la rotation/pivot, les modes de fusion, les fenêtres de timing et les masques.
4. Rendez seulement après que le plan semble correct.
5. Exécutez video-quality-check, storyboard ou thumbnail, et video_release_checkpoint.

Le compositeur prend en charge les modes de fusion pleine toile et positionnés autorisés (multiply, screen, overlay, darken, lighten) avec opacité et fenêtres de timing ; les reçus restent layer_plan v2. Les modes de fusion non-normal prennent en charge l'opacité et les fenêtres de start/duration dans deux géométries : pleine toile à {0,0} sans dimensionnement explicite, ou un rectangle positionné avec à la fois width et height entiers positifs et une position entière non négative dans la toile. La fusion RVB évite d'appliquer l'arithmétique des couleurs aux plans chroma sous-échantillonnés. L'échelle, la rotation/pivot, le masque/détourage, les positions fractionnaires et les rectangles hors toile restent différés et échouent-fermé avec unsupported_blend_geometry. Les couches vidéo et les masques vidéo commencent la lecture à leur début déclaré. Gardez toutes les sources et tous les masques dans le répertoire spec. La sortie est uniquement vidéo ; anchor est un alias de position distinct de pivot. La rotation + masque, le compositing audio et les adaptateurs NLE complets restent différés. Inspectez le reçu avant la révision humaine ; ne traitez pas cela comme un remplacement NLE complet.

Moteur de workflow d'agent

Lorsque le montage est un travail en plusieurs étapes (pas un seul appel d'outil), utilisez le moteur de workflow pour planifier, valider, rendre, récupérer et prouver à partir d'une seule spec de travail JSON — via video_workflow_* (MCP), workflow-* (CLI), ou Client.workflow_* (Python). Les opérations sont une petite liste blanche (probe | trim | resize | convert | crop | add_text | merge | composite_layers | burn_in) liée à des moteurs vérifiés ; les références média sont symboliques (@sources.*, @work/*, @outputs.*) et confinées à l'espace de travail ; tout échoue-fermé. Voir ../../docs/WORKFLOWS.md.

Planifier → valider → rendre → inspecter → reprendre :

1. workflow-validate --spec job.json — contrôle structurel peu coûteux ; ne rend rien.
2. workflow-plan --spec job.json --save-plan plan.json — graphique d'opération en simulation + sondes/hachages source ; rend zéro média.
3. workflow-render --spec job.json --save-receipt receipt.json — exécute séquentiellement ; émet un reçu de provenance (hachages par étape, manifeste de nettoyage, mise en garde de déterminisme). Ajoutez --all-variants pour les variantes par lots.
4. workflow-inspect --receipt receipt.json — re-vérification d'intégrité en lecture seule + pointeurs de révision humaine avant de faire confiance à un reçu.
5. workflow-render --spec job.json --resume receipt.json — reprend un travail qui a échoué avec des intermédiaires conservés (échec-fermé sur une spec modifiée).

Les reçus stockent uniquement des chemins relatifs à l'espace de travail — gardez les specs et les exemples de reçus exempts de chemins personnels, de noms d'utilisateur et de jetons.

Workflow

1. Inspectez d'abord l'entrée : kino info <fichier> ou l'équivalent MCP/Python.

2. Faites un plan à faible risque : découpage, redimensionnement, normalisation audio, sous-titres, superpositions, effets ou rendu Hyperframes.

3. Préférez les aperçus ou les manifestes en simulation avant les exportations coûteuses ou destructrices :

   • preview pour un examen visuel rapide.
   • repurpose-plan avant repurpose.
   • Hyperframes inspect, snapshot ou still avant le rendu complet.
   • Pour les plans de courts-métrages enregistrés : shorts-plan-show → shorts-review → shorts-render → shorts-package.
   • Pour le son fin : sound-capabilities puis sound-plan-validate / sound-voice-batch / sound-mix-render / sound-qa-loudness / sound-qa-asr (ou kino sound <action>).
   • Fournissez des valeurs numériques pour les durées sonores, les gains, la sonie et les versions de profil ; les booléens sont rejetés avant coercition. Les plans invalides explicites ne peuvent pas sélectionner le plan d'exemple. Les plans typés sont revalidés ; voir docs/SOUND_INPUT_VALIDATION.md pour les règles de compatibilité spécifiques aux champs.
   • L'ASR réel utilise une demande audio/référence hachée et une racine explicite ; conservez son ZIP de transcription et signalez honnêtement les divergences. Whisper local en cache uniquement ; pas de téléchargements automatiques. Les appels hérités uniquement hachés sont des simulations. Voir docs/SOUND_ASR_REQUESTS.md.
   • Pour l'AQ de sonie PCM16 mono/stéréo réel, fournissez SoundLoudnessRequest plus la racine du projet et inspectez within_tolerance ; une mesure réussie peut être non conforme. FFmpeg est requis, et le fixture sans entrée est étiqueté comme une démo. Voir docs/SOUND_LOUDNESS_REQUESTS.md.
   • Pour le mastering mono/stéréo conservé, fournissez SoundMasterRequest et la racine explicite à sound-master-render ; voir docs/SOUND_MASTER_REQUESTS.md. Inspectez le ZIP vérifié, le mode de normalisation réel et la conformité à la politique finale mesurée, puis écoutez avant la publication. Les canaux d'entrée sont préservés ; la sortie existante n'est jamais remplacée.
   • Pour l'ASR EN/ES local actuel avec une racine de projet, une demande audio hachée et une référence hachée optionnelle, le reçu inclut le ZIP de transcription et un résumé de divergence ; les différences de durée ne sont pas des appels de réessai. Voir docs/SOUND_ASR_REQUESTS.md.

4. Utilisez --dry-run / --save-plan avec composite-layers.

5. Utilisez video-quality-check sur la sortie.

6. Validez avec assert_quality avant les points de contrôle de publication.

7. Utilisez video_release_checkpoint une fois que la qualité et l'inspection humaine sont terminées.

8. Libérez un package de réutilisation avec une preuve de qualité (ou expliquez pourquoi vous sautez).

Extensions

• Sauts de visage & sauts de mots de remplissage — utilisez video_intent / intent (intention : "tighten" ou "remove filler words").
• Hyperframes — édition vidéo pilotée par IA (pasque, tourne-disque, etc.)
• Rendu vidéo Revideo avec inspection TypeScript.
• Récupération vidéo AI.
• Analyse de sonie, mastering, voix off (mono/stéréo).
• Création de contenu pour les réseaux sociaux (courts-métrages, réutilisation, packages de sortie).
• Compositing par couches.

Règles

• Inspectez d'abord, puis planifiez, puis rendez.
• kino doctor avant tout outil externe.
• Ne rendez pas à partir d'un plan proposed ou non examiné.
• Utilisez --dry-run ou --save-plan lorsque cela est disponible.
• video-quality-check et assert_quality sur la sortie.
• Utilisez video_release_checkpoint avant de marquer comme fait (après la révision humaine).
• Signalez les actions non prises en charge ou les preuves manquantes — n'inventez pas.
• Ne traitez pas un reçu de rendu comme une publication.
• Ne sautez pas la révision visuelle/audio humaine.
• Gardez tous les fichiers src et mask dans le répertoire spec.
• Pas d'invention de noms de méthode.
• Pas de décisions de force/outrepassement.
• Pas d'exécution de code de scène non fiable.
• Pas de basculement cloud automatique.