mcp-video

Servidor MCP de edição de vídeo nativo de IA para fluxos de trabalho com FFmpeg.

Documentação

Kinocut

Servidor MCP de edição de vídeo com guardrails para agentes de IA.
Ferramentas FFmpeg locais, Video Receipts, portões de qualidade, Hyperframes e reaproveitamento para Shorts/Reels — para Claude Code, Cursor e qualquer cliente MCP. Gratuito, Apache-2.0. Anteriormente mcp-video.

Demonstração • Status • 1.14.1 • Changelog • Além • Instalação • Início Rápido • Ferramentas • Referência de Ferramentas • Resgate • montagem 360 • vídeo com IA • Habilidade do Agente • kinocut.dev • O que é o Kinocut? • FAQ • llms.txt

Kinocut é um servidor MCP de edição de vídeo gratuito e de código aberto, além de um mecanismo de workflow para agentes de IA (com cliente Python e CLI kino) que permite que agentes de IA cortem, legendem, reaproveitem e apliquem portões de qualidade em mídia de vídeo local com ferramentas tipadas e Video Receipts — e não com flags FFmpeg inventadas.

O que é o Kinocut?

Em resumo: Kinocut é um servidor MCP de edição de vídeo gratuito e local (com cliente Python e CLI kino) para que agentes de IA possam cortar, legendar, reaproveitar e aplicar portões de qualidade em mídia com ferramentas tipadas e Video Receipts — e não flags FFmpeg inventadas.

Kinocut é um servidor de Protocolo de Contexto de Modelo (MCP) gratuito e de código aberto, uma biblioteca Python e uma CLI kino que dá aos agentes de IA uma superfície local de edição de vídeo com guardrails. Ele encapsula o FFmpeg (e extras opcionais de Hyperframes / Whisper) com ferramentas tipadas, validação de preflight, proveniência via Video Receipt e checkpoints de qualidade/versão, para que a mídia produzida por agentes possa ser inspecionada antes da publicação.


Também conhecido como	`kino` (CLI); anteriormente mcp-video / `mcp_video`
Última versão publicada	1.14.1 (2026-08-13)
Site do produto	kinocut.dev
PyPI	`kinocut`
Registro MCP	`io.github.KyaniteLabs/kinocut`
Código-fonte	GitHub (colab público) · Forgejo (fonte canônica)
Licença	Apache-2.0
Executa em	Sua máquina (macOS, Linux, Windows) — FFmpeg necessário em `PATH`
Não é	Um editor em nuvem hospedado, SaaS medido por créditos ou um wrapper de shell FFmpeg sem tipagem

Buscas com melhor correspondência: servidor MCP de edição de vídeo · edição de vídeo com agente de IA · FFmpeg MCP · ferramentas de vídeo para Claude Code · vídeo MCP para Cursor · automação de Shorts/Reels · workflow local de vídeo com IA · mídia agêntica com guardrails.

Resumo legível por máquina para crawlers de IA: llms.txt · site: kinocut.dev/llms.txt.

Veja Funcionando

Diga ao agente o que você quer em linguagem simples:

"Corte esta entrevista para os 45 segundos mais fortes, adicione legendas queimadas, deixe na vertical e faça a verificação de qualidade antes de exportar."

O Kinocut transforma isso em chamadas de ferramenta tipadas e com guardrails — sem flags FFmpeg para adivinhar, sem exportações quebradas silenciosamente:

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

Função principal: transformar uma entrevista ou podcast local em clipes verticais legendados com um Video Receipt que os agentes podem reexecutar e os humanos podem aprovar.

Três usos comuns

Reaproveitamento — uma gravação em pacotes de Shorts, Reels e TikTok legendados com manifests e artefatos de revisão.
Cortes de podcast e entrevista — encontrar o segmento mais forte, normalizar o áudio, adicionar capítulos e exportar.
Mídia dirigida por agentes em CI — edições repetíveis e revisáveis a partir de Claude Code, Cursor, clientes estilo Codex ou scripts.

Caminhos: Matriz de instalação · Caminho dourado · Prompts · Tutorial · Comparar · Quando recomendar

Status e versões

Superfície	Versão / dica	O que significa
PyPI / npm / GitHub Release	1.14.1 (2026-08-13)	Kinocut publicado mais recente. Instale com `pip install kinocut`.
Este repositório (`master`)	1.14.1 · 196 ferramentas MCP / 167 comandos CLI	Mesmas contagens publicadas. A montagem 360 reutiliza `video_intent` / revisão (não é uma 197ª ferramenta).
Próxima versão pública	TBD	Resíduos humanos (diretórios, posts de lançamento) permanecem bloqueados; novos avanços exigem nova autorização.

