Communitygithub.com

sacredvoid/skillkit

비디오/오디오 녹화(줌, 회의 등)를 처리하여 Whisper로 오디오를 텍스트로 변환하고 ffmpeg로 시각적 프레임을 추출합니다. 사용자의 하드웨어(Apple Silicon, NVIDIA, AMD, CPU)를 자동 감지하여 최적의 전사 모델을 선택합니다. macOS, Linux, Windows에서 모두 사용 가능합니다.

skillkit란 무엇인가요?

이 스킬은 비디오 및 오디오 녹화물을 텍스트 전사와 시각적 프레임 캡처로 처리하여 분석할 수 있도록 해주는 AI 에이전트 도구입니다. 사용자의 하드웨어(Apple Silicon, NVIDIA GPU, AMD GPU, CPU)를 자동으로 감지하고, 감지된 하드웨어에 가장 적합한 전사 엔진(Whisper)과 모델을 선택하여 최적의 성능을 제공합니다. macOS, Linux, Windows를 모두 지원하며, ffmpeg를 사용하여 비디오에서 1분당 1프레임을 추출하고, faster-whisper(CUDA) 또는 openai-whisper(MPS/CPU)를 사용하여 오디오를 전사합니다. 또한 전사 중에 추출된 프레임을 검토하여 화면 공유 내용, 참가자 이름, 타임스탬프 등 시각적 정보를 함께 분석할 수 있어 회의 내용을 종합적으로 이해하는 데 도움을 줍니다. 이 스킬은 Claude Code, Cursor, Codex 등 AI 에이전트와 함께 사용하도록 설계되었습니다.

지원 대상~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/sacredvoid/skillkit/tree/HEAD/skills/video-audio-processor

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

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

문서

비디오/오디오 프로세서

비디오 및 오디오 녹화물을 텍스트 전사와 시각적 프레임 캡처로 처리하여 분석합니다. 사용자의 하드웨어를 자동 감지하고 최적의 전사 모델, 장치 및 설정을 선택합니다.

0단계: 컴퓨팅 환경 감지

매 호출 시작 시 실행합니다. 이후 모든 작업을 결정합니다.

python3 -c "
import platform, shutil, subprocess, json

info = {'os': platform.system(), 'arch': platform.machine(), 'ram_gb': 0, 'gpu': 'none', 'vram_gb': 0, 'device': 'cpu', 'dtype': 'float32'}

# RAM
try:
    if platform.system() == 'Darwin':
        import os; info['ram_gb'] = round(os.sysconf('SC_PAGE_SIZE') * os.sysconf('SC_PHYS_PAGES') / (1024**3))
    elif platform.system() == 'Linux':
        with open('/proc/meminfo') as f:
            for line in f:
                if line.startswith('MemTotal'):
                    info['ram_gb'] = round(int(line.split()[1]) / (1024**2))
                    break
    else:
        import ctypes
        mem = ctypes.c_ulonglong(0)
        ctypes.windll.kernel32.GetPhysicallyInstalledMemory(ctypes.byref(mem))
        info['ram_gb'] = round(mem.value / (1024**2))
except: pass

# GPU 감지
try:
    import torch
    if torch.cuda.is_available():
        info['gpu'] = torch.cuda.get_device_name(0)
        info['vram_gb'] = round(torch.cuda.get_device_properties(0).total_mem / (1024**3))
        info['device'] = 'cuda'
        info['dtype'] = 'float16'
    elif hasattr(torch.backends, 'mps') and torch.backends.mps.is_available():
        info['gpu'] = 'Apple Silicon (MPS)'
        info['vram_gb'] = info['ram_gb']  # 통합 메모리
        info['device'] = 'mps'
        info['dtype'] = 'float16'
    elif hasattr(torch, 'hip') or 'AMD' in str(getattr(torch, '_C', '')):
        info['gpu'] = 'AMD (ROCm)'
        info['device'] = 'cuda'  # ROCm은 cuda API 사용
        info['dtype'] = 'float16'
except ImportError:
    pass

# ffmpeg 감지
info['ffmpeg'] = shutil.which('ffmpeg') is not None
info['ffprobe'] = shutil.which('ffprobe') is not None

print(json.dumps(info))
"

JSON 출력을 파싱하고 내부적으로 COMPUTE로 저장합니다. 결과를 사용자에게 표시합니다.

감지된 하드웨어:

  • OS: {os} ({arch})
  • RAM: {ram_gb} GB
  • GPU: {gpu} ({vram_gb} GB VRAM)
  • 컴퓨팅 장치: {device}
  • ffmpeg: {설치됨/없음}

Whisper 엔진 선택

하드웨어에 따라 전사 엔진을 선택합니다:

조건엔진이유
CUDA GPU 사용 가능faster-whisperGPU 가속 CTranslate2, 표준 Whisper보다 4배 빠름
MPS (Apple Silicon)openai-whisper표준 Whisper, 가능한 경우 MPS 가속 사용
CPU 전용openai-whisperCPU에서 표준 Whisper, 안정적인 폴백

