fix: gapless autoplay transitions via Web Audio pre-scheduling

[chinmaykrishnroy]

Fix: Gapless Autoplay Transitions

Problem

When a song finishes and auto-advances to the next track, there's a 400ms-800ms audible gap caused by the server's audio loading coordination round-trip. Even bypassing coordination leaves a minimum 400ms scheduling delay.

Solution

Client-side gapless playback using the Web Audio API's sample-accurate scheduling. When a track starts playing, the next track's AudioBufferSourceNode is pre-scheduled to begin at the exact sample the current track ends, 0ms gap, no server round-trip.

How It Works

• Pre-scheduling: nextNode.start(currentTrackEndTime, 0) on the AudioContext timeline, sample-accurate
• On track end: State transitions instantly (audio already playing), server notified for bookkeeping only
• Chain continuation: After each transition, the next-next track is preloaded + pre-scheduled automatically
• Late pre-scheduling: If next track finishes downloading mid-playback, it's pre-scheduled at that point
• Cleanup: Pre-scheduled nodes are cancelled on pause, manual skip, track change, or store reset
• Duplicate guard: schedulePlay ignores the server echo from the bookkeeping notification
• Fallback: Shuffle mode or unloaded tracks gracefully fall back to server-coordinated autoplay (~400ms)

Behavior

Scenario	Gap
Sequential, next preloaded	0ms
Next track loads mid-playback	0ms
Shuffle mode	~400ms (server-coordinated)
Next track not loaded by song end	~400ms (fallback)

Verification

• Client + server TypeScript compile cleanly
• 109/109 server tests pass
• All pre-commit hooks pass

Preview

Optional self-hosted preview: https://beatsync.prefect-sys.online/

Note: this preview is my self-hosted deployment and may include local deployment-specific configuration, but the PR itself only changes the gapless autoplay transitions behavior.

[vercel]

@chinmaykrishnroy is attempting to deploy a commit to the freemanjiang's projects Team on Vercel.

A member of the Team first needs to authorize it.