Instale a partir do PyPI para obter o pacote estável. Clone master somente quando você quiser intencionalmente o trabalho não lançado da ponta.

O que há na 1.14.1 (última versão)

O Kinocut 1.14.1 é o que você obtém de pip install kinocut hoje. É um patch sobre a 1.14.0: mesma montagem dual-cam 360 e correções de desempenho do comitê, além de uma correção de lint pyright no GitHub (caminho de cancelamento render_rescue). A superfície permanece 196 MCP / 167 CLI — nenhum novo nome de ferramenta pública.

Montagem dual-cam 360 — qualquer MP4 equiretangular costurado (Insta360, Ricoh Theta, GoPro MAX, DJI Osmo 360, …) → 360_assembly_plan revisável (mesa / mesa / front_back, divisão / alternância / PiP / única) → aprovar → render FFmpeg v360. MCP: video_intent goal= + video_review_decide. Python: Client.propose_360_assembly / decide_360_assembly / render_360_assembly. .insv / .360 bruto rejeitado. O diretor é um plug (local primeiro; nuvem opcional). Não é uma alegação de IA otimizada. Guia: docs/360_ASSEMBLY.md.
Caminho 360 e de importação mais rápido — filter_complex de divisão/PiP/alternância em passagem única (áudio-fonte mantido); janela de análise de qualidade-gate amostrada; cache de caminho/mtime SHA-256; merge pode pular o re-probe quando infos= é fornecido; stills de storyboard 360 em lote; mcp_video / CLI / Client.search_tools preguiçoso; doctor pula npx --yes a menos que Hyperframes já esteja no PATH.
Import público preguiçoso — import kinocut não carrega mais Client/engines avidamente (PEP 562). from kinocut import Client e kinocut.Client is mcp_video.Client ainda se mantêm.
Honestidade de costura de navio — repurpose padrão do CLI/Client --min-score 80; shorts-package falha-fechado a menos que --allow-fail; video_repurpose MCP durável não aplica min_score.
Janela de compatibilidade — mcp-video==1.6.10 instala kinocut==1.14.1; mcp_video imports, variáveis de ambiente MCP_VIDEO_*, dados ~/.mcp-video, recursos mcp-video:// e chaves de receipt legadas permanecem suportados na linha 1.14.x.

Também já na linha publicada a partir da 1.13.x:

Superfície de verbo-intenção — video_intent / intent (~10 verbos) para simular planos sem mutações de mídia silenciosas
Piso de guardrail de vigilância — video_review_run / video_review_decide (blackdetect/LUFS + inspeção dos primeiros 15s)
Propostas de B-roll, tradução de legendas ES-first, editor de still/plate, render de cutfile, metric-qc
Mecanismo de workflow de agente, resgate de vídeo dedicado, composição em camadas, Hyperframes, reaproveitamento de Shorts/Reels
Contagens canônicas — 196 ferramentas MCP e 167 comandos CLI

Notas completas: CHANGELOG.md · versão v1.14.1

Além da 1.14.1 (rascunho / bloqueado)

1.14.1 é a versão publicada mais recente. Envios de diretórios ao vivo e posts de lançamento permanecem resíduos de operador/humano (docs/HUMAN_GATES.md) e não são declarados completos.

Superfícies em Fase e Bloqueadas

Embora a edição FFmpeg principal, a montagem 360, o mecanismo de workflow, a edição de still/plate, a revisão/resgate de vídeo com IA e as capacidades de som estejam totalmente integradas e publicadas na 1.14.1, as seguintes superfícies permanecem bloqueadas, parciais ou não lançadas:

Empacotamento Desktop MCPB: O pacote desktop em fase (mcpb/) é uma configuração em fase e não é um runtime nativo autônomo publicado ainda (pendente de proveniência FFmpeg, licenciamento e portões de máquina limpa). Veja docs/MCPB.md.
Áudio Sonic World (kinocut_sound): Embora as capacidades S1–S12 estejam integradas na linha publicada, as fatias restantes estão bloqueadas ou em fase:
- S13 (Host Joins / bindings): Bloqueado — receipts do proprietário externo incompletos.
- S14 (Benchmark dual-classe): Parcial — x86 disponível, host Apple Silicon indisponível.
- S15 (Portão Adversarial): Em fase sob um STOP de versão — requer receipts S13, benchmarks dual-classe e autorização humana explícita.
Kernel de Execução Confiável: O kernel de execução confiável de timeline protegida é pós-programa/em fase e não executa sem o contrato upstream nomeado e portão humano (docs/plans/2026-07-09-kinocut-trusted-execution-layer.md).
Planos Pagos de Geração / Dublagem: Planos gerativos com teto de gastos e dublagem TTS permanecem definições de rascunho não executáveis até que backends externos e credenciais sejam configurados.

