Jellyfin Ratings Plugin

February 18, 2026 · View on GitHub

A professional, feature-rich rating system for Jellyfin media server with performance-optimized card overlays, a built-in media request system, deletion request workflow, user ban management, and real-time new media notifications.

Issues & Support: https://github.com/K3ntas/jellyfin-plugin-ratings/issues

Screenshots

Rating Detail Page

Interactive 1-10 star rating system displayed below the movie title

Hover over stars to see detailed ratings from all users

Rated Media

Your rating is saved and displayed with highlighted stars

Card Overlays

Rating badges automatically appear on media thumbnails throughout Jellyfin

Netflix-Style View

Netflix-style genre rows Optional Netflix-style view with horizontal genre rows and smooth scrolling

New Media Notifications

New media notification popup Real-time notifications when new movies or episodes are added to your library

Latest Media Button

Latest Media dropdown Quick access to your 50 most recently added movies and series with time-ago indicators

Live Chat System

Live chat interface Real-time public chat with Messenger-style bubbles, emoji support, and GIF integration

Private Messages & Notifications

Chat notification badge Private messaging - type /username to start a DM. Badge shows unread conversation count.

Note: All features are optional and can be enabled/disabled through the plugin settings in the Jellyfin Dashboard.

Ban durations: 1 day, 1 week, 1 month, or permanent
Two ban types: Media request bans and deletion request bans (independent)
Ban management: User dropdown and duration selector in each admin tab
User notification: Banned users see a notice with expiry info instead of the request form or deletion buttons
Auto-expiry: Timed bans expire automatically, permanent bans require manual lift

Features

Star Rating System

1-10 star rating for all media types (movies, TV shows, music, etc.)
Interactive UI with smooth hover effects and instant feedback
Visual indicators showing your rating and average community rating
Persistent ratings saved per-user across all devices

User Ratings Display

Hover popup showing detailed ratings from all users
Username display with individual ratings (e.g., "John: 8/10")
Rating statistics including average rating and total number of ratings
Privacy-aware - only shows ratings, not full user profiles

Media Card Overlays

Rating badges displayed on media cards (e.g., "7.5")
Lazy loading using IntersectionObserver for optimal performance
Smart caching prevents duplicate API requests
Optimized for large libraries (tested with 15TB+ media collections)
Non-intrusive design that doesn't interfere with Jellyfin's UI

New Media Notifications

Real-time notifications when new movies, series, or episodes are added
Beautiful popup UI with media poster, title, and year
Episode grouping - multiple episodes show as single notification (e.g., "Episodes 4-8")
Smart timing - 2-10 minute random delay between notifications to avoid spam
24-hour duplicate prevention - same item won't notify twice
Toggle control - users can enable/disable notifications via header toggle
Works during playback - notifications appear even in fullscreen mode
Fire TV/Android TV support - native app notifications via DisplayMessage

Latest Media Button

Replaces Sync Play - button in header shows your 50 most recently added media
Compact dropdown - scrollable list with thumbnail, title, year, and type badge
Type badges - Movie (blue), Series (green), Anime (purple), Other (gray)
Time-ago indicator - shows when media was added (e.g., "5 min ago", "2 d ago")
Clean titles - automatically removes IMDB IDs from display
Click to navigate - go directly to media detail page
Responsive design - inherits Jellyfin's native header button behavior
Configurable - can be disabled in plugin settings

Media Request System

Request Button - Animated "Request Media" button in the header
User Features:
- Submit requests for Movies, TV Series, or Anime
- Add notes (e.g., "Season 2", "Need ASAP")
- Track request status (Pending → Processing → Done)
- See timestamps for when requested and completed
- "Watch Now" button when request is fulfilled with link
- Multi-language support (EN/LT)
Admin Features:
- Notification badge showing pending request count (includes deletion requests)
- Tabbed interface: Create Request, Manage Media Requests, Deletion Requests
- Pending count badges on each admin tab
- One-click status updates (Pending/Processing/Done)
- Add media link when marking as Done
- Delete requests permanently
- See request and completion timestamps
Mobile Responsive - Card layout and dropdown selector on mobile devices
Multi-user Support - Cache clears on logout/account switch

Deletion Request System

Two deletion types: "Request to delete request" (cancel pending/processing) and "Request to delete media" (remove fulfilled media)
User Features:
- Request deletion directly from "Your Requests" list
- See rejection status with clickable reason popup showing all rejection messages
- 3-request limit per media item to prevent spam
Admin Features:
- Dedicated "Deletion Requests" tab with all pending and resolved requests
- Schedule deletion: ~1 hour, 1 day, 1 week, or 1 month delay
- Reject with custom reason via dark-themed modal
- Integrates with existing scheduled deletion service
Rejection Reasons - Custom dark-themed modal for admin input, popup display for users with admin name and date

User Ban System

Ban users from submitting media requests or deletion requests
Ban durations: 1 day, 1 week, 1 month, or permanent
Independent ban types: Media request bans and deletion request bans managed separately
Admin UI: Ban section in each admin tab with user dropdown (populated from request history) and duration selector
Banned users list: Shows username, expiry date, and who issued the ban with one-click unban
User enforcement: Banned users see a styled notice with expiry info instead of the request form or deletion buttons
Backend enforcement: API rejects requests from banned users with clear error messages
Auto-expiry: Timed bans expire automatically without admin intervention

Live Chat System

Public chat - real-time messaging for all authenticated users
Private messages (DMs) - secure direct messaging between users (type /username to start)
Messenger-style bubbles - own messages on right (blue), others on left (grey with avatar)
Emoji picker - full emoji support with categorized picker
GIF integration - Klipy-powered GIF search and sharing
Smart auto-scroll - doesn't interrupt reading; shows jump-to-bottom button
Tab system - switch between public chat and DM conversations
User autocomplete - type / followed by username to search and start DM
Notification badges - shows unread DM conversation count on chat button
Background polling - notifications work even when chat is closed
Online users - see who's currently active in chat
Admin moderation - admins can delete any message
Multi-language - 16 languages supported

Performance Optimized

IntersectionObserver loads ratings only for visible cards
Request caching eliminates duplicate API calls
Efficient DOM handling prevents UI lag
Minimal server load even with thousands of media items
Silent logging - server only logs errors, not routine operations

Installation

Add Plugin Repository
- Go to Jellyfin Dashboard → Plugins → Repositories
- Add repository URL: https://raw.githubusercontent.com/K3ntas/jellyfin-plugin-ratings/main/manifest.json
Install Plugin
- Go to Plugins → Catalog
- Find "Ratings" and click Install
- Restart Jellyfin server
Automatic Setup
- Plugin automatically injects rating UI on detail pages
- Request Media button appears in the header
- Notification toggle appears near the search field
- No manual configuration required
- Works immediately after server restart

Usage

Rating Media

Open any movie, TV show, or media item
Find the rating stars below the title/logo
Click a star (1-10) to submit your rating
Your rating is saved immediately

Viewing Ratings

Your rating: Displayed with highlighted stars
Average rating: Shown as "X.X/10" with total count
All user ratings: Hover over stars to see detailed popup
Card badges: Rating badges appear on media thumbnails automatically

New Media Notifications

Notifications appear automatically when new content is added
Use the toggle switch in the header to enable/disable notifications
Episode notifications show series name with season (e.g., "SPOOKS S01 - Episodes 4-8")
Click notification to navigate to the media item

Requesting Media (Users)

Click the "Request Media" button in the header
Fill in the media title (required)
Select the type (Movie, TV Series, Anime, etc.)
Add any additional notes (season number, year, etc.)
Click "Submit Request"
Track your requests in the "Your Requests" section

Managing Requests (Admins)

Click the "Request Media" button (shows pending count)
Use tabs: Manage Media Requests and Deletion Requests (with pending badges)
View all user requests with details
Update status: Pending → Processing → Done
When marking as Done, paste the media URL first
Users will see a "Watch Now" button linking to the media
Delete requests using the trash button

Deletion Requests (Users)

From "Your Requests", click "Request to delete media" (for fulfilled) or "Request to delete request" (for pending)
Track deletion status - click on "REJECTED" to see all rejection reasons with admin comments
Maximum 3 deletion requests per media item

Deletion Requests (Admins)

Open the Deletion Requests tab (badge shows pending count)
For media deletion: choose schedule (~1h, 1 day, 1 week, 1 month)
For request deletion: approve to remove the original request
Reject with a custom reason using the styled modal

Banning Users (Admins)

Scroll to the Banned Users section in any admin tab
Select a user from the dropdown (shows users who have submitted requests)
Choose duration: 1 day, 1 week, 1 month, or permanent
Click Ban User - the user will see a ban notice instead of the request form
Click Unban next to any banned user to lift the ban immediately

Using Live Chat

Click the chat icon in the header (shows notification badge if you have unread DMs)
Public chat: Type a message and press Enter or click Send
Send GIF: Click the GIF button, search, and click a GIF to send
Send emoji: Click the emoji button and select an emoji
Switch conversations: Use tabs at the top to switch between public chat and DMs
Close chat: Click the X button or click outside the chat panel

Private Messages (DMs)

To start a private conversation with another user:

Type / followed by username - e.g., /john or /admin in the message box
Select from dropdown - A list of matching users appears as you type
Click on user - Opens a new DM tab for that conversation
Send your message - Messages in DM tabs go only to that user
Notification badge - Shows count of conversations with unread messages (not total messages)
Close tab - Click the X on any DM tab to close that conversation

You can also click on a user's avatar in the public chat to start a DM with them.

Technical Details

Requirements

Jellyfin: 10.11.0 or higher
.NET: 9.0
Browser: Modern browser with JavaScript enabled

Architecture

Backend: ASP.NET Core controller with RESTful API
Frontend: Vanilla JavaScript (no dependencies)
Storage: JSON-based file storage in plugin data directory
Authentication: Jellyfin's built-in authentication system
Notifications: Library event subscription with queue-based delivery

API Endpoints

Ratings

POST /Ratings/Items/{itemId}/Rating?rating={1-10} - Submit rating
GET /Ratings/Items/{itemId}/Stats - Get rating statistics
GET /Ratings/Items/{itemId}/DetailedRatings - Get all user ratings
DELETE /Ratings/Items/{itemId}/Rating - Delete your rating

Notifications

GET /Ratings/Notifications?since={ISO8601} - Get notifications since timestamp
POST /Ratings/Notifications/Test - Send test notification (admin only)
GET /Ratings/Config - Get plugin configuration

Media Requests

POST /Ratings/Requests - Create new request
GET /Ratings/Requests - Get all requests
POST /Ratings/Requests/{requestId}/Status?status={status}&mediaLink={url} - Update status
DELETE /Ratings/Requests/{requestId} - Delete request

Deletion Requests

POST /Ratings/DeletionRequests - Create deletion request
GET /Ratings/DeletionRequests - Get all deletion requests
POST /Ratings/DeletionRequests/{requestId}/Action?action={approve|reject} - Admin action with optional delay/reason

User Bans

POST /Ratings/Bans?userId={id}&banType={type}&duration={1d|1w|1m|permanent} - Create ban
GET /Ratings/Bans?banType={type} - Get active bans by type (admin)
GET /Ratings/Bans/Check?banType={type} - Check if current user is banned
DELETE /Ratings/Bans/{banId} - Lift a ban

Live Chat

GET /Ratings/Chat/Messages?since={ISO8601} - Get public chat messages
POST /Ratings/Chat/Messages - Send public chat message
DELETE /Ratings/Chat/Messages/{id} - Delete message (admin or sender)
GET /Ratings/Chat/Users/Online - Get online users
POST /Ratings/Chat/Heartbeat - Update online presence

Private Messages (DMs)

GET /Ratings/Chat/DM/Users?query={search} - Search users for DM autocomplete
GET /Ratings/Chat/DM/Conversations - Get user's DM threads with unread counts
GET /Ratings/Chat/DM/{userId}/Messages - Get messages with specific user
POST /Ratings/Chat/DM/{userId}/Messages - Send DM to user
DELETE /Ratings/Chat/DM/Messages/{id} - Delete own DM

Performance Characteristics

Initial load: ~1.5 seconds delay for page stability
Per-card overhead: Single cached API request per unique item
Memory usage: Minimal (~1MB for 1000 cached ratings)
Server load: Negligible (lazy loading prevents request storms)
Notification polling: 10-second intervals, silent operation

Development

Building from Source

git clone https://github.com/K3ntas/jellyfin-plugin-ratings.git
cd jellyfin-plugin-ratings
dotnet build -c Release

Project Structure

├── Api/                    # API controllers
│   ├── RatingsController.cs
│   └── ChatController.cs   # Chat and DM endpoints
├── Data/                   # Data layer
│   └── RatingsRepository.cs
├── Models/                 # Data models
│   ├── Rating.cs
│   ├── MediaRequest.cs
│   ├── DeletionRequest.cs
│   ├── DeletionRequestDto.cs
│   ├── UserBan.cs
│   ├── NewMediaNotification.cs
│   ├── ChatMessage.cs
│   ├── ChatMessageDto.cs
│   ├── PrivateMessage.cs
│   └── PrivateMessageDto.cs
├── Web/                    # Frontend assets
│   └── ratings.js         # Main client-side script (~15k lines)
├── Configuration/          # Plugin config pages
├── images/                 # README screenshots
├── NotificationService.cs  # Library event handler
├── DeletionService.cs      # Scheduled deletion background service
└── manifest.json          # Plugin catalog manifest

Messenger-style chat bubbles - own messages on right with blue bubble, others on left with grey bubble and avatar
Chat UI improvements - polished design matching modern chat apps

1.0.294.0 - 1.0.305.0

Private messaging (DM) system - secure direct messaging between users
Tab-based chat UI - switch between public chat and DM conversations
User autocomplete - type / to search and start DM with any user
Smart auto-scroll - doesn't interrupt reading history, shows jump-to-bottom button
Notification badges - shows unread DM conversation count (not message count)
Background polling - notifications work even when chat is closed
GIF picker improvements - closes after selection, better sizing
Chat reliability fixes - avatar loading, scroll behavior, badge visibility

1.0.288.0 - 1.0.293.0

Live chat system - real-time public chat for all authenticated users
Emoji picker - full emoji support with categorized selection
GIF integration - Klipy-powered GIF search and sharing
Online users - see who's currently active in chat
Admin moderation - admins can delete any message
Chat button in header - easy access to chat from anywhere

1.0.274.0

Multi-language localization - 16 languages: English, Spanish, Chinese, Portuguese, Russian, Japanese, German, French, Korean, Italian, Turkish, Polish, Dutch, Arabic, Hindi, Lithuanian
Language selector - dropdown in UI for users to choose their language
Admin default language - admin can set default language for all users

1.0.273.0

Settings redesign - cleaner admin configuration interface
Rating widget repositioning - above detail ribbon with responsive mobile layout
Badge display profiles - resolution-based profiles for customizing rating widget appearance

1.0.253.0

Rating badge display profiles - resolution-based profiles to customize the detail page rating widget appearance
Horizontal/vertical offset - move the rating badge by screen width/height percentage
Badge size adjustment - scale the rating widget up or down by percentage
Hide text option - show stars only, hiding "X/10 - N ratings" and "Your rating" text
Remove background option - make the rating widget background transparent
Multi-profile system - create multiple profiles for different screen resolution ranges, auto-switches on resize

1.0.252.0

User ban system - admins can ban users from submitting media requests or deletion requests (1 day, 1 week, 1 month, or permanent)
Ban management UI - ban sections in both "Manage Media Requests" and "Deletion Requests" admin tabs with user dropdown and duration selector
Ban enforcement - banned users see a notice with expiry info instead of the request form or deletion buttons
Show all rejection messages - users now see all rejection reasons from admins (not just the latest), clickable with date and admin info
Security audit - verified no hardcoded server addresses or IP addresses in codebase

1.0.251.0

Custom rejection reason modal - replaced browser prompt/alert with styled dark-themed modals for admin input and user viewing
Notification badges on admin tabs - "Manage Media Requests" and "Deletion Requests" tabs show pending count badges
Brighter bell cross lines - disabled notification bell now has more visible, longer red cross lines with glow effect

1.0.250.0

Rejection reasons for deletion requests - admins can provide a reason when rejecting, visible to users
3-request limit per media item for deletion requests (combined total for both types)
Fixed badge vertical alignment in Deletion Requests admin tab
Cleaned up console logging - removed all debug console.log statements, only errors remain

1.0.249.0

Two deletion request types: "Request to delete request" (for pending/processing requests) and "Request to delete media" (for fulfilled requests)
Fixed button always visible - no longer requires GUID extraction from media link
Admin sees different actions per type: Approve for request deletion, schedule options for media deletion
Orange button for request deletion, red button for media deletion

1.0.248.0

Ask to Delete feature - users can request deletion of fulfilled media from their request list
New "Deletion Requests" admin tab to approve/reject deletion requests
Admin can schedule deletion with ~1h, 1 day, 1 week, or 1 month delay
Request badge includes pending deletion request count for admins
EN/LT translations for all new strings

1.0.244.0

Redesigned notification toggle - replaced slide on/off switch with clean bell icon
Disabled state shown with red cross lines overlay instead of toggle switch
Smaller, cleaner look with all responsive positioning preserved