Communitygithub.com

IGTA-Tech/claude-skills-research

使用 yt-dlp 和 ffmpeg 下載 YouTube 影片及來自 Mux、Vimeo 等平台的 HLS 串流(m3u8)。當使用者要求下載影片、提取音訊、處理需驗證標頭的受保護串流,或排除 nsig 提取失敗、403 錯誤、Cookie 提取問題等下載故障時,請使用此技能。

claude-skills-research 是什麼?

這是一個專為 AI 代理(如 Claude Code、Cursor、Codex)設計的技能,透過 yt-dlp 和 ffmpeg 實現可靠的影片與音訊下載功能。它支援從 YouTube 下載最高 4K 解析度的影片,並能處理來自 Mux、Vimeo 等平台的 HLS(m3u8)串流,特別針對需要認證標頭的受保護內容提供解決方案。技能內建完整的工作流程,包括透過 PO Token Provider 或瀏覽器 Cookie 獲取高畫質影片,以及使用 ffmpeg 直接下載 HLS 串流並處理常見的 403 錯誤、nsig 提取失敗和 Cookie 提取問題。此外,還包含 WebM 轉 MP4 格式轉換、音訊提取、字幕下載、播放列表下載等常見任務的指令範例。這項技能特別適合需要自動化下載任務、處理受保護串流內容或排除下載故障的開發者與 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 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

YouTube 下載器

概述

使用 yt-dlp 和 ffmpeg,從 YouTube 及 HLS 串流平台(Mux、Vimeo 等)可靠地下載影片和音訊。此技能提供以下工作流程:

  • YouTube 下載(最高 4K),使用 PO Token Provider 或瀏覽器 Cookie
  • 使用認證標頭下載 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 Token Provider 以取得高畫質存取權限。

高畫質下載工作流程

步驟 1:安裝 PO Token Provider(一次性設定)

若要存取 1080p/1440p/4K,請在 yt-dlp 的 Python 環境中安裝 PO token provider 外掛:

# 找出 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 token provider 後:

# 下載最高 1080p 的最佳畫質
yt-dlp -f "bestvideo[height<=1080]+bestaudio/best" "VIDEO_URL"

# 下載可用的最佳畫質(若有 4K 則下載 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

替代方案:瀏覽器 Cookie 方法

如果 PO token provider 設定有問題,請使用瀏覽器 Cookie:

# 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:恒定品質因子(範圍 18-28,數值越低畫質越好)
  • -c:a aac:使用 AAC 音訊編碼
  • -b:a 128k:音訊位元率 128 kbps

提示:轉換可維持 1080p 解析度,並在現代硬體上提供約 6 倍的編碼速度。

疑難排解快速參考

僅有 360p 可用(格式 18)

原因:缺少 PO token provider 或 yt-dlp 版本過舊。

解決方案:

  1. 更新 yt-dlp:brew upgrade yt-dlp
  2. 安裝 PO token provider(請參閱上方步驟 1)
  3. 或使用瀏覽器 Cookie 方法

nsig 提取失敗

症狀:

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

解決方案:

  1. 將 yt-dlp 更新至最新版本
  2. 安裝 PO token provider
  3. 如果仍然失敗,請使用 Android 用戶端:yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"

下載速度慢或網路錯誤

針對位於中國或受限代理後方的使用者:

  • 下載速度可能因網路狀況而變慢
  • 請預留足夠時間完成下載
  • yt-dlp 會在暫時性失敗時自動重試

PO Token 警告(無害)

WARNING: android client https formats require a GVS PO Token

處理方式:如果下載成功,則忽略此訊息。這表示 Android 用戶端在沒有 PO token 的情況下,格式存取權限有限。

附帶腳本參考

scripts/download_video.py

一個便利包裝程式,預設會套用 Android 用戶端解決方法:

基本用法:

scripts/download_video.py "VIDEO_URL"

引數:

  • url - YouTube 影片網址(必要)
  • -o, --output-dir - 輸出目錄
  • -f, --format - 格式指定
  • -a, --audio-only - 提取音訊為 MP3
  • -F, --list-formats - 列出可用格式
  • --no-android-client - 停用 Android 用戶端解決方法

注意:此腳本使用 Android 用戶端(若無 PO token 則僅限 360p)。如需高畫質,請直接使用 yt-dlp 搭配 PO token provider。

畫質預期

設定360p720p1080p1440p4K
無設定(預設)✗✗✗✗✗
僅 Android 用戶端✓✗✗✗✗
PO token provider✓✓✓✓✓
瀏覽器 Cookie✓✓✓✓✓

HLS 串流下載(m3u8)

對於 Mux、Vimeo 和其他基於 HLS 的串流平台,請使用 ffmpeg 作為主要工具。這些串流通常需要認證標頭,yt-dlp 可能無法正確處理。

辨識 HLS 串流

HLS 串流使用 .m3u8 播放清單檔案:

  • 主播放清單:列出多個畫質選項
  • 轉譯播放清單:包含實際的影片/音訊片段網址

下載工作流程

步驟 1:取得串流網址

從影片來源取得 m3u8 網址。對於受保護的串流:

  1. 開啟瀏覽器開發者工具 → 網路標籤
  2. 播放影片
  3. 搜尋 "m3u8" 以找到播放清單網址
  4. 複製轉譯網址(通常包含畫質資訊,例如 "rendition.m3u8")

步驟 2:辨識所需的標頭

許多 CDN 需要認證標頭:

  • Referer:來源網站(例如 https://maven.com/)
  • Origin:與 Referer 相同,用於 CORS
  • 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 禁止錯誤

原因:缺少或不正確的認證標頭。

解決方案:

  1. 確認 Referer 標頭與影片來源網站相符
  2. 檢查是否需要其他標頭(Origin、User-Agent)
  3. 確保 m3u8 網址包含瀏覽器中的所有查詢參數

yt-dlp 在 Cookie 提取時卡住

症狀:Extracting cookies from chrome 無限等待。

解決方案:對 HLS 串流直接使用 ffmpeg,而非 yt-dlp。

通訊協定未列入白名單

錯誤:Protocol 'https' not on whitelist 'file,crypto,data'

解決方案:加上 -protocol_whitelist file,http,https,tcp,tls,crypto,httpproxy

空的片段或沒有串流

原因:m3u8 網址中的簽名已過期。

解決方案:

  1. 從瀏覽器開發者工具取得新的網址
  2. 取得網址後立即下載
  3. 尋找帶有更新簽名參數的轉譯網址

效能提示

  • 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.

相關技能