<!-- Three.js WebAudio 3D音频演示 - 功能与核心技术详解
🎯 项目功能概述
这是一个基于Three.js和WebAudio API的3D空间音频可视化演示。项目模拟了一个虚拟音频环境，用户可以在其中体验基于位置的3D音效，并直观地看到音频传播的方向和范围。

主要功能亮点：
3D空间音频体验

音频音量、方向随听者（相机）位置变化

模拟现实世界的声音衰减和方向性

音频源具有明确的指向性（锥形辐射）

沉浸式3D场景

BoomBox（音箱）3D模型展示

真实的环境反射效果（瑞典皇家城堡环境贴图）

完整的灯光和阴影系统

交互式用户体验

鼠标控制相机旋转、缩放

直观的可视化音频辅助线

模拟音频遮挡效果的半透明墙面

物理效果模拟

声音随距离衰减（距离加倍，音量减半）

声音方向性（前方声音响亮，后方声音微弱）

音频遮挡效果演示

🔧 核心技术实现
1. Three.js 3D图形技术栈
技术组件	功能作用	实现细节
场景图系统	管理所有3D对象层级关系	THREE.Scene作为根容器，包含相机、灯光、模型等
透视相机	提供3D视角投影	PerspectiveCamera(45°, 宽高比, 0.1, 100)
WebGL渲染器	将3D场景渲染到2D画布	支持抗锯齿、阴影映射、HDR渲染
轨道控制器	鼠标交互控制	OrbitControls实现旋转、缩放、平移
2. WebAudio API 音频处理
音频组件	功能作用	关键技术点
AudioListener	音频接收点（"耳朵"）	附加到相机，随视角移动
PositionalAudio	3D位置音频源	基于PannerNode的空间音频
方向性锥体	模拟声音方向性	内锥角180°（全音量），外锥角230°（衰减）
距离衰减模型	模拟声音随距离衰减	setRefDistance(1) - 距离加倍音量减半
3. 3D模型与材质系统
模型相关技术	功能作用	实现方式
GLTF模型加载	加载BoomBox 3D模型	GLTFLoader加载.glb格式
环境反射贴图	模拟真实环境反射	立方体贴图（6张环境图）
Phong材质	实现高光和反射效果	MeshPhongMaterial配合环境贴图
阴影系统	模拟真实光影关系	方向光投射阴影，地面接收阴影
4. 物理模拟技术
javascript
// 距离衰减模型 - 基于真实物理的1/r衰减
positionalAudio.setRefDistance(1);  // 参考距离1单位

// 方向性模拟 - 类似真实扬声器的辐射模式
positionalAudio.setDirectionalCone(180, 230, 0.1);
// 参数说明：
// 180°内锥角：完全音量区域（前方半球）
// 230°外锥角：声音衰减区域
// 0.1：外锥体音量衰减到10%
5. 可视化辅助技术
可视化组件	功能作用	实现技术
PositionalAudioHelper	音频方向可视化	绘制音频锥体的3D线框
GridHelper	空间尺度参考	50x50单位的网格线
CameraHelper	调试阴影范围	可选的可视化阴影相机范围
半透明墙面	遮挡效果可视化	MeshBasicMaterial带透明度
🏗️ 系统架构设计
核心数据流：
text
音频源 (HTMLAudioElement)
    ↓
位置音频处理器 (PositionalAudio)
    ↓
WebAudio空间处理 (PannerNode)
    ↓
音频输出 (AudioContext → 扬声器)
    ↑
听者位置 (Camera Position)
3D渲染流水线：
text
场景初始化
    ↓
资源加载 (模型、纹理、音频)
    ↓
场景构建 (灯光、地面、模型)
    ↓
用户交互处理 (OrbitControls)
    ↓
渲染循环 (60fps动画)
    ↓
WebGL渲染输出
🎨 视觉效果实现
环境与光照：
半球光：模拟天空环境光（上亮下暗）

方向光：模拟直射阳光，产生清晰阴影

环境反射：立方体贴图模拟真实反射

雾效：距离雾增强深度感

材质与纹理：
地面使用Phong材质接收阴影

BoomBox模型应用环境反射贴图

墙面使用透明基础材质

