Communitygithub.com

lilinji/GeneTind-Life-Skills

비디오 파일을 처리하여 오디오 추출, 형식 변환(mp4, webm), Whisper 음성 인식을 수행합니다. 사용자가 비디오 변환, 오디오 추출, 음성 인식, mp4, webm, ffmpeg, whisper를 언급할 때 사용하세요.

GeneTind-Life-Skills란 무엇인가요?

이 AI 에이전트 스킬은 FFmpeg와 OpenAI Whisper 모델을 활용하여 비디오 파일 처리 기능을 제공합니다. 비디오에서 오디오를 추출하고, MP4 또는 WebM 형식으로 변환하며, Whisper를 통해 음성을 텍스트로 변환할 수 있습니다. 주로 Claude Code, Cursor, Codex 등 uv 패키지 관리자를 지원하는 에이전트 환경에서 사용되며, 하나의 Python 스크립트(scripts/video_processor.py)를 통해 모든 작업을 일관된 CLI 명령어로 수행합니다. 사용자는 extract-audio, to-mp4, to-webm, transcribe 명령어로 원하는 작업을 선택할 수 있으며, 각 명령어는 다양한 옵션(코덱, 모델 크기, 언어, 출력 형식 등)을 지원합니다. 특히 transcribe 명령어는 비디오 파일을 입력받아 자동으로 오디오를 추출한 후 Whisper로 처리하고, TXT, SRT, VTT, JSON 등 여러 출력 형식을 지원합니다. 이 스킬은 FFmpeg와 Whisper의 사전 설치를 필요로 하지만, PEP 723 스크립트 의존성 관리를 통해 추가 패키지(click, ffmpeg-python)를 자동으로 처리합니다.

지원 대상✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/lilinji/GeneTind-Life-Skills/tree/HEAD/skills/Video-Processor

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

비디오 프로세서

사용 방법

이 스킬은 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

음성 인식 워크플로우:

  1. 입력이 비디오인 경우 FFmpeg가 임시 WAV 파일로 오디오를 추출합니다.
  2. Whisper가 오디오 파일을 처리합니다.
  3. 음성 인식 결과가 요청된 형식으로 저장됩니다.
  4. 임시 파일은 자동으로 정리됩니다.

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로 변환해 주시겠어요?

다음과 같이 수행:

  1. 기본 설정으로 to-mp4 명령어 사용:
    uv run .claude/skills/video-processor/scripts/video_processor.py to-mp4 old_video.avi output.mp4
    
  2. 변환이 성공적으로 완료되었는지 확인
  3. 사용자에게 출력 파일 위치 알림

예시 2: 오디오 추출 및 음성 인식

사용자 요청:

강의 비디오를 녹화했는데 기록이 필요합니다. 오디오를 추출하고 음성 인식해 주시겠어요?

다음과 같이 수행:

  1. 먼저 오디오 추출:
    uv run .claude/skills/video-processor/scripts/video_processor.py extract-audio lecture.mp4 lecture.wav
    
  2. 그런 다음 base 모델(속도/정확도의 좋은 균형)을 사용하여 음성 인식:
    uv run .claude/skills/video-processor/scripts/video_processor.py transcribe lecture.mp4 transcript.txt --model base
    
  3. transcript.txt 파일을 사용자와 공유

예시 3: 자막이 포함된 웹 최적화 비디오 생성

사용자 요청:

이 비디오를 웹사이트에 자막과 함께 올려야 합니다. 도와주시겠어요?

다음과 같이 수행:

  1. 웹 최적화를 위해 WebM으로 변환:
    uv run .claude/skills/video-processor/scripts/video_processor.py to-webm presentation.mp4 presentation.webm
    
  2. SRT 자막 파일 생성:
    uv run .claude/skills/video-processor/scripts/video_processor.py transcribe presentation.mp4 subtitles.srt --format srt --model small
    
  3. 사용자에게 다음이 있음을 알림:
    • presentation.webm (웹 최적화 비디오)
    • subtitles.srt (임베딩용 자막 파일)

예시 4: 언어 지정을 통한 고품질 음성 인식

사용자 요청:

게시용으로 정확한 기록이 필요한 스페인어 인터뷰 비디오가 있습니다.

다음과 같이 수행:

  1. 최고 정확도를 위해 더 큰 모델과 언어 지정 사용:
    uv run .claude/skills/video-processor/scripts/video_processor.py transcribe interview.mp4 transcript.txt --model medium --language es
    
  2. 선택사항으로 검토용 SRT 생성:
    uv run .claude/skills/video-processor/scripts/video_processor.py transcribe interview.mp4 transcript.srt --format srt --model medium --language es
    
  3. 사용자와 기록을 검토하고 필요한 수정 사항 반영

예시 5: 여러 비디오 일괄 처리

사용자 요청:

모두 WebM으로 변환하고 음성 인식해야 하는 교육 비디오 폴더가 있습니다.

다음과 같이 수행:

  1. 디렉터리의 모든 비디오 파일 나열:
    ls training_videos/*.mp4
    
  2. 각 비디오 파일에 대해 변환 및 음성 인식 실행:
    # 각 비디오에 대해: 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
    
    # 각 파일에 대해 반복
    
  3. 모든 변환 및 음성 인식이 완료되었는지 확인
  4. 출력 파일 요약 제공

요약

video-processor 스킬은 일반적인 비디오 처리 작업을 위한 통합 인터페이스를 제공합니다:

  • 오디오 추출: 다양한 형식의 오디오 트랙 추출
  • 형식 변환: MP4(범용) 또는 WebM(웹 최적화)으로 변환
  • 음성 인식: 여러 출력 형식을 지원하는 음성-텍스트 변환
  • 유연성: 모델 선택, 언어 및 출력 형식을 위한 CLI 인수

모든 작업은 합리적인 기본값과 포괄적인 오류 처리를 갖춘 단일의 잘 문서화된 스크립트를 통해 처리됩니다.

관련 스킬