From 00a1f404b64c6cf015741c012eead47624e2338e Mon Sep 17 00:00:00 2001
From: Dylan Audius <dylan@audius.co>
Date: Tue, 27 Oct 2026 12:04:19 -0700
Subject: [PATCH] feat(web): waveform with comment avatars on desktop track
 tiles

Large desktop track tiles get a bar waveform between the title and the
stats row, behind the track_tile_waveform flag (default on in dev, off
in prod). Clicking the waveform seeks the playing track or starts the
tile at that point. Comments with a track timestamp sit on the baseline
as avatars; hover shows the comment, click opens it on the track page.

No node serves audio peaks yet, so the shape is synthesized from the
track id. Comments are fetched once per tile, only for tiles with
comments that have scrolled near the viewport.

The timestamped-comments hook moves from mobile into common so both
the Now Playing scrubber and the web tile share it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 .../src/api/tan-query/comments/index.ts       |   1 +
 .../comments}/useTimestampedComments.ts       |   5 +-
 .../services/remote-config/feature-flags.ts   |  10 +-
 .../now-playing-drawer/CommentBubble.tsx      |   3 +-
 .../now-playing-drawer/NowPlayingDrawer.tsx   |   3 +-
 .../components/track/desktop/TrackTile.tsx    |  50 ++-
 .../track/desktop/TrackTileWaveform.tsx       | 324 ++++++++++++++++++
 7 files changed, 380 insertions(+), 16 deletions(-)
 rename packages/{mobile/src/components/now-playing-drawer => common/src/api/tan-query/comments}/useTimestampedComments.ts (90%)
 create mode 100644 packages/web/src/components/track/desktop/TrackTileWaveform.tsx

diff --git a/packages/common/src/api/tan-query/comments/index.ts b/packages/common/src/api/tan-query/comments/index.ts
index e0cca9a48c3..12278377c7a 100644
--- a/packages/common/src/api/tan-query/comments/index.ts
+++ b/packages/common/src/api/tan-query/comments/index.ts
@@ -2,6 +2,7 @@ export * from './types'
 export * from './utils'
 export * from './useUserComments'
 export * from './useTrackComments'
+export * from './useTimestampedComments'
 export * from './useComment'
 export * from './useComments'
 export * from './useTrackCommentCount'
diff --git a/packages/mobile/src/components/now-playing-drawer/useTimestampedComments.ts b/packages/common/src/api/tan-query/comments/useTimestampedComments.ts
similarity index 90%
rename from packages/mobile/src/components/now-playing-drawer/useTimestampedComments.ts
rename to packages/common/src/api/tan-query/comments/useTimestampedComments.ts
index ea6863c240b..ad1ee72adde 100644
--- a/packages/mobile/src/components/now-playing-drawer/useTimestampedComments.ts
+++ b/packages/common/src/api/tan-query/comments/useTimestampedComments.ts
@@ -1,7 +1,8 @@
 import { useMemo } from 'react'
 
-import { useTrackComments } from '@audius/common/api'
-import type { Comment, ID } from '@audius/common/models'
+import type { Comment, ID } from '~/models'
+
+import { useTrackComments } from './useTrackComments'
 
 const PAGE_SIZE = 50
 // GetTrackCommentsSortMethodEnum.Timestamp
diff --git a/packages/common/src/services/remote-config/feature-flags.ts b/packages/common/src/services/remote-config/feature-flags.ts
index fab3d5a4901..33bb76af67c 100644
--- a/packages/common/src/services/remote-config/feature-flags.ts
+++ b/packages/common/src/services/remote-config/feature-flags.ts
@@ -18,7 +18,8 @@ export enum FeatureFlags {
   QUEUE_NEW_FEATURE_BADGE = 'queue_new_feature_badge',
   WEEKLY_ROTATION = 'weekly_rotation',
   TRACK_ROWS = 'track_rows',
-  NOW_PLAYING_COMMENTS = 'now_playing_comments'
+  NOW_PLAYING_COMMENTS = 'now_playing_comments',
+  TRACK_TILE_WAVEFORM = 'track_tile_waveform'
 }
 
 type FlagDefaults = Record<FeatureFlags, boolean>
@@ -28,7 +29,8 @@ export const environmentFlagDefaults: Record<
   Partial<FlagDefaults>
 > = {
   development: {
-    [FeatureFlags.FAN_CLUB_TEXT_POST_POSTING]: true
+    [FeatureFlags.FAN_CLUB_TEXT_POST_POSTING]: true,
+    [FeatureFlags.TRACK_TILE_WAVEFORM]: true
   },
   production: {}
 }
