Here's the complete README.md file in one view for easy copying:

1# React Udux Player
2
3A customizable music player for React applications with HLS streaming support, track preloading, style isolation, and a rich set of features.
4
5## Features
6
7- 🎵 HLS streaming support
8- 🔄 Track preloading for smooth transitions
9- 🎨 Fully customizable theming
10- 🧩 Pluggable UI components
11- 📱 Responsive design
12- 🔊 Volume control with mute toggle
13- 🔀 Shuffle and repeat modes
14- ⏱️ Progress bar with seeking
15- 🎧 Event callbacks for player state changes
16- 🔒 Style isolation to prevent conflicts with your app's styles
17
18## Installation
19
20```bash
21npm install react-udux-player
22# or
23yarn add react-udux-player
24# or
25pnpm add react-udux-player

Quick Start

1import { UduxPlayerProvider, UduxPlayer, useUduxPlayer } from 'react-Udux-player';
2
3// Define your tracks
4const tracks = [
5  {
6    id: "1",
7    title: "Song Title",
8    artist: "Artist Name",
9    duration: 180,
10    streamUrl: "https://example.com/song.m3u8",
11    coverUrl: "/images/cover.jpg"
12  },
13  // More tracks...
14];
15
16// In your component
17function App() {
18  return (
19    <UduxPlayerProvider>
20      {/* Your app content */}
21      <MusicLibrary />
22      <UduxPlayer />
23    </UduxPlayerProvider>
24  );
25}
26
27// Use the player in any component
28function MusicLibrary() {
29  const { setQueue, togglePlay, currentTrack } = useUduxPlayer();
30  
31  return (
32    <div>
33      <h1>My Music</h1>
34      <button onClick={() => {
35        setQueue(tracks);
36        togglePlay();
37      }}>
38        Play All
39      </button>
40      
41      {/* Display current track */}
42      {currentTrack && (
43        <div>
44          Now playing: {currentTrack.title} by {currentTrack.artist}
45        </div>
46      )}
47    </div>
48  );
49}

Style Isolation

The player uses a scoped CSS approach to prevent style conflicts with your application. All player styles are:

• Dynamically generated and injected at runtime
• Prefixed with unique class names (udux-player-*)
• Contained within the player's DOM structure
• Automatically cleaned up when the player is unmounted

This ensures that the player's styles won't affect your application's styles and vice versa.

Customization

Theming

You can customize the player's appearance by providing a theme object:

1import { UduxPlayerProvider, UduxPlayer } from 'react-Udux-player';
2
3const myTheme = {
4  colors: {
5    primary: '#1DB954',           // Main accent color
6    background: '#121212',        // Player background
7    text: '#FFFFFF',              // Primary text color
8    textSecondary: '#B3B3B3',     // Secondary text color
9    progressBar: '#535353',       // Progress bar background
10    progressBarFilled: '#1DB954', // Filled part of progress bar
11    controlBackground: '#282828', // Background for controls
12    playerBorder: '#282828',      // Border color
13  },
14  sizes: {
15    playerHeight: '90px',         // Height of the player
16    progressBarHeight: '4px',     // Height of progress bar
17    controlButtonSize: '32px',    // Size of control buttons
18    volumeSliderWidth: '100px',   // Width of volume slider
19    coverArtSize: '56px',         // Size of cover art
20  },
21  borderRadius: '4px',            // Border radius for elements
22  fontFamily: 'system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif', // Font family
23};
24
25function App() {
26  return (
27    <UduxPlayerProvider theme={myTheme}>
28      <UduxPlayer />
29    </UduxPlayerProvider>
30  );
31}

Custom Components

You can replace any part of the player UI with your own components:

1import { UduxPlayerProvider, UduxPlayer } from 'react-Udux-player';
2import MyCustomPlayButton from './MyCustomPlayButton';
3import MyCustomVolumeControl from './MyCustomVolumeControl';
4
5function App() {
6  return (
7    <UduxPlayerProvider
8      components={{
9        PlayButton: MyCustomPlayButton,
10        VolumeControl: MyCustomVolumeControl,
11      }}
12    >
13      <UduxPlayer />
14    </UduxPlayerProvider>
15  );
16}

Example of a custom play button component:

1// MyCustomPlayButton.jsx
2import React from 'react';
3
4const MyCustomPlayButton = ({ isPlaying, onClick, isBuffering }) => {
5  return (
6    <button
7      onClick={onClick}
8      style={{
9        backgroundColor: '#1DB954',
10        color: 'white',
11        border: 'none',
12        borderRadius: '50%',
13        width: '40px',
14        height: '40px',
15        display: 'flex',
16        alignItems: 'center',
17        justifyContent: 'center',
18        cursor: 'pointer',
19      }}
20    >
21      {isBuffering ? (
22        <span>⋯</span>
23      ) : isPlaying ? (
24        <span>❚❚</span>
25      ) : (
26        <span>▶</span>
27      )}
28    </button>
29  );
30};
31
32export default MyCustomPlayButton;

Custom Icons and Styling

The player comes with a set of custom icons and styling out of the box:

• Like/favorite button
• Fullscreen toggle
• Add to playlist button
• Minimize player button
• Now playing view toggle
• Dynamic background colors based on album artwork

Dominant Color Extraction

The player automatically extracts dominant colors from the album artwork and applies them as a gradient background:

Event Callbacks

Listen to player events:

1import { UduxPlayerProvider, UduxPlayer } from 'react-Udux-player';
2
3function App() {
4  return (
5    <UduxPlayerProvider
6      onTrackChange={(track) => console.log('Now playing:', track?.title)}
7      onPlaybackStateChange={(isPlaying) => console.log('Playback:', isPlaying ? 'playing' : 'paused')}
8      onError={(error) => console.error('Player error:', error)}
9      onTimeUpdate={(time) => console.log('Current time:', time)}
10      onQueueChange={(queue) => console.log('Queue updated:', queue.length, 'tracks')}
11      onVolumeChange={(volume, isMuted) => console.log('Volume:', volume, isMuted ? '(muted)' : '')}
12      onShuffleChange={(shuffleEnabled) => console.log('Shuffle:', shuffleEnabled ? 'on' : 'off')}
13      onRepeatChange={(repeatMode) => console.log('Repeat mode:', repeatMode)}
14      onSeek={(time) => console.log('Seeked to:', time)}
15      onEnded={() => console.log('Track ended')}
16      onLike={(track, isLiked) => console.log(`Track ${track?.title} ${isLiked ? 'liked' : 'unliked'}`)}
17      onAddToPlaylist={(track) => console.log(`Add ${track?.title} to playlist`)}
18      onFullscreenChange={(isFullscreen) => console.log(`Fullscreen: ${isFullscreen}`)}
19      onViewChange={(isNowPlayingView) => console.log(`Now playing view: ${isNowPlayingView}`)}
20      onMinimize={() => console.log('Player minimized')}
21    >
22      <UduxPlayer />
23    </UduxPlayerProvider>
24  );
25}

Creating a Custom Player

You can create your own player UI while still using the player context:

1import React from 'react';
2import { UduxPlayerProvider, useUduxPlayer } from 'react-Udux-player';
3
4// Custom player component
5function CustomPlayer() {
6  const {
7    currentTrack,
8    isPlaying,
9    togglePlay,
10    nextTrack,
11    previousTrack,
12    currentTime,
13    duration,
14    seek,
15  } = useUduxPlayer();
16
17  // Format time as MM:SS
18  const formatTime = (time) => {
19    if (!time) return '0:00';
20    const minutes = Math.floor(time / 60);
21    const seconds = Math.floor(time % 60);
22    return `${minutes}:${seconds.toString().padStart(2, '0')}`;
23  };
24
25  if (!currentTrack) {
26    return <div>No track selected</div>;
27  }
28
29  return (
30    <div className="my-custom-player">
31      <div className="track-info">
32        <img 
33          src={currentTrack.coverUrl || '/default-cover.jpg'} 
34          alt={currentTrack.title} 
35          className="cover-art"
36        />
37        <div>
38          <h3>{currentTrack.title}</h3>
39          <p>{currentTrack.artist}</p>
40        </div>
41      </div>
42
43      <div className="controls">
44        <button onClick={previousTrack}>Previous</button>
45        <button onClick={togglePlay}>
46          {isPlaying ? 'Pause' : 'Play'}
47        </button>
48        <button onClick={nextTrack}>Next</button>
49      </div>
50
51      <div className="progress">
52        <span>{formatTime(currentTime)}</span>
53        <input
54          type="range"
55          min={0}
56          max={duration || 100}
57          value={currentTime || 0}
58          onChange={(e) => seek(Number(e.target.value))}
59        />
60        <span>{formatTime(duration)}</span>
61      </div>
62    </div>
63  );
64}
65
66// Main app
67function App() {
68  return (
69    <UduxPlayerProvider>
70      <div>
71        {/* Your app content */}
72        <CustomPlayer />
73      </div>
74    </UduxPlayerProvider>
75  );
76}

API Reference

UduxPlayerProvider Props

Prop	Type	Description
children	ReactNode	Child components
theme	Theme	Theme customization object
components	CustomComponents	Custom UI components
initialVolume	number	Initial volume level (0-100)
initialShuffle	boolean	Initial shuffle state
initialRepeat	"off"	"all"
onTrackChange	(track: Track	null) => void
onPlaybackStateChange	(isPlaying: boolean) => void	Called when playback starts or stops
onError	(error: Error) => void	Called when an error occurs
onTimeUpdate	(time: number) => void	Called when playback time updates
onQueueChange	(queue: Track[]) => void	Called when the queue changes
onVolumeChange	(volume: number, isMuted: boolean) => void	Called when volume changes
onShuffleChange	(shuffleEnabled: boolean) => void	Called when shuffle mode changes
onRepeatChange	(repeatMode: RepeatMode) => void	Called when repeat mode changes
onSeek	(time: number) => void	Called when seeking to a position
onEnded	() => void	Called when a track ends
onLike	(track: Track	null, isLiked: boolean) => void
onAddToPlaylist	(track: Track	null) => void
onFullscreenChange	(isFullscreen: boolean) => void	Called when you trigger fullscreen mode
onViewChange	(isNowPlayingView: boolean) => void	Called when you toggle now playing
onMinimize	() => void	Called when you toggle minimize player

useUduxPlayer Hook

The useUduxPlayer hook provides access to the player state and controls:

Property/Method	Type	Description
currentTrack	Track	null
queue	Track[]	Current queue of tracks
isPlaying	boolean	Whether playback is active
volume	number	Current volume (0-100)
isMuted	boolean	Whether audio is muted
currentTime	number	Current playback position in seconds
duration	number	Duration of current track in seconds
shuffle	boolean	Whether shuffle mode is active
repeat	"off"	"all"
isBuffering	boolean	Whether the player is buffering
togglePlay	() => void	Toggle play/pause
nextTrack	() => void	Skip to next track
previousTrack	() => void	Go to previous track
seek	(time: number) => void	Seek to position in seconds
setVolume	(volume: number) => void	Set volume (0-100)
toggleMute	() => void	Toggle mute
toggleShuffle	() => void	Toggle shuffle mode
toggleRepeat	() => void	Cycle repeat modes
setQueue	(tracks: Track[]) => void	Set the queue of tracks
theme	Theme	Current theme object
tracksToPreload	number[]	Indices of tracks being preloaded

Track Interface

1interface Track {
2  id: string;
3  title: string;
4  artist: string;
5  album?: string;
6  duration: number;
7  coverUrl?: string;
8  streamUrl: string;
9}

Theme Interface

1interface Theme {
2  colors: {
3    primary: string;
4    background: string;
5    text: string;
6    textSecondary: string;
7    progressBar: string;
8    progressBarFilled: string;
9    controlBackground?: string;
10    playerBorder?: string;
11  };
12  sizes: {
13    playerHeight: string;
14    progressBarHeight: string;
15    controlButtonSize: string;
16    volumeSliderWidth?: string;
17    coverArtSize?: string;
18  };
19  borderRadius: string;
20  fontFamily?: string;
21}

CustomComponents Interface

1interface CustomComponents {
2  PlayButton?: React.ComponentType<{ isPlaying: boolean; onClick: () => void; isBuffering: boolean }>;
3  NextButton?: React.ComponentType<{ onClick: () => void; disabled: boolean }>;
4  PreviousButton?: React.ComponentType<{ onClick: () => void; disabled: boolean }>;
5  ShuffleButton?: React.ComponentType<{ active: boolean; onClick: () => void; disabled: boolean }>;
6  RepeatButton?: React.ComponentType<{ mode: RepeatMode; onClick: () => void; disabled: boolean }>;
7  VolumeControl?: React.ComponentType<{
8    volume: number;
9    isMuted: boolean;
10    onVolumeChange: (volume: number) => void;
11    onMuteToggle: () => void;
12  }>;
13  ProgressBar?: React.ComponentType<{
14    currentTime: number;
15    duration: number;
16    onSeek: (time: number) => void;
17    isBuffering: boolean;
18  }>;
19  TrackInfo?: React.ComponentType<{ track: Track | null }>;
20  PlayerContainer?: React.ComponentType<{ children: React.ReactNode }>;
21}

Troubleshooting

Controls not working

If the player controls are not responding:

1. Make sure you've set up a queue of tracks using setQueue
2. Check that your stream URLs are valid and accessible
3. Verify that you're using the useUduxPlayer hook within a component that's a child of UduxPlayerProvider
4. Add console logs to your click handlers to verify they're being called

Style conflicts

If you're experiencing style conflicts:

1. The player uses scoped CSS with prefixed class names (udux-player-*) to prevent conflicts
2. If conflicts persist, you can create a custom player UI using the useUduxPlayer hook

Audio not playing

If audio doesn't play:

1. Check that your stream URLs are valid and accessible
2. Verify that the browser supports HLS playback (most modern browsers do)
3. Check browser console for any errors
4. Try using a public test stream like https://test-streams.mux.dev/x36xhzz/x36xhzz.m3u8

Browser Support

The player works in all modern browsers that support HTML5 audio and video. For HLS streaming support, it uses the react-hls-player package which provides cross-browser compatibility.

License