在 WebRTC 的音频采集链路里，自动增益控制（Automatic Gain Control，AGC）是确保人声清晰、避免爆音或过弱信号的重要处理环节。浏览器通过 MediaStreamTrack 暴露了 autoGainControl 约束，但标准类型库中并没有直接给出目标电平默认值的具体类型，很多团队在扩展该能力时会遇到类型定义缺失的问题。本文会围绕 TypeScript 如何为媒体轨道处理中的自动增益目标电平默认值补齐类型声明展开，既说明接口扩展思路，也给出现成的声明文件写法。

自动增益控制与目标电平默认值的类型背景

自动增益控制的目标电平通常以 dBFS（相对于满量程的分贝值）表示，常见默认值有 -18 dBFS 或 -6 dBFS。该值直接影响麦克风输出信号的响度稳定性：目标电平设得过高，环境噪声会被放大；设得过低，人声可能显得单薄。在原生浏览器实现里，autoGainControl 只是一个布尔约束，只能开启或关闭算法，并不会暴露具体的目标电平数值，更不能直接指定默认值。因此当业务需要把目标电平默认值作为可配置参数时，TypeScript 侧就出现了类型缺口。

标准 DOM 类型库为 MediaTrackSettings 和 MediaTrackConstraintSet 提供了一组音频处理字段，例如 echoCancellation、noiseSuppression 以及 autoGainControl，但并没有任何与 target level default 相关的属性。如果开发者直接在约束对象里写入自定义属性，TypeScript 会提示对象字面量可能不包含该属性，除非使用 any 规避，而这会失去类型安全。更合适的做法是利用 TypeScript 的声明合并机制，在项目声明文件中为原生接口追加自定义成员，这样既不会修改 node_modules，也不会破坏全局 DOM 类型。

下面的代码展示了最直接的接口扩展方式。把这段声明放到 global.d.ts 或专门的类型声明文件中，编译器就会认为 MediaTrackSettings 和 MediaTrackConstraintSet 都包含 autoGainControlTargetLevelDefault 字段。

interface MediaTrackSettings {
  autoGainControl?: boolean;
  autoGainControlTargetLevelDefault?: number;
}
interface MediaTrackConstraintSet {
  autoGainControlTargetLevelDefault?: ConstrainDouble;
}

其中 ConstrainDouble 是标准类型库里已经存在的约束类型，表示可以是数值或数值范围描述。这里使用可选属性是为了兼容未实现该特性的浏览器，调用方可以通过类型守卫区分支持情况。

三种类型声明方案与声明合并实践

在真实项目中，不同的团队结构决定了类型声明应该放在哪里。如果只是一个小型业务项目，直接扩展全局接口最省事；如果要封装成一个媒体 SDK 供多个应用复用，则建议使用模块级类型或命名空间扩展，把影响范围限制在模块内部。下面分别说明三种方案。

方案一是全局声明合并。在 globals.d.ts 中使用 declare global 需要文件本身是模块，通常加一行 export {} 作为标记。例如：

export {};
declare global {
  interface MediaTrackSettings {
    autoGainControlTargetLevelDefault?: number;
  }
  interface MediaTrackConstraintSet {
    autoGainControlTargetLevelDefault?: ConstrainDouble;
  }
}

这种做法会让整个项目任何地方都能识别该字段，适合快速补齐类型。但缺点在于所有引入该声明文件的模块都共享这一扩展，如果某个依赖也有同名属性但含义不同，就可能产生冲突。因此全局扩展应当保持字段命名足够具体，例如增加前缀或使用命名空间。

方案二是模块级类型，不修改全局接口，而是定义自己的类型并让业务代码显式导入。这种方式更清晰，适合 SDK 或对类型控制要求较高的项目。可以定义一个 CustomMediaTrackSettings，它继承标准接口并叠加自动增益目标电平默认值。

export interface AgcTargetLevelDefaults {
  autoGainControlTargetLevelDefault: number;
}
export type CustomMediaTrackSettings = MediaTrackSettings & AgcTargetLevelDefaults;
export const DEFAULT_AGC_TARGET_LEVEL_DBFS = -18 as const;

业务代码使用 CustomMediaTrackSettings 后，就可以安全地读取和写入该字段，而不必担心污染全局类型。如果某些底层 API 返回的是原生 MediaTrackSettings，开发者可以在运行时做一次断言或类型守卫，把返回值收窄为自定义类型。

方案三是模块增强。当第三方库已经暴露了一个媒体处理模块，但类型定义没有包含目标电平字段时，可以使用 declare module 为其补充声明。例如某个 media-track-processing 包提供 AutomaticGainControlOptions 接口，但缺少 targetLevelDefault，可以这样写：

