YouTube 다운로더
개요
yt-dlp와 ffmpeg를 사용하여 YouTube 및 HLS 스트리밍 플랫폼(Mux, Vimeo 등)에서 동영상과 오디오를 안정적으로 다운로드할 수 있습니다. 이 스킬은 다음 워크플로우를 제공합니다.
- PO 토큰 공급자 또는 브라우저 쿠키를 사용한 YouTube 다운로드(최대 4K)
- 인증 헤더가 포함된 HLS 스트림 다운로드
- 보호된 콘텐츠 처리 및 일반적인 다운로드 실패 문제 해결
비기술적 사용자 경험 (기본값)
사용자가 비기술적이라고 가정합니다. 사용자에게 명령어를 실행하도록 요청하지 마십시오. 모든 작업을 직접 수행하고 진행 상황을 평이한 언어로 보고합니다. 사용자가 묻지 않는 한 도구에 대해 언급하지 마십시오.
기본 흐름:
- URL을 묻습니다(제공되지 않은 경우).
- 동영상 메타데이터(제목/업로더/길이/썸네일)를 가져와 사용자의 의도와 일치하는지 확인합니다.
- yt-dlp가 "confirm you’re not a bot"으로 차단된 경우, 제목/업로더/썸네일을 위해 YouTube oEmbed로 대체합니다(길이는 알 수 없을 수 있음).
- 간단한 선택 항목을 제공합니다(동영상 vs 오디오 전용, 화질, 자막, 저장 위치).
- 사용자가 지정하지 않은 경우 합리적인 기본값으로 진행합니다.
- 최고 화질의 동영상 다운로드
- MP4 병합 출력
- 단일 동영상만(재생 목록 없음)
- 다운로드하여 최종 파일 경로, 파일 크기, 해상도(동영상인 경우)를 보고합니다.
사용자 친화적인 용어로 선택 항목 제공:
- "최고 화질로 동영상 다운로드 (기본값)"
- "오디오만 다운로드 (MP3)"
- "화질 선택: 1080p / 720p / 480p / 360p"
- "자막 포함 (가능한 경우)"
- "다운로드 폴더에 저장 (기본값) 또는 다른 폴더를 알려주세요"
가능하면 항상 썸네일을 렌더링합니다:
- 메타데이터에 썸네일 URL이 포함된 경우 Markdown 이미지 구문을 사용하여 포함합니다:
.
추가 작업 전에 물어보십시오:
- 재생 목록 다운로드 확인 (용량이 클 수 있음).
- 의존성 설치/업그레이드가 필요한 경우 확인.
- 브라우저 쿠키 추출 전에 물어보십시오.
- 쿠키를 사용하는 경우, 사용자 대상 응답에 쿠키 개수나 원시 쿠키 세부 정보를 절대 언급하지 마십시오. "사용자의 Chrome 로그인 세션을 사용했습니다"라고 말합니다.
- 인증이 필요한 경우 자동으로 로컬 PO 토큰 도우미를 설정합니다(사용자 작업 불필요). Docker가 없거나 실패하면 Docker 설치를 시도하지 말고 브라우저 기반 PO 토큰 공급자로 전환합니다.
법적/안전 알림 (간략):
- 사용자가 콘텐츠를 다운로드할 권리나 허가가 있는 경우에만 진행합니다.
응답 템플릿 (명령어 없이 평이한 언어 사용):

