yt

yt

エージェントと人間のためのYouTubeトランスクリプトです。静的なGoバイナリ1つで、APIキーもAIへの依存も実行時要件もありません。

• YouTubeの内部Innertube APIをANDROID／IOSクライアントコンテキストで利用し、動画自身の字幕トラック（手動または自動生成）を取得します。WEBクライアントの字幕URLは2025年半ば以降、pot-tokenによる制限がかかっており、空の本文を返します。
• innertube-android → innertube-ios → watch-pageの順にフォールバックするため、単一のエンドポイントが速度制限されても取得が中断されません。すべてのレスポンスで、どの方法が成功したか（source）が報告されます。
• チャンネルの監視：yt channel @handle（またはlist_channel_videos）でハンドルを解決し、チャンネルのRSSフィードから取得した正確な公開タイムスタンプとともに最新のアップロードを一覧表示します。エージェントはウォーターマークと比較して、新着動画を確認できます。
• 同じバイナリがMCPサーバーになります。yt mcp、または標準入力がパイプされている場合はyt（MCPクライアントが起動する形式）を使用します。ターミナルで単独のytを実行すると、ヘルプが表示されます。
• MCPレスポンスは、エージェントのコンテキスト予算を考慮して設計されています。上限付きペイロード、正確な再開位置を示す構造的な切り詰め、時刻／キュー指定の範囲、サーバー側検索、型付きエラー、セッション単位のキャッシュにより、get_video_info、get_transcript、search_transcriptが1回のプレーヤー取得を共有します。

依存関係：cobra（CLI）、modelcontextprotocol/go-sdk（公式MCP SDK）、golang.org/x/term（TTY検出）。YouTube取得レイヤーは標準ライブラリのみを使用します — net/http、encoding/json、encoding/xml。

レイアウト

リポジトリのルートはGoモジュール（github.com/ArasanDev/yt）であり、製品のルートでもあります。

cmd/yt/               binary entry point
internal/cli/         cobra commands and flags
internal/mcp/         MCP tool schemas, handlers, safety warnings
internal/youtube/     Innertube client, captions, channels, cache, typed failures
internal/search/      pure transcript search
internal/render/      block/cue rendering, SRT, truncation metadata
internal/transcript/  shared Segment/Transcript model and timestamp helpers
internal/apperr/      typed error contract (code, retryable, suggestion)
internal/version/     build version, commit, and date

CIは.github/workflows/ci.ymlにあり、gofmt、go vet、go test -race、ネイティブビルド、およびリリース対象のクロスビルドマトリックスを実行します。

依存関係は内側を向いています。cliとmcpはyoutube、search、render、transcriptに依存し、youtubeはapperrとtranscriptに依存します。searchとrenderが依存するのはtranscriptのみです。取得レイヤーがアダプターをインポートすることはありません。

インストール

Homebrew（macOS/Linux）

brew trust arasandev/tap          # Homebrew 7+ trusts third-party taps explicitly
brew install --cask arasandev/tap/yt

インストールスクリプト（macOS/Linux）

curl -fsSL https://raw.githubusercontent.com/ArasanDev/yt/main/install.sh | sh

スクリプトは、お使いのOS／アーキテクチャに対応する最新リリースをダウンロードし、checksums.txtと照合して検証した後、書き込み可能であれば/usr/local/bin、それ以外の場合は~/.local/binにインストールします。インストール先はYT_INSTALL_DIRで変更でき、バージョンはYT_VERSIONで指定できます。

YT_VERSION=v0.1.0 YT_INSTALL_DIR="$HOME/bin" \
  curl -fsSL https://raw.githubusercontent.com/ArasanDev/yt/main/install.sh | sh

Go開発者向け

go install github.com/ArasanDev/yt/cmd/yt@latest

go installはモジュールのバージョンを記録するため、ldflagsを注入できない場合でもyt --versionでリリースが報告されます。コミットと日付も記録するローカルビルドにはmake installを使用してください。

Docker

