marvinkraus/bettermonitor

# 更好的 Monitor 一款 macOS 菜单栏应用，利用面板的 HDR 余量，突破内置 Liquid Retina XDR 显示器约 600 尼特的 SDR 亮度上限。 一个滑块即可覆盖整个范围。滑块下半部分是普通亮度，范围 0–100 %。超过 100 % 后，滑块会继续进入**增强** (boost) 段，此时显示器会被推至超出系统亮度控制所能达到的极限。 ## 工作原理 两个独立的机制，结合成一个 0 → 2 的范围： **0.0 – 1.0 · 原生亮度。** 设置面板的真实亮度，与控制中心滑块移动的值相同。在 Apple Silicon 的内置显示器上，此功能没有公开的 API，因此 — 与 BetterDisplay、MonitorControl 和 Lunar 一样 — 本应用会在运行时通过 `dlsym` 从私有的 `DisplayServices.framework` 中解析 `DisplayServicesGetBrightness` / `DisplayServicesSetBrightness`。参见 [`NativeBrightness.swift`](Sources/BetterMonitor/NativeBrightness.swift)。 **1.0 – 2.0 · 增强。** 仅使用公开 API： 1. 一个不可见的 1×1 Metal 窗口会渲染一个扩展范围的清除颜色，并设置 `wantsExtendedDynamicRangeContent = true`。显示该窗口会将显示器切换到 EDR 模式，从而提升 mini-LED 背光并开启余量。 ([`EDROverlay.swift`](Sources/BetterMonitor/EDROverlay.swift)) 2. EDR 启动后，macOS 会将 SDR 内容*按比例缩小*，使 SDR 白色保持在参考水平 — 因此，单靠桌面会变暗，而不是变亮。本应用通过将显示器的 Gamma 传输表相乘来进行补偿，从而将普通的 SDR 内容映射到该余量中。 ([`BoostEngine.swift`](Sources/BetterMonitor/BoostEngine.swift)) 在 1.0 处的交接是无缝的：原生亮度处于最大值，而增强值为零。余量上限为 **2.5×**。在低亮度下，显示器报告的原始值会急剧膨胀（它是相对于当前参考白场的值，而不是绝对的尼特数值），并且将 Gamma 表乘以 11× 只会把所有中间调都变成纯白色。 ## 系统要求 - 一台具有可报告 EDR 余量内置显示器的 Mac — 即 Liquid Retina XDR（14"/16" MacBook Pro，2021 年及更新型号）。当显示器未报告余量时，应用会在其菜单中提示你。 - 根据清单文件要求，需要 macOS 14 或更高版本；**仅在搭载 M4 Pro 的机型 (Mac16,8) 上的 macOS 26.5.2 环境中开发和测试过**。 - 需要 Swift 6 工具链（Xcode 16 或更高版本）进行构建。 ## 安装 ``` git clone cd bettermonitor ./scripts/build-app.sh --install ``` 该命令会构建一个发布版二进制文件，将其打包为 `dist/BetterMonitor.app`，进行临时签名，将其复制到 `/Applications` 并启动。如果不加 `--install` 参数，它只会在构建后停止并存放在 `dist/` 目录中。 没有经过公证的发布版本 — 你需要自行构建。 ## 使用方法 在菜单栏中找到 ☀︎ 图标。**它大约需要四秒钟才会出现**：macOS 会先将新的状态项放置在屏幕外，然后才会将其固定到栏位中。 - 拖动滑块中点左侧的部分以设置正常亮度。 - 拖动滑块中点右侧的部分进行增强。状态行会显示增强百分比、Gamma 系数以及大致的尼特估算值。 - 随着 EDR 逐渐提升，增强效果会在大约两秒钟内启动；应用会不断重新应用该效果，直到其稳定下来。 - 点击 **Beenden** 可退出应用并恢复所有设置。 本应用以代理 (`LSUIElement`) 形式运行：没有 Dock 图标，也没有应用切换器条目。 ### 无界面测试 ``` swift build && .build/debug/BetterMonitor --verify ``` 启动 EDR，采样余量变化曲线，应用完全增强效果，恢复原状并进行报告。在一台搭载 M4 Pro 的 14" MacBook Pro 上： ``` === BetterMonitor · EDR boost verification === Display: Built-in Retina Display Potential EDR headroom: 16.000× (>1.0 means the panel can boost) Native brightness available (DisplayServices): yes baseline (SDR) headroom = 1.000× (~600 nits est) Engaging EDR trigger + gamma boost (fraction = 1.0) ... t+0.5s headroom = 1.444× (~867 nits est) t+1.5s headroom = 6.337× (~3802 nits est) t+2.5s (boost on) headroom = 11.429× (~6857 nits est) ``` 该输出中的尼特数值是比率乘以 600 的结果 — 参见[局限性](#limitations)。请将它们视为余量存在的信号，而不是精确的测量值。 ## 局限性 **增强会裁剪高光。** 将 Gamma 表乘以一个系数会提升所有内容，因此在范围的最高点（2.5×），任何高于 40 % 白色的内容都会被压平为纯白色。你会得到更亮*但*更泛白的画面。这里没有色调映射。 **尼特数值仅为估算值。** `maximumExtendedDynamicRangeColorComponentValue` 是相对于当前参考白场的比率，而不是绝对的测量值。状态行中的“~1500 nits”是基于该比率的算术结果，而不是从面板读取的数值。 **自动亮度会产生冲突。** 环境光调整会在增强效果底层移动参考白场。请关闭自动亮度以获得一致的结果。 **仅限内置显示器。** 所有操作均针对 `CGMainDisplayID()`。不支持外接显示器，不支持 DDC/CI，不支持虚拟显示器，也不支持分辨率管理。 **依赖一个私有框架。** `DisplayServices` 不是公开 API。它仅用于原生亮度部分；增强路径完全使用公开 API。这里的任何内容都无法满足上架 App Store 的条件，且 Apple 可能会在不事先通知的情况下移除或更改这些符号。 **对 macOS 更新非常脆弱。** 整个技术依赖于未公开的 EDR 行为。Apple 已经在 macOS 26.3 中更改了相关行为。每次系统更新后，请使用 `--verify` 重新验证。 **UI 使用德语。** 菜单字符串未进行本地化。 ### 关于安全性 Gamma 表是一种在进程终止后依然存在的全局状态 — 如果应用在增强状态下崩溃，整个桌面将保持泛白状态，且亮度调节键无法撤销。本应用在退出以及接收到 `SIGINT`/`SIGTERM`/`SIGHUP` 信号时会恢复该表。如果真的发生了意外情况，可以使用以下命令进行重置： ``` swift -e 'import CoreGraphics; CGDisplayRestoreColorSyncSettings()' ``` 同时运行其他亮度工具（如 MonitorControl、Lunar、BetterDisplay）会导致对同一状态的争抢冲突。 ## 布局 ``` Sources/BetterMonitor/ main.swift entry point, accessory app setup AppDelegate.swift lifecycle, refresh timer, signal handlers MenuBarController.swift status item, slider, status line BrightnessController.swift the unified 0–2 model and the handoff at 1.0 NativeBrightness.swift private DisplayServices binding BoostEngine.swift EDR trigger + gamma multiply, with baseline restore EDROverlay.swift the invisible Metal window that engages EDR Verify.swift the --verify harness scripts/ build-app.sh package + install the .app make-icon.swift generate the app icon ``` ## 相关前人研究 EDR 结合 Gamma 的技术并非本文原创。[BrightIntosh][bi] 在其已发布的商业应用中演示了这一点，而 [BetterDisplay][bd] 涵盖了此功能及更多其他特性。[MonitorControl][mc] 和 [Lunar][lunar] 则是对原生亮度的 `DisplayServices` 处理方式记录最详尽的地方。 ## 许可证 MIT 许可证 — 详见 [LICENSE](LICENSE)。

标签：HDR/EDR, Metal, Swift, 亮度增强, 菜单栏应用