集成功能与 CLI

启用集成功能

集成功能可在 设置 > 应用程序 > 集成 下激活（CLI 和基于通知的集成默认已启用）。

控制集成

从应用版本 v3.5.3 开始，控制集成（通过脚本或网络控制显示器、接收器和其他设备）也可以在特定显示器/设备下进行配置。以下是一些关于如何配置网络控制的示例链接：

• 显示器（及其他设备）控制集成支持
• 添加控制集成参数
• 基于 URL（http/s、自定义 URL Scheme）的控制集成
• 基于 Shell 脚本（zsh）的控制集成
• 通过 http/s get 或 Shell 脚本输出拉取/获取控制集成数据

（注意：基于分布式通知中心的控制集成也可用。）

概述与语法

应用支持以下集成方式：

• 命令行集成
• 自定义 URL Scheme 集成
• HTTP 集成
• 基于通知的集成 — 更多详情请参阅：betterdisplay.pro/integration
• macOS 快捷指令（App Intents）

各种集成方式可以在应用设置中单独启用和禁用。

一个集成命令可以接收一个或多个操作以及零个或多个参数。参数可以有也可以没有关联的值。

命令行访问语法

./BetterDisplay operation [operation] [-parameter[=value]] [-parameter[=value]]

说明：

• 应用二进制文件 BetterDisplay 位于已安装的 macOS 应用包中（安装在 Applications 下时的完整路径为 /Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay）。
• 您可以使用单连字符和双连字符参数风格。

您也可以使用 betterdisplaycli 进行更简便的访问。通过 Homebrew 安装：

brew install waydabber/betterdisplay/betterdisplaycli

示例（两个命令都将名为 MyDisplay 的显示器亮度设置为 80%）：

./BetterDisplay set -name=MyDisplay -brightness=0.8
betterdisplaycli set --name=MyDisplay --brightness=80%

自定义 URL Scheme 集成语法

BetterDisplay://operation[/operation (…)][?parameter[=value]][&parameter[=value]]

示例（原始 URL 和使用 open 命令的脚本访问，带正确转义）：

BetterDisplay://set?name=MyDisplay&brightness=0.8
open BetterDisplay://set\?name=MyDisplay\&brightness=0.8

为保护访问安全，可以在设置中定义一个特殊令牌，然后必须通过 token= 参数包含在 URL 中。自定义 URL Scheme 集成支持 x-callback-url 来回报成功、错误和结果。更多信息：x-callback-url.com/specification

HTTP 集成语法

http://<hostname>:55777/command/[command/][?parameter[=value]][&parameter[=value]]

示例（原始 URL 和使用 curl 命令的脚本访问，带正确转义）：

http://localhost:55777/set?name=MyDisplay&brightness=0.8
curl http://localhost:55777/set\?name=MyDisplay\&brightness=0.8

监听端口可在设置中自定义。以上示例使用 localhost 进行本地访问 — 远程调用时请使用适当的主机名。为保护访问安全，可以在设置中定义一个特殊令牌，然后必须通过 token= 参数包含在 URL 中。

在 URL 中可以使用 %20 替代空格。

操作（Operations）

操作定义了命令的解释方式。某些操作可以组合使用（例如 set 或 toggle 与 get 组合，同时设置和获取值）。

• perform — 执行命令。用于不需要任何值的功能。
• set — 设置值。可用于需要设置值的功能。
• get — 获取值。适用于可以报告某种值的功能（对于有范围意义的功能，还可选择返回最小值和最大值）。
• toggle — 切换布尔值。可用于开/关（可切换）功能。
• feed — 更新自定义控制的值而不执行设置操作。可用于从外部源向自定义控制馈送/同步数据。
• create — 创建设备。需要指定 type=VirtualScreen。可以添加其他 set 操作参数来配置虚拟屏幕或更改其标识符。如果未提供标识符，应用将提供默认值或（如果合理的话）随机值。
• discard — 丢弃设备。使用各种设备标识参数来缩小要丢弃的设备范围。警告：不带标识符时，应用将无条件丢弃所有可丢弃的设备且无法撤销 — 请谨慎使用！
• help — 提供关于一般用法或指定操作、功能或参数的帮助。

