mcp-video

Servidor MCP de edición de video nativo con IA para flujos de trabajo con FFmpeg.

Documentación

Kinocut

Servidor MCP de edición de video con protecciones para agentes de IA.
Herramientas FFmpeg locales primero, Recibos de Video, controles de calidad, Hyperframes y reutilización para Shorts/Reels: para Claude Code, Cursor y cualquier cliente MCP. Gratuito, Apache-2.0. Anteriormente mcp-video.

Demo • Estado • 1.14.1 • Registro de cambios • Más allá • Instalación • Inicio rápido • Herramientas • Referencia de herramientas • Rescate • Ensamblaje 360 • Video con IA • Habilidad de agente • kinocut.dev • ¿Qué es Kinocut? • Preguntas frecuentes • llms.txt

Kinocut es un servidor MCP de edición de video gratuito y de código abierto, además de un motor de flujo de trabajo para agentes de IA (con cliente Python y CLI kino) que permite a los agentes de IA recortar, subtitular, reutilizar y controlar la calidad de medios de video locales con herramientas tipadas y Recibos de Video, no con banderas FFmpeg inventadas.

¿Qué es Kinocut?

En resumen: Kinocut es un servidor MCP de edición de video gratuito y local primero (además de cliente Python y CLI kino) para que los agentes de IA puedan recortar, subtitular, reutilizar y controlar la calidad de medios con herramientas tipadas y Recibos de Video, no con banderas FFmpeg inventadas.

Kinocut es un Protocolo de Contexto de Modelo (MCP) gratuito y de código abierto, una biblioteca de Python y una CLI kino que brinda a los agentes de IA una superficie de edición de video local con protecciones. Envuelve FFmpeg (y extras opcionales de Hyperframes / Whisper) con herramientas tipadas, validación previa, procedencia de Recibo de Video y puntos de control de calidad/versión para que los medios producidos por agentes puedan inspeccionarse antes de publicarse.


También conocido como	`kino` (CLI); anteriormente mcp-video / `mcp_video`
Última versión publicada	1.14.1 (2026-08-13)
Sitio del producto	kinocut.dev
PyPI	`kinocut`
Registro MCP	`io.github.KyaniteLabs/kinocut`
Código fuente	GitHub (colaboración pública) · Forgejo (fuente canónica)
Licencia	Apache-2.0
Se ejecuta en	Tu máquina (macOS, Linux, Windows) — FFmpeg requerido en `PATH`
No es	Un editor en la nube alojado, SaaS con medidor de créditos ni un envoltorio de shell FFmpeg sin tipos

Búsquedas de mejor ajuste: servidor MCP de edición de video · edición de video con agentes de IA · FFmpeg MCP · herramientas de video para Claude Code · video MCP para Cursor · automatización de Shorts/Reels · flujo de trabajo de video local con IA · medios agénticos con protecciones.

Resumen legible por máquina para rastreadores de IA: llms.txt · sitio: kinocut.dev/llms.txt.

Verlo en acción

Dile al agente lo que quieres en lenguaje natural:

"Recorta esta entrevista a los 45 segundos más fuertes, añade subtítulos quemados, hazla vertical y verifica su calidad antes de exportarla."

Kinocut convierte eso en llamadas de herramientas tipadas y con protecciones: sin banderas FFmpeg que adivinar, sin exportaciones rotas en silencio:

from kinocut import Client
video = Client()

clip = video.trim("interview.mp4", start="00:02:15", duration="00:00:45")
video.ai_transcribe(clip.output_path, output_srt="captions.srt")
captioned = video.subtitles(clip.output_path, subtitle_file="captions.srt")
short = video.resize(captioned.output_path, aspect_ratio="9:16")
video.release_checkpoint(short.output_path)  # thumbnail + quality gate before you publish

Trabajo principal: convertir una entrevista o podcast local en clips verticales subtitulados con un Recibo de Video que los agentes puedan re-ejecutar y los humanos aprobar.

Tres usos comunes

Reutilización — una grabación en paquetes de Shorts, Reels y TikTok subtitulados con manifiestos y artefactos de revisión.
Cortes de podcasts y entrevistas — encontrar el segmento más fuerte, normalizar el audio, añadir capítulos y exportar.
Medios impulsados por agentes en CI — ediciones repetibles y revisables desde Claude Code, Cursor, clientes estilo Codex o scripts.

Rutas: Matriz de instalación · Ruta dorada · Indicaciones · Tutorial · Comparar · Cuándo recomendar

Estado y versiones

Superficie	Versión / punta	Qué significa
PyPI / npm / GitHub Release	1.14.1 (2026-08-13)	Última versión publicada de Kinocut. Instalar con `pip install kinocut`.
Este repositorio (`master`)	1.14.1 · 196 herramientas MCP / 167 comandos CLI	Mismos conteos publicados. El ensamblaje 360 reutiliza `video_intent` / revisión (no una herramienta 197).
Próxima versión pública	Pendiente	Los residuales humanos (directorios, publicaciones de lanzamiento) permanecen restringidos; nuevos aumentos requieren una nueva autorización.

Instala desde PyPI para el paquete estable. Clona master solo cuando quieras intencionalmente trabajo de punta no publicado.

Qué hay en 1.14.1 (última versión)

