0
# React H5 Audio Player
1

2
React H5 Audio Player is a customizable React audio player component written in TypeScript that provides consistent UI/UX across different browsers and mobile devices. It features comprehensive customization options, full keyboard accessibility, MSE/EME support, and modular design with extensive event handling capabilities.
3

4
## Package Information
5

6
- **Package Name**: react-h5-audio-player
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-h5-audio-player`
10

11
## Core Imports
12

13
```typescript
14
import AudioPlayer from 'react-h5-audio-player';
15
import 'react-h5-audio-player/lib/styles.css';
16
```
17

18
For CommonJS:
19

20
```javascript
21
const AudioPlayer = require('react-h5-audio-player');
22
require('react-h5-audio-player/lib/styles.css');
23
```
24

25
Additional imports for UI customization and MSE:
26

27
```typescript
28
import AudioPlayer, { RHAP_UI, OnSeek } from 'react-h5-audio-player';
29
import { ReactNode, CSSProperties } from 'react';
30
```
31

32
## Basic Usage
33

34
```typescript
35
import React from 'react';
36
import AudioPlayer from 'react-h5-audio-player';
37
import 'react-h5-audio-player/lib/styles.css';
38

39
const MyAudioPlayer = () => (
40
  <AudioPlayer
41
    src="https://example.com/audio.mp3"
42
    onPlay={e => console.log("Playing audio")}
43
    onPause={e => console.log("Paused audio")}
44
    // Additional props as needed
45
  />
46
);
47
```
48

49
Advanced usage with customization:
50

51
```typescript
52
import React from 'react';
53
import AudioPlayer, { RHAP_UI } from 'react-h5-audio-player';
54
import 'react-h5-audio-player/lib/styles.css';
55

56
const CustomPlayer = () => (
57
  <AudioPlayer
58
    src="https://example.com/audio.mp3"
59
    autoPlay={false}
60
    showSkipControls={true}
61
    showJumpControls={true}
62
    customAdditionalControls={[RHAP_UI.LOOP]}
63
    customVolumeControls={[RHAP_UI.VOLUME]}
64
    onClickPrevious={() => console.log('Previous track')}
65
    onClickNext={() => console.log('Next track')}
66
    header={<div>Now Playing: Song Title</div>}
67
    footer={<div>Artist Name</div>}
68
  />
69
);
70
```
71

72
## Architecture
73

74
React H5 Audio Player is built around several key components:
75

76
- **Main Component**: `H5AudioPlayer` class component providing the primary interface
77
- **UI Modules**: Modular components like ProgressBar, VolumeBar, CurrentTime, and Duration
78
- **Customization System**: Extensible UI through custom icons, layouts, and control sections
79
- **Event System**: Comprehensive HTML5 audio event handling with custom extensions
80
- **Accessibility**: Full keyboard navigation and ARIA label support
81
- **Styling**: SCSS/CSS with customizable themes and responsive design
82

83
## Capabilities
84

85
### Core Audio Player
86

87
The main H5AudioPlayer component providing comprehensive audio playback functionality with extensive customization options.
88

89
```typescript { .api }
90
interface PlayerProps {
91
  // Core HTML5 audio properties
92
  src?: string;
93
  autoPlay?: boolean;
94
  loop?: boolean;
95
  muted?: boolean;
96
  volume?: number;
97
  preload?: AUDIO_PRELOAD_ATTRIBUTE;
98
  crossOrigin?: React.AudioHTMLAttributes<HTMLAudioElement>['crossOrigin'];
99
  mediaGroup?: string;
100
  
101
  // Player behavior
102
  autoPlayAfterSrcChange?: boolean;
103
  hasDefaultKeyBindings?: boolean;
104
  listenInterval?: number;
105
  progressUpdateInterval?: number;
106
  progressJumpStep?: number;
107
  progressJumpSteps?: { backward?: number; forward?: number };
108
  volumeJumpStep?: number;
109
  
110
  // UI configuration
111
  className?: string;
112
  style?: CSSProperties;
113
  layout?: MAIN_LAYOUT;
114
  showJumpControls?: boolean;
115
  showSkipControls?: boolean;
116
  showDownloadProgress?: boolean;
117
  showFilledProgress?: boolean;
118
  showFilledVolume?: boolean;
119
  timeFormat?: TIME_FORMAT;
120
  
121
  // Custom content
122
  header?: ReactNode;
123
  footer?: ReactNode;
124
  defaultCurrentTime?: ReactNode;
125
  defaultDuration?: ReactNode;
126
  children?: ReactNode;
127
  
128
  // Event handlers - see Component Props & Events doc
129
  onPlay?: (e: Event) => void;
130
  onPause?: (e: Event) => void;
131
  onEnded?: (e: Event) => void;
132
  // ... many more event handlers
133
}
134

