PannerNode - 表示空间中音频源信号的位置和行为

PannerNode 接口表示空间中音频源信号的位置和行为。它是一个 AudioNode 音频处理模块，它使用右手笛卡尔坐标描述其位置，使用速度矢量进行的移动以及使用方向性锥的方向性。

PannerNode 总是只有一个输入和一个输出：输入可以是 mono 或 stereo，但是输出始终是 stereo（两个通道）；如果没有两个或以上的音频通道，您将无法获得声像效果！

输入数量	1
输出数量	1
通道计数模式	"clamped-max"
通道数	2
通道解释	"speakers"

构造函数

PannerNode.PannerNode

创建一个新的 PanerNode 对象实例。

属性

从其父接口 AudioNode 继承了属性。

由于方向和位置值存储为 AudioParam 值，因此它们使用不同的语法进行设置和检索。检索是通过访问例如 PanerNode.positionX 来完成的。而设置相同的属性则是通过 PannerNode.positionX.value 来完成的。这就是为什么这些值没有标记为只读，这是它们在 WebIDL 中的显示方式。

PannerNode.coneInnerAngle

一个双精度值，它描述圆锥的角度（以度为单位），该圆锥内的体积不会减少。

PannerNode.coneOuterAngle

一个双精度值，以度为单位，描述圆锥的角度，在其外部体积将由常量值减小，该值由 coneOuterGain 属性定义。

PannerNode.coneOuterGain

一个双精度值，描述由 coneOuterAngle 属性定义的圆锥体外部的体积减少量。它的默认值为 0，表示无法听到声音。

PannerNode.distanceModel

一个枚举值，用于确定在音频源从听众移开时使用哪种算法来减小音频源的音量。

PannerNode.maxDistance

一个双精度值，代表音频源和收听者之间的最大距离，此后音量不再减小。

PannerNode.orientationX

表示右手笛卡尔坐标系中音频源矢量的水平位置。虽然无法直接更改此 AudioParam}，但可以使用其 value 属性来更改其值。默认值为 1。

PannerNode.orientationY

表示右手笛卡尔坐标系中音频源矢量的垂直位置。默认值为 0。虽然无法直接更改此 AudioParam，但可以使用其 value 属性来更改其值。

PannerNode.orientationZ

表示在右手笛卡尔坐标系中音频源矢量的纵向（来回）位置。默认值为 0。虽然无法直接更改此 AudioParam}，但可以使用其 value 属性来更改其值。

PannerNode.panningModel

一个枚举值，确定要使用哪种空间化算法将音频定位在 3D 空间中。

PannerNode.positionX

表示音频在右笛卡尔坐标系中的水平位置。默认值为 0。虽然无法直接更改此 AudioParam，但可以使用其 value 属性来更改其值。

PannerNode.positionY

表示音频在垂直笛卡尔坐标系中的垂直位置。默认值为 0。虽然无法直接更改此 AudioParam，但可以使用其 value 属性来更改其值。

PannerNode.positionZ

表示音频在笛卡尔直角坐标系中的纵向（前后）位置。默认值为 0。虽然无法直接更改此 AudioParam}，但可以使用其 value 属性来更改其值。

PannerNode.refDistance

一个双精度值，表示参考距离，用于在音频源远离听众时减小音量。

PannerNode.rolloffFactor

一个双精度值，描述当源远离监听器时减小音量的速度。所有距离模型均使用此值。

方法

从其父接口 AudioNode 继承了方法。

PannerNode.setPosition()

定义音频源相对于监听器的位置（由存储在 AudioContext.listener 属性中的 AudioListener 对象表示）。

PannerNode.setOrientation()

定义音频源播放的方向。

PannerNode.setVelocity()

定义音频源的速度矢量 - 它的移动速度和方向。在规范的先前版本中，PannerNode} 的速度可以向上或向下倾斜连接到下游的 AudioBufferSourceNode。该功能没有明确指定，存在很多问题，因此已从规范中删除。

实例

在下面的实例中，您将看到如何使用 createPanner() 方法、AudioListener 和 PannerNode} 来控制音频空间化的示例。通常，您将在 3D 空间中定义音频监听器和声像器（源）最初占据的位置，然后在使用该应用程序时更新其中一个或两个的位置。例如，您可能要在游戏世界中移动角色，并希望随着您的角色靠近或远离音乐播放器（例如立体声音响）而使音频的传递发生实际变化。在实例中，您可以看到它是由 moveRight()，moveLeft() 等函数控制的，它们通过 PositionPanner() 函数设置了全景位置的新值。

