xorbitlab
/
nextav
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 1 Wiki Activity
nextav/docs/active/recommendations/SURPRISE_ME_SUMMARY.md

5.9 KiB
Raw Permalink Blame History

Surprise Me Feature - Quick Summary

What is "Surprise Me"?

A lightweight video recommendation system for personal video collections that helps users rediscover content they might have forgotten about or haven't watched yet.

Key Concept

Unlike YouTube's complex ML-based recommendations, "Surprise Me" focuses on:

  • ✨ Rediscovery: Surface videos you've forgotten
  • 🎲 Variety: Mix content from different libraries
  • 🎯 Simplicity: No complex ML, just smart queries
  • 📊 Personal: Uses YOUR ratings, bookmarks, and viewing patterns

UI Location

Sidebar Item (NOT a tab):

Sidebar Navigation:
├── Home
├── Settings  
├── Videos
├── Photos
├── Texts
├── Bookmarks
├── 🎲 Surprise Me  ← NEW standalone page at /surprise-me
├── Clusters
└── Folder Viewer

When clicked → navigates to dedicated /surprise-me page

Recommendation Algorithms

1. Smart Mix (Default)

Balanced combination of all algorithms:

  • 30% Weighted Random
  • 25% Forgotten Gems
  • 20% Similar to Favorites
  • 15% Unwatched First
  • 10% Time-Based

2. Weighted Random

Smart randomization considering:

  • How long since last viewed (prefer older)
  • Video ratings (slight boost for higher rated)
  • Library diversity (ensure variety)

3. Forgotten Gems

Videos you showed interest in but haven't watched recently:

  • Bookmarked videos (30+ days ago)
  • Highly-rated videos (4+ stars, 60+ days)
  • Videos from bookmarked folders

4. Similar to Favorites

Find videos from same folders as your 4+ star videos

5. Time-Based

  • Recently added but unwatched
  • Seasonal (same time last year)
  • Archive discoveries (old, never watched)

6. Pure Random

Complete serendipity - totally random selection

7. Unwatched First

Prioritize videos never accessed before

Technical Architecture

New Database Table

media_access (
  media_id,
  access_type: 'view' | 'play' | 'bookmark' | 'rate',
  created_at
)

Tracks when users interact with videos for better recommendations.

New API Endpoints

GET /api/videos/recommendations

  • Query params: algorithm, limit, exclude_recent_days
  • Returns: Array of recommended videos with reasons

POST /api/media-access/:id

  • Tracks user interactions for recommendation improvement

New Components

  1. /src/app/surprise-me/page.tsx - Main page
  2. /src/lib/recommendation-service.ts - Algorithm logic
  3. Modified sidebar.tsx - Add Surprise Me item

User Flow

  1. User clicks "🎲 Surprise Me" in sidebar
  2. Page loads with 20 recommended videos (default: Smart Mix)
  3. Each video card shows:
    • Thumbnail
    • Title, path, size
    • Rating/bookmark status
    • Recommendation reason badge (e.g., "From your favorite library")
  4. User can:
    • Click video to watch
    • Click "Refresh" for new recommendations
    • Change algorithm via dropdown
    • Bookmark/rate directly from cards

Implementation Phases

Phase 1: Foundation ✅

  • Design documentation
  • Database migration
  • Basic service structure

Phase 2: Core (Week 1)

  • 3 basic algorithms (Weighted Random, Unwatched, Pure Random)
  • API endpoint
  • Basic UI page

Phase 3: Advanced (Week 2)

  • 4 advanced algorithms
  • Smart Mix
  • Polished UI

Phase 4: Integration (Week 3)

  • Auto-track video views
  • Recommendation badges
  • Performance optimization

Benefits

For Users

  • 🎯 Discover new content in their own library
  • ⏰ Save time deciding what to watch
  • 💎 Rediscover forgotten favorites
  • 🎲 Serendipitous discoveries
  • 📚 Explore entire collection systematically

Technical

  • 🚀 Lightweight - no ML infrastructure needed
  • ⚡ Fast - simple SQL queries with indexes
  • 📈 Scalable - works with 1K to 100K+ videos
  • 🔧 Maintainable - pure SQL, no black boxes
  • 🎨 Extensible - easy to add new algorithms

Example Scenarios

Scenario: Large Movie Collection

Problem: User has 5,000 movies but always watches the same 50

Solution:

  • Unwatched First: Shows 100s of movies never opened
  • Forgotten Gems: Surfaces 4-star movies from 2 years ago
  • Similar to Favorites: Finds movies in same genre folders

Scenario: New Content Added

Problem: User adds 200 new videos but forgets about them

Solution:

  • Time-Based: "Recently added" shows last 7 days
  • Smart Mix: Includes 30% new content automatically

Scenario: Bored, Want Something Different

Problem: User wants to watch something but doesn't know what

Solution:

  • Pure Random: Complete surprise from entire collection
  • Weighted Random: Random but slightly favors good stuff

Why This Design?

Lightweight Approach

  • ✅ No complex ML training
  • ✅ No external dependencies
  • ✅ Works offline
  • ✅ Instant results
  • ✅ Easy to understand and debug

Personal-Focused

  • ✅ Designed for single user
  • ✅ Leverages existing data (bookmarks, ratings)
  • ✅ Respects user's organizational structure
  • ✅ No privacy concerns (all local)

Practical

  • ✅ Solves real problem (content discovery)
  • ✅ Easy to implement incrementally
  • ✅ Low maintenance overhead
  • ✅ Clear success metrics

Success Metrics

  • 80% of users try the feature
  • 30% click-through rate on recommendations
  • 50% of recommendations are unwatched videos
  • High diversity across libraries/folders

Future Enhancements

  • 🎵 Playlist generation from recommendations
  • 📊 Statistics dashboard
  • 🎯 "Similar videos" on player page
  • 📅 "Video of the Day" feature
  • 🔍 Advanced filters (by library, rating, size)
  • 💾 Save recommendation sets
  • 🚫 "Not interested" exclusions

See Full Design: SURPRISE_ME_RECOMMENDATION_DESIGN.md

Status: 📝 Design Complete → Ready for Implementation
Next Step: Database schema migration