Communitygithub.com

Biznomad/agent-skills

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

agent-skills 是什麼?

這是一個專為 AI 代理程式(如 Claude Code、Cursor、Codex)設計的技能,用於執行可靠且高品質的影片與音訊下載。它主要透過 yt-dlp 和 ffmpeg 工具,支援從 YouTube 下載最高 4K 解析度的影片,以及從 Mux、Vimeo 等平台下載 HLS(m3u8)串流。此技能提供了一個完整的自動化流程,包含智慧型中繼資料擷取、格式選擇、字幕下載與轉換功能。為了解決 YouTube 常見的下載限制(如僅顯示 360p 格式或「確認您不是機器人」驗證),此整合方案會自動設定 PO Token 提供者(優先使用 Docker 背景工具,若失敗則切換為瀏覽器型提供者)或使用瀏覽器 Cookie 進行驗證。使用者體驗被設計為對非技術使用者友善:代理程式會自行執行所有命令,以簡單明瞭的語言報告進度,並提供清晰的選項(例如「下載最佳品質影片」、「僅下載音訊(MP3)」),同時在回應中渲染影片縮圖。此技能也包含詳細的逐步除錯 SOP,涵蓋了常見錯誤情境(如 nsig 提取失敗、SSL EOF 錯誤、僅有圖片可用)的處理方式,並針對身處嚴格的代理環境(例如中國)的使用者進行了最佳化。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Biznomad/agent-skills/tree/HEAD/youtube-downloader

在你喜歡的 AI 中提問

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

預覽

來自技能 README

Thumbnail
Thumbnail

說明文件

YouTube 下載器

概述

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

  • 使用 PO Token 提供者或瀏覽器 Cookie 進行 YouTube 下載(最高 4K)
  • 使用驗證標頭進行 HLS 串流下載
  • 處理受保護內容並排除常見的下載失敗問題

非技術使用者體驗(預設)

假設使用者為非技術人員。不要要求他們執行命令。自行執行所有操作,並以簡單明瞭的語言回報進度。除非使用者詢問,否則避免提及工具名稱。

預設流程:

  1. 詢問網址(如果未提供)。
  2. 擷取影片中繼資料(標題/上傳者/時長/縮圖),並確認與使用者的意圖相符。
  • 如果 yt-dlp 被「確認您不是機器人」封鎖,則退回使用 YouTube oEmbed 來取得標題/上傳者/縮圖(時長可能未知)。
  1. 提供簡單的選擇(影片 vs. 僅音訊、畫質、字幕、儲存位置)。
  2. 如果使用者未指定,則使用合理的預設值繼續:
  • 以下載最佳畫質的影片
  • MP4 合併輸出
  • 僅下載單一影片(非播放清單)
  1. 下載並回報最終檔案路徑、檔案大小以及解析度(如果是影片)。

以使用者友善的用語提供選項:

  • 「下載最佳畫質的影片(預設)」
  • 「僅下載音訊(MP3)」
  • 「選擇畫質:1080p / 720p / 480p / 360p」
  • 「包含字幕(如果有的話)」
  • 「儲存到「下載」資料夾(預設)或告訴我另一個資料夾」

有縮圖時一律呈現:

  • 如果中繼資料包含縮圖網址,請使用 Markdown 圖片語法將其包含:![Thumbnail](URL)。

進行額外工作前先詢問:

  • 確認播放清單的下載(可能很大)。
  • 如果缺少相依套件,確認安裝/升級。
  • 在提取瀏覽器 Cookie 前先詢問。
  • 如果使用 Cookie,切勿在使用者面對的回應中提及 Cookie 數量或原始 Cookie 詳細資訊。應說「使用了您的 Chrome 登入工作階段」。
  • 如果需要驗證,自動設定本機 PO Token 輔助工具(無需使用者操作)。如果 Docker 缺失或失敗,不要嘗試安裝 Docker — 應切換為基於瀏覽器的 PO Token 提供者。

法律/安全提醒(簡短):

  • 僅在使用者有權利或獲得許可下載內容時才繼續。

回應範本(使用簡單明瞭的語言,不使用命令):

![Thumbnail](THUMBNAIL_URL)

標題:…
頻道:…
時長:…

我可以幫您:
1) 下載影片(最佳畫質,MP4)
2) 僅下載音訊(MP3)
3) 選擇特定畫質(1080p/720p/480p/360p)
4) 包含字幕(如果有的話)

我該儲存到哪裡?(預設:下載資料夾)

