EG/plugins/user/audio_reverb_effects/README.md

# 音频混响和效果插件

一个功能完整的专业音频效果处理系统插件，为EG引擎提供基于Panda3D的高级音频效果处理功能，支持混响、均衡器、压缩器、调制效果和失真等多种音频效果。

## 功能特性

### 核心功能
- **专业混响处理**: 基于物理模型的高质量混响效果
- **多频段均衡器**: 精确的频段控制和滤波处理
- **动态范围压缩**: 专业级压缩器效果处理
- **调制效果**: 合唱、镶边、移相等多种调制效果
- **失真效果**: 过载、失真、模糊等多种失真类型
- **3D空间音频**: 真实的3D音频定位和空间化处理
- **效果链处理**: 支持多个效果的串联和并联处理
- **实时参数控制**: 所有效果参数支持实时调整

### 混响效果
- **房间建模**: 支持多种预设房间类型（小房间、大厅、教堂等）
- **参数控制**: 房间大小、阻尼、湿信号电平、干信号电平、宽度等
- **高级参数**: 早期反射、晚期混响、扩散、密度等
- **冲激响应**: 支持基于房间几何的冲激响应生成
- **预设系统**: 内置多种专业混响预设

### 均衡器效果
- **多频段控制**: 支持最多32个独立频段调节
- **滤波器类型**: 峰值滤波器、低频搁架、高频搁架
- **参数控制**: 频率、增益、Q因子、主增益等
- **专业功能**: 独奏模式、频段绕过、频段添加/移除
- **预设系统**: 内置多种音乐风格EQ预设

### 压缩器效果
- **动态控制**: 阈值、压缩比、启动时间、释放时间
- **高级参数**: 膝点、输出增益、自动补偿增益
- **专业功能**: 侧链处理、RMS窗口、预测处理
- **可视化表**: 增益减少量表、压缩比率表、包络跟随器
- **预设系统**: 内置多种应用场景压缩器预设

### 调制效果
- **效果类型**: 合唱、镶边、移相器
- **参数控制**: 速率、深度、反馈、湿信号混合、延迟时间
- **波形选择**: 正弦波、三角波、方波、锯齿波
- **立体声处理**: 立体声扩散、相位控制
- **滤波器**: 高频截止、低频截止
- **预设系统**: 内置多种调制效果预设

### 失真效果
- **效果类型**: 过载、失真、模糊、削波器
- **参数控制**: 驱动、音调、输出电平、偏置
- **整流模式**: 全波整流、半波整流、无整流
- **不对称处理**: 可调不对称度
- **滤波器**: 预滤波器、后滤波器
- **预设系统**: 内置多种失真效果预设

### 空间音频效果
- **3D定位**: 基于听者位置的精确3D音频定位
- **距离衰减**: 可配置的最小/最大距离和衰减因子
- **方向性**: 锥形效应、方位角、仰角计算
- **物理效应**: 多普勒效应、空气吸收
- **遮挡处理**: 遮挡和阻挡效果模拟
- **HRTF支持**: 头部相关传递函数实现更真实的3D音效
- **混响发送**: 可配置的混响发送量

### 效果管理
- **效果链**: 支持多个效果的串联处理
- **参数自动化**: 所有参数支持实时调整
- **预设系统**: 效果预设的创建、保存、加载
- **状态监控**: 实时效果处理状态和性能统计
- **资源管理**: 智能的效果资源管理和清理

### 性能优化
- **高效处理**: 优化的音频处理算法
- **内存管理**: 智能缓冲区管理和内存复用
- **多线程支持**: 支持多线程音频处理
- **采样率适配**: 自动适配不同采样率
- **质量控制**: 可配置的处理质量等级

## 使用方法

