feat: the seek bar shows the waveform of the track

The seek bar of the player is the shape of the track, with the part already
heard in colour, as in the approved mockups.

- GET /tracks/{id}/peaks gives 120 levels from 0 to 255 (the loudest part is
  255 whatever the volume). The server finds them by decoding the file, MP3 with
  go-mp3 and FLAC with eaburns/flac, both in pure Go. It takes a few seconds, so
  the first request starts the work in the background and answers 202 with
  Retry-After. It is done once for each file (migration 0025), worked out again
  if the size or the date of the file change, one track at a time so that a NAS
  is not kept busy, and a file that cannot be decoded is remembered as such. A
  track deleted while its file is being decoded is not an error.
- The seek bar of the player bar and of the full-screen player draws the shape
  and asks again every few seconds until it is there. Until then, and for a
  friend's track, which has none, the bar is flat. The heard part is teal, or
  the friend colour. It is still a native range input, 44 pixels high in the
  bar.
- OpenAPI path and schema, contract test, tests with real MP3 and FLAC files,
  and a real server checked: a 4-minute MP3 is ready in about a second and a
  half, a 12 MB FLAC in three, and asking again takes a millisecond.
This commit is contained in:
tgiachi 2026-11-13 17:35:00 +01:00
commit bfa3e6e458
7 changed files with 1213 additions and 55 deletions

View file

@ -0,0 +1,50 @@
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { renderHook, waitFor } from '@testing-library/react'
import type { ReactNode } from 'react'
import { expect, test } from 'vitest'
import { apiError, mockFetch } from '@/test/mockFetch'
import { usePeaks } from './peaks'
function wrapper({ children }: { children: ReactNode }) {
return <QueryClientProvider client={new QueryClient({ defaultOptions: { queries: { retry: false } } })}>{children}</QueryClientProvider>
}
const shape = { count: 3, peaks: [10, 200, 50] }
test('it gives the shape of the track once the server has it', async () => {
mockFetch({ 'GET /api/v1/tracks/7/peaks': () => shape })
const { result } = renderHook(() => usePeaks(7), { wrapper })
await waitFor(() => expect(result.current).toEqual([10, 200, 50]))
})
test('while the server works it out, it asks again until it is there', async () => {
let asked = 0
const { calls } = mockFetch({
'GET /api/v1/tracks/7/peaks': () => {
asked++
return asked < 3
? new Response(JSON.stringify({ status: 'working' }), { status: 202, headers: { 'Content-Type': 'application/json' } })
: shape
},
})
const { result } = renderHook(() => usePeaks(7, { pollMs: 10 }), { wrapper })
expect(result.current).toBeUndefined()
await waitFor(() => expect(result.current).toEqual([10, 200, 50]))
expect(calls.filter((c) => c.key === 'GET /api/v1/tracks/7/peaks')).toHaveLength(3)
})
test('a track whose shape cannot be had is left alone: no shape, and no asking again', async () => {
const { calls } = mockFetch({ 'GET /api/v1/tracks/7/peaks': () => apiError(404, 'waveform_unavailable') })
const { result } = renderHook(() => usePeaks(7, { pollMs: 10 }), { wrapper })
await new Promise((r) => setTimeout(r, 80))
expect(result.current).toBeUndefined()
expect(calls).toHaveLength(1)
})
test('it asks nothing when it is told not to (a friend’s track, or nothing playing)', async () => {
const { calls } = mockFetch({ 'GET /api/v1/tracks/7/peaks': () => shape })
const { result } = renderHook(() => usePeaks(7, { enabled: false }), { wrapper })
await new Promise((r) => setTimeout(r, 40))
expect(result.current).toBeUndefined()
expect(calls).toHaveLength(0)
})

34
web/src/api/peaks.ts Normal file
View file

