PannerNode: refDistance 属性

Baseline 已广泛支持

此特性已相当成熟,可在许多设备和浏览器版本上使用。自 ⁨2015 年 7 月⁩以来,各浏览器均已提供此特性。

PannerNode 接口的 refDistance 属性是一个双精度浮点数值,表示音频源距离听众越远音量衰减的参考距离——即音量开始衰减生效的距离。此值由所有距离模型使用。

refDistance 属性的默认值为 1

一个非负数。如果该值设置为小于 0,则会抛出 RangeError

异常

RangeError

如果属性的值超出了接受的范围,则会抛出此错误。

示例

此示例演示了 refDistance 的不同值如何影响声音在远离听众时的音量衰减。与 rolloffFactor 不同,更改此值还会延迟音量衰减,直到声音经过参考点。

js
const context = new AudioContext();
// all our test tones will last this many seconds
const NOTE_LENGTH = 6;
// this is how far we'll move the sound
const Z_DISTANCE = 20;

// this function creates a graph for the test tone with a given refDistance
// and schedules it to move away from the listener along the Z (depth-wise) axis
// at the given start time, resulting in a decrease in volume (decay)
const scheduleTestTone = (refDistance, startTime) => {
  const osc = new OscillatorNode(context);

  const panner = new PannerNode(context);
  panner.refDistance = refDistance;

  // set the initial Z position, then schedule the ramp
  panner.positionZ.setValueAtTime(0, startTime);
  panner.positionZ.linearRampToValueAtTime(Z_DISTANCE, startTime + NOTE_LENGTH);

  osc.connect(panner).connect(context.destination);

  osc.start(startTime);
  osc.stop(startTime + NOTE_LENGTH);
};

// this tone should decay immediately and fairly quickly
scheduleTestTone(1, context.currentTime);
// this tone should decay slower and later than the previous one
scheduleTestTone(4, context.currentTime + NOTE_LENGTH);
// this tone should decay only slightly, and only start decaying fairly late
scheduleTestTone(7, context.currentTime + NOTE_LENGTH * 2);

运行此代码后,生成的波形应如下所示:

A waveform visualization of three oscillator tones produced in Web Audio. Each oscillator moves away from the listener at the same speed, but with different refDistances affecting the resulting volume decay.

规范

规范
Web Audio API
# dom-pannernode-refdistance

浏览器兼容性

另见