vincent/gerbeur
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v4: an audio file's waveform is made once by the server, and the player seeks on one accessible scrubber — every player downloaded the whole file a second time and decoded all of it in the browser to draw 150 bars, so a long FLAC cost tens of megabytes of memory per page, and the waveform could only be clicked: no drag, no keyboard, no slider for a screen reader. GET /api/dumps/:id/waveform now answers an audio dump's peaks, which lib/ffmpeg.ts decodes with ffmpeg on first request, mono at 8 kHz and streamed, keeps beside the thumbnails as the response itself, and serves with an ETag (a ten-minute MP3 takes about a second, then a few hundred bytes). The peaks are taken by shared/waveform.ts's peaksOf, scaled to the loudest so a quiet recording fills the track, and the dump form's preview of a file not yet uploaded decodes it with the same function, at 8 kHz in an OfflineAudioContext. Scrubber replaces Waveform and SeekBar: a role="slider" that seeks where a pointer lets go, follows a drag (the clock shows where it is held), takes arrows, Home and End, and draws the bars as one path with the played part clipped by a nested svg, so it moves smoothly and a timeupdate redraws two attributes instead of 150 rects; audio without a waveform, and video, get a plain bar. MediaPlayer reads whether it plays from the element's events alone, so a click no longer reports the change twice, its handles for PlayerProvider are stable callbacks instead of refs to refs, the drag no longer reattaches every listener, and the <source> children that src made dead are gone, with the mime prop. The file, thumbnail and waveform routes resolve their dump, token and caching through lib/dump-media.ts, and what is generated from an upload is named and removed in lib/ffmpeg.ts, the custom thumbnail by dump-service's customThumbnailPath, instead of paths spelled out in each. The test setup's play() and pause() fire their events as a browser does. 277 backend tests and 684 frontend tests pass, and deno check, tsc, eslint, doc:lint and i18n:compile --strict are clean; checked in the app with a real FLAC on its dump page and in the global player at 1280 and 390px, seeking by keyboard.

Browse Source 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
khannurien
2026-10-09 13:34:22 +00:00
parent c709b56911
commit fac0e2db28
30 changed files with 1217 additions and 680 deletions
Download Patch File Download Diff File Expand all files Collapse all files

29
src/components/dump/FilePreview.tsx
View File

