# 3D空间音效插件 一个功能完整的3D空间音效系统插件，为EG引擎提供基于Panda3D的3D音频处理功能，支持空间音效、环境音效和音频效果处理。 ## 功能特性 ### 核心功能 - **3D音频定位**: 基于听者位置和方向的实时3D音频定位 - **2D音频支持**: 支持传统的2D音频播放 - **音频源管理**: 完整的音频源创建、播放、暂停、停止和删除功能 - **环境音频**: 区域化的环境音效系统 - **音频效果**: 支持多种音频效果处理（混响、回声、滤波等） - **音频缓存**: 智能音频文件缓存系统，提高加载性能 - **淡入淡出**: 支持音频的淡入淡出效果 ### 音频处理 - **空间化处理**: 基于距离和方向的音量衰减和声道平衡 - **多普勒效应**: 根据音源和听者的相对运动计算频率变化 - **HRTF支持**: 头部相关传递函数实现更真实的3D音效 - **环境混响**: 根据房间尺寸和材质自动计算混响参数 - **音量控制**: 精确的音量控制和淡入淡出效果 - **距离衰减**: 可配置的最小/最大距离和衰减因子 - **音频优先级**: 音频资源管理和优先级控制 ### 音频效果 - **混响效果**: 模拟不同环境的混响效果 - **回声效果**: 创建回声和延迟效果 - **滤波效果**: 低通、高通和带通滤波器 - **失真效果**: 音频失真和过载效果 - **压缩效果**: 动态范围压缩 - **均衡器**: 多频段均衡器 - **合声/镶边**: 调制效果 - **效果链**: 支持多个效果的组合应用 ### 环境系统 - **音频区域**: 定义具有特定音频属性的3D区域 - **环境音效**: 区域内的背景环境音效 - **区域属性**: 可配置的区域音频参数 - **动态切换**: 听者在不同区域间移动时的音频切换 - **过渡效果**: 区域间平滑的音频过渡 - **遮挡效果**: 音频遮挡和 occlusion 处理 - **回调系统**: 区域进入/离开/内部状态回调 ### 编辑功能 - **可视化编辑**: 图形化界面编辑音频场景 - **多种工具**: 选择、添加音效、添加区域等工具 - **场景保存/加载**: 音频场景的序列化和反序列化 - **网格对齐**: 网格对齐功能提高编辑精度 - **实时预览**: 编辑过程中的实时音频预览 ### 性能优化 - **资源管理**: 智能的音频资源加载和卸载 - **内存优化**: 音频缓冲区管理和内存复用 - **批量处理**: 支持大量音频源的同时处理 - **LOD支持**: 根据距离调整音频处理质量 - **对象池**: 音频对象池减少GC压力 ## 使用方法 ### 快捷键操作 - **F1**: 切换音频调试模式 - **F2**: 切换空间音频 - **F3**: 播放测试音效 - **F4**: 停止所有音频 - **F5**: 显示音频统计信息 - **F6**: 切换环境音频 - **F7**: 应用混响效果 - **F8**: 应用回声效果 - **F9**: 创建测试区域 - **F10**: 切换多普勒效应 - **F11**: 切换HRTF - **F12**: 显示详细统计信息 ### GUI界面操作 插件会在屏幕左上角创建控制面板，右上角创建编辑器面板，可以通过按钮直接操作音频功能。 ### 编程接口 ```python # 获取插件实例 audio_plugin = world.plugin_manager.get_plugin("spatial_audio") # 创建3D音效 sound_id = audio_plugin.create_3d_sound( "sounds/footsteps.wav", (10, 0, 5), # 位置 False, # 循环 0.8, # 音量 1.0, # 最小距离 100.0, # 最大距离 1.0 # 衰减因子 ) # 创建2D音效 music_id = audio_plugin.create_2d_sound("sounds/background_music.mp3", True, 0.6) # 播放音效（支持淡入） audio_plugin.play_sound(sound_id, fade_in_time=1.0) # 设置音源位置 audio_plugin.set_sound_position(sound_id, (15, 0, 8)) # 设置音量 audio_plugin.set_sound_volume(sound_id, 0.5) # 检查音效状态 if audio_plugin.is_sound_playing(sound_id): print("音效正在播放") # 创建音频效果 reverb_effect_id = audio_plugin.create_audio_effect("reverb", { "reverb_time": 2.0, "early_reflections": 0.3, "late_reverb": 0.7 }) # 应用效果到音效 audio_plugin.apply_effect_to_sound(sound_id, reverb_effect_id) # 创建环境区域 audio_plugin.create_environment_zone("cave", (0, 0, 0), 20.0, { "reverb": 0.8, "absorption": 0.3, "ambient_volume": 0.4 }) # 为区域添加环境音效 audio_plugin.environment_audio_manager.add_ambient_sound_to_zone( "cave", "sounds/cave_ambience.wav", 0.4, True) # 设置听者位置 audio_plugin.set_listener_position((5, 0, 5)) # 设置听者方向 audio_plugin.set_listener_orientation((0, 0, 0)) # 停止音效（支持淡出） audio_plugin.stop_sound(sound_id, fade_out_time=1.0) # 删除音效 audio_plugin.delete_sound(sound_id) # 使用预设效果 cathedral_reverb = audio_plugin.create_preset_effect("cathedral_reverb") audio_plugin.apply_effect_to_sound(sound_id, cathedral_reverb) # 设置主音量 audio_plugin.set_master_volume(0.8) # 绑定音效到对象 audio_plugin.attach_sound_to_object(sound_id, character_node) # 添加区域回调 def on_enter_zone(zone_id): print(f"进入区域: {zone_id}") audio_plugin.add_zone_enter_callback("cave", on_enter_zone) ``` ## 核心组件 ### 音频源管理器 负责音频源的创建、播放和控制。 主要功能： - 3D和2D音效创建 - 音频播放控制（播放、暂停、停止） - 音源位置和属性设置 - 音频状态查询 - 资源管理和缓存 - 淡入淡出效果 ### 音频效果处理器 处理各种音频效果的应用和管理。 主要功能： - 多种音频效果创建 - 效果参数配置 - 效果应用到音源 - 效果启用/禁用控制 - 效果链管理 - 预设效果系统 ### 环境音频管理器 管理环境音效和区域音频效果。 主要功能： - 音频区域创建和管理 - 环境音效播放 - 区域属性配置 - 区域间音频切换 - 动态环境效果 - 区域状态回调 ### 音频编辑器 提供可视化编辑音频场景的功能。 主要功能： - 图形化界面编辑 - 多种编辑工具 - 场景保存和加载 - 实时预览 - 网格对齐 ## 音频组件 ### 音频源组件 为游戏对象添加音频播放功能。 主要功能： - 音频文件加载 - 3D空间化处理 - 音频播放控制 - 对象绑定 ### 音频听者组件 设置音频听者位置和方向。 主要功能： - 听者位置设置 - 听者方向设置 - 对象绑定 ### 音频效果组件 为音频源应用效果。 主要功能： - 音频效果创建 - 效果参数配置 - 效果应用和移除 ## 音频工具 ### 距离计算 计算两点间距离用于音量衰减计算。 ### 音量衰减 基于距离的音量衰减计算。 ### 声道平衡 根据音源相对位置计算左右声道平衡。 ### 多普勒效应 计算音源和听者相对运动引起的频率变化。 ### HRTF处理 头部相关传递函数实现更真实的3D音效。 ## 性能优化 ### 资源管理 - **智能加载**: 根据需要动态加载音频资源 - **内存复用**: 音频缓冲区复用减少内存分配 - **自动卸载**: 不使用的音频资源自动卸载 - **缓存系统**: 音频文件智能缓存 ### 处理优化 - **批量更新**: 批量处理音频源更新 - **LOD系统**: 根据距离调整处理质量 - **效果优化**: 根据重要性调整效果处理 ### 内存优化 - **对象池**: 音频对象池减少GC压力 - **流式加载**: 大型音频文件流式加载 - **压缩存储**: 音频数据压缩存储 ## 扩展开发 ### 添加新的音频效果 1. 在[effects](file:///home/hello/EG/plugins/user/spatial_audio/effects)目录中创建新的效果处理器 2. 实现效果处理逻辑 3. 在[AudioEffectProcessor](file:///home/hello/EG/plugins/user/spatial_audio/effects/audio_effect_processor.py#L11-L94)中注册新效果 ### 添加新的音频组件 1. 在[components](file:///home/hello/EG/plugins/user/spatial_audio/components)目录中创建新的组件类 2. 继承AudioComponent基类 3. 实现组件功能 ### 添加新的工具函数 1. 在[utils](file:///home/hello/EG/plugins/user/spatial_audio/utils)目录中创建新的工具模块 2. 实现工具函数 3. 在需要的地方使用工具函数 ## 故障排除 ### 音频无法播放 1. 检查音频文件路径是否正确 2. 确认音频格式是否支持 3. 检查音频系统是否正确初始化 4. 验证音频文件是否损坏 ### 3D音效不工作 1. 确认听者位置是否正确设置 2. 检查音源位置是否正确设置 3. 验证音频系统是否支持3D音效 4. 检查音频格式是否支持3D处理 ### 性能问题 1. 使用音频统计功能分析性能瓶颈 2. 减少同时播放的音频数量 3. 降低音频处理质量 4. 使用LOD系统优化远处音频 ### 环境音频问题 1. 检查区域定义是否正确 2. 确认听者位置是否在区域内 3. 验证环境音效文件是否正确加载 4. 检查区域属性设置 ## API参考 ### Plugin类主要方法 #### 初始化和控制 - `initialize()` - 初始化插件 - `enable()` - 启用插件 - `disable()` - 禁用插件 - `finalize()` - 清理插件资源 - `update(dt)` - 更新插件状态 #### 音频源操作 - `create_3d_sound(filepath, position, loop, volume, min_distance, max_distance, rolloff_factor)` - 创建3D音效 - `create_2d_sound(filepath, loop, volume)` - 创建2D音效 - `play_sound(sound_id, fade_in_time)` - 播放音效 - `stop_sound(sound_id, fade_out_time)` - 停止音效 - `pause_sound(sound_id)` - 暂停音效 - `resume_sound(sound_id)` - 恢复音效 - `set_sound_position(sound_id, position)` - 设置音源位置 - `set_sound_volume(sound_id, volume)` - 设置音源音量 - `set_sound_loop(sound_id, loop)` - 设置音源循环模式 - `is_sound_playing(sound_id)` - 检查音效是否正在播放 - `get_sound_duration(sound_id)` - 获取音效时长 - `get_sound_position(sound_id)` - 获取音源位置 - `delete_sound(sound_id)` - 删除音效 - `stop_all_sounds()` - 停止所有音频 - `attach_sound_to_object(sound_id, obj)` - 绑定音效到对象 - `detach_sound_from_object(sound_id)` - 解绑音效从对象 #### 音频效果操作 - `create_audio_effect(effect_type, parameters)` - 创建音频效果 - `apply_effect_to_sound(sound_id, effect_id)` - 应用效果到音效 - `remove_effect_from_sound(sound_id, effect_id)` - 从音效移除效果 - `create_preset_effect(preset_name)` - 创建预设效果 - `enable_audio_effects(enable)` - 启用/禁用音频效果处理 #### 听者操作 - `set_listener_position(position)` - 设置听者位置 - `set_listener_orientation(orientation)` - 设置听者方向 - `get_listener_velocity()` - 获取听者速度 #### 环境音频操作 - `create_environment_zone(zone_id, position, radius, properties)` - 创建环境区域 - `set_zone_property(zone_id, property_name, value)` - 设置区域属性 - `add_zone_enter_callback(zone_id, callback)` - 添加区域进入回调 - `add_zone_exit_callback(zone_id, callback)` - 添加区域离开回调 #### 系统控制 - `set_master_volume(volume)` - 设置主音量 - `get_master_volume()` - 获取主音量 - `set_audio_quality(quality)` - 设置音频质量 - `set_doppler_factor(factor)` - 设置多普勒效应因子 - `set_environment_occlusion(enable)` - 启用/禁用环境遮挡效果 #### 统计和信息 - `get_stats()` - 获取插件统计信息 - `get_cached_sound_files()` - 获取已缓存的音频文件列表 - `clear_sound_cache()` - 清空音频文件缓存 ## 音频格式支持 支持的音频格式： - **WAV**: 未压缩的PCM音频 - **OGG**: Ogg Vorbis压缩音频 - **MP3**: MPEG音频层III ## 性能调优建议 ### 音频源管理 1. 合理控制同时播放的音频数量 2. 及时删除不需要的音频源 3. 使用对象池管理音频对象 4. 预加载常用的音频资源 5. 合理设置音频缓存大小 ### 效果处理 1. 根据重要性选择效果 2. 限制同时应用的效果数量 3. 使用简化的效果处理远处音频 4. 及时移除不需要的效果 ### 环境音频 1. 合理设置区域大小 2. 控制区域内环境音效数量 3. 使用LOD系统优化远处区域 4. 及时清理不需要的区域 ### 内存管理 1. 定期清理音频缓存 2. 及时释放不需要的音频资源 3. 使用流式加载大型音频文件 4. 监控内存使用情况 ## 版本信息 - 版本: 1.0.0 - 作者: EG Team - 发布日期: 2024年 ## 许可证 本插件遵循EG引擎许可证协议。