Merge pull request 'New look of the web app, part 2: the player with a live spectrogram' (#145) from feat/ui-player into main

This commit is contained in:
squidd 2026-11-13 17:19:29 +01:00
commit f99d2bddcc
14 changed files with 417 additions and 20 deletions

View file

@ -343,7 +343,7 @@ Back up the database and `sonda.toml`. Your music stays wherever you keep it.
## Web app
A web client lives in `web/` (React, Vite and shadcn/ui). It talks only to the Sonda server: no CDN, no external fonts, no analytics. With the app built into the binary (`make build`, or the Docker image) `sondad` serves it: open the address of the server, for example `http://127.0.0.1:8080`, and sign in. The page carries a strict Content-Security-Policy (only resources of the server itself, no inline scripts), cannot be framed and sends no referrer, and a link inside the app (`/admin/users`) works when you reload it.
A web client lives in `web/` (React, Vite and shadcn/ui). It talks only to the Sonda server: no CDN, no external fonts, no analytics. With the app built into the binary (`make build`, or the Docker image) `sondad` serves it: open the address of the server, for example `http://127.0.0.1:8080`, and sign in. The page carries a strict Content-Security-Policy (only resources of the server itself, no inline scripts), cannot be framed and sends no referrer, and a link inside the app (`/admin/users`) works when you reload it. The player draws a live spectrogram of what is playing, in the browser, from the sound itself (Web Audio): the last seconds, low notes at the bottom, in the colour of this server or, for a friend's track, in the colour of the friend. It listens to the sound and changes nothing of it, and it is drawn only while something plays.
To work on the interface itself, run the Vite dev server next to a running `sondad` (set `SONDA_URL` to where it listens: the default is `http://127.0.0.1:8080`):

View file

@ -0,0 +1,21 @@
import { useTranslation } from 'react-i18next'
import { useFriends } from '@/api/friends'
import { cn } from '@/lib/utils'
/**
* The name of the friend whose server a track comes from, in the colour of what comes from elsewhere. Nothing while
* the friends are not known yet: a track never shows a wrong name.
*/
export default function FriendChip({ friend, className }: { friend: number; className?: string }) {
const { t } = useTranslation()
const name = useFriends().data?.find((f) => f.id === friend)?.name
if (!name) return null
return (
<span
aria-label={t('player.fromFriend', { name })}
className={cn('shrink-0 rounded-full border border-friend px-2.5 text-[13px] leading-5 font-semibold text-friend', className)}
>
{name}
</span>
)
}

View file

@ -0,0 +1,27 @@
import { render, screen } from '@testing-library/react'
import { beforeEach, expect, test, vi } from 'vitest'
import { initI18n } from '@/i18n'
import Spectrogram from './Spectrogram'
beforeEach(async () => {
vi.spyOn(navigator, 'language', 'get').mockReturnValue('en-US')
await initI18n()
})
test('it is a picture with a name, and a canvas where the browser can draw', () => {
render(<Spectrogram className="h-10 w-40" />)
const picture = screen.getByRole('img', { name: 'Spectrogram of what is playing' })
expect(picture.querySelector('canvas')).not.toBeNull()
})
test('where the browser has no Web Audio it draws nothing and breaks nothing', () => {
vi.stubGlobal('AudioContext', undefined)
expect(() => render(<Spectrogram className="h-10 w-40" />)).not.toThrow()
})
test('it takes the colour of this server, or of a friend', () => {
const { rerender } = render(<Spectrogram />)
expect(screen.getByRole('img').className).toContain('text-primary')
rerender(<Spectrogram friend />)
expect(screen.getByRole('img').className).toContain('text-friend')
})

View file

@ -0,0 +1,91 @@
import { useEffect, useRef } from 'react'
import { useTranslation } from 'react-i18next'
import { hasAnalyser, readBins } from '@/player/analyser'
import { currentTrack, usePlayer } from '@/player/store'
import { ColumnBuffer, rowsFromBins } from '@/player/spectrum'
import { cn } from '@/lib/utils'
/** A new column every this many milliseconds (every quarter of a second with reduced motion: it is a picture, not a show). */
const FRAME_MS = 80
const REDUCED_FRAME_MS = 250
function colourOf(canvas: HTMLCanvasElement): [number, number, number] {
const match = /rgba?\(\s*(\d+)[,\s]+(\d+)[,\s]+(\d+)/.exec(getComputedStyle(canvas).color)
return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : [255, 255, 255]
}
function draw(canvas: HTMLCanvasElement, columns: number[][], rows: number) {
const ctx = canvas.getContext('2d')
if (!ctx) return
const ratio = window.devicePixelRatio || 1
const width = Math.round(canvas.clientWidth * ratio)
const height = Math.round(canvas.clientHeight * ratio)
if (canvas.width !== width) canvas.width = width
if (canvas.height !== height) canvas.height = height
ctx.clearRect(0, 0, width, height)
const [r, g, b] = colourOf(canvas)
const gap = 2 * ratio
const cols = columns.length
const cellW = (width - gap * (cols - 1)) / cols
const cellH = (height - gap * (rows - 1)) / rows
for (let c = 0; c < cols; c++) {
for (let row = 0; row < rows; row++) {
const level = columns[c][row]
ctx.fillStyle = `rgba(${r}, ${g}, ${b}, ${(0.08 + 0.92 * Math.pow(level, 1.25)).toFixed(2)})`
ctx.fillRect(c * (cellW + gap), height - (row + 1) * cellH - row * gap, cellW, cellH)
}
}
}
interface SpectrogramProps {
/** How many columns it holds: the last seconds, the newest on the right. */
columns?: number
/** How many rows: low notes at the bottom. */
rows?: number
/** The track is a friend's: the colour is the friend's. */
friend?: boolean
className?: string
}
/**
* A spectrogram of what is playing, drawn from the sound itself: the last seconds, time running to the right and ending
* now, low notes at the bottom, brighter where there is more energy. It is drawn only while something plays and the page
* is in view, and where the browser cannot listen to the sound it stays empty. It is a picture, with a name.
*/
export default function Spectrogram({ columns = 48, rows = 12, friend = false, className }: SpectrogramProps) {
const { t } = useTranslation()
const canvas = useRef<HTMLCanvasElement>(null)
const playing = usePlayer((s) => s.playing)
const now = usePlayer(currentTrack)
const key = now ? `${now.friend ?? 0}:${now.id}` : ''
useEffect(() => {
const el = canvas.current
if (!el) return
const buffer = new ColumnBuffer(columns, rows)
draw(el, buffer.columns(), rows)
if (!playing) return
const reduced = typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches
const every = reduced ? REDUCED_FRAME_MS : FRAME_MS
let last = 0
let frame = 0
const tick = (at: number) => {
frame = requestAnimationFrame(tick)
if (document.hidden || at - last < every || !hasAnalyser()) return
last = at
const bins = readBins()
if (!bins) return
buffer.push(rowsFromBins(bins, rows))
draw(el, buffer.columns(), rows)
}
frame = requestAnimationFrame(tick)
return () => cancelAnimationFrame(frame)
// A new track starts from an empty picture.
}, [playing, key, columns, rows])
return (
<div role="img" aria-label={t('player.spectrogram')} className={cn(friend ? 'text-friend' : 'text-primary', className)}>
<canvas ref={canvas} aria-hidden="true" className="size-full" />
</div>
)
}

View file

@ -3,8 +3,10 @@ import { useEffect } from 'react'
import { useTranslation } from 'react-i18next'
import { Link } from 'react-router-dom'
import Cover from '@/components/Cover'
import FriendChip from '@/components/FriendChip'
import FullscreenButton from '@/components/FullscreenButton'
import Scrubber from '@/components/Scrubber'
import Spectrogram from '@/components/Spectrogram'
import TrackRow from '@/components/TrackRow'
import VolumeControl from '@/components/VolumeControl'
import { Button } from '@/components/ui/button'
@ -74,7 +76,7 @@ export default function NowPlaying() {
<DialogTitle className="text-4xl leading-tight font-extrabold tracking-tight md:text-6xl">
{track.title}
</DialogTitle>
<p className="text-xl font-semibold">
<p className="flex flex-wrap items-center gap-x-3 gap-y-1 text-xl font-semibold">
{track.artists.length === 0
? '—'
: track.artists.map((a, i) => (
@ -85,6 +87,7 @@ export default function NowPlaying() {
</Link>
</span>
))}
{track.friend !== undefined && <FriendChip friend={track.friend} className="text-sm font-semibold" />}
</p>
{track.album && (
<Link
@ -97,6 +100,8 @@ export default function NowPlaying() {
)}
</div>
<Spectrogram columns={72} rows={16} friend={track.friend !== undefined} className="h-36 w-full" />
<NowPlayingSeek durationMs={track.duration_ms} />
<PlayerControls large />

View file

@ -1,4 +1,5 @@
import { Profiler } from 'react'
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
import { act, fireEvent, render, screen, within } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { MemoryRouter } from 'react-router-dom'
@ -12,6 +13,7 @@ import { initI18n } from '@/i18n'
import { usePlayer } from '@/player/store'
import { useNowPlayingUi } from '@/player/ui'
import { fakeFullscreen } from '@/test/fullscreen'
import { mockFetch } from '@/test/mockFetch'
import PlayerBar from './PlayerBar'
import PlayerControls from './PlayerControls'
@ -51,11 +53,14 @@ beforeEach(async () => {
})
function renderBar(extra?: React.ReactNode) {
mockFetch({ 'GET /api/v1/friends': () => ({ friends: [{ id: 3, name: 'Anna' }] }) })
return render(
<MemoryRouter>
<PlayerBar />
{extra}
</MemoryRouter>,
<QueryClientProvider client={new QueryClient({ defaultOptions: { queries: { retry: false } } })}>
<MemoryRouter>
<PlayerBar />
{extra}
</MemoryRouter>
</QueryClientProvider>,
)
}
@ -355,3 +360,41 @@ test('a local list does not mark a row because a friend’s track with the same
)
expect(screen.getByRole('button', { name: /Song 1/ })).not.toHaveAttribute('aria-current')
})
test('the play button is round, and teal for this server’s music', () => {
act(() => usePlayer.getState().playTracks([a]))
renderBar()
const play = screen.getByRole('button', { name: 'Pause' })
expect(play).toHaveClass('rounded-full', 'bg-primary')
expect(play).not.toHaveClass('bg-friend')
})
test('a friend’s music has the play button of the friend colour and says whose it is', async () => {
act(() => usePlayer.getState().playTracks([theirs(1)]))
renderBar()
expect(screen.getByRole('button', { name: 'Pause' })).toHaveClass('bg-friend')
expect(await screen.findByLabelText('From Anna’s server')).toHaveTextContent('Anna')
})
test('this server’s own music carries no name of a friend', async () => {
act(() => usePlayer.getState().playTracks([a]))
renderBar()
await screen.findByText('Song 1')
expect(screen.queryByLabelText(/server/)).not.toBeInTheDocument()
})
test('the bar and the full-screen player both show the spectrogram of what plays', async () => {
act(() => usePlayer.getState().playTracks([a]))
renderBar()
expect(screen.getAllByRole('img', { name: 'Spectrogram of what is playing' })).toHaveLength(1)
await userEvent.click(screen.getByRole('button', { name: 'Open the full-screen player' }))
// The full-screen player covers the page: what is behind it is not reachable while it is open.
expect(within(screen.getByRole('dialog')).getAllByRole('img', { name: 'Spectrogram of what is playing' })).toHaveLength(1)
})
test('the full-screen player says whose music a friend’s track is', async () => {
act(() => usePlayer.getState().playTracks([theirs(1)]))
renderBar()
await userEvent.click(screen.getByRole('button', { name: 'Open the full-screen player' }))
expect((await screen.findAllByLabelText('From Anna’s server')).length).toBeGreaterThanOrEqual(2)
})

View file

@ -4,8 +4,10 @@ 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'
import Scrubber from '@/components/Scrubber'
import Spectrogram from '@/components/Spectrogram'
import VolumeControl from '@/components/VolumeControl'
import { Button } from '@/components/ui/button'
import { formatTime } from '@/lib/time'
@ -67,17 +69,20 @@ export default function PlayerBar() {
<button type="button" onClick={() => setOpen(true)} className="truncate text-left font-bold">
{track.title}
</button>
<span className="truncate text-sm text-muted-foreground">
{track.artists.length === 0
? '—'
: track.artists.map((a, i) => (
<span key={a.id}>
{i > 0 && ', '}
<Link to={artistHref(track, a)} className="hover:underline">
{a.name}
</Link>
</span>
))}
<span className="flex min-w-0 items-center gap-2 text-sm text-muted-foreground">
<span className="truncate">
{track.artists.length === 0
? '—'
: track.artists.map((a, i) => (
<span key={a.id}>
{i > 0 && ', '}
<Link to={artistHref(track, a)} className="hover:underline">
{a.name}
</Link>
</span>
))}
</span>
{track.friend !== undefined && <FriendChip friend={track.friend} />}
</span>
</div>
</>
@ -93,6 +98,7 @@ export default function PlayerBar() {
<PlayerSeek track={track} />
<div className="player-extras flex items-center justify-end max-sm:hidden">
<Spectrogram columns={28} rows={6} friend={track?.friend !== undefined} className="mr-3 h-10 w-36 max-lg:hidden" />
<VolumeControl />
<FullscreenButton />
<Button

View file

@ -8,6 +8,8 @@ import { currentTrack, usePlayer } from '@/player/store'
export default function PlayerControls({ large = false }: { large?: boolean }) {
const { t } = useTranslation()
const none = usePlayer((s) => currentTrack(s) === null)
// A friend's track has the play button of the friend colour, so that what comes from elsewhere is told apart.
const friend = usePlayer((s) => currentTrack(s)?.friend !== undefined)
const playing = usePlayer((s) => s.playing)
const shuffle = usePlayer((s) => s.shuffle)
const repeat = usePlayer((s) => s.repeat)
@ -35,7 +37,11 @@ export default function PlayerControls({ large = false }: { large?: boolean }) {
<SkipBack />
</Button>
<Button
className={cn(large ? 'size-16' : 'size-11', 'rounded-md')}
className={cn(
large ? 'size-[72px]' : 'size-12',
'rounded-full',
friend && 'bg-friend text-friend-foreground hover:bg-friend/80',
)}
aria-label={playing ? t('player.pause') : t('player.play')}
disabled={none}
onClick={togglePlay}

View file

@ -51,7 +51,9 @@
"nowPlaying": "Now playing",
"volume": "Volume",
"mute": "Mute",
"unmute": "Unmute"
"unmute": "Unmute",
"spectrogram": "Spectrogram of what is playing",
"fromFriend": "From {{name}}’s server"
},
"settings": {
"account": "Account",

View file

@ -51,7 +51,9 @@
"nowPlaying": "In riproduzione",
"volume": "Volume",
"mute": "Silenzia",
"unmute": "Riattiva l'audio"
"unmute": "Riattiva l'audio",
"spectrogram": "Spettrogramma di ciò che sta suonando",
"fromFriend": "Dal server di {{name}}"
},
"settings": {
"account": "Account",

View file

@ -0,0 +1,64 @@
/**
* The ear of the player: the audio element is passed through an analyser, which tells how loud each pitch is at this
* moment. It is made the first time something plays (the browser lets an audio context start only after the person
* did something), and it only listens: the sound goes on to the speakers unchanged. Where the browser has no Web
* Audio there is no analyser and the spectrogram stays quiet.
*
* The audio comes from this server for every track, a friend's included, so it is never cross-origin and the analyser
* is never given silence for that reason.
*/
interface Ear {
context: AudioContext
analyser: AnalyserNode
bins: Uint8Array<ArrayBuffer>
}
let ear: Ear | null = null
let tried = false
type AudioContextConstructor = typeof AudioContext
/** Connects the audio element to an analyser, once. Safe to call at every play. */
export function attachAnalyser(audio: HTMLMediaElement): void {
if (ear) {
void ear.context.resume?.()
return
}
if (tried) return
tried = true
const Ctx: AudioContextConstructor | undefined =
typeof window === 'undefined' ? undefined : (window.AudioContext ?? (window as unknown as { webkitAudioContext?: AudioContextConstructor }).webkitAudioContext)
if (!Ctx) return
try {
const context = new Ctx()
const analyser = context.createAnalyser()
analyser.fftSize = 512
analyser.smoothingTimeConstant = 0.6
const source = context.createMediaElementSource(audio)
source.connect(analyser)
analyser.connect(context.destination)
ear = { context, analyser, bins: new Uint8Array(analyser.frequencyBinCount) }
void context.resume?.()
} catch {
ear = null // the sound plays as it did, without the picture
}
}
/** How loud each pitch is now (0 to 255 for each of the bins, lowest first), or null when nothing listens. */
export function readBins(): Uint8Array | null {
if (!ear) return null
ear.analyser.getByteFrequencyData(ear.bins)
return ear.bins
}
/** True once an analyser is connected. */
export function hasAnalyser(): boolean {
return ear !== null
}
/** For tests: forget the analyser. */
export function resetAnalyser(): void {
ear = null
tried = false
}

View file

@ -0,0 +1,65 @@
import { expect, test } from 'vitest'
import { ColumnBuffer, rowEdges, rowsFromBins } from './spectrum'
test('the rows cover every bin once, from the lowest to the highest, each with at least one', () => {
for (const [bins, rows] of [[256, 16], [256, 6], [128, 12], [32, 16]] as const) {
const edges = rowEdges(bins, rows)
expect(edges).toHaveLength(rows + 1)
expect(edges[0]).toBe(1) // bin 0 is the level of silence, not a note
expect(edges[rows]).toBe(bins)
for (let i = 0; i < rows; i++) expect(edges[i + 1]).toBeGreaterThan(edges[i])
}
})
test('low notes get fewer bins than high ones, as the ear hears them', () => {
const edges = rowEdges(256, 16)
expect(edges[2] - edges[1]).toBeLessThan(edges[16] - edges[15])
})
test('silence is nothing and a full signal is everything, in every row', () => {
expect(rowsFromBins(new Uint8Array(256), 16)).toEqual(new Array(16).fill(0))
expect(rowsFromBins(new Uint8Array(256).fill(255), 16)).toEqual(new Array(16).fill(1))
})
test('a single note lights the row that holds it and no other', () => {
const bins = new Uint8Array(256)
bins[100] = 255
const rows = rowsFromBins(bins, 16)
const edges = rowEdges(256, 16)
const lit = rows.map((v, i) => (v > 0 ? i : -1)).filter((i) => i >= 0)
expect(lit).toHaveLength(1)
expect(edges[lit[0]]).toBeLessThanOrEqual(100)
expect(edges[lit[0] + 1]).toBeGreaterThan(100)
expect(rows[lit[0]]).toBe(1)
})
test('a row shows its loudest bin, not the average', () => {
const bins = new Uint8Array(256)
bins[200] = 102
bins[201] = 0
expect(Math.max(...rowsFromBins(bins, 8))).toBeCloseTo(0.4, 5)
})
test('anything that is not a signal gives silence instead of an error', () => {
expect(rowsFromBins(new Uint8Array(0), 8)).toEqual(new Array(8).fill(0))
})
test('the buffer keeps the last columns, oldest first, and pads with silence while it fills', () => {
const buffer = new ColumnBuffer(3, 2)
expect(buffer.columns()).toEqual([[0, 0], [0, 0], [0, 0]])
buffer.push([0.1, 0.2])
expect(buffer.columns()).toEqual([[0, 0], [0, 0], [0.1, 0.2]])
buffer.push([0.3, 0.4])
buffer.push([0.5, 0.6])
buffer.push([0.7, 0.8])
expect(buffer.columns()).toEqual([[0.3, 0.4], [0.5, 0.6], [0.7, 0.8]])
})
test('the buffer can be emptied, and a column of the wrong height is made to fit', () => {
const buffer = new ColumnBuffer(2, 3)
buffer.push([1])
buffer.push([1, 1, 1, 1])
expect(buffer.columns()).toEqual([[1, 0, 0], [1, 1, 1]])
buffer.clear()
expect(buffer.columns()).toEqual([[0, 0, 0], [0, 0, 0]])
})

View file

@ -0,0 +1,60 @@
/**
* The arithmetic of the spectrogram: turning what the browser says about the sound into a few rows of brightness, and
* keeping the last columns. It draws nothing, so it can be tested without a browser.
*/
/**
* Where each row starts among `bins` frequency bins, from bin 1 (bin 0 is the level of silence). Low notes are close
* together in the ear and far apart in the bins, so the rows are spaced as a logarithm: the lowest rows hold one bin
* each, the highest many. Every row holds at least one, and the last ends at `bins`.
*/
export function rowEdges(bins: number, rows: number): number[] {
const edges = [1]
for (let i = 1; i <= rows; i++) {
const wanted = Math.round(bins ** (i / rows))
// At least one bin more than the row before, and room left for the rows that follow.
edges.push(Math.min(Math.max(edges[i - 1] + 1, wanted), bins - (rows - i)))
}
edges[rows] = bins
return edges
}
/** From the frequency bins (0 to 255 each) to `rows` levels from 0 to 1: each row shows its loudest bin, not the average. */
export function rowsFromBins(bins: Uint8Array, rows: number): number[] {
const out = new Array<number>(rows).fill(0)
if (bins.length <= rows) return out
const edges = rowEdges(bins.length, rows)
for (let r = 0; r < rows; r++) {
let loudest = 0
for (let b = edges[r]; b < edges[r + 1]; b++) loudest = Math.max(loudest, bins[b])
out[r] = loudest / 255
}
return out
}
/** The last columns of the spectrogram, oldest first. Until it fills, the older ones are silence. */
export class ColumnBuffer {
private data: number[][] = []
private readonly cols: number
private readonly rows: number
constructor(cols: number, rows: number) {
this.cols = cols
this.rows = rows
}
push(column: number[]): void {
const fitted = Array.from({ length: this.rows }, (_, i) => column[i] ?? 0)
this.data.push(fitted)
if (this.data.length > this.cols) this.data.shift()
}
columns(): number[][] {
const silence = Array.from({ length: this.cols - this.data.length }, () => new Array<number>(this.rows).fill(0))
return [...silence, ...this.data]
}
clear(): void {
this.data = []
}
}

View file

@ -2,6 +2,7 @@ import { useEffect } from 'react'
import { sendListen } from '@/api/listens'
import { uuid } from '@/lib/uuid'
import { createEngine } from './engine'
import { attachAnalyser } from './analyser'
import { createListenReporter } from './listens'
import { trackKey } from './media'
import { setMediaSession } from './mediaSession'
@ -14,6 +15,9 @@ import { currentTrack, usePlayer } from './store'
export function usePlayerEngine(): void {
useEffect(() => {
const audio = new Audio()
// The spectrogram listens to the sound: the analyser is connected when something first plays.
const onPlay = () => attachAnalyser(audio)
audio.addEventListener('play', onPlay)
const reporter = createListenReporter({
send: sendListen,
uuid,
@ -45,6 +49,7 @@ export function usePlayerEngine(): void {
window.removeEventListener('pagehide', onPageHide)
stopMediaSession()
engine.destroy()
audio.removeEventListener('play', onPlay)
audio.pause()
// The app is closing (signed out): the next person to sign in on this page must not inherit the queue.
usePlayer.getState().playTracks([])