Video Comparer
Visão Geral
Compara dois vídeos e gera um relatório HTML interativo para analisar resultados de 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 taxa de bits
- 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, taxa de bits, duração, tamanho do arquivo)
- Métricas de qualidade (PSNR, SSIM, porcentagens de redução de tamanho/taxa de bits)
- Comparação quadro a quadro (padrão: quadros em intervalos de 5s)
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 dos arquivos, extensões e limites de tamanho
- Segurança de caminhos (impede traversal de diretórios)
Mensagens de erro claras com orientações de resolução são exibidas 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 a 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 uma altura consistente (800px) para comparação e os incorpora como URLs de dados base64 no 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: Ampliação de 50% a 200%
- Formato autocontido (não requer servidor, funciona offline)
Detalhes Importantes de Implementação
Segurança
O script implementa:
- Validação de caminhos (caminhos absolutos, impede traversal de diretórios)
- 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 excedeu o tempo limite": 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 trunca automaticamente para o número mínimo de quadros e exibe 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 início 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 PSNR/SSIM, alvos de compressão, diretrizes de taxa de bits)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: Template do relatório HTML para personalizar modos de visualização e estilo