Audio Player

A composable audio player with transport, seeking, time, volume, rate, loop and keyboard shortcuts.

3 min read · 542 words

Loading…

Installation

$ pnpm dlx shadcn-svelte@latest add https://juddisjudd.github.io/audiocn-svelte/r/audio-player.json

$ npx shadcn-svelte@latest add https://juddisjudd.github.io/audiocn-svelte/r/audio-player.json

$ yarn dlx shadcn-svelte@latest add https://juddisjudd.github.io/audiocn-svelte/r/audio-player.json

$ bunx --bun shadcn-svelte@latest add https://juddisjudd.github.io/audiocn-svelte/r/audio-player.json

Usage

<script lang="ts">
	import {
		AudioPlayer,
		AudioPlayerPlay,
		AudioPlayerSeek,
	} from "#lib/components/ui/audio-player/index.js";
</script>

<AudioPlayer src="/episode.mp3">
	<AudioPlayerPlay />
	<AudioPlayerSeek />
</AudioPlayer>

Every part is optional. A play button and a seek bar is a complete player. Buttons show a text label unless you pass an icon as children, so the component works with any icon set.

Anatomy

<AudioPlayer>
	<AudioPlayerArtwork />
	<AudioPlayerTitle />
	<AudioPlayerDescription />
	<AudioPlayerControls>
		<AudioPlayerPrevious />
		<AudioPlayerSkipBack />
		<AudioPlayerPlay />
		<AudioPlayerSkipForward />
		<AudioPlayerNext />
	</AudioPlayerControls>
	<AudioPlayerTime />
	<AudioPlayerSeek />
	<AudioPlayerTime type="remaining" />
	<AudioPlayerVolume />
	<AudioPlayerRate />
	<AudioPlayerLoop />
</AudioPlayer>

Examples

Compact

With a waveform and a playlist

The Music Player block uses a Waveform as the seek bar and a Track List for the queue.

Your own player state

Create the player with useAudioPlayer and pass it in, to reach it from outside, route it into a mixer or analyse it.

<script lang="ts">
	import { AudioPlayer } from "#lib/components/ui/audio-player/index.js";
	import { useAudioAnalyser } from "#lib/hooks/use-audio-analyser.svelte.js";
	import { useAudioPlayer } from "#lib/hooks/use-audio-player.svelte.js";

	let { src }: { src: string } = $props();

	const player = useAudioPlayer(() => ({ src }));
	const analyser = useAudioAnalyser(() => player.element);
</script>

<AudioPlayer {player}>…</AudioPlayer>

useAudioPlayerContext() reads the player from inside any part. Call it during the setup of a component inside the player.

Keyboard

While focus is inside the player:

Key	Action
Space or K	Play or pause
Left / Right	Seek 5 s
Shift + Left / Right	Seek 15 s
Up / Down	Volume
M	Mute
Home / End	Start or end

Theming

Data attribute	Meaning
`data-playing`, `data-paused`, `data-loading`, `data-ended`, `data-error`, `data-muted`	Player state, on the root
`data-playing`, `data-loading`	On `AudioPlayerPlay`
`data-looping`	On `AudioPlayerLoop` when on
`data-dragging`	On the seek bar while dragged
`data-type`	On `AudioPlayerTime`

API reference

AudioPlayer

Prop	Type	Default
`src`	`string`	—
`player` Use an external player from useAudioPlayer.	`AudioPlayerController`	—
`autoPlay / loop / muted`	`boolean`	`false`
`volume` 0..1.	`number`	`1`
`playbackRate`	`number`	`1`
`preload`	`"none" \| "metadata" \| "auto"`	`"metadata"`
`crossOrigin` Needed to analyse remote audio.	`"anonymous" \| "use-credentials"`	—
`onPlay / onPause / onEnded`	`() => void`	—
`onTimeUpdate`	`(time) => void`	—
`onPrevious / onNext` Enable the previous and next buttons.	`() => void`	—
`onError`	`(error: MediaError \| null) => void`	—
`shortcuts` Keyboard shortcuts while focus is inside.	`boolean`	`true`

AudioPlayerPlay

Prop	Type	Default
`children` An icon, or a snippet that takes the state.	`Snippet<[{ playing, loading }]>`	—

<AudioPlayerPlay>
	{#snippet children({ playing })}
		{#if playing}
			<PauseIcon weight="fill" />
		{:else}
			<PlayIcon weight="fill" />
		{/if}
	{/snippet}
</AudioPlayerPlay>

Buttons

AudioPlayerPlay, AudioPlayerPrevious, AudioPlayerNext, AudioPlayerSkipBack, AudioPlayerSkipForward, AudioPlayerRate and AudioPlayerLoop render a <button>.

Prop	Type	Default
`child` Render your own element. Spread props on it.	`Snippet<[{ props }]>`	—

AudioPlayerSkipBack, AudioPlayerSkipForward

Prop	Type	Default
`seconds`	`number`	`10`

AudioPlayerSeek

Prop	Type	Default
`step / largeStep` Seconds for the keyboard.	`number`	`5 / 15`
`disabled` Disabled until the duration is known.	`boolean`	—

AudioPlayerTime

Prop	Type	Default
`type`	`"current" \| "remaining" \| "duration"`	`"current"`
`format`	`(seconds, type) => string`	`formatTime`

AudioPlayerRate

Prop	Type	Default
`rates` Cycles on click.	`number[]`	`[0.5, 0.75, 1, 1.25, 1.5, 2]`

AudioPlayerVolume

A VolumeControl bound to the player's volume and mute. It takes the same props, except value and muted.