🎧 AudioStreamPlayer

一个专为 AI 实时交互场景 打造的高性能音频流播放器。

它基于浏览器原生 Media Source Extensions (MSE) 构建，旨在解决传统 <audio> 标签在播放实时生成的音频流（如 LLM 语音回复、实时翻译）时存在的延迟高、卡顿或无法无缝拼接片段的问题。

文档： https://agentsflex.com/zh/audio/audio-stream-player.html

✨ 为什么需要它？

在 AI 语音对话场景中，音频通常是 分块（Chunk） 实时生成的。传统的播放方式往往面临以下痛点：

• 延迟高：需要等待整个文件生成完毕才能播放。
• 卡顿/断连多：多个音频片段拼接时会出现明显的静音间隙。
• 内存泄漏风险：长时间运行可能导致浏览器内存堆积。

AudioStreamPlayer 通过 流式缓冲机制 和 智能状态管理，实现了：

1. 极低首帧延迟：只需缓冲少量数据即可开始播放。
2. 无缝拼接：内部使用环形缓冲区平滑处理音频数据流。
3. 内存安全：自动管理缓冲上限，防止长时间运行导致页面崩溃。
4. 状态可控：提供清晰的播放状态（Buffering, Playing, Paused 等），方便 UI 同步。

📦 安装

通过 npm 或 yarn 安装：

npm install @agents-flex/audio-stream-player

或者使用 yarn：

yarn add @agents-flex/audio-stream-player

🚀 快速开始

1. 导入模块

支持 ES Module 和 CommonJS 引入：

// ES Module (推荐，适用于 Vite/Webpack/Rollup)
import { AudioStreamPlayer } from '@agents-flex/audio-stream-player';

// CommonJS (适用于 Node.js 环境或旧版打包工具)
const { AudioStreamPlayer } = require('@agents-flex/audio-stream-player');

2. 初始化

const player = new AudioStreamPlayer({
  // 可选：指定音频格式，默认为 'audio/mpeg' （ MP3 格式）
  mimeType: 'audio/mpeg', 
  
  // 可选：最小缓冲时间(ms)，达到此阈值后自动开始播放
  minBufferMs: 300, 
  
  // 可选：最大缓冲时间(ms)，防止内存溢出，默认 5000ms
  maxBufferMs: 5000,

  // 状态变化回调
  onStateChange: (state) => {
    console.log('Current State:', state); 
    // 'idle' | 'buffering' | 'playing' | 'paused' | 'ended' | 'error'
  },

  onError: (err) => {
    console.error('Playback error:', err);
  }
});

3. 打开播放器

在使用前必须先调用 open()，这会初始化媒体源。

await player.open();

4. 喂入音频数据

当你的 AI 服务返回音频二进制数据（Uint8Array 或 ArrayBuffer）时，直接调用 feed`。

// 假设这是从 WebSocket 或 Fetch Stream 接收到的数据
function onAudioChunkReceived(data: Uint8Array) {
  player.feed(data);
}

注意：一旦缓冲达到 minBufferMs，播放器会自动开始播放（除非被手动暂停）。

5. 控制播放

// 手动暂停（数据会继续接收并缓冲，但不会播放）
player.pause();

// 恢复播放
await player.resume();

// 结束流（当 AI 回复完全结束时调用）
player.close();

6. 销毁实例

当组件卸载或不再需要播放器时，务必调用 destroy 以释放内存和 URL 对象。

player.destroy();

📊 状态机说明

播放器维护一个明确的状态生命周期，你可以通过 onStateChange 监听这些状态来更新 UI（例如显示“正在思考...”、“正在说话”、“暂停”等图标）。

状态	说明
idle	初始状态，未打开或未开始接收数据
buffering	正在接收数据，但尚未达到最小缓冲阈值，或网络波动导致缓冲不足
playing	正在正常播放音频
paused	用户主动暂停，音频停止输出，但后台仍在接收和缓冲数据
ended	调用了 close() 且所有缓冲数据已播放完毕
error	发生解码错误或网络错误

⚙️ 配置选项详解

参数	类型	默认值	说明
mimeType	string	自动检测	音频 MIME 类型。推荐 AAC (audio/mp4) 或 Opus (audio/webm)。
autoplay	boolean	true	是否允许达到缓冲阈值后自动播放。
minBufferMs	number	300	启动播放所需的最小缓冲时长（毫秒）。越小延迟越低，但越容易卡顿。
maxBufferMs	number	5000	最大缓冲时长。超过此值将丢弃旧数据，防止内存无限增长。
audioElement	HTMLAudioElement	新建	你可以传入现有的 <audio> 标签以便自定义样式或挂载事件。
onStateChange	Function	-	状态变更回调。
onError	Function	-	错误捕获回调。

📄 License

MIT