feat(player): add gapless queue handoff and SPA navigation by tui2019 · Pull Request #248 · sozercan/kaset

tui2019 · 2026-05-09T18:35:51Z

Description

This PR adds best-effort gapless playback by mirroring Kaset's expected next queue occurrence into YouTube Music's native Up Next queue. It also keeps the YouTube Music app shell warm and prefers the web player's SPA router before falling back to a full watch page load.

Kaset's local queue remains the source of truth. Manual Next/Previous actions—including media keys—advance Kaset's queue through deterministic play(song:) / loadVideo(videoId:) navigation. Natural track-end playback uses the native queue only after the expected source/target relationship has been confirmed. Kaset commits the handoff only when the media-bound observer reports the expected target; stale events, wrong tracks, queue edits, failed injection, or timeout all fall back to deterministic loading.

AI Prompt (Optional)

🤖 AI Prompt Used

Implement gapless playback by intercepting YouTube Music's native "Up Next" queue and injecting Kaset's local queue items via JavaScript. Update the track navigation to use the web player's SPA router (`navigateEndpoint`) instead of fully reloading the page.

AI Tools: Gemini CLI for the initial implementation; Codex for follow-up diagnosis, hardening, tests, and documentation.

Type of Change

🐛 Bug fix (non-breaking change that fixes an issue)
✨ New feature (non-breaking change that adds functionality)
💥 Breaking change (fix or feature that would cause existing functionality to change)
📚 Documentation update
🎨 UI/UX improvement
♻️ Refactoring (no functional changes)
🧪 Test update
🔧 Build/CI configuration

Related Issues

Fixes #241
Fixes #245

Changes Made

Native queue handoff: Injects the exact expected next queue occurrence through YouTube Music's own Play next command, then verifies the rendered queue before trusting it.
Best-effort gapless playback: Lets natural track end use YouTube Music's native auto-advance only after confirmed injection; a wrong target or three-second timeout falls back to deterministic Kaset navigation.
Occurrence-scoped playback identity: Binds bridge events to document, observer epoch, media generation, and media video ID so stale metadata or duplicate ended events cannot move the queue backward or double-advance it.
Deterministic manual navigation: Keeps Next/Previous buttons and media keys on Kaset's local queue path, with bounded/coalesced recovery when stale WebView metadata conflicts with the selected target.
Queue maintenance hardening: Cancels stale radio/mix maintenance after external queue replacement, preserves task-local mutations, handles queue edits during handoff, and follows ephemeral Smart Shuffle entries even when the persisted signature is unchanged.
SPA routing and preload: Keeps the singleton playback WebView mounted when needed, preloads the YouTube Music app shell, prefers watchEndpoint router navigation, and generation-guards full-load fallbacks.
Restoration and autoplay safety: Restores deferred sessions and saved seek positions without hidden playback, while explicit Resume/Next/Previous actions unblock autoplay.
API exploration: Adds api-explorer queue-probe for inspecting YouTube Music next/radio queue response shapes.
Regression coverage: Adds focused tests for queue injection, native handoff, playback identity, persistence synchronization, navigation recovery, repeat/duplicate tracks, and stale async work; serializes CI unit tests and replaces an equalizer timing sleep with an explicit persistence await.
Documentation and agent guidance: Adds ADR-0026, updates docs/playback.md, and expands the playback WebView debugging skill with the new queue/handoff components.

Testing

swift build
swiftlint --strict --quiet
swift test --skip KasetUITests --disable-xctest --no-parallel
GitHub Actions build, API Explorer, lint/format, unit-test, and UI-test checks pass
Structured autoreview/adversarial review passed with no accepted/actionable findings
Manual playback testing performed on macOS 26+

Checklist

My code follows the project's style guidelines
I have run swiftlint --strict && swiftformat .
I have added tests that prove my fix/feature works
New and existing unit tests pass locally
I have updated documentation if needed
I have checked for any performance implications
My changes generate no new warnings

Screenshots

Bildschirmaufnahme.2026-05-09.um.8.35.21.PM.mov

Additional Notes

This is best-effort gapless playback through YouTube Music's WebView player, not sample-perfect native audio-engine gapless playback. Real-world seamlessness still depends on YouTube Music buffering, WebKit timing, network state, and YouTube's internal player behavior. When native queue state cannot be proven correct, Kaset deliberately prioritizes queue correctness over gaplessness.

…ueue tools

…stentPlayerView

… resume

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds tighter WebView/PlayerService coordination to improve playback continuity: native YouTube Music queue injection for gapless transitions, router-based navigation to reduce full reloads, and startup autoplay suppression/restoration handling.

Changes:

Inject the expected next track into YouTube Music’s native “Up Next” queue and advance locally when YTM auto-advances.
Add startup autoplay blocking knobs and restoration flow that waits for a server-restored track before falling back.
Prefer in-page router navigation and preload the YTM home shell once logged in.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
Sources/Kaset/Views/SingletonPlayerWebView+QueueInjection.swift	Adds JS-based “Play next” injection via DOM + JSON.stringify interception.
Sources/Kaset/Views/SingletonPlayerWebView+PlaybackControls.swift	Adds a JS toggle to block/unblock autoplay at runtime.
Sources/Kaset/Views/SingletonPlayerWebView+ObserverScript.swift	Honors the autoplay-block flag in playback observers.
Sources/Kaset/Views/MiniPlayerWebView.swift	Adds home preload, router navigation, updated autoplay bootstrap flags.
Sources/Kaset/Views/MiniPlayerViews.swift	Allows the persistent player view to exist without an immediate videoId.
Sources/Kaset/Views/MainWindow.swift	Keeps the persistent web view alive while logged in (even without pending video).
Sources/Kaset/Services/Player/PlayerService.swift	Tracks restoration wait state and last injected web-queue videoId.
Sources/Kaset/Services/Player/PlayerService+WebQueueSync.swift	Implements web-queue sync/injection and restoration metadata application.
Sources/Kaset/Services/Player/PlayerService+Queue.swift	Re-syncs web queue when persisting queue/session changes.
Sources/Kaset/Services/Player/PlayerService+PlaybackRestoration.swift	Defers restored playback until server-restored track is observed (or times out).
Sources/Kaset/Services/Player/PlayerService+PlaybackControls.swift	Syncs web queue after playback start; changes resume/next/previous autoplay behavior.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Signed-off-by: Sertac Ozercan <sozercan@gmail.com> # Conflicts: # Sources/Kaset/Services/Player/PlayerService+PlaybackControls.swift # Sources/Kaset/Services/Player/PlayerService+Queue.swift # Sources/Kaset/Views/MiniPlayerWebView.swift # Sources/Kaset/Views/SingletonPlayerWebView+PlaybackControls.swift

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Copilot

Review details

Files reviewed: 14/14 changed files
Comments generated: 1
Review effort level: Medium

Copilot

Review details

Files reviewed: 15/15 changed files
Comments generated: 0 new
Review effort level: Medium

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Copilot

Review details

Files reviewed: 21/21 changed files
Comments generated: 0 new
Review effort level: Medium

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Copilot

Review details

Files reviewed: 37/37 changed files
Comments generated: 3
Review effort level: Medium

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Copilot

Review details

Files reviewed: 38/38 changed files
Comments generated: 1
Review effort level: Medium

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Copilot

Review details

Files reviewed: 39/39 changed files
Comments generated: 1
Review effort level: Medium

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Copilot

Review details

Files reviewed: 39/39 changed files
Comments generated: 2
Review effort level: Medium

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Copilot

Review details

Files reviewed: 40/40 changed files
Comments generated: 4
Review effort level: Medium

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Copilot

Review details

Files reviewed: 46/46 changed files
Comments generated: 3
Review effort level: Medium

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Copilot

Review details

Files reviewed: 46/46 changed files
Comments generated: 2
Review effort level: Medium

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Reject outgoing media observations during a receipt-time-bounded navigation grace, while allowing persistent mismatches to reach recovery. Wait for YouTube Music's selected source queue row before invoking Play Next so its empty-queue fallback cannot start the target immediately. Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

tui2019 and others added 7 commits May 7, 2026 23:07

Port gapless playback and SPA navigation from fork

06f9250

Restore pre-loading home page for faster SPA routing

40a5c98

Refactor next() and previous() to use native YouTube Music built-in q…

764b016

…ueue tools

Fix web page preload on first launch by conditionally rendering Persi…

e60078e

…stentPlayerView

Fix cloud-synced queue restoration on first launch

0fa771d

Block autoplay during initial home page preload and unblock on manual…

8744f0a

… resume

Apply swiftformat

13a221e

Copilot AI review requested due to automatic review settings May 9, 2026 18:35

Copilot AI reviewed May 9, 2026

View reviewed changes

AnthonyLenglet mentioned this pull request Jul 6, 2026

[Bug]: Next track does not auto-play #245

Open

1 task

sozercan added 2 commits July 6, 2026 20:19

chore: clarify feedback token local name

8c4fef0

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Copilot AI review requested due to automatic review settings July 7, 2026 06:22

Copilot started reviewing on behalf of sozercan July 7, 2026 06:22 View session

Copilot AI reviewed Jul 7, 2026

View reviewed changes

Comment thread Sources/Kaset/Services/Player/PlayerService+WebQueueSync.swift Outdated

sozercan force-pushed the feature/implement-queues branch from db07ab2 to 1e4f415 Compare July 7, 2026 07:01

Copilot AI review requested due to automatic review settings July 7, 2026 07:23

sozercan force-pushed the feature/implement-queues branch from 1e4f415 to 695f39c Compare July 7, 2026 07:23

Copilot started reviewing on behalf of sozercan July 7, 2026 07:23 View session

Copilot AI reviewed Jul 7, 2026

View reviewed changes

fix: confirm web queue injection before trusting it

f49ee0b

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

sozercan force-pushed the feature/implement-queues branch from 695f39c to f49ee0b Compare July 7, 2026 18:19

Copilot AI review requested due to automatic review settings July 7, 2026 19:11

Copilot started reviewing on behalf of sozercan July 7, 2026 19:12 View session

Copilot AI reviewed Jul 7, 2026

View reviewed changes

sozercan added 2 commits July 7, 2026 19:23

fix: make manual next deterministic

b4cbccf

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

docs: document gapless playback architecture

b2f23e3

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Copilot AI review requested due to automatic review settings July 8, 2026 02:31

sozercan force-pushed the feature/implement-queues branch from 2a10062 to b2f23e3 Compare July 8, 2026 02:31

Copilot started reviewing on behalf of sozercan July 8, 2026 02:31 View session

Copilot AI review requested due to automatic review settings July 12, 2026 01:28

Copilot started reviewing on behalf of sozercan July 12, 2026 01:28 View session

sozercan approved these changes Jul 12, 2026

View reviewed changes

Copilot AI reviewed Jul 12, 2026

View reviewed changes

Comment thread Sources/Kaset/Services/Player/PlayerService+WebQueueSync.swift Outdated

Comment thread Sources/Kaset/Services/Player/PlayerService+ManualSeek.swift Outdated

Comment thread Sources/Kaset/Services/Player/PlayerService+PlaybackControls.swift Outdated

sozercan changed the title ~~Implement queues, native router~~ feat(player): add gapless queue handoff and SPA navigation Jul 12, 2026

fix(player): handle queue transition edge cases

8fa6a0b

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Copilot AI review requested due to automatic review settings July 12, 2026 02:53

Copilot started reviewing on behalf of sozercan July 12, 2026 02:53 View session

Copilot AI reviewed Jul 12, 2026

View reviewed changes

Comment thread Tests/KasetTests/PlayerServiceWebQueueSyncFollowUpTests.swift Outdated

test: replace timing-based async waits

1aa8027

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Copilot AI review requested due to automatic review settings July 12, 2026 03:18

Copilot started reviewing on behalf of sozercan July 12, 2026 03:18 View session

Copilot AI reviewed Jul 12, 2026

View reviewed changes

Comment thread Sources/Kaset/Services/Player/PlayerService.swift Outdated

fix(player): preserve maintenance during enrichment

5c50eae

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Copilot AI review requested due to automatic review settings July 12, 2026 03:41

Copilot started reviewing on behalf of sozercan July 12, 2026 03:42 View session

Copilot AI reviewed Jul 12, 2026

View reviewed changes

Comment thread Sources/Kaset/Views/SingletonPlayerWebView+NavigationState.swift

Comment thread Sources/Kaset/Views/SingletonPlayerWebView+QueueInjection.swift

test(equalizer): await round-trip persistence

68cb81c

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Copilot AI review requested due to automatic review settings July 12, 2026 03:48

test(player): cover stale navigation safeguards

51784f6

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Copilot AI reviewed Jul 12, 2026

View reviewed changes

Copilot AI reviewed Jul 12, 2026

sozercan added 2 commits July 12, 2026 00:41

fix(player): bind async navigation to playback context

e629ae8

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

chore: merge main into feature/implement-queues

c3e9811

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Copilot AI reviewed Jul 12, 2026

View reviewed changes

Comment thread Sources/Kaset/Services/Player/PlayerService+PlaybackControls.swift

Comment thread Sources/Kaset/Services/Player/PlayerService+PlaybackControls.swift

Comment thread Sources/Kaset/Views/SingletonPlayerWebView+ObserverScript.swift

Copilot AI reviewed Jul 12, 2026

fix(scrobbling): retain playback observation provenance

4a784f7

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Copilot AI reviewed Jul 12, 2026

View reviewed changes

Comment thread Sources/Kaset/Services/Player/PlayerService+PlaybackControls.swift

Comment thread Sources/Kaset/Services/Player/PlayerService+PlaybackControls.swift

sozercan added 2 commits July 12, 2026 05:32

fix(player): preserve manual intent and media identity

53f569c

Signed-off-by: Sertac Ozercan <sozercan@gmail.com>

Uh oh!

Conversation

tui2019 commented May 9, 2026 • edited by sozercan Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

AI Prompt (Optional)

Type of Change

Related Issues

Changes Made

Testing

Checklist

Screenshots

Additional Notes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Review details

Uh oh!

Uh oh!

Uh oh!

tui2019 commented May 9, 2026 •

edited by sozercan

Loading