开源地址:https://github.com/hzl790209/volmon | 许可证:MIT | 参与贡献:CONTRIBUTING.md | 安全漏洞:SECURITY.md
volmon-mac 1.0.3(macOS 版,2026-09-27 定版;1.0 之后的行为增强,按 1.0.x 递增)—— 当前已打包发布版本
volmon 是一款跨平台开源的环境音量 / 噪音监控软件。通过电脑麦克风实时监控周边音量,提供 Web 实时页面 与 命令行终端 两种可视化形态,支持 专业设备校准、阈值预警、声音报警、分时段策略、触发录音、 超量监控日志 与 每日报警邮件推送。
目前提供 macOS / Windows / Android 三端:macOS 与 Windows 共用同一套 Python 后端(差异仅在入口与打包), Android 为原生 Kotlin 实现(复用 dB 算法与 Web 仪表盘思路)。
| 平台 | 状态 | 说明 |
|---|---|---|
| macOS | ✅ 已发布(volmon-mac 1.0.3,DMG 双击即用) | 桌面端主阵地,详见下文「安装(macOS)」 |
| Windows | ✅ 已发布(volmon-win 1.0.11,含 MSI 安装包) | 同一套 Python 后端;MSI 见 GitHub Release v1.0.11 |
| Android | 🧪 开发预览 | 原生 Kotlin + Compose,详见 volmon-android/ 目录与 音量监控软件_PRD.md |
| Web 面板 | ✅ 内置 | web/index.html 单体页面,WebSocket 实时推送,三端通用 |
麦克风 → AudioEngine(采集+RMS→dB+校准) → AlertManager(阈值/持续) → Storage(SQLite)
↓
WebSocket 广播 → Web 页面 / CLI 终端
详细日志 → data/volmon.log(按日切割)
cd 项目目录
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt若 sounddevice 报缺少 PortAudio,请安装 [Microsoft C++ 运行库] 与 [PortAudio]; 绝大多数情况下
pip install sounddevice自带可用后端。
产物:volmon-mac-1.0.3.dmg(约 23 MB,x86_64 / Intel Mac)
# 1) 双击 volmon-mac-1.0.dmg
# 2) 把 volmon-mac.app 拖到右边的 Applications 文件夹
# 3) 在启动台打开 volmon-mac —— 会自动开始监测并打开浏览器面板- 首次打开提示"来自身份不明的开发者":本包用的是 ad-hoc 签名(非正式开发者证书), 请 右键点击 app → 打开 → 确认 即可,之后就能正常双击。
- 麦克风权限:首次运行会弹窗请求,点「好」。若误点了「不允许」, 到「系统设置 → 隐私与安全性 → 麦克风」里把 volmon-mac 打开。
- app 没有独立窗口是正常的(服务在后台跑),看浏览器面板即可。
- 退出:用面板「服务控制」里的 ■ 停止服务(桌面版没有菜单栏,这是正常退出方式);
也可在「活动监视器」里结束
volmon-mac。
数据存放位置(刻意不写在 app 内部,卸载/升级 app 都不会丢):
~/Library/Application Support/volmon-mac/data/
config.json 配置(首次启动后在这里改,网页上改的也存这)
volmon.db 采样与告警数据
volmon.log 运行日志(按日切割,保留 30 天)
alerts.csv 告警 CSV(按日切割)
recordings/ 触发录音(按日分目录)
终端实时波形(可选):
/Applications/volmon-mac.app/Contents/MacOS/volmon-mac cli从源码重新打 DMG:
./build_dmg.sh # 产物 dist/volmon-mac.app + volmon-mac-1.0.3.dmg打包要点(改代码时别踩):
.app内部是只读的,所以新增的数据文件必须走volmon/paths.py(data_root()写用户目录,resource_path()读包内资源), 不能直接用__file__拼路径——否则打包后要么写不进去、要么破坏签名。
注意:
main.py必须带子命令。直接python main.py只会打印帮助并退出,不会启动。
最简:一键启动脚本(推荐)
# Windows:双击 start.bat,或命令行执行
start.bat
# macOS / Linux / 本沙箱:
./start.sh脚本会自动创建虚拟环境、安装依赖并启动服务。
volmon 命令(macOS/Linux,已安装到 ~/bin)——一条命令即可启动
volmon # 一键:后端服务没在跑就自动后台拉起 → 就绪后进入终端实时波形
volmon status # 看服务是否在跑(版本 / 采集设备 / 报警输出)
volmon start # 只启动后端服务
volmon stop # 停止后端服务
volmon restart # 重启后端服务
volmon web # 浏览器打开实时面板(服务没起会自动起)
volmon cli # 只进终端波形(服务没起会自动起)
volmon quiet 60 # 60 分钟内超阈值也不发声(监测与记录照常)
volmon quiet --cancel
volmon mail --send # 立即发送报警日报邮件以前不带参数只跑 CLI,服务没启动时等于什么都没发生(CLI 连不上后端)。 现在会自动探测
/api/health,没在跑就nohup后台拉起并等待就绪,再进入波形。 Ctrl-C 退出波形后服务仍在后台运行,要停请volmon stop。
手动(需先装依赖)
pip install -r requirements.txt
# 1) 启动后端服务(同时托管 Web 页面 + WebSocket 广播 + 落库)
python main.py serve
# 1b) 无麦克风演示/测试模式(用模拟音量,验证全栈无需真实声卡)
python main.py serve --fake
# 2) 浏览器打开实时面板(默认 http://127.0.0.1:8000)
python main.py web
# 3) 另开一个终端,看命令行实时波形 + 超量横幅
python main.py clipython main.py cli / volmon 在终端渲染带完整坐标轴的实时音量图,呈现方式与 Web 波形图一致:
音量监控终端 正常 [未校准(估算)]
当前: 28.3 dB (原始 -61.7 dBFS) 阈值: 70.0 峰值: 0.0
80 |
75 |
69 |------------------------------------------------------------- <=阈值70.0
64 |
58 |
53 |
47 |
42 |
36 |
31 |*
25 |
20 |
-------------------------------------------------------------
13:01:13 13:01:13 13:01:13 现在
纵轴=音量 dB (20~80) 横轴=时间 红色行=预警阈值 70.0 dB
- 纵轴 = 音量 dB(自适应刻度,含阈值,最小跨度 30dB);横轴 = 时间(左起点 / 中 / 右
现在) - 红色
-行 = 预警阈值;*为采样点,|为纵向连线 - 顶部状态条:报警播放中(静默) / 冷却中(静默) / 超量告警! / 超阈值 / 正常
- 图表尺寸随终端窗口自适应;全 ASCII 字符,任意终端下不错位
- 用专业噪音仪测得当前环境真实 dB(例如 65.0)。
- 保持环境稳定,在 Web 校准面板输入
65.0并点「一键校准」;或命令行:python main.py calibrate 65.0
- 此后软件读数 = 原始值 + 偏移,与专业设备一致。可随时重新校准。
关于"未校准时显示负数":麦克风算出的是 dBFS(满刻度=0,真实声音恒为负,如 -46), 直接显示会看到负值。软件已按
dB SPL ≈ dBFS + 90换算成估算声压级(界面标注「未校准(估算)」), 典型映射:-46→44 dB(安静房间)、-30→60 dB(正常交谈)、-10→80 dB(嘈杂)。 90 是通用估计值;用专业设备「一键校准」后即为真实 dB SPL。若你的麦克风灵敏度特殊, 可调ref_spl_offset_db:python main.py config set ref_spl_offset_db 95
- Web 页面「预警设置」面板直接修改并保存(阈值、持续时长、采集/落库频率、输入设备)。
- 或命令行:
python main.py config set threshold_db 70
- Web 页面「音量报警」面板勾选「开启音量报警」即可:音量持续超阈值后,电脑扬声器播放 "嘀—嘀—"报警声(默认 10s),提示现场人员。
- 报警声会被本机麦克风拾回,因此播放期间 + 结束后冷却期(默认共 15s)内,噪声监测整体静默: 不写入采样、也不触发噪声超量告警,避免报警声被误记为噪音、造成自激;冷却结束后自动恢复检测。
- 可调参数:
alarm_enabled(开关)、alarm_duration_sec(报警时长,默认 10)、alarm_cooldown_sec(冷却秒数,默认 5)。 - 命令行:
python main.py config set alarm_enabled true - 听不到声音? 先用「🔊 试听报警音」按钮(或
curl http://127.0.0.1:8000/api/alarm/test)验证扬声器与播放器是否正常。 注意:报警只在音量持续超过阈值时触发(不是开启就响);且改动代码后必须重启服务才会生效。 另:serve --fake演示模式不发声。
- Web「音量报警」面板的报警声输出设备下拉里选,改完立即生效,无需重启。
- 选完点「🔊 试听报警音」就能确认声音是不是从你想的那一路出来。
- 命令行:
python main.py config set alarm_output_device "HECATE GM400"(设为空串 = 系统默认输出)。 - 插拔耳机后列表没更新?点下拉下方的「🔄 刷新输出设备列表」。
- 改了输入设备会立即生效,不需要重启服务(2.7.0 起):在服务广播循环里检测到配置变化后, 自动停流 → 换设备 → 重启采集流(100ms 内完成);若新设备打不开会自动回滚到原设备继续采集。
- 怎么确认到底在用哪个麦克风? 「实时音量」面板有一行
采集设备:HECATE GM400(索引 0 · 44100Hz),显示的是采集流真正打开的设备; 若与你所选的不一致会红字告警。也可curl http://127.0.0.1:8000/api/status查看。 - 插了 USB 声卡/耳机但列表里没有新设备? 不是权限问题——PortAudio 在进程内只在启动时枚举一次 音频设备,之后插上的设备不会自动出现。点「预警设置 → 🔄 刷新输入设备列表」即可(会中断采集约 1 秒), 不需要重启服务。
- 若读数恒为 -100 dBFS(页面/终端红字提示「麦克风持续静音」),多半是 PortAudio 默认输入设备 指向了虚拟声卡或已拔出的设备。更多排查见下方「输入设备选不对会一直静音」。
每个版本都会在页面标题栏显示版本徽章(如 v2.6.0),并同步写入浏览器标签标题
(音量监控 · 实时面板 v2.6.0)。目的是一眼确认「改完代码是否已重启生效」——
若页面版本与你刚改的代码版本不一致,说明服务还跑着旧进程,点「⟳ 重启服务」即可。
取值唯一来源为 volmon/__init__.py 的 __version__,页面不硬编码;
WebSocket 未连上时会自动从 /api/health 兜底取。终端 CLI 状态条同样显示 v2.6.0。
右栏顶部「当前生效策略」面板,一张表列出此刻真正生效的一整套策略:
| 项 | 内容 |
|---|---|
| 策略来源 | 全局设置 / 分时段·白天 / 分时段·晚间 |
| 当前时段 | 白天(距切换约 7 小时 18 分) |
| 时段区间 | 白天 07:00 |
| 预警阈值 | 70 dB(需持续 3 s) |
| 声音报警 | 开启 · 响 10 s(冷却 5 s)/ 关闭 |
| 报警输出 | USB 耳机 / 系统默认输出设备 |
| 报警静音 | 生效中 · 剩余 45:12 / 未启用 |
| 采集设备 | HECATE GM400(索引 0) |
| 校准状态 | 已校准 11.16 dB / 未校准(估算) |
| 日志条数 | 采样 N 条 / 超量告警 M 条 |
每 20 秒自动刷新,也可点「刷新」。命令行:python main.py policy。
右栏「日志维护(清空)」面板:
- 清空范围:采样 + 超量告警 / 仅采样记录 / 仅超量告警
- 时间范围:全部(一键清空)/ 近 1 小时 / 近 24 小时 / 近 7 天 / 自定义起止时间
- 清空告警后会同步重写本地
data/alerts.csv,不会出现"库里没了、CSV 里还在"。 - 命令行:
python main.py clear --all # 一键清空全部(会二次确认) python main.py clear --hours 24 # 只清近 24 小时 python main.py clear --start "2026-09-27 00:00" --end "2026-09-27 12:00" python main.py clear --scope alerts --hours 24 # 只清超量告警 python main.py clear --all --yes # 跳过确认
- 对应接口
POST /api/logs/clear,参数{"all":true}/{"hours":N}/{"start_ts":ms,"end_ts":ms}+{"scope":"all|samples|alerts"}。 - 按时间段清空时,对应日期的归档 CSV 也会同步重写,不会出现"库里没了、归档 CSV 里还在"。
在页面右栏「触发录音」面板打开开关即可。默认关闭(涉及录音,请自行确认后开启)。
为什么不会漏掉开头? 声音往往很短(敲门、喊叫、器物掉落),而从"发声 → 算 dB → 判超阈值 → 判持续时长 → 打开文件准备写入"这条链路有延迟,等报警了才开始录必然缺开头。 所以这里用的是常驻环形缓冲 + 前置录音:
时间轴 ──────────────────────────────────────────────►
声音: ▁▂▅█▇▅▂▁ (只有 0.3 秒)
↑
缓冲: [一直在滚动保留最近 5 秒……][触发点][继续录 5 秒……]
└── 前置(内存里倒出来)──┘ └── 后置 ──┘
文件: ┕━━━━━━━━━━ 完整一段,开头不缺 ━━━━━━━━━━┙
- 采集流一直在跑,最近若干秒的原始音频始终留在内存(约 1.8 MB,开销可忽略)
- 触发瞬间直接把"触发前"那段取出来,再接着录"触发后",拼成完整一段 WAV
- 触发链路再慢、声音再短,开头都不会缺
| 配置项 | 默认 | 说明 |
|---|---|---|
rec_enabled |
false | 总开关(默认关闭) |
rec_trigger |
alert | alert=正式报警(推荐,误录最少);over=刚超阈值(最早但可能较多) |
rec_pre_sec / rec_post_sec |
5 / 5 | 触发前保留 / 触发后继续录的秒数 |
rec_keep_days / rec_max_files / rec_max_mb |
30 / 500 / 2048 | 保留天数 / 最多文件数 / 总大小上限,超出自动删最旧的 |
rec_dir |
data/recordings | 存放目录(内部按日分子目录) |
rec_cut_on_alarm |
true | 开启声音报警时,报警一触发就把正在录的这段截断在触发瞬间(仅留触发前音频,绝不录报警声,见下) |
- 回放:超量告警表格新增「录音」列,点 ▶ 播放 即可试听或下载;
alerts表与 CSV 也增加了audio_file列 - 命令行:
python main.py rec(看状态)/--list(列文件)/--prune(立即清理)
报警声是本机扬声器放出去的,会被同一台电脑的麦克风原样拾回——录进 WAV 就是一段刺耳的 "嘀嘀"声,把真实环境音盖掉。软件没法把两个混在一起的声音再分开,所以采取最干脆也最可靠 的办法:报警声是从触发点才响起来的,那报警一触发,立刻把录音"定格"在触发瞬间,触发之后的声音一个字节都不写。
报警触发瞬间
│
▼
──┴────────── 前置段(触发前,真实环境音)────────────┐
│ ┝━ 这一份写进 WAV(完整)
麦克风 ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁░░░░░░░░
└ 触发点之后的报警声(本机外放)── 直接丢弃,永不写入
-
前置段照留:触发前那段环形缓冲里的真实环境声照常保留、写入 WAV(报警声那时还没响,本来就是干净的)
-
触发点之后一刀切:报警一旦触发,所有"正在录"的任务立刻标记为"已截断",只等把已有前置段写盘即收工, 报警声(以及之后其它声音)一律不进文件
-
面板上会显示 ✂ 报警触发即截断;保存的录音会标注"报警触发·已截断(仅含触发前音频)"
-
这是与"跳过污染窗口"不同的更可靠方案:不再计算"报警响多久"去雕刻录音,而是直接从触发点切断, 因此无论报警时长、冷却怎么设,报警声物理上不可能出现在录音里
-
已知限制:
- 服务刚启动的头几秒缓冲还在填充,这时的录音"前置段"会短一些,运行片刻后即稳定
- 开着声音报警时,录音会在触发点结束(不含报警后声音)——这是预期行为,目的是保护录音不被报警声污染
- 从根本上避免串扰,还是建议报警输出接耳机(或外接音箱远离麦克风), 这样触发点之后也能录到连续完整的真实声音
- 演示模式(
--fake)录到的是合成噪声,不是真实声音
右栏「每日报警邮件」面板:填好 SMTP 与收件人后,软件每天自动把前一天的报警日志发一封邮件。
-
邮件内容:超量次数 / 峰值 dB 及发生时刻 / 平均峰值 / 累计超标时长 / 最长一次 / 时段分布(白天·晚间)/ 阈值分布 / 开启声音报警的次数 / 明细表(最多 50 条); 正文有 HTML 与纯文本两种,可选附带当天告警 CSV 附件。
-
发送时机:每天
mail_send_time(默认 09:00)自动发一次,报表范围默认昨天全天 (可改成"今天 00:00 起")。服务当天启动晚了会补发一次,同一天不会重复发; 发送失败当天最多重试 3 次。 -
配置(页面填写即可):
项 说明 每天自动发送 总开关 SMTP 服务器 / 端口 / 加密 内置 QQ / 163 / Gmail / Outlook / 腾讯企业邮 一键填入 发件邮箱账号 如 123456@qq.com授权码 不是登录密码,需在邮箱设置里开启 SMTP 后生成 收件人 多个用英文逗号分隔;留空则发给自己 报表范围 / 发送时间 昨天全天(默认)/ 今天起;默认 09:00 附带 CSV / 无告警时不发 是否带附件;无告警时是否跳过(默认仍发"平安信") -
先预览再发:点「预览报表」会在新窗口打开邮件正文;确认无误再点「立即发送测试邮件」。
-
命令行:
python main.py mail # 查看当前邮件配置与最近发送结果 python main.py mail --preview # 预览报表(不发送) python main.py mail --send # 立即发送昨天日报 python main.py mail --send --day 2026-09-26 # 补发指定日期 python main.py config set mail_to you@example.com
-
接口:
GET /api/mail、POST /api/mail/send({"dry_run":true}预览 /{"day":"..."}补发)。 -
安全:密码请填授权码;接口返回给页面的密码一律脱敏为
●●●●●●。
右栏「日志文件(按日切割)」面板可看到每类日志的今天文件与各天归档(含大小), 并可调整「按日切割」开关与「保留天数」(0 = 永不删除)。命名规则:
| 日志 | 当前文件(今天) | 归档文件 |
|---|---|---|
| 运行日志 | data/volmon.log |
data/volmon_2026-09-26.log |
| 超量告警 CSV | data/alerts.csv |
data/alerts_2026-09-26.csv |
| 重启日志 | data/restart.log |
data/restart_2026-09-26.log |
| 采样数据 | data/volmon.db(单库不切割,用「日志维护」清理) |
— |
- 跨天后的第一次写日志/写告警自动切割;服务启动时也会把"昨天遗留的当前文件"归位, 保证当前文件里只有今天的内容
- 超过
log_keep_days(默认 30)天的归档自动删除 - 命令行:
python main.py logs --files # 查看日志文件清单(当前 + 归档) python main.py logs --rotate # 立刻切割一次(只在真跨日时动) python main.py logs --rotate --force # 强制归档当前文件 python main.py config set log_keep_days 60
- 对应接口
GET /api/logs/files、POST /api/logs/rotate({"force":true})
每条超量告警都会记下当时的策略,便于事后追溯"那次报警用的是哪套阈值、报警开没开":
- 新增列:
period(白天/晚间)、schedule_applied(是否分时段)、alarm_enabled(是否启用声音报警)、alarm_duration_s、alarm_cooldown_s - Web「超量告警日志」表格新增「时段/策略」「声音报警」两列
- 本地
data/alerts.csv同样包含这些列(Excel 可直接看) - 文本日志示例:
超量片段结束 | 峰值=62.5 dB | 阈值=55.0 | 持续=4.0 s | 策略=晚间(分时段) | 声音报警=开 10s
白天和晚间用不同的管理策略。Web「分时段策略(白天 / 晚间)」面板:
-
勾选启用分时段策略(默认关闭,关闭时沿用全局阈值与报警设置)。
-
两个时段各自设置起止时刻,支持跨零点(例如晚间
22:00 → 07:00)。 -
每个时段可独立设置:
项目 说明 阈值 (dB) 该时段超多少 dB 算超量 持续 (秒) 需连续超多久才判定为告警(避免瞬时误报) 报警开关 该时段超阈值时是否发声报警 报警时长 / 冷却 该时段的报警声持续秒数与结束后冷却秒数 -
改动立即生效,无需保存或重启。面板底部实时显示:
当前:白天(分时段已启用) 生效阈值 70 dB · 持续 3s · 报警 关 | 距切换约 7 小时 30 分 -
典型用法:白天
70 dB只记录不报警(白天本来就有各种声响),晚间55 dB且开启报警。 -
两个时段若没覆盖满 24 小时,会黄字提示「有 N 分钟空档 / N 分钟重叠」;空档按白天策略执行。
-
命令行:
python main.py schedule # 查看当前时段与生效策略 python main.py schedule night_threshold_db 55 # 设置晚间阈值 python main.py schedule night_start 22:00 # 设置晚间开始时刻 python main.py schedule day_alarm_enabled false # 白天不发声报警
可选键:
schedule_enabled、day_start/day_end、night_start/night_end、day_threshold_db/night_threshold_db、day_sustain_sec/night_sustain_sec、day_alarm_enabled/night_alarm_enabled、day_alarm_duration_sec/night_alarm_duration_sec、day_alarm_cooldown_sec/night_alarm_cooldown_sec。 -
分时段只覆盖阈值与报警策略;报警声输出设备、报警静音时段仍是全局的。
布置好环境后你要走开,脚步声/说话声会不停触发报警——用这个功能:设一段时间后, 该时段内超阈值也不发声,到期自动恢复,也可随时手动取消。
-
Web「报警静音时段」面板:静音 30 分钟 / 1 小时 / 2 小时 快捷按钮,或填自定义分钟数, 另有「▶ 取消静音」立即恢复发声。面板实时显示剩余倒计时。
-
命令行:
python main.py quiet 60 # 静音 60 分钟 python main.py quiet # 查看当前静音状态与剩余时间 python main.py quiet --cancel # 取消静音,立即恢复发声
-
与"报警后自激静默"的区别(重要):
场景 发声 采样落库 超量告警记录 报警播放中 + 冷却期 正在响 ❌ 暂停 ❌ 暂停 报警静音时段 ❌ 不响 ✅ 照常 ✅ 照常 即:静音时段只是不响,不会丢数据,你回来后仍能在超量日志里查到期间的超量事件。
-
配置
quiet_until_ms(截止时刻 epoch 毫秒,0 = 未静音);「恢复默认设置」会一并清除静音。
- ↺ 恢复默认设置:把阈值/校准偏移/报警/输入设备等全部还原为出厂默认值。
- ⟳ 重启服务:派生接替进程并以相同参数重启(用于更换输入设备或改代码后生效),约 2 秒后刷新页面。
- 若读数恒为 -100 dBFS(页面/终端会红字提示「麦克风持续静音」),多半是 PortAudio 默认输入设备指向了 虚拟声卡或已拔出的设备(如 iPhone continuity 麦克风),并非麦克风权限问题。
- 处理:在「预警设置 → 输入设备」下拉里换成有信号的设备(可用
python -c "import sounddevice as sd; print(sd.query_devices())"查看), 保存后点「⟳ 重启服务」生效。
python main.py logs --hours 24 # 查看近 24h 超量事件
python main.py logs --hours 24 --export data/export.csv # 导出采样为 CSV
python main.py logs --hours 24 --export-alerts data/alerts_x.csv # 导出超量告警为 CSVWeb 面板:「超量告警日志」每页 100 条,可用「上一页 / 下一页」翻页,超出部分不会丢弃。
本地日志文件(按日切割,方便用工具查看)
data/alerts.csv:每条超量告警实时追加写入今天的告警,含start_time, end_time, peak_db, threshold_db, duration_s与策略列,UTF-8 BOM 编码, Excel / Numbers / 文本编辑器双击即可打开。跨日自动归档为data/alerts_YYYY-MM-DD.csv。data/volmon.db:SQLite 完整数据(samples + alerts),可用 DB 工具查询。不切割,单库保存。data/volmon.log:运行事件日志(启动、配置变更、校准、超量片段结束等), 跨日自动归档为data/volmon_YYYY-MM-DD.log。- 超过
log_keep_days(默认 30 天)的归档自动删除。详见「日志按日切割与保留」。
data/config.json(自动生成):
| 键 | 默认 | 说明 |
|---|---|---|
| threshold_db | 70 | 预警阈值(校准后 dB) |
| sustain_sec | 3 | 持续超过多久才触发告警 |
| sample_interval_ms | 100 | 实时广播间隔 |
| log_interval_ms | 1000 | 采样落库频率(后台详细日志采样率) |
| calib_offset_db | 0 | 校准偏移 |
| device | default | 输入设备 |
| alarm_enabled | false | 是否开启音量报警(电脑发声) |
| alarm_duration_sec | 10 | 单次报警声持续秒数 |
| alarm_cooldown_sec | 5 | 报警结束后冷却秒数(期间仍静默) |
| alarm_output_device | "" | 报警声输出设备名(空=系统默认输出) |
| quiet_until_ms | 0 | 报警静音截止时刻(epoch ms,0=未静音) |
| db_path / log_path | data/... | 数据库 / 文本日志路径 |
| log_rotate_daily | true | 运行日志与告警 CSV 是否按日切割 |
| log_keep_days | 30 | 归档文件保留天数(0 = 永不删除) |
| mail_enabled | false | 是否每天自动发送报警日报邮件 |
| mail_host / mail_port | smtp.qq.com / 465 | SMTP 服务器与端口(587 配 mail_starttls) |
| mail_user / mail_password | "" | 发件邮箱与授权码(非登录密码) |
| mail_to | "" | 收件人,多个用逗号分隔(留空发给自己) |
| mail_send_time / mail_day_offset | 09:00 / 1 | 每天发送时刻 / 报表范围(1=昨天,0=今天) |
| mail_attach_csv / mail_skip_if_empty | true / false | 带 CSV 附件 / 无告警时跳过 |
| rec_enabled | false | 是否录制触发报警时的真实声音(默认关闭) |
| rec_trigger | alert | alert=正式报警时录 / over=刚超阈值时录 |
| rec_pre_sec / rec_post_sec | 5 / 5 | 触发前保留 / 触发后继续录的秒数(前置由环形缓冲提供) |
| rec_keep_days / rec_max_files / rec_max_mb | 30 / 500 / 2048 | 录音保留天数 / 文件数上限 / 总大小上限 MB |
data/volmon.db:采样表(samples)+ 超量告警表(alerts)。单库,不按日切割。data/volmon.log:启动、配置变更、校准、超量片段结束等详细事件日志(按日切割)。data/alerts.csv:超量告警 CSV,按日切割为alerts_YYYY-MM-DD.csv。
- 读数经校准后接近真实声压级;未校准时为相对值,仅供趋势参考。
- 仅保存数值,不录制/上传任何音频内容,保护隐私。
- 需在系统/浏览器中授权麦克风权限。
- 读数恒为一条直线 / 显示 -100 dBFS? 这通常是麦克风未授权(macOS 会允许打开音频流但送进全零数据)。
页面与终端会显示红色告警「麦克风持续静音」。处理:系统设置 → 隐私与安全性 → 麦克风,
给运行服务的终端(Terminal/iTerm)开启权限,然后用该终端重启服务
(
volmon serve)。恢复读数后务必重新校准——在静音状态下做的校准结果无效。
同一份代码可编译出 Windows 版(产品名 volmon-win),无需重写业务逻辑。平台差异(数据目录、入口、打包、后台服务管理)已抽象在少量专属文件中:
MSI 安装包已发布:Windows 版安装包
volmon-win-x64.msi(v1.0.11)已上传至 GitHub Release v1.0.11,双击即装。仓库也含完整源码,可源码运行(start.bat/volmon.bat)或自行构建便携 EXE(build_win.bat)。
- 一键命令:
volmon.bat(对应 macOS 的volmon) - 桌面入口:
winapp.py(对应macapp.py);打包配置:volmon-win.spec - 跨平台启动器:
volmon/launcher.py(start/stop/restart/status/web/cli) - 路径分流:
volmon/paths.py(%APPDATA%/volmon-win);产品名:volmon/__init__.py
详见 WINDOWS.md(环境准备、运行、打包 .exe、已知坑)。
- 许可证:MIT —— 可自由使用、修改、再分发,仅需保留版权声明。
- 参与贡献:欢迎提交 Issue 与 Pull Request,详见 CONTRIBUTING.md。
- 安全漏洞:请通过 GitHub 的 Security 私报告知,勿在公开 Issue 披露,详见 SECURITY.md。
- 需求与设计:音量监控软件_PRD.md(产品需求)、音量监控软件开发规范.md(开发规范)。
volmon 以 MIT 协议开源,由社区共同维护。如果使用对你有帮助,欢迎 Star ⭐ 与分享。