example.config.yaml

# homescreen-hero Configuration Example
# For security best practices, use environment variables for sensitive values.
# See .env.example for the recommended approach.

plex:
  base_url: "YOUR_PLEX_SERVER_URL"  # e.g., "http://192.168.1.100:32400"
  # token: "YOUR_PLEX_TOKEN"  # RECOMMENDED: Use HSH_PLEX_TOKEN environment variable instead
  libraries: # List of Plex libraries to use
    - name: Movies
      enabled: true
    - name: TV Shows
      enabled: false

rotation:
  enabled: true
  interval_hours: 12
  max_collections: 5
  strategy: random # random, weighted, lru (see repo for explanation on how each strategy works)
  allow_repeats: false
  sync_all_on_rotation: true # Default: true
  # If true, sync all third-party lists on each rotation run (good if < 15 lists)
  # If false, only sync lists when they're selected during a rotation (runs faster if you have a bunch of lists)

  # Optional: Collections that will never be selected during rotation
  # blacklisted_collections:
  #   - "Some Collection You Want To Skip"
  #   - "Another One To Ignore"

  # Optional: Limit how many collections can be featured per library
  # Useful if you want to prevent one library from dominating the homescreen
  # per_library_limits:
  #   Movies: 3
  #   TV Shows: 2

  # Optional: Auto-rotate mode - rotates ALL collections from selected libraries
  # instead of using the group-based system below. Groups are ignored when this is enabled.
  # auto_rotate:
  #   enabled: false
  #   libraries: []  # Empty = all enabled libraries. Or specify: ["Movies", "TV Shows"]
  #   visibility_home: true
  #   visibility_shared: false
  #   visibility_recommended: false

# Optional: Display settings for how groups appear on the homescreen
# display:
#   group_display_mode: grouped  # 'grouped' (cluster by group) or 'merged' (round-robin across groups)

# Optional: Authentication settings
auth:
  enabled: true
  method: "password"  # "password", "plex", or "both"
  username: "admin"
  # password: ""  # RECOMMENDED: Use HSH_AUTH_PASSWORD environment variable instead
  # secret_key: ""  # RECOMMENDED: Use HSH_AUTH_SECRET_KEY environment variable instead
  token_expire_days: 30
  auto_approve_users: true  # When false, new Plex users require admin approval before they can sign in

# Optional: Trakt integration
trakt:
  enabled: false
  # client_id: "YOUR_TRAKT_CLIENT_ID"  # RECOMMENDED: Use HSH_TRAKT_CLIENT_ID environment variable instead
  base_url: https://api.trakt.tv
  sources:
  - name: "TRAKT_COLLECTION_NAME"  # This is the name that will show up in Plex
    url: "LINK_TO_TRAKT_COLLECTION_OR_LIST"  # e.g., https://trakt.tv/users/username/collections/movies
    plex_library: "YOUR_PLEX_LIBRARY_NAME" # e.g., "Movies"

# Optional: Letterboxd integration
letterboxd:
  sources:
  - name: "LETTERBOXD_LIST_NAME"  # This is the name that will show up in Plex
    url: "LINK_TO_LETTERBOXD_LIST"  # e.g., https://letterboxd.com/username/list/listname/
    plex_library: "YOUR_PLEX_LIBRARY_NAME" # e.g., "Movies"

# Optional: AniList integration (no credentials needed)
# Supports user lists and public browse lists
anilist:
  sources:
  - name: "My Anime Watchlist"  # This is the name that will show up in Plex
    url: "https://anilist.co/user/username/animelist"  # Fetches all default lists (Watching, Completed, etc.)
    plex_library: "Anime"
# - name: "Completed Anime"
#   url: "https://anilist.co/user/username/animelist/completed"  # A specific user list
#   plex_library: "Anime"
# - name: "Trending Anime"
#   url: "anilist://browse/trending"  # Currently trending anime
#   plex_library: "Anime"
#   max_items: 50  # Limit items for browse lists (default: 100, range: 10-500)

