Use ProgressState for precise EPUB location tracking

[bluesam1]

Summary

To make the 'Books' feature useful, this updates the BookPlayer to read and write CFI (Canonical Fragment Identifier) strings via the new ProgressState field for precise EPUB location resumption. Falls back to percentage-based resume for backward compatibility.

Problem

EPUB reading position cannot be accurately synced across devices because the current implementation uses percentage-based position tracking, which breaks when text reflows on different screen sizes.

Solution

• Add getProgressState() method to BookPlayer to expose CFI string
• Store CFI on page navigation via relocated event
• Read ProgressState from API on book load for precise resume
• Add self.getProgressState() to PlaybackManager following existing patterns
• Include ProgressState in playback progress reports

Changes

• BookPlayer:

  • Added getProgressState() method returning current CFI
  • Store CFI in progressState on relocated event
  • Read item.UserData?.ProgressState on load, fallback to percentage if not present

• PlaybackManager:

  • Added self.getProgressState() method for consistency with other player state methods
  • Include ProgressState in getPlayerState() output

Testing

• Tested EPUB resume with CFI strings
• Verified fallback to percentage-based resume for items without ProgressState
• Confirmed progress reports include ProgressState in API calls
• Confirmed other media types still work as before

Related

Complements backend PR: jellyfin/jellyfin#15633 (Add ProgressState field for precise EPUB location tracking)
Discussion here: /issues/3791

[jellyfin-bot]

Cloudflare Pages deployment

Latest commit	5bba58b
Status	✅ Deployed!
Preview URL	https://0cc5a4a0.jellyfin-web.pages.dev
Type	🔀 Preview

View build logs

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[dkanada]

@bluesam1 this is a great improvement but the server portion might need some changes - there has been an effort to avoid more attributes that only apply to specific library types. This is why it originally used the percentage value.

For what it's worth, the percentage is slightly more granular than per-chapter and keeps progress per-page as long as you use the same device. I believe most of the reports in #2582 and #3791 are from changing devices or exiting and reloading without refreshing the page, which will try to load the previous state in some cases.

[bluesam1]

@bluesam1 this is a great improvement but the server portion might need some changes - there has been an effort to avoid more attributes that only apply to specific library types. This is why it originally used the percentage value.

For what it's worth, the percentage is slightly more granular than per-chapter and keeps progress per-page as long as you use the same device. I believe most of the reports in #2582 and #3791 are from changing devices or exiting and reloading without refreshing the page, which will try to load the previous state in some cases.

Thanks for the feedback. My thinking was that in order for this to be an ebook reader worth using, an almost-exact location is necessary. I had found the page was still off when using the same device, so I'll do some testing to see if I can replicate the issue.