Communitygithub.com

IGTA-Tech/claude-skills-research

YouTube動画やHLSストリーム(m3u8)をyt-dlpとffmpegを使ってダウンロードします。ユーザーが動画のダウンロード、音声抽出、保護されたストリームの認証ヘッダー処理、nsig抽出失敗や403エラー、クッキー抽出の問題などのトラブルシューティングを要求した際に使用します。

claude-skills-research とは?

このスキルは、AIエージェント(Claude Code、Cursor、Codexなど)がYouTube動画やHLSストリーム(Mux、Vimeoなど)をyt-dlpとffmpegを使って信頼性高くダウンロードするためのワークフローを提供します。主な機能は、POトークンプロバイダーやブラウザクッキーを用いた高品質(最大4K)ダウンロード、認証ヘッダーが必要なHLSストリームのダウンロード、そしてnsig抽出失敗や403エラー、クッキー抽出問題など、一般的なダウンロード障害のトラブルシューティングです。このスキルは、ユーザーが特定の動画品質を要求したり、ダウンロードに失敗した場合に呼び出すべきであり、yt-dlpのインストール確認、POトークンプロバイダーのセットアップ、ブラウザクッキーを用いた代替方法、ffmpegを使ったHLSストリームの認証ヘッダー付きダウンロード手順をカバーしています。バンドルされたスクリプト(download_video.py)も提供され、Androidクライアントの回避策をデフォルトで適用します。このスキールはマークダウン形式で構造化されており、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アクセスのために、POトークンプロバイダープラグインをyt-dlpのPython環境にインストールします:

# 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: オーディオビットレート128 kbps

ヒント: 変換により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 → Networkタブを開く
  2. 動画を再生
  3. 「m3u8」でフィルタリングしてプレイリストURLを見つける
  4. レンディションURLをコピーする(通常「rendition.m3u8」のように品質情報を含む)

ステップ2: 必要なヘッダーを特定

多くのCDNは認証ヘッダーを必要とします:

  • Referer: 元のWebサイト(例:https://maven.com/)
  • Origin: CORSのためにRefererと同じ
  • User-Agent: ブラウザの識別情報

Networkタブでブラウザが送信するヘッダーを確認します。

ステップ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ヘッダーが動画ソースのWebサイトと一致しているか確認
  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.

関連スキル