参数（Parameters）

参数影响操作的执行方式。某些参数可以相互混合使用。参数可以有也可以没有值。某些参数需要额外的参数才能工作。

设备识别与设备列表

• tagID — 通过 BetterDisplay 提供的唯一数字 ID 识别设备或组。
• UUID — 通过 macOS 分配的显示器 UUID 识别设备。
• displayID — 使用 macOS 发出的 displayID 识别设备。此 ID 可能会不时更改。
• name — 使用设备在 BetterDisplay 中的显示名称识别设备或组。
• nameLike（或 n）— 使用设备在 BetterDisplay 中显示名称的一部分识别设备或组（不区分大小写）。
• originalName — 使用设备在 BetterDisplay 中的原始名称识别设备。
• originalNameLike — 使用设备在 BetterDisplay 中原始名称的一部分识别设备（不区分大小写）。
• productName — 使用产品名称（EDID 中记录的）识别设备。
• productNameLike — 使用产品名称的一部分识别设备（不区分大小写）。
• vendor — 使用供应商代码（数字值）识别设备。
• model — 使用型号识别设备。
• serial — 使用序列号识别设备。
• alphanumericSerial — 使用字母数字序列标识符识别设备。
• yearOfManufacture — 使用制造年份识别设备。
• weekOfManufacture — 使用制造周识别设备。
• registryLocation — 使用 I/O 注册表位置字符串识别设备。
• type（或 deviceType）— 基于类型识别设备或组。可以是 Display、VirtualScreen 或 DisplayGroup。
• displayWithMouse — 识别鼠标所在的显示器。
• displayWithFocus — 识别具有焦点窗口的显示器。
• displayWithMainStatus — 识别设为主显示器的显示器。
• displayWithNonMainStatus — 识别设为非主显示器的显示器。

设置或获取值

• value — 为功能或操作提供值。根据功能不同，值可以是整数、实数、百分比、on 或 off（用于可切换功能）或字符串。对于大多数参数，您可以使用更直接的 -<feature_name>=[value] 语法。与 get 操作一起使用时，如果您明确希望返回当前值以及 min 或 max 值，请提供此参数。
• offset — 表示指定的值是偏移值（正或负），适用于有意义的功能（通常期望实数或百分比作为值）。例如，为 brightness 提供 -10% 将使亮度降低 10%。
• min — 不带值添加时，get 操作将返回最小值（如果对访问的功能有意义）。带值用于 set 或 get 操作时，作为归一化工具指定值范围的下界。
• max — 不带值添加时，get 操作将返回最大值（如果对访问的功能有意义）。带值用于 set 或 get 操作时，作为归一化工具指定值范围的上界。

调用应用功能的参数

亮度与音量控制

• brightness — 亮度。自动选择最合适的亮度控制方式。接受连续范围的值。
• combinedBrightness — 组合亮度（硬件 + 软件）。仅在 brightness 自动选择不适用时使用。
• hardwareBrightness — 硬件亮度（DDC 或 Apple）。
• softwareBrightness — 软件亮度/调暗。
• volume — 音量。仅影响具有硬件音量控制（DDC 音量）的设备。
• mute — 静音。适用于具有音量控制的设备。布尔值（on 或 off）。

硬件显示控制（DDC）

• hardwareContrast — 硬件对比度。适用于支持 DDC 对比度控制的显示器。
• redHardwareBlackLevel / greenHardwareBlackLevel / blueHardwareBlackLevel — RGB 各分量的硬件黑电平。
• redHardwareGain / greenHardwareGain / blueHardwareGain — RGB 各分量的硬件视频增益。
• hardwareBacklight — 开关硬件背光。布尔值。
• hardwarePowerOff — 关闭显示器。需要支持此功能的 DDC 兼容外接显示器。
• hardwareFactoryReset — 重置显示器出厂设置。

软件图像调整

