# Track player

> A small lacquered player: the disc turns, the waveform ripples and fills as it plays, and changing track drifts a veil of light across it.

Music, podcasts, a radio show, a playlist preview: most small players are a grey bar and three icons. Track player is an object with its own finish, a dark lacquer in each track’s colour with a turning disc, the title and three round controls, and a waveform you can drag. While it plays the disc turns, the waveform ripples gently along its length and fills white as the track goes; drag along it, or use the arrow keys, and the fill and the times follow and it carries on from there. Previous and next drift a soft veil of light across the player, and under it the track, its lacquer colour and its disc change over. It plays your audio when a track has a src; without one it keeps its own clock, for previews.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/track-player.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: `lucide-react`
- Hairline UI components it needs (the CLI installs them too): `text-morph`
- Docs and live preview: https://hairlineui.com/ui/track-player
- Registry item (source): https://hairlineui.com/r/track-player.json

## Usage

```tsx
import { TrackPlayer } from "@/components/track-player";

<TrackPlayer tracks={[{ id: "1", title: "Altamira Night", artist: "Lumen Vale", duration: 214, src: "/audio/altamira.mp3", tone: "ember" }]} />
```

## A playlist with peaks from your server

Work out each track’s peaks once when it’s uploaded and send them with the track; the player draws them as 48 bars.

```tsx
"use client";
import { useState } from "react";
import { TrackPlayer, type PlayerTrack } from "@/components/track-player";

export function Playlist({ tracks }: { tracks: PlayerTrack[] }) {
  const [index, setIndex] = useState(0);
  const [playing, setPlaying] = useState(false);
  return <TrackPlayer tracks={tracks} index={index} onIndexChange={setIndex} playing={playing} onPlayingChange={setPlaying} label="Playlist" />;
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `tracks` | `{ id, title, artist, duration, src?, peaks?, tone?, output?, art? }[]` | – | Each track: its length in seconds, audio, loudness peaks (any length), lacquer colour, where it plays and cover art. |
| `index / defaultIndex` | `number` | `0` | The track on show; controlled or not. |
| `onIndexChange` | `(index: number) => void` | – | Called under the veil when the track changes. |
| `playing / defaultPlaying` | `boolean` | `false` | Whether it plays; controlled or not. |
| `onPlayingChange` | `(playing: boolean) => void` | – | Called on play, pause and at the end. |
| `playingLabel / pausedLabel` | `string` | `"Now playing" / "Paused"` | Top left. |
| `label` | `string` | `"Player"` | Names the player for screen readers. |

## States

- **play**: The disc turns once every 6s; each bar ripples to 72% height and back over 900ms, 55ms apart, so a slow wave runs along it; the fill grows as the track plays.
- **pause**: The disc and the ripple stop where they are; the play and pause icons crossfade.
- **scrub**: The fill and times follow the pointer; letting go seeks there.
- **change**: A veil drifts across over 1.02s in the next track’s colours; at 36% the track, lacquer and disc change over.
- **end**: At the end it stops and goes back to the start.
- **reduced motion**: No ripple, spin or veil.

## What it handles

A plain audio bar gives no sense of the track, and swapping tracks just changes the text.

- **Your audio**: A src per track plays through an <audio> element; its own length replaces yours once known.
- **Scrub the waveform**: Drag along it or use the arrow keys; it carries on from there.
- **Each track its colour**: The lacquer and the disc follow the track; cover art works too.
- **A change you can see**: Previous and next drift a veil of light; the track changes under it.
- **Controlled or not**: Track and playing state, with callbacks for both.
- **Cheap while playing**: The fill is one clipped layer; the times re-render once a second.

## Replaces

audio player, music player card, now playing widget, waveform scrubber, podcast player

## Where it fits

- **Music apps**: A now-playing card in a sidebar, a profile or a release page.
- **Podcasts**: An episode player with the waveform to jump to a moment.
- **Audio tools**: Previewing mixes, stems or takes in a studio app.
- **Landing pages**: A playable sample of a product that makes sound.

## Notes

- Always dark: each track’s lacquer is the card’s own finish, so it reads the same on any page and needs no light version.
- While playing, one requestAnimationFrame loop reads the audio’s time and writes the fill to a clipped layer; React re-renders only when the whole second changes.
- The ripple is a CSS animation on each bar paused with the track, so nothing runs while it’s stopped.
- Without a src it keeps its own clock, so a preview plays with no audio file.
- The waveform is a slider (arrows ±5s, Page keys ±15s, Home and End); the track title and artist are announced when they change.
- Reduced motion drops the ripple, the spin and the veil.

License: MIT (https://hairlineui.com/license#components)
