peertube

peertube — ターミナルからPeerTubeのフェデレーション動画を利用

フェデレーション型のデプロイであり、単一のAPIではないPeerTubeインスタンスを、ターミナルから閲覧できます。インスタンス統計、最新動画、動画の詳細、コメントスレッド、チャンネル、アカウント、インスタンス内検索を利用できます。自分のアカウントのコマンドを実行する場合に限り、OAuth2で認証します。login／logout以外のコマンドはすべて読み取り専用です。

セットアップ

1. 接続先のインスタンスを選択します。すべてのコマンドはインスタンス単位です。APIの形式はどこでも同じですが、アカウント、トークン、ルール、カタログは異なります。

export PEERTUBE_SERVER="https://<INSTANCE_HOST>"   # e.g. https://tilvids.com

1つのインスタンスではなくフェディバース全体を検索するには、同じ変数に公開検索インデックスを指定します：PEERTUBE_SERVER=https://sepiasearch.org（APIの形式は同じです。詳しくはreferences/search-and-discovery.mdを参照してください）。

2. 閲覧に必要な設定はほかにありません。動画、検索、チャンネル、コメント、インスタンス情報は匿名で読み取れます。

3. （任意）自分のアカウントのコマンド（me、my-videos）を実行する場合に限り、ログインします。

scripts/peertube login --username <NAME> --prompt

認証の仕組み

PeerTubeではインスタンスごとのクライアント認証情報を使用する、標準的なOAuth2を採用しています。CLIは匿名でGET /api/v1/oauth-clients/local（単数形のlocal）からクライアントのペアを取得し、続いてユーザー名とパスワードをPOST /api/v1/users/tokenに送信してベアラートークンと交換します（grant_type=password、フォームエンコード）。トークンはAuthorization: Bearer <token>で送信され、インスタンスで設定された有効期間中利用できます（レスポンスのexpires_inを読み取り、固定値を想定しないでください）。有効期限が切れると自動的に更新されます。トークンファイルはサーバーURLをキーとして~/.config/peertube/token.jsonに所有者のみが読み取り可能な状態で保存されます。 トークンをコミットしないでください。トークンはアカウント認証情報です。使用後はscripts/peertube logout（POST /users/revoke-token）で取り消してください。現在の本番インスタンスではAPIレスポンス内のclient_secretがマスクされています。CLIはこれを検出し、回避方法を説明します。詳細と通信レベルのエラー形式については、references/auth-and-tokens.mdを参照してください。

主なコマンド

server — インスタンスの統計情報と識別情報（匿名）

scripts/peertube server              # name, description, user/video/view counters
scripts/peertube server --json

GET /config/aboutとGET /server/statsを組み合わせます（正規のパスはこれらです。/instance/statsはありません）。

videos — インスタンスにアップロードされた動画を閲覧（匿名）

scripts/peertube videos                       # latest 15, offset pagination
scripts/peertube videos --limit 50 --offset 50
scripts/peertube videos --sort -views --json  # popular first

ページネーションにはstart／countオフセットを使用します（countの最大値は100）。APIに**pageパラメーターはありません**。

search — このインスタンスの動画を検索（匿名）

scripts/peertube search --query "linux"            # instance-local (searchTarget=local)
scripts/peertube search -q "docker" --limit 20 --json
PEERTUBE_SERVER="https://sepiasearch.org" scripts/peertube search -q "linux"   # fediverse-wide

同梱のCLIで実行できるのはインスタンス内検索のみです（searchTarget=local）。フェディバース全体を検索するには、PEERTUBE_SERVERにSepiaSearchを指定します。コマンドは同じままで、検索対象のインデックスが広がります。検索結果には、フェデレーションされた検索結果の配信元インスタンスを示すchannel.host／urlが含まれます。

video — 1つの動画の詳細（匿名）

scripts/peertube video --id <UUID>          # numeric id, UUID, or shortUUID all work
scripts/peertube video --id <UUID> --json | jq '{name, description, views, url}'

comments — トップレベルのコメントスレッド（匿名）

scripts/peertube comments --id <UUID>                 # GET /videos/{id}/comment-threads
scripts/peertube comments --id <UUID> --limit 30 --json

channels / channel / account — クリエイター（匿名）

