obs-profanity-filter 是一个为 OBS Studio 开发的高级音频插件，旨在直播过程中实时检测并屏蔽脏话。

• 预读屏蔽: 延迟输出，播出前替换为静音、哔声或多种特效（小黄人、电报等）。
• 离线识别: Sherpa-ONNX，本地运行、低资源占用。
• 一键模型与全局配置: 工具菜单统一管理模型、词库、延迟。
• 拼音增强匹配: 忽略声调与常见模糊音，提升中文命中率。
• 可定制: 词库/正则、音效选择、调试控制台。

• 打开：工具 → 语音脏话屏蔽配置
• 模型：选择/一键下载，或自定义路径
• 延迟：设置 ≥300ms（推荐 500ms），可开启“音画同步缓冲”
• 词库与音效：按需配置，最后点击“保存并应用”

展开全局配置截图

• 为所有音频轨道添加：右键音源 → 滤镜 → + → 语音脏话屏蔽。
• 必须为所有音频轨道添加后，再按音源决定是否开启过滤；例如仅开启麦克风过滤，其他轨道关闭过滤但保留延迟以保持同步。
• 自测：在混音器的 高级音频设置 中设为 仅监听 或 监听并输出。

展开音频滤镜截图

• 启用“音画同步缓冲”后自动为所有场景添加同步滤镜并按延迟同步视频，无需手动“渲染延迟”。
• 需要手动控制时可关闭该开关后自行添加“渲染延迟”。
• ⚠️ 延迟越大显存占用越高；未激活场景会自动释放显存。

展开场景滤镜截图

完整更新历史请查看 CHANGELOG.md

• 功能新增:
  • 音频处理: 添加自动增益控制 (AGC) 功能。
  • 模型管理: 增加模型延迟补偿与自动应用预设。
  • 脏词过滤: 重构过滤系统，引入内置词库与密码模式。
  • 界面与状态: 增加模型状态显示与全局状态管理。
  • 模型维护: 支持删除已安装模型并更新默认列表。
• 重大变更:
  • 移除日志文件记录功能及相关 UI/配置项。

• 功能新增:
  • 模型管理: 添加模型自动下载与管理功能，支持在设置界面一键下载并自动配置推荐模型。

• 功能新增:
  • 多种屏蔽音效: 新增四种屏蔽音效（标准哔声、静音、小黄人音效、电报音效）。
  • 喜剧模式: 优先屏蔽短词实现趣味变声效果，增强直播互动性。
• 改进:
  • 支持音效预览与原始音频缓存，提升配置体验。
  • 优化匹配算法，减少误屏蔽，并支持不同优先级策略。
• 重大变更:
  • 移除旧的“哔声频率”和“混合比例”设置项，配置界面已简化。请在设置中改用新的音效类型选择。

如果您是开发者并希望自行修改代码，请遵循以下步骤。

• 操作系统: Windows 10/11 (x64)
• 编译器: Visual Studio 2022 (MSVC) - 需支持 C++20
• 构建工具: CMake 3.28 或更高版本
• 依赖库:
  • Qt 6 (用于配置界面)
  • libobs (OBS 核心库)
  • obs-frontend-api (OBS 前端接口)

1. 克隆仓库:

   # 务必使用 --recursive 参数以拉取 cpp-pinyin 子模块
   git clone --recursive https://github.com/Cloud370/obs-profanity-filter.git
   cd obs-profanity-filter
   
   # 如果已经克隆但没有子模块:
   # git submodule update --init --recursive

2. 配置项目:

   # 确保 Qt6 在您的环境变量中，或者通过 CMAKE_PREFIX_PATH 指定
   cmake -B build -G "Visual Studio 17 2022" -A x64

   CMake 会自动从 HuggingFace 下载 Sherpa-ONNX 依赖库。

3. 编译:

   cmake --build build --config Release

4. 安装: 编译完成后，生成的 DLL 文件位于 build/Release/。将它们复制到 OBS 插件目录进行测试。

5. 制作安装包 (可选): 如果您想生成 Windows 安装程序 (.exe)，请运行项目根目录下的 PowerShell 脚本：

   .\Make-Installer.ps1

   该脚本会自动检测环境、编译 Release 版本并生成 InnoSetup 安装包。 需预先安装 Inno Setup 6

