# Pill Karaoke

Karaoke-style captions in a rounded pill container — active word snaps to full contrast, others stay dimmed.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

## Installation

<TabsTrigger value="cli">Command</TabsTrigger>
<TabsTrigger value="manual">Manual</TabsTrigger>

```bash
npx shadcn@latest add @framecn/caption-pill-karaoke
```

<Step>Copy and paste the following code into your project.</Step>

<Step>Update the import paths to match your project setup.</Step>

## Usage

```tsx
import { CaptionPillKaraoke } from "@/components/framecn/caption-pill-karaoke";
import type { CaptionWord } from "@/components/framecn/caption-pill-karaoke";
```

```tsx
const words: CaptionWord[] = [
  { text: "Every", start: 0.0, end: 0.35 },
  { text: "great", start: 0.35, end: 0.65 },
  // ...
];

<CaptionPillKaraoke words={words} />;
```

## API Reference

### CaptionPillKaraoke

| Prop               | Type            | Default      |
| ------------------ | --------------- | ------------ |
| `words`            | `CaptionWord[]` | (demo words) |
| `wordsPerSegment`  | `number`        | `6`          |
| `activeColor`      | `string`        | `"#1a1a1a"`  |
| `dimColor`         | `string`        | `"#a6a6a6"`  |
| `pillColor`        | `string`        | `"#e7e5e7"`  |
| `fontSize`         | `number`        | `60`         |
| `fontWeight`       | `number`        | `700`        |
| `background`       | `string`        | `"#0a0a0a"`  |
| `speed`            | `number`        | `1`          |
| `fps`              | `number`        | `30`         |
| `durationInFrames` | `number`        | `180`        |
| `width`            | `number`        | `1280`       |
| `height`           | `number`        | `720`        |
| `className`        | `string`        | `-`          |

### CaptionWord

| Field   | Type     | Description           |
| ------- | -------- | --------------------- |
| `text`  | `string` | The word text         |
| `start` | `number` | Start time in seconds |
| `end`   | `number` | End time in seconds   |

## Notes

  `wordsPerSegment` determines how many words share a pill at once. A new pill
  slides in each time a new segment starts. Set it lower for shorter, punchier
  pills or higher for longer lines.

  The defaults use a light pill with dark text. For a dark pill on a light
  background, swap: `pillColor="#1a1a1a"`, `activeColor="#ffffff"`,
  `dimColor="#555555"`.