1. はじめに
YouTube の解説動画や講義動画を見ていて、次のように思ったことはないでしょうか。
- 動画の内容を後からテキストで読み返したい
- 長い動画を見る前に、まず要点を把握したい
- 技術カンファレンスや講義の内容を
md,txt,json,srt,vttとして保存したい - 英語動画の字幕を取得して、日本語で要約したい
yttext は、YouTube の元言語の字幕を取得し、再利用しやすいファイルとして保存できる Python アプリケーションです。
Gemini API キーを用意すると、取得した字幕から Gemini による Markdown 要約も作成できます。
利用方法は大きく 2 つあります。
- CLI — ターミナルから字幕取得・要約・ファイル保存を行う
- Web アプリ — ブラウザから設定し、字幕・要約をプレビュー、コピー、ダウンロードする
2. インストール方法
yttext は PyPI、Homebrew、ソースコードから利用できます。
2.1. PyPI から CLI をインストール
頻繁に利用する場合はツールとしてインストールできます。
uv：
uv tool install yttext
pipx：
pipx install yttext
確認：
yttext --version
2.2. PyPI から Web アプリもインストール
Web アプリは web extra の依存パッケージを使用します。
uv：
uv tool install 'yttext[web]'
pipx：
pipx install 'yttext[web]'
インストール後は次のコマンドで起動できます。
yttext web
2.3. Homebrew
Homebrew では CLI と Web アプリをまとめてインストールできます。
brew install kkensuke/tap/yttext
確認：
yttext --version
Web アプリもそのまま起動できます。
yttext web
3. Gemini API キーの設定
字幕を取得するだけなら Gemini API キーは不要です。
要約や Gemini モデル一覧の取得を行う場合は、Google AI Studio で API キーを用意します。
3.1. macOS / Linux
CLI では GEMINI_API_KEY 環境変数を利用します。
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
利用するモデルを固定したい場合は GEMINI_MODEL も設定できます。
export GEMINI_MODEL="gemini-flash-lite-latest"
3.2. Windows PowerShell
$env:GEMINI_API_KEY = "YOUR_GEMINI_API_KEY"
$env:GEMINI_MODEL = "gemini-flash-lite-latest"
3.3. API キーは CLI 引数では渡さない
API キーをコマンドライン引数として指定する機能はありません。
CLI では GEMINI_API_KEY を使用します。
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
yttext "YOUTUBE_URL"
4. Web アプリの使い方
4.1. 起動する
PyPI の Web extra または Homebrew でインストールした場合：
yttext web
ローカルモードではデフォルトで次のアドレスを使用します。
http://127.0.0.1:8000
起動すると標準ブラウザが自動的に開きます。
終了するときはターミナルで Ctrl+C を押します。
4.2. Web アプリで Gemini を使う
- Gemini summary を ON にした状態では API キーが必要です。
- ローカルサーバーに
GEMINI_API_KEYが設定されていない場合は、ブラウザの設定画面へ自分の Gemini API キーを入力します。 - 入力した API キーは Gemini の処理にだけ使われます。
- Load available models から利用可能な Gemini モデルを読み込み、モデルを選択できます。
4.3. ローカル環境変数を使う
毎回ブラウザへ API キーを入力したくない場合は、Web アプリを起動する前に環境変数を設定できます。
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
export GEMINI_MODEL="gemini-flash-lite-latest"
yttext web
- ブラウザ側へ別の API キーを入力した場合は、そのキーが優先されます。
- サーバー側の API キーそのものがブラウザへ返されることはありません。
5. CLI の基本
基本形式は次の通りです。
yttext [OPTIONS] YOUTUBE_URL_OR_VIDEO_ID
ヘルプ：
yttext --help
5.1. CLI オプション
| オプション | 説明 |
|---|---|
-o, --output-dir DIR |
字幕・要約ファイルの出力先 |
-f, --format {md,txt,json,srt,vtt} |
字幕形式。デフォルト md
|
-n, --no-summary |
Gemini 要約を行わない |
-l, --summary-lang LANGUAGE |
auto または BCP 47 言語タグ |
-L, --long-summary {skip,truncate,full} |
50,000 文字を超える字幕の要約方法 |
-c, --cookies-from-browser BROWSER |
ローカルブラウザの Cookie を利用 |
-m, --gemini-model MODEL_ID |
Gemini モデルを指定 |
-M, --list-gemini-models |
generateContent 対応モデルを一覧表示 |
-V, --version |
バージョン表示 |
-h, --help |
ヘルプ表示 |
6. CLI の実行例
6.1. 字幕と Gemini 要約を作成
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
yttext "https://www.youtube.com/watch?v=VIDEO_ID"
Video ID だけでも実行できます。
yttext "VIDEO_ID"
API キーが設定されていない場合でも字幕取得は行われ、要約だけがスキップされます。
6.2. 字幕だけ取得
yttext "YOUTUBE_URL" --no-summary
# 短縮形：
yttext "YOUTUBE_URL" -n
Gemini API キーは不要です。
6.3. 出力先を変更
yttext "YOUTUBE_URL" --output-dir output/
# 短縮形：
yttext "YOUTUBE_URL" -o output/
-o はファイル名ではなく出力ディレクトリを指定します。
6.4. JSON で保存
yttext "YOUTUBE_URL" --format json --no-summary
# 短縮形：
yttext "YOUTUBE_URL" -f json -n
6.5. 英語動画を日本語で要約
yttext "ENGLISH_VIDEO_URL" --summary-lang ja
# 短縮形：
yttext "ENGLISH_VIDEO_URL" -l ja
6.6. その他の言語
よく使う言語として Web UI には次の選択肢があります。
en
ja
zh-Hans
zh-Hant
ko
es
fr
de
pt-BR
hi
CLI ではこれら以外にも、有効な BCP 47 言語タグを指定できます。
たとえばイタリア語：
yttext "YOUTUBE_URL" --summary-lang it
6.7. Gemini モデルを指定
yttext "YOUTUBE_URL" \
--gemini-model "gemini-flash-latest" \
--summary-lang ja
# 短縮形：
yttext "YOUTUBE_URL" -m "gemini-flash-latest" -l ja
6.8. 利用可能な Gemini モデルを確認
yttext --list-gemini-models
# 短縮形：
yttext -M
このコマンドは URL を必要としません。
GEMINI_API_KEY に設定されているキーで利用でき、generateContent をサポートする Gemini モデル ID が一覧表示されます。
6.9. 50,000 文字を超える字幕の要約
# 全文要約
yttext "YOUTUBE_URL" --long-summary full
# 先頭 50,000 文字以内だけ要約
yttext "YOUTUBE_URL" --long-summary truncate
# 長文の場合は要約しない
yttext "YOUTUBE_URL" --long-summary skip
CLI のデフォルトです。
6.10. Chrome の Cookie を使う
制限の動画の場合はブラウザの Cookie を使います。
yttext "YOUTUBE_URL" --cookies-from-browser chrome
# 短縮形：
yttext "YOUTUBE_URL" -c chrome
7. 生成されるファイル
字幕ファイルでMarkdown の場合：
{video_id}_transcript.md
要約に成功した場合：
{video_id}_summarized.md
8. Markdown 字幕の内容
Markdown 出力には動画情報、チャプター、字幕が含まれます。
イメージは次のようになります。
# Python プログラミング入門
**Video ID:** a1b2C3d4E5F
**YouTube URL:** https://www.youtube.com/watch?v=a1b2C3d4E5F
**Duration:** 01:02:34
**Captions:** Auto-generated captions (ja)
## Chapters
- [00:00 — はじめに](https://www.youtube.com/watch?v=a1b2C3d4E5F&t=0s)
- [03:15 — 変数](https://www.youtube.com/watch?v=a1b2C3d4E5F&t=195s)
---
**[00:00](https://www.youtube.com/watch?v=a1b2C3d4E5F&t=0s)** こんにちは。今日は Python の基礎について解説します。
字幕のタイムスタンプをクリックすると、その時刻から YouTube を開けます。
チャプターが存在しない動画では Chapters セクションは出力されません。
9. 実践的な活用例
9.1. 講義動画から復習ノートを作る
yttext "LECTURE_VIDEO_URL" --summary-lang ja
字幕全文を保存しつつ、Gemini の要約も作成できます。
用途としては次のようなものがあります。
- 講義内容の復習
- 試験前の要点整理
- Markdown ノートの作成
- 動画を見直す箇所の検索
9.2. 海外の技術動画を日本語で読む
yttext "ENGLISH_VIDEO_URL" --summary-lang ja
字幕そのものは元言語で保存され、要約だけ日本語にできます。
そのため、
- 原文字幕で技術用語を確認する
- 日本語要約で全体像を把握する
- 必要な部分だけ動画へ戻る
といった使い方ができます。
9.3. 英語学習用に字幕を保存
要約を作らず字幕だけ取得します。
yttext "ENGLISH_VIDEO_URL" --no-summary
SRT：
yttext "ENGLISH_VIDEO_URL" -f srt -n
用途：
- リスニング後の答え合わせ
- フレーズ検索
- 単語検索
- 字幕プレイヤーへの読み込み
9.4. JSON にしてプログラムから処理
yttext "YOUTUBE_URL" -f json -n -o output/
用途：
- RAG 用データの前処理
- 字幕セグメント解析
- チャプター単位の処理
- 検索インデックスの作成
- 独自の要約処理
9.5. 長時間カンファレンスを Gemini で要約
yttext "CONFERENCE_VIDEO_URL" \
--summary-lang ja \
--long-summary full
字幕全文を Gemini へ送るため、モデルのコンテキスト上限や API 利用量を確認した上で利用します。
10. トラブルシューティング
10.1. 字幕が見つからない
次を確認します。
- 動画に手動字幕または自動生成字幕があるか
- YouTube が元言語字幕を取得可能な形で公開しているか
- URL / Video ID が正しいか
-
yttextやyt-dlpが古くないか
PyPI の uv 版：
uv tool upgrade yttext
pipx：
pipx upgrade yttext
Homebrew：
brew update
brew upgrade yttext
ソース版で yt-dlp を更新する場合：
uv lock --upgrade-package yt-dlp
uv sync
10.2. HTTP 429 が出る
YouTube 側から一時的にレート制限されている可能性があります。
時間を置いてから再実行します。
ローカル環境では、ログイン済みブラウザの Cookie を利用すると取得できる場合があります。
yttext "YOUTUBE_URL" -c chrome
10.3. HTTP 403 で字幕を取得できない
字幕へのアクセスが拒否されている場合があります。
ローカル環境で、その動画を閲覧できるブラウザの Cookie を試します。
yttext "YOUTUBE_URL" --cookies-from-browser chrome
10.4. Gemini 要約だけ失敗する
字幕取得と Gemini 要約は分離されています。
Gemini の処理に失敗しても、取得済みの字幕は利用できます。
確認する項目：
- Gemini API キーが有効か
- API クォータを超えていないか
- API キーの制限設定に問題がないか
- 選択した Gemini モデルが利用可能か
CLI では利用可能なモデルを確認できます。
yttext --list-gemini-models
Web アプリでは Load available models を利用できます。
10.5. Web アプリで API キーが消えた
ブラウザへ入力した Gemini API キーは、要約リクエストを送信するとクリアされます。
要約を再試行する場合は API キーを再入力します。
ローカルで毎回入力したくない場合は、サーバー起動前に GEMINI_API_KEY を設定します。
export GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
yttext web
環境変数を変更した場合は Web アプリを再起動します。
10.6. yttext web で依存パッケージのエラーになる
PyPI から CLI のみをインストールした環境では、Web 用依存パッケージが入っていません。
Web アプリを利用する場合は web extra を含めます。
uv tool install 'yttext[web]'
または：
pipx install 'yttext[web]'
Homebrew 版には Web アプリ用依存パッケージも含まれています。
11. コード構成
主要コードは src/yttext/ にあります。
src/yttext/
├── cli.py # CLI
├── web.py # FastAPI Web アプリ
├── web_state.py # 有効期限付きの短期要約ジョブ
├── service.py # 字幕取得・要約の共通ワークフロー
├── youtube.py # YouTube メタデータ・字幕取得
├── gemini.py # Gemini API クライアント
├── renderers.py # md/txt/json/srt/vtt の出力
├── summary_languages.py# 要約言語
├── models.py # データモデル
├── errors.py # エラー
├── utils.py # 共通処理
└── ui/ # Web UI
CLI と Web アプリは字幕取得処理を別々に持つのではなく、service.py を中心とした共通処理を利用します。
12. 開発環境
Web と開発用依存関係をインストールします。
uv sync --extra web --extra dev
Web アプリ：
uv run yttext web
リポジトリには起動用スクリプトもあります。
./scripts/run-app.sh
テスト
uv run --extra web --extra dev pytest
Ruff
uv run --extra web --extra dev ruff check .
フォーマット確認：
uv run --extra web --extra dev ruff format --check .
Web UI の JavaScript も構文確認できます。
node --check src/yttext/ui/app.js
node --check src/yttext/ui/enhancements.js
node --check src/yttext/ui/theme-control.js
13. 要約プロンプトをカスタマイズする
Gemini の要約プロンプトは次のファイルにあります。
src/yttext/gemini.py
_build_prompt() を編集すると、自分の用途に合わせた要約方針にできます。
たとえば技術動画向けなら、次のような要件を追加できます。
- 実装に使える具体例を優先する
- ベストプラクティスを整理する
- 注意点や典型的な失敗をまとめる
- コマンドやコード断片を可能な限り保持する
開発目的でカスタマイズする場合は、インストール済みパッケージを直接編集するのではなく、Git リポジトリを clone してソース版を利用する方が管理しやすいです。
14. 50,000 文字の基準
長文判定は次の定数で管理されています。
src/yttext/service.py
MAX_SUMMARY_LENGTH = 50_000
通常利用ではソースコードを書き換える必要はありません。
CLI では --long-summary、Web アプリでは長文検出後の選択画面から処理方法を決められます。
15. セキュリティ
yttext では字幕取得と Gemini の認証情報を分離して扱います。
字幕取得
字幕取得には Gemini API キーを必要としません。
Web アプリでも、字幕取得リクエストへ Gemini API キーを含める必要はありません。
Gemini API キー
ブラウザから Gemini を利用する場合、API キーは Gemini の処理時だけ FastAPI バックエンドへ送信されます。
バックエンドはそのキーを Google Gemini API の認証ヘッダーへ渡します。
アプリケーションは API キーを意図的に次の場所へ保存しません。
- URL
- レスポンス本文
- 字幕ファイル
- 要約ファイル
- 短期要約ジョブ
- ブラウザの localStorage / sessionStorage / Cookie
ローカル Web アプリ
ローカルモードでは、loopback からのアクセスに限り、サーバー環境の GEMINI_API_KEY をフォールバックとして使用できます。
環境変数に入っている API キーそのものがブラウザへ返されることはありません。
ホストされた Web アプリ
公開サーバーとして動作させる Hosted mode では、サーバー側の GEMINI_API_KEY と GEMINI_MODEL は使用しません。
各利用者が自分の Gemini API キーをブラウザへ入力する BYOK（Bring Your Own Key）方式です。
また、ホストされたサーバーから訪問者自身のブラウザ Cookie を読み取ることはできないため、ブラウザ Cookie 機能はローカル実行専用です。
16. まとめ
yttext は、YouTube の元言語字幕を取得し、必要に応じて Gemini で要約できる CLI / Web アプリです。
主な特徴をまとめると次の通りです。
- ✅ 字幕取得は API キー不要
- ✅ CLI と Web アプリの両方を利用可能
- ✅ PyPI から
uv/pipxでインストール可能 - ✅ Homebrew から CLI + Web アプリをまとめてインストール可能
- ✅ Markdown / Text / JSON / SRT / VTT に対応
- ✅ YouTube のチャプター情報を利用
- ✅ Markdown のタイムスタンプから動画の該当位置を開ける
- ✅ Gemini による構造化 Markdown 要約
- ✅ 要約言語を BCP 47 タグで指定可能
- ✅ 利用可能な Gemini モデルを取得可能
- ✅ 50,000 文字を超える字幕の扱いを選択可能
- ✅ ローカルではブラウザ Cookie を利用可能
- ✅ Gemini 要約が失敗しても字幕を利用可能
- ✅ Web では字幕・要約のプレビュー、コピー、ダウンロードに対応
- ✅ Hosted mode は BYOK 方式
長い YouTube 動画を最初から最後まで再生し直さなくても、まず字幕をファイル化し、必要に応じて Gemini で要約してから内容を確認できます。
講義、技術解説、カンファレンス、語学学習、RAG の前処理など、YouTube の字幕を「見るためのもの」だけでなく「再利用できるテキストデータ」として扱いたい場合に便利です。