0
# Component Props & Events
1

2
Comprehensive documentation of all props and event handlers available for the H5AudioPlayer component.
3

4
## Required Imports
5

6
```typescript
7
import AudioPlayer from 'react-h5-audio-player';
8
import { ReactNode, CSSProperties } from 'react';
9
```
10

11
## Capabilities
12

13
### Core HTML5 Audio Properties
14

15
Standard HTML5 audio element properties directly supported by the component.
16

17
```typescript { .api }
18
interface CoreAudioProps {
19
  /** HTML5 Audio tag src property */
20
  src?: string;
21
  /** HTML5 Audio tag autoPlay property */
22
  autoPlay?: boolean;
23
  /** HTML5 Audio tag loop property */
24
  loop?: boolean;
25
  /** HTML5 Audio tag muted property */  
26
  muted?: boolean;
27
  /** Volume level from 0 to 1 (won't work on most mobile devices) */
28
  volume?: number;
29
  /** HTML5 Audio tag preload property */
30
  preload?: AUDIO_PRELOAD_ATTRIBUTE;
31
  /** CORS attribute for cross-origin requests */
32
  crossOrigin?: React.AudioHTMLAttributes<HTMLAudioElement>['crossOrigin'];
33
  /** Media group for synchronized playback */
34
  mediaGroup?: string;
35
}
36
```
37

38
### Player Behavior Configuration
39

40
Props that control how the audio player behaves and responds to user interactions.
41

42
```typescript { .api }
43
interface BehaviorProps {
44
  /** Whether to play audio after src prop is changed */
45
  autoPlayAfterSrcChange?: boolean;
46
  /** Enable/disable default keyboard shortcuts */
47
  hasDefaultKeyBindings?: boolean;
48
  /** Time interval in milliseconds to trigger onListen event */
49
  listenInterval?: number;
50
  /** Progress indicator refresh interval in milliseconds */
51
  progressUpdateInterval?: number;
52
  /** Default jump step for rewind/forward in milliseconds */
53
  progressJumpStep?: number;
54
  /** Separate backward/forward jump steps in milliseconds */
55
  progressJumpSteps?: {
56
    backward?: number;
57
    forward?: number;
58
  };
59
  /** Volume increment for up/down arrow keys */
60
  volumeJumpStep?: number;
61
}
62
```
63

64
**Default Values:**
65
- `progressJumpStep`: 5000 (5 seconds)
66
- `progressJumpSteps`: `{ backward: 5000, forward: 5000 }`
67
- `hasDefaultKeyBindings`: true
68
- `progressUpdateInterval`: 20ms
69
- `listenInterval`: 1000ms
70

71
### UI Display Configuration
72

73
Props controlling the visual appearance and layout of the player interface.
74

75
```typescript { .api }
76
interface UIDisplayProps {
77
  /** Custom CSS classes */
78
  className?: string;
79
  /** Inline CSS styles */
80
  style?: CSSProperties;
81
  /** Layout orientation */
82
  layout?: MAIN_LAYOUT;
83
  /** Show rewind/forward buttons */
84
  showJumpControls?: boolean;
85
  /** Show previous/next buttons */
86
  showSkipControls?: boolean;
87
  /** Show download progress indicator */
88
  showDownloadProgress?: boolean;
89
  /** Show filled progress indicator */
90
  showFilledProgress?: boolean;
91
  /** Show filled volume indicator */
92
  showFilledVolume?: boolean;
93
  /** Time display format */
94
  timeFormat?: TIME_FORMAT;
95
}
96
```
97

98
**Default Values:**
99
- `layout`: 'stacked'
100
- `showJumpControls`: true
101
- `showSkipControls`: false
102
- `showDownloadProgress`: true
103
- `showFilledProgress`: true
104
- `showFilledVolume`: false
105
- `timeFormat`: 'auto'
106

107
### Custom Content Props
108

109
Props for adding custom content and default display values.
110

111
```typescript { .api }
112
interface CustomContentProps {
113
  /** Custom header content above the player */
114
  header?: ReactNode;
115
  /** Custom footer content below the player */
116
  footer?: ReactNode;
117
  /** Default current time display when audio not loaded */
118
  defaultCurrentTime?: ReactNode;
119
  /** Default duration display when audio not loaded */
120
  defaultDuration?: ReactNode;
121
  /** Child elements (e.g., <track> elements for captions) */
122
  children?: ReactNode;
123
}
124
```
125

126
### HTML5 Audio Event Handlers
127

128
Standard HTML5 audio events with optional callback handlers.
129

