Comparador de Vídeos
Visão Geral
Compare dois vídeos e gere um relatório HTML interativo analisando os resultados da compressão. O script extrai metadados dos vídeos, calcula métricas de qualidade (PSNR, SSIM) e cria comparações visuais quadro a quadro com três modos de visualização: controle deslizante, lado a lado e grade.
Quando Usar Esta Habilidade
Use esta habilidade quando:
- Comparar vídeos original e comprimido
- Analisar a qualidade e eficiência da compressão de vídeo
- Avaliar o desempenho de codecs ou o impacto da redução de bitrate
- Usuários mencionarem "comparar vídeos", "qualidade de vídeo", "análise de compressão" ou "antes/depois da compressão"
Uso Principal
Comando Básico
python3 scripts/compare.py original.mp4 compressed.mp4
Gera comparison.html com:
- Parâmetros do vídeo (codec, resolução, bitrate, duração, tamanho do arquivo)
- Métricas de qualidade (PSNR, SSIM, porcentagens de redução de tamanho/bitrate)
- Comparação quadro a quadro (padrão: quadros a cada 5 segundos)
Opções de Comando
# Arquivo de saída personalizado
python3 scripts/compare.py original.mp4 compressed.mp4 -o report.html
# Intervalo de quadros personalizado (maior = menos quadros, processamento mais rápido)
python3 scripts/compare.py original.mp4 compressed.mp4 --interval 10
# Comparação em lote
for original in originals/*.mp4; do
compressed="compressed/$(basename "$original")"
output="reports/$(basename "$original" .mp4).html"
python3 scripts/compare.py "$original" "$compressed" -o "$output"
done
Requisitos
Dependências do Sistema
FFmpeg e FFprobe (necessários para análise de vídeo e extração de quadros):
# macOS
brew install ffmpeg
# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg
# Windows
# Baixe de https://ffmpeg.org/download.html
# Ou use: winget install ffmpeg
Python 3.8+ (usa type hints, f-strings, pathlib)
Especificações de Vídeo
- Formatos suportados:
.mp4(recomendado),.mov,.avi,.mkv,.webm - Limite de tamanho de arquivo: 500MB por vídeo (configurável)
- Tempo de processamento: ~1-2 minutos para vídeos típicos; varia conforme duração e intervalo de quadros
Comportamento do Script
Validação Automática
O script valida automaticamente:
- Instalação e disponibilidade do FFmpeg/FFprobe
- Existência do arquivo, extensões e limites de tamanho
- Segurança do caminho (previne directory traversal)
Mensagens de erro claras com orientações de resolução aparecem quando a validação falha.
Métricas de Qualidade
O script calcula duas métricas de qualidade padrão:
PSNR (Peak Signal-to-Noise Ratio): Medição de similaridade em nível de pixel (escala de 20-50 dB, quanto maior, melhor)
SSIM (Structural Similarity Index): Medição de similaridade perceptual (escala de 0.0-1.0, quanto maior, melhor)
Para escalas de interpretação detalhadas e limites de qualidade, consulte references/video_metrics.md.
Extração de Quadros
O script extrai quadros em intervalos especificados (padrão: 5 segundos), redimensiona-os para altura consistente (800px) para comparação e incorpora-os como URLs de dados base64 em HTML autocontido. Arquivos temporários são automaticamente limpos após o processamento.
Relatório de Saída
O relatório HTML gerado inclui:
- Modo Controle Deslizante: Arraste para revelar original vs comprimido (padrão)
- Modo Lado a Lado: Exibição simultânea para comparação direta
- Modo Grade: Layout compacto de 2 colunas
- Controles de Zoom: Magnificação de 50%-200%
- Formato autocontido (não requer servidor, funciona offline)
Detalhes de Implementação Importantes
Segurança
O script implementa:
- Validação de caminho (caminhos absolutos, previne directory traversal)
- Prevenção de injeção de comandos (sem
shell=True, argumentos validados) - Limites de recursos (tamanho de arquivo, timeouts)
- Exceções personalizadas:
ValidationError,FFmpegError,VideoComparisonError
Cenários de Erro Comuns
"FFmpeg não encontrado": Instale o FFmpeg via gerenciador de pacotes da plataforma (consulte a seção Requisitos)
"Arquivo muito grande": Comprima os vídeos antes da comparação, ou ajuste MAX_FILE_SIZE_MB em scripts/compare.py
"Operação expirou": Aumente a constante FFMPEG_TIMEOUT ou use um valor maior para --interval (processa menos quadros)
"Incompatibilidade na contagem de quadros": Os vídeos têm durações/taxas de quadros diferentes; o script truncará automaticamente para a contagem mínima de quadros e exibirá um aviso
Configuração
O script inclui constantes ajustáveis para limites de tamanho de arquivo, timeouts, dimensões de quadros e intervalos de extração. Para personalizar o comportamento, edite as constantes no topo de scripts/compare.py. Para opções de configuração detalhadas e seus impactos, consulte references/configuration.md.
Materiais de Referência
Consulte estes arquivos para informações detalhadas:
references/video_metrics.md: Interpretação de métricas de qualidade (escalas de PSNR/SSIM, alvos de compressão, diretrizes de bitrate)references/ffmpeg_commands.md: Referência de comandos FFmpeg (extração de metadados, extração de quadros, solução de problemas)references/configuration.md: Opções de configuração do script e constantes ajustáveisassets/template.html: Modelo de relatório HTML para personalizar modos de visualização e estilo