KyaniteLabs/kinocut

O que kinocut faz?

Use Kinocut quando um agente precisar de uma superfície de edição de vídeo estruturada em vez de escrever comandos FFmpeg manualmente. Ele expõe ferramentas MCP, um cliente Python e uma CLI para edição, análise, legendas, áudio, Hyperframes, composição em camadas e fluxos de trabalho de reaproveitamento local.

Caminho padrão (faça isso primeiro)

1. kino doctor depois kino --format json info <arquivo>.
2. Para uma tarefa desconhecida, chame search_tools com a tarefa do usuário (por exemplo, "remover palavras de preenchimento" ou "manter rosto no quadro") e inspecione as entradas necessárias da ferramenta retornada. Planeje com video_intent para intenções suportadas (goal= opcional compila um cutfile; uma meta 360/mesa/x4 também propõe um 360_assembly_plan). Verifique se a proposta realmente atende à solicitação antes de renderizar.
3. Renderize (video_cutfile_render, video_edit, fluxo de trabalho ou uma única ferramenta de engine). Para 360: video_review_decide aprove/rejeite esse plano, depois renderize — nunca renderize um plano proposed. .insv é rejeitado; precisa de um MP4 360 costurado. Guia: docs/360_ASSEMBLY.md.
4. video-quality-check / assert_quality. Sincronize repurpose e shorts-package falham fechados na pontuação 80, a menos que ignorados/allow_fail.
5. Revisão visual/áudio humana. Nunca trate um recibo como publicado.

Profundidade (resgate, salvamento, composição, Hyperframes, som fino S12): docs/TOOLS.md, docs/RESCUE.md, docs/WORKFLOWS.md. Lista de permissão de fluxo de trabalho: probe, trim, resize, convert, crop, add_text, merge, composite_layers, burn_in.

Carregue o guia relevante quando necessário. Use evidências de fonte para escolhas editoriais; preserve nomes, números, negações e qualificações. Relate evidências ausentes ou ações não suportadas em vez de inventar alegações, carimbos de data/hora ou capacidades. Uma ferramenta de planejamento propõe uma edição; sua existência não significa que o detector ou modelo necessário foi executado. O código possui tempo, transformações, validação e execução; a revisão humana permanece separada do julgamento do modelo.

Fluxo de código-vídeo local Revideo (dica de desenvolvimento)

Use revideo_materialize, revideo_install e revideo_render quando o chamador precisar de um projeto encenado inspecionável. Use revideo_render_job para as mesmas etapas protegidas em uma chamada. Uma cena fornecida é TypeScript executável confiável: inspecione-a antes de usar e nunca execute código de cena não confiável. A instalação de dependências pode acessar o npm; a renderização é executada localmente contra o modelo fixado do Kinocut. O recibo de renderização vincula a mídia observada e os bytes de saída ao resumo exato do arquivo de trabalho em disco delimitado. .mp4, .webm e .mov selecionam modos de exportação MP4, WebM e ProRes 4444 fixados e são verificados antes da publicação. Verifique o recibo contra os bytes de saída, execute video_quality_check e video_release_checkpoint, então exija revisão visual humana.

Comece Aqui

• Leia ../../README.md para instalação e o contrato de segurança.
• Execute kino doctor antes de FFmpeg / Hyperframes / extras de IA.

Escolha Uma Superfície

• MCP: melhor para Claude Code, Cursor, clientes estilo Codex e outros hosts de agente. Configure uvx --from kinocut kino.
• CLI: melhor para edições locais diretas, diagnósticos rápidos, composite-layers --dry-run, trabalhos em lote e saída JSON amigável para CI.
• Cliente Python: melhor para pipelines repetíveis que precisam de resultados estruturados, caminhos de saída e recibos de plano de camada salvos.

Montagem de câmera dupla 360 (publicado 1.14.0)

Use quando a fonte for um MP4 360 equirretangular costurado de qualquer câmera (Insta360, Ricoh Theta, GoPro MAX, DJI Osmo 360, …) e o pedido for duas câmeras virtuais como dividir/alternar/PiP/único.