@ -0,0 +1,34 @@
import { useQuery } from '@tanstack/react-query'
import { ApiError, api } from './client'
/** What the server answers while it is still working the shape out (202). */
interface Working {
status: 'working'
}
interface Shape {
count: number
peaks: number[]
}
/** How long to wait before asking again while the server works (it also says so in Retry-After). */
const POLL_MS = 3000
/**
* The shape of a local track, from 0 to 255 for each of its bars: how loud it is along its length. The server works it out
* the first time it is asked for, so until then this is `undefined` and the question is asked again every few seconds.
* A track whose shape cannot be had stays without one. A friend's track has none: pass `enabled: false`.
*/
export function usePeaks(trackId: number | null, opts: { enabled?: boolean; pollMs?: number } = {}): number[] | undefined {
const { enabled = true, pollMs = POLL_MS } = opts
const query = useQuery({
queryKey: ['peaks', trackId],
enabled: enabled && trackId !== null,
retry: false,
// A shape does not change while the file does not: keep it for as long as the page lives.
staleTime: Infinity,
queryFn: () => api.get<Shape | Working>(`/tracks/${trackId}/peaks`),
refetchInterval: (q) => ('status' in (q.state.data ?? {}) ? pollMs : false),
})
if (query.error instanceof ApiError || query.data === undefined || 'status' in query.data) return undefined
return query.data.peaks
}

View file

@ -0,0 +1,51 @@
import { fireEvent, render, screen } from '@testing-library/react'
import { beforeEach, expect, test, vi } from 'vitest'
import { initI18n } from '@/i18n'
import Scrubber from './Scrubber'
beforeEach(async () => {
vi.spyOn(navigator, 'language', 'get').mockReturnValue('en-US')
await initI18n()
})
const bars = (container: HTMLElement) => [...container.querySelectorAll<HTMLElement>('[data-bar]')]
test('with the shape of the track each bar is as tall as the track is loud there', () => {
const peaks = [0, 64, 128, 255]
const { container } = render(<Scrubber positionMs={0} durationMs={1000} onSeek={() => {}} size="big" peaks={peaks} />)
expect(bars(container)).toHaveLength(4)
const heights = bars(container).map((b) => parseFloat(b.style.height))
expect(heights[3]).toBe(100)
expect(heights[2]).toBeGreaterThan(heights[1])
expect(heights[1]).toBeGreaterThan(heights[0])
expect(heights[0]).toBeGreaterThan(0) // silence is still a thin line, never a gap
})
test('without the shape the bar is flat, with its bars as many as ever', () => {
const { container } = render(<Scrubber positionMs={0} durationMs={1000} onSeek={() => {}} size="big" />)
const heights = new Set(bars(container).map((b) => b.style.height))
expect(bars(container).length).toBeGreaterThanOrEqual(60)
expect(heights.size).toBe(1)
})
test('the part already heard is in colour and the rest is quiet', () => {
const { container } = render(<Scrubber positionMs={500} durationMs={1000} onSeek={() => {}} size="big" peaks={new Array(10).fill(200)} />)
const colours = bars(container).map((b) => (b.className.includes('bg-primary') ? 'on' : 'off'))
expect(colours.slice(0, 5)).toEqual(new Array(5).fill('on'))
expect(colours.slice(5)).toEqual(new Array(5).fill('off'))
})
test('a friend’s track is heard in the friend colour', () => {
const { container } = render(<Scrubber positionMs={1000} durationMs={1000} onSeek={() => {}} size="big" peaks={[100, 100]} friend />)
expect(bars(container)[0].className).toContain('bg-friend')
expect(bars(container)[0].className).not.toContain('bg-primary')
})
test('it is still a slider that is moved with the keyboard and says where it is in words', () => {
const onSeek = vi.fn()
render(<Scrubber positionMs={147_000} durationMs={387_000} onSeek={onSeek} size="bar" peaks={[1, 2, 3]} />)
const slider = screen.getByRole('slider', { name: 'Seek' })
expect(slider).toHaveAttribute('aria-valuetext', '2:27 of 6:27')
fireEvent.change(slider, { target: { value: '1000' } })
expect(onSeek).toHaveBeenCalledWith(1000)
})

View file