Checklist do produto: ROADMAP.md.

Mecanismo de Workflow de Agente

Os agentes podem planejar, validar, renderizar, recuperar e comprovar um trabalho de vídeo local em várias etapas a partir de uma única especificação de trabalho JSON — via MCP (video_workflow_*), a CLI (workflow-*) ou o cliente Python (Client.workflow_*) — com receipts fortes o suficiente para que outro agente ou humano confie antes e depois de um render. As operações são uma pequena allowlist (probe | trim | resize | convert | merge | add_text | composite_layers) mapeada 1:1 para as mesmas funções de mecanismo auditadas que as ferramentas individuais usam; as referências de mídia são simbólicas e confinadas ao workspace; tudo falha de forma fechada.

{
  "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

O receipt de render registra hashes de entrada/saída por etapa, um cursor de retomada e um manifest de limpeza, tudo com caminhos relativos ao workspace:

{
  "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 saídas distintas a partir de uma declaração, e --resume continua um trabalho que falhou mantendo seus intermediários (falha-fechado em especificação alterada). Schema completo, gramática @ref, variantes, retomada e limpeza estão em docs/WORKFLOWS.md; uma especificação executável está em examples/workflows/.

Revisão de vídeo com IA governada

No Kinocut, um caminho contrato-primeiro é fornecido para mídia editada por agente que deve permanecer atribuível e revisável:

Ingestão da fonte em um projeto privado com endereçamento por conteúdo (video_ingest / video-ingest)
Preflight + inspeção temporal no ativo armazenado (video_preflight, video_inspect_temporal)
Veredito + aceitação com evidência humana exata (video_verdict, video_acceptance_eval)
Somente derivados limitados — troca de corpo preservando áudio ou receitas de resgate na allowlist (video_body_swap, video_salvage), cada uma com linhagem e um novo slot de revisão não aprovado Não há flag de força/desvio. A saída do analisador sozinha não pode aprovar. Entradas obsoletas, aliasadas ou protegidas falham de forma fechada. Guia de operação: docs/AI_VIDEO_REVIEW_AND_SALVAGE.md. Essas superfícies estão totalmente integradas na versão publicada 1.14.1 — veja Status e lançamentos.

Resgate de Vídeo Dedicado

Para solicitações de "corrija este clipe" em que a história e a linha do tempo devem permanecer inalteradas, use o pipeline de resgate que prioriza a revisão. Planeje e inspecione o diagnóstico, aprove apenas IDs de reparo seguros, renderize e inspecione o pacote verificado. A fonte permanece imutável; a cópia master e de compartilhamento universal são sempre verificadas; legendas opcionais permanecem como sidecars. Veja docs/RESCUE.md para CLI, MCP, Python, cancelamento, retomada e erros estáveis.

Composição em Camadas

composite-layers / video_composite_layers adiciona uma pilha de camadas ordenada orientada a spec para agentes que precisam de mais do que primitivas de sobreposição de dois planos. Suporta camadas de imagem, vídeo e sólida; composição alfa normal; opacidade por camada; posicionamento x/y; dimensionamento por transformação; janelas de tempo; e fontes alfa de máscara/matte — além de modos de mesclagem de tela cheia (multiply, screen, overlay, darken, lighten) e rotação com um novo ponto de referência pivot. Planos de dry-run e recibos determinísticos de layer_plan v2 capturam hashes de origem, filtergraph e saída.

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 quando um agente precisar de uma pilha planejada de sobreposições, mattes, terços inferiores, placas de desfoque ou variantes de plataforma que devem ser revisadas antes da renderização. Uma camada de mesclagem não normal deve ser em tela cheia (posição {0,0}, opacidade total, sem escala/máscara/timing) ou falha de forma fechada; a saída é apenas vídeo. Mesclagem posicionada/escalada/mascarada/temporalizada, rotação + máscara e roteamento de efeitos por camada são rastreados como fases posteriores para que esta superfície permaneça determinística e pré-verificável.

Montagem 360 dual-cam

Qualquer MP4 360 equirectangular já costurado (Insta360, Ricoh Theta, GoPro MAX, DJI, …) pode se tornar um corte 16:9 ou 9:16 de duas câmeras sem um novo nome de ferramenta. Exporte do aplicativo da câmera primeiro — o Kinocut não costura .insv ou 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 com uma meta de 360/mesa/tabela e source=, depois video_review_decide. Contrato completo: docs/360_ASSEMBLY.md.

Edição de Imagem Estática / Still

O Kinocut trata pacotes de múltiplas imagens estáticas como mídia de primeira classe — plano → recibo → portão de falha fechada, mesma postura de segurança do resgate de vídeo. Requer pip install "kinocut[image]"; execute kino doctor para verificar a pilha de imagens.

Fluxo de trabalho: estabeleça uma placa hero → edite os beats em direção a ela → corresponda ao WB/exposição compartilhado → grave (opcionalmente LUT de sinal) → portão de coesão.

# 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 falha de forma fechada em spread de luma e métricas de verde/ciano de sombra; toda ferramenta escreve um recibo JSON com hashes e ganhos. Backends generativos pagos permanecem desativados por padrão (prefer=edit, allow_paid_gen=false). Guia completo: docs/STILL_PLATES.md.

Descoberta Pública

O Kinocut é construído para ser encontrável e citável tanto por mecanismos de busca quanto por motores de resposta de IA:

URL canônica do produto: https://kinocut.dev/
README do GitHub + llms.txt com fatos da entidade, comandos de instalação e regras de segurança
Registro oficial no MCP Registry sob io.github.KyaniteLabs/kinocut
Respostas de FAQ neste README e em docs/faq.md (respostas primeiro, alegações versionadas)

Kinocut vs FFmpeg puro (e vs editores em nuvem)

	Kinocut	FFmpeg puro no shell do agente	API típica de editor em nuvem
Interface	MCP / Python / CLI tipado	Flags de forma livre	API HTTP hospedada
Pré-verificação	Guardrails antes da renderização	Agente inventa flags	Específica do fornecedor
Proveniência	Recibos de vídeo + hashes	Logs ad-hoc	Dashboard do fornecedor
Localização da mídia	Local-first	Local	Upload necessário
Custo principal	Grátis (Apache-2.0)	Grátis	Frequentemente medido

Por que Existe

Agentes de IA podem escrever comandos FFmpeg, mas não deveriam precisar adivinhar flags, analisar erros stderr frágeis ou publicar silenciosamente mídia quebrada. O Kinocut dá aos agentes operações tipadas, metadados de ferramentas inspecionáveis, resultados estruturados, guardrails de pré-verificação e checkpoints de qualidade para que um fluxo de trabalho de vídeo possa ser automatizado e revisado sem se transformar em roleta de comandos shell.

Use quando quiser que um assistente de IA:

corte, una, redimensione, recorte, gire, transcode ou exporte vídeo;
adicione texto, legendas, marcas d'água, sobreposições, filtros, fades, efeitos e transições;
extraia áudio, normalize áudio, sintetize áudio, adicione áudio gerado ou crie formas de onda;
detecte cenas, faça miniaturas, gere storyboards, compare qualidade e crie checkpoints de lançamento;
corresponda, grave e gate pacotes de imagens com coesão de cor bloqueada por estabelecimento, ou analise imagens de produto para cores e paletas;
crie esqueletos de projetos cinematográficos, leia blocos STYLE_/NEG_, analise tabelas de storyboard e expanda prompts de cena;
crie novos projetos Hyperframes, inspecione layouts renderizados, capture sites, gere fala local, remova fundos e pós-processe o resultado com ferramentas FFmpeg;
reutilize um vídeo fonte em pacotes verticais, horizontais e quadrados de entrega local com manifestos e artefatos de revisão;
conduza fluxos de mídia repetíveis a partir do Claude Code, Cursor, clientes estilo Codex, scripts ou CI.

Instalação

Pré-requisito: FFmpeg deve estar instalado e disponível em PATH.

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

Execute sem instalação global:

uvx --from kinocut kino doctor

Ou instale com pip:

pip install kinocut
kino doctor

Para instalações MCPB estilo Claude Desktop, o Kinocut inclui um pacote local encenado em mcpb/ e um script de build local:

python3 scripts/build-mcpb.py

Este pacote é honesto sobre seu runtime: ele lança um ambiente Python existente com Kinocut instalado e ainda requer FFmpeg local. Pacotes nativos autocontidos permanecem bloqueados até que proveniência do FFmpeg, licenciamento e portões de máquina limpa sejam resolvidos. Veja docs/MCPB.md.

Assinatura opcional C2PA para exportações MP4 finais está disponível na ponta de desenvolvimento quando c2patool e um manifesto/assinante estiverem configurados. A assinatura fica desativada por padrão e só reporta signed após uma leitura de verificação bem-sucedida. Veja docs/C2PA_PROVENANCE.md.

As ferramentas Hyperframes também precisam de Node.js 22+ e um CLI Hyperframes resolvível. Instale/pin Hyperframes no layout de pacote Node ativo, adicione hyperframes a PATH, ou defina MCP_VIDEO_HYPERFRAMES_COMMAND.

Qual extra eu preciso?

A instalação principal cobre todas as ferramentas de edição FFmpeg. Recursos opcionais são fornecidos como extras — instale apenas o que usar:

Você quer	Instale	Tamanho extra aproximado
Legendas de fala para texto (Whisper)	`pip install "kinocut[transcribe]"`	~1 GB (torch)
Análise de imagem (cores, layout, contraste)	`pip install "kinocut[image]"`	~50 MB
Separação de stems vocal/instrumental	`pip install "kinocut[stems]"`	~2 GB (torch + demucs)
Upscaling por IA	`pip install "kinocut[upscale]"`	~2 GB (Python ≤3.12)
Ferramentas de áudio/música processual	`pip install "kinocut[audio]"`	~30 MB (numpy)
Tudo de IA	`pip install "kinocut[ai]"`	vários GB

Misture livremente, por exemplo pip install "kinocut[transcribe,image]". Execute kino doctor depois — ele reporta exatamente quais recursos estão disponíveis e o que está faltando.

Atualizando de mcp-video

O Kinocut preserva a superfície original durante a janela de renomeação. Instalações existentes podem atualizar sem mudar código:

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

mcp-video==1.6.10 é um instalador de compatibilidade apenas de metadados para kinocut==1.14.1. O import mcp_video, o comando mcp-video, as variáveis de ambiente MCP_VIDEO_*, o diretório de dados ~/.mcp-video, os URIs de recurso mcp-video:// e as chaves de recibo existentes permanecem suportados na linha 1.14.x. Novas integrações devem usar kinocut, from kinocut import Client e o 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.

Início Rápido

Caminho dourado (60 segundos)

Prove que a instalação funciona antes de conectar um host de agente:

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

Critérios de sucesso e recuperação de falhas: docs/GOLDEN_PATH.md.
Pacote compartilhável (recibo + qualidade + mídia): python scripts/generate_golden_pack.py → demo/golden-pack/.

Tente a prova baseada em recibo primeiro

A partir de um clone deste repositório, execute o fluxo de confiança mais simples antes de conectar um 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

O fluxo gera um pequeno clipe fonte, cria um vídeo vertical verificado, executa etapas de checkpoint de qualidade/lançamento e escreve workflows/05-confidence-baseline/output/video_receipt.json.

Notas de prova vivem em docs/proofs/. Alegações públicas de marketing (versão, contagens de ferramentas, URLs) vivem em docs/public_claims.json e são 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"]
    }
  }
}

