Files
obs-soundwave/README.md
T
2026-11-12 21:00:55 +08:00

96 lines
4.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# obs-audio-waveform-dock
OBS Studio 插件:在主窗口右侧增加「音频频谱监视」面板,实时分析 **选定音频输入源** 与 **主输出(Master / Program Mix)** 的频谱,并可切换为波形显示;同时保留 OBS 原版的音频快速设置(监听 / 电平 / 滤镜)。
![频谱分析](docs/dock-spectrum.png)
## 功能
- **双路实时频谱**
- 上方:下拉框选择的音频输入源(麦克风、桌面音频、媒体源、采集卡音频等)。
- 下方:主输出(所有音频轨道混音后的 Program Mix,`obs_add_raw_audio_callback(0, ...)`)。
- 8192 点 Hann 窗 FFT,20 Hz ~ 20 kHz 对数频率轴,-90 ~ 0 dB 幅度显示;带峰值频率标记与实时读数(如 `439 Hz`)。
- 输入源按源音量/静音加权,和 OBS 混音器电平表一致。
- **波形模式**
- 同一面板可在「频谱 / 波形」之间切换,波形按逐像素 min/max 包络滚动显示最近 3 秒,并显示峰值 / RMS 与电平表。
![波形模式](docs/dock-waveform.png)
- **保留原版快速设置**
- **监听**(与混音器耳机按钮等价,调用 `obs_source_set_monitoring_enabled`;OBS 33 起监听为开关式)。
- **静音** 开关。
- **电平/音量** 滑杆(-60.0 dB ~ 0.0 dB),与源音量双向同步。
- **滤镜** 按钮:直接打开 OBS 原生滤镜窗口,增益、压缩器、限制器、噪声门、EQ 等原版滤镜全部可用。
![原版滤镜窗口](docs/native-filters.png)
- 在显示区域 **右键**:监听 / 静音 / 音量重置 0 dB / 滤镜 / 属性。
- 自动记住上次选择的输入源与显示模式(写入当前 OBS 配置文件);源被删除时自动回退;无记录时优先选择「桌面音频」。
- 面板启动后自动停靠在右侧,也可从 **视图 → 停靠窗口(Docks)** 中开关。
## 安装
1. 退出 OBS。
2. 以管理员身份运行 `scripts/install.ps1`:
```powershell
powershell -ExecutionPolicy Bypass -File scripts\install.ps1
```
脚本会把以下文件复制到 OBS 安装目录(默认 `C:\Program Files\obs-studio`):
```
obs-plugins/64bit/audio-waveform-dock.dll
data/obs-plugins/audio-waveform-dock/locale/{en-US,zh-CN}.ini
```
也可以手动复制 `dist/audio-waveform-dock.dll` 与 `data/` 目录到对应位置。
卸载:`scripts\uninstall.ps1`。
## 从源码构建(Windows)
依赖:
- Visual Studio 2022 Build Tools(MSVC v143 + Windows 10/11 SDK)
- Qt 6.10.x(或任意 Qt 6.9+)MSVC 2022 64-bit,仅需 Core/Gui/Widgets
- CMake ≥ 3.28、Ninja、Python 3(`pip install pefile`)
- obs-studio 33.0.0 源码(**只使用头文件**,不需要编译 OBS)
```powershell
# 1) 从已安装 OBS 的 DLL 导出表生成 obs.lib / obs-frontend-api.lib
powershell -ExecutionPolicy Bypass -File scripts\gen-obs-libs.ps1 `
-ObsPath "C:\Program Files\obs-studio" `
-OutDir "D:\dsh-build\obs-libs"
# 2) 编译
powershell -ExecutionPolicy Bypass -File scripts\build.ps1 `
-ObsSource "D:\dsh-build\obs-studio-33" `
-ObsLibs "D:\dsh-build\obs-libs" `
-QtRoot "D:\Qt\6.10.3\msvc2022_64" `
-VsPath "D:\VS\BuildTools"
```
产物:`build\bin\audio-waveform-dock.dll`。
## 实现说明
- 输入源音频:`obs_source_add_audio_capture_callback`(滤波后、推子前的 float planar,插件按源音量/静音加权显示);源通过 `obs_weak_source_t` 持有,切换/删除/退出时注销回调。
- 主输出音频:`obs_add_raw_audio_callback(0, conversion, ...)`,mix 0 即主混音,转换请求为 48 kHz / float planar / stereo。
- 频谱:对两路音频分别做 8192 点 Hann 窗 radix-2 FFT(单声道混合),按对数频率映射到像素列,峰值快速起、55 dB/s 缓慢回落;峰值频率由最大幅度 bin 计算。
- 监听:OBS 33 将三态监听合并为开关,`obs_source_set_monitoring_type` 已废弃,插件使用 `obs_source_set_monitoring_enabled` 保持与原版一致。
- 滤镜:`obs_frontend_open_source_filters` 打开 OBS 原生滤镜窗口,不重新实现滤镜 UI。
- 停靠:等待 OBS 恢复完布局后,通过 `toggleViewAction()` 显示,再 `setFloating(false)` 停靠到右侧;不对已由 OBS 管理的 Dock 再次调用 `addDockWidget()`(会破坏 Qt 布局并导致启动崩溃)。
- 编译期通过 `third_party/obsconfig/obsconfig.h` 提供 obs-studio 配置头,避免依赖完整的 OBS 构建树。
## 兼容性
- 在 OBS Studio 33.0.0(Windows x64,Qt 6.11.1 runtime)上构建并实测:
- 面板加载、自动停靠;
- 440 Hz 测试音在输入源与主输出频谱中均正确显示峰值频率(439 Hz)与幅度;
- 频谱/波形模式切换;
- 监听开关、音量同步、原生滤镜窗口均正常;
- 连续多次启动稳定性测试通过。
- 插件使用 Qt 6.10.3 开发包编译,依赖 Qt 6 的二进制向前兼容,在 OBS 自带的 Qt 6.11.1 下运行正常。
- 仅支持 64 位 OBS。