130
```typescript { .api }
131
interface HTML5AudioEvents {
132
  /** Fired when playback is aborted */
133
  onAbort?: (e: Event) => void;
134
  /** Fired when enough data is available to start playing */
135
  onCanPlay?: (e: Event) => void;
136
  /** Fired when enough data is available to play through without buffering */
137
  onCanPlayThrough?: (e: Event) => void;
138
  /** Fired when playback reaches the end */
139
  onEnded?: (e: Event) => void;
140
  /** Fired when playback starts after being paused or delayed */
141
  onPlaying?: (e: Event) => void;
142
  /** Fired when a seek operation begins */
143
  onSeeking?: (e: Event) => void;
144
  /** Fired when a seek operation completes */
145
  onSeeked?: (e: Event) => void;
146
  /** Fired when data loading is stalled */
147
  onStalled?: (e: Event) => void;
148
  /** Fired when data loading is suspended */
149
  onSuspend?: (e: Event) => void;
150
  /** Fired when loading begins */
151
  onLoadStart?: (e: Event) => void;
152
  /** Fired when metadata has finished loading */
153
  onLoadedMetaData?: (e: Event) => void;
154
  /** Fired when the first frame has finished loading */
155
  onLoadedData?: (e: Event) => void;
156
  /** Fired when playback is waiting for more data */
157
  onWaiting?: (e: Event) => void;
158
  /** Fired when the media element is reset to its initial state */
159
  onEmptied?: (e: Event) => void;
160
  /** Fired when an error occurs during loading or playback */
161
  onError?: (e: Event) => void;
162
  /** Fired during playback at intervals specified by listenInterval */
163
  onListen?: (e: Event) => void;
164
  /** Fired when volume changes */
165
  onVolumeChange?: (e: Event) => void;
166
  /** Fired when playback is paused */
167
  onPause?: (e: Event) => void;
168
  /** Fired when playback starts */
169
  onPlay?: (e: Event) => void;
170
}
171
```
172

173
### Custom Control Event Handlers
174

175
Event handlers for custom player controls and interactions.
176

177
```typescript { .api }
178
interface CustomControlEvents {
179
  /** Called when previous button is clicked */
180
  onClickPrevious?: (e: React.SyntheticEvent) => void;
181
  /** Called when next button is clicked */
182
  onClickNext?: (e: React.SyntheticEvent) => void;
183
  /** Called when play() promise is rejected */
184
  onPlayError?: (err: Error) => void;
185
  /** Called when currentTime change fails */
186
  onChangeCurrentTimeError?: (err: Error) => void;
187
}
188
```
189

190
### Complete PlayerProps Interface
191

192
The complete interface combining all prop categories:
193

194
```typescript { .api }
195
interface PlayerProps extends 
196
  CoreAudioProps,
197
  BehaviorProps, 
198
  UIDisplayProps,
199
  CustomContentProps,
200
  HTML5AudioEvents,
201
  CustomControlEvents {
202
  
203
  // UI Customization (see UI Customization & Layout doc)
204
  customIcons?: CustomIcons;
205
  customProgressBarSection?: CustomUIModules;
206
  customControlsSection?: CustomUIModules;
207
  customAdditionalControls?: CustomUIModules;
208
  customVolumeControls?: CustomUIModules;
209
  i18nAriaLabels?: I18nAriaLabels;
210
  
211
  // Advanced Features (see Advanced Features & MSE doc)
212
  mse?: MSEPropsObject;
213
}
214
```
215

216
## Default Keyboard Shortcuts
217

218
When `hasDefaultKeyBindings` is true (default), these keyboard shortcuts are available:
219

220
| Key | Action |
221
|-----|--------|
222
| Space | Play/Pause (when player or progress bar is focused) |
223
| ← (Left Arrow) | Rewind by progressJumpStep |
224
| → (Right Arrow) | Forward by progressJumpStep |
225
| ↑ (Up Arrow) | Increase volume by volumeJumpStep |
226
| ↓ (Down Arrow) | Decrease volume by volumeJumpStep |
227
| L | Toggle loop mode |
228
| M | Toggle mute |
229
230
## Usage Examples
231

232
**Basic Configuration:**
233

234
```typescript
235
<AudioPlayer
236
  src="audio.mp3"
237
  autoPlay={false}
238
  loop={false}
239
  volume={0.8}
240
  onPlay={e => console.log('Started playing')}
241
  onPause={e => console.log('Paused')}
242
  onEnded={e => console.log('Finished playing')}
243
/>
244
```
245

246
**Advanced Event Handling:**
247

248
```typescript
249
<AudioPlayer
250
  src="podcast.mp3"
251
  listenInterval={500}
252
  onListen={e => {
253
    const audio = e.target as HTMLAudioElement;
254
    console.log('Current time:', audio.currentTime);
255
    // Update progress, save position, etc.
256
  }}
257
  onLoadedMetaData={e => {
258
    const audio = e.target as HTMLAudioElement;
259
    console.log('Duration:', audio.duration);
260
  }}
261
  onError={e => {
262
    console.error('Audio error:', e);
263
    // Handle error, show message, etc.
264
  }}
265
/>
266
```
267

268
**Custom Controls Integration:**
269

270
```typescript
271
const [currentTrack, setCurrentTrack] = useState(0);
272
const playlist = ['song1.mp3', 'song2.mp3', 'song3.mp3'];
273

274
<AudioPlayer
275
  src={playlist[currentTrack]}
276
  showSkipControls={true}
277
  onClickPrevious={() => {
278
    setCurrentTrack(prev => Math.max(0, prev - 1));
279
  }}
280
  onClickNext={() => {
281
    setCurrentTrack(prev => Math.min(playlist.length - 1, prev + 1));
282
  }}
283
  onEnded={() => {
284
    // Auto-advance to next track
285
    if (currentTrack < playlist.length - 1) {
286
      setCurrentTrack(prev => prev + 1);
287
    }
288
  }}
289
/>
290
```