Então pergunte ao seu agente:

Corte esta entrevista em um clipe vertical de 45 segundos, adicione legendas queimadas, normalize o áudio, faça uma miniatura e crie um checkpoint de lançamento antes da exportação.

Skill de Agente

O Kinocut inclui uma skill de agente pública em skills/kinocut/SKILL.md. Use $kinocut em hosts de agente compatíveis quando quiser que o agente escolha entre o servidor MCP, CLI e cliente Python preservando o fluxo de inspecionar, editar, verificar e revisão humana.

Para pacotes baseados em caminho de formato curto apenas de ferramentas atuais (sem comandos inventados, sem publicação externa), veja skills/kinocut-repurpose/SKILL.md. Essa skill é uma semente de marketing explícita; o produto de reutilização durável baseado em kernel ainda está no roadmap de execução confiável.

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

O Que os Agentes Podem Fazer

Fluxo de trabalho	Exemplo de prompt
Clipes sociais	"Transforme esta gravação paisagem em um TikTok e YouTube Short com legendas."
Produção de podcast	"Encontre o segmento mais forte, corte-o, normalize o áudio, adicione capítulos e exporte."
Demonstrações de produto	"Crie um vídeo curto de lançamento a partir de capturas de tela, cartões de título e narração."
Planejamento cinematográfico	"Crie um pacote de estilo e storyboard, depois renderize prompts de cena para geração."
Revisão de qualidade	"Compare estas duas exportações, faça miniaturas e sinalize problemas visuais ou de áudio."
Automação em lote	"Converta esta pasta de clipes para MP4 pronto para web com loudness consistente."
Vídeo criado por código	"Crie um esqueleto de composição Hyperframes, inspecione-o, renderize-o e adicione legendas e marca d'água."
Reutilização local	"Transforme este clipe master em ativos Shorts, Reels, TikTok e YouTube com miniaturas e um manifesto."
Resgate de vídeo	"Diagnostique este clipe danificado, proponha apenas reparos seguros, renderize um pacote aprovado e verifique o recibo."
Revisão governada (dev tip)	"Ingira esta exportação em um projeto, execute inspeção de pré-verificação e temporal, escreva um veredito e salve apenas a região quebrada."