1. video_intent(verb="reformat_vertical", goal="desk 360 split 9:16", source=ABS_PATH) ou Client.propose_360_assembly(...).
2. Mostre câmeras, layout e stills de storyboard. Não invente yaw/pitch.
3. video_review_decide / Client.decide_360_assembly com approve ou reject.
4. Renderize apenas um plano aprovado (Client.render_360_assembly ou video_review_decide + output_path).

Não há ferramenta MCP video_360_* e nenhum comando kino 360. CLI intent e review-decide não executam este compilador. Hooks de diretor aceitam um proponente JSON injetado; um nome de modelo configurado sozinho não executa um modelo. Propostas em nuvem exigem allow_cloud; diretores nunca escrevem pixels.

Matte de produto/objeto (publicado em 1.15.1; atual em 1.15.3)

O extra opcional de matte de objeto está disponível no 1.15.3 publicado. Use o comando existente hyperframes-remove-background / hyperframes_remove_background. O modelo padrão é pessoas. Para SKUs de catálogo, joias, garrafas, sapatos, embalagens ou qualquer coisa que não seja uma pessoa:

1. hyperframes_remove_background(info=true) — lista modelos, sem download.
2. pip install "kinocut[object-matte]" então model="birefnet-general".
3. Opcional --mask-interval 3 em vídeo de produto. Sobreposição de equipamento opcional para sobras de toca-discos/suporte/tripé/varredura.
4. Componha em uma placa de loja com composite-layers. Mantenha cada src dentro do diretório de especificação.

Não invente video_product_matte; esta não é uma nova ferramenta MCP. Não recorra ao modelo de pessoas quando o extra de objeto estiver faltando. Guia: docs/PRODUCT_MATTE.md. Exemplo: examples/product-matte/.

Resgate Dedicado de Vídeo

Use video_rescue_*, rescue-* ou Client.rescue_* quando a solicitação for corrigir um clipe local preservando sua fonte, história e linha do tempo.

Sequência necessária:

1. Chame o plano e salve o artefato do plano.
2. Apresente safe_repairs, recommendations, unavailable_repairs, blocked_repairs, prévias, intenções de pacote, capacidades e estimativa ao usuário.
3. Inspecione o plano antes de renderizar. Obtenha ou infira aprovação explícita apenas para IDs em safe_repairs; omitir a lista de IDs significa que todos os IDs seguros no plano revisado.
4. Chame a renderização com exatamente esses IDs seguros aprovados.
5. Inspecione o recibo de renderização, então relate caminhos de pacote, sidecars indisponíveis, integridade, verificação de bloqueio, privacidade, retomada e estado de limpeza.

Nunca renderize diretamente de um plano não revisado. Nunca adicione IDs de recomendação, IDs indisponíveis ou IDs bloqueados à aprovação. Nunca use ferramentas em nuvem, queime legendas de resgate, reescreva a fonte ou trate unavailable como falha automática. Um cancelamento ou falha de verificação deve permanecer não promovido ou em quarentena.

Inspeção Determinística de Vídeo com IA

Use video_ingest, video_preflight e video_inspect_temporal (ou seus equivalentes CLI planos e Python) quando a filmagem gerada precisar de evidências antes de uma decisão de edição. Ingest primeiro, depois aborde o ativo pelo seu hash retornado. Nunca substitua esse ID de ativo por um caminho de host ou construa um AssetRecord no limite público. A inspeção temporal retorna o pacote completo de quadros amostrados e tiras de movimento, descobertas determinísticas e capacidades explícitas de provedor indisponível. A ausência de provedor é esperada e não deve acionar um download ou um fallback de rede.

Revisão e Salvamento Governados de Vídeo com IA

Use video_verdict, video_acceptance_eval, video_body_swap e video_salvage (ou seus equivalentes CLI planos e Python) para decisões editoriais exatas de ativos e recuperação derivada. Um veredito não aprovado pode capturar análise de agente, mas uma disposição aprovada deve vincular uma decisão humana exata e ativa com requisito, função e evidência de artefato explícitos. A avaliação de aceitação é derivada em vez de uma ação de aprovação, e cada saída de salvamento começa em um novo slot de revisão não aprovado.

