NFLMeta
NFLMetaCities

Complete Plex Agent Capabilities

A full, feature-level inventory of what the NFLMetaCities scanner + agent can do. This page mirrors the implementation details in the repo.

Key Files
plex/NFLMetaCities.py plex/NFLMetaCities.bundle/Contents/Code/__init__.py

1) Core Data Sources

  • API base: NFLMETA_API_BASE_URL (default http://127.0.0.1:3000).
  • Auth header: X-NFLMeta-Key from NFLMETA_API_KEY.
  • Endpoints: show, season, games, byes, and date disambiguation.
  • Assets base: NFLMETA_ASSET_BASE_URL (default to API base).
  • Cache-busting via NFLMETA_ASSET_VERSION.

2) File Parsing + Matching

  • Game files: YYYY-MM-DD_AwayCity_at_HomeCity.mkv (case-insensitive).
  • Bye files: Team_BYE.mkv or YYYY-MM-DD_Team_BYE.mkv.
  • Season folders: Season 2005 → season 2005.
  • Super Bowls: Season Superbowls → Season 0.
  • Week folders: Week 01 used for numbering + collections.

3) Show-Level Metadata

  • Summary/tagline/studio/network/content rating from API, with fallbacks.
  • Genres set to Sports and Football.
  • Show art from NFLMETA_SHOW_ART_URL or default background.
  • Theme music upload + selection from NFLMETA_SHOW_THEME_URL.
  • Show posters upload from /plex/season_posters/Main_Plex*.png.

4) Season-Level Metadata

  • Season 0 renamed to Super Bowls.
  • Season summary pulled from /api/plex/season/:year.
  • Season posters from /plex/season_posters/YYYY.png (+ variants).
  • Poster selection/locking honors NFLMETA_SKIP_POSTER_SELECT and NFLMETA_LOCK_SEASON_THUMB.
  • Season 0 art from /plex/superbowl_art/Season_0.png.

5) Episode Metadata

  • Titles: Away at Home with scores if available.
  • Summaries from API; announcers appended as Announcers:.
  • Premiere dates from game_date.
  • Coach roles: away/home head coach with team-specific role labels + photos.
  • Roles written via Plex API + Plex SQLite DB for stability, then locked.

6) Posters & Art (Episodes)

  • Matchup posters from /plex/weekly_matchups/<team>/Away_at_Home.png.
  • City-aware slugs support historical team moves.
  • Uploads use raw PNG/JPG bytes; multipart uploads are avoided.
  • Selection re-tries happen in timed waves to survive Plex indexing lag.
  • Super Bowls use /plex/superbowl_logos/Super_Bowl_<Roman>.png.
  • Bye weeks use /plex/bye_posters/<Nickname>_Bye_Week.png.

7) Bye Week Automation

  • Manual: add Team_BYE.mkv for a bye entry.
  • Auto: NFLMETA_AUTO_BYE_FILES=1 creates placeholders in week folders.
  • Bye cache stored under Plex plugin data to reduce API calls.

8) Week Collections

  • If enabled, episodes in Week 01 create collection YYYY Week 01.
  • Collection posters pulled from /weekly_posters/01.png etc.

9) Scanner Behavior

  • Episode numbering: week * 100 + game_index.
  • Bye numbering: week * 100 + 99.
  • Fallback numbering: YYYYMMDD (bye adds 99).
  • Show refresh is triggered for new seasons once per season set.

10) Environment Flags (Complete)

Required

NFLMETA_API_BASE_URL NFLMETA_API_KEY PLEX_TOKEN

Library + Plex

PLEX_LIBRARY_TITLE PLEX_LIBRARY_ID PLEX_LIBRARY_STRICT PLEX_SHOW_KEY PLEX_SHOW_TITLE PLEX_API_BASE_URL

Assets + Posters

NFLMETA_ASSET_BASE_URL NFLMETA_ASSET_VERSION NFLMETA_ALLOW_UPLOAD_POSTERS NFLMETA_ALLOW_URL_POSTERS NFLMETA_SKIP_POSTER_SELECT NFLMETA_LOCK_SEASON_THUMB NFLMETA_UPLOAD_MISSING_VARIANTS NFLMETA_FORCE_UPLOAD_SELECTION NFLMETA_FORCE_SEASON_POSTERS NFLMETA_ENABLE_MATCHUP_POSTERS NFLMETA_MATCHUP_ALWAYS_UPLOAD NFLMETA_USE_PROXY_POSTERS

Show Art + Theme

NFLMETA_SHOW_THEME_URL NFLMETA_SHOW_THEME_PATH NFLMETA_SHOW_ART_URL NFLMETA_SHOW_ART_PATH

Coaches + DB

NFLMETA_PLEX_DB_PATH NFLMETA_DISABLE_COACH_DB_WRITE NFLMETA_ALLOW_SHOW_REFRESH_COACHES

Bye + Collections

NFLMETA_AUTO_BYE_FILES NFLMETA_AUTO_BYE_EXT NFLMETA_FORCE_BYE_CACHE NFLMETA_ENABLE_WEEK_COLLECTIONS

Plex Client Headers (Optional)

PLEX_CLIENT_IDENTIFIER PLEX_PRODUCT PLEX_VERSION

11) Known Constraints

  • Plex tokens can rotate; update PLEX_TOKEN if refresh fails.
  • Cloudflare Access must bypass /api/plex/* and /plex/*.
  • Matchups require correct away/home order and city-based filenames.