@@ -59,5 +61,7 @@ export const flagDefaults: FlagDefaults = {
   [FeatureFlags.TRACK_ROWS]: false,
   // Timestamped comments as markers and bubbles on the Now Playing scrubber.
   // Default on; the remote flag is the kill switch.
-  [FeatureFlags.NOW_PLAYING_COMMENTS]: true
+  [FeatureFlags.NOW_PLAYING_COMMENTS]: true,
+  // Waveform with timestamped comment avatars on desktop web track tiles.
+  [FeatureFlags.TRACK_TILE_WAVEFORM]: false
 }
diff --git a/packages/mobile/src/components/now-playing-drawer/CommentBubble.tsx b/packages/mobile/src/components/now-playing-drawer/CommentBubble.tsx
index f9547c4aa14..765055fd0ec 100644
--- a/packages/mobile/src/components/now-playing-drawer/CommentBubble.tsx
+++ b/packages/mobile/src/components/now-playing-drawer/CommentBubble.tsx
@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useMemo, useState } from 'react'
 
 import { useUser } from '@audius/common/api'
+import type { TimestampedComment } from '@audius/common/api'
 import type { ID } from '@audius/common/models'
 import { playbackSelectors } from '@audius/common/store'
 import { Dimensions, Pressable, View } from 'react-native'
@@ -13,8 +14,6 @@ import { useCommentDrawer } from 'app/components/comments/CommentDrawerContext'
 import { ProfilePicture } from 'app/components/core'
 import { useNavigation } from 'app/hooks/useNavigation'
 