Kinocut 1.14.1 es lo que obtienes de pip install kinocut hoy. Es un parche sobre 1.14.0: mismo ensamblaje de doble cámara 360 y mejoras de rendimiento del comité, más una corrección de Lint de pyright en GitHub (ruta de cancelación render_rescue). La superficie se mantiene en 196 MCP / 167 CLI — sin nuevo nombre de herramienta pública.

Ensamblaje de doble cámara 360 — cualquier MP4 equirectangular cosido (Insta360, Ricoh Theta, GoPro MAX, DJI Osmo 360, …) → 360_assembly_plan revisable (escritorio / mesa / front_back, dividido / alternado / PiP / único) → aprobar → render FFmpeg v360. MCP: video_intent goal= + video_review_decide. Python: Client.propose_360_assembly / decide_360_assembly / render_360_assembly. .insv / .360 crudos rechazados. El director es un complemento (local primero; nube opcional). No es una afirmación de IA optimizada. Guía: docs/360_ASSEMBLY.md.
Ruta 360 e importación más rápida — filter_complex de división/PiP/alternado de una sola pasada (audio fuente conservado); ventana de análisis de control de calidad muestreada; caché de ruta/mtime SHA-256; la fusión puede omitir la re-sonda cuando se proporciona infos=; fotogramas de guion gráfico 360 por lotes; mcp_video / CLI / Client.search_tools perezosos; el doctor omite npx --yes a menos que Hyperframes ya esté en PATH.
Importación pública perezosa — import kinocut ya no carga Client/motores de forma ansiosa (PEP 562). from kinocut import Client y kinocut.Client is mcp_video.Client siguen en pie.
Honestidad en la costura de envío — CLI/Client repurpose predeterminado --min-score 80; shorts-package falla cerrado a menos que --allow-fail; el video_repurpose MCP duradero no aplica min_score.
Ventana de compatibilidad — mcp-video==1.6.10 instala kinocut==1.14.1; mcp_video importa, variables de entorno MCP_VIDEO_*, datos ~/.mcp-video, recursos mcp-video:// y claves de recibo heredadas siguen siendo compatibles en la línea 1.14.x.

También ya en la línea publicada desde 1.13.x:

Superficie de verbo de intención — video_intent / intent (~10 verbos) para planes de prueba en seco sin mutaciones de medios silenciosas
Piso de protección de visualización — video_review_run / video_review_decide (blackdetect/LUFS + inspección de primeros 15 segundos)
Propuestas de B-roll, traducción de subtítulos ES-primero, editor de fotograma/placa, render de archivo de corte, metric-qc
Motor de flujo de trabajo para agentes, rescate de video dedicado, composición en capas, Hyperframes, reutilización de Shorts/Reels
Conteos canónicos — 196 herramientas MCP y 167 comandos CLI

Notas completas: CHANGELOG.md · versión v1.14.1

Más allá de 1.14.1 (borrador / restringido)

1.14.1 es la última versión publicada. Las presentaciones de directorios en vivo y las publicaciones de lanzamiento siguen siendo residuales de operador/humano (docs/HUMAN_GATES.md) y no se declaran completas.

Superficies Escalonadas y Restringidas

Mientras que la edición FFmpeg central, el ensamblaje 360, el motor de flujo de trabajo, la edición de fotograma/placa, la revisión/rescate de video con IA y las capacidades de sonido están completamente integradas y publicadas en 1.14.1, las siguientes superficies permanecen restringidas, parciales o no publicadas:

Empaquetado MCPB de escritorio: El paquete de escritorio escalonado (mcpb/) es una configuración escalonada y no es un runtime nativo autónomo publicado aún (pendiente de procedencia FFmpeg, licencias y controles de máquina limpia). Ver docs/MCPB.md.
Audio Sonic World (kinocut_sound): Mientras que las capacidades S1–S12 están integradas en la línea publicada, las rebanadas restantes están bloqueadas o restringidas:
- S13 (Host se une / enlaces): Bloqueado — recibos de propietario externo incompletos.
- S14 (Benchmark de doble clase): Parcial — x86 disponible, host Apple Silicon no disponible.
- S15 (Control Adversarial): Restringido bajo un STOP de versión — requiere recibos S13, benchmarks de doble clase y autorización humana explícita.
Kernel de Ejecución Confiable: El kernel de ejecución confiable de línea de tiempo protegida está post-programa/restringido y no se ejecuta sin el contrato ascendente nombrado y la restricción humana (docs/plans/2026-07-09-kinocut-trusted-execution-layer.md).
Planes Pagados de Generación / Doblaje: Los planes de generación con límite de gasto y el doblaje TTS siguen siendo definiciones de borrador no ejecutables hasta que se configuren backends externos y credenciales.

Lista de verificación del producto: ROADMAP.md.

Motor de Flujo de Trabajo para Agentes

Los agentes pueden planificar, validar, renderizar, recuperar y probar un trabajo de video local de múltiples pasos desde una sola especificación de trabajo JSON — a través de MCP (video_workflow_*), la CLI (workflow-*) o el cliente Python (Client.workflow_*) — con recibos lo suficientemente sólidos para que otro agente o un humano confíe antes y después de un render. Las operaciones son una lista de permitidos pequeña (probe | trim | resize | convert | merge | add_text | composite_layers) mapeada 1:1 a las mismas funciones de motor validadas que usan las herramientas individuales; las referencias de medios son simbólicas y confinadas al espacio de trabajo; todo falla cerrado.

