synced transcript.md

Synced Transcript

A transcript that follows the spoken word, lets you click any word to jump there, and waits when you scroll away.

Source: https://kokonutui.com/docs/media/synced-transcript

Installation

npx shadcn@latest add @kokonutui/synced-transcript

Props

Prop Type Default Description
title? string "Frame Rate · Episode 48"
segments? TranscriptSegment[] built-in
duration? number Seconds. Defaults to the end of the last segment. Playback is simulated; drive it from your own audio with onTimeChange.
onTimeChange? (seconds: number) => void
className? string Extra classes for the root element.

TranscriptSegment

Field Type Description
speaker string
start number Seconds from the start.
end number
text string

Source

"use client";

/**
 * @author: @dorianbaffier
 * @description: Synced Transcript
 * @version: 1.0.0
 * @date: 2026-10-16
 * @license: MIT
 * @website: https://kokonutui.com
 * @github: https://github.com/kokonut-labs/kokonutui
 */

import { ArrowDown, ArrowUp, Pause, Play } from "lucide-react";
import {
  type KeyboardEvent,
  type MouseEvent,
  memo,
  type PointerEvent,
  useCallback,
  useEffect,
  useLayoutEffect,
  useMemo,
  useRef,
  useState,
} from "react";
import { cn } from "@/lib/utils";

const SPEEDS = [1, 1.5, 2];
const WHITESPACE = /\s+/;

export interface TranscriptSegment {
  speaker: string;
  /** Seconds from the start. */
  start: number;
  end: number;
  text: string;
}

export interface SyncedTranscriptProps {
  title?: string;
  segments?: TranscriptSegment[];
  /** Seconds. Defaults to the end of the last segment. Playback is simulated; drive it from your own audio with `onTimeChange`. */
  duration?: number;
  onTimeChange?: (seconds: number) => void;
  className?: string;
}

interface Word {
  text: string;
  start: number;
  /** Index across the whole transcript. */
  index: number;
}

function timed(lines: [string, string][]): TranscriptSegment[] {
  const out: TranscriptSegment[] = [];
  let t = 0.6;
  for (const [speaker, text] of lines) {
    const words = text.split(WHITESPACE).length;
    const end = t + words / 2.7;
    out.push({ speaker, start: t, end, text });
    t = end + 0.7;
  }
  return out;
}

const DEFAULT_SEGMENTS = timed([
  [
    "Maya",
    "Welcome back. Today we're talking about the small details in interfaces, the ones nobody notices until they're missing.",
  ],
  [
    "Theo",
    "Right. Like a menu that opens in a hundred and fifty milliseconds instead of four hundred. You never think about it, but the slow one feels broken.",
  ],
  ["Maya", "So where do you start when something feels off?"],
  [
    "Theo",
    "I slow it down. I record the screen and step through it frame by frame. Most of the time the easing is wrong, or two things move that should move as one.",
  ],
  ["Maya", "And when it finally feels right?"],
  [
    "Theo",
    "Then I stop touching it. The best motion is the kind you only miss when it's gone.",
  ],
]);

const clamp = (v: number, lo: number, hi: number) =>
  Math.min(hi, Math.max(lo, v));

function formatTime(seconds: number) {
  const s = Math.max(0, Math.floor(seconds));
  return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
}

function splitWords(segments: TranscriptSegment[]) {
  let index = 0;
  return segments.map((segment) => {
    const parts = segment.text.split(WHITESPACE).filter(Boolean);
    const total = parts.reduce((sum, w) => sum + w.length + 1, 0);
    let t = segment.start;
    return parts.map((text) => {
      const word = { text, start: t, index };
      t += ((text.length + 1) / total) * (segment.end - segment.start);
      index += 1;
      return word;
    });
  });
}

function paragraphActive(segment: number, current: number, active: number) {
  if (segment < current) {
    return Number.MAX_SAFE_INTEGER;
  }
  return segment === current ? active : -1;
}

const Paragraph = memo(function Paragraph({
  words,
  active,
}: {
  words: Word[];
  /** The spoken word's global index. */
  active: number;
}) {
  return (
    <>
      {words.map((word) => (
        <span
          className={cn(
            "transition-colors duration-150 ease-out",
            word.index <= active
              ? "text-zinc-900 dark:text-zinc-100"
              : "text-zinc-400 dark:text-zinc-500"
          )}
          data-index={word.index}
          key={word.index}
        >
          {word.text}{