如何在TypeScript中定义MediaRecorder音频处理延迟API的类型？

MediaRecorder 接口在录制音视频流时，标准实现并不暴露音频处理延迟的具体数值，但基于 Chromium 的部分浏览器开始通过实验性事件返回 AudioProcessingLatency 数据。TypeScript 的 lib.dom.d.ts 尚未收录这部分类型，于是严格模式下访问 onaudioprocessinglatency 会直接报错。解决思路是先定义延迟信息结构，再借助声明合并把事件补进 MediaRecorder 全局类型，最后用类型守卫保证运行时安全。

一、音频处理延迟的数据来源与接口设计

音频处理延迟通常指从麦克风采集到原始音频信号，到经过降噪、回声消除、自动增益控制等算法处理后输出，这段时间差。MediaRecorder 本身只负责编码和封装，不会主动处理音频，但它可以接收来自 MediaStreamTrack 的统计事件。因此，延迟信息多半通过一个自定义事件对象传递，字段往往包含输入端延迟、处理管线延迟和输出端延迟。

在编写 TypeScript 类型前，需要先明确字段的单位和可选性。不同浏览器的实现可能只提供总延迟，而不区分阶段，所以接口设计要留有余地。下面是最小可用接口，三个延迟值都采用毫秒为单位的 number，同时保留一个时间戳字段用于计算趋势。

interface AudioProcessingLatencyInfo {
  readonly inputLatency: number;
  readonly processingLatency: number;
  readonly outputLatency: number;
  readonly timestamp: number;
}

如果项目要适配多个浏览器版本，建议放宽为可选属性，并加入索引签名以便扩展未知字段。这样即使某些实现只返回 processingLatency，类型检查也不会因为缺少 inputLatency 而报错。

interface AudioProcessingLatencyInfo {
  inputLatency?: number;
  processingLatency?: number;
  outputLatency?: number;
  timestamp: number;
  [key: string]: unknown;
}

二、通过声明合并扩展 MediaRecorder 全局类型

MediaRecorder 是浏览器内置对象，TypeScript 允许通过声明合并给它增加新成员。最常见的方式是在项目的 .d.ts 文件中使用 declare global，但前提是该文件必须包含至少一个 export 或 import，使文件成为模块。否则 declare global 会被视为全局声明块而报错。

先定义事件对象 AudioProcessingLatencyEvent，它继承自 Event 并持有 latencyInfo 属性。然后把 onaudioprocessinglatency 事件处理器添加到 MediaRecorder 接口上，同时扩展 MediaRecorderEventMap 以便 addEventListener 获得准确的类型推断。

export {};

declare global {
  interface AudioProcessingLatencyEvent extends Event {
    readonly latencyInfo: AudioProcessingLatencyInfo;
  }

  interface MediaRecorderEventMap {
    audioprocessinglatency: AudioProcessingLatencyEvent;
  }

  interface MediaRecorder {
    onaudioprocessinglatency: ((this: MediaRecorder, ev: AudioProcessingLatencyEvent) => any) | null;
  }
}

注意这里 addEventListener 的重载已经由 lib.dom.d.ts 提供，但默认的 MediaRecorderEventMap 并不包含 audioprocessinglatency 键。声明合并之后，当调用 recorder.addEventListener('audioprocessinglatency', handler) 时，handler 的参数会自动推断为 AudioProcessingLatencyEvent，不再需要手动断言。

如果不想使用全局声明，也可以在局部模块中创建独立的类型别名，然后在事件监听回调里用 as 断言。不过这种方式无法让全局 MediaRecorder 获得新方法，复用性较差。维护一个统一的 .d.ts 文件是更稳妥的做法，建议放在项目根目录的 types 文件夹下，并在 tsconfig.json 的 include 字段中引入。

三、类型守卫与兼容性降级

类型定义解决的是编译期问题，但运行时仍需要确认当前浏览器是否真的实现了该事件。直接在未支持的浏览器中注册 onaudioprocessinglatency 是安全的，因为事件根本不会触发，但更严谨的做法是先做特性检测，再决定是否启用延迟监控。可以通过判断属性是否存在于 MediaRecorder.prototype 上来避免意外访问未定义的全局方法。

