TypeScript如何定义媒体轨道自动增益控制的增益范围类型

处理麦克风采音时，自动增益控制（AGC）会让浏览器自动调整输入音量，但增益幅度失控时常会出现背景噪声被放大的问题。要精细控制这个行为，就需要用到媒体轨道约束中与增益范围相关的字段。TypeScript项目里，这些字段并没有全部出现在官方的lib.dom.d.ts中，部分需要自己补全类型。本文从约束模型讲起，给出可直接复用的类型定义。

媒体约束中的数值范围模型

MediaTrack约束分为两种语义：写在exact里的叫精确约束，浏览器必须满足否则直接报错；写在ideal里的叫理想约束，浏览器会尽力靠近但不保证。对于布尔型的AGC开关，直接用exact: true即可，而增益范围这类连续数值参数，规范采用了一个双字段结构来描述区间。

规范中定义的ULongRange、DoubleRange等结构都是这个思路：用min和max两个可选属性表达一个闭区间。增益范围约束（在一些实现中叫autoGainControl的扩展，另一些叫googAutoGainControl或在高级约束里以数值对形式出现）本质上就是这样一个区间。理解了这一点，类型定义的骨架就出来了。

// 基础范围类型，对应规范中的 DoubleRange / ULongRange
interface NumberRange {
  min?: number;
  max?: number;
  exact?: number;
  ideal?: number;
}

// 单独描述增益区间的最小值与最大值
interface GainRange {
  min: number;  // 增益最小值，单位通常为 dB 或 mB，视实现而定
  max: number;  // 增益最大值
}</h2>

注意min和max可以只给其中一个，表示单边约束。例如只写max: 20表示增益上限20，浏览器可以自由选择下限。

为AGC相关约束编写完整类型

官方类型库中，MediaTrackConstraintSet已经包含autoGainControl的布尔形式，但增益范围的扩展字段往往缺失。推荐的做法是不去修改全局接口，而是声明模块扩展，把自己的字段补充进去。这样既保留原有提示，又不会污染其他人的代码。

下面的例子展示了如何声明一个包含增益范围的约束集，并在getUserMedia中安全使用。关键是把布尔型AGC开关和数值型增益范围分开定义，避免类型合并后出现既可以是布尔又可以是对象的混乱情况。

// 声明对 DOM 类型的模块扩展
declare global {
  interface MediaTrackConstraintSet {
    autoGainControl?: ConstrainBoolean;
    // 增益范围字段，不同浏览器命名可能不同，这里以常见扩展名为例
    autoGainControlRange?: GainRangeConstraint;
  }
}

// 增益范围约束：支持精确区间与理想区间两种写法
type GainRangeConstraint =
  | GainRange
  | { exact: GainRange }
  | { ideal: GainRange };

async function openMic() {
  const stream = await navigator.mediaDevices.getUserMedia({
    audio: {
      autoGainControl: { ideal: true },
      autoGainControlRange: { exact: { min: -10, max: 30 } },
    },
  });
  return stream;
}

这里用了联合类型区分三种形态：裸区间、精确区间、理想区间。调用方传错结构时，比如把min写成minimum，编译器会立刻报错，这正是补类型的最大价值。

运行时校验与applyConstraints的配合

类型只管编译期，浏览器实际支持哪些约束要看getCapabilities的返回。稳妥的流程是：先查询能力，再过滤参数，最后通过applyConstraints动态调整。这个查询结果同样可以套用前面定义的GainRange类型。

// 读取轨道的增益能力范围并动态收紧
async function tightenGain(track: MediaStreamTrack) {
  const caps = track.getCapabilities() as MediaTrackCapabilities & {
    autoGainControlRange?: GainRange;
  };

  const supported = caps.autoGainControlRange;
  if (!supported) {
    console.warn('当前浏览器不支持增益范围约束');
    return;
  }

  // 在设备能力区间内取一个更保守的范围
  const safeMin = Math.max(supported.min, -5);
  const safeMax = Math.min(supported.max, 15);

  await track.applyConstraints({
    advanced: [{ autoGainControlRange: { min: safeMin, max: safeMax } }],
  } as MediaTrackConstraints);
}

由于applyConstraints失败会抛出OverconstrainedError，建议外层包一层try/catch，失败时回退到只开关AGC不限制范围。此外，Chrome的底层实现中增益单位通常是毫贝（mB，即dB的十分之一），写约束前先打印能力值确认量纲，否则很容易把数值理解错一个数量级。

最后提一点工程化建议：把上述类型集中放在一个media-constraints.d.ts文件中，配合一份运行时的字段白名单校验函数，就能同时覆盖编译期与运行时两端。这样即使将来规范把字段名标准化了，也只需要改一处声明，业务代码完全不用动。

TypeScript自动增益控制MediaTrack约束修改时间：2026-09-07 03:42:27