企业官网建设流程全解析

local-deep-research 通知声音配置指南：success.mp3 与 error.mp3 的职责、选材与触发机制

【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research

在 local-deep-research 的 Web 界面中，当一次深度研究任务在后台跑完时，系统会通过声音提醒用户"研究已完成"或"研究出错"。这些提示音的来源、命名约定与播放策略，由 src/local_deep_research/web/static/sounds/README.md 统一定义。本文以该文档为主体，结合仓库前端的实际引用与实现现状，完整讲解通知声音文件的安装、替换、触发时机与浏览器播放限制，帮助你在部署和使用中正确配置提示音。

通知声音的职责划分：success.mp3 与 error.mp3

声音目录位于src/local_deep_research/web/static/sounds/，其中必须存在两个固定的声音文件，各司其职：

通过 list 实际确认，当前仓库中这两个文件均已就位：

• src/local_deep_research/web/static/sounds/success.mp3
• src/local_deep_research/web/static/sounds/error.mp3

之所以采用"固定文件名 + 固定语义"的设计，而不是在业务代码中内嵌任意音频路径，是因为前端页面通过静态资源路径直接引用这些文件，文件名即接口。任何第三方音效只要重命名覆盖到这两个位置，即可无缝替换提示音，无需改动一行业务代码。

声音素材的来源与选型

原文档给出了两个免版权（copyright-free）音效素材渠道，用于获取可合法用于项目的声音文件：

• Freesound：一个大型的社区音效共享平台，提供海量 CC 许可的短音效，搜索关键词建议使用success sound、error sound、notification等。
• Free Sound Library：另一个免版权音效库，适合快速检索短促提示音。

同时文档给出了两份经过筛选的推荐素材（均来自 Freesound，素材名与其创作者信息可在平台内检索）：

• 成功音效：Success Sound，创作者 grunz（素材编号 109662），适合作为研究完成的提示音——短促、轻快、不刺耳。
• 错误音效：Error Sound，创作者 Autistic Lucario（素材编号 142608），适合作为失败告警音——低沉、明确、具有警示性。

选择第三方音效时需注意两点：其一，确认素材的许可协议允许在商业/自部署应用中使用（CC0 或注明署名的 CC-BY 均可）；其二，优先选择时长在 0.5～2 秒内的短音效，避免打断用户操作。若不想引入第三方素材，也可以自行用本地工具合成一段简单的双音/三音提示音导出为 MP3，同样满足需求。

触发时机与"标签页不在焦点"的播放策略

原文档明确了这套声音机制的核心使用规则：

应用会在研究任务完成或失败时自动播放这些声音，但仅当浏览器标签页不在焦点时。

这句话包含两层设计意图：

1. 触发时机绑定研究任务终态。研究任务结束分为两种终态：成功（complete）与失败（error/fail），分别对应success.mp3与error.mp3。在前端进度页中，这一"完成/失败"判定逻辑可见于 src/local_deep_research/web/static/js/components/progress.js：任务完成时会调用showNotification('Research Completed', ...)推送结果提醒（约第 678 行），失败分支则会尝试展示错误报告——声音播放正是与这类终态通知同步触发的。

2. 只在后台播放，避免打扰前台用户。当用户正盯着进度页时，视觉上的进度条、状态文本已经足够传达信息，此时再播放声音反而冗余；只有当用户切走标签页、任务在后台默默推进时才需要"声音唤醒"。这一设计与浏览器自动播放策略（Autoplay Policy）天然契合：

• 现代浏览器默认禁止未经用户交互的音频自动播放，而"用户在页面内有过点击操作"即可被视为已交互；
• 标签页处于后台（不可见）时，浏览器对音频播放的容忍度更高，声音得以正常输出；
• 前端判断标签页可见性通常使用document.hidden/visibilitychange，可据此决定是否触发播放。

因此，这套机制在实现上是"状态机 + 可见性"的组合：研究任务到达终态 → 判断标签页是否在前台 → 前台则静默更新 UI，后台则播放对应提示音。

前端实现现状与预留接口（源码证据）

值得注意的是，仓库当前的音频服务实现仍处于"预留接口"阶段。前端音频服务模块 src/local_deep_research/web/static/js/services/audio.js 目前是一个占位实现（Audio Service Stub），它在window.audio上暴露了四个接口：

从源码结构看，这套接口是为未来的完整通知功能预留的稳定契约：页面无需关心声音文件路径与播放细节，只要调用window.audio.playSuccess()/window.audio.playError()即可。该模块已被两个页面引用：

• src/local_deep_research/web/templates/pages/progress.html#L59：研究进度页，即声音触发的主战场；
• src/local_deep_research/web/templates/pages/benchmark.html#L2561：基准测试页，测试任务批量跑完时同样需要完成/失败提醒。

也就是说：声音文件本身（success.mp3 / error.mp3）已随仓库就绪，调用契约（window.audio 接口）已定义，真正的播放逻辑将在 audio.js 的未来版本中实现。部署方若需要立即获得提示音能力，可参照上述接口自行补齐playSuccess内部实现（例如new Audio('/static/sounds/success.mp3').play()），并接入progress.js的完成/失败分支。

自定义声音的实践建议

基于原文档的命名约定与浏览器兼容性要求，替换或定制提示音时请遵循以下规范：

1. 文件命名必须保持原样：仅接受success.mp3与error.mp3两个文件名，扩展名统一为.mp3（浏览器原生支持、体积小、兼容性最好）。
2. 覆盖式替换即可生效：将自备音效处理后放到 src/local_deep_research/web/static/sounds/ 目录覆盖同名文件，无需修改任何前端代码；静态资源加载后可强制刷新（Ctrl/Cmd + Shift + R）清除浏览器缓存验证效果。
3. 控制时长与响度：建议单段提示音不超过 2 秒、响度峰值保持在 -3dB 以下，避免与研究完成后的页面跳转音叠加造成惊吓。
4. 语义要可区分：success.mp3与error.mp3应在音色、音高上明显不同（如上行双音 vs 下行低音），确保用户无需看屏幕即可辨别结果好坏。
5. 留意浏览器策略：由于自动播放受浏览器策略约束，若在部署环境中发现声音不响，优先检查用户是否已在页面内完成过至少一次交互，以及标签页是否确实处于后台。

小结与相关资源

通知声音是 local-deep-research 后台研究体验的重要一环：success.mp3与error.mp3分别承载成功与失败的听觉反馈，仅在浏览器标签页失焦时播放的设计兼顾了信息传达与不打扰。声音文件、目录约定与素材来源已由 声音目录 README 完整定义，前端接口由 audio.js 预留，播放时机与完成/失败判定则锚定在 progress.js 的通知逻辑中。读者如需进一步了解研究任务的完成/失败状态流转与页面结构，可继续阅读 progress.html 与前端进度组件实现。

【免费下载链接】local-deep-research~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.项目地址: https://gitcode.com/GitHub_Trending/lo/local-deep-research