{
  "schema_version": 1,
  "name": "captioned-vertical-short",
  "sources": { "hero": { "path": "input/hero.mp4" } },
  "steps": [
    { "id": "trim-hero", "op": "trim", "inputs": { "src": "@sources.hero" },
      "params": { "start": 0, "duration": 6 }, "output": "@work/hero_trim.mp4" },
    { "id": "vertical", "op": "resize", "inputs": { "src": "@work/hero_trim.mp4" },
      "params": { "width": 1080, "height": 1920 }, "output": "@work/hero_vertical.mp4" },
    { "id": "caption", "op": "add_text", "inputs": { "src": "@work/hero_vertical.mp4" },
      "params": { "text": "Watch this", "position": "bottom-center" }, "output": "@outputs.master" }
  ],
  "outputs": { "master": { "path": "output/final.mp4" } }
}

kino workflow-validate --spec job.json    # cheap structural gate, no render
kino workflow-plan     --spec job.json --save-plan plan.json     # dry-run op graph + hashes
kino workflow-render   --spec job.json --save-receipt receipt.json   # execute + provenance receipt
kino workflow-inspect  --receipt receipt.json    # read-only integrity re-check

El recibo de render registra hashes de entrada/salida por paso, un cursor de reanudación y un manifiesto de limpieza, todo con rutas relativas al espacio de trabajo:

{
  "receipt_kind": "workflow",
  "versions": { "mcp_video": "1.13.2", "ffmpeg": "8.1" },
  "spec_hash": "sha256:be2f3a9b...",
  "steps": [
    { "id": "trim-hero", "op": "trim", "status": "completed",
      "input_hashes": { "src": "sha256:3b976d49..." },
      "output": "work/be2f3a9b-2effedb3/mcp_video_hero_trim.mp4", "output_hash": "sha256:00727499..." },
    { "id": "caption", "op": "add_text", "status": "completed",
      "output": "output/final.mp4", "output_hash": "sha256:8633ad2a..." }
  ],
  "cleanup_manifest": { "cleaned": true, "policy": "clean-on-success" },
  "resume_cursor": { "last_completed_step": "caption", "next_step": null },
  "status": "completed",
  "render_determinism_scope": "spec/input/output hashes are deterministic; rendered bytes may vary across FFmpeg builds"
}

--all-variants emite N salidas distintas de una declaración, y --resume continúa un trabajo que falló con sus intermedios conservados (falla cerrado en una especificación cambiada). Esquema completo, gramática @ref, variantes, reanudación y limpieza están en docs/WORKFLOWS.md; una especificación ejecutable está en examples/workflows/.

Revisión de video con IA gobernada

En Kinocut, se proporciona una ruta de contrato primero para medios editados por agentes que deben permanecer atribuibles y revisables:

Ingesta la fuente en un proyecto privado con direccionamiento por contenido (video_ingest / video-ingest)
Pre-vuelo + inspección temporal en el activo almacenado (video_preflight, video_inspect_temporal)
Veredicto + aceptación con evidencia humana exacta (video_verdict, video_acceptance_eval)
Solo derivados limitados — intercambio de cuerpo que preserva audio o recetas de rescate en lista de permitidos (video_body_swap, video_salvage), cada uno con linaje y una ranura de revisión nueva no aprobada No hay indicador de fuerza/omisión. La salida del analizador por sí sola no puede aprobar. Las entradas obsoletas, con alias o protegidas fallan de forma cerrada. Guía de operación: docs/AI_VIDEO_REVIEW_AND_SALVAGE.md. Estas superficies están totalmente integradas en la versión publicada 1.14.1 — consulte Estado y versiones.

Rescate de video dedicado

Para solicitudes de "arregla este clip" donde la historia y la línea de tiempo deben permanecer sin cambios, use el pipeline de rescate con revisión primero. Planifique e inspeccione el diagnóstico, apruebe solo los ID de reparación seguros, renderice, luego inspeccione el paquete verificado. La fuente permanece inmutable; la copia maestra y la copia de uso compartido universal siempre se verifican; los subtítulos opcionales permanecen como archivos laterales. Consulte docs/RESCUE.md para CLI, MCP, Python, cancelación, reanudación y errores estables.

Composición en capas

composite-layers / video_composite_layers agrega una pila de capas ordenada impulsada por especificaciones para agentes que necesitan más que primitivas de superposición de dos tomas. Admite capas de imagen, video y sólidas; composición alfa normal; opacidad por capa; colocación x/y; tamaño de transformación; ventanas de tiempo; y fuentes alfa de máscara/matte — además de modos de fusión de lienzo completo (multiply, screen, overlay, darken, lighten) y rotación con un nuevo punto de referencia pivot. Los planes de ejecución en seco y los recibos deterministas layer_plan v2 capturan fuente, filtergraph y hashes de salida.

kino composite-layers --spec layers.json --dry-run --save-layer-plan layer-plan.json
kino composite-layers --spec layers.json -o out.mp4 --save-layer-plan layer-plan.json

Use composite-layers cuando un agente necesite una pila planificada de superposiciones, mattes, tercios inferiores, placas de desenfoque de fondo o variantes de plataforma que deban revisarse antes de renderizar. Una capa de fusión que no sea normal debe ser de lienzo completo (posición {0,0}, opacidad completa, sin escala/máscara/temporización) o falla de forma cerrada; la salida es solo video. La fusión posicionada/escalada/enmascarada/temporizada, la rotación + máscara y el enrutamiento de efectos por capa se rastrean como fases posteriores para que esta superficie permanezca determinista y preflightable.

