🎧 AudioStreamPlayer

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

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

✨ 为什么需要它？

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

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

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

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

🚀 快速开始

1. 初始化

import { AudioStreamPlayer } from './AudioStreamPlayer';

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);
  }
});

2. 打开播放器

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

await player.open();

3. 喂入音频数据

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

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

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

4. 控制播放

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

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

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

5. 销毁实例

当组件卸载或不再需要播放器时，务必调用 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