sf-ryanyan/fullgrade

O que fullgrade faz?

Correção automática e suave de cor para vídeo. Tudo roda localmente com ffmpeg + Python; sem GPU, sem API em nuvem, quase nenhum token (a análise é feita pelo script, não olhando para os quadros).

Idioma: responda no idioma do usuário. Se o usuário escrever em português, use os comandos com --lang pt para que o relatório e as imagens de comparação estejam em português; caso contrário, use --lang en.

1. Ambiente (primeira execução, ou quando algo falha)

python3 <skill_dir>/scripts/fullgrade.py --check

Se algo estiver faltando, informe ao usuário o comando necessário:

Ausente	macOS	Windows	Linux
ffmpeg	brew install ffmpeg	winget install ffmpeg	sudo apt install ffmpeg
numpy / Pillow	python3 -m pip install numpy pillow (adicione --break-system-packages se o pip recusar)
recorte inteligente facial (opcional)	python3 -m pip install opencv-python-headless

Execute o script na máquina onde os vídeos estão. Se os arquivos foram carregados em um sandbox, execute-o lá e envie as saídas de volta. No Windows, use python em vez de python3 se python3 não for encontrado.

Opcional: python3 <skill_dir>/scripts/fullgrade.py --selftest cria filmagens sintéticas e verifica todos os recursos (cerca de 2–3 minutos). Use se o usuário perguntar "funciona no meu computador?".

2. Transforme a solicitação em um comando

python3 <skill_dir>/scripts/fullgrade.py <arquivos-ou-pastas> [opções] --lang <pt|en>

O usuário diz…	Opção
nada sobre estilo / "só corrigir" / natural	--preset natural (padrão)
imobiliário, interior, claro e arejado	--preset real-estate
quente, aconchegante, anoitecer	--preset warm
vívido, comida, produto	--preset vivid
limpo, frio, moderno, tecnologia	--preset cool-modern
cinematográfico, look de filme, vlog	--preset cinematic
vertical, TikTok, Reels, Shorts	--ratio 9:16
YouTube, paisagem / horizontal	--ratio 16:9
quadrado / feed do Instagram	--ratio 1:1 ou --ratio 4:5
preencher a tela, sem barras	--fit crop
manter a imagem inteira / não cortar, preencher bordas	--fit blur
barras pretas / brancas	--fit color --pad-color black (ou white)
drone / DJI D-Log	--log dlog
Sony S-Log3 / Panasonic V-Log / iPhone Apple Log	--log slog3 / --log vlog / --log applelog
fazer tudo combinar com este clipe / foto	--match <arquivo> (--match-method mkl padrão; reinhard, hist)
fazer todos os clipes combinarem entre si	--match hero
toque mais suave / não exagerar	--strength 0.6
exportação mais rápida	--fast (codificador de hardware Apple / NVIDIA / Intel, fallback automático)
melhor qualidade	--quality best
incluir subpastas	--recursive
apenas verificar, sem exportar	--analyze-only
uma graduação para o arquivo inteiro	--no-split
arquivos LUT para Premiere / DaVinci / Final Cut / CapCut	aponte para <skill_dir>/luts/ (ou --export-luts <pasta>)

Padrões que já funcionam para a maioria: --fit auto (corta se mantiver ≥60% da imagem, caso contrário fundo desfocado — então 16:9 ↔ 9:16 usa fundo desfocado a menos que o usuário peça para cortar), --dynamic auto, --denoise auto.

Não pergunte sobre a proporção a menos que o usuário a mencione — mantenha a original. Pergunte apenas quando a solicitação for realmente ambígua (por exemplo, ele diz "LOG" mas não qual câmera).

3. O que acontece (explique brevemente apenas se perguntado)

1. iPhone HDR → SDR automaticamente; LOG decodificado quando --log é fornecido (o script avisa quando um clipe parece ser LOG).
2. Uma edição finalizada é dividida em cenas (detecção de cena); cada cena é graduada individualmente.
3. Por cena: balanço de branco → níveis de preto/branco (realces protegidos) → exposição dentro de uma faixa confortável → contraste → saturação → preset visual → opcionalmente combinação (match). Tudo consolidado em um LUT 3D por cena com limites de segurança, para nunca exagerar.
4. O brilho que varia dentro de uma cena (andar de um corredor escuro para uma sala clara) é suavizado (exposição dinâmica). Cenas com brilho elevado recebem leve redução de ruído.
5. O redimensionamento nunca estica; o recorte inteligente segue rostos (se OpenCV estiver instalado) ou a área mais detalhada.
6. Um clipe que já parece correto é copiado sem recompressão.

Velocidade: o processamento leva cerca de 1–3× a duração do vídeo para 1080p (4K leva mais tempo). Para arquivos longos ou muitos, informe ao usuário que está rodando e aguarde; não cancele. Use --fast se estiver com pressa.

Código de saída: 0 = tudo concluído · 2 = alguns arquivos falharam (outros estão ok — o final da saída lista Feito: X OK, Y falharam e o relatório mostra o motivo) · 1 = nada pôde ser processado. Sempre informe ao usuário quais arquivos falharam e por quê (causas comuns: não é um vídeo, arquivo danificado, arquivo apenas de áudio).

4. Saídas

• Vídeos: <pasta de entrada>/_graded/<nome>_<preset>[_9x16].mp4 — nunca sobrescreve (adiciona _v2), originais intactos.
• _graded/compare/*_compare.jpg — imagens de antes/depois. Sempre mostre pelo menos uma ao usuário.
• _graded/fullgrade_report.html — controles deslizantes antes/depois, números e escopos para cada cena. Ofereça-o.
• _graded/fullgrade_report.md — os mesmos números em texto; leia para escrever seu resumo.

5. Resposta

Breve resumo no idioma do usuário: quantos vídeos, qual preset/proporção, onde estão os arquivos, uma ou duas frases sobre o que mudou (do relatório, por exemplo "a cena 2 estava muito amarelada e agora está neutra; os realces da janela foram protegidos"), a(s) imagem(ns) de comparação e um próximo passo útil (outro preset, uma versão 9:16, --strength se quiser mais suave).

Limitações honestas

• Janelas/céus totalmente estourados (branco puro) não podem ser recuperados; o resto da imagem ainda é melhorado.
• Filmagens muito escuras mostram ruído quando clareadas (redução de ruído leve ajuda, não é mágica).
• Luz mista em uma cena (lâmpada laranja + luz do dia azul) é equilibrada como um compromisso.
• Dissolvências entre duas cenas muito diferentes podem mostrar um pequeno degrau no corte.
• DJI D-Log M e outras curvas LOG não listadas não são suportadas na V1 — gradue-as sem --log e use --strength.