### 快捷键操作
- **F1**: 切换调试模式
- **F2**: 切换效果处理
- **F3**: 应用测试混响效果
- **F4**: 应用测试均衡器效果
- **F5**: 显示效果统计信息
- **F6**: 应用测试压缩器效果
- **F7**: 应用测试调制效果
- **F8**: 应用测试失真效果
- **F9**: 创建测试预设
- **F10**: 切换音质设置
- **F11**: 显示详细统计信息
- **F12**: 重置所有效果

### GUI界面操作
插件会在屏幕右上角创建控制面板，可以通过按钮直接操作音频效果功能。

### 编程接口
```python
# 获取插件实例
audio_effects_plugin = world.plugin_manager.get_plugin("audio_reverb_effects")

# 创建混响效果
reverb_params = {
    'room_size': 0.8,
    'damping': 0.5,
    'wet_level': 0.3,
    'dry_level': 0.7,
    'width': 1.0
}
reverb_effect_id = audio_effects_plugin.create_reverb_effect(reverb_params)

# 创建均衡器效果
eq_params = {
    'bands': {
        100: 2.0,   # 100Hz 提升2dB
        500: -1.0,  # 500Hz 降低1dB
        2000: 3.0,  # 2kHz 提升3dB
        8000: -2.0  # 8kHz 降低2dB
    }
}
eq_effect_id = audio_effects_plugin.create_eq_effect(eq_params)

# 创建压缩器效果
compressor_params = {
    'threshold': -20.0,
    'ratio': 4.0,
    'attack': 0.01,
    'release': 0.1,
    'gain': 2.0
}
compressor_effect_id = audio_effects_plugin.create_compressor_effect(compressor_params)

# 创建调制效果
modulation_params = {
    'type': 'chorus',
    'rate': 1.0,
    'depth': 0.5,
    'feedback': 0.3,
    'mix': 0.5
}
modulation_effect_id = audio_effects_plugin.create_modulation_effect(modulation_params)

# 创建失真效果
distortion_params = {
    'drive': 0.5,
    'tone': 0.8,
    'level': 0.7,
    'type': 'overdrive'
}
distortion_effect_id = audio_effects_plugin.create_distortion_effect(distortion_params)

# 应用效果到音效
audio_effects_plugin.apply_effect_to_sound(sound_id, reverb_effect_id)
audio_effects_plugin.apply_effect_to_sound(sound_id, eq_effect_id)
audio_effects_plugin.apply_effect_to_sound(sound_id, compressor_effect_id)

# 创建效果预设
preset_data = {
    'reverb': reverb_params,
    'eq': eq_params,
    'compressor': compressor_params
}
audio_effects_plugin.create_preset("my_preset", preset_data)

# 应用预设到音效
audio_effects_plugin.apply_preset_to_sound(sound_id, "my_preset")

# 设置效果参数
audio_effects_plugin.set_effect_parameter(reverb_effect_id, 'room_size', 0.6)
audio_effects_plugin.set_effect_parameter(eq_effect_id, 'bands', {100: 3.0, 1000: -1.0})

# 启用/禁用效果
audio_effects_plugin.enable_effect(reverb_effect_id)
audio_effects_plugin.disable_effect(eq_effect_id)

# 获取效果类型
effect_type = audio_effects_plugin.get_effect_type(compressor_effect_id)

# 获取音效应用的效果列表
applied_effects = audio_effects_plugin.get_sound_effects(sound_id)

# 从音效移除效果
audio_effects_plugin.remove_effect_from_sound(sound_id, reverb_effect_id)

# 删除效果
audio_effects_plugin.delete_effect(modulation_effect_id)
audio_effects_plugin.delete_effect(distortion_effect_id)

# 设置主音量
audio_effects_plugin.set_master_volume(0.8)

# 设置音质等级
audio_effects_plugin.set_quality_settings("high")

# 获取统计信息
stats = audio_effects_plugin.get_stats()
```

## 核心组件

### 混响处理器
负责专业混响效果的处理和管理。

主要功能：
- 多种混响算法实现
- 丰富的混响参数控制
- 房间冲激响应生成
- 预设管理系统

