使い方

このページでは、PosterPilot を インストール して 設定 した後の、日々のワークフローを順を追って説明します。

初回インストールウィザード

新規インストールでは、バナーが /setup のウィザードへ案内します。これは 6 つのステップを 順を追って案内し、進めるごとにそれぞれを永続化します：

1. 言語 — UI のロケールを選びます。
2. メディアサーバー — Plex、Jellyfin、または Emby を選びます。Plex の場合は PIN で サインインでき（PosterPilot がコードと認証リンクを表示し、取得したトークンを保存します）、 検出されたローカル／リモート接続を選べます。Jellyfin と Emby はサーバー URL を取り、 ユーザー名とパスワードでサインイン できます — PosterPilot がそれらをアクセストークンと 引き換えるため、API キーを探し回る必要はありません（パスワードはその 1 回のリクエストにのみ 使われ、保存されることはありません。キーを手動で貼り付けることもフォールバックとして 引き続き利用できます）。テスト ボタンが接続を検証します。
3. TMDB — TMDB API キーを貼り付けます（TMDB の API 設定へのリンクが提供されます）。
4. プロバイダー — アートワークプロバイダー（MediUX、TMDB、Fanart.tv、ThePosterDB）を 切り替え、使用する場合は Fanart.tv キーを入力します。
5. ライブラリ — 接続されると、ウィザードは映画と番組のライブラリを一覧表示します。 同期するものにチェックを入れます（デフォルトではすべて選択されており、後から追加する ライブラリも取り込まれます）。
6. 最初の同期 — 初回の同期を実行し、それからダッシュボードへ移動します。

ウィザードはいつでも スキップ可能 です（スキップ リンクはダッシュボードへ直接移動します） — ウィザードが網羅する内容はすべて 設定 でも利用できます。

ライブラリを同期する

同期は、アクティブなメディアサーバーから映画と番組のライブラリを PosterPilot のローカル キャッシュに取り込み、各タイトルを TMDB id に解決して、アートワークプロバイダーに問い合わせ できるようにします。

1. アクティブなサーバータイプの認証情報と TMDB キーが構成されていることを確認します。 構成されていない場合、同期はブロックされます（何が欠けているかについての明確なメッセージ付き）。
2. 任意で、同期するライブラリ チェックリスト（ウィザードまたは設定 → メディアサーバー） または INCLUDED_SECTIONS で、どのセクションを同期するかを絞り込みます — すべての映画と 番組のセクション（後から追加するものも含む）を同期するには、空のままにします。
3. ダッシュボード（同期 ボタン）から同期を実行します。これはライブ進捗がその場に 表示されるバックグラウンドジョブとして実行されます。実行中、統計カード（アイテム数、映画、 番組、解決済み、MediUX あり、適用済み）が増えていきます。

各アイテムは、そのタイトル、年、タイプ、外部 GUID（存在する場合は tmdb/imdb/tvdb）、 および現在のポスターとともに返されます。外部 GUID を持たないアイテムも一覧には表示されますが、 削除されるのではなく、プロバイダー検索では解決不能としてフラグが立てられます。

繰り返しの同期はデフォルトで 増分 です：PosterPilot は各アイテムをメディアサーバーの 最終更新タイムスタンプと比較し、前回の同期以降に変更されたものだけを再解決・再エンリッチ するため、定例の再スキャンは初回よりもはるかに高速です。すべてを再処理する フルスキャン も引き続き利用でき、増分同期を完全にオフにすることもできます（ 設定 → パフォーマンスとチューニングを参照）。

ライブラリウォール

同期されたライブラリは、Notion 風のツールバーを備えたポスターグリッドとしてレンダリング されます。次のことができます：