@@ -8,7 +8,11 @@
import { useContext } from "react";
import type { Dump } from "../../../shared/dump.ts";
import { formatBytes } from "../../utils/shared/format.ts";
import { dumpFileUrl, dumpThumbnailUrl } from "../../utils/shared/urls.ts";
import {
dumpFileUrl,
dumpThumbnailUrl,
dumpWaveformUrl,
} from "../../utils/shared/urls.ts";
import { useAuth } from "../../hooks/auth/useAuth.ts";
import {
fileArtworkUrl,
@@ -16,7 +20,8 @@ import {
usePlayFile,
} from "../../hooks/player/usePlayFile.ts";
import { MediaPlayer } from "../player/MediaPlayer.tsx";
import { Waveform } from "../player/Waveform.tsx";
import { Scrubber } from "../player/Scrubber.tsx";
import { usePeaks } from "../../hooks/player/usePeaks.ts";
import { Thumbnail } from "../shared/Thumbnail.tsx";
import {
PlayerContext,
@@ -84,7 +89,9 @@ function FilePlayButton({ dump }: { dump: Dump }) {
function AudioFilePreview({ dump }: { dump: Dump }) {
const { seekTo } = useContext(PlayerContext);
const { currentTime, duration } = useContext(PlayerTimeContext);
const { fileUrl, active, toggle } = usePlayFile(dump);
const { mediaToken: token } = useAuth();
const { active, toggle } = usePlayFile(dump);
const peaks = usePeaks({ peaksUrl: dumpWaveformUrl(dump, token) });
return (
<div
@@ -93,13 +100,13 @@ function AudioFilePreview({ dump }: { dump: Dump }) {
}`}
>
<FilePlayButton dump={dump} />
<Waveform
src={fileUrl}
<Scrubber
current={active ? currentTime : 0}
duration={active ? duration : 0}
// The player has no media to seek yet, so a first click plays from the
// start and ignores where it landed.
onSeek={(time) => active ? seekTo(time) : toggle()}
peaks={peaks}
/>
</div>
);
@@ -190,14 +197,18 @@ export function FilePreview(
</button>
);
}
return (
<MediaPlayer src={fileUrl} kind="video" mime={mime} poster={artworkUrl} />
);
return <MediaPlayer src={fileUrl} kind="video" poster={artworkUrl} />;
}
if (mime.startsWith("audio/")) {
if (useGlobal) return <AudioFilePreview dump={dump} />;
return <MediaPlayer src={fileUrl} kind="audio" mime={mime} />;
return (
<MediaPlayer
src={fileUrl}
kind="audio"
waveform={{ peaksUrl: dumpWaveformUrl(dump, token) }}
/>
);
}
if (mime === "application/pdf") {

12
src/components/dump/create/LocalFilePreview.tsx
View File

@@ -38,10 +38,18 @@ export function LocalFilePreview(
return <img src={src} alt={file.name} className="local-preview-image" />;
}
if (mime.startsWith("video/")) {
return <MediaPlayer key={src} src={src} kind="video" mime={mime} />;
return <MediaPlayer key={src} src={src} kind="video" />;
}
if (mime.startsWith("audio/")) {
return <MediaPlayer key={src} src={src} kind="audio" mime={mime} />;
// Not uploaded yet, so its waveform is decoded here.
return (
<MediaPlayer
key={src}
src={src}
kind="audio"
waveform={{ localFile: src }}
/>
);
}
return null;
}

6
src/components/player/GlobalPlayer.tsx
View File

@@ -289,7 +289,9 @@ export function GlobalPlayer(): React.JSX.Element | null {
key={current.fileUrl}
src={current.fileUrl}
kind={current.mimeType.startsWith("video/") ? "video" : "audio"}
mime={current.mimeType}
waveform={current.waveformUrl
? { peaksUrl: current.waveformUrl }
: undefined}
autoplay={autoplay}
startTime={startTime}
onPlayStateChange={onPlayStateChange}
@@ -308,8 +310,6 @@ export function GlobalPlayer(): React.JSX.Element | null {
key={current.streamUrl}
src={current.streamUrl}
kind="audio"
mime="audio/mpeg"
trackStyle="progress"
autoplay={autoplay}
startTime={startTime}
onPlayStateChange={onPlayStateChange}

153
src/components/player/MediaPlayer.tsx
View File

@@ -6,7 +6,7 @@
* @module
*/
import { useEffect, useRef, useState } from "react";
import { useCallback, useEffect, useRef, useState } from "react";
import { fmt } from "../../utils/player/duration.ts";
import { t } from "@lingui/core/macro";
import {
@@ -15,8 +15,9 @@ import {
IconPlay,
IconVolume,
} from "./PlayerIcons.tsx";
import { SeekBar } from "./SeekBar.tsx";
import { Waveform } from "./Waveform.tsx";
import { Scrubber } from "./Scrubber.tsx";
import { usePeaks } from "../../hooks/player/usePeaks.ts";
import type { PeaksSource } from "../../utils/player/waveform.ts";
import { rememberVolume, storedVolume } from "../../utils/player/volume.ts";
/** How long a playing video's controls stay after the pointer stops, in ms. */
@@ -30,8 +31,6 @@ const HIDE_DELAY = 2500;
export interface MediaPlayerProps {
src: string;
kind: "audio" | "video";
/** The `<source>` type, when known. */
mime?: string;
/** Shown before a video plays. */
poster?: string;
autoplay?: boolean;
@@ -47,10 +46,10 @@ export interface MediaPlayerProps {
*/
onError?: () => void;
/**
* "waveform" (the default for audio) decodes peaks from the source;
* "progress" draws a seek bar and never fetches the media a second time.
* Where an audio file's waveform comes from. Without it, as for a stream
* whose bytes another site serves, audio seeks on a plain bar.
*/
trackStyle?: "waveform" | "progress";
waveform?: PeaksSource;
/** Receives its seek handle while mounted, for PlayerContext's `seekTo`. */
seekRef?: { current: ((t: number) => void) | null };
/** Receives its play/pause handle while mounted, for `togglePlay`. */
@@ -58,17 +57,17 @@ export interface MediaPlayerProps {
}
/**
* Renders a media element with the site's own controls. Audio gets a waveform
* to seek on, unless `trackStyle` asks for a seek bar; video gets a seek bar, a
* fullscreen button, and controls that hide while it plays. The volume carries
* over to the next MediaPlayer, which matters since GlobalPlayer mounts a new
* one for each track.
* Renders a media element with the site's own controls. Audio seeks on its
* waveform when it has one; video gets a slim bar, a fullscreen button, and
* controls that hide while it plays. Whether it plays is read from the
* element's own events, so a media key or the OS's controls show too. The
* volume carries over to the next MediaPlayer, which matters since
* GlobalPlayer mounts a new one for each track.
*/
export function MediaPlayer(
{
src,
kind,
mime,
poster,
autoplay,
startTime,
@@ -76,7 +75,7 @@ export function MediaPlayer(
onTimeUpdate,
onEnded,
onError,
trackStyle = "waveform",
waveform,
seekRef,
toggleRef,
}: MediaPlayerProps,
@@ -85,11 +84,13 @@ export function MediaPlayer(
const [playing, setPlaying] = useState(false);
const [current, setCurrent] = useState(0);
const [duration, setDuration] = useState(0);
const [dragging, setDragging] = useState(false);
// Where the scrubber is held, which the clock shows until it lets go.
const [scrubTime, setScrubTime] = useState<number | null>(null);
const [volume, setVolume] = useState(() => storedVolume().volume);
const [muted, setMuted] = useState(() => storedVolume().muted);
const [controlsVisible, setControlsVisible] = useState(true);
const hideTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
const peaks = usePeaks(kind === "audio" ? waveform : undefined);
// The media listeners call the latest callbacks through these refs, without
// being attached again. They are written after render, as the linter wants;
@@ -106,40 +107,18 @@ export function MediaPlayer(
onErrorRef.current = onError;
});
// seekRef and toggleRef get wrappers that call these, so the handles never go
// null while the functions are replaced.
const seekToFnRef = useRef((_t: number) => {});
const toggleFnRef = useRef(() => {});
// Everything it uses is stable, so it is set once.
useEffect(() => {
seekToFnRef.current = (time: number) => {
setCurrent(time);
mediaRef.current!.currentTime = time;
};
// Both read the element alone, so they never change, and the handles given
// to PlayerProvider stay valid while this is mounted.
const seekTo = useCallback((time: number) => {
setCurrent(time);
mediaRef.current!.currentTime = time;
}, []);
// The play and pause events update the state, whoever asked.
const toggle = useCallback(() => {
const a = mediaRef.current!;
if (a.paused) a.play().catch(() => {});
else a.pause();
}, []);
// It reads `playing`, so it is replaced when that changes.
useEffect(() => {
toggleFnRef.current = () => {
const a = mediaRef.current!;
if (playing) {
a.pause();
setPlaying(false);
onPlayStateChangeRef.current?.(false);
} else {
a.play()
.then(() => {
setPlaying(true);
onPlayStateChangeRef.current?.(true);
})
.catch(() => {});
}
};
}, [playing]);
const seekTo = (time: number) => seekToFnRef.current(time);
const toggle = () => toggleFnRef.current();
// The element can't seek before its metadata loads.
useEffect(() => {
@@ -165,18 +144,6 @@ export function MediaPlayer(
// eslint-disable-next-line react-hooks/exhaustive-deps
}, []);
// The browser may refuse to play without a user gesture, and the player then
// just shows paused.
useEffect(() => {
if (!autoplay) return;
mediaRef.current?.play()
.then(() => {
setPlaying(true);
onPlayStateChangeRef.current?.(true);
})
.catch(() => {});
}, [autoplay]);
// Cutting the callbacks on unmount keeps a late timeupdate or ended event of
// this element from reaching PlayerProvider once the next item is playing.
useEffect(() => {
@@ -192,22 +159,19 @@ export function MediaPlayer(
// The refs are PlayerProvider's, which never change, so this runs once.
useEffect(() => {
if (seekRef) seekRef.current = (t) => seekToFnRef.current(t);
if (toggleRef) toggleRef.current = () => toggleFnRef.current();
if (seekRef) seekRef.current = seekTo;
if (toggleRef) toggleRef.current = toggle;
return () => {
if (seekRef) seekRef.current = null;
if (toggleRef) toggleRef.current = null;
};
}, [seekRef, toggleRef]);
}, [seekRef, toggleRef, seekTo, toggle]);
useEffect(() => {
const a = mediaRef.current!;
const onTime = () => {
// While the seek bar is dragged, its thumb follows the pointer.
if (!dragging) {
setCurrent(a.currentTime);
onTimeUpdateRef.current?.(a.currentTime, a.duration);
}
setCurrent(a.currentTime);
onTimeUpdateRef.current?.(a.currentTime, a.duration);
};
const onDuration = () => {
setDuration(a.duration);
@@ -222,9 +186,6 @@ export function MediaPlayer(
setPlaying(false);
onErrorRef.current?.();
};
// The element can also be started or stopped from outside the page — a
// media key, a headset, the OS's media controls — so follow it rather
// than only what our own button did.
const onPlayEvent = () => {
setPlaying(true);
onPlayStateChangeRef.current?.(true);
@@ -247,7 +208,13 @@ export function MediaPlayer(
a.removeEventListener("ended", onEndedEvent);
a.removeEventListener("error", onErrorEvent);
};
}, [dragging]);
}, []);
// After the listeners, which the play event must find. The browser may
// refuse to play without a user gesture, and the player then shows paused.
useEffect(() => {
if (autoplay) mediaRef.current?.play().catch(() => {});
}, [autoplay]);
useEffect(() => {
if (kind !== "video") return;
@@ -300,27 +267,6 @@ export function MediaPlayer(
(mediaRef.current as HTMLVideoElement).requestFullscreen?.();
};
// A waveform needs the raw bytes, which cross-origin streams won't hand over.
// Those get an honest progress bar rather than a permanent loading skeleton.
const track = kind === "audio" && trackStyle === "waveform"
? (
<Waveform
src={src}
current={current}
duration={duration}
onSeek={seekTo}
/>
)
: (
<SeekBar
current={current}
duration={duration}
onSeek={seekTo}
onDragChange={setDragging}
className={kind === "audio" ? "audio-player-track--stream" : undefined}
/>
);
const controls = (
<>
<button
@@ -332,9 +278,16 @@ export function MediaPlayer(
{playing ? <IconPause /> : <IconPlay />}
</button>
<span className="audio-player-time">{fmt(current)}</span>
<span className="audio-player-time">{fmt(scrubTime ?? current)}</span>
{track}
<Scrubber
current={current}
duration={duration}
onSeek={seekTo}
onScrub={setScrubTime}
peaks={peaks}
slim={kind === "video"}
/>
<span className="audio-player-time">{fmt(duration)}</span>
@@ -394,9 +347,7 @@ export function MediaPlayer(
preload="metadata"
className="video-player-video"
onClick={toggle}
>
{mime && <source src={src} type={mime} />}
</video>
/>
<div className="video-player-controls audio-player">
{controls}
</div>
@@ -410,9 +361,7 @@ export function MediaPlayer(
ref={mediaRef as React.RefObject<HTMLAudioElement>}
src={src}
preload="metadata"
>
{mime && <source src={src} type={mime} />}
</audio>
/>
{controls}
</div>
);

151
src/components/player/Scrubber.tsx Normal file
View File

@@ -0,0 +1,151 @@
/**
* Renders the track MediaPlayer seeks on: an audio file's waveform, or a plain
* bar for a stream, a video, or audio whose waveform isn't in yet. The dump
* page's audio preview shows one too, beside its cover.
*
* @module
*/
import { useMemo, useState } from "react";
import { t } from "@lingui/core/macro";
import { fmt } from "../../utils/player/duration.ts";
/** A bar's width, in viewBox units. */
const BAR_W = 3;
/** The gap between bars, in viewBox units. */
const BAR_GAP = 1;
/** The waveform's height, in viewBox units. */
const WAVEFORM_H = 48;
/** How far an arrow key seeks, in seconds. */
const KEY_STEP = 5;
/** Passed to {@link Scrubber} by MediaPlayer and FilePreview. Times are in seconds. */
export interface ScrubberProps {
current: number;
duration: number;
/** Called once a click, a drag or a key lands somewhere. */
onSeek: (time: number) => void;
/**
* Called with the time under the pointer while it holds the scrubber, and
* with null once it lets go, so MediaPlayer's clock can follow the drag.
*/
onScrub?: (time: number | null) => void;
/** The waveform's heights from 0 to 1; without them, a plain bar. */
peaks?: number[] | null;
/** Draws the thin bar of a video's controls instead of the audio track. */
slim?: boolean;
}
/**
* Returns the waveform's bars as one path, each `BAR_W` wide and centred on
* the middle line, so a redraw for the playhead touches two attributes rather
* than a hundred and fifty elements.
*/
function barsPath(peaks: number[]): string {
return peaks.map((p, i) => {
const h = Math.max(p * WAVEFORM_H, 2);
const x = i * (BAR_W + BAR_GAP);
return `M${x} ${(WAVEFORM_H - h) / 2}h${BAR_W}v${h}h-${BAR_W}z`;
}).join("");
}
/**
* Renders a slider over the media's timeline. A pointer seeks where it lets
* go, showing where it is while held; arrows seek {@link KEY_STEP} seconds,
* Home and End to either end. The played part of the waveform is the same
* path clipped to the playhead by a nested `<svg>`, so it moves smoothly
* within a bar.
*/
export function Scrubber(
{ current, duration, onSeek, onScrub, peaks, slim = false }: ScrubberProps,
): React.JSX.Element {
// The fraction under the pointer while it holds the scrubber.
const [held, setHeld] = useState<number | null>(null);
const path = useMemo(() => peaks && barsPath(peaks), [peaks]);
const shown = held !== null ? held * duration : current;
const progress = duration > 0
? Math.min(1, Math.max(0, shown / duration))
: 0;
const fractionAt = (e: React.PointerEvent<HTMLElement>) => {
const rect = e.currentTarget.getBoundingClientRect();
if (rect.width <= 0) return 0;
return Math.min(1, Math.max(0, (e.clientX - rect.left) / rect.width));
};
const hold = (fraction: number | null) => {
setHeld(fraction);
onScrub?.(fraction === null ? null : fraction * duration);
};
const onKeyDown = (e: React.KeyboardEvent) => {
const to = {
ArrowLeft: current - KEY_STEP,
ArrowDown: current - KEY_STEP,
ArrowRight: current + KEY_STEP,
ArrowUp: current + KEY_STEP,
Home: 0,
End: duration,
}[e.key];
if (to === undefined || !(duration > 0)) return;
e.preventDefault();
onSeek(Math.min(duration, Math.max(0, to)));
};
const width = peaks ? peaks.length * (BAR_W + BAR_GAP) - BAR_GAP : 0;
return (
<div
role="slider"
tabIndex={0}
aria-label={t`Seek`}
aria-valuemin={0}
aria-valuemax={Math.floor(duration) || 0}
aria-valuenow={Math.floor(shown) || 0}
aria-valuetext={`${fmt(shown)} / ${fmt(duration)}`}
className={`scrubber${slim ? " scrubber--slim" : ""}`}
onPointerDown={(e) => {
if (e.button !== 0) return;
// Keeps the pointer's moves coming here when it leaves the track.
e.currentTarget.setPointerCapture?.(e.pointerId);
hold(fractionAt(e));
}}
onPointerMove={(e) => held !== null && hold(fractionAt(e))}
onPointerUp={(e) => {
if (held === null) return;
const fraction = fractionAt(e);
hold(null);
onSeek(fraction * duration);
}}
onPointerCancel={() => held !== null && hold(null)}
onKeyDown={onKeyDown}
>
{path
? (
<svg
viewBox={`0 0 ${width} ${WAVEFORM_H}`}
preserveAspectRatio="none"
className="scrubber-peaks"
aria-hidden="true"
>
<path d={path} />
<svg
width={progress * width}
height={WAVEFORM_H}
className="scrubber-peaks-played"
>
<path d={path} />
</svg>
</svg>
)
: (
<div className="scrubber-bar">
<div
className="scrubber-fill"
style={{ width: `${progress * 100}%` }}
/>
</div>
)}
</div>
);
}

54
src/components/player/SeekBar.tsx
View File

@@ -1,54 +0,0 @@
/**
* Renders the slim seek bar MediaPlayer shows for video and for streams.
*
* @module
*/
import { t } from "@lingui/core/macro";
/** Passed to {@link SeekBar} by MediaPlayer. Times are in seconds. */
export interface SeekBarProps {
current: number;
duration: number;
onSeek: (t: number) => void;
/**
* Called as the thumb is grabbed and let go, so that MediaPlayer stops moving
* it with the playhead in between.
*/
onDragChange: (dragging: boolean) => void;
className?: string;
}
/**
* Renders a progress bar with a range input over it to seek. MediaPlayer uses
* it for video, and for streams, whose bytes can't be read cross-origin to
* draw a waveform.
*/
export function SeekBar(
{ current, duration, onSeek, onDragChange, className }: SeekBarProps,
): React.JSX.Element {
const progress = duration > 0 ? current / duration : 0;
return (
<div className={`audio-player-track${className ? ` ${className}` : ""}`}>
<div
className="audio-player-fill"
style={{ width: `${progress * 100}%` }}
/>
<input
type="range"
className="audio-player-range"
min={0}
max={duration || 1}
step={0.01}
value={current}
// Pointer events, so a finger holds the thumb as a mouse does.
onPointerDown={() =>
onDragChange(true)}
onPointerUp={() => onDragChange(false)}
onPointerCancel={() => onDragChange(false)}
onChange={(e) => onSeek(Number(e.target.value))}
aria-label={t`Seek`}
/>
</div>
);
}

99
src/components/player/Waveform.tsx
View File

@@ -1,99 +0,0 @@
/**
* Renders an audio file's waveform, which MediaPlayer shows as its seek bar and
* an audio file's dump page beside its cover.
*
* @module
*/
import { useEffect, useState } from "react";
import {
BAR_GAP,
BAR_W,
extractPeaks,
NUM_BARS,
VIEWBOX_W,
WAVEFORM_H,
} from "../../utils/player/waveform.ts";
/**
* Passed to {@link Waveform} by MediaPlayer and FilePreview. Times are in
* seconds.
*/
export interface WaveformProps {
/** Fetched again, apart from the media element, to decode its peaks. */
src: string;
current: number;
duration: number;
onSeek: (t: number) => void;
}
/**
* Renders the peaks of `src` as bars, the played ones highlighted, and seeks
* where clicked. Until the peaks are decoded, or if they can't be, it shows a
* plain progress bar that seeks all the same.
*/
export function Waveform(
{ src, current, duration, onSeek }: WaveformProps,
): React.JSX.Element {
const [peaks, setPeaks] = useState<Float32Array | null>(null);
useEffect(() => {
let cancelled = false;
extractPeaks(src, NUM_BARS)
.then((p) => {
if (!cancelled) setPeaks(p);
})
.catch(() => {});
return () => {
cancelled = true;
};
}, [src]);
const progress = duration > 0 ? current / duration : 0;
const handleClick = (e: React.MouseEvent<Element>) => {
const rect = e.currentTarget.getBoundingClientRect();
const ratio = Math.max(
0,
Math.min(1, (e.clientX - rect.left) / rect.width),
);
onSeek(ratio * duration);
};
if (!peaks) {
return (
<div className="waveform-skeleton" onClick={handleClick}>
<div
className="waveform-skeleton-fill"
style={{ width: `${progress * 100}%` }}
/>
</div>
);
}
return (
<svg
viewBox={`0 0 ${VIEWBOX_W} ${WAVEFORM_H}`}
preserveAspectRatio="none"
className="waveform-svg"
onClick={handleClick}
>
{Array.from(peaks).map((p, i) => {
const barH = Math.max(p * WAVEFORM_H, 2);
const x = i * (BAR_W + BAR_GAP);
const y = (WAVEFORM_H - barH) / 2;
const played = i / NUM_BARS <= progress;
return (
<rect
key={i}
x={x}
y={y}
width={BAR_W}
height={barH}
className={`waveform-bar${played ? " waveform-bar--played" : ""}`}
/>
);
})}
</svg>
);
}