编写一个类型守卫函数，用来把宽泛的 Event 对象收窄为 AudioProcessingLatencyEvent。这个守卫在事件回调内部使用，既能保证 latencyInfo 存在，又能避开 as any 的滥用。

function isAudioProcessingLatencyEvent(event: Event): event is AudioProcessingLatencyEvent {
  return 'latencyInfo' in event && typeof (event as AudioProcessingLatencyEvent).latencyInfo === 'object';
}

const recorder = new MediaRecorder(stream);

if ('onaudioprocessinglatency' in recorder) {
  recorder.addEventListener('audioprocessinglatency', (event) => {
    if (isAudioProcessingLatencyEvent(event)) {
      const { inputLatency, processingLatency } = event.latencyInfo;
      console.log(`输入延迟：${inputLatency ?? '未知'}ms，处理延迟：${processingLatency ?? '未知'}ms`);
    }
  });
}

这里在 addEventListener 之前用 in 操作符检查属性，可以避免在不支持该事件的浏览器中注册回调。回调内部再用类型守卫二次确认，兼顾了运行时安全和类型正确性。若浏览器完全不支持，类型守卫虽然永远不会被调用，但代码路径不会报错，后续可以根据需要降级为模拟延迟数据或直接显示未知。

如果同一套代码要部署到多种内核的浏览器，还可以进一步把延迟信息设计成联合类型。例如某些版本返回的是 latency 字段而不是 latencyInfo，这时可以在 AudioProcessingLatencyInfo 中加入可选的 latency 属性，并在类型守卫里同时检查两个分支。适当的宽松设计能显著降低跨浏览器适配成本。

四、封装可复用的延迟监控模块

将前面的类型、检测和监听逻辑集中到一个类中，可以避免每次录制都重复编写模板代码。RecordingLatencyMonitor 接收一个 MediaRecorder 实例和一个延迟更新回调，内部负责注册事件、处理类型收窄以及停止时清理监听器。

class RecordingLatencyMonitor {
  private recorder: MediaRecorder;
  private onLatencyUpdate: (info: AudioProcessingLatencyInfo) => void;
  private listener: ((event: AudioProcessingLatencyEvent) => void) | null = null;

  constructor(recorder: MediaRecorder, onLatencyUpdate: (info: AudioProcessingLatencyInfo) => void) {
    this.recorder = recorder;
    this.onLatencyUpdate = onLatencyUpdate;
  }

  start(): void {
    if (!('onaudioprocessinglatency' in this.recorder)) {
      console.warn('当前环境不支持音频处理延迟事件');
      return;
    }

    this.listener = (event: AudioProcessingLatencyEvent) => {
      this.onLatencyUpdate(event.latencyInfo);
    };

    this.recorder.addEventListener('audioprocessinglatency', this.listener as EventListener);
  }

  stop(): void {
    if (this.listener) {
      this.recorder.removeEventListener('audioprocessinglatency', this.listener as EventListener);
      this.listener = null;
    }
  }
}

使用时只需要在开始录制前调用 start，在停止录制后调用 stop。延迟数据通过回调传递，上层可以自行计算平均值、绘制趋势图，或者根据延迟超过阈值动态关闭某些重处理模块。

监控模块的设计还应该考虑错误边界：如果回调内部抛出异常，监听器不应该中断录制流程。可以在内部用 try catch 包裹 onLatencyUpdate 调用，或者把回调异常记录到日志并继续执行。这类细节在长期运行的录制任务中尤其重要，因为一次延迟事件导致的未捕获异常可能让整个页面崩溃。

为 MediaRecorder 音频处理延迟 API 补齐 TypeScript 类型，本质上是在标准库覆盖之前给团队提供一个安全的类型边界。通过先定义接口、再用声明合并扩展全局对象、最后配合类型守卫和模块封装，可以有效避免运行时访问不存在的属性，同时让回调参数获得完整的类型提示。这个模式也适用于其他尚未进入 lib.dom.d.ts 的浏览器扩展 API。

TypeScriptMediaRecorder音频延迟修改时间：2026-09-30 03:46:31