如果使用者說「直接下載」:

  • 使用預設值繼續,並在下載完成時確認。
    • 如果被 403 錯誤封鎖,自動設定驗證輔助工具並重試。

可靠下載 SOP(內部)

請遵循此 SOP 以避免常見失敗與混淆:

  1. 在 Shell 命令中為 URL 加上引號(zsh 會將 ? 視為 glob 模式)。範例:'https://www.youtube.com/watch?v=VIDEO_ID'。
  2. 確保 Proxy 同時對 yt-dlp 和 PO Token 提供者生效(HTTP_PROXY/HTTPS_PROXY/ALL_PROXY)。
  3. 如果您看到「登入以確認您不是機器人」,請求許可並使用瀏覽器 Cookie。如果沒有 Cookie 請勿繼續。
  4. 在下載前先啟動 PO Token 提供者(若無法啟動則快速失敗)。
  • 可用時使用 Docker bgutil 提供者。
  • 如果 Docker 缺失或失敗,切換為基於瀏覽器的 WPC 提供者。
  1. 如果使用了 Cookie,偏好使用 web_safari 播放器客戶端。否則,對於 PO Token 偏好使用 mweb。
  2. 在 WPC 鑄造 Token 期間保持瀏覽器視窗開啟。確保 Chrome 能透過相同的 Proxy 連線到 YouTube。
  3. 如果收到「Only images are available」或「Requested format is not available」,將其視為 PO Token 失敗,並在修復 Token 提供者/瀏覽器狀態後重試。
  4. 如果收到 SSL EOF 或片段錯誤,將其視為 Proxy/網路問題。使用漸進式格式和/或更好的 Proxy 重試。

代理程式執行檢查清單(內部)

  • 執行 scripts/download_video.py URL --info(如果獲得許可,則添加 --cookies-from-browser chrome)以擷取中繼資料和縮圖。
  • 如果 yt-dlp 中繼資料失敗,依賴腳本的 oEmbed 備援方案以取得標題/上傳者/縮圖,並註明時長可能不可用。
  • 如果有縮圖網址,請在回應中使用 Markdown 圖片語法呈現。
  • 要求使用者選擇影片或僅音訊,以及(選擇性地)畫質預設。
  • 使用友善的預設儲存位置(下載資料夾),除非使用者指定了資料夾。
  • 對於字幕,使用 --subtitles 和請求的 --sub-lang 執行。
  • 下載後,以簡單明瞭的語言回報檔案名稱、大小以及解析度(如果是影片)。
  • 如果下載因 403/片段錯誤而失敗,使用非 m3u8 的漸進式格式重試一次。
  • 如果出現「登入以確認您不是機器人」,請求 Cookie 存取權限,並使用 Cookie 和 web_safari 重試。
  • 如果出現「Only images are available」,將其視為 PO Token 失敗,並在修復提供者/瀏覽器狀態後重試。
  • 在下載前啟動 PO Token 提供者(--auto-po-token 為預設)。如果無法啟動則快速失敗。
  • 如果基於 Docker 的提供者失敗(在中國常見),自動備援到基於瀏覽器的 WPC 提供者(它可能會短暫開啟一個瀏覽器視窗)。
  • 如果使用了 WPC 提供者,請保持瀏覽器視窗開啟直到下載開始。如果瀏覽器啟動失敗,請明確設定 Chrome 的路徑。
  • 如果 PO Token 提供者超時,重新啟動一次並重試。
  • 如果設定了系統 Proxy,將其傳遞給提供者容器。如果 Proxy 指向 127.0.0.1/localhost,則將其改寫為 host.docker.internal 以供 Docker 使用。

何時使用此技能

當使用者有以下情況時,應呼叫此技能:

  • 請求下載 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 提供者才能存取高畫質。

高畫質下載工作流程

步驟 1:安裝 PO Token 提供者(一次性設定)

為存取 1080p/1440p/4K,請將 PO Token 提供者外掛安裝到 yt-dlp 的 Python 環境中:

# 尋找 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 Token 提供者:

# 下載最高 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

替代方案:瀏覽器 Cookie 方法

如果 PO Token 提供者設定有問題,請使用瀏覽器 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。
  • 瀏覽器和 yt-dlp 必須使用相同的 IP/Proxy。
  • 不要將 Android 客戶端與 Cookie 一起使用(Android 客戶端不支援 Cookie)。

常見任務

僅下載音訊(自行執行此操作)

將音訊提取為 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:音訊位元率 128 kbps

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

故障排除快速參考

僅有 360p 可用(格式 18)

原因:缺少 PO Token 提供者或 yt-dlp 版本過舊。