• gain — 软件视频增益。Pro 功能。
• gamma / rGamma / gGamma / bGamma — 软件 Gamma（整体及 RGB 各分量）。Pro 功能。
• rGain / gGain / bGain — RGB 各分量的软件增益。Pro 功能。
• temperature — 软件色温。Pro 功能。
• quantization — 软件色彩量化。Pro 功能。
• contrast — 软件对比度。
• inverted — 反转色彩（使用色彩表调整）。布尔值。
• suspendImageAdjustments — 暂停各种软件图像调整（亮度除外）。布尔值。
• resetColorAdjustments — 重置软件色彩调整。无需值。

显示模式与分辨率

• resolution — 显示器/屏幕分辨率（WIDTHxHEIGHT 格式）。
• refreshRate — 刷新率（Hz）。可与 resolution、hiDPI 等配合使用。
• colorDepth — 色彩深度（通常为 8 或 10 位/通道）。设置仅适用于 Intel Mac。
• hiDPI — 开关 HiDPI 渲染。布尔值。
• rotation — 显示器旋转。有效值为 0、90、180、270。Pro 功能。
• displayModeNumber — 显示模式编号。
• favoriteMode — 设置为指定收藏夹槽位中记录的显示模式。值为 1 到 5。Pro 功能。
• saveFavoriteMode — 将当前显示模式记录到指定收藏夹槽位。值为 1 到 5。Pro 功能。
• underscan — 欠扫描。适用于支持欠扫描控制的显示器。

HDR 与 XDR

• hdr — 开关 HDR 模式。需要第三方 HDR 显示器。Pro 功能。布尔值。
• brightnessUpscaling — 开关软件亮度增强。需要 XDR 或 HDR 显示器。Pro 功能。布尔值。
• nativeBrightnessUpscaling — 开关原生亮度增强。需要内置 XDR 显示器。Pro 功能。布尔值。
• xdrPreset — Apple 显示器预设设置。
• xdrPresetReset — 重置 Apple 显示器预设为出厂设置。

色彩配置文件与连接模式

• colorProfileURL — 显示器的色彩配置文件设置。
• colorProfileReset — 重置色彩配置文件为出厂设置。
• connectionMode — 底层连接模式。可使用 bpc:[8|10|12|16]+range:[limited|full]+encoding:[rgb|ycbcr]+chroma:[444|422|420]+hdrmode:[sdr|hdr10|dolby] 格式指定。适用于 Apple Silicon Mac 的原生连接显示器。注意：更改连接模式是有风险的操作！
• gpuDithering — GPU 抖动。布尔值。

显示器布局与状态

• placement — 显示器在全局坐标空间中的位置（XxY 格式）。使用逻辑像素。
• moveTo — 使用方向说明符将显示器移动到另一个显示器旁边。Pro 功能。可用值：topLeftCorner、top、left、right、bottom 等。
• main — 设置显示器为主显示器。布尔值。
• connected — 连接或断开显示器或虚拟屏幕。布尔值。
• autoBrightness — 开关自动亮度。需要 Apple 显示器。布尔值。
• notch — 开关 Apple Liquid Retina 显示器的"刘海"区域。Pro 功能。布尔值。
• mirror — 镜像显示器。需要指定一个或多个目标显示器。布尔值。

虚拟屏幕管理

• virtualScreenName — 定义虚拟屏幕名称。
• virtualScreenSerial — 定义虚拟屏幕序列号。
• virtualScreenVendorNumber / virtualScreenModelNumber — 定义虚拟屏幕供应商/型号编号。
• aspectWidth / aspectHeight — 虚拟屏幕的宽高比。
• sizeInch — 虚拟屏幕的对角线尺寸（英寸）。
• multiplierStep — 生成分辨率的倍增步长。
• flipped — 虚拟屏幕翻转。布尔值。
• virtualScreenHiDPI — 在虚拟屏幕分辨率列表中启用 HiDPI 分辨率。布尔值。
• resolutionList — 分辨率列表，格式为 WIDTHxHEIGHT,[WIDTHxHEIGHT[,…]]。

串流与画中画（PIP）

