PCM Player SDK

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

特性

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

安装

npm install @siliconoid/pcm-player

快速开始

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 文档

new PCMPlayer(options)

• 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 install
2. 启动 Demo: npm run dev
3. 构建 SDK: npm run build

License

ISC