0
# xgplayer-hls.js
1

2
xgplayer-hls.js is a plugin that integrates hls.js into the xgplayer video player framework, enabling HTTP Live Streaming (HLS) video playback capabilities. It provides a seamless integration layer between the popular hls.js library and xgplayer's plugin architecture.
3

4
## Package Information
5

6
- **Package Name**: xgplayer-hls.js
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install xgplayer-hls.js xgplayer`
10

11
## Core Imports
12

13
```javascript
14
import HlsJsPlugin from 'xgplayer-hls.js';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const HlsJsPlugin = require('xgplayer-hls.js');
21
```
22

23
For CDN/UMD:
24

25
```javascript
26
// Available as window.HlsJsPlugin
27
```
28

29
## Basic Usage
30

31
```javascript
32
import Player from 'xgplayer';
33
import 'xgplayer/dist/xgplayer.min.css';
34
import HlsJsPlugin from 'xgplayer-hls.js';
35

36
const player = new Player({
37
  id: 'video-container',
38
  url: 'https://example.com/video.m3u8',
39
  plugins: [HlsJsPlugin],
40
  hlsJsPlugin: {
41
    hlsOpts: {
42
      // hls.js configuration options
43
      startPosition: 0,
44
      maxBufferLength: 30,
45
      maxMaxBufferLength: 600
46
    }
47
  }
48
});
49
```
50

51
## Architecture
52

53
The plugin follows xgplayer's standard plugin architecture pattern:
54

55
- **Plugin Class**: `HlsJsPlugin` extends `BasePlugin` from xgplayer
56
- **HLS Integration**: Uses hls.js library for HLS stream processing
57
- **Event System**: Bridges hls.js events to xgplayer's event system
58
- **Error Handling**: Automatic recovery for network and media errors
59
- **Statistics**: Real-time playback statistics and media information
60

61
## Capabilities
62

63
### Plugin Class
64

65
The main plugin class that integrates hls.js with xgplayer.
66

67
```javascript { .api }
68
class HlsJsPlugin extends BasePlugin {
69
  constructor(args);
70
  static get pluginName(): string;
71
  static get defaultConfig(): HlsPluginConfig;
72
  static get isSupported(): boolean;
73
  afterCreate(): void;
74
  beforePlayerInit(): void;
75
  destroy(): void;
76
  register(url: string): void;
77
}
78
```
79

80
### Static Properties
81

82
Plugin metadata and configuration.
83

84
```javascript { .api }
85
/**
86
 * Plugin name identifier
87
 */
88
static get pluginName(): string; // Returns 'HlsJsPlugin'
89

90
/**
91
 * Default plugin configuration
92
 */
93
static get defaultConfig(): HlsPluginConfig;
94

95
/**
96
 * Browser HLS support check via hls.js
97
 */
98
static get isSupported(): boolean;
99
```
100

101
### Constructor
102

103
Creates new plugin instance and initializes internal properties.
104

105
```javascript { .api }
106
/**
107
 * Creates a new HlsJsPlugin instance
108
 * @param {object} args - Plugin configuration from xgplayer
109
 */
110
constructor(args);
111
```
112

113
**Internal Properties:**
114
- `this.browser` - Browser version string from getBrowserVersion()
115
- `this.hls` - hls.js instance (null until initialized)
116
- `this.hlsOpts` - Processed hls.js configuration options
117

118
### Lifecycle Methods
119

120
Plugin lifecycle management methods called by xgplayer.
121

122
```javascript { .api }
123
/**
124
 * Called after plugin creation - sets up URL change handling and player properties
125
 * Sets up URL_CHANGE event listener to automatically re-register new HLS sources
126
 */
127
afterCreate(): void;
128

129
/**
130
 * Called before player initialization - registers initial HLS source
131
 */
132
beforePlayerInit(): void;
133

134
/**
135
 * Cleanup method - destroys hls.js instance and restores player state
136
 */
137
destroy(): void;
138
```
139

140
### HLS Source Management
141

142
Methods for managing HLS sources and automatic URL change handling.
143

144
```javascript { .api }
145
/**
146
 * Registers HLS source with the player
147
 * Creates new hls.js instance, attaches to media element, and loads the source
148
 * @param {string} url - HLS manifest URL (.m3u8)
149
 */
150
register(url: string): void;
151
```
152

153
**Automatic URL Change Handling:**
154
The plugin automatically listens for `URL_CHANGE` events from xgplayer and calls `register()` with the new URL, enabling seamless source switching during playback.
155

156
### Configuration Options
157

158
Plugin configuration through xgplayer's `hlsJsPlugin` option.
159

160
```javascript { .api }
161
interface HlsPluginConfig {
162
  /** Configuration options passed directly to hls.js */
163
  hlsOpts?: HlsConfig;
164
}
165

