Video Comparer은(는) 무엇을 하나요?
개요
두 비디오를 비교하고 압축 결과를 분석하는 대화형 HTML 보고서를 생성합니다. 이 스크립트는 비디오 메타데이터를 추출하고, 품질 지표(PSNR, SSIM)를 계산하며, 세 가지 보기 모드(슬라이더, 나란히 보기, 그리드)로 프레임별 시각적 비교를 만듭니다.
이 스킬을 사용해야 하는 경우
다음과 같은 경우 이 스킬을 사용하세요:
- 원본 비디오와 압축된 비디오를 비교할 때
- 비디오 압축 품질과 효율성을 분석할 때
- 코덱 성능 또는 비트레이트 감소 영향을 평가할 때
- 사용자가 "compare videos", "video quality", "compression analysis" 또는 "before/after compression"을 언급할 때
핵심 사용법
기본 명령어
python3 scripts/compare.py original.mp4 compressed.mp4
다음을 포함하는 comparison.html을 생성합니다:
- 비디오 매개변수(코덱, 해상도, 비트레이트, 재생 시간, 파일 크기)
- 품질 지표(PSNR, SSIM, 크기/비트레이트 감소 비율)
- 프레임별 비교(기본값: 5초 간격 프레임)
명령어 옵션
# 사용자 정의 출력 파일
python3 scripts/compare.py original.mp4 compressed.mp4 -o report.html
# 사용자 정의 프레임 간격 (값이 클수록 프레임 수가 적어 처리 속도가 빠름)
python3 scripts/compare.py original.mp4 compressed.mp4 --interval 10
# 일괄 비교
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
요구 사항
시스템 종속성
FFmpeg 및 FFprobe (비디오 분석 및 프레임 추출에 필요):
# macOS
brew install ffmpeg
# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg
# Windows
# https://ffmpeg.org/download.html 에서 다운로드
# 또는 winget install ffmpeg 사용
Python 3.8+ (타입 힌트, f-strings, pathlib 사용)
비디오 사양
- 지원 형식:
.mp4(권장),.mov,.avi,.mkv,.webm - 파일 크기 제한: 비디오당 500MB (구성 가능)
- 처리 시간: 일반 비디오의 경우 약 1-2분; 재생 시간과 프레임 간격에 따라 다름
스크립트 동작
자동 검증
스크립트는 자동으로 다음을 검증합니다:
- FFmpeg/FFprobe 설치 및 가용성
- 파일 존재, 확장자 및 크기 제한
- 경로 보안 (디렉토리 트래버설 방지)
검증 실패 시 해결 지침이 포함된 명확한 오류 메시지가 표시됩니다.
품질 지표
스크립트는 두 가지 표준 품질 지표를 계산합니다:
PSNR (최대 신호 대 잡음비): 픽셀 수준의 유사성 측정 (20-50 dB 범위, 높을수록 좋음)
SSIM (구조적 유사성 지수): 지각적 유사성 측정 (0.0-1.0 범위, 높을수록 좋음)
자세한 해석 척도와 품질 임계값은 references/video_metrics.md를 참조하세요.
프레임 추출
스크립트는 지정된 간격(기본값: 5초)으로 프레임을 추출하고, 비교를 위해 일관된 높이(800px)로 크기를 조정하며, 자체 포함된 HTML에 base64 데이터 URL로 포함시킵니다. 임시 파일은 처리 후 자동으로 정리됩니다.
출력 보고서
생성된 HTML 보고서에는 다음이 포함됩니다:
- 슬라이더 모드: 드래그하여 원본과 압축본을 비교 (기본값)
- 나란히 보기 모드: 직접 비교를 위한 동시 표시
- 그리드 모드: 간결한 2열 레이아웃
- 확대/축소 컨트롤: 50%-200% 배율
- 자체 포함 형식 (서버 불필요, 오프라인에서 작동)
중요한 구현 세부 사항
보안
스크립트는 다음을 구현합니다:
- 경로 검증 (절대 경로, 디렉토리 트래버설 방지)
- 명령 주입 방지 (
shell=True없음, 검증된 인자) - 리소스 제한 (파일 크기, 시간 초과)
- 사용자 정의 예외:
ValidationError,FFmpegError,VideoComparisonError
일반적인 오류 시나리오
"FFmpeg not found": 플랫폼 패키지 관리자를 통해 FFmpeg 설치 (요구 사항 섹션 참조)
"File too large": 비교 전에 비디오를 압축하거나 scripts/compare.py에서 MAX_FILE_SIZE_MB 조정
"Operation timed out": FFMPEG_TIMEOUT 상수 증가 또는 더 큰 --interval 값 사용 (더 적은 프레임 처리)
"Frame count mismatch": 비디오의 재생 시간/프레임 속도가 다름; 스크립트가 자동으로 최소 프레임 수로 자르고 경고 표시
구성
스크립트에는 파일 크기 제한, 시간 초과, 프레임 크기 및 추출 간격에 대한 조정 가능한 상수가 포함되어 있습니다. 동작을 사용자 정의하려면 scripts/compare.py 상단의 상수를 편집하세요. 자세한 구성 옵션 및 영향은 references/configuration.md를 참조하세요.
참고 자료
자세한 정보는 다음 파일을 참조하세요:
references/video_metrics.md: 품질 지표 해석 (PSNR/SSIM 척도, 압축 목표, 비트레이트 지침)references/ffmpeg_commands.md: FFmpeg 명령어 참조 (메타데이터 추출, 프레임 추출, 문제 해결)references/configuration.md: 스크립트 구성 옵션 및 조정 가능한 상수assets/template.html: 보기 모드 및 스타일 사용자 정의를 위한 HTML 보고서 템플릿