• タイトルで 検索 する。
• フィルタ ポップオーバーから フィルタ する：メディアタイプ（映画 / 番組）、最低評価、 ジャンル、ポスター欠如、MediUX の利用可否（候補あり）、変更状態（変更なし / まだデフォルトの ポスターのまま）、および無視状態。フィルタボタンには、アクティブなファセットの数を示す バッジが表示されます。
• ソート ポップオーバーから、タイトル、公開年、評価、再生時間、最近変更された順、または メディアサーバーへの追加日で ソート する。昇順／降順の切り替えは独立しています。 ウォールは 設定 → Kometa と詳細設定 で構成されたソート（デフォルト：タイトル）で 開きます。ツールバーでの明示的な選択が常に優先されます。
• アクティブな各フィルターとソートは、ツールバーの下に 削除可能なチップ として表示されます — チップの ✕ をクリックするとそれだけを外せ、すべてクリア ですべてをリセットできます。
• 自動適用（⚡ ボタン）を切り替える：オンにすると各変更がすぐに反映され、オフにすると 適用 を押すまで変更がステージングされます。この選択は記憶されます。
• 手を加えたくないアイテムを 無視 する — 無視されたアイテムは検出、適用、自動選択から スキップされ、ウォール上で視覚的にマークされ、フィルタポップオーバーで表示／非表示を 切り替えられます。いつでも再びオフに切り替えて、アイテムをワークフローに戻せます。
• スポットライトバナー を表示する — 少なくとも 1 つのカバーが適用されると、ウォールの上に 最近変更されたアイテムの背景が表示されます。

各タイルには、アイテムの評価とステータスバッジ（例：MediUX 利用可能、変更済み）が表示され、 ホバーするとタイトルと年が表示されます。

カバーを見つける

アイテムを開くと、その詳細ビューが表示されます：アイテムのロゴ（ロゴがない場合はタイトル）、 評価、年、再生時間（番組の場合はシーズン／エピソード数）、ジャンル、概要を備えた背景ヒーロー、 そして主要キャストも表示されます。

• カバーがまだ検出されていない場合は、カバーを見つける を使ってそのアイテムの検出を 実行します。
• 検出はすべての有効なプロバイダーをまたいで展開し、それらの候補の和集合を保存して、 それぞれにそのプロバイダーのタグを付けます。
• 候補は まずプロバイダーごとに、次にセットごとに グループ化されます。各セットには、 ポスターと背景をまとめてアップロード者の帰属が表示されます。番組の場合、ビューには シーズンポスターのセットとタイトルカードのセットも表示されます。
• プロバイダーのセクション、個々のセットカード、そして（番組の場合）シーズングループは 折りたたみ可能 です。初回読み込み時は最初のプロバイダーとその最初のセットが展開され、 それ以外はすべて折りたたまれます。折りたたみ／展開の選択はブラウザに保存され、再読み込み 後やアイテム間を移動しても保持されます。
• おすすめアートワーク が有効な場合、各スロットで最高スコアの候補が、受け入れるか上書き できる明確にマークされたおすすめとして事前選択されます。候補はプロバイダーの品質、解像度、 アスペクト比の適合度でスコア付けされます。重みの調整 — またはこの事前選択のオフ — は設定で 行えます（設定 → パフォーマンスとチューニングを参照）。

セット全体をステージング（「このセットを使う」）することも、あるセットから個別のポスターを、 別のセットから背景を取ることもできます — 2 つのスロットは独立しています。

シーズンとエピソードのアートワーク

番組の場合、アートワークはスロットごとにステージングされるため、番組カバー、各シーズンの ポスター、各エピソードのタイトルカードは、互いに独立しています：

• セットのアートワークは、番組グループ（ポスターと背景）と、シーズンごとに 1 つの グループ に整理されます。各シーズングループは、そのシーズンのポスターとそのエピソードの タイトルカードを保持します。（シーズン背景スロットはモデル上に存在しますが、現在シーズン 背景を提供するプロバイダーがないため、表示されません。）
• シーズンまたはエピソードのスロット内で候補を選択すると、番組レベルや他のどのスロットにも 触れることなく、そのスロットだけがステージングされます。すでにスロットにステージングされて いる候補を再選択すると、それが再びクリアされます。
• このセットを使う は、セットがカバーするすべてのスロット — 番組、各シーズン、各 エピソード — を、シーズン番号とエピソード番号で照合して一度に埋めます。その後、任意の単一 スロットを上書きし、セットの残りをステージングしたまま保つことができます。