• stream — 启用/禁用显示器串流或更改串流设置。Pro 功能。布尔值。
• pip — 启用/禁用画中画或更改 PIP 设置。Pro 功能。布尔值。
• videoFilterWindow — 启用/禁用视频滤镜窗口。Pro 功能。布尔值。
• rotateBy — 旋转图像。有效值为 0、90、180、270。
• flipHorizontal / flipVertical — 水平/垂直翻转。布尔值。
• zoom — 缩放级别。
• magnification — 放大倍率（PIP）。
• partial — 裁剪图像。布尔值。
• alpha — 透明度（百分比值）。
• cursorShown — 显示鼠标光标。布尔值。

显示器保护设置

• protectResolution / protectRefreshRate / protectHDR / protectRotation — 保护分辨率/刷新率/HDR 状态/旋转。Pro 功能。布尔值。
• protectAsMain — 保护主显示器状态。Pro 功能。布尔值。
• protectSDRProfile / protectHDRProfile — 保护 SDR/HDR 配置文件。Pro 功能。布尔值。
• protectAll — 启用/禁用所有保护。Pro 功能。布尔值。

EDID 操作

• customEDID — Base64 格式的自定义 EDID 二进制数据。仅适用于 Apple Silicon Mac。
• applyCustomEDID — 应用自定义 EDID。Pro 功能。
• applyFactoryEDID — 恢复出厂 EDID。Pro 功能。
• i2cEDID — 使用 I2C 读取显示器的 EDID。
• osEDID — 显示操作系统记录的显示器 EDID。

帧缓冲色彩映射

• standardFramebuffer — 设置帧缓冲色彩映射为正常。
• invertedFramebuffer — 设置为反转。
• grayscaleFramebuffer — 设置为灰度。
• invertedGrayscaleFramebuffer — 设置为反转灰度。

信息检索

• identifier — 返回指定标识符的值。与 get 操作一起使用。
• identifiers — 以 JSON 结构列出显示器、虚拟屏幕和显示器组的标识符。
• displayModeList — 列出可用的显示模式。
• connectionModeList / connectionModeListAll — 列出可用的连接模式。适用于 Apple Silicon Mac。
• refreshRateList — 列出可用的刷新率和 VRR 状态选项。
• xdrPresetList — 列出适用于显示器的 Apple 显示器预设。
• installedColorProfileURLs — 列出已安装的色彩配置文件。
• ddcCapabilities / ddcCapabilitiesString — 探索 DDC 功能。

全局功能（非设备特定）

• nightShift / nightShiftValue — 开关 Night Shift 及设置值。Pro 功能。
• trueTone — 开关原彩显示。Pro 功能。布尔值。
• darkMode — 开关深色模式。Pro 功能。布尔值。
• ambientLight — 返回当前环境光级别。Pro 功能。
• reconfigure — 重新检测/重新配置显示器。
• disconnectAllButMain — 断开除主显示器外的所有显示器。Pro 功能。
• connectAllDisplays — 连接所有显示器。Pro 功能。
• appMenu / settingsWindow — 显示应用菜单/设置窗口。布尔值。
• restartApp / quitApp — 重启/退出应用。

显示器组管理

• enabled — 启用或禁用显示器组。布尔值。
• active — 获取显示器组的激活状态。
• activationPolicy — 显示器组激活策略。可用值：always、allMembersPresent、anyMembersPresent 等。
• synchronization — 显示器组同步。布尔值。
• layoutProtection — 显示器组布局保护。布尔值。

DDC 直接访问参数

• ddc — 向显示器发送直接 DDC 命令。需要启用 DDC 的原生连接显示器。使用 vcp 参数指定 DDC 控制代码，使用 value 提供值。
• ddcAlt — 使用替代寻址发送 DDC 命令（主要用于某些 LG 显示器控制输入源）。
• vcp — 指定被访问的 DDC 控制代码（VCP — 虚拟控制面板）。可使用 VCP 名称、十进制或十六进制数字（带 0x 前缀）。

通过 CLI 直接访问 DDC

这可以作为 m1ddc 的替代方案（支持所有连接，包括 m1ddc 不支持的连接）。与 m1ddc 不同，DDC CLI 访问需要运行中的 BetterDisplay 进程。示例：