@ -2,54 +2,68 @@ import { useTranslation } from 'react-i18next'
import { formatTime } from '@/lib/time'
import { cn } from '@/lib/utils'
const BARS = 64
/** How many bars a track whose shape is not known yet is drawn with. */
const FLAT_BARS = 64
/** The height of those bars, and the least height of a bar of a known shape: a thin line, never a gap. */
const FLAT_HEIGHT = 18
interface ScrubberProps {
positionMs: number
durationMs: number
onSeek(ms: number): void
/** `line` is a thin bar; `bars` is a row of equal segments (a progress control, not a waveform). */
variant: 'line' | 'bars'
/** `bar` is the one of the player bar, `big` the one of the full-screen player. */
size: 'bar' | 'big'
/** How loud the track is along its length, from 0 to 255 for each bar. Not known yet: the bar is flat. */
peaks?: number[]
/** The track is a friend's: the part already heard is in the friend colour. */
friend?: boolean
}
/** The seek control of the player: always a native range input, so the keyboard and screen readers work. */
export default function Scrubber({ positionMs, durationMs, onSeek, variant }: ScrubberProps) {
/**
* The seek control of the player: the shape of the track, with the part already heard in colour. It is a native range
* input laid over the picture, so the keyboard and screen readers work, and the whole area takes a tap.
*/
export default function Scrubber({ positionMs, durationMs, onSeek, size, peaks, friend = false }: ScrubberProps) {
const { t } = useTranslation()
const disabled = !(durationMs > 0)
const max = disabled ? 1 : durationMs
const value = Math.min(Math.max(positionMs, 0), max)
const filled = (value / max) * BARS
const input = (
<input
type="range"
min={0}
max={max}
step={1}
value={value}
disabled={disabled}
aria-label={t('player.seek')}
aria-valuetext={t('player.seekValue', { position: formatTime(value), duration: formatTime(durationMs) })}
onChange={(e) => onSeek(Number(e.target.value))}
className={cn(
'cursor-pointer disabled:cursor-default',
variant === 'line' ? '-my-2 h-11 w-full accent-primary' : 'absolute inset-0 h-full w-full opacity-0',
)}
/>
)
if (variant === 'line') return input
const known = peaks !== undefined && peaks.length > 0
const count = known ? peaks.length : FLAT_BARS
const filled = (value / max) * count
return (
<div className="relative flex h-8 items-center gap-[3px] rounded-sm focus-within:outline-2 focus-within:outline-offset-2 focus-within:outline-ring">
{Array.from({ length: BARS }, (_, i) => (
<span
key={i}
aria-hidden="true"
className={cn('h-full min-w-px flex-1 rounded-[2px]', i + 0.5 <= filled ? 'bg-primary' : 'bg-input/50')}
/>
))}
{input}
<div
className={cn(
'relative flex items-center gap-[2px] rounded-sm focus-within:outline-2 focus-within:outline-offset-2 focus-within:outline-ring',
size === 'bar' ? 'h-11' : 'h-16',
)}
>
{Array.from({ length: count }, (_, i) => {
const height = known ? Math.max(FLAT_HEIGHT, Math.round((peaks[i] / 255) * 100)) : FLAT_HEIGHT
const heard = i + 0.5 <= filled
return (
<span
key={i}
data-bar
aria-hidden="true"
style={{ height: `${height}%` }}
className={cn('min-w-px flex-1 rounded-[2px]', heard ? (friend ? 'bg-friend' : 'bg-primary') : 'bg-input')}
/>
)
})}
<input
type="range"
min={0}
max={max}
step={1}
value={value}
disabled={disabled}
aria-label={t('player.seek')}
aria-valuetext={t('player.seekValue', { position: formatTime(value), duration: formatTime(durationMs) })}
onChange={(e) => onSeek(Number(e.target.value))}
className="absolute inset-0 h-full w-full cursor-pointer opacity-0 disabled:cursor-default"
/>
</div>
)
}

View file

@ -2,6 +2,7 @@ import { X } from 'lucide-react'
import { useEffect } from 'react'
import { useTranslation } from 'react-i18next'
import { Link } from 'react-router-dom'
import { usePeaks } from '@/api/peaks'
import Cover from '@/components/Cover'
import FriendChip from '@/components/FriendChip'
import FullscreenButton from '@/components/FullscreenButton'
@ -12,7 +13,7 @@ import VolumeControl from '@/components/VolumeControl'
import { Button } from '@/components/ui/button'
import { Dialog, DialogContent, DialogDescription, DialogTitle } from '@/components/ui/dialog'
import { formatTime } from '@/lib/time'
import { albumHref, artistHref } from '@/player/media'
import { albumHref, artistHref, type QueuedTrack } from '@/player/media'
import { currentTrack, usePlayer } from '@/player/store'
import { useNowPlayingUi } from '@/player/ui'
import PlayerControls from './PlayerControls'
@ -20,12 +21,14 @@ import PlayerControls from './PlayerControls'
const UP_NEXT = 3
/** The big seek bar and the times. The part of this screen that follows the playback every moment. */
function NowPlayingSeek({ durationMs }: { durationMs: number }) {
function NowPlayingSeek({ track }: { track: QueuedTrack }) {
const durationMs = track.duration_ms
const positionMs = usePlayer((s) => s.positionMs)
const seek = usePlayer((s) => s.seek)
const peaks = usePeaks(track.id, { enabled: track.friend === undefined })
return (
<div className="flex flex-col gap-1">
<Scrubber positionMs={positionMs} durationMs={durationMs} onSeek={seek} variant="bars" />
<Scrubber positionMs={positionMs} durationMs={durationMs} onSeek={seek} size="big" peaks={peaks} friend={track.friend !== undefined} />
<div className="flex justify-between text-sm text-muted-foreground tabular-nums">
<span>{formatTime(positionMs)}</span>
<span>{formatTime(durationMs)}</span>
@ -102,7 +105,7 @@ export default function NowPlaying() {
<Spectrogram columns={72} rows={16} friend={track.friend !== undefined} className="h-36 w-full" />
<NowPlayingSeek durationMs={track.duration_ms} />
<NowPlayingSeek track={track} />
<PlayerControls large />
<VolumeControl className="-mt-3" />

View file

@ -1,6 +1,6 @@
import { Profiler } from 'react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { act, fireEvent, render, screen, within } from '@testing-library/react'
import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { MemoryRouter } from 'react-router-dom'
import { beforeEach, expect, test, vi } from 'vitest'
@ -52,8 +52,13 @@ beforeEach(async () => {
useNowPlayingUi.setState({ open: false })
})
let calls: { key: string }[] = []
function renderBar(extra?: React.ReactNode) {
mockFetch({ 'GET /api/v1/friends': () => ({ friends: [{ id: 3, name: 'Anna' }] }) })
calls = mockFetch({
'GET /api/v1/friends': () => ({ friends: [{ id: 3, name: 'Anna' }] }),
...Object.fromEntries([1, 2, 3, 4, 5].map((n) => [`GET /api/v1/tracks/${n}/peaks`, () => ({ count: 120, peaks: new Array(120).fill(100) })])),
}).calls
return render(
<QueryClientProvider client={new QueryClient({ defaultOptions: { queries: { retry: false } } })}>
<MemoryRouter>
@ -66,20 +71,20 @@ function renderBar(extra?: React.ReactNode) {
// --- Scrubber ----------------------------------------------------------------------------------
test.each(['line', 'bars'] as const)('the %s scrubber seeks to the position that was chosen', (variant) => {
test.each(['bar', 'big'] as const)('the %s scrubber seeks to the position that was chosen', (size) => {
const onSeek = vi.fn()
render(<Scrubber positionMs={0} durationMs={200_000} onSeek={onSeek} variant={variant} />)
render(<Scrubber positionMs={0} durationMs={200_000} onSeek={onSeek} size={size} />)
fireEvent.change(screen.getByRole('slider', { name: 'Seek' }), { target: { value: '100000' } })
expect(onSeek).toHaveBeenCalledWith(100_000)
})
test('the scrubber says where it is in words', () => {
render(<Scrubber positionMs={147_000} durationMs={387_000} onSeek={() => {}} variant="line" />)
render(<Scrubber positionMs={147_000} durationMs={387_000} onSeek={() => {}} size="bar" />)
expect(screen.getByRole('slider', { name: 'Seek' })).toHaveAttribute('aria-valuetext', '2:27 of 6:27')
})
test('a scrubber with no known length cannot be moved', () => {
render(<Scrubber positionMs={0} durationMs={0} onSeek={() => {}} variant="line" />)
render(<Scrubber positionMs={0} durationMs={0} onSeek={() => {}} size="bar" />)
expect(screen.getByRole('slider', { name: 'Seek' })).toBeDisabled()
})
@ -329,8 +334,8 @@ test('the controls and the title do not render again when only the position move
})
test('the seek bar of the player bar is 44 pixels high to take a thumb', () => {
render(<Scrubber positionMs={0} durationMs={1000} onSeek={() => {}} variant="line" />)
expect(screen.getByRole('slider')).toHaveClass('h-11')
render(<Scrubber positionMs={0} durationMs={1000} onSeek={() => {}} size="bar" />)
expect(screen.getByRole('slider').parentElement).toHaveClass('h-11')
})
const theirs = (n: number) => ({ ...track(n), friend: 3, album: { id: 10, title: 'Their Album' }, artists: [{ id: 5, name: 'Their Band' }] })
@ -398,3 +403,18 @@ test('the full-screen player says whose music a friend’s track is', async () =
await userEvent.click(screen.getByRole('button', { name: 'Open the full-screen player' }))
expect((await screen.findAllByLabelText('From Anna’s server')).length).toBeGreaterThanOrEqual(2)
})
test('the seek bar of a track of this server is the shape of the track', async () => {
act(() => usePlayer.getState().playTracks([a]))
const { container } = renderBar()
await waitFor(() => expect(container.querySelectorAll('footer [data-bar]').length).toBe(120))
expect(calls.some((c) => c.key === 'GET /api/v1/tracks/1/peaks')).toBe(true)
})
test('a friend’s track has a plain bar, and its shape is not asked for', async () => {
act(() => usePlayer.getState().playTracks([theirs(1)]))
const { container } = renderBar()
await screen.findByLabelText('From Anna’s server')
expect(container.querySelectorAll('footer [data-bar]').length).toBe(64)
expect(calls.some((c) => c.key.includes('/peaks'))).toBe(false)
})

View file

@ -2,7 +2,6 @@ import { ListMusic } from 'lucide-react'
import { useEffect } from 'react'
import { useTranslation } from 'react-i18next'
import { Link } from 'react-router-dom'
import type { Track } from '@/api/catalog'
import Cover from '@/components/Cover'
import FriendChip from '@/components/FriendChip'
import FullscreenButton from '@/components/FullscreenButton'
@ -10,8 +9,9 @@ import Scrubber from '@/components/Scrubber'
import Spectrogram from '@/components/Spectrogram'
import VolumeControl from '@/components/VolumeControl'
import { Button } from '@/components/ui/button'
import { usePeaks } from '@/api/peaks'
import { formatTime } from '@/lib/time'
import { artistHref } from '@/player/media'
import { artistHref, type QueuedTrack } from '@/player/media'
import { currentTrack, usePlayer } from '@/player/store'
import { useNowPlayingUi } from '@/player/ui'
import NowPlaying from './NowPlaying'
@ -33,14 +33,23 @@ function usePlayPauseKey() {
}
/** The position, the seek bar and the length. The only part of the bar that follows the playback every moment. */
function PlayerSeek({ track }: { track: Track | null }) {
function PlayerSeek({ track }: { track: QueuedTrack | null }) {
const positionMs = usePlayer((s) => s.positionMs)
const seek = usePlayer((s) => s.seek)
// A friend's track has no shape here (the friend's server would have to work it out): its bar is flat.
const peaks = usePeaks(track?.id ?? null, { enabled: track !== null && track.friend === undefined })
return (
<div className="player-seek flex w-full max-w-xl items-center gap-3 justify-self-center text-[13px] text-muted-foreground tabular-nums">
<span>{formatTime(track ? positionMs : 0)}</span>
<div className="flex-1">
<Scrubber positionMs={positionMs} durationMs={track?.duration_ms ?? 0} onSeek={seek} variant="line" />
<Scrubber
positionMs={positionMs}
durationMs={track?.duration_ms ?? 0}
onSeek={seek}
size="bar"
peaks={peaks}
friend={track?.friend !== undefined}
/>
</div>
<span>{formatTime(track?.duration_ms ?? 0)}</span>
</div>