-import type { TimestampedComment } from './useTimestampedComments'
-
 const { getSeek, getSeekCounter } = playbackSelectors
 
 const messages = {
diff --git a/packages/mobile/src/components/now-playing-drawer/NowPlayingDrawer.tsx b/packages/mobile/src/components/now-playing-drawer/NowPlayingDrawer.tsx
index a217ed0b090..8681e30f751 100644
--- a/packages/mobile/src/components/now-playing-drawer/NowPlayingDrawer.tsx
+++ b/packages/mobile/src/components/now-playing-drawer/NowPlayingDrawer.tsx
@@ -8,7 +8,7 @@ import {
   useState
 } from 'react'
 
-import { useUser } from '@audius/common/api'
+import { useUser, useTimestampedComments } from '@audius/common/api'
 import { useCurrentTrack, useFeatureFlag } from '@audius/common/hooks'
 import { FeatureFlags } from '@audius/common/services'
 import { playbackActions, playbackSelectors } from '@audius/common/store'
@@ -60,7 +60,6 @@ import { TitleBar } from './TitleBar'
 import { TrackInfo } from './TrackInfo'
 import { PLAY_BAR_HEIGHT } from './constants'
 import { useCurrentTrackDuration } from './useCurrentTrackDuration'
-import { useTimestampedComments } from './useTimestampedComments'
 const { seekTo: seek, reset, next, previous } = playbackActions
 
 const { getPlaying, getTrackId, getCounter, getBuffering } = playbackSelectors
diff --git a/packages/web/src/components/track/desktop/TrackTile.tsx b/packages/web/src/components/track/desktop/TrackTile.tsx
index 04908f19b44..0091b81fd57 100644
--- a/packages/web/src/components/track/desktop/TrackTile.tsx
+++ b/packages/web/src/components/track/desktop/TrackTile.tsx
@@ -1,13 +1,14 @@
 import { useCallback, useEffect, MouseEvent } from 'react'
 
 import { useCurrentUserId, useTrack, useUser } from '@audius/common/api'
-import { useGatedContentAccess } from '@audius/common/hooks'
+import { useFeatureFlag, useGatedContentAccess } from '@audius/common/hooks'
 import {
   ShareSource,
   RepostSource,
   FavoriteSource,
   ID
 } from '@audius/common/models'
+import { FeatureFlags } from '@audius/common/services'
 import {
   tracksSocialActions,
   shareModalUIActions,
@@ -51,6 +52,7 @@ import { TrackTileSize } from '../types'
 
 import styles from './TrackTile.module.css'
 import { TrackTileDuration } from './TrackTileDuration'
+import { TrackTileWaveform } from './TrackTileWaveform'
 
 const { requestOpen: requestOpenShareModal } = shareModalUIActions
 const { repostTrack, undoRepostTrack, saveTrack, unsaveTrack } =
@@ -62,6 +64,8 @@ const {
   getPlaying
 } = playbackSelectors
 
+const WAVEFORM_ARTWORK_SIZE = 176
+
 // Props from ConnectedTrackTile
 export type TrackTileProps = {
   id: ID
@@ -139,7 +143,9 @@ export const TrackTile = ({
     permalink,
     _co_sign: coSign,
     has_current_user_reposted: isReposted,
-    has_current_user_saved: isFavorited
+    has_current_user_saved: isFavorited,
+    duration,
+    comment_count: commentCount
   } = trackWithFallback
 
   const isArtistPick = partialUser?.artist_pick_track_id === trackId
@@ -148,6 +154,21 @@ export const TrackTile = ({
     useGatedContentAccess(trackWithFallback)
   const loading = isLoading || isFetchingNFTAccess || isPending
 
+  const { isEnabled: isWaveformEnabled } = useFeatureFlag(
+    FeatureFlags.TRACK_TILE_WAVEFORM
+  )
+  const showWaveform =
+    isWaveformEnabled &&
+    size === TrackTileSize.LARGE &&
+    !loading &&
+    duration > 0
+  // With the waveform the right column is ~176px tall; the artwork matches it.
+  const artworkSize = showWaveform
+    ? WAVEFORM_ARTWORK_SIZE
+    : size === TrackTileSize.LARGE
+      ? 128
+      : 108
+
   const [, setLockedContentVisibility] = useModalState('LockedContent')
 
   useEffect(() => {
@@ -319,7 +340,12 @@ export const TrackTile = ({
         disableActions && { opacity: 0.5, pointerEvents: 'none' },
         {
           cursor: canClickTile ? 'pointer' : 'default',
-          height: size === TrackTileSize.LARGE ? 144 : 128,
+          // The waveform tile is taller; its height comes from the content.
+          height: showWaveform
+            ? undefined
+            : size === TrackTileSize.LARGE
+              ? 144
+              : 128,
           containerType: 'inline-size',
           '&:hover .artworkIcon': { opacity: 0.75 },
           '&:hover': { transform: 'scale(1.004)' },
@@ -343,10 +369,7 @@ export const TrackTile = ({
           </Flex>
         )}
         {/* Track tile image */}
-        <Box
-          h={size === TrackTileSize.LARGE ? 128 : 108}
-          w={size === TrackTileSize.LARGE ? 128 : 108}
-        >
+        <Box h={artworkSize} w={artworkSize}>
           <button
             type='button'
             aria-label={artworkActionLabel}
@@ -440,6 +463,19 @@ export const TrackTile = ({
               </Flex>
             </Flex>
           </Flex>
+          {showWaveform ? (
+            <TrackTileWaveform
+              trackId={trackId}
+              title={title}
+              permalink={permalink}
+              duration={duration}
+              commentCount={commentCount}
+              isActive={isActive}
+              isPlaying={isTrackPlaying}
+              canSeek={hasStreamAccess}
+              onPlay={onTogglePlay}
+            />
+          ) : null}
           <TrackTileStats
             trackId={trackId}
             size={size}
diff --git a/packages/web/src/components/track/desktop/TrackTileWaveform.tsx b/packages/web/src/components/track/desktop/TrackTileWaveform.tsx
new file mode 100644
index 00000000000..2930c9aeb84
--- /dev/null
+++ b/packages/web/src/components/track/desktop/TrackTileWaveform.tsx
@@ -0,0 +1,324 @@
+import { MouseEvent, useCallback, useEffect, useMemo, useState } from 'react'
+
+import {
+  useTimestampedComments,
+  useUser,
+  type TimestampedComment
+} from '@audius/common/api'
+import { ID } from '@audius/common/models'
+import {
+  CommonState,
+  playbackActions,
+  playbackSelectors
+} from '@audius/common/store'
+import { Box, Tooltip, useTheme } from '@audius/harmony'
+import { Id } from '@audius/sdk'
+import { useDispatch, useSelector } from 'react-redux'
+import { useMeasure } from 'react-use'
+
+import { Avatar } from 'components/avatar'
+import { useDeferredElement } from 'pages/search-explore-page/components/desktop/useDeferredElement'
+import { audioPlayer } from 'services/audio-player'
+import { push } from 'utils/navigation'
+
+const { seekTo } = playbackActions
+const { getSeek, getSeekCounter } = playbackSelectors
+
+const messages = {
+  seek: (title: string) => `Seek within ${title}`,
+  openComment: (name: string) => `Open comment by ${name}`
+}
+
+const HEIGHT = 56
+const BAR_WIDTH = 2
+const BAR_GAP = 1
+const MIN_BAR_HEIGHT = 2
+const AVATAR_SIZE = 24
+const MAX_AVATARS = 24
+const POLL_MS = 250
+// Matches the comments context: play first, seek once the engine has loaded.
+const SEEK_AFTER_PLAY_MS = 100
+
+const clamp = (value: number, min: number, max: number) =>
+  Math.min(max, Math.max(min, value))
+
+// Small deterministic PRNG so a track always draws the same shape.
+const mulberry32 = (seed: number) => () => {
+  seed = (seed + 0x6d2b79f5) | 0
+  let t = Math.imul(seed ^ (seed >>> 15), 1 | seed)
+  t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t
+  return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+}
+
+/**
+ * No node serves audio peaks yet, so the shape is synthesized from the track
+ * id: a slow section envelope with per-bar jitter, which reads as a song
+ * without pretending to be one. Swap this for real peaks when they exist.
+ */
+const makePeaks = (seed: number, count: number) => {
+  const rand = mulberry32(seed)
+  const peaks: number[] = []
+  let envelope = 0.3
+  for (let i = 0; i < count; i++) {
+    if (rand() < 0.03) envelope = 0.2 + rand() * 0.75
+    const jitter = 0.55 + rand() * 0.45
+    const noise = (rand() - 0.5) * 0.12
+    peaks.push(clamp(envelope * jitter + noise, 0.05, 1))
+  }
+  return peaks
+}
+
+const buildPath = (peaks: number[]) => {
+  let d = ''
+  for (let i = 0; i < peaks.length; i++) {
+    const h = Math.max(MIN_BAR_HEIGHT, Math.round(peaks[i] * HEIGHT))
+    const x = i * (BAR_WIDTH + BAR_GAP)
+    d += `M${x} ${HEIGHT - h}h${BAR_WIDTH}v${h}h-${BAR_WIDTH}z`
+  }
+  return d
+}
+
+/** Fraction of the track that has played, polled only while this tile is the active track. */
+const useTrackProgress = (
+  isActive: boolean,
+  isPlaying: boolean,
+  duration: number
+) => {
+  const [position, setPosition] = useState(0)
+  const seek = useSelector((state: CommonState) => getSeek(state))
+  const seekCounter = useSelector((state: CommonState) => getSeekCounter(state))
+
+  useEffect(() => {
+    if (!isActive) setPosition(0)
+  }, [isActive])
+
+  useEffect(() => {
+    if (isActive && seek !== null) setPosition(seek)
+  }, [isActive, seek, seekCounter])
+
+  useEffect(() => {
+    if (!isActive) return
+    const tick = () => {
+      const next = audioPlayer?.getPosition() ?? 0
+      setPosition((current) =>
+        Math.abs(current - next) < 0.05 ? current : next
+      )
+    }
+    tick()
+    if (!isPlaying) return
+    const interval = window.setInterval(tick, POLL_MS)
+    return () => window.clearInterval(interval)
+  }, [isActive, isPlaying])
+
+  return duration > 0 ? clamp(position / duration, 0, 1) : 0
+}
+
+type CommentAvatarProps = {
+  comment: TimestampedComment
+  x: number
+  permalink: string
+}
+
+const CommentAvatar = ({ comment, x, permalink }: CommentAvatarProps) => {
+  const dispatch = useDispatch()
+  const { data: name } = useUser(comment.userId, {
+    select: (user) => user.name
+  })
+
+  const handleClick = useCallback(
+    (e: MouseEvent) => {
+      e.stopPropagation()
+      // The desktop track page highlights and scrolls to this comment.
+      dispatch(push(`${permalink}?commentId=${Id.parse(comment.id)}`))
+    },
+    [dispatch, permalink, comment.id]
+  )
+
+  if (!name) return null
+
+  return (
+    <Tooltip
+      placement='top'
+      mouseEnterDelay={0.1}
+      shouldWrapContent
+      text={
+        <>
+          <strong>{name}</strong> {comment.message}
+        </>
+      }
+    >
+      <Box
+        role='button'
+        aria-label={messages.openComment(name)}
+        onClick={handleClick}
+        css={{
+          position: 'absolute',
+          bottom: 0,
+          left: x,
+          zIndex: 1,
+          cursor: 'pointer',
+          borderRadius: '50%',
+          transform: 'translateX(-50%)',
+          transition: 'transform 120ms ease-out',
+          '&:hover': { transform: 'translateX(-50%) scale(1.15)', zIndex: 2 }
+        }}
+      >
+        <Avatar userId={comment.userId} size='small' aria-hidden />
+      </Box>
+    </Tooltip>
+  )
+}
+
+type TrackTileWaveformProps = {
+  trackId: ID
+  title: string
+  permalink: string
+  duration: number
+  commentCount: number
+  isActive: boolean
+  isPlaying: boolean
+  /** Seeking is only meaningful on the full stream, not a gated preview. */
+  canSeek: boolean
+  /** Start this tile playing; the tile owns gating and queue semantics. */
+  onPlay: () => void
+}
+
+/**
+ * Bar waveform for a desktop track tile. Click seeks (or starts the track at
+ * that point), and comments with a track timestamp sit on the baseline as
+ * avatars that open the comment on the track page.
+ */
+export const TrackTileWaveform = (props: TrackTileWaveformProps) => {
+  const {
+    trackId,
+    title,
+    permalink,
+    duration,
+    commentCount,
+    isActive,
+    isPlaying,
+    canSeek,
+    onPlay
+  } = props
+  const dispatch = useDispatch()
+  const { color } = useTheme()
+  const [measureRef, { width }] = useMeasure<HTMLDivElement>()
+  const { ref: inViewRef, inView } = useDeferredElement()
+  const progress = useTrackProgress(isActive, isPlaying, duration)
+
+  // One comments request per tile, and only for tiles that have comments and
+  // have scrolled near the viewport.
+  const comments = useTimestampedComments(trackId, inView && commentCount > 0)
+
+  const barCount = Math.max(0, Math.floor(width / (BAR_WIDTH + BAR_GAP)))
+  const path = useMemo(
+    () => (barCount ? buildPath(makePeaks(trackId, barCount)) : ''),
+    [trackId, barCount]
+  )
+
+  const avatars = useMemo(() => {
+    if (!width || !duration) return []
+    const placed: { comment: TimestampedComment; x: number }[] = []
+    let lastX = -Infinity
+    for (const comment of comments) {
+      const x = clamp(
+        (comment.trackTimestampS / duration) * width,
+        AVATAR_SIZE / 2,
+        width - AVATAR_SIZE / 2
+      )
+      // Keep neighbours from stacking; the first comment at a spot wins.
+      if (x - lastX < AVATAR_SIZE + 2) continue
+      placed.push({ comment, x })
+      lastX = x
+      if (placed.length >= MAX_AVATARS) break
+    }
+    return placed
+  }, [comments, duration, width])
+
+  const setRefs = useCallback(
+    (node: HTMLDivElement | null) => {
+      if (node) measureRef(node)
+      inViewRef(node)
+    },
+    [measureRef, inViewRef]
+  )
+
+  const handleClick = useCallback(
+    (e: MouseEvent<HTMLDivElement>) => {
+      e.stopPropagation()
+      if (!canSeek) {
+        onPlay()
+        return
+      }
+      const rect = e.currentTarget.getBoundingClientRect()
+      const fraction = clamp((e.clientX - rect.left) / rect.width, 0, 1)
+      const seconds = fraction * duration
+      if (isActive) {
+        dispatch(seekTo({ seconds }))
+      } else {
+        onPlay()
+        window.setTimeout(
+          () => dispatch(seekTo({ seconds })),
+          SEEK_AFTER_PLAY_MS
+        )
+      }
+    },
+    [canSeek, duration, isActive, onPlay, dispatch]
+  )
+
+  return (
+    <Box
+      ref={setRefs}
+      role='slider'
+      aria-label={messages.seek(title)}
+      aria-valuemin={0}
+      aria-valuemax={duration}
+      aria-valuenow={Math.round(progress * duration)}
+      onClick={handleClick}
+      css={{
+        position: 'relative',
+        width: '100%',
+        height: HEIGHT,
+        cursor: 'pointer',
+        userSelect: 'none'
+      }}
+    >
+      {path ? (
+        <>
+          <svg
+            width={width}
+            height={HEIGHT}
+            css={{ position: 'absolute', inset: 0, display: 'block' }}
+            aria-hidden
+          >
+            <path d={path} fill={color.neutral.n150} />
+          </svg>
+          <Box
+            css={{
+              position: 'absolute',
+              top: 0,
+              left: 0,
+              bottom: 0,
+              width: `${progress * 100}%`,
+              overflow: 'hidden',
+              transition: isPlaying ? `width ${POLL_MS}ms linear` : undefined
+            }}
+            aria-hidden
+          >
+            <svg width={width} height={HEIGHT} css={{ display: 'block' }}>
+              <path d={path} fill={color.primary.p300} />
+            </svg>
+          </Box>
+        </>
+      ) : null}
+      {avatars.map(({ comment, x }) => (
+        <CommentAvatar
+          key={comment.id}
+          comment={comment}
+          x={x}
+          permalink={permalink}
+        />
+      ))}
+    </Box>
+  )
+}