v1.7.2 — Fix scheduler DB-connection leak (container lock-up)

Fixes the #82/#136 lock-up: the background scheduler held a Postgres connection while parked, and the plugin is re-instantiated on every Dispatcharr discovery (UI plugins-list polling), so connections leaked until max_connections was hit and the server locked up. Independent of channel count, so it affected small installs too.

The scheduler now closes its DB connection before every sleep and on exit, and Plugin.init is idempotent (leaves a healthy scheduler running instead of churning a new thread per discovery). Verified live: connection count stays bounded and login no longer wedges. See CHANGELOG.md.

v1.7.0 — Field-event sports (UFC, F1, golf, NASCAR, ATP/WTA) match channels

Fixes #127: field-event sports (UFC, F1, golf, NASCAR, ATP/WTA) now match channels.

These single-event sports have no opponent, so they emit a "Field" away sentinel. The matcher's both-teams gate fed that sentinel into its keyword logic, and since no channel or EPG title contains the word "Field" the gate could never pass: every field-event game became a streamless placeholder. The matcher and the EPG candidate lookup now match on the event name alone for these sports. Two-team sports are unchanged. "Diagnose matching" now diagnoses field events too.

See CHANGELOG.md.

v1.6.0 — Diagnose matching: verbose log

Diagnose matching now logs a full verbose report (every matchup listing in the game's window, all unmatched games, the matched set) to the container logs alongside the short toast, so a user can paste the toast AND provide logs. Toast trimmed to fit the UI notification. See CHANGELOG.md.

v1.5.0 — Diagnose matching action

Adds a Diagnose matching action (#128): a short, copy-pasteable toast that names the soonest unmatched game, shows whether any head-to-head listing in its window names the teams (surfacing alias gaps), and gives a one-line verdict. Internal: shared matcher._kw_hit, single _ACTION_HANDLERS dispatch + contract test. Surfaced #127 (field-event sports unmatchable) and #129 (matcher false positives). See CHANGELOG.md.

v1.4.0 — chronological numbering, Xtream Codes binding, per-game channel matching

First release since v1.2.0; rolls up everything since.

Channel numbering & guide binding (#119, #121)

• Channel numbers are now kickoff-time integers: the Top Matchups list sorts strictly by day then start time (soonest games first), and each game keeps the same number for its whole life.
• Because the number never moves, the EPG binds to the right game with no client setup in both the default M3U/EPG output and the Xtream Codes API (both bind by the integer channel number). Fixes the #117 name↔guide mismatch at the source; the prior "set TVG-ID Source = TVG-ID" requirement is removed.

Stream matching (#123)

• The matcher now binds dedicated per-game tournament channels that carry no EPG (e.g. FIFA World Cup 2026 06: USA 02:00 Paraguay), and a new national-team alias set resolves broadcast forms the canonical name lacks (USA, Estados Unidos, and Spanish exonyms). Marquee games now stack all their provider feeds (4K / Spanish / regional) instead of one or none.

Earlier (since 1.2.0)

• Customizable channel-name template, scoring tuning recipes (SCORING.md), widened stream pool with English/quality ordering.

Install via the Dispatcharr Plugins repo, or point your installer at this release's plugin.zip.

v1.2.0 — gevent-safe pipeline (subprocess isolation)

Packaged for the official Dispatcharr Plugins repo (external-plugin distribution).

Highlights

• Fix: gevent worker freeze (#106). The Monte Carlo scoring is pure-Python and holds the GIL; under Dispatcharr 0.26.0's gevent uWSGI it froze the worker hub (login + live streams hung during a refresh). The pipeline now runs in an isolated subprocess (_pipeline_runner.py), so the worker's event loop stays free.

Install

This plugin.zip is the importable plugin folder (top-level dispatcharr_ranked_matchups/). Distributed via the Dispatcharr Plugins repo as an external plugin; source_url resolves to this asset.

v1.0.0 — Dispatcharr Ranked Matchups, first stable release

First stable release. The plugin has been running daily in production
for several months; this release marks the point where the public
contract (settings, action surface, channel naming, EPG description
shape) is stable enough to commit to semver promises.

What this plugin does

Curates the most interesting upcoming sports games from across
20+ sports / leagues into a single "Top Matchups" channel group in
your Dispatcharr guide. Every channel description shows the why —
ranks, closeness, rivalry, favorite team, tournament stakes, race
implications — so you can pick what to watch without scrolling
through your full guide.

Sports supported

Americas — NFL, NHL, MLB, NBA, MLS, NWSL, Liga MX, NCAA Football,
NCAA Men's Basketball, NCAA Women's Basketball (with March Madness),
NCAA Baseball (regular + postseason), NCAA Men's & Women's Soccer
(regular + College Cup), NCAA Softball.

European soccer — English Premier League, EFL Championship, UEFA
Champions League, Bundesliga, La Liga, Serie A, Ligue 1, Eredivisie,
Primeira Liga, Brazilian Série A.

International tournaments — FIFA World Cup 2026 (with full Annex
C 495-row 3rd-placer slot table for accurate bracket leverage), UEFA
European Championship.

Scoring signals (each tunable on the settings page)

• Rank pair — both teams in their sport's top-25 poll, or one ranked
• Close game — bookmaker-implied coin-flip-ness (devigged moneylines
  in soccer, normalized point spread in NCAAF / NCAAM)
• Favorite team alert — flag your teams; their games auto-rank
  higher and the EPG description calls them out
• Importance — Monte Carlo simulation of how much each game moves
  each team's chance of advancing / winning the title / making
  playoffs / getting relegated. Locked games score lower; do-or-die
  games rank to the top
• Tournament stage — knockout cup games (R16, QF, SF, F) rank
  higher than regular season
• Rivalry — known rivalry games (initial DB ships with CFB / EPL
  / NHL / NBA pairings)

Raw signals sum and compress to a 0-10 ★ score using a tanh curve so
top games asymptote without losing differentiation among the rest.

Curated channels

Virtual channels live in a configurable target group (default
"Top Matchups") with names like:

CFB 1v5 ★10.0: Texas at Oklahoma — both top-5, rivalry, toss-up
EPL 3v9 ⭐ ★8.4: Brentford at Manchester United (favorite: Brentford)
NHL Stanley Cup F ★9.7: Game 5 Avalanche at Golden Knights

Each channel's EPG description shows kickoff time, the matchup,
the sport, the raw score, the score breakdown, and (when enabled) an
LLM-rewritten narrative with rivalry / stakes / form context.

Today's games are auto-sorted to the front (lowest channel numbers)
so they appear first in any IPTV client (TiviMate, Plex, Jellyfin,
the Dispatcharr UI itself, etc).

Behavior

• Daily auto-refresh runs at the time(s) you choose (default
  0400 local). On-demand "Refresh + apply now" button returns
  within ~100ms; progress shows under "Show current state" while
  the pipeline works in the background.
• Dry-run mode previews channel-profile changes before applying.
• EPG channel matching finds the actual broadcast channel airing
  each game (across however many IPTV providers you have) and pulls
  its stream into the virtual matchup channel.
• AI-written descriptions (optional, Claude-powered) — rivalry
  framing, recent form, what's at stake. Off by default.
• SportsDB matchup logos when available.
• Saved state caches across refreshes so iterations are fast and
  survive Dispatcharr restarts.

API keys

Most data sources offer free tiers and the plugin's fetch volume stays
inside them comfortably. EPG matching uses Claude and is the only
paid requirement.

Source	Tier	Required for
Anthropic (Claude)	Paid	EPG channel matching (required), narrative descriptions (optional)
CollegeFootballData	Free 1k req/day	NCAA football + men's basketball
Football-Data.org	Free 10 req/min, 12 free comps	EPL / EFL / UCL / Bundesliga / La Liga / Serie A / Ligue 1 / WC / EURO
The Odds API	Free 500 req/mo	Spread / closeness on any sport
SportsDB	Free key 3 works	Matchup logos (optional)
ESPN / NHL / MLB	No key required	NHL, MLB, NBA, MLS, NWSL, Liga MX, NCAA Baseball, NCAA Soccer, NCAA Softball, NCAA Women's Basketball

Compatibility

• Dispatcharr v0.25.1+ (tested; older versions may work but aren't tested)
• Platforms linux / docker
• Python 3.13+ (matches Dispatcharr's bundled interpreter)

Known limitations

Two upstream-blocked gaps tracked as GitHub issues:

• MLS mid-season importance — ESPN publishes only ~1-2 weeks of
  future MLS fixtures (other leagues publish months ahead), so the
  Monte Carlo importance signal reads close to 0 for marginal
  mid-season MLS games. Signal sharpens as the season-end window
  narrows.
• UEFA EURO 2028 bracket leverage — the cross-source bracket
  wiring that makes WC 2026 group games show R16+ leverage is WC-
  specific; EURO 2028 needs analogous wiring once UEFA publishes the
  bracket structure (~12-18 months pre-tournament).