PCM 流式音频播放

PCM 音频播放器技术方案

一、核心思想

本方案实现了一个高效的流式音频播放系统，用于实时播放 PCM 格式的音频数据。主要核心思想包括：

1. 全局共享 AudioContext：使用单一 AudioContext 实例管理所有音频播放，避免超出浏览器限制（通常为 6 个），同时减少内存和 CPU 开销。

2. 多格式支持：自动识别并转换多种 PCM 数据格式（ArrayBuffer、Int16Array、Float32Array），提供灵活的输入接口。

3. 无缝连续播放：通过精确维护音频片段的播放时间点，确保流式接收的音频数据可以连续播放无间隙。

4. 高性能播放：利用 Web Audio API 的原生能力，实现低延迟、高保真的音频播放。

二、技术架构

2.1 架构概览

PCM 数据输入（多种格式）→ 格式转换（Int16/二进制 → Float32）→ AudioBuffer → 音频源节点 → 输出设备
                                        ↓
                                  归一化处理
                                        ↓
                              -32768~32767 → -1.0~1.0

2.2 关键技术点

技术点	说明
AudioContext	全局共享，管理音频处理图和输出
AudioBuffer	Web Audio API 的音频数据容器，使用 Float32 格式
AudioBufferSourceNode	音频源节点，负责播放 AudioBuffer
格式转换	Int16/二进制 → Float32 归一化处理
时间管理	维护 nextStartTime 确保连续播放

2.3 数据流转

1. 接收数据：接收 PCM 数据，支持 ArrayBuffer、Int16Array、Float32Array 格式
2. 格式转换：统一转换为 Float32Array 格式（Web Audio API 标准）
3. 创建缓冲区：创建 AudioBuffer 并填充转换后的数据
4. 调度播放：根据当前时间和上一个片段的结束时间，安排当前片段的播放时间
5. 更新时间：记录下一个音频片段的预计开始时间

2.4 全局共享架构

AudioContext（全局共享）
    │
    ├── AudioBufferSourceNode 1 ── 播放片段 1
    ├── AudioBufferSourceNode 2 ── 播放片段 2
    ├── AudioBufferSourceNode 3 ── 播放片段 3
    └── ...

三、技术细节

3.1 音频格式

格式类型	输入范围	内部处理范围	说明
Int16Array	-32768 ~ 32767	-1.0 ~ 1.0	标准 16 位 PCM
ArrayBuffer	-32768 ~ 32767	-1.0 ~ 1.0	二进制数据
Float32Array	-1.0 ~ 1.0	-1.0 ~ 1.0	已归一化数据

3.2 格式转换算法

Int16 到 Float32 归一化公式：

// 归一化处理：将 Int16 范围映射到 Float32 范围
float32Value = int16Value / 32768;

3.3 播放时间管理

为了保证连续播放无间隙，播放器维护 nextStartTime 变量：

// 计算当前片段的播放开始时间
const currentTime = globalAudioContext.currentTime;
const startTime = Math.max(currentTime, this.nextStartTime);

// 更新下一个片段的开始时间
this.nextStartTime = startTime + audioBuffer.duration;

逻辑说明：

• 如果 nextStartTime 大于当前时间，说明还有未播放的片段，使用 nextStartTime
• 如果 nextStartTime 小于等于当前时间，说明之前的播放已经结束或超时，从当前时间开始播放
• 确保音频片段按接收顺序连续播放

3.4 AudioContext 配置

配置项	说明
实例化方式	全局单例模式
默认采样率	跟随系统默认（通常 48000 Hz）
最大实例限制	浏览器通常限制为 6 个
线程模型	主线程调度，音频线程处理

3.5 播放器配置

配置项	默认值	说明
采样率	24000 Hz	音频数据的采样率，需与数据源一致
声道数	1（单声道）	播放配置为单声道

四、代码实现

4.1 全局 AudioContext 定义

/**
 * 全局共享的音频上下文
 * @remarks
 * 浏览器对 AudioContext 数量有限制，共用单个实例可以：
 * - 避免超出浏览器限制（通常为 6 个）
 * - 减少内存和 CPU 开销
 * - 避免多个音频上下文之间的冲突
 */