Nunca invente um ID de decisão, passe uma aprovação não armazenada ou procure uma rota forçada/de substituição. Body swap rejeita incompatibilidade de duração, a menos que o chamador escolha uma política explícita. Salvamento requer um projeto privado existente, um ativo de fonte armazenado, uma política de receita limitada e um ID de especificação de aceitação exato.

A avaliação de aceitação recebe acceptance_spec_id e verdict_ids ativos armazenados, nunca objetos de evidência construídos pelo chamador. Body swap público sempre recebe project_dir primeiro e ambos os caminhos de fonte devem resolver para ativos ativos nesse projeto exato.

Leia docs/AI_VIDEO_REVIEW_AND_SALVAGE.md antes de operar este fluxo de trabalho. Trate cada derivado como novo trabalho não aprovado e mantenha a barreira explícita visual/áudio humana antes da publicação.

Planejamento Pós-Resgate

Use a ferramenta MCP video_* correspondente, comando CLI plano ou método Client quando a solicitação precisar de recuperação semântica, edições de limpeza comuns, transformações conscientes do assunto, restauração, composição, coordenação criativa ou saída remota. Passe evidências e intenção compatíveis com JSON; apresente o plano retornado e o diff antes de qualquer etapa de renderização separada.

Nunca invente descrições de fonte, esconda incerteza, infira aprovação de um plano ou trate a falta de um executor local como permissão para usar um provedor em nuvem. O trabalho remoto requer um manifesto de saída separado e aprovação. Um planejador que carece de evidências ou capacidade deve se abster.

Composição em Camadas

Use composite-layers / video_composite_layers quando a edição for uma pilha ordenada de camadas de imagem, vídeo ou sólidas, especialmente terços inferiores, variantes picture-in-picture, placas de desfoque, máscaras/mattes ou variantes de layout específicas de plataforma.

Prefira este caminho em vez de filtergraphs FFmpeg brutos quando um agente precisar de transformações, opacidade, janelas de início/duração, fontes alfa de máscara/matte ou um recibo que possa ser revisado antes da publicação.

Fluxo de plano primeiro:

1. Escreva uma especificação JSON com canvas, layers ordenadas e saída explícita.
2. Execute kino composite-layers --spec layers.json --dry-run --save-layer-plan layer-plan.json.
3. Inspecione o plano de camada para hashes de fonte, hash de filtergraph, transformações, rotação/pivô, modos de mesclagem, janelas de tempo e máscaras.
4. Renderize apenas após o plano parecer correto.
5. Execute video-quality-check, storyboard ou thumbnail e video_release_checkpoint.

O compositor suporta modos de mesclagem de tela cheia e posicionados permitidos (multiply, screen, overlay, darken, lighten) com opacidade e janelas de tempo; recibos permanecem layer_plan v2. Mesclagens não normal suportam opacidade e janelas start/duration em duas geometrias: tela cheia em {0,0} sem dimensionamento explícito, ou um retângulo posicionado com width e height inteiros positivos e uma posição integral não negativa dentro da tela. A mesclagem RGB evita aplicar aritmética de cor a planos de croma subamostrados. Escala, rotação/pivô, máscara/matte, posições fracionárias e retângulos fora da tela permanecem adiados e falham fechados com unsupported_blend_geometry. Camadas de vídeo e máscaras de vídeo começam a reprodução em seu início declarado. Mantenha todas as fontes e máscaras dentro do diretório de especificação. A saída é apenas vídeo; anchor é um alias de posição distinto de pivot. Rotação + máscara, composição de áudio e adaptadores NLE completos permanecem adiados. Inspecione o recibo antes da revisão humana; não trate isso como uma substituição completa de NLE.

Motor de Fluxo de Trabalho do Agente