Ferramentas MCP

On the published 1.14.1 surface (and matching tip), kino registers 196 MCP tools and 167 CLI commands. The table summarizes core categories — search_tools discovers the exact operation without loading every description.

Categoria	Contagem	Destaques
Edição de vídeo principal	32	cortar, mesclar, redimensionar, recortar, girar, converter, sobreposições, legendas, exportar, limpeza, modelos, proteções de compatibilidade de mesclagem
Inspeção com respaldo de projeto	3	ingestão endereçada por conteúdo, pré-verificação unificada, pacotes de evidência temporal
Vídeo IA governado	4	veredictos de ativos exatos, avaliação de aceitação, trocas de corpo com preservação de áudio, recuperação vinculada à linhagem
Mecanismo de fluxo de trabalho para agentes	4	validar, planejar, renderizar, retomar, inspecionar trabalhos de múltiplas etapas com recibos de procedência
Resgate dedicado	3	diagnosticar, aprovar, renderizar, verificar, quarentenar e retomar reparos locais com preservação de conteúdo
Planejamento pós-resgate	8	linhas do tempo/consultas semânticas, EDLs, transformações visuais, restauração, composição, piloto automático, saída explícita
Criação cinematográfica	4	estrutura de projeto, análise de pacotes de estilo, análise de storyboard, expansão de prompts de cena
Mídia assistida por IA	11	transcrição, detecção de cenas, upscaling, separação de stems, remoção de silêncio, correção de cor
Hyperframes	18	init, preview, render, snapshots, inspect, catalog, website capture, TTS local, transcrição, remoção de fundo, diagnósticos, benchmark, pós-processamento
Reaproveitamento	2	manifestos de dry-run, variantes prontas para plataforma, miniaturas, storyboards, checkpoints de lançamento
Áudio procedural	7	sintetizar, compor, predefinições, efeitos, sequências, áudio gerado, áudio espacial, proteções de parâmetros de mixagem
Efeitos visuais	8	vinheta, brilho, ruído, scanlines, aberração cromática, luma key, máscara, máscara de forma, parâmetros de filtro limitados
Transições	3	glitch, morph, pixelizar
Layout e movimento	6	grade, picture-in-picture, tela dividida, texto animado, contadores, barras de progresso, capítulos automáticos, avisos de incompatibilidade de layout
Análise	8	detecção de cenas, miniatura, preview, storyboard, comparação de qualidade, metadados, forma de onda, checkpoint de lançamento
Análise de imagem	3	extrair cores, gerar paletas, analisar imagens de produto
Edição de still / plate	5	still-match, still-grade, still-gate, image-edit, still-package — correspondência de cor fixada com gate de coesão
Descoberta	1	`search_tools`

