feat: add now-playing API for teal.fm/Piper integration (#416)

* feat: add now-playing API for teal.fm/Piper integration

exposes real-time playback state for external scrobbler services.

backend:
- NowPlayingService with TTL cache (5 min expiry) for ephemeral state
- POST /now-playing/ - frontend reports playback state
- DELETE /now-playing/ - clear state on stop
- GET /now-playing/by-handle/{handle} - public endpoint for Piper
- GET /now-playing/by-did/{did} - alternative by DID
- returns 204 when nothing playing (matches Spotify pattern)
- response format compatible with Piper's expectations

frontend:
- now-playing.svelte.ts service with throttling/debouncing
- reports every 10s during playback, debounced for seeks
- integrated into Player.svelte effects

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

Co-Authored-By: Claude <[e-mail]>

* fix: use cookie-based auth check in now-playing service

auth is cookie-based (HttpOnly), not localStorage. the localStorage.getItem('session_id')
check was leftover dead code that always failed, preventing now-playing from reporting.

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

Co-Authored-By: Claude <[e-mail]>

* fix: use latest state in debounced now-playing reports

when pause events were debounced, the scheduled report used stale values
captured at schedule time instead of the latest state. now stores pending
state separately so the timer always fires with current values.

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

Co-Authored-By: Claude <[e-mail]>

---------

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

backend/src/backend/_internal/__init__.py

···
 )
 from backend._internal.constellation import get_like_count_safe
 from backend._internal.notifications import notification_service
