設定

PosterPilot は 2 つの設定元を組み合わせます。

• デプロイとシークレット管理向けの環境変数。
• /data の SQLite に保存されるアプリ内設定。

同じ項目では環境変数が常に優先され、UI は環境管理として編集をロックします。保存したシークレットは AES-256-GCM で暗号化し、ブラウザーやログへ完全な値を返しません。

暗号化キー

未設定なら所有者のみ読める data/.app-key を生成します。APP_SECRET は移植可能なキーを導出して優先されます。移動／復元時は同じキーを保持してください。失うと資格情報の再入力が必要です。自動化と復旧も参照してください。

名前付きメディアサーバー

設定 → サーバーで複数の Plex、Jellyfin、Emby を追加、テスト、有効化、切り替え、無効化、切断できます。Library、Review、コレクション、FUN、変更操作には 1 台がアクティブです。URL、暗号化資格情報、機能はインスタンスごとに分離されます。

従来の SERVER_TYPE と PLEX_* / JELLYFIN_* / EMBY_* は保護された既定サーバーを定義します。追加サーバーは DB に保存します。複数サーバー移行を参照してください。

• Plex: 手動トークン、またはセットアップの PIN ログイン／接続検出。
• Jellyfin／Emby: URL とキー／トークン。セットアップではユーザー名／パスワードを再利用可能トークンに交換し、パスワードは保存しません。

TMDB、プロバイダー、スコア

TMDB_KEY は v3 キーまたは v4 bearer/JWT に対応します。MediUX と TMDB は既定で有効、Fanart.tv は FANART_KEY が必要、ThePosterDB は任意です。1 プロバイダーの失敗は他を止めず、既知候補を古い状態として保持できます。

ThePosterDB はアカウントなしで動作しますが、一部のページでは匿名アクセスに実際のポスターの代わりにプレースホルダー画像を返します。実画像を取得するには、任意でサインインできます — メタデータとプロバイダー（ThePosterDB を有効にするとフィールドが表示）または THEPOSTERDB_USERNAME / THEPOSTERDB_PASSWORD で設定します。パスワードは他のシークレットと同様に保存時に暗号化され、サインインに失敗した場合はその実行を匿名スクレイピングにフォールバックし、検索を止めません。匿名スクレイピングに戻すにはユーザー名を空にします（サインインには両方が必要です）。保存済みパスワードは暗号化されたままデータベースに残り、ユーザー名を再入力すると再び使われます。削除するには、パスワード欄の下の保存済みパスワードを削除を使ってください——保存すると取り除かれます。

メタデータとプロバイダーでは 4 つのプロバイダーを並べ替えられます。ハンドルをドラッグするか移動ボタンを使い、既定の並び順に戻すで MediUX、ThePosterDB、Fanart.tv、TMDB に復帰します。このコントロールがあるのは、検索が全プロバイダーを並列に実行してそれぞれが自分の結果をコミットするため、候補が保存された順番はどのプロバイダーが先に応答したかしか記録していないからです。このタイミングの偶然をランキングとして見せるのは誤解を招くので、項目ビューは設定した順に従います。この順序は項目ページがどのプロバイダーのカードを最初に見せるかを決め（表示のみで、カード内の候補は自分の順序を保ちます）、スコアが完全に等しい候補どうしの決着に、数値スコアの後で厳密に適用されます。等しくないスコアを覆すことは決してありません。最後に置いたプロバイダーのより鮮明な、あるいは比率の良い画像でも候補としては勝ちます。プロバイダーは決着の手段であって上書きの手段ではありません。無効なプロバイダーも位置を保つので、再び有効にしても最後尾に送られません。保存した並び順に載っていないプロバイダー（新しく追加された取得元や、削除された取得元が残した行）は、周りを組み替える代わりに最後に表示されます。