from kinocut import Client

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

Referência completa: docs/TOOLS.md

Fluxo de Trabalho Seguro para Agentes

Para agentes autônomos, o caminho pretendido é inspecionar, editar, verificar e, em seguida, pedir a um humano que revise os artefatos de lançamento:

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 segurança:

Chamadas que produzem mídia retornam resultados estruturados com caminhos de saída.
Caminhos de edição de alto risco agora executam proteções de pré-verificação antes da execução do FFmpeg: limites de filtro, compatibilidade de mesclagem, volume/tempo de mixagem de áudio, opacidade e similaridade de sobreposição/marca d'água/croma, tempo/estouro de texto animado e avisos de incompatibilidade de grade/tela dividida.
Chamadas de análise e descoberta retornam relatórios JSON estruturados.
A descoberta de ferramentas está disponível por meio de search_tools() e Client.inspect().
Erros inesperados de palavras-chave são convertidos em orientações acionáveis de MCPVideoError.
Não publique vídeo gerado por agente sem video_quality_check, video_release_checkpoint e inspeção visual/auditiva humana.
Para derivados de vídeo IA governado, exija identidades armazenadas, evidência ativa de decisão humana e um novo slot de revisão após cada recuperação ou troca de corpo — nunca soluções alternativas brutas com FFmpeg rotuladas como governadas.

