From 92d9c8ed780b82877eae28b35621c5147c90e4d9 Mon Sep 17 00:00:00 2001 From: tgiachi Date: Thu, 12 Nov 2026 11:26:54 +0100 Subject: [PATCH] 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 --- web/src/player/engine.test.ts | 250 ++++++++++++++++++++++++++++ web/src/player/engine.ts | 155 +++++++++++++++++ web/src/player/mediaSession.test.ts | 85 ++++++++++ web/src/player/mediaSession.ts | 29 ++++ web/src/player/usePlayer.ts | 27 +++ 5 files changed, 546 insertions(+) create mode 100644 web/src/player/engine.test.ts create mode 100644 web/src/player/engine.ts create mode 100644 web/src/player/mediaSession.test.ts create mode 100644 web/src/player/mediaSession.ts create mode 100644 web/src/player/usePlayer.ts diff --git a/web/src/player/engine.test.ts b/web/src/player/engine.test.ts new file mode 100644 index 0000000..c970fcc --- /dev/null +++ b/web/src/player/engine.test.ts @@ -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 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('') +}) diff --git a/web/src/player/engine.ts b/web/src/player/engine.ts new file mode 100644 index 0000000..370e9a2 --- /dev/null +++ b/web/src/player/engine.ts @@ -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 + 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) + }, + } +} diff --git a/web/src/player/mediaSession.test.ts b/web/src/player/mediaSession.test.ts new file mode 100644 index 0000000..faf90ec --- /dev/null +++ b/web/src/player/mediaSession.test.ts @@ -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) { + Object.assign(this, init) + } +} + +const handlers = { play: vi.fn(), pause: vi.fn(), next: vi.fn(), prev: vi.fn() } + +function withMediaSession() { + const registered = new Map 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).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() +}) diff --git a/web/src/player/mediaSession.ts b/web/src/player/mediaSession.ts new file mode 100644 index 0000000..5881db0 --- /dev/null +++ b/web/src/player/mediaSession.ts @@ -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) +} diff --git a/web/src/player/usePlayer.ts b/web/src/player/usePlayer.ts new file mode 100644 index 0000000..e9a8797 --- /dev/null +++ b/web/src/player/usePlayer.ts @@ -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() + } + }, []) +}