Communitygithub.com

KyaniteLabs/kinocut

Usa Kinocut para edición de video guiada, planificación basada en fuentes, operaciones FFmpeg, análisis de medios, subtítulos, flujos de audio, renderizado Hyperframes o Revideo, paquetes de reutilización y puntos de control de lanzamiento a través de un servidor MCP, cliente Python o CLI. Actívalo cuando un agente necesite inspeccionar, planificar, editar, renderizar, validar o empaquetar medios locales de manera segura.

¿Qué es kinocut?

Kinocut es una herramienta moderna de edición de video estructurada, diseñada para agentes de IA que necesitan interactuar con medios locales de forma segura y controlada, evitando comandos FFmpeg escritos a mano. Proporciona una superficie de edición con herramientas MCP, un cliente Python y una CLI que cubren análisis, edición, subtítulos, audio, composición por capas, renderizado con Hyperframes y Revideo, y flujos de reutilización para redes sociales. Su enfoque principal es la planificación basada en evidencia: primero se inspecciona el archivo, luego se planifica la edición con `video_intent` o herramientas similares, y solo después de revisar y aprobar el plan se procede al renderizado. Soporta flujos avanzados como ensamblaje de video 360, rescate de clips con reparaciones seguras, inspección temporal determinista, revisión de calidad y empaquetado con puntos de control. Está diseñado para entornos de desarrollo local con agentes como Claude Code, Cursor o Codex, y su motor de flujos de trabajo permite ejecutar trabajos de múltiples pasos con validación, reanudación y recepción de integridad. La seguridad es clave: nunca se ejecutan planes no revisados, no se inventan capacidades y se requiere revisión humana antes de publicar cualquier resultado.

Compatible con✓Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/KyaniteLabs/kinocut/tree/HEAD/skills/kinocut

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace kinocut?

Usa Kinocut cuando un agente necesite una superficie de edición de video estructurada en lugar de escribir comandos FFmpeg a mano. Expone herramientas MCP, un cliente Python y una CLI para edición, análisis, subtítulos, audio, Hyperframes, composición por capas y flujos de reutilización local.

Ruta predeterminada (haz esto primero)

  1. kino doctor luego kino --format json info <archivo>.
  2. Para una tarea desconocida, llama a search_tools con la tarea del usuario (por ejemplo, "eliminar palabras de relleno" o "mantener el rostro en el encuadre"), luego inspecciona las entradas requeridas de la herramienta devuelta. Planifica con video_intent para intenciones compatibles (el goal= opcional compila un archivo de corte; un objetivo 360/escritorio/mesa/x4 también propone un 360_assembly_plan). Verifica que la propuesta realmente cumpla con la solicitud antes de renderizar.
  3. Renderiza (video_cutfile_render, video_edit, flujo de trabajo, o una herramienta de motor única). Para 360: video_review_decide aprueba/rechaza ese plan, luego renderiza — nunca renderices un plan proposed. .insv es rechazado; necesitas un MP4 360 cosido. Guía: docs/360_ASSEMBLY.md.
  4. video-quality-check / assert_quality. La sincronización de repurpose y shorts-package falla cerrada con puntuación 80 a menos que se omita/allow_fail.
  5. Revisión visual/auditiva humana. Nunca trates un recibo como publicado.

Profundidad (rescate, salvamento, composición, Hyperframes, sonido fino S12): docs/TOOLS.md, docs/RESCUE.md, docs/WORKFLOWS.md. Lista blanca de flujos de trabajo: probe, trim, resize, convert, crop, add_text, merge, composite_layers, burn_in.

Carga la guía relevante cuando sea necesario. Usa evidencia de origen para decisiones editoriales; preserva nombres, números, negaciones y calificaciones. Reporta evidencia faltante o acciones no compatibles en lugar de inventar afirmaciones de origen, marcas de tiempo o capacidades. Una herramienta de planificación propone una edición; su existencia no significa que el detector o modelo requerido se haya ejecutado. El código es dueño de la sincronización, transformaciones, validación y ejecución; la revisión humana sigue siendo independiente del juicio del modelo.

Flujo de video-código local Revideo (consejo de desarrollo)