135
class H5AudioPlayer extends Component<PlayerProps> {
136
  static defaultI18nAriaLabels: I18nAriaLabels;
137
  static defaultProps: Partial<PlayerProps>;
138
  
139
  togglePlay(e: React.SyntheticEvent): void;
140
  playAudioPromise(): void;
141
  isPlaying(): boolean;
142
}
143
```
144

145
[Component Props & Events](./component-props-events.md)
146

147
### UI Customization & Layout
148

149
Advanced customization system for modifying the player's appearance, layout, and individual UI components.
150

151
```typescript { .api }
152
interface CustomIcons {
153
  play?: ReactNode;
154
  pause?: ReactNode;
155
  rewind?: ReactNode;
156
  forward?: ReactNode;
157
  previous?: ReactNode;
158
  next?: ReactNode;
159
  loop?: ReactNode;
160
  loopOff?: ReactNode;
161
  volume?: ReactNode;
162
  volumeMute?: ReactNode;
163
}
164

165
type CustomUIModule = RHAP_UI | ReactElement;
166
type CustomUIModules = Array<CustomUIModule>;
167

168
enum RHAP_UI {
169
  CURRENT_TIME = 'CURRENT_TIME',
170
  CURRENT_LEFT_TIME = 'CURRENT_LEFT_TIME',
171
  PROGRESS_BAR = 'PROGRESS_BAR',
172
  DURATION = 'DURATION',
173
  ADDITIONAL_CONTROLS = 'ADDITIONAL_CONTROLS',
174
  MAIN_CONTROLS = 'MAIN_CONTROLS',
175
  VOLUME_CONTROLS = 'VOLUME_CONTROLS',
176
  LOOP = 'LOOP',
177
  VOLUME = 'VOLUME'
178
}
179

180
type MAIN_LAYOUT = 'stacked' | 'stacked-reverse' | 'horizontal' | 'horizontal-reverse';
181
type TIME_FORMAT = 'auto' | 'mm:ss' | 'hh:mm:ss';
182
```
183

184
[UI Customization & Layout](./ui-customization-layout.md)
185

186
### Advanced Features & MSE
187

188
Media Source Extensions (MSE), Encrypted Media Extensions (EME) support, and advanced audio features for streaming and encrypted content.
189

190
```typescript { .api }
191
interface MSEPropsObject {
192
  onSeek: OnSeek;
193
  onEcrypted?: (e: unknown) => void;
194
  srcDuration: number;
195
}
196

197
type OnSeek = (audio: HTMLAudioElement, time: number) => Promise<void>;
198

199
interface I18nAriaLabels {
200
  player?: string;
201
  progressControl?: string;
202
  volumeControl?: string;
203
  play?: string;
204
  pause?: string;
205
  rewind?: string;
206
  forward?: string;
207
  previous?: string;
208
  next?: string;
209
  loop?: string;
210
  loopOff?: string;
211
  volume?: string;
212
  volumeMute?: string;
213
}
214
```
215

216
[Advanced Features & MSE](./advanced-features-mse.md)
217

218
## Types
219

220
```typescript { .api }
221
type AUDIO_PRELOAD_ATTRIBUTE = 'auto' | 'metadata' | 'none';
222
```