feat: timed comments on tracks (#359)

* feat: add timed comments on tracks

- add TrackComment model with timestamp_ms for positioning
- add allow_comments toggle to UserPreferences (off by default)
- add ATProto fm.plyr.comment record support
- add GET/POST/DELETE endpoints for comments API
- add frontend UI for viewing comments on track page
- add toggle in portal settings for artists
- limit to 20 comments per track
- comments ordered by timestamp for playback sync

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

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

* fix: play button resume and clickable comment timestamps

- fix play button not resuming after pause (check if track is loaded, not playing state)
- make comment timestamps clickable to seek to that point in the song
- fix layout overlap with share button (add flex-direction: column to main)
- make comments section more compact with scroll overflow

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

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

* refactor: extract _make_pds_request utility for ATProto record operations

consolidates duplicated OAuth session handling and token refresh logic
from 5 separate functions into a single private utility:
- create_track_record
- update_record
- create_like_record
- delete_record_by_uri
- create_comment_record

also adds _parse_at_uri helper for AT URI parsing.

net reduction of ~147 lines.

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

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

* fix: address PR review feedback

- add db.rollback() before cleanup on comment creation failure
- add aria-label for accessibility on comment input and toggle
- fix seekToTimestamp race condition by waiting for loadedmetadata

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

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

* fix: address copilot review feedback

- fix Index syntax in track_comment.py (can't use .desc() in constructor)
- make migration idempotent for allow_comments column
- add console.error for failed comment loads

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

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

---------

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

backend/alembic/env.py

···
     Artist,
     CopyrightScan,
     Track,
+    TrackComment,
     TrackLike,
+    UserPreferences,
     UserSession,
 )
 from backend.models.database import Base

backend/alembic/versions/2025_11_25_233843_20d550e3d14b_add_track_comments_table_and_allow_.py

···
+"""add track_comments table and allow_comments preference
+
+Revision ID: 20d550e3d14b
+Revises: b8a3d4500bb6
+Create Date: 2025-11-25 23:38:43.896501
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from sqlalchemy.engine.reflection import Inspector
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "20d550e3d14b"
+down_revision: str | Sequence[str] | None = "b8a3d4500bb6"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """Upgrade schema."""
+    # check if track_comments table already exists (dev has it)
+    conn = op.get_bind()
+    inspector = Inspector.from_engine(conn)
+    existing_tables = inspector.get_table_names()
+
+    if "track_comments" not in existing_tables:
+        op.create_table(
+            "track_comments",
+            sa.Column("id", sa.Integer(), nullable=False),
+            sa.Column("track_id", sa.Integer(), nullable=False),
+            sa.Column("user_did", sa.String(), nullable=False),
+            sa.Column("text", sa.Text(), nullable=False),
+            sa.Column("timestamp_ms", sa.Integer(), nullable=False),
+            sa.Column("atproto_comment_uri", sa.String(), nullable=False),
+            sa.Column("created_at", sa.DateTime(timezone=True), nullable=False),
+            sa.ForeignKeyConstraint(["track_id"], ["tracks.id"], ondelete="CASCADE"),
+            sa.PrimaryKeyConstraint("id"),
+        )
+        op.create_index(
+            op.f("ix_track_comments_id"), "track_comments", ["id"], unique=False
+        )
+        op.create_index(
+            op.f("ix_track_comments_track_id"),
+            "track_comments",
+            ["track_id"],
+            unique=False,
+        )
+        op.create_index(
+            op.f("ix_track_comments_user_did"),
+            "track_comments",
+            ["user_did"],
+            unique=False,
+        )
+        op.create_index(
+            op.f("ix_track_comments_atproto_comment_uri"),
+            "track_comments",
+            ["atproto_comment_uri"],
+            unique=True,
+        )
+        op.create_index(
+            "ix_track_comments_track_timestamp",
+            "track_comments",
+            ["track_id", "timestamp_ms"],
+            unique=False,
+        )
+        op.create_index(
+            "ix_track_comments_user_created",
+            "track_comments",
+            ["user_did", "created_at"],
+            unique=False,
+        )
+
+    # add allow_comments to user_preferences (check if column exists first)
+    existing_columns = [
+        col["name"] for col in inspector.get_columns("user_preferences")
+    ]
+    if "allow_comments" not in existing_columns:
+        op.add_column(
+            "user_preferences",
+            sa.Column(
+                "allow_comments",
+                sa.Boolean(),
+                server_default=sa.text("false"),
+                nullable=False,
+            ),
+        )
+
+
+def downgrade() -> None:
+    """Downgrade schema."""
+    op.drop_column("user_preferences", "allow_comments")
+    op.drop_table("track_comments")

backend/src/backend/_internal/atproto/__init__.py

···
     normalize_avatar_url,
 )
 from backend._internal.atproto.records import (
+    create_comment_record,
     create_like_record,
     create_track_record,
     delete_record_by_uri,
 )
 
 __all__ = [
+    "create_comment_record",
     "create_like_record",
     "create_track_record",
     "delete_record_by_uri",

backend/src/backend/_internal/atproto/records.py

···
             raise ValueError(f"failed to refresh access token: {e}") from e
 
 
+async def _make_pds_request(
+    auth_session: AuthSession,
+    method: str,
+    endpoint: str,
+    payload: dict[str, Any],
+    success_codes: tuple[int, ...] = (200, 201),
+) -> dict[str, Any]:
+    """make an authenticated request to the PDS with automatic token refresh.
+
+    args:
+        auth_session: authenticated user session
+        method: HTTP method (POST, GET, etc.)
+        endpoint: XRPC endpoint (e.g., "com.atproto.repo.createRecord")
+        payload: request payload
+        success_codes: HTTP status codes considered successful
+
+    returns:
+        response JSON dict (empty dict for 204 responses)
+
+    raises:
+        ValueError: if session is invalid
+        Exception: if request fails after retry
+    """
+    oauth_data = auth_session.oauth_session
+    if not oauth_data or "access_token" not in oauth_data:
+        raise ValueError(
+            f"OAuth session data missing or invalid for {auth_session.did}"
+        )
+
+    oauth_session = _reconstruct_oauth_session(oauth_data)
+    url = f"{oauth_data['pds_url']}/xrpc/{endpoint}"
+
+    for attempt in range(2):
+        response = await oauth_client.make_authenticated_request(
+            session=oauth_session,
+            method=method,
+            url=url,
+            json=payload,
+        )
+
+        if response.status_code in success_codes:
+            if response.status_code == 204:
+                return {}
+            return response.json()
+
+        # token expired - refresh and retry
+        if response.status_code == 401 and attempt == 0:
+            try:
+                error_data = response.json()
+                if "exp" in error_data.get("message", ""):
+                    logger.info(
+                        f"access token expired for {auth_session.did}, attempting refresh"
+                    )
+                    oauth_session = await _refresh_session_tokens(
+                        auth_session, oauth_session
+                    )
+                    continue
+            except (json.JSONDecodeError, KeyError):
+                pass
+
+    raise Exception(f"PDS request failed: {response.status_code} {response.text}")
+
+
 def build_track_record(
     title: str,
     artist: str,
···
     duration: int | None = None,
     features: list[dict] | None = None,
     image_url: str | None = None,
-) -> tuple[str, str] | None:
+) -> tuple[str, str]:
     """Create a track record on the user's PDS using the configured collection.
 
     args:
···
         ValueError: if session is invalid
         Exception: if record creation fails
     """
-    # get OAuth session data from database
-    oauth_data = auth_session.oauth_session
-    if not oauth_data or "access_token" not in oauth_data:
-        raise ValueError(
-            f"OAuth session data missing or invalid for {auth_session.did}"
-        )
-
-    # reconstruct OAuthSession from database
-    oauth_session = _reconstruct_oauth_session(oauth_data)
-
-    # construct record
     record = build_track_record(
         title=title,
         artist=artist,
···
         image_url=image_url,
     )
 
-    # make authenticated request to create record
-    url = f"{oauth_data['pds_url']}/xrpc/com.atproto.repo.createRecord"
     payload = {
         "repo": auth_session.did,
         "collection": settings.atproto.track_collection,
         "record": record,
     }
 
-    # try creating the record, refresh token if expired
-    for attempt in range(2):  # max 2 attempts: initial + 1 retry after refresh
-        response = await oauth_client.make_authenticated_request(
-            session=oauth_session,
-            method="POST",
-            url=url,
-            json=payload,
-        )
+    result = await _make_pds_request(
+        auth_session, "POST", "com.atproto.repo.createRecord", payload
+    )
+    return result["uri"], result["cid"]
 
-        # success
-        if response.status_code in (200, 201):
-            result = response.json()
-            return result["uri"], result["cid"]
 
-        # token expired - refresh and retry
-        if response.status_code == 401 and attempt == 0:
-            try:
-                error_data = response.json()
-                if "exp" in error_data.get("message", ""):
-                    logger.info(
-                        f"access token expired for {auth_session.did}, attempting refresh"
-                    )
-                    oauth_session = await _refresh_session_tokens(
-                        auth_session, oauth_session
-                    )
-                    continue  # retry with refreshed token
-            except (json.JSONDecodeError, KeyError):
-                pass  # not a token expiration error
-
-        # other error or retry failed
-        raise Exception(
-            f"Failed to create ATProto record: {response.status_code} {response.text}"
-        )
+def _parse_at_uri(uri: str) -> tuple[str, str, str]:
+    """parse an AT URI into (repo, collection, rkey)."""
+    if not uri.startswith("at://"):
+        raise ValueError(f"Invalid AT URI format: {uri}")
+    parts = uri.replace("at://", "").split("/")
+    if len(parts) != 3:
+        raise ValueError(f"Invalid AT URI structure: {uri}")
+    return parts[0], parts[1], parts[2]
 
 
 async def update_record(
     auth_session: AuthSession,
     record_uri: str,
     record: dict[str, Any],
-) -> tuple[str, str] | None:
+) -> tuple[str, str]:
     """Update an existing record on the user's PDS.
 
     args:
···
         ValueError: if session is invalid or URI is malformed
         Exception: if record update fails
     """
-    # get OAuth session data from database
-    oauth_data = auth_session.oauth_session
-    if not oauth_data or "access_token" not in oauth_data:
-        raise ValueError(
-            f"OAuth session data missing or invalid for {auth_session.did}"
-        )
+    repo, collection, rkey = _parse_at_uri(record_uri)
 
-    # reconstruct OAuthSession from database
-    oauth_session = _reconstruct_oauth_session(oauth_data)
-
-    # parse the AT URI to get repo and collection
-    # format: at://did:plc:.../collection/rkey
-    if not record_uri.startswith("at://"):
-        raise ValueError(f"Invalid AT URI format: {record_uri}")
-
-    parts = record_uri.replace("at://", "").split("/")
-    if len(parts) != 3:
-        raise ValueError(f"Invalid AT URI structure: {record_uri}")
-
-    repo, collection, rkey = parts
-
-    # make authenticated request to update record
-    url = f"{oauth_data['pds_url']}/xrpc/com.atproto.repo.putRecord"
     payload = {
         "repo": repo,
         "collection": collection,
···
         "record": record,
     }
 
-    # try updating the record, refresh token if expired
-    for attempt in range(2):  # max 2 attempts: initial + 1 retry after refresh
-        response = await oauth_client.make_authenticated_request(
-            session=oauth_session,
-            method="POST",
-            url=url,
-            json=payload,
-        )
-
-        # success
-        if response.status_code in (200, 201):
-            result = response.json()
-            return result["uri"], result["cid"]
-
-        # token expired - refresh and retry
-        if response.status_code == 401 and attempt == 0:
-            try:
-                error_data = response.json()
-                if "exp" in error_data.get("message", ""):
-                    logger.info(
-                        f"access token expired for {auth_session.did}, attempting refresh"
-                    )
-                    oauth_session = await _refresh_session_tokens(
-                        auth_session, oauth_session
-                    )
-                    continue  # retry with refreshed token
-            except (json.JSONDecodeError, KeyError):
-                pass  # not a token expiration error
-
-        # other error or retry failed
-        raise Exception(
-            f"Failed to update ATProto record: {response.status_code} {response.text}"
-        )
+    result = await _make_pds_request(
+        auth_session, "POST", "com.atproto.repo.putRecord", payload
+    )
+    return result["uri"], result["cid"]
 
 
 async def create_like_record(
···
         ValueError: if session is invalid
         Exception: if record creation fails
     """
-    # get OAuth session data from database
-    oauth_data = auth_session.oauth_session
-    if not oauth_data or "access_token" not in oauth_data:
-        raise ValueError(
-            f"OAuth session data missing or invalid for {auth_session.did}"
-        )
-
-    # reconstruct OAuthSession from database
-    oauth_session = _reconstruct_oauth_session(oauth_data)
-
-    # construct like record
     record = {
         "$type": settings.atproto.like_collection,
         "subject": {
···
         "createdAt": datetime.now(UTC).isoformat().replace("+00:00", "Z"),
     }
 
-    # make authenticated request to create record
-    url = f"{oauth_data['pds_url']}/xrpc/com.atproto.repo.createRecord"
     payload = {
         "repo": auth_session.did,
         "collection": settings.atproto.like_collection,
         "record": record,
     }
 
-    # try creating the record, refresh token if expired
-    for attempt in range(2):
-        response = await oauth_client.make_authenticated_request(
-            session=oauth_session,
-            method="POST",
-            url=url,
-            json=payload,
-        )
-
-        # success
-        if response.status_code in (200, 201):
-            result = response.json()
-            return result["uri"]
-
-        # token expired - refresh and retry
-        if response.status_code == 401 and attempt == 0:
-            try:
-                error_data = response.json()
-                if "exp" in error_data.get("message", ""):
-                    logger.info(
-                        f"access token expired for {auth_session.did}, attempting refresh"
-                    )
-                    oauth_session = await _refresh_session_tokens(
-                        auth_session, oauth_session
-                    )
-                    continue  # retry with refreshed token
-            except (json.JSONDecodeError, KeyError):
-                pass  # not a token expiration error
-
-    # all attempts failed
-    raise Exception(
-        f"Failed to create like record: {response.status_code} {response.text}"
+    result = await _make_pds_request(
+        auth_session, "POST", "com.atproto.repo.createRecord", payload
     )
+    return result["uri"]
 
 
 async def delete_record_by_uri(
···
         ValueError: if session is invalid or URI is malformed
         Exception: if record deletion fails
     """
-    # get OAuth session data from database
-    oauth_data = auth_session.oauth_session
-    if not oauth_data or "access_token" not in oauth_data:
-        raise ValueError(
-            f"OAuth session data missing or invalid for {auth_session.did}"
-        )
-
-    # reconstruct OAuthSession from database
-    oauth_session = _reconstruct_oauth_session(oauth_data)
-
-    # parse the AT URI to get repo and collection
-    # format: at://did:plc:.../collection/rkey
-    if not record_uri.startswith("at://"):
-        raise ValueError(f"Invalid AT URI format: {record_uri}")
+    repo, collection, rkey = _parse_at_uri(record_uri)
 
-    parts = record_uri.replace("at://", "").split("/")
-    if len(parts) != 3:
-        raise ValueError(f"Invalid AT URI structure: {record_uri}")
-
-    repo, collection, rkey = parts
-
-    # make authenticated request to delete record
-    url = f"{oauth_data['pds_url']}/xrpc/com.atproto.repo.deleteRecord"
     payload = {
         "repo": repo,
         "collection": collection,
         "rkey": rkey,
     }
 
-    # try deleting the record, refresh token if expired
-    for attempt in range(2):
-        response = await oauth_client.make_authenticated_request(
-            session=oauth_session,
-            method="POST",
-            url=url,
-            json=payload,
-        )
+    await _make_pds_request(
+        auth_session,
+        "POST",
+        "com.atproto.repo.deleteRecord",
+        payload,
+        success_codes=(200, 201, 204),
+    )
 
-        # success
-        if response.status_code in (200, 201, 204):
-            return
 
-        # token expired - refresh and retry
-        if response.status_code == 401 and attempt == 0:
-            try:
-                error_data = response.json()
-                if "exp" in error_data.get("message", ""):
-                    logger.info(
-                        f"access token expired for {auth_session.did}, attempting refresh"
-                    )
-                    oauth_session = await _refresh_session_tokens(
-                        auth_session, oauth_session
-                    )
-                    continue  # retry with refreshed token
-            except (json.JSONDecodeError, KeyError):
-                pass  # not a token expiration error
+async def create_comment_record(
+    auth_session: AuthSession,
+    subject_uri: str,
+    subject_cid: str,
+    text: str,
+    timestamp_ms: int,
+) -> str:
+    """create a timed comment record on the user's PDS.
 
-    # all attempts failed
-    raise Exception(f"Failed to delete record: {response.status_code} {response.text}")
+    args:
+        auth_session: authenticated user session
+        subject_uri: AT URI of the track being commented on
+        subject_cid: CID of the track being commented on
+        text: comment text content
+        timestamp_ms: playback position in milliseconds when comment was made
+
+    returns:
+        comment record URI
+
+    raises:
+        ValueError: if session is invalid
+        Exception: if record creation fails
+    """
+    record = {
+        "$type": settings.atproto.comment_collection,
+        "subject": {
+            "uri": subject_uri,
+            "cid": subject_cid,
+        },
+        "text": text,
+        "timestampMs": timestamp_ms,
+        "createdAt": datetime.now(UTC).isoformat().replace("+00:00", "Z"),
+    }
+
+    payload = {
+        "repo": auth_session.did,
+        "collection": settings.atproto.comment_collection,
+        "record": record,
+    }
+
+    result = await _make_pds_request(
+        auth_session, "POST", "com.atproto.repo.createRecord", payload
+    )
+    return result["uri"]

backend/src/backend/api/preferences.py

···
 
     accent_color: str
     auto_advance: bool
+    allow_comments: bool
 
 
 class PreferencesUpdate(BaseModel):
···
 
     accent_color: str | None = None
     auto_advance: bool | None = None
+    allow_comments: bool | None = None
 
 
 @router.get("/")
···
         await db.refresh(prefs)
 
     return PreferencesResponse(
-        accent_color=prefs.accent_color, auto_advance=prefs.auto_advance
+        accent_color=prefs.accent_color,
+        auto_advance=prefs.auto_advance,
+        allow_comments=prefs.allow_comments,
     )
 
 
···
             auto_advance=update.auto_advance
             if update.auto_advance is not None
             else True,
+            allow_comments=update.allow_comments
+            if update.allow_comments is not None
+            else False,
         )
         db.add(prefs)
     else:
···
             prefs.accent_color = update.accent_color
         if update.auto_advance is not None:
             prefs.auto_advance = update.auto_advance
+        if update.allow_comments is not None:
+            prefs.allow_comments = update.allow_comments
 
     await db.commit()
     await db.refresh(prefs)
 
     return PreferencesResponse(
-        accent_color=prefs.accent_color, auto_advance=prefs.auto_advance
+        accent_color=prefs.accent_color,
+        auto_advance=prefs.auto_advance,
+        allow_comments=prefs.allow_comments,
     )

backend/src/backend/api/tracks/__init__.py

···
 from .router import router
 
 # Import route modules to register handlers on the shared router.
+from . import comments as _comments
+from . import likes as _likes
 from . import listing as _listing
-from . import likes as _likes
 from . import mutations as _mutations
 from . import playback as _playback
 from . import uploads as _uploads

backend/src/backend/api/tracks/comments.py

···
+"""Track timed comments endpoints."""
+
+import logging
+from typing import Annotated
+
+from fastapi import Depends, HTTPException
+from pydantic import BaseModel, Field
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend._internal import Session as AuthSession
+from backend._internal import require_auth
+from backend._internal.atproto import create_comment_record, delete_record_by_uri
+from backend.models import Artist, Track, TrackComment, UserPreferences, get_db
+
+from .router import router
+
+logger = logging.getLogger(__name__)
+
+# max comments per track (configurable via settings later)
+MAX_COMMENTS_PER_TRACK = 20
+
+
+class CommentCreate(BaseModel):
+    """request body for creating a comment."""
+
+    text: str = Field(..., min_length=1, max_length=300)
+    timestamp_ms: int = Field(..., ge=0)
+
+
+class CommentResponse(BaseModel):
+    """response model for a single comment."""
+
+    id: int
+    user_did: str
+    user_handle: str
+    user_display_name: str | None
+    user_avatar_url: str | None
+    text: str
+    timestamp_ms: int
+    created_at: str
+
+
+class CommentsListResponse(BaseModel):
+    """response model for list of comments."""
+
+    comments: list[CommentResponse]
+    count: int
+    comments_enabled: bool
+
+
[e-mail]("/{track_id}/comments")
+async def get_track_comments(
+    track_id: int,
+    db: Annotated[AsyncSession, Depends(get_db)],
+) -> CommentsListResponse:
+    """get all comments for a track, ordered by timestamp.
+
+    public endpoint - no auth required.
+    """
+    # check track exists and get artist's allow_comments setting
+    track_result = await db.execute(select(Track).where(Track.id == track_id))
+    track = track_result.scalar_one_or_none()
+
+    if not track:
+        raise HTTPException(status_code=404, detail="track not found")
+
+    # check if artist allows comments
+    prefs_result = await db.execute(
+        select(UserPreferences).where(UserPreferences.did == track.artist_did)
+    )
+    prefs = prefs_result.scalar_one_or_none()
+    comments_enabled = prefs.allow_comments if prefs else False
+
+    if not comments_enabled:
+        return CommentsListResponse(comments=[], count=0, comments_enabled=False)
+
+    # fetch comments with user info
+    stmt = (
+        select(TrackComment, Artist)
+        .outerjoin(Artist, Artist.did == TrackComment.user_did)
+        .where(TrackComment.track_id == track_id)
+        .order_by(TrackComment.timestamp_ms)
+    )
+    result = await db.execute(stmt)
+    rows = result.all()
+
+    comments = [
+        CommentResponse(
+            id=comment.id,
+            user_did=comment.user_did,
+            user_handle=artist.handle if artist else comment.user_did,
+            user_display_name=artist.display_name if artist else None,
+            user_avatar_url=artist.avatar_url if artist else None,
+            text=comment.text,
+            timestamp_ms=comment.timestamp_ms,
+            created_at=comment.created_at.isoformat(),
+        )
+        for comment, artist in rows
+    ]
+
+    return CommentsListResponse(
+        comments=comments, count=len(comments), comments_enabled=True
+    )
+
+
[e-mail]("/{track_id}/comments")
+async def create_comment(
+    track_id: int,
+    body: CommentCreate,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    auth_session: AuthSession = Depends(require_auth),
+) -> CommentResponse:
+    """create a timed comment on a track.
+
+    requires auth. track owner must have allow_comments enabled.
+    """
+    # get track
+    track_result = await db.execute(select(Track).where(Track.id == track_id))
+    track = track_result.scalar_one_or_none()
+
+    if not track:
+        raise HTTPException(status_code=404, detail="track not found")
+
+    if not track.atproto_record_uri or not track.atproto_record_cid:
+        raise HTTPException(
+            status_code=422,
+            detail="track missing ATProto record - cannot comment",
+        )
+
+    # check if artist allows comments
+    prefs_result = await db.execute(
+        select(UserPreferences).where(UserPreferences.did == track.artist_did)
+    )
+    prefs = prefs_result.scalar_one_or_none()
+
+    if not prefs or not prefs.allow_comments:
+        raise HTTPException(
+            status_code=403,
+            detail="comments are disabled for this artist's tracks",
+        )
+
+    # check comment limit
+    count_result = await db.execute(
+        select(func.count()).where(TrackComment.track_id == track_id)
+    )
+    comment_count = count_result.scalar() or 0
+
+    if comment_count >= MAX_COMMENTS_PER_TRACK:
+        raise HTTPException(
+            status_code=400,
+            detail=f"track has reached maximum of {MAX_COMMENTS_PER_TRACK} comments",
+        )
+
+    # create ATProto record
+    comment_uri = None
+    try:
+        comment_uri = await create_comment_record(
+            auth_session=auth_session,
+            subject_uri=track.atproto_record_uri,
+            subject_cid=track.atproto_record_cid,
+            text=body.text,
+            timestamp_ms=body.timestamp_ms,
+        )
+
+        # create database record
+        comment = TrackComment(
+            track_id=track_id,
+            user_did=auth_session.did,
+            text=body.text,
+            timestamp_ms=body.timestamp_ms,
+            atproto_comment_uri=comment_uri,
+        )
+        db.add(comment)
+        await db.commit()
+        await db.refresh(comment)
+
+    except Exception as e:
+        await db.rollback()
+        logger.error(
+            f"failed to create comment on track {track_id} by {auth_session.did}: {e}",
+            exc_info=True,
+        )
+        # cleanup ATProto record if created
+        if comment_uri:
+            try:
+                await delete_record_by_uri(auth_session, comment_uri)
+                logger.info(
+                    f"cleaned up orphaned ATProto comment record: {comment_uri}"
+                )
+            except Exception as cleanup_exc:
+                logger.error(
+                    f"failed to cleanup orphaned comment record: {cleanup_exc}"
+                )
+        raise HTTPException(status_code=500, detail="failed to create comment") from e
+
+    # get user info for response
+    artist_result = await db.execute(
+        select(Artist).where(Artist.did == auth_session.did)
+    )
+    artist = artist_result.scalar_one_or_none()
+
+    return CommentResponse(
+        id=comment.id,
+        user_did=comment.user_did,
+        user_handle=artist.handle if artist else auth_session.did,
+        user_display_name=artist.display_name if artist else None,
+        user_avatar_url=artist.avatar_url if artist else None,
+        text=comment.text,
+        timestamp_ms=comment.timestamp_ms,
+        created_at=comment.created_at.isoformat(),
+    )
+
+
[e-mail]("/comments/{comment_id}")
+async def delete_comment(
+    comment_id: int,
+    db: Annotated[AsyncSession, Depends(get_db)],
+    auth_session: AuthSession = Depends(require_auth),
+) -> dict:
+    """delete a comment. only the author can delete their own comments."""
+    comment_result = await db.execute(
+        select(TrackComment).where(TrackComment.id == comment_id)
+    )
+    comment = comment_result.scalar_one_or_none()
+
+    if not comment:
+        raise HTTPException(status_code=404, detail="comment not found")
+
+    if comment.user_did != auth_session.did:
+        raise HTTPException(status_code=403, detail="can only delete your own comments")
+
+    # delete ATProto record
+    try:
+        await delete_record_by_uri(auth_session, comment.atproto_comment_uri)
+    except Exception as e:
+        logger.error(f"failed to delete ATProto comment record: {e}")
+        # continue with DB deletion anyway
+
+    await db.delete(comment)
+    await db.commit()
+
+    return {"deleted": True}

backend/src/backend/config.py

···
 
     @computed_field
     @property
+    def comment_collection(self) -> str:
+        """Collection name for timed comment records."""
+
+        return f"{self.app_namespace}.comment"
+
+    @computed_field
+    @property
     def old_track_collection(self) -> str | None:
         """Collection name for old namespace, if migration is active."""
 
···
         if self.scope_override:
             return self.scope_override
 
-        # base scopes: our track collection + our like collection
+        # base scopes: our track, like, and comment collections
         scopes = [
             f"repo:{self.track_collection}",
             f"repo:{self.like_collection}",
+            f"repo:{self.comment_collection}",
         ]
 
         # if we have an old namespace, add old track collection too

backend/src/backend/models/__init__.py

···
 from backend.models.queue import QueueState
 from backend.models.session import UserSession
 from backend.models.track import Track
+from backend.models.track_comment import TrackComment
 from backend.models.track_like import TrackLike
 from backend.utilities.database import db_session, get_db, init_db
 
···
     "QueueState",
     "ScanResolution",
     "Track",
+    "TrackComment",
     "TrackLike",
     "UserPreferences",
     "UserSession",

backend/src/backend/models/preferences.py

···
         Boolean, nullable=False, default=True, server_default=text("true")
     )
 
+    # artist preferences
+    allow_comments: 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/models/track_comment.py

···
+"""track comment model for timed comments on tracks."""
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING
+
+from sqlalchemy import DateTime, ForeignKey, Index, Integer, String, Text
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from backend.models.database import Base
+
+if TYPE_CHECKING:
+    from backend.models.track import Track
+
+
+class TrackComment(Base):
+    """timed comment on a track.
+
+    indexes ATProto comment records (fm.plyr.comment) for efficient querying.
+    the source of truth is the ATProto record on the user's PDS.
+    """
+
+    __tablename__ = "track_comments"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, index=True)
+
+    # which track is being commented on
+    track_id: Mapped[int] = mapped_column(
+        Integer,
+        ForeignKey("tracks.id", ondelete="CASCADE"),
+        nullable=False,
+        index=True,
+    )
+    track: Mapped["Track"] = relationship("Track", lazy="raise")
+
+    # who commented
+    user_did: Mapped[str] = mapped_column(String, nullable=False, index=True)
+
+    # comment content
+    text: Mapped[str] = mapped_column(Text, nullable=False)
+
+    # playback position in milliseconds when comment was made
+    timestamp_ms: Mapped[int] = mapped_column(Integer, nullable=False)
+
+    # ATProto comment record URI (source of truth)
+    atproto_comment_uri: Mapped[str] = mapped_column(
+        String, nullable=False, unique=True, index=True
+    )
+
+    # when it was created (indexed from ATProto record)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        default=lambda: datetime.now(UTC),
+        nullable=False,
+    )
+
+    __table_args__ = (
+        # composite index for fetching comments ordered by timestamp
+        Index("ix_track_comments_track_timestamp", "track_id", "timestamp_ms"),
+        # composite index for user's comments (order by recency handled in queries)
+        Index("ix_track_comments_user_created", "user_did", "created_at"),
+    )

backend/tests/api/test_track_comments.py

···
+"""tests for track comment api endpoints."""
+
+from collections.abc import Generator
+from unittest.mock import patch
+
+import pytest
+from fastapi import FastAPI
+from httpx import ASGITransport, AsyncClient
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from backend._internal import Session, require_auth
+from backend.main import app
+from backend.models import Artist, Track, TrackComment, UserPreferences
+
+
+class MockSession(Session):
+    """mock session for auth bypass in tests."""
+
+    def __init__(self, did: str = "did:test:commenter123"):
+        self.did = did
+        self.handle = "commenter.bsky.social"
+        self.session_id = "test_session_id"
+        self.access_token = "test_token"
+        self.refresh_token = "test_refresh"
+        self.oauth_session = {
+            "did": did,
+            "handle": "commenter.bsky.social",
+            "pds_url": "https://test.pds",
+            "authserver_iss": "https://auth.test",
+            "scope": "atproto transition:generic",
+            "access_token": "test_token",
+            "refresh_token": "test_refresh",
+            "dpop_private_key_pem": "fake_key",
+            "dpop_authserver_nonce": "",
+            "dpop_pds_nonce": "",
+        }
+
+
[e-mail]
+async def test_artist(db_session: AsyncSession) -> Artist:
+    """create a test artist."""
+    artist = Artist(
+        did="did:plc:artist123",
+        handle="artist.bsky.social",
+        display_name="Test Artist",
+    )
+    db_session.add(artist)
+    await db_session.commit()
+    return artist
+
+
[e-mail]
+async def test_track(db_session: AsyncSession, test_artist: Artist) -> Track:
+    """create a test track."""
+    track = Track(
+        title="Test Track",
+        artist_did=test_artist.did,
+        file_id="test123",
+        file_type="mp3",
+        extra={"duration": 180},
+        atproto_record_uri="at://did:plc:artist123/fm.plyr.track/test123",
+        atproto_record_cid="bafytest123",
+    )
+    db_session.add(track)
+    await db_session.commit()
+    await db_session.refresh(track)
+    return track
+
+
[e-mail]
+async def artist_with_comments_enabled(
+    db_session: AsyncSession, test_artist: Artist
+) -> UserPreferences:
+    """create user preferences with comments enabled."""
+    prefs = UserPreferences(
+        did=test_artist.did,
+        allow_comments=True,
+    )
+    db_session.add(prefs)
+    await db_session.commit()
+    return prefs
+
+
[e-mail]
+async def commenter_artist(db_session: AsyncSession) -> Artist:
+    """create the artist record for the commenter."""
+    artist = Artist(
+        did="did:test:commenter123",
+        handle="commenter.bsky.social",
+        display_name="Test Commenter",
+    )
+    db_session.add(artist)
+    await db_session.commit()
+    return artist
+
+
[e-mail]
+def test_app(db_session: AsyncSession) -> Generator[FastAPI, None, None]:
+    """create test app with mocked auth."""
+
+    async def mock_require_auth() -> Session:
+        return MockSession()
+
+    app.dependency_overrides[require_auth] = mock_require_auth
+    yield app
+    app.dependency_overrides.clear()
+
+
+async def test_get_comments_returns_empty_when_disabled(
+    test_app: FastAPI, db_session: AsyncSession, test_track: Track
+):
+    """test that comments endpoint returns empty list when artist has comments disabled."""
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.get(f"/tracks/{test_track.id}/comments")
+
+    assert response.status_code == 200
+    data = response.json()
+    assert data["comments"] == []
+    assert data["comments_enabled"] is False
+
+
+async def test_get_comments_returns_list_when_enabled(
+    test_app: FastAPI,
+    db_session: AsyncSession,
+    test_track: Track,
+    artist_with_comments_enabled: UserPreferences,
+):
+    """test that comments endpoint returns comments when enabled."""
+    # add a test comment directly to DB
+    comment = TrackComment(
+        track_id=test_track.id,
+        user_did="did:test:commenter123",
+        text="great track!",
+        timestamp_ms=45000,
+        atproto_comment_uri="at://did:test:commenter123/fm.plyr.comment/abc",
+    )
+    db_session.add(comment)
+    await db_session.commit()
+
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.get(f"/tracks/{test_track.id}/comments")
+
+    assert response.status_code == 200
+    data = response.json()
+    assert data["comments_enabled"] is True
+    assert len(data["comments"]) == 1
+    assert data["comments"][0]["text"] == "great track!"
+    assert data["comments"][0]["timestamp_ms"] == 45000
+
+
+async def test_create_comment_fails_when_comments_disabled(
+    test_app: FastAPI, db_session: AsyncSession, test_track: Track
+):
+    """test that creating a comment fails when artist has comments disabled."""
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.post(
+            f"/tracks/{test_track.id}/comments",
+            json={"text": "hello", "timestamp_ms": 1000},
+        )
+
+    assert response.status_code == 403
+    assert "disabled" in response.json()["detail"].lower()
+
+
+async def test_create_comment_success(
+    test_app: FastAPI,
+    db_session: AsyncSession,
+    test_track: Track,
+    artist_with_comments_enabled: UserPreferences,
+    commenter_artist: Artist,
+):
+    """test successful comment creation."""
+    with patch("backend.api.tracks.comments.create_comment_record") as mock_create:
+        mock_create.return_value = "at://did:test:commenter123/fm.plyr.comment/xyz"
+
+        async with AsyncClient(
+            transport=ASGITransport(app=test_app), base_url="http://test"
+        ) as client:
+            response = await client.post(
+                f"/tracks/{test_track.id}/comments",
+                json={"text": "awesome drop at this moment!", "timestamp_ms": 30000},
+            )
+
+    assert response.status_code == 200
+    data = response.json()
+    assert data["text"] == "awesome drop at this moment!"
+    assert data["timestamp_ms"] == 30000
+    assert data["user_did"] == "did:test:commenter123"
+
+    # verify ATProto record was created
+    mock_create.assert_called_once()
+
+    # verify DB entry
+    result = await db_session.execute(
+        select(TrackComment).where(TrackComment.track_id == test_track.id)
+    )
+    comment = result.scalar_one()
+    assert comment.text == "awesome drop at this moment!"
+    assert comment.timestamp_ms == 30000
+
+
+async def test_create_comment_respects_limit(
+    test_app: FastAPI,
+    db_session: AsyncSession,
+    test_track: Track,
+    artist_with_comments_enabled: UserPreferences,
+):
+    """test that comment limit is enforced."""
+    # add 20 comments (the limit)
+    for i in range(20):
+        comment = TrackComment(
+            track_id=test_track.id,
+            user_did=f"did:test:user{i}",
+            text=f"comment {i}",
+            timestamp_ms=i * 1000,
+            atproto_comment_uri=f"at://did:test:user{i}/fm.plyr.comment/{i}",
+        )
+        db_session.add(comment)
+    await db_session.commit()
+
+    # try to add 21st comment
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.post(
+            f"/tracks/{test_track.id}/comments",
+            json={"text": "one more", "timestamp_ms": 21000},
+        )
+
+    assert response.status_code == 400
+    assert "maximum" in response.json()["detail"].lower()
+
+
+async def test_comments_ordered_by_timestamp(
+    test_app: FastAPI,
+    db_session: AsyncSession,
+    test_track: Track,
+    artist_with_comments_enabled: UserPreferences,
+):
+    """test that comments are returned ordered by timestamp."""
+    # add comments out of order
+    for timestamp in [30000, 10000, 50000, 20000]:
+        comment = TrackComment(
+            track_id=test_track.id,
+            user_did="did:test:user",
+            text=f"at {timestamp}",
+            timestamp_ms=timestamp,
+            atproto_comment_uri=f"at://did:test:user/fm.plyr.comment/{timestamp}",
+        )
+        db_session.add(comment)
+    await db_session.commit()
+
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.get(f"/tracks/{test_track.id}/comments")
+
+    assert response.status_code == 200
+    comments = response.json()["comments"]
+    timestamps = [c["timestamp_ms"] for c in comments]
+    assert timestamps == [10000, 20000, 30000, 50000]
+
+
+async def test_get_comments_track_not_found(test_app: FastAPI):
+    """test that 404 is returned for non-existent track."""
+    async with AsyncClient(
+        transport=ASGITransport(app=test_app), base_url="http://test"
+    ) as client:
+        response = await client.get("/tracks/99999/comments")
+
+    assert response.status_code == 404

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

···
 	let displayName = $state('');
 	let bio = $state('');
 	let avatarUrl = $state('');
+	let allowComments = $state(false);
 	let savingProfile = $state(false);
 	let profileSuccess = $state('');
 	let profileError = $state('');
···
 			await loadMyTracks();
 			await loadArtistProfile();
 			await loadMyAlbums();
+			await loadPreferences();
 		} catch (_e) {
 			console.error('error loading portal data:', _e);
 			error = 'failed to load portal data';
···
 			console.error('failed to load albums:', _e);
 		} finally {
 			loadingAlbums = false;
+		}
+	}
+
+	async function loadPreferences() {
+		try {
+			const response = await fetch(`${API_URL}/preferences`, {
+				credentials: 'include'
+			});
+			if (response.ok) {
+				const prefs = await response.json();
+				allowComments = prefs.allow_comments;
+			}
+		} catch (_e) {
+			console.error('failed to load preferences:', _e);
+		}
+	}
+
+	async function saveAllowComments(enabled: boolean) {
+		try {
+			const response = await fetch(`${API_URL}/preferences`, {
+				method: 'POST',
+				headers: { 'Content-Type': 'application/json' },
+				credentials: 'include',
+				body: JSON.stringify({ allow_comments: enabled })
+			});
+			if (response.ok) {
+				allowComments = enabled;
+				toast.success(enabled ? 'comments enabled on your tracks' : 'comments disabled');
+			} else {
+				toast.error('failed to update preference');
+			}
+		} catch (_e) {
+			console.error('failed to save preference:', _e);
+			toast.error('failed to update preference');
 		}
 	}
 
···
 			{/if}
 		</section>
 
-		{#if tracks.length > 0}
-			<section class="export-section">
-				<div class="export-header">
-					<h2>export your music</h2>
-					<p class="export-description">
-						download all {tracks.length} {tracks.length === 1 ? 'track' : 'tracks'} as a zip archive.
-						files are provided in their original format (mp3, wav, m4a) exactly as uploaded.
+		<section class="data-section">
+			<h2>your data</h2>
+
+			<div class="data-control">
+				<div class="control-info">
+					<h3>timed comments</h3>
+					<p class="control-description">
+						allow other users to leave comments on your tracks
 					</p>
 				</div>
-				<button
-					class="export-main-btn"
-					onclick={exportAllMedia}
-					disabled={exportingMedia}
-				>
-					{exportingMedia ? 'exporting...' : tracks.length === 1 ? 'export track' : `export all ${tracks.length} tracks`}
-				</button>
-			</section>
-		{/if}
+				<label class="toggle-switch">
+					<input
+						type="checkbox"
+						aria-label="Allow timed comments on your tracks"
+						checked={allowComments}
+						onchange={(e) => saveAllowComments((e.target as HTMLInputElement).checked)}
+					/>
+					<span class="toggle-slider"></span>
+					<span class="toggle-label">{allowComments ? 'enabled' : 'disabled'}</span>
+				</label>
+			</div>
+
+			{#if tracks.length > 0}
+				<div class="data-control">
+					<div class="control-info">
+						<h3>export tracks</h3>
+						<p class="control-description">
+							{tracks.length === 1 ? 'download your track as a zip archive' : `download all ${tracks.length} tracks as a zip archive`}
+						</p>
+					</div>
+					<button
+						class="export-btn"
+						onclick={exportAllMedia}
+						disabled={exportingMedia}
+					>
+						{exportingMedia ? 'exporting...' : 'export'}
+					</button>
+				</div>
+			{/if}
+		</section>
 	</main>
 {/if}
 
···
 		justify-content: flex-end;
 	}
 
-	.export-section {
+	/* your data section */
+	.data-section {
 		margin-top: 3rem;
-		padding: 2rem;
+	}
+
+	.data-section h2 {
+		font-size: var(--text-page-heading);
+		margin-bottom: 1.5rem;
+	}
+
+	.data-control {
+		padding: 1.5rem;
 		background: #1a1a1a;
 		border: 1px solid #2a2a2a;
 		border-radius: 8px;
+		display: flex;
+		justify-content: space-between;
+		align-items: center;
+		gap: 1rem;
+		margin-bottom: 1rem;
 	}
 
-	.export-header {
-		margin-bottom: 1.5rem;
+	.data-control:last-child {
+		margin-bottom: 0;
 	}
 
-	.export-header h2 {
-		font-size: var(--text-page-heading);
-		margin-bottom: 0.75rem;
+	.control-info h3 {
+		font-size: 1rem;
+		font-weight: 600;
+		margin: 0 0 0.25rem 0;
+		color: #e8e8e8;
 	}
 
-	.export-description {
-		color: #aaa;
-		font-size: 0.95rem;
-		line-height: 1.6;
+	.control-description {
+		font-size: 0.85rem;
+		color: #888;
 		margin: 0;
 	}
 
-	.export-main-btn {
-		width: 100%;
-		padding: 1rem;
+	.export-btn {
+		padding: 0.6rem 1.25rem;
 		background: #3a7dff;
 		color: white;
 		border: none;
 		border-radius: 6px;
-		font-size: 1rem;
+		font-size: 0.9rem;
 		font-weight: 600;
 		cursor: pointer;
 		transition: all 0.2s;
+		white-space: nowrap;
+		width: auto;
 	}
 
-	.export-main-btn:hover:not(:disabled) {
+	.export-btn:hover:not(:disabled) {
 		background: #2868e6;
 		transform: translateY(-1px);
 		box-shadow: 0 4px 12px rgba(58, 125, 255, 0.3);
 	}
 
-	.export-main-btn:disabled {
+	.export-btn:disabled {
 		opacity: 0.5;
 		cursor: not-allowed;
 		transform: none;
 	}
 
-	.export-main-btn:active:not(:disabled) {
-		transform: translateY(0);
+	.toggle-switch {
+		display: flex;
+		align-items: center;
+		gap: 0.75rem;
+		cursor: pointer;
+		flex-shrink: 0;
+	}
+
+	.toggle-switch input {
+		display: none;
+	}
+
+	.toggle-slider {
+		width: 44px;
+		height: 24px;
+		background: #333;
+		border-radius: 12px;
+		position: relative;
+		transition: background 0.2s;
+	}
+
+	.toggle-slider::after {
+		content: '';
+		position: absolute;
+		top: 2px;
+		left: 2px;
+		width: 20px;
+		height: 20px;
+		background: #888;
+		border-radius: 50%;
+		transition: all 0.2s;
+	}
+
+	.toggle-switch input:checked + .toggle-slider {
+		background: var(--accent, #3a7dff);
+	}
+
+	.toggle-switch input:checked + .toggle-slider::after {
+		left: 22px;
+		background: white;
+	}
+
+	.toggle-label {
+		font-size: 0.85rem;
+		color: #888;
+		min-width: 60px;
 	}
 </style>

frontend/src/routes/track/[id]/+page.svelte

···
 	import { player } from '$lib/player.svelte';
 	import { queue } from '$lib/queue.svelte';
 	import { auth } from '$lib/auth.svelte';
+	import { toast } from '$lib/toast.svelte';
 	import type { Track } from '$lib/types';
 
+	interface Comment {
+		id: number;
+		user_did: string;
+		user_handle: string;
+		user_display_name: string | null;
+		user_avatar_url: string | null;
+		text: string;
+		timestamp_ms: number;
+		created_at: string;
+	}
+
 	// receive server-loaded data
 	let { data }: { data: PageData } = $props();
 
 	let track = $state<Track>(data.track);
 
+	// comments state
+	let comments = $state<Comment[]>([]);
+	let commentsEnabled = $state(false);
+	let loadingComments = $state(true);
+	let newCommentText = $state('');
+	let submittingComment = $state(false);
+
 	// reactive check if this track is currently playing
 	let isCurrentlyPlaying = $derived(
 		player.currentTrack?.id === track.id && !player.paused
···
 	}
 
 	function handlePlay() {
-		if (isCurrentlyPlaying) {
+		if (player.currentTrack?.id === track.id) {
+			// this track is already loaded - just toggle play/pause
 			player.togglePlayPause();
 		} else {
+			// different track or no track - start this one
 			queue.playNow(track);
 		}
 	}
···
 		queue.addTracks([track]);
 	}
 
+	async function loadComments() {
+		loadingComments = true;
+		try {
+			const response = await fetch(`${API_URL}/tracks/${track.id}/comments`);
+			if (response.ok) {
+				const data = await response.json();
+				comments = data.comments;
+				commentsEnabled = data.comments_enabled;
+			} else {
+				console.error('failed to load comments: response not OK');
+			}
+		} catch (e) {
+			console.error('failed to load comments:', e);
+		} finally {
+			loadingComments = false;
+		}
+	}
+
+	async function submitComment() {
+		if (!newCommentText.trim() || submittingComment) return;
+
+		// get current playback position (default to 0 if not playing this track)
+		let timestampMs = 0;
+		if (player.currentTrack?.id === track.id) {
+			timestampMs = Math.floor((player.currentTime || 0) * 1000);
+		}
+
+		submittingComment = true;
+		try {
+			const response = await fetch(`${API_URL}/tracks/${track.id}/comments`, {
+				method: 'POST',
+				headers: { 'Content-Type': 'application/json' },
+				credentials: 'include',
+				body: JSON.stringify({
+					text: newCommentText.trim(),
+					timestamp_ms: timestampMs
+				})
+			});
+
+			if (response.ok) {
+				const comment = await response.json();
+				// insert comment in sorted position by timestamp
+				const insertIndex = comments.findIndex(c => c.timestamp_ms > comment.timestamp_ms);
+				if (insertIndex === -1) {
+					comments = [...comments, comment];
+				} else {
+					comments = [...comments.slice(0, insertIndex), comment, ...comments.slice(insertIndex)];
+				}
+				newCommentText = '';
+				toast.success('comment added');
+			} else {
+				const error = await response.json();
+				toast.error(error.detail || 'failed to add comment');
+			}
+		} catch (e) {
+			console.error('failed to submit comment:', e);
+			toast.error('failed to add comment');
+		} finally {
+			submittingComment = false;
+		}
+	}
+
+	function formatTimestamp(ms: number): string {
+		const totalSeconds = Math.floor(ms / 1000);
+		const minutes = Math.floor(totalSeconds / 60);
+		const seconds = totalSeconds % 60;
+		return `${minutes}:${seconds.toString().padStart(2, '0')}`;
+	}
+
+	function seekToTimestamp(ms: number) {
+		const doSeek = () => {
+			if (player.audioElement) {
+				player.audioElement.currentTime = ms / 1000;
+			}
+		};
+
+		// if this track is already loaded, seek immediately
+		if (player.currentTrack?.id === track.id) {
+			doSeek();
+			return;
+		}
+
+		// otherwise start playing and wait for audio to be ready
+		queue.playNow(track);
+		if (player.audioElement && player.audioElement.readyState >= 1) {
+			doSeek();
+		} else {
+			// wait for metadata to load before seeking
+			const onReady = () => {
+				doSeek();
+				player.audioElement?.removeEventListener('loadedmetadata', onReady);
+			};
+			player.audioElement?.addEventListener('loadedmetadata', onReady);
+		}
+	}
+
 onMount(async () => {
 	if (auth.isAuthenticated) {
 		await loadLikedState();
 	}
+	await loadComments();
 });
 
 let shareUrl = $state('');
···
 				</div>
 			</div>
 		</div>
+
+		<!-- comments section -->
+		{#if commentsEnabled}
+			<section class="comments-section">
+				<h2 class="comments-title">
+					comments
+					{#if comments.length > 0}
+						<span class="comment-count">({comments.length})</span>
+					{/if}
+				</h2>
+
+				{#if auth.isAuthenticated}
+					<form class="comment-form" onsubmit={(e) => { e.preventDefault(); submitComment(); }}>
+						<input
+							type="text"
+							class="comment-input"
+							aria-label="Add a timed comment"
+							placeholder={player.currentTrack?.id === track.id ? `comment at ${formatTimestamp((player.currentTime || 0) * 1000)}...` : 'add a comment...'}
+							bind:value={newCommentText}
+							maxlength={300}
+							disabled={submittingComment}
+						/>
+						<button
+							type="submit"
+							class="comment-submit"
+							disabled={!newCommentText.trim() || submittingComment}
+						>
+							{submittingComment ? '...' : 'post'}
+						</button>
+					</form>
+				{:else}
+					<p class="login-prompt">
+						<a href="/login">log in</a> to leave a comment
+					</p>
+				{/if}
+
+				{#if loadingComments}
+					<div class="comments-loading">loading comments...</div>
+				{:else if comments.length === 0}
+					<div class="no-comments">no comments yet</div>
+				{:else}
+					<div class="comments-list">
+						{#each comments as comment}
+							<div class="comment">
+								<button
+									class="comment-timestamp"
+									onclick={() => seekToTimestamp(comment.timestamp_ms)}
+									title="jump to {formatTimestamp(comment.timestamp_ms)}"
+								>
+									{formatTimestamp(comment.timestamp_ms)}
+								</button>
+								<div class="comment-content">
+									<div class="comment-header">
+										{#if comment.user_avatar_url}
+											<img src={comment.user_avatar_url} alt="" class="comment-avatar" />
+										{:else}
+											<div class="comment-avatar-placeholder"></div>
+										{/if}
+										<a href="/u/{comment.user_handle}" class="comment-author">
+											{comment.user_display_name || comment.user_handle}
+										</a>
+									</div>
+									<p class="comment-text">{comment.text}</p>
+								</div>
+							</div>
+						{/each}
+					</div>
+				{/if}
+			</section>
+		{/if}
 	</main>
 </div>
 
···
 	main {
 		flex: 1;
 		display: flex;
+		flex-direction: column;
 		align-items: center;
-		justify-content: center;
+		justify-content: flex-start;
 		padding: 2rem;
 		padding-bottom: 8rem;
 		width: 100%;
···
 		.btn-queue svg {
 			width: 18px;
 			height: 18px;
+		}
+	}
+
+	/* comments section */
+	.comments-section {
+		width: 100%;
+		max-width: 500px;
+		margin-top: 1.5rem;
+		padding-top: 1.5rem;
+		border-top: 1px solid #2a2a2a;
+	}
+
+	.comments-title {
+		font-size: 1rem;
+		font-weight: 600;
+		color: #e8e8e8;
+		margin: 0 0 0.75rem 0;
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+	}
+
+	.comment-count {
+		color: #888;
+		font-weight: 400;
+	}
+
+	.comment-form {
+		display: flex;
+		gap: 0.5rem;
+		margin-bottom: 0.75rem;
+	}
+
+	.comment-input {
+		flex: 1;
+		padding: 0.6rem 0.8rem;
+		background: #1a1a1a;
+		border: 1px solid #333;
+		border-radius: 6px;
+		color: #e8e8e8;
+		font-size: 0.9rem;
+		font-family: inherit;
+	}
+
+	.comment-input:focus {
+		outline: none;
+		border-color: var(--accent);
+	}
+
+	.comment-input::placeholder {
+		color: #666;
+	}
+
+	.comment-submit {
+		padding: 0.6rem 1rem;
+		background: var(--accent);
+		color: #000;
+		border: none;
+		border-radius: 6px;
+		font-size: 0.9rem;
+		font-weight: 600;
+		font-family: inherit;
+		cursor: pointer;
+		transition: opacity 0.2s;
+	}
+
+	.comment-submit:disabled {
+		opacity: 0.5;
+		cursor: not-allowed;
+	}
+
+	.comment-submit:hover:not(:disabled) {
+		opacity: 0.9;
+	}
+
+	.login-prompt {
+		color: #888;
+		font-size: 0.9rem;
+		margin-bottom: 1rem;
+	}
+
+	.login-prompt a {
+		color: var(--accent);
+		text-decoration: none;
+	}
+
+	.login-prompt a:hover {
+		text-decoration: underline;
+	}
+
+	.comments-loading,
+	.no-comments {
+		color: #666;
+		font-size: 0.9rem;
+		text-align: center;
+		padding: 1rem;
+	}
+
+	.comments-list {
+		display: flex;
+		flex-direction: column;
+		gap: 0.5rem;
+		max-height: 300px;
+		overflow-y: auto;
+	}
+
+	.comment {
+		display: flex;
+		gap: 0.6rem;
+		padding: 0.5rem 0.6rem;
+		background: #1a1a1a;
+		border-radius: 6px;
+	}
+
+	.comment-timestamp {
+		font-size: 0.8rem;
+		font-weight: 600;
+		color: var(--accent);
+		background: rgba(138, 179, 255, 0.1);
+		padding: 0.2rem 0.5rem;
+		border-radius: 4px;
+		white-space: nowrap;
+		height: fit-content;
+		border: none;
+		cursor: pointer;
+		transition: all 0.2s;
+		font-family: inherit;
+	}
+
+	.comment-timestamp:hover {
+		background: rgba(138, 179, 255, 0.25);
+		transform: scale(1.05);
+	}
+
+	.comment-content {
+		flex: 1;
+		min-width: 0;
+	}
+
+	.comment-header {
+		display: flex;
+		align-items: center;
+		gap: 0.5rem;
+		margin-bottom: 0.25rem;
+	}
+
+	.comment-avatar {
+		width: 20px;
+		height: 20px;
+		border-radius: 50%;
+		object-fit: cover;
+	}
+
+	.comment-avatar-placeholder {
+		width: 20px;
+		height: 20px;
+		border-radius: 50%;
+		background: #333;
+	}
+
+	.comment-author {
+		font-size: 0.85rem;
+		font-weight: 500;
+		color: #b0b0b0;
+		text-decoration: none;
+	}
+
+	.comment-author:hover {
+		color: var(--accent);
+	}
+
+	.comment-text {
+		font-size: 0.9rem;
+		color: #e8e8e8;
+		margin: 0;
+		line-height: 1.4;
+		word-break: break-word;
+	}
+
+	@media (max-width: 768px) {
+		.comments-section {
+			margin-top: 1rem;
+			padding-top: 1rem;
+		}
+
+		.comments-list {
+			max-height: 200px;
+		}
+
+		.comment {
+			padding: 0.5rem;
+		}
+
+		.comment-timestamp {
+			font-size: 0.75rem;
+			padding: 0.15rem 0.4rem;
 		}
 	}
 </style>