Custom Audio Player

A modern, fully customizable React Audio Player with support for playlists, progress tracking, volume control, loop, playback speed adjustments, and more.

🎮 Demo

---

📜 Table of Contents

• Features
• Installation
• Usage
  • Hybrid Component
  • Uncontrolled Component
• Props
• Styling & Customization
• Contributing
• Changelog
• License

---

🚀 Features

✅ Fully customizable UI with Tailwind CSS support
✅ Supports playlist playback
✅ Hybrid & Uncontrolled component usage
✅ Loop, volume, and playback speed controls
✅ Supports click-to-play song selection
✅ Smooth progress tracking and seek
✅ Lightweight and optimized for performance

---

📦 Installation

You can install this package via npm or yarn:

1npm install react-pro-audio-player

or

1yarn add react-pro-audio-player

---

📖 Usage

1️⃣ Hybrid Component

A hybrid component gives you full control over the player's state, such as isPlaying and currentSongIndex, allowing external management of playback.

1import React, { useState } from "react";
2import CustomAudioPlayer from "react-pro-audio-player";
3
4const songsList = [
5  { id: 1, url: "./assets/song1.mp3", title: "Song One", thumbnail:"Song Image" , singer:"Song Singer"},
6  { id: 2, url: "./assets/song2.mp3", title: "Song Two", thumbnail:"Song Image" , singer:"Song Singer" },
7  { id: 3, url: "./assets/song3.mp3", title: "Song Three", thumbnail:"Song Image" , singer:"Song Singer" },
8];
9
10const App = () => {
11  const [songs, setSongs] = useState(songsList);
12  const [isPlaying, setIsPlaying] = useState(false);
13  const [currentSongIndex, setCurrentSongIndex] = useState(null);
14
15  return (
16    <>
17      <div>
18        {songs.map((song, index) => (
19          <div key={song.id} onClick={() => setCurrentSongIndex(index)}>
20            {song.title}
21          </div>
22        ))}
23      </div>
24      {currentSongIndex !== null && (
25        <CustomAudioPlayer
26          songs={songs}
27          isPlaying={isPlaying}
28          currentSongIndex={currentSongIndex}
29          onPlayPauseChange={setIsPlaying}
30          onSongChange={setCurrentSongIndex}
31          songUrlKey="url"
32          songNameKey="title"
33          songThumbnailKey="thumbnail" 
34          songSingerKey="singer"
35        />
36      )}
37    </>
38  );
39};
40
41export default App;

2️⃣ Uncontrolled Component

If you want default behavior with minimal setup, use the uncontrolled component. This does not require managing state externally.

1import CustomAudioPlayer from "react-pro-audio-player";
2
3const songsList = [
4  { id: 1, url: "./assets/song1.mp3", title: "Song One" , thumbnail:"Song Image" , singer:"Song Singer" },
5  { id: 2, url: "./assets/song2.mp3", title: "Song Two" , thumbnail:"Song Image" , singer:"Song Singer"},
6  { id: 3, url: "./assets/song3.mp3", title: "Song Three" , thumbnail:"Song Image" , singer:"Song Singer" },
7];
8
9const App = () => {
10  return (
11    <CustomAudioPlayer songs={songsList} songUrlKey="url" songNameKey="title" songThumbnailKey="thumbnail" songSingerKey="singer" />
12  );
13};
14
15export default App;

---

🎛️ Props

Prop	Type	Required	Description
songs	Array	✅ Yes	List of songs with { id, url, title } objects.
songUrlKey	string	✅ Yes	The key name in the song object that stores the song URL
songNameKey	string	❌ No	The key name in the song object that stores the song name
songThumbnailKey	string	❌ No	The key name in the song object that stores the song image
songSingerKey	string	❌ No	The key name in the song object that stores the song singers
isPlaying	boolean	❌ No	Controls playback state (Hybrid mode only).
currentSongIndex	number	❌ No	Index of the currently playing song (Hybrid mode only).
onPlayPauseChange	function	❌ No	Callback function to toggle play/pause (Hybrid mode only).
onSongChange	function	❌ No	Callback function when song changes (Hybrid mode only).

📝 Note:

• Props isPlaying, currentSongIndex, onPlayPauseChange, and onSongChange should be used together in Hybrid mode.

---

🎨 Styling & Customization

You can customize the player with CSS classes. The default styles use Tailwind-like classes:

Class Name	Description
.custom-audio-player	Main player container
.audio-player	Inner audio player container
.progress-bar	Custom progress bar styling
.controls-wrapper	Wrapper for playback controls
.playback-btn	Button for play, pause, next, and previous
.volume-slider	Volume control styling
.playback-speed	Dropdown for speed selection

---

🎭 Customization

You can enhance the audio player by adding more styles or modifying props. Example of custom styling:

1.custom-audio-player {
2  background-color: #333;
3  color: #fff;
4  padding: 10px;
5  border-radius: 8px;
6}

But need to import the CustomAudioPlayer.css file:

1import "react-pro-audio-player/src/CustomAudioPlayer.css";

Before the global css file

1import "react-pro-audio-player/src/CustomAudioPlayer.css";
2import "./index.css";

---

🤝 Contributing

We welcome contributions! Here’s how you can help:

1. Fork the repository.
2. Create a new branch (feature-xyz).
3. Make your changes.
4. Submit a pull request.

GitHub Repository: CustomAudioPlayer

---

📌 Changelog

v3.0.0 - (Latest Release)

• 🎨 Revamped UI with Tailwind CSS support
• 🎵 Added songs details to be displayed

v2.0.0 -

• 🎵 Added Hybrid & Uncontrolled component support
• 🎚 Improved progress tracking and seek function
• 🔄 Loop & playback speed controls added
• 🎨 Revamped UI with Tailwind CSS support
• 🛠 Optimized state management for better performance

v1.0.0

• Initial release with core audio playback features.
• Play/Pause, Forward/Backward, Volume Control, Loop, and Playback Speed.
• Responsive UI.

---

📝 License

This package is open-source and available under the MIT License. Feel free to use and modify it as needed!

---

🚀 Enjoy building with Custom Audio Player! 🎧