Changelog

1.14.1 (2026-08-13):

Correção sobre a 1.14.0: pyright NoReturn em cancelamento de resgate para manter o GitHub Lint verde. Mesma superfície de 360 + performance.
mcp-video==1.6.10 instala o kinocut==1.14.1.

1.14.0 (2026-08-13):

Publicada a montagem dual-cam 360 a partir de um MP4 equiretangular costurado (agnóstico de câmera; não exclusivo do X4) via video_intent / Client.propose_360_assembly — ainda 196 MCP / 167 CLI.
Concluído o top-10 do comitê de performance: filter_complex 360 em passagem única (áudio preservado), QC amostrado, imports preguiçosos, cache SHA, stills de storyboard em lote.
mcp-video==1.6.9 instala o kinocut==1.14.0.

1.13.0 (2026-08-07):

Adicionadas superfície de verbo-intenção (video_intent / intent), piso de proteção Watching (video_review_run / video_review_decide), propostas de B-roll (video_propose_broll), tradução de legendas priorizando ES (video_translate_captions) e melhorias de qualidade de vida do Trusted execution (TE).
Superfície publicada expandida para 196 ferramentas MCP e 167 comandos CLI (totalmente sincronizados entre interfaces padrão, de teste e de cliente).
Validação de caminho reforçada para tradução de legendas, brand kit e exportações OTIO.

1.12.0 (2026-08-07):

Adicionada superfície de editor de still/plate (still-match, still-grade, still-gate, image-edit, still-package) com gate de coesão fail-closed.

1.11.x (2026-07-24):

Adicionados adaptadores finos de associação pública kinocut_sound S12 (sound-capabilities, sound-plan-validate, sound-mix-render, etc.).
Reforço de segurança pós-tema para evitar vazamentos de caminho absoluto do host e garantir que todas as operações descobertas tenham caminhos de invocação fail-closed.

Consulte CHANGELOG.md para obter as notas de versão históricas completas, ou veja a página GitHub Releases.

FAQ

O que é Kinocut?

Kinocut é um servidor MCP gratuito e de código aberto, uma biblioteca Python e uma CLI kino para edição de vídeo por agentes de IA. Ele envolve o FFmpeg (e extras opcionais do Hyperframes/Whisper) com proteções de pré-verificação, Video Receipts e checkpoints de qualidade. Antigamente era chamado de mcp-video.

Como instalo?

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

É gratuito e local-primeiro?

Sim. Apache-2.0, roda na sua máquina, não exige conta Kinocut ou chave de API para a superfície principal, e a mídia não é enviada para uma nuvem Kinocut.

Quais agentes funcionam com ele?

Qualquer cliente compatível com MCP que possa executar um servidor stdio local (Claude Code, Cursor, Windsurf, Cline e similares). Você também pode usar o cliente Python ou a CLI sem um agente.

Quantas ferramentas existem?

A 1.14.1 publicada documenta 196 ferramentas MCP / 167 comandos CLI. O tip de desenvolvimento mantém essas contagens. A montagem 360 reutiliza video_intent e video_review_decide — não é uma 197ª ferramenta MCP.

O Kinocut pode editar vídeo 360 da Insta360 X4?

Sim — a partir de um MP4 360 costurado, não .insv. Proponha um 360_assembly_plan, aprove-o e renderize split/switch/PiP/única. Funciona também para outras câmeras equiretangulares costuradas. Consulte docs/360_ASSEMBLY.md.

Era chamado de mcp-video?

Sim. mcp-video==1.6.10 instala o kinocut==1.14.1. Imports de compatibilidade, nome da CLI, variáveis de ambiente, diretório de dados, URIs de recursos e chaves de recibos continuam suportados na linha 1.14.x.