### 均衡器处理器
负责多频段均衡器效果的处理和管理。

主要功能：
- 多频段参数控制
- 多种滤波器类型
- 专业EQ功能实现
- 音乐风格预设

### 压缩器处理器
负责动态范围压缩效果的处理和管理。

主要功能：
- 专业压缩参数控制
- 侧链处理支持
- 实时可视化表
- 应用场景预设

### 调制处理器
负责合唱、镶边、移相等调制效果的处理和管理。

主要功能：
- 多种调制效果类型
- 波形选择和控制
- 立体声处理
- 效果预设系统

### 失真处理器
负责过载、失真、模糊等失真效果的处理和管理。

主要功能：
- 多种失真类型
- 整流模式控制
- 滤波器处理
- 失真预设系统

### 空间处理器
负责3D空间音频效果的处理和管理。

主要功能：
- 3D音频定位
- 距离衰减处理
- 物理效应模拟
- HRTF支持

## 效果预设

### 混响预设
- `small_room`: 小房间混响
- `medium_room`: 中等房间混响
- `large_room`: 大房间混响
- `large_hall`: 大厅混响
- `cathedral`: 教堂混响
- `bathroom`: 浴室混响

### 均衡器预设
- `flat`: 平衡设置
- `pop`: 流行音乐风格
- `rock`: 摇滚音乐风格
- `jazz`: 爵士音乐风格
- `classical`: 古典音乐风格
- `vocal_booster`: 人声增强
- `bass_boost`: 低音增强
- `treble_boost`: 高音增强

### 压缩器预设
- `vocal_compressor`: 人声压缩
- `bass_compressor`: 贝斯压缩
- `drum_compressor`: 鼓组压缩
- `master_bus`: 总线压缩
- `aggressive`: 强烈压缩
- `gentle`: 温和压缩

### 调制预设
- `chorus_light`: 轻柔合唱
- `chorus_medium`: 中等合唱
- `chorus_heavy`: 强烈合唱
- `flanger_light`: 轻柔镶边
- `flanger_medium`: 中等镶边
- `flanger_heavy`: 强烈镶边
- `phaser_light`: 轻柔移相
- `phaser_medium`: 中等移相
- `phaser_heavy`: 强烈移相

### 失真预设
- `mild_overdrive`: 轻度过载
- `heavy_overdrive`: 重度过载
- `classic_distortion`: 经典失真
- `metal_distortion`: 金属失真
- `fuzz_box`: 模糊效果
- `bass_overdrive`: 贝斯过载
- `tube_amp`: 胆机模拟
- `bit_crusher`: 位破碎

### 空间音频预设
- `close`: 近距离设置
- `medium`: 中距离设置
- `far`: 远距离设置
- `outdoor`: 户外设置
- `indoor`: 室内设置
- `underwater`: 水下设置

## 性能优化

### 算法优化
- **高效滤波器**: 优化的数字滤波器实现
- **快速傅里叶变换**: 频域处理优化
- **缓冲区管理**: 智能缓冲区复用
- **内存池**: 减少内存分配开销

### 处理优化
- **并行处理**: 支持多线程音频处理
- **质量等级**: 可配置的处理质量
- **动态调整**: 根据系统负载动态调整处理复杂度
- **效果链优化**: 优化的效果处理顺序

### 资源管理
- **智能加载**: 根据需要动态加载效果资源
- **自动清理**: 不使用的资源自动清理
- **缓存系统**: 效果参数和处理结果缓存
- **引用计数**: 资源引用计数管理

## 扩展开发

