Skip to content

About

键盘亮度键调焦点窗口所在的屏幕,支持 MacBook 自带屏与 Studio Display

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

FocusBright 图标

FocusBright

键盘亮度键调的是你正在用的那块屏幕,而不是永远只调 MacBook。

最新版本 CI macOS 15+ MIT License


解决什么

MacBook 接了外接显示器之后,按键盘上的亮度键(F1 / F2)通常只调 MacBook 自带屏。Apple 外接屏要去控制中心拖滑条,普通显示器往往还要按机身按钮。

FocusBright 在菜单栏里守着:按亮度键时,看当前焦点窗口在哪块屏上,就调哪块屏。

  • 焦点在外接屏:FocusBright 接管,按 1/16 一格调亮度,Option+Shift 细调 1/64 一格,和系统一致
  • 焦点在 MacBook 屏:原样交给系统,系统自带的亮度提示照常显示
  • 单按 Option + 亮度键依旧打开「显示器」设置

支持的显示器

根据设备自动选择硬件控制通道:Apple 屏使用 DisplayServices,第三方外接屏使用 DDC/CI 的 VCP 0x10(亮度)。

  • ✅ MacBook 自带屏
  • ✅ Apple Studio Display、Pro Display XDR 等 Apple 显示器
  • 🧪 支持 DDC/CI 的第三方显示器(如 Dell USB-C 显示器):新增实验性支持,包含 Apple Silicon 和 Intel 通信路径
  • 不支持 DDC/CI、没有有效回复或无法唯一匹配的设备:把按键原样交给系统

Apple 通道在 macOS 27 上实测通过。新增 DDC 通道已通过协议测试及 ARM / Intel 编译,尚待第三方显示器实机验证;不保证所有显示器、接口和扩展坞组合可用。

Dell / 第三方显示器排查

  1. 在显示器自身菜单中开启 DDC/CI(Dell 通常在「其他 / Others」里,具体以型号手册为准)。
  2. 优先 USB-C 或 DisplayPort 直连 Mac;部分扩展坞、KVM、HDMI 转接器和 DisplayLink 连接不透传 DDC。
  3. 在 FocusBright 菜单点「重新检测显示器」。检测成功后会出现亮度滑条,悬停可查看控制方式或失败原因。
  4. 如果仍无法调节,运行 --probe 查看检测信息,并提供显示器具体型号、Mac 芯片和连接方式。该命令只检测、读取,不修改亮度。

插拔及唤醒后会自动重新检测。通信失败后停止接管该屏的亮度键;检查连接后可手动重新检测。不会用黑色遮罩模拟硬件亮度。

安装

  1. 到 Releases 下载 dmg,打开后把 FocusBright 拖到「应用程序」。

  2. 首次打开会被 Gatekeeper 拦下(本地签名,未经 Apple 公证)。右键点击应用选「打开」,或在终端执行:

    xattr -d com.apple.quarantine /Applications/FocusBright.app
  3. 首次启动会显示权限设置窗口。点击「打开辅助功能设置」,将窗口中的应用图标拖入权限列表,再打开 FocusBright 右侧开关。也可以点击「在 Finder 中显示」后,将应用拖入列表。授权后几秒内自动生效,不用重启。

要求 macOS 15 或更新。

使用

打开后菜单栏出现太阳图标。之后照常按亮度键即可。

菜单项 说明
权限设置… 随时查看授权与亮度键监听状态、打开系统设置或在 Finder 中显示应用
屏幕滑条 每块屏一个亮度滑条,标着「亮度键」的是现在按键会调的那块
重新检测显示器 重新识别硬件控制能力,适合开启 DDC/CI 或更换线缆后使用
亮度键调节 跟随焦点窗口所在屏幕(默认),或跟随鼠标所在屏幕
暂停接管亮度键 勾上后亮度键回到系统默认行为
开机启动 登录时自动运行
打开日志 ~/Library/Logs/FocusBright/runtime.log,记录控制通道、检测结果及亮度读写情况

焦点窗口的位置用 CGWindowList 读取,只读窗口边框,不读标题和内容,所以不需要屏幕录制权限。

构建与发布

swift test                                          # 跑测试
Scripts/build-app.sh && Scripts/make-dmg.sh         # 本地打包到 build/
.build/debug/FocusBright --probe                    # 打印屏幕、亮度和当前焦点判断,排查问题用
# 已安装的应用也可以检测:
/Applications/FocusBright.app/Contents/MacOS/FocusBright --probe

DDC 的读写和检测在串行后台队列进行,菜单和键盘事件只查询能力快照。只有校验通过的亮度回复才能启用 DDC,写入按设备返回的实际量程换算。多屏身份存在歧义时拒绝分配控制端点,避免调错屏幕。

本地签名每次重新构建都会变,旧的辅助功能授权可能失效。若列表里已开启却仍提示未授权,可在「权限设置…」中点击「修复旧授权…」并确认。此操作仅重置 FocusBright 的辅助功能授权;随后需重新添加当前应用并打开开关。修复仅在打包后的 FocusBright.app 内可用,命令行开发版本不提供重置。

发版:改 Resources/Info.plist 里的版本号并推到 main,然后在 GitHub 上用 v<版本号> 作 tag 发布 Release。 Actions 会自动测试、打 dmg、上传到这个 Release,并在说明末尾补上安装步骤。版本号以 tag 为准。

License

MIT

DDC 实现参考 MonitorControl,许可与署名见 THIRD_PARTY_NOTICES.md,打包时会一起包含在应用内。

About

键盘亮度键调焦点窗口所在的屏幕,支持 MacBook 自带屏与 Studio Display

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages