Version 2.0.0
A modern Flask app that connects to your Plex server and suggests a random unwatched movie, TV show, anime, or other video from your Plex library.
Features a sleek, responsive Plex-themed UI with modern glass morphism design, interactive elements, secure JWT-based authentication, and Plex Match functionality for group viewing decisions.
- 🔥 Tinder-Style Swipe UI:
Complete redesign of Plex Match with swipeable card stack, drag gestures (touch & mouse), fly-off animations, and keyboard shortcuts (←/A pass, →/D like, ↑/W super). - 🌐 Global Room Sharing:
Rooms now sync across all deployments via central backend. Share 6-character room codes with friends to join from anywhere. - 🎉 Match Celebrations:
Beautiful full-screen celebration overlay with animated posters and particle effects when matches are found. - ⚡ Backend Integration:
All match data stored onplex-like.satrawi.ccfor cross-instance synchronization.
- 🎨 Complete UI Redesign:
Modern glass morphism design with animated gradients, CSS variables system, Space Grotesk + Inter fonts, and smooth hover animations throughout. - 📺 Movie Duration & Genres:
Main suggestion page now displays movie duration (e.g., "1h 54m") and genre tags, matching the comparison mode styling. - 🎯 Simplified Plex Match:
Match API no longer requires JWT authentication - uses environment PLEX_TOKEN directly for seamless room creation and joining. - ✨ Improved Match UI:
Redesigned room cards, swipe buttons with animations, better modals, and enhanced notification styling.
- 🎬 Movie Comparison Mode:
New side-by-side comparison view showing 2-3 random movies at once. Click to select your choice, then watch or get new options. Perfect for when you can't decide! - ⚡ Blazing Fast Performance:
Complete performance overhaul - pages now load instantly. Anime/TV libraries that took 30+ seconds now load in under 1 second. - 🔐 Enhanced Security:
Strengthened JWT authentication with proper signature verification, secure secret key generation, issuer/audience claims, and protection against token spoofing. - 🖼️ Smart Actor Images:
Actor photos now lazy-load from Wikipedia with multiple fallbacks. Page loads fast, images appear progressively. - 🎥 Async Trailer Loading:
Trailer URLs load in the background - no more waiting for YouTube searches to complete before seeing your movie.
- Donation Support:
Added donation buttons (Buy Me a Coffee, Ko-fi) integrated seamlessly into the interface with matching project theme and smooth animations. - Enhanced User Experience:
Coffee steam and heart pulse animations on hover for donation buttons provide delightful micro-interactions. - Responsive Design:
Donation buttons adapt perfectly to mobile and desktop layouts while maintaining the elegant glass morphism aesthetic.
- Enhanced Plex Match Actions:
Direct integration with Plex functionality including "Add to Watchlist", "Mark as Watched", and "Open in Plex" buttons. - Real-time Match Notifications:
Instant popup notifications when new matches are found with auto-polling and dismissible alerts. - Enriched Match Display:
Movie posters, summaries, and action buttons in beautifully designed match cards. - Backend API Extensions:
New watchlist and watch tracking endpoints with PostgreSQL persistence. - Enhanced UX:
Smart button states, visual feedback, and comprehensive error handling throughout.
- Plex Match Feature:
Tinder-style movie matching for group viewing decisions with real-time collaboration. - Group Swiping:
Create or join match rooms with friends and family to find movies everyone wants to watch. - Optimized Performance:
Ultra-fast movie and poster loading with intelligent preloading and caching systems. - Real-time Matching:
Instant match detection when users like the same movies with beautiful match displays. - Session Management:
Persistent room sessions with participant tracking and room expiration handling. - FastAPI Backend Integration:
Seamless integration with plex-backend for match data persistence and user management. - Mobile-First Design:
Fully responsive design optimized for touch devices with swipe animations.
- Hybrid Authentication System:
Supports both environment variable configuration (backward compatible) and web-based Plex token authentication. - Seamless Integration:
Automatically handles JWT authentication with external like/dislike/watch backend services. - Settings Management:
Built-in settings modal allows users to securely manage their Plex tokens when not using environment variables. - Enhanced UI/UX:
Settings button repositioned next to dropdown as elegant icon-only design; fixed blur overlay gaps for seamless full-screen coverage; improved responsive design for all devices; added donation buttons for supporting the project. - Bearer Token API:
API requests use Bearer token authentication when required for enhanced security. - Improved Security:
Plex tokens are validated server-side and JWT tokens are issued for secure API access to external services. - Support the Project:
Easy access to donation links (Buy Me a Coffee, Ko-fi) integrated seamlessly into the interface. - Backward Compatibility:
Fully compatible with existing Docker deployments using environment variables.
- Enhanced Button Layout:
Trailer button is now positioned alongside "Watch on Plex" and "Suggest Another" buttons for better user experience. - Consistent Plex Theming:
Trailer button now uses the same brown/gold Plex color scheme as the rest of the interface. - Improved UI Consistency:
All action buttons now follow the same design language and hover effects.
- Modern UI Overhaul:
Complete visual redesign with glass morphism effects, modern typography (Inter + Poppins fonts), and enhanced animations. - Watch Count Tracking:
Track how many users clicked "Watch on Plex" for each item with an eye icon counter. - Enhanced Cast Section:
Modern grid layout with glass cards, improved hover effects, and better responsive design. - Improved Interactive Elements:
Better buttons with gradient effects, shimmer animations, and consistent Plex theming. - GitHub Integration:
Quick access to the project repository via a GitHub icon in the top-left corner. - External Trailer Support:
Watch trailers directly from YouTube/internet sources instead of Plex-hosted trailers. - Enhanced Typography:
Gradient text effects for titles and improved readability throughout.
- Plex Poster Proxy:
Poster images are now always visible, even when the app is hosted behind a Cloudflare Tunnel or reverse proxy. Posters are fetched from your Plex server by the Flask backend and served to the frontend, so they are accessible from anywhere. - Version bump:
Updated version to 1.3.2
- Like/Dislike Functionality:
Users can now like or dislike movies and shows.- Like/Dislike counts are displayed and update in real time.
- Dislike Support:
Dislike button and count added. - JWT Authentication:
All like/dislike actions require a valid JWT token. - UI Cleanup:
Like/Dislike buttons no longer display emojis, for a cleaner look. - Frontend User ID:
Each user gets a unique, persistent ID stored in their browser. JWTs are generated server-side using this ID as thesubclaim. - No Secret in Frontend:
JWT secrets are never exposed to the frontend. All JWTs are issued by the backend.
- Hybrid Authentication System - supports both environment variables and web-based Plex token configuration
- Automatic JWT Integration - seamlessly handles authentication with external backend services
- Built-in Settings Management - configure Plex tokens directly in the web interface (when not using environment variables)
- Enhanced UI/UX - icon-only settings button positioned next to dropdown, improved blur overlay coverage
- Plex Match Feature - Tinder-style movie matching for group viewing decisions with real-time collaboration
- Suggests a random unwatched movie, show, anime, or other video from your Plex library
- Modern glass morphism UI with enhanced visual effects and animations
- Posters are always visible (even when hosted behind a tunnel), thanks to backend proxying
- Shows poster and summary with beautiful card designs and gradient effects
- Enhanced cast section with modern grid layout and interactive cards
- Displays top cast with images (tries Plex, IMDB, AniList, Wikipedia, then fallback)
- Links to trailer and direct "Watch on Plex"
- External trailer integration with YouTube/internet sources for better accessibility
- Watch count tracking displays how many users clicked "Watch on Plex" for each item
- GitHub integration with quick access to project repository
- "Suggest Another" button with modern styling keeps your library selection
- Custom dropdown menu with Plex theming and smooth animations
- Dropdown menu to select any video library (Movies, TV, Anime, etc.)
- Fully responsive design optimized for mobile, tablet, and desktop
- Like/Dislike buttons with real-time counts and modern icons
- Professional typography using Inter and Poppins fonts
- Bearer token API security for authenticated requests to external services
PLEX_URL: Your Plex server URL (e.g.http://192.168.1.100:32400) - RequiredPLEX_TOKEN: Your Plex authentication token - Optional (can be set via web interface)PLEX_LIBRARY: Default Plex library to suggest from (default: "Movies")JWT_SECRET_KEY: Secret key for JWT token signing (default provided, change in production)BACKEND_API_URL: URL for the plex-backend service for plex match functionality (default: "https://plex-like.satrawi.cc")
Note: When PLEX_TOKEN is provided as an environment variable, the app will use it directly and skip the web-based authentication prompt. The app will still obtain JWT tokens for external API integrations (like like/dislike/watch functionality and plex matching) as needed.
docker run -d -p 5000:5000 \
-e PLEX_URL="http://your-plex-server:32400" \
-e PLEX_TOKEN="your-plex-token" \
-e JWT_SECRET_KEY="your-secure-secret-key" \
theinfamoustoto/plex-suggester:latestNote: When PLEX_TOKEN is provided, the app will use it directly and users won't be prompted for authentication. The app will still handle JWT authentication for external service integrations automatically.
Create a docker-compose.yml file:
version: "3.8"
services:
plex-suggester:
image: theinfamoustoto/plex-suggester:latest
container_name: plex-suggester
ports:
- "5000:5000"
environment:
PLEX_URL: "http://your-plex-server:32400"
PLEX_TOKEN: "your-plex-token" # Recommended for Docker deployments
PLEX_LIBRARY: "Movies"
JWT_SECRET_KEY: "change-this-secret-key-in-production"
restart: unless-stoppedThen start the service:
docker compose up -dImportant: Make sure to change the JWT_SECRET_KEY to a secure random value in production.
When you first access the application, you'll be prompted to enter your Plex token. Here's how to find it:
-
Quick Method (via Plex Web):
- Open Plex in your web browser
- Navigate to any movie or show
- Click the "..." menu and select "Get Info"
- Click "View XML" at the bottom
- Look for
X-Plex-Tokenin the URL
-
Alternative Methods:
- Visit the official Plex support guide
- Use browser developer tools to inspect network requests to your Plex server
-
Settings Management:
- Once entered, your token is stored securely in your browser
- Use the Settings button in the app to update or clear your token
- Tokens are validated against your Plex server before being accepted
-
Clone the repository:
git clone https://github.com/theinfamoustoto/plex-suggester.git cd plex-suggester -
Install dependencies:
pip install -r requirements.txt
-
Set environment variables:
export PLEX_URL="http://your-plex-server:32400" export JWT_SECRET_KEY="your-secure-secret-key" # PLEX_TOKEN is optional - you can set it via the web interface # export PLEX_TOKEN="your-plex-token" export PLEX_LIBRARY="Movies"
-
Run the app:
python app.py
The app will be available at http://localhost:5000.
The provided Dockerfile uses Python 3.11-slim and runs the app with Gunicorn for production readiness.
app.py: Main Flask application.requirements.txt: Python dependencies.templates/: HTML templates for the web UI.Dockerfile: Docker configuration.
- Connects to your Plex server using the provided URL and token.
- Fetches all video libraries (Movies, TV, Anime, etc.).
- Picks a random unwatched item from the selected library and displays its details.
- How it Works section updated to reflect modern UI and enhanced features
- Like/Dislike/Watch API with comprehensive tracking capabilities
- Enhanced visual design with glass morphism and modern animations
- Always provides fallback images for cast and posters with Plex-themed placeholders
- Allows refreshing for new suggestions while keeping library selection
- Real-time engagement tracking with like, dislike, and watch counts
- Secure JWT authentication for all user interactions
- Modern responsive design that works beautifully on all devices
- Like a movie:
POST /like/<movie_id> - Unlike a movie:
DELETE /like/<movie_id> - Dislike a movie:
POST /dislike/<movie_id> - Remove dislike:
DELETE /dislike/<movie_id> - Track watch:
POST /watch/<movie_id> - Get like count:
GET /like-count/<movie_id> - Get dislike count:
GET /dislike-count/<movie_id> - Get watch count:
GET /watch-count/<movie_id>
The Plex Match feature provides a Tinder-style swipe interface for group movie selection. Rooms sync globally via the backend API.
Room Management:
- Create room:
POST /api/match/create- Create a new room with 6-character code{ "name": "Movie Night", "username": "Alice" } - List rooms:
GET /api/match/rooms- List all active public rooms - Join by code:
POST /api/match/join- Join room using 6-character code{ "room_code": "CFU43W", "username": "Bob" } - Join by ID:
POST /api/match/join-by-id- Join room using room ID - Room state:
GET /api/match/state/{room_id}- Get participants, swipes, matches
Movie Swiping:
- Record swipe:
POST /api/match/swipe- Record like/pass/super{ "room_id": "abc123", "username": "Alice", "movie_id": "1234", "movie_title": "Dune", "movie_year": 2024, "action": "like" } - Rejoin room:
POST /api/match/rejoin- Rejoin a room with existing user ID
How Plex Match Works:
- Create a room and share the 6-character code with friends
- Friends join from any deployment using the room code
- Swipe through movies: drag right to like, left to pass
- Movies liked by multiple participants become "matches"
- Celebrate matches with full-screen animations!
- Rooms automatically expire after 24 hours
Keyboard Shortcuts:
→orD- Like movie←orA- Pass movie↑orW- Super like movie
The Plex Match feature integrates with the separate plex-backend service:
- Authentication: Uses the same JWT system as like/dislike features
- Data Storage: Room and swipe data stored in PostgreSQL backend
- Real-time Sync: Multiple users can swipe simultaneously
- Cross-Device: Works on mobile, tablet, and desktop
- Backend URL: Configure via
BACKEND_API_URLenvironment variable
- Ensure your Plex server is accessible from where you run the app (the app must be able to reach Plex).
- Double-check your Plex token and library name.
- If posters are not visible, ensure the backend can reach your Plex server.
- Check logs for errors if the app fails to connect or display items.
- For like/dislike/watch functionality: If these features return 401 errors, ensure that:
- Your Plex token is valid and can authenticate with the external backend
- The JWT tokens are being obtained correctly (check browser console for authentication messages)
If you find Plex Movie Suggester useful, consider supporting its development:
Your support helps maintain and improve this project!
MIT License. See LICENSE for details.
Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes.
This project is inspired by the need for a simple, user-friendly way to discover new content in Plex libraries. Thanks to the Plex API for making this possible.
For any questions or feedback, please open an issue or contact me on GitHub.
This project was created by [theinfamoustoto]
