feat: teal.fm scrobbling integration (#467)

* checkpoint

* checkpoint

* feat: teal.fm scrobbling integration

adds teal.fm scrobbling support - when users enable the toggle in settings
and re-authenticate, their plays are recorded to their PDS using teal's
ATProto lexicons.

changes:
- add TealSettings config class for configurable namespaces (TEAL_PLAY_COLLECTION,
TEAL_STATUS_COLLECTION, TEAL_ENABLED env vars)
- fix play count fetch missing credentials: 'include' (root cause of scrobbles
not triggering)
- add preferences.fetch() after login to ensure teal toggle state is current
- add unit tests for env var overrides (proves we can adapt when teal graduates
from alpha namespace)

the teal namespace defaults to fm.teal.alpha.* but can be changed via env vars
when teal.fm updates their lexicons.

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

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

* refactor: code quality improvements and bug fixes

- walrus operators throughout auth and playback code
- extract bearer token parsing into utilities/auth.py
- move DeveloperTokenInfo to top of file with field_validator for truncation
- fix now-playing firing every 1s (update lastReportedState in scheduled reports)
- use settings.frontend.url/domain for origin URLs (environment-aware)
- move teal.fm scrobbling setting from gear menu to portal "Your Data" section

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

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

---------

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

AGENTS.md

···
 
 **music streaming on AT Protocol**
 
+## Reminders
+- i am already hot-reloading the backend and frontend. i might also have ngrok exposing 8001
+- check the justfiles. there's a root one, one for the backend, one for the frontend, and one for the transcoder etc
+
 ## 🚨 Critical Rules & Workflows
 *   **Read `STATUS.md` First:** Always check for active tasks and known issues. This file is NEVER tracked in git.
 *   **Workflow:**
···
 *   **Observability:** Logfire.
 *   **`just` use the justfiles!**
 *   **use MCPs** for access to external systems, review docs/tools when needed
+
+### Neon Serverless Postgres
+- `plyr-prd` (cold-butterfly-11920742) - production (us-east-1)
+- `plyr-stg` (frosty-math-37367092) - staging (us-west-2)
+- `plyr-dev` (muddy-flower-98795112) - development (us-east-2)
 
 ## 💻 Development Commands
 *   **Backend:** `just backend run`

backend/alembic/versions/2025_12_03_172719_d4e6457a0fe3_add_enable_teal_scrobbling_preference.py

···
+"""add enable_teal_scrobbling preference
+
+Revision ID: d4e6457a0fe3
+Revises: 0d634c0a7259
+Create Date: 2025-12-03 17:27:19.016378
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "d4e6457a0fe3"
+down_revision: str | Sequence[str] | None = "0d634c0a7259"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    op.add_column(
+        "user_preferences",
+        sa.Column(
+            "enable_teal_scrobbling",
+            sa.Boolean(),
+            server_default=sa.text("false"),
+            nullable=False,
+        ),
+    )
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    op.drop_column("user_preferences", "enable_teal_scrobbling")

backend/src/backend/_internal/atproto/teal.py

···
+"""teal.fm record creation for scrobbling integration."""
+
+import logging
+from datetime import UTC, datetime
+from typing import Any
+
+from backend._internal import Session as AuthSession
+from backend._internal.atproto.records import _make_pds_request
+from backend.config import settings
+
+logger = logging.getLogger(__name__)
+
+
+def build_teal_play_record(
+    track_name: str,
+    artist_name: str,
+    duration: int | None = None,
+    album_name: str | None = None,
+    origin_url: str | None = None,
+) -> dict[str, Any]:
+    """build a teal.fm play record for scrobbling.
+
+    args:
+        track_name: track title
+        artist_name: primary artist name
+        duration: track duration in seconds
+        album_name: optional album/release name
+        origin_url: optional URL to the track on plyr.fm
+
+    returns:
+        record dict ready for ATProto
+    """
+    now = datetime.now(UTC)
+
+    record: dict[str, Any] = {
+        "$type": settings.teal.play_collection,
+        "trackName": track_name,
+        "artists": [{"artistName": artist_name}],
+        "musicServiceBaseDomain": "plyr.fm",
+        "submissionClientAgent": "plyr.fm/1.0",
+        "playedTime": now.isoformat().replace("+00:00", "Z"),
+    }
+
+    if duration:
+        record["duration"] = duration
+    if album_name:
+        record["releaseName"] = album_name
+    if origin_url:
+        record["originUrl"] = origin_url
+
+    return record
+
+
+def build_teal_status_record(
+    track_name: str,
+    artist_name: str,
+    duration: int | None = None,
+    album_name: str | None = None,
+    origin_url: str | None = None,
+) -> dict[str, Any]:
+    """build a teal.fm actor status record (now playing).
+
+    args:
+        track_name: track title
+        artist_name: primary artist name
+        duration: track duration in seconds
+        album_name: optional album/release name
+        origin_url: optional URL to the track on plyr.fm
+
+    returns:
+        record dict ready for ATProto
+    """
+    now = datetime.now(UTC)
+    # expiry defaults to 10 minutes from now
+    expiry = datetime.fromtimestamp(now.timestamp() + 600, UTC)
+
+    # build the playView item
+    item: dict[str, Any] = {
+        "trackName": track_name,
+        "artists": [{"artistName": artist_name}],
+        "musicServiceBaseDomain": "plyr.fm",
+        "submissionClientAgent": "plyr.fm/1.0",
+        "playedTime": now.isoformat().replace("+00:00", "Z"),
+    }
+
+    if duration:
+        item["duration"] = duration
+    if album_name:
+        item["releaseName"] = album_name
+    if origin_url:
+        item["originUrl"] = origin_url
+
+    record: dict[str, Any] = {
+        "$type": settings.teal.status_collection,
+        "time": now.isoformat().replace("+00:00", "Z"),
+        "expiry": expiry.isoformat().replace("+00:00", "Z"),
+        "item": item,
+    }
+
+    return record
+
+
+async def create_teal_play_record(
+    auth_session: AuthSession,
+    track_name: str,
+    artist_name: str,
+    duration: int | None = None,
+    album_name: str | None = None,
+    origin_url: str | None = None,
+) -> str:
+    """create a teal.fm play record (scrobble) on the user's PDS.
+
+    args:
+        auth_session: authenticated user session with teal scopes
+        track_name: track title
+        artist_name: primary artist name
+        duration: track duration in seconds
+        album_name: optional album/release name
+        origin_url: optional URL to the track on plyr.fm
+
+    returns:
+        record URI
+
+    raises:
+        ValueError: if session is invalid
+        Exception: if record creation fails
+    """
+    record = build_teal_play_record(
+        track_name=track_name,
+        artist_name=artist_name,
+        duration=duration,
+        album_name=album_name,
+        origin_url=origin_url,
+    )
+
+    payload = {
+        "repo": auth_session.did,
+        "collection": settings.teal.play_collection,
+        "record": record,
+    }
+
+    result = await _make_pds_request(
+        auth_session, "POST", "com.atproto.repo.createRecord", payload
+    )
+    return result["uri"]
+
+
+async def update_teal_status(
+    auth_session: AuthSession,
+    track_name: str,
+    artist_name: str,
+    duration: int | None = None,
+    album_name: str | None = None,
+    origin_url: str | None = None,
+) -> str:
+    """update the user's teal.fm status (now playing).
+
+    uses putRecord with rkey "self" as per the lexicon spec.
+
+    args:
+        auth_session: authenticated user session with teal scopes
+        track_name: track title
+        artist_name: primary artist name
+        duration: track duration in seconds
+        album_name: optional album/release name
+        origin_url: optional URL to the track on plyr.fm
+
+    returns:
+        record URI
+
+    raises:
+        ValueError: if session is invalid
+        Exception: if record creation fails
+    """
+    record = build_teal_status_record(
+        track_name=track_name,
+        artist_name=artist_name,
+        duration=duration,
+        album_name=album_name,
+        origin_url=origin_url,
+    )
+
+    payload = {
+        "repo": auth_session.did,
+        "collection": settings.teal.status_collection,
+        "rkey": "self",
+        "record": record,
+    }
+
+    result = await _make_pds_request(
+        auth_session, "POST", "com.atproto.repo.putRecord", payload
+    )
+    return result["uri"]

backend/src/backend/_internal/auth.py

···
 
 from backend._internal.oauth_stores import PostgresStateStore
 from backend.config import settings
-from backend.models import ExchangeToken, PendingDevToken, UserSession
+from backend.models import ExchangeToken, PendingDevToken, UserPreferences, UserSession
 from backend.utilities.database import db_session
 
 logger = logging.getLogger(__name__)
···
 _state_store = PostgresStateStore()
 _session_store = MemorySessionStore()
 
-# OAuth client
+# OAuth clients - base client for normal auth, teal client for users who want scrobbling
 oauth_client = OAuthClient(
     client_id=settings.atproto.client_id,
     redirect_uri=settings.atproto.redirect_uri,
···
     state_store=_state_store,
     session_store=_session_store,
 )
+
+oauth_client_with_teal = OAuthClient(
+    client_id=settings.atproto.client_id,
+    redirect_uri=settings.atproto.redirect_uri,
+    scope=settings.atproto.resolved_scope_with_teal(
+        settings.teal.play_collection, settings.teal.status_collection
+    ),
+    state_store=_state_store,
+    session_store=_session_store,
+)
+
+
+def get_oauth_client_for_scope(scope: str) -> OAuthClient:
+    """get the appropriate OAuth client for a given scope string."""
+    if settings.teal.play_collection in scope:
+        return oauth_client_with_teal
+    return oauth_client
+
 
 # encryption for sensitive OAuth data at rest
 # CRITICAL: encryption key must be configured and stable across restarts
···
             await db.commit()
 
 
+async def _check_teal_preference(did: str) -> bool:
+    """check if user has enabled teal.fm scrobbling."""
+    async with db_session() as db:
+        result = await db.execute(
+            select(UserPreferences.enable_teal_scrobbling).where(
+                UserPreferences.did == did
+            )
+        )
+        pref = result.scalar_one_or_none()
+        return pref is True
+
+
 async def start_oauth_flow(handle: str) -> tuple[str, str]:
-    """start OAuth flow and return (auth_url, state)."""
+    """start OAuth flow and return (auth_url, state).
+
+    uses extended scope if user has enabled teal.fm scrobbling.
+    """
+    from backend._internal.atproto.handles import resolve_handle
+
     try:
-        auth_url, state = await oauth_client.start_authorization(handle)
+        # resolve handle to DID to check preferences
+        resolved = await resolve_handle(handle)
+        if resolved:
+            did = resolved["did"]
+            wants_teal = await _check_teal_preference(did)
+            client = oauth_client_with_teal if wants_teal else oauth_client
+            logger.info(f"starting OAuth for {handle} (did={did}, teal={wants_teal})")
+        else:
+            # fallback to base client if resolution fails
+            # (OAuth flow will resolve handle again internally)
+            client = oauth_client
+            logger.info(f"starting OAuth for {handle} (resolution failed, using base)")
+
+        auth_url, state = await client.start_authorization(handle)
         return auth_url, state
     except Exception as e:
         raise HTTPException(
···
 async def handle_oauth_callback(
     code: str, state: str, iss: str
 ) -> tuple[str, str, dict]:
-    """handle OAuth callback and return (did, handle, oauth_session)."""
+    """handle OAuth callback and return (did, handle, oauth_session).
+
+    uses the appropriate OAuth client based on stored state's scope.
+    """
     try:
-        oauth_session = await oauth_client.handle_callback(
+        # look up stored state to determine which scope was used
+        if stored_state := await _state_store.get_state(state):
+            client = get_oauth_client_for_scope(stored_state.scope)
+            logger.info(
+                f"callback using client for scope: {stored_state.scope[:50]}..."
+            )
+        else:
+            # fallback to base client (state might have been cleaned up)
+            client = oauth_client
+            logger.warning(f"state {state[:8]}... not found, using base client")
+
+        oauth_session = await client.handle_callback(
             code=code,
             state=state,
             iss=iss,

backend/src/backend/api/auth.py

···
 
 from fastapi import APIRouter, Depends, HTTPException, Query, Request
 from fastapi.responses import JSONResponse, RedirectResponse
-from pydantic import BaseModel
+from pydantic import BaseModel, field_validator
 from starlette.responses import Response
 
 from backend._internal import (
···
 
     did: str
     handle: str
+
+
+class DeveloperTokenInfo(BaseModel):
+    """info about a developer token (without the actual token)."""
+
+    session_id: str
+    name: str | None
+    created_at: str  # ISO format
+    expires_at: str | None  # ISO format or null for never
+
+    @field_validator("session_id", mode="before")
+    @classmethod
+    def truncate_session_id(cls, v: str) -> str:
+        """truncate to 8-char prefix for safe display."""
+        return v[:8] if len(v) > 8 else v
+
+
+class DeveloperTokenListResponse(BaseModel):
+    """response model for listing developer tokens."""
+
+    tokens: list[DeveloperTokenInfo]
 
 
 @router.get("/start")
···
     )
 
 
-class DeveloperTokenInfo(BaseModel):
-    """info about a developer token (without the actual token)."""
-
-    session_id: str  # first 8 chars only for identification
-    name: str | None
-    created_at: str  # ISO format
-    expires_at: str | None  # ISO format or null for never
-
-
-class DeveloperTokenListResponse(BaseModel):
-    """response model for listing developer tokens."""
-
-    tokens: list[DeveloperTokenInfo]
-
-
 @router.get("/developer-tokens")
 async def get_developer_tokens(
     session: Session = Depends(require_auth),
···
     return DeveloperTokenListResponse(
         tokens=[
             DeveloperTokenInfo(
-                session_id=t.session_id[:8],  # only show prefix for identification
+                session_id=t.session_id,
                 name=t.token_name,
                 created_at=t.created_at.isoformat(),
                 expires_at=t.expires_at.isoformat() if t.expires_at else None,

backend/src/backend/api/now_playing.py

···
     track_url: str
     image_url: str | None
 
-    # service identifier for Piper
-    service_base_url: str = "plyr.fm"
+    # service identifier for Piper (domain extracted from frontend URL)
+    service_base_url: str
 
 
 @router.post("/")
···
         file_id=state.file_id,
         track_url=state.track_url,
         image_url=state.image_url,
-        service_base_url="plyr.fm",
+        service_base_url=settings.frontend.domain,
     )
 
 
···
         file_id=state.file_id,
         track_url=state.track_url,
         image_url=state.image_url,
-        service_base_url="plyr.fm",
+        service_base_url=settings.frontend.domain,
     )

backend/src/backend/api/preferences.py

···
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from backend._internal import Session, require_auth
+from backend.config import settings
 from backend.models import UserPreferences, get_db
 from backend.utilities.tags import DEFAULT_HIDDEN_TAGS
 
···
     auto_advance: bool
     allow_comments: bool
     hidden_tags: list[str]
+    enable_teal_scrobbling: bool
+    # indicates if user needs to re-login to activate teal scrobbling
+    teal_needs_reauth: bool = False
 
 
 class PreferencesUpdate(BaseModel):
···
     auto_advance: bool | None = None
     allow_comments: bool | None = None
     hidden_tags: list[str] | None = None
+    enable_teal_scrobbling: bool | None = None
+
+
+def _has_teal_scope(session: Session) -> bool:
+    """check if session has teal.fm scopes."""
+    if not session.oauth_session:
+        return False
+    scope = session.oauth_session.get("scope", "")
+    return settings.teal.play_collection in scope
 
 
 @router.get("/")
···
         await db.commit()
         await db.refresh(prefs)
 
+    # check if user wants teal but doesn't have the scope
+    has_scope = _has_teal_scope(session)
+    teal_needs_reauth = prefs.enable_teal_scrobbling and not has_scope
+
     return PreferencesResponse(
         accent_color=prefs.accent_color,
         auto_advance=prefs.auto_advance,
         allow_comments=prefs.allow_comments,
         hidden_tags=prefs.hidden_tags or [],
+        enable_teal_scrobbling=prefs.enable_teal_scrobbling,
+        teal_needs_reauth=teal_needs_reauth,
     )
 
 
···
             hidden_tags=update.hidden_tags
             if update.hidden_tags is not None
             else list(DEFAULT_HIDDEN_TAGS),
+            enable_teal_scrobbling=update.enable_teal_scrobbling
+            if update.enable_teal_scrobbling is not None
+            else False,
         )
         db.add(prefs)
     else:
···
             prefs.allow_comments = update.allow_comments
         if update.hidden_tags is not None:
             prefs.hidden_tags = update.hidden_tags
+        if update.enable_teal_scrobbling is not None:
+            prefs.enable_teal_scrobbling = update.enable_teal_scrobbling
 
     await db.commit()
     await db.refresh(prefs)
 
+    # check if user wants teal but doesn't have the scope
+    has_scope = _has_teal_scope(session)
+    teal_needs_reauth = prefs.enable_teal_scrobbling and not has_scope
+
     return PreferencesResponse(
         accent_color=prefs.accent_color,
         auto_advance=prefs.auto_advance,
         allow_comments=prefs.allow_comments,
         hidden_tags=prefs.hidden_tags or [],
+        enable_teal_scrobbling=prefs.enable_teal_scrobbling,
+        teal_needs_reauth=teal_needs_reauth,
     )

backend/src/backend/api/tracks/playback.py

···
 """Track detail and playback endpoints."""
 
+import asyncio
+import logging
 from typing import Annotated
 
-from fastapi import Cookie, Depends, HTTPException, Request
+from fastapi import BackgroundTasks, Cookie, Depends, HTTPException, Request
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import selectinload
 
+from backend._internal.atproto.teal import create_teal_play_record, update_teal_status
 from backend._internal.auth import get_session
-from backend.models import Artist, Track, TrackLike, get_db
+from backend.config import settings
+from backend.models import Artist, Track, TrackLike, UserPreferences, get_db
 from backend.schemas import TrackResponse
 from backend.utilities.aggregations import get_like_counts, get_track_tags
+from backend.utilities.auth import get_session_id_from_request
 
 from .router import router
+
+logger = logging.getLogger(__name__)
 
 
 @router.get("/{track_id}")
···
 ) -> TrackResponse:
     """Get a specific track."""
     liked_track_ids: set[int] | None = None
-    session_id = session_id_cookie or request.headers.get("authorization", "").replace(
-        "Bearer ", ""
-    )
     if (
-        session_id
+        (session_id := get_session_id_from_request(request, session_id_cookie))
         and (auth_session := await get_session(session_id))
         and await db.scalar(
             select(TrackLike.track_id).where(
···
         .options(selectinload(Track.artist), selectinload(Track.album_rel))
         .where(Track.id == track_id)
     )
-    track = result.scalar_one_or_none()
-
-    if not track:
+    if not (track := result.scalar_one_or_none()):
         raise HTTPException(status_code=404, detail="track not found")
 
-    like_counts = await get_like_counts(db, [track_id])
-    track_tags = await get_track_tags(db, [track_id])
+    like_counts, track_tags = await asyncio.gather(
+        get_like_counts(db, [track_id]),
+        get_track_tags(db, [track_id]),
+    )
 
     return await TrackResponse.from_track(
         track,
···
     )
 
 
+async def _scrobble_to_teal(
+    session_id: str,
+    track_id: int,
+    track_title: str,
+    artist_name: str,
+    duration: int | None,
+    album_name: str | None,
+) -> None:
+    """scrobble a play to teal.fm (creates play record + updates status)."""
+    if not (auth_session := await get_session(session_id)):
+        logger.warning(f"teal scrobble failed: session {session_id[:8]}... not found")
+        return
+
+    origin_url = f"{settings.frontend.url}/track/{track_id}"
+
+    try:
+        # create play record (scrobble)
+        play_uri = await create_teal_play_record(
+            auth_session=auth_session,
+            track_name=track_title,
+            artist_name=artist_name,
+            duration=duration,
+            album_name=album_name,
+            origin_url=origin_url,
+        )
+        logger.info(f"teal play record created: {play_uri}")
+
+        # update status (now playing)
+        status_uri = await update_teal_status(
+            auth_session=auth_session,
+            track_name=track_title,
+            artist_name=artist_name,
+            duration=duration,
+            album_name=album_name,
+            origin_url=origin_url,
+        )
+        logger.info(f"teal status updated: {status_uri}")
+
+    except Exception as e:
+        logger.error(f"teal scrobble failed for track {track_id}: {e}", exc_info=True)
+
+
 @router.post("/{track_id}/play")
 async def increment_play_count(
-    track_id: int, db: Annotated[AsyncSession, Depends(get_db)]
+    track_id: int,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    request: Request,
+    background_tasks: BackgroundTasks,
+    session_id_cookie: Annotated[str | None, Cookie(alias="session_id")] = None,
 ) -> dict:
-    """Increment play count for a track (called after 30 seconds of playback)."""
-    result = await db.execute(select(Track).where(Track.id == track_id))
-    track = result.scalar_one_or_none()
+    """Increment play count for a track (called after 30 seconds of playback).
+
+    If user has teal.fm scrobbling enabled and has the required scopes,
+    also writes play record to their PDS.
+    """
+    # load track with artist info
+    result = await db.execute(
+        select(Track)
+        .options(selectinload(Track.artist), selectinload(Track.album_rel))
+        .where(Track.id == track_id)
+    )
 
-    if not track:
+    if not (track := result.scalar_one_or_none()):
         raise HTTPException(status_code=404, detail="track not found")
 
     track.play_count += 1
     await db.commit()
+
+    # check if user wants teal scrobbling
+    if (
+        (session_id := get_session_id_from_request(request, session_id_cookie))
+        and (auth_session := await get_session(session_id))
+        and (
+            prefs := await db.scalar(
+                select(UserPreferences).where(UserPreferences.did == auth_session.did)
+            )
+        )
+        and prefs.enable_teal_scrobbling
+    ):
+        # check if session has teal scopes
+        scope = auth_session.oauth_session.get("scope", "")
+        if settings.teal.play_collection in scope:
+            background_tasks.add_task(
+                _scrobble_to_teal,
+                session_id=session_id,
+                track_id=track_id,
+                track_title=track.title,
+                artist_name=track.artist.display_name or track.artist.handle,
+                duration=track.duration,
+                album_name=track.album_rel.title if track.album_rel else None,
+            )
 
     return {"play_count": track.play_count}

backend/src/backend/config.py

···
 
     @computed_field
     @property
+    def domain(self) -> str:
+        """extract domain from frontend URL (e.g., 'plyr.fm', 'stg.plyr.fm')."""
+        from urllib.parse import urlparse
+
+        parsed = urlparse(self.url)
+        return parsed.netloc or "plyr.fm"
+
+    @computed_field
+    @property
     def resolved_cors_origin_regex(self) -> str:
         """Resolved CORS origin regex pattern."""
         if self.cors_origin_regex is not None:
···
 
         return f"atproto {' '.join(scopes)}"
 
+    def resolved_scope_with_teal(self, teal_play: str, teal_status: str) -> str:
+        """OAuth scope including teal.fm scrobbling permissions.
+
+        args:
+            teal_play: teal.fm play collection NSID (e.g., fm.teal.alpha.feed.play)
+            teal_status: teal.fm status collection NSID (e.g., fm.teal.alpha.actor.status)
+        """
+        base = self.resolved_scope
+        teal_scopes = [f"repo:{teal_play}", f"repo:{teal_status}"]
+        return f"{base} {' '.join(teal_scopes)}"
+
+
+class TealSettings(AppSettingsSection):
+    """teal.fm integration settings for scrobbling.
+
+    teal.fm is a music scrobbling service built on ATProto. when users enable
+    scrobbling, plyr.fm writes play records to their PDS using teal's lexicons.
+
+    these namespaces may change as teal.fm evolves from alpha to stable.
+    configure via environment variables to adapt without code changes.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="TEAL_",
+        env_file=".env",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    enabled: bool = Field(
+        default=True,
+        description="Enable teal.fm scrobbling feature. When False, the toggle is hidden and no scrobbles are sent.",
+    )
+    play_collection: str = Field(
+        default="fm.teal.alpha.feed.play",
+        description="Lexicon NSID for teal.fm play records (scrobbles)",
+    )
+    status_collection: str = Field(
+        default="fm.teal.alpha.actor.status",
+        description="Lexicon NSID for teal.fm actor status (now playing)",
+    )
+
 
 class ObservabilitySettings(AppSettingsSection):
     """Observability configuration."""
···
     moderation: ModerationSettings = Field(
         default_factory=ModerationSettings,
         description="Moderation service settings",
+    )
+    teal: TealSettings = Field(
+        default_factory=TealSettings,
+        description="teal.fm scrobbling integration settings",
     )
 
 

backend/src/backend/main.py

···
         "client_name": settings.app.name,
         "client_uri": client_uri,
         "redirect_uris": [settings.atproto.redirect_uri],
-        "scope": settings.atproto.resolved_scope,
+        "scope": settings.atproto.resolved_scope_with_teal(
+            settings.teal.play_collection, settings.teal.status_collection
+        ),
         "grant_types": ["authorization_code", "refresh_token"],
         "response_types": ["code"],
         "token_endpoint_auth_method": "none",

backend/src/backend/models/preferences.py

···
         server_default=text("'[\"ai\"]'::jsonb"),
     )
 