export const globalAudioContext = new AudioContext();

4.2 PCM 流式播放器类

/**
 * PCM 流式音频播放器
 * @remarks
 * 用于播放流式返回的 PCM 音频数据（Float32Array 格式），支持连续播放多个音频片段
 * 使用 Web Audio API 实现低延迟的实时音频播放
 * - 音频格式：Float32Array（范围 -1.0 到 1.0）
 * - 声道：单声道
 * - 播放模式：流式连续播放
 * - 共用全局 AudioContext，避免资源浪费
 */
export class PCMStreamPlayer {
  /**
   * 采样率，每秒采样次数，常见值：16000, 24000, 48000
   */
  sampleRate = 24000;
  /**
   * 下一个音频片段的开始时间，用于维护连续播放
   */
  private nextStartTime = 0;

  /**
   * 将 Int16Array 转换为 Float32Array
   * @param int16Data - Int16Array 格式的 PCM 数据
   * @returns Float32Array 格式的音频数据，范围为 -1.0 到 1.0
   * @remarks
   * 归一化处理：-32768~32767 -> -1.0~1.0
   */
  static int16ToPCMFloat32(int16Data: Int16Array): Float32Array {
    const length = int16Data.length;
    const float32Array = new Float32Array(length);
    for (let i = 0; i < length; i++) float32Data[i]! / 32768;
    return float32Array;
  }

  /**
   * 将 PCM Int16 二进制数据转换为 Float32Array
   * @param buffer - PCM 音频数据的 ArrayBuffer（Int16 格式）
   * @returns Float32Array 格式的音频数据，范围为 -1.0 到 1.0
   * @remarks
   * 将二进制数据转换为 Int16Array，再归一化为 Float32Array（-32768~32767 -> -1.0~1.0）
   */
  static binaryToPCMFloat32(buffer: ArrayBuffer): Float32Array {
    return PCMStreamPlayer.int16ToPCMFloat32(new Int16Array(buffer));
  }

  static toPCMFloat32(buffer: unknown): Float32Array {
    if (buffer instanceof ArrayBuffer) return PCMStreamPlayer.binaryToPCMFloat32(buffer);
    if (buffer instanceof Int16Array) return PCMStreamPlayer.int16ToPCMFloat32(buffer);
    if (buffer instanceof Float32Array) return buffer;
    throw new TypeError("Invalid PCM data format");
  }

  /**
   * 播放 PCM 数据片段
   * @param pcmData - PCM 音频数据，支持以下格式：
   *   - ArrayBuffer: Int16 格式的二进制数据
   *   - Int16Array: Int16 格式的音频数据
   *   - Float32Array: 归一化后的音频数据，范围为 -1.0 到 1.0
   * @remarks
   * 自动维护播放队列，确保音频片段连续播放无间隙
   * Web Audio API 内部使用 Float32 格式处理音频，AudioBuffer 只接受 Float32Array
   */
  play(pcmData: unknown) {
    // 统一转换为 Float32Array
    const float32Data = PCMStreamPlayer.toPCMFloat32(pcmData);
    // 创建 AudioBuffer（单声道）
    const audioBuffer = globalAudioContext.createBuffer(1, float32Data.length, this.sampleRate);
    // 填充音频数据
    const channelData = audioBuffer.getChannelData(0);
    for (let i = 0; i < channelData.length; i++) channelData[i] = float32Data[i]!;
    // 创建音频源节点
    const source = globalAudioContext.createBufferSource();
    source.buffer = audioBuffer;
    source.connect(globalAudioContext.destination);
    // 计算播放时间，确保连续播放
    const currentTime = globalAudioContext.currentTime;
    const startTime = Math.max(currentTime, this.nextStartTime);
    source.start(startTime);
    // 更新下一个音频片段的开始时间
    this.nextStartTime = startTime + audioBuffer.duration;
  }
}

五、使用示例

5.1 基本使用