Mais respostas: docs/faq.md · FAQ no site: kinocut.dev/#faq

Documentação

Testes

A verificação de desenvolvimento está em docs/TESTING.md. Mantenha as verificações de superfície pública, fluxo de trabalho de mídia e segurança atualizadas ao alterar o comportamento das ferramentas.

Desenvolvimento

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"

Comunidade

Implantações da comunidade

Operadores que desejam uma URL MCP pública sem abrir portas do roteador doméstico podem estudar a pilha de referência comunitária Apache-2.0 que coloca Kinocut + Hyperframes atrás de Tailscale Funnel, Caddy e Google OAuth (mcp-auth-proxy): hyperframes-selfhost (não afiliado à KyaniteLabs; avalie a segurança conforme seu modelo de ameaça).

Licença

Apache 2.0. Consulte LICENSE.

Construído com FFmpeg, Hyperframes e o Model Context Protocol.

Parte da KyaniteLabs

Mais da KyaniteLabs. Projetos relacionados:

Epoch — servidor MCP de estimativa de tempo (PERT) para agentes de IA
DialectOS — servidor MCP e CLI de localização de dialetos de espanhol
checkyourself — verificações de prontidão para produção local-primeiro para código construído por IA

→ Mais em kyanitelabs.tech

Se o Kinocut for útil para você, marque com estrela ou acompanhe-o — isso ajuda outros construtores de agentes a encontrá-lo.

Construído por Simon Gonzalez De Cruz — disponível para engenharia Forward-Deployed / Applied-AI e trabalho contratual pelos links públicos de perfil acima.

O que é Kinocut?

Kinocut é um servidor MCP e CLI de edição de vídeo com proteções para agentes de IA que ajuda construtores de agentes de IA, usuários do Claude Code/Cursor e operadores de mídia local a editar, legendar, reaproveitar e controlar qualidade de vídeo com ferramentas FFmpeg tipadas.


Produto	Kinocut
Categoria	servidor MCP e CLI de edição de vídeo com proteções para agentes de IA
Melhor para	construtores de agentes de IA, usuários do Claude Code/Cursor e operadores de mídia local
Não é	um editor de nuvem hospedado ou shell FFmpeg não tipado
Origem	GitHub · Forgejo
Palavras-chave	MCP de edição de vídeo, vídeo para agentes de IA, FFmpeg MCP, Shorts Reels, montagem 360 Insta360

Para quem é

Principal: construtores de agentes de IA, usuários do Claude Code/Cursor e operadores de mídia local
Use quando precisar editar, legendar, reaproveitar e controlar qualidade de vídeo com ferramentas FFmpeg tipadas
Pule se precisar de um editor de nuvem hospedado ou shell FFmpeg não tipado

FAQ

O que é Kinocut?

Kinocut é um servidor MCP e CLI de edição de vídeo com proteções para agentes de IA. Ele ajuda construtores de agentes de IA, usuários do Claude Code/Cursor e operadores de mídia local a editar, legendar, reaproveitar e controlar qualidade de vídeo com ferramentas FFmpeg tipadas.

Quem deve usar o Kinocut?

Construtores de agentes de IA, usuários do Claude Code/Cursor e operadores de mídia local.

Como o Kinocut é diferente?

Ao contrário de scripts FFmpeg brutos ou shells de agentes sem proteção, o Kinocut valida ferramentas e emite recibos.

O Kinocut é software de produção?

Trate o status do README e as tags de lançamento como fonte de verdade para maturidade. Valide contra seus próprios requisitos antes do uso em produção.

O Kinocut pode transformar um arquivo da Insta360 X4 em uma edição de duas câmeras?

Sim: exporte um MP4 360 costurado e depois proponha → aprove → renderize. .insv é rejeitado. Isso está no pacote publicado 1.14.1.

Status

Mantido em 2026 no branch padrão
Prefira tags de lançamento ao fixar dependências
Reporte issues no repositório canônico listado acima

Superfície do agente

Agentes de codificação: leiam este README primeiro, depois docs/AGENTS.md do repositório, se presente
Prefira briefs legíveis por máquina (llms.txt) quando o repositório os fornecer
Pontos de entrada de MCP ou skill são documentados no repositório, quando aplicável

Contribuindo

Issues e PRs são bem-vindos no remoto canônico. Mantenha a documentação pública livre de segredos e caminhos locais de máquina.

Licença

Consulte LICENSE neste repositório (ou metadados do pacote, se a licença for apenas de pacote).