YouTube 다운로더
개요
yt-dlp와 ffmpeg을 사용하여 YouTube 및 HLS 스트리밍 플랫폼(Mux, Vimeo 등)에서 안정적인 비디오 및 오디오 다운로드를 지원합니다. 이 스킬은 다음 워크플로우를 제공합니다:
- PO 토큰 제공자 또는 브라우저 쿠키를 사용한 YouTube 다운로드(최대 4K)
- 인증 헤더가 있는 HLS 스트림 다운로드
- 보호된 콘텐츠 처리 및 일반적인 다운로드 실패 문제 해결
이 스킬을 사용해야 하는 경우
이 스킬은 사용자가 다음과 같은 경우에 호출되어야 합니다:
- YouTube 동영상 또는 재생 목록 다운로드를 요청하는 경우
- YouTube 동영상에서 오디오를 추출하려는 경우
- yt-dlp 다운로드 실패 또는 제한된 형식 가용성을 경험하는 경우
- 형식 선택 또는 품질 옵션에 대한 도움이 필요한 경우
- 저화질(360p) 형식만 사용 가능하다고 보고하는 경우
- 특정 품질(1080p, 4K 등)로 YouTube 콘텐츠 다운로드에 대해 문의하는 경우
- 다운로드한 WebM 비디오를 더 넓은 호환성을 위해 MP4 형식으로 변환해야 하는 경우
- Mux, Vimeo 또는 기타 스트리밍 서비스와 같은 플랫폼에서 HLS 스트림(m3u8) 다운로드를 요청하는 경우
- 인증 헤더가 필요한 보호된 스트림을 다운로드해야 하는 경우
전제 조건
1. yt-dlp 설치 확인
which yt-dlp
yt-dlp --version
설치되지 않았거나 오래된 경우(< 2025.10.22):
brew upgrade yt-dlp # macOS
# 또는
pip install --upgrade yt-dlp # 크로스 플랫폼
중요: 오래된 yt-dlp 버전은 nsig 추출 실패 및 형식 누락을 유발합니다.
2. 현재 품질 액세스 확인
다운로드 전에 사용 가능한 형식을 확인하세요:
yt-dlp -F "https://youtu.be/VIDEO_ID"
형식 18(360p)만 나타나는 경우: 고품질 액세스를 위해 PO 토큰 제공자 설정이 필요합니다.
고품질 다운로드 워크플로우
1단계: PO 토큰 제공자 설치 (일회성 설정)
1080p/1440p/4K 액세스를 위해 yt-dlp의 Python 환경에 PO 토큰 제공자 플러그인을 설치하세요:
# yt-dlp의 Python 경로 찾기
head -1 $(which yt-dlp)
# 플러그인 설치 (yt-dlp 버전에 맞게 경로 조정)
/opt/homebrew/Cellar/yt-dlp/$(yt-dlp --version)/libexec/bin/python -m pip install bgutil-ytdlp-pot-provider
확인: yt-dlp -F "VIDEO_URL"을 다시 실행하세요. 형식 137(1080p), 271(1440p) 또는 313(4K)를 찾습니다.
자세한 설정 지침 및 문제 해결은 references/po-token-setup.md를 참조하세요.
2단계: 최고 품질로 다운로드
PO 토큰 제공자가 설치되면:
# 최고 품질(최대 1080p) 다운로드
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
# 사용 가능한 최고 품질 다운로드(4K 사용 가능한 경우)
yt-dlp -f "bestvideo+bestaudio/best" "VIDEO_URL"
3단계: 다운로드 품질 확인
# 비디오 해상도 확인
ffprobe -v error -select_streams v:0 -show_entries stream=width,height,codec_name -of default=noprint_wrappers=1 video.mp4
1080p에 대한 예상 출력:
codec_name=vp9
width=1920
height=1080
대안: 브라우저 쿠키 방법
PO 토큰 제공자 설정이 문제가 있는 경우 브라우저 쿠키를 사용하세요:
# Firefox
yt-dlp --cookies-from-browser firefox -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
# Chrome
yt-dlp --cookies-from-browser chrome -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"
이점: 연령 제한 및 회원 전용 콘텐츠에 액세스할 수 있습니다. 요구 사항: 지정된 브라우저에서 YouTube에 로그인되어 있어야 합니다.
일반적인 작업
오디오 전용 다운로드
MP3로 오디오 추출:
yt-dlp -x --audio-format mp3 "VIDEO_URL"
사용자 지정 출력 디렉토리
yt-dlp -P ~/Downloads/YouTube "VIDEO_URL"
자막과 함께 다운로드
yt-dlp --write-subs --sub-lang en "VIDEO_URL"
재생 목록 다운로드
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "PLAYLIST_URL"
WebM을 MP4로 변환
YouTube 고품질 다운로드는 종종 WebM 형식(VP9 코덱)을 사용합니다. 더 넓은 호환성을 위해 MP4로 변환하세요:
# ffmpeg 설치 확인
which ffmpeg || brew install ffmpeg # macOS
# 좋은 품질 설정으로 WebM을 MP4로 변환
ffmpeg -i "video.webm" -c:v libx264 -preset medium -crf 23 -c:a aac -b:a 128k "video.mp4"
매개변수 설명:
-c:v libx264: H.264 비디오 코덱 사용(광범위하게 호환 가능)-preset medium: 인코딩 속도와 파일 크기 간의 균형-crf 23: 품질을 위한 Constant Rate Factor(18-28 범위, 낮을수록 더 나은 품질)-c:a aac: AAC 오디오 코덱 사용-b:a 128k: 오디오 비트레이트 128kbps
팁: 변환은 1080p 해상도를 유지하며 최신 하드웨어에서 약 6배의 인코딩 속도를 제공합니다.
문제 해결 빠른 참조
360p(형식 18)만 사용 가능한 경우
원인: PO 토큰 제공자 누락 또는 오래된 yt-dlp.
해결 방법:
- yt-dlp 업데이트:
brew upgrade yt-dlp - PO 토큰 제공자 설치(위 1단계 참조)
- 또는 브라우저 쿠키 방법 사용
nsig 추출 실패
증상:
WARNING: [youtube] nsig extraction failed: Some formats may be missing
해결 방법:
- yt-dlp를 최신 버전으로 업데이트
- PO 토큰 제공자 설치
- 여전히 실패하면 Android 클라이언트 사용:
yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"
느린 다운로드 또는 네트워크 오류
중국 또는 제한적인 프록시 뒤에 있는 사용자의 경우:
- 네트워크 상태로 인해 다운로드가 느릴 수 있음
- 완료될 때까지 충분한 시간 허용
- yt-dlp는 일시적인 실패 시 자동으로 재시도
PO 토큰 경고(무해)
WARNING: android client https formats require a GVS PO Token
조치: 다운로드가 성공하면 무시하세요. 이는 Android 클라이언트가 PO 토큰 없이 제한된 형식 액세스를 가지고 있음을 나타냅니다.
번들 스크립트 참조
scripts/download_video.py
기본적으로 Android 클라이언트 해결 방법을 적용하는 편리한 래퍼:
기본 사용법:
scripts/download_video.py "VIDEO_URL"
인수:
url- YouTube 비디오 URL(필수)-o, --output-dir- 출력 디렉토리-f, --format- 형식 지정-a, --audio-only- MP3로 오디오 추출-F, --list-formats- 사용 가능한 형식 나열--no-android-client- Android 클라이언트 해결 방법 비활성화
참고: 이 스크립트는 Android 클라이언트를 사용합니다(PO 토큰 없이 360p만). 고품질을 위해서는 PO 토큰 제공자와 함께 yt-dlp를 직접 사용하세요.
품질 기대치
| 설정 | 360p | 720p | 1080p | 1440p | 4K |
|---|---|---|---|---|---|
| 설정 없음(기본값) | ✗ | ✗ | ✗ | ✗ | ✗ |
| Android 클라이언트만 | ✓ | ✗ | ✗ | ✗ | ✗ |
| PO 토큰 제공자 | ✓ | ✓ | ✓ | ✓ | ✓ |
| 브라우저 쿠키 | ✓ | ✓ | ✓ | ✓ | ✓ |
HLS 스트림 다운로드(m3u8)
Mux, Vimeo 및 기타 HLS 기반 서비스와 같은 스트리밍 플랫폼의 경우 기본 도구로 ffmpeg를 사용하세요. 이러한 스트림에는 yt-dlp가 올바르게 처리하지 못할 수 있는 인증 헤더가 필요한 경우가 많습니다.
HLS 스트림 식별
HLS 스트림은 .m3u8 재생 목록 파일을 사용합니다:
- 마스터 재생 목록: 여러 품질 옵션 나열
- 렌디션 재생 목록: 실제 비디오/오디오 세그먼트 URL 포함
다운로드 워크플로우
1단계: 스트림 URL 얻기
비디오 소스에서 m3u8 URL을 가져옵니다. 보호된 스트림의 경우:
- 브라우저 DevTools → 네트워크 탭 열기
- 비디오 재생
- "m3u8" 필터링하여 재생 목록 URL 찾기
- 렌디션 URL 복사(일반적으로 "rendition.m3u8"와 같은 품질 정보 포함)
2단계: 필수 헤더 식별
많은 CDN에 인증 헤더가 필요합니다:
- Referer: 원본 웹사이트(예:
https://maven.com/) - Origin: CORS를 위해 Referer와 동일
- User-Agent: 브라우저 식별
네트워크 탭에서 브라우저가 보내는 헤더를 확인하세요.
3단계: ffmpeg로 다운로드
보호된 스트림의 경우 -headers 플래그와 함께 ffmpeg를 사용하세요:
ffmpeg -headers "Referer: https://example.com/" \
-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
-i "https://cdn.example.com/path/rendition.m3u8?params" \
-c copy -bsf:a aac_adtstoasc \
output.mp4
주요 매개변수:
-headers: HTTP 헤더 설정(인증에 중요)-protocol_whitelist: HLS에 필요한 프로토콜 활성화-c copy: 스트림 복사(재인코딩 없음, 더 빠름)-bsf:a aac_adtstoasc: AAC 오디오 호환성 수정
일반적인 헤더 패턴:
# 단일 헤더
-headers "Referer: https://example.com/"
# 여러 헤더
-headers "Referer: https://example.com/" \
-headers "User-Agent: Mozilla/5.0..."
# 대체 구문
-headers $'Referer: https://example.com/\r\nUser-Agent: Mozilla/5.0...'
별도의 오디오/비디오 스트림 처리
일부 플랫폼(예: Mux)은 오디오와 비디오를 별도로 제공합니다:
- 오디오 스트림 다운로드:
ffmpeg -headers "Referer: https://example.com/" \
-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
-i "https://cdn.example.com/audio/rendition.m3u8" \
-c copy audio.m4a
- 비디오 스트림 다운로드:
ffmpeg -headers "Referer: https://example.com/" \
-protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy \
-i "https://cdn.example.com/video/rendition.m3u8" \
-c copy video.mp4
- 스트림 병합:
ffmpeg -i video.mp4 -i audio.m4a -c copy merged.mp4
HLS 다운로드 문제 해결
403 Forbidden 오류
원인: 인증 헤더 누락 또는 잘못됨.
해결 방법:
- Referer 헤더가 비디오 소스 웹사이트와 일치하는지 확인
- 추가 헤더(Origin, User-Agent)가 필요한지 확인
- m3u8 URL에 브라우저의 모든 쿼리 매개변수가 포함되어 있는지 확인
yt-dlp가 쿠키 추출에서 멈춤
증상: Extracting cookies from chrome이 무기한 중단됩니다.
해결 방법: HLS 스트림의 경우 yt-dlp 대신 ffmpeg를 직접 사용하세요.
프로토콜이 허용 목록에 없음
오류: Protocol 'https' not on whitelist 'file,crypto,data'
해결 방법: -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy 추가
빈 세그먼트 또는 스트림 없음
원인: m3u8 URL의 만료된 서명.
해결 방법:
- 브라우저 DevTools에서 새 URL 가져오기
- URL 획득 후 즉시 다운로드
- 업데이트된 서명 매개변수가 있는 렌디션 URL 찾기
성능 팁
- HLS 다운로드는 일반적으로 실시간 속도의 10-15배로 실행됨
-c copy로 재인코딩 없음(가장 빠름)- 실시간 진행률 표시로 다운로드 모니터링
- 디렉토리 혼동을 피하기 위해 절대 출력 경로 사용
추가 자료
- PO 토큰 설정: 자세한 설치 및 문제 해결은
references/po-token-setup.md참조 - yt-dlp 문서: https://github.com/yt-dlp/yt-dlp
- 형식 선택 가이드: https://github.com/yt-dlp/yt-dlp#format-selection