解決方案:

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

登入以確認您不是機器人

原因:YouTube 要求驗證才能繼續。

解決方案:

  1. 請求許可並使用瀏覽器 Cookie(--cookies-from-browser chrome)。
  2. 確保瀏覽器和 yt-dlp 使用相同的 IP/Proxy。
  3. 如有必要,使用 web_safari 客戶端重試。

僅有圖片可用 / 要求的格式不可用

原因:未套用 PO Token,或者提供者/瀏覽器驗證失敗。

解決方案:

  1. 在下載前確認 PO Token 提供者正在執行。
  2. 如果使用 WPC,請保持瀏覽器視窗開啟。
  3. 如果使用了 Cookie,偏好使用 web_safari 客戶端並重試。

nsig 提取失敗

症狀:

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

解決方案:

  1. 將 yt-dlp 更新至最新版本
  2. 安裝 PO Token 提供者
  3. 如果仍然失敗且 PO Token 已停用,請使用 Android 客戶端:yt-dlp --extractor-args "youtube:player_client=android" "VIDEO_URL"

SSL EOF / 片段錯誤

原因:Proxy 或網路不穩定。

解決方案:

  1. 使用漸進式格式(非 m3u8)重試。
  2. 切換到更穩定的 Proxy/節點。
  3. 避免在下載期間關閉 PO Token 瀏覽器視窗。

下載緩慢或網路錯誤

對於位於中國或嚴格的 Proxy 後方的使用者:

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

PO Token 警告(無害)

WARNING: android client https formats require a GVS PO Token

操作:如果下載成功則忽略此訊息。這表示 Android 客戶端在沒有 PO Token 的情況下只能存取有限的格式。

捆綁腳本參考

scripts/download_video.py

使用此便利包裝腳本,預設會自動啟動 PO Token 提供者以進行高畫質下載。自行使用它,並向使用者回報結果,無需要求他們執行命令。

基本用法:

scripts/download_video.py "VIDEO_URL"

引數:

  • url - YouTube 影片網址(必要)
  • -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 - 從瀏覽器載入 Cookie(例如:chrome, firefox)
  • --cookies-file - 從 cookies.txt 檔案載入 Cookie
  • --player-client - 使用特定的 YouTube 播放器客戶端(例如:web_safari)
  • --auto-po-token - 自動啟動 PO Token 提供者(預設;如果 Docker 可用則使用它,否則切換為基於瀏覽器的提供者)
  • --no-auto-po-token - 停用自動 PO Token 設定
  • --proxy - 用於 yt-dlp 和 PO Token 提供者的 Proxy 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 Token 停用時使用 Android 客戶端。請保持 PO Token 啟用以獲得高畫質。

畫質預期

設定360p720p1080p1440p4K
自動 PO Token(預設)✓✓✓✓✓
僅 Android 客戶端✓✗✗✗✗
PO Token 提供者(手動)✓✓✓✓✓
瀏覽器 Cookie✓✓✓✓✓

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

Biznomad/agent-skills

Landing page quality assessment for paid advertising campaigns. Evaluates message match, page speed, mobile experience, trust signals, form optimization, and conversion rate potential. Use when user says "landing page", "post-click experience", "landing page audit", "conversion rate", or "landing page optimization".

Biznomad/agent-skills

TikTok Ads deep analysis covering creative quality, tracking, bidding, campaign structure, and TikTok Shop. Evaluates 25 checks with emphasis on creative-first strategy, safe zone compliance, and Smart+ campaigns. Use when user says "TikTok Ads", "TikTok marketing", "TikTok Shop", "Spark Ads", "Smart+", or "TikTok campaign".

Biznomad/agent-skills

YouTube Ads specific analysis covering campaign types, creative quality, audience targeting, and measurement. Evaluates video ad performance across skippable, non-skippable, bumper, Shorts, and Demand Gen formats. Use when user says "YouTube Ads", "video ads", "pre-roll", "bumper ads", "YouTube campaign", or "Shorts ads".

Biznomad/agent-skills

Help users get promoted at work. Use when someone is preparing for a promotion conversation, building their case for advancement, trying to understand what's blocking their promotion, or figuring out how to get to the next level in their career.

Biznomad/agent-skills

CSS animation adapter patterns for HyperFrames. Use when authoring CSS keyframes, animation-delay based timing, animation-fill-mode, animation-play-state, or CSS-only motion that HyperFrames must seek deterministically during preview and rendering.

Biznomad/agent-skills