Ensamblaje 360 de doble cámara

Cualquier MP4 360 equirectangular cosido (Insta360, Ricoh Theta, GoPro MAX, DJI, …) puede convertirse en una edición de dos cámaras 16:9 o 9:16 sin un nuevo nombre de herramienta. Exporte desde la aplicación de la cámara primero — Kinocut no cose .insv ni GoPro .360.

from kinocut import Client

video = Client()
plan = video.propose_360_assembly("x4-export.mp4", goal="desk 360 split 9:16")
approved = video.decide_360_assembly(plan, "approve")
video.render_360_assembly(approved, "desk-split.mp4")

Agentes: video_intent con un objetivo 360/escritorio/mesa y source=, luego video_review_decide. Contrato completo: docs/360_ASSEMBLY.md.

Edición de imágenes fijas / imágenes

Kinocut trata los paquetes de múltiples imágenes fijas como medios de primera clase — plan → recibo → compuerta de fallo cerrado, misma postura de seguridad que el rescate de video. Requiere pip install "kinocut[image]"; ejecute kino doctor para verificar la pila de imágenes.

Flujo de trabajo: establezca una placa hero → edite los tiempos hacia ella → iguale el WB/exposición compartido → gradación (LUT de señal opcional) → compuerta de cohesión.

# Image analysis: extract colors, generate palettes, analyze products
kino image-extract-colors product.jpg -n 8
kino image-generate-palette scene.png --harmony triadic
kino image-analyze-product listing.jpg --use-ai

