Timed comments on the waveform

Each comment sits as a dot under the moment it was left at. When the music
gets there the dot pings and a bubble grows out of it on a spark, then drifts
up and fades; a mouse over a dot peeks at it. The server fetches the newest
60 comments from pl8list on demand and keeps them for 15 minutes. A setting
turns them off.

web/index.html

@@ -144,6 +144,7 @@
       <label><input type="radio" name="crossfade" value="8"> dj mix</label>
     </fieldset>
     <label class="switch"><input type="checkbox" name="bass"> <span>bass boost</span></label>
+    <label class="switch"><input type="checkbox" name="comments"> <span>comments on the waveform</span></label>
     <fieldset class="modes">
       <legend>sleep timer <span id="sleep-left"></span></legend>
       <label><input type="radio" name="sleep" value="off"> off</label>

web/src/api.ts

@@ -130,6 +130,20 @@ export const artist = (handle: string) => getJSON<ArtistInfo>("/local/artist?" +
 export const track = (handle: string, slug: string) =>
   getJSON<{ track: Track }>("/local/track?" + new URLSearchParams({ handle, slug }));
 
+/// A comment left at a moment of the track (`at`, seconds in).
+export interface Comment {
+  id: number;
+  at: number;
+  body: string;
+  handle: string;
+  name: string;
+  img: string | null;
+  verified: boolean;
+}
+
+export const comments = (trackId: number) =>
+  getJSON<{ comments: Comment[] }>("/local/comments?" + new URLSearchParams({ id: String(trackId) }));
+
 export const likes = () => getJSON<{ tracks: Track[] }>("/local/likes");
 
 export const me = () => getJSON<Me>("/local/me");

web/src/cards.ts

@@ -1,8 +1,9 @@
 // One card per track. Elements are built when a card first comes near the screen
 // and dropped again once it is far behind, so a long session stays light.
 
-import { type Track, artistImg, artistUrl, trackUrl } from "./api";
+import { type Track, artistImg, artistUrl, comments, trackUrl } from "./api";
 import { accentFor, accentForName, backdrop } from "./color";
+import { WaveComments } from "./comments";
 
 export interface CardActions {
   like(card: Card): void;
@@ -88,6 +89,27 @@ export class Card {
   private station: string | undefined;
   /// Drops in the waveform, 0..1 of the track.
   readonly drops: number[];
+  /// Its timed comments, once asked for.
+  private comments: WaveComments | null = null;
+  private commentsAsked = false;
+
+  /// Fetch the timed comments, once. Previews have none: their moments are those
+  /// of the full track.
+  loadComments(): void {
+    if (this.commentsAsked || this.track.preview || !this.track.comments) return;
+    this.commentsAsked = true;
+    comments(this.track.id).then(({ comments: list }) => {
+      if (!list.length) return;
+      this.comments = new WaveComments(list, () => this.actions.duration(this));
+      const wrap = this.canvas?.parentElement;
+      if (wrap) this.comments.mount(wrap);
+    }, () => { this.commentsAsked = false; });
+  }
+
+  /// Playback of this card is at `seconds`.
+  commentsAt(seconds: number): void {
+    this.comments?.tick(seconds);
+  }
 
   element(): HTMLElement {
     return this.el ?? this.build();
@@ -96,6 +118,7 @@ export class Card {
   /// Forget the element; it is built again if the card comes back.
   release(): void {
     this.el?.remove();
+    this.comments?.unmount();
     this.el = this.canvas = null;
     this.drawn = "";
   }
@@ -176,6 +199,7 @@ export class Card {
     this.el = el;
     this.canvas = $<HTMLCanvasElement>(".wave");
     this.bindWaveform();
+    this.comments?.mount(this.canvas.parentElement!);
     this.showLike();
     this.showFollow();
     requestAnimationFrame(() => this.drawWave(this.lastProgress, true));
@@ -321,7 +345,10 @@ export class Card {
       tip.textContent = fmtTime(f * this.actions.duration(this));
       tip.style.left = `${f * 100}%`;
     };
+    const peek = (e: PointerEvent | null) =>
+      this.comments?.peek(e && !this.dragging && e.pointerType === "mouse" ? fraction(e) : null, canvas.clientWidth);
     canvas.addEventListener("pointerdown", (e) => {
+      peek(null);
       if (!this.actions.canSeek(this)) return;
       e.preventDefault();
       canvas.setPointerCapture(e.pointerId);
@@ -331,6 +358,7 @@ export class Card {
       this.drawWave(fraction(e), true);
     });
     canvas.addEventListener("pointermove", (e) => {
+      peek(e);
       if (this.dragging) this.drawWave(fraction(e), true);
       if (this.dragging || e.pointerType === "mouse") {
         wrap.classList.add("hover");
@@ -346,6 +374,7 @@ export class Card {
     canvas.addEventListener("pointerup", finish);
     canvas.addEventListener("pointercancel", finish);
     canvas.addEventListener("pointerleave", () => {
+      peek(null);
       if (!this.dragging) wrap.classList.remove("hover");
     });
   }

web/src/comments.ts

@@ -0,0 +1,159 @@
+// Timed comments on the waveform: a dot under the moment each one was left at,
+// and a bubble that grows out of the dot when the music gets there, then drifts
+// up and fades. A mouse over the waveform peeks at the comment under it.
+
+import { type Comment, imgUrl } from "./api";
+import { accentForName } from "./color";
+
+const LIFE = 4600; // ms a bubble shows; the length of its CSS animation
+const GAP = 900; // ms at least between two bubbles; dots in between only ping
+const MAX_SHOWN = 2; // bubbles on screen at once, the older pushed up
+const STACK = 6; // px between stacked bubbles
+const PEEK_PX = 8; // how close the mouse has to be to a dot to peek
+const GAP_ABOVE = 8; // px between the waveform and a bubble (.wc-bubble's bottom)
+const DOTS_ROW = 0.28; // share of the waveform's height the dots' row takes (.wave-comments)
+const SEEK = 1.5; // s; a longer step between two ticks is a seek, which fires nothing
+
+export class WaveComments {
+  private wrap: HTMLElement | null = null;
+  private layer: HTMLElement | null = null;
+  private dots: HTMLElement[] = [];
+  private shown: HTMLElement[] = [];
+  private peeked: { el: HTMLElement; id: number } | null = null;
+  private last = -1;
+  private lastBubble = 0;
+
+  constructor(readonly list: Comment[], private duration: () => number) {}
+
+  /// Put the dots under the waveform in `wrap`; they sprout from left to right.
+  mount(wrap: HTMLElement): void {
+    this.unmount();
+    const d = this.duration();
+    if (!d || !this.list.length) return;
+    this.wrap = wrap;
+    const layer = document.createElement("div");
+    layer.className = "wave-comments";
+    layer.setAttribute("aria-hidden", "true");
+    this.dots = this.list.map((c) => {
+      const dot = document.createElement("i");
+      dot.className = "wc-dot";
+      const x = Math.min(1, c.at / d);
+      dot.style.left = `${x * 100}%`;
+      dot.style.setProperty("--x", x.toFixed(3));
+      if (c.at <= this.last) dot.classList.add("past");
+      layer.append(dot);
+      return dot;
+    });
+    wrap.append(layer);
+    this.layer = layer;
+  }
+
+  unmount(): void {
+    this.layer?.remove();
+    for (const b of this.shown) b.remove();
+    this.peeked?.el.remove();
+    this.layer = this.wrap = this.peeked = null;
+    this.dots = [];
+    this.shown = [];
+  }
+
+  /// Playback is at `t` seconds. Comments passed since the last tick fire, unless
+  /// the step was a seek; dots behind the playhead stay lit.
+  tick(t: number): void {
+    const from = this.last;
+    this.last = t;
+    const played = t > from && t - from < SEEK;
+    let fire: Comment | null = null;
+    for (let i = 0; i < this.list.length; i++) {
+      const c = this.list[i], dot = this.dots[i];
+      dot?.classList.toggle("past", c.at <= t);
+      if (played && c.at > from && c.at <= t) {
+        if (dot) ping(dot);
+        fire = c;
+      }
+    }
+    const now = performance.now();
+    if (fire && this.layer && now - this.lastBubble >= GAP) {
+      this.lastBubble = now;
+      this.bubble(fire);
+    }
+  }
+
+  /// The mouse is at `f` (0..1) of the waveform, `width` px wide; null when it left.
+  peek(f: number | null, width: number): void {
+    const d = this.duration();
+    let near: Comment | null = null;
+    if (f !== null && d && this.layer) {
+      let best = PEEK_PX;
+      for (const c of this.list) {
+        const px = Math.abs(c.at / d - f) * width;
+        if (px <= best) [best, near] = [px, c];
+      }
+    }
+    if (near?.id === this.peeked?.id) return;
+    this.peeked?.el.remove();
+    this.peeked = null;
+    if (near) this.peeked = { el: this.place(near, "peek"), id: near.id };
+  }
+
+  private bubble(c: Comment): void {
+    const el = this.place(c, "");
+    const h = el.offsetHeight + STACK;
+    // The ones already up make room, the oldest leaves early.
+    for (const b of this.shown) b.style.setProperty("--lift", `${(parseFloat(b.style.getPropertyValue("--lift")) || 0) + h}px`);
+    this.shown.push(el);
+    while (this.shown.length > MAX_SHOWN) leave(this.shown.shift()!);
+    setTimeout(() => {
+      el.remove();
+      this.shown = this.shown.filter((b) => b !== el);
+    }, LIFE);
+  }
+
+  /// A bubble for `c` over its dot, kept inside the waveform's width, its tail
+  /// pointing at the dot.
+  private place(c: Comment, kind: string): HTMLElement {
+    const wrap = this.wrap!;
+    const el = document.createElement("div");
+    el.className = `wc-bubble ${kind}`.trim();
+    const inner = document.createElement("div");
+    inner.className = "wc-in";
+    const avatar = document.createElement("span");
+    avatar.className = "wc-avatar";
+    const img = imgUrl(c.img);
+    if (img) avatar.style.backgroundImage = `url("${img}")`;
+    else {
+      avatar.textContent = (c.name || "?")[0].toUpperCase();
+      avatar.style.background = accentForName(c.name || "?");
+    }
+    const text = document.createElement("span");
+    text.className = "wc-text";
+    const name = document.createElement("b");
+    name.textContent = c.name + (c.verified ? " ✓" : "");
+    const body = document.createElement("span");
+    body.textContent = c.body;
+    text.append(name, body);
+    inner.append(avatar, text);
+    el.append(inner);
+    wrap.append(el);
+    const w = wrap.clientWidth;
+    const x = Math.min(1, c.at / (this.duration() || 1)) * w;
+    const left = Math.max(0, Math.min(w - el.offsetWidth, x - el.offsetWidth / 2));
+    el.style.left = `${left}px`;
+    el.style.setProperty("--tail", `${Math.round(x - left)}px`);
+    // From the bubble down to the middle of the dots' row (see .wave-comments).
+    el.style.setProperty("--reach", `${Math.round(GAP_ABOVE + wrap.clientHeight * (1 - DOTS_ROW / 2))}px`);
+    return el;
+  }
+}
+
+/// Restart the dot's ping.
+function ping(dot: HTMLElement): void {
+  dot.classList.remove("hit");
+  void dot.offsetWidth;
+  dot.classList.add("hit");
+}
+
+function leave(el: HTMLElement): void {
+  el.classList.add("out");
+  setTimeout(() => el.remove(), 300);
+}

web/src/main.ts

@@ -25,7 +25,11 @@ const FILTERS_KEY = "pl8inf.filters";
 const MODE_KEY = "pl8inf.mode";
 const HINT_KEY = "pl8inf.hintShown";
 const NUDGE_KEY = "pl8inf.signInNudged";
+const COMMENTS_KEY = "pl8inf.waveComments";
 const NUDGE_LIKES = 5; // a guest is asked to sign in after this many likes, or a first follow
+/// Timed comments on the waveform, on unless turned off.
+let waveComments = localStorage.getItem(COMMENTS_KEY) !== "0";
+document.body.classList.toggle("no-wave-comments", !waveComments);
 
 const $ = <T extends HTMLElement = HTMLElement>(id: string) => document.getElementById(id) as T;
 
@@ -199,6 +203,7 @@ function activate(idx: number): void {
   if (pager.index !== idx) pager.go(idx, { instant: true });
   card.element().classList.add("current");
   visual.attach(card);
+  if (waveComments) card.loadComments();
   if (started) play(card.track);
   else showStart(card);
   clearTimeout(preloadTimer);
@@ -361,6 +366,7 @@ player.on("timeupdate", () => {
   lastTime = t;
   const card = current();
   card?.setTime(t);
+  card?.commentsAt(t);
   updatePosition();
   if (card && !remembered && listened >= HISTORY_AFTER) {
     remembered = true;
@@ -842,6 +848,13 @@ function showSetting(name: string, value: string): void {
   for (const input of filtersForm.querySelectorAll<HTMLInputElement>(`input[name=${name}]`)) input.checked = input.value === value;
 }
 
+function setWaveComments(on: boolean): void {
+  waveComments = on;
+  localStorage.setItem(COMMENTS_KEY, on ? "1" : "0");
+  document.body.classList.toggle("no-wave-comments", !on);
+  if (on) current()?.loadComments();
+}
+
 function setVisuals(v: VisualsSetting): void {
   visual.visuals = v;
   showSetting("visuals", v);
@@ -854,6 +867,7 @@ filtersForm.addEventListener("change", (e) => {
   else if (input.name === "spikes") visual.spikes = input.value as SpikeSetting;
   else if (input.name === "crossfade") player.crossfade = Number(input.value);
   else if (input.name === "bass") player.bassBoost = input.checked;
+  else if (input.name === "comments") setWaveComments(input.checked);
   else if (input.name === "sleep") setSleep(input.value);
 });
 filtersForm.addEventListener("submit", (e) => { e.preventDefault(); applyFilters(); });
@@ -874,6 +888,7 @@ function showSettings(): void {
   const bass = filtersForm.elements.namedItem("bass") as HTMLInputElement;
   bass.checked = player.bassBoost;
   bass.closest("label")!.hidden = !player.canMix;
+  (filtersForm.elements.namedItem("comments") as HTMLInputElement).checked = waveComments;
   showSleep();
 }
 sheets.filters.onOpen = showSettings;

web/src/style.css

@@ -645,6 +645,133 @@ button.danger:not(.link) { background: var(--accent); border: none; color: #fff;
   transition: opacity 0.1s;
 }
 .wave-wrap.hover .wave-tip { opacity: 1; }
+
+/* Timed comments: dots in the reflection under the waveform, lit once played,
+   and bubbles that grow out of a dot when the music gets there. */
+.wave-comments { position: absolute; inset: auto 0 0; height: 28%; pointer-events: none; }
+.wc-dot {
+  position: absolute;
+  top: 50%;
+  width: 5px;
+  height: 5px;
+  margin: -2.5px 0 0 -2.5px;
+  border-radius: 50%;
+  background: #ffffffa0;
+  transition: background 0.3s, box-shadow 0.3s;
+  animation: wc-sprout 0.5s calc(var(--x) * 0.7s) cubic-bezier(.2, .9, .3, 1.5) both;
+}
+.wc-dot.past { background: var(--card-accent); box-shadow: 0 0 6px var(--card-accent); }
+.wc-dot.hit { animation: wc-ping 0.7s ease-out; }
+@keyframes wc-sprout { from { transform: scale(0); opacity: 0; } }
+@keyframes wc-ping {
+  0% { transform: scale(1); box-shadow: 0 0 0 0 color-mix(in oklab, var(--card-accent) 80%, transparent); }
+  25% { transform: scale(2.2); }
+  100% { transform: scale(1); box-shadow: 0 0 0 10px transparent; }
+}
+
+.wc-bubble {
+  position: absolute;
+  z-index: 3;
+  bottom: calc(100% + 8px);
+  width: max-content;
+  max-width: min(17rem, 100%);
+  pointer-events: none;
+  translate: 0 calc(-1 * var(--lift, 0px));
+  transition: translate 0.4s cubic-bezier(.2, .9, .3, 1.2), opacity 0.2s;
+}
+/* A spark running up from the dot to the bubble as it opens. */
+.wc-bubble::before {
+  content: "";
+  position: absolute;
+  top: 100%;
+  left: calc(var(--tail) - 1px);
+  width: 2px;
+  height: var(--reach, 3rem);
+  border-radius: 1px;
+  background: linear-gradient(to top, var(--card-accent), transparent);
+  filter: drop-shadow(0 0 4px var(--card-accent));
+  transform-origin: bottom;
+  animation: wc-spark 0.9s ease-out both;
+}
+.wc-in {
+  position: relative;
+  display: flex;
+  gap: 0.45rem;
+  align-items: flex-start;
+  padding: 0.35rem 0.7rem 0.4rem 0.35rem;
+  border-radius: 14px;
+  background: #000000a8;
+  backdrop-filter: blur(12px);
+  box-shadow:
+    inset 0 0 0 1px color-mix(in oklab, var(--card-accent) 45%, transparent),
+    0 6px 22px #0008,
+    0 0 18px color-mix(in oklab, var(--card-accent) 22%, transparent);
+  font-size: 0.78rem;
+  line-height: 1.25;
+  text-align: left;
+  transform-origin: var(--tail) 100%;
+  animation: wc-rise 4.6s cubic-bezier(.2, .8, .3, 1) both;
+}
+/* The tail, pointing down at the dot. */
+.wc-in::after {
+  content: "";
+  position: absolute;
+  top: 100%;
+  left: calc(var(--tail) - 6px);
+  width: 12px;
+  height: 6px;
+  background: #000000a8;
+  clip-path: polygon(0 0, 100% 0, 50% 100%);
+}
+.wc-avatar {
+  flex: none;
+  width: 1.6rem;
+  height: 1.6rem;
+  display: grid;
+  place-items: center;
+  border-radius: 50%;
+  background: center / cover #333;
+  color: #000;
+  font-size: 0.75rem;
+  font-weight: 700;
+}
+.wc-text { display: flex; flex-direction: column; min-width: 0; }
+.wc-text b {
+  overflow: hidden;
+  color: var(--card-accent);
+  font-size: 0.7rem;
+  font-weight: 600;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+.wc-text span {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: 3;
+  line-clamp: 3;
+  overflow: hidden;
+  overflow-wrap: anywhere;
+}
+@keyframes wc-rise {
+  0% { opacity: 0; transform: translateY(14px) scale(0.3); filter: blur(4px); }
+  12% { opacity: 1; transform: translateY(-3px) scale(1.06); filter: blur(0); }
+  20% { transform: translateY(0) scale(1); }
+  82% { opacity: 1; transform: translateY(-4px); }
+  100% { opacity: 0; transform: translateY(-18px) scale(0.96); filter: blur(3px); }
+}
+@keyframes wc-spark {
+  0% { transform: scaleY(0); opacity: 1; }
+  40% { transform: scaleY(1); opacity: 1; }
+  100% { transform: scaleY(1); opacity: 0; }
+}
+.wc-bubble.out { opacity: 0; }
+/* Peeking with the mouse: above the time tip, no spark, no fading out. */
+.wc-bubble.peek { bottom: calc(100% + 1.9rem); }
+.wc-bubble.peek::before { display: none; }
+.wc-bubble.peek .wc-in { animation: wc-peek 0.2s cubic-bezier(.2, .9, .3, 1.3) both; }
+@keyframes wc-peek { from { opacity: 0; transform: translateY(6px) scale(0.8); } }
+.wave-wrap:has(.wc-bubble.peek) .wc-bubble:not(.peek) { opacity: 0; }
+body.no-wave-comments :is(.wave-comments, .wc-bubble), body.zen :is(.wave-comments, .wc-bubble) { display: none; }
 .time { width: 100%; display: flex; justify-content: space-between; gap: 1rem; color: var(--muted); font-size: 0.75rem; font-variant-numeric: tabular-nums; }
 .counts { opacity: 0.8; }
 .to-drop {
@@ -1183,4 +1310,7 @@ body.zen .content { gap: 0.3rem; }
 
 @media (prefers-reduced-motion: reduce) {
   *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; }
+  /* Comment bubbles stay for their time instead of flashing past. */
+  .wc-in { animation: none; }
+  .wc-bubble::before { display: none; }
 }