youtube-tools

YouTube ツール（yt-dlp）

概要

yt-dlp を使った、無料のローカル YouTube 操作です。API キーは不要で、動画ごとの費用もかかりません。インストール後はオフラインでも動作します。

Apify との使い分け

┌─────────────────────────────────────────────────────────────────┐
│ DECISION: YouTube Tools (yt-dlp) vs Apify                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│ Use youtube-tools (FREE) when:                                  │
│ ├── Downloading videos to local storage                         │
│ ├── Extracting transcripts/subtitles                            │
│ ├── Getting video metadata (title, duration, views, etc.)       │
│ ├── Bulk downloading playlists or channels                      │
│ ├── Converting to audio-only (MP3)                              │
│ └── You want zero API costs                                     │
│                                                                 │
│ Use apify-scrapers when:                                        │
│ ├── Scraping YouTube SEARCH results                             │
│ ├── Getting comments at scale                                   │
│ ├── Channel analytics and statistics                            │
│ ├── Trending video discovery                                    │
│ └── You need cloud-based processing                             │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

クイック判断ツリー

What do you need?
│
├── Download video(s)
│   ├── Single video → scripts/download_video.py URL
│   ├── Multiple videos → scripts/download_video.py --urls-file list.txt
│   ├── Playlist → scripts/download_video.py "playlist_url"
│   ├── Audio only → scripts/download_video.py URL --audio-only
│   └── Specific quality → scripts/download_video.py URL --quality 720p
│
├── Get transcript/subtitles
│   ├── Auto-generated captions → scripts/get_transcript.py URL
│   ├── Manual subtitles → scripts/get_transcript.py URL --manual-only
│   ├── Specific language → scripts/get_transcript.py URL --lang es
│   └── All available → scripts/get_transcript.py URL --all-langs
│
├── Get video metadata
│   ├── Single video → scripts/get_video_info.py URL
│   ├── Multiple videos → scripts/get_video_info.py --urls-file list.txt
│   └── Playlist info → scripts/get_video_info.py "playlist_url"
│
└── Advanced
    ├── Age-restricted → scripts/download_video.py URL --cookies-from-browser chrome
    ├── Private videos → Requires authentication (see references/yt-dlp-guide.md)
    └── Live streams → scripts/download_video.py URL --live-from-start

環境設定

# Install yt-dlp (required)
pip install yt-dlp

# Optional: Install ffmpeg for format conversion
# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Windows
winget install ffmpeg

API キーは不要です！ 完全に無料です。

よくある使い方

動画を 1 本ダウンロードする

python scripts/download_video.py "https://www.youtube.com/watch?v=VIDEO_ID"

品質を指定してダウンロードする

python scripts/download_video.py "https://youtu.be/VIDEO_ID" --quality 1080p

音声のみをダウンロードする（MP3）

python scripts/download_video.py "https://youtube.com/watch?v=VIDEO_ID" --audio-only

再生リスト全体をダウンロードする

python scripts/download_video.py "https://youtube.com/playlist?list=PLAYLIST_ID" --output-dir ./videos

ファイルから一括ダウンロードする

# Create urls.txt with one URL per line
python scripts/download_video.py --urls-file urls.txt --output-dir ./downloads

文字起こしを取得する

python scripts/get_transcript.py "https://youtube.com/watch?v=VIDEO_ID"

言語を指定して文字起こしを取得する

python scripts/get_transcript.py "https://youtu.be/VIDEO_ID" --lang es

動画のメタデータを取得する

python scripts/get_video_info.py "https://youtube.com/watch?v=VIDEO_ID"

複数の動画のメタデータを取得する

python scripts/get_video_info.py --urls-file videos.txt --output metadata.json

出力先

すべての出力は、デフォルトで .tmp/youtube/ に保存されます。

• 動画：.tmp/youtube/videos/
• 音声：.tmp/youtube/audio/
• 文字起こし：.tmp/youtube/transcripts/
• メタデータ：.tmp/youtube/metadata/

費用

無料 - API キーも、動画ごとの費用も、サブスクリプションも不要です。

セキュリティに関する注意事項

安全性を考慮した設計

• URL の検証：YouTube の URL（youtube.com、youtu.be）のみを受け付けます
• ファイル名のサニタイズ：危険な文字を削除します
• 出力先の制限：.tmp/ ディレクトリにのみ書き込みます
• シェルインジェクションなし：文字列連結ではなく、引数リストを使ってサブプロセスを実行します
• 認証情報の保存なし：Cookie は明示的に要求された場合にのみ使用します

著作権に関する警告

• アクセスする権利のあるコンテンツのみダウンロードしてください
• YouTube の利用規約を遵守してください
• 著作権で保護されたコンテンツを再配布しないでください
• 個人利用または教育目的で使用してください

レート制限

• yt-dlp にはレート制限機能が組み込まれています
• 一括ダウンロードでは、スロットリングを避けるために --sleep-interval 5 を使用してください
• リクエストが過剰な場合、YouTube によって IP が一時的にブロックされることがあります

トラブルシューティング

問題：「Video unavailable」

原因： 動画が非公開、年齢制限付き、または地域制限されています
解決策： 年齢制限付きコンテンツには --cookies-from-browser chrome を使用します

問題：「Unable to extract video data」

原因： YouTube のページ構造が変更されました
解決策： yt-dlp を更新します：pip install -U yt-dlp

問題：字幕が見つからない

原因： 動画に字幕（自動生成または手動）がありません
解決策： まず --list-subs を使用して、利用可能な字幕を確認します

問題：ダウンロードが遅い

原因： YouTube のスロットリング、またはネットワークの問題です
解決策： ダウンロードを高速化するには、--concurrent-fragments 4 を試してください

問題：形式の変換に失敗する

原因： ffmpeg がインストールされていません
解決策： ffmpeg をインストールします（「環境設定」を参照）

統合パターン

ダウンロード＋文字起こし＋要約

# 1. Download video
python scripts/download_video.py "URL" --output-dir .tmp/video

# 2. Get transcript
python scripts/get_transcript.py "URL" --output .tmp/transcript.txt

# 3. Use content-generation to summarize
# (transcript file is now ready for summarization)

一括リサーチのワークフロー

# 1. Get metadata for research videos
python scripts/get_video_info.py --urls-file research_videos.txt --output .tmp/metadata.json

# 2. Download transcripts for text analysis
python scripts/get_transcript.py --urls-file research_videos.txt --output-dir .tmp/transcripts

# 3. Use parallel-research to analyze content

コースコンテンツのダウンロード

# Download entire playlist as course modules
python scripts/download_video.py "PLAYLIST_URL" --output-dir .tmp/course --quality 720p

# Get all transcripts for notes
python scripts/get_transcript.py "PLAYLIST_URL" --output-dir .tmp/course/transcripts

リソース

• references/yt-dlp-guide.md - すべてのオプションを網羅した yt-dlp の完全なリファレンス
• yt-dlp ドキュメント：https://github.com/yt-dlp/yt-dlp#readme