제목: ...
채널: ...
길이: ...
다음을 도와드릴 수 있습니다:
1) 동영상 다운로드 (최고 화질, MP4)
2) 오디오만 다운로드 (MP3)
3) 특정 화질 선택 (1080p/720p/480p/360p)
4) 자막 포함 (가능한 경우)
어디에 저장할까요? (기본값: 다운로드 폴더)
사용자가 "그냥 다운로드"라고 말하면:
- 기본값으로 진행하고 다운로드가 완료되면 확인합니다.
- 403 오류로 차단된 경우 자동으로 인증 도우미를 설정하고 다시 시도합니다.
안정적인 다운로드 SOP (내부)
일반적인 오류와 혼동을 피하려면 이 SOP를 따르십시오.
- 셸 명령어에서 URL을 따옴표로 묶습니다(zsh는
?를 glob으로 처리함). 예:'https://www.youtube.com/watch?v=VIDEO_ID'. - yt-dlp와 PO 토큰 공급자 모두에 대해 프록시가 활성화되어 있는지 확인합니다(HTTP_PROXY/HTTPS_PROXY/ALL_PROXY).
- "Sign in to confirm you’re not a bot"이 표시되면 권한을 요청하고 브라우저 쿠키를 사용합니다. 쿠키 없이 진행하지 마십시오.
- 다운로드 전에 PO 토큰 공급자를 시작합니다(시작할 수 없으면 빠르게 실패).
- 사용 가능한 경우 Docker bgutil 공급자를 사용합니다.
- Docker가 없거나 실패하면 브라우저 기반 WPC 공급자로 전환합니다.
- 쿠키를 사용하는 경우
web_safari플레이어 클라이언트를 선호합니다. 그렇지 않으면 PO 토큰에 대해mweb를 선호합니다. - WPC가 토큰을 생성하는 동안 브라우저 창을 열어 둡니다. Chrome이 동일한 프록시를 통해 YouTube에 도달할 수 있는지 확인합니다.
- "Only images are available" 또는 "Requested format is not available"이 표시되면 PO 토큰 실패로 처리하고 토큰 공급자/브라우저 상태를 수정한 후 다시 시도합니다.
- SSL EOF 또는 조각 오류가 발생하면 프록시/네트워크 문제로 처리합니다. 프로그레시브 형식 및/또는 더 나은 프록시로 다시 시도합니다.
에이전트 실행 체크리스트 (내부)
scripts/download_video.py URL --info를 실행합니다(권한이 부여된 경우--cookies-from-browser chrome추가)하여 메타데이터와 썸네일을 가져옵니다.- yt-dlp 메타데이터가 실패하면 스크립트의 oEmbed 대체 기능을 사용하여 제목/업로더/썸네일을 가져오고 길이를 사용할 수 없을 수 있음을 알립니다.
- 썸네일 URL이 있으면 Markdown 이미지 구문을 사용하여 응답에 렌더링합니다.
- 사용자에게 동영상 또는 오디오 전용을 선택하도록 요청하고 (선택적으로) 화질 사전 설정을 요청합니다.
- 사용자가 폴더를 지정하지 않는 한 친숙한 기본 저장 위치(다운로드 폴더)를 사용합니다.
- 자막의 경우
--subtitles및 요청된--sub-lang와 함께 실행합니다. - 다운로드 후 파일 이름, 크기 및 해상도(동영상인 경우)를 평이한 언어로 보고합니다.
- 다운로드가 403/조각 오류로 실패하면 m3u8이 아닌 프로그레시브 형식으로 한 번 다시 시도합니다.
- "Sign in to confirm you’re not a bot"이 나타나면 쿠키 액세스를 요청하고 쿠키 +
web_safari로 다시 시도합니다. - "Only images are available"이 나타나면 PO 토큰 실패로 처리하고 공급자/브라우저 상태를 수정한 후 다시 시도합니다.
- 다운로드 전에 PO 토큰 공급자를 시작합니다(
--auto-po-token기본값). 시작할 수 없으면 빠르게 실패합니다. - Docker 기반 공급자가 실패하면(중국에서 흔함) 자동으로 브라우저 기반 WPC 공급자로 대체됩니다(브라우저 창이 잠시 열릴 수 있음).
- WPC 공급자를 사용하는 경우 다운로드가 시작될 때까지 브라우저 창을 열어 둡니다. 브라우저 실행에 실패하면 Chrome 경로를 명시적으로 설정합니다.
- PO 토큰 공급자가 시간 초과되면 한 번 다시 시작하고 다시 시도합니다.
- 시스템 프록시가 구성된 경우 공급자 컨테이너에 전달합니다. 프록시가 127.0.0.1/localhost를 가리키는 경우 Docker에서
host.docker.internal로 다시 작성합니다.
이 스킬을 사용하는 경우
사용자가 다음과 같은 경우 이 스킬을 호출해야 합니다.
- 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 경로 찾기(yt-dlp에서 사용하는 인터프리터)
head -1 $(which yt-dlp)
# 위 줄의 인터프리터를 사용하여 플러그인 설치
<YTDLP_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에 로그인되어 있어야 합니다.
- 브라우저와 yt-dlp가 동일한 IP/프록시를 사용해야 합니다.
- Android 클라이언트를 쿠키와 함께 사용하지 마십시오(Android 클라이언트는 쿠키를 지원하지 않음).
일반적인 작업
오디오 전용 다운로드 (직접 실행)
오디오를 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: 품질을 위한 상수 비율 계수 (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단계 참조)
- 또는 브라우저 쿠키 방법 사용
봇이 아님을 확인하려면 로그인
원인: YouTube에서 계속 진행하려면 인증이 필요합니다.
해결 방법:
- 권한을 요청하고 브라우저 쿠키를 사용합니다(
--cookies-from-browser chrome). - 브라우저와 yt-dlp가 동일한 IP/프록시를 사용하는지 확인합니다.
- 필요한 경우
web_safari클라이언트로 다시 시도합니다.
이미지만 사용 가능 / 요청한 형식을 사용할 수 없음
원인: PO 토큰이 적용되지 않았거나 공급자/브라우저 확인에 실패했습니다.
해결 방법:
- 다운로드 전에 PO 토큰 공급자가 실행 중인지 확인합니다.
- WPC를 사용하는 경우 브라우저 창을 열어 둡니다.
- 쿠키를 사용하는 경우
web_safari클라이언트를 선호하고 다시 시도합니다.
nsig 추출 실패
증상:
WARNING: [youtube] nsig extraction failed: Some formats may be missing
해결 방법:
- yt-dlp를 최신 버전으로 업데이트
- PO 토큰 공급자 설치
- 여전히 실패하고 PO 토큰이 비활성화된 경우 Android 클라이언트 사용:
yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"
SSL EOF / 조각 오류
원인: 프록시 또는 네트워크 불안정.
해결 방법:
- 프로그레시브 형식(m3u8 아님)으로 다시 시도합니다.
- 더 안정적인 프록시/노드로 전환합니다.
- 다운로드 중에 PO 토큰 브라우저 창을 닫지 마십시오.
느린 다운로드 또는 네트워크 오류
중국 또는 제한적인 프록시 뒤에 있는 사용자의 경우:
- 네트워크 상태로 인해 다운로드가 느릴 수 있습니다.
- 완료될 때까지 충분한 시간을 허용합니다.
- yt-dlp는 일시적인 오류에서 자동으로 재시도합니다.
PO 토큰 경고 (무해)
WARNING: android client https formats require a GVS PO Token
조치: 다운로드가 성공하면 무시합니다. 이는 Android 클라이언트가 PO 토큰 없이 제한된 형식 액세스를 가지고 있음을 나타냅니다.
번들 스크립트 참조
scripts/download_video.py
이 편리한 래퍼를 사용하여 고화질 다운로드를 위해 기본적으로 PO 토큰 공급자를 자동 시작합니다. 직접 사용하고 사용자에게 명령어를 실행하도록 요청하지 않고 결과를 보고합니다.
기본 사용법:
scripts/download_video.py "VIDEO_URL"
인수:
url- YouTube 동영상 URL (필수)-o, --output-dir- 출력 디렉토리--output-template- 출력 파일 이름 템플릿 (yt-dlp 구문)-f, --format- 형식 지정-q, --quality- 화질 사전 설정 (best, 1080p, 720p, 480p, 360p, worst). 기본값: best (--audio-only의 경우 건너뜀)-a, --audio-only- 오디오를 MP3로 추출--subtitles- 가능한 경우 자막 다운로드--sub-lang- 자막 언어 (쉼표로 구분, 기본값: en)--cookies-from-browser- 브라우저에서 쿠키 로드 (예: chrome, firefox)--cookies-file- cookies.txt 파일에서 쿠키 로드--player-client- 특정 YouTube 플레이어 클라이언트 사용 (예: web_safari)--auto-po-token- PO 토큰 공급자 자동 시작 (기본값; 가능하면 Docker 사용, 그렇지 않으면 브라우저 기반 공급자로 전환)--no-auto-po-token- 자동 PO 토큰 설정 비활성화--proxy- yt-dlp 및 PO 토큰 공급자를 위한 프록시 URL (예: http://127.0.0.1:1082)--wpc-browser-path- WPC 공급자를 위한 브라우저 실행 파일 경로-F, --list-formats- 사용 가능한 형식 나열--merge-format- 출력 컨테이너 병합 (예: mp4, mkv). 기본값: mp4--playlist- 재생 목록 다운로드 허용 (기본값: 단일 동영상만)--info- 제목/업로더/길이/썸네일을 출력하고 종료--no-android-client- Android 클라이언트 대체 비활성화
참고: PO 토큰이 비활성화된 경우에만 Android 클라이언트를 사용하십시오. 고화질을 위해 PO 토큰을 활성화된 상태로 유지하십시오.
화질 기대치
| 설정 | 360p | 720p | 1080p | 1440p | 4K |
|---|---|---|---|---|---|
| 자동 PO 토큰 (기본값) | ✓ | ✓ | ✓ | ✓ | ✓ |
| Android 클라이언트만 | ✓ | ✗ | ✗ | ✗ | ✗ |
| PO 토큰 공급자 (수동) | ✓ | ✓ | ✓ | ✓ | ✓ |
| 브라우저 쿠키 | ✓ | ✓ | ✓ | ✓ | ✓ |