docker run --rm -i ghcr.io/arasandev/yt:latest mcp
# CLI use:
docker run --rm ghcr.io/arasandev/yt:latest transcript dQw4w9WgXcQ

イメージはdistrolessの静的ビルドです。TTYがない場合、単独のytですでにMCPを提供するため、コンテナーのデフォルトコマンドはmcpです。

Linuxパッケージ

リリースアセットには、amd64およびarm64向けの.deb、.rpm、.apkパッケージが含まれます。

sudo dpkg -i yt_<version>_linux_amd64.deb
sudo rpm -i yt_<version>_linux_amd64.rpm
sudo apk add --allow-untrusted yt_<version>_linux_amd64.apk

ビルド済みバイナリ

各リリースでは、アーカイブ、Linuxパッケージ、checksums.txtが公開されます。

https://github.com/ArasanDev/yt/releases

対象：amd64およびarm64向けのdarwin／linux／windows。Linuxではdeb／rpm／apkパッケージも提供されます。

ソースからビルド

git clone https://github.com/ArasanDev/yt.git
cd yt
make build          # ./bin/yt
make install        # into GOBIN with version/commit/date stamped

リリースビルドでは、バージョン、コミット、日付が記録されます（デフォルトはdevです）。

go build -trimpath -ldflags "\
  -X github.com/ArasanDev/yt/internal/version.Version=v0.1.0 \
  -X github.com/ArasanDev/yt/internal/version.Commit=$(git rev-parse --short HEAD) \
  -X github.com/ArasanDev/yt/internal/version.Date=$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -o bin/yt ./cmd/yt
yt --version

CLI

yt transcript <url-or-id>                       # transcript to stdout
yt transcript <url> -l en,es -t                 # language fallback + [MM:SS] stamps
yt transcript <url> --start 1274 --end 1290     # time range
yt transcript <url> -f srt -o subs.srt          # SRT file
yt transcript <url> -f json --max-chars 2000    # cue JSON, bounded
yt transcript <url> --bare                      # body only, no metadata header
yt transcript <url> --start-cue 120 --max-cues 40  # resumable cue window
yt search <url> "harness engineering"           # timestamped hits, no full read
yt search <url> "M C P" --match-mode any        # spelled acronyms collapse to mcp
yt search <url> "state of the art" --match-mode phrase
yt search <url> "harness" --context-cues 2      # human output shows context
yt tracks <url>                               # list caption languages
yt info <url>                                 # title, channel, duration, views, chapters
yt channel @aiDotEngineer --limit 10          # latest uploads (exact timestamps)
yt channel @aiDotEngineer --since 2026-10-01 --json
yt doctor                                     # probe which acquisition clients work
yt --version                                  # build version (or module version under go install)

watch?v=、youtu.be/、/shorts/、/live/、/embed/ の URL、または 11 文字の動画 ID をそのまま受け付けます。デフォルトでは、-f text にメタデータヘッダーが含まれ、必要な場合は切り詰めを示す末尾情報も含まれます。本文のみを標準出力に出力するには、--bare を使用します。この場合、切り詰めは標準エラー出力に報告されます。取得およびレンダラーに関する注記は、常に標準エラー出力に出力されます。

CLI の使用法エラーと上流の障害は、型付きで返されます。cmd/yt は標準出力をクリーンな状態に保ちながら、code、retryable、retry_after_seconds、suggestion を標準エラー出力に出力します。無効な形式、負の制限値、前後が逆転した時間範囲は、ネットワークリクエストを送信する前にエラーになります。

MCP

yt mcp は stdio JSON-RPC を提供します。標準入力がターミナルでない場合（MCP クライアントがサーバーを起動するとき）も、yt のみで同じように動作します。一方、プロンプトで yt のみを実行すると、ヘルプが表示されます。まず get_video_info を呼び出してください。字幕の有無、ライブ配信の状態、文字起こしの推定サイズが報告されるため、文字起こし全体を読むか、検索するか、範囲を指定して読むかを判断できます。

