Headless React Library for Custom Audio Players – re-audio

Description:

re-audio is a React component library for building custom audio players. It handles the core logic of audio playback, including playlists, track management, and timekeeping. You retain full control over the user interface and styling.

You can use re-audio to build various audio-related features. Examples include custom music players for websites, embedded podcast players for blogs, or audio playback functionality within web applications.

The headless design means you are not restricted to a predefined player skin and can match the player’s design to your application’s branding.

Features

• 🎯 Built with TypeScript for reliable type safety and developer experience.
• 📀 Manages complex audio functionality like playlists and track sequencing.
• ⏱️ Includes utilities such as formatTime for displaying audio timestamps.
• 🎨 Offers custom React hooks for creating advanced features like audio visualizers.

Use Cases

• Custom Music Players: Build a unique music player for a band’s website or an artist’s portfolio.
• Podcast Player Integration: Create a branded podcast player that embeds directly into a blog or media site.
• Audio in E-Learning: Develop audio components for educational platforms to play lectures or instructional content.
• Website Background Audio: Implement background audio for promotional or immersive websites.

How to Use It

1. Before installation, check your React version. Version 2.0.0 and newer of re-audio requires React 19. If you are using React 18, you must install version 1.1.1.

2. Installation

For React 19 and later, run the following command:

npm i --save @sina_byn/re-audio

For React 18, install the specific version:

npm install --save @sina_byn/[email protected]

3. Wrap your player components with the Audio provider. This provider manages the audio state and makes it available to all child components. It requires a playlist prop, which is an array of objects, each representing an audio track.

Here is an example of setting up the Audio provider in a component:

// AudioPlayer.tsx
import { Audio, formatTime } from '@sina_byn/re-audio';
import PlaybackControls from './PlaybackControls';
const AudioPlayer = () => {
  const myPlaylist = [
    { id: 1, src: '/audio/track1.mp3', name: 'Ambient Chill' },
    { id: 2, src: '/audio/track2.mp3', name: 'Trap Beat Instrumental' },
    { id: 3, src: '/audio/track3.mp3', name: 'Afro Dancehall' },
  ];
  return (
    <Audio playlist={myPlaylist}>
      {audioContext => (
        <div>
          <p>Now Playing: {audioContext.track?.name}</p>
          <div>
            <span>{formatTime(audioContext.currentTime)}</span> / <span>{formatTime(audioContext.duration)}</span>
          </div>
          <PlaybackControls />
        </div>
      )}
    </Audio>
  );
};
export default AudioPlayer;

4. You can create separate components for playback controls. The useAudio hook provides access to playback functions and state, such as togglePlay, nextTrack, prevTrack, and the current playing status.

Below is an example of a PlaybackControls component:

// PlaybackControls.tsx
import { useAudio } from '@sina_byn/re-audio';
const PlaybackControls = () => {
  const { playing, togglePlay, prevTrack, nextTrack } = useAudio();
  return (
    <div>
      <button type="button" onClick={prevTrack}>
        Prev
      </button>
      <button type="button" onClick={togglePlay}>
        {playing ? 'Pause' : 'Play'}
      </button>
      <button type="button" onClick={nextTrack}>
        Next
      </button>
    </div>
  );
};
export default PlaybackControls;

5. Available audio props.

export type AudioProps = {
  playlist: AudioTrack[];
  defaultMuted?: boolean;
  defaultRepeat?: RepeatMode;
  defaultShuffle?: boolean;
  defaultVolume?: number;
  defaultPlaybackRate?: number;
  defaultTrackIndex?: number;
  startMargin?: number | boolean;
  children: AudioChildren;
};

FAQs

Q: How do I customize the look of the audio player?
A: re-audio is a headless library, which means it does not come with any predefined styles. You build the UI with your own components and apply your own styling.

Q: Can I build an audio visualizer with this library?
A: Yes, re-audio includes custom React hooks specifically for creating audio visualizers.

Q: Does the library support playlists?
A: Yes, you can pass an array of audio track objects to the playlist prop of the Audio component to manage a playlist.