どのプロバイダーが普段勝つかを変えたいときは、並び順ではなくスコアの重みを調整してください。メタデータとプロバイダーでプロバイダー／解像度／縦横比の重みを調整できます。並び順と同様に重みもデータベースに保存され、対応する環境変数はありません。プレビューと実行は同じ決定的設定を使います。SUGGEST_PRESELECT は候補を表示しますが、ステージは常に明示操作です。

TMDB アートワークの言語

TMDB_ARTWORK_LANGUAGE（既定 any）は、どの言語の TMDB アートワークを閲覧し自動選択の対象にするかを決めます。APP_LANGUAGE とは意図的に独立です。any は TMDB が返したすべての言語を保持し、ui は UI 言語をベースコードに正規化して従い（pt-BR の UI は pt を優先）、UI ロケールを解決できないとき——一度もロケールを保存していないインストールで動く無人ジョブなど——は言語をでっち上げずに any へ落とします。en、de などの ISO 639-1 ベースコードを直接指定することもでき、明示コードは翻訳済みの 6 UI ロケールに限りません。TMDB は PosterPilot が翻訳されているよりずっと多くの言語でアートワークにタグを付けるからです。設定のドロップダウンは厳選した 10 言語（ドイツ語、英語、スペイン語、フランス語、イタリア語、日本語、韓国語、ポルトガル語、ロシア語、中国語）を提供します。環境変数で設定した、この一覧にないコードは捨てられずにドロップダウンへ追加されるので、設定を保存しても黙って書き換えられることはありません。認識できない値は未設定として扱われ、壊れた絞り込みを適用せず any に戻ります——打ち間違いで候補グリッドが空になるべきではないからです。他の設定と同様に環境変数が優先され、設定画面では環境管理として表示されます。

決める前に知っておく価値のある挙動が 4 つあります。支配するのは TMDB だけです。他のプロバイダーのアートワークはどの設定でも対象のままで、これは近道ではなく規則です。MediUX と ThePosterDB は言語をまったく報告しないので、「言語なし」を対象外とすると、設定した瞬間にそれらのグリッドが空になり、しかも新しく検索し直しても再び言語なしと報告されるだけで戻せません。Fanart.tv は実際に言語タグを付けますが、それでも手を付けません。この設定が本来支配するはずのない信号でスコアの高いアセットを黙って捨てることになるからです。文字なしのアートワークは常に残ります。TMDB が言語を含まないと明示したアートワークは言語中立として扱われ、どの設定でも残るので、中立のアートワークしかないペインが設定によって空になることはありません。検索はすべてを保持します。設定が制御するのは閲覧と自動選択であってダウンロード対象ではなく、TMDB が返した言語はすべて保存されます。変更しても既存の候補を絞り込み直すだけで、再検索は不要です。自動選択は正直なままです。他言語のポスターを使うのは、優先言語の候補もタグなしの候補も存在しない場合だけで、そのときはラベルで示されます。そうしてステージされたフォールバックは、それを生んだ設定に絞り込まれて消えたりせずページ上に残ります——見えなければならない選択は、取り消せなければならない選択だからです。

アプリ自身では答えられない場合が 1 つあります。PosterPilot が言語をどう知ったかを記録し始める前に見つかった TMDB 候補には未確認の印が付きます。そこで言語欄が空なのは「私たちがそれを記録していない」という意味であって、「TMDB が文字なしと言った」という意味ではありません。これらの候補は隠さず保持します——設定した瞬間にライブラリのアップグレード前 TMDB 在庫を丸ごと格下げする方が悪いからです——そしてプロバイダーグループが再検索を提供し、新しい実行が本当のタグを記録できるようにしています。

アイテムページにはすべての言語を表示の切り替え（と、戻すための「〈言語〉のみ表示」）があり、グローバル設定を変えずに 1 作品だけ設定を越えて確認できます。ある作品で設定に一致するものがないときは、空のグリッドを見せる代わりに、他の言語に何件のカバーがあるかを伝えて同じ逃げ道を出します。

候補インベントリと「さらに読み込む」

