¿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)
kino doctorluegokino --format json info <archivo>.- Para una tarea desconocida, llama a
search_toolscon 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 convideo_intentpara intenciones compatibles (elgoal=opcional compila un archivo de corte; un objetivo 360/escritorio/mesa/x4también propone un360_assembly_plan). Verifica que la propuesta realmente cumpla con la solicitud antes de renderizar. - Renderiza (
video_cutfile_render,video_edit, flujo de trabajo, o una herramienta de motor única). Para 360:video_review_decideaprueba/rechaza ese plan, luego renderiza — nunca renderices un planproposed..insves rechazado; necesitas un MP4 360 cosido. Guía:docs/360_ASSEMBLY.md. video-quality-check/assert_quality. La sincronización derepurposeyshorts-packagefalla cerrada con puntuación 80 a menos que se omita/allow_fail.- 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.mdpara la instalación y el contrato de seguridad. - Ejecuta
kino doctorantes 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.
video_intent(verb="reformat_vertical", goal="desk 360 split 9:16", source=ABS_PATH)oClient.propose_360_assembly(...).- Muestra cámaras, diseño y fotogramas del storyboard. No inventes yaw/pitch.
video_review_decide/Client.decide_360_assemblyconapproveoreject.- Renderiza solo un plan aprobado (
Client.render_360_assemblyovideo_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:
hyperframes_remove_background(info=true)— lista modelos, sin descarga.pip install "kinocut[object-matte]"luegomodel="birefnet-general".- Opcional
--mask-interval 3en video de producto. Superposición opcional de equipo para plato giratorio/soporte/trípode/barrido sobrante. - Compón sobre un plato de tienda con
composite-layers. Mantén cadasrcdentro 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:
- Llama al plan y guarda el artefacto del plan.
- Presenta
safe_repairs,recommendations,unavailable_repairs,blocked_repairs, vistas previas, intenciones de paquete, capacidades y estimación al usuario. - 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. - Llama al renderizado con exactamente esos IDs seguros aprobados.
- 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:
- Escribe una especificación JSON con
canvas,layersordenados y salida explícita. - Ejecuta
kino composite-layers --spec layers.json --dry-run --save-layer-plan layer-plan.json. - 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.
- Renderiza solo después de que el plan se vea correcto.
- Ejecuta
video-quality-check,storyboardothumbnail, yvideo_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:
workflow-validate --spec job.json— compuerta estructural económica; no renderiza nada.workflow-plan --spec job.json --save-plan plan.json— gráfico de operaciones en seco + sondas/hashes de fuente; renderiza cero medios.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-variantspara variantes por lotes.workflow-inspect --receipt receipt.json— re-verificación de integridad de solo lectura + punteros de revisión humana antes de confiar en un recibo.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
- Inspecciona la entrada primero:
kino info <archivo>o el equivalente MCP/Python. - Haz un plan de bajo riesgo: trim, resize, normalizar audio, subtítulos, superposiciones, efectos o renderizado Hyperframes.
- Prefiere vistas previas o manifiestos de ejecución en seco antes de exportaciones costosas o destructivas:
previewpara revisión visual rápida.repurpose-planantes derepurpose.- Hyperframes
inspect,snapshotostillantes del renderizado completo. - Para planes de shorts guardados:
shorts-plan-show→shorts-review→shorts-render→shorts-package. - Para sonido fino:
sound-capabilitiesluegosound-plan-validate/sound-voice-batch/sound-mix-render/sound-qa-loudness/sound-qa-asr(okino 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.mdpara 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
SoundLoudnessRequestmás raíz del proyecto e inspeccionawithin_tolerance; la medición exitosa puede ser no conforme. Se requiere FFmpeg, y el fixture sin entrada está etiquetado como demo. Consultadocs/SOUND_LOUDNESS_REQUESTS.md. - Para masterización mono/estéreo retenida, proporciona
SoundMasterRequesty raíz explícita asound-master-render; consultadocs/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
SoundAsrRequesty raíz explícita asound-asr-render; el camporeferencese 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. Consultadocs/SOUND_ASR_REQUESTS.md. - Para generación de voz real, usa
sound-voice-batchcon una lista deSoundVoiceRowy raíz explícita. Las filas con voz existente se omiten; las solicitudes sinvoice_providerexplícito usan la configuración del proyecto. Consultadocs/SOUND_VOICE_REQUESTS.md. - Para producción de mezcla de sonido real, usa
sound-mix-renderconSoundMixRequesty raíz explícita. Las entradas deben ser archivos locales (WAV, MP3, FLAC, etc.), no solo índices de voz sintéticos. Consultadocs/SOUND_MIX_REQUESTS.md.
- Renderiza y revisa:
video-quality-check,storyboardothumbnail,video_release_checkpoint. - 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_cloudexplí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ámetrosdocs/RESCUE.md— flujo completo de rescate de videodocs/WORKFLOWS.md— especificación del motor de flujo de trabajodocs/360_ASSEMBLY.md— guía de ensamblaje de video 360docs/PRODUCT_MATTE.md— guía de máscara de productodocs/SOUND_INPUT_VALIDATION.md— reglas de validación de entrada de sonidodocs/SOUND_ASR_REQUESTS.md— especificación de solicitud ASRdocs/SOUND_LOUDNESS_REQUESTS.md— especificación de solicitud de sonoridaddocs/SOUND_MASTER_REQUESTS.md— especificación de solicitud de masterizacióndocs/SOUND_VOICE_REQUESTS.md— especificación de solicitud de vozdocs/SOUND_MIX_REQUESTS.md— especificación de solicitud de mezcladocs/AI_VIDEO_REVIEW_AND_SALVAGE.md— revisión y salvamento de video con IAexamples/product-matte/— ejemplos de máscara de producto../../README.md— instalación y contrato de seguridad