PCM Player SDK

一个基于 Web Audio API 的高性能音频流（PCM）播放器 SDK，支持流式音频播放、断点续播、背景音乐混音等特性。

特性

- 🚀 流式播放：支持边下边播，并在网络卡顿时自动缓冲。
- ⏯️ 断点续播：支持暂停/继续，且能精确恢复播放进度。
- 🎵 背景音乐：支持混入背景音乐，并自动处理音量闪避。
- 🛠️ 稳健容错：内置转码 Worker，避免主线程卡顿；自动处理音频格式兼容性。
- 📝 完整日志：提供规范化的内部状态日志，便于调试。
- 🛡️ 优雅的错误处理：支持将异步获取数据时的错误注入到播放流中，确保错误在正确的时机抛出，不打断已有音频的播放。

安装

``bash
npm install @siliconoid/pcm-player
`

快速开始

`typescript
import PCMPlayer from '@siliconoid/pcm-player'

// 1. 初始化播放器
const player = new PCMPlayer({
numberOfChannels: 1, // 声道数
dataEmptyTriggerThreshold: 6000, // 缓冲区低于 6s 时触发 dataempty 事件
debug: true, // 开启调试日志
})

// 2. 监听关键事件
player.on('play', () => console.log('开始播放'))
player.on('pause', () => console.log('暂停播放'))
player.on('ended', () => console.log('全部播放结束'))
player.on('error', (err) => console.error('播放出错', err))

// 3. 数据驱动播放
// 监听 dataempty 事件，当缓冲区不足时请求新数据
player.on('dataempty', async () => {
try {
const pcmData = await fetchNextAudioChunk()
if (pcmData) {
player.appendData(pcmData, {
sampleRate: 24000,
endFrame: false, // 如果是最后一段，设为 true
})
}
} catch (error) {
// 异步获取数据失败时，将错误注入到播放队列
// 播放器会播完当前缓冲区内容，再触发 error 事件并停止
player.appendError(error)
}
})

// 4. 控制播放
player.play()
`

API 文档

$3

- numberOfChannels (number, optional): 声道数，默认 1。
- dataEmptyTriggerThreshold (number, optional): 触发 dataempty 事件的剩余播放时间阈值（毫秒），默认 6000ms。
- debug (boolean, optional): 是否开启控制台调试日志，默认 false。

$3

- play(): 开始或恢复播放。
- pause(): 暂停播放（支持断点续播）。
- appendData(pcmData, info): 追加 PCM 音频数据。
- pcmData: ArrayBuffer 或 Base64 字符串。
- info.sampleRate: 采样率。
- info.endFrame: 是否为最后一段数据（设置为 true 会在播放完后触发 ended 事件）。
- info.byteOffset: (number, optional) 数据偏移量。
- info.littleEndian: (boolean, optional) 是否为小端序。
- info.extend: (object, optional) 自定义扩展数据，将在 timeupdate 事件中返回。
- appendError(error): 注入一个错误到播放队列。用于处理异步数据获取失败的场景，确保错误在音频流的对应位置精确抛出。
- dispose(): 销毁播放器，释放资源。

$3

- bgMusic (string): 设置背景音乐 URL。
- bgVolume (number): 设置背景音乐音量 (0.0 - 1.0)。

$3

| 事件名 | 描述 |
| ------------ | -------------------------------------------- |
| play | 开始播放时触发（调用 play 方法时） |
| playing | 实际开始播放声音时触发 |
| pause | 暂停播放时触发 |
| waiting | 缓冲区数据不足，进入等待状态时触发 |
| ended | 所有音频数据播放完毕时触发 |
| dataempty | 缓冲区数据低于阈值时触发，提示加载更多数据 |
| empty | 缓冲区完全变空时触发 |
| timeupdate | 播放进度更新，回调参数：(playedTime, extend) |
| error | 发生错误时触发，回调参数为 Error 对象 (any) |

开发

1. 安装依赖: npm install
2. 启动 Demo: npm run dev
3. 构建 SDK: npm run build`

License

ISC