YouTube 트랜스크립트 다운로더은(는) 무엇을 하나요?
이 스킬은 yt-dlp를 사용하여 YouTube 동영상에서 트랜스크립트(자막/캡션)를 다운로드하는 데 도움을 줍니다.
이 스킬을 사용해야 하는 경우
다음과 같은 경우에 이 스킬을 활성화하세요:
- 사용자가 YouTube URL을 제공하고 트랜스크립트를 원할 때
- "YouTube에서 트랜스크립트 다운로드"를 요청할 때
- 동영상에서 "캡션 가져오기" 또는 "자막 가져오기"를 원할 때
- "YouTube 동영상 트랜스크립트"를 요청할 때
- YouTube 동영상의 텍스트 콘텐츠가 필요할 때
작동 방식
우선 순위:
- yt-dlp 설치 확인 - 필요 시 설치
- 사용 가능한 자막 나열 - 실제로 무엇이 있는지 확인
- 수동 자막 먼저 시도 (
--write-sub) - 최고 품질 - 자동 생성 자막으로 대체 (
--write-auto-sub) - 일반적으로 사용 가능 - 최후의 수단: Whisper 트랜스크립션 - 자막이 없는 경우 (사용자 확인 필요)
- 다운로드 확인 및 파일 저장 위치를 사용자에게 표시
- 선택적으로 VTT 형식 정리 - 사용자가 일반 텍스트를 원하는 경우
설치 확인
중요: 항상 yt-dlp가 설치되어 있는지 먼저 확인하세요:
which yt-dlp || command -v yt-dlp
설치되지 않은 경우
시스템에 따라 자동 설치를 시도합니다:
macOS (Homebrew):
brew install yt-dlp
Linux (apt/Debian/Ubuntu):
sudo apt update && sudo apt install -y yt-dlp
대체 방법 (pip - 모든 시스템에서 작동):
pip3 install yt-dlp
# 또는
python3 -m pip install yt-dlp
설치 실패 시: 사용자에게 yt-dlp를 수동으로 설치해야 한다고 알리고 https://github.com/yt-dlp/yt-dlp#installation 에서 설치 지침을 제공하세요.
사용 가능한 자막 확인
항상 다운로드 시도 전에 먼저 이 작업을 수행하세요:
yt-dlp --list-subs "YOUTUBE_URL"
이 명령은 아무것도 다운로드하지 않고 어떤 자막 유형이 있는지 보여줍니다. 다음을 확인하세요:
- 수동 자막 (더 나은 품질)
- 자동 생성 자막 (일반적으로 사용 가능)
- 사용 가능한 언어
다운로드 전략
옵션 1: 수동 자막 (권장)
이것을 먼저 시도하세요 - 최고 품질, 사람이 만든 것:
yt-dlp --write-sub --skip-download --output "OUTPUT_NAME" "YOUTUBE_URL"
옵션 2: 자동 생성 자막 (대체)
수동 자막을 사용할 수 없는 경우:
yt-dlp --write-auto-sub --skip-download --output "OUTPUT_NAME" "YOUTUBE_URL"
두 명령 모두 .vtt 파일(WebVTT 자막 형식)을 생성합니다.
옵션 3: Whisper 트랜스크립션 (최후의 수단)
수동 및 자동 생성 자막을 모두 사용할 수 없는 경우에만 사용하세요.
1단계: 파일 크기 표시 및 확인 요청
# 오디오 파일 크기 예상 값 가져오기
yt-dlp --print "%(filesize,filesize_approx)s" -f "bestaudio" "YOUTUBE_URL"
# 또는 길이를 가져와 예상
yt-dlp --print "%(duration)s %(title)s" "YOUTUBE_URL"
중요: 파일 크기를 사용자에게 표시하고 다음과 같이 질문하세요: "사용 가능한 자막이 없습니다. 오디오(약 X MB)를 다운로드하여 Whisper로 트랜스크립션할 수 있습니다. 계속하시겠습니까?"
계속하기 전에 사용자 확인을 기다리세요.
2단계: Whisper 설치 확인
command -v whisper
설치되지 않은 경우, 사용자에게 문의하세요: "Whisper가 설치되지 않았습니다. pip install openai-whisper로 설치하시겠습니까? (모델에 약 1-3GB 필요) 일회성 설치입니다."
설치 전에 사용자 확인을 기다리세요.
승인되면 설치:
pip3 install openai-whisper
3단계: 오디오만 다운로드
yt-dlp -x --audio-format mp3 --output "audio_%(id)s.%(ext)s" "YOUTUBE_URL"
4단계: Whisper로 트랜스크립션
# 언어 자동 감지 (권장)
whisper audio_VIDEO_ID.mp3 --model base --output_format vtt
# 또는 언어를 알고 있으면 지정
whisper audio_VIDEO_ID.mp3 --model base --language en --output_format vtt
모델 옵션 (지금은 base 사용):
tiny- 가장 빠름, 정확도 낮음 (~1GB)base- 좋은 균형 (~1GB) ← 이것 사용small- 더 나은 정확도 (~2GB)medium- 매우 좋음 (~5GB)large- 최고 정확도 (~10GB)
5단계: 정리
트랜스크립션이 완료된 후 사용자에게 문의하세요: "트랜스크립션이 완료되었습니다! 공간을 절약하기 위해 오디오 파일을 삭제할까요?"
예인 경우:
rm audio_VIDEO_ID.mp3
동영상 정보 가져오기
동영상 제목 추출 (파일 이름용)
yt-dlp --print "%(title)s" "YOUTUBE_URL"
이 정보를 사용하여 동영상 제목을 기반으로 의미 있는 파일 이름을 만드세요. 파일 시스템 호환성을 위해 제목을 정리하세요:
/를-로 바꾸기- 문제를 일으킬 수 있는 특수 문자 바꾸기
- 정리된 버전 사용 고려:
$(yt-dlp --print "%(title)s" "URL" | tr '/' '-' | tr ':' '-')
후처리
일반 텍스트로 변환 (권장)
YouTube의 자동 생성 VTT 파일에는 중복 줄이 포함되어 있습니다. 캡션이 겹치는 타임스탬프와 함께 점진적으로 표시되기 때문입니다. 일반 텍스트로 변환할 때 항상 중복을 제거하고 원래 말하는 순서를 유지하세요.
python3 -c "
import sys, re
seen = set()
with open('transcript.en.vtt', 'r') as f:
for line in f:
line = line.strip()
if line and not line.startswith('WEBVTT') and not line.startswith('Kind:') and not line.startswith('Language:') and '-->' not in line:
clean = re.sub('<[^>]*>', '', line)
clean = clean.replace('&', '&').replace('>', '>').replace('<', '<')
if clean and clean not in seen:
print(clean)
seen.add(clean)
" > transcript.txt
동영상 제목을 포함한 전체 후처리
# 동영상 제목 가져오기
VIDEO_TITLE=$(yt-dlp --print "%(title)s" "YOUTUBE_URL" | tr '/' '_' | tr ':' '-' | tr '?' '' | tr '"' '')
# VTT 파일 찾기
VTT_FILE=$(ls *.vtt | head -n 1)
# 중복 제거하여 변환
python3 -c "
import sys, re
seen = set()
with open('$VTT_FILE', 'r') as f:
for line in f:
line = line.strip()
if line and not line.startswith('WEBVTT') and not line.startswith('Kind:') and not line.startswith('Language:') and '-->' not in line:
clean = re.sub('<[^>]*>', '', line)
clean = clean.replace('&', '&').replace('>', '>').replace('<', '<')
if clean and clean not in seen:
print(clean)
seen.add(clean)
" > "${VIDEO_TITLE}.txt"
echo "✓ 저장 위치: ${VIDEO_TITLE}.txt"
# VTT 파일 정리
rm "$VTT_FILE"
echo "✓ 임시 VTT 파일 정리 완료"
출력 형식
- VTT 형식 (
.vtt): 타임스탬프와 서식 포함, 비디오 플레이어에 적합 - 일반 텍스트 (
.txt): 텍스트 내용만, 읽기 또는 분석에 적합
팁
- 파일 이름은
{output_name}.{language_code}.vtt형식입니다 (예:transcript.en.vtt) - 대부분의 YouTube 동영상에는 자동 생성 영어 자막이 있습니다
- 일부 동영상에는 여러 언어 옵션이 있을 수 있습니다
- 자동 자막을 사용할 수 없는 경우 수동 자막을 위해
--write-sub를 대신 시도하세요
전체 워크플로 예제
VIDEO_URL="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# 파일 이름을 위한 동영상 제목 가져오기
VIDEO_TITLE=$(yt-dlp --print "%(title)s" "$VIDEO_URL" | tr '/' '_' | tr ':' '-' | tr '?' '' | tr '"' '')
OUTPUT_NAME="transcript_temp"
# ============================================
# 1단계: yt-dlp 설치 확인
# ============================================
if ! command -v yt-dlp &> /dev/null; then
echo "yt-dlp를 찾을 수 없습니다. 설치를 시도합니다..."
if command -v brew &> /dev/null; then
brew install yt-dlp
elif command -v apt &> /dev/null; then
sudo apt update && sudo apt install -y yt-dlp
else
pip3 install yt-dlp
fi
fi
# ============================================
# 2단계: 사용 가능한 자막 나열
# ============================================
echo "사용 가능한 자막을 확인하는 중..."
yt-dlp --list-subs "$VIDEO_URL"
# ============================================
# 3단계: 수동 자막 먼저 시도
# ============================================
echo "수동 자막 다운로드 시도 중..."
if yt-dlp --write-sub --skip-download --output "$OUTPUT_NAME" "$VIDEO_URL" 2>/dev/null; then
echo "✓ 수동 자막이 성공적으로 다운로드되었습니다!"
ls -lh ${OUTPUT_NAME}.*
else
# ============================================
# 4단계: 자동 생성 자막으로 대체
# ============================================
echo "수동 자막을 사용할 수 없습니다. 자동 생성 자막을 시도합니다..."
if yt-dlp --write-auto-sub --skip-download --output "$OUTPUT_NAME" "$VIDEO_URL" 2>/dev/null; then
echo "✓ 자동 생성 자막이 성공적으로 다운로드되었습니다!"
ls -lh ${OUTPUT_NAME}.*
else
# ============================================
# 5단계: 최후의 수단 - Whisper 트랜스크립션
# ============================================
echo "⚠ 이 동영상에 사용 가능한 자막이 없습니다."
# 파일 크기 가져오기
FILE_SIZE=$(yt-dlp --print "%(filesize_approx)s" -f "bestaudio" "$VIDEO_URL")
DURATION=$(yt-dlp --print "%(duration)s" "$VIDEO_URL")
TITLE=$(yt-dlp --print "%(title)s" "$VIDEO_URL")
echo "동영상: $TITLE"
echo "길이: $((DURATION / 60)) 분"
echo "오디오 크기: ~$((FILE_SIZE / 1024 / 1024)) MB"
echo ""
echo "Whisper로 다운로드 및 트랜스크립션하시겠습니까? (y/n)"
read -r RESPONSE
if [[ "$RESPONSE" =~ ^[Yy]$ ]]; then
# Whisper 확인
if ! command -v whisper &> /dev/null; then
echo "Whisper가 설치되지 않았습니다. 지금 설치하시겠습니까? (약 1-3GB 필요) (y/n)"
read -r INSTALL_RESPONSE
if [[ "$INSTALL_RESPONSE" =~ ^[Yy]$ ]]; then
pip3 install openai-whisper
else
echo "Whisper 없이는 진행할 수 없습니다. 종료합니다."
exit 1
fi
fi
# 오디오 다운로드
echo "오디오 다운로드 중..."
yt-dlp -x --audio-format mp3 --output "audio_%(id)s.%(ext)s" "$VIDEO_URL"
# 실제 오디오 파일 이름 가져오기
AUDIO_FILE=$(ls audio_*.mp3 | head -n 1)
# 트랜스크립션
echo "Whisper로 트랜스크립션 중 (몇 분 정도 소요될 수 있음)..."
whisper "$AUDIO_FILE" --model base --output_format vtt
# 정리
echo "트랜스크립션이 완료되었습니다! 오디오 파일을 삭제할까요? (y/n)"
read -r CLEANUP_RESPONSE
if [[ "$CLEANUP_RESPONSE" =~ ^[Yy]$ ]]; then
rm "$AUDIO_FILE"
echo "오디오 파일이 삭제되었습니다."
fi
ls -lh *.vtt
else
echo "트랜스크립션이 취소되었습니다."
exit 0
fi
fi
fi
# ============================================
# 6단계: 중복 제거하여 읽기 쉬운 일반 텍스트로 변환
# ============================================
VTT_FILE=$(ls ${OUTPUT_NAME}*.vtt 2>/dev/null || ls *.vtt | head -n 1)
if [ -f "$VTT_FILE" ]; then
echo "읽기 쉬운 형식으로 변환하고 중복 제거 중..."
python3 -c "
import sys, re
seen = set()
with open('$VTT_FILE', 'r') as f:
for line in f:
line = line.strip()
if line and not line.startswith('WEBVTT') and not line.startswith('Kind:') and not line.startswith('Language:') and '-->' not in line:
clean = re.sub('<[^>]*>', '', line)
clean = clean.replace('&', '&').replace('>', '>').replace('<', '<')
if clean and clean not in seen:
print(clean)
seen.add(clean)
" > "${VIDEO_TITLE}.txt"
echo "✓ 저장 위치: ${VIDEO_TITLE}.txt"
# 임시 VTT 파일 정리
rm "$VTT_FILE"
echo "✓ 임시 VTT 파일 정리 완료"
else
echo "⚠ 변환할 VTT 파일을 찾을 수 없습니다"
fi
echo "✓ 완료!"
참고: 이 전체 워크플로는 각 결정 지점에서 적절한 오류 검사와 사용자 프롬프트를 통해 모든 시나리오를 처리합니다.
오류 처리
일반적인 문제 및 해결 방법:
1. yt-dlp가 설치되지 않음
- 시스템에 따라 자동 설치 시도 (Homebrew/apt/pip)
- 설치 실패 시 수동 설치 링크 제공
- 진행 전 설치 확인
2. 자막을 사용할 수 없음
- 먼저 사용 가능한 자막을 나열하여 확인
--write-sub와--write-auto-sub모두 시도- 둘 다 실패하면 Whisper 트랜스크립션 옵션 제공
- 오디오 다운로드 전 파일 크기 표시 및 사용자 확인 요청
3. 잘못되었거나 비공개 동영상
- URL 형식이 올바른지 확인:
https://www.youtube.com/watch?v=VIDEO_ID - 일부 동영상은 비공개, 연령 제한 또는 지역 차단될 수 있음
- yt-dlp의 특정 오류 메시지를 사용자에게 전달
4. Whisper 설치 실패
- 시스템 종속성(ffmpeg, rust)이 필요할 수 있음
- 대체 방법 제공: "수동으로 설치:
pip3 install openai-whisper" - 사용 가능한 디스크 공간 확인 (모델 크기에 따라 1-10GB 필요)
5. 다운로드 중단 또는 실패
- 인터넷 연결 확인
- 충분한 디스크 공간 확인
- SSL 문제 발생 시
--no-check-certificate로 다시 시도
6. 여러 자막 언어
- 기본적으로 yt-dlp는 모든 사용 가능한 언어를 다운로드
--sub-langs en으로 영어만 지정 가능- 먼저
--list-subs로 사용 가능한 언어 나열
모범 사례:
- ✅ 항상 다운로드 시도 전에 무엇이 가능한지 확인 (
--list-subs) - ✅ 각 단계의 성공을 확인한 후 다음 단계로 진행
- ✅ 대용량 다운로드(오디오 파일, Whisper 모델) 전에 사용자에게 물어보기
- ✅ 처리 후 임시 파일 정리
- ✅ 각 단계에서 무슨 일이 일어나고 있는지 명확한 피드백 제공
- ✅ 오류를 우아하게 처리하고 도움이 되는 메시지 제공