feat: add total duration to platform stats and artist analytics (#522)

- add `total_duration_seconds` to platform stats endpoint (`/stats`)
- add `total_duration_seconds` to artist analytics endpoint (`/artists/{did}/analytics`)
- display duration in homepage stats bar (header and menu variants)
- show duration as subtitle in artist page "total tracks" card
- add `formatDuration()` helper for human-readable format (e.g., "25h 32m")
- add `scripts/user_upload_stats.py` for viewing per-user upload durations
- add regression tests for stats and analytics endpoints

this lays groundwork for future upload caps per user.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude <[e-mail]>

backend/src/backend/api/artists.py

···
 
 from fastapi import APIRouter, Depends, HTTPException
 from pydantic import BaseModel, ConfigDict, field_validator
-from sqlalchemy import func, select
+from sqlalchemy import func, select, text
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from backend._internal import Session, require_auth
···
 
     total_plays: int
     total_items: int
+    total_duration_seconds: int
     top_item: TopItemResponse | None
     top_liked: TopItemResponse | None
 
···
 
     returns zeros if artist has no tracks.
     """
-    # get total plays and item count in one query
+    # get total plays, item count, and duration in one query
     result = await db.execute(
-        select(func.sum(Track.play_count), func.count(Track.id)).where(
-            Track.artist_did == artist_did
-        )
+        select(
+            func.sum(Track.play_count),
+            func.count(Track.id),
+            func.coalesce(func.sum(text("(extra->>'duration')::int")), 0),
+        ).where(Track.artist_did == artist_did)
     )
-    total_plays, total_items = result.one()
+    total_plays, total_items, total_duration = result.one()
     total_plays = total_plays or 0  # handle None when no tracks
     total_items = total_items or 0
+    total_duration = total_duration or 0
 
     # get top item by plays (only if artist has tracks)
     top_item = None
···
     return AnalyticsResponse(
         total_plays=total_plays,
         total_items=total_items,
+        total_duration_seconds=total_duration,
         top_item=top_item,
         top_liked=top_liked,
     )

backend/src/backend/api/stats.py

···
 
 from fastapi import APIRouter, Depends
 from pydantic import BaseModel
-from sqlalchemy import func, select
+from sqlalchemy import func, select, text
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from backend.models import Track, get_db
···
     total_plays: int
     total_tracks: int
     total_artists: int
+    total_duration_seconds: int
 
 
 @router.get("")
···
             func.coalesce(func.sum(Track.play_count), 0),
             func.count(Track.id),
             func.count(func.distinct(Track.artist_did)),
+            # sum duration from JSONB extra column (cast to int, coalesce nulls to 0)
+            func.coalesce(
+                func.sum(text("(extra->>'duration')::int")),
+                0,
+            ),
         )
     )
     row = result.one()
···
         total_plays=int(row[0]),
         total_tracks=int(row[1]),
         total_artists=int(row[2]),
+        total_duration_seconds=int(row[3]),
     )

backend/tests/api/test_analytics.py

···
     # verify total metrics
     assert data["total_plays"] == 160  # 100 + 50 + 10
     assert data["total_items"] == 3
+    assert data["total_duration_seconds"] == 0  # no duration set on tracks
 
     # verify top played track
     assert data["top_item"]["title"] == "Most Played"
···
 
     assert data["total_plays"] == 0
     assert data["total_items"] == 0
+    assert data["total_duration_seconds"] == 0
     assert data["top_item"] is None
     assert data["top_liked"] is None
 
···
 
     assert data["total_plays"] == 50
     assert data["total_items"] == 1
+    assert data["total_duration_seconds"] == 0  # no duration set
     assert data["top_item"]["title"] == "Unloved Track"
     assert data["top_liked"] is None  # no likes
+
+
+async def test_get_artist_analytics_with_duration(
+    test_app: FastAPI, db_session: AsyncSession
+):
+    """test analytics returns total duration from tracks."""
+    artist = Artist(
+        did="did:plc:artist_duration",
+        handle="duration-artist.bsky.social",
+        display_name="Duration Artist",
+    )
+    db_session.add(artist)
+    await db_session.flush()
+
+    # create tracks with duration in extra field
+    tracks = [
+        Track(
+            title="Short Track",
+            artist_did=artist.did,
+            file_id="short_1",
+            file_type="mp3",
+            play_count=10,
+            extra={"duration": 180},  # 3 minutes
+        ),
+        Track(
+            title="Long Track",
+            artist_did=artist.did,
+            file_id="long_1",
+            file_type="mp3",
+            play_count=5,
+            extra={"duration": 3600},  # 1 hour
+        ),
+        Track(
+            title="No Duration Track",
+            artist_did=artist.did,
+            file_id="no_dur_1",
+            file_type="mp3",
+            play_count=3,
+            extra={},  # no duration
+        ),
+    ]
+    for track in tracks:
+        db_session.add(track)
+    await db_session.commit()
+
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.get(f"/artists/{artist.did}/analytics")
+
+    assert response.status_code == 200
+    data = response.json()
+
+    assert data["total_plays"] == 18  # 10 + 5 + 3
+    assert data["total_items"] == 3
+    # duration should sum only tracks that have it: 180 + 3600 = 3780
+    assert data["total_duration_seconds"] == 3780

backend/tests/api/test_stats.py

···
+"""tests for platform stats api endpoint."""
+
+import pytest
+from fastapi.testclient import TestClient
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend.models import Artist, Track
+
+
[e-mail]
+async def artist(db_session: AsyncSession) -> Artist:
+    """create a test artist."""
+    artist = Artist(
+        did="did:plc:stats_test_artist",
+        handle="stats-test.bsky.social",
+        display_name="Stats Test Artist",
+    )
+    db_session.add(artist)
+    await db_session.commit()
+    return artist
+
+
[e-mail]
+async def tracks_with_duration(db_session: AsyncSession, artist: Artist) -> list[Track]:
+    """create multiple test tracks with duration metadata."""
+    tracks = [
+        Track(
+            title="Short Track",
+            artist_did=artist.did,
+            file_id="track1",
+            file_type="mp3",
+            extra={"duration": 180},  # 3 minutes
+            play_count=10,
+        ),
+        Track(
+            title="Long Track",
+            artist_did=artist.did,
+            file_id="track2",
+            file_type="mp3",
+            extra={"duration": 3600},  # 1 hour
+            play_count=5,
+        ),
+        Track(
+            title="Medium Track",
+            artist_did=artist.did,
+            file_id="track3",
+            file_type="mp3",
+            extra={"duration": 300},  # 5 minutes
+            play_count=20,
+        ),
+    ]
+    for track in tracks:
+        db_session.add(track)
+    await db_session.commit()
+    return tracks
+
+
[e-mail]
+async def track_without_duration(db_session: AsyncSession, artist: Artist) -> Track:
+    """create a test track without duration (legacy upload)."""
+    track = Track(
+        title="No Duration Track",
+        artist_did=artist.did,
+        file_id="track_noduration",
+        file_type="mp3",
+        extra={},  # no duration
+        play_count=3,
+    )
+    db_session.add(track)
+    await db_session.commit()
+    return track
+
+
+async def test_get_stats_returns_total_duration(
+    client: TestClient,
+    tracks_with_duration: list[Track],
+) -> None:
+    """stats endpoint returns total duration in seconds."""
+    response = client.get("/stats")
+    assert response.status_code == 200
+
+    data = response.json()
+    assert "total_duration_seconds" in data
+
+    # 180 + 3600 + 300 = 4080 seconds
+    assert data["total_duration_seconds"] == 4080
+
+
+async def test_get_stats_duration_ignores_null(
+    client: TestClient,
+    tracks_with_duration: list[Track],
+    track_without_duration: Track,
+) -> None:
+    """stats endpoint handles tracks without duration gracefully."""
+    response = client.get("/stats")
+    assert response.status_code == 200
+
+    data = response.json()
+    # should still be 4080 (the track without duration doesn't add to total)
+    assert data["total_duration_seconds"] == 4080
+    # but track count should include all 4
+    assert data["total_tracks"] == 4
+
+
+async def test_get_stats_empty_database(client: TestClient) -> None:
+    """stats endpoint returns zeros for empty database."""
+    response = client.get("/stats")
+    assert response.status_code == 200
+
+    data = response.json()
+    assert data["total_plays"] == 0
+    assert data["total_tracks"] == 0
+    assert data["total_artists"] == 0
+    assert data["total_duration_seconds"] == 0
+
+
+async def test_get_stats_aggregates_play_counts(
+    client: TestClient,
+    tracks_with_duration: list[Track],
+) -> None:
+    """stats endpoint correctly aggregates play counts."""
+    response = client.get("/stats")
+    assert response.status_code == 200
+
+    data = response.json()
+    # 10 + 5 + 20 = 35 total plays
+    assert data["total_plays"] == 35
+
+
+async def test_get_stats_counts_distinct_artists(
+    client: TestClient,
+    db_session: AsyncSession,
+) -> None:
+    """stats endpoint counts distinct artists correctly."""
+    # create two artists
+    artist1 = Artist(
+        did="did:plc:artist1",
+        handle="artist1.bsky.social",
+        display_name="Artist 1",
+    )
+    artist2 = Artist(
+        did="did:plc:artist2",
+        handle="artist2.bsky.social",
+        display_name="Artist 2",
+    )
+    db_session.add_all([artist1, artist2])
+    await db_session.flush()
+
+    # create tracks from both artists
+    tracks = [
+        Track(
+            title="Track A1",
+            artist_did=artist1.did,
+            file_id="a1",
+            file_type="mp3",
+            extra={"duration": 100},
+        ),
+        Track(
+            title="Track A2",
+            artist_did=artist1.did,
+            file_id="a2",
+            file_type="mp3",
+            extra={"duration": 100},
+        ),
+        Track(
+            title="Track B1",
+            artist_did=artist2.did,
+            file_id="b1",
+            file_type="mp3",
+            extra={"duration": 100},
+        ),
+    ]
+    for track in tracks:
+        db_session.add(track)
+    await db_session.commit()
+
+    response = client.get("/stats")
+    assert response.status_code == 200
+
+    data = response.json()
+    assert data["total_tracks"] == 3
+    assert data["total_artists"] == 2
+    assert data["total_duration_seconds"] == 300

frontend/src/lib/components/PlatformStats.svelte

···
 <script lang="ts">
 	import { onMount } from 'svelte';
-	import { statsCache } from '$lib/stats.svelte';
+	import { statsCache, formatDuration } from '$lib/stats.svelte';
 
 	interface Props {
 		variant?: 'header' | 'menu';
···
 					<path d="M3 14c0-2.5 2-4.5 5-4.5s5 2 5 4.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" />
 				</svg>
 				<span class="header-value">{stats.total_artists.toLocaleString()}</span>
+			</div>
+			<div class="header-stat" title="{formatDuration(stats.total_duration_seconds)} of music">
+				<svg class="header-icon" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+					<circle cx="12" cy="12" r="10"></circle>
+					<polyline points="12 6 12 12 16 14"></polyline>
+				</svg>
+				<span class="header-value">{formatDuration(stats.total_duration_seconds)}</span>
 			</div>
 		{/if}
 	</div>
···
 					<span class="stats-menu-value">{stats.total_artists.toLocaleString()}</span>
 					<span class="stats-menu-label">{pluralize(stats.total_artists, 'artist', 'artists')}</span>
 				</div>
+				<div class="stats-menu-item">
+					<svg class="menu-stat-icon" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+						<circle cx="12" cy="12" r="10"></circle>
+						<polyline points="12 6 12 12 16 14"></polyline>
+					</svg>
+					<span class="stats-menu-value">{formatDuration(stats.total_duration_seconds)}</span>
+					<span class="stats-menu-label">of music</span>
+				</div>
 			</div>
 		{/if}
 	</div>
···
 
 	.stats-menu-grid {
 		display: grid;
-		grid-template-columns: repeat(3, 1fr);
+		grid-template-columns: repeat(2, 1fr);
 		gap: 0.5rem;
 	}
 

frontend/src/lib/stats.svelte.ts

···
 	total_plays: number;
 	total_tracks: number;
 	total_artists: number;
+	total_duration_seconds: number;
+}
+
+/**
+ * format seconds into human-readable duration string.
+ * examples: "25h 32m", "3h 45m", "45m", "1h"
+ */
+export function formatDuration(totalSeconds: number): string {
+	const hours = Math.floor(totalSeconds / 3600);
+	const minutes = Math.floor((totalSeconds % 3600) / 60);
+
+	if (hours === 0) {
+		return `${minutes}m`;
+	}
+	if (minutes === 0) {
+		return `${hours}h`;
+	}
+	return `${hours}h ${minutes}m`;
 }
 
 class StatsCache {

frontend/src/lib/types.ts

···
 export interface Analytics {
 	total_plays: number;
 	total_items: number;
+	total_duration_seconds: number;
 	top_item: TopItem | null;
 	top_liked: TopItem | null;
 }

frontend/src/routes/u/[handle]/+page.svelte

···
 	import { API_URL } from '$lib/config';
 	import { browser } from '$app/environment';
 	import type { Analytics, Track, Playlist } from '$lib/types';
+	import { formatDuration } from '$lib/stats.svelte';
 	import TrackItem from '$lib/components/TrackItem.svelte';
 	import ShareButton from '$lib/components/ShareButton.svelte';
 	import Header from '$lib/components/Header.svelte';
···
 						<div class="stat-card" transition:fade={{ duration: 200 }}>
 							<div class="stat-value">{analytics.total_items}</div>
 							<div class="stat-label">total tracks</div>
+							{#if analytics.total_duration_seconds > 0}
+								<div class="stat-duration">{formatDuration(analytics.total_duration_seconds)}</div>
+							{/if}
 						</div>
 						{#if analytics.top_item}
 							<a href="/track/{analytics.top_item.id}" class="stat-card top-item" transition:fade={{ duration: 200 }}>
···
 		font-size: 0.9rem;
 		text-transform: lowercase;
 		line-height: 1;
+	}
+
+	.stat-duration {
+		margin-top: 0.5rem;
+		font-size: 0.85rem;
+		color: var(--text-secondary);
+		font-variant-numeric: tabular-nums;
 	}
 
 	.stat-card.top-item {

scripts/user_upload_stats.py

···
+#!/usr/bin/env -S uv run --script --quiet
+"""view per-user upload duration statistics.
+
+## Context
+
+Track how much content each user has uploaded to support future upload caps.
+Currently informational - no enforcement yet.
+
+## What This Script Does
+
+1. Queries all tracks grouped by artist
+2. Sums duration from extra JSONB column
+3. Displays sorted by total upload time
+
+## Usage
+
+```bash
+# show all users with upload stats
+uv run scripts/user_upload_stats.py
+
+# show only users above a threshold (in hours)
+uv run scripts/user_upload_stats.py --min-hours 1
+
+# target specific environment
+DATABASE_URL=postgresql://... uv run scripts/user_upload_stats.py
+```
+"""
+
+import asyncio
+import logging
+import sys
+from pathlib import Path
+
+# add src to path so we can import backend modules
+sys.path.insert(0, str(Path(__file__).parent.parent / "backend" / "src"))
+
+from sqlalchemy import func, select, text
+
+from backend.models import Artist, Track
+from backend.utilities.database import db_session
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+def format_duration(total_seconds: int) -> str:
+    """format seconds into human-readable duration string."""
+    hours = total_seconds // 3600
+    minutes = (total_seconds % 3600) // 60
+
+    if hours == 0:
+        return f"{minutes}m"
+    if minutes == 0:
+        return f"{hours}h"
+    return f"{hours}h {minutes}m"
+
+
+async def get_user_upload_stats(min_hours: float = 0) -> None:
+    """query and display per-user upload statistics."""
+
+    min_seconds = int(min_hours * 3600)
+
+    async with db_session() as db:
+        # aggregate tracks by artist
+        stmt = (
+            select(
+                Track.artist_did,
+                Artist.handle,
+                Artist.display_name,
+                func.count(Track.id).label("track_count"),
+                func.coalesce(
+                    func.sum(text("(tracks.extra->>'duration')::int")),
+                    0,
+                ).label("total_seconds"),
+            )
+            .join(Artist, Track.artist_did == Artist.did)
+            .group_by(Track.artist_did, Artist.handle, Artist.display_name)
+            .order_by(text("total_seconds DESC"))
+        )
+
+        result = await db.execute(stmt)
+        rows = result.all()
+
+        if not rows:
+            logger.info("no tracks found")
+            return
+
+        # also get totals
+        total_stmt = select(
+            func.count(Track.id),
+            func.coalesce(func.sum(text("(tracks.extra->>'duration')::int")), 0),
+        )
+        total_result = await db.execute(total_stmt)
+        total_row = total_result.one()
+        total_tracks = total_row[0]
+        total_seconds = total_row[1]
+
+        print("\n" + "=" * 80)
+        print("USER UPLOAD STATISTICS")
+        print("=" * 80)
+        print(
+            f"\nPlatform totals: {total_tracks} tracks, {format_duration(total_seconds)}"
+        )
+        print("-" * 80)
+        print(f"{'handle':<30} {'display name':<20} {'tracks':>8} {'duration':>12}")
+        print("-" * 80)
+
+        shown = 0
+        for row in rows:
+            artist_did, handle, display_name, track_count, user_seconds = row
+
+            if user_seconds < min_seconds:
+                continue
+
+            shown += 1
+            display = (display_name or handle)[:20]
+            handle_str = handle[:30] if handle else artist_did[:30]
+
+            print(
+                f"{handle_str:<30} {display:<20} {track_count:>8} {format_duration(user_seconds):>12}"
+            )
+
+        print("-" * 80)
+
+        if min_hours > 0:
+            hidden = len(rows) - shown
+            print(
+                f"showing {shown} users with >= {min_hours}h (hiding {hidden} below threshold)"
+            )
+        else:
+            print(f"total: {len(rows)} users")
+
+        print()
+
+
+async def main() -> None:
+    """main entry point."""
+    min_hours = 0.0
+
+    for i, arg in enumerate(sys.argv):
+        if arg == "--min-hours" and i + 1 < len(sys.argv):
+            min_hours = float(sys.argv[i + 1])
+
+    await get_user_upload_stats(min_hours=min_hours)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())