feat(web): audio engine that survives token renewal

- drives the audio element from the player store: load, play, pause, seek, next on end
- a renewed access token swaps the stream URL and resumes at the same second, playing or paused
- reports start, listened time (in steps of at most two seconds) and finish for the listen reporter
- media keys and lock screen through the Media Session API
This commit is contained in:
tgiachi 2026-11-12 11:26:54 +01:00
commit 92d9c8ed78
5 changed files with 546 additions and 0 deletions

View file

@ -0,0 +1,250 @@
import { afterEach, beforeEach, expect, test, vi } from 'vitest'
import type { Track } from '@/api/catalog'
import { login, sessionStore } from '@/auth/session'
import { mockFetch } from '@/test/mockFetch'
import { createEngine, type AudioLike } from './engine'
import { usePlayer } from './store'
type AudioEvent = 'timeupdate' | 'ended' | 'error' | 'loadedmetadata'
/** A stand-in for the audio element: it keeps what was set and lets a test fire the events. */
class FakeAudio implements AudioLike {
currentTime = 0
duration = Number.NaN
paused = true
playCalls = 0
private url = ''
private handlers = new Map<string, Set<() => void>>()
get src() {
return this.url
}
set src(value: string) {
this.url = value
this.currentTime = 0 // a new resource starts over, and loading pauses the element
this.paused = true
}
async play() {
this.playCalls++
this.paused = false
}
pause() {
this.paused = true
}
addEventListener(type: AudioEvent, fn: () => void) {
if (!this.handlers.has(type)) this.handlers.set(type, new Set())
this.handlers.get(type)!.add(fn)
}
removeEventListener(type: string, fn: () => void) {
this.handlers.get(type)?.delete(fn)
}
emit(type: AudioEvent) {
this.handlers.get(type)?.forEach((fn) => fn())
}
listenerCount() {
return [...this.handlers.values()].reduce((n, set) => n + set.size, 0)
}
}
function track(n: number): Track {
return {
id: n,
title: `t${n}`,
duration_ms: 200_000,
track_no: n,
disc_no: 1,
album: null,
artists: [],
format: 'mp3',
}
}
const [t1, t2, t3] = [1, 2, 3].map(track)
function session(access: string) {
return {
access_token: access,
access_expires_at: new Date(Date.now() + 900_000).toISOString(),
refresh_token: `r-${access}`,
refresh_expires_at: new Date(Date.now() + 86_400_000).toISOString(),
user: { id: 1, username: 'tom', is_admin: false },
}
}
let audio: FakeAudio
let engine: { destroy(): void }
const hooks = { onStart: vi.fn(), onPlayed: vi.fn(), onFinish: vi.fn() }
beforeEach(async () => {
usePlayer.setState({
queue: [],
original: [],
index: 0,
playing: false,
positionMs: 0,
shuffle: false,
repeat: 'off',
seekMs: null,
seekId: 0,
playId: 0,
})
sessionStore.setState({ status: 'anonymous', user: null, accessToken: null, accessExpiresAt: 0, refreshToken: null })
hooks.onStart.mockClear()
hooks.onPlayed.mockClear()
hooks.onFinish.mockClear()
mockFetch({ 'POST /api/v1/auth/login': () => session('tok1') })
await login('tom', 'secret123')
audio = new FakeAudio()
engine = createEngine(audio, hooks)
})
afterEach(() => {
engine.destroy()
})
test('the current track is loaded from its stream URL with the token and played', () => {
usePlayer.getState().playTracks([t1, t2])
expect(audio.src).toBe('/api/v1/tracks/1/stream?access_token=tok1')
expect(audio.paused).toBe(false)
expect(hooks.onStart).toHaveBeenCalledWith(1)
})
test('pause and play follow the player', () => {
usePlayer.getState().playTracks([t1])
usePlayer.getState().togglePlay()
expect(audio.paused).toBe(true)
usePlayer.getState().togglePlay()
expect(audio.paused).toBe(false)
})
test('a seek moves the audio', () => {
usePlayer.getState().playTracks([t1])
usePlayer.getState().seek(42_000)
expect(audio.currentTime).toBe(42)
})
test('the position of the player follows the audio', () => {
usePlayer.getState().playTracks([t1])
audio.currentTime = 12.5
audio.emit('timeupdate')
expect(usePlayer.getState().positionMs).toBe(12_500)
})
test('a renewed token while a track plays keeps it playing from the same second', async () => {
usePlayer.getState().playTracks([t1])
audio.currentTime = 42
mockFetch({ 'POST /api/v1/auth/login': () => session('tok2') })
await login('tom', 'secret123')
expect(audio.src).toBe('/api/v1/tracks/1/stream?access_token=tok2')
const playsBefore = audio.playCalls
audio.emit('loadedmetadata')
expect(audio.currentTime).toBe(42)
expect(audio.paused).toBe(false)
expect(audio.playCalls).toBe(playsBefore + 1)
expect(hooks.onStart).toHaveBeenCalledTimes(1) // the same play, not a new one
})
test('a renewed token while paused keeps the position and stays paused', async () => {
usePlayer.getState().playTracks([t1])
usePlayer.getState().togglePlay()
audio.currentTime = 42
mockFetch({ 'POST /api/v1/auth/login': () => session('tok2') })
await login('tom', 'secret123')
const playsBefore = audio.playCalls
audio.emit('loadedmetadata')
expect(audio.currentTime).toBe(42)
expect(audio.paused).toBe(true)
expect(audio.playCalls).toBe(playsBefore)
})
test('a renewed token with nothing loaded does nothing', async () => {
mockFetch({ 'POST /api/v1/auth/login': () => session('tok2') })
await login('tom', 'secret123')
expect(audio.src).toBe('')
})
test('a track that ends moves on to the next and is reported as complete once', () => {
usePlayer.getState().playTracks([t1, t2])
audio.emit('ended')
expect(usePlayer.getState().index).toBe(1)
expect(audio.src).toBe('/api/v1/tracks/2/stream?access_token=tok1')
expect(hooks.onFinish).toHaveBeenCalledTimes(1)
expect(hooks.onFinish).toHaveBeenCalledWith('complete')
expect(hooks.onStart).toHaveBeenLastCalledWith(2)
})
test('moving on before the end reports a skip, but only if something had been played', () => {
usePlayer.getState().playTracks([t1, t2, t3])
usePlayer.getState().next() // nothing played yet
expect(hooks.onFinish).not.toHaveBeenCalled()
audio.currentTime = 1.5
audio.emit('timeupdate')
usePlayer.getState().next()
expect(hooks.onFinish).toHaveBeenCalledTimes(1)
expect(hooks.onFinish).toHaveBeenCalledWith('skip')
})
test('playing the same track again starts a new play', () => {
usePlayer.getState().playTracks([t1])
audio.currentTime = 1
audio.emit('timeupdate')
usePlayer.getState().playTracks([t1])
expect(hooks.onFinish).toHaveBeenCalledWith('skip')
expect(hooks.onStart).toHaveBeenCalledTimes(2)
})
test('repeat one after the end starts a new play of the same track', () => {
usePlayer.getState().playTracks([t1])
usePlayer.getState().cycleRepeat()
usePlayer.getState().cycleRepeat() // one
audio.emit('ended')
expect(hooks.onFinish).toHaveBeenCalledWith('complete')
expect(hooks.onStart).toHaveBeenCalledTimes(2)
expect(audio.currentTime).toBe(0)
expect(audio.paused).toBe(false)
})
test('time played is counted in steps of at most two seconds, so a seek is not counted', () => {
usePlayer.getState().playTracks([t1])
audio.currentTime = 0.5
audio.emit('timeupdate')
audio.currentTime = 1
audio.emit('timeupdate')
audio.currentTime = 31
audio.emit('timeupdate')
expect(hooks.onPlayed.mock.calls.map(([ms]) => ms)).toEqual([500, 500, 2000])
})
test('time is not counted while paused', () => {
usePlayer.getState().playTracks([t1])
usePlayer.getState().togglePlay()
audio.currentTime = 5
audio.emit('timeupdate')
expect(hooks.onPlayed).not.toHaveBeenCalled()
})
test('a stream that cannot be played stops the player', () => {
usePlayer.getState().playTracks([t1])
audio.emit('error')
expect(usePlayer.getState().playing).toBe(false)
})
test('an empty queue unloads the audio', () => {
usePlayer.getState().playTracks([t1])
usePlayer.getState().removeAt(0)
expect(audio.paused).toBe(true)
expect(audio.src).toBe('')
})
test('after destroy the engine no longer listens to anyone', async () => {
engine.destroy()
expect(audio.listenerCount()).toBe(0)
usePlayer.getState().playTracks([t1])
expect(audio.src).toBe('')
mockFetch({ 'POST /api/v1/auth/login': () => session('tok9') })
await login('tom', 'secret123')
expect(audio.src).toBe('')
})

