trakt

Trakt メディアの発見

視聴されている作品、広く人気のある作品、注目を集めている作品を調べるには、このスキルを使用します。カタログのメタデータを提供するサービスではなく、読み取り専用の探索機能です。

セットアップと認証

Trakt OAuth applications でアプリを登録し、Client ID を環境変数としてエクスポートします。

export TRAKT_CLIENT_ID="YOUR_TRAKT_CLIENT_ID"

すべてのリクエストには、trakt-api-key: <client id> に加えて必須のヘッダー trakt-api-version: 2、JSON のコンテンツタイプ、内容がわかる User-Agent を指定する必要があります。公開されている探索エンドポイントでは、Authorization: Bearer ではなくキーのヘッダーを使用します。OAuth ベアラートークンは、OAuth が必須のエンドポイント、またはユーザーに紐づくリスト、履歴、コレクション、ウォッチリスト、変更操作に使用します。ベアラートークンでキーとバージョンの組み合わせを置き換えることはできません。

基本的なコマンド

6 つの探索コマンドはいずれも --page N と --limit N を受け付けます。デフォルト値はそれぞれ 1 と 10 で、API のクエリ文字列に渡されます。

Trending：過去 24 時間の視聴状況

trakt movie trending --limit 20
trakt tv trending --limit 20 --page 2 --json

Trending のレスポンスでは、各メディアオブジェクトが movie または show の中に含まれ、watchers の数も含まれます。

Popular：幅広い人気ランキング

trakt movie popular --limit 25 --json
trakt tv popular --page 2 --limit 25

Popular は評価の割合と評価数に基づくランキングであり、個人向けのおすすめではありません。

Anticipated：今後の注目度

trakt movie anticipated --page 3 --limit 10
trakt tv anticipated --limit 10 --json

Anticipated はリストへの掲載状況と今後の注目度を示すもので、公開カレンダーとは異なります。

グローバルフラグはリソースの前後どちらにも指定できます：--json、--dry-run、--quiet、--verbose。

パイプラインのレシピ

Trending の結果を別のツールに渡す

1. trakt --json movie trending --limit 20 を実行します。
2. .movie を取り出し、視聴状況を示す値として .watchers を保持します。
3. 利用可能な .movie.ids.tmdb または .movie.ids.imdb を後続のツールに渡します。不足している ID を生成できるとは限りません。

trakt --json movie trending --limit 20 |
  jq '.movies[] | {title: (.movie.title // .title), year: (.movie.year // null), watchers: (.watchers // null), ids: (.movie.ids // .ids)}'

探索シグナルを比較する

Trending、Popular、Anticipated の同じページを取得します（例：それぞれに --page 1 を指定）。結合する前に、各データセットにラベルを付けます。Trending は最近の視聴状況、Popular は幅広いランキング、Anticipated は今後の注目度を示します。

Anticipated をフィードの終わりまでページ送りする

--page を繰り返し指定し、JSON 出力の pagination.page_count を参照して終了するページを決めます。ページに項目がなければ、早めに終了します。

for p in $(seq 1 "$(trakt --json movie anticipated --page 1 --limit 100 | jq -r '.pagination.page_count')"); do
  trakt --json movie anticipated --page "$p" --limit 100 |
    jq --arg p "$p" '{page: ($p|tonumber), pagination: .pagination,
                      movies: [.movies[] | {title: (.movie.title // .title), year: (.movie.year // null)}]}'
done

ページごとの出力はラベル付き NDJSON として保持し、後で結合します。429 が返された場合は、ループを続ける前に Retry-After の時間だけ待機します。

JSON とページネーション

--json は、movies または shows の配列（Trending の項目はラッパーを保持します）と、API の X-Pagination-* ヘッダーに対応するキー page、limit、page_count、item_count を持つ pagination オブジェクトを出力します。ヘッダーが存在する場合、ページネーションの値は整数になります。ヘッダーがない場合はオブジェクトが空の {} になるため、.pagination.page_count // 1 のような jq の式でも安全に処理できます。人間向けの出力では、ヘッダーが存在する場合に Page N of M の行が追加され、ない場合は何も表示されません。互換性のため、API のデフォルトはページ 1、件数 10 です。再現可能な自動処理のため、両方を明示的に指定し、短いページが終端だと決めつけず page_count まで処理してください。

既知の注意点

• ヘッダーの組み合わせは必須です： trakt-api-version: 2 なしで trakt-api-key を送信した場合（またはその逆）、無効なリクエスト／認証エラーのような失敗が発生することがあります。付属のスクリプトは、ライブリクエストごとに両方を設定します。
• 401 と 403 の違い： 401 は通常、OAuth が必要な場合や認証が無効な場合を示します。403 は、アプリケーションキーが無効または未承認であることを示します。どちらもむやみに再試行しないでください。
• レート制限： 429 の場合は Retry-After を順守し、X-Ratelimit を確認してください。回数を制限して再試行します。一時的な 502／503／504 応答は、バックオフを入れて再試行できます。
• OAuth の更新： アクセストークンの有効期間は 7 日間で、リフレッシュトークンは 1 回限り使用できます。更新が成功したら、保存済みのリフレッシュトークンを置き換えてください。invalid_grant が発生した場合は、再認証が必要です。
• Trakt は TMDb ではありません： Trakt ID とディスカバリーのランキングは、TMDb のメタデータではありません。クレジット、画像、プロバイダーメタデータ、カタログの拡充には tmdb スキルを使用してください。
• トレンドデータの形式： タイトル／ID の前に .movie または .show を読み込み、watchers は保持してください。
• ページネーションは呼び出しごとです： CLI 呼び出し 1 回につき、1 ページ（--page）だけを取得します。スクリプトが自動でリンクをたどることを期待せず、pagination.page_count を読み取りながら呼び出しを繰り返してください。

使用する場合

現在の視聴状況、幅広い人気、今後の関心度、メディアのワークフローに利用する識別子を確認する場合は、Trakt を使用してください。

使用しない場合

個人の視聴履歴、ウォッチリスト、コレクション、リストの読み取りや更新には、この CLI を使用しないでください。これらのコマンドにも OAuth にも対応していません。トークンを指定しても利用可能にはなりません。この制限を説明し、個人的な操作には Trakt のウェブサイト、または別途実装した認証済みクライアントを使用してください。存在しない CLI コマンドを作り上げたり、要求された更新が成功したと主張したりしないでください。カタログのメタデータ、クレジット、画像、プロバイダーの利用可否には tmdb を使用してください。

参考ファイル

ファイル	トピック
references/auth-and-request-contract.md	必須ヘッダー、OAuth の範囲、エラー、レート制限
references/discovery-endpoints.md	エンドポイントの仕様、フィルター、レスポンス形式、ページネーション
references/recipes-and-operations.md	パイプライン、jq による正規化、運用時の処理

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

• scripts/trakt は、標準ライブラリと requests のみを使用する実行可能な Python CLI です。
• --dry-run は Client ID がなくても動作し、ネットワーク I/O は一切行いません。
• ライブのディスカバリーには TRAKT_CLIENT_ID が必要です。テストはモックのみで行います。