作者： 还是大剑师兰特 ，曾为美国某知名大学计算机专业研究生，现为国内GIS领域高级前端工程师，CSDN知名博主，深耕openlayers、leaflet、mapbox、cesium，webgl，ThreeJS，canvas，echarts等技术开发，欢迎加微信（gis-dajianshi），一起交流。

查看本专栏目录 - 本文是第 091篇入门文章

THREE.PositionalAudio 是 Three.js 中用于实现三维空间中具有位置信息的音频源的一个类。通过 THREE.PositionalAudio，你可以为场景中的对象赋予声音，并根据这些对象的位置和听者的位置来调整声音的效果，如距离衰减、方向感等。这对于创建沉浸式的声音体验非常有用，尤其是在游戏和虚拟现实应用中。

构造函数

构造函数 new THREE.PositionalAudio(listener) 接受一个参数来定义一个具有位置信息的音频源。

参数说明

• listener：一个 THREE.AudioListener 对象，用于绑定音频源，使之能够在三维环境中正确播放音频。

属性

THREE.PositionalAudio 的实例拥有如下属性：

• refDistance：一个浮点数，表示参考距离，在这个距离内的声音不会受到距离衰减的影响。
• coneInnerAngle：一个角度值，表示内锥角度，用于定义声音的最大传播方向。
• coneOuterAngle：一个角度值，表示外锥角度，当声音传播方向超出这个角度时，声音会受到衰减。
• coneOuterGain：一个介于 0 到 1 之间的浮点数，表示当声音传播方向超出外锥角度时的声音增益。
• distanceModel：一个字符串，表示使用的距离模型，可选值有 'inverse', 'linear', 'exponential'。
• rolloffFactor：一个浮点数，表示声音衰减的速度。
• panningModel：一个字符串，表示使用的立体声模型，可选值有 'equalpower', 'HRTF'。

方法

THREE.PositionalAudio 提供了以下常用的方法来操作和控制音频源：

• setBuffer(buffer)：设置音频的缓冲区，使其能够播放指定的音频文件。
• play()：开始播放音频。
• pause()：暂停播放音频。
• stop()：停止播放音频。
• setVolume(volume)：设置音频的音量大小，范围通常在 [0, 1] 之间。
• setRefDistance(distance)：设置参考距离。
• setRolloffFactor(factor)：设置衰减因子。
• setMaxDistance(distance)：设置最大距离，在超过这个距离后，声音将不再衰减。
• setConeOrientation(vector)：设置声音传播的方向。
• setConeInnerAngle(angle)：设置内锥角度。
• setConeOuterAngle(angle)：设置外锥角度。
• setConeOuterGain(gain)：设置外锥增益。
• setDistanceModel(model)：设置距离模型。
• setPanningModel(model)：设置立体声模型。

示例

创建一个基本的 THREE.PositionalAudio 对象，并将其附加到一个 THREE.Object3D 上：

// 假设已经创建了 `THREE.AudioListener` 对象 `audioListener`
const positionalAudio = new THREE.PositionalAudio(audioListener);// 加载音频文件
const audioLoader = new THREE.AudioLoader();
audioLoader.load('path/to/audio.mp3', function (buffer) {positionalAudio.setBuffer(buffer);positionalAudio.setLoop(true); // 设置音频循环播放positionalAudio.setVolume(0.5); // 设置音量大小positionalAudio.play(); // 开始播放音频
});// 创建一个三维对象，并将音频源附加到该对象上
const object3D = new THREE.Object3D();
object3D.position.set(10, 0, 0); // 设置物体的位置
object3D.add(positionalAudio);
scene.add(object3D);

使用 THREE.PositionalAudio 在 Three.js 中

THREE.PositionalAudio 在 Three.js 中主要用于实现具有位置信息的音频源。通过结合 THREE.AudioListener，可以实现三维空间中的声音效果，如距离衰减、方向感等。

示例：创建一个带有三维音频的场景

假设你想在一个 Three.js 场景中播放音频，并根据物体的位置调整音频效果：

// 创建一个场景、相机和渲染器
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(75, window.innerWidth / window.innerHeight, 0.1, 1000);
const renderer = new THREE.WebGLRenderer();
renderer.setSize(window.innerWidth, window.innerHeight);
document.body.appendChild(renderer.domElement);// 创建一个音频监听器
const audioListener = new THREE.AudioListener();
camera.add(audioListener);// 创建一个具有位置信息的音频源
const positionalAudio = new THREE.PositionalAudio(audioListener);// 加载音频文件
const audioLoader = new THREE.AudioLoader();
audioLoader.load('path/to/audio.mp3', function (buffer) {positionalAudio.setBuffer(buffer);positionalAudio.setLoop(true); // 设置音频循环播放positionalAudio.setVolume(0.5); // 设置音量大小positionalAudio.play(); // 开始播放音频
});// 创建一个三维对象，并将音频源附加到该对象上
const object3D = new THREE.Object3D();
object3D.position.set(10, 0, 0); // 设置物体的位置
object3D.add(positionalAudio);
scene.add(object3D);// 定义动画函数
function animate() {requestAnimationFrame(animate);// 更新音频监听器的位置和方向audioListener.position.set(camera.position.x, camera.position.y, camera.position.z);audioListener.forward.set(camera.getWorldDirection(new THREE.Vector3()).x, camera.getWorldDirection(new THREE.Vector3()).y, camera.getWorldDirection(new THREE.Vector3()).z);// 更新物体的位置（例如，模拟物体的移动）object3D.position.y += 0.01;// 渲染场景renderer.render(scene, camera);
}animate();

这段代码展示了如何使用 THREE.PositionalAudio 创建一个带有三维音频的三维场景，并根据物体的位置调整音频效果。

总结

THREE.PositionalAudio 是一个用于实现三维空间中具有位置信息的音频源的类，提供了丰富的操作和控制音频源的方法。通过这些方法，你可以设置音频的缓冲、音量、距离衰减等，并结合 THREE.AudioListener 实现三维空间中的声音效果。在 Three.js 的许多功能中，THREE.PositionalAudio 对于实现真实的三维音频体验非常重要。理解并熟练使用 THREE.PositionalAudio 对于开发高质量的 Three.js 应用程序是非常有帮助的。