Usa revideo_materialize, revideo_install y revideo_render cuando la persona que llama necesite un proyecto por etapas inspeccionable. Usa revideo_render_job para los mismos pasos protegidos en una sola llamada. Una escena proporcionada es TypeScript ejecutable confiable: inspecciónala antes de usarla y nunca ejecutes código de escena no confiable. La instalación de dependencias puede acceder a npm; el renderizado se ejecuta localmente contra la plantilla fija de Kinocut. El recibo de renderizado vincula los bytes de medios observados y de salida al resumen exacto del archivo de trabajo en disco. .mp4, .webm y .mov seleccionan modos de exportación fijos MP4, WebM y ProRes 4444 y se verifican antes de la publicación. Verifica el recibo contra los bytes de salida, ejecuta video_quality_check y video_release_checkpoint, luego requiere revisión visual humana.

Comienza Aquí

  • Lee ../../README.md para la instalación y el contrato de seguridad.
  • Ejecuta kino doctor antes de FFmpeg / Hyperframes / extras de IA.

Elige una Superficie

  • MCP: mejor para Claude Code, Cursor, clientes estilo Codex y otros hosts de agentes. Configura uvx --from kinocut kino.
  • CLI: mejor para ediciones locales directas, diagnósticos rápidos, composite-layers --dry-run, trabajos por lotes y salida JSON amigable para CI.
  • Cliente Python: mejor para pipelines repetibles que necesitan resultados estructurados, rutas de salida y recibos de plan de capas guardados.

Ensamblaje de cámara dual 360 (publicado 1.14.0)

Úsalo cuando la fuente sea un MP4 360 equirectangular cosido de cualquier cámara (Insta360, Ricoh Theta, GoPro MAX, DJI Osmo 360, …) y la solicitud sean dos cámaras virtuales como divididas / conmutadas / PiP / individuales.

  1. video_intent(verb="reformat_vertical", goal="desk 360 split 9:16", source=ABS_PATH) o Client.propose_360_assembly(...).
  2. Muestra cámaras, diseño y fotogramas del storyboard. No inventes yaw/pitch.
  3. video_review_decide / Client.decide_360_assembly con approve o reject.
  4. Renderiza solo un plan aprobado (Client.render_360_assembly o video_review_decide + output_path).

No existe una herramienta MCP video_360_* ni un comando kino 360. CLI intent y review-decide no ejecutan este compilador. Los enlaces de director aceptan un proponedor JSON inyectado; un nombre de modelo configurado solo no ejecuta un modelo. Las propuestas en la nube requieren allow_cloud; los directores nunca escriben píxeles.

Máscara de producto / objeto (publicado en 1.15.1; actual en 1.15.3)

El extra opcional de máscara de objeto está disponible en la versión publicada 1.15.3. Usa el comando existente hyperframes-remove-background / hyperframes_remove_background. El modelo predeterminado es personas. Para SKUs de catálogo, joyas, botellas, zapatos, empaques o cualquier cosa que no sea una persona:

  1. hyperframes_remove_background(info=true) — lista modelos, sin descarga.
  2. pip install "kinocut[object-matte]" luego model="birefnet-general".
  3. Opcional --mask-interval 3 en video de producto. Superposición opcional de equipo para plato giratorio/soporte/trípode/barrido sobrante.
  4. Compón sobre un plato de tienda con composite-layers. Mantén cada src dentro del directorio de especificaciones.

No inventes video_product_matte; esto no es una nueva herramienta MCP. No recurras al modelo de personas cuando falte el extra de objeto. Guía: docs/PRODUCT_MATTE.md. Ejemplo: examples/product-matte/.

Rescate de Video Dedicado

Usa video_rescue_*, rescue-* o Client.rescue_* cuando la solicitud sea arreglar un clip local mientras se preserva su fuente, historia y línea de tiempo.

Secuencia requerida:

  1. Llama al plan y guarda el artefacto del plan.
  2. Presenta safe_repairs, recommendations, unavailable_repairs, blocked_repairs, vistas previas, intenciones de paquete, capacidades y estimación al usuario.
  3. Inspecciona el plan antes de renderizar. Obtén o infiere aprobación explícita solo para IDs en safe_repairs; omitir la lista de IDs significa todos los IDs seguros en el plan revisado.
  4. Llama al renderizado con exactamente esos IDs seguros aprobados.
  5. Inspecciona el recibo de renderizado, luego reporta rutas de paquete, sidecars no disponibles, integridad, verificación de compuerta, privacidad, reanudación y estado de limpieza.

