What goes in a row

Recommendation sources

Settings → Finding titles controls where candidate titles come from. Shortlist pools every source you enable, keeps only what’s already in your library, then ranks them with a simple no-AI score and writes each pick’s “why” in code. More sources means wider reach. Available today:

• TMDB, similar titles. The baseline. Titles TMDB says are similar to what each person watched.
• TMDB, discover by taste. Widens into popular, well-rated titles in the genres each person leans toward, derived from their watch history.
• Trakt, related titles. Needs a Trakt API key, added in Connections. Uses Trakt’s recommendation graph, which often surfaces “what to watch next” picks that TMDB’s similar list misses. Trakt now requires a paid VIP subscription to create an API key, so this source is only available if you have one. Everything else here works without it.

• AI web search for what to watch next. Searches the live web for current, well-reviewed titles, then resolves each against your library. This reaches beyond TMDB and Trakt to fresh releases and critics’ lists.

  It works on every provider. Choose its Search backend in Settings → Connections → Web search: your provider’s own web search (Claude, GPT or Gemini), an Exa key, or your own self-hosted SearXNG — either external works with any provider, including a local Ollama model. Exactly one backend is used, and its credentials live on that same card.

Each row also chooses which libraries it builds in, using the row editor’s Libraries picker. A Plex collection lives in one library, so a row builds one collection per library you tick. Leave them all ticked, the default, to cover every library, or point a row at just one such as “4K Movies” on a server with several libraries of a type. What the row recommends, movies or shows or both, follows the libraries you pick.

How often rows rebuild, already-watched, and cost

Settings → Finding titles has four more dials, each of which a row can override:

• How often it changes, called How often rows rebuild in Settings where the global lives. A number of days, so it says what it does: 1 rebuilds every night, 7 weekly, 30 monthly, and 0 means build once and never reshuffle.

  On most nights an unchanged row is left exactly as it is, with no rebuild and no Plex write, which is why a person’s row stays familiar instead of being reshuffled daily. On a rebuild night the strongest two-thirds or so of the picks stay and the weakest third rotates out. The default is 8 days. If you trigger two runs the same day, a row that isn’t due won’t change. That is expected.

  This used to be a 0–1 “Freshness” percentage that a curve turned into days behind the scenes, so 0.55 meant “every 7 days” and there was no way to ask for anything slower than a fortnight. Upgrading converts every value to the day count it already meant, so no row changes pace.

• Recent releases. How much a title’s release date counts when Shortlist ranks it. At 0.0 release date is ignored entirely: a well-rated 1996 film and a well-rated 2024 one are judged the same, which is why rows can fill up with older titles. Turn it up and newer titles rank higher.

  The default is 0.5 — “leans towards recent releases”. Age-blind is not the neutral setting it looks like: a library holds decades of catalog against a trickle of new releases, so a ranker with no opinion about age just inherits that skew.

  This applies to existing servers too. Upgrading to the release that introduced it shifts each row towards newer titles on its next rebuild night — staggered by each row’s cadence rather than all at once. Nothing about who can see what changes. If you preferred the old behaviour, set the slider to 0 and ranking ignores release date exactly as it used to.

  It is a preference, not a filter. Nothing is excluded for being old — an older title simply has to be a better match to win a slot, so a classic three of someone’s watches point at still beats a forgettable new release. At 1.0, roughly every 8 years of age halves a title’s ranking weight; at 0.5 it takes about 16 years. The slider shows a live strip of what each era is worth so you can see the trade before you save it.

  This is not the rebuild cadence. That is how often a row re-picks; this is which titles win when it does. A row can rebuild every night and still be full of 1990s films — that pairing is exactly what this dial is for.

• Already-watched titles. How much of a partly-watched title still counts as watched and gets filtered out. The default keeps anything finished out of the picks.
• Watches the AI web search looks up. How many of each person’s recent titles the AI web-search source looks up, one cached search each, taken off the front of the list above. This is the main cost lever on that source. Lower it to spend fewer tokens and web searches.

If a watched title still gets recommended

This is rare, because Shortlist reads each person’s complete watched set from Plex every run, including titles they only marked watched, whether ticked off individually or a whole season at once, rather than played.

It reads the library as that user, with the per-user server token Plex mints for every share, and viewCount > 0 covers both plays and marks at any depth. There is nothing to configure, and it works whether or not Shortlist runs on the same machine as Plex. This replaced an older playback-history read that saw plays only and capped at around 200. On one real server that hid 13,201 of a user’s watched titles behind the roughly 1,000 the API reported.

When it does happen, it is almost always timing. The read is per-run, so a title you mark watched after the last run stays eligible until the next one. To fix it immediately without waiting for a scheduled run, go to Jobs → Sync history. That re-reads every user’s watched set right now, writes nothing to Plex, and updates what Shortlist knows, including the “N titles watched” count on the Users page. Any run after that leaves the title out.