# Optional: MyAnimeList integration
mal:
  enabled: false
  # client_id: "YOUR_MAL_CLIENT_ID"  # RECOMMENDED: Use HSH_MAL_CLIENT_ID environment variable instead
  # Get your Client ID from: https://myanimelist.net/apiconfig
  sources:
  - name: "My MAL Watchlist"  # This is the name that will show up in Plex
    url: "https://myanimelist.net/animelist/username"  # Fetches all statuses by default
    plex_library: "Anime"
# - name: "Completed Anime"
#   url: "https://myanimelist.net/animelist/username?status=completed"  # A specific status filter
#   plex_library: "Anime"
# - name: "Top Anime"
#   url: "mal://ranking/all"  # MAL global ranking (options: all, airing, upcoming, bypopularity, favorite)
#   plex_library: "Anime"
#   max_items: 50  # Limit items for ranking/seasonal lists (default: 100, range: 10-500)
# - name: "Winter 2026 Anime"
#   url: "mal://season/2026/winter"  # Seasonal anime (seasons: winter, spring, summer, fall)
#   plex_library: "Anime"
#   max_items: 50

# Optional: TMDb integration
tmdb:
  enabled: false
  # api_key: "YOUR_TMDB_API_KEY"  # RECOMMENDED: Use HSH_TMDB_API_KEY environment variable instead
  # Get your API key from: https://www.themoviedb.org/settings/api
  base_url: https://api.themoviedb.org/3
  sources:
  - name: "TMDB_LIST_NAME"  # This is the name that will show up in Plex
    url: "LINK_TO_TMDB_LIST"  # e.g., https://www.themoviedb.org/list/123456
    plex_library: "YOUR_PLEX_LIBRARY_NAME" # e.g., "Movies"

# Optional: MDBList integration
mdblist:
  enabled: false
  # api_key: "YOUR_MDBLIST_API_KEY"  # RECOMMENDED: Use HSH_MDBLIST_API_KEY environment variable instead
  # Get your API key from: https://mdblist.com/preferences/
  base_url: https://api.mdblist.com
  sources:
  - name: "MDBLIST_LIST_NAME"  # This is the name that will show up in Plex
    url: "LINK_TO_MDBLIST_LIST"  # e.g., https://mdblist.com/lists/username/listname
    plex_library: "YOUR_PLEX_LIBRARY_NAME" # e.g., "Movies"

# Optional: Tautulli integration for analytics
tautulli:
  enabled: false
  # api_key: "YOUR_TAUTULLI_API_KEY"  # RECOMMENDED: Use HSH_TAUTULLI_API_KEY environment variable instead
  # Get your API key from: Tautulli Settings → Web Interface → API → API Key
  base_url: "http://localhost:8181"  # Your Tautulli instance URL
  collect_on_rotation: true  # Automatically collect analytics after each rotation
  collect_interval_hours: 24  # How often to collect analytics snapshots (in hours)

# Optional: Seerr/Jellyseerr/Overseerr integration
seerr:
  enabled: false
  # api_key: "YOUR_SEERR_API_KEY"  # RECOMMENDED: Use HSH_SEERR_API_KEY environment variable instead
  # Get your API key from: Seerr Settings → General → API Key
  base_url: "http://localhost:5055"  # Your Seerr instance URL

logging:
  level: INFO

groups:
- name: ExampleGroup
  enabled: true
  min_picks: 1
  max_picks: 1
  weight: 1
  min_gap_rotations: 0
  display_order: 0  # Controls position on homescreen (lower = first)
  visibility_home: true        # Show collections on server owner's Home page
  visibility_shared: false     # Show collections on shared users' Home pages
  visibility_recommended: false  # Show collections on Library Recommended section
  collections:
  - Example Collection 1
  - Example Collection 2
  - Testing Testing