# Transcript (/docs/agent-ui/components/transcript)

Use a transcript when the agent works with a call, a meeting or a voice note, so readers can follow along as it plays, jump to a moment, and find what someone said. Each segment shows its speaker, its start time and its words, and the segment and word playing at `currentTime` are marked.

<Example caption="Press Play to follow the recording, or press a segment to jump to it. Type billing in the search field to show only the segments that mention it.">
<Basic />

```tsx
"use client";

import type { TranscriptSegment } from "@kind-ui/agent-ui";
import { useEffect, useState } from "react";
import { Transcript } from "@/components/ui/transcript";

// Each word gets a moment of its own, the way a speech-to-text service times them.
const timed = (id: string, speaker: string, start: number, text: string): TranscriptSegment => {
  let at = start;
  const words = text.split(" ").map((word) => {
    const timing = { text: word, start: at, end: at + 0.3 };
    at += 0.4;
    return timing;
  });
  return { id, speaker, start, end: at, text, words };
};

const segments = [
  timed("1", "Priya", 0, "Morning, everyone. Let's start with the release checklist for Thursday."),
  timed("2", "Marco", 5, "The migration ran cleanly on staging last night, so that box is ticked."),
  timed("3", "Priya", 11, "Great. Is the billing page still waiting on review?"),
  timed(
    "4",
    "Lena",
    15,
    "It is. I pushed the copy changes an hour ago, and the screenshots are in the thread.",
  ),
  timed("5", "Marco", 22, "I can take that review after lunch."),
];
const length = 25;

export default function TranscriptExample() {
  const [time, setTime] = useState(0);
  const [playing, setPlaying] = useState(false);

  useEffect(() => {
    if (!playing) return;
    const timer = setInterval(() => setTime((now) => (now + 0.1) % length), 100);
    return () => clearInterval(timer);
  }, [playing]);

  return (
    <div className="flex w-full max-w-xl flex-col gap-2">
      <button type="button" className="self-start text-sm underline" onClick={() => setPlaying(!playing)}>
        {playing ? "Pause" : "Play"}
      </button>
      <Transcript segments={segments} currentTime={time} onSeek={(start) => setTime(start)} />
    </div>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="React"
npx shadcn@latest add @kind-ui/transcript
```

```bash tab="Web Components"
npx shadcn@latest add @kind-ui/transcript-web
```

## Composition [#composition]

```text
Transcript
├── TranscriptSearch
│   └── TranscriptCount
└── TranscriptViewport
    └── TranscriptList
        └── TranscriptSegment
            ├── div[data-transcript-header]
            │   ├── TranscriptSpeaker
            │   └── TranscriptSeek
            │       └── TranscriptTime
            └── TranscriptText
                └── TranscriptWord
```

`TranscriptSearch` renders a UI SDK Input with a clear button, and `TranscriptCount` beside it says how many segments match. `TranscriptViewport` scrolls the segments, and `TranscriptList` renders a `TranscriptSegment` for each one in view. A segment's header holds `TranscriptSpeaker` and its start in `TranscriptTime`, inside a `TranscriptSeek` button while `onSeek` is set. `TranscriptText` holds a `TranscriptWord` for each word, or one for the whole text when the segment has no words.

## Usage [#usage]

### Segments [#segments]

Pass `segments` in time order. Each has an `id`, a `speaker`, a `start` and `end` in seconds, and its `text`. Give it `words`, each with its `text`, `start` and `end`, to mark the word playing; without them, the transcript marks the whole segment. Only the segments in view are rendered, so a long recording costs the same as a short one. The view is 24rem tall, whatever the search leaves in it; set `--kind-transcript-height` to change it.

```tsx
<Transcript
  segments={[{ id: "1", speaker: "Priya", start: 0, end: 4.5, text: "Let's start with the release checklist." }]}
/>
```

A segment added later fades in once; the ones already there stay where they are.

### Playback [#playback]

