Configuration

homescreen-hero stores its settings in config.yaml. Most settings can be managed through the dashboard UI, but you can also edit this file directly.

tip

Sensitive values like API keys and passwords should be set using environment variables instead of putting them directly in config.yaml.

Example Config

plex:
  base_url: http://192.168.1.100:32400
  token: null                        # Use HSH_PLEX_TOKEN env var instead
  libraries:
    - name: Movies
      enabled: true
    - name: TV Shows
      enabled: true

auth:
  enabled: true
  username: admin
  password: null                     # Use HSH_AUTH_PASSWORD env var instead
  secret_key: null                   # Use HSH_AUTH_SECRET_KEY env var instead
  token_expire_days: 30

rotation:
  enabled: true
  interval_hours: 12
  max_collections: 5
  strategy: random
  allow_repeats: false
  sync_all_on_rotation: true
  blacklisted_collections: []

groups:
  - name: Favorites
    enabled: true
    min_picks: 1
    max_picks: 2
    weight: 1
    min_gap_rotations: 0
    visibility_home: true
    visibility_shared: false
    visibility_recommended: false
    collections:
      - Best of 2024
      - Award Winners

  - name: Christmas
    enabled: true
    min_picks: 0
    max_picks: 1
    weight: 1
    min_gap_rotations: 0
    visibility_home: true
    visibility_shared: true
    visibility_recommended: false
    date_range:
      start: "11-20"
      end: "12-26"
    collections:
      - Holiday Movies
      - Christmas Classics

trakt:
  enabled: false
  client_id: null                    # Use HSH_TRAKT_CLIENT_ID env var instead
  base_url: https://api.trakt.tv
  sources:
    - name: Popular Movies This Week
      url: https://trakt.tv/users/username/lists/popular
      plex_library: Movies

letterboxd:
  enabled: false
  sources:
    - name: Top 250 Narrative Films
      url: https://letterboxd.com/dave/list/official-top-250-narrative-feature-films/
      plex_library: Movies

mdblist:
  enabled: false
  api_key: null                      # Use HSH_MDBLIST_API_KEY env var instead
  base_url: https://api.mdblist.com
  sources:
    - name: Trending Movies
      url: https://mdblist.com/lists/username/trending
      plex_library: Movies

tautulli:
  enabled: false
  api_key: null                      # Use HSH_TAUTULLI_API_KEY env var instead
  base_url: http://localhost:8181
  collect_on_rotation: true
  collect_interval_hours: 24

seerr:
  enabled: false
  api_key: null                      # Use HSH_SEERR_API_KEY env var instead
  base_url: http://localhost:5055

logging:
  level: INFO

Section Reference

plex

Field	Type	Default	Description
base_url	string	-	Plex server URL
token	string	null	Plex API token (prefer env var)
libraries	list	-	Libraries to manage
libraries[].name	string	-	Library name in Plex
libraries[].enabled	bool	true	Whether this library is active

rotation

Field	Type	Default	Description
enabled	bool	true	Enable automatic rotation
interval_hours	int	12	Hours between rotations (min: 1)
max_collections	int	5	Max collections on homescreen at once (min: 1)
strategy	string	random	Selection strategy: random, weighted, or lru
allow_repeats	bool	false	Allow same collection in consecutive rotations
sync_all_on_rotation	bool	true	Sync all third-party lists when rotating
blacklisted_collections	list	[]	Collections to never select during rotation

Strategies

• random - Randomly select from eligible collections
• weighted - Prioritize groups with higher weight values
• lru - Least Recently Used, picks collections that haven't been featured recently

groups

Groups organize your Plex collections for rotation.

Field	Type	Default	Description
name	string	-	Group name
enabled	bool	true	Whether group is active
min_picks	int	0	Minimum collections to pick per rotation
max_picks	int	1	Maximum collections to pick per rotation
weight	int	1	Priority for weighted strategy (higher = more likely)
min_gap_rotations	int	0	Rotations before reusing a collection from this group
visibility_home	bool	true	Show on admin Home page
visibility_shared	bool	false	Show on shared users' Home pages
visibility_recommended	bool	false	Show in Library Recommended section
date_range	object	null	Restrict group to a yearly date window
date_range.start	string	-	Start date in MM-DD format
date_range.end	string	-	End date in MM-DD format
collections	list	-	Plex collection names in this group

auth

Field	Type	Default	Description
enabled	bool	false	Require login to access the dashboard
username	string	admin	Login username
password	string	null	Password - plaintext or bcrypt hash (prefer env var)
secret_key	string	null	JWT signing secret (prefer env var)
token_expire_days	int	30	Days before login expires

trakt

Field	Type	Default	Description
enabled	bool	false	Enable Trakt integration
client_id	string	null	Trakt API client ID (prefer env var)
base_url	string	https://api.trakt.tv	Trakt API base URL
sources	list	[]	Trakt list sources to sync
sources[].name	string	-	Display name (becomes the Plex collection name)
sources[].url	string	-	Full Trakt list URL
sources[].plex_library	string	-	Target Plex library to sync into

mdblist

Field	Type	Default	Description
enabled	bool	false	Enable MDBList integration
api_key	string	null	MDBList API key (prefer env var)
base_url	string	https://api.mdblist.com	MDBList API base URL
sources	list	[]	MDBList sources to sync
sources[].name	string	-	Display name (becomes the Plex collection name)
sources[].url	string	-	Full MDBList list URL
sources[].plex_library	string	-	Target Plex library to sync into

letterboxd

Field	Type	Default	Description
enabled	bool	false	Enable Letterboxd integration
sources	list	[]	Letterboxd list sources to sync
sources[].name	string	-	Display name (becomes the Plex collection name)
sources[].url	string	-	Full or short Letterboxd list URL
sources[].plex_library	string	-	Target Plex library to sync into

tautulli

Field	Type	Default	Description
enabled	bool	false	Enable Tautulli analytics
api_key	string	null	Tautulli API key (prefer env var)
base_url	string	http://localhost:8181	Tautulli server URL
collect_on_rotation	bool	true	Collect analytics after each rotation
collect_interval_hours	int	24	Hours between analytics collection

seerr

Field	Type	Default	Description
enabled	bool	false	Enable Seerr integration
api_key	string	null	Seerr API key (prefer env var)
base_url	string	http://localhost:5055	Seerr server URL

logging

Field	Type	Default	Description
level	string	INFO	Log level: DEBUG, INFO, WARNING, ERROR