Nunca renderices directamente desde un plan no revisado. Nunca agregues IDs de recomendación, IDs no disponibles o IDs bloqueados a la aprobación. Nunca uses herramientas en la nube, quemes subtítulos de rescate, reescribas la fuente o trates unavailable como fallo automático. Una cancelación o fallo de verificación debe permanecer sin promocionar o en cuarentena.

Inspección Determinista de Video con IA

Usa video_ingest, video_preflight y video_inspect_temporal (o sus equivalentes planos CLI y Python) cuando el metraje generado necesite evidencia antes de una decisión de edición. Ingiere primero, luego dirige el activo por su hash devuelto. Nunca reemplaces ese ID de activo con una ruta de host o construyas un AssetRecord en el límite público. La inspección temporal devuelve el paquete completo de fotogramas muestreados y tiras de movimiento, hallazgos deterministas y capacidades explícitas de proveedor no disponibles. La ausencia de proveedor es esperada y no debe desencadenar una descarga o un respaldo de red.

Revisión y Salvamento de Video Gobernado con IA

Usa video_verdict, video_acceptance_eval, video_body_swap y video_salvage (o sus equivalentes planos CLI y Python) para decisiones editoriales de activos exactos y recuperación derivada. Un veredicto no aprobado puede capturar análisis del agente, pero una disposición aprobada debe vincular una decisión humana activa y exacta con requisito, rol y evidencia de artefacto explícitos. La evaluación de aceptación se deriva en lugar de ser una acción de aprobación, y cada salida de salvamento comienza en una nueva ranura de revisión no aprobada.

Nunca inventes un ID de decisión, pases una aprobación no almacenada o busques una ruta de fuerza/anulación. Body swap rechaza la falta de coincidencia de duración a menos que la persona que llama elija una política explícita. Salvamento requiere un proyecto privado existente, un activo fuente almacenado, una política de receta limitada y un ID de especificación de aceptación exacto.

La evaluación de aceptación toma acceptance_spec_id y verdict_ids activos almacenados, nunca objetos de evidencia construidos por la persona que llama. Body swap público siempre toma project_dir primero y ambas rutas de origen deben resolverse a activos activos en ese proyecto exacto.

Lee docs/AI_VIDEO_REVIEW_AND_SALVAGE.md antes de operar este flujo de trabajo. Trata cada derivado como trabajo nuevo no aprobado y mantén la compuerta visual/auditiva humana explícita antes de la publicación.

Planificación Post-Rescate

Usa la herramienta MCP video_* correspondiente, el comando CLI plano o el método Client cuando la solicitud necesite recuperación semántica, ediciones de limpieza ordinarias, transformaciones conscientes del sujeto, restauración, composición, coordinación creativa o salida remota. Pasa evidencia e intención compatibles con JSON; presenta el plan devuelto y el diff antes de cualquier paso de renderizado separado.

Nunca inventes descripciones de fuente, ocultes incertidumbre, infieras aprobación de un plan o trates un ejecutor local faltante como permiso para usar un proveedor de nube. El trabajo remoto requiere un manifiesto de salida separado y aprobación. Un planificador que carece de evidencia o capacidad debe abstenerse.

Composición por Capas

Usa composite-layers / video_composite_layers cuando la edición sea una pila ordenada de capas de imagen, video o sólidas, especialmente tercios inferiores, variantes de imagen en imagen, placas de fondo borroso, máscaras/máscaras mate, o variantes de diseño específicas de plataforma.

Prefiere este camino sobre los filtergraphs FFmpeg sin procesar cuando un agente necesite transformaciones, opacidad, ventanas de inicio/duración, fuentes alfa de máscara/mate, o un recibo que pueda revisarse antes de publicar.

Flujo de planificación primero:

  1. Escribe una especificación JSON con canvas, layers ordenados y salida explícita.
  2. Ejecuta kino composite-layers --spec layers.json --dry-run --save-layer-plan layer-plan.json.
  3. Inspecciona el plan de capas en busca de hashes de fuente, hash de filtergraph, transformaciones, rotación/pivote, modos de mezcla, ventanas de sincronización y máscaras.
  4. Renderiza solo después de que el plan se vea correcto.
  5. Ejecuta video-quality-check, storyboard o thumbnail, y video_release_checkpoint.