155
web/src/player/engine.ts Normal file
View file

@ -0,0 +1,155 @@
import { mediaUrl, onTokenChange } from '@/auth/session'
import { currentTrack, usePlayer, type PlayerState } from './store'
export type AudioEvent = 'timeupdate' | 'ended' | 'error' | 'loadedmetadata'
/** The part of an audio element the engine uses, so that tests can stand in for it. */
export interface AudioLike {
src: string
currentTime: number
duration: number
paused: boolean
play(): Promise<void>
pause(): void
addEventListener(type: AudioEvent, fn: () => void): void
removeEventListener(type: string, fn: () => void): void
}
export type FinishType = 'complete' | 'skip' | 'play'
export interface EngineHooks {
/** A play of a track begins. */
onStart?(trackId: number): void
/** Time that was really listened to, in milliseconds (never more than 2000 at once). */
onPlayed?(deltaMs: number): void
/** The play ends: `complete` when the track reached its end, `skip` when the listener moved on. */
onFinish?(type: FinishType): void
}
/** The largest step of `timeupdate` that counts as listening; a bigger one is a seek. */
const MAX_STEP_MS = 2000
const streamUrl = (trackId: number) => mediaUrl(`/tracks/${trackId}/stream`)
/**
* Drives an audio element from the player store: loads the current track, plays and pauses, seeks,
* advances when a track ends, and swaps the URL when the access token is renewed without losing the place.
*/
export function createEngine(audio: AudioLike, hooks: EngineHooks = {}): { destroy(): void } {
const initial = usePlayer.getState()
let loadedId: number | null = null
let loadedPlayId = initial.playId
let loadedSeekId = initial.seekId
let finished = true
let playedMs = 0
let lastTime = 0
let pendingRestore: { time: number; resume: boolean } | null = null
function play() {
audio.play().catch(() => usePlayer.setState({ playing: false })) // the browser refused: wait for a click
}
function load(state: PlayerState) {
if (loadedId !== null && !finished && playedMs > 0) hooks.onFinish?.('skip')
const track = currentTrack(state)
loadedPlayId = state.playId
loadedSeekId = state.seekId
pendingRestore = null
playedMs = 0
lastTime = 0
if (!track) {
audio.pause()
audio.src = ''
loadedId = null
finished = true
return
}
audio.src = streamUrl(track.id)
loadedId = track.id
finished = false
hooks.onStart?.(track.id)
if (state.playing) play()
}
function seek(state: PlayerState, previous: PlayerState) {
loadedSeekId = state.seekId
const ms = state.seekMs ?? 0
audio.currentTime = ms / 1000
lastTime = ms
if (finished && ms === 0 && loadedId !== null) {
// The track ran to its end and starts over: that is a new play.
finished = false
playedMs = 0
hooks.onStart?.(loadedId)
}
if (state.playing && state.playing === previous.playing) play()
}
function sync(state: PlayerState, previous: PlayerState) {
const track = currentTrack(state)
if ((track?.id ?? null) !== loadedId || state.playId !== loadedPlayId) {
load(state)
return
}
if (state.seekId !== loadedSeekId) seek(state, previous)
if (state.playing !== previous.playing) {
if (state.playing) play()
else audio.pause()
}
}
const unsubscribeStore = usePlayer.subscribe(sync)
sync(initial, { ...initial, queue: [], playId: initial.playId - 1 })
const unsubscribeToken = onTokenChange(() => {
if (loadedId === null) return
pendingRestore = { time: audio.currentTime, resume: usePlayer.getState().playing }
audio.src = streamUrl(loadedId)
})
const onLoadedMetadata = () => {
if (!pendingRestore) return
const { time, resume } = pendingRestore
pendingRestore = null
audio.currentTime = time
if (resume) play()
}
const onTimeUpdate = () => {
const ms = audio.currentTime * 1000
usePlayer.getState().tick(Math.round(ms))
const delta = ms - lastTime
lastTime = ms
if (!audio.paused && delta > 0) {
const step = Math.min(delta, MAX_STEP_MS)
playedMs += step
hooks.onPlayed?.(step)
}
}
const onEnded = () => {
if (!finished) {
finished = true
hooks.onFinish?.('complete')
}
usePlayer.getState().trackEnded()
}
const onError = () => usePlayer.setState({ playing: false })
audio.addEventListener('loadedmetadata', onLoadedMetadata)
audio.addEventListener('timeupdate', onTimeUpdate)
audio.addEventListener('ended', onEnded)
audio.addEventListener('error', onError)
return {
destroy() {
unsubscribeStore()
unsubscribeToken()
audio.removeEventListener('loadedmetadata', onLoadedMetadata)
audio.removeEventListener('timeupdate', onTimeUpdate)
audio.removeEventListener('ended', onEnded)
audio.removeEventListener('error', onError)
},
}
}