모델 선택 매트릭스

하드웨어 및 녹화 길이에 따라 모델을 권장합니다:

조건권장 모델속도 (1시간 녹화)정확도
CUDA >= 8 GB VRAMlarge-v3~5분최고
CUDA 4-7 GB VRAMmedium~8분높음
MPS (Apple Silicon, 16+ GB)medium~15분높음
MPS (Apple Silicon, 8 GB)small~10분좋음
CPU + RAM >= 16 GBsmall~30분좋음
CPU + RAM < 16 GBbase~15분적정

권장 사항을 제시하고 사용자가 선택할 수 있도록 합니다:

AskUserQuestion: "어떤 전사 모델을 사용해야 하나요?"
Options:
- [Recommended model] (권장) - [하드웨어 기반 이유]
- large-v3 - 최고 정확도, 8+ GB VRAM 또는 많은 RAM 필요
- medium - 높은 정확도, 균형 잡힌 속도
- small - 좋은 정확도, 빠른 처리
- base - 대부분의 회의에 적합, 가장 빠름

선택한 모델을 WHISPER_MODEL로, 엔진을 WHISPER_ENGINE으로 저장합니다.

1단계: 녹화물 식별

파일을 찾습니다. Zoom 녹화는 일반적으로 다음 패턴을 따릅니다:

  • GMT{날짜}-{시간}_Recording_{해상도}.mp4 (비디오)
  • GMT{날짜}-{시간}_Recording.m4a (오디오 전용)
  • GMT{날짜}-{시간}_RecordingnewChat.txt (채팅 로그)

세 가지 아티팩트를 모두 확인합니다. 채팅 파일을 먼저 읽습니다 (작고 즉각적인 컨텍스트를 제공).

2단계: 종속성 설치

플랫폼에 따라 필요한 항목을 확인하고 설치합니다.

ffmpeg

# ffmpeg 사용 가능 여부 확인
ffmpeg -version 2>&1 | head -1
ffprobe -version 2>&1 | head -1

ffmpeg가 없으면 플랫폼에 따라 설치합니다:

플랫폼설치 명령어
macOS (Homebrew)brew install ffmpeg
macOS (Homebrew 없음)사용자에게 Homebrew 먼저 설치 후 ffmpeg 설치 안내
Ubuntu/Debiansudo apt update && sudo apt install -y ffmpeg
Fedora/RHELsudo dnf install -y ffmpeg
Arch Linuxsudo pacman -S ffmpeg
Windows (winget)winget install Gyan.FFmpeg
Windows (choco)choco install ffmpeg
Windows (scoop)scoop install ffmpeg

Python + Whisper

python3 -c "import torch; print(torch.__version__)" 2>&1

torch가 없으면 플랫폼에 따라 설치합니다:

플랫폼설치 명령어
macOS (MPS)pip3 install torch torchvision torchaudio
Linux (CUDA)pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
Linux (ROCm)pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.0
Linux/Windows (CPU)pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
Windows (CUDA)pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

그런 다음 전사 엔진을 설치합니다:

# CUDA 시스템용 (faster-whisper with CTranslate2 가속)
pip3 install faster-whisper

# MPS / CPU 시스템용 (표준 OpenAI Whisper)
pip3 install openai-whisper

3단계: 재생 시간 확인

ffprobe (크로스 플랫폼)를 사용하여 파일 재생 시간을 얻습니다:

ffprobe -v quiet -show_entries format=duration -of csv=p=0 "/path/to/file"

초 단위로 재생 시간을 반환합니다. 사람이 읽을 수 있는 형식으로 변환하여 사용자에게 표시합니다. 이를 사용하여 선택한 모델과 하드웨어를 기반으로 전사 시간을 추정합니다.

계획을 제시합니다:

처리 계획:

  • 파일: {filename} ({duration})
  • 엔진: {WHISPER_ENGINE} with {WHISPER_MODEL} on {device}
  • 예상 전사 시간: {estimate}
  • 프레임 추출: 1분당 1프레임 ({frame_count} 프레임)

시작하기 전에 조정할 사항이 있나요?

시간 추정

장치basesmallmediumlarge-v3
CUDA (RTX 3060+)~1분/시간~2분/시간~4분/시간~5분/시간
CUDA (faster-whisper)~30초/시간~1분/시간~2분/시간~3분/시간
MPS (M1/M2/M3/M4)~3분/시간~6분/시간~15분/시간~25분/시간
CPU (16GB+ RAM)~8분/시간~15분/시간~30분/시간~60분/시간

4단계: 시각적 프레임 추출

시각적 컨텍스트를 위해 1분당 1프레임을 추출합니다. 크로스 플랫폼 임시 디렉토리를 사용합니다:

# 임시 디렉토리 생성 (크로스 플랫폼)
python3 -c "import tempfile, os; d = os.path.join(tempfile.gettempdir(), 'av-frames'); os.makedirs(d, exist_ok=True); print(d)"