TMDB の取り込みは以前、アートワークの種類ごとに 20 件で打ち切られていました。ポスターと背景は別々に数えられるため、「カバーが 40 件で頭打ち」という報告はここから生じています。現在ははるかに多くを保持します。まず検証し、次に TMDB 自身のファイル識別子で重複排除し、最後に上限をかける——厳密にこの順なので、不正な形式のエントリーが候補 1 件を黙って奪うことはもうありません——そして TMDB の並び順をそのまま保ちます。

項目ページはその後、各ペインを 24 件ずつのバッチで表示し、あと何件が隠れているかを告げるさらに読み込む操作を添えます。24 はページが描画するどのグリッドでも割り切れる（背景は 2 列、タイトルカードは 4 列、シーズンポスターは 8 列）ので、展開しても半端な行が残りません。各ペインは独立して開きます——プロバイダーごと、セットごと、ポスターと背景は別々、各シーズンのポスターとそのタイトルカードも別々——なので、一方を広げても他方は広がりません。続きを出してもネットワーク通信は発生しません。保持された在庫はすでにページと一緒に届いているので、ここで抑えているのは描画コストであって帯域ではありません。

取り込みには依然としてアートワークの種類ごとに 200 件という防御的上限があり、1 つの異常なタイトルが際限なく画像を引き込むのを防ぎます。これは保存と描画のための上限であって品質フィルターではありません。そして上限に達したことは黙って見過ごされず報告されます。ペインは、TMDB のすべてを見ているかのように見せる代わりに、そのプロバイダーが PosterPilot の保持する上限を超えるアートワークを返したと述べます。この上限に数えられるのは、本来なら保持されていたはずの候補だけです。捨てられた重複や不正な形式のエントリーは数えません。どちらも、そもそもあなたが選べたものではないからです。

サムネイルキャッシュ（THUMB_CACHE_TTL_DAYS、THUMB_CACHE_MAX_MB）が保持するのは閲覧用のプレビューだけです。拡大した原寸プレビューと実際に適用されるアセットは意図的にプロバイダーから直接取得し、オリジナルがこのキャッシュ本来のサムネイルを追い出さないようにしています。使い方の「閲覧で実際にダウンロードされるもの」を参照してください。

Kometa と適用方法

DEFAULT_APPLY_METHOD は plex（サーバー直接）、kometa、both。操作ごとの変更は保存済み既定値を変えません。

posterpilot-movies.yml（TMDB）と posterpilot-shows.yml（TVDB、なければ IMDb）を KOMETA_ASSETS_DIR に出力します。KOMETA_CONFIG_PATH があれば config.yml と同じディレクトリです。KOMETA_SERVER_INSTANCE_ID は正確な Plex インスタンスを指定し、KOMETA_METADATA_PATH_PREFIX は物理パスではなく Kometa から見える相対参照を指定します。Kometa マネージャーを参照してください。

自動化、バックアップ、診断

• 自動化: サーバー／ライブラリごとの間隔、毎日時刻、イベント。Review 向けに同期／検索し、自動適用しません。
• バックアップと復元: /data/backups のバンドル、個数／日数保持、検証、エクスポート、プレビュー復元。保持設定に環境変数はありません。
• 診断: サーバー、TMDB、プロバイダー、パスを変更せず検査し、明示操作で秘匿化サポートバンドルを出力します。

セキュリティ、言語、FUN

AUTH_MODE は disabled、local、enabled。プロキシでは ADDRESS_HEADER と XFF_DEPTH で実クライアント IP を指定します。言語は APP_LANGUAGE、Accept-Language、英語の順です。FUN_ENABLED は 3 候補ピッカー、Poster Match、ギャラリー、セッションプランナーを有効にします。

環境変数一覧

