コンテンツにスキップ
PosterPilot PosterPilot PosterPilot

設定

PosterPilot は 2 つの方法で設定され、それらは連携して機能します：

  • 環境変数 — コンテナに設定します。無人セットアップやシークレット管理に適しています。
  • アプリ内の設定ページ — UI で入力し、/data 下の SQLite データベースに永続化される ため、再起動後も残ります。設定はタブに分かれています：メディアサーバー、 メタデータとプロバイダー、Kometa と詳細設定、言語、そして アクティビティ （アプリ内のイベントログ）。/setup のガイド付き 初回インストールウィザードは、新規インストール において同じ範囲を順を追って網羅します。

環境変数 vs. 設定 UI

Section titled “環境変数 vs. 設定 UI”

任意の設定について、環境変数は常に永続化された UI 値より優先されます。値が環境経由で 与えられると、設定ページはそれを 環境管理済み として表示し、UI での編集をロックします — そのため、信頼できる情報源が曖昧になりません。

値がどちらの場所にも設定されていない場合、文書化されたデフォルト（あれば）が適用されるか、 それに依存する機能は設定するまで未構成のままになります。

シークレット（Plex トークン、Jellyfin/Emby の API キー、TMDB 認証情報、および Fanart.tv キー）は、保存後にブラウザへ送り返されることは決してなく、ログからは編集（除去） されます — 設定ページはシークレットが 設定されている ことを示すだけです。

シークレットと暗号化

Section titled “シークレットと暗号化”

これらと同じシークレット — Plex トークン、Jellyfin と Emby の API キー／アクセストークン、 TMDB 認証情報、および Fanart.tv キー — は、SQLite データベースに書き込まれる前に AES-256-GCM で 保存時に暗号化 されます。保存される各値は自己記述的で（enc:v1: というプレフィックスを 持ちます）、そのため PosterPilot は暗号化された値とレガシーの平文を区別できます。

  • デフォルトでゼロセットアップ。 初回実行時に PosterPilot はランダムな 32 バイトの インスタンスキーを生成し、それを data/.app-key に — 所有者のみ読み取り可能な状態で — 永続化します。構成するものは何もありません：シークレットは自動的に暗号化されます。 （必要なら APP_KEY_FILE でパスを上書きできます。）
  • 共有デプロイ向けのポータブルキー。 任意の APP_SECRET 環境変数を設定すると、あなたが 管理する値から（scrypt で決定論的に）キーを導出します。1 つのデータベースを共有する複数の レプリカを実行する場合や、キーファイルを持ち回ることなくコンテナを再作成しても同じキーを 存続させたい場合に使用します。APP_SECRET が設定されている場合は、生成された data/.app-key より優先されます。
  • 既存のインストールは壊れません。 古いバージョンが平文として保存したシークレットは透過的に 読み取られ、その設定が次に保存されるときに再暗号化されます — 手動での再入力は不要です。
  • 安全な失敗。 シークレットを復号できない場合（例えばキーが失われたり変更されたりした 場合）、PosterPilot はそれを未設定として扱い、クラッシュするのではなく再入力を促します。

メディアサーバー

Section titled “メディアサーバー”

PosterPilot は一度に 1 つのアクティブなメディアサーバーと通信し、それは SERVER_TYPE （plex、jellyfin、または emby。デフォルトは plex）で選択されます。同期の前には アクティブなサーバーの認証情報のみが検証されます。

Plex

Section titled “Plex”

Plex にはベース URL と X-Plex-Token が必要です。3 つの方法で指定できます：

  • PIN ログイン（推奨）。 設定で Plex ログインを開始します。PosterPilot は plex.tv で 強力な PIN を作成し、コードと認証リンクを表示して、あなたが認証するまでポーリングします — そして取得したトークンを保存するので、生のトークンを探して貼り付ける必要はありません。 認証する前に PIN の有効期限が切れた場合は、新しいログインを開始するだけです。
  • 接続の検出。 トークンが利用可能になると、PosterPilot は plex.tv からあなたの Plex サーバーとその接続を検出し、各接続を local または remote とラベル付けします （リレーはフラグが立てられます）。URL を入力する代わりに 1 つを選択します。選んだ接続は、 アクティブな Plex ベース URL として保存される前に接続テストで検証されます。
  • 手動。 ベース URL（例：http://192.168.1.10:32400）と X-Plex-Token を直接 貼り付けます。

Jellyfin