View file

@ -0,0 +1,85 @@
import { afterEach, expect, test, vi } from 'vitest'
import type { Track } from '@/api/catalog'
import { setMediaSession } from './mediaSession'
class FakeMetadata {
title = ''
artist = ''
album = ''
artwork: { src: string }[] = []
constructor(init: Partial<FakeMetadata>) {
Object.assign(this, init)
}
}
const handlers = { play: vi.fn(), pause: vi.fn(), next: vi.fn(), prev: vi.fn() }
function withMediaSession() {
const registered = new Map<string, () => void>()
const mediaSession = {
metadata: null as FakeMetadata | null,
setActionHandler: vi.fn((action: string, fn: (() => void) | null) => {
if (fn) registered.set(action, fn)
else registered.delete(action)
}),
}
vi.stubGlobal('MediaMetadata', FakeMetadata)
Object.defineProperty(navigator, 'mediaSession', { configurable: true, value: mediaSession })
return { mediaSession, registered }
}
afterEach(() => {
delete (navigator as unknown as Record<string, unknown>).mediaSession
})
const track: Track = {
id: 7,
title: 'Paranoid Android',
duration_ms: 387_000,
track_no: 2,
disc_no: 1,
album: { id: 3, title: 'OK Computer' },
artists: [
{ id: 1, name: 'Radiohead' },
{ id: 2, name: 'Guest' },
],
format: 'flac',
}
test('the lock screen shows the title, the artists and the album', () => {
const { mediaSession } = withMediaSession()
setMediaSession(track, handlers)
expect(mediaSession.metadata).toMatchObject({ title: 'Paranoid Android', artist: 'Radiohead, Guest', album: 'OK Computer' })
expect(mediaSession.metadata!.artwork[0].src).toContain('/albums/3/cover')
})
test('a track with no album and no artists still shows its title', () => {
const { mediaSession } = withMediaSession()
setMediaSession({ ...track, album: null, artists: [] }, handlers)
expect(mediaSession.metadata).toMatchObject({ title: 'Paranoid Android', artist: '', album: '' })
expect(mediaSession.metadata!.artwork).toEqual([])
})
test('the media keys are wired to the player', () => {
const { registered } = withMediaSession()
setMediaSession(track, handlers)
registered.get('play')!()
registered.get('pause')!()
registered.get('nexttrack')!()
registered.get('previoustrack')!()
expect(handlers.play).toHaveBeenCalledTimes(1)
expect(handlers.pause).toHaveBeenCalledTimes(1)
expect(handlers.next).toHaveBeenCalledTimes(1)
expect(handlers.prev).toHaveBeenCalledTimes(1)
})
test('nothing playing clears the lock screen', () => {
const { mediaSession } = withMediaSession()
setMediaSession(track, handlers)
setMediaSession(null, handlers)
expect(mediaSession.metadata).toBeNull()
})
test('a browser without the Media Session API is left alone', () => {
expect(() => setMediaSession(track, handlers)).not.toThrow()
})

