Script for user ratings, community ratings and more

[G1ebel]

Hi everyone, I'm new to GitHub and would like to share something with you. I used the user script by @wrecks-code as a model and started my own little project. Feel free to get in touch if you're interested.

Note

I'm not a developer, and most of the code was written using AI.

Features

• Fetch Goodreads ratings directly from Komga
• Convert Goodreads' 5-star ratings to a 10-point scale
• Search Goodreads by ISBN
• Store Goodreads ratings in Komga metadata
• Calculate average ratings for complete series
• Rate books and series personally on a 1–10 scale
• Store personal ratings directly in Komga metadata
• Display external and personal ratings directly on library covers
• Support books, series, and one-shots
• Display book counts for completed series

---

How It Works

The project consists of two complementary userscripts.

1. Rating Fetching & Personal Rating Script

The first script extends Komga's detail pages with two main features:

• a Fetch Ratings button
• an interactive 1–10 star rating control

On book, series, and one-shot pages, the script detects the current Komga item and retrieves its metadata through the Komga API.

Fetching Goodreads Ratings

Important

Works right now, but unfortunately, user ratings entered manually aren’t displayed for one-shots.

When Fetch Ratings is pressed, the script determines the appropriate source:

• Books: the ISBN is extracted from the Komga page
• One-shots: the ISBN is used for the underlying book
• Series: ratings from the individual books are used to calculate a series average

For books and one-shots, the script searches Goodreads using the ISBN. It then extracts the rating from the Goodreads result and stores it in Komga.
The Goodreads request is routed through a local /api/goodreads/ proxy path, allowing the script to retrieve and parse the Goodreads HTML from within the Komga environment.

Goodreads Rating Conversion

Goodreads ratings use a 5-point scale.

This integration converts them to a 10-point scale:

Goodreads 4.22 → Komga 8.4
Goodreads 4.5 → Komga 9.0
Goodreads 3.78 → Komga 7.6

The conversion is performed by multiplying the Goodreads rating by two.
This allows Goodreads ratings and personal ratings to use the same 1–10 scale throughout Komga.

---

Series Rating Calculation

Series are handled differently from individual books.
When Fetch Ratings is used on a series page, the script retrieves the books belonging to that series and reads their previously stored User Rating metadata links. It then calculates the arithmetic mean of those ratings.

For example:

Book 1: 8.0
Book 2: 8.5
Book 3: 9.0

Series rating: 8.5

The resulting average is stored as a User Rating link on the series itself.
The series average is only calculated when a rating is available for every book returned by the series API.

If a book is missing a User Rating, the calculation is aborted instead of producing a partial average.
This prevents a series rating from being silently calculated from incomplete data.

---

Personal Ratings

The integration also adds a 10-star interactive rating control to Komga detail pages. The stars react to mouse hover and immediately show the selected rating.
The selected rating is stored in Komga as: "Your Rating: 8"

One-Shot Support

One-shots receive special handling because Komga represents them differently from ordinary books.
When a personal rating is assigned to a one-shot, the rating is stored both:

• on the one-shot's series-level metadata
• on the underlying book

The same approach is used when storing Goodreads ratings.
This keeps the rating accessible regardless of which representation of the one-shot is being displayed.

---

2. Rating Display & Library Enhancement Script

The second script focuses on the Komga library interface.
Instead of opening every book or series individually to see its ratings, the script adds compact rating badges directly to the cover cards. User Ratings and Your Rating can both be displayed, if available.
The badges are positioned in opposite bottom corners of the cover, making both ratings visible without taking up significant space.

Completed Series: Book Count

The library enhancement script also modifies the information displayed for completed series.
For series marked as ended, it replaces the standard book-count text with a value based on the series' booksCount and totalBookCount metadata:

X / Y books

For example:

12 / 12 books

A small loading indicator is displayed while the series metadata is being retrieved.
This provides a quick overview of the available versus expected book count directly from the library view.

Some examples

Books view:

Books detail view:

Series view: