feat: the seek bar shows the waveform of a friend's track

A friend's server works out the peaks of a track in a shared library and gives
them to a signed friend (GET /peer/tracks/{id}/peaks). This server asks for them
and passes them on to the listener after checking them: 1 to 1000 levels from 0
to 255, as many as the count says (GET /friends/{friend}/tracks/{id}/peaks). The
player uses it for a friend's track, so its bar is no longer flat.
This commit is contained in:
tgiachi 2026-11-13 19:46:37 +01:00
commit 7243fe7a04
6 changed files with 862 additions and 33 deletions

View file

@ -41,10 +41,37 @@ test('a track whose shape cannot be had is left alone: no shape, and no asking a
expect(calls).toHaveLength(1)
})
test('it asks nothing when it is told not to (a friend’s track, or nothing playing)', async () => {
test('it asks nothing when it is told not to (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)
})
test('the shape of a friend’s track is asked of the friend, and is not the shape of the local track with the same id', async () => {
const theirs = { count: 2, peaks: [255, 0] }
const { calls } = mockFetch({
'GET /api/v1/friends/3/tracks/7/peaks': () => theirs,
'GET /api/v1/tracks/7/peaks': () => shape,
})
const client = new QueryClient({ defaultOptions: { queries: { retry: false } } })
const shared = ({ children }: { children: ReactNode }) => <QueryClientProvider client={client}>{children}</QueryClientProvider>
const friend = renderHook(() => usePeaks(7, { friend: 3 }), { wrapper: shared })
const local = renderHook(() => usePeaks(7), { wrapper: shared })
await waitFor(() => expect(friend.result.current).toEqual([255, 0]))
await waitFor(() => expect(local.result.current).toEqual([10, 200, 50]))
expect(calls.map((c) => c.key).sort()).toEqual(['GET /api/v1/friends/3/tracks/7/peaks', 'GET /api/v1/tracks/7/peaks'])
})
test('a friend’s track is worked out by the friend: it is asked again until it is there', async () => {
let asked = 0
mockFetch({
'GET /api/v1/friends/3/tracks/7/peaks': () => {
asked++
return asked < 2 ? new Response(JSON.stringify({ status: 'working' }), { status: 202, headers: { 'Content-Type': 'application/json' } }) : shape
},
})
const { result } = renderHook(() => usePeaks(7, { friend: 3, pollMs: 10 }), { wrapper })
await waitFor(() => expect(result.current).toEqual([10, 200, 50]))
})

View file

@ -14,19 +14,20 @@ interface Shape {
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 shape of a 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`.
* A track whose shape cannot be had stays without one. For a friend's track pass the `friend`: this server asks the
* friend's, and the track id is the friend's own.
*/
export function usePeaks(trackId: number | null, opts: { enabled?: boolean; pollMs?: number } = {}): number[] | undefined {
const { enabled = true, pollMs = POLL_MS } = opts
export function usePeaks(trackId: number | null, opts: { friend?: number; enabled?: boolean; pollMs?: number } = {}): number[] | undefined {
const { friend, enabled = true, pollMs = POLL_MS } = opts
const query = useQuery({
queryKey: ['peaks', trackId],
queryKey: ['peaks', friend ?? null, 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`),
queryFn: () => api.get<Shape | Working>(friend === undefined ? `/tracks/${trackId}/peaks` : `/friends/${friend}/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

View file

@ -1792,6 +1792,33 @@ export interface paths {
patch?: never;
trace?: never;
};
"/tracks/{id}/peaks": {
parameters: {
query?: never;
header?: never;
path: {
id: components["parameters"]["Id"];
};
cookie?: never;
};
/**
* The shape of a track, for the seek bar
* @description How loud the track is along its length, as 120 levels from 0 to 255: the loudest part is 255 whatever the volume of
* the track. The server finds it by decoding the file (MP3 and FLAC, no extra program needed), which takes a few
* seconds, so the first request for a track starts the work in the background and answers `202` with `Retry-After`;
* ask again then. It is done once for each file and worked out again if the size or the date of the file change. One
* track is worked out at a time. A file that cannot be decoded (another format, or damaged) is `waveform_unavailable`,
* and that is kept too, so it is not tried at every request.
*/
get: operations["getTrackPeaks"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/tracks/{id}/stream": {
parameters: {
query?: never;
@ -2373,6 +2400,31 @@ export interface paths {
patch?: never;
trace?: never;
};
"/peer/tracks/{id}/peaks": {
parameters: {
query?: never;
header?: never;
path: {
id: components["parameters"]["Id"];
};
cookie?: never;
};
/**
* The shape of a track of the shared libraries (called by a friend)
* @description How loud the track is along its length, as `GET /tracks/{id}/peaks` gives it, for a track that lives in a shared
* library, so that a friend's seek bar can draw it. The first request starts the work in the background and answers
* `202` with `Retry-After`; ask again then. A track that is only in libraries that are not shared is `track_not_found`;
* a file that cannot be decoded is `waveform_unavailable`.
*/
get: operations["peerGetTrackPeaks"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/peer/tracks/{id}/stream": {
parameters: {
query?: never;
@ -2555,6 +2607,94 @@ export interface paths {
patch?: never;
trace?: never;
};
"/friends/{friend}/tracks/{id}/peaks": {
parameters: {
query?: never;
header?: never;
path: {
/** @description The id from `GET /friends`. */
friend: number;
id: components["parameters"]["Id"];
};
cookie?: never;
};
/**
* The shape of a track of a friend, for the seek bar
* @description How loud a track that a friend shares is along its length, as `GET /tracks/{id}/peaks` gives it for a local track.
* This server asks the friend, signed, and passes the answer on once it has checked that it is a list of 1 to 1000
* levels from 0 to 255; anything else is `502` (`friend_unreachable`). The friend works the shape out the first time and
* answers `202` with `Retry-After`: ask again then. A file the friend cannot decode is `waveform_unavailable`. The track
* id is the friend's own.
*/
get: operations["getFriendTrackPeaks"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/friends/{friend}/tracks/{id}/stream": {
parameters: {
query?: never;
header?: never;
path: {
/** @description The id from `GET /friends`. */
friend: number;
id: components["parameters"]["Id"];
};
cookie?: never;
};
/**
* Stream a track of a friend
* @description The audio of a track that a friend shares, passed on by this server: it asks the friend with a request signed by its
* own key and sends the bytes on, so the listener's browser talks to this server only, and the friend sees this server
* and nothing of the listener. `Range` and the conditional headers are passed to the friend, so a player can seek.
* Only audio is passed on, with `Content-Type`, `Content-Length`, `Content-Range`, `Accept-Ranges` and `Last-Modified`
* and nothing else of what the friend sends. Streaming never records a listen here, and a friend's track never counts
* for taste. The track id is the friend's own.
*
* Like the stream of a local track, this accepts the access token as the `access_token` query parameter. A header, when
* present, always wins. A friend that already has as many streams open as its admin allows is a `429`
* (`friend_busy`).
*/
get: operations["streamFriendTrack"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
"/friends/{friend}/albums/{id}/cover": {
parameters: {
query?: never;
header?: never;
path: {
/** @description The id from `GET /friends`. */
friend: number;
id: components["parameters"]["Id"];
};
cookie?: never;
};
/**
* The cover of an album of a friend
* @description The cover of an album that a friend shares, passed on like the stream. Only a JPEG is passed on. The friend gives a
* cover only once it was built on its server from the audio files of the album, so an album may have none yet
* (`cover_not_found`): the listener then sees the usual placeholder. Accepts the access token as the `access_token`
* query parameter, like the cover of a local album.
*/
get: operations["getFriendAlbumCover"];
put?: never;
post?: never;
delete?: never;
options?: never;
head?: never;
patch?: never;
trace?: never;
};
}
export type webhooks = Record<string, never>;
export interface components {
@ -3632,6 +3772,12 @@ export interface components {
*/
bytes: number;
};
Peaks: {
/** @description How many levels there are (120). */
count: number;
/** @description From the start of the track to its end. */
peaks: number[];
};
FriendRef: {
/**
* Format: int64
@ -6826,6 +6972,53 @@ export interface operations {
};
};
};
getTrackPeaks: {
parameters: {
query?: never;
header?: never;
path: {
id: components["parameters"]["Id"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description The shape. */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Peaks"];
};
};
/** @description The shape is being worked out. Ask again after `Retry-After` seconds. */
202: {
headers: {
/** @description Seconds to wait. */
"Retry-After"?: number;
[name: string]: unknown;
};
content: {
"application/json": {
/** @enum {string} */
status: "working";
};
};
};
400: components["responses"]["InvalidInput"];
401: components["responses"]["Unauthorized"];
/** @description No such track (`track_not_found`), its file is not available (`file_missing`), or its shape cannot be worked out (`waveform_unavailable`). */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
streamTrack: {
parameters: {
query?: never;
@ -7882,6 +8075,54 @@ export interface operations {
};
};
};
peerGetTrackPeaks: {
parameters: {
query?: never;
header?: never;
path: {
id: components["parameters"]["Id"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description The shape. */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Peaks"];
};
};
/** @description The shape is being worked out. Ask again after `Retry-After` seconds. */
202: {
headers: {
/** @description Seconds to wait. */
"Retry-After"?: number;
[name: string]: unknown;
};
content: {
"application/json": {
/** @enum {string} */
status: "working";
};
};
};
400: components["responses"]["InvalidInput"];
401: components["responses"]["FriendUnauthorized"];
403: components["responses"]["FriendNotApproved"];
/** @description No such track among the shared libraries (`track_not_found`), its file is not available (`file_missing`), its shape cannot be worked out (`waveform_unavailable`), or federation is off (`not_found`). */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
};
};
peerStreamTrack: {
parameters: {
query?: never;
@ -8242,4 +8483,183 @@ export interface operations {
502: components["responses"]["FriendUnreachable"];
};
};
getFriendTrackPeaks: {
parameters: {
query?: never;
header?: never;
path: {
/** @description The id from `GET /friends`. */
friend: number;
id: components["parameters"]["Id"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description The shape. */
200: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Peaks"];
};
};
/** @description The friend is working the shape out. Ask again after `Retry-After` seconds. */
202: {
headers: {
/** @description Seconds to wait. */
"Retry-After"?: number;
[name: string]: unknown;
};
content: {
"application/json": {
/** @enum {string} */
status: "working";
};
};
};
400: components["responses"]["InvalidInput"];
401: components["responses"]["Unauthorized"];
/** @description No such friend, or it is not active (`friend_not_found`), the friend has no such track among what it shares (`track_not_found`), or its shape cannot be worked out (`waveform_unavailable`). */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
409: components["responses"]["FriendGone"];
429: components["responses"]["FriendBusy"];
502: components["responses"]["FriendUnreachable"];
};
};
streamFriendTrack: {
parameters: {
query?: never;
header?: {
/** @description A byte range, for example `bytes=0-99`. */
Range?: string;
"If-Modified-Since"?: string;
};
path: {
/** @description The id from `GET /friends`. */
friend: number;
id: components["parameters"]["Id"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description The whole file. */
200: {
headers: {
"Accept-Ranges": components["headers"]["AcceptRanges"];
"Content-Length": components["headers"]["ContentLength"];
"Last-Modified": components["headers"]["LastModified"];
[name: string]: unknown;
};
content: {
"audio/mpeg": string;
"audio/flac": string;
};
};
/** @description The requested byte range. */
206: {
headers: {
/** @description The range sent and the size of the file, for example `bytes 0-99/40635`. */
"Content-Range"?: string;
[name: string]: unknown;
};
content: {
"audio/mpeg": string;
"audio/flac": string;
};
};
/** @description Not modified since `If-Modified-Since`. */
304: {
headers: {
[name: string]: unknown;
};
content?: never;
};
400: components["responses"]["InvalidInput"];
401: components["responses"]["Unauthorized"];
/** @description No such friend, or it is not active (`friend_not_found`), or the friend has no such track among what it shares (`track_not_found`). */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
409: components["responses"]["FriendGone"];
/** @description The range cannot be satisfied. */
416: {
headers: {
/** @description `bytes *\/<size of the file>`. */
"Content-Range"?: string;
[name: string]: unknown;
};
content?: never;
};
429: components["responses"]["FriendBusy"];
502: components["responses"]["FriendUnreachable"];
};
};
getFriendAlbumCover: {
parameters: {
query?: {
/** @description `small` or `large`. Large when absent. */
size?: "small" | "large";
};
header?: {
"If-None-Match"?: string;
};
path: {
/** @description The id from `GET /friends`. */
friend: number;
id: components["parameters"]["Id"];
};
cookie?: never;
};
requestBody?: never;
responses: {
/** @description The cover. */
200: {
headers: {
ETag: components["headers"]["ETag"];
"Cache-Control": components["headers"]["CacheControl"];
"Content-Length": components["headers"]["ContentLength"];
[name: string]: unknown;
};
content: {
"image/jpeg": string;
};
};
/** @description Not modified since `If-None-Match`. */
304: {
headers: {
[name: string]: unknown;
};
content?: never;
};
400: components["responses"]["InvalidInput"];
401: components["responses"]["Unauthorized"];
/** @description No such friend, or it is not active (`friend_not_found`), or no such album or no cover built there yet (`cover_not_found`). */
404: {
headers: {
[name: string]: unknown;
};
content: {
"application/json": components["schemas"]["Error"];
};
};
409: components["responses"]["FriendGone"];
429: components["responses"]["FriendBusy"];
502: components["responses"]["FriendUnreachable"];
};
};
}

View file

@ -26,7 +26,7 @@ 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 })
const peaks = usePeaks(track.id, { friend: track.friend })
return (
<div className="flex flex-col gap-1">
<Scrubber positionMs={positionMs} durationMs={durationMs} onSeek={seek} size="big" peaks={peaks} friend={track.friend !== undefined} />

View file

@ -58,6 +58,7 @@ function renderBar(extra?: React.ReactNode) {
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) })])),
...Object.fromEntries([1, 2, 3, 4, 5].map((n) => [`GET /api/v1/friends/3/tracks/${n}/peaks`, () => ({ count: 120, peaks: new Array(120).fill(100) })])),
}).calls
return render(
<QueryClientProvider client={new QueryClient({ defaultOptions: { queries: { retry: false } } })}>
@ -439,10 +440,10 @@ test('the seek bar of a track of this server is the shape of the track', async (
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 () => {
test('the seek bar of a friend’s track is its shape too, asked of the friend', 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)
await waitFor(() => expect(container.querySelectorAll('footer [data-bar]').length).toBe(120))
expect(calls.some((c) => c.key === 'GET /api/v1/friends/3/tracks/1/peaks')).toBe(true)
expect(calls.some((c) => c.key === 'GET /api/v1/tracks/1/peaks')).toBe(false)
})

View file

@ -36,8 +36,8 @@ function usePlayPauseKey() {
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 })
// A friend's track has its shape from the friend's server, which works it out the first time.
const peaks = usePeaks(track?.id ?? null, { friend: track?.friend })
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>