// 创建播放器实例
const player = new PCMStreamPlayer();

// 播放 Float32Array 格式的音频数据
const float32Data = new Float32Array([0.5, -0.3, 0.8, ...]);
player.play(float32Data);

// 播放 Int16Array 格式的音频数据
const int16Data = new Int16Array([16384, -9830, 26214, ...]);
player.play(int16Data);

// 播放 ArrayBuffer 格式的音频数据
const arrayBuffer = new Int16Array([16384, -9830, 26214, ...]).buffer;
player.play(arrayBuffer);

5.2 流式播放（连续接收音频数据）

class AudioStreamer {
  private player = new PCMStreamPlayer();
  private ws: WebSocket;

  constructor(wsUrl: string) {
    this.ws = new WebSocket(wsUrl);

    this.ws.binaryType = "arraybuffer";

    this.ws.addEventListener("message", (event: MessageEvent<ArrayBuffer>) => {
      // 直接播放从服务器接收的音频数据
      this.player.play(event.data);
    });
  }

  close() {
    this.ws.close();
  }
}

// 使用
const streamer = new AudioStreamer("wss://example.com/audio-stream");

5.3 与录制器配合使用

// 创建播放器（采样率需与录制器一致）
const player = new PCMStreamPlayer(24000);
const recorder = new PCMStreamRecorder(24000);

// 将录制的数据直接播放
recorder.addEventListener("message", (event: MessageEvent<ArrayBuffer>) => {
  player.play(event.data);
});

await recorder.start();

5.4 播放带有缓冲延迟的音频

class DelayedPlayer extends PCMStreamPlayer {
  private bufferQueue: Float32Array[] = [];
  private playDelay = 0; // 延迟时间（秒）

  setDelay(delay: number) {
    this.playDelay = delay;
  }

  playWithDelay(pcmData: unknown) {
    const float32Data = PCMStreamPlayer.toPCMFloat32(pcmData);
    this.bufferQueue.push(float32Data);

    // 延迟播放
    setTimeout(() => {
      if (this.bufferQueue.length > 0) {
        const data = this.bufferQueue.shift();
        if (data) {
          this.play(data);
        }
      }
    }, this.playDelay * 1000);
  }
}

5.5 批量播放多个片段

class BatchPlayer extends PCMStreamPlayer {
  /**
   * 批量播放多个音频片段
   * @param segments 音频片段数组
   * @param delay 片段之间的延迟时间（秒）
   */
  playBatch(segments: Array<Float32Array | Int16Array | ArrayBuffer>, delay = 0) {
    segments.forEach((segment, index) => {
      if (delay > 0 && index > 0) {
        setTimeout(
          () => {
            this.play(segment);
          },
          delay * 1000 * index,
        );
      } else {
        this.play(segment);
      }
    });
  }
}

六、注意事项

6.1 AudioContext 全局共享

• 全局 AudioContext 是单例模式，所有播放器实例共享
• 不要手动关闭 globalAudioContext，除非确定不再需要任何音频播放
• 如需关闭音频功能，建议在应用卸载时关闭

6.2 采样率一致性

• 播放器的采样率必须与音频数据的实际采样率一致
• 不一致的采样率会导致播放速度异常（过快或过慢）
• 常见采样率：
  • 8000 Hz：电话质量
  • 16000 Hz：语音应用常用
  • 24000 Hz：高质量语音（默认）
  • 48000 Hz：专业音频

6.3 连续播放时间管理

• 播放器通过维护 nextStartTime 实现无缝连续播放
• 如果音频数据接收间隔过大，可能出现播放跳跃
• 建议定期检查播放状态，必要时重置时间

6.4 内存管理

• 每次 play() 调用都会创建新的 AudioBuffer 和 SourceNode
• 这些资源会在播放结束后由浏览器自动回收
• 不需要手动释放，但应避免短时间内创建过多音频片段

6.5 浏览器自动播放策略

• 现代浏览器要求音频播放必须由用户交互触发
• 建议在用户点击事件中初始化播放器：

  button.addEventListener("click", () => {
    const player = new PCMStreamPlayer();
    // 现在可以播放音频了
  });
  