要查看完整的实现，请查看我们的 panner-node 实例（查看源代码）— 该演示将您带到 2.5D “金属房”，您可以在动臂箱上播放曲目，然后在动臂箱周围走动以查看声音如何变化！

请注意，我们如何使用某些功能检测为浏览器提供较新的属性值（例如 AudioListener.forwardX）来设置位置（如果支持的话），或者使用较旧的方法（例如 AudioListener.setOrientation()）（如果浏览器支持这些属性，但不支持新属性）。

// 设置监听器和声像器的位置信息
var WIDTH = window.innerWidth;
var HEIGHT = window.innerHeight;

var xPos = Math.floor(WIDTH/2);
var yPos = Math.floor(HEIGHT/2);
var zPos = 295;

// 定义其他变量

var AudioContext = window.AudioContext || window.webkitAudioContext;
var audioCtx = new AudioContext();

var panner = audioCtx.createPanner();
panner.panningModel = 'HRTF';
panner.distanceModel = 'inverse';
panner.refDistance = 1;
panner.maxDistance = 10000;
panner.rolloffFactor = 1;
panner.coneInnerAngle = 360;
panner.coneOuterAngle = 0;
panner.coneOuterGain = 0;

if(panner.orientationX) {
  panner.orientationX.setValueAtTime(1, audioCtx.currentTime);
  panner.orientationY.setValueAtTime(0, audioCtx.currentTime);
  panner.orientationZ.setValueAtTime(0, audioCtx.currentTime);
} else {
  panner.setOrientation(1,0,0);
}

var listener = audioCtx.listener;

if(listener.forwardX) {
  listener.forwardX.setValueAtTime(0, audioCtx.currentTime);
  listener.forwardY.setValueAtTime(0, audioCtx.currentTime);
  listener.forwardZ.setValueAtTime(-1, audioCtx.currentTime);
  listener.upX.setValueAtTime(0, audioCtx.currentTime);
  listener.upY.setValueAtTime(1, audioCtx.currentTime);
  listener.upZ.setValueAtTime(0, audioCtx.currentTime);
} else {
  listener.setOrientation(0,0,-1,0,1,0);
}

var source;

var play = document.querySelector('.play');
var stop = document.querySelector('.stop');

var boomBox = document.querySelector('.boom-box');

var listenerData = document.querySelector('.listener-data');
var pannerData = document.querySelector('.panner-data');

leftBound = (-xPos) + 50;
rightBound = xPos - 50;

xIterator = WIDTH/150;

// 收听者将始终在此演示的同一位置

if(listener.positionX) {
  listener.positionX.setValueAtTime(xPos, audioCtx.currentTime);
  listener.positionY.setValueAtTime(yPos, audioCtx.currentTime);
  listener.positionZ.setValueAtTime(300, audioCtx.currentTime);
} else {
  listener.setPosition(xPos,yPos,300);
}

listenerData.innerHTML = '收听者数据：X ' + xPos + ' Y ' + yPos + ' Z ' + 300;

// 当音箱在屏幕上移动时，声像将移动
function positionPanner() {
  if(panner.positionX) {
    panner.positionX.setValueAtTime(xPos, audioCtx.currentTime);
    panner.positionY.setValueAtTime(yPos, audioCtx.currentTime);
    panner.positionZ.setValueAtTime(zPos, audioCtx.currentTime);
  } else {
    panner.setPosition(xPos,yPos,zPos);
  }
  pannerData.innerHTML = '声像数据：X ' + xPos + ' Y ' + yPos + ' Z ' + zPos;
}

注意：在确定要应用于监听器和声像器的位置值，使声音适合屏幕上的视觉效果方面，需要进行大量的数学运算，但是通过一些实验，您很快就会习惯了。

规范

规范	状态	备注
Web Audio API PannerNode 的定义	工作草案	-

桌面浏览器兼容性

移动浏览器兼容性

1. 在 Chrome 59 之前，不支持默认值。

2. Before Samsung Internet 7.0, the default values were not supported.

3. 在 59 版本之前，不支持默认值。

相关链接

• 使用网络音频 API