Skip to main content

AudioPlayer Pro

The pieces of a podcast or music app. AudioPlayer is the track card: artwork, title and show, a waveform you scrub with the played part filled, skip back 15 and forward 30 seconds, speed (1×, 1.25×, 1.5×, 2×, 0.75×), and previous and next in a playlist. MiniPlayer is the bar that keeps playing at the bottom of the screen while people browse. TrackList is the list of episodes or songs, with bars bouncing on the one that's playing.

All three read one player from useAudioPlayer, so pressing play in one updates the others. The web plays through an HTMLAudioElement; on iOS and Android you pass an adapter built on expo-audio (below).

import { AudioPlayer, MiniPlayer, TrackList, useAudioPlayer } from '@patine-ui/pro';
Loading…
<AudioPlayer track={EPISODE} style={{ width: '100%', maxWidth: 640 }} />

Under 520 points wide the card stacks: the artwork beside the title, the waveform below, and the controls centred.

Example: a podcast app​

One useAudioPlayer drives everything. TrackList loads and plays the episode you press (pressing the playing one pauses it); onEnded moves to the next; the card's previous and next walk the list; and the MiniPlayer stays at the bottom with the same state.

Loading…
<VStack gap="md" style={{ width: '100%', maxWidth: 640 }}>
  <AudioPlayer player={player} onPrevious={() => step(-1)} onNext={() => step(1)} />
  <TrackList tracks={EPISODES} player={player} />
  <MiniPlayer player={player} onPress={() => {}} />
</VStack>

In an app, put the MiniPlayer above the tab bar in your root layout and open the full AudioPlayer in a sheet from its onPress.

Compact​

variant="compact" is one row (play, title, waveform, time) for a voice note, a lesson clip or a preview in a feed.

Loading…
<VStack gap="sm" style={{ width: '100%', maxWidth: 420 }}>
  <AudioPlayer variant="compact" track={{ id: 'a', title: 'Lesson 3 · Listening', src: 'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-3.mp3', duration: 343, peaks: wave(1) }} />
  <AudioPlayer variant="compact" track={{ id: 'b', title: 'Voice memo from Maya', src: 'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-4.mp3', duration: 302 }} />
</VStack>

Without peaks the scrubber is a plain bar.

An album​

numbered shows track numbers in place of artwork, with the bars on the playing one.

Loading…
<TrackList tracks={TRACKS} player={player} numbered style={{ width: '100%', maxWidth: 480 }} />

iOS and Android with expo-audio​

The adapter gets a source and emit, starts a native player, and returns the controls for it:

import { createAudioPlayer, setAudioModeAsync } from 'expo-audio';

await setAudioModeAsync({ playsInSilentMode: true, shouldPlayInBackground: true });

export const expoAudio = (src, emit) => {
const player = createAudioPlayer(src, { updateInterval: 100 });
const sub = player.addListener('playbackStatusUpdate', (s) =>
emit({
playing: s.playing,
currentTime: s.currentTime,
duration: s.duration,
waiting: s.isBuffering,
ended: s.didJustFinish,
started: s.playing || s.currentTime > 0,
})
);
return {
play: () => player.play(),
pause: () => player.pause(),
seek: (t) => player.seekTo(t),
setRate: (r) => player.setPlaybackRate(r),
setVolume: (v) => (player.volume = v),
setMuted: (m) => (player.muted = m),
release: () => {
sub.remove();
player.remove();
},
};
};

const player = useAudioPlayer({ track, adapter: expoAudio });

For lock-screen controls, call expo-audio's setActiveForLockScreen with the track's title and artwork in the same adapter.

Accessibility​

  • Play and pause, skip ("Back 15 seconds"), speed ("Playback speed: 1.5×"), previous and next are named buttons, 44pt or larger.
  • The waveform is a slider: screen readers read "2 minutes 5 seconds of 6 minutes 12 seconds" and step with increment and decrement; on the web it takes focus.
  • TrackList rows read title, show and length, and say "Now playing" on the current one (aria-current). The bouncing bars are hidden from screen readers and still with reduce motion on.

Props​

useAudioPlayer​

OptionTypeDefaultDescription
trackAudioTrack—The first track.
autoPlaybooleanfalsePlay it as soon as it loads.
adapter(src, emit) => MediaController—Plays on iOS and Android.
ratesnumber[][1, 1.25, 1.5, 2, 0.75]Speeds the speed button cycles through.
onEnded(track) => void—A track finished: load the next.

It returns { track, state, load(track, { autoPlay }), play, pause, toggle, seek, seekBy, setRate, cycleRate }. state has playing, currentTime, duration, buffered, rate, waiting, ended, error.

AudioTrack is { id, src, title, artist?, artwork?, duration?, peaks?, meta? }; peaks are 0 to 1, any count (they're resampled to fit).

AudioPlayer​

PropTypeDefaultDescription
playerAudioPlayerController—A shared player from useAudioPlayer.
trackAudioTrack—Without player, a track for a player of its own.
variant'card' | 'compact''card'The card, or one row.
skipBack, skipForwardnumber15, 30Seconds the skip buttons jump.
onPrevious, onNext() => void—Show previous and next buttons.
labels, style, theme, design

MiniPlayer​

PropTypeDefaultDescription
playerAudioPlayerControllerrequiredThe shared player. Draws nothing until it has a track.
onPress() => void—Open the full player.
onClose() => void—Show a close button.
skipForwardnumber30Seconds its skip button jumps.
labels, style, theme, design

TrackList​

PropTypeDefaultDescription
tracksAudioTrack[]requiredThe episodes or songs.
playerAudioPlayerControllerrequiredMarks its track; a press plays or pauses.
numberedbooleanfalseNumbers in place of artwork.
labels, style, theme, design