スティッキービルダーは、現在ステージングされているすべて — 番組のポスター／背景に加えて、 ステージングされたシーズンとエピソードの数 — を要約し、単一の 適用 がそのすべてを 1 つの アクションで書き込みます（カバーを適用するを参照）。

カバーを適用する

ステージングした選択を、選んだ方法で適用します。適用アクションごとに選択でき、設定可能な デフォルトがあります（DEFAULT_APPLY_METHOD、デフォルトは both）：

• メディアサーバー（直接）。 アクティブなメディアサーバープロバイダーを通じてポスター （と背景）をアップロードし、サーバーの自動エージェントがそれを上書きしないようフィールドを ロックします。変更は実質的に即座に反映されます。プロバイダーのタイプとともにサーバー適用 として記録されます。
• Kometa エクスポート。 メディアサーバーに接触せずに、構成された Kometa アセット ディレクトリに Kometa/PMM 互換の YAML — TMDB id をキーとした url_poster（背景が ステージングされている場合は url_background）— を書き込みます。既存の Kometa インスタンスが 次回の実行時にカバーを適用します。再適用すると、エントリは複製されるのではなくその場で 更新されます。
• 両方。 直接アップロードを実行 し、かつ Kometa YAML を書き込み、それぞれの結果を独立して 記録するため、部分的な失敗が見えるようになります。

単一の適用は、ステージングされたすべてのスロット — 番組、シーズン、エピソード — を、 選んだ方法で書き込みます。直接アップロードの場合、PosterPilot はメディアサーバー上の各 シーズンとエピソードの子を番号で解決してそこにアップロードします。シーズンまたはエピソードが サーバー上に一致する子を持たないステージング済みスロットは、適用全体を失敗させるのではなく スキップされて報告され、1 つの子の失敗が残りを中断させることは決してありません。Kometa エクスポートは、ステージングされたシーズンポスターを seasons:（シーズン番号をキーとする）の 下に、ステージングされたエピソードのタイトルカードを episodes:（エピソード番号をキーとする） の下に、番組レベルの url_poster / url_background と並べて入れ子にします。シーズンの 背景 は直接方法でのみ適用され — YAML からは省略されます。

すべての適用 — 成功でも失敗でも — は、アイテム、アセット URL、方法、結果、タイムスタンプ とともに記録されるため、履歴をクエリでき、再適用を検出できます。

Kometa がエクスポートを消費する方法

PosterPilot は KOMETA_ASSETS_DIR に、TMDB id をキーとし url_poster / url_background エントリを持つ単一のメタデータファイル（デフォルト posterpilot.yml）を書き込みます。Kometa が 次回の実行時にカバーを適用するよう、そのファイルを Kometa のライブラリ設定（例： metadata_path / metadata_files の下）に追加してください。

元に戻す

適用したすべてのカバーは、アイテムの詳細ビューから元に戻せます：

• オリジナルに戻す は、番組レベルのアートワーク と、適用されたすべてのシーズンと エピソード を 1 つのアクションで元に戻し、PosterPilot が変更する前にメディアサーバーが 持っていたものを復元します。
• 各シーズングループには独自の シーズンを元に戻す コントロールがあり、そのシーズンの ポスター／背景とそのエピソードのタイトルカードだけを元に戻し、番組レベルや他のシーズンの アートワークはそのままにします。

元に戻す処理は、適用と同じ方法で、シーズンとエピソードの子を番号で再解決します。

カスタムセット

アイテムの詳細ビューには、ポスタースロットと背景スロットを持つ永続的でスティッキーな ビルダー があり、これらが一緒になってカスタム「セット」を形成します：

• ポスター候補をクリックするとポスタースロットに、背景候補をクリックすると背景スロットに ルーティングされます — 種類によって自動的に行われます。
• 各スロットは、貼り付けた画像 URL または アップロードした画像ファイル からも 埋められます。
• ビルダーを適用すると、ステージングされた両方のピースが、選んだ方法で 1 つのアクションで 適用されます。

アップロードはサーバー専用

