npm package: @nebulars/hls-audio-player
Description: A lightweight HLS audio player component for web applications
Latest version: 1.0.0


## 安装方式

### 方式 1：NPM 安装

```bash
npm install hls-audio-player
```

### 方式 2：直接引入 JS 文件

将构建产物复制到项目中：

```bash
# 构建
cd hls-audio-player
npm install
npm run build

# 复制到服务器
cp dist/index.umd.js /var/www/your-project/js/hls-audio-player.umd.js
```

---

## 使用方式

```html
<!DOCTYPE html>
<html>
<head>
    <title>HLS Audio Player Demo</title>
</head>
<body>
    <!-- 播放器容器 -->
    <div id="player"></div>

    <!-- 引入依赖 -->
    <script src="/js/hls.min.js"></script>
    <script src="/js/hls-audio-player.umd.js"></script>

    <script>
        // 获取播放器类
        const PlayerClass = window.HLSAudioPlayer.HLSAudioPlayer || window.HLSAudioPlayer;

        const player = new PlayerClass({
            container: '#player',
            src: 'https://your-server.com/audio/playlist.m3u8',
            autoplay: false,
            controls: true,
            theme: 'light'
        });
    </script>
</body>
</html>
```


## 配置选项

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| container | HTMLElement \| string | 必填 | 容器元素或选择器 |
| src | string | - | HLS 播放列表 URL (.m3u8) |
| autoplay | boolean | false | 是否自动播放 |
| controls | boolean | true | 是否显示控制条 |
| theme | 'light' \| 'dark' | 'light' | 播放器主题 |

---

## 事件回调

```javascript
// 获取播放器类
const PlayerClass = window.HLSAudioPlayer.HLSAudioPlayer || window.HLSAudioPlayer;

const player = new PlayerClass({
    container: '#player',
    src: 'https://your-server.com/audio/playlist.m3u8',

    // 播放器就绪
    onReady: () => {
        console.log('播放器已就绪');
    },

    // 开始播放
    onPlay: () => {
        console.log('开始播放');
    },

    // 暂停播放
    onPause: () => {
        console.log('暂停播放');
    },

    // 播放结束
    onEnded: () => {
        console.log('播放结束');
    },

    // 播放进度更新
    onTimeUpdate: (currentTime, duration) => {
        console.log(`进度: ${currentTime}/${duration} 秒`);
    },

    // 开始加载
    onLoadStart: () => {
        console.log('开始加载');
    },

    // 加载完成
    onLoadEnd: () => {
        console.log('加载完成');
    },

    // 错误处理
    onError: (error) => {
        console.error('播放错误:', error);
    }
});
```

---

## API 方法

### 播放控制

```javascript
// 播放
player.play();

// 暂停
player.pause();

// 切换播放/暂停
player.togglePlay();

// 跳转到指定时间（秒）
player.seek(60);

// 加载新的音频源
player.load('https://your-server.com/new-audio.m3u8');
```

### 音量控制

```javascript
// 设置音量 (0-1)
player.setVolume(0.5);

// 获取当前音量
const volume = player.getVolume();

// 静音
player.mute();

// 取消静音
player.unmute();

// 切换静音状态
player.toggleMute();
```

### 获取状态

```javascript
const state = player.getState();

// state 包含:
// {
//     playing: boolean,      // 是否正在播放
//     currentTime: number,   // 当前播放时间（秒）
//     duration: number,      // 总时长（秒）
//     buffered: number,      // 缓冲进度
//     volume: number,        // 音量 (0-1)
//     muted: boolean,        // 是否静音
//     loading: boolean       // 是否正在加载
// }
```

### 销毁播放器

```javascript
// 销毁播放器，释放资源
player.destroy();
```

---


### 示例

```html
<!DOCTYPE html>
<html>
<head>
    <title>基础播放器</title>
    <style>
        #player {
            width: 400px;
            margin: 50px auto;
        }
    </style>
</head>
<body>
    <div id="player"></div>

    <script src="/js/hls.min.js"></script>
    <script src="/js/hls-audio-player.umd.js"></script>
    <script>
        const PlayerClass = window.HLSAudioPlayer.HLSAudioPlayer || window.HLSAudioPlayer;
        const player = new PlayerClass({
            container: '#player',
            src: 'https://example.com/audio.m3u8',
            theme: 'dark'
        });
    </script>
</body>
</html>
```

---

## 常见问题

### Q: 播放器无法播放？

1. 检查 hls.js 是否正确加载
2. 检查 m3u8 地址是否可访问
3. 检查浏览器控制台是否有 CORS 错误


### Q: 如何自定义样式？

播放器内置了 light 和 dark 两种主题，如需自定义样式，可以通过 CSS 覆盖：

```css
/* 自定义播放器样式 */
.hls-audio-player {
    background: #your-color;
}

.hls-audio-player .play-button {
    color: #your-color;
}
```