Suggestion system
Personalised recommendation shelves — settings, data and background jobs
RamTV can build personalised recommendation shelves for every viewer — what to watch next, what they haven't finished, what matches their taste — without you writing a line of code or picking anything by hand. This article covers every shelf type, exactly what data drives each one, the background job that builds them, and every setting under Admin → Settings → Suggestions.
How it works
The system works in three stages:
Collect — viewing progress, likes, watchlist entries and completed-playback events are recorded as people use the site. This isn't new data collected just for suggestions; it's the same activity RamTV already tracks for other reasons.
Build — a background cronjob computes each viewer's shelves on a schedule and stores the result. This is the expensive part, and it happens ahead of time rather than while someone is looking at a page.
Show — a page just reads the already-built shelves. There's no per-request computation, so a suggestion widget is as fast as any other widget on the page. The one exception is Continue Watching, which is computed live on every page load — that's deliberate, so pressing play shows up there immediately instead of waiting for the next scheduled rebuild.
The background job
The "Content suggestions" cronjob does the building. Its interval is configurable, but it doesn't rebuild every viewer on every run — it uses an activity-tiered schedule, so people who are actually using the site get fresher shelves without wasting cycles on people who aren't:
| Viewer last active | Rebuilt every |
| Within the last day | 6 hours (default) |
| Within the last week | 24 hours (default) |
| Within the last month | Weekly (default) |
| Longer ago | Your own schedule, or never |
Each run also processes at most a configurable number of viewers and stops after a configurable time limit — a large user base doesn't create one giant job that blocks everything else; it just picks up the rest of the queue on the next run.
The eight suggestion shelves
| Shelf | Built | What drives it |
| Continue Watching | Live, every page load | Your own progress — the furthest-touched episode per show |
| Up Next | Background job | For each show with a recently finished episode, the next one in broadcast order |
| Recommended | Background job | Seeded from your recent liked/watched/watchlisted titles; matched against local catalogue data, live TMDB data, or both — configurable |
| Because You Watched/Liked X | Background job | One shelf per seed title, matched from local catalogue data only |
| Finish the Collection | Background job | The rest of a movie franchise (a TMDB collection) you've already started |
| Top Genre | Background job | Your most-watched genre across movies and TV, surfacing its highest-rated titles |
| Watchlist, Ready to Watch | Background job | Titles on your watchlist that have just become playable |
| Forgotten Favourites | Background job | Titles you liked or watched more than once, but haven't touched in a while |
Settings
General — turn the whole system on or off, the cronjob's interval, how many viewers and how many seconds each run may use, whether already-seen titles are hidden across every shelf, and whether every shelf is restricted to currently-playable titles only.
Rebuild schedule — the four activity tiers from the table above, each with its own "rebuild every N hours" setting.
Per-shelf settings — one settings group per shelf: on/off, its position among the other shelves, and how many titles it returns. Some shelves have extra settings of their own — Recommended's is the richest: choose local catalogue matching, live TMDB calls, or both, and whether a TMDB suggestion RamTV doesn't have yet is allowed to auto-create a bare catalogue entry for the automation tools to fill in later.
Where viewers actually see it
PageBuilder — a "Suggestion widget" you can drop on any page, any number of times. Each copy on the page shows the next shelf in line, so placing it three times on a page shows three different shelves without any per-widget configuration.
The viewer's library — a "For You" tab that stacks every remaining shelf as its own row, shown only once at least one shelf actually has something in it.
If it's not showing anything
Check, in order: that the system is enabled in Settings; that the Content suggestions cronjob has recent successful runs (Admin → Settings → Cronjob → Run logs — see the Installation article for how to confirm your cronjob is actually running at all); and, for a specific viewer, that they have enough history for that particular shelf to have anything to show — a viewer with no watch history yet won't have a Continue Watching or Top Genre shelf, because there's nothing to build one from.
Is this available on other RamTV platforms?
The engine itself doesn't know what a movie or a TV episode is — every shelf described above is supplied by RamTV's own catalogue plugins sitting on top of a generic recommendation engine. That means this system isn't automatically available on every BusyOwl platform: as of this article, it's specific to RamTV. Bringing it to another catalogue type would mean building that platform's own equivalents of the shelves above — a "next chapter" instead of "next episode", a discography instead of a film collection — rather than rewriting the underlying engine.