Communitygithub.com

MadAppGang/claude-code

OpenAI Whisper를 사용한 오디오/비디오 트랜스크립션. 설치, 모델 선택, 트랜스크립트 형식(SRT, VTT, JSON), 타이밍 동기화 및 화자 분리까지 다룹니다. 미디어 트랜스크립션이나 자막 생성에 사용하세요.

claude-code란 무엇인가요?

이 스킬은 OpenAI Whisper를 사용하여 오디오 및 비디오 파일에서 고품질 트랜스크립션을 생성하는 방법을 종합적으로 제공합니다. 설치 옵션(OpenAI Whisper, whisper.cpp, Insanely Fast Whisper)과 모델(tiny부터 large-v3까지) 선택 지침을 포함하며, 정확도와 속도 간의 균형을 맞추는 방법을 제안합니다. 주요 기능으로는 기본 트랜스크립션, SRT/VTT/JSON 형식의 트랜스크립트 생성, 프레임 정확도 타이밍 동기화를 위한 ffmpeg 오디오 추출, pyannote.audio를 사용한 화자 분리, 그리고 여러 파일을 일괄 처리하는 배치 스크립트가 포함됩니다. 이 스킬은 Claude Code, Cursor, Codex와 같은 AI 에이전트 플랫폼에서 작업하며, 최종 편집을 위한 정확한 자막과 트랜스크립트가 필요한 비디오 편집자, 콘텐츠 제작자, 자동화 파이프라인에 특히 유용합니다.

지원 대상✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/MadAppGang/claude-code/tree/HEAD/plugins/video-editing/skills/transcription

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

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

문서

plugin: video-editing updated: 2026-01-20

Whisper를 사용한 트랜스크립션

OpenAI Whisper를 사용한 오디오/비디오 트랜스크립션을 위한 프로덕션 준비 패턴입니다.

시스템 요구 사항

설치 옵션

옵션 1: OpenAI Whisper (Python)

# macOS/Linux/Windows
pip install openai-whisper

# 확인
whisper --help

옵션 2: whisper.cpp (C++ - 더 빠름)

# macOS
brew install whisper-cpp

# Linux - 소스에서 빌드
git clone https://github.com/ggerganov/whisper.cpp
cd whisper.cpp && make

# Windows - 사전 빌드된 바이너리 사용 또는 cmake로 빌드

옵션 3: Insanely Fast Whisper (GPU 가속)

pip install insanely-fast-whisper

모델 선택

모델크기VRAM정확도속도사용 사례
tiny39M~1GB낮음가장 빠름빠른 미리보기
base74M~1GB중간빠름초안 트랜스크립트
small244M~2GB좋음중간일반 사용
medium769M~5GB더 좋음느림품질 트랜스크립트
large-v31550M~10GB최고가장 느림최종 프로덕션

권장 사항: 속도와 품질의 균형을 위해 small로 시작하세요. 최종 전달 시에는 large-v3를 사용하세요.

기본 트랜스크립션

OpenAI Whisper 사용

# 기본 트랜스크립션 (언어 자동 감지)
whisper audio.mp3 --model small

# 언어 및 출력 형식 지정
whisper audio.mp3 --model medium --language en --output_format srt

# 여러 출력 형식
whisper audio.mp3 --model small --output_format all

# 타임스탬프 및 단어 수준 타이밍 포함
whisper audio.mp3 --model small --word_timestamps True

whisper.cpp 사용

# 먼저 모델 다운로드
./models/download-ggml-model.sh base.en

# 트랜스크립션 수행
./main -m models/ggml-base.en.bin -f audio.wav -osrt

# 타임스탬프 포함
./main -m models/ggml-base.en.bin -f audio.wav -ocsv

출력 형식

SRT (SubRip Subtitle)

1
00:00:01,000 --> 00:00:04,500
Hello and welcome to this video.

2
00:00:05,000 --> 00:00:08,200
Today we'll discuss video editing.

VTT (WebVTT)

WEBVTT

00:00:01.000 --> 00:00:04.500
Hello and welcome to this video.

00:00:05.000 --> 00:00:08.200
Today we'll discuss video editing.

JSON (단어 수준 타이밍 포함)

{
  "text": "Hello and welcome to this video.",
  "segments": [
    {
      "id": 0,
      "start": 1.0,
      "end": 4.5,
      "text": " Hello and welcome to this video.",
      "words": [
        {"word": "Hello", "start": 1.0, "end": 1.3},
        {"word": "and", "start": 1.4, "end": 1.5},
        {"word": "welcome", "start": 1.6, "end": 2.0},
        {"word": "to", "start": 2.1, "end": 2.2},
        {"word": "this", "start": 2.3, "end": 2.5},
        {"word": "video", "start": 2.6, "end": 3.0}
      ]
    }
  ]
}

