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