Communitygithub.com

YouTube 및 HLS 스트림 다운로더

yt-dlp와 ffmpeg을 사용하여 YouTube 동영상 및 Mux, Vimeo 등 플랫폼의 HLS 스트림(m3u8)을 다운로드합니다. 사용자가 동영상 다운로드, 오디오 추출, 인증 헤더가 필요한 보호된 스트림 처리, 또는 nsig 추출 실패, 403 오류, 쿠키 추출 문제와 같은 다운로드 문제 해결을 요청할 때 이 스킬을 사용하세요.

YouTube 및 HLS 스트림 다운로더란 무엇인가요?

이 스킬은 AI 에이전트가 yt-dlp와 ffmpeg을 사용하여 YouTube 및 HLS 스트리밍 플랫폼(Mux, Vimeo 등)에서 고품질 비디오 및 오디오를 안정적으로 다운로드할 수 있는 포괄적인 워크플로우를 제공합니다. PO 토큰 제공자 플러그인 설정, 브라우저 쿠키 사용, 403 오류 처리 및 nsig 추출 실패 디버깅을 포함하여 고품질(최대 4K) 액세스를 위한 자세한 단계를 다룹니다. 또한 인증 헤더가 필요한 보호된 콘텐츠를 다루고, Mux와 같은 플랫폼에서 별도의 오디오/비디오 스트림을 병합하는 방법을 설명합니다. 주요 사용 사례로는 형식 선택, 자막 다운로드, WebM에서 MP4로의 변환, 재생 목록 다운로드 등이 있으며, 모든 지침은 Cursor, Claude Code, Codex와 같은 AI 코딩 에이전트와의 통합을 위해 설계되어 원활한 자동화와 문제 해결을 가능하게 합니다.

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

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

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

문서

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.

해결 방법:

  1. yt-dlp 업데이트: brew upgrade yt-dlp
  2. PO 토큰 제공자 설치(위 1단계 참조)
  3. 또는 브라우저 쿠키 방법 사용

nsig 추출 실패

증상:

WARNING: [youtube] nsig extraction failed: Some formats may be missing

해결 방법:

  1. yt-dlp를 최신 버전으로 업데이트
  2. PO 토큰 제공자 설치
  3. 여전히 실패하면 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를 직접 사용하세요.

품질 기대치

설정360p720p1080p1440p4K
설정 없음(기본값)✗✗✗✗✗
Android 클라이언트만✓✗✗✗✗
PO 토큰 제공자✓✓✓✓✓
브라우저 쿠키✓✓✓✓✓

HLS 스트림 다운로드(m3u8)

Mux, Vimeo 및 기타 HLS 기반 서비스와 같은 스트리밍 플랫폼의 경우 기본 도구로 ffmpeg를 사용하세요. 이러한 스트림에는 yt-dlp가 올바르게 처리하지 못할 수 있는 인증 헤더가 필요한 경우가 많습니다.

HLS 스트림 식별

HLS 스트림은 .m3u8 재생 목록 파일을 사용합니다:

  • 마스터 재생 목록: 여러 품질 옵션 나열
  • 렌디션 재생 목록: 실제 비디오/오디오 세그먼트 URL 포함

다운로드 워크플로우

1단계: 스트림 URL 얻기

비디오 소스에서 m3u8 URL을 가져옵니다. 보호된 스트림의 경우:

  1. 브라우저 DevTools → 네트워크 탭 열기
  2. 비디오 재생
  3. "m3u8" 필터링하여 재생 목록 URL 찾기
  4. 렌디션 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)은 오디오와 비디오를 별도로 제공합니다:

  1. 오디오 스트림 다운로드:
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
  1. 비디오 스트림 다운로드:
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
  1. 스트림 병합:
ffmpeg -i video.mp4 -i audio.m4a -c copy merged.mp4

HLS 다운로드 문제 해결

403 Forbidden 오류

원인: 인증 헤더 누락 또는 잘못됨.

해결 방법:

  1. Referer 헤더가 비디오 소스 웹사이트와 일치하는지 확인
  2. 추가 헤더(Origin, User-Agent)가 필요한지 확인
  3. 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의 만료된 서명.

해결 방법:

  1. 브라우저 DevTools에서 새 URL 가져오기
  2. URL 획득 후 즉시 다운로드
  3. 업데이트된 서명 매개변수가 있는 렌디션 URL 찾기

성능 팁

  • HLS 다운로드는 일반적으로 실시간 속도의 10-15배로 실행됨
  • -c copy로 재인코딩 없음(가장 빠름)
  • 실시간 진행률 표시로 다운로드 모니터링
  • 디렉토리 혼동을 피하기 위해 절대 출력 경로 사용

추가 자료

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

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.

IGTA-Tech/claude-skills-research

Download YouTube video transcripts when user provides a YouTube URL or asks to download/get/fetch a transcript from YouTube. Also use when user wants to transcribe or get captions/subtitles from a YouTube video.

관련 스킬