그런 다음 프레임을 추출합니다:

ffmpeg -i "/path/to/video.mp4" \
  -vf "fps=1/60,scale=1280:-1" -q:v 3 {TEMP_DIR}/frame_%03d.jpg

Read 도구를 사용하여 각 프레임을 봅니다. 프레임은 다음을 보여줍니다:

  • 화면 공유 (코드, 슬라이드, UI)
  • 참가자 이름 (각 비디오 타일의 왼쪽 하단)
  • 타임스탬프 (화면 공유에 표시되는 경우)

5단계: 오디오 전사

전사 엔진을 실행합니다. WHISPER_ENGINE에 따라 올바른 코드를 선택합니다:

faster-whisper (CUDA 시스템)

from faster_whisper import WhisperModel
import json

model = WhisperModel("{WHISPER_MODEL}", device="cuda", compute_type="float16")
segments, info = model.transcribe("/path/to/audio", beam_size=5, language="en")

results = []
for segment in segments:
    results.append({
        "start": segment.start,
        "end": segment.end,
        "text": segment.text.strip()
    })

# 타임스탬프가 포함된 전사 저장
with open("{TEMP_DIR}/transcript.json", "w") as f:
    json.dump({"language": info.language, "segments": results}, f, indent=2)

with open("{TEMP_DIR}/transcript.txt", "w") as f:
    for seg in results:
        start = int(seg["start"])
        mins, secs = divmod(start, 60)
        f.write(f"[{mins:02d}:{secs:02d}] {seg['text']}\n")

print(f"{len(results)}개 세그먼트 전사 완료")

openai-whisper (MPS / CPU 시스템)

import whisper, json

model = whisper.load_model("{WHISPER_MODEL}")
result = model.transcribe("/path/to/audio", verbose=False)

# 타임스탬프가 포함된 전사 저장
with open("{TEMP_DIR}/transcript.json", "w") as f:
    json.dump(result, f, indent=2)

with open("{TEMP_DIR}/transcript.txt", "w") as f:
    for seg in result["segments"]:
        start = int(seg["start"])
        mins, secs = divmod(start, 60)
        f.write(f"[{mins:02d}:{secs:02d}] {seg['text'].strip()}\n")

print(f"{len(result['segments'])}개 세그먼트 전사 완료")

시간이 많이 소요되므로 전사를 백그라운드에서 실행합니다. 실행 중에 추출된 프레임을 시각적으로 검토합니다.

6단계: 종합

시각적 프레임 + 전사 + 채팅을 결합하여 이해를 구축합니다:

  • 누가: 비디오 이름 레이블과 음성 귀속을 통해 참가자 식별
  • 무엇: 화면에 표시된 내용 (데모, 슬라이드, 코드)
  • 말한 내용: 주요 인용문, 결정 사항, 요구 사항, 피드백
  • 액션 아이템: 명시적인 약속 및 후속 조치

모델 참조

모델파라미터속도정확도최적 사용
tiny39M매우 빠름낮음빠른 스캔, 오디오 사용 가능 여부 확인
base74M빠름적정짧고 명확한 회의 기본값
small244M보통좋음악센트가 있는 일반 회의
medium769M느림높음중요한 회의, 고객 대면
large-v31.5B매우 느림최고중요한 녹화, 낮은 오디오 품질

팁

  • 프레임을 시각적으로 검토하는 동안 항상 전사를 백그라운드에서 실행
  • 프레임을 8개씩 일괄 읽기 (도구 병렬 처리 제한)
  • 표준 Whisper는 CPU와 MPS에서 FP32를 사용하고, faster-whisper는 CUDA에서 CTranslate2와 FP16을 사용
  • 매우 긴 녹화(>1시간)의 경우 먼저 오디오 분할 고려
  • Zoom의 채팅 파일에는 타임스탬프와 공유 링크가 포함되어 있으므로 빠른 컨텍스트를 위해 먼저 읽기
  • Windows에서는 Python 파일 경로에 슬래시 또는 원시 문자열 사용

오류 처리

오류원인해결 방법
ffmpeg: command not foundffmpeg가 설치되지 않음위 플랫폼별 표에 따라 설치
No module named 'whisper'Whisper가 설치되지 않음pip3 install openai-whisper
No module named 'faster_whisper'faster-whisper가 설치되지 않음pip3 install faster-whisper
CUDA out of memory모델이 VRAM에 비해 너무 큼더 작은 모델로 전환
RuntimeError: MPS backend구형 macOS의 MPS 문제macOS 업데이트, 또는 PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0으로 CPU 폴백
torch not foundPython 종속성 누락위 플랫폼별 표에 따라 torch 설치
왜곡된 전사잘못된 언어 또는 낮은 오디오 품질language="en" 지정 또는 더 큰 모델 사용 시도
매우 느린 전사CPU에서 큰 모델 실행base 또는 small 모델로 전환

관련 스킬