declare module 'media-track-processing' {
  export interface AutomaticGainControlOptions {
    targetLevelDefault: number;
  }
  export function createAgcProcessor(options: AutomaticGainControlOptions): void;
}

注意模块增强只适用于第三方包的声明文件已经被 TypeScript 加载的情况。如果包本身没有类型声明，还需要先处理基础类型，否则增强无效。

在业务代码中应用自动增益目标电平默认值

类型声明完成后，业务代码就可以在 getUserMedia 的音频约束里传入 autoGainControlTargetLevelDefault。需要注意的是，这属于非标准约束，主流浏览器未必支持。比较稳妥的做法是先尝试使用自定义约束，再根据 track.getSettings() 或 MediaTrackSupportedConstraints 判断是否真正生效。

下面的示例封装了一个打开麦克风函数，它返回 CustomMediaTrackSettings 类型。即使浏览器不识别自定义字段，运行时约束也会被忽略，但类型层已经保证调用方拿到的设置结构包含该字段。

async function openMicWithAgc(): Promise<CustomMediaTrackSettings> {
  const stream = await navigator.mediaDevices.getUserMedia({
    audio: {
      autoGainControl: true,
      autoGainControlTargetLevelDefault: DEFAULT_AGC_TARGET_LEVEL_DBFS,
    },
  });
  const track = stream.getAudioTracks()[0];
  const settings = track.getSettings() as CustomMediaTrackSettings;
  return settings;
}

如果直接使用类型断言，虽然编译通过，但运行时 settings 上可能并不存在 autoGainControlTargetLevelDefault。因此最好定义一个类型守卫，只有在确实读取到数值时才进入后续处理分支。这样既能保留类型收窄，又能避免把 undefined 当成有效默认值。

function hasAgcTargetLevelDefault(
  settings: MediaTrackSettings
): settings is CustomMediaTrackSettings {
  return typeof (settings as CustomMediaTrackSettings).autoGainControlTargetLevelDefault === 'number';
}
const current = track.getSettings();
if (hasAgcTargetLevelDefault(current)) {
  console.log(current.autoGainControlTargetLevelDefault);
}

自动增益开关和目标电平默认值之间还存在一个协作关系。如果用户手动关闭了 autoGainControl，那么即使约束里传了 autoGainControlTargetLevelDefault，算法也不会处理它。为了让类型更准确地反映这种状态，可以使用联合类型。开启时要求提供目标电平，关闭时禁止提供该字段。

type AgcAwareSettings =
  | { autoGainControl: true; autoGainControlTargetLevelDefault: number }
  | { autoGainControl: false; autoGainControlTargetLevelDefault?: never };

这种条件类型让 TypeScript 帮你拦截错误配置。例如只写 autoGainControl: true 而缺少目标电平会报错，而在 autoGainControl: false 时传了目标电平也会报错。对于复杂的音视频设置，这种类型约束能减少很多运行时排查成本。

类型测试与工程化维护

类型声明本身也需要持续维护。除了编写正常的单元测试外，可以引入类型测试来验证关键字段不会被意外移除或改错类型。工具层面上，expect-type 或 tsd 都是轻量选择，它们不会生成运行时代码，只在编译阶段检查类型是否符合预期。

import { expectType } from 'expect-type';
expectType<number>(DEFAULT_AGC_TARGET_LEVEL_DBFS);
expectType<boolean | undefined>(defaultAgcSettings.autoGainControl);

上面的示例中 defaultAgcSettings 需要预先定义并符合自定义类型。类型测试写好后，可以把它们纳入 CI 流程，避免后续有人把 autoGainControlTargetLevelDefault 改成字符串或删除字段时无人察觉。

工程化维护还需要在文档中明确默认值的单位。自动增益的目标电平并非无单位数值，它通常以 dBFS 为基准。建议在类型声明文件中使用 JSDoc 注释说明单位、取值范围以及默认值含义，例如 /** 自动增益目标电平默认值，单位为 dBFS，-18 表示 -18 dBFS */。这样协作者在使用时不会误以为是线性增益系数。

最后总结几个原则：优先扩展类型而不是使用 any；全局声明合并要谨慎，避免命名冲突；对非标准字段必须配合运行时特性检测；把有依赖关系的约束建模成联合类型，让错误在编译期暴露。按照这些思路，你就能在 TypeScript 中为媒体轨道处理的自动增益目标电平默认值建立起一套安全的类型体系。