Handle Audiobookshelf user_item_progress_updated realtime events #8

Closed
opened 2026-09-18 08:44:16 +02:00 by alexander · 0 comments
Owner

Migrated from GitHub issue #90. Forgejo issue: #8. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links.

Why

Device testing of GitHub PR #83 showed that BookWave's realtime socket authenticates and survives profile switching, but remote playback progress changes do not produce Applying a realtime account update.

Current Audiobookshelf playback-session code emits user_item_progress_updated when /api/session/.../sync or local-session sync changes progress. BookWave currently handles user_updated but not this more specific playback-progress event, so the event is silently ignored and progress is learned later through REST fallback instead.

Observed device evidence:

  • realtime authenticated successfully;
  • deliberate profile teardown logged normally;
  • remote playback progress was not applied through realtime;
  • a later account refresh reported written=1, proving there was newer server progress available.

Scope

  • Capture/pin the current user_item_progress_updated Socket.IO payload contract.
  • Add a typed realtime event for that payload.
  • Apply only the affected media progress through the existing repository conflict rules.
  • Preserve unsynced-local-progress protection and timestamp/freshness semantics.
  • Add parser/contract/use-case tests.
  • Verify one remote playback progress change produces exactly one realtime application on device.

Important boundary: realtime does not drive the live player

This issue is protocol coverage and low-latency progress ingestion only.

A Socket.IO progress event must not directly seek active playback. While BookWave is actively playing, its live player/journal/outbox remain authoritative for this device. While paused, the pushed position may become an input/candidate for the next resume decision, but Socket.IO cannot replace the REST fallback because events are not replayed after a disconnect/background/process death.

The shared resume policy and control-surface integration are tracked in #9. #8 should feed that policy with a profile/book-scoped realtime candidate rather than implement a second resume policy of its own.

Relationship to existing work

  • GitHub #83: not a blocker. GitHub #83 is only WebSocket ownership/lifecycle cleanup; its device test exposed this separate protocol-coverage gap.
  • GitHub #89: complementary, not a replacement. GitHub #89 must still establish the restored paused baseline and perform the REST freshness fallback because WebSocket events can be missed.
  • #9: owns the larger architecture: one resume-freshness decision across app Play, notification, Bluetooth/headset and Android Auto. The realtime event implemented here is one input to that decision.

Do not merge automatically.

> Migrated from [GitHub issue #90](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/90). Forgejo issue: #8. GitHub source content synchronized on 2026-09-19. Migrated issue references below use Forgejo numbers where an equivalent issue exists; historical references without a Forgejo counterpart remain explicit GitHub links. ## Why Device testing of [GitHub PR #83](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/pull/83) showed that BookWave's realtime socket authenticates and survives profile switching, but remote playback progress changes do not produce `Applying a realtime account update`. Current Audiobookshelf playback-session code emits `user_item_progress_updated` when `/api/session/.../sync` or local-session sync changes progress. BookWave currently handles `user_updated` but not this more specific playback-progress event, so the event is silently ignored and progress is learned later through REST fallback instead. Observed device evidence: - realtime authenticated successfully; - deliberate profile teardown logged normally; - remote playback progress was not applied through realtime; - a later account refresh reported `written=1`, proving there was newer server progress available. ## Scope - Capture/pin the current `user_item_progress_updated` Socket.IO payload contract. - Add a typed realtime event for that payload. - Apply only the affected media progress through the existing repository conflict rules. - Preserve unsynced-local-progress protection and timestamp/freshness semantics. - Add parser/contract/use-case tests. - Verify one remote playback progress change produces exactly one realtime application on device. ## Important boundary: realtime does not drive the live player This issue is protocol coverage and low-latency progress ingestion only. A Socket.IO progress event must **not directly seek active playback**. While BookWave is actively playing, its live player/journal/outbox remain authoritative for this device. While paused, the pushed position may become an input/candidate for the next resume decision, but Socket.IO cannot replace the REST fallback because events are not replayed after a disconnect/background/process death. The shared resume policy and control-surface integration are tracked in #9. #8 should feed that policy with a profile/book-scoped realtime candidate rather than implement a second resume policy of its own. ## Relationship to existing work - **[GitHub #83](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/83):** not a blocker. [GitHub #83](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/83) is only WebSocket ownership/lifecycle cleanup; its device test exposed this separate protocol-coverage gap. - **[GitHub #89](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/89):** complementary, not a replacement. [GitHub #89](https://github.com/AlexanderWilhelmsenBerg/Audiobookshelf-Manager-Claude/issues/89) must still establish the restored paused baseline and perform the REST freshness fallback because WebSocket events can be missed. - **#9:** owns the larger architecture: one resume-freshness decision across app Play, notification, Bluetooth/headset and Android Auto. The realtime event implemented here is one input to that decision. Do not merge automatically.
Sign in to join this conversation.
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
alexander/Audiobookshelf-Manager-Claude#8
No description provided.