starred/audiobookshelf
1
0
Fork 0
mirror of https://github.com/advplyr/audiobookshelf.git synced 2026-05-30 23:40:40 +02:00
Code Issues 1.0k Packages Projects Releases 10 Wiki Activity

[PR #4452] [CLOSED] Add book ratings #4257

New Issue
Closed
opened 2026-04-25 00:19:01 +02:00 by adam · 0 comments
adam commented 2026-04-25 00:19:01 +02:00
Owner
Copy Link
Copy Source

📋 Pull Request Information

Original PR: https://github.com/advplyr/audiobookshelf/pull/4452
Author: @peter1490
Created: 7/1/2025
Status: ❌ Closed

Base: master ← Head: add-book-ratings

📝 Commits (8)

  • 7c3504f Added server wide audiobook rating (admin only)
  • 3bfd9f4 Added User personal audiobook rating
  • dba5757 Added Explicit user book rating + Community rating
  • ab00b30 provider rating editable + fix config settings
  • f7bf970 Merge into one migration file
  • db34ddd Merge branch 'advplyr:master' into add-book-ratings
  • 89bd541 Added frontend + backend tests
  • 9a94b9b Fix to rate only books

📊 Changes

35 files changed (+19789 additions, -12529 deletions)

View changed files

📝 Dockerfile (+1 -1)
📝 client/components/cards/LazyBookCard.vue (+2 -2)
📝 client/components/modals/item/EditModal.vue (+18 -4)
📝 client/components/modals/item/tabs/Details.vue (+1 -0)
📝 client/components/modals/item/tabs/Match.vue (+31 -3)
➕ client/components/ui/FlameIcon.vue (+32 -0)
➕ client/components/ui/RatingInput.vue (+114 -0)
📝 client/components/widgets/BookDetailsEdit.vue (+34 -9)
📝 client/cypress.config.js (+4 -4)
📝 client/cypress/tests/components/cards/LazyBookCard.cy.js (+3 -4)
➕ client/cypress/tests/components/ui/RatingInput.cy.js (+88 -0)
📝 client/package-lock.json (+18311 -12410)
📝 client/package.json (+11 -4)
📝 client/pages/config/index.vue (+43 -0)
📝 client/pages/item/_id/index.vue (+163 -38)
📝 client/plugins/init.client.js (+45 -31)
➕ client/static/audible.svg (+2 -0)
➕ client/static/flame-icon.svg (+1 -0)
📝 client/store/libraries.js (+12 -1)
📝 client/strings/en-us.json (+10 -1)

...and 15 more files

📄 Description

Brief summary

This PR introduces a comprehensive book rating system to Audiobookshelf. Users can now rate books on a 1-5 star scale, give an explicit rating and view community average ratings for both rating types. The system also supports fetching ratings from external providers like Audible during metadata matching.

Which issue is fixed?

Here are the enhancements requests:

In-depth Description

This feature adds a full-stack implementation for book ratings.

Backend:

  • Database: New tables userBookRatings and userBookExplicitRatings have been added to store user-specific ratings. The books table has been extended to store ratings from external metadata providers.
  • API: New endpoints (/rate and /rate-explicit) have been added to the API to submit and update ratings. The /item/:id endpoint now returns rating information.
  • Controllers: The LibraryItemController has been updated to handle the logic for saving user ratings, calculating community averages, and fetching rating data.
  • Settings: New server settings have been added to allow administrators to enable or disable the simple rating system, explicit rating and community ratings.
  • Scanner: The metadata scanner has been updated to pull in ratings from matched providers.

Frontend:

  • Rating Component: A new reusable RatingInput.vue component has been created for capturing star (or flame) ratings.
  • Item Page: The book details page (/item/:id) now displays the user's rating, the community rating, and an explicit rating. Users can add or update their rating directly from this page.
  • Settings Page: The admin's settings page has been updated with toggles to manage the new rating features.
  • Edit Modals: The metadata editing modals have been updated to include and preserve provider's rating information.
  • Developer Experience: The client-side development setup has been migrated from Webpack to Vite for a faster development experience, and the necessary Cypress configuration has been updated.

This solution provides a robust and configurable way to handle book ratings, enhancing the user experience by providing more metadata and interaction possibilities with their library items.

How have you tested this?

The changes have been tested both manually and with automated tests.

Automated tests:

  • Unit tests have been added for the new backend logic in LibraryItemController.test.js.
  • Cypress component tests have been created for the new RatingInput.vue component to ensure it functions correctly.

Manual testing steps:

  1. Navigated to Settings > General and enabled "Enable Ratings", "Enable Community Ratings", and "Enable Explicit Ratings".
  2. Opened a book details page and verified the new rating section is visible.
  3. Clicked on the stars to add a personal rating and confirmed it was saved and displayed correctly after a page refresh.
  4. Clicked the flames to add a personal explicit rating and confirmed it was saved and displayed correctly after a page refresh.
  5. Observed the community rating values (from rating with another user).
  6. Used the "Match" feature on a book and checked if a rating was populated from the metadata provider.
  7. Edited a book's details and ensured the rating information was not lost.

Screenshots

Item Page:

With all settings enabled (rating + community rating + explicit rating):
image

With just rating enabled + explicit rating enabled:
image

With just the simple rating system enabled:
image

With just the explicit rating enabled:
image

Matchin Tool Tab:

When the provider has a rating value:
image

Edit Details Tab:

image

Settings Page:

By default just the simple rating system is enabled:
image

🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/advplyr/audiobookshelf/pull/4452 **Author:** [@peter1490](https://github.com/peter1490) **Created:** 7/1/2025 **Status:** ❌ Closed **Base:** `master` ← **Head:** `add-book-ratings` --- ### 📝 Commits (8) - [`7c3504f`](https://github.com/advplyr/audiobookshelf/commit/7c3504fe2b2af2d4b7a387d9af5fb1ccafc43a70) Added server wide audiobook rating (admin only) - [`3bfd9f4`](https://github.com/advplyr/audiobookshelf/commit/3bfd9f419c917103f6b92b7b13ca11535273683f) Added User personal audiobook rating - [`dba5757`](https://github.com/advplyr/audiobookshelf/commit/dba575761ec3a824842a6229674efd83d9107557) Added Explicit user book rating + Community rating - [`ab00b30`](https://github.com/advplyr/audiobookshelf/commit/ab00b306e2e3cf6f27b59e6eb6b69819758e635f) provider rating editable + fix config settings - [`f7bf970`](https://github.com/advplyr/audiobookshelf/commit/f7bf970938a23d40514b01e49e859d2a65fa86e1) Merge into one migration file - [`db34ddd`](https://github.com/advplyr/audiobookshelf/commit/db34ddd0a9a4d3527927812d54da863b2ec27360) Merge branch 'advplyr:master' into add-book-ratings - [`89bd541`](https://github.com/advplyr/audiobookshelf/commit/89bd541247c27eb2ffdd8577a573d83f2961a971) Added frontend + backend tests - [`9a94b9b`](https://github.com/advplyr/audiobookshelf/commit/9a94b9b0c31d13315f0331113dc8a1c171500c14) Fix to rate only books ### 📊 Changes **35 files changed** (+19789 additions, -12529 deletions) <details> <summary>View changed files</summary> 📝 `Dockerfile` (+1 -1) 📝 `client/components/cards/LazyBookCard.vue` (+2 -2) 📝 `client/components/modals/item/EditModal.vue` (+18 -4) 📝 `client/components/modals/item/tabs/Details.vue` (+1 -0) 📝 `client/components/modals/item/tabs/Match.vue` (+31 -3) ➕ `client/components/ui/FlameIcon.vue` (+32 -0) ➕ `client/components/ui/RatingInput.vue` (+114 -0) 📝 `client/components/widgets/BookDetailsEdit.vue` (+34 -9) 📝 `client/cypress.config.js` (+4 -4) 📝 `client/cypress/tests/components/cards/LazyBookCard.cy.js` (+3 -4) ➕ `client/cypress/tests/components/ui/RatingInput.cy.js` (+88 -0) 📝 `client/package-lock.json` (+18311 -12410) 📝 `client/package.json` (+11 -4) 📝 `client/pages/config/index.vue` (+43 -0) 📝 `client/pages/item/_id/index.vue` (+163 -38) 📝 `client/plugins/init.client.js` (+45 -31) ➕ `client/static/audible.svg` (+2 -0) ➕ `client/static/flame-icon.svg` (+1 -0) 📝 `client/store/libraries.js` (+12 -1) 📝 `client/strings/en-us.json` (+10 -1) _...and 15 more files_ </details> ### 📄 Description <!-- For Work In Progress Pull Requests, please use the Draft PR feature, see https://github.blog/2019-02-14-introducing-draft-pull-requests/ for further details. If you do not follow this template, the PR may be closed without review. Please ensure all checks pass. If you are a new contributor, the workflows will need to be manually approved before they run. --> ## Brief summary This PR introduces a comprehensive book rating system to Audiobookshelf. Users can now rate books on a 1-5 star scale, give an explicit rating and view community average ratings for both rating types. The system also supports fetching ratings from external providers like Audible during metadata matching. ## Which issue is fixed? Here are the enhancements requests: * #4375 * #1184 * #901 * #701 ## In-depth Description This feature adds a full-stack implementation for book ratings. **Backend:** * **Database:** New tables `userBookRatings` and `userBookExplicitRatings` have been added to store user-specific ratings. The `books` table has been extended to store ratings from external metadata providers. * **API:** New endpoints (`/rate` and `/rate-explicit`) have been added to the API to submit and update ratings. The `/item/:id` endpoint now returns rating information. * **Controllers:** The `LibraryItemController` has been updated to handle the logic for saving user ratings, calculating community averages, and fetching rating data. * **Settings:** New server settings have been added to allow administrators to enable or disable the simple rating system, explicit rating and community ratings. * **Scanner:** The metadata scanner has been updated to pull in ratings from matched providers. **Frontend:** * **Rating Component:** A new reusable `RatingInput.vue` component has been created for capturing star (or flame) ratings. * **Item Page:** The book details page (`/item/:id`) now displays the user's rating, the community rating, and an explicit rating. Users can add or update their rating directly from this page. * **Settings Page:** The admin's settings page has been updated with toggles to manage the new rating features. * **Edit Modals:** The metadata editing modals have been updated to include and preserve provider's rating information. * **Developer Experience:** The client-side development setup has been migrated from Webpack to Vite for a faster development experience, and the necessary Cypress configuration has been updated. This solution provides a robust and configurable way to handle book ratings, enhancing the user experience by providing more metadata and interaction possibilities with their library items. ## How have you tested this? The changes have been tested both manually and with automated tests. **Automated tests:** * Unit tests have been added for the new backend logic in `LibraryItemController.test.js`. * Cypress component tests have been created for the new `RatingInput.vue` component to ensure it functions correctly. **Manual testing steps:** 1. Navigated to `Settings > General` and enabled "Enable Ratings", "Enable Community Ratings", and "Enable Explicit Ratings". 2. Opened a book details page and verified the new rating section is visible. 3. Clicked on the stars to add a personal rating and confirmed it was saved and displayed correctly after a page refresh. 4. Clicked the flames to add a personal explicit rating and confirmed it was saved and displayed correctly after a page refresh. 5. Observed the community rating values (from rating with another user). 6. Used the "Match" feature on a book and checked if a rating was populated from the metadata provider. 7. Edited a book's details and ensured the rating information was not lost. ## Screenshots <!-- Please add screenshots of the new UI components here. For example: rating section on item page, and new settings in the admin panel. --> **Item Page:** With all settings enabled (rating + community rating + explicit rating): <img width="1332" alt="image" src="https://github.com/user-attachments/assets/605a93fc-cf1e-4d3f-8826-190dcd417c6f" /> With just rating enabled + explicit rating enabled: <img width="1341" alt="image" src="https://github.com/user-attachments/assets/2e3c906b-f642-41ef-8c0b-c7694e779718" /> With just the simple rating system enabled: <img width="1329" alt="image" src="https://github.com/user-attachments/assets/5b3ea909-f267-4a86-b2c9-2e9c6d6bc9aa" /> With just the explicit rating enabled: <img width="1342" alt="image" src="https://github.com/user-attachments/assets/1044165f-022e-49a1-802a-c7db2f620a9c" /> **Matchin Tool Tab:** When the provider has a rating value: <img width="995" alt="image" src="https://github.com/user-attachments/assets/f5d24264-bc8f-4bbd-9e80-be9e1aa7b4ca" /> **Edit Details Tab:** <img width="874" alt="image" src="https://github.com/user-attachments/assets/b419f276-de2e-4e7a-a243-2dec311e9daa" /> **Settings Page:** By default just the simple rating system is enabled: <img width="1409" alt="image" src="https://github.com/user-attachments/assets/65266e0a-3474-405d-b70c-e81d359b5d0a" /> --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
adam added the pull-request label 2026-04-25 00:19:01 +02:00
adam closed this issue 2026-04-25 00:19:02 +02:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
authentication
backlog
bug
chapter editor
config-issue
ebooks
encoding/embedding
enhancement
help wanted
listening sessions & progress
planned
possible plugin
progress sync
pull-request
Mirrored from GitHub Pull Request
 sorting/filtering/searching
unable to reproduce
upload
users & permissions
waiting
No Label pull-request
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam (Adam Melkus)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/audiobookshelf#4257
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?