refactor(mobile): split playback provider and replace polling with player events

Move native playlist sync and progress persistence into their own hooks,
wait on playlist events instead of timers and polling, and build the
album/artist/playlist play actions from one table.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
joshuafhigginsandClaude Opus 5.5 committed 2026-11-16 13:54:07 -05:00 Verified
1 parent dce66b7697
commit cc9654c747
3 files changed
+955 -784

No files matched your search

File diff suppressed because it is too large. Load diff
@@ -0,0 +1,683 @@
import { dolbyAtmosSupported } from "@/lib/playback-capabilities"
import {
createAudioPlaylist,
setAudioModeAsync,
setIsAudioActiveAsync,
type AudioMetadata,
type AudioPlaylist,
type AudioPlaylistStatus,
type AudioSource,
} from "expo-audio"
import { useConvex } from "convex/react"
import { useCallback, useEffect, useMemo, useRef, useState } from "react"
import { useCacheScope } from "@/contexts/persistent-cache"
import { useServerConfig } from "@/contexts/server-config"
import { useCachedQuery } from "@/hooks/use-cached-query"
import { api } from "@otunes/convex/_generated/api"
import type { Id } from "@otunes/convex/_generated/dataModel"
import type { BrowseSong } from "@otunes/convex/types"
import { playbackStreamPlan } from "@otunes/convex/playback-stream"
import * as playbackQueue from "@otunes/convex/client/playback-queue"
import type { RepeatMode } from "@otunes/convex/client/playback-queue"
import type { PlaybackStore } from "@otunes/convex/client/playback-store"
import { getAuthCookieHeader } from "@/lib/auth-cookies"
import { loadPlaybackSongs } from "@/lib/playback-files"
import { showError } from "@/lib/toast"
import { albumCoverUrl, songAudioSource } from "@/lib/urls"
import {
activatePlaylistLockScreen,
releaseAudioPlaylist,
updatePlaylistLockScreenMetadata,
} from "@/lib/audio-playlist-lock-screen"
import {
nativePlaylistEdits,
nativePlaylistNeedsRebuild,
nativePlaylistSongIds,
repeatToPlaylistLoop,
} from "@/lib/native-playlist-window"
const PLAYBACK_READY_TIMEOUT_MS = 20_000
function lockScreenMetadata(
song: BrowseSong,
serverUrl: string
): AudioMetadata {
return {
title: song.title,
artist: song.artist.name,
albumTitle: song.album.title,
artworkUrl: albumCoverUrl(serverUrl, song.album.id, 512),
}
}
type PlaybackWaiter = { playing?: boolean; resolve: () => void }
/** Where the last sync left the native player, and the queue it reflects. */
type SyncedPosition = {
index: number
songId: Id<"songs"> | undefined
historyLength: number
}
/**
* Keeps the native `AudioPlaylist` in step with the playback queue, and
* feeds its status (position, playing, track changes) back into the queue.
*/
export function useNativePlaylistSync({
store,
queueSongIds,
queueHistorySongIds,
repeatEnabled,
currentSong,
queueStartVersion,
}: {
store: PlaybackStore
queueSongIds: Id<"songs">[]
queueHistorySongIds: Id<"songs">[]
repeatEnabled: RepeatMode
currentSong: BrowseSong | null
queueStartVersion: number
}) {
const convex = useConvex()
const { config } = useServerConfig()
const cacheScope = useCacheScope()
const user = useCachedQuery(api.auth.currentUser)
const storeRef = useRef(store)
storeRef.current = store
const playlistRef = useRef<AudioPlaylist | null>(null)
const statusSubscriptionRef = useRef<{ remove: () => void } | null>(null)
const trackChangedSubscriptionRef = useRef<{ remove: () => void } | null>(
null
)
const loadedSongIdsRef = useRef<Id<"songs">[]>([])
const loadedLoadKeyRef = useRef<string | null>(null)
const syncedPositionRef = useRef<SyncedPosition | null>(null)
const waitersRef = useRef(new Map<Id<"songs">, Set<PlaybackWaiter>>())
const autoPlayNextRef = useRef(false)
const isPlayingRef = useRef(false)
const currentTimeRef = useRef(0)
const pendingSeekRef = useRef<number | null>(null)
const seekInFlightRef = useRef(false)
const loadRequestIdRef = useRef(0)
const [isPlaying, setIsPlayingState] = useState(false)
const [currentTime, setCurrentTime] = useState(0)
const [measuredDuration, setDuration] = useState(0)
const currentSongId = queueSongIds[0] ?? null
const duration =
measuredDuration > 0
? measuredDuration
: (currentSong?.durationSeconds ?? 0)
const queueSyncKey = useMemo(
() => JSON.stringify(queueSongIds),
[queueSongIds]
)
const historySyncKey = useMemo(
() => JSON.stringify(queueHistorySongIds),
[queueHistorySongIds]
)
const currentSongSyncKey = currentSong
? JSON.stringify([
currentSong.id,
currentSong.title,
currentSong.artist.name,
currentSong.album.id,
currentSong.album.title,
currentSong.album.cover ?? "",
])
: ""
const userPlaybackKey = user
? JSON.stringify([
user._id,
user.playbackQuality,
dolbyAtmosSupported && (user.preferAtmos ?? false),
])
: ""
const settleWaiters = useCallback(() => {
const player = playlistRef.current
if (waitersRef.current.size === 0 || !player) return
const songId = loadedSongIdsRef.current[player.currentIndex]
const waiters = songId && waitersRef.current.get(songId)
if (!waiters || !player.isLoaded) return
for (const waiter of waiters) {
if (waiter.playing === undefined || player.playing === waiter.playing) {
waiter.resolve()
}
}
}, [])
const markSynced = useCallback(
(playlist: AudioPlaylist, songId: Id<"songs">, historyLength: number) => {
syncedPositionRef.current = {
index: playlist.currentIndex,
songId,
historyLength,
}
settleWaiters()
},
[settleWaiters]
)
const destroyPlaylist = useCallback(() => {
statusSubscriptionRef.current?.remove()
statusSubscriptionRef.current = null
trackChangedSubscriptionRef.current?.remove()
trackChangedSubscriptionRef.current = null
const playlist = playlistRef.current
if (playlist) {
playlist.pause()
releaseAudioPlaylist(playlist)
}
playlistRef.current = null
loadedSongIdsRef.current = []
loadedLoadKeyRef.current = null
syncedPositionRef.current = null
}, [])
const resetPosition = useCallback(() => {
pendingSeekRef.current = null
currentTimeRef.current = 0
setCurrentTime(0)
setDuration(0)
}, [])
// A new queue must not inherit the native player's position or a pending seek.
const resetForNewQueue = useCallback(() => {
loadRequestIdRef.current += 1
destroyPlaylist()
seekInFlightRef.current = false
resetPosition()
}, [destroyPlaylist, resetPosition])
const handlePlaylistStatusUpdate = useCallback(
(status: AudioPlaylistStatus) => {
settleWaiters()
if (!status.isLoaded) return
const state = storeRef.current.getState()
if (loadedSongIdsRef.current[status.currentIndex] !== state.queue[0]) {
return
}
if (status.duration > 0) {
setDuration(status.duration)
}
if (pendingSeekRef.current !== null && pendingSeekRef.current > 0) {
const seekSeconds = pendingSeekRef.current
pendingSeekRef.current = null
const playlist = playlistRef.current
if (playlist) {
// Statuses report the old position until the seek lands.
seekInFlightRef.current = true
void playlist.seekTo(seekSeconds).finally(() => {
seekInFlightRef.current = false
})
}
currentTimeRef.current = seekSeconds
setCurrentTime(seekSeconds)
} else if (!seekInFlightRef.current) {
currentTimeRef.current = status.currentTime
setCurrentTime(status.currentTime)
}
if (status.playing) {
autoPlayNextRef.current = false
if (!isPlayingRef.current) {
isPlayingRef.current = true
setIsPlayingState(true)
}
} else if (isPlayingRef.current && !status.didJustFinish) {
autoPlayNextRef.current = false
isPlayingRef.current = false
setIsPlayingState(false)
}
if (!status.didJustFinish) return
if (state.repeatEnabled === "once") return
if (status.currentIndex < status.trackCount - 1) return
const shouldContinue =
state.repeatEnabled !== "none" || state.queue.length > 1
if (!shouldContinue) {
autoPlayNextRef.current = false
isPlayingRef.current = false
setIsPlayingState(false)
storeRef.current.update(playbackQueue.skipNext)
void playlistRef.current?.seekTo(0)
currentTimeRef.current = 0
setCurrentTime(0)
return
}
autoPlayNextRef.current = true
isPlayingRef.current = true
setIsPlayingState(true)
storeRef.current.update(playbackQueue.skipNext)
if (storeRef.current.getState().queue[0] === state.queue[0]) {
const playlist = playlistRef.current
void playlist?.seekTo(0)
playlist?.play()
}
},
[settleWaiters]
)
const handleTrackChanged = useCallback(() => {
const playlist = playlistRef.current
const synced = syncedPositionRef.current
if (!playlist || !synced) return
// Queue edits run synchronously, so an event can describe an index from
// before them (Android's `previousIndex` also goes stale). The player's
// live index is the one that matters; if it is where the last sync left
// it, this change was ours.
const index = playlist.currentIndex
if (index === synced.index) return
const state = storeRef.current.getState()
// A queue change is still being applied and will move the player itself.
if (
state.queue[0] !== synced.songId ||
state.history.length !== synced.historyLength
) {
return
}
// The window is history then queue, so the current track sits at
// `history.length`.
const steps = index - state.history.length
if (steps === 0) return
autoPlayNextRef.current = true
isPlayingRef.current = true
setIsPlayingState(true)
storeRef.current.update((state) => {
if (steps === 1) return playbackQueue.skipNext(state)
if (steps > 1) return playbackQueue.skipToQueueIndex(state, steps)
let next = state
for (let i = 0; i < -steps; i++) {
next = playbackQueue.skipPrevious(next)
}
return next
})
const next = storeRef.current.getState()
syncedPositionRef.current = {
index,
songId: next.queue[0],
historyLength: next.history.length,
}
settleWaiters()
}, [settleWaiters])
const ensurePlaylist = useCallback(
(sources: AudioSource[]) => {
if (playlistRef.current) {
return playlistRef.current
}
const playlist = createAudioPlaylist({
sources,
updateInterval: 500,
loop: repeatToPlaylistLoop(storeRef.current.getState().repeatEnabled),
})
// System volume controls loudness; keep the player gain at full scale.
playlist.volume = 1
statusSubscriptionRef.current = playlist.addListener(
"playlistStatusUpdate",
handlePlaylistStatusUpdate
)
trackChangedSubscriptionRef.current = playlist.addListener(
"trackChanged",
handleTrackChanged
)
playlistRef.current = playlist
return playlist
},
[handlePlaylistStatusUpdate, handleTrackChanged]
)
useEffect(() => {
let cancelled = false
void setAudioModeAsync({
playsInSilentMode: true,
shouldPlayInBackground: true,
interruptionMode: "doNotMix",
}).catch(() => {
if (!cancelled) {
showError("Audio playback could not be initialized.")
}
})
return () => {
cancelled = true
destroyPlaylist()
}
}, [destroyPlaylist])
useEffect(() => {
const playlist = playlistRef.current
if (playlist) {
playlist.loop = repeatToPlaylistLoop(repeatEnabled)
}
}, [repeatEnabled])
const setIsPlaying = useCallback((playing: boolean) => {
isPlayingRef.current = playing
setIsPlayingState(playing)
const playlist = playlistRef.current
if (!playlist) return
if (playing) {
playlist.play()
} else {
playlist.pause()
}
}, [])
const seekTo = useCallback(
async (seconds: number) => {
const playlist = playlistRef.current
if (!playlist) return
const maxDuration = playlist.duration || duration || 0
const clamped = Math.max(0, Math.min(seconds, maxDuration))
await playlist.seekTo(clamped)
currentTimeRef.current = clamped
setCurrentTime(clamped)
},
[duration]
)
const handlePlaybackLoadFailure = useCallback(() => {
autoPlayNextRef.current = false
isPlayingRef.current = false
destroyPlaylist()
setIsPlayingState(false)
showError("Could not play this track. The queue has been cleared.")
storeRef.current.update(playbackQueue.clearQueue)
}, [destroyPlaylist])
useEffect(() => {
const loadRequestId = ++loadRequestIdRef.current
const isCurrentLoad = () => loadRequestIdRef.current === loadRequestId
async function syncPlaylist() {
if (!config || !currentSongId || !user) {
if (!currentSongId) {
destroyPlaylist()
}
return
}
const windowSongIds = nativePlaylistSongIds(
queueHistorySongIds,
queueSongIds
)
const currentIndex = queueHistorySongIds.length
const cookieHeader = await getAuthCookieHeader(
config.serverUrl,
config.convexUrl
)
if (!cookieHeader) {
showError("Your session has expired. Please sign in again.")
return
}
if (!isCurrentLoad()) return
const loadKey = `${user.playbackQuality}:${dolbyAtmosSupported && (user.preferAtmos ?? false)}:${cookieHeader}`
const needsRebuild =
loadedLoadKeyRef.current !== loadKey ||
nativePlaylistNeedsRebuild(
loadedSongIdsRef.current,
queueHistorySongIds,
queueSongIds
)
const metadata = currentSong
? lockScreenMetadata(currentSong, config.serverUrl)
: null
const shouldPlay = isPlayingRef.current || autoPlayNextRef.current
if (!needsRebuild) {
const playlist = playlistRef.current
if (!playlist) return
if (playlist.currentIndex !== currentIndex) {
playlist.skipTo(currentIndex)
}
playlist.loop = repeatToPlaylistLoop(repeatEnabled)
if (metadata) {
updatePlaylistLockScreenMetadata(playlist, metadata)
}
markSynced(playlist, currentSongId, currentIndex)
if (shouldPlay) {
isPlayingRef.current = true
setIsPlayingState(true)
playlist.play()
}
return
}
const buildSources = async (songIds: Id<"songs">[]) => {
const songs = await loadPlaybackSongs(convex, cacheScope, songIds)
const sources = new Map<Id<"songs">, AudioSource>()
for (const song of songs) {
if (!song) return null
const plan = playbackStreamPlan(
song.files,
user.playbackQuality,
dolbyAtmosSupported && (user.preferAtmos ?? false)
)
sources.set(
song.id,
songAudioSource(
config.serverUrl,
song.id,
plan.playbackQuality,
plan.preferAtmos,
plan.useHls,
{ cookieHeader, songTitle: song.title }
)
)
}
return sources
}
// Queue and history edits around the playing track are applied in place
// so playback isn't interrupted.
const loadedPlaylist = playlistRef.current
const edits =
loadedPlaylist && loadedLoadKeyRef.current === loadKey
? nativePlaylistEdits(
loadedSongIdsRef.current,
loadedPlaylist.currentIndex,
windowSongIds,
currentIndex
)
: null
if (loadedPlaylist && edits) {
const addedSongIds = edits.flatMap((edit) =>
edit.type === "remove" ? [] : [edit.songId]
)
const sources = await buildSources([...new Set(addedSongIds)])
if (!isCurrentLoad()) return
if (!sources) {
handlePlaybackLoadFailure()
return
}
for (const edit of edits) {
if (edit.type === "remove") {
loadedPlaylist.remove(edit.index)
} else if (edit.type === "insert") {
loadedPlaylist.insert(sources.get(edit.songId)!, edit.index)
} else {
loadedPlaylist.add(sources.get(edit.songId)!)
}
}
loadedSongIdsRef.current = windowSongIds
loadedPlaylist.loop = repeatToPlaylistLoop(repeatEnabled)
markSynced(loadedPlaylist, currentSongId, currentIndex)
if (shouldPlay && !loadedPlaylist.playing) {
isPlayingRef.current = true
setIsPlayingState(true)
loadedPlaylist.play()
}
return
}
const sourcesById = await buildSources(windowSongIds)
if (!isCurrentLoad()) return
if (!sourcesById) {
handlePlaybackLoadFailure()
return
}
const sources = windowSongIds.map((songId) => sourcesById.get(songId)!)
// Keep the position when only the stream settings changed.
const resumeSeconds =
loadedPlaylist &&
loadedSongIdsRef.current[loadedPlaylist.currentIndex] === currentSongId
? currentTimeRef.current
: null
destroyPlaylist()
if (resumeSeconds !== null && resumeSeconds > 0) {
pendingSeekRef.current = resumeSeconds
}
// Start at the current track and put history in front of it, so an
// earlier song is never loaded first.
const playlist = ensurePlaylist(sources.slice(currentIndex))
for (let index = 0; index < currentIndex; index++) {
playlist.insert(sources[index], index)
}
loadedSongIdsRef.current = windowSongIds
loadedLoadKeyRef.current = loadKey
playlist.loop = repeatToPlaylistLoop(repeatEnabled)
activatePlaylistLockScreen(
playlist,
metadata ?? { title: currentSong?.title }
)
markSynced(playlist, currentSongId, currentIndex)
if (shouldPlay) {
isPlayingRef.current = true
setIsPlayingState(true)
playlist.play()
} else {
playlist.pause()
// Enable audio for the restored queue without starting playback.
try {
await setIsAudioActiveAsync(true)
} catch {
if (isCurrentLoad()) {
showError("Audio playback could not be initialized.")
}
}
}
}
void syncPlaylist().catch(() => {
if (!isCurrentLoad()) return
handlePlaybackLoadFailure()
})
return () => {
if (loadRequestIdRef.current === loadRequestId) {
loadRequestIdRef.current += 1
}
}
}, [
cacheScope,
config,
convex,
currentSongId,
currentSongSyncKey,
destroyPlaylist,
ensurePlaylist,
handlePlaybackLoadFailure,
historySyncKey,
markSynced,
queueSyncKey,
queueStartVersion,
repeatEnabled,
userPlaybackKey,
])
/**
* Resolves once the native player has `songId` loaded (and playing or
* paused, if given). Rejects if the queue moves to another song first.
*/
const waitForSong = useCallback(
(songId: Id<"songs">, playing?: boolean) =>
new Promise<void>((resolve, reject) => {
const store = storeRef.current
const waiters = waitersRef.current
let songWaiters = waiters.get(songId)
if (!songWaiters) {
songWaiters = new Set()
waiters.set(songId, songWaiters)
}
const finish = (error?: Error) => {
clearTimeout(timeout)
unsubscribe()
songWaiters.delete(waiter)
if (songWaiters.size === 0 && waiters.get(songId) === songWaiters) {
waiters.delete(songId)
}
if (error) reject(error)
else resolve()
}
const waiter: PlaybackWaiter = { playing, resolve: () => finish() }
const timeout = setTimeout(
() =>
finish(
new Error(
"The audio did not become ready. Check your connection and try again."
)
),
PLAYBACK_READY_TIMEOUT_MS
)
// Starting a queue clears it and fills it in one go; only the
// settled queue counts.
const unsubscribe = store.subscribe(() => {
queueMicrotask(() => {
if (store.getState().queue[0] !== songId) {
finish(
new Error(
"The playback queue changed before the request finished."
)
)
}
})
})
songWaiters.add(waiter)
settleWaiters()
}),
[settleWaiters]
)
const queueSeek = useCallback((seconds: number) => {
pendingSeekRef.current = seconds
}, [])
const hasPlayer = useCallback(() => playlistRef.current !== null, [])
const requestAutoPlay = useCallback(() => {
autoPlayNextRef.current = true
}, [])
return {
isPlaying,
setIsPlaying,
currentTime,
currentTimeRef,
duration,
seekTo,
queueSeek,
hasPlayer,
requestAutoPlay,
resetPosition,
resetForNewQueue,
waitForSong,
}
}
@@ -0,0 +1,128 @@
import { useMutation } from "convex/react"
import { useCallback, useEffect, useRef, useState, type RefObject } from "react"
import { AppState } from "react-native"
import { api } from "@otunes/convex/_generated/api"
import type { Id } from "@otunes/convex/_generated/dataModel"
import type { PlaybackStore } from "@otunes/convex/client/playback-store"
import { flushPersistentCache } from "@/lib/persistent-cache"
const PROGRESS_SAVE_INTERVAL_MS = 5000
/**
* Restores the saved position when a song becomes current, and saves the
* position while it plays, on pause, and when the app leaves the foreground.
*/
export function useProgressPersistence({
store,
currentSongId,
isPlaying,
duration,
queueStartVersion,
currentTimeRef,
hasPlayer,
queueSeek,
resetPosition,
}: {
store: PlaybackStore
currentSongId: Id<"songs"> | null
isPlaying: boolean
duration: number
queueStartVersion: number
currentTimeRef: RefObject<number>
hasPlayer: () => boolean
queueSeek: (seconds: number) => void
resetPosition: () => void
}) {
const updateSongProgressMutation = useMutation(
api.playback.updateSongProgress
)
const storeRef = useRef(store)
storeRef.current = store
const progressRestoredForSongRef = useRef<Id<"songs"> | null>(null)
const lastSavedProgressRef = useRef(-1)
const prevIsPlayingRef = useRef(false)
const [progressToRestore, setProgressToRestore] = useState<number | null>(
null
)
const saveProgress = useCallback(
(seconds: number) => {
const songId = storeRef.current.getState().queue[0]
if (!songId) return
const progressSeconds = Math.max(0, Math.floor(seconds))
if (progressSeconds === lastSavedProgressRef.current) return
lastSavedProgressRef.current = progressSeconds
storeRef.current.setProgress(songId, progressSeconds)
void updateSongProgressMutation({
songId,
progressSeconds,
}).catch(() => {})
},
[updateSongProgressMutation]
)
const resetProgress = useCallback(() => {
progressRestoredForSongRef.current = null
lastSavedProgressRef.current = -1
setProgressToRestore(null)
}, [])
useEffect(() => {
if (!currentSongId) {
progressRestoredForSongRef.current = null
return
}
if (progressRestoredForSongRef.current === currentSongId) return
progressRestoredForSongRef.current = currentSongId
lastSavedProgressRef.current = -1
resetPosition()
setProgressToRestore(store.getState().progressSeconds)
}, [currentSongId, queueStartVersion, resetPosition, store])
useEffect(() => {
if (progressToRestore === null || progressToRestore <= 0) return
if (!currentSongId || !hasPlayer()) return
const maxDuration = duration > 0 ? duration : progressToRestore
queueSeek(Math.min(progressToRestore, maxDuration))
setProgressToRestore(null)
}, [progressToRestore, currentSongId, duration, hasPlayer, queueSeek])
useEffect(() => {
if (!currentSongId) return
if (prevIsPlayingRef.current === isPlaying) return
prevIsPlayingRef.current = isPlaying
saveProgress(currentTimeRef.current)
}, [isPlaying, currentSongId, currentTimeRef, saveProgress])
useEffect(() => {
const subscription = AppState.addEventListener("change", (state) => {
if (state === "active") return
const restorePending = progressToRestore !== null && progressToRestore > 0
if (currentSongId && hasPlayer() && !restorePending) {
saveProgress(currentTimeRef.current)
}
flushPersistentCache()
})
return () => subscription.remove()
}, [
currentSongId,
currentTimeRef,
hasPlayer,
progressToRestore,
saveProgress,
])
useEffect(() => {
if (!isPlaying || !currentSongId) return
const interval = setInterval(() => {
saveProgress(currentTimeRef.current)
}, PROGRESS_SAVE_INTERVAL_MS)
return () => clearInterval(interval)
}, [isPlaying, currentSongId, currentTimeRef, saveProgress])
return { resetProgress }
}