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 #5080] feat: MediaSession respects "Use chapter track" setting #4418

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

📋 Pull Request Information

Original PR: https://github.com/advplyr/audiobookshelf/pull/5080
Author: @n8jadams
Created: 2/23/2026
Status: 🔄 Open

Base: master ← Head: media_session_respect_use_chapter_track

📝 Commits (1)

  • cdd9800 feat: Add chapter-relative MediaSession position state

📊 Changes

2 files changed (+227 additions, -3 deletions)

View changed files

📝 client/components/app/MediaPlayerContainer.vue (+114 -1)
📝 client/pages/share/_slug.vue (+113 -2)

📄 Description

Brief summary

  • When "Use chapter track" is enabled in player settings, the Media Session API now reports the current chapter's duration/position instead of the full audiobook
  • OS lock screen and notification center scrubbers now span only the current chapter
  • Seek requests from OS controls are mapped back to the correct absolute position

Which issue is fixed?

Implements https://github.com/advplyr/audiobookshelf/issues/5079

In-depth Description

The Problem

When playing an M4B audiobook with embedded chapters (e.g., a 12-hour book with 30 chapters), the OS media controls (lock screen, notification center, Control Center) show a scrubber spanning the entire 12 hours! This makes precise navigation nearly impossible - a tiny thumb movement might skip 30 minutes.

The Solution

When the user enables Use chapter track in player settings, we intercept the Media Session API to report values relative to the chapter instead of to the full audio file.

Technical Implementation

  1. Position State Reporting (updateMediaSessionPositionState)

Instead of:

setPositionState({ duration: 43200, position: 7200 })  // 12hr book, 2hr in

We calculate:

chapterStart = 7000      // Chapter 5 starts at 1:56:40
chapterEnd = 8440        // Chapter 5 ends at 2:20:40
chapterDuration = 1440   // 24 minutes
chapterPosition = 200    // 3:20 into chapter

setPositionState({ duration: 1440, position: 200 })
  1. Seek Mapping (mediaSessionSeekTo)

When the user drags the OS scrubber, the OS sends a seek request relative to what we reported. We map it back:

// OS requests: "seek to 600 seconds" (10 min into the 24-min chapter)
// We translate: chapterStart + 600 = 7000 + 600 = 7600
audio.currentTime = 7600  // Correct absolute position
  1. Metadata Updates (updateMediaSessionForChapter)

When chapters change, we update the displayed title to show the chapter name instead of the book title.

Why This Approach?

This was the minimum code change necessary to get the consistent UX between the web app interface and the OS media controls. This also gets the UI/UX in consistency with other apps, such as Audible.

How have you tested this?

  1. Tested on an iPad using the iOS Safari.
  2. Tested for regressions. During playback and in the lock screen, the full audio progress shows if the "Use chapter track" is disabled, or if the audio file doesn't have tracker markers.
  3. Tested new functionality, enabled "Use chapter track", locked the screen, now only the current chapter appears. Scrubbing and skipping ahead/behind 10s works as expected. Chapters transition at the right time.

Screenshots

Before while listening to chapter 1 of Fourth Wing:
audiobookshelf-screen-2

After listening to chapter 1 of Fourth Wing:
audiobookshelf-screen-3

🔄 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/5080 **Author:** [@n8jadams](https://github.com/n8jadams) **Created:** 2/23/2026 **Status:** 🔄 Open **Base:** `master` ← **Head:** `media_session_respect_use_chapter_track` --- ### 📝 Commits (1) - [`cdd9800`](https://github.com/advplyr/audiobookshelf/commit/cdd9800dfffa5bac20d17c6af44d5aaca9a2b547) feat: Add chapter-relative MediaSession position state ### 📊 Changes **2 files changed** (+227 additions, -3 deletions) <details> <summary>View changed files</summary> 📝 `client/components/app/MediaPlayerContainer.vue` (+114 -1) 📝 `client/pages/share/_slug.vue` (+113 -2) </details> ### 📄 Description ## Brief summary - When "Use chapter track" is enabled in player settings, the Media Session API now reports the current chapter's duration/position instead of the full audiobook - OS lock screen and notification center scrubbers now span only the current chapter - Seek requests from OS controls are mapped back to the correct absolute position ## Which issue is fixed? Implements https://github.com/advplyr/audiobookshelf/issues/5079 ## In-depth Description ### The Problem When playing an M4B audiobook with embedded chapters (e.g., a 12-hour book with 30 chapters), the OS media controls (lock screen, notification center, Control Center) show a scrubber spanning the entire 12 hours! This makes precise navigation nearly impossible - a tiny thumb movement might skip 30 minutes. ### The Solution When the user enables `Use chapter track` in player settings, we intercept the Media Session API to report values relative to the chapter instead of to the full audio file. ### Technical Implementation 1. Position State Reporting (`updateMediaSessionPositionState`) Instead of: ```javascript setPositionState({ duration: 43200, position: 7200 }) // 12hr book, 2hr in ``` We calculate: ```javascript chapterStart = 7000 // Chapter 5 starts at 1:56:40 chapterEnd = 8440 // Chapter 5 ends at 2:20:40 chapterDuration = 1440 // 24 minutes chapterPosition = 200 // 3:20 into chapter setPositionState({ duration: 1440, position: 200 }) ``` 2. Seek Mapping (`mediaSessionSeekTo`) When the user drags the OS scrubber, the OS sends a seek request relative to what we reported. We map it back: ```javascript // OS requests: "seek to 600 seconds" (10 min into the 24-min chapter) // We translate: chapterStart + 600 = 7000 + 600 = 7600 audio.currentTime = 7600 // Correct absolute position ``` 3. Metadata Updates (`updateMediaSessionForChapter`) When chapters change, we update the displayed title to show the chapter name instead of the book title. ### Why This Approach? This was the minimum code change necessary to get the consistent UX between the web app interface and the OS media controls. This also gets the UI/UX in consistency with other apps, such as Audible. ## How have you tested this? 1. Tested on an iPad using the iOS Safari. 2. Tested for regressions. During playback and in the lock screen, the full audio progress shows if the "Use chapter track" is disabled, or if the audio file doesn't have tracker markers. 3. Tested new functionality, enabled "Use chapter track", locked the screen, now only the current chapter appears. Scrubbing and skipping ahead/behind 10s works as expected. Chapters transition at the right time. ## Screenshots Before while listening to chapter 1 of Fourth Wing: ![audiobookshelf-screen-2](https://github.com/user-attachments/assets/cc936fef-c2e7-43e1-b9cd-5ede4783560a) After listening to chapter 1 of Fourth Wing: ![audiobookshelf-screen-3](https://github.com/user-attachments/assets/e792ddc4-8f8a-45ae-9416-bab7099bb031) --- <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:40 +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#4418
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?