A PCM Web Audio API based TTS player SDK
npm install @siliconoid/pcm-player一个基于 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()
`
- numberOfChannels (number, optional): 声道数,默认 1。dataEmptyTriggerThreshold
- (number, optional): 触发 dataempty 事件的剩余播放时间阈值(毫秒),默认 6000ms。debug
- (boolean, optional): 是否开启控制台调试日志,默认 false。
- 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()
- : 销毁播放器,释放资源。
- bgMusic (string): 设置背景音乐 URL。bgVolume
- (number): 设置背景音乐音量 (0.0 - 1.0)。
| 事件名 | 描述 |
| ------------ | -------------------------------------------- |
| play | 开始播放时触发(调用 play 方法时) |playing
| | 实际开始播放声音时触发 |pause
| | 暂停播放时触发 |waiting
| | 缓冲区数据不足,进入等待状态时触发 |ended
| | 所有音频数据播放完毕时触发 |dataempty
| | 缓冲区数据低于阈值时触发,提示加载更多数据 |empty
| | 缓冲区完全变空时触发 |timeupdate
| | 播放进度更新,回调参数:(playedTime, extend) |error
| | 发生错误时触发,回调参数为 Error 对象 (any) |
1. 安装依赖: npm installnpm run dev
2. 启动 Demo: npm run build`
3. 构建 SDK:
ISC