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

추가 작업 전에 묻기:
- 재생 목록 다운로드 확인 (클 수 있음)
- 누락된 종속성 설치/업그레이드 확인
- 브라우저 쿠키 추출 전에 묻기
- 쿠키를 사용하는 경우, 사용자 응답에 쿠키 개수나 원시 쿠키 세부 정보를 절대 언급하지 마세요. "Chrome 로그인 세션을 사용했습니다"라고 말하세요.
- 인증이 필요한 경우, 로컬 PO 토큰 도우미를 자동으로 설정합니다(사용자 작업 없음). Docker가 없거나 실패하면 Docker 설치를 시도하지 말고 브라우저 기반 PO 토큰 제공자로 전환하세요.
법적/안전 알림 (간략):
- 사용자가 콘텐츠를 다운로드할 권리나 허가가 있는 경우에만 진행하세요.
응답 템플릿 (일반 언어 사용, 명령어 없음):

제목: …
채널: …
길이: …
다음을 도와드릴 수 있습니다:
1) 동영상 다운로드 (최고 화질, MP4)
2) 오디오만 다운로드 (MP3)
3) 특정 화질 선택 (1080p/720p/480p/360p)
4) 자막 포함 (가능한 경우)
어디에 저장할까요? (기본값: 다운로드 폴더)
사용자가 "그냥 다운로드"라고 말하는 경우:
- 기본값으로 진행하고 다운로드가 완료되면 확인합니다.
- 403 오류로 차단된 경우, 자동으로 인증 도우미를 설정하고 재시도합니다.
안정적인 다운로드 SOP (내부)
일반적인 실패와 혼란을 피하려면 이 SOP를 따르세요:
- 셸 명령어에서 URL을 따옴표로 묶습니다(zsh는
?를 글롭으로 처리). 예:'https://www.youtube.com/watch?v=VIDEO_ID' - yt-dlp와 PO 토큰 제공자 모두에 프록시가 활성화되어 있는지 확인합니다(HTTP_PROXY/HTTPS_PROXY/ALL_PROXY).
- "로그인하여 로봇이 아님을 확인하세요" 메시지가 표시되면, 권한을 요청하고 브라우저 쿠키를 사용하세요. 쿠키 없이 진행하지 마세요.
- 다운로드 전에 PO 토큰 제공자를 시작하세요(시작할 수 없으면 빠르게 실패).
- Docker bguutil 제공자가 가능할 때 사용하세요.
- Docker가 없거나 실패하면 브라우저 기반 WPC 제공자로 전환하세요.
- 쿠키를 사용 중이면
web_safari플레이어 클라이언트를 선호하세요. 그렇지 않으면 PO 토큰에mweb를 선호하세요. - WPC가 토큰을 발행하는 동안 브라우저 창을 열어 두세요. Chrome이 동일한 프록시를 통해 YouTube에 도달할 수 있는지 확인하세요.
- "이미지만 사용 가능" 또는 "요청한 형식을 사용할 수 없음"이 표시되면 PO 토큰 실패로 처리하고 토큰 제공자/브라우저 상태를 수정한 후 재시도하세요.
- SSL EOF 또는 조각 오류가 발생하면 프록시/네트워크 문제로 처리하세요. 프로그레시브 형식 및/또는 더 나은 프록시로 재시도하세요.
에이전트 실행 체크리스트 (내부)
scripts/download_video.py URL --info실행(권한이 부여된 경우--cookies-from-browser chrome추가)하여 메타데이터와 썸네일을 가져옵니다.- yt-dlp 메타데이터가 실패하면 스크립트의 oEmbed 대체를 사용하여 제목/업로더/썸네일을 가져오고 길이를 사용할 수 없을 수 있음을 알립니다.
- 썸네일 URL이 있으면 마크다운 이미지 구문으로 응답에 렌더링합니다.
- 사용자에게 동영상 vs. 오디오 전용 및 (선택적으로) 화질 사전 설정을 선택하도록 요청합니다.
- 사용자가 폴더를 지정하지 않는 한 친숙한 기본 저장 위치(다운로드 폴더)를 사용하세요.
- 자막의 경우
--subtitles및 요청된--sub-lang으로 실행합니다. - 다운로드 후 파일 이름, 크기 및 해상도(동영상인 경우)를 일반 언어로 보고합니다.
- 다운로드가 403/조각 오류로 실패하면 m3u8이 아닌 프로그레시브 형식으로 한 번 재시도합니다.
- "로그인하여 로봇이 아님을 확인하세요"가 나타나면 쿠키 액세스를 요청하고 쿠키 +
web_safari로 재시도합니다. - "이미지만 사용 가능"이 나타나면 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 토큰 제공자 (수동) | ✓ | ✓ | ✓ | ✓ | ✓ |
| 브라우저 쿠키 | ✓ | ✓ | ✓ | ✓ | ✓ |
일반적인 실수
- 잊어버린 URL 따옴표:
?매개변수가 포함된 URL은 zsh에서 실패합니다. 항상 따옴표를 사용하세요. - 프록시 불일치: 브라우저와 yt-dlp가 동일한 IP를 통해 YouTube에 도달하는지 확인합니다(WPC 및 쿠키의 일반적인 실패 모드).
- Android 클라이언트를 쿠키와 함께 사용: Android 클라이언트는 쿠키를 지원하지 않습니다.
web_safari를 사용하세요. - Docker 제공자 문제를 무시함: Docker가 없거나 실패할 때 자동 대체는 필수입니다. 수동으로 건너뛰지 마세요.
보안 고려 사항
- YouTube 개인 정보: 다운로드 기록 및 시청 패턴이 YouTube에 표시될 수 있습니다. 시청 기록을 비활성화하거나 별도의 계정을 사용하는 것을 고려하세요.
- 타사 사이트 개인 정보: 다른 스트리밍 플랫폼(HLS)을 다운로드할 때 타사 쿠키가 관련될 수 있습니다. 사용자에게 데이터가 액세스되고 있음을 알리세요.
- 콘텐츠 보호: 저작권법을 존중하고 다운로드 권한이 있는 콘텐츠만 다운로드하세요.
- 자동화 딜레마: 무인 다운로드는 잠재적으로 ToS를 위반할 수 있습니다. 사용자에게 진행에 대한 확인을 구하세요.
- Android 클라이언트 및 GVS 토큰: Android 클라이언트 및 보호된 https 형식과 관련된 경고가 표시될 수 있습니다. 이 경고는 일반적으로 고품질 다운로드에 영향을 미치지 않습니다.