Recommendations & Discovery

Since: 0.15.0

TL;DR

Phlix surfaces personalized content through three discovery surfaces: Explore (browsable collections by mood, genre, and activity), Watch History (continuing shows and resuming paused content), and Similar / Because You Watched (content recommendations based on your viewing patterns).

---

1. Explore

Overview

Explore is a browsable discovery surface that organizes content into collections curated by category — genre, mood, activity, actor, decade, and more. Unlike search (which requires a query), Explore surfaces content proactively.

Collection Types

Collection Type	Description
Genre	Action, Drama, Comedy, Documentary, etc.
Mood	"Cozy Night In", "Adrenaline Rush", "Thought Provoking"
Activity	"Family Movie Night", "Date Night", "Kids"
Actor/Director	All content featuring a specific person
Decade	Content from a specific era (e.g., "80s Classics")
Critically Acclaimed	Award winners and highly-rated titles
Trending Now	Content with recent high play activity

How Collections Are Generated

Explore collections are generated by the DiscoveryService:

1. Static collections are pre-seeded by administrators via the admin UI or API
2. Dynamic collections are refreshed on a schedule (configurable, default: every 6 hours) by analyzing media metadata and user activity
3. Personalized collections (BYW, Continue Watching) are computed per-user

Admin Configuration

Administrators can manage collections in Admin → Library → Discover Collections:

• Create new collections with custom rules (e.g., "genre = documentary AND year >= 2020")
• Set collection visibility (public, logged-in users, specific user tags)
• Pin or hide specific items within any collection
• Schedule collections to appear at specific times (e.g., "Halloween Horror" in October)

---

2. Watch History

Overview

Watch History tracks every piece of content a user has started or finished, enabling features like "Continue Watching," "Up Next," and "Resume from position."

Data Tracked

For each user-media pair, Phlix records:

Field	Description
started_at	Timestamp when playback began
completed_at	Timestamp when playback reached 90%+
position_secs	Last known playback position in seconds
percent_complete	How much of the media was watched (0–100)
play_count	Number of times playback was started

Continue Watching

The Continue Watching row on the home screen surfaces unwatched or partially-watched content, sorted by most recently played. Items where percent_complete >= 90 are excluded (considered "finished").

Up Next

For TV shows, the Up Next feature links episodes in a series. When a user finishes Episode N, Episode N+1 is promoted to the top of Continue Watching. The server considers:

• Whether the next episode exists and is available
• User's auto-play settings
• Whether the show is still actively airing (new episodes get higher priority)

---

3. Similar / Because You Watched (BYW)

Overview

"Similar" and "Because You Watched" are personalized recommendation rows computed from a user's viewing history using item-similarity algorithms.

Because You Watched (BYW)

BYW takes a specific title the user has watched and finds other titles with similar attributes:

• Same genre(s)
• Same actors or directors
• Shared tags or keywords
• Similar release year range
• Similar runtime

The BYW algorithm uses a weighted attribute vector. Weights are configurable in config/discovery.php:

return [
    'byw_weights' => [
        'genre'       => 0.35,
        'actor'        => 0.25,
        'director'     => 0.15,
        'tag'          => 0.15,
        'year_range'   => 0.07,
        'runtime'      => 0.03,
    ],
    'byw_max_results' => 20,
    'byw_min_similarity' => 0.15,
];

Similar (Global)

"Similar" recommendations are precomputed for all titles and do not depend on the current user's history. These are used in public-facing rows like "If you liked X, you might also like Y." The precomputation runs nightly and is cached.

Cold Start

New users with no watch history receive generic popular/trending content in BYW slots. The system gradually personalizes as watch history accumulates (minimum 5 items watched to trigger personalization).

---

Privacy

Watch history data is stored per-user. Users can:

• View their watch history: Settings → Privacy → Watch History
• Clear individual items: Click the X on any item in the history list
• Clear all history: Settings → Privacy → Clear Watch History

Admins can disable watch history tracking server-wide via PHLIX_WATCH_HISTORY_ENABLED=false in the environment.

---

Related Pages

• Discovery Developer Guide — API reference and plugin hooks for adding recommendation sources
• Smart Playlists — Admin-defined algorithmic playlists
• Collections — How collection rules are structured