Skip to content
hzl790209Public

About

跨平台音量/噪音监控软件:麦克风实时监测、Web+CLI 可视化、专业校准、阈值预警、声音报警、分时段策略、触发录音、每日报警邮件。MIT 开源。

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

4 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

volmon · 跨平台音量 / 噪音监控软件

开源地址: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(按日切割)

安装(Windows)

cd 项目目录
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt

若 sounddevice 报缺少 PortAudio,请安装 [Microsoft C++ 运行库] 与 [PortAudio]; 绝大多数情况下 pip install sounddevice 自带可用后端。

安装(macOS)——DMG 安装包(推荐,双击即用)

产物: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 cli

终端波形(CLI)

python 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 字符,任意终端下不错位

校准(让软件读数与专业声级计对齐)

  1. 用专业噪音仪测得当前环境真实 dB(例如 65.0)。
  2. 保持环境稳定,在 Web 校准面板输入 65.0 并点「一键校准」;或命令行:
    python main.py calibrate 65.0
  3. 此后软件读数 = 原始值 + 偏移,与专业设备一致。可随时重新校准。

关于"未校准时显示负数":麦克风算出的是 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 演示模式不发声。

报警声从哪一路输出(3.5mm 耳机 / USB 耳机 / 本机扬声器)

  • 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:0022:00 | 晚间 22:0007: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(立即清理)

开启声音报警时:报警触发即截断(rec_cut_on_alarm,默认开)

报警声是本机扬声器放出去的,会被同一台电脑的麦克风原样拾回——录进 WAV 就是一段刺耳的 "嘀嘀"声,把真实环境音盖掉。软件没法把两个混在一起的声音再分开,所以采取最干脆也最可靠 的办法:报警声是从触发点才响起来的,那报警一触发,立刻把录音"定格"在触发瞬间,触发之后的声音一个字节都不写。

报警触发瞬间
   │
   ▼
──┴────────── 前置段(触发前,真实环境音)────────────┐
   │                                              ┝━ 这一份写进 WAV(完整)
麦克风 ▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁░░░░░░░░
   └ 触发点之后的报警声(本机外放)── 直接丢弃,永不写入
  • 前置段照留:触发前那段环形缓冲里的真实环境声照常保留、写入 WAV(报警声那时还没响,本来就是干净的)

  • 触发点之后一刀切:报警一旦触发,所有"正在录"的任务立刻标记为"已截断",只等把已有前置段写盘即收工, 报警声(以及之后其它声音)一律不进文件

  • 面板上会显示 ✂ 报警触发即截断;保存的录音会标注"报警触发·已截断(仅含触发前音频)"

  • 这是与"跳过污染窗口"不同的更可靠方案:不再计算"报警响多久"去雕刻录音,而是直接从触发点切断, 因此无论报警时长、冷却怎么设,报警声物理上不可能出现在录音里

  • 已知限制:

    1. 服务刚启动的头几秒缓冲还在填充,这时的录音"前置段"会短一些,运行片刻后即稳定
    2. 开着声音报警时,录音会在触发点结束(不含报警后声音)——这是预期行为,目的是保护录音不被报警声污染
    3. 从根本上避免串扰,还是建议报警输出接耳机(或外接音箱远离麦克风), 这样触发点之后也能录到连续完整的真实声音
    4. 演示模式(--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":"..."} 补发)。

  • 安全:密码请填授权码;接口返回给页面的密码一律脱敏为 ●●●●●●。

日志按日切割与保留(默认保留 30 天)

右栏「日志文件(按日切割)」面板可看到每类日志的今天文件与各天归档(含大小), 并可调整「按日切割」开关与「保留天数」(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 = 未静音);「恢复默认设置」会一并清除静音。

服务控制(Web 页面「服务控制」面板)

  • ↺ 恢复默认设置:把阈值/校准偏移/报警/输入设备等全部还原为出厂默认值。
  • ⟳ 重启服务:派生接替进程并以相同参数重启(用于更换输入设备或改代码后生效),约 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  # 导出超量告警为 CSV

Web 面板:「超量告警日志」每页 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 1.0.11)

同一份代码可编译出 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、已知坑)。

开源相关


volmon 以 MIT 协议开源,由社区共同维护。如果使用对你有帮助,欢迎 Star ⭐ 与分享。

About

跨平台音量/噪音监控软件:麦克风实时监测、Web+CLI 可视化、专业校准、阈值预警、声音报警、分时段策略、触发录音、每日报警邮件。MIT 开源。

Topics

Resources

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages