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

[Enhancement]: Explicit isFinished status and persistent userMediaProgress in API #3163

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

Originally created by @Quixotic-Limit on GitHub (Dec 30, 2025).

Type of Enhancement

None

Describe the Feature/Enhancement

I am requesting that the Audiobookshelf API provide a consistent and explicit isFinished boolean for all podcast episodes, regardless of whether they have been cleared from the "Continue Listening" queue.

Currently, when an episode is "Marked as Played" or finished naturally, the userMediaProgress object is often removed entirely from the API response. This makes it impossible for external integrations (like Home Assistant) to distinguish between an episode that is brand new and an episode that has been finished.

The request: 1. Ensure the userMediaProgress object (or at least an isFinished flag) remains present in the libraryItem and episode API responses even after an episode is completed. 2. Ensure that "Marking as Played" explicitly sets an isFinished: true flag that is visible via the API, rather than simply deleting the progress record.

Why would this be helpful?

This would greatly enhance the ability to automate playlists and syncing with external platforms. Specifically:

  • Migration Support: Users migrating from other platforms (like Spotify) often bulk "Mark as Played" hundreds of archived episodes. Because the API currently reports these with "No Progress Data" (matching the status of new episodes), automation scripts mistakenly re-add these old archives to "Unplayed" playlists.
  • Integration Reliability: In Home Assistant, logic designed to "add the oldest unplayed episode" fails because it cannot verify if an episode with 0% progress was finished elsewhere or is genuinely new.
  • State Management: It allows 3rd-party dashboards to accurately display "Played" vs "Unplayed" states without needing to guess based on the absence of data.

Future Implementation (Screenshot)

Proposed API Response for a Finished Episode:
"episodes": [
{
"id": "episode_123",
"title": "Argument: 1. Thesis",
"userMediaProgress": {
"isFinished": true,
"progress": 1.0,
"lastUpdate": 1735505152
}
}
]

Current behavior often returns userMediaProgress: null for this state, leading to ambiguity.

Audiobookshelf Server Version

2.32.1 (docker)

Current Implementation (Screenshot)

I was looking at the Podcast Episode List and the API response payload for a specific podcast. Even though episodes were marked as finished in the UI, the API debug logs showed:

isFinished: No Progress Data

Progress: 0

Hidden: False

This lack of distinction in the data payload is the primary driver for this request.

Originally created by @Quixotic-Limit on GitHub (Dec 30, 2025). ### Type of Enhancement None ### Describe the Feature/Enhancement I am requesting that the Audiobookshelf API provide a consistent and explicit isFinished boolean for all podcast episodes, regardless of whether they have been cleared from the "Continue Listening" queue. Currently, when an episode is "Marked as Played" or finished naturally, the userMediaProgress object is often removed entirely from the API response. This makes it impossible for external integrations (like Home Assistant) to distinguish between an episode that is brand new and an episode that has been finished. The request: 1. Ensure the userMediaProgress object (or at least an isFinished flag) remains present in the libraryItem and episode API responses even after an episode is completed. 2. Ensure that "Marking as Played" explicitly sets an isFinished: true flag that is visible via the API, rather than simply deleting the progress record. ### Why would this be helpful? This would greatly enhance the ability to automate playlists and syncing with external platforms. Specifically: - Migration Support: Users migrating from other platforms (like Spotify) often bulk "Mark as Played" hundreds of archived episodes. Because the API currently reports these with "No Progress Data" (matching the status of new episodes), automation scripts mistakenly re-add these old archives to "Unplayed" playlists. - Integration Reliability: In Home Assistant, logic designed to "add the oldest unplayed episode" fails because it cannot verify if an episode with 0% progress was finished elsewhere or is genuinely new. - State Management: It allows 3rd-party dashboards to accurately display "Played" vs "Unplayed" states without needing to guess based on the absence of data. ### Future Implementation (Screenshot) Proposed API Response for a Finished Episode: "episodes": [ { "id": "episode_123", "title": "Argument: 1. Thesis", "userMediaProgress": { "isFinished": true, "progress": 1.0, "lastUpdate": 1735505152 } } ] Current behavior often returns userMediaProgress: null for this state, leading to ambiguity. ### Audiobookshelf Server Version 2.32.1 (docker) ### Current Implementation (Screenshot) I was looking at the Podcast Episode List and the API response payload for a specific podcast. Even though episodes were marked as finished in the UI, the API debug logs showed: isFinished: No Progress Data Progress: 0 Hidden: False This lack of distinction in the data payload is the primary driver for this request.
adam added the enhancement label 2026-04-25 00:14:01 +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 enhancement
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#3163
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?