scripts/peertube channels --limit 20 --json           # instance channel list
scripts/peertube channel --handle [email protected]   # name or name@host
scripts/peertube account --name [email protected]

channelはメタデータと、そのチャンネルのアップロード動画（オフセットによるページネーション）を表示します。

me / my-videos — 自分のアカウント（ログインが必要）

scripts/peertube me --json | jq '.role.label'
scripts/peertube my-videos --limit 50 --json

login / logout — OAuth2セッション管理

scripts/peertube login --username <NAME> --prompt        # hidden prompt
echo "<PASSWORD>" | scripts/peertube login --username <NAME> --password-stdin
scripts/peertube login --username <NAME> --otp <CODE>    # 2FA-enabled accounts
scripts/peertube logout                                   # revoke server-side + delete file

グローバルフラグ

scripts/peertube --json videos                     # flag before or after the subcommand
scripts/peertube videos --json
scripts/peertube --dry-run search --query test     # request plan, zero network
scripts/peertube --verbose videos --limit 2        # trace requests on stderr
scripts/peertube --server https://tilvids.com server   # per-invocation instance override

--dry-runは{"dry_run": true, "method", "path", "params"}を出力します（loginでは値を出さず、form_fields名のみを追加します）。実際に実行する前に、jqの処理チェーンを検証するために使用してください。--helpと--dry-runに認証情報は必要ありません。

パイプラインの使用例

検索して、上位の結果を確認

scripts/peertube search --query "linux" --limit 5 --json | jq -r '.videos[0].uuid'
scripts/peertube video --id "$(scripts/peertube search -q linux --limit 1 --json | jq -r '.videos[0].uuid')" --json

チャンネルのアップロード動画をページごとに取得

scripts/peertube channel --handle [email protected] --limit 100 --offset 0 --json | jq -r '.videos[].name'
# loop: advance --offset by the returned count until you reach .total (no page param exists)

インスタンスの概要レポート

scripts/peertube server --json | jq '{name: .instance.name, videos: .stats.totalLocalVideos, users: .stats.totalUsers, views: .stats.totalLocalVideoViews}'

ログインして、割り当て量を確認し、ログアウト

scripts/peertube login --username <NAME> --prompt
scripts/peertube me --json | jq '{username, role: .role.label, quota_bytes: .videoQuota}'
scripts/peertube logout

JSON と jq

--json の出力キーは、API の生オブジェクトを安定した snake_case でラップしたものです。videos （API の {total, data} リストオブジェクト）、channels、threads（total_not_deleted を含む）、 instance と stats、channel、プラン用の dry_run／method／path／params です。動画 オブジェクトは PeerTube 独自のフィールド名（uuid、shortUUID、name、duration （秒）、views、publishedAt、account{name,displayName,host}、 channel{name,displayName,host}）を保持するため、jq セレクターを /api/v1 に対する生の curl にもそのまま適用できます。例：jq -r '.videos[] | [.name, .views, .channel.displayName] | @tsv'。

既知の注意点

• インスタンスはそれぞれ独立しています（単一の API ではなく、連合しています） — アカウント、トークン、ルール、 有効な機能、カタログはインスタンスごとに異なります。インスタンス A のトークンをインスタンス B で使うと 401 が返されます。 CLI はサーバー URL ごとにトークンファイルを管理します。インスタンスに連合されているコンテンツも、そのオリジンに属します （channel.host、動画の url）。
• 検索範囲には異なる 2 種類があります — searchTarget=local はインスタンス独自のカタログを検索し、 search-index（または SepiaSearch のベース URL）は外部インデックスを通じて フェディバースを検索します。searchTarget を省略すると、現在のサーバーではフェディバースではなく、 インスタンス独自の範囲が対象になります。同梱の CLI は、sepiasearch.org を指定しない限りインスタンス内を検索します。
• page は存在しません — コレクションのページネーションには start／count（最大 100）を使います。 page= を送信するクライアントは、エラーを返さずに最初のページを延々と再取得します。
• コメントのルートは /comment-threads（ハイフンあり）です — /comments と /commentthreads はルートではありません（現在のサーバーでは 400 が返されます）。
• インスタンスのメタデータパスは混在しています — 統計情報は /server/stats（操作名は 「instance stats」）、概要は /config/about、設定は /config です。/instance/* の メタデータパスは存在しません。
• 本番環境では client_secret がマスクされます — oauth-clients/local は現在の本番インスタンスで "********************************" を返します。マスクされた値でトークンをリクエストすると 400 が返されます。 CLI はこれを検出し、フロントエンドアセットを使う回避策を説明します。古いクイックスタートの curl 例には response_type=code が含まれていますが、現在のトークンスキーマには含まれません。CLI はこれを省略します。
• トークンの有効期間はインスタンスごとに設定できます — レスポンスごとに expires_in を読み取ります。 CLI は絶対時刻の expires_at を保存し、自動で更新します。トークンは所有者のみがアクセスできるように保存し、 決してコミットしないでください。ログアウト時には失効させてください（ファイルを削除しただけでは セッションは有効なままです）。
• 2FA には OTP ヘッダーが必要です — トークンリクエストに x-peertube-otp を指定します。CLI は 401 が返された場合に「--otp を渡してください」と案内します。
• レート制限 — デフォルトでは IP ごとに 10 秒あたり 50 回（トークンエンドポイントはより厳しい制限）です。429 が返された場合は Retry-After を読み取り、待機時間を空けて再試行してください。エラーは RFC7807 の application/problem+json 本文を使います。 不明なルートには 404 ではなく 400 が返されるため、本文を確認してください。
• duration は秒単位です。ID は 3 種類（id、uuid、shortUUID）があり、いずれも詳細エンドポイントで受け付けられます。 role は {id, label} というオブジェクトで、videoQuota はバイト単位です。
• 匿名アクセスと認証済みアクセス — ブラウジング／検索／コメント／インスタンス情報にはトークンは不要です。 /users/me* と更新操作には常にトークンが必要です。

使用する場面

PeerTube インスタンスを読み取り専用で操作する場合に、このスキルを使います。動画の閲覧や絞り込み、 インスタンス内またはフェディバース全体の検索（SepiaSearch 経由）、動画の詳細やコメントの確認、 チャンネル／アカウントの調査、インスタンス統計情報の取得、OAuth2 を使った自身のアカウント セッションの管理（ログイン、プロフィール、マイ動画、ログアウト）が対象です。

使用しない場面

YouTube、Vimeo、その他のプラットフォームへのアップロードや動画編集／トランスコードには、このスキルを使わないでください （各プラットフォーム独自のツールや ffmpeg に振り分けてください）。PeerTube サーバーのインストール、 ホスティング、管理にも使わないでください（インスタンス管理は対象外です。同梱の CLI でできるのは 読み取りとログイン／ログアウトのみです）。また、ActivityPub／Mastodon の一般的な連合に関する質問には使わず、 Mastodon または ActivityPub のスキルを使ってください。

参考ファイル

ファイル	用途
references/auth-and-tokens.md	OAuth2 フロー（oauth-clients/local、パスワードグラント）、シークレットのマスキング、トークンの更新／失効、トークンファイルの取り扱い、通信プロトコルのエラーシグネチャ
references/search-and-discovery.md	searchTarget の local と search-index の違い、SepiaSearch の仕様、検索パラメーターと並べ替え
references/endpoint-catalog.md	すべての読み取りエンドポイントのパラメーター、レスポンス形式、ページネーション、レート制限
references/gotchas-field-guide.md	すべての障害シグネチャとバージョン差異に関する、症状 → 原因 → 対処法の表
references/worked-recipes.md	複数ステップの CLI／jq ワークフロー、curl による認証の一連の手順、jq の処理パターン

利用可能なスクリプトと前提条件

• scripts/peertube — 同梱の Python CLI（--json、--dry-run、--verbose、 --server によるオーバーライド）。標準ライブラリと requests のみをインポートします。
• scripts/test_peertube.py — オフラインのテストスイート（pytest および unittest に対応）。HTTP はすべてモックされ、ネットワークへの外部接続は一切ありません。
• Python 3.8 以降と requests が必要です。到達可能な任意の PeerTube インスタンス（または SepiaSearch）を利用できます。デフォルトでは認証情報は存在せず、必要もありません。このスキルによってサービスが起動されることはありません。