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 | 지속 시간과 max-frames에 기반한 균등 간격 프레임 | 고정 샘플링, 예측 가능한 출력 |
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 출력 스키마 문서