Section titled “Jellyfin”

Jellyfin にはベース URL（JELLYFIN_URL）と、API キー（JELLYFIN_API_KEY）として保存される アクセストークンが必要です。アクティブなサーバーにするには SERVER_TYPE=jellyfin を設定します。 最も簡単な接続方法は、設定で Jellyfin のユーザー名とパスワードでサインイン することです — PosterPilot がサーバーに対して認証し、返されたアクセストークンを（保存時に暗号化して）保存する ため、API キーを手動で生成する必要はありません。パスワードはその 1 回のリクエストにのみ使われ、 永続化されることはありません。API キーを直接貼り付けることもフォールバックとして引き続き利用 できます。ポスターと背景は Jellyfin の画像 API（ポスターには Primary、背景には Backdrop）に アップロードされます。Plex のような PIN ログインや接続検出はありません。

Emby

Section titled “Emby”

Emby にはベース URL（EMBY_URL）と、API キー（EMBY_API_KEY）として保存されるアクセス トークンが必要です。アクティブなサーバーにするには SERVER_TYPE=emby を設定します。Jellyfin と同様に、Emby も ユーザー名とパスワードでサインイン できます — PosterPilot がそれらを アクセストークンと引き換えて（暗号化して）保存するため、API キーを探す必要はなく、手動での API キー入力もフォールバックとして利用できます。PIN ログインや接続検出はありません。

TMDB キー

Section titled “TMDB キー”

TMDB の API 認証情報が必要です：PosterPilot は同期された各 タイトルを TMDB id に解決し（プロバイダーに正確に問い合わせできるように）、TMDB は アートワークプロバイダーの 1 つでもあります。TMDB_KEY 経由または設定で設定します。 v3 API キー と v4 ベアラー/JWT トークン の両方が受け付けられます — 形式は自動検出 されます。

アートワークプロバイダー

Section titled “アートワークプロバイダー”

PosterPilot は検出中に複数のアートワークプロバイダーをまたいで展開し、その候補をマージして、 それぞれにその出所となったプロバイダーのタグを付けます。各プロバイダーは、設定または その環境変数経由で、独立して有効または無効にできます。

プロバイダーデフォルトキーが必要備考
MediUXonnoアップロード者の帰属付きでスクレイピングされたポスター／背景セット。
TMDBonTMDB_KEY を再利用TMDB の画像エンドポイントからのポスターと背景。
Fanart.tvoffFANART_KEYFanart.tv API からのポスター、背景、ロゴ。
ThePosterDBoffnoスクレイピングされたコミュニティのポスター／背景セット。スロットリングとキャッシュあり。

Fanart.tv は唯一のキー付きプロバイダーです：有効化されているのに FANART_KEY が 構成されていない場合、検出はそれをスキップし、実行全体を失敗させるのではなく、認証情報欠如の 状態を表面化させます。あるプロバイダーからの失敗、タイムアウト、または解析不能な応答が、 他のプロバイダーが候補を返すのを妨げることは決してありません。

パフォーマンスとチューニング

Section titled “パフォーマンスとチューニング”

いくつかの詳細設定（Kometa と詳細設定 の設定タブ、または環境経由）が、PosterPilot が どのようにスコア付け、同期、適用、キャッシュするかをチューニングします。これらは通常の優先順位 に従います — 環境変数は永続化された値を上書きし、UI のコントロールをロックします。

  • おすすめアートワークの事前選択（SUGGEST_PRESELECT、デフォルトはオン）。オンの場合、 アイテムビューは各スロットで最高スコアの候補を、上書き可能なおすすめとして事前選択します。 オフにすると、選ぶまで各スロットは未選択のままになります。
  • スコアリングの重み。 PosterPilot は候補を 3 つの項目でランク付けします — プロバイダー ごとのベース重み（MediUX、ThePosterDB、Fanart.tv、TMDB）、解像度スコア、そしてアスペクト比の 適合度スコア（ポスターは 2:3、背景とタイトルカードは 16:9）。デフォルトは MediUX を優先し つつ、別のプロバイダーのはるかに鮮明な、またはより形の整った画像が勝てるようにもなっています。 重みは設定で調整します。これらはデータベースに保存され、環境変数はありません。
  • 増分同期（INCREMENTAL_SYNC、デフォルトはオン）。繰り返しの同期は、メディアサーバーの 最終更新タイムスタンプが前回の同期以降変わっていないアイテムをスキップします。フルスキャンは オンデマンドで引き続き利用できます。
  • 適用並行数（APPLY_CONCURRENCY、デフォルト 4）。一括適用が一度に処理するアイテム数 です。大きなバッチをより速く完了させるには上げ、サーバーやプロバイダーに優しくするには 下げます。
  • サムネイルキャッシュ（THUMB_CACHE_TTL_DAYS、デフォルト 30；THUMB_CACHE_MAX_MB、 デフォルト 512）。プロバイダーのプレビュー画像は、グリッドを高速化しプロバイダーの帯域を 削減するため、/data 下のディスクにキャッシュされます。エントリは TTL（日数）が切れるまで 再利用され、キャッシュは最大サイズ（MB）で上限が定められます — それを超えると、最も最近 使われていないエントリが削除されます。
  • ライブラリの既定の並び順（LIBRARY_DEFAULT_SORT、デフォルト title）。URL がソートを 指定していないときに、ライブラリウォールがどのソートで開くかです：title、year、 rating、runtime、recent（最近変更された順）、または added（メディアサーバーへの 追加日）。ライブラリのツールバーでソートを選ぶと、常にそれが優先されます。