🔊 音频空间化原理
位置音频的数学基础：
javascript
// WebAudio PannerNode的内部计算（简化）
function calculatePanning(listenerPos, sourcePos, sourceOrientation) {
    // 1. 计算相对向量
    const relativeVec = sourcePos - listenerPos;
    
    // 2. 计算距离衰减
    const distance = relativeVec.length();
    const gain = 1 / Math.max(distance, refDistance);
    
    // 3. 计算方向性衰减
    const angle = angleBetween(relativeVec, sourceOrientation);
    let directionGain = 1.0;
    
    if (angle > innerAngle) {
        if (angle < outerAngle) {
            // 线性衰减区域
            directionGain = 1 - (angle - innerAngle) / (outerAngle - innerAngle);
        } else {
            // 外锥体区域
            directionGain = outerGain;
        }
    }
    
    return gain * directionGain;
}
🚀 性能优化技术
阴影优化

精确设置阴影相机范围，避免过度渲染

使用合适的阴影贴图分辨率

渲染优化

设置合理的剪裁平面（0.1-100单位）

地面材质设置depthWrite: false

使用setAnimationLoop替代传统循环

资源加载优化

音频预加载（preload="auto"）

按需加载模型资源

立方体贴图一次性加载6个面

📱 响应式设计
自适应分辨率：根据devicePixelRatio适配Retina屏

窗口尺寸适配：实时调整相机宽高比和渲染器大小

交互适配：鼠标/触摸屏友好的控制方式

🎮 用户体验设计
渐进式体验

点击开始按钮进入场景

音频自动播放（需要用户交互触发）

直观的操作提示

视觉反馈

音频辅助线直观显示音频方向

半透明墙示意音频遮挡

平滑的相机运动（阻尼效果）

🔍 技术难点与解决方案
技术难点	解决方案
音频与3D场景同步	AudioListener附加到Camera，确保音频视角一致
跨浏览器音频兼容	提供OGG和MP3双格式，兼容所有现代浏览器
性能与视觉质量平衡	合理设置阴影质量、抗锯齿等参数
用户交互与音频播放	通过按钮点击触发音频播放，绕过浏览器自动播放限制
📊 技术栈总结
text
前端技术栈：
├── Three.js (r128+) - 3D图形渲染引擎
├── WebAudio API - 空间音频处理
├── ES6 Modules - 模块化开发
├── GLTF 2.0 - 3D模型格式
└── Import Maps - 模块路径映射

核心依赖：
├── three/addons/controls/OrbitControls
├── three/addons/helpers/PositionalAudioHelper
└── three/addons/loaders/GLTFLoader -->


<!DOCTYPE html>
<html lang="zh-CN">
	<head>
		<!-- 页面标题：Three.js WebAudio 音频方向演示 -->
		<title>Three.js WebAudio - 3D音频方向与空间音效演示</title>
		<!-- 字符编码设置为UTF-8，支持中文字符 -->
		<meta charset="utf-8">
		<!-- 
			视口设置（响应式设计）：
			width=device-width - 宽度等于设备宽度
			user-scalable=no - 禁止用户手动缩放（适合全屏应用）
			minimum-scale=1.0 - 最小缩放比例为1倍
			maximum-scale=1.0 - 最大缩放比例为1倍
		-->
		<meta name="viewport" content="width=device-width, user-scalable=no, minimum-scale=1.0, maximum-scale=1.0">
		<!-- 引入外部CSS样式表 -->
		<link type="text/css" rel="stylesheet" href="main.css">
	</head>
