Limpeza de Sobreposições em Vídeo

Repositório: https://github.com/hyuuuliu/video-overlay-cleanup-skill

Visão Geral

Use esta skill para transformar um vídeo bruto ou gravação de tela em uma versão mais limpa com menos sobreposições visíveis.

Esta skill é uma skill de fluxo de trabalho, não uma alegação de recuperação mágica da verdade fundamental. Ela é melhor para:

sobreposições fixas em posições estáveis
banners de curta duração ou UI flutuante com uma máscara conhecida
limpar gravações de tela para edição ou redistribuição
preparar um trabalho de restauração quadro a quadro para o Gemini Nano Banana 2

Esta skill deve enquadrar a tarefa como limpeza de vídeo ou remoção de sobreposição, não como restauração fática garantida de conteúdo oculto.

Suporte a Provedores

Esta versão suporta um provedor de modelo real para reparo gerador de quadros:

Gemini Nano Banana 2 via API de geração e edição de imagens do Gemini

Antes de usar o modo gemini-nano-banana, o usuário deve configurar uma chave de API:

export GEMINI_API_KEY='sua_chave_api_aqui'

Substituição opcional de modelo:

export GEMINI_MODEL='gemini-3.1-flash-image-preview'
export GEMINI_IMAGE_SIZE='1K'

Requisitos de Execução

Declare-os explicitamente ao instalar ou revisar a skill:

binários necessários:
- bash
- ffmpeg
- ffprobe
- python3
credencial necessária para o modo Gemini:
- GEMINI_API_KEY
variáveis de ambiente opcionais do Gemini:
- GEMINI_MODEL
- GEMINI_IMAGE_SIZE
pacotes Python necessários para o modo Gemini:
- google-genai
- Pillow

Leia references/gemini-provider.md quando o usuário quiser o caminho do Gemini.

Solicitações Mais Adequadas

Use esta skill quando o usuário pedir qualquer um dos seguintes:

remover uma barra de status, barra superior, barra inferior, faixa de legenda, marca d'água ou controle flutuante de um vídeo
limpar uma gravação de tela de celular antes de reutilizar ou recortar
dividir um vídeo em quadros, reparar regiões mascaradas e remontá-lo
preparar um pipeline FFmpeg repetível para remoção de sobreposições em vídeo
usar o Gemini Nano Banana 2 para reparar uma região de sobreposição mascarada quadro a quadro
gerar máscaras ou especificações de região para áreas de sobreposição conhecidas

Estratégia Padrão

Escolha o caminho mais leve que possa funcionar:

Sobreposição fixa, região estável: use ffmpeg com uma máscara gerada e removelogo
Região fixa, mas a qualidade do removelogo não é suficiente: extraia quadros e execute o Gemini Nano Banana 2 na área mascarada
Sobreposição dinâmica: extraia quadros, crie ou propague máscaras, execute o Gemini Nano Banana 2 e depois remonte o vídeo

Não padronize para edição geradora de quadro completo quando um método de região fixa ou determinístico for suficiente.

Fluxo de Trabalho

1. Classifique a sobreposição

Decida qual destes casos se aplica:

sobreposição-fixa-na-borda: barra de status superior, barra de navegação inferior, faixa de legenda, logotipo de canto
sobreposição-fixa-em-caixa: marca d'água estável ou widget flutuante em uma área
sobreposição-dinâmica: banner de notificação, adesivo em movimento, controle flutuante transitório
desconhecido: o usuário ainda não forneceu detalhes suficientes para definir uma máscara

Se a localização da sobreposição não estiver clara, peça o menor detalhe faltante necessário ou proponha uma primeira máscara razoável e rotule-a como rascunho.

2. Escolha o caminho

Para sobreposição-fixa-na-borda ou sobreposição-fixa-em-caixa, prefira os scripts integrados:

scripts/make_mask.py
scripts/clean_video.sh --mode removelogo

Para fluxos de trabalho baseados em Gemini, use:

scripts/clean_video.sh --mode gemini-nano-banana
scripts/gemini_nano_banana_edit.py

Para fluxos de trabalho de baixo nível ou com provedor personalizado, use:

scripts/extract_frames.sh
scripts/restore_frames.py
scripts/rebuild_video.sh

Leia references/pipeline.md para o fluxo de ponta a ponta, references/mask-strategies.md para orientação sobre design de máscaras, e references/gemini-provider.md para comportamento específico do Gemini.

3. Construa a máscara cuidadosamente

As máscaras determinam o sucesso. Mantenha estas regras:

Máscara apenas a sobreposição, não o quadro inteiro
Prefira uma máscara ligeiramente apertada a uma superdimensionada
Para barras fixas, use predefinições ou regiões baseadas em porcentagem
Para sobreposições dinâmicas, mantenha o escopo da edição do quadro local e explícito

O formato de região usado por esta skill é x:y:w:h. Cada valor pode ser pixels como 120 ou uma porcentagem como 8%.

Exemplos:

Topo 7 por cento: 0:0:100%:7%
Faixa inferior: 0:92%:100%:8%
Marca d'água de canto: 78%:3%:18%:12%

4. Execute o caminho de limpeza

Caminho rápido para sobreposição fixa

Use quando a sobreposição permanece no mesmo lugar.

