Configuração

O PosterPilot combina duas fontes:

• Variáveis de ambiente, adequadas a deploy e gerenciamento de segredos.
• Configurações da aplicação, persistidas no SQLite sob /data.

Para a mesma opção, o ambiente sempre prevalece. A interface marca o valor como gerenciado pelo ambiente e bloqueia sua edição. Segredos persistidos são criptografados com AES-256-GCM e nunca retornam completos ao navegador ou aos logs.

Chave de criptografia

Sem configuração, o PosterPilot cria data/.app-key com acesso apenas do proprietário. APP_SECRET deriva uma chave portátil e tem precedência. Preserve a mesma chave ao mover ou restaurar a instalação; sem ela, será necessário informar as credenciais de novo. Veja Automação e recuperação.

Servidores de mídia nomeados

Configurações → Servidores permite adicionar, testar, ativar, habilitar, desabilitar e desconectar várias instâncias Plex, Jellyfin e Emby. Uma fica ativa para Biblioteca, Revisão, Coleções, FUN e mutações. Cada instância mantém URL, credencial criptografada e capacidades próprias.

As variáveis legadas SERVER_TYPE e PLEX_* / JELLYFIN_* / EMBY_* definem o servidor padrão protegido. Servidores adicionais ficam no banco; consulte Migração multi-servidor.

• Plex: token manual ou login PIN/descoberta no setup.
• Jellyfin/Emby: URL e chave/token; o setup também troca usuário/senha por um token reutilizável sem persistir a senha.

TMDB, provedores e score

TMDB_KEY aceita chave v3 ou bearer/JWT v4. MediUX e TMDB começam ativos; Fanart.tv requer FANART_KEY; ThePosterDB é opcional. A falha de um provedor não bloqueia os demais e pode manter candidatos conhecidos marcados como desatualizados.

O ThePosterDB funciona sem conta, mas em algumas páginas ele serve uma imagem de preenchimento a visitantes anônimos no lugar da artwork real. Você pode fazer login de forma opcional — em Metadados e provedores (os campos aparecem ao habilitar o ThePosterDB) ou com THEPOSTERDB_USERNAME / THEPOSTERDB_PASSWORD — para obter as imagens reais. A senha é criptografada em repouso como os demais segredos, e um login que falha volta ao modo anônimo naquela execução em vez de bloquear a descoberta. Para voltar ao modo anônimo, limpe o usuário (o login exige os dois); a senha guardada permanece criptografada e volta a ser usada se você reinserir o usuário, a menos que você a remova com o controle Limpar a senha guardada sob o campo de senha, que apaga o segredo ao salvar.

Em Metadados e provedores, ajuste os pesos de provedor, resolução e proporção. A mesma configuração determinística vale na prévia e execução. SUGGEST_PRESELECT mostra a melhor sugestão, mas aceitar/preparar é sempre explícito.

Ordem dos provedores

Metadados e provedores também permite reordenar os quatro provedores, arrastando uma alça ou usando os botões de mover; Restaurar a ordem padrão devolve MediUX, ThePosterDB, Fanart.tv, TMDB. Como os pesos, a ordem fica no banco e não tem variável de ambiente.

O controle existe porque a descoberta roda todos os provedores em paralelo e cada um confirma os próprios resultados, então a ordem em que os candidatos acabaram armazenados não registra nada além de quem respondeu primeiro; apresentar esse acidente de relógio como ranking seria enganoso, e por isso a tela do item segue a ordem que você configurou. O que a ordem faz — e, igualmente importante, o que ela não faz:

• Decide qual card de provedor a página do item mostra primeiro. Só apresentação; os candidatos dentro de um card mantêm a ordem própria.
• Desempata candidatos com scores exatamente iguais, aplicada estritamente depois do score numérico.
• Nunca reverte um score desigual. Uma imagem mais nítida ou mais bem proporcionada de um provedor que você pôs por último ainda leva a sugestão: provedor é critério de desempate, não substituição. Para mudar quem costuma ganhar, ajuste os pesos por provedor.
• Um provedor desativado mantém a posição, então reativá-lo não o joga para o fim. Um provedor que a sua ordem salva não menciona — uma fonte recém-adicionada, ou uma linha deixada por outra removida — aparece por último em vez de rearranjar tudo em volta dele.

Idioma das artes do TMDB

TMDB_ARTWORK_LANGUAGE (padrão any) define em qual idioma você navega e o que a seleção automática pode escolher entre as artes do TMDB, independentemente de APP_LANGUAGE: any mantém todos os idiomas que o TMDB devolveu, ui segue o idioma da interface normalizado para o código base (uma interface pt-BR prefere pt; se nenhum idioma de interface puder ser resolvido — um job desassistido numa instalação que nunca persistiu um — o valor cai para any em vez de inventar um idioma) e um código ISO 639-1 explícito (en, de…) não se limita aos seis locales traduzidos: o menu suspenso das Configurações oferece dez selecionados (alemão, inglês, espanhol, francês, italiano, japonês, coreano, português, russo, chinês) e um código definido pelo ambiente que não esteja nessa lista é adicionado ao menu em vez de descartado, então salvar as Configurações nunca o reescreve em silêncio. Um valor não reconhecido é tratado como ausente e volta para any em vez de aplicar um filtro quebrado. Como nos demais, o ambiente prevalece e o campo aparece como gerenciado pelo ambiente.

Rege o TMDB e nada mais. As artes de todos os outros provedores continuam elegíveis sob qualquer preferência, e isso é a regra, não um atalho: MediUX e ThePosterDB nunca informam idioma algum, então tratar «sem idioma» como inelegível esvaziaria as grades deles assim que qualquer preferência fosse definida, e uma busca nova jamais os traria de volta, porque voltaria a não informar idioma; o Fanart.tv de fato etiqueta idiomas e ainda assim é deixado em paz, porque filtrá-lo descartaria em silêncio um arquivo mais bem pontuado por causa de um sinal que esta configuração nunca teve a função de reger.

Artes que o TMDB marca explicitamente como sem idioma contam como neutras e continuam disponíveis em qualquer preferência, então uma preferência nunca esvazia um painel que só tem arte neutra. A descoberta sempre guarda todos os idiomas — a preferência rege a navegação e a seleção automática, não o que é baixado —, de modo que alterá-la refiltra o que você já tem e nunca exige refazer a busca. A seleção automática só recorre a um pôster em outro idioma quando não resta nenhuma opção preferida nem sem etiqueta, e sinaliza quando isso acontece; um recurso já preparado continua visível na página em vez de ser escondido pela própria preferência que o produziu, porque uma escolha que você precisa poder ver é uma escolha que você precisa poder revogar.

Há um caso que a aplicação não resolve sozinha: candidatos do TMDB descobertos antes de o PosterPilot registrar como aprendeu um idioma são marcados como Não verificada, porque ali um campo de idioma vazio significa «nunca registramos isso», não «o TMDB disse que é sem texto». Esses candidatos são mantidos em vez de escondidos — rebaixar todo o inventário TMDB anterior à atualização assim que uma preferência fosse definida seria pior — e o grupo do provedor oferece Pesquisar novamente, para que uma execução nova registre as etiquetas reais.

A página do item traz um alternador Mostrar todos os idiomas (e Mostrar apenas idioma para voltar), que não muda a configuração global. Quando a preferência não corresponde a nada para um título, a página diz quantas capas existem em outros idiomas e oferece a mesma saída em vez de exibir uma grade vazia.

Inventário de candidatos e «carregar mais»

