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, and Letterboxd 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

Groups are how you organize collections for rotation. Each group is a named pool of collections with its own selection rules.

For example, you might have a "Holiday" group that's only active in December, a "New Releases" group that always gets at least 1 pick, and a "Deep Cuts" group with lower priority.

Group Settings

Setting	Description
Name	Display name for the group
Enabled	Toggle the group on/off without deleting it
Min Picks	Minimum collections to select from this group per rotation
Max Picks	Maximum collections to select from this group per rotation
Weight	Relative priority when using the weighted strategy (higher = processed first)
Min Gap Rotations	How many rotations must pass before a collection from this group can be featured again
Collections	The collection names that belong to this group
Date Range	Optional - restrict the group to a date window (e.g., Nov 20 – Dec 26 for holiday collections)

Visibility Settings

Each group also controls how its collections appear on Plex:

• Home - Show on the admin's homescreen
• Shared - Show on shared users' homescreens
• Recommended - Show in the Library Recommended section

This lets you, for example, show curated collections to shared users while keeping niche ones admin-only.

Strategies

The strategy controls how groups are ordered and how collections are picked within each group.

Random

Groups are processed in config order. Collections within each group are selected randomly. This is the simplest option - good variety, no special prioritization.

Weighted

Groups are sorted by weight (highest first), so higher-priority groups get their picks before lower-priority ones. Collections within each group are still selected randomly. Use this when you want certain categories to always take priority (e.g., "Featured" before "Deep Cuts").

Least Recently Used (LRU)

Groups are processed in config order. Collections are selected based on how recently they were featured - those that haven't appeared in the longest time get priority. This ensures fair rotation across your entire library over time.

tip

All three strategies respect the min_gap_rotations setting. Even with random selection, a collection won't appear again until the gap threshold is met.

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 above)
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, and Letterboxd 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)