本插件采用了 "延迟+回溯" (Delay & Backtrack) 的架构设计：

1. 环形缓冲区 (Circular Buffer): 插件维护一个巨大的音频缓冲区，所有输入的麦克风声音都会先进入这个缓冲区。
2. 异步识别 (Async ASR): 独立的后台线程从缓冲区获取最新的音频数据，送入 Sherpa-ONNX 引擎进行识别。
3. 延迟回放: OBS 从插件获取的音频数据并非“当前”的声音，而是 1 秒之前 的声音。
4. 时间戳映射: 当 ASR 识别出脏话时，插件会计算该脏话在原始音频流中的精确时间戳。由于输出有 1 秒 的延迟，这段脏话的音频数据此刻 仍然在缓冲区中等待播放。
5. 即时修改: 插件直接定位到缓冲区中的对应位置，将脏话片段的数据抹除（置零或替换为正弦波），从而在声音播出前完成“净化”。

• 安装后没有任何效果

  • 在每个需要处理的音频源上添加滤镜：右键音频源 → 滤镜 → 语音脏话屏蔽 (Profanity Filter)。
  • 必须为所有音频轨道添加滤镜（麦克风、桌面音频、虚拟设备、应用音频捕获等），后续可在滤镜属性中关闭某些轨道的过滤，仅保留延迟。
  • 打开 工具 → 语音脏话屏蔽配置，确认“启用全局脏话过滤功能”已开启且模型已正确安装或路径有效。

• 添加滤镜后没有声音

  • 全局延迟设置过大会造成明显监听延迟，建议 500ms，最低不要低于 300ms。
  • 在混音器的 高级音频设置 中，将需要验证的音源设置为 仅监听 或 监听并输出 以便自测。
  • 如仍无声，检查模型是否加载成功，并查看调试日志是否有错误。

• 检测不到脏话或屏蔽不生效

  • 确认模型文件完整且路径正确；首选使用内置的“一键下载模型”。
  • 屏蔽词需包含目标词或使用正则表达式，支持中英混合与拼音匹配。
  • 开启“拼音增强识别”可提高短词与口语化表达的命中率。
  • 延迟过短会导致来不及替换，确保延迟≥300ms（推荐 500ms）。

• 音画不同步

  • 启用“音画同步缓冲”后会自动为所有场景添加 语音屏蔽-音画同步 滤镜，并按“全局延迟时间”同步视频，无需手动添加 渲染延迟。
  • 如需手动控制，可在配置中关闭自动同步，然后按需为场景添加 渲染延迟 滤镜。
  • ⚠️ 若“延迟对不上”，通常是因为并未为所有音频轨道添加本插件的音频滤镜。请确保麦克风、桌面音频、虚拟设备、应用音频捕获等全部轨道都已添加滤镜。

• 显存占用高

  • 视频同步的显存与分辨率、帧率、延迟成正比。降低延迟或分辨率/帧率可显著减少显存占用。
  • 配置窗口会显示“当前音画同步显存占用”；场景未激活时滤镜会自动释放显存。

• 模型下载失败或速度慢

  • 检查网络与代理设置；可换用备用下载源或离线手动安装。
  • 手动安装：下载模型压缩包后解压到固定目录，确保包含 tokens.txt, encoder.onnx, decoder.onnx, joiner.onnx 等文件，并在配置中指向该目录。

• 多音轨管理与选择性过滤

  • 所有音频轨道均应添加插件滤镜以保证同步与可控性；需要关闭过滤的轨道可在滤镜属性中关闭，仅保留延迟。

• 自定义屏蔽词与正则

  • 支持中文/英文/拼音；可使用正则增强匹配能力（如处理变体与空格）。
  • 建议先用简洁词表验证效果，再逐步加入正则以避免过度匹配。

• 性能与资源占用

  • 语音识别在 CPU 上运行，视频同步占用 GPU 显存；在资源有限的机器上可降低延迟或关闭自动视频同步以节省显存。
  • 关闭调试控制台与不必要的后台程序可减少干扰并提升稳定性。

• Sherpa-ONNX: 强大的开源语音识别框架。
• cpp-pinyin: 高效的中文拼音转换库。