yt-search-download

YouTube 検索 & ダウンロード

YouTube Data API v3 に基づく高度な検索と、yt-dlp によるダウンロードに対応しています。

前提条件

1. YouTube API Key：

   echo $YT_BROWSE_API_KEY
   

   空の場合：Google Cloud Console → YouTube Data API v3 を有効化 → API Key を作成 → ~/.zshrc に書き込みます：

   export YT_BROWSE_API_KEY=your_key
   

2. yt-dlp（ダウンロード用）：

   brew install yt-dlp   # macOS
   pip install yt-dlp     # 或 pip 安装
   

コマンドの説明

スクリプトのパス：~/.claude/skills/yt-search-download/scripts/yt_search.py

全体からキーワード検索

python3 scripts/yt_search.py search "关键词" -n 20

パラメーター	説明
-n 20	最大取得件数（デフォルトは 20）
-o date	時間順に並べ替え（デフォルトは relevance）
-o viewCount	再生回数順に並べ替え（API レベルで正確）
--sort-by views	ローカルで二次並べ替え（再生回数の降順）
--sort-by duration-asc	ローカルで並べ替え：再生時間の短い順
--sort-by duration-desc	ローカルで並べ替え：再生時間の長い順
--min-duration 30m	フィルター：最短再生時間（30m、1h、1h30m、数字のみの場合は分に対応）
--max-duration 1h	フィルター：最長再生時間
--after 2024-01-01	公開日の開始
--before 2024-12-31	公開日の終了
-c @handle	チャンネルを指定
-d	説明を表示
--json	JSON 形式で出力

チャンネルの動画を閲覧

# 频道最新视频（按时间倒序）
python3 scripts/yt_search.py channel @channelHandle -n 10

# 频道内关键词搜索
python3 scripts/yt_search.py channel @channelHandle -q "关键词"

# 频道内按播放量排序
python3 scripts/yt_search.py channel @channelHandle -o viewCount

# 只看长视频（超过 1 小时）
python3 scripts/yt_search.py channel @channelHandle --min-duration 1h

# 只看短视频（30 分钟内），按时长升序
python3 scripts/yt_search.py channel @channelHandle --max-duration 30m --sort-by duration-asc

チャンネルの形式は、@handle、https://youtube.com/@handle、チャンネル ID（UCxxxx）に対応しています。

動画をダウンロード

# 最佳画质下载到 ~/Downloads
python3 scripts/yt_search.py download "VIDEO_URL"

# 指定画质
python3 scripts/yt_search.py download "VIDEO_URL" -q 1080p

# 指定目录
python3 scripts/yt_search.py download "VIDEO_URL" --dir ~/Desktop

# 仅下载音频（MP3）
python3 scripts/yt_search.py download "VIDEO_URL" --audio-only

動画の詳細を照会

python3 scripts/yt_search.py info "VIDEO_URL"

出力形式（Markdown テーブル）

スクリプトは Markdown テーブルを出力します。AI は、ユーザーに表示する前に各行の 【译】___ を実際の日本語訳に置き換える必要があります。

最終的な表示例：

#	タイトル（原文 → 日本語訳）	日付	再生時間	再生回数
1	Rick Beato: Greatest Guitarists... リック・ベアト：史上最高のギタリスト	2026-03-01	2h33m	302.2K
2	State of AI in 2026: LLMs, Coding... 2026年の AI の現状：LLM、コーディング、スケーリングの法則	2026-01-31	4h25m	741.7K

🔴 必須ルール：

• ✅ 英語の元タイトルを保持します（クリック可能なリンクとして表示）
• ✅ 【译】___ を簡潔な日本語訳に置き換えます（リンクの後、同じセルに配置）
• ✅ すべての動画を 1 行ずつ翻訳し、省略しません
• ❌ 翻訳が必要かどうかをユーザーに尋ねません（そのまま翻訳します）
• ❌ 【译】___ をそのままユーザーに表示しません

典型的なワークフロー

特定のチャンネルの最新動画を探してダウンロード：

1. channel @handle -n 10 → 検索結果を閲覧
2. ダウンロードする動画をユーザーに尋ねる
3. download "URL" → ~/Downloads に保存

検索して再生回数で絞り込む：

1. search "关键词" -o viewCount -n 20

ポッドキャストの音声を抽出：

1. search "播客名" -o date -n 5
2. download "URL" --audio-only

字幕をダウンロード（デフォルトで SRT + TXT を同時に出力）

標準手順：字幕をダウンロードして SRT に変換し、タイムスタンプを保持した TXT も生成します（AI による要約用。タイムスタンプがあると内容の位置を特定しやすくなります）。

# Step 1：下载字幕并转为 SRT（英文优先，无则用自动字幕）
yt-dlp --cookies-from-browser chrome \
  --write-auto-sub --write-sub \
  --sub-lang en,zh-Hans \
  --convert-subs srt \
  --skip-download \
  -o "~/Downloads/%(title)s.%(ext)s" \
  "VIDEO_URL"
# 输出：~/Downloads/视频标题.en.srt 或 .zh-Hans.srt

# Step 2：从 SRT 生成 TXT（保留时间戳，仅去除序号和空行，供 AI 总结使用）
python3 -c "
import re, sys
srt = open(sys.argv[1]).read()
# 去除序号行（纯数字行），保留时间戳和字幕文本
txt = re.sub(r'^\d+\s*\n', '', srt, flags=re.MULTILINE)
txt = re.sub(r'\n{3,}', '\n\n', txt).strip()
txt_path = sys.argv[1].replace('.srt', '.txt')
open(txt_path, 'w').write(txt)
print(f'已保存：{txt_path}')
" ~/Downloads/视频标题.en.srt
# 输出：~/Downloads/视频标题.en.txt（格式：时间戳 + 字幕文本）

TXT の形式例（タイムスタンプを保持し、AI が要約する際に具体的な時刻を引用しやすくします）：

00:00:01,000 --> 00:00:04,000
Welcome to the Lex Fridman podcast.

00:00:05,000 --> 00:00:09,000
Today we're talking about the greatest guitarists of all time.

その他のケース：

# 仅中文字幕（SRT + TXT）
yt-dlp --cookies-from-browser chrome --write-auto-sub --write-sub \
  --sub-lang zh-Hans --convert-subs srt --skip-download \
  -o "~/Downloads/%(title)s.%(ext)s" "VIDEO_URL"

# 字幕 + 视频一起下载
yt-dlp --cookies-from-browser chrome --write-auto-sub --write-sub \
  --sub-lang en --convert-subs srt \
  -o "~/Downloads/%(title)s.%(ext)s" "VIDEO_URL"

ルール：字幕をダウンロードする際は必ず --convert-subs srt を付けます。ダウンロード完了後は必ず Step 2 を実行して TXT を生成し、ユーザーが .srt（タイムライン付き）と .txt（プレーンテキスト）の両方を受け取れるようにします。

高度な使い方（yt-dlp を直接使用）

# 列出可用格式
yt-dlp --cookies-from-browser chrome -F "VIDEO_URL"

# 下载整个播放列表
yt-dlp --cookies-from-browser chrome -o "~/Downloads/%(playlist_title)s/%(title)s.%(ext)s" "PLAYLIST_URL"