変数	既定	内容
SERVER_TYPE	plex	従来サーバーの種類: plex、jellyfin、emby。
PLEX_URL	—	既定 Plex のベース URL。
PLEX_TOKEN	—	Plex トークン（シークレット）。
PLEX_CLIENT_ID	生成	PIN／検出用の安定 ID。
JELLYFIN_URL	—	Jellyfin ベース URL。
JELLYFIN_API_KEY	—	Jellyfin キー／トークン（シークレット）。
EMBY_URL	—	Emby ベース URL。
EMBY_API_KEY	—	Emby キー／トークン（シークレット）。
TMDB_KEY	—	TMDB v3 または v4 bearer/JWT（シークレット）。
KOMETA_ASSETS_DIR	./data/kometa（Docker: /kometa）	config path がない場合の型別 YAML 出力先。
KOMETA_CONFIG_PATH	—	config.yml 絶対パス。空ならマネージャー無効。
KOMETA_CONFIG_MODE	merge	merge または own。
KOMETA_SERVER_INSTANCE_ID	legacy-default	Kometa に結び付ける Plex。
KOMETA_METADATA_PATH_PREFIX	config	Kometa 実行環境から見える相対ディレクトリ。. はファイル名だけ。
DEFAULT_APPLY_METHOD	both	plex、kometa、both。
INCLUDED_SECTIONS	すべて	カンマ区切りキー。環境設定はサーバー別選択より優先。
PROVIDER_MEDIUX	有効	MediUX を有効化。
PROVIDER_TMDB	有効	TMDB 画像を有効化。
PROVIDER_FANART	無効	Fanart.tv を有効化。
PROVIDER_THEPOSTERDB	無効	ThePosterDB を有効化。
FANART_KEY	—	Fanart.tv キー（シークレット）。
THEPOSTERDB_USERNAME	—	サインインしてスクレイピングするための任意の ThePosterDB ユーザー名またはメール。
THEPOSTERDB_PASSWORD	—	任意の ThePosterDB アカウントのパスワード（シークレット、暗号化保存）。
TMDB_ARTWORK_LANGUAGE	any	閲覧と自動選択の対象にする TMDB アートワークの言語: any、ui（UI 言語に追従）、または en などの ISO 639-1 ベースコード。無効な値は any に戻ります。
MEDIUX_REQUEST_DELAY_MS	2000	MediUX 要求間隔（ms）。
MEDIUX_CONCURRENCY	5	MediUX 同時要求数。
HTTP_CACHE_TTL_DAYS	7	HTTP キャッシュ日数。
APPLY_CONCURRENCY	4	一括適用の同時項目数。
SUGGEST_PRESELECT	有効	明示的な候補を計算／表示。
INCREMENTAL_SYNC	有効	通常同期で未変更項目を省略。
LIBRARY_DEFAULT_SORT	title	title、year、rating、runtime、recent、added。
FUN_ENABLED	無効	FUN ツールを表示。
THUMB_CACHE_TTL_DAYS	30	サムネイル有効日数。
THUMB_CACHE_MAX_MB	512	サムネイルキャッシュ上限 MB。
APP_LANGUAGE	自動	en、es、zh、ja、pt-BR、fr。
AUTH_MODE	disabled	disabled、local、enabled。UI より優先。
ADDRESS_HEADER	—	プロキシ配下の実 IP ヘッダー。
XFF_DEPTH	—	信頼するプロキシ数。
MAX_UPLOAD_MB	15	画像アップロード上限。
LOG_DIR	./data/logs（Docker: /data/logs）	ローテーションログ先。
EVENT_RETENTION	2000	DB の最大イベント数。
DATABASE_URL	file:./data/posterpilot.db	SQLite の libsql URL。
PORT	3000	HTTP ポート。
APP_SECRET	—	暗号化キーを導出し .app-key より優先。
APP_KEY_FILE	./data/.app-key	生成キーのパス。

真偽値は 1、true、on、yes を受け付けます。DATABASE_URL、PORT、APP_SECRET、APP_KEY_FILE、ADDRESS_HEADER、XFF_DEPTH、MAX_UPLOAD_MB は環境変数専用です。