ツール	用途
list_channel_videos	RSS からチャンネル（@ハンドル／URL／UC…）の最新のアップロードを取得します。正確な公開時刻、タイトル、リンク、説明文の抜粋が含まれます。
get_video_info	メタデータ＋字幕の概要＋文字起こしサイズの推定値＋チャプター。文字起こしはダウンロードしません。
get_transcript	範囲を指定して取得できる、文字起こしテキストまたはキューの JSON。
search_transcript	トピックをタイムスタンプと前後の文脈付きで検索します。match_mode は all／any／phrase に対応し、結果が 0 件の場合はその理由が説明されます。
list_tracks	字幕トラック。非推奨 — get_video_info.captions を使用してください。

監視する場合は、list_channel_videos を呼び出し、前回の応答の newest_published を since として渡します。フィルタリング条件は厳密に published > since のため、同じ動画が重複して報告されることはありません。フィードが公開するエントリは最大 15 件で、動画の長さや再生回数は含まれません。これらの情報を取得するには、対象の動画に対して get_video_info を呼び出す必要があります。

get_transcript の主なパラメーター：languages（CSV、デフォルトは en。アップロード者自身の言語には original）、allow_translation、format（text|json）、granularity（デフォルトは block |cue）、timestamp_mode（デフォルトは block |cue|none）、start_seconds／end_seconds、start_cue／max_cues、max_chars（デフォルトは 50000。文字起こし本文のみを制限します）。

切り詰めが通知されないことはありません。ヘッダーに TRUNCATED next_start_seconds=… next_cue_index=… が記載され、構造化メタデータにも同じフィールドが含まれます。next_* の値は正確で、丸められないため、その値から再開しても境界のキューが抜け落ちることはありません。end_seconds も設定されている場合でも、max_cues による切り詰めは報告されます。エラーは isError の結果として返され、機械可読な error.code（bot_check、rate_limited、no_captions、bad_request、…）に加えて、retryable と suggestion が含まれます。

クライアントとの互換性のため、文字起こし本文は content と structuredContent の両方で返されます。そのため、応答サイズは本文のおよそ 2 倍になります。returned_chars は本文 1 つ分の文字数です。

自動吹き替えされた動画では、言語ごとに自動生成トラックが 1 つ表示されます。言語がアップロード者の既知の元の言語と異なるトラックは、手動か ASR かを問わず、translated=true として報告されます。これにより、機械翻訳された音声が話者本人の言葉として提示されることはありません。get_video_info.captions.original_language は、そのトラックの言語を示します。プレーヤーの応答に音声トラックのメタデータがなく、複数の字幕言語がある場合、元の言語は不明です。このとき languages=original は推測せず、対処方法を示す no_matching_language エラーを返します。また、original_language が空の場合もあります。その場合は、特定の言語を指定してください。

任意のエージェントに接続するには：

devin mcp add yt -- yt mcp          # Devin CLI
claude mcp add yt -- yt mcp         # Claude Code

または、生の mcpServers JSON（Devin、Claude Desktop、Cursor、Windsurf、…）を使用します：

{"mcpServers": {"yt": {"command": "yt", "args": ["mcp"]}}}

リリースと配布

v* タグを付けると .github/workflows/release.yml が起動し、次の処理を行います。

1. テストスイートと GoReleaser を実行します（アーカイブ、Linux パッケージ、チェックサム、GitHub Release）。
2. マルチアーキテクチャの ghcr.io/arasandev/yt イメージをビルドしてプッシュします。
3. バージョンを server.json に記録し、MCP レジストリに公開します。

git tag v0.1.0
git push origin v0.1.0

リポジトリに HOMEBREW_TAP_GITHUB_TOKEN シークレットがない場合、Homebrew cask の更新はスキップされます。このシークレットには、ArasanDev/homebrew-tap に対する contents: write 権限を持つ、きめ細かい PAT を設定してください。シークレットがなくても、バイナリ、Docker、MCP メタデータはリリースされます。cask を手動で追加するか、シークレットを追加して再実行してください。