直接设置亮度：

curl http://localhost:55777/set\?namelike=gp27\&feature=ddc\&vcp=luminance\&value=50

使用不同风格（CLI 风格和十六进制数字）：

./BetterDisplay set -namelike=gp27 -feature=ddc -vcp=0x10 -value=0x32

设置亮度值然后获取当前值、最小值（始终为 0）和最大值：

curl http://localhost:55777/set/get\?namelike=16p-l\&feature=ddc\&vcp=luminance\&value=30\&min\&max

获取亮度的当前值和最大值：

./BetterDisplay get -namelike=gp27 -feature=ddc -vcp=luminance -value -max

CLI 示例

与自定义控制交互（set、get、feed、toggle、perform）：

• 自定义控制交互示例

以下是包含各种 CLI 命令使用示例的讨论和评论：

• CLI 基础使用示例
• CLI 讨论与示例

更改显示模式：

• 显示模式更改示例

色彩配置文件和 XDR 预设：

• 色彩配置文件示例
• XDR 预设示例

管理虚拟屏幕：

• 虚拟屏幕管理示例

使用 -moveTo 移动显示器（也可使用 -placement 指定坐标）和配置镜像：

• 显示器移动示例
• 镜像配置示例

配置显示器保护设置：

• 保护设置示例

配置 PIP 和串流：

• PIP 配置示例
• 串流配置示例
• 高级串流示例

EDID 操作：

• EDID 操作示例

配置连接色彩模式（Apple Silicon）：

• 连接色彩模式示例

管理显示器组：

• 显示器组管理示例

管理 Sidecar：

• Sidecar 管理示例

通过安装 betterdisplaycli 进行 CLI 访问

传统 CLI 操作可以通过应用包中嵌入的应用二进制文件访问。如果应用安装在 /Applications 下，可以使用绝对路径。例如，以下命令将打印帮助信息：

/Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay help

为简化 CLI 访问，您可以安装 betterdisplaycli：

betterdisplaycli help

该工具可通过以下方式安装：

• 通过 Homebrew 自动安装：brew install waydabber/betterdisplay/betterdisplaycli
• 从仓库手动安装：github.com/waydabber/betterdisplaycli

基于 DistributedNotificationCenter 的第三方应用集成

BetterDisplay 可以使用 macOS 通知分发系统与第三方应用集成。

向 BetterDisplay 发送请求

以下 Swift 结构体定义了发送给 BetterDisplay 的通知必须符合的 JSON 数据结构：

struct IntegrationNotificationRequestData: Codable {
  var uuid: String?
  var commands: [String] = []
  var parameters: [String: String?] = [:]
}

字段说明

• uuid — 字符串（推荐使用 UUID().uuidString，但可以是任何值或为空）— 用于将返回的响应通知与请求通知匹配。
• commands — 命令列表（可用命令请参阅 CLI 帮助）。
• parameters — 参数及其（可选）值的列表（可用参数请参阅 CLI 帮助）。

请求通知必须使用以下通知名称发送：

com.betterdisplay.BetterDisplay.request

示例代码

以下示例代码演示如何请求 BetterDisplay 将所有已连接显示器的亮度设置为 80%（0.8）：

let integrationNotificationRequestData = IntegrationNotificationRequestData(
  uuid: UUID().uuidString,
  commands: ["set"],
  parameters: ["brightness": "0.8"]
)
do {
  let encoded = try JSONEncoder().encode(integrationNotificationRequestData)
  if let encodedString = String(data: encoded, encoding: .utf8) {
    DistributedNotificationCenter.default().postNotificationName(
      "com.betterdisplay.BetterDisplay.request",
      object: encodedString,
      userInfo: nil,
      deliverImmediately: true
    )
  }
} catch {}

接收 BetterDisplay 的响应

以下 Swift 结构体定义了 BetterDisplay 返回的响应 JSON 数据结构：

struct IntegrationNotificationResponseData: Codable {
  var uuid: String?
  var result: Bool?
  var payload: String?
}

字段说明