bash scripts/clean_video.sh \
  --input /caminho/abs/entrada.mp4 \
  --output /caminho/abs/saida.mp4 \
  --mode removelogo \
  --region '0:0:100%:7%'

Você também pode adicionar predefinições:

bash scripts/clean_video.sh \
  --input /caminho/abs/entrada.mp4 \
  --output /caminho/abs/saida.mp4 \
  --mode removelogo \
  --preset iphone-status-bar

Caminho Gemini Nano Banana 2

Use quando o usuário quiser restauração mascarada por quadro.

export GEMINI_API_KEY='sua_chave_api_aqui'

bash scripts/clean_video.sh \
  --input /caminho/abs/entrada.mp4 \
  --output /caminho/abs/saida.mp4 \
  --mode gemini-nano-banana \
  --region '0:0:100%:12%' \
  --image-size 1K

Substituição opcional de modelo:

bash scripts/clean_video.sh \
  --input /caminho/abs/entrada.mp4 \
  --output /caminho/abs/saida.mp4 \
  --mode gemini-nano-banana \
  --region '0:0:100%:12%' \
  --model gemini-3.1-flash-image-preview \
  --image-size 2K

Caminho de edição de quadro personalizado

Use apenas quando o usuário quiser explicitamente um comando de editor personalizado em vez do Gemini.

bash scripts/clean_video.sh \
  --input /caminho/abs/entrada.mp4 \
  --output /caminho/abs/saida.mp4 \
  --mode frame-edit \
  --region '0:0:100%:12%' \
  --editor-cmd 'meu-editor --input {input} --mask {mask} --output {output}'

O comando do editor recebe:

{input}: caminho do quadro de origem
{mask}: caminho da máscara
{output}: caminho do quadro de destino
{index}: número do quadro baseado em zero

5. Seja explícito sobre os limites

Sempre observe quando uma destas condições for verdadeira:

o conteúdo oculto nunca foi visível em nenhum quadro
o resultado é uma reconstrução visual, não uma recuperação factual
a sobreposição é dinâmica e a máscara é aproximada
edições quadro a quadro podem precisar de estabilização temporal além desta primeira passagem
o Gemini pode variar ligeiramente de quadro para quadro, especialmente em regiões mascaradas grandes
o modo Gemini agora relata contagem de quadros, estimativa de custo base e progresso cumulativo de tokens/gastos durante a execução
o modo Gemini agora preserva todos os pixels não mascarados do quadro original no momento da gravação, de modo que apenas as regiões mascaradas são adotadas da saída do modelo

Limitações Conhecidas

Mantenha a declaração de risco simples:

áreas mascaradas ou cobertas não são restauradas de forma confiável todas as vezes
o resultado é uma limpeza visual plausível, não uma recuperação verdadeira garantida
o processamento do Gemini pode ser caro, especialmente em vídeos mais longos ou com contagens de quadros maiores

Notas de Confiabilidade Atuais

A implementação atual do Gemini usa várias salvaguardas:

estimativa de orçamento antes do início do processamento
relatório cumulativo de tokens e gastos durante o processamento
validação e repetição por quadro
repetição em nível de solicitação para erros transitórios do provedor
composição mascarada que mantém todos os pixels não mascarados do quadro original

Essa última salvaguarda é importante: se o modelo editar o hamster, a gaiola ou outro conteúdo da cena visível fora da máscara branca, a saída salva ainda mantém os pixels originais não mascarados. Isso melhora a estabilidade visual, mas também significa que todas as edições úteis devem acontecer dentro da máscara fornecida.

Expectativas de Saída

Um bom resultado inclui:

o caminho do vídeo limpo
o método escolhido: removelogo, gemini-nano-banana ou frame-edit
a máscara exata ou predefinições usadas
se GEMINI_API_KEY foi necessária
a contagem de quadros que o modo Gemini planejava processar
o gasto base estimado antes das chamadas do Gemini começarem
o resumo cumulativo de tokens e gastos relatado durante o processamento
quaisquer ressalvas importantes sobre realismo, consistência ou artefatos residuais

Quando útil, também mantenha o diretório de trabalho para que o usuário possa inspecionar:

quadros extraídos
arquivos de máscara gerados
vídeo intermediário reconstruído
manifesto do trabalho

Padrão de Qualidade

Prefira uma limpeza estável e repetível a edições ambiciosas, mas ruidosas
Evite editar partes não tocadas do quadro
Use caminhos FFmpeg determinísticos primeiro
Trate a edição geradora como um fallback direcionado, não o padrão
Separe com aparência mais limpa de factualmente restaurado
Lembre o usuário quando uma chave de API do provedor for necessária

Padrões de Prompt

Boas invocações:

"Use $video-overlay-cleanup para remover a barra de status superior desta gravação de tela."
"Use $video-overlay-cleanup com Gemini Nano Banana 2 para limpar o banner superior deste vídeo."
"Use $video-overlay-cleanup para dividir este vídeo em quadros, limpar a sobreposição flutuante e remontá-lo."

Para detalhes de implementação, carregue:

hyuuuliu/limpeza-de-sobreposicoes-em-video

O que é limpeza-de-sobreposicoes-em-video?

Perguntar na sua IA favorita

Documentação