<body>

	<!-- 
		音频元素：
		1. id="music" - 用于JavaScript中获取元素引用
		2. loop - 设置音频循环播放
		3. preload="auto" - 自动预加载音频资源
		4. style="display: none" - 隐藏音频控件，仅作为音频源使用
		
		提供两种音频格式确保浏览器兼容性：
		- OGG格式：开源格式，Chrome、Firefox支持
		- MP3格式：广泛支持格式
	-->
	<audio loop id="music" preload="auto" style="display: none">
		<source src="sounds/376737_Skullbeatz___Bad_Cat_Maste.ogg" type="audio/ogg">
		<source src="sounds/376737_Skullbeatz___Bad_Cat_Maste.mp3" type="audio/mpeg">
	</audio>

	<!-- 
		开始界面覆盖层：
		页面加载时显示，点击开始按钮后移除
		id="overlay" - 用于JavaScript操作
	-->
	<div id="overlay">
		<!-- 
			开始按钮：
			id="startButton" - 用于添加点击事件监听器
			用户点击后触发init()函数初始化Three.js场景
		-->
		<button id="startButton">开始体验3D音频</button>
	</div>
	
	<!-- 
		Three.js渲染器容器：
		id="container" - WebGL渲染器将生成的canvas元素插入到此容器中
	-->
	<div id="container"></div>
	
	<!-- 
		页面信息区域：
		显示项目信息和版权信息
		id="info" - 可用于CSS样式化
	-->
	<div id="info">
		<!-- 
			项目技术栈信息：
			Three.js - WebGL 3D图形库
			WebAudio API - 网页音频处理API
			target="_blank" - 在新标签页中打开链接
			rel="noopener noreferrer" - 安全考虑，防止新页面访问原始页面
		-->
		<a href="https://threejs.org" target="_blank" rel="noopener noreferrer">Three.js</a> WebAudio - 3D音频方向与空间音效演示<br/>
		<!-- 
			音乐版权信息：
			显示音乐作者和来源链接
			音乐由skullbeatz创作，来自Newgrounds音频平台
		-->
		背景音乐: <a href="http://www.newgrounds.com/audio/listen/376737" target="_blank" rel="noopener noreferrer">skullbeatz - Bad Cat Master</a><br/>
		<!-- 
			功能说明：
			1. 使用鼠标左键拖动旋转视角
			2. 使用鼠标滚轮缩放视角
			3. 红色半透明墙面模拟音频遮挡效果
		-->
		<div style="font-size: 12px; margin-top: 5px;">
			操作说明: 鼠标左键旋转视角 | 滚轮缩放 | 红色墙面模拟音频遮挡
		</div>
	</div>

	<!-- 
		导入映射表 (Import Maps)：
		现代JavaScript模块系统特性，用于指定模块路径
		允许在import语句中使用简化的模块名称
	-->
	<script type="importmap">
		{
			"imports": {
				"three": "../build/three.module.js",
				"three/addons/": "./jsm/"
			}
		}
	</script>

	<!-- 
		主JavaScript模块：
		type="module" - 标识为ES6模块，支持import/export语法
		这个脚本包含了整个Three.js场景的创建和交互逻辑
	-->
	<script type="module">
		// ============ 导入Three.js核心库和扩展模块 ============
		
		// 导入Three.js核心库的所有功能
		import * as THREE from 'three';

		// 导入轨道控制器：允许用户通过鼠标控制相机旋转和缩放
		import { OrbitControls } from 'three/addons/controls/OrbitControls.js';
		// 导入位置音频辅助器：可视化音频的方向和范围
		import { PositionalAudioHelper } from 'three/addons/helpers/PositionalAudioHelper.js';
		// 导入GLTF加载器：用于加载GLTF/GLB格式的3D模型
		import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';

		// ============ 全局变量声明 ============
		
		// 场景对象：包含所有3D对象（模型、灯光、相机等）的容器
		let scene;
		// 相机对象：定义观察3D场景的视角
		let camera;
		// 渲染器对象：负责将3D场景渲染到2D画布上
		let renderer;

		// ============ DOM元素获取和事件绑定 ============
		
		// 获取开始按钮的DOM元素引用
		const startButton = document.getElementById('startButton');
		// 为开始按钮添加点击事件监听器
		// 当用户点击按钮时，调用init()函数初始化Three.js场景
		startButton.addEventListener('click', init);

		// ============ 初始化函数 ============
		
		/**
		 * init()函数 - Three.js场景初始化主函数
		 * 功能：创建场景、相机、渲染器、灯光、音频、模型等所有必要组件
		 * 执行时机：用户点击开始按钮后调用
		 */
		function init() {
			// 获取并移除开始界面覆盖层，显示3D场景
			const overlay = document.getElementById('overlay');
			overlay.remove();

			// 获取Three.js渲染器的容器元素
			const container = document.getElementById('container');

			// ============ 创建相机 ============
			
			/**
			 * 创建透视相机（PerspectiveCamera）：
			 * 参数1: 45 - 视野角度（FOV），单位度，模拟人眼视野范围
			 * 参数2: window.innerWidth / window.innerHeight - 宽高比，根据窗口尺寸计算
			 * 参数3: 0.1 - 近剪裁平面，距离相机0.1单位以内的物体不渲染
			 * 参数4: 100 - 远剪裁平面，距离相机100单位以外的物体不渲染
			 */
			camera = new THREE.PerspectiveCamera(45, window.innerWidth / window.innerHeight, 0.1, 100);
			// 设置相机初始位置：X=3, Y=2, Z=3（三维空间坐标）
			camera.position.set(3, 2, 3);

			// ============ 创建立方体环境贴图 ============
			
			/**
			 * 创建立方体贴图（CubeTexture），用于环境反射：
			 * 加载6张图片组成立方体贴图，模拟环境反射效果
			 * setPath() - 设置纹理图片的路径
			 * load() - 加载六个面的纹理（顺序：右、左、上、下、前、后）
			 */
			const reflectionCube = new THREE.CubeTextureLoader()
				.setPath('textures/cube/SwedishRoyalCastle/')
				.load(['px.jpg', 'nx.jpg', 'py.jpg', 'ny.jpg', 'pz.jpg', 'nz.jpg']);

			// ============ 创建场景 ============
			
			// 创建Three.js场景对象
			scene = new THREE.Scene();
			// 设置场景背景颜色（浅灰色）
			scene.background = new THREE.Color(0xa0a0a0);
			// 添加雾效：增强场景深度感，远处的物体逐渐淡出
			// 参数1: 0xa0a0a0 - 雾的颜色
			// 参数2: 2 - 雾的起始距离
			// 参数3: 20 - 雾的结束距离
			scene.fog = new THREE.Fog(0xa0a0a0, 2, 20);

			// ============ 创建灯光系统 ============
			
			/**
			 * 创建半球光（HemisphereLight）：
			 * 模拟环境天空光，从上到下渐变
			 * 参数1: 0xffffff - 天空颜色（白色）
			 * 参数2: 0x8d8d8d - 地面颜色（深灰色）
			 * 参数3: 3 - 光照强度
			 */
			const hemiLight = new THREE.HemisphereLight(0xffffff, 0x8d8d8d, 3);
			// 设置半球光位置：场景上方
			hemiLight.position.set(0, 20, 0);
			// 将半球光添加到场景
			scene.add(hemiLight);

			/**
			 * 创建方向光（DirectionalLight）：
			 * 模拟太阳光，产生清晰的阴影
			 * 参数1: 0xffffff - 光颜色（白色）
			 * 参数2: 3 - 光照强度
			 */
			const dirLight = new THREE.DirectionalLight(0xffffff, 3);
			// 设置方向光位置
			dirLight.position.set(5, 5, 0);
			// 启用方向光的阴影投射功能
			dirLight.castShadow = true;
			
			// 配置方向光的阴影相机参数（控制阴影渲染范围）
			dirLight.shadow.camera.top = 1;     // 阴影相机上边界
			dirLight.shadow.camera.bottom = -1; // 阴影相机下边界
			dirLight.shadow.camera.left = -1;   // 阴影相机左边界
			dirLight.shadow.camera.right = 1;   // 阴影相机右边界
			dirLight.shadow.camera.near = 0.1;  // 阴影相机近剪裁面
			dirLight.shadow.camera.far = 20;    // 阴影相机远剪裁面
			
			// 将方向光添加到场景
			scene.add(dirLight);

			// 可选：添加方向光阴影相机辅助对象（用于调试阴影范围）
			// scene.add(new THREE.CameraHelper(dirLight.shadow.camera));

			// ============ 创建地面 ============
			
			/**
			 * 创建地面网格：
			 * PlaneGeometry(50, 50) - 创建50x50单位的平面几何体
			 * MeshPhongMaterial - 使用Phong材质，支持高光反射
			 * color: 0xcbcbcb - 材质颜色（浅灰色）
			 * depthWrite: false - 优化渲染，地面不写入深度缓冲区
			 */
			const mesh = new THREE.Mesh(
				new THREE.PlaneGeometry(50, 50),
				new THREE.MeshPhongMaterial({ color: 0xcbcbcb, depthWrite: false })
			);
			// 旋转平面使其水平放置（Three.js中平面默认是垂直的）
			mesh.rotation.x = -Math.PI / 2;
			// 允许地面接收阴影
			mesh.receiveShadow = true;
			// 将地面添加到场景
			scene.add(mesh);

			// 创建网格辅助线：帮助理解3D空间尺度
			// 参数：尺寸50x50，50个细分，网格线颜色
			const grid = new THREE.GridHelper(50, 50, 0xc1c1c1, 0xc1c1c1);
			scene.add(grid);

			// ============ 创建音频系统 ============
			
			/**
			 * 创建音频监听器（AudioListener）：
			 * 音频监听器代表听众的耳朵位置
			 * 通常附加到相机上，随相机移动而移动
			 */
			const listener = new THREE.AudioListener();
			// 将音频监听器附加到相机上
			camera.add(listener);

			// 获取页面中的音频元素
			const audioElement = document.getElementById('music');
			// 开始播放音频
			audioElement.play();

			/**
			 * 创建位置音频（PositionalAudio）：
			 * 实现3D空间音效，音频音量、方向随位置变化
			 * 参数：音频监听器对象
			 */
			const positionalAudio = new THREE.PositionalAudio(listener);
			// 将HTML音频元素设置为位置音频的源
			positionalAudio.setMediaElementSource(audioElement);
			// 设置参考距离：距离加倍时音量减半（真实世界声音衰减模型）
			positionalAudio.setRefDistance(1);
			/**
			 * 设置方向性锥体参数：
			 * 参数1: 180 - 内锥角度（完全音量区域）
			 * 参数2: 230 - 外锥角度（声音衰减区域）
			 * 参数3: 0.1 - 外锥体音量（在外锥角度外的音量衰减到10%）
			 */
			positionalAudio.setDirectionalCone(180, 230, 0.1);

			// 创建位置音频辅助对象，可视化音频的方向和范围
			// 参数1: 位置音频对象
			// 参数2: 0.1 - 辅助线长度
			const helper = new PositionalAudioHelper(positionalAudio, 0.1);
			// 将辅助对象添加到音频对象中
			positionalAudio.add(helper);

			// ============ 加载3D模型 ============
			
			// 创建GLTF加载器实例
			const gltfLoader = new GLTFLoader();
			/**
			 * 加载GLTF模型文件：
			 * 'models/gltf/BoomBox.glb' - 模型文件路径
			 * function (gltf) - 加载完成后的回调函数
			 */
			gltfLoader.load('models/gltf/BoomBox.glb', function (gltf) {
				// 获取加载的模型场景
				const boomBox = gltf.scene;
				// 设置模型位置：X=0, Y=0.2, Z=0
				boomBox.position.set(0, 0.2, 0);
				// 设置模型缩放：放大20倍
				boomBox.scale.set(20, 20, 20);

				/**
				 * 遍历模型中的所有对象：
				 * traverse()方法递归访问模型的所有子对象
				 */
				boomBox.traverse(function (object) {
					// 检查对象是否为网格对象
					if (object.isMesh) {
						// 为网格材质应用环境反射贴图
						object.material.envMap = reflectionCube;
						// 旋转几何体（调整模型朝向）
						object.geometry.rotateY(-Math.PI);
						// 允许网格投射阴影
						object.castShadow = true;
					}
				});

				// 将位置音频附加到BoomBox模型上
				// 这样音频会随模型一起移动和旋转
				boomBox.add(positionalAudio);
				// 将模型添加到场景中
				scene.add(boomBox);
		
				// 启动渲染循环
				// setAnimationLoop替代之前的requestAnimationFrame
				renderer.setAnimationLoop(animate);
			});

			// ============ 创建音频遮挡墙 ============
			
			/**
			 * 创建红色半透明墙面，用于模拟音频遮挡效果：
			 * 当音频源在墙后时，声音会被部分阻挡
			 * BoxGeometry(2, 1, 0.1) - 长方体几何体，宽2高1厚0.1
			 */
			const wallGeometry = new THREE.BoxGeometry(2, 1, 0.1);
			/**
			 * 创建基础材质：
			 * color: 0xff0000 - 红色
			 * transparent: true - 启用透明度
			 * opacity: 0.5 - 50%透明度
			 */
			const wallMaterial = new THREE.MeshBasicMaterial({
				color: 0xff0000,
				transparent: true,
				opacity: 0.5
			});

			// 创建墙面网格
			const wall = new THREE.Mesh(wallGeometry, wallMaterial);
			// 设置墙面位置：在音频源后面
			wall.position.set(0, 0.5, -0.5);
			// 将墙面添加到场景
			scene.add(wall);

			// ============ 创建渲染器 ============
			
			/**
			 * 创建WebGL渲染器：
			 * antialias: true - 启用抗锯齿，使边缘更平滑
			 */
			renderer = new THREE.WebGLRenderer({ antialias: true });
			// 设置设备像素比，适配高DPI屏幕（Retina显示屏）
			renderer.setPixelRatio(window.devicePixelRatio);
			// 设置渲染器尺寸为窗口尺寸
			renderer.setSize(window.innerWidth, window.innerHeight);
			// 启用阴影映射
			renderer.shadowMap.enabled = true;
			// 将渲染器的DOM元素（canvas）添加到容器中
			container.appendChild(renderer.domElement);

			// ============ 创建轨道控制器 ============
			
			/**
			 * 创建轨道控制器：
			 * 允许用户通过鼠标交互控制相机
			 * 参数1: camera - 要控制的相机
			 * 参数2: renderer.domElement - 监听交互事件的DOM元素
			 */
			const controls = new OrbitControls(camera, renderer.domElement);
			// 设置控制器的目标点（相机围绕此点旋转）
			controls.target.set(0, 0.1, 0);
			// 更新控制器内部状态
			controls.update();
			// 设置相机最小距离（不能过于接近目标点）
			controls.minDistance = 0.5;
			// 设置相机最大距离（不能过于远离目标点）
			controls.maxDistance = 10;
			// 设置相机最大垂直旋转角度（防止相机翻转）
			controls.maxPolarAngle = 0.5 * Math.PI; // 90度

			// ============ 窗口大小变化事件监听 ============
			
			// 监听窗口大小变化事件
			window.addEventListener('resize', onWindowResize);
		}

		// ============ 窗口大小调整处理函数 ============
		
		/**
		 * onWindowResize()函数
		 * 功能：当浏览器窗口大小改变时，调整相机和渲染器设置
		 * 确保3D场景正确适配新的窗口尺寸
		 */
		function onWindowResize() {
			// 更新相机的纵横比（根据新的窗口尺寸计算）
			camera.aspect = window.innerWidth / window.innerHeight;
			// 更新相机投影矩阵（必须调用此方法应用更改）
			camera.updateProjectionMatrix();

			// 更新渲染器大小为新的窗口尺寸
			renderer.setSize(window.innerWidth, window.innerHeight);
		}

		// ============ 动画循环函数 ============
		
		/**
		 * animate()函数 - 渲染循环
		 * 功能：每一帧调用，渲染3D场景
		 * 这是Three.js应用的核心循环函数
		 */
		function animate() {
			// 渲染场景：将3D场景通过相机视角渲染到2D画布
			renderer.render(scene, camera);
			
			// 注意：此函数会持续调用，通常每秒60次（取决于屏幕刷新率）
			// 可以在此处添加动画逻辑，如对象旋转、位置更新等
		}

		// ============ 总结 ============
		/**
		 * 本示例展示了Three.js与WebAudio API的结合使用
		 * 核心功能点：
		 * 1. 3D场景创建和渲染
		 * 2. 位置音频的实现（3D音效）
		 * 3. 模型加载和环境反射
		 * 4. 灯光和阴影系统
		 * 5. 用户交互控制（轨道控制器）
		 * 6. 响应式设计（窗口大小适配）
		 * 
		 * 音频特性：
		 * - 音频随相机（听众）位置变化而改变音量和方向
		 * - 音频源具有方向性（锥形辐射）
		 * - 模拟现实世界的声音传播特性
		 */
	</script>

</body>
</html>