218 lines
5.9 KiB
Markdown
218 lines
5.9 KiB
Markdown
# 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
|
|
```sql
|
|
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 ✅
|
|
- [x] 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](./SURPRISE_ME_RECOMMENDATION_DESIGN.md)
|
|
|
|
**Status**: 📝 Design Complete → Ready for Implementation
|
|
**Next Step**: Database schema migration
|