video-understand
ffmpeg을 사용한 프레임 추출과 Whisper 음성 인식을 통해 로컬에서 비디오 콘텐츠를 이해합니다. 완전히 오프라인이며 API 키가 필요하지 않습니다.
필수 조건
ffmpeg+ffprobe(필수):brew install ffmpegopenai-whisper(선택, 음성 인식용):pip install openai-whisper
명령어
# 장면 감지 + 음성 인식 (기본값)
python3 skills/video-understand/scripts/understand_video.py video.mp4
# 키프레임 추출
python3 skills/video-understand/scripts/understand_video.py video.mp4 -m keyframe
# 일정 간격 추출
python3 skills/video-understand/scripts/understand_video.py video.mp4 -m interval
# 추출할 최대 프레임 제한
python3 skills/video-understand/scripts/understand_video.py video.mp4 --max-frames 10
# 더 큰 Whisper 모델 사용
python3 skills/video-understand/scripts/understand_video.py video.mp4 --whisper-model small
# 프레임만 추출, 음성 인식 생략
python3 skills/video-understand/scripts/understand_video.py video.mp4 --no-transcribe
# 조용한 모드 (JSON만 출력, 진행 메시지 없음)
python3 skills/video-understand/scripts/understand_video.py video.mp4 -q
# 파일로 출력
python3 skills/video-understand/scripts/understand_video.py video.mp4 -o result.json
CLI 옵션
| 플래그 | 설명 |
|---|---|
video | 입력 비디오 파일 (위치 인수, 필수) |
-m, --mode | 추출 모드: scene (기본값), keyframe, interval |
--max-frames | 유지할 최대 프레임 수 (기본값: 20) |
--whisper-model | Whisper 모델 크기: tiny, base, small, medium, large (기본값: base) |
--no-transcribe | 오디오 음성 인식을 건너뛰고 프레임만 추출 |
-o, --output | 결과 JSON을 stdout 대신 파일로 저장 |
-q, --quiet | 진행 메시지 숨기고 JSON만 출력 |
추출 모드
| 모드 | 작동 방식 | 최적 대상 |
|---|---|---|
scene | ffmpeg select='gt(scene,0.3)'을 통해 장면 변화 감지 | 대부분의 비디오, 다양한 콘텐츠 |
keyframe | I-프레임 (코덱 키프레임) 추출 | 자연스러운 키프레임 배치가 있는 인코딩된 비디오 |
interval | 지속 시간과 최대 프레임 수에 따라 균등 간격으로 프레임 추출 | 고정 샘플링, 예측 가능한 출력 |
scene 모드에서 장면 변화가 감지되지 않으면 자동으로 interval 모드로 전환됩니다.
출력
스크립트는 JSON을 stdout으로 출력합니다 (-o 사용 시 파일로 출력). 전체 스키마는 references/output-format.md를 참조하세요.
{
"video": "video.mp4",
"duration": 18.076,
"resolution": {"width": 1224, "height": 1080},
"mode": "scene",
"frames": [
{"path": "/abs/path/frame_0001.jpg", "timestamp": 0.0, "timestamp_formatted": "00:00"}
],
"frame_count": 12,
"transcript": [
{"start": 0.0, "end": 2.5, "text": "안녕하세요, 환영합니다..."}
],
"text": "전체 음성 인식 텍스트...",
"note": "Read 도구를 사용하여 프레임 이미지를 확인하고 시각적으로 이해하세요."
}
추출된 프레임 이미지 경로에 Read 도구를 사용하여 시각적으로 확인할 수 있습니다.
참고 자료
references/output-format.md-- 전체 JSON 출력 스키마 문서