+
+
+
+ {cachedStatsQuery.isPending ? (
+
+
+
+
+
+
+
+
+
+ ) : (
+
+ );
+}
+
+function OverviewCards({
+ overview,
+}: {
+ overview: Partial<{
+ total_plays: number;
+ total_time_ms: number;
+ unique_artists: number;
+ unique_albums: number;
+ unique_tracks: number;
+ }>;
+}) {
+ const cards = [
+ { label: 'Total Plays', value: formatCompactNumber(overview.total_plays) },
+ { label: 'Listening Time', value: formatListeningTime(overview.total_time_ms) },
+ { label: 'Artists', value: formatCompactNumber(overview.unique_artists) },
+ { label: 'Albums', value: formatCompactNumber(overview.unique_albums) },
+ { label: 'Tracks', value: formatCompactNumber(overview.unique_tracks) },
+ ];
+
+ return (
+
+ 
+
+
+ Listening Stats
+
+
+
+ {(['7d', '30d', '12m', 'all'] as const).map((option) => (
+
+ ))}
+
+
+
+ {lastSynced ? `Last synced: ${lastSynced}` : 'Not synced yet'}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ {cards.map((card) => (
+
+ );
+}
+
+function StatsSectionCard({
+ children,
+ fullWidth = false,
+ title,
+}: {
+ children: ReactNode;
+ fullWidth?: boolean;
+ title: string;
+}) {
+ return (
+
+
+ ))}
+ {card.value}
+ {card.label}
+ {title}
+ {children}
+
+ {topGenres.map((genre, index) => (
+
+ );
+}
+
+function TopArtistsVisual({
+ artists,
+ onArtistSelect,
+}: {
+ artists: StatsArtistRow[];
+ onArtistSelect: (artistId: string | number, artistName: string) => void;
+}) {
+ const topArtists = getTopArtistBubbles(artists);
+ if (topArtists.length === 0) return null;
+
+ return (
+
+
+ {genre.genre}
+ {genre.percentage}%
+
+ ))}
+
+
+ );
+}
+
+function StatsRankedArtists({
+ artists,
+ onArtistSelect,
+}: {
+ artists: StatsArtistRow[];
+ onArtistSelect: (artistId: string | number, artistName: string) => void;
+}) {
+ return (
+
+ {topArtists.map(({ artist, percent, size }) => {
+ const isClickable = artist.id !== null && artist.id !== undefined;
+ return (
+
+ );
+ })}
+
+
+ {artists.length === 0 ?
+ );
+}
+
+function StatsRankedAlbums({
+ albums,
+ onArtistSelect,
+}: {
+ albums: StatsAlbumRow[];
+ onArtistSelect: (artistId: string | number, artistName: string) => void;
+}) {
+ return (
+
+ {index + 1}
+ {artist.image_url ? (
+ 
+ ) : (
+
+ )}
+
+ ))}
+
+
+
+ {formatCompactNumber(artist.play_count)} plays
+
+
+ {artist.id ? (
+
+ ) : (
+ artist.name
+ )}
+ {artist.soul_id && !String(artist.soul_id).startsWith('soul_unnamed_') ? (
+
+ ) : null}
+
+
+ ) : null}
+
+ {artist.global_listeners
+ ? `${formatCompactNumber(artist.global_listeners)} global listeners`
+ : ''}
+
+
+ {albums.length === 0 ?
+ );
+}
+
+function StatsRankedTracks({
+ tracks,
+ onArtistSelect,
+ onPlay,
+}: {
+ tracks: StatsTrackRow[];
+ onArtistSelect: (artistId: string | number, artistName: string) => void;
+ onPlay: (track: { title: string; artist: string; album: string }) => Promise
+ {index + 1}
+ {album.image_url ? (
+ 
+ ) : (
+
+ )}
+
+ ))}
+
+
+
+ {formatCompactNumber(album.play_count)} plays
+
+ {album.name}
+
+ {album.artist_id ? (
+
+ ) : (
+ album.artist || ''
+ )}
+
+
+ {tracks.length === 0 ?
+ );
+}
+
+function StatsRecentPlays({
+ tracks,
+ onPlay,
+}: {
+ tracks: StatsRecentTrack[];
+ onPlay: (track: { title: string; artist: string; album: string }) => Promise
+ {index + 1}
+ {track.image_url ? (
+ 
+ ) : (
+
+ )}
+
+ ))}
+
+
+
+
+ {formatCompactNumber(track.play_count)} plays
+
+ {track.name}
+
+ {track.artist_id ? (
+
+ ) : (
+ track.artist || ''
+ )}
+ {track.album ? ` · ${track.album}` : ''}
+
+
+ {tracks.length === 0 ?
+ );
+}
+
+function StatsLibraryHealth({ health }: { health: StatsHealth }) {
+ const totalTracks = health.total_tracks ?? 0;
+ const formatEntries = Object.entries(health.format_breakdown ?? {});
+ const formatTotal = formatEntries.reduce((sum, [, count]) => sum + count, 0) || 1;
+ const formatColors: Record
+
+ {track.title}
+ {track.artist || ''}
+ {formatRelativePlayedAt(track.played_at)}
+
+ ))}
+
+
+
+
+ Format Breakdown
+
+ {formatEntries.map(([format, count]) => {
+ const percentage = ((count / formatTotal) * 100).toFixed(1);
+ return (
+
+
+ {Number(percentage) > 8 ? format : ''}
+
+ );
+ })}
+
+
+
+ {formatCompactNumber(health.unplayed_count)} ({health.unplayed_percentage || 0}%)
+
+ Unplayed Tracks
+
+
+
+ {formatTotalDuration(health.total_duration_ms)}
+
+ Total Duration
+
+
+ {formatCompactNumber(totalTracks)}
+ Total Tracks
+
+ {STATS_ENRICHMENT_SERVICES.map((service) => {
+ const percent = health.enrichment_coverage?.[service.key] || 0;
+ return (
+
+
+ );
+}
+
+function StatsDiskUsage({
+ error,
+ payload,
+}: {
+ error: unknown;
+ payload: StatsLibraryDiskUsagePayload | undefined;
+}) {
+ if (error) {
+ return
+ {service.label}
+
+ );
+ })}
+
+
+
+ {percent}%
+
+
+ );
+}
+
+function StatsDbStorage({
+ error,
+ payload,
+}: {
+ error: unknown;
+ payload: StatsDbStoragePayload | undefined;
+}) {
+ if (error) {
+ return
+
+
+ {hasData ? formatBytes(payload?.total_bytes) : '—'}
+
+
+ {hasData
+ ? `${tracksWithSize.toLocaleString()} tracks measured${
+ tracksWithoutSize > 0
+ ? ` (+${tracksWithoutSize.toLocaleString()} pending next Deep Scan)`
+ : ''
+ }`
+ : tracksWithoutSize > 0
+ ? `Run a Deep Scan to populate (${tracksWithoutSize.toLocaleString()} tracks pending)`
+ : 'No tracks in library yet'}
+
+
+ {formats.map(([format, bytes]) => {
+ const width = Math.max(2, Math.round((bytes / max) * 100));
+ return (
+
+
+ {format.toUpperCase()}
+
+ );
+ })}
+
+
+
+ {formatBytes(bytes)}
+
+
+ );
+}
+
+function StatsEmptyState() {
+ return (
+
+
+
+
+ {tables.map((table, index) => (
+ |
+ ))}
+
+
+
+
+
+
+
+ {formatDbStorageValue(payload?.total_file_size || 0, method)}
+
+ Total Size
+
+ {tables.map((table, index) => (
+
+
+
+ {table.name}
+
+ {formatDbStorageValue(table.size, method)}
+
+
+ ))}
+
+
+ );
+}
+
+function SectionLoadingState() {
+ return 📊
+ No Listening Data Yet
++ Enable "Listening Stats" in Settings to start tracking your listening activity + from your media server. +
+Loading listening stats...
;
+}
+
+function SectionErrorState({ message }: { message: string }) {
+ return (
+
+
+ );
+}
+
+function SectionSubtleError({ message }: { message: string }) {
+ return Failed to load listening stats
+{message}
+{message}
;
+}
+
+function EmptyListState({ message }: { message: string }) {
+ return {message}
;
+}
+
+async function openArtistDetail(artistId: string | number, artistName: string) {
+ await window.SoulSyncWebRouter?.navigateToPage('library');
+ window.setTimeout(() => {
+ window.navigateToArtistDetail?.(artistId, artistName);
+ }, 300);
+}
+
+async function playStatsTrack(track: { title: string; artist: string; album: string }) {
+ const resolvedTrack = await resolveStatsTrack(track.title, track.artist);
+ if (resolvedTrack) {
+ void window.playLibraryTrack?.(
+ {
+ id: resolvedTrack.id,
+ title: resolvedTrack.title,
+ file_path: resolvedTrack.file_path,
+ bitrate: resolvedTrack.bitrate,
+ artist_id: resolvedTrack.artist_id,
+ album_id: resolvedTrack.album_id,
+ _stats_image: resolvedTrack.image_url || null,
+ },
+ resolvedTrack.album_title || track.album,
+ resolvedTrack.artist_name || track.artist,
+ );
+ return;
+ }
+
+ window.showLoadingOverlay?.(`Searching for ${track.title}...`);
+ try {
+ const streamResult = await streamStatsTrack(track.title, track.artist, track.album);
+ window.hideLoadingOverlay?.();
+
+ if (streamResult) {
+ if (typeof window.startStream === 'function') {
+ await window.startStream(streamResult);
+ } else {
+ window.showToast?.('Streaming not available', 'error');
+ }
+ return;
+ }
+
+ window.showToast?.('Track not found in library or any source', 'error');
+ } catch (error) {
+ window.hideLoadingOverlay?.();
+ window.showToast?.(getErrorMessage(error), 'error');
+ }
+}
+
+function getErrorMessage(error: unknown): string {
+ return error instanceof Error ? error.message : 'Unknown error';
+}
diff --git a/webui/src/routes/stats/route.tsx b/webui/src/routes/stats/route.tsx
new file mode 100644
index 00000000..364eb651
--- /dev/null
+++ b/webui/src/routes/stats/route.tsx
@@ -0,0 +1,28 @@
+import { createFileRoute, redirect } from '@tanstack/react-router';
+
+import { getProfileHomePath } from '@/platform/shell/bridge';
+
+import { listeningStatsStatusQueryOptions, statsCachedQueryOptions } from './-stats.api';
+import { statsSearchSchema } from './-stats.types';
+import { StatsPage } from './-ui/stats-page';
+
+export const Route = createFileRoute('/stats')({
+ validateSearch: statsSearchSchema,
+ beforeLoad: ({ context }) => {
+ const { bridge } = context.shell;
+
+ if (!bridge.isPageAllowed('stats')) {
+ throw redirect({ href: getProfileHomePath(bridge), replace: true });
+ }
+ },
+ loaderDeps: ({ search }) => ({
+ range: search.range,
+ }),
+ loader: async ({ context, deps }) => {
+ await Promise.all([
+ context.queryClient.ensureQueryData(statsCachedQueryOptions(deps.range)),
+ context.queryClient.ensureQueryData(listeningStatsStatusQueryOptions()),
+ ]);
+ },
+ component: StatsPage,
+});