Pass `currentTime` as the recording plays. The segment at that time gets `aria-current` and its word `data-current`, and the words still to come in it are dimmed; in a gap between segments, nothing is marked. While focus is outside the transcript, a new segment scrolls to the middle of the view. Once someone focuses a time or types a search, the view stays where they put it. Pass `follow={false}` to never scroll.

### Seeking [#seeking]

Pass `onSeek` to make each time a **Seek to 0:05** button. A press on the time or anywhere on its segment calls `onSeek` with the segment's `start` in seconds, unless the press selected some of its text. Set your player's position there and pass the new `currentTime`.

### Search [#search]

Type in the search field to show only the segments whose text or speaker matches, with what matched marked. The count, like "2 matches", is announced. Clearing the search shows every segment again, and the segment that held focus keeps it. Pass `defaultQuery` to start with a search, or control it with `query` and `onQueryChange`.

### Keyboard and Motion [#keyboard-and-motion]

The search field, the scrolling view and the times are a Tab stop each. Among the times, Up Arrow and Down Arrow move between segments and Home and End go to the first and last, bringing segments that aren't rendered into view; Enter or Space seeks. Times are written in `locale`, else the page's language. Following playback scrolls smoothly; under `prefers-reduced-motion`, or with `motion="reduced"`, it jumps and new segments fade in over 120 ms, and with `motion="none"` nothing moves.

## API Reference [#api-reference]

### TranscriptOptions

| Prop             | Type                                                                                          | Description                                                                                                               |
| ---------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `segments?`      | `TranscriptSegment[] \| undefined`                                                            | The speakers' turns, in time order. Default: `[]`                                                                         |
| `label?`         | `string \| undefined`                                                                         | Names the transcript. Default: `"Transcript"`                                                                             |
| `currentTime?`   | `number \| undefined`                                                                         | Where playback is, in seconds. The segment at that time and its word are marked as playing.                               |
| `onSeek?`        | `((time: number, details: ChangeDetails<TranscriptSeekReason>) => void) \| undefined`         | Called when someone seeks to a segment, with its start in seconds. Makes each segment's time a button.                    |
| `query?`         | `string \| undefined`                                                                         | The search. Passing it controls it: change it in `onQueryChange`.                                                         |
| `defaultQuery?`  | `string \| undefined`                                                                         | The search at first, when `query` isn't passed. Default: `""`                                                             |
| `onQueryChange?` | `((query: string, details: ChangeDetails<TranscriptQueryChangeReason>) => void) \| undefined` | Called when the search changes, with why.                                                                                 |
| `follow?`        | `boolean \| undefined`                                                                        | Whether the segment playing scrolls into view as playback moves, while focus isn't inside the transcript. Default: `true` |
| `locale?`        | `string \| undefined`                                                                         | The language times are written in. Defaults to the page's language.                                                       |
| `motion?`        | `"auto" \| "none" \| "reduced"`                                                               | How segments enter and the view follows playback. `"auto"` follows `prefers-reduced-motion`. Default: `"auto"`            |

### Agent [#agent]

An agent connected with `createAgent` finds the transcript by its `label` and reads `query`. It can `search` with any text, which filters the segments as typing does, and while `onSeek` is set it can `seek` to a segment by its id; the segments are listed by speaker and time, and an id that isn't there is refused.

### TranscriptAgentActions

| Prop     | Type                                                    | Description                                                                                                                 |
| -------- | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `search` | `(text: string) => boolean`                             | Searches the segments, as typing does. An empty `text` shows every segment. Returns whether it was accepted.                |
| `seek`   | `((id: string, event?: Event) => boolean) \| undefined` | Calls `onSeek` with the start of the segment whose id is `id`. Returns false for an unknown id. Only while `onSeek` is set. |

<Caption>
Runs in React and Web Components. On `<kind-transcript>`, set `segments` as a property; the other props are kebab-case attributes. Add `can-seek` for the times to seek: `onSeek` is the `seek` event, and `onQueryChange` is `querychange`.
</Caption>