FUN セクション

Section titled “FUN セクション”

FUN（FUN_ENABLED、デフォルトはオフ）は、ライブラリ実験のためのオプトインの置き場所で、 設定 → Kometa と詳細設定 で有効にするまで隠されています。最初のツールはランダムな 映画／シリーズピッカーです — 使い方 を参照してください。トグルが オフの間、FUN にはナビゲーション項目がなく、そのページは 404 を返します。

Kometa エクスポート

Section titled “Kometa エクスポート”

Kometa の方法でカバーを適用すると、PosterPilot は KOMETA_ASSETS_DIR（Docker では デフォルト /kometa）で指定されたディレクトリに、Kometa/PMM 互換の YAML（TMDB id を キーとした url_poster / url_background）を書き込みます。そのパスを既存の Kometa 設定 ディレクトリにマウントすることで、Kometa が次回の実行時にカバーを適用します。エクスポートが どのように消費されるかについては 使い方 を参照してください。

言語

Section titled “言語”

UI の言語はリクエストごとに解決されます：(1) サポートされているロケールを指定している場合の 優先言語設定、次に (2) リクエストの Accept-Language ヘッダー、次に (3) 英語。優先言語は APP_LANGUAGE 経由、設定ページ経由、またはヘッダーの言語スイッチャーで設定します。サポートされて いるロケールは、英語（en）、スペイン語（es）、簡体字中国語（zh）、日本語（ja）、 ブラジルポルトガル語（pt-BR）です。未設定またはサポート外の値は Accept-Language に、 次に英語にフォールスルーします — エラーになることも生のキーになることも決してありません。

ロギングとアクティビティログ

Section titled “ロギングとアクティビティログ”

すべての操作イベントは 3 つの方法で記録されます：コンテナのコンソールにミラーされ、アプリ内の アクティビティ ログ（設定 → アクティビティ）に行として挿入され、ローテーションするファイル ログに追記されます。ファイルは LOG_DIR（Docker ではデフォルト /data/logs）内の posterpilot.log です。約 5 MB を超えて大きくなるとローテーションされ（posterpilot.log → .1 → .2 …）、約 5 ファイルを保持します。デフォルトが /data 下にあるため、既存の /data ボリュームがすでにそれを永続化します — 追加のマウントは不要です。

アクティビティログのテーブルは EVENT_RETENTION 行（デフォルト 2000）で上限が設けられ、 古い行は自動的に削除されます。アクティビティタブの アクティビティをクリア ボタンで、 いつでもテーブルを消去できます（これはディスク上のログファイルを削除しません）。

環境変数リファレンス

Section titled “環境変数リファレンス”

以下のすべての設定は環境変数として指定できます。ほとんどは設定ページでも編集可能です。 環境経由で設定されると優先され、UI ではロックされます。

