Communitygithub.com

YouTube 트랜스크립트 다운로더

사용자가 YouTube URL을 제공하거나 YouTube에서 트랜스크립트/자막을 다운로드/가져오라고 요청할 때 YouTube 동영상의 트랜스크립트를 다운로드합니다.

YouTube 트랜스크립트 다운로더란 무엇인가요?

이 스킬은 YouTube 동영상의 트랜스크립트(자막/캡션)를 다운로드하는 전문 도구입니다. 사용자가 YouTube URL을 제공하거나 '트랜스크립트 다운로드', '자막 가져오기', '동영상 트랜스크립션' 등을 요청할 때 활성화됩니다. yt-dlp를 기반으로 하며, 수동 자막(최고 품질), 자동 생성 자막(일반적으로 사용 가능), Whisper 음성 인식(최후의 수단) 순으로 우선순위를 두어 트랜스크립트를 추출합니다. Claude Code, Cursor, Codex 등 다양한 AI 에이전트 플랫폼에서 사용할 수 있습니다. 이 스킬은 먼저 yt-dlp 설치를 확인하고, 사용 가능한 자막을 나열한 후, 우선 순위에 따라 다운로드 전략을 실행합니다. 수동 또는 자동 자막이 없을 경우 사용자에게 동의를 구한 후 Whisper를 사용해 오디오를 다운로드하고 트랜스크립션합니다. 마지막으로 VTT 파일을 중복 제거된 일반 텍스트로 변환하여 최종 결과물을 제공합니다. 모든 단계에서 오류 처리가 포함되어 있으며, 사용자에게 명확한 피드백을 제공합니다.

지원 대상✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/IGTA-Tech/claude-skills-research/tree/HEAD/tapestry-skills-for-claude-code/youtube-transcript

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

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

문서

YouTube 트랜스크립트 다운로더은(는) 무엇을 하나요?

이 스킬은 yt-dlp를 사용하여 YouTube 동영상에서 트랜스크립트(자막/캡션)를 다운로드하는 데 도움을 줍니다.

이 스킬을 사용해야 하는 경우

다음과 같은 경우에 이 스킬을 활성화하세요:

  • 사용자가 YouTube URL을 제공하고 트랜스크립트를 원할 때
  • "YouTube에서 트랜스크립트 다운로드"를 요청할 때
  • 동영상에서 "캡션 가져오기" 또는 "자막 가져오기"를 원할 때
  • "YouTube 동영상 트랜스크립트"를 요청할 때
  • YouTube 동영상의 텍스트 콘텐츠가 필요할 때

작동 방식

우선 순위:

  1. yt-dlp 설치 확인 - 필요 시 설치
  2. 사용 가능한 자막 나열 - 실제로 무엇이 있는지 확인
  3. 수동 자막 먼저 시도 (--write-sub) - 최고 품질
  4. 자동 생성 자막으로 대체 (--write-auto-sub) - 일반적으로 사용 가능
  5. 최후의 수단: Whisper 트랜스크립션 - 자막이 없는 경우 (사용자 확인 필요)
  6. 다운로드 확인 및 파일 저장 위치를 사용자에게 표시
  7. 선택적으로 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('&amp;', '&').replace('&gt;', '>').replace('&lt;', '<')
            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('&amp;', '&').replace('&gt;', '>').replace('&lt;', '<')
            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('&amp;', '&').replace('&gt;', '>').replace('&lt;', '<')
            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 모델) 전에 사용자에게 물어보기
  • ✅ 처리 후 임시 파일 정리
  • ✅ 각 단계에서 무슨 일이 일어나고 있는지 명확한 피드백 제공
  • ✅ 오류를 우아하게 처리하고 도움이 되는 메시지 제공

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

IGTA-Tech/claude-skills-research

Use when localizing apps, using String Catalogs, generating type-safe symbols (Xcode 26+), handling plurals, RTL layouts, locale-aware formatting, or migrating from .strings files - comprehensive i18n patterns for Xcode 15-26

IGTA-Tech/claude-skills-research

Use when implementing SwiftUI animations, understanding VectorArithmetic, using @Animatable macro, choosing between spring and timing curve animations, or debugging animation behavior - comprehensive animation reference from iOS 13 through iOS 26

IGTA-Tech/claude-skills-research

Use when CAAnimation completion handler doesn't fire, spring physics look wrong on device, animation duration mismatches actual time, gesture + animation interaction causes jank, or timing differs between simulator and real hardware - systematic CAAnimation diagnosis with CATransaction patterns, frame rate awareness, and device-specific behavior

IGTA-Tech/claude-skills-research

This skill should be used when comparing two videos to analyze compression results or quality differences. Generates interactive HTML reports with quality metrics (PSNR, SSIM) and frame-by-frame visual comparisons. Triggers when users mention "compare videos", "video quality", "compression analysis", "before/after compression", or request quality assessment of compressed videos.

IGTA-Tech/claude-skills-research

Download YouTube videos and HLS streams (m3u8) from platforms like Mux, Vimeo, etc. using yt-dlp and ffmpeg. Use this skill when users request downloading videos, extracting audio, handling protected streams with authentication headers, or troubleshooting download issues like nsig extraction failures, 403 errors, or cookie extraction problems.

IGTA-Tech/claude-skills-research

Write high-converting landing page copy using proven frameworks like PAS (Problem-Agitate-Solution), AIDA, and StoryBrand. Creates headlines, value propositions, CTAs, and full page sections optimized for conversion. Use when users need landing page copy, sales page content, or marketing website text.

IGTA-Tech/claude-skills-research

Downloads videos from YouTube and other platforms for offline viewing, editing, or archival. Handles various formats and quality options.

관련 스킬