El compositor admite modos de mezcla de lienzo completo y posicionados en lista blanca (multiply, screen, overlay, darken, lighten) con opacidad y ventanas de sincronización; los recibos permanecen layer_plan v2. Las mezclas no normal admiten opacidad y ventanas start/duration en dos geometrías: lienzo completo en {0,0} sin tamaño explícito, o un rectángulo posicionado con width y height enteros positivos y una posición integral no negativa dentro del lienzo. La mezcla RGB evita aplicar aritmética de color a planos de croma submuestreados. La escala, rotación/pivote, máscara/mate, posiciones fraccionarias y rectángulos fuera del lienzo permanecen diferidos y fallan cerrados con unsupported_blend_geometry. Las capas de video y las máscaras de video comienzan la reproducción en su inicio declarado. Mantén todas las fuentes y máscaras dentro del directorio de especificaciones. La salida es solo video; anchor es un alias de posición distinto de pivot. La rotación + máscara, la composición de audio y los adaptadores NLE completos permanecen diferidos. Inspecciona el recibo antes de la revisión humana; no trates esto como un reemplazo NLE completo.

Motor de Flujo de Trabajo del Agente

Cuando la edición sea un trabajo de múltiples pasos (no una sola llamada de herramienta), usa el motor de flujo de trabajo para planificar, validar, renderizar, recuperar y probar desde una especificación de trabajo JSON — a través de video_workflow_* (MCP), workflow-* (CLI) o Client.workflow_* (Python). Las operaciones son una pequeña lista blanca (probe | trim | resize | convert | crop | add_text | merge | composite_layers | burn_in) vinculada a motores examinados; las referencias de medios son simbólicas (@sources.*, @work/*, @outputs.*) y confinadas al espacio de trabajo; todo falla cerrado. Ver ../../docs/WORKFLOWS.md.

Planificar → validar → renderizar → inspeccionar → reanudar:

  1. workflow-validate --spec job.json — compuerta estructural económica; no renderiza nada.
  2. workflow-plan --spec job.json --save-plan plan.json — gráfico de operaciones en seco + sondas/hashes de fuente; renderiza cero medios.
  3. workflow-render --spec job.json --save-receipt receipt.json — ejecuta secuencialmente; emite un recibo de procedencia (hashes por paso, manifiesto de limpieza, advertencia de determinismo). Agrega --all-variants para variantes por lotes.
  4. workflow-inspect --receipt receipt.json — re-verificación de integridad de solo lectura + punteros de revisión humana antes de confiar en un recibo.
  5. workflow-render --spec job.json --resume receipt.json — reanuda un trabajo que falló con intermedios conservados (falla cerrado en una especificación cambiada).

Los recibos almacenan solo rutas relativas al espacio de trabajo — mantén las especificaciones y los recibos de ejemplo libres de rutas de inicio, nombres de usuario y tokens.

Flujo de Trabajo

  1. Inspecciona la entrada primero: kino info <archivo> o el equivalente MCP/Python.
  2. Haz un plan de bajo riesgo: trim, resize, normalizar audio, subtítulos, superposiciones, efectos o renderizado Hyperframes.
  3. Prefiere vistas previas o manifiestos de ejecución en seco antes de exportaciones costosas o destructivas:
    • preview para revisión visual rápida.
    • repurpose-plan antes de repurpose.
    • Hyperframes inspect, snapshot o still antes del renderizado completo.
    • Para planes de shorts guardados: shorts-plan-show → shorts-review → shorts-render → shorts-package.
    • Para sonido fino: sound-capabilities luego sound-plan-validate / sound-voice-batch / sound-mix-render / sound-qa-loudness / sound-qa-asr (o kino sound <acción>).
    • Proporciona valores numéricos para duraciones de sonido, ganancias, sonoridad y versiones de perfil; los booleanos son rechazados antes de la coerción. Los planes inválidos explícitos no pueden seleccionar el plan de ejemplo. Los planes tipificados se revalidan; consulta docs/SOUND_INPUT_VALIDATION.md para reglas de compatibilidad específicas del campo.
    • ASR real usa una solicitud de audio/referencia hash y raíz explícita; conserva su ZIP de transcripción y reporta discrepancias honestamente. Solo Whisper en caché local; sin descargas automáticas. Las llamadas heredadas solo hash son simulaciones. Consulta docs/SOUND_ASR_REQUESTS.md.
    • Para QA de sonoridad PCM16 mono/estéreo real, proporciona SoundLoudnessRequest más raíz del proyecto e inspecciona within_tolerance; la medición exitosa puede ser no conforme. Se requiere FFmpeg, y el fixture sin entrada está etiquetado como demo. Consulta docs/SOUND_LOUDNESS_REQUESTS.md.
    • Para masterización mono/estéreo retenida, proporciona SoundMasterRequest y raíz explícita a sound-master-render; consulta docs/SOUND_MASTER_REQUESTS.md. Inspecciona el ZIP verificado, el modo de normalización real y el cumplimiento de la política final medido, luego escucha antes del lanzamiento. Los canales de entrada se preservan; la salida existente nunca se reemplaza.
    • Para ASR local real EN/ES, proporciona SoundAsrRequest y raíz explícita a sound-asr-render; el campo reference se hashea para auditoría local; el resultado inspeccionado siempre es un ZIP verificado. No se permiten descargas automáticas; el caché local es solo Whisper. Consulta docs/SOUND_ASR_REQUESTS.md.
    • Para generación de voz real, usa sound-voice-batch con una lista de SoundVoiceRow y raíz explícita. Las filas con voz existente se omiten; las solicitudes sin voice_provider explícito usan la configuración del proyecto. Consulta docs/SOUND_VOICE_REQUESTS.md.
    • Para producción de mezcla de sonido real, usa sound-mix-render con SoundMixRequest y raíz explícita. Las entradas deben ser archivos locales (WAV, MP3, FLAC, etc.), no solo índices de voz sintéticos. Consulta docs/SOUND_MIX_REQUESTS.md.
  4. Renderiza y revisa: video-quality-check, storyboard o thumbnail, video_release_checkpoint.
  5. Aprobación humana final y publicación.

Equivalencias de Herramientas MCP y CLI

Las herramientas MCP, comandos CLI y métodos de cliente se corresponden por nombre a través de normalización de kebab-case / snake_case / camelCase. La herramienta MCP video_cutfile_render se convierte en kino cutfile-render, y Client.cutfile_render(...). hyperframes_remove_background se convierte en kino hyperframes remove-background. La lista completa está en docs/TOOLS.md.

Referencia Lingüística

En video_intent / Client.intent(...), el parámetro goal opcional selecciona patrones predefinidos como "desk 360 split 9:16" o "table x4 1:1". El parámetro plan debe ser una cadena JSON válida; allow_fallback permite que detectores degradados ejecuten planes fallidos. Skybox es un tipo de escena de video 360; no lo confundas con fondos generados. "Plan de trabajo" en workflow-* se refiere a una especificación de trabajo guardada.

Principios de Seguridad

  • Nunca difundas un recibo como publicación ni trates un plan como ejecución.
  • Nunca ejecutes código no confiable de Revideo.
  • Prefiere herramientas locales; la nube requiere allow_cloud explícito.
  • Verifica cada paso: hashes de fuente, hashes de salida y puntos de control de calidad.
  • Errores de validación y solicitudes no compatibles deben ser reportados, no ignorados.
  • Las afirmaciones de la IA deben ser verificadas contra la fuente antes de la acción.

Archivos de Documentación Relacionados

  • docs/TOOLS.md — lista completa de herramientas y mapeo de parámetros
  • docs/RESCUE.md — flujo completo de rescate de video
  • docs/WORKFLOWS.md — especificación del motor de flujo de trabajo
  • docs/360_ASSEMBLY.md — guía de ensamblaje de video 360
  • docs/PRODUCT_MATTE.md — guía de máscara de producto
  • docs/SOUND_INPUT_VALIDATION.md — reglas de validación de entrada de sonido
  • docs/SOUND_ASR_REQUESTS.md — especificación de solicitud ASR
  • docs/SOUND_LOUDNESS_REQUESTS.md — especificación de solicitud de sonoridad
  • docs/SOUND_MASTER_REQUESTS.md — especificación de solicitud de masterización
  • docs/SOUND_VOICE_REQUESTS.md — especificación de solicitud de voz
  • docs/SOUND_MIX_REQUESTS.md — especificación de solicitud de mezcla
  • docs/AI_VIDEO_REVIEW_AND_SALVAGE.md — revisión y salvamento de video con IA
  • examples/product-matte/ — ejemplos de máscara de producto
  • ../../README.md — instalación y contrato de seguridad

Skills relacionados