트랜스크립션을 위한 오디오 추출

비디오를 트랜스크립션하기 전에 최적의 형식으로 오디오를 추출하세요:

# 오디오를 WAV로 추출 (16kHz, 모노 - Whisper에 최적)
ffmpeg -i video.mp4 -ar 16000 -ac 1 -c:a pcm_s16le audio.wav

# 보관용 고품질 WAV로 추출
ffmpeg -i video.mp4 -vn -c:a pcm_s16le audio.wav

# 압축된 MP3로 추출 (더 작지만 여전히 작동)
ffmpeg -i video.mp4 -vn -c:a libmp3lame -q:a 2 audio.mp3

타이밍 동기화

Whisper JSON을 FCP 타이밍으로 변환

import json

def whisper_to_fcp_timing(whisper_json_path, fps=24):
    """Whisper JSON 출력을 FCP 호환 타이밍으로 변환합니다."""
    with open(whisper_json_path) as f:
        data = json.load(f)

    segments = []
    for seg in data.get("segments", []):
        segments.append({
            "start_time": seg["start"],
            "end_time": seg["end"],
            "start_frame": int(seg["start"] * fps),
            "end_frame": int(seg["end"] * fps),
            "text": seg["text"].strip(),
            "words": seg.get("words", [])
        })

    return segments

프레임 정확도 타이밍

# 정확한 프레임 수와 지속 시간 가져오기
ffprobe -v error -count_frames -select_streams v:0 \
  -show_entries stream=nb_read_frames,duration,r_frame_rate \
  -of json video.mp4

화자 분리

여러 화자가 있는 콘텐츠의 경우 pyannote.audio를 사용하세요:

pip install pyannote.audio
from pyannote.audio import Pipeline

pipeline = Pipeline.from_pretrained("pyannote/[email protected]")
diarization = pipeline("audio.wav")

for turn, _, speaker in diarization.itertracks(yield_label=True):
    print(f"{turn.start:.1f}s - {turn.end:.1f}s: {speaker}")

배치 처리

#!/bin/bash
# 디렉토리의 모든 비디오를 트랜스크립션합니다.

MODEL="small"
OUTPUT_DIR="transcripts"
mkdir -p "$OUTPUT_DIR"

for video in *.mp4 *.mov *.avi; do
  [[ -f "$video" ]] || continue

  base="${video%.*}"

  # 오디오 추출
  ffmpeg -i "$video" -ar 16000 -ac 1 -c:a pcm_s16le "/tmp/${base}.wav" -y

  # 트랜스크립션
  whisper "/tmp/${base}.wav" --model "$MODEL" \
    --output_format all \
    --output_dir "$OUTPUT_DIR"

  # 임시 오디오 정리
  rm "/tmp/${base}.wav"

  echo "트랜스크립션 완료: $video"
done

품질 최적화

정확도 향상

  1. 트랜스크립션 전 노이즈 감소:
ffmpeg -i noisy_audio.wav -af "highpass=f=200,lowpass=f=3000,afftdn=nf=-25" clean_audio.wav
  1. 언어 힌트 사용:
whisper audio.mp3 --language en --model medium
  1. 컨텍스트를 위한 초기 프롬프트 제공:
whisper audio.mp3 --initial_prompt "Technical discussion about video editing software."

성능 팁

  1. GPU 가속 (사용 가능한 경우):
whisper audio.mp3 --model large-v3 --device cuda
  1. 긴 비디오의 경우 청크로 처리:
# 10분 청크로 오디오 분할
# 각 청크 트랜스크립션
# 시간 오프셋 조정으로 결과 병합

오류 처리

# 트랜스크립션 전 오디오 파일 검증
validate_audio() {
  local file="$1"
  if ffprobe -v error -select_streams a:0 -show_entries stream=codec_type -of csv=p=0 "$file" 2>/dev/null | grep -q "audio"; then
    return 0
  else
    echo "오류: $file에서 오디오 스트림을 찾을 수 없습니다"
    return 1
  fi
}

# Whisper 설치 확인
check_whisper() {
  if command -v whisper &> /dev/null; then
    echo "Whisper 사용 가능"
    return 0
  else
    echo "오류: Whisper가 설치되지 않았습니다. 실행: pip install openai-whisper"
    return 1
  fi
}

관련 스킬

  • ffmpeg-core - 오디오 추출 및 전처리
  • final-cut-pro - 트랜스크립트를 타이틀/마커로 가져오기

관련 스킬