+    # teal.fm scrobbling integration
+    # when enabled, plays are written to user's PDS as fm.teal.alpha.feed.play records
+    # requires re-login to grant teal scopes after enabling
+    enable_teal_scrobbling: Mapped[bool] = mapped_column(
+        Boolean, nullable=False, default=False, server_default=text("false")
+    )
+
     # metadata
     created_at: Mapped[datetime] = mapped_column(
         DateTime(timezone=True),

backend/src/backend/utilities/auth.py

···
+"""authentication utilities."""
+
+from fastapi import Request
+
+
+def get_session_id_from_request(
+    request: Request, session_id_cookie: str | None = None
+) -> str | None:
+    """extract session ID from cookie or authorization header.
+
+    checks cookie first (browser requests), then falls back to bearer token
+    in authorization header (SDK/CLI clients).
+    """
+    if session_id_cookie:
+        return session_id_cookie
+
+    if authorization := request.headers.get("authorization"):
+        return authorization.removeprefix("Bearer ")
+
+    return None

backend/tests/api/test_now_playing.py

···
 from sqlalchemy.ext.asyncio import AsyncSession
 
 from backend._internal import Session, now_playing_service
+from backend.config import settings
 from backend.main import app
 from backend.models import Artist
 
···
     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"
+    assert data["service_base_url"] == settings.frontend.domain
 
 
 async def test_get_now_playing_by_handle_returns_204_when_not_playing(
···
     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"
+    assert data["service_base_url"] == settings.frontend.domain
 
 
 async def test_get_now_playing_by_did_returns_204_when_not_playing(

backend/tests/api/test_preferences.py

···
+"""tests for preferences api endpoints."""
+
+from collections.abc import AsyncGenerator
+
+import pytest
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend._internal import Session, require_auth
+from backend.config import settings
+from backend.main import app
+
+
+class MockSession(Session):
+    """mock session for auth bypass in tests."""
+
+    def __init__(
+        self, did: str = "did:test:user123", scope: str = "atproto transition:generic"
+    ):
+        self.did = did
+        self.handle = "testuser.bsky.social"
+        self.session_id = "test_session_id"
+        self.access_token = "test_token"
+        self.refresh_token = "test_refresh"
+        self.oauth_session = {
+            "did": did,
+            "handle": "testuser.bsky.social",
+            "pds_url": "https://test.pds",
+            "authserver_iss": "https://auth.test",
+            "scope": scope,
+            "access_token": "test_token",
+            "refresh_token": "test_refresh",
+            "dpop_private_key_pem": "fake_key",
+            "dpop_authserver_nonce": "",
+            "dpop_pds_nonce": "",
+        }
+
+
[e-mail]
+def mock_session() -> MockSession:
+    """default mock session without teal scopes."""
+    return MockSession()
+
+
[e-mail]
+def mock_session_with_teal() -> MockSession:
+    """mock session with teal scopes."""
+    return MockSession(
+        scope=settings.atproto.resolved_scope_with_teal(
+            settings.teal.play_collection, settings.teal.status_collection
+        )
+    )
+
+
[e-mail]
+async def client_no_teal(
+    db_session: AsyncSession,
+    mock_session: MockSession,
+) -> AsyncGenerator[AsyncClient, None]:
+    """authenticated client without teal scopes."""
+    app.dependency_overrides[require_auth] = lambda: mock_session
+
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+    ) as client:
+        yield client
+
+    app.dependency_overrides.clear()
+
+
[e-mail]
+async def client_with_teal(
+    db_session: AsyncSession,
+    mock_session_with_teal: MockSession,
+) -> AsyncGenerator[AsyncClient, None]:
+    """authenticated client with teal scopes."""
+    app.dependency_overrides[require_auth] = lambda: mock_session_with_teal
+
+    async with AsyncClient(
+        transport=ASGITransport(app=app),
+        base_url="http://test",
+    ) as client:
+        yield client
+
+    app.dependency_overrides.clear()
+
+
+async def test_get_preferences_includes_teal_fields(
+    client_no_teal: AsyncClient,
+):
+    """should return teal scrobbling fields in preferences response."""
+    response = await client_no_teal.get("/preferences/")
+    assert response.status_code == 200
+
+    data = response.json()
+    assert "enable_teal_scrobbling" in data
+    assert "teal_needs_reauth" in data
+    # default should be disabled
+    assert data["enable_teal_scrobbling"] is False
+
+
+async def test_update_teal_scrobbling_preference(
+    client_no_teal: AsyncClient,
+):
+    """should update teal scrobbling preference."""
+    # enable teal scrobbling
+    response = await client_no_teal.post(
+        "/preferences/",
+        json={"enable_teal_scrobbling": True},
+    )
+    assert response.status_code == 200
+
+    data = response.json()
+    assert data["enable_teal_scrobbling"] is True
+    # should need reauth since session doesn't have teal scopes
+    assert data["teal_needs_reauth"] is True
+
+
+async def test_teal_needs_reauth_false_when_disabled(
+    client_no_teal: AsyncClient,
+):
+    """should not need reauth when teal scrobbling is disabled."""
+    response = await client_no_teal.post(
+        "/preferences/",
+        json={"enable_teal_scrobbling": False},
+    )
+    assert response.status_code == 200
+
+    data = response.json()
+    assert data["enable_teal_scrobbling"] is False
+    assert data["teal_needs_reauth"] is False
+
+
+async def test_teal_no_reauth_needed_with_scope(
+    client_with_teal: AsyncClient,
+):
+    """should not need reauth when teal is enabled and scope is present."""
+    # first enable teal
+    await client_with_teal.post(
+        "/preferences/",
+        json={"enable_teal_scrobbling": True},
+    )
+
+    # then get preferences
+    response = await client_with_teal.get("/preferences/")
+    assert response.status_code == 200
+
+    data = response.json()
+    assert data["enable_teal_scrobbling"] is True
+    # should NOT need reauth since session has teal scopes
+    assert data["teal_needs_reauth"] is False

backend/tests/test_teal_scrobbling.py

···
+"""tests for teal.fm scrobbling integration."""
+
+from backend._internal.atproto.teal import (
+    build_teal_play_record,
+    build_teal_status_record,
+)
+from backend.config import TealSettings, settings
+
+
+class TestBuildTealPlayRecord:
+    """tests for build_teal_play_record."""
+
+    def test_builds_minimal_record(self):
+        """should build record with required fields only."""
+        record = build_teal_play_record(
+            track_name="Test Track",
+            artist_name="Test Artist",
+        )
+
+        assert record["$type"] == settings.teal.play_collection
+        assert record["trackName"] == "Test Track"
+        assert record["artists"] == [{"artistName": "Test Artist"}]
+        assert record["musicServiceBaseDomain"] == "plyr.fm"
+        assert record["submissionClientAgent"] == "plyr.fm/1.0"
+        assert "playedTime" in record
+
+    def test_includes_optional_fields(self):
+        """should include optional fields when provided."""
+        record = build_teal_play_record(
+            track_name="Test Track",
+            artist_name="Test Artist",
+            duration=180,
+            album_name="Test Album",
+            origin_url="https://plyr.fm/track/123",
+        )
+
+        assert record["duration"] == 180
+        assert record["releaseName"] == "Test Album"
+        assert record["originUrl"] == "https://plyr.fm/track/123"
+
+
+class TestBuildTealStatusRecord:
+    """tests for build_teal_status_record."""
+
+    def test_builds_status_record(self):
+        """should build status record with item."""
+        record = build_teal_status_record(
+            track_name="Now Playing",
+            artist_name="Cool Artist",
+        )
+
+        assert record["$type"] == settings.teal.status_collection
+        assert "time" in record
+        assert "expiry" in record
+        assert "item" in record
+
+        item = record["item"]
+        assert item["trackName"] == "Now Playing"
+        assert item["artists"] == [{"artistName": "Cool Artist"}]
+
+    def test_expiry_is_after_time(self):
+        """should set expiry after time."""
+        record = build_teal_status_record(
+            track_name="Test",
+            artist_name="Test",
+        )
+
+        # expiry should be 10 minutes after time
+        assert record["expiry"] > record["time"]
+
+
+class TestTealSettings:
+    """tests for teal.fm settings configuration."""
+
+    def test_default_play_collection(self):
+        """should have correct default teal play collection."""
+        assert settings.teal.play_collection == "fm.teal.alpha.feed.play"
+
+    def test_default_status_collection(self):
+        """should have correct default teal status collection."""
+        assert settings.teal.status_collection == "fm.teal.alpha.actor.status"
+
+    def test_default_enabled(self):
+        """should be enabled by default."""
+        assert settings.teal.enabled is True
+
+    def test_resolved_scope_with_teal(self):
+        """should include teal scopes in extended scope."""
+        scope = settings.atproto.resolved_scope_with_teal(
+            settings.teal.play_collection, settings.teal.status_collection
+        )
+
+        assert "fm.teal.alpha.feed.play" in scope
+        assert "fm.teal.alpha.actor.status" in scope
+        # should also include base scopes
+        assert settings.atproto.track_collection in scope
+
+    def test_env_override_play_collection(self, monkeypatch):
+        """should allow overriding play collection via environment variable.
+
+        this proves we can adapt when teal.fm changes namespaces
+        (e.g., from alpha to stable: fm.teal.feed.play).
+        """
+        monkeypatch.setenv("TEAL_PLAY_COLLECTION", "fm.teal.feed.play")
+
+        # create fresh settings to pick up env var
+        teal = TealSettings()
+        assert teal.play_collection == "fm.teal.feed.play"
+
+    def test_env_override_status_collection(self, monkeypatch):
+        """should allow overriding status collection via environment variable."""
+        monkeypatch.setenv("TEAL_STATUS_COLLECTION", "fm.teal.actor.status")
+
+        teal = TealSettings()
+        assert teal.status_collection == "fm.teal.actor.status"
+
+    def test_env_override_enabled(self, monkeypatch):
+        """should allow disabling teal integration via environment variable."""
+        monkeypatch.setenv("TEAL_ENABLED", "false")
+
+        teal = TealSettings()
+        assert teal.enabled is False
+
+    def test_scope_uses_configured_collections(self, monkeypatch):
+        """should use configured collections in OAuth scope.
+
+        when teal.fm graduates from alpha, we can update via env vars
+        without code changes.
+        """
+        monkeypatch.setenv("TEAL_PLAY_COLLECTION", "fm.teal.feed.play")
+        monkeypatch.setenv("TEAL_STATUS_COLLECTION", "fm.teal.actor.status")
+
+        teal = TealSettings()
+        scope = settings.atproto.resolved_scope_with_teal(
+            teal.play_collection, teal.status_collection
+        )
+
+        assert "fm.teal.feed.play" in scope
+        assert "fm.teal.actor.status" in scope
+        # alpha namespaces should NOT be in scope when overridden
+        assert "fm.teal.alpha.feed.play" not in scope
+        assert "fm.teal.alpha.actor.status" not in scope

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

···
 		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
-				);
+				const { track, isPlaying, currentTimeMs, durationMs } = this.pendingState;
+				await this.sendReport(track, isPlaying, currentTimeMs, durationMs);
 				this.pendingState = null;
 				this.lastReportTime = Date.now();
+				// update fingerprint so we don't re-report the same state
+				this.lastReportedState = JSON.stringify({
+					trackId: track.id,
+					isPlaying,
+					progressBucket: Math.floor(currentTimeMs / 5000)
+				});
 			}
 		}, REPORT_DEBOUNCE_MS);
 	}