166
interface HlsConfig {
167
  /** Start position in seconds */
168
  startPosition?: number;
169
  /** Maximum buffer length in seconds */
170
  maxBufferLength?: number;
171
  /** Maximum buffer size limit */
172
  maxMaxBufferLength?: number;
173
  /** Enable/disable debug logging */
174
  debug?: boolean;
175
  /** Fragment loading timeout */
176
  fragLoadingTimeOut?: number;
177
  /** Manifest loading timeout */
178
  manifestLoadingTimeOut?: number;
179
  /** Additional hls.js configuration options */
180
  [key: string]: any;
181
}
182
```
183

184
### Events
185

186
Events emitted by the plugin through xgplayer's event system.
187

188
```javascript { .api }
189
/**
190
 * HLS-specific error event with detailed error information
191
 * @event HLS_ERROR
192
 * @type {object}
193
 * @property {string} errorType - Error type from hls.js (NETWORK_ERROR, MEDIA_ERROR, etc.)
194
 * @property {string} errorDetails - Specific error details from hls.js
195
 * @property {boolean} errorFatal - Whether the error is fatal and requires recovery
196
 */
197

198
/**
199
 * Generic error event for fatal errors that cannot be recovered
200
 * @event error
201
 * @type {object}
202
 * @property {string} type - Error type from hls.js
203
 * @property {string} details - Error details from hls.js
204
 * @property {boolean} fatal - Always true for this event
205
 */
206

207
/**
208
 * Media information event with stream metadata
209
 * @event media_info
210
 * @type {MediaInfo}
211
 */
212

213
/**
214
 * Statistics information event (emitted every second during playback)
215
 * @event statistics_info
216
 * @type {StatsInfo}
217
 */
218
```
219

220
### Event Data Types
221

222
Data structures for events emitted by the plugin.
223

224
```javascript { .api }
225
interface MediaInfo {
226
  /** Video data rate in kbps */
227
  videoDataRate: number;
228
  /** Audio data rate in kbps */
229
  audioDataRate: number;
230
  /** Frames per second */
231
  fps?: number;
232
  /** Whether stream has audio track */
233
  hasAudio: boolean;
234
  /** Whether stream has video track */
235
  hasVideo: boolean;
236
  /** Audio channel count */
237
  audioChannelCount: number;
238
  /** Audio codec information */
239
  audioCodec: string;
240
  /** Video codec information */
241
  videoCodec: string;
242
  /** Video width in pixels */  
243
  width: number;
244
  /** Video height in pixels */
245
  height: number;
246
  /** Stream duration */
247
  duration: number;
248
  /** HLS quality level */
249
  level: number;
250
  /** MIME type with codecs */
251
  mimeType: string;
252
}
253

254
interface StatsInfo {
255
  /** Current download speed in KB/s */
256
  speed: number;
257
  /** Player type identifier */
258
  playerType: string; // Always 'HlsPlayer'
259
}
260
```
261

262
### Utilities
263

264
Internal utility functions used by the plugin.
265

266
```javascript { .api }
267
/**
268
 * Browser version detection utility
269
 * @returns {string} Browser name and version (e.g., "Chrome 95", "Firefox 94", "Unknown")
270
 */
271
function getBrowserVersion(): string;
272
```
273

274
### Browser Support
275

276
The plugin requires HLS support via hls.js (checked via `HlsJsPlugin.isSupported`). Browser detection is handled internally for statistics purposes using the `getBrowserVersion()` utility.
277

278
### Error Handling
279

280
The plugin automatically handles common HLS errors:
281

282
- **Network Errors**: Attempts to restart loading (except for 404 errors)
283
- **Media Errors**: Attempts media error recovery via hls.js
284
- **Fatal Errors**: Emits error event to xgplayer
285

286
### Dependencies
287

288
Required peer and direct dependencies:
289

290
```javascript { .api }
291
// Peer dependencies (must be installed separately)
292
"xgplayer": ">=3.0.13"
293
"core-js": ">=3.12.1"
294

295
// Direct dependencies (installed automatically)
296
"hls.js": "^1.5.6"
297
"deepmerge": "2.0.1" 
298
"event-emitter": "^0.3.5"
299
```
300

301
## Types
302

303
### Configuration Types
304

305
```javascript { .api }
306
interface HlsPluginConfig {
307
  hlsOpts?: HlsConfig;
308
}
309

310
interface HlsConfig {
311
  startPosition?: number;
312
  maxBufferLength?: number;
313
  maxMaxBufferLength?: number;
314
  debug?: boolean;
315
  fragLoadingTimeOut?: number;
316
  manifestLoadingTimeOut?: number;
317
  [key: string]: any;
318
}
319
```
320

321
### Event Data Types
322

323
```javascript { .api }
324
interface MediaInfo {
325
  videoDataRate: number;
326
  audioDataRate: number;
327
  fps?: number;
328
  hasAudio: boolean;
329
  hasVideo: boolean;
330
  audioChannelCount: number;
331
  audioCodec: string;
332
  videoCodec: string;
333
  width: number;
334
  height: number;
335
  duration: number;
336
  level: number;
337
  mimeType: string;
338
}
339

340
interface StatsInfo {
341
  speed: number;
342
  playerType: string;
343
}
344
```