Audio Player

A compact audio player with playlist support, timeline scrubbing, volume controls, repeat and shuffle modes, and track artwork.

Installation

npx shadcn add @limeplay/audio-player

Minimal Usage

import {
  AudioPlayer,
  type AudioPlayerAsset,
} from "@/components/limeplay/audio-player/components/media-player"

const playlist: AudioPlayerAsset[] = [
  {
    duration: 372_000,
    id: "soundhelix-1",
    poster: "https://placehold.co/160x160/png",
    src: "https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3",
    title: "SoundHelix Song 1",
  },
]

export function Player() {
  return <AudioPlayer source={playlist} />
}

Use source for media loading. Use mediaProps only for native audio attributes.

<AudioPlayer
  source={playlist}
  mediaProps={{ autoPlay: true, loop: false }}
/>

Single Track Usage

Pass one asset object when you do not need a queue.

<AudioPlayer
  source={{
    artistName: "SoundHelix",
    id: "soundhelix-1",
    poster: "https://placehold.co/160x160/png",
    src: "https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3",
    title: "SoundHelix Song 1",
  }}
/>

Custom Loading

The audio block includes an opinionated default resolver for src and playbackUrls.primary. Use loading.resolveSource when your app needs signed URLs, token refresh, or a different URL shape.

<AudioPlayer
  source={{ id: "track-123", title: "Track" }}
  loading={{
    resolveSource: async ({ asset, signal }) => {
      const response = await fetch(`/api/tracks/${asset.id}/source`, { signal })
      const source = await response.json()

      return source.url
    },
  }}
/>

Features

Playlist queue with track artwork, title, genre, and duration.
Fixed timeline with elapsed, duration, hover time, and scrub support.
Previous, play/pause, next, volume, mute, repeat, and shuffle controls.
Playback URL resolution for direct src values or playbackUrls.primary endpoints.
Automatic skip/reload behavior for recoverable load and playback failures.
Shared source and loading contract used by all source-driven blocks.

Notes

AudioPlayer does not ship with bundled tracks. Pass a playlist from your app.
Use duration in milliseconds when you want stable duration labels before metadata loads.
Do not pass mediaProps.src; pass source instead.
For the full block loading model, see Usage.

API Reference

Prop

Type

Attribution

Inspired by Youtube Music.

License & Usage

Free to use and modify in personal and commercial projects.
Attribution to Limeplay is appreciated but not required.
Do not resell the registry item as a standalone component library.