frontend/src/lib/player.svelte.ts

···
 			this.playCountedForTrack = this.currentTrack.id;
 
 			fetch(`${API_URL}/tracks/${this.currentTrack.id}/play`, {
-				method: 'POST'
+				method: 'POST',
+				credentials: 'include'
 			}).catch(err => {
 				console.error('failed to increment play count:', err);
 			});

frontend/src/lib/preferences.svelte.ts

···
 	allow_comments: boolean;
 	hidden_tags: string[];
 	theme: Theme;
+	enable_teal_scrobbling: boolean;
+	teal_needs_reauth: boolean;
 }
 
 const DEFAULT_PREFERENCES: Preferences = {
···
 	auto_advance: true,
 	allow_comments: true,
 	hidden_tags: ['ai'],
-	theme: 'dark'
+	theme: 'dark',
+	enable_teal_scrobbling: false,
+	teal_needs_reauth: false
 };
 
 class PreferencesManager {
···
 		return this.data?.theme ?? DEFAULT_PREFERENCES.theme;
 	}
 
+	get enableTealScrobbling(): boolean {
+		return this.data?.enable_teal_scrobbling ?? DEFAULT_PREFERENCES.enable_teal_scrobbling;
+	}
+
+	get tealNeedsReauth(): boolean {
+		return this.data?.teal_needs_reauth ?? DEFAULT_PREFERENCES.teal_needs_reauth;
+	}
+
 	setTheme(theme: Theme): void {
 		if (browser) {
 			localStorage.setItem('theme', theme);
···
 					auto_advance: data.auto_advance ?? DEFAULT_PREFERENCES.auto_advance,
 					allow_comments: data.allow_comments ?? DEFAULT_PREFERENCES.allow_comments,
 					hidden_tags: data.hidden_tags ?? DEFAULT_PREFERENCES.hidden_tags,
-					theme: data.theme ?? DEFAULT_PREFERENCES.theme
+					theme: data.theme ?? DEFAULT_PREFERENCES.theme,
+					enable_teal_scrobbling: data.enable_teal_scrobbling ?? DEFAULT_PREFERENCES.enable_teal_scrobbling,
+					teal_needs_reauth: data.teal_needs_reauth ?? DEFAULT_PREFERENCES.teal_needs_reauth
 				};
 			} else {
 				this.data = { ...DEFAULT_PREFERENCES };

frontend/src/routes/+layout.ts

···
 	auto_advance: true,
 	allow_comments: true,
 	hidden_tags: ['ai'],
-	theme: 'dark'
+	theme: 'dark',
+	enable_teal_scrobbling: false,
+	teal_needs_reauth: false
 };
 
 export async function load({ fetch }: LoadEvent): Promise<LayoutData> {
···
 						auto_advance: data.auto_advance ?? true,
 						allow_comments: data.allow_comments ?? true,
 						hidden_tags: data.hidden_tags ?? ['ai'],
-						theme: data.theme ?? 'dark'
+						theme: data.theme ?? 'dark',
+						enable_teal_scrobbling: data.enable_teal_scrobbling ?? false,
+						teal_needs_reauth: data.teal_needs_reauth ?? false
 					};
 				}
 			} catch (e) {

frontend/src/routes/portal/+page.svelte

···
 	let avatarUrl = $state('');
 	// derive from preferences store
 	let allowComments = $derived(preferences.allowComments);
+	let enableTealScrobbling = $derived(preferences.enableTealScrobbling);
+	let tealNeedsReauth = $derived(preferences.tealNeedsReauth);
 	let savingProfile = $state(false);
 	let profileSuccess = $state('');
 	let profileError = $state('');
···
 						developerToken = data.session_id;
 						toast.success('developer token created - save it now!');
 					} else {
-						// regular login - initialize auth
+						// regular login - initialize auth and refresh preferences
 						await auth.initialize();
+						await preferences.fetch();
 					}
 				}
 			} catch (_e) {
···
 		try {
 			await preferences.update({ allow_comments: enabled });
 			toast.success(enabled ? 'comments enabled on your tracks' : 'comments disabled');
+		} catch (_e) {
+			console.error('failed to save preference:', _e);
+			toast.error('failed to update preference');
+		}
+	}
+
+	async function saveTealScrobbling(enabled: boolean) {
+		try {
+			await preferences.update({ enable_teal_scrobbling: enabled });
+			await preferences.fetch(); // refetch to get updated teal_needs_reauth status
+			toast.success(enabled ? 'teal.fm scrobbling enabled' : 'teal.fm scrobbling disabled');
 		} catch (_e) {
 			console.error('failed to save preference:', _e);
 			toast.error('failed to update preference');
···
 
 		<section class="data-section">
 			<h2>your data</h2>
+
+			<div class="data-control">
+				<div class="control-info">
+					<h3>teal.fm scrobbling</h3>
+					<p class="control-description">
+						track your listens as <a href="https://pdsls.dev/at://{auth.user?.did}/fm.teal.alpha.feed.play" target="_blank" rel="noopener">fm.teal.alpha.feed.play</a> records
+					</p>
+				</div>
+				<label class="toggle-switch">
+					<input
+						type="checkbox"
+						aria-label="Enable teal.fm scrobbling"
+						checked={enableTealScrobbling}
+						onchange={(e) => saveTealScrobbling((e.target as HTMLInputElement).checked)}
+					/>
+					<span class="toggle-slider"></span>
+					<span class="toggle-label">{enableTealScrobbling ? 'enabled' : 'disabled'}</span>
+				</label>
+			</div>
+			{#if tealNeedsReauth}
+				<div class="reauth-notice">
+					<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+						<circle cx="12" cy="12" r="10" />
+						<path d="M12 16v-4M12 8h.01" />
+					</svg>
+					<span>please log out and back in to connect teal.fm</span>
+				</div>
+			{/if}
 
 			<div class="data-control">
 				<div class="control-info">
···
 
 	.control-description a {
 		color: var(--accent);
+	}
+
+	.reauth-notice {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+		padding: 0.6rem 0.75rem;
+		background: color-mix(in srgb, var(--accent) 12%, transparent);
+		border: 1px solid color-mix(in srgb, var(--accent) 35%, transparent);
+		border-radius: 6px;
+		color: var(--accent);
+		font-size: 0.8rem;
+		margin-top: -0.5rem;
+	}
+
+	.reauth-notice svg {
+		flex-shrink: 0;
 	}
 
 	.export-btn {