A ingestão do TMDB parava antes em 20 imagens por tipo de arte — pôsteres e fundos eram contados separadamente, daí os relatos de «limitado a 40 capas». Agora muitas mais são mantidas: primeiro validadas, depois deduplicadas pela identidade de arquivo do próprio TMDB e depois limitadas, estritamente nessa ordem, de modo que uma entrada malformada não custa mais um candidato em silêncio, e a ordem em que o TMDB as classificou é preservada.

A página do item então mostra cada painel em lotes de 24 miniaturas, com um controle carregar mais que nomeia quantas continuam ocultas. 24 divide exato em todas as grades que a página desenha (duas colunas para fundos, quatro para title cards, oito para pôsteres de temporada), então nenhuma revelação deixa meia fileira torta. Cada painel se abre de forma independente — provedor a provedor, set a set, pôsteres separados de fundos, e os pôsteres de cada temporada separados dos title cards dela —, então abrir um nunca abre outro. Revelar mais não custa tráfego de rede: o inventário mantido já vem junto com a página, então isso limita o custo de renderização, não a banda.

A ingestão mantém um teto defensivo de 200 candidatos por tipo de arte — um limite de armazenamento e renderização, não um filtro de qualidade —, e encostar nele é avisado em vez de passar batido: o painel diz que o provedor retornou mais capas do que o PosterPilot mantém, em vez de sugerir que você está vendo tudo o que o TMDB tem. Só conta para esse teto um candidato que de outro modo teria sido mantido; duplicatas descartadas e entradas malformadas não, porque nem umas nem outras chegaram a ser algo que você pudesse escolher.

O cache de miniaturas (THUMB_CACHE_TTL_DAYS, THUMB_CACHE_MAX_MB) guarda apenas prévias de navegação: a prévia ampliada em tamanho cheio e o arquivo de fato aplicado vêm direto do provedor, de propósito, para que originais não expulsem as miniaturas que esse cache existe para servir. Veja Uso → Descobrir e preparar artwork.

Kometa e método de aplicação

DEFAULT_APPLY_METHOD aceita plex (servidor direto), kometa ou both. É o valor inicial; escolher outro em uma ação não altera o padrão salvo.

O export grava posterpilot-movies.yml (TMDB) e posterpilot-shows.yml (TVDB, com fallback IMDb) em KOMETA_ASSETS_DIR; com KOMETA_CONFIG_PATH, grava ao lado de config.yml. KOMETA_SERVER_INSTANCE_ID deve indicar uma instância Plex exata. KOMETA_METADATA_PATH_PREFIX define a referência relativa vista pelo Kometa, não o caminho físico. Veja o Gerenciador do Kometa.

Automação, backup e diagnóstico

• Automação: intervalo, horário diário ou evento por servidor/biblioteca; sincroniza/descobre para Revisão e nunca aplica automaticamente.
• Backup e restauração: bundles sob /data/backups, retenção por quantidade ou idade, validação, exportação e restauração pré-visualizada. A retenção é persistida na aplicação e não possui variável de ambiente.
• Diagnósticos: testes sem mutação para servidores, TMDB, provedores e caminhos, além de bundle de suporte redigido por exportação explícita.

Segurança e FUN

AUTH_MODE é disabled, local ou enabled. Atrás de proxy, configure ADDRESS_HEADER e XFF_DEPTH para que o modo local use o IP real. FUN_ENABLED ativa o sorteio de três opções, Poster Match, galeria e planejador de sessão.

Idioma

O idioma usa APP_LANGUAGE, depois Accept-Language, depois inglês. Os locales suportados são en, es, zh, ja, pt-BR e fr.

Referência completa de variáveis de ambiente