Quando a edição for um trabalho de várias etapas (não uma única chamada de ferramenta), use o motor de fluxo de trabalho para planejar, validar, renderizar, recuperar e provar a partir de uma especificação de trabalho JSON — através de video_workflow_* (MCP), workflow-* (CLI) ou Client.workflow_* (Python). As operações são uma pequena lista de permissão (probe | trim | resize | convert | crop | add_text | merge | composite_layers | burn_in) vinculada a engines verificados; referências de mídia são simbólicas (@sources.*, @work/*, @outputs.*) e confinadas ao espaço de trabalho; tudo falha fechado. Veja ../../docs/WORKFLOWS.md.

Planejar → validar → renderizar → inspecionar → retomar:

1. workflow-validate --spec job.json — barreira estrutural barata; não renderiza nada.
2. workflow-plan --spec job.json --save-plan plan.json — gráfico de operação dry-run + sondas/hashes de fonte; renderiza zero mídia.
3. workflow-render --spec job.json --save-receipt receipt.json — execute sequencialmente; emita um recibo de proveniência (hashes por etapa, manifesto de limpeza, advertência de determinismo). Adicione --all-variants para variantes em lote.
4. workflow-inspect --receipt receipt.json — re-verificação de integridade somente leitura + ponteiros de revisão humana antes de confiar em um recibo.
5. workflow-render --spec job.json --resume receipt.json — retome um trabalho que falhou com intermediários mantidos (falha fechada em uma especificação alterada).

Recibos armazenam apenas caminhos relativos ao espaço de trabalho — mantenha especificações e recibos de exemplo livres de caminhos pessoais, nomes de usuário e tokens.

Fluxo de Trabalho

1. Inspecione a entrada primeiro: kino info <arquivo> ou o equivalente MCP/Python.
2. Faça um plano de baixo risco: cortar, redimensionar, normalizar áudio, legendas, sobreposições, efeitos ou renderização Hyperframes.
3. Prefira prévias ou manifestos de dry-run antes de exportações caras ou destrutivas:
   • preview para revisão visual rápida.
   • repurpose-plan antes de repurpose.
   • Hyperframes inspect, snapshot ou still antes da renderização completa.
   • Para planos de shorts salvos: shorts-plan-show → shorts-review → shorts-render → shorts-package.
   • Para som fino: sound-capabilities então sound-plan-validate / sound-voice-batch / sound-mix-render / sound-qa-loudness / sound-qa-asr (ou kino sound <ação>).
   • Forneça valores numéricos para durações de som, ganhos, loudness e versões de perfil; booleanos são rejeitados antes da coerção. Planos inválidos explícitos não podem selecionar o plano de exemplo. Planos tipados são revalidados; veja docs/SOUND_INPUT_VALIDATION.md para regras de compatibilidade específicas de campo.
   • ASR real usa uma solicitação de áudio/referência hashada e raiz explícita; retenha seu ZIP de transcrição e relate discrepâncias honestamente. Apenas Whisper local em cache; sem downloads automáticos. Chamadas legadas apenas com hash são simulações. Veja docs/SOUND_ASR_REQUESTS.md.
   • Para QA de loudness PCM16 mono/estéreo real, forneça SoundLoudnessRequest mais raiz do projeto e inspecione within_tolerance; medição bem-sucedida pode ser não conforme. FFmpeg é necessário, e o fixture sem entrada é rotulado como demo. Veja docs/SOUND_LOUDNESS_REQUESTS.md.
   • Para masterização mono/estéreo retida, forneça SoundMasterRequest e raiz explícita para sound-master-render; veja docs/SOUND_MASTER_REQUESTS.md. Inspecione o ZIP verificado, o modo de normalização real e a conformidade de política final medida, depois ouça antes do lançamento. Os canais de entrada são preservados; a saída existente nunca é substituída.
   • Para ASR EN/ES local real, veja docs/SOUND_ASR_LOCAL.md; chame com SoundAsrRequest e raiz explícita, inspecione o ZIP de transcrição verificado contra os segmentos e relate quaisquer discrepâncias ou corrupção honestamente antes de usar. Veja também docs/SOUND_INPUT_VALIDATION.md e docs/SOUND_ASR_REQUESTS.md.