+from backend._internal.now_playing import now_playing_service
 from backend._internal.queue import queue_service
 
 __all__ = [
···
     "handle_oauth_callback",
     "list_developer_tokens",
     "notification_service",
+    "now_playing_service",
     "oauth_client",
     "queue_service",
     "require_artist_profile",

backend/src/backend/_internal/now_playing.py

···
+"""now playing service for real-time playback state.
+
+exposes current playback state for external integrations like teal.fm/Piper.
+"""
+
+import logging
+from dataclasses import dataclass
+from datetime import UTC, datetime
+
+from cachetools import TTLCache
+
+logger = logging.getLogger(__name__)
+
+# playback state expires after 5 minutes of no updates
+# this handles cases where user closes browser without explicit stop
+NOW_PLAYING_TTL_SECONDS = 300
+
+
+@dataclass
+class NowPlayingState:
+    """current playback state for a user."""
+
+    # track metadata
+    track_name: str
+    artist_name: str
+    album_name: str | None
+    duration_ms: int
+    progress_ms: int
+
+    # track identifiers
+    track_id: int
+    file_id: str
+
+    # plyr.fm URLs
+    track_url: str  # e.g., https://plyr.fm/track/123
+    image_url: str | None
+
+    # playback state
+    is_playing: bool
+    updated_at: datetime
+
+
+class NowPlayingService:
+    """service for tracking real-time playback state.
+
+    uses TTL cache - playback state expires after 5 minutes of no updates.
+    this is ephemeral data, no database persistence needed.
+    """
+
+    def __init__(self, ttl_seconds: int = NOW_PLAYING_TTL_SECONDS):
+        # keyed by DID
+        self._cache: TTLCache[str, NowPlayingState] = TTLCache(
+            maxsize=10000, ttl=ttl_seconds
+        )
+
+    def update(
+        self,
+        did: str,
+        track_name: str,
+        artist_name: str,
+        album_name: str | None,
+        duration_ms: int,
+        progress_ms: int,
+        track_id: int,
+        file_id: str,
+        track_url: str,
+        image_url: str | None,
+        is_playing: bool,
+    ) -> None:
+        """update playback state for a user."""
+        state = NowPlayingState(
+            track_name=track_name,
+            artist_name=artist_name,
+            album_name=album_name,
+            duration_ms=duration_ms,
+            progress_ms=progress_ms,
+            track_id=track_id,
+            file_id=file_id,
+            track_url=track_url,
+            image_url=image_url,
+            is_playing=is_playing,
+            updated_at=datetime.now(UTC),
+        )
+        self._cache[did] = state
+        logger.debug(f"updated now playing for {did}: {track_name} by {artist_name}")
+
+    def get(self, did: str) -> NowPlayingState | None:
+        """get current playback state for a user."""
+        return self._cache.get(did)
+
+    def clear(self, did: str) -> None:
+        """clear playback state for a user (stopped playing)."""
+        self._cache.pop(did, None)
+        logger.debug(f"cleared now playing for {did}")
+
+    def get_active_count(self) -> int:
+        """get count of users currently playing (for metrics)."""
+        return len(self._cache)
+
+
+# global instance
+now_playing_service = NowPlayingService()

backend/src/backend/api/__init__.py

···
 from backend.api.audio import router as audio_router
 from backend.api.auth import router as auth_router
 from backend.api.exports import router as exports_router
+from backend.api.now_playing import router as now_playing_router
 from backend.api.oembed import router as oembed_router
 from backend.api.preferences import router as preferences_router
 from backend.api.queue import router as queue_router
···
     "audio_router",
     "auth_router",
     "exports_router",
+    "now_playing_router",
     "oembed_router",
     "preferences_router",
     "queue_router",

backend/src/backend/api/now_playing.py

···
+"""now playing API endpoints for external scrobbler integrations.
+
+exposes real-time playback state for services like teal.fm/Piper.
+"""
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Response
+from pydantic import BaseModel
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend._internal import Session, now_playing_service, require_auth
+from backend.config import settings
+from backend.models import Artist, get_db
+
+router = APIRouter(prefix="/now-playing", tags=["now-playing"])
+
+
+class NowPlayingUpdate(BaseModel):
+    """request to update now playing state."""
+
+    track_id: int
+    file_id: str
+    track_name: str
+    artist_name: str
+    album_name: str | None = None
+    duration_ms: int
+    progress_ms: int
+    is_playing: bool
+    image_url: str | None = None
+
+
+class NowPlayingResponse(BaseModel):
+    """now playing state response.
+
+    designed to be compatible with teal.fm/Piper expectations.
+    matches the fields Piper expects from music sources like Spotify.
+    """
+
+    # track metadata (required by teal.fm lexicon)
+    track_name: str
+    artist_name: str
+    album_name: str | None
+
+    # playback state
+    duration_ms: int
+    progress_ms: int
+    is_playing: bool
+
+    # plyr.fm-specific identifiers
+    track_id: int
+    file_id: str
+    track_url: str
+    image_url: str | None
+
+    # service identifier for Piper
+    service_base_url: str = "plyr.fm"
+
+
[e-mail]("/")
+async def update_now_playing(
+    update: NowPlayingUpdate,
+    session: Session = Depends(require_auth),
+) -> dict:
+    """update now playing state (authenticated).
+
+    called by frontend to report current playback state.
+    state expires after 5 minutes of no updates.
+    """
+    track_url = f"{settings.frontend.url}/track/{update.track_id}"
+
+    now_playing_service.update(
+        did=session.did,
+        track_name=update.track_name,
+        artist_name=update.artist_name,
+        album_name=update.album_name,
+        duration_ms=update.duration_ms,
+        progress_ms=update.progress_ms,
+        track_id=update.track_id,
+        file_id=update.file_id,
+        track_url=track_url,
+        image_url=update.image_url,
+        is_playing=update.is_playing,
+    )
+
+    return {"status": "ok"}
+
+
[e-mail]("/")
+async def clear_now_playing(
+    session: Session = Depends(require_auth),
+) -> dict:
+    """clear now playing state (authenticated).
+
+    called when user explicitly stops playback.
+    """
+    now_playing_service.clear(session.did)
+    return {"status": "ok"}
+
+
[e-mail]("/by-handle/{handle}")
+async def get_now_playing_by_handle(
+    handle: str,
+    response: Response,
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> NowPlayingResponse:
+    """get now playing state by handle (public).
+
+    this is the endpoint Piper will poll to fetch current playback state.
+    returns 204 No Content if nothing is playing.
+
+    response format matches what Piper expects from music sources:
+    - track_name: track title
+    - artist_name: artist display name
+    - album_name: album name (optional)
+    - duration_ms: total duration in milliseconds
+    - progress_ms: current playback position in milliseconds
+    - is_playing: whether actively playing
+    - track_url: link to track on plyr.fm
+    - service_base_url: "plyr.fm" for Piper to identify the source
+    """
+    # resolve handle to DID
+    result = await db.execute(select(Artist.did).where(Artist.handle == handle))
+    did = result.scalar_one_or_none()
+
+    if not did:
+        raise HTTPException(status_code=404, detail="user not found")
+
+    state = now_playing_service.get(did)
+
+    if not state or not state.is_playing:
+        # nothing playing - return 204 like Spotify does
+        response.status_code = 204
+        # must return something for FastAPI, but 204 has no body
+        raise HTTPException(status_code=204)
+
+    return NowPlayingResponse(
+        track_name=state.track_name,
+        artist_name=state.artist_name,
+        album_name=state.album_name,
+        duration_ms=state.duration_ms,
+        progress_ms=state.progress_ms,
+        is_playing=state.is_playing,
+        track_id=state.track_id,
+        file_id=state.file_id,
+        track_url=state.track_url,
+        image_url=state.image_url,
+        service_base_url="plyr.fm",
+    )
+
+
[e-mail]("/by-did/{did}")
+async def get_now_playing_by_did(
+    did: str,
+    response: Response,
+) -> NowPlayingResponse:
+    """get now playing state by DID (public).
+
+    alternative to by-handle for clients that already have the DID.
+    returns 204 No Content if nothing is playing.
+    """
+    state = now_playing_service.get(did)
+
+    if not state or not state.is_playing:
+        raise HTTPException(status_code=204)
+
+    return NowPlayingResponse(
+        track_name=state.track_name,
+        artist_name=state.artist_name,
+        album_name=state.album_name,
+        duration_ms=state.duration_ms,
+        progress_ms=state.progress_ms,
+        is_playing=state.is_playing,
+        track_id=state.track_id,
+        file_id=state.file_id,
+        track_url=state.track_url,
+        image_url=state.image_url,
+        service_base_url="plyr.fm",
+    )

backend/src/backend/main.py

···
     audio_router,
     auth_router,
     exports_router,
+    now_playing_router,
     oembed_router,
     preferences_router,
     queue_router,
···
 app.include_router(search_router)
 app.include_router(preferences_router)
 app.include_router(queue_router)
+app.include_router(now_playing_router)
 app.include_router(migration_router)
 app.include_router(exports_router)
 app.include_router(oembed_router)

backend/tests/api/test_now_playing.py

···
+"""tests for now-playing api endpoints."""
+
+from collections.abc import Generator
+
+import pytest
+from fastapi import FastAPI
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend._internal import Session, now_playing_service
+from backend.main import app
+from backend.models import Artist
+
+
+# create a mock session object
+class MockSession(Session):
+    """mock session for auth bypass in tests."""
+
+    def __init__(self, did: str = "did:test:user123", handle: str = "test.user"):
+        self.did = did
+        self.handle = handle
+        self.session_id = "test_session"
+        self.access_token = "test_token"
+        self.refresh_token = "test_refresh"
+
+
[e-mail]
+def test_app(db_session: AsyncSession) -> Generator[FastAPI, None, None]:
+    """create test app with mocked auth."""
+    from backend._internal import require_auth
+
+    # mock the auth dependency to return a mock session
+    async def mock_require_auth() -> Session:
+        return MockSession()
+
+    # override the auth dependency
+    app.dependency_overrides[require_auth] = mock_require_auth
+
+    # clear the now_playing_service cache before each test
+    now_playing_service._cache.clear()
+
+    yield app
+
+    # cleanup
+    app.dependency_overrides.clear()
+    now_playing_service._cache.clear()
+
+
+async def test_update_now_playing(test_app: FastAPI, db_session: AsyncSession):
+    """test POST /now-playing updates playback state."""
+    payload = {
+        "track_id": 123,
+        "file_id": "test-file-abc",
+        "track_name": "Test Track",
+        "artist_name": "Test Artist",
+        "album_name": "Test Album",
+        "duration_ms": 180000,
+        "progress_ms": 30000,
+        "is_playing": True,
+        "image_url": "https://example.com/cover.jpg",
+    }
+
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.post("/now-playing/", json=payload)
+
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}
+
+    # verify state was stored
+    state = now_playing_service.get("did:test:user123")
+    assert state is not None
+    assert state.track_name == "Test Track"
+    assert state.artist_name == "Test Artist"
+    assert state.album_name == "Test Album"
+    assert state.duration_ms == 180000
+    assert state.progress_ms == 30000
+    assert state.is_playing is True
+
+
+async def test_clear_now_playing(test_app: FastAPI, db_session: AsyncSession):
+    """test DELETE /now-playing clears playback state."""
+    # first set a state
+    now_playing_service.update(
+        did="did:test:user123",
+        track_name="Test",
+        artist_name="Artist",
+        album_name=None,
+        duration_ms=100000,
+        progress_ms=0,
+        track_id=1,
+        file_id="test",
+        track_url="https://plyr.fm/track/1",
+        image_url=None,
+        is_playing=True,
+    )
+
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.delete("/now-playing/")
+
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}
+
+    # verify state was cleared
+    state = now_playing_service.get("did:test:user123")
+    assert state is None
+
+
+async def test_get_now_playing_by_handle(test_app: FastAPI, db_session: AsyncSession):
+    """test GET /now-playing/by-handle/{handle} returns playback state."""
+    # create artist with matching handle
+    artist = Artist(
+        did="did:test:user123",
+        handle="test.user",
+        display_name="Test User",
+    )
+    db_session.add(artist)
+    await db_session.commit()
+
+    # set now playing state
+    now_playing_service.update(
+        did="did:test:user123",
+        track_name="Test Track",
+        artist_name="Test Artist",
+        album_name="Test Album",
+        duration_ms=180000,
+        progress_ms=45000,
+        track_id=123,
+        file_id="test-file-abc",
+        track_url="https://plyr.fm/track/123",
+        image_url="https://example.com/cover.jpg",
+        is_playing=True,
+    )
+
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.get("/now-playing/by-handle/test.user")
+
+    assert response.status_code == 200
+    data = response.json()
+
+    assert data["track_name"] == "Test Track"
+    assert data["artist_name"] == "Test Artist"
+    assert data["album_name"] == "Test Album"
+    assert data["duration_ms"] == 180000
+    assert data["progress_ms"] == 45000
+    assert data["is_playing"] is True
+    assert data["track_id"] == 123
+    assert data["file_id"] == "test-file-abc"
+    assert data["track_url"] == "https://plyr.fm/track/123"
+    assert data["image_url"] == "https://example.com/cover.jpg"
+    assert data["service_base_url"] == "plyr.fm"
+
+
+async def test_get_now_playing_by_handle_returns_204_when_not_playing(
+    test_app: FastAPI, db_session: AsyncSession
+):
+    """test GET /now-playing/by-handle/{handle} returns 204 when nothing playing."""
+    # create artist
+    artist = Artist(
+        did="did:test:user123",
+        handle="test.user",
+        display_name="Test User",
+    )
+    db_session.add(artist)
+    await db_session.commit()
+
+    # no now playing state set
+
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.get("/now-playing/by-handle/test.user")
+
+    assert response.status_code == 204
+
+
+async def test_get_now_playing_by_handle_returns_204_when_paused(
+    test_app: FastAPI, db_session: AsyncSession
+):
+    """test GET /now-playing/by-handle/{handle} returns 204 when paused."""
+    # create artist
+    artist = Artist(
+        did="did:test:user123",
+        handle="test.user",
+        display_name="Test User",
+    )
+    db_session.add(artist)
+    await db_session.commit()
+
+    # set state with is_playing=False
+    now_playing_service.update(
+        did="did:test:user123",
+        track_name="Test Track",
+        artist_name="Test Artist",
+        album_name=None,
+        duration_ms=180000,
+        progress_ms=45000,
+        track_id=123,
+        file_id="test-file-abc",
+        track_url="https://plyr.fm/track/123",
+        image_url=None,
+        is_playing=False,  # paused
+    )
+
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.get("/now-playing/by-handle/test.user")
+
+    assert response.status_code == 204
+
+
+async def test_get_now_playing_by_handle_returns_404_for_unknown_user(
+    test_app: FastAPI, db_session: AsyncSession
+):
+    """test GET /now-playing/by-handle/{handle} returns 404 for unknown handle."""
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.get("/now-playing/by-handle/unknown.user")
+
+    assert response.status_code == 404
+    assert "not found" in response.json()["detail"].lower()
+
+
+async def test_get_now_playing_by_did(test_app: FastAPI, db_session: AsyncSession):
+    """test GET /now-playing/by-did/{did} returns playback state."""
+    # set now playing state
+    now_playing_service.update(
+        did="did:test:user123",
+        track_name="Test Track",
+        artist_name="Test Artist",
+        album_name=None,
+        duration_ms=180000,
+        progress_ms=60000,
+        track_id=456,
+        file_id="test-file-xyz",
+        track_url="https://plyr.fm/track/456",
+        image_url=None,
+        is_playing=True,
+    )
+
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.get("/now-playing/by-did/did:test:user123")
+
+    assert response.status_code == 200
+    data = response.json()
+
+    assert data["track_name"] == "Test Track"
+    assert data["artist_name"] == "Test Artist"
+    assert data["is_playing"] is True
+    assert data["service_base_url"] == "plyr.fm"
+
+
+async def test_get_now_playing_by_did_returns_204_when_not_playing(
+    test_app: FastAPI, db_session: AsyncSession
+):
+    """test GET /now-playing/by-did/{did} returns 204 when nothing playing."""
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.get("/now-playing/by-did/did:test:unknown")
+
+    assert response.status_code == 204
+
+
+async def test_now_playing_state_isolated_by_user(
+    test_app: FastAPI, db_session: AsyncSession
+):
+    """test that different users have isolated now-playing states."""
+    # set states for two different users
+    now_playing_service.update(
+        did="did:test:user1",
+        track_name="Track 1",
+        artist_name="Artist 1",
+        album_name=None,
+        duration_ms=100000,
+        progress_ms=10000,
+        track_id=1,
+        file_id="file1",
+        track_url="https://plyr.fm/track/1",
+        image_url=None,
+        is_playing=True,
+    )
+
+    now_playing_service.update(
+        did="did:test:user2",
+        track_name="Track 2",
+        artist_name="Artist 2",
+        album_name=None,
+        duration_ms=200000,
+        progress_ms=20000,
+        track_id=2,
+        file_id="file2",
+        track_url="https://plyr.fm/track/2",
+        image_url=None,
+        is_playing=True,
+    )
+
+    # verify states are isolated
+    state1 = now_playing_service.get("did:test:user1")
+    state2 = now_playing_service.get("did:test:user2")
+
+    assert state1 is not None
+    assert state2 is not None
+    assert state1.track_name == "Track 1"
+    assert state2.track_name == "Track 2"
+
+
+async def test_update_now_playing_without_album(
+    test_app: FastAPI, db_session: AsyncSession
+):
+    """test POST /now-playing works without optional album_name."""
+    payload = {
+        "track_id": 123,
+        "file_id": "test-file-abc",
+        "track_name": "Single Track",
+        "artist_name": "Solo Artist",
+        "duration_ms": 180000,
+        "progress_ms": 0,
+        "is_playing": True,
+    }
+
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.post("/now-playing/", json=payload)
+
+    assert response.status_code == 200
+
+    state = now_playing_service.get("did:test:user123")
+    assert state is not None
+    assert state.album_name is None
+    assert state.image_url is None