Variável	Padrão	Significado
SERVER_TYPE	plex	Tipo do servidor legado: plex, jellyfin ou emby.
PLEX_URL	—	URL base do Plex padrão.
PLEX_TOKEN	—	Token Plex (segredo).
PLEX_CLIENT_ID	gerado	ID estável para PIN/descoberta.
JELLYFIN_URL	—	URL base do Jellyfin.
JELLYFIN_API_KEY	—	Chave/token Jellyfin (segredo).
EMBY_URL	—	URL base do Emby.
EMBY_API_KEY	—	Chave/token Emby (segredo).
TMDB_KEY	—	Chave v3 ou bearer/JWT v4 do TMDB (segredo).
KOMETA_ASSETS_DIR	./data/kometa (/kometa no Docker)	Diretório dos YAMLs tipados sem config path.
KOMETA_CONFIG_PATH	—	Caminho absoluto do config.yml; vazio desativa o gerenciador.
KOMETA_CONFIG_MODE	merge	merge ou own.
KOMETA_SERVER_INSTANCE_ID	legacy-default	Instância Plex exata vinculada ao Kometa.
KOMETA_METADATA_PATH_PREFIX	config	Diretório relativo visto pelo runtime do Kometa; . usa nomes simples.
DEFAULT_APPLY_METHOD	both	plex, kometa ou both.
INCLUDED_SECTIONS	todas	Chaves separadas por vírgula; ambiente substitui seleção por servidor.
PROVIDER_MEDIUX	ligado	Habilita MediUX.
PROVIDER_TMDB	ligado	Habilita imagens TMDB.
PROVIDER_FANART	desligado	Habilita Fanart.tv.
PROVIDER_THEPOSTERDB	desligado	Habilita ThePosterDB.
FANART_KEY	—	Chave Fanart.tv (segredo).
THEPOSTERDB_USERNAME	—	Usuário ou e-mail opcional do ThePosterDB para buscar com login.
THEPOSTERDB_PASSWORD	—	Senha da conta opcional do ThePosterDB (segredo, criptografada em repouso).
TMDB_ARTWORK_LANGUAGE	any	Artes do TMDB navegadas e autosselecionadas: any, ui (segue a interface) ou um código ISO 639-1 como en; valor inválido volta para any.
MEDIUX_REQUEST_DELAY_MS	2000	Intervalo entre requisições MediUX, ms.
MEDIUX_CONCURRENCY	5	Requisições MediUX simultâneas.
HTTP_CACHE_TTL_DAYS	7	TTL do cache HTTP em dias.
APPLY_CONCURRENCY	4	Itens simultâneos em aplicação em massa.
SUGGEST_PRESELECT	ligado	Calcula e mostra sugestões explícitas.
INCREMENTAL_SYNC	ligado	Ignora itens inalterados no sync normal.
LIBRARY_DEFAULT_SORT	title	title, year, rating, runtime, recent ou added.
FUN_ENABLED	desligado	Exibe as ferramentas FUN.
THUMB_CACHE_TTL_DAYS	30	Dias de validade das miniaturas em cache.
THUMB_CACHE_MAX_MB	512	Limite do cache de miniaturas em MB.
APP_LANGUAGE	automático	en, es, zh, ja, pt-BR ou fr.
AUTH_MODE	disabled	disabled, local ou enabled; substitui/bloqueia a UI.
ADDRESS_HEADER	—	Header do IP real atrás de proxy, por exemplo x-forwarded-for.
XFF_DEPTH	—	Número de proxies confiáveis.
MAX_UPLOAD_MB	15	Tamanho máximo de upload de imagem.
LOG_DIR	./data/logs (/data/logs no Docker)	Diretório do log rotativo.
EVENT_RETENTION	2000	Máximo de eventos no banco.
DATABASE_URL	file:./data/posterpilot.db	URL libsql do SQLite.
PORT	3000	Porta HTTP.
APP_SECRET	—	Deriva a chave e substitui .app-key.
APP_KEY_FILE	./data/.app-key	Caminho da chave gerada.

Booleanos aceitam 1, true, on ou yes sem diferenciar maiúsculas. Valores de deploy como DATABASE_URL, PORT, APP_SECRET, APP_KEY_FILE, ADDRESS_HEADER, XFF_DEPTH e MAX_UPLOAD_MB só podem vir do ambiente.