View file

@ -0,0 +1,29 @@
import type { Track } from '@/api/catalog'
import { mediaUrl } from '@/auth/session'
export interface MediaKeyHandlers {
play(): void
pause(): void
next(): void
prev(): void
}
/** Tells the operating system what is playing (lock screen, media keys). Does nothing where the API is missing. */
export function setMediaSession(track: Track | null, handlers: MediaKeyHandlers): void {
const session = navigator.mediaSession as MediaSession | undefined
if (!session) return
if (!track) {
session.metadata = null
return
}
session.metadata = new MediaMetadata({
title: track.title,
artist: track.artists.map((a) => a.name).join(', '),
album: track.album?.title ?? '',
artwork: track.album ? [{ src: mediaUrl(`/albums/${track.album.id}/cover`) }] : [],
})
session.setActionHandler('play', handlers.play)
session.setActionHandler('pause', handlers.pause)
session.setActionHandler('nexttrack', handlers.next)
session.setActionHandler('previoustrack', handlers.prev)
}

View file

@ -0,0 +1,27 @@
import { useEffect } from 'react'
import { createEngine } from './engine'
import { setMediaSession } from './mediaSession'
import { currentTrack, usePlayer } from './store'
/** Mounts the audio engine once for the whole app, and keeps the media keys and lock screen in step. */
export function usePlayerEngine(): void {
useEffect(() => {
const audio = new Audio()
const engine = createEngine(audio)
const keys = {
play: () => !usePlayer.getState().playing && usePlayer.getState().togglePlay(),
pause: () => usePlayer.getState().playing && usePlayer.getState().togglePlay(),
next: () => usePlayer.getState().next(),
prev: () => usePlayer.getState().prev(),
}
const stopMediaSession = usePlayer.subscribe((state, previous) => {
const track = currentTrack(state)
if (track?.id !== currentTrack(previous)?.id) setMediaSession(track, keys)
})
return () => {
stopMediaSession()
engine.destroy()
audio.pause()
}
}, [])
}