MCP レジストリのジョブはベストエフォートで実行されます（continue-on-error）。GHCR パッケージはデフォルトで非公開です。パッケージ設定で yt パッケージを一度公開に変更してから、ジョブを再実行してください。レジストリは、イメージのアノテーション io.modelcontextprotocol.server.name と server.json の name が一致することを確認するため、両方の文字列を同期させてください。

タグ付け前に実行できる便利なローカルチェック：

goreleaser check
goreleaser release --snapshot --clean   # artifacts in dist/, never published
docker build --build-arg VERSION=dev -t yt:dev .

開発

make build          # ./bin/yt
make test           # go test -race ./...
make check          # gofmt + go vet + go test -race
make snapshot       # local GoReleaser snapshot
make clean

エージェントが維持すべきアーキテクチャ、契約、規約については AGENTS.md を参照してください。要点は、標準出力はデータ、標準エラー出力は診断情報であること、エラーは型付きであること、切り詰めは必ず通知され、再開ポインターは正確であること、出典情報と content_trust ラベルは必須であること、テストではネットワークにアクセスしないことです。

注意事項

• IP ブロック：データセンターの IP（AWS/GCP/VPS）は YouTube にブロックまたはレート制限され、bot_check または rate_limited として通知されます。住宅用 IP（お使いの Mac）からであれば問題なく動作します。サーバーで使用する場合は、クロスコンパイル（GOOS=linux GOARCH=arm64 go build）し、いずれ住宅用プロキシが必要になることを見込んでください。
• 自動生成（asr）字幕には句読点がないため、granularity=sentence は注記付きで block にフォールバックします。手動の字幕トラックが優先されます。要求された言語のトラックがない場合は YouTube の自動翻訳が使われ、結果には translated=true が設定されます。
• 複数音声吹き替え動画では、言語ごとに1つの ASR トラックが公開されます。languages=original は YouTube の音声トラックから字幕への対応付けを使って、実際のオリジナル言語を解決します。そのメタデータがない場合、オリジナル言語は不明となり、ツールは推測せず、対処方法を示すエラーを返します。
• 年齢制限付き動画や非公開動画には認証が必要です。現時点ではサポートされていません。
• search_transcript は、複数語のクエリを1つの字幕キュー内、または隣接する最大3つのキューにまたがって照合します。match_mode=any は AND 条件を緩和し、match_mode=phrase は隣接を必須とします。1文字のトークンが3つ以上連続する場合（M C P）は mcp にまとめられ、3文字以下の語は完全一致でのみ照合されます。結果が0件の場合は、語句ごとのヒット数と、不足している語句または開始キューの境界を示す注記が含まれるため、行き詰まりが通知されないままになることはありません。検索対象はトランスクリプト全体で、時間範囲による絞り込みにはまだ対応していません。
• chapters は説明文の Chapters: ブロックをもとに取得され、抜粋部分が切り詰められる前に説明文全体から解析されます。絵文字や Markdown の見出し、最初のエントリーをインラインで記述する形式も受け付けます。無効なエントリー、重複するエントリー、順序が前後するエントリー、動画の長さを超えるエントリーは除外されます。有効で、厳密に増加する動画の長さ以内のタイムスタンプが少なくとも2つ必要です。
• timestamp_window_seconds はタイムスタンプのモードに従います。ブロック単位のタイムスタンプでは 30、キュー単位または無効なタイムスタンプでは 0 です。ブロックのタイムスタンプは単一行ではなく、その時間範囲の開始時刻として引用してください。
• warnings は参考情報です。トランスクリプト、検索結果とコンテキスト、動画メタデータ、チャンネル一覧に含まれる、指示のようなテキストにフラグを付けます。これにより、呼び出し側はそのテキストに従うのではなく、引用できます。ユーザー生成コンテンツは、いずれの場合も content_trust: "untrusted" のままです。