URL ベースのカスタムカバーは、メディアサーバーと Kometa の両方で適用できます。 アップロードしたファイル はメディアサーバー経由でのみ適用できます — バイナリアップロードは Kometa YAML の URL として表現できないため、Kometa エクスポートからは省略され、無効なエントリを 書き込むのではなく、その制限が見えるようになっています。

一括アクション

複数のアイテムを選択し、選択範囲全体にわたる検出かつ／または適用を、単一のバックグラウンド ジョブとして実行します。自動選択を伴う一括適用は、（必要なら）検出し、自動選択し、選択した 各アイテムにカバーを適用します。ライブ進捗付きです。

自動選択は、すべての有効なプロバイダーにまたがってすべての候補をスコア付けし — プロバイダーの 品質、解像度、アスペクト比の適合度を組み合わせて — 各アイテムについて最高スコアのポスター （および利用可能な場合は背景）を選びます。これは、アイテムビューのおすすめ事前選択を駆動する スコアリングと同じものです。無視されたアイテムは選択から除外されます。

一括適用が実行される前に、ドライラン プレビュー が何が起こるかを正確に要約します — 予定 されているアップロード、Kometa エクスポート、およびスキップされるアイテムやスロット — ので、 何かが書き込まれる前に確認できます。その後、一括適用はアイテムを 並行して 処理し（適用 並行数の設定で上限が定められます）、大きなバッチがより速く完了します。ライブ進捗とキャンセルは 同じです。

FUN：ランダムな映画／シリーズピッカー

FUN は、ライブラリ実験のためのオプトインのセクションです（設定 → Kometa と詳細設定 の FUN トグル、または FUN_ENABLED=true で有効にします）。それまでは完全に隠されたままです — ナビゲーション項目はなく、そのページは 404 を返します。

最初のツールは「今夜は何を観る？」に答えます：ワンクリックで、同期されたライブラリから ランダムに 1 つのタイトルを引き、それを画像前面で — 背景、ポスター、ジャンル、評価、概要 とともに — 提示します。アイテムへのリンクと、同じフィルタのもとで再び引く もう一度選ぶ ボタン付きです。引き当ては次の条件で絞り込めます：

• 種類 — 映画、シリーズ、または両方。
• ジャンル — ライブラリのジャンルの 1 つ、またはすべて。
• 年の範囲 — 任意の最小かつ／または最大の公開年。
• 視聴済み — すでに観たタイトルをスキップします。視聴状態はライブラリの同期中に取得 されます（Plex は再生回数、Jellyfin/Emby は再生済みフラグ — シリーズは、すべての エピソードが再生されている場合にのみ視聴済みとしてカウントされます）。

ノート

Jellyfin/Emby では再生済みフラグにユーザーコンテキストが必要なため、生の API キーではなくユーザー名とパスワードでサインインしてください — API キーだけでは、 すべてが未視聴として同期され、視聴済みスキップのフィルタには除外するものが何も ありません。

ダッシュボードとジョブ

ダッシュボード はホームベースです。ライブラリの統計カード、同期 ボタン、そして ライブ進捗バー（手動更新なしで Server-Sent Events 経由で更新）付きの実行中のジョブを表示し、 それらを キャンセル できます。ダッシュボードの隣のナビバッジは、いくつのジョブがアクティブ であるかを反映します。その下の 最近のジョブ テーブルには、最新のジョブがそのタイプ、 処理済み／合計の数、最終ステータスとともに一覧表示されます。別のジョブページはありません — ライブ進捗も最近の履歴も、どちらもダッシュボードにあります。

アクティビティログ

きめ細かいイベントログは 設定 → アクティビティ にあります。すべての操作イベントがそこに 記録されます（そしてコンテナのコンソールとローテーションするファイルログにもミラーされます）。 次のことができます：

• レベルで絞り込む — すべて / Info / Warn / Error。
• さらに読み込む で履歴をページ送りする。
• アクティビティをクリア でアプリ内のテーブルを消去する（これはディスク上のログファイルを 削除しません）。

テーブルは EVENT_RETENTION 行（デフォルト 2000）で上限が設けられ、古い行は自動的に削除 されます。ファイルログと保持の詳細については 設定 → ロギングとアクティビティログ を参照してください。