video-digest은(는) 무엇을 하나요?
개요
동영상 하나를 검색 가능한 단일 마크다운 다이제스트로 변환합니다. 이 스킬은 각 클립에 대해 세 가지 결과물을 생성하고 이를 하나의 digest.md 파일로 결합합니다:
- 자막 — 음성 단어 (faster-whisper, 기기 내 처리)
- 화면 내 텍스트 — 프레임에서 볼 수 있는 모든 고유 텍스트 라인 (OCR), URL 및 @핸들은 따로 추출
- 접촉 시트 몽타주 — 클립 전체에 걸친 프레임 그리드로, 시각적 스토리를 한눈에 파악 가능
모든 작업은 로컬에서 실행됩니다. 네트워크 호출 없음, 계정 불필요, 원격 측정 없음. 핵심 기능은 ffmpeg만 필요하며, 자막과 OCR은 선택 사항으로 없어도 정상 작동합니다.
사용 시기
- "이 동영상 / 이 200개 동영상에 뭐가 있지?" 싶을 때 동영상을 일일이 보지 않고 확인
- 리일, 강연, 튜토리얼, 영상 자료의 검색 가능한 카탈로그 구축
- 클립에서 잠깐 등장한 링크와 핸들 복구
- 길거나 많은 녹화물의 빠른 시각적 개요(몽타주) 획득
적합하지 않은 경우: 라이브 스트리밍, 동영상 편집/자르기, 동영상 생성. 이 도구는 동영상을 읽고 텍스트 + 이미지 요약을 출력합니다.
빠른 참조
scripts/check-deps.sh # 설치된 항목 확인 + 나머지 설치 방법 안내
scripts/video-digest.sh clip.mp4 # 하나의 동영상 → ./video-digest-out/clip/digest.md
scripts/video-digest.sh --out ~/digests *.mp4 # 폴더 전체 일괄 처리
scripts/video-digest.sh --lang en talk.mov # 자막 언어 힌트
scripts/video-digest.sh --no-transcript reel.mp4 # 오디오 건너뛰기, 시각 정보와 텍스트만
scripts/video-digest.sh --ocr-engine tesseract x.mp4 # 특정 OCR 엔진 강제 사용
| 플래그 | 용도 | 기본값 |
|---|---|---|
-o, --out DIR | 출력 루트 | ./video-digest-out |
--fps N | OCR 프레임 샘플링 속도 | 2 |
--montage-frames N | 클립 전체에 분산될 프레임 수 | 90 |
--tile CxR | 몽타주 그리드 | 3x3 |
--ocr-engine E | auto|vision|tesseract|none | auto |
--whisper-model M | tiny|base|small|medium(+.en) | small |
--whisper-python P | faster-whisper가 있는 Python 인터프리터 | 자동 감지 |
--lang CODE | 자막 언어 힌트 | 자동 감지 |
--no-transcript / --no-ocr / --no-montage | 특정 단계 건너뛰기 | — |
--force | 캐시가 있어도 단계 재실행 | 꺼짐 |
전체 목록은 scripts/video-digest.sh --help를 실행하세요.
작동 방식
진입점 scripts/video-digest.sh는 세 개의 독립적인 작은 도구를 조율하며, 각 도구는 단독으로도 실행할 수 있습니다:
| 단계 | 스크립트 | 엔진 |
|---|---|---|
| 몽타주 | scripts/montage.sh | ffmpeg 타일 필터 |
| 화면 내 텍스트 | scripts/ocr.sh (+ ocr_vision.swift) | macOS Vision (기본) 또는 tesseract |
| 자막 | scripts/transcribe.py | faster-whisper |
각 단계는 재개 가능합니다 — 완료된 작업은 .done으로 표시되어 캐시되며, --force를 전달하지 않는 한 재실행 시 건너뜁니다. 다이제스트는 항상 존재하는 단계들을 기반으로 재구성되므로, 부분 실행만 해도 유용한 파일이 생성됩니다.
OCR 엔진 선택은 자동입니다: macOS에서는 내장 Vision 프레임워크(설치 불필요, 기기 내 처리)를 사용하고, 그 외의 경우 tesseract가 있으면 사용하며, 없으면 경고와 함께 OCR을 건너뜁니다. 선택적 백엔드 설치 방법은 references/setup.md를, 정확한 출력 형식은 references/output-format.md를 참고하세요.
흔한 실수
- 자막이 비어 있음 → 사용 중인 인터프리터에 faster-whisper가 설치되어 있지 않은 경우.
scripts/check-deps.sh를 실행한 후pip install faster-whisper를 하거나,--whisper-python /path/to/python으로 기존 환경을 지정하세요. - Linux에서 화면 내 텍스트 없음 →
tesseract를 설치하세요 (apt install tesseract-ocr). Vision 엔진은 macOS 전용입니다. - 짧은 클립에 몽타주 프레임 수가 너무 많음 →
--montage-frames값을 낮추세요 (예:30). - 자막 언어가 잘못됨 →
--lang을 전달하거나 (예:--lang sk), 다국어 오디오에는.en이 아닌 모델을 사용하세요.
예시
examples/sample-digest/ 디렉토리에는 작은 샘플 클립과 그로부터 생성된 digest.md가 포함되어 있습니다 — 자막, 하나의 감지된 URL, 하나의 @핸들, 그리고 몽타주 시트가 있습니다. 다음 명령으로 재현할 수 있습니다 (자막 라인은 faster-whisper가 설치되어 있어야 함):
scripts/video-digest.sh --montage-frames 9 examples/sample-digest/sample.mp4