### 添加新的效果类型
1. 在[effects](file:///home/hello/EG/plugins/user/audio_reverb_effects/effects)目录中创建新的效果处理器
2. 实现效果处理逻辑
3. 在[Plugin](file:///home/hello/EG/plugins/user/audio_reverb_effects/plugin.py#L15-L1344)类中注册新效果

### 添加新的预设
1. 在对应的效果处理器中添加预设数据
2. 实现预设创建方法
3. 在插件中提供预设应用接口

### 添加新的处理算法
1. 在现有处理器中实现新的算法
2. 添加算法选择参数
3. 实现算法切换逻辑

## 故障排除

### 效果不生效
1. 检查效果是否已启用
2. 确认效果已正确应用到音效
3. 验证参数设置是否正确
4. 检查音效是否正在播放

### 性能问题
1. 使用统计信息分析性能瓶颈
2. 降低处理质量等级
3. 减少同时应用的效果数量
4. 优化效果参数设置

### 音质问题
1. 检查采样率设置是否正确
2. 确认缓冲区大小是否合适
3. 验证效果参数是否在合理范围
4. 检查是否出现削波现象

### 内存泄漏
1. 使用统计信息监控内存使用
2. 确认效果是否正确删除
3. 检查资源是否正确释放
4. 验证引用计数是否正确

## API参考

### Plugin类主要方法

#### 初始化和控制
- `initialize()` - 初始化插件
- `enable()` - 启用插件
- `disable()` - 禁用插件
- `finalize()` - 清理插件资源
- `update(dt)` - 更新插件状态

#### 效果创建和管理
- `create_reverb_effect(parameters)` - 创建混响效果
- `create_eq_effect(parameters)` - 创建均衡器效果
- `create_compressor_effect(parameters)` - 创建压缩器效果
- `create_modulation_effect(parameters)` - 创建调制效果
- `create_distortion_effect(parameters)` - 创建失真效果
- `create_spatial_effect(parameters)` - 创建空间效果
- `delete_effect(effect_id)` - 删除效果
- `apply_effect_to_sound(sound_id, effect_id)` - 应用效果到音效
- `remove_effect_from_sound(sound_id, effect_id)` - 从音效移除效果

#### 效果参数控制
- `set_effect_parameter(effect_id, parameter, value)` - 设置效果参数
- `get_effect_parameters(effect_id)` - 获取效果参数
- `enable_effect(effect_id)` - 启用效果
- `disable_effect(effect_id)` - 禁用效果
- `get_effect_type(effect_id)` - 获取效果类型
- `get_sound_effects(sound_id)` - 获取音效应用的效果列表

#### 预设系统
- `create_preset(preset_name, preset_data)` - 创建效果预设
- `apply_preset_to_sound(sound_id, preset_name)` - 应用预设到音效
- `get_preset_names()` - 获取所有预设名称
- `delete_preset(preset_name)` - 删除预设

#### 系统控制
- `set_master_volume(volume)` - 设置主音量
- `get_master_volume()` - 获取主音量
- `set_quality_settings(quality)` - 设置音质等级
- `get_quality_settings()` - 获取音质等级
- `process_audio_with_effects(sound_id, audio_data)` - 使用效果处理音频数据

#### 统计和信息
- `get_stats()` - 获取插件统计信息

## 音频格式支持

支持的音频格式：
- **WAV**: 未压缩的PCM音频
- **OGG**: Ogg Vorbis压缩音频
- **MP3**: MPEG音频层III

## 性能调优建议

### 效果处理优化
1. 合理控制同时处理的效果数量
2. 根据应用场景选择合适的效果预设
3. 及时删除不需要的效果
4. 使用预设减少参数配置时间

### 资源管理优化
1. 定期清理未使用的效果
2. 合理设置缓冲区大小
3. 使用对象池管理效果对象
4. 预加载常用的效果预设

### 系统性能优化
1. 根据硬件性能选择合适的质量等级
2. 监控系统资源使用情况
3. 动态调整处理复杂度
4. 使用多线程处理提高性能

## 版本信息

- 版本: 1.0.0
- 作者: EG Team
- 发布日期: 2024年

## 许可证

本插件遵循EG引擎许可证协议。