音频开发 / 系统课时
用 PannerNode 处理空间位置
用 PannerNode 处理空间位置
当一个音源需要表现为位于玩家左侧、右侧、前方或远处时,不能只调左右声道音量。PannerNode 会根据音源和监听者的三维位置计算声像与距离衰减,本节完成一个可拖动音源位置的最小空间音频示例。
学习目标
- 理解
PannerNode在音频图中的位置,以及音源坐标如何影响听感 - 配置三维位置、声像模型和距离衰减参数
- 在浏览器中移动音源并验证左右声像变化
空间位置如何进入音频图
PannerNode 是一个普通的音频节点:上游连接音源或增益节点,下游连接 AudioContext.destination。它不会移动真实扬声器,而是根据音源相对监听者的位置,对信号应用空间化处理。

最常用的位置参数是 positionX、positionY 和 positionZ。它们都是 AudioParam,因此既可以直接设置 .value,也可以使用自动化方法实现平滑运动。
通常可以把监听者放在原点,并约定前方为负 Z 轴:音源的 X 值为负时位于左侧,为正时位于右侧。真正的左右听感还会同时受到监听者朝向影响。
配置声像与距离模型
panningModel 决定如何计算方向感。HRTF 会使用更复杂的头部相关传递函数,适合耳机中的三维定位;equalpower 计算更简单,更接近基础左右声像处理。
距离相关参数决定音源远离监听者后如何衰减。distanceModel 常用 inverse、linear 或 exponential,并与 refDistance、maxDistance、rolloffFactor 一起工作。应用中应根据场景尺度统一坐标含义,不要让一部分对象把 1 个单位当 1 米、另一部分又当 10 米。
让音源沿 X 轴移动
下面的完整页面在第一次点击按钮时创建音频图。滑块把音源从 -5 移到 5,监听者保持默认位置,适合戴耳机验证基本的左右空间变化。
<!doctype html>
<html lang="zh-CN">
<body>
<button id="start">启动音频</button>
<label>
音源 X 位置
<input id="sourceX" type="range" min="-5" max="5" step="0.1" value="-3">
</label>
<script>
const startButton = document.querySelector('#start');
const sourceX = document.querySelector('#sourceX');
let context;
let panner;
startButton.addEventListener('click', async () => {
if (!context) {
context = new AudioContext();
const oscillator = new OscillatorNode(context, { frequency: 440 });
const gain = new GainNode(context, { gain: 0.08 });
panner = new PannerNode(context, {
panningModel: 'HRTF',
distanceModel: 'inverse',
refDistance: 1,
maxDistance: 100,
rolloffFactor: 1
});
// 音源位于监听者前方,并由滑块控制左右位置。
panner.positionX.value = Number(sourceX.value);
panner.positionY.value = 0;
panner.positionZ.value = -1;
oscillator.connect(gain).connect(panner).connect(context.destination);
oscillator.start();
}
// 浏览器通常要求在用户手势后恢复 AudioContext。
await context.resume();
});
sourceX.addEventListener('input', () => {
if (panner) {
panner.positionX.value = Number(sourceX.value);
}
});
</script>
</body>
</html>预期结果
点击“启动音频”后会持续听到较轻的 440 Hz 音调。
滑块接近 -5 时声音主要从左侧感知,接近 5 时主要从右侧感知,经过 0 附近时逐渐移向中央。
具体空间感会因耳机、扬声器和浏览器实现不同而有所差异。动态位置不要产生跳变
直接修改 .value 适合交互验证,但游戏角色或动画音源持续移动时,离散坐标更新可能造成声像跳变。此时可以对 positionX、positionY、positionZ 使用 linearRampToValueAtTime() 等 AudioParam 自动化方法,让位置在两个时间点之间连续变化。
另外,PannerNode 只负责单个音源的空间化。多个独立声源通常各自拥有一个 PannerNode,再汇入共同的输出链路。只要所有节点使用同一个 AudioContext,它们就会依据同一个 AudioListener 计算相对空间关系。