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 版本過舊。
解決方案:
- 更新 yt-dlp:
brew upgrade yt-dlp - 安裝 PO token provider(請參閱上方步驟 1)
- 或使用瀏覽器 Cookie 方法
nsig 提取失敗
症狀:
WARNING: [youtube] nsig extraction failed: Some formats may be missing
解決方案:
- 將 yt-dlp 更新至最新版本
- 安裝 PO token provider
- 如果仍然失敗,請使用 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。
畫質預期
| 設定 | 360p | 720p | 1080p | 1440p | 4K |
|---|---|---|---|---|---|
| 無設定(預設) | ✗ | ✗ | ✗ | ✗ | ✗ |
| 僅 Android 用戶端 | ✓ | ✗ | ✗ | ✗ | ✗ |
| PO token provider | ✓ | ✓ | ✓ | ✓ | ✓ |
| 瀏覽器 Cookie | ✓ | ✓ | ✓ | ✓ | ✓ |
HLS 串流下載(m3u8)
對於 Mux、Vimeo 和其他基於 HLS 的串流平台,請使用 ffmpeg 作為主要工具。這些串流通常需要認證標頭,yt-dlp 可能無法正確處理。
辨識 HLS 串流
HLS 串流使用 .m3u8 播放清單檔案:
- 主播放清單:列出多個畫質選項
- 轉譯播放清單:包含實際的影片/音訊片段網址
下載工作流程
步驟 1:取得串流網址
從影片來源取得 m3u8 網址。對於受保護的串流:
- 開啟瀏覽器開發者工具 → 網路標籤
- 播放影片
- 搜尋 "m3u8" 以找到播放清單網址
- 複製轉譯網址(通常包含畫質資訊,例如 "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)會分別提供音訊和影片:
- 下載音訊串流:
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 禁止錯誤
原因:缺少或不正確的認證標頭。
解決方案:
- 確認 Referer 標頭與影片來源網站相符
- 檢查是否需要其他標頭(Origin、User-Agent)
- 確保 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 網址中的簽名已過期。
解決方案:
- 從瀏覽器開發者工具取得新的網址
- 取得網址後立即下載
- 尋找帶有更新簽名參數的轉譯網址
效能提示
- HLS 下載通常以即時速度的 10-15 倍執行
- 使用
-c copy無需重新編碼(最快) - 透過即時進度顯示監控下載狀態
- 使用絕對輸出路徑以避免目錄混淆
延伸閱讀
- PO Token 設定:詳細安裝和疑難排解請參閱
references/po-token-setup.md - yt-dlp 文件:https://github.com/yt-dlp/yt-dlp
- 格式選擇指南:https://github.com/yt-dlp/yt-dlp#format-selection