Any row can override all of this

Settings → Finding titles sets what a row uses unless the row says otherwise. Open any row (Rows → Edit) and it defines its own recipe:

So a “What to watch next” row can be Trakt-only, a “Hidden gems” row can use AI web search alone pointed at just your 4K library with Recent releases turned all the way down, a “New & notable” row can turn the same dial all the way up, and your default “Picked for You” can stay on the global settings. All on the same server, all at once. The Rows list shows each row’s overrides on its card, so you can see at a glance which rows differ.

A row left on “Use global default” stays in sync with Settings → Finding titles.

You can go one step finer, per person. Row size and recent-watches depth can also be set for a single person on a single row. Open that person (Users → click them), find the row, and use Customize for this person. Their value wins over the row’s, which wins over the global default. Leave a customization on “default” and that person follows the row like everyone else.

There is one exception, the seeded “Picked for You” row. Its name and size always follow the global Settings under Row defaults so they stay in sync everywhere, and the row editor points you there instead of offering its own. Its sources, libraries and audience are its own, exactly like any other row.

Changes clean up Plex right away. You don’t have to wait for a run:

• Delete a row. Its collections are removed from Plex immediately, for everyone who had it. That includes rows whose title is built from a person’s top pick, which Shortlist finds by the exact title the last run delivered. The titles stay in your library; only the row goes.
• Rename a row. Its collection is retitled in place for every user, so nothing is orphaned.
• Disable a user, or drop someone from a row’s audience. That person’s now-stale collections are removed immediately.
• Remove from Plex, the button on each row. Clears a row’s collections on demand without deleting the row’s settings. Handy to force a rebuild on the next run.
• Disable a row, its on/off switch. Its collection comes off Plex Home on the next run. A row whose title is dynamic, built from a top pick, is left for that rebuild; use Remove from Plex if you want it gone right now. Everything left in place stays private, because the row’s label keeps it excluded from everyone else.

Blocking a seed

A seed is one of a person’s recent watches that Shortlist searches from. When a watch isn’t really them, such as a film they put on for someone else or a genre they don’t want more of, block it. The watch stays in their history, it just stops shaping their picks.

The natural place to do it is a run’s How we picked page, on the seeds list, since a bad seed is usually what you noticed in the first place. There is also a search box on a person’s detail page (Users → someone → Settings → Blocked seeds) for a title you remember but can’t find a run for.

Blocks are personal. A shared row is public, so one person’s block does not reshape what everyone else sees. Otherwise an individual preference would become a server-wide edit nobody else can see or undo. Shared rows use their own server-wide list, recommendations.blocked_shared_seeds.

Letting people block their own

Blocking is something only you can do, which means anyone who wants a bad seed gone has to message you about it. Respect Plex ratings (Settings → Finding titles) closes that gap: when someone rates a title 1 star or gives it a thumbs-down in Plex, it stops being used to find similar things for them, exactly as if you had blocked it.

Nothing changes for them. They rate it in Plex, on the screen they just finished watching on. There is no Shortlist account, no login, and nothing for you to do per person.

A few things worth knowing:

• A rating they haven’t given changes nothing. Only a low rating acts, so this is silent for the majority of people, who rate nothing at all.
• Rating what they just watched works straight away. The nightly sync reads everything watched since it last ran, and a rating rides along with it. Rating something from months ago is the slow case: that title is behind the point the nightly read reaches back to, so it waits for the weekly full re-read. Lower sync.watch_full_days if you’d rather not wait for those.
• A title stops seeding only if it was going to seed. Rows are built from someone’s most recent watches, so disliking a film from two years ago is recorded but changes nothing — it was never going to be picked as a seed. The rating matters when it’s something they saw lately.
• Shared rows ignore ratings, for the same reason they ignore blocks.
• Ratings written by another tool are ignored. If you run Kometa’s rating sync, or anything else that copies IMDb scores into Plex’s user rating, Shortlist won’t mistake those for your opinion — Plex’s own star control only writes whole numbers, so a rating with a decimal in it wasn’t typed by a person. A person’s page says so plainly when this is happening to their account.

You can see all of this on Users → someone → Watch history: what they rated each title, and which ones have stopped seeding as a result.

Per run, it’s in the trace. Open a run, then How we picked for a person: the “Watched recently” step says in one line what ratings did on that run — off, on but nothing rated low enough, on but the account’s ratings were ignored as tool-written, or how many titles a rating dropped — and lists the ones it dropped. That line reports the setting as it was when the run happened, so changing it later doesn’t rewrite the history of a run you’re reading a fortnight after the fact. Runs from before v1.2.1 don’t carry it and show only the dropped titles, as they always did.