• uuid — 请求标识符。
• result — true 或 false，取决于操作是否成功。
• payload — 返回的结果（如果对该操作有意义，格式也取决于操作类型）。

所有字段都是可选的。BetterDisplay 使用以下通知名称发送响应：

com.betterdisplay.BetterDisplay.response

betterdisplaycli 代码

请查看 betterdisplaycli，它是 BetterDisplay 的简单 CLI 工具，其代码也演示了如何使用通知分发进行应用集成。

OSD 通知分发集成

BetterDisplay 可以向第三方应用发送通知，这些应用可以使用此信息来呈现替代的 OSD GUI。此功能已在 MediaMate 和 DynamicLakePro（3.0 及更新版本）中实现。

该功能必须在 设置 > 应用程序 > 集成 下启用才能工作：

开发者信息

通知包含一个 JSON 文本数据，可以解码为以下结构：

struct OsdNotification: Codable {
  var displayID: Int? = nil       // 应在哪个显示器上显示 OSD
  var systemIconID: Int? = nil    // 1 - 亮度, 3 - 音量, 4 - 静音, 0 - 无图标
  var customSymbol: String? = nil // 使用自定义图标时的 SF Symbol 名称
  var text: String? = nil         // OSD HUD 中显示的附加文本
  var lock: Bool? = nil           // 同时显示锁定图标
  var controlTarget: String? = nil // 控制类型的进一步描述
  var value: Double? = nil        // OSD 值（刻度：0 到最大值）
  var maxValue: Double? = nil     // 最大值
  var symbolFadeAfter: Int? = nil // 次要符号淡出时间（毫秒）
  var symbolSizeMultiplier: Double? = nil // 符号大小调整
  var textFadeAfter: Int? = nil   // 文本淡出时间（毫秒）
}

所有值都是可选的。如果同时添加了系统图标和自定义符号，则自定义符号为次要符号。

controlTarget 目前可以有以下值，此信息帮助呈现应用进一步自定义 OSD 外观：

combinedBrightness / hardwareBrightness / softwareBrightness
volume / mute
hardwareContrast
redHardwareBlackLevel / greenHardwareBlackLevel / blueHardwareBlackLevel
redHardwareGain / greenHardwareGain / blueHardwareGain
gain / gamma / rGamma / gGamma / bGamma
temperature / contrast / blueLight / underscan

接收通知的方式很简单，只需添加一个观察者：

DistributedNotificationCenter.default.addObserver(
  self,
  selector: #selector(osdNotificationBetterDisplay),
  name: .init("com.betterdisplay.BetterDisplay.osd"),
  object: nil
)

@objc func integrationOsdNotification(notification: NSNotification) {
  guard let notificationString = notification.object as? String else { return }
  do {
    let osdNotification = try JSONDecoder().decode(
      OsdNotification.self,
      from: Data(notificationString.utf8)
    )
    // 处理 osdNotification
  } catch {}
}

更多注意事项：GitHub 讨论

App Intents 支持（macOS 快捷指令）

应用还通过 App Intents 框架支持 macOS 快捷指令应用。请注意，并非所有操作都可作为 App Intents 使用 — 对于高级用户，建议在快捷指令应用中使用 CLI。

一些通过终端命令可访问的额外应用设置

隐藏 PIP 窗口调整大小百分比信息：

defaults write pro.betterdisplay.BetterDisplay pipShowResizePercent NO

允许应用使用所有有效许可证激活：

defaults write pro.betterdisplay.BetterDisplay disallowActivationWithOutdatedLicense NO

启用 PIP 鼠标光标自动跳转：

defaults write pro.betterdisplay.BetterDisplay pipAutoWarp YES

启用屏幕串流鼠标光标自动跳转：

defaults write pro.betterdisplay.BetterDisplay screenStreamAutoWarp YES

禁用屏幕串流目标上的鼠标光环（虚线圆圈）：

defaults write pro.betterdisplay.BetterDisplay screenStreamMouseHalo NO

应用菜单滑块出现时添加动画效果：

defaults write pro.betterdisplay.BetterDisplay sliderRevealAnimation YES