Video and audio processing with FFmpeg. Use for format conversion, resizing, compression, audio extraction, and preparing assets for Remotion. Triggers include converting GIF to MP4, resizing video, extracting audio, compressing files, or any media transformation task.

Biznomad/agent-skills

Read-only queue dashboard for workspace-aware ship. Shows which VERSION slots are currently claimed by open PRs, which sibling Conductor workspaces have WIP work likely to ship soon, and what slot /ship would pick next. No mutations — just a snapshot. Use when asked to "landing report", "what's in the queue", "show me open PRs", or "which version do I claim next". (gstack)

Biznomad/agent-skills

HyperFrames CLI dev loop — `npx hyperframes` for scaffolding (init), validation (lint, inspect), preview, render, and environment troubleshooting (doctor, browser, info, upgrade). Use when running any of these commands or troubleshooting the HyperFrames build/render environment. For asset preprocessing commands (`tts`, `transcribe`, `remove-background`), invoke the `hyperframes-media` skill instead.

Biznomad/agent-skills

Asset preprocessing for HyperFrames compositions — text-to-speech narration (Kokoro), audio/video transcription (Whisper), and background removal for transparent overlays (u2net). Use when generating voiceover from text, transcribing speech for captions, removing the background from a video or image to use as a transparent overlay, choosing a TTS voice or whisper model, or chaining these (TTS → transcribe → captions). Each command downloads its own model on first run.

Biznomad/agent-skills

Install and wire registry blocks and components into HyperFrames compositions. Use when running hyperframes add, installing a block or component, wiring an installed item into index.html, or working with hyperframes.json. Covers the add command, install locations, block sub-composition wiring, component snippet merging, and registry discovery.

Biznomad/agent-skills

Create video compositions, animations, title cards, overlays, captions, voiceovers, audio-reactive visuals, and scene transitions in HyperFrames HTML. Use when asked to build any HTML-based video content, add captions or subtitles synced to audio, generate text-to-speech narration, create audio-reactive animation (beat sync, glow, pulse driven by music), add animated text highlighting (marker sweeps, hand-drawn circles, burst lines, scribble, sketchout), or add transitions between scenes (crossfades, wipes, reveals, shader transitions). Covers composition authoring, timing, media, and the full video production workflow. For dev-loop CLI commands (init, lint, inspect, preview, render) see the hyperframes-cli skill; for asset preprocessing commands (tts, transcribe, remove-background) see the hyperframes-media skill.

Biznomad/agent-skills

Still-to-video conversion guide: model selection, motion prompting, and camera movement. Covers Wan 2.5 i2v, Seedance, Fabric, Grok Video with when to use each. Use for: animating images, creating video from stills, adding motion, product animations. Triggers: image to video, i2v, animate image, still to video, add motion to image, image animation, photo to video, animate still, wan i2v, image2video, bring image to life, animate photo, motion from image

Biznomad/agent-skills

>- The Landing Page Audit skill performs comprehensive evaluations of post-click experiences, combining technical performance analysis with conversion rate optimization (CRO) assessment.

Biznomad/agent-skills

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.

Biznomad/agent-skills

Optimize landing pages for higher conversion rates using proven frameworks and design patterns. Use when designing, reviewing, or improving landing pages, hero sections, pricing pages, CTAs, or when the user asks about conversion optimization.

Biznomad/agent-skills

Read-only queue dashboard for workspace-aware ship. (gstack)

Biznomad/agent-skills

Building promotion cases, brag documents, tracking wins, and self-advocacy for career advancement. Use when preparing for promotions, documenting accomplishments, or building your case for advancement.

Biznomad/agent-skills

Best practices for Remotion - Video creation in React

Biznomad/agent-skills

Translate an existing Remotion (React-based) video composition into a HyperFrames HTML composition. Use ONLY when the user explicitly asks to port, convert, migrate, translate, or rewrite a Remotion composition as HyperFrames (e.g. "port my Remotion project to HyperFrames"). Do NOT use when (a) authoring a NEW HyperFrames composition (even if A/B-testing a Remotion video); (b) Remotion is mentioned in passing; (c) Remotion code is shared as reference, not for translation; (d) the user wants "the same video as my Remotion one" without explicitly asking to migrate the source — treat as a fresh HyperFrames build. When in doubt, default to the `hyperframes` skill. Detects unsupported patterns (useState, useEffect side effects, async calculateMetadata, third-party React component libraries, `@remotion/lambda`) and recommends the runtime interop escape hatch instead of a lossy translation.

Biznomad/agent-skills

Produce programmable videos with Remotion using scene planning, asset orchestration, and validation gates for automated, brand-consistent video content.

相關技能