整合功能與 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