変数設定デフォルト意味
SERVER_TYPEサーバータイプplexアクティブなメディアサーバー：plex、jellyfin、または emby。
PLEX_URLPlex URL—Plex のベース URL、例：http://192.168.1.10:32400。
PLEX_TOKENPlex トークン（シークレット）—あなたの X-Plex-Token。
PLEX_CLIENT_IDPlex クライアント id生成されるPIN ログイン／検出のために plex.tv に送られる、インストールごとに安定した識別子。
JELLYFIN_URLJellyfin URL—Jellyfin のベース URL（SERVER_TYPE=jellyfin のとき）。
JELLYFIN_API_KEYJellyfin API キー（シークレット）—Jellyfin の API キー。
EMBY_URLEmby URL—Emby のベース URL（SERVER_TYPE=emby のとき）。
EMBY_API_KEYEmby API キー（シークレット）—Emby の API キー。
TMDB_KEYTMDB キー（シークレット）—TMDB v3 API キー または v4 ベアラー/JWT（自動検出）。
KOMETA_ASSETS_DIRKometa アセットディレクトリ./data/kometa（Docker では /kometa）エクスポートされた Kometa YAML が書き込まれるディレクトリ。
DEFAULT_APPLY_METHODデフォルトの適用方法bothデフォルトの適用方法：plex、kometa、または both。
INCLUDED_SECTIONS含めるセクションすべての映画／番組同期するライブラリセクションキー。カンマ区切り（env）または JSON 配列（永続化）。空 = すべて。
PROVIDER_MEDIUXMediUX プロバイダーonMediUX プロバイダーを有効にします。
PROVIDER_TMDBTMDB プロバイダーonTMDB アートワークプロバイダーを有効にします。
PROVIDER_FANARTFanart.tv プロバイダーoffFanart.tv プロバイダーを有効にします（FANART_KEY が必要）。
PROVIDER_THEPOSTERDBThePosterDB プロバイダーoffThePosterDB プロバイダーを有効にします。
FANART_KEYFanart.tv キー（シークレット）—Fanart.tv の API キー（唯一のキー付きプロバイダー）。
MEDIUX_REQUEST_DELAY_MSMediUX リクエスト遅延2000MediUX リクエスト間の遅延、ミリ秒単位（スロットリング）。
MEDIUX_CONCURRENCYMediUX 並行数5MediUX への最大同時リクエスト数。
HTTP_CACHE_TTL_DAYSHTTP キャッシュ TTL7キャッシュされた HTTP 応答（スクレイプ）が再利用される期間、日単位。
APPLY_CONCURRENCY適用並行数4一括適用が並行して処理するアイテム数。
SUGGEST_PRESELECTおすすめ事前選択on各スロットで最高スコアの候補を上書き可能なおすすめとして事前選択します。
INCREMENTAL_SYNC増分同期on繰り返しの同期で変更されていないアイテムをスキップします（フルスキャンは引き続き利用可能）。
LIBRARY_DEFAULT_SORTライブラリの既定の並び順titleライブラリウォールが開くソート：title、year、rating、runtime、recent、または added。
FUN_ENABLEDFUN セクションoff実験的な FUN セクション（ランダムな映画／シリーズピッカー）を表示します。
THUMB_CACHE_TTL_DAYSサムネイルキャッシュ TTL30キャッシュされたプロバイダーのプレビュー画像が再取得されるまで新鮮さを保つ日数。
THUMB_CACHE_MAX_MBサムネイルキャッシュサイズ512サムネイルキャッシュのディスク上の最大サイズ（MB）。超過すると最も最近使われていないものから削除。
APP_LANGUAGE言語—（自動）優先 UI ロケール：en、es、zh、ja、または pt-BR。
LOG_DIR—/data/logs（Docker）ローテーションする posterpilot.log ファイルのフォルダ（約 5 MB × 5 ファイル）。
EVENT_RETENTION—2000データベースに保持されるアクティビティログ行の最大数（古い行は削除されます）。
DATABASE_URL—file:/data/posterpilot.db（Docker）SQLite データベース用の libsql ファイル URL。
PORT—3000リッスンするポート。
APP_SECRET——（自動キー）保存時暗号化キーを導出します（scrypt）。生成された data/.app-key より優先されます。
APP_KEY_FILE—./data/.app-key自動生成されるインスタンス暗号化キーファイルのパス（APP_SECRET が未設定のときに使用）。

ブール値フラグは、有効 には 1 / true / on / yes（大文字小文字を区別しない）を 受け付けます。それ以外（または未設定）は、文書化されたデフォルトのままにします。

PosterPilot is an independent project, not affiliated with or endorsed by Plex, Jellyfin, Emby, MediUX, Fanart.tv, TMDB, ThePosterDB, or Kometa. Trademarks belong to their respective owners. This product uses the TMDB API but is not endorsed or certified by TMDB.