비디오 비교기은(는) 무엇을 하나요?
개요
두 비디오를 비교하고 압축 결과를 분석하는 대화형 HTML 보고서를 생성합니다. 스크립트는 비디오 메타데이터를 추출하고, 품질 측정항목(PSNR, SSIM)을 계산하며, 세 가지 보기 모드(슬라이더, 나란히 보기, 그리드)로 프레임별 시각적 비교를 만듭니다.
이 스킬을 사용해야 하는 경우
다음과 같은 경우에 이 스킬을 사용하세요:
- 원본 비디오와 압축 비디오를 비교할 때
- 비디오 압축 품질과 효율성을 분석할 때
- 코덱 성능이나 비트레이트 감소 영향을 평가할 때
- 사용자가 "비디오 비교", "비디오 품질", "압축 분석", "압축 전/후 비교" 등을 언급할 때
핵심 사용법
기본 명령어
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)로 크기를 조정하여 비교하며, base64 데이터 URL로 자체 포함 HTML에 내장합니다. 처리 후 임시 파일은 자동으로 정리됩니다.
출력 보고서
생성된 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 보고서 템플릿