七、常见问题

Q1: 为什么使用全局 AudioContext 而不是每个播放器实例一个？

原因：

1. 浏览器限制：大多数浏览器限制同时存在的 AudioContext 数量（通常为 6 个）
2. 资源效率：共享单个 AudioContext 可以减少内存和 CPU 开销
3. 避免冲突：多个 AudioContext 可能导致音频上下文切换和同步问题
4. 统一管理：全局共享便于统一控制音频状态（暂停、恢复等）

Q2: 播放时音频速度异常（过快或过慢）？

原因： 播放器的采样率与音频数据的实际采样率不一致。

解决方案：

// 确保采样率一致
const player = new PCMStreamPlayer(24000); // 使用正确的采样率

// 如果不知道采样率，可以先分析音频数据
const analyzeSampleRate = (buffer: ArrayBuffer) => {
  // 根据业务逻辑确定采样率
  return 24000;
};

const sampleRate = analyzeSampleRate(audioBuffer);
player.sampleRate = sampleRate;
player.play(audioBuffer);

Q3: 音频片段之间有明显的间隙或重叠？

原因： 时间管理出现问题，可能是数据接收速度不均匀。

解决方案：

class GaplessPlayer extends PCMStreamPlayer {
  private lastPlayTime = 0;

  play(pcmData: unknown) {
    const float32Data = PCMStreamPlayer.toPCMFloat32(pcmData);
    const audioBuffer = globalAudioContext.createBuffer(1, float32Data.length, this.sampleRate);

    const channelData = audioBuffer.getChannelData(0);
    for (let i = 0; i < channelData.length; i++) {
      channelData[i] = float32Data[i]!;
    }

    const source = globalAudioContext.createBufferSource();
    source.buffer = audioBuffer;
    source.connect(globalAudioContext.destination);

    // 更精确的时间管理
    const currentTime = globalAudioContext.currentTime;

    // 如果之前安排的播放时间已经过期，从当前时间开始
    if (this.nextStartTime <= currentTime) {
      this.nextStartTime = currentTime;
    }

    source.start(this.nextStartTime);
    this.nextStartTime += audioBuffer.duration;

    // 记录实际播放时间用于调试
    this.lastPlayTime = this.nextStartTime;
  }

  // 获取当前播放进度
  getPlayProgress(): number {
    const currentTime = globalAudioContext.currentTime;
    return Math.max(0, this.nextStartTime - currentTime);
  }
}

Q4: 如何处理播放过程中的错误？

class SafePlayer extends PCMStreamPlayer {
  private lastError: Error | null = null;

  play(pcmData: unknown) {
    try {
      super.play(pcmData);
      this.lastError = null;
    } catch (error) {
      this.lastError = error as Error;
      console.error("播放失败:", error);
      // 可以选择重试或使用备用方案
    }
  }

  getLastError(): Error | null {
    return this.lastError;
  }

  hasError(): boolean {
    return this.lastError !== null;
  }
}

Q5: 如何实现暂停和恢复功能？

class PausablePlayer extends PCMStreamPlayer {
  private paused = false;
  private pauseTime = 0;
  private pendingSegments: Float32Array[] = [];

  pause() {
    if (!this.paused) {
      this.paused = true;
      this.pauseTime = this.nextStartTime;
    }
  }

  resume() {
    if (this.paused) {
      this.paused = false;
      this.nextStartTime = Math.max(globalAudioContext.currentTime, this.pauseTime);

      // 播放暂停期间缓存的片段
      this.pendingSegments.forEach((segment) => {
        this.play(segment);
      });
      this.pendingSegments = [];
    }
  }

  play(pcmData: unknown) {
    if (this.paused) {
      // 暂停时缓存片段
      const float32Data = PCMStreamPlayer.toPCMFloat32(pcmData);
      this.pendingSegments.push(float32Data);
    } else {
      super.play(pcmData);
    }
  }

  isPaused(): boolean {
    return this.paused;
  }
}