fix: keep the board up between episodes

[roblesi]

Problem

A user reported that with a 30-second refresh, the board sometimes flips to an empty display between episodes, then flips back once the next one starts. Their workaround was to pull the data through Home Assistant and delay the entities.

When an episode ends, Plex removes the session from /status/sessions during its Up Next countdown. It only creates a new session once the next episode starts. A poll that lands in that gap gets no sessions, so the plugin reports Idle with every media variable blank.

Filtering out updates with a blank episode title doesn't help on its own. In the gap the session is usually missing entirely, not present with an empty title.

Change

• New hold_seconds setting, titled "Hold Between Episodes": default 60, range 0–600, 0 turns it off. When Plex reports no streams, the plugin keeps returning the last streams it saw until the hold runs out. The timer starts at the first empty poll, not the last poll that saw a stream, so the hold doesn't depend on the refresh interval. A new stream replaces the held one immediately and resets the timer.
• Held data is the last parsed session list (after the Plex User filter), laid out again for each board. The board content doesn't change, so nothing flips. That includes state, is_playing and stream_count.
• Sessions with no title are skipped. A session Plex hasn't loaded yet has nothing to show, and it can't replace the stream being held.
• validate_config rejects a hold_seconds that isn't a number or is outside 0–600.
• Docs: the README configuration table, the SETUP configuration reference, and two troubleshooting entries: the board going blank between episodes, and the board lingering after you stop watching.
• Version: bumped to 1.2.0.

Trade-off: after playback really stops, "Nothing playing" now appears up to hold_seconds plus one refresh later. Set the hold to 0 to get the old behavior.

Tests

There are 13 new tests: 11 in TestHoldBetweenEpisodes and 2 validation tests. I wrote them before the implementation.

With only import time added, so the time.monotonic patch resolves, they failed on behavior:

E       AssertionError: assert [] == ['Hold must b... 600 seconds']
E       AssertionError: assert '' == 'Ozymandias'
E       AssertionError: assert '' == 'Granite State'
E       AssertionError: assert 'Playing' == 'Idle'
FAILED TestValidateConfig::test_hold_out_of_range
FAILED TestValidateConfig::test_hold_not_a_number
FAILED TestHoldBetweenEpisodes::test_last_stream_is_held_through_a_gap
FAILED TestHoldBetweenEpisodes::test_hold_counts_from_the_first_empty_poll
FAILED TestHoldBetweenEpisodes::test_hold_restarts_after_playback_resumes
FAILED TestHoldBetweenEpisodes::test_held_stream_is_laid_out_for_each_board
FAILED TestHoldBetweenEpisodes::test_stream_without_a_title_is_skipped
FAILED TestHoldBetweenEpisodes::test_stream_without_a_title_does_not_replace_the_held_one

Some tests already passed before the change, because they cover idle behavior that exists today. To check those, I broke the implementation in six ways and confirmed each break is caught:

Mutation	Caught by
Hold removed	test_last_stream_is_held_through_a_gap and 4 more
< → <= at the hold boundary	test_idle_once_the_hold_runs_out, test_hold_counts_from_the_first_empty_poll, test_zero_turns_the_hold_off
Timer restarted on every empty poll	test_idle_stays_idle_after_the_hold and 2 more
hold_seconds: 0 treated as the default	test_zero_turns_the_hold_off
Title filter removed	test_stream_without_a_title_is_skipped, test_stream_without_a_title_does_not_replace_the_held_one
Timer not reset when playback resumes	test_hold_restarts_after_playback_resumes

A seventh mutation survived: removing the line that cleared the held list once the hold ran out. That showed the line had no effect on behavior, so I removed it from the implementation. One more redundant early return came out the same way.

Changed test: test_minor_version_bump pinned version == "1.1.0", so any release would fail it. I renamed it to test_sign_in_is_not_a_breaking_release; it now asserts major 1 and at least 1.1. That keeps what it protected: sign-in shipped without breaking 1.0.x settings.

Results:

• ./run_tests.sh: 125 passed, __init__.py at 100% coverage.
• FiestaBoard's scripts/validate_plugins.py --plugin=plex --strict: passed, no warnings.

Not verified: I couldn't test against a real Plex server. The gap behavior comes from how Plex handles Up Next sessions, not from a captured response. Once this ships, it's worth asking the reporting user to confirm the 60-second default covers their countdown.

🤖 Generated with Claude Code

https://claude.ai/code/session_01A7aYfsnp25o3X3x3AYhzPQ

---

Generated by Claude Code