Collection Rotation

The feature that started it all. homescreen-hero automatically rotates collections on your Plex homescreen on a schedule, keeping things fresh for all your users without any manual effort.

How a Rotation Works

When a rotation runs - either on schedule or manually triggered - here's what happens:

1. Sync integrations - If enabled, syncs your Trakt, MDBList, Letterboxd, and AniList sources to make sure collections are up to date before selecting
2. Process groups - Each group is evaluated in order (or by weight). For each active group, homescreen-hero picks a random number of collections between the group's min and max picks
3. Select collections - Collections are chosen based on your strategy (random, weighted, or LRU), respecting gap rules to avoid repeats
4. Apply to Plex - Selected collections are promoted on your Plex homescreen. Everything else gets hidden. Pinned collections are placed first, followed by the rotation picks
5. Record history - The rotation is logged with a timestamp and the list of featured collections, so LRU and gap rules work correctly on future rotations
6. Collect analytics - If Tautulli is connected, watch stats are collected for the featured collections

Groups

Collections are organized into groups, each with their own selection rules, ordering, visibility settings, and strategy.

Rotation Settings

Setting	Default	Description
Interval (hours)	12	How often rotations run automatically
Max Collections	5	Global cap on featured collections per rotation
Strategy	Random	Selection strategy — see Strategies
Sync on Rotation	Enabled	Sync all integration sources before each rotation
Blacklisted Collections	None	Collections that should never be selected

Pinned Collections

Some collections should always be on your homescreen regardless of what gets rotated. Pinned collections:

• Are always featured on the homescreen, every rotation
• Don't count against the max collections limit
• Are placed first in the homescreen order, before rotation picks
• Have their own visibility settings (home, shared, recommended) independent of groups

This is useful for collections like "Continue Watching," "Recently Added," or a personal favorites collection that you always want visible.

Pin or unpin collections from the Collections page in the dashboard.

Manual Rotation & Simulation

You don't have to wait for the scheduler. From the dashboard you can:

• Rotate Now - Run an immediate rotation. Updates your Plex homescreen and records history just like a scheduled run
• Dry Run - Preview what the next rotation would select without actually applying it to Plex
• Simulate - Generate a simulated rotation that you can review and then choose to apply or discard

Simulation is useful if you want to see what the algorithm would pick before committing - especially handy when you're tuning group settings or trying a new strategy.

Scheduler

The rotation scheduler runs in the background on an interval (default: every 12 hours). You can:

• Enable/disable the scheduler without changing other settings
• Change the interval - the scheduler adjusts automatically without a restart
• View status from the Rotation Status widget on the dashboard, which shows whether it's running and a countdown to the next scheduled rotation

Integration Sync Modes

How homescreen-hero handles integration syncing during rotation depends on the sync_all_on_rotation setting:

• Enabled (default) - All Trakt, MDBList, Letterboxd, and AniList sources are synced before collections are selected. This ensures everything is up to date but takes longer.
• Disabled - Collections are selected first, then only the sources that match the selected collections are synced. Faster, but newly added list items won't be considered until their source gets selected.

Rotation History

Every rotation is recorded with a timestamp and the list of featured collections. This history powers:

• LRU strategy - Knowing which collections were used least recently
• Gap rules - Enforcing min_gap_rotations to prevent repeats
• Recent Rotations widget - Viewing past rotations on the dashboard
• Analytics - Tracking collection performance over time (with Tautulli)