# Get Started



<br>

<Steps>

This guide will walk you through adding **svelte-audio-ui** components using the [shadcn-svelte](https://shadcn-svelte.com) CLI and registry system.

## Prerequisites

Before you begin, make sure you have:

- A **Svelte 5 project** (SvelteKit recommended for most use cases)
- **Tailwind CSS v4** properly configured
- **shadcn-svelte** initialized in your project

If you haven’t initialized shadcn-svelte yet, run:

<PMExecute command="shadcn-svelte@latest init" />

## Adding Components

You can add components **svelte-audio-ui** using **shadcn-svelte** CLI or **manually by copying the files.**

<InstallTabs>

{#snippet cli()}

<PMAddComp name="https://svelte-audio-ui.vercel.app/r/player.json" />

This command will:

- add the `AudioPlayer` component
- automatically install required shadcn primitives
- include the audio store and core logic
- install the `AudioProvider` if it does not already exist

Everything is copied into your project—nothing is installed as a runtime dependency.

{/snippet}

{#snippet manual()}

> On Progress

{/snippet}

</InstallTabs>

## Step 3: Setup AudioProvider

The `AudioProvider` is required and will be added automatically when installing your first audio component.

It acts as the central engine that:

- initializes and manages the HTMLAudioElement
- syncs playback state with the store
- handles buffering, retries, and errors
- preloads upcoming tracks for smoother playback
- persists playback state (volume, progress, queue, etc)

Wrap your app with `AudioProvider` at the root level:

```svelte


<AudioProvider tracks={initialTracks}>{@render children()}</AudioProvider>
```

This ensures all audio components share a single, consistent playback state.

## Step 4: Use the component

```svelte


<AudioProvider tracks={initialTracks}>{@render children()}</AudioProvider>
```

## Styling

Components are styled with a design token system defined by CSS variables and implemented with Tailwind CSS. The variables follow the same approach as shadcn/ui and are fully customizable.

For detailed information about styling, color tokens, and customization options, see the [shadcn-svelte theming documentation.](https://www.shadcn-svelte.com/docs/theming)

## Working with LLMs

I try to keep the documentation structured in a way that’s easy for AI to read and work with.
To support that, I include:

- **[llms.txt](/llms.txt)** — a lightweight map of the documentation and component structure, so AI tools can quickly understand how things are organized without scanning everything.

- **[llms-full.txt](/llms-full.txt)** — a more complete dump of the docs and component sources, useful when you want deeper analysis or more accurate generation.

- **Copy Markdown button** — available on every page, so you can quickly grab the content and feed it into your own AI workflow without extra cleanup.

</Steps>


# Introduction



<br>

**svelte-audio-ui** is a collection of audio UI components built with [Svelte](https://svelte.dev), [Tailwind CSS](https://tailwindcss.com), and on top of [shadcn-svelte](https://shadcn-svelte.com).

It is inspired by [audio-ui](https://audio-ui.xyz)—an audio component system built on top of shadcn/ui for React—but rethought and rebuilt for the Svelte ecosystem.

**This is not a component library. It is how you build your own audio component system.**

## Why

I’ve used a lot of UI libraries over time, and they usually work well at the beginning.

But once you need deeper control—like adjusting behavior, matching a design system, or building something slightly outside the provided components—things start to break down.

You end up:

- wrapping components just to change small behavior details
- overriding styles in ways that feel fragile and hard to maintain
- mixing multiple libraries that don’t share the same API or design language

That friction adds up quickly.

svelte-audio-ui is my attempt to solve that by keeping everything simple:

> give you the actual code, not an abstraction layer

## Not a Component Library

svelte-audio-ui follows the same philosophy as audio-ui and shadcn:

You don’t install it as a dependency.  
You copy the component into your project and own it.

This approach gives you:

- **No Lock-in:** Your components live inside your codebase, so you are never tied to an external package or update cycle that might break your UI.
- **Full Control Over Behavior:** You can change logic, structure, or state handling without needing to wrap or override anything.
- **Long-Term Maintainability:** Instead of fighting abstractions, your components evolve naturally alongside your application.

## Built for Svelte 5

This project is built specifically for modern Svelte, not adapted from another framework.

It uses Svelte 5 patterns and runes to keep components:

- **Explicit and Predictable:** State and reactivity are easy to follow without hidden magic or complex abstractions.
- **Lightweight by Default:** No unnecessary layers, just straightforward component logic that feels close to plain JavaScript.
- **Easy to Extend:** Adding new features or modifying behavior does not require learning a custom API.

The goal is simple: everything should feel like native Svelte code.

## Inspired by shadcn-svelte

The workflow is heavily influenced by [shadcn-svelte](https://shadcn-svelte.com):

- components are copied, not installed
- everything lives in your project
- nothing is hidden behind a package boundary

svelte-audio-ui just narrows the focus into one domain:

**building audio interfaces that are flexible and composable.**

## Composition

Instead of shipping one large “Audio Player” component, the system is built from smaller primitives that can be combined as needed.

Typical building blocks include:

- **Player Controls:** Play, pause, skip, and other interaction elements designed to be reused across different layouts.
- **Timeline / Progress:** A flexible progress system that can be adapted into simple sliders or more advanced scrubbing interactions.
- **Volume Controls:** Independent and composable volume handling that can be reused in different contexts.
- **Optional Layers (Waveform, Metadata):** Additional UI layers that can be plugged in when needed without affecting the core system.

This makes the system flexible enough for both simple players and more complex audio interfaces.

## Beautiful Defaults

Styling is handled with [Tailwind CSS](https://tailwindcss.com), with a focus on clean and consistent defaults.

- **Minimal but Practical:** Components look good out of the box without trying to impose a heavy visual identity.
- **Consistent Across Components:** Spacing, sizing, and interaction patterns are aligned so everything feels like part of the same system.
- **Easy to Customize:** Because styles are local and not abstracted, you can adjust them directly without fighting specificity or overrides.

## AI-Ready

Because everything is just code inside your project, AI tools can work with it more effectively.

- **Readable Structure:** Components follow consistent patterns, making them easier for AI to understand.
- **Extensible System:** AI can help generate new components that match your existing structure and conventions.
- **Faster Iteration:** Instead of starting from scratch, you can evolve your system with AI assistance over time.

## Particles

On top of primitives, there are also [particles](/particles)—pre-built compositions of multiple components.

## Open Source

svelte-audio-ui is open source and built in the open.
I’m working on this as an indie developer, so the project will continue to evolve as I use it in real projects.
If it’s useful for you, feel free to use it, adapt it, or contribute back.


# Audio Playback Speed



<br>A compact dropdown button for switching playback speed on the fly — from a slow `0.5x` all the way up to `2x`. Shows the current rate directly on the button, auto-disables itself when a live stream is detected, and remembers your choice across page reloads.

<ComponentPreview name="playback-speed-demo" class="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[100px]" description="Playback speed control" align="center">

<div></div>

</ComponentPreview>

## Installation

<InstallTabs>

{#snippet cli()}

<PMAddComp name="https://svelte-audio-ui.vercel.app/r/playback-speed.json" />

{/snippet}

{#snippet manual()}

{#if viewerData}
	<ComponentSource item={viewerData} data-llm-ignore />
{:else}
	<p class="text-muted-foreground mt-4 text-sm">Source code not available.</p>
{/if}

{/snippet}

</InstallTabs>

## Usage

```svelte

```

### Basic

Drop it anywhere — no extra wiring needed, it reads from and writes to `audioStore` directly:

```svelte
<AudioPlaybackSpeed />
```

### Icon-only mode

Pass `size="icon"` to hide the gauge icon and show only the speed label — handy when space is tight in a control bar:

```svelte
<AudioPlaybackSpeed size="icon" variant="ghost" />
```

### Custom speeds

Swap out the default speed options with your own list:

```svelte
<AudioPlaybackSpeed
  speeds={[
    { value: 0.75, label: "0.75x" },
    { value: 1, label: "Normal" },
    { value: 1.5, label: "1.5x" },
    { value: 2, label: "2x" },
  ]}
/>
```

## API Reference

### AudioPlaybackSpeed

#### Props

| Prop      | Type                                 | Default           | Description                                                                    |
| --------- | ------------------------------------ | ----------------- | ------------------------------------------------------------------------------ |
| `speeds`  | `{ value: number; label: string }[]` | `DEFAULT_SPEEDS`  | Speed options. Defaults: `0.5x`, `0.75x`, `1x`, `1.25x`, `1.5x`, `2x`.       |
| `size`    | `string`                             | `"sm"`            | Button size. Use `"icon"` to hide the gauge icon and show only the speed label.|
| `variant` | `string`                             | `"outline"`       | Button visual variant.                                                         |
| `class`   | `string`                             | -                 | Additional CSS classes.                                                        |

Accepts any additional HTML button attributes via `...rest`.

#### Behavior

- **Live streams** — automatically disabled when `htmlAudio.isLive()` returns `true`. Tooltip changes to `"Not available for live streams"` so the user always knows why.
- **Current speed indicator** — the active rate is shown on the button and marked with a radio checkmark in the dropdown.
- **Persistence** — speed is saved to `localStorage` via `audioStore` and restored on the next page load.
- **Icon mode** — when `size="icon"`, the `Gauge` icon is hidden; only the speed label (e.g. `1x`) is shown.

> **Note:** `AudioPlaybackSpeed` requires `AudioProvider` (or the audio store) to be mounted higher in the tree. It reads `audioStore.playbackRate` and `audioStore.duration` reactively via Svelte 5 `$derived` runes — no hook wrappers needed.

## Examples

### Inside a player control bar

```svelte


<AudioPlayer.Root>
  <AudioPlayer.ControlBar>
    <AudioPlayer.ControlGroup>
      <AudioPlayer.SkipBack />
      <AudioPlayer.Play />
      <AudioPlayer.SkipForward />
    </AudioPlayer.ControlGroup>
    <AudioPlayer.ControlGroup>
      <AudioPlaybackSpeed />
      <AudioPlayer.Volume />
    </AudioPlayer.ControlGroup>
  </AudioPlayer.ControlBar>
</AudioPlayer.Root>
```

### Custom labels

```svelte
<AudioPlaybackSpeed
  speeds={[
    { value: 0.75, label: "Slow" },
    { value: 1, label: "Normal" },
    { value: 1.5, label: "Fast" },
    { value: 2, label: "Turbo" },
  ]}
/>
```

## Related

- [Audio Player](/docs/components/player) — the full player component system
- [Audio Provider](/docs/components/provider) — required wrapper that manages playback state


# Audio Player



<ComponentPreview name="player-demo" class="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[400px]" description="A fully featured audio player component" align="center">

<div></div>

</ComponentPreview>

## Installation

<InstallTabs>

{#snippet cli()}

<PMAddComp name="https://svelte-audio-ui.vercel.app/r/player.json" />

{/snippet}

{#snippet manual()}

{#if viewerData}
	<ComponentSource item={viewerData} data-llm-ignore />
{:else}
	<p class="text-muted-foreground mt-4 text-sm">Source code not available.</p>
{/if}

{/snippet}

</InstallTabs>

## Setup

Wrap your app with `AudioProvider` at the root level. It powers everything behind the scenes—state, playback, events, retries, and preloading—so all audio components stay in sync.

First, wrap your app with `AudioProvider` at the root level:

```svelte


<AudioProvider tracks={initialTracks}>{@render children()}</AudioProvider>
```

## Usage

Use the component you need :

```svelte


<AudioPlayer.Root>
  <AudioPlayer.ControlBar>
    <AudioPlayer.ControlGroup>
      <AudioPlayer.SkipBack />
      <AudioPlayer.Rewind />
      <AudioPlayer.Play />
      <AudioPlayer.FastForward />
      <AudioPlayer.SkipForward />
      <AudioPlayer.SeekBar />
      <AudioPlayer.TimeDisplay />
      <AudioPlayer.TimeDisplay remaining />
      <AudioPlayer.Volume />
    </AudioPlayer.ControlGroup>
  </AudioPlayer.ControlBar>
</AudioPlayer.Root>
```

### Stacked Layout

A player with stacked variant, showing time displays above and below the seek bar.

<ComponentPreview name="player-stacked-layout-demo" class="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[400px]" description="A fully featured audio player component" align="center">

<div></div>

</ComponentPreview>

### Player with Queue

A full-featured player with queue management, shuffle, and repeat controls. Uses `AudioPlayerControlGroup` for flexible layout management.

<ComponentPreview name="player-with-queue-demo" class="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[400px]" description="A fully featured audio player component" align="center">

<div></div>

</ComponentPreview>

For more queue management options, see the [Audio Queue documentation](/docs/components/queue).

## API Reference

### AudioPlayer.Root

A styled container component for audio controls. This is a presentational wrapper that provides consistent styling. All audio components are self-contained and read state from the global store.

#### Props

Inherits all props from `HTMLDivElement`.

#### Example

```svelte
<AudioPlayer.Root>{/* Your audio controls */}</AudioPlayer.Root>
```

### AudioPlayer.ControlBar

A container component that holds audio player controls. Use it to wrap your control components.

#### Props

| Prop      | Type                     | Default     | Description                         |
| --------- | ------------------------ | ----------- | ----------------------------------- |
| `variant` | `"compact" \| "stacked"` | `"compact"` | Layout variant for the control bar. |
| `class`   | `string`                 | -           | Additional CSS classes.             |

#### Example

```svelte
<AudioPlayer.ControlBar>
  <AudioPlayer.Play />
  <AudioPlayer.SeekBar />
  <AudioPlayer.TimeDisplay />
</AudioPlayer.ControlBar>
```

#### Stacked Layout

```svelte
<AudioPlayer.ControlBar variant="stacked">
  <AudioPlayer.ControlGroup>
    <AudioPlayer.TimeDisplay />
    <AudioPlayer.SeekBar />
    <AudioPlayer.TimeDisplay remaining />
  </AudioPlayer.ControlGroup>
</AudioPlayer.ControlBar>
```

### AudioPlayer.ControlGroup

A flexible wrapper component for grouping audio controls and managing flex layouts. Useful for creating custom layouts with flex-col, justify-between, etc.

#### Props

| Prop    | Type     | Default | Description             |
| ------- | -------- | ------- | ----------------------- |
| `class` | `string` | -       | Additional CSS classes. |

#### Example

```svelte
<AudioPlayer.ControlBar variant="stacked">
  <AudioPlayer.ControlGroup>
    <AudioPlayer.TimeDisplay />
    <AudioPlayer.SeekBar />
    <AudioPlayer.TimeDisplay remaining />
  </AudioPlayer.ControlGroup>
  <AudioPlayer.ControlGroup class="justify-between">
    <AudioPlayer.ControlGroup>
      <AudioPlayer.SkipBack />
      <AudioPlayer.Play />
      <AudioPlayer.SkipForward />
    </AudioPlayer.ControlGroup>
    <AudioPlayer.Volume />
  </AudioPlayer.ControlGroup>
</AudioPlayer.ControlBar>
```

### AudioPlayer.Play

A button that toggles play/pause state. Shows a loading spinner when buffering or loading, and automatically handles the Space bar keyboard shortcut.

#### Props

| Prop      | Type                      | Default   | Description               |
| --------- | ------------------------- | --------- | ------------------------- |
| `class`   | `string`                  | -         | Additional CSS classes.   |
| `size`    | `string`                  | `"icon"`  | Button size variant.      |
| `variant` | `string`                  | `"ghost"` | Button visual variant.    |
| `onclick` | `(e: MouseEvent) => void` | -         | Additional click handler. |

> **Keyboard Shortcuts**: Automatically handles the Space bar to toggle play/pause when focus is on `document.body`.

### AudioPlayer.SkipBack

Navigates to the previous track. If the current track has played for more than 3 seconds, it restarts the current track instead.

Accepts `class`, `size`, and `variant` props (same as `AudioPlayer.Play`).

### AudioPlayer.SkipForward

Navigates to the next track in the queue.

Accepts `class`, `size`, and `variant` props (same as `AudioPlayer.Play`).

### AudioPlayer.Rewind

Seeks backward by 10 seconds. Disabled on live streams.

Accepts `class`, `size`, and `variant` props (same as `AudioPlayer.Play`).

### AudioPlayer.FastForward

Seeks forward by 10 seconds. Disabled on live streams.

Accepts `class`, `size`, and `variant` props (same as `AudioPlayer.Play`).

### AudioPlayer.SeekBar

A slider that shows playback progress and allows seeking. Locked and shows 100% for live streams.

#### Props

| Prop    | Type     | Default | Description             |
| ------- | -------- | ------- | ----------------------- |
| `class` | `string` | -       | Additional CSS classes. |

### AudioPlayer.TimeDisplay

Displays the current playback time or remaining time.

#### Props

| Prop        | Type      | Default | Description                                     |
| ----------- | --------- | ------- | ----------------------------------------------- |
| `remaining` | `boolean` | `false` | Display remaining time instead of elapsed time. |
| `class`     | `string`  | -       | Additional CSS classes.                         |

On live streams: the non-remaining display shows elapsed time, and the remaining display shows a pulsing **LIVE** badge with a Radio icon.

### AudioPlayer.Volume

A dropdown button that opens a volume slider. Includes a mute toggle button inside the dropdown. Hidden on mobile (`hidden md:flex`).

#### Props

| Prop      | Type     | Default     | Description             |
| --------- | -------- | ----------- | ----------------------- |
| `class`   | `string` | -           | Additional CSS classes. |
| `size`    | `string` | `"icon"`    | Button size variant.    |
| `variant` | `string` | `"outline"` | Button visual variant.  |

## Notes

#### Important Information :

- **Component Architecture:** All audio components are self-contained and read state directly from the global `audioStore` — a Svelte 5 reactive class instance (using `$state` fields) defined in `audio-store.svelte.ts`. The audio player uses the HTML5 audio element under the hood via the `htmlAudio` singleton from `html-audio.ts`.

- **AudioProvider Role:** The `AudioProvider` component manages the audio element lifecycle by importing the `htmlAudio` singleton directly (no hook needed). It initialises the `HTMLAudioElement` inside `onMount`, registers all playback event listeners via an `AbortController` (automatically cleaned up on destroy), handles error retries (up to 3 retries with exponential backoff), preloads the next track into a secondary muted `<audio>` element, and uses seven `$effect` runes to reactively sync `audioStore` state changes (track changes, play/pause, seek, volume, mute, playback rate, and localStorage persistence) back to the audio element. It also restores the last playback position from `localStorage` on mount. `AudioProvider` is required for all audio components to function correctly.

- **Previous Button Behavior:** `AudioPlayer.SkipBack` restarts the current track if it has been playing for more than 3 seconds, otherwise it navigates to the previous track in the queue.

- **State Persistence:** `audioStore` automatically persists queue, current track, volume, playback rate, repeat mode, shuffle, insert mode, and playback position to `localStorage` under the key `audio:ui:store`, restored on page reload.

**Live Stream Limitations:**
Live streams disable seeking, rewind, fast-forward, and playback speed controls. The seek bar is locked at 100% progress, and the time display switches to a pulsing **LIVE** badge. Live streams are detected automatically via the HTML5 `audio.duration` value (`Infinity` or `NaN`).


# Audio Provider



<br>

`AudioProvider` is the engine behind every audio component. It initializes the HTML audio element, registers all event listeners, syncs playback state with the `audioStore`, handles errors and retries, preloads the next track, and persists state to `localStorage`.

**It is required.** All audio components depend on it.

## Installation

<InstallTabs>

{#snippet cli()}

<PMAddComp name="https://svelte-audio-ui.vercel.app/r/provider.json" />

{/snippet}

{#snippet manual()}

{#if viewerData}
	<ComponentSource item={viewerData} data-llm-ignore />
{:else}
	<p class="text-muted-foreground mt-4 text-sm">Source code not available.</p>
{/if}

{/snippet}

</InstallTabs>

## Usage

The recommended place to mount `AudioProvider` is in your layout file so all pages share the same playback state:

```svelte


<AudioProvider {tracks}>
  {@render children()}
</AudioProvider>
```

## API Reference

### Props

| Prop       | Type      | Default | Description                                          |
| ---------- | --------- | ------- | ---------------------------------------------------- |
| `tracks`   | `Track[]` | `[]`    | Initial list of tracks to load into the queue.       |
| `children` | `Snippet` | —       | Required. The content to render inside the provider. |

### Track Shape

Each track in the `tracks` array must follow this shape:

```ts
interface Track {
  id: string | number;
  title: string;
  artist?: string;
  url: string; // URL to the audio file or stream
  cover?: string; // Optional album art URL
  duration?: number; // Optional pre-known duration in seconds
}
```

## How It Works

`AudioProvider` coordinates three layers:

1. **`htmlAudio`** — a singleton that holds the actual `HTMLAudioElement`
2. **`audioStore`** — a Svelte 5 reactive class instance that holds all playback state
3. **`AudioProvider`** — the glue layer that wires DOM events → store updates and store changes → DOM mutations

```
tracks prop → audioStore.queue
audioStore state changes → htmlAudio (DOM)
htmlAudio DOM events → audioStore state
audioStore → localStorage
```

### Lifecycle

On mount, `AudioProvider`:

1. Calls `htmlAudio.init()` to create the underlying `HTMLAudioElement`
2. Creates a secondary muted `<audio>` element for pre-loading the next track
3. Attaches all event listeners via `AbortController` (automatically cleaned up on destroy)
4. Restores the last playback position, volume, and track from `localStorage`

### Reactive `$effect` Sync

Eight `$effect` runes keep the `HTMLAudioElement` in sync with `audioStore`:

| Effect        | Trigger                              | Action                                      |
| ------------- | ------------------------------------ | ------------------------------------------- |
| Track sync    | `tracks` prop changes                | Updates `audioStore.queue` if tracks differ |
| Track change  | `audioStore.currentTrack` changes    | Loads and plays new track                   |
| Seek          | `audioStore.currentTime` user update | Seeks `HTMLAudioElement`                    |
| Volume        | `audioStore.volume` changes          | Sets `audio.volume`                         |
| Mute          | `audioStore.isMuted` changes         | Sets `audio.muted`                          |
| Playback rate | `audioStore.playbackRate` changes    | Sets `audio.playbackRate`                   |
| Queue reset   | `audioStore.queue` becomes empty     | Clears preload audio `src`                  |
| Persistence   | Any tracked state changes            | Saves to `localStorage`                     |

### Error Handling

`AudioProvider` classifies `MediaError` codes and decides if an error is recoverable:

| Error code                        | Message                    | Recoverable |
| --------------------------------- | -------------------------- | ----------- |
| `MEDIA_ERR_ABORTED` (1)           | Playback cancelled         | Yes         |
| `MEDIA_ERR_NETWORK` (2)           | Network error              | Yes         |
| `MEDIA_ERR_DECODE` (3)            | Audio file decoding error  | No          |
| `MEDIA_ERR_SRC_NOT_SUPPORTED` (4) | File/network loading error | Yes         |

For recoverable errors, it retries up to **3 times** with exponential backoff (1s → 2s → 4s). If all retries fail, `audioStore.isError` is set to `true` with an error message.

### Next Track Preloading

When playback starts, `AudioProvider` preloads the next track in a secondary muted `<audio>` element. This minimizes buffering delay when skipping or when the current track ends. It respects shuffle and repeat mode when calculating which track to preload.

### State Persistence

`audioStore` automatically saves to `localStorage` under the key `audio:ui:store` whenever any of these fields change:

- Current track and queue
- Volume and mute
- Playback rate
- Repeat mode and shuffle
- Current playback position
- Queue insert mode and current index

On the next page load, `AudioProvider` restores these values and seeks to the last known position.

## Notes

- **Only one instance** — mount `AudioProvider` once at the top of your app. Multiple instances will conflict because they share the same `htmlAudio` singleton.

- **`tracks` prop is additive** — if `audioStore.queue` already has tracks (e.g. restored from `localStorage`), the `tracks` prop won't overwrite them unless they differ by length or `id`. This prevents overwriting the restored queue on page reload.

- **No playback on restore** — `AudioProvider` restores the last position and loads the track, but does not auto-play. The user must press play.

- **Live stream detection** — live streams are detected via `audio.duration === Infinity` or `NaN`. On a live stream end event (stream drops), `audioStore.isError` is set with the message `"Live stream connection lost"`.


# Audio Queue



<br>A set of composable components for managing the audio queue. Includes a browseable queue dialog, shuffle, repeat mode, and an advanced preferences panel.

## Installation

<InstallTabs>

{#snippet cli()}

<PMAddComp name="https://svelte-audio-ui.vercel.app/r/queue.json" />

{/snippet}

{#snippet manual()}

{#if viewerData}
	<ComponentSource item={viewerData} data-llm-ignore />
{:else}
	<p class="text-muted-foreground mt-4 text-sm">Source code not available.</p>
{/if}

{/snippet}

</InstallTabs>

## Usage

Import the components:

```svelte

```

### Basic Queue

The `AudioQueue` component opens a dialog showing the current queue with search functionality and track selection.

```svelte
<AudioPlayer.Root>
  <AudioPlayer.ControlBar>
    <AudioQueue.Root />
  </AudioPlayer.ControlBar>
</AudioPlayer.Root>
```

### Queue with Shuffle and Repeat

Use this when you want quick access to shuffle and repeat controls. The toggle buttons provide fast switching between modes.

<ComponentPreview name="queue-shuffle-repeat-demo" class="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[400px]" description="Queue with Shuffle and Repeat" align="center">

<div></div>

</ComponentPreview>

### Queue with Preferences

Use this when you want a compact interface with all queue settings in a dropdown menu. Ideal for space-constrained layouts.

<ComponentPreview name="queue-preferences-demo" class="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[400px]" description="Queue with Preferences" align="center">

<div></div>

</ComponentPreview>

### Queue with All Controls

Use this when you want a compact interface with all queue settings in a dropdown menu. Ideal for space-constrained layouts.

<ComponentPreview name="queue-all-controls-demo" class="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[400px]" description="Queue with All Controls" align="center">

<div></div>

</ComponentPreview>

## API Reference

### AudioQueue

An icon button that opens a dialog showing the current queue. Supports live search by title or artist, drag-to-reorder tracks (disabled when filtering), per-track remove, and a clear-all button.

#### Props

| Prop                | Type                      | Default                                 | Description                                   |
| ------------------- | ------------------------- | --------------------------------------- | --------------------------------------------- |
| `class`             | `string`                  | -                                       | Additional CSS classes on the trigger button. |
| `searchPlaceholder` | `string`                  | `"Search for a track..."`               | Placeholder text in the search input.         |
| `emptyLabel`        | `string`                  | `"No tracks found"`                     | Heading shown when the queue is empty.        |
| `emptyDescription`  | `string`                  | `"Try searching for a different track"` | Subtext for the empty state.                  |
| `onTrackSelect`     | `(index: number) => void` | -                                       | Called when a track row is clicked.           |

#### Behavior

- Opens a modal dialog with a full-height track list
- Search filters by `title` and `artist` (case-insensitive)
- When not filtering, the list is **drag-to-reorder** enabled
- Clicking a track plays it immediately; clicking the current track toggles play/pause
- Remove button appears on non-current tracks
- **Clear** button removes all tracks from the queue and closes the dialog

---

### AudioQueueShuffle

A toggle button that enables or disables shuffle mode. Highlights when active.

#### Props

| Prop      | Type     | Default     | Description             |
| --------- | -------- | ----------- | ----------------------- |
| `class`   | `string` | -           | Additional CSS classes. |
| `size`    | `string` | `"icon"`    | Button size variant.    |
| `variant` | `string` | `"outline"` | Button visual variant.  |

Accepts any additional HTML button attributes via `...rest`.

#### Behavior

- When shuffle is **enabled**: `audioStore.shuffle()` randomizes the remaining tracks
- When shuffle is **disabled**: `audioStore.unshuffle()` restores original order
- Uses `role="switch"` and `aria-checked` for accessibility

---

### AudioQueueRepeatMode

A toggle button that cycles through three repeat modes: **none → all → one**.

#### Props

| Prop      | Type     | Default     | Description             |
| --------- | -------- | ----------- | ----------------------- |
| `class`   | `string` | -           | Additional CSS classes. |
| `size`    | `string` | `"icon"`    | Button size variant.    |
| `variant` | `string` | `"outline"` | Button visual variant.  |

Accepts any additional HTML button attributes via `...rest`.

#### Behavior

| State  | Icon                    | Tooltip             |
| ------ | ----------------------- | ------------------- |
| `none` | `Repeat` (dimmed)       | "Disable repeat"    |
| `all`  | `Repeat` (highlighted)  | "Repeat playlist"   |
| `one`  | `Repeat1` (highlighted) | "Repeat this track" |

Cycles on click via `audioStore.changeRepeatMode()`. Uses `role="switch"` for accessibility.

---

### AudioQueuePreferences

An icon button that opens a dropdown with advanced queue settings: **Repeat Mode** and **Insert Mode**.

#### Props

| Prop           | Type     | Default               | Description                   |
| -------------- | -------- | --------------------- | ----------------------------- |
| `class`        | `string` | -                     | Additional CSS classes.       |
| `size`         | `string` | `"icon"`              | Button size variant.          |
| `variant`      | `string` | `"outline"`           | Button visual variant.        |
| `tooltipLabel` | `string` | `"Queue preferences"` | Tooltip text for the trigger. |

#### Repeat Mode options

| Value  | Description                              |
| ------ | ---------------------------------------- |
| `none` | No repeat — stops after the last track   |
| `one`  | Repeat the current track indefinitely    |
| `all`  | Loop through the full queue continuously |

#### Insert Mode options

Controls where newly added tracks are inserted into the queue:

| Value   | Description                                |
| ------- | ------------------------------------------ |
| `first` | Insert at the beginning of the queue       |
| `last`  | Append to the end of the queue             |
| `after` | Insert immediately after the current track |

## Related

- [Audio Player](/docs/components/player) — player controls to use alongside queue components
- [Audio Provider](/docs/components/provider) — required wrapper that manages queue state


# Audio Track



<br>Track components for displaying and managing audio tracks. These components support two modes:

- **Store mode**: reads from and controls the global audio queue provided by `audioStore`.
- **Controlled mode**: accepts an explicit list or single track for use in search results or external lists.

## Installation

<InstallTabs>

{#snippet cli()}

<PMAddComp name="https://svelte-audio-ui.vercel.app/r/track.json" />

{/snippet}

{#snippet manual()}

{#if viewerData}
	<ComponentSource item={viewerData} data-llm-ignore />
{:else}
	<p class="text-muted-foreground mt-4 text-sm">Source code not available.</p>
{/if}

{/snippet}

</InstallTabs>

## Usage

Import the components:

```svelte

```

### AudioTrack

Displays a single track with optional cover, metadata, and playback controls. Use either:

- `trackId` to render an item from the global audio queue (store mode), or
- `track` to render a provided track object (controlled mode).

<ComponentPreview name="track-demo" class="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[200px]" description="Single track item" align="center">

<div></div>

</ComponentPreview>

```svelte
<!-- From queue by id -->
<AudioTrack.Root trackId={track.id} />

<!-- With explicit data -->
<AudioTrack.Root track={customTrack} onclick={() => handlePlay(customTrack)} />
```

### AudioTrackList

Renders a list of tracks. Pass `tracks` for a controlled list, otherwise the component renders the global queue.

Key features:

- Text filtering via `filterQuery` or a custom `filterFn`.
- Optional drag-and-drop (`sortable`) — reordering updates the queue only when not filtered and when `tracks` is not provided.
- Per-item remove action and play/pause controls (configurable via props).

<ComponentPreview name="track-list-demo" class="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[300px]" description="Track list (store mode)" align="center">

<div></div>

</ComponentPreview>

```svelte
<!-- Store mode: renders global queue -->
<AudioTrack.List onTrackSelect={(index) => console.log(index)} />

<!-- Controlled mode: render custom set -->
<AudioTrack.List tracks={searchResults} onTrackSelect={handleSelect} />
```

#### Grid Layout

<ComponentPreview name="track-list-grid-demo" class="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[300px]" description="Track list grid layout" align="center">

<div></div>

</ComponentPreview>

#### Sortable

<ComponentPreview name="track-sortable-list-demo" class="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[300px]" description="Sortable track list" align="center">

<div></div>

</ComponentPreview>

#### Sortable Grid

<ComponentPreview name="track-sortable-list-grid-demo" class="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[300px]" description="Sortable track list grid" align="center">

<div></div>

</ComponentPreview>

## API Reference

### AudioTrack

#### Props

| Prop             | Type                        | Default | Description                                                                           |
| ---------------- | --------------------------- | ------- | ------------------------------------------------------------------------------------- |
| `trackId`        | `string \| number`          | -       | Load a track from the global queue (store mode). Do not use together with `track`.    |
| `track`          | `Track`                     | -       | Render a provided track object (controlled mode). Do not use together with `trackId`. |
| `index`          | `number`                    | -       | Display index (shown as one-based when `showCover` is false).                         |
| `onclick`        | `() => void`                | -       | Click handler invoked when the track row is clicked.                                  |
| `onRemove`       | `(trackId: string) => void` | -       | Called when the remove button is used. Receives the track `id` as a string.           |
| `showRemove`     | `boolean`                   | `false` | Whether to show the remove (✕) button. Always hidden for the currently playing track. |
| `showPlayPause`  | `boolean`                   | `true`  | Show play/pause control button.                                                       |
| `showDragHandle` | `boolean`                   | `false` | Show a drag handle (use together with a sortable list).                               |
| `showCover`      | `boolean`                   | `true`  | Show album artwork. Falls back to a music icon when no artwork is available.          |
| `class`          | `string`                    | -       | Additional CSS classes on the track row element.                                      |

> **Note:** Use either `trackId` (store mode) or `track` (controlled mode). Both should not be used together. Store mode requires `AudioProvider` to be set up. Cover images are taken from `track.artwork` or `track.images[0]`. Live tracks show a **Live** badge and the duration is hidden — live detection uses `htmlAudio.isLive()`.

---

### AudioTrackList

#### Props

| Prop               | Type                                     | Default                    | Description                                                                                                                                         |
| ------------------ | ---------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tracks`           | `Track[]`                                | -                          | Controlled list of tracks. When omitted, the component reads from the global queue (store mode).                                                    |
| `onTrackSelect`    | `(index: number, track?: Track) => void` | -                          | Called when a track is selected or played. In store mode the index is the queue index; in controlled mode it refers to the provided `tracks` array. |
| `onTrackRemove`    | `(trackId: string) => void`              | -                          | Remove handler used by the per-item remove button.                                                                                                  |
| `sortable`         | `boolean`                                | `false`                    | Enable drag-and-drop reordering. Reordering updates the store queue only when not filtered and when `tracks` is not provided.                       |
| `showCover`        | `boolean`                                | `true`                     | Show track cover image.                                                                                                                             |
| `variant`          | `"default" \| "grid"`                    | `"default"`                | Layout variant: stacked list or responsive grid.                                                                                                    |
| `filterQuery`      | `string`                                 | -                          | Simple text filter (matches `title` or `artist`, case-insensitive).                                                                                 |
| `filterFn`         | `(track: Track) => boolean`              | -                          | Custom filter function. When provided, `filterQuery` is ignored.                                                                                    |
| `emptyLabel`       | `string`                                 | `"No tracks found"`        | Label shown when the list is empty.                                                                                                                 |
| `emptyDescription` | `string`                                 | `"Try adding some tracks"` | Description shown in the empty state.                                                                                                               |
| `class`            | `string`                                 | -                          | Additional CSS classes.                                                                                                                             |

> **Store vs Controlled Mode:** When `tracks` is omitted, the component reads from the global queue. When `tracks` is provided, it operates in controlled mode using the provided array.

> **Sortable Behavior:** When `sortable` is enabled, reordering will only update the store queue when the list is not filtered (`filterQuery` and `filterFn` are not used) AND the component is in store mode (`tracks` prop is not provided). Keep `sortable` disabled while filtering to avoid unexpected reordering behavior.

## Examples

### Store mode (main queue)

```svelte
<AudioTrack.List
  sortable
  onTrackSelect={(i) => console.log("play queue index", i)}
/>
```

### Controlled mode (external list)

```svelte
<AudioTrack.List
  tracks={searchResults}
  variant="grid"
  onTrackSelect={(index, track) => addToQueue(track)}
/>
```

### Filtering

```svelte
<!-- Simple text filter -->
<AudioTrack.List filterQuery="jazz" />

<!-- Custom filter function -->
<AudioTrack.List filterFn={(t) => t.genre === "jazz"} />
```

### With removal

```svelte
<AudioTrack.List onTrackRemove={(id) => removeFromQueue(id)} />
```

## Related

- [Audio Player](/docs/components/player) — player controls to use alongside track components
- [Audio Provider](/docs/components/provider) — required wrapper that manages queue state
- [Audio Queue](/docs/components/queue) — queue dialog and ordering controls


# Fader



<br>A drag-to-adjust fader built entirely from plain HTML elements and Tailwind — no external slider primitives. Ideal for volume controls, mixing boards, or any parameter you want to expose in a tactile, studio-style UI. Supports vertical and horizontal orientations, three size variants, and configurable thumb marks.

<ComponentPreview name="fader-demo" class="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[250px]" description="Vertical fader" align="center">

<div></div>

</ComponentPreview>

## Installation

<InstallTabs>

{#snippet cli()}

<PMAddComp name="https://svelte-audio-ui.vercel.app/r/fader.json" />

{/snippet}

{#snippet manual()}

{#if viewerData}
	<ComponentSource item={viewerData} data-llm-ignore />
{:else}
	<p class="text-muted-foreground mt-4 text-sm">Source code not available.</p>
{/if}

{/snippet}

</InstallTabs>

## Usage

```svelte

```

```svelte
<Fader {value} onValueChange={(e) => (value = e)} />
```

### Horizontal Fader

<ComponentPreview name="fader-horizontal-demo" class="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[150px]" description="Horizontal fader" align="center">

<div></div>

</ComponentPreview>

### Custom Thumb Marks

<ComponentPreview name="fader-custom-thumb-marks-demo" class="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[250px]" description="Custom thumb marks count" align="center">

<div></div>

</ComponentPreview>

### No Thumb Marks

<ComponentPreview name="fader-no-thumb-marks-demo" class="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[250px]" description="Fader with no thumb marks" align="center">

<div></div>

</ComponentPreview>

## API Reference

### Fader

#### Props

| Prop            | Type                         | Default      | Description                                                 |
| --------------- | ---------------------------- | ------------ | ----------------------------------------------------------- |
| `value`         | `number`                     | `50`         | Current value (bindable).                                   |
| `min`           | `number`                     | `0`          | Minimum value.                                              |
| `max`           | `number`                     | `100`        | Maximum value.                                              |
| `step`          | `number`                     | `1`          | Step increment.                                             |
| `disabled`      | `boolean`                    | `false`      | Disables all interaction and adds reduced-opacity styling.  |
| `orientation`   | `"horizontal" \| "vertical"` | `"vertical"` | Fader orientation.                                          |
| `size`          | `"sm" \| "default" \| "lg"`  | `"default"`  | Controls the track width and thumb dimensions.              |
| `thumbMarks`    | `number \| false`            | `3`          | Number of grip lines on the thumb, or `false` to hide them. |
| `label`         | `string`                     | -            | Optional text label rendered above the fader.               |
| `onValueChange` | `(value: number) => void`    | -            | Fires on every input event as the user drags.               |
| `class`         | `string`                     | -            | Additional CSS classes on the root wrapper.                 |

#### Behavior

- Interaction is handled by an invisible native `<input type="range">` stretched over the full component — keyboard and pointer events just work, fully accessible.
- Vertical mode uses `writing-mode: vertical-lr` + `direction: rtl` on the hidden input so dragging upward increases the value, matching physical fader muscle memory.
- The fill and thumb position are driven by derived state — no manual DOM manipulation needed.

> **Tip:** Use `bind:value` for two-way binding in Svelte, or pass `value` + `onValueChange` for a controlled setup.

## Examples

### Volume Control

Wire directly to `audioStore` for a store-driven volume fader:

<ComponentPreview name="fader-volume-control-demo" class="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[250px]" description="Volume control fader" align="center">

<div></div>

</ComponentPreview>

### Multiple Faders (Mixing Board)

<ComponentPreview name="fader-multiple-control-demo" class="[&_.preview>[data-orientation=vertical]]:sm:max-w-[80%] **:[.preview]:min-h-[300px]" description="Mixing board with multiple faders" align="center">

<div></div>

</ComponentPreview>

## Related

- [Audio Player](/docs/components/player) — player controls to pair with faders
- [Audio Provider](/docs/components/provider) — audio context and state management


# Knob



<br>A pure Svelte knob built from plain HTML and SVG — no external primitives. Drag up/down to adjust, use keyboard arrows for fine control, and see value progress through a 270° arc indicator. Four size variants keep it fitting everywhere from compact effect panels to large master controls.

<ComponentPreview name="knob-demo" description="Basic knob" align="center">

<div></div>

</ComponentPreview>

## Installation

<InstallTabs>

{#snippet cli()}

<PMAddComp name="https://svelte-audio-ui.vercel.app/r/knob.json" />

{/snippet}

{#snippet manual()}

{#if viewerData}
	<ComponentSource item={viewerData} data-llm-ignore />
{:else}
	<p class="text-muted-foreground mt-4 text-sm">Source code not available.</p>
{/if}

{/snippet}

</InstallTabs>

## Usage

```svelte

```

```svelte
<Knob value={50} />
```

### Size Variants

<ComponentPreview name="knob-size-variants-demo" description="All four knob size variants" align="center">

<div></div>

</ComponentPreview>

## API Reference

### Knob

#### Props

| Prop            | Type                                | Default     | Description                                        |
| --------------- | ----------------------------------- | ----------- | -------------------------------------------------- |
| `value`         | `number`                            | `50`        | Current value (bindable).                          |
| `min`           | `number`                            | `0`         | Minimum value.                                     |
| `max`           | `number`                            | `100`       | Maximum value.                                     |
| `step`          | `number`                            | `1`         | Step increment.                                    |
| `disabled`      | `boolean`                           | `false`     | Disables all interaction and adds reduced-opacity. |
| `size`          | `"sm" \| "default" \| "lg" \| "xl"` | `"default"` | Controls the knob diameter.                        |
| `label`         | `string`                            | -           | Optional text label rendered above the knob.       |
| `onValueChange` | `(value: number) => void`           | -           | Fires on every change while the user interacts.    |
| `class`         | `string`                            | -           | Additional CSS classes on the root wrapper.        |

#### Behavior

- **Drag:** Click and drag vertically — drag up to increase, drag down to decrease. 200 px of travel covers the full value range.
- **Keyboard:** `ArrowUp` / `ArrowRight` increases; `ArrowDown` / `ArrowLeft` decreases by one step. `Home` jumps to `min`, `End` to `max`.
- **Arc indicator:** A 270° SVG arc shows the track (dimmed) and the active fill from min to the current value.
- **Pointer indicator:** The inner disc rotates with the value, with a small dot marking the exact position.

> **Tip:** Use `bind:value` for two-way binding in Svelte, or pass `value` + `onValueChange` for a controlled setup.

## Examples

### Filter Control

<ComponentPreview name="knob-filter-control-demo" description="Filter frequency, resonance, and mix knobs" align="center">

<div></div>

</ComponentPreview>

### Multiple Knobs

<ComponentPreview name="knob-multiple-control-demo" description="Multiple knobs for a channel strip" align="center">

<div></div>

</ComponentPreview>

## Related

- [Fader](/docs/ui/fader) — linear slider-style control for mixing boards
- [Audio Player](/docs/components/player) — player controls to pair with knobs
- [Audio Provider](/docs/components/provider) — audio context and state management


# Slider



<ComponentPreview name="slider-demo" description="A slider component with buffer support." align="center">

<div></div>

</ComponentPreview>

## Installation

<InstallTabs>

{#snippet cli()}

<PMAddComp name="https://svelte-audio-ui.vercel.app/r/slider.json" />

{/snippet}

{#snippet manual()}

{#if viewerData}
	<ComponentSource item={viewerData} data-llm-ignore />
{:else}
	<p class="text-muted-foreground mt-4 text-sm">Source code not available.</p>
{/if}

{/snippet}

</InstallTabs>

## Usage

```svelte

```

```svelte
<Slider value={[33]} max={100} step={1} />
```

### Buffer Indicator

This slider extends the shadcn-svelte slider component (which uses `bits-ui`) to add support for a `bufferValue` prop, which displays a buffer indicator behind the current value. This is particularly useful for media players to show loading progress:

```svelte showLineNumbers


<Slider
  bufferValue={75}
  class="w-[60%]"
  value={[25]}
  max={100}
  step={1}
/>
```

## API Reference

### Slider

This component extends the `bits-ui` Slider component and inherits its props. Additionally, it supports:

| Prop            | Type                                  | Default        | Description                                                                                                                                         |
| --------------- | ------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`         | `number[]`                            | -              | The controlled value array of the slider.                                                                                                           |
| `defaultValue`  | `number[]`                            | -              | The uncontrolled default value array.                                                                                                               |
| `bufferValue`   | `number`                              | -              | Buffer indicator value (0-100). Displays a semi-transparent overlay behind the current value. Useful for showing loading progress in media players. |
| `min`           | `number`                              | `0`            | The minimum value for the range.                                                                                                                    |
| `max`           | `number`                              | `100`          | The maximum value for the range.                                                                                                                    |
| `step`          | `number`                              | `1`            | The stepping interval.                                                                                                                              |
| `orientation`   | `"horizontal" \| "vertical"`          | `"horizontal"` | The orientation of the slider.                                                                                                                      |
| `disabled`      | `boolean`                             | `false`        | When `true`, prevents the user from interacting with the slider.                                                                                    |
| `onValueChange` | `(value: number[]) => void`           | -              | Event handler called when the value changes.                                                                                                        |
| `onValueCommit` | `(value: number[]) => void`           | -              | Event handler called when the value changes at the end of an interaction (e.g. pointer up).                                                         |

For all other props, see the [Bits UI Slider API Reference](https://bits-ui.com/docs/components/slider).

## Notes

> **Important Information:**
>
> * **Custom Component:** This component is based on the default shadcn-svelte registry `Slider` component but extends it with audio-specific features. All standard slider functionality is preserved, with the addition of the `bufferValue` prop for buffer indicators.
> * **Buffer Indicator:** The buffer indicator displays a semi-transparent overlay behind the current value. This is particularly useful for media players to show loading progress or buffered content.
> * **Usage in Audio Player:** This slider is used by the `AudioPlayerSeekBar` component to display playback progress and buffer status.


# Sortable List



<ComponentPreview name="sortable-list-demo" description="A sortable list component with drag-and-drop support." >
	<div></div>

</ComponentPreview>

## Installation

<InstallTabs>

{#snippet cli()}

<PMAddComp name="https://svelte-audio-ui.vercel.app/r/sortable-list.json" />

{/snippet}

{#snippet manual()}

{#if viewerData}
	<ComponentSource item={viewerData} data-llm-ignore />
{:else}
	<p class="text-muted-foreground mt-4 text-sm">Source code not available.</p>
{/if}

{/snippet}

</InstallTabs>

## Usage

```svelte

```

```svelte showLineNumbers


<div class="w-full max-w-sm">
  <SortableList bind:items onDrop={(v) => (items = v)}>
    {#snippet item(row)}
      <SortableItem
        class="border-border bg-muted/40 rounded-md border p-3 text-sm"
      >
        <SortableDragHandle />
        <div class="flex flex-col">
          <span class="font-semibold">{row.title}</span>
          <span class="text-muted-foreground text-xs"
            >{row.description}</span
          >
        </div>
      </SortableItem>
    {/snippet}
  </SortableList>
</div>
```

## API Reference

### SortableList

The main container component for sortable items. Built with `svelte-dnd-action` for accessibility and smooth drag-and-drop interactions.

#### Props

| Prop       | Type                                | Description                                                                                                                             |
| ---------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `items`    | `Item[]`                            | Array of items to display (bindable). Each item must have an `id` property.                                                             |
| `onDrop`   | `(items: Item[]) => void`           | Callback fired when items are reordered.                                                                                                |
| `item`     | `Snippet<[Item]>`                   | The snippet block to render each item.                                                                                                  |
| `class`    | `string`                            | Additional CSS classes for the list container.                                                                                          |

### SortableItem

A wrapper component for individual sortable items.

#### Props

| Prop       | Type      | Description                                        |
| ---------- | --------- | -------------------------------------------------- |
| `class`    | `string`  | Additional CSS classes on the inner `div` wrapper. |
| `children` | `Snippet` | Content of the sortable item.                      |

> **Note:** `SortableItem` does not require an `id` prop, as the item layout and ID configuration are managed at the `SortableList` level via `<svelte:animate>`.

### SortableDragHandle

A pre-built drag handle button that uses the sortable component state context to initiate a drag mechanism. Extends your existing `Button` component layout.

#### Props

Inherits all props from shadcn-svelte's `Button` component, overriding `active` states automatically to establish grip interactions.

## Notes

> **Important Information:**
>
> - **Custom Component:** This component is based on the Svelte port of the ui registry. It's a custom component built specifically to enable drag-and-drop reordering of tracks in user interfaces.
> - **Built with svelte-dnd-action:** This component is built on top of `svelte-dnd-action`, which abstracts accessibility attributes.
> - **Drag Handle:** The `SortableDragHandle` component uses shadcn/ui's `Button` component and provides a pre-configured drag handle with localized event listeners contextually bound to the active `SortableList`. Use it to create designated draggable interaction anchors in a list.
> - **Item IDs:** Each item must have a unique `id` property (either string or number). The type requirement is checked internally.
> - **Usage in Audio Components:** This component is used by the `AudioTrackList` internally to enable drag-and-drop reordering of tracks in the queue.


# XY Pad



<ComponentPreview name="xypad-demo" description="Basic XY Pad" align="center">

<div></div>

</ComponentPreview>

## Installation

<InstallTabs>

{#snippet cli()}

<PMAddComp name="https://svelte-audio-ui.vercel.app/r/xypad.json" />

{/snippet}

{#snippet manual()}

{#if viewerData}
	<ComponentSource item={viewerData} data-llm-ignore />
{:else}
	<p class="text-muted-foreground mt-4 text-sm">Source code not available.</p>
{/if}

{/snippet}

</InstallTabs>

## Usage

```svelte

```

### Basic XY Pad

```svelte
<XYPad defaultValue={{ x: 50, y: 50 }} />
```

### Custom Value Display

<ComponentPreview name="xypad-format-value-demo" description="Custom formatted value display" align="center">

<div></div>

</ComponentPreview>

### Hide Value Display

<ComponentPreview name="xypad-hide-value-demo" description="XY Pad with hidden value display overlay" align="center">

<div></div>

</ComponentPreview>

## API Reference

### XYPad

#### Props

| Prop               | Type                                          | Default                | Description                                     |
| ------------------ | --------------------------------------------- | ---------------------- | ----------------------------------------------- |
| `value`            | `{ x: number; y: number }`                    | -                      | Controlled value.                               |
| `defaultValue`     | `{ x: number; y: number }`                    | `{ x: 50, y: 50 }`     | Uncontrolled default value.                     |
| `size`             | `"sm" \| "default" \| "lg" \| "xl"`           | `"default"`            | Size variant (affects height).                  |
| `disabled`         | `boolean`                                     | `false`                | Disables interaction and lowers opacity.        |
| `label`            | `string`                                      | -                      | Optional text label rendered above the pad.     |
| `showValueDisplay` | `boolean`                                     | `true`                 | Whether to show the value display overlay.      |
| `formatValue`      | `(value: { x: number; y: number }) => string` | -                      | Custom formatter for the value text.            |
| `class`            | `string`                                      | -                      | Additional CSS classes for the root element.    |
| `onValueChange`    | `(value: { x: number; y: number }) => void`   | -                      | Callback when value changes during interaction. |
| `onValueCommit`    | `(value: { x: number; y: number }) => void`   | -                      | Callback when value is committed (on release).  |

## Examples

### Synthesizer Control

<ComponentPreview name="xypad-synthesizer-control-demo" description="Synthesizer parameter mapping" align="center">

<div></div>

</ComponentPreview>

### Filter Control

<ComponentPreview name="xypad-filter-control-demo" description="Filter cutoff and resonance control" align="center">

<div></div>

</ComponentPreview>

## Notes

> **Important Information:**
>
> * **Native Implementation:** This component is built as a pure Svelte implementation, providing a high-quality, accessible XY pad control without bulky dependencies.
> * **Grid Display:** The pad includes a visual grid to help with positioning.
> * **Crosshair:** Visual crosshairs indicate the current X and Y positions.
> * **Value Display:** By default, a value display overlay shows the current position. You can customize the formatter function or hide it entirely.
> * **Size Variants:** Four size variants are available (`sm`, `default`, `lg`, and `xl`). These effectively control the pad height.
> * **Keyboard Support:** Arrow keys adjust the value by 1. Holding `Shift` while using arrow keys changes the step amount to 10. `y = 100` maps to the top of the pad following standard musical conventions.


# Audio Store



<br/>

## Installation

<InstallTabs>

{#snippet cli()}

<PMAddComp name="https://svelte-audio-ui.vercel.app/r/provider.json" />

{/snippet}

{#snippet manual()}

{#if viewerData}
	<ComponentSource item={viewerData} data-llm-ignore />
{:else}
	<p class="text-muted-foreground mt-4 text-sm">Source code not available.</p>
{/if}

{/snippet}

</InstallTabs>

### Import

Import the global store and helper types directly into your Svelte components:

```svelte

```

## Core Concepts

### The `audioStore` Singleton

We leverage Svelte 5's powerful `$state` runes to create a highly reactive, class-based global store. Instead of messy subscriptions or cumbersome contexts, you just import `audioStore` and read its properties anywhere. Svelte handles the magic.

<Callout variant="info">
  <strong>Performance Best Practices:</strong> Because `audioStore` uses runes, accessing its properties in your markup or inside `$derived` / `$effect` blocks automatically establishes granular reactivity. Only the parts of your UI that depend on changed state will re-render!
</Callout>

```svelte


<p>
  {audioStore.currentTrack?.title} ({audioStore.duration}s) — {audioStore.isPlaying
    ? "▶"
    : "⏸"}
</p>
```

### Architecture

The `AudioStore` focuses purely on **state management**. It doesn't touch the `<audio>` element directly. Instead, the `AudioProvider` component listens to the store and orchestrates the browser's Audio API.

## Store State

The store exposes properties organized by concern. All of these are deeply reactive (`$state`).

| Category          | Property            | Type                           | Description                  |
| ----------------- | ------------------- | ------------------------------ | ---------------------------- |
| **Playback**      | `isPlaying`         | `boolean`                      | Currently playing            |
|                   | `isLoading`         | `boolean`                      | Loading track                |
|                   | `isBuffering`       | `boolean`                      | Buffering audio              |
|                   | `isError`           | `boolean`                      | Error state                  |
|                   | `errorMessage`      | `string \| null`               | Error details                |
| **Current Track** | `currentTrack`      | `Track \| null`                | Active track object          |
|                   | `currentTime`       | `number`                       | Playback position (seconds)  |
|                   | `duration`          | `number`                       | Track length                 |
|                   | `progress`          | `number`                       | Normalized progress 0–100    |
|                   | `bufferedTime`      | `number`                       | Buffered amount              |
| **Queue**         | `queue`             | `Track[]`                      | Array of tracks              |
|                   | `currentQueueIndex` | `number`                       | Active track index           |
| **Controls**      | `volume`            | `number`                       | Volume 0–1                   |
|                   | `isMuted`           | `boolean`                      | Mute state                   |
|                   | `playbackRate`      | `number`                       | Playback speed (0.25–2)      |
|                   | `repeatMode`        | `"none" \| "one" \| "all"`     | Repeat mode                  |
|                   | `shuffleEnabled`    | `boolean`                      | Shuffle state                |
|                   | `insertMode`        | `"first" \| "last" \| "after"` | Insertion position for queue |

## Types

| Type         | Values                         | Description                             |
| ------------ | ------------------------------ | --------------------------------------- |
| `RepeatMode` | `"none" \| "one" \| "all"`     | Repeat playback mode                    |
| `InsertMode` | `"first" \| "last" \| "after"` | Where new tracks are added to the queue |

## Utility Functions

### `calculateNextIndex`

Calculate the next track index based on playback mode, queue length, and shuffle state.

```typescript
const nextIndex = calculateNextIndex({
  queue: audioStore.queue,
  currentQueueIndex: audioStore.currentQueueIndex,
  shuffleEnabled: audioStore.shuffleEnabled,
  repeatMode: audioStore.repeatMode,
});
// Returns: number (track index or -1 if none)
```

### `calculatePreviousIndex`

Calculate the previous track index based on playback mode.

```typescript
const prevIndex = calculatePreviousIndex({
  queue: audioStore.queue,
  currentQueueIndex: audioStore.currentQueueIndex,
  shuffleEnabled: audioStore.shuffleEnabled,
  repeatMode: audioStore.repeatMode,
});
// Returns: number (track index or -1 if none)
```

### `canUseDOM()`

Check if code runs in a DOM environment (safe for SSR).

```typescript
if (canUseDOM()) {
  // Safe to access window or localStorage
}
```

## Actions

Access actions directly on the `audioStore` instance.

| Category       | Action             | Signature                                        | Description                                            |
| -------------- | ------------------ | ------------------------------------------------ | ------------------------------------------------------ |
| **Playback**   | `play`             | `() => void`                                     | Signifies playback intent                              |
|                | `pause`            | `() => void`                                     | Pause playback                                         |
|                | `togglePlay`       | `() => void`                                     | Toggle play/pause state                                |
|                | `seek`             | `(time: number) => void`                         | Seek to position (seconds)                             |
| **Navigation** | `next`             | `() => void`                                     | Play next track                                        |
|                | `previous`         | `() => void`                                     | Play previous track (or restart based on time)         |
|                | `setCurrentTrack`  | `(track: Track \| null) => void`                 | Load and play specific track                           |
|                | `setQueueAndPlay`  | `(tracks: Track[], startIndex: number) => void`  | Set queue and play from index                          |
| **Queue**      | `addToQueue`       | `(track: Track, mode?: InsertMode) => void`      | Add track to queue (supports "first", "last", "after") |
|                | `removeFromQueue`  | `(trackId: string) => void`                      | Remove track from queue                                |
|                | `moveInQueue`      | `(fromIndex: number, toIndex: number) => void`   | Move track in queue                                    |
|                | `setQueue`         | `(tracks: Track[], startIndex?: number) => void` | Replace entire queue                                   |
|                | `clearQueue`       | `() => void`                                     | Clear all tracks from queue                            |
| **Volume**     | `setVolume`        | `({ volume: number }) => void`                   | Set volume (0-1)                                       |
|                | `toggleMute`       | `() => void`                                     | Toggle mute state                                      |
| **Modes**      | `setPlaybackRate`  | `(rate: number) => void`                         | Adjust playback speed                                  |
|                | `changeRepeatMode` | `() => void`                                     | Cycle repeat mode (none → one → all → none)            |
|                | `setRepeatMode`    | `(mode: RepeatMode) => void`                     | Set repeat mode                                        |
|                | `shuffle`          | `() => void`                                     | Randomize queue order                                  |
|                | `unshuffle`        | `() => void`                                     | Restore original queue order                           |
|                | `setInsertMode`    | `(mode: InsertMode) => void`                     | Set insert mode                                        |
| **Error**      | `setError`         | `(message: string \| null) => void`              | Set or clear error state                               |

## Examples

### Basic Usage

Building a custom minimal player is insanely easy. Just wire up the store.

```svelte


<div class="rounded-md border p-4">
  <p class="font-bold">Track: {audioStore.currentTrack?.title ?? "None"}</p>
  <p class="text-sm text-gray-500">
    Time: {formatDuration(audioStore.currentTime)} / {formatDuration(
      audioStore.duration
    )}
  </p>
  <p class="mb-2">Status: {audioStore.isPlaying ? "▶ Playing" : "⏸ Paused"}</p>

  <div class="flex gap-2">
    <button onclick={() => audioStore.previous()}>◀ Prev</button>
    <button onclick={() => audioStore.togglePlay()}>
      {audioStore.isPlaying ? "⏸" : "▶"}
    </button>
    <button onclick={() => audioStore.next()}>Next ▶</button>
  </div>
</div>
```

### Queue Management

Easily manipulate the queue with just a few method calls.

```svelte


<div>
  <div class="mb-4 flex gap-2">
    <button onclick={() => audioStore.addToQueue(newTrack, "last")}
      >Add Track</button
    >
    <button onclick={() => audioStore.clearQueue()}>Clear</button>
  </div>
  <div class="space-y-1">
    {#each audioStore.queue as track (track.id)}
      <div class="flex justify-between border p-2">
        <span>{track.title}</span>
        <button onclick={() => audioStore.removeFromQueue(track.id)}
          >Remove</button
        >
      </div>
    {/each}
  </div>
</div>
```

### Outside of Components

Need to kick off music from a vanilla `.ts` file or a SvelteKit load function? Since `audioStore` is a class singleton, it works anywhere.

```typescript
import { audioStore } from "$lib/audio-store.svelte";

// Read state
console.log(audioStore.isPlaying);

// Call actions
audioStore.play();

// Update volume
audioStore.setVolume({ volume: 0.5 });
```

## Persistence

We hate it when a refresh kills the vibe. The store automatically hydrates and syncs a subset of its state to `localStorage` on the fly.

| Category     | Properties                                                         |
| ------------ | ------------------------------------------------------------------ |
| **Playback** | `currentTrack`, `currentTime`, `currentQueueIndex`, `playbackRate` |
| **Queue**    | `queue`                                                            |
| **Settings** | `volume`, `isMuted`, `repeatMode`, `shuffleEnabled`, `insertMode`  |

**Storage Key:** `audio:ui:store`

The user can resume their queue seamlessly after a page refresh, as if they never left.

## Related

- [Audio Library](/docs/libs/html-audio) — Core HTMLAudio integration
- [Audio Provider](/docs/components/provider) — Handles the HTML `<audio>` bindings.
- [Audio Player](/docs/components/player) — Drop-in UI components.
- [Audio Queue](/docs/components/queue) — Queue UI management.

## Notes

<Callout variant="info">

  <strong>
    Best Practices:
  </strong>

- `audioStore` focuses solely on state. The `AudioProvider` component handles the actual loading and syncing of the `<audio>` element.
- Ensure the `AudioProvider` wraps your app, or at least the part where playback happens, for the state to translate to real sound.
- Async events (buffering, track end) are driven by the `AudioProvider` which calls methods like `handleTrackEnd()` or sets `syncTime()` on the `audioStore`.
- The `playbackRate` automatically resets to `1` when loading live streams to prevent awful chipmunk audio.

</Callout>


# HTML Audio



<br/>

The `htmlAudio` singleton manages playback of HTML5 audio with automatic retry logic, event handling, and volume fading. Use it alongside the [Audio Store](/docs/libs/audio-store) for full player functionality.

## Installation

<InstallTabs>

{#snippet cli()}

<PMAddComp name="https://svelte-audio-ui.vercel.app/r/provider.json" />

{/snippet}

{#snippet manual()}

{#if viewerData}
	<ComponentSource item={viewerData} data-llm-ignore />
{:else}
	<p class="text-muted-foreground mt-4 text-sm">Source code not available.</p>
{/if}

{/snippet}

</InstallTabs>

### Import

Import the singleton and helpers from the audio library:

```svelte

```

## Core API

### The `htmlAudio` Singleton

Manages the underlying `HTMLAudioElement`, playback state, retries, and custom events. Initialize on client start — the instance is built to be server-safe.

```typescript
import { htmlAudio } from "$lib/html-audio";

// Initialize on the client
htmlAudio.init();

// Load and play
await htmlAudio.load({ url: "https://example.com/audio.mp3", startTime: 0 });
await htmlAudio.play();
```

<Callout variant="info">

<strong>Client initialization:</strong>

The `htmlAudio` singleton must be initialized on the client.

Call `htmlAudio.init()` inside `onMount` or an `$effect` so the underlying
`HTMLAudioElement` is created only in the browser environment.

</Callout>

#### Lifecycle

| Method      | Description                                             |
| ----------- | ------------------------------------------------------- |
| `init()`    | Initialize on the client. Safe to call multiple times.  |
| `cleanup()` | Reset and release the audio element (pause, clear src). |

#### Playback

| Method                                     | Description                                                                                                                                 |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `load({ url, startTime?, isLiveStream? })` | Load an audio source and wait for readiness. Pass `isLiveStream: true` for live streams (longer timeout, no seek). Returns `Promise<void>`. |
| `play()`                                   | Start or resume playback. Returns a promise that resolves when the browser allows playback.                                                 |
| `pause()`                                  | Pause playback immediately.                                                                                                                 |
| `setCurrentTime(time)`                     | Seek when metadata is available. Ignored and bounded by duration safely.                                                                    |
| `setPlaybackRate(rate)`                    | Adjust playback speed (0.25 - 2). Disabled automatically if it's a live stream.                                                             |

<Callout variant="warning">

**Browser autoplay restrictions:**

The `play()` call returns a promise which may be rejected by browser autoplay policies if there was no recent user gesture.
Make sure playback is initiated by a user interaction.

</Callout>

<Callout variant="info">

**Live streams:** For live streams (when `isLiveStream` is
true) seeking is disabled and longer timeouts (60s instead of 30s) are used carefully to handle stream buffering.

</Callout>

#### Volume

| Method                             | Description                                                                 |
| ---------------------------------- | --------------------------------------------------------------------------- |
| `setVolume({ volume, fadeTime? })` | Set or fade volume (0–1). If `fadeTime` > 0, animates smoothly.             |
| `getVolume()`                      | Return current volume (0–1).                                                |
| `setMuted(muted)`                  | Mute or unmute. Restores previous volume when unmuting using a smooth fade. |

#### State

| Method                | Description                                                    |
| --------------------- | -------------------------------------------------------------- |
| `getDuration()`       | Return loaded source duration (seconds) or `0` if unavailable. |
| `getCurrentTime()`    | Return current playback position (seconds).                    |
| `isPaused()`          | Return boolean — is playback paused.                           |
| `getBufferedRanges()` | Return underlying `TimeRanges` or `null`.                      |
| `getSource()`         | Return current source URL string.                              |
| `getAudioElement()`   | Return raw `HTMLAudioElement` or `null` on server.             |
| `getPlaybackRate()`   | Return current playback rate.                                  |

#### Events

The library emits custom events via an internal `EventTarget`. You can listen to these without messing with the raw `<audio>` element events:

```typescript
htmlAudio.addEventListener("bufferingStart", () =>
  console.log("Buffering...")
);
htmlAudio.addEventListener("bufferingEnd", () => console.log("Ready to play"));
htmlAudio.addEventListener("playbackStarted", () => console.log("Playing"));
htmlAudio.addEventListener("audioError", () => console.error("Error"));
htmlAudio.addEventListener("bufferUpdate", (e) => {
  if (e instanceof CustomEvent)
    console.log("Buffered:", e.detail.bufferedTime);
});
```

## Utilities

### `formatDuration`

Format seconds into an `MM:SS` string. Extremely handy for UI constraints. Handles invalid input gracefully.

```typescript
import { formatDuration } from "$lib/html-audio";

console.log(formatDuration(125)); // "2:05"
console.log(formatDuration(3661)); // "61:01"
```

### `htmlAudio.isLive`

Check if a duration value indicates a live stream.

```typescript
import { htmlAudio } from "$lib/html-audio";

const duration = htmlAudio.getDuration();

if (htmlAudio.isLive(duration)) {
  // Disable scrubbers, hide fast-forward buttons, etc.
}
```

<Callout variant="info">

**Live Stream Detection:** The `isLive()` method checks
if a duration `isNaN`,`Infinity`, or `-Infinity`. A duration of `0` just means the metadata hasn't loaded yet.

</Callout>

## Types

### Track

A versatile representation of an audio track to be used across your components:

| Prop            | Type               | Description                      |
| --------------- | ------------------ | -------------------------------- |
| `id`            | `string \| number` | Unique identifier (optional).    |
| `url`           | `string`           | URL of the audio file or stream. |
| `title`         | `string`           | Track title.                     |
| `artist`        | `string`           | Artist name.                     |
| `artwork`       | `string`           | Album artwork URL.               |
| `images`        | `string[]`         | Array of image URLs.             |
| `duration`      | `number`           | Track duration in seconds.       |
| `album`         | `string`           | Album name.                      |
| `genre`         | `string`           | Genre.                           |
| `live`          | `boolean`          | Whether this is a live stream.   |
| `[key: string]` | `unknown`          | Additional ad-hoc properties.    |

## Examples

### Basic Playback

Just wire it up on mount.

```svelte


<button onclick={() => playTrack("/music.mp3")}>Play Track</button>
```

### Volume Fading

Awesome polish feature: you can smoothly fade the volume instead of jarring the user.

```typescript
import { htmlAudio } from "$lib/html-audio";

// Immediate jump
htmlAudio.setVolume({ volume: 0.5 });

// Smooth, butter-like fade over 1 second (1000ms)
htmlAudio.setVolume({ volume: 0.8, fadeTime: 1000 });

// Mute with memory (remembers previous volume when toggled back)
htmlAudio.setMuted(true);
htmlAudio.setMuted(false);
```

### Listening to Progress

```svelte


<span>{formatDuration(time)}</span>
```

## Related

- [Audio Store](/docs/libs/audio-store) — A Svelte 5 global store wrapping this class to provide reactive state.
- [Audio Provider](/docs/components/provider) — Composable provider that orchestrates `htmlAudio` inside your layout.
- [Audio Player](/docs/components/player) — Composable player UI components.

## Notes

- **Singleton pattern**: All methods access the exact same `htmlAudio` instance behind the scenes.
- **Server-safe**: Most methods (`getVolume()`, etc) have built-in `isClient()` guards, so they won't blow up during SSR.
- **Resilience**: It handles native HTML5 `<audio>` random error events entirely manually, throwing up to 3 retries under the hood before giving up.
- **Polished Fades**: Built-in volume cross-fades use `getAnimationFrame` / timers for smooth transitions. Just supply `fadeTime`.