# Still/plate editing: match package to hero, grade, gate
kino still-match --hero establish.png --inputs beat1.png beat2.png --output-dir out/matched
kino still-grade --inputs out/matched/*.png --hero establish.png --output-dir out/graded
kino still-gate  --inputs out/graded/*.png --output-dir out/gate

# Establish-locked edit with plan/receipt (dry-run first)
kino image-edit --source beat.png --reference establish.png \
  --intent "match establish world and light" --output-dir out/edit --dry-run

# Or run the full pipeline in one shot
kino still-package --establish establish.png --beats beat1.png beat2.png --output-dir out/pkg

from kinocut import Client

c = Client()
c.still_match(hero="establish.png", inputs=["a.png", "b.png"], output_dir="out/m")
c.still_gate(inputs=["out/m/a_matched.png", "out/m/b_matched.png"], output_dir="out/g")

still-gate falla de forma cerrada en la dispersión de luma y las métricas de sombra verde/cian; cada herramienta escribe un recibo JSON con hashes y ganancias. Los backends generativos de pago permanecen desactivados por defecto (prefer=edit, allow_paid_gen=false). Guía completa: docs/STILL_PLATES.md.

Descubrimiento público

Kinocut está construido para ser encontrable y citable tanto por motores de búsqueda como por motores de respuesta de IA:

URL canónica del producto: https://kinocut.dev/
README de GitHub + llms.txt con hechos de entidad, comandos de instalación y reglas de seguridad
Registro oficial del MCP Registry bajo io.github.KyaniteLabs/kinocut
Respuestas de FAQ en este README y docs/faq.md (respuestas primero, afirmaciones versionadas)

Kinocut vs FFmpeg crudo (y vs editores en la nube)

	Kinocut	FFmpeg crudo en shell de agente	API típica de editor en la nube
Interfaz	MCP / Python / CLI tipado	Banderas de forma libre	API HTTP alojada
Preflight	Barreras de seguridad antes de renderizar	El agente inventa banderas	Específico del proveedor
Procedencia	Recibos de video + hashes	Registros ad-hoc	Panel del proveedor
Ubicación de medios	Local primero	Local	Carga requerida
Costo principal	Gratis (Apache-2.0)	Gratis	A menudo medido

Por qué existe

Los agentes de IA pueden escribir comandos FFmpeg, pero no deberían tener que adivinar banderas, analizar stderr frágil o publicar silenciosamente medios rotos. Kinocut brinda a los agentes operaciones tipadas, metadatos de herramientas inspeccionables, resultados estructurados, barreras de seguridad previas al vuelo y puntos de control de calidad para que un flujo de trabajo de video pueda automatizarse y revisarse sin convertirse en ruleta de comandos de shell.

Úselo cuando quiera que un asistente de IA:

recorte, combine, redimensione, recorte, rote, transcodifique o exporte video;
agregue texto, subtítulos, marcas de agua, superposiciones, filtros, fundidos, efectos y transiciones;
extraiga audio, normalice audio, sintetice audio, agregue audio generado o cree formas de onda;
detecte escenas, haga miniaturas, genere guiones gráficos, compare calidad y cree puntos de control de lanzamiento;
iguale, gradúe y compuerta paquetes de imágenes fijas con cohesión de color bloqueada por establecimiento, o analice imágenes de productos para colores y paletas;
andamie proyectos cinematográficos, lea bloques STYLE_/NEG_, analice tablas de guiones gráficos y expanda indicaciones de tomas;
cree nuevos proyectos Hyperframes, inspeccione diseños renderizados, capture sitios web, genere voz local, elimine fondos y post-procese el resultado con herramientas FFmpeg;
reutilice un video fuente en paquetes de entrega locales verticales, horizontales y cuadrados con manifiestos y artefactos de revisión;
impulse flujos de trabajo de medios repetibles desde Claude Code, Cursor, clientes estilo Codex, scripts o CI.

Instalación

Requisito previo: FFmpeg debe estar instalado y disponible en PATH.

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

Ejecute sin una instalación global:

uvx --from kinocut kino doctor

O instale con pip:

pip install kinocut
kino doctor

Para instalaciones MCPB estilo Claude Desktop, Kinocut incluye un paquete local escalonado en mcpb/ y un script de compilación local:

python3 scripts/build-mcpb.py

Este paquete es honesto sobre su tiempo de ejecución: lanza un entorno Python existente con Kinocut instalado y aún requiere FFmpeg local. Los paquetes nativos autocontenidos permanecen bloqueados pendiente de procedencia de FFmpeg, licencias y compuertas de máquina limpia. Consulte docs/MCPB.md.

El firmado opcional C2PA para exportaciones MP4 finales está disponible en la punta de desarrollo cuando c2patool y un manifiesto/firmante están configurados. El firmado está desactivado por defecto y solo informa signed después de que una lectura de verificación tenga éxito. Consulte docs/C2PA_PROVENANCE.md.

Las herramientas Hyperframes adicionalmente necesitan Node.js 22+ y una CLI Hyperframes resoluble. Instale/fije Hyperframes en el diseño de paquete Node activo, agregue hyperframes a PATH, o establezca MCP_VIDEO_HYPERFRAMES_COMMAND.

¿Qué extra necesito?

La instalación principal cubre todas las herramientas de edición FFmpeg. Las funciones opcionales se envían como extras — instale solo lo que use:

Usted quiere	Instalar	Tamaño extra aprox.
Subtítulos de voz a texto (Whisper)	`pip install "kinocut[transcribe]"`	~1 GB (torch)
Análisis de imágenes (colores, diseño, contraste)	`pip install "kinocut[image]"`	~50 MB
Separación de pistas vocales/instrumentales	`pip install "kinocut[stems]"`	~2 GB (torch + demucs)
Escalado de IA	`pip install "kinocut[upscale]"`	~2 GB (Python ≤3.12)
Herramientas de audio/música procedural	`pip install "kinocut[audio]"`	~30 MB (numpy)
Todo IA	`pip install "kinocut[ai]"`	varios GB

Mezcle libremente, p. ej. pip install "kinocut[transcribe,image]". Ejecute kino doctor después — informa exactamente qué funciones están disponibles y qué falta.

Actualización desde mcp-video

Kinocut preserva la superficie original durante la ventana de renombrado. Las instalaciones existentes pueden actualizarse sin cambiar código:

pip install --upgrade mcp-video
mcp-video doctor

mcp-video==1.6.10 es un instalador de compatibilidad solo de metadatos para kinocut==1.14.1. La importación mcp_video, el comando mcp-video, las variables de entorno MCP_VIDEO_*, el directorio de datos ~/.mcp-video, los URI de recursos mcp-video:// y las claves de recibo existentes permanecen compatibles en la línea 1.14.x. Las nuevas integraciones deben usar kinocut, from kinocut import Client y el comando kino.

En español

Kinocut es un servidor MCP de edición de video para agentes de IA. La última versión publicada es 1.14.1 (pip install kinocut, 196 herramientas MCP / 167 CLI). Incluye ensamblaje 360 de dual-cam desde un MP4 equirectangular ya stitched (no .insv), import perezoso PEP 562 y el mismo surface FFmpeg tipado para recortar, unir, subtitular, mezclar audio, efectos y reutilizar contenido (Shorts, Reels, TikTok), motor de flujos (workflow) con recibos verificables, rescate de video, revisión AI-video gobernada y barreras de seguridad antes de renderizar. Programas humanos residuales (directorios, lanzamiento) no se reclaman completos.

Requisito: FFmpeg instalado y disponible en el PATH.

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Instalación y diagnóstico
pip install kinocut
kino doctor

Para Claude Code:

claude mcp add kinocut -- uvx --from kinocut kino

kino doctor informa qué funciones están disponibles y qué falta instalar. La documentación completa está en inglés; los mensajes de error principales son bilingües.

Inicio rápido

Camino dorado (60 segundos)

Pruebe que la instalación funciona antes de conectar un host de agente:

pip install -e .          # or: pip install kinocut
kino doctor               # required checks must pass
python scripts/golden_path.py

Criterios de éxito y recuperación de fallos: docs/GOLDEN_PATH.md.
Paquete compartible (recibo + calidad + medios): python scripts/generate_golden_pack.py → demo/golden-pack/.

Pruebe primero la prueba respaldada por recibo

Desde un clon de este repositorio, ejecute el flujo de trabajo de confianza más pequeño antes de conectar un host de agente:

uv run --no-project --with kinocut python workflows/05-confidence-baseline/workflow.py
uv run --no-project --with kinocut python workflows/benchmarks/run_confidence_benchmark.py

El flujo de trabajo genera un clip fuente pequeño, crea un video vertical verificado, ejecuta pasos de punto de control de calidad/lanzamiento y escribe workflows/05-confidence-baseline/output/video_receipt.json.

Las notas de prueba viven en docs/proofs/. Las afirmaciones de marketing público (versión, conteos de herramientas, URL) viven en docs/public_claims.json y están protegidas por CI.

Claude Code

claude mcp add kinocut -- uvx --from kinocut kino

Claude Desktop

{
  "mcpServers": {
    "kinocut": {
      "command": "uvx",
      "args": ["--from", "kinocut", "kino"]
    }
  }
}

Cursor

{
  "mcpServers": {
    "kinocut": {
      "command": "uvx",
      "args": ["--from", "kinocut", "kino"]
    }
  }
}

Luego pregunte a su agente:

Recorta esta entrevista en un clip vertical de 45 segundos, agrega subtítulos quemados, normaliza el audio, haz una miniatura y crea un punto de control de lanzamiento antes de exportar.

Habilidad de agente

Kinocut incluye una habilidad de agente pública en skills/kinocut/SKILL.md. Use $kinocut en hosts de agentes compatibles cuando quiera que el agente elija entre el servidor MCP, CLI y cliente Python mientras preserva el flujo de trabajo de inspeccionar, editar, verificar y revisión humana.

Para paquetes de formato corto basados en rutas solo de herramientas actuales (sin comandos inventados, sin publicación externa), consulte skills/kinocut-repurpose/SKILL.md. Esa habilidad es una semilla de marketing explícita; el producto de reutilización duradero respaldado por kernel sigue en la hoja de ruta de ejecución confiable.

Cliente Python

from kinocut import Client

editor = Client()

clip = editor.trim("interview.mp4", start="00:02:15", duration="00:00:45")
caption_file = "captions.srt"
editor.ai_transcribe(clip.output_path, output_srt=caption_file)
captioned = editor.subtitles(clip.output_path, subtitle_file=caption_file)
vertical = editor.resize(captioned.output_path, aspect_ratio="9:16")
checkpoint = editor.release_checkpoint(vertical.output_path)

print(checkpoint["thumbnail"])
print(checkpoint["storyboard"])

CLI

kino info interview.mp4
kino trim interview.mp4 -s 00:02:15 -d 45
kino video-ai-transcribe clip.mp4 --output captions.srt
kino subtitles clip.mp4 captions.srt
kino resize clip.mp4 --aspect-ratio 9:16
kino video-quality-check clip.mp4
kino repurpose clip.mp4 --platforms youtube-shorts instagram-reel tiktok
kino image-extract-colors product.jpg
kino still-package --establish hero.png --beats shot1.png shot2.png --output-dir out/stills

Lo que los agentes pueden hacer

Flujo de trabajo	Ejemplo de indicación
Clips sociales	"Convierte esta grabación horizontal en un TikTok y YouTube Short con subtítulos."
Producción de podcasts	"Encuentra el segmento más fuerte, recórtalo, normaliza el audio, agrega capítulos y exporta."
Demos de productos	"Crea un video de lanzamiento corto a partir de capturas de pantalla, tarjetas de título y voz en off."
Planificación cinematográfica	"Crea un paquete de estilo y guión gráfico, luego renderiza indicaciones de tomas para generación."
Revisión de calidad	"Compara estas dos exportaciones, haz miniaturas y señala problemas visuales o de audio."
Automatización por lotes	"Convierte esta carpeta de clips a MP4 listo para web con sonoridad consistente."
Video creado por código	"Andamia una composición Hyperframes, inspecciónala, renderízala, luego agrega subtítulos y una marca de agua."
Reutilización local	"Convierte este clip maestro en activos de Shorts, Reels, TikTok y YouTube con miniaturas y un manifiesto."
Rescate de video	"Diagnostica este clip dañado, propón solo reparaciones seguras, renderiza un paquete aprobado y verifica el recibo."
Revisión gobernada (punta de desarrollo)	"Ingiere esta exportación en un proyecto, ejecuta preflight e inspección temporal, escribe un veredicto y rescata solo la región rota."

Herramientas MCP

En la superficie publicada 1.14.1 (y la punta correspondiente), kino registra 196 herramientas MCP y 167 comandos CLI. La tabla resume las categorías principales — search_tools descubre la operación exacta sin cargar cada descripción.

Categoría	Cantidad	Destacados
Edición de video principal	32	trim, merge, resize, crop, rotate, convert, overlays, subtitles, export, cleanup, templates, merge-compatibility guardrails
Inspección respaldada por proyecto	3	content-addressed ingest, unified preflight, temporal evidence packages
Video IA gobernado	4	exact-asset verdicts, acceptance evaluation, audio-preserving body swaps, lineage-bound salvage
Motor de flujo de trabajo de agentes	4	validate, plan, render, resume, inspect multi-step jobs with provenance receipts
Rescate dedicado	3	diagnose, approve, render, verify, quarantine, and resume local content-preserving repairs
Planificación posterior al rescate	8	semantic timelines/query, EDLs, visual transforms, restoration, composition, autopilot, explicit egress
Creación cinematográfica	4	project scaffold, style-pack parsing, storyboard parsing, shot prompt expansion
Medios asistidos por IA	11	transcription, scene detection, upscaling, stem separation, silence removal, color grading
Hyperframes	18	init, preview, render, snapshots, inspect, catalog, website capture, local TTS, transcription, background removal, diagnostics, benchmark, post-process
Reutilización	2	dry-run manifests, platform-ready variants, thumbnails, storyboards, release checkpoints
Audio procedural	7	synthesize, compose, presets, effects, sequences, generated audio, spatial audio, mix-parameter guardrails
Efectos visuales	8	vignette, glow, noise, scanlines, chromatic aberration, luma key, mask, shape mask, bounded filter parameters
Transiciones	3	glitch, morph, pixelate
Diseño y movimiento	6	grid, picture-in-picture, split-screen, animated text, counters, progress bars, auto-chapters, layout mismatch warnings
Análisis	8	scene detection, thumbnail, preview, storyboard, quality compare, metadata, waveform, release checkpoint
Análisis de imágenes	3	extract colors, generate palettes, analyze product images
Edición de fotogramas / placas	5	still-match, still-grade, still-gate, image-edit, still-package — establish-locked color match with cohesion gate
Descubrimiento	1	`search_tools`

from kinocut import Client

editor = Client()
matches = editor.search_tools("subtitle")
print(matches["tools"])

Referencia completa: docs/TOOLS.md

Flujo de trabajo seguro para agentes

Para agentes autónomos, la ruta prevista es inspeccionar, editar, verificar y luego pedir a un humano que revise los artefactos de publicación:

from kinocut import Client

client = Client()

print(client.inspect("trim"))

result = client.pipeline(
    [
        {"op": "trim", "input": "source.mp4", "start": "00:01:00", "duration": "00:00:45"},
        {"op": "add_text", "text": "Launch clip", "position": "top-center"},
        {"op": "normalize_audio"},
        {"op": "resize", "aspect_ratio": "9:16"},
        {"op": "export", "quality": "high"},
        {"op": "release_checkpoint"},
    ],
    output_path="final-short.mp4",
)

Contrato de seguridad:

Las llamadas que producen medios devuelven resultados estructurados con rutas de salida.
Las rutas de edición de alto riesgo ahora ejecutan protecciones previas antes de la ejecución de FFmpeg: límites de filtro, compatibilidad de fusión, volumen/temporización de mezcla de audio, opacidad y similitud de superposición/marca de agua/croma, temporización/desbordamiento de texto animado y advertencias de desajuste de cuadrícula/pantalla dividida.
Las llamadas de análisis y descubrimiento devuelven informes JSON estructurados.
El descubrimiento de herramientas está disponible a través de search_tools() y Client.inspect().
Los errores de palabras clave inesperados se convierten en orientación accionable de MCPVideoError.
No publiques video generado por agentes sin video_quality_check, video_release_checkpoint e inspección visual/auditiva humana.
Para derivados de video IA gobernado, exige identidades almacenadas, evidencia activa de decisión humana y una ranura de revisión nueva después de cada rescate o intercambio de cuerpo — nunca soluciones alternativas de FFmpeg sin procesar etiquetadas como gobernadas.

Registro de cambios

1.14.1 (2026-08-13):

Parche sobre 1.14.0: pyright NoReturn en cancelación de rescate para que GitHub Lint siga en verde. Misma superficie 360 + rendimiento.
mcp-video==1.6.10 instala kinocut==1.14.1.

1.14.0 (2026-08-13):

Publicado ensamblaje de doble cámara 360 desde un MP4 equirect cosido (independiente de cámara; no solo X4) mediante video_intent / Client.propose_360_assembly — aún 196 MCP / 167 CLI.
Implementado el top-10 del comité de rendimiento: filter_complex 360 de una sola pasada (audio conservado), QC muestreado, importaciones diferidas, caché SHA, fotogramas de storyboard por lotes.
mcp-video==1.6.9 instala kinocut==1.14.0.

1.13.0 (2026-08-07):

Añadida superficie de verbo de intención (video_intent / intent), piso de protección Watching (video_review_run / video_review_decide), propuestas de B-roll (video_propose_broll), traducción de subtítulos ES-primero (video_translate_captions) y mejoras de calidad de vida de ejecución confiable (TE).
Superficie publicada ampliada a 196 herramientas MCP y 167 comandos CLI (totalmente sincronizada entre interfaces estándar, de prueba y de cliente).
Validación de rutas reforzada para traducción de subtítulos, kit de marca y exportaciones OTIO.

1.12.0 (2026-08-07):

Añadida superficie de editor de fotogramas/placas (still-match, still-grade, still-gate, image-edit, still-package) con compuerta de cohesión de cierre ante fallo.

1.11.x (2026-07-24):

Añadidos adaptadores de unión públicos S12 delgados de kinocut_sound (sound-capabilities, sound-plan-validate, sound-mix-render, etc.).
Endurecimiento de seguridad posterior al tema para evitar fugas de rutas de host absolutas y garantizar que todas las operaciones descubiertas tengan rutas de invocación de cierre ante fallo.

Consulta CHANGELOG.md para las notas de versión históricas completas, o la página de GitHub Releases.

Preguntas frecuentes

¿Qué es Kinocut?

Kinocut es un servidor MCP gratuito de código abierto, una biblioteca de Python y una CLI kino para edición de video con agentes de IA. Envuelve FFmpeg (y extras opcionales de Hyperframes/Whisper) con protecciones previas, recibos de video y puntos de control de calidad. Anteriormente se llamaba mcp-video.

¿Cómo lo instalo?

brew install ffmpeg   # or apt install ffmpeg
pip install kinocut
kino doctor
claude mcp add kinocut -- uvx --from kinocut kino

¿Es gratuito y local-primero?

Sí. Apache-2.0, se ejecuta en tu máquina, no se requiere cuenta de Kinocut ni clave API para la superficie principal, y los medios no se suben a una nube de Kinocut.

¿Qué agentes funcionan con él?

Cualquier cliente compatible con MCP que pueda ejecutar un servidor stdio local (Claude Code, Cursor, Windsurf, Cline y similares). También puedes usar el cliente de Python o la CLI sin un agente.

¿Cuántas herramientas hay?

La 1.14.1 publicada documenta 196 herramientas MCP / 167 comandos CLI. La punta de desarrollo mantiene esos recuentos. El ensamblaje 360 reutiliza video_intent y video_review_decide — no es una herramienta MCP número 197.

¿Puede Kinocut editar video 360 de Insta360 X4?

Sí — desde un MP4 360 cosido, no .insv. Propón un 360_assembly_plan, apruébalo y luego renderiza split/switch/PiP/single. También funciona para otras cámaras equirect cosidas. Consulta docs/360_ASSEMBLY.md.

¿Se llamaba mcp-video?

Sí. mcp-video==1.6.10 instala kinocut==1.14.1. Las importaciones de compatibilidad, el nombre de la CLI, las variables de entorno, el directorio de datos, las URI de recursos y las claves de recibos siguen siendo compatibles en la línea 1.14.x.

Más respuestas: docs/faq.md · FAQ en el sitio: kinocut.dev/#faq

Documentación

Pruebas

La verificación de desarrollo está en docs/TESTING.md. Mantén actualizados los controles de superficie pública, flujo de trabajo de medios y seguridad al cambiar el comportamiento de las herramientas.

Desarrollo

git clone https://git.kyanitelabs.tech/KyaniteLabs/kinocut.git
cd kinocut
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v -m "not slow and not hyperframes"

Comunidad

Despliegues de la comunidad

Los operadores que quieran una URL MCP pública sin abrir puertos del router doméstico pueden estudiar la pila de referencia Apache-2.0 de la comunidad que coloca Kinocut + Hyperframes detrás de Tailscale Funnel, Caddy y Google OAuth (mcp-auth-proxy): hyperframes-selfhost (no afiliado con KyaniteLabs; evalúa la seguridad para tu modelo de amenazas).

Licencia

Apache 2.0. Consulta LICENSE.

Construido con FFmpeg, Hyperframes y el Model Context Protocol.

Parte de KyaniteLabs

Más de KyaniteLabs. Proyectos relacionados:

Epoch — servidor MCP de estimación de tiempo (PERT) para agentes de IA
DialectOS — servidor MCP y CLI de localización de dialectos españoles
checkyourself — controles de preparación para producción local-primero para código construido por IA

→ Más en kyanitelabs.tech

Si Kinocut te resulta útil, dale una estrella o síguelo — ayuda a otros creadores de agentes a encontrarlo.

Construido por Simon Gonzalez De Cruz — disponible para ingeniería Forward-Deployed / IA aplicada y trabajo por contrato a través de los enlaces de perfil público anteriores.

¿Qué es Kinocut?

Kinocut es un servidor MCP y CLI de edición de video con protecciones para agentes de IA que ayuda a creadores de agentes de IA, usuarios de Claude Code/Cursor y operadores de medios locales a editar, subtitular, reutilizar y controlar la calidad del video con herramientas FFmpeg tipadas.


Producto	Kinocut
Categoría	servidor MCP y CLI de edición de video con protecciones para agentes de IA
Ideal para	creadores de agentes de IA, usuarios de Claude Code/Cursor y operadores de medios locales
No es	un editor en la nube alojado ni un shell FFmpeg sin tipar
Fuente	GitHub · Forgejo
Palabras clave	video editing MCP, AI agent video, FFmpeg MCP, Shorts Reels, Insta360 360 assembly

Para quién es

Principal: creadores de agentes de IA, usuarios de Claude Code/Cursor y operadores de medios locales
Úsalo cuando necesites editar, subtitular, reutilizar y controlar la calidad del video con herramientas FFmpeg tipadas
Omítelo si necesitas un editor en la nube alojado o un shell FFmpeg sin tipar

Preguntas frecuentes

¿Qué es Kinocut?

Kinocut es un servidor MCP y CLI de edición de video con protecciones para agentes de IA. Ayuda a creadores de agentes de IA, usuarios de Claude Code/Cursor y operadores de medios locales a editar, subtitular, reutilizar y controlar la calidad del video con herramientas FFmpeg tipadas.

¿Quién debería usar Kinocut?

Creadores de agentes de IA, usuarios de Claude Code/Cursor y operadores de medios locales.

¿En qué se diferencia Kinocut?

A diferencia de los scripts FFmpeg sin procesar o los shells de agentes sin protección, Kinocut valida herramientas y emite recibos.

¿Es Kinocut software de producción?

Trata el estado del README y las etiquetas de versión como fuente de verdad para la madurez. Valida según tus propios requisitos antes del uso en producción.

¿Puede Kinocut convertir un archivo Insta360 X4 en una edición de dos cámaras?

Sí: exporta un MP4 360 cosido, luego propón → aprueba → renderiza. .insv se rechaza. Esto está en el paquete 1.14.1 publicado.

Estado

Mantenido a partir de 2026 en la rama predeterminada
Prefiere etiquetas de versión al fijar dependencias
Reporta problemas en el remoto canónico listado arriba

Superficie de agentes

Agentes de codificación: lean primero este README, luego los docs del repositorio AGENTS.md si están presentes
Prefieran briefs legibles por máquina (llms.txt) cuando el repositorio incluya uno
Los puntos de entrada de MCP o habilidades están documentados en el repositorio cuando corresponde

Contribuciones

Las issues y PRs son bienvenidas en el remoto canónico. Mantengan la documentación pública libre de secretos y rutas locales de la máquina.

Licencia

Consulte LICENSE en este repositorio (o los metadatos del paquete si la licencia es solo del paquete).