비디오 프로세서
사용 방법
이 스킬은 FFmpeg 및 OpenAI Whisper 모델을 사용하여 비디오 처리 유틸리티(오디오 추출, 형식 변환, 오디오 음성 인식)를 제공합니다.
사전 요구 사항
필수 도구 (환경에 설치되어 있어야 함):
-
FFmpeg: 비디오/오디오 처리를 위한 멀티미디어 프레임워크
# macOS brew install ffmpeg # Ubuntu/Debian apt-get install ffmpeg # 설치 확인 ffmpeg -version -
OpenAI Whisper: 음성-텍스트 변환 모델
# pip를 통해 설치 pip install -U openai-whisper # 설치 확인 whisper --help
Python 패키지 (PEP 723을 통해 스크립트에 포함됨):
- click (CLI 프레임워크)
- ffmpeg-python (FFmpeg용 Python 래퍼)
워크플로우
모든 비디오 처리 작업에는 scripts/video_processor.py 스크립트를 사용하세요. 이 스크립트는 다음과 같은 명령어가 포함된 간단한 CLI를 제공합니다.
1. 비디오에서 오디오 추출
비디오 파일에서 오디오 트랙을 추출합니다.
uv run .claude/skills/video-processor/scripts/video_processor.py extract-audio input.mp4 output.wav
옵션:
--format: 출력 오디오 형식 (기본값: wav). 지원: wav, mp3, aac, flac- 출력은 음성 인식 또는 독립형 오디오 사용에 적합합니다.
2. 비디오를 MP4로 변환
모든 비디오 파일을 MP4 형식으로 변환합니다.
uv run .claude/skills/video-processor/scripts/video_processor.py to-mp4 input.avi output.mp4
옵션:
--codec: 비디오 코덱 (기본값: libx264). 일반 옵션: libx264, libx265, h264--preset: 인코딩 속도/품질 프리셋 (기본값: medium). 옵션: ultrafast, fast, medium, slow, veryslow
3. 비디오를 WebM으로 변환
모든 비디오 파일을 WebM 형식(웹 최적화)으로 변환합니다.
uv run .claude/skills/video-processor/scripts/video_processor.py to-webm input.mp4 output.webm
옵션:
--codec: 비디오 코덱 (기본값: libvpx-vp9). 옵션: libvpx, libvpx-vp9- WebM은 웹 재생 및 스트리밍에 최적화되어 있습니다.
4. Whisper로 오디오 음성 인식
OpenAI Whisper 모델을 사용하여 오디오 또는 비디오 파일을 텍스트로 변환합니다.
# 비디오 파일 음성 인식 (오디오가 자동으로 추출됨)
uv run .claude/skills/video-processor/scripts/video_processor.py transcribe input.mp4 transcript.txt
# 오디오 파일 직접 음성 인식
uv run .claude/skills/video-processor/scripts/video_processor.py transcribe audio.wav transcript.txt
옵션:
--model: Whisper 모델 크기 (기본값: base). 옵션:tiny: 가장 빠름, 가장 낮은 정확도 (~1GB RAM)base: 빠름, 좋은 정확도 (~1GB RAM) [기본값]small: 균형 잡힘 (~2GB RAM)medium: 높은 정확도 (~5GB RAM)large: 최고 정확도, 가장 느림 (~10GB RAM)
--language: 언어 코드 (기본값: 자동 감지). 예: en, es, fr, de, zh--format: 출력 형식 (기본값: txt). 옵션: txt, srt, vtt, json
음성 인식 워크플로우:
- 입력이 비디오인 경우 FFmpeg가 임시 WAV 파일로 오디오를 추출합니다.
- Whisper가 오디오 파일을 처리합니다.
- 음성 인식 결과가 요청된 형식으로 저장됩니다.
- 임시 파일은 자동으로 정리됩니다.
5. 통합 워크플로우 예시
비디오를 종단 간 처리합니다.
# 1. 분석을 위해 오디오 추출
uv run .claude/skills/video-processor/scripts/video_processor.py extract-audio lecture.mp4 lecture.wav
# 2. SRT 자막으로 음성 인식
uv run .claude/skills/video-processor/scripts/video_processor.py transcribe lecture.mp4 lecture.srt --format srt --model small
# 3. 웹 형식으로 변환
uv run .claude/skills/video-processor/scripts/video_processor.py to-webm lecture.mp4 lecture.webm
주요 기술 세부 사항
FFmpeg 및 Whisper 통합:
- FFmpeg는 자체적으로 오디오를 음성 인식하지 않으며, 외부 음성 인식을 위해 오디오를 준비합니다.
- 워크플로우: 오디오 추출(FFmpeg) → 음성 인식(Whisper) → 선택사항: 비디오와 재통합
- FFmpeg는 실시간 처리를 위해 오디오를 Whisper로 직접 파이프할 수 있습니다(고급 사용 사례).
음성 인식을 위한 오디오 형식:
- Whisper는 WAV 또는 MP3 형식에서 가장 잘 작동합니다.
- 샘플 레이트: 16kHz가 최적입니다(스크립트가 자동으로 변환 처리).
- 스크립트는 Whisper에 최적화된 설정으로 오디오를 추출합니다.
출력 형식:
- txt: 일반 텍스트 기록
- srt: SubRip 자막 형식(타임스탬프 포함)
- vtt: WebVTT 자막 형식(웹 표준)
- json: 단어 수준 타임스탬프가 포함된 상세 JSON
오류 처리
스크립트는 포괄적인 오류 처리를 포함합니다:
- 입력 파일 존재 여부 확인
- FFmpeg 및 Whisper 설치 확인
- 누락된 종속성에 대한 명확한 오류 메시지 제공
- 오류 발생 시 임시 파일 정리 처리
성능 팁
- 빠른 초안에는
tiny또는base모델을 사용하세요. - 프로덕션 음성 인식에는
small또는medium을 사용하세요. - 최대 정확도가 필요한 경우에만
large를 사용하세요. - 긴 비디오의 경우 먼저 오디오를 추출한 다음 세그먼트별로 음성 인식하는 것이 좋습니다.
- VP9을 사용한 WebM 변환은 시간이 더 걸리지만 파일 크기가 더 작습니다.
예시
예시 1: 비디오를 MP4로 빠르게 변환
사용자 요청:
오래된 카메라에서 가져온 AVI 파일이 있습니다. MP4로 변환해 주시겠어요?
다음과 같이 수행:
- 기본 설정으로 to-mp4 명령어 사용:
uv run .claude/skills/video-processor/scripts/video_processor.py to-mp4 old_video.avi output.mp4 - 변환이 성공적으로 완료되었는지 확인
- 사용자에게 출력 파일 위치 알림
예시 2: 오디오 추출 및 음성 인식
사용자 요청:
강의 비디오를 녹화했는데 기록이 필요합니다. 오디오를 추출하고 음성 인식해 주시겠어요?
다음과 같이 수행:
- 먼저 오디오 추출:
uv run .claude/skills/video-processor/scripts/video_processor.py extract-audio lecture.mp4 lecture.wav - 그런 다음 base 모델(속도/정확도의 좋은 균형)을 사용하여 음성 인식:
uv run .claude/skills/video-processor/scripts/video_processor.py transcribe lecture.mp4 transcript.txt --model base - transcript.txt 파일을 사용자와 공유
예시 3: 자막이 포함된 웹 최적화 비디오 생성
사용자 요청:
이 비디오를 웹사이트에 자막과 함께 올려야 합니다. 도와주시겠어요?
다음과 같이 수행:
- 웹 최적화를 위해 WebM으로 변환:
uv run .claude/skills/video-processor/scripts/video_processor.py to-webm presentation.mp4 presentation.webm - SRT 자막 파일 생성:
uv run .claude/skills/video-processor/scripts/video_processor.py transcribe presentation.mp4 subtitles.srt --format srt --model small - 사용자에게 다음이 있음을 알림:
- presentation.webm (웹 최적화 비디오)
- subtitles.srt (임베딩용 자막 파일)
예시 4: 언어 지정을 통한 고품질 음성 인식
사용자 요청:
게시용으로 정확한 기록이 필요한 스페인어 인터뷰 비디오가 있습니다.
다음과 같이 수행:
- 최고 정확도를 위해 더 큰 모델과 언어 지정 사용:
uv run .claude/skills/video-processor/scripts/video_processor.py transcribe interview.mp4 transcript.txt --model medium --language es - 선택사항으로 검토용 SRT 생성:
uv run .claude/skills/video-processor/scripts/video_processor.py transcribe interview.mp4 transcript.srt --format srt --model medium --language es - 사용자와 기록을 검토하고 필요한 수정 사항 반영
예시 5: 여러 비디오 일괄 처리
사용자 요청:
모두 WebM으로 변환하고 음성 인식해야 하는 교육 비디오 폴더가 있습니다.
다음과 같이 수행:
- 디렉터리의 모든 비디오 파일 나열:
ls training_videos/*.mp4 - 각 비디오 파일에 대해 변환 및 음성 인식 실행:
# 각 비디오에 대해: video1.mp4, video2.mp4 등 uv run .claude/skills/video-processor/scripts/video_processor.py to-webm training_videos/video1.mp4 output/video1.webm uv run .claude/skills/video-processor/scripts/video_processor.py transcribe training_videos/video1.mp4 output/video1.txt --model base # 각 파일에 대해 반복 - 모든 변환 및 음성 인식이 완료되었는지 확인
- 출력 파일 요약 제공
요약
video-processor 스킬은 일반적인 비디오 처리 작업을 위한 통합 인터페이스를 제공합니다:
- 오디오 추출: 다양한 형식의 오디오 트랙 추출
- 형식 변환: MP4(범용) 또는 WebM(웹 최적화)으로 변환
- 음성 인식: 여러 출력 형식을 지원하는 음성-텍스트 변환
- 유연성: 모델 선택, 언어 및 출력 형식을 위한 CLI 인수
모든 작업은 합리적인 기본값과 포괄적인 오류 처리를 갖춘 단일의 잘 문서화된 스크립트를 통해 처리됩니다.