UFC auto-schedule
UFC auto-schedule
Turns the operator Stop into a standby: the cockpit wakes itself up 10 minutes before a UFC card’s earliest published segment, follows every segment, and stands itself back down 30 minutes after every bout is decided. Along the way it posts countdown / go-live / wrap-up embeds to Discord.
Motivation: before this, the NVENC transcode ran 24/7 (~39 W) even hours after a card ended, because the only way to stop it was a manual Stop that stayed down until a human pressed Start.
Where the code lives
The feature is a self-contained package, obbyschedule/, which never imports app.py — the
cockpit injects its primitives as callbacks, so the dependency runs one way only.
| Module | Contents |
|---|---|
models.py |
Frozen dataclasses + StrEnums. ScheduleSettings.from_config does all coercion/bounding. No I/O. |
espn.py |
EspnScheduleProvider. Pure @staticmethod parsers (parse_calendar, parse_event) so tests run on recorded JSON. |
notify.py |
DiscordNotifier (retries, 429 handling, never raises) + EmbedBuilder (dict in, dict out). |
state.py |
ScheduleState + ScheduleStateStore — atomic JSON at schedule.state_path. |
scheduler.py |
UfcScheduler. decide() and due_milestones() are pure and synchronous; tick()/run() are the async shell. |
protocols.py |
ScheduleProvider / Notifier structural interfaces, so stubs are type-legal. |
Data source
https://site.api.espn.com/apis/site/v2/sports/mma/ufc/scoreboard — public, unauthenticated.
leagues[0].calendar→ the season’s cards (label,startDate,endDate).events[].competitions[]→ one row per bout, each with its owndateandstatus.type.completed. Distinct dates are the broadcast segments (early prelims / prelims / main card), and the completion flags are how the card’s end is detected.
Gotcha: the calendar start is not always the first bout
For the 2026-07-25 Abu Dhabi card the calendar reads 16:00Z (main card) while the prelims open at
13:00Z. Countdowns therefore anchor on first_card_start from the event detail, and the detail
is loaded max(warn_minutes) + 60m + CALENDAR_SKEW(12h) ≈ 37h ahead so the 24-hour warning is never
missed. next_wakeup() keeps that wide window cheap by sleeping until the next milestone rather than
polling every two minutes for a day and a half.
Gotcha: a scratched bout never completes
STATUS_CANCELED / STATUS_POSTPONED bouts are excluded from the “is everything done?” test, and a
completed main event also ends the card. Otherwise one cancelled prelim would hold the stream up
forever.
Policy
UfcScheduler.decide() — evaluated fresh every tick (level-triggered, so a restart self-heals):
- START once
now >= first_card_start - lead_minutes(default 10), if the card is not finished, not suppressed, and nothing is already running. Clears the operator Stop and kicks a private-IPTV refresh — the pre-roll is the one window where the spare provider connection is free. - STOP once every bout is decided and
end_grace_minutes(default 30) has elapsed since the card was first observed final, or whenmax_runtime_hours(default 8) trips as a failsafe if ESPN stalls. The failsafe is checked first so a stuck grace stamp cannot defeat it. - Re-arm if the encode goes down mid-card (a crash the watchdog could not recover, or a scraper stand-down). The scheduler is level-triggered, so it re-issues START rather than sitting idle until the card ends.
- Only ever stands down a stream it owns (
started_by_scheduler).
Adoption — why it isn’t “only what I started”
The obvious rule, never touch a stream you did not start, quietly makes the whole feature a no-op in the case that actually matters. Production had the encode up for six days straight; if nobody remembers to press Stop first, the scheduler never owns it, the stand-down never fires, and the card ends with ffmpeg still burning — the exact 24/7 behaviour this replaces.
So should_adopt() takes ownership of an already-running stream, but only once the card is genuinely
in its window (PRE_ROLL or LIVE). It will not adopt a card the operator vetoed with Stop, one
already stood down, a finished card, or anything at all while auto-schedule is off. That keeps the
operator’s explicit “not this card” intact while still guaranteeing the card ends in standby.
Operator override
Pressing Stop during a card records stream.stop_reason = "manual" and stamps
suppressed_event_id with the card being tracked. That means “not this event” — the scheduler
stays armed for the next one. A manual Start or Restart lifts the suppression.
schedule_start_stream / schedule_stop_stream in app.py both take PROCESS_LOCK, which is what
serialises the scheduler against a human pressing Stop: whoever takes the lock first wins, and the
loser observes the other’s effect.
Ownership continuity
If ESPN changes an event’s id mid-card, ScheduleState.track() carries scheduler ownership onto
the new id. Dropping it would orphan the encode, since the stand-down branch only fires for
scheduler-owned events.
Notifications
Milestones per card, each fired at most once (deduped in the persisted ledger):
- Coming up — posted when a card is first tracked (~37h out), announcing what’s next with a static per-timezone time table for every segment. See below.
- Countdowns at 24h / 12h / 6h / 2h / 30m before the first bout (
notify.warn_minutes). - Card start for each segment.
- Event end, including the main-event winner from
competitors[].winner.
“Coming up” and the timezone table
Discord’s <t:…:R> markup only localises for the person reading the message in Discord. That is
useless the moment someone quotes the post, screenshots it, or reads it through a bridge — and this
audience is spread across North America, Europe and APAC. So the “Coming up” embed carries a static,
aligned table per card segment:
Los Angeles Sat 1 Aug, 10:00 AM PDT
New York Sat 1 Aug, 1:00 PM EDT
London Sat 1 Aug, 6:00 PM BST
Sydney Sun 2 Aug, 3:00 AM AEST
Zones come from notify.timezones, which accepts bare IANA names or {zone, label} pairs. An
unknown zone is dropped, never rendered: load_zone() falls back to UTC, so a typo would
otherwise print a confidently wrong time under the right city name.
Operators can re-post it any time from the cockpit’s Post “Coming up” button, or
POST /api/schedule {"coming_up": true} — that path force-fetches the next card’s detail even when
the loop would not have loaded it yet, and bypasses the once-per-event ledger.
Card times use Discord’s dynamic timestamp markup (<t:epoch:f> / <t:epoch:R>) so each reader sees
them in their own timezone. Every embed links to https://fight.nswfiles.com/.
A milestone more than notify.max_late_minutes (20) past due is dropped, not fired — after a
redeploy or an outage the channel should get silence, not a burst of stale countdowns. sweep_stale()
marks those as fired so they are not re-evaluated forever.
Config
Lives under the top-level schedule: key.
schedule:
enabled: true
espn_scoreboard_url: https://site.api.espn.com/apis/site/v2/sports/mma/ufc/scoreboard
include_pattern: '^UFC\s+(\d+|Fight Night)'
exclude_pattern: 'Contender Series|Road to UFC'
lead_minutes: 10
end_grace_minutes: 30
max_runtime_hours: 8
calendar_refresh_seconds: 3600
live_poll_seconds: 120
acquisition_poll_seconds: 180 # retry until the current segment has a high-grade source
cache_max_age_hours: 72 # validated detail survives a temporary ESPN outage
stall_hours: 6 # stand-down backstop when ESPN never marks the card final
stall_idle_minutes: 45
require_event_match: true # a feed must identify the tracked card
display_timezone: Canada/Pacific
state_path: /etc/obbystreams/schedule_state.json
notify:
enabled: true
discord_webhook_url: '<secret>'
watcher_url: https://fight.nswfiles.com/
warn_minutes: [1440, 720, 360, 120, 30]
notify_card_start: true
notify_event_end: true
max_late_minutes: 20
normalize_configgotcha. It rebuilds the config fromDEFAULT_CONFIGon every save and only copies whitelisted sections.scheduleis copied through explicitly innormalize_config; without that line an operator’s settings would be silently erased by the next unrelatedsave_config(). There is a regression test for exactly this (test_schedule_section_survives_an_unrelated_save).
The webhook URL is a bearer credential and is masked to "***" by public_config(), so it never
leaves the box via /api/config or /api/status.
API
GET /api/schedule(guarded) →{enabled, phase, event, next_event, countdown_seconds, cards, …}POST /api/schedule(guarded) →{"enabled": bool}to toggle,{"test_notification": true}to post one test embed.- The same snapshot is embedded in
/api/statusunderschedule, so the SPA needs no extra polling.
Event-aware source discovery
Arming on time is only half the job — the encode also has to be carrying that card. Until 2026-08-02 it frequently was not: the scraper’s only questions were “does this channel say UFC?” and “is there a date within 30h?”, so the feeds auto-selected for one Saturday stayed selected the next. On 2026-08-01 the cockpit armed perfectly for Medić vs. Rodriguez and then ran the entire event on the three soursignal channels picked a week earlier for Ankalaev vs. Guskov, reporting healthy the whole time (ffmpeg was decoding fine — it was simply the wrong fight).
Four things changed:
- The card’s identity reaches the scraper.
UfcEvent.context()builds anEventContext(fighter surnames, theUFC 330-style event number, and ESPN’s real per-segment start times). The scheduler publishes it every tick through theSourceResolverprotocol, implemented in the cockpit byCockpitSourceResolver. Names are folded to ASCII (normalize_match_text), because ESPN saysMedićand the provider saysMEDIC. - Discovery runs before the start, not after.
UfcScheduler.tick()refreshes sources before applying its START decision. Previously the encode came up on stale links and the refresh that followed then declined to touch a stream that looked healthy —should_protect_live_private_streampinned the mistake for hours. Protection is now forfeited by a feed that cannot be the tracked card, or one chosen before the card moved to its next segment. - Unverified means nothing goes on air.
schedule_start_links()only returns feeds tagged with the trackedevent_id; with none, the cockpit stays armed with the encode down and retries onacquisition_poll_seconds(180s). Discord gets a warning if the card starts with nothing found. Public backup sources are pulled in afterpublic_fallback_after_attemptsfailed sweeps, but only after the card is live; an unidentified fallback is never aired during pre-roll. If ffmpeg was already carrying a stale/unidentified source when pre-roll opens, it is replaced with a verified source or quarantined offline — decoder health alone is never treated as card identity. - Segments switch dynamically. ESPN can publish one segment (main card only), two (prelims + main), or three (early prelims + prelims + main). The earliest one opens pre-roll, and every later boundary forces discovery and selects only current-segment feeds.
- Switching is bounded. Every swap costs viewers a few seconds, so
switch_cooldown_seconds,switch_confirm_samplesandmax_switches_per_cardstop it flapping mid-fight. A confirmed wrong-card feed overrides the cooldown: that is a correction, not an improvement.
Sources carry event_id + discovered_at in stream.sources. purge_foreign_event_sources() runs
at every arming and the stand-down retires the card’s feeds and clears locked_source_id.
GET /api/schedule gains a source_state block (matched sources, match terms, rejected candidates
with reasons, switch count), and the cockpit renders it — including
🔍 Acquiring a verified source for … — 6 candidates rejected (wrong event).
Stand-down backstop
ESPN sometimes never flips a card’s final flag. card_stalled() stands the stream down when the
last segment started more than stall_hours (6) ago and no bout has been decided for
stall_idle_minutes (45) — both conditions, so a genuinely slow card is never cut off mid-broadcast.
The absolute failsafe allows at least max_runtime_hours (8h) from the earliest segment and a
full five-hour runway from the Main card start, whichever is later. That keeps a three-block card’s
early prelims from consuming the Main card’s safety margin.
Restart safety
With auto-schedule enabled, the service always boots into process standby. The scheduler’s first event-aware tick — not the watchdog — decides whether ffmpeg may start. The exact links handed to the running process are tracked separately from mutable config, so a config refresh cannot make an old process appear to be carrying a newly selected source. Mid-card crash recovery is gated through the same current-event link selection, and the persisted absolute deadline remains enforceable even when both ESPN and the cached detail are unavailable.
Cockpit UI
- The header banner becomes state-aware:
⏸ STANDBY — auto-starts for … in 3h 12mwhile auto-schedule is on, versus the existing red⏹ STOPPED (manual)when it is off. - An Auto-schedule switch sits in the header actions.
- A
SchedulePanellists the tracked card, each segment’s start time, and bout progress, plus a Test Discord button. - Pure helpers live in
frontend/src/lib/schedule.tsso the countdown/banner logic is vitest-testable without a DOM.
Verifying
cd /opt/obbystreams
uv run ruff check . && uv run ty check && uv run pytest -q && npm test && npm run build
# Walk a whole event timeline offline — no network, no Discord, no ffmpeg:
uv run python tools/schedule_replay.py --step 10
# Against the real ESPN calendar (only meaningful for a card that hasn't happened yet):
uv run python tools/schedule_replay.py --live
Tests: tests/test_schedule_parsing.py (ESPN shapes), tests/test_schedule_policy.py (the state
machine on a fake clock), tests/test_schedule_notifications.py (milestones + embeds),
tests/test_schedule_loop.py (the async shell with stubs). Fixtures in tests/fixtures/espn_*.json
are trimmed captures of the real 2026-07-25 card plus pre / mid / cancelled variants.
Note the test harness never enters the ASGI lifespan, so SCHEDULER is None there — the endpoints
degrade to an “scheduler not running” snapshot rather than erroring.
Deploying
Code changes require restarting obbystreams.service, which interrupts the live encode. Do it
in a non-event window and check /api/status for viewers first.