frontend/src/lib/components/player/Player.svelte

···
 <script lang="ts">
 	import { player } from '$lib/player.svelte';
 	import { queue } from '$lib/queue.svelte';
+	import { nowPlaying } from '$lib/now-playing.svelte';
 	import { API_URL } from '$lib/config';
 	import { onMount } from 'svelte';
 	import { page } from '$app/stores';
···
 		}
 	});
 
+	// report now-playing state for external integrations (teal.fm/Piper)
+	$effect(() => {
+		if (!player.currentTrack || !player.duration) return;
+
+		nowPlaying.report(
+			player.currentTrack,
+			!player.paused,
+			player.currentTime * 1000, // convert to ms
+			player.duration * 1000
+		);
+	});
+
 	// handle track changes - load new audio when track changes
 	let previousTrackId = $state<number | null>(null);
 	let isLoadingTrack = $state(false);
···
 	function handleTrackEnded() {
 		if (!queue.autoAdvance) {
 			player.reset();
+			nowPlaying.clear();
 			return;
 		}
 
···
 			queue.next();
 		} else {
 			player.reset();
+			nowPlaying.clear();
 		}
 	}
 

frontend/src/lib/now-playing.svelte.ts

···
+/**
+ * now-playing service for reporting playback state to backend.
+ *
+ * enables external integrations like teal.fm/Piper to fetch current playback.
+ * reports are throttled to avoid excessive API calls.
+ */
+
+import { browser } from '$app/environment';
+import { auth } from './auth.svelte';
+import { API_URL } from './config';
+import type { Track } from './types';
+
+const REPORT_INTERVAL_MS = 10_000; // report every 10 seconds during playback
+const REPORT_DEBOUNCE_MS = 1_000; // debounce rapid changes
+
+class NowPlayingService {
+	private lastReportTime = 0;
+	private reportTimer: number | null = null;
+	private lastReportedState: string | null = null;
+
+	/**
+	 * report current playback state to backend.
+	 * automatically debounces and throttles to avoid excessive API calls.
+	 */
+	async report(
+		track: Track | null,
+		isPlaying: boolean,
+		currentTimeMs: number,
+		durationMs: number
+	): Promise<void> {
+		if (!browser || !track) {
+			return;
+		}
+
+		// skip if not authenticated (auth uses HttpOnly cookies)
+		if (!auth.isAuthenticated) {
+			return;
+		}
+
+		// create state fingerprint to detect actual changes
+		const stateFingerprint = JSON.stringify({
+			trackId: track.id,
+			isPlaying,
+			// round progress to nearest 5 seconds to reduce noise
+			progressBucket: Math.floor(currentTimeMs / 5000)
+		});
+
+		// skip if state hasn't meaningfully changed
+		if (stateFingerprint === this.lastReportedState) {
+			return;
+		}
+
+		// throttle reports during continuous playback
+		const now = Date.now();
+		const timeSinceLastReport = now - this.lastReportTime;
+
+		if (timeSinceLastReport < REPORT_DEBOUNCE_MS) {
+			// debounce rapid changes (e.g., seeking)
+			this.scheduleReport(track, isPlaying, currentTimeMs, durationMs);
+			return;
+		}
+
+		if (isPlaying && timeSinceLastReport < REPORT_INTERVAL_MS) {
+			// throttle during continuous playback
+			this.scheduleReport(track, isPlaying, currentTimeMs, durationMs);
+			return;
+		}
+
+		// clear any pending scheduled report
+		if (this.reportTimer !== null) {
+			window.clearTimeout(this.reportTimer);
+			this.reportTimer = null;
+		}
+
+		await this.sendReport(track, isPlaying, currentTimeMs, durationMs);
+		this.lastReportTime = now;
+		this.lastReportedState = stateFingerprint;
+	}
+
+	private pendingState: { track: Track; isPlaying: boolean; currentTimeMs: number; durationMs: number } | null = null;
+
+	private scheduleReport(
+		track: Track,
+		isPlaying: boolean,
+		currentTimeMs: number,
+		durationMs: number
+	): void {
+		// always update pending state so timer fires with latest values
+		this.pendingState = { track, isPlaying, currentTimeMs, durationMs };
+
+		if (this.reportTimer !== null) {
+			return; // timer already running
+		}
+
+		this.reportTimer = window.setTimeout(async () => {
+			this.reportTimer = null;
+			if (this.pendingState) {
+				await this.sendReport(
+					this.pendingState.track,
+					this.pendingState.isPlaying,
+					this.pendingState.currentTimeMs,
+					this.pendingState.durationMs
+				);
+				this.pendingState = null;
+				this.lastReportTime = Date.now();
+			}
+		}, REPORT_DEBOUNCE_MS);
+	}
+
+	private async sendReport(
+		track: Track,
+		isPlaying: boolean,
+		currentTimeMs: number,
+		durationMs: number
+	): Promise<void> {
+		try {
+			await fetch(`${API_URL}/now-playing/`, {
+				method: 'POST',
+				headers: { 'Content-Type': 'application/json' },
+				credentials: 'include',
+				body: JSON.stringify({
+					track_id: track.id,
+					file_id: track.file_id,
+					track_name: track.title,
+					artist_name: track.artist,
+					album_name: track.album?.title ?? null,
+					duration_ms: Math.round(durationMs),
+					progress_ms: Math.round(currentTimeMs),
+					is_playing: isPlaying,
+					image_url: track.image_url ?? track.artist_avatar_url ?? null
+				})
+			});
+		} catch (error) {
+			// fail silently - now-playing is best-effort
+			console.debug('failed to report now-playing:', error);
+		}
+	}
+
+	/**
+	 * clear now-playing state when playback stops.
+	 */
+	async clear(): Promise<void> {
+		if (!browser) {
+			return;
+		}
+
+		// skip if not authenticated (auth uses HttpOnly cookies)
+		if (!auth.isAuthenticated) {
+			return;
+		}
+
+		// clear any pending report
+		if (this.reportTimer !== null) {
+			window.clearTimeout(this.reportTimer);
+			this.reportTimer = null;
+		}
+
+		this.lastReportedState = null;
+
+		try {
+			await fetch(`${API_URL}/now-playing/`, {
+				method: 'DELETE',
+				credentials: 'include'
+			});
+		} catch (error) {
+			console.debug('failed to clear now-playing:', error);
+		}
+	}
+}
+
+export const nowPlaying = new NowPlayingService();