Integration features, CLI

BetterDisplay provides various app integration options.

Note

The article reflects app version v2.2.3

Warning

Some of the features described in this entry require a Pro license.

This entry is under construction, features mentioned are currently under active development, details and syntax may change.

Enabling integration features

Various integration features must be activated under Settings > Application > Integration (CLI and notification based integration are enabled by default).

General overview and syntax

The app supports the following integration methods:

Command line integration
Custom URL scheme based integration
HTTP integration
Notification based integration - for more details on this, see: https://betterdisplay.pro/integration
macOS Shortcuts (App Intents)

The various integration methods can be separately enabled and disabled under Settings in the application UI.

An integration command might receive one or more operations and zero or more parameters. A parameter might or might not have a value associated with it.

Syntax for command line access:

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

Notes:

The app binary BetterDisplay is available in the installed macOS app bundle (the full path when installed under Applications is /Applications/BetterDisplay.app/Contents/MacOS/BetterDisplay).
You can use both single and double hyphen parameter style.

You can also use betterdisplaycli for simpler access. Installation via Homebrew:

brew install waydabber/betterdisplay/betterdisplaycli

Examples (both commands set the brightness of a display with the name MyDisplay to 80%):

./BetterDisplay set -name=MyDisplay -brightness=0.8

betterdisplaycli set --name=MyDisplay --brightness=80%

Syntax for custom URL scheme integration:

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

Example (raw URL and scripted access using open command with proper escaping):

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

To safeguard access, a special token can optionally be defined in Settings which must then be present in the URL via a token= parameter. The custom URL scheme integration supports x-callback-url to report back success or error and results. More information: https://x-callback-url.com/specification/

Syntax for HTTP based integration:

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

Example (raw URL and scripted access using curl command with proper escaping):

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

The listening port can be customized under Settings. Example uses local access via localhost - use the appropriate hostname with remote calls. To safeguard access, a special token can optionally be defined in Settings which must then be present in the URL via a token= parameter.

With URLs you can use %20 to substitute for space.

Operations

Operations define how a command will be interpreted. Some operations can be combined (for example set or toggle with get to both set and get a value.

perform - Perform a command. Used for features that do not expect any value.
set - Sets a value. Can be used for features that excpect a value to set.
get - Gets a value. Useful for features that can report some kind of value (and optionally minimum and maximum values for features where a range makes sense).
toggle - Toggle a bool value. Can be used for on/off (togglable) features.
create - Create a device. You need to specify deviceType=VirtualScreen. You can add other set operation parameters to configure the virtual screen or alter its identifiers from default. If an identifier is not provided, the app will provide a default or (if it makes sense) random value.
discard - Discard a device. Use various device identifiers using identification parameters to narrow the devices you want to discard. Warning: without identifiers, the app will discard all discardable devices without question and any ability to undo - be careful with this!
help - Provides help about general usage or a specified operation, feature or parameter.

Parameters

Parameters affect how an operation is carried out. Some parameters can be mixed with each other. Parameters may or may not have values. Some parameters require additional parameters to function.

Device identification and device listing

tagID - Identify a device via the display's tagID which is a BetterDisplay provided unique numeric ID specific to this app installation.
UUID - Identify a device via the display's UUID assigned by this macOS installation.
displayID - Identify a device using the displayID issued by macOS. This ID might change from time-to-time.
name - Identify a device using its displayed name in BetterDisplay.
nameLike - Identify a device using a part of its displayed name in BetterDisplay (case insensitive).
originalName - Identify a device using its name in BetterDisplay.
originalNameLike - Identify a device using a part of its name in BetterDisplay (case insensitive).
productName - Identify a device using its product name (as recorded in the display EDID).
productNameLike - Identify a device using a part of its name (as recorded in the display EDID, case insensitive).
vendor - Identify a device using its vendor code (numeric value).
model - Identify a device using its model number.
serial - Identify a device using its serial number.
alphanumericSerial - Identify a device using its alphanumerical serial identifier.
yearOfManufacture - Identify a device using the year of manufacture.
weekOfManufacture - Identify a device using the week of manufacture.
registryLocation - Identify a device using its I/O registry location string.
displayWithMouse - Identify the display with mouse.
displayWithFocus - Identify the display with the focused window.
deviceType - Identify a device based on its type. Can be Display or VirtualScreen.

Setting or getting values

value - Provides value when required for a feature or operation. Depending on the feature, the value may be an integer number, real number, percentage, on or off (for togglable features) or string. For most parameters you can use a more direct -<feature_name>=[value] syntax instead). When used with the get operation, provide this if you explicitly want the current value returned alongside minimum min or maximum max values.
offset - Signifies that any of the specified values are offset values (positive or negative) for features where it makes sense (these usually expect some real number or percentage as value). For example, providing -10% as value for a parameter will decrease the value of a feature (let's say brightness) by 10%.
min - If added without a value, the get operation will return the minimum value if it makes sense for the accessed feature. If added with a value for a set or get operation, it acts as a normalizaton tool to specify the lower bound of the value range on which the provided value must be interpreted or the requested value to be returned.
max - If added without a value, the get operation will return the maximum value if it makes sense for the accessed feature. If added with a value for a set or get operation, it acts as a normalizaton tool to specify the upper bound of the value range on which the provided value must be interpreted or the requested value to be returned.

Parameters invoking an app feature

brightness - Brightness. Selects the most appropriate brightness control method if more than one is available. A contiguous range of values are accepted. Device (display) specific feature.
combinedBrightness - Combined brightness (hardware + software). Should only be used if auto-selection using brightness is not adequate. A contiguous range of values are accepted. Device (display) specific feature.
hardwareBrightness - Hardware brightness (DDC or Apple). Should only be used if auto-selection using brightness is not adequate. A contiguous range of values are accepted. Device (display) specific feature.
softwareBrightness - Software brightness/dimming. Should only be used if auto-selection using brightness is not adequate. A contiguous range of values are accepted. Device (display) specific feature.
volume - Volume. Affects only devices with hardware volume control (DDC volume). A contiguous range of values are accepted. Device (display) specific feature.
hardwareContrast - Hardware contrast. Works on displays with DDC contrast control. A contiguous range of values are accepted. Device (display) specific feature.
redHardwareBlackLevel - Hardware black level for RGB red component. Works on displays with proper DDC control. A contiguous range of values are accepted. Device (display) specific feature.
greenHardwareBlackLevel - Hardware black level for RGB green component. Works on displays with proper DDC control. A contiguous range of values are accepted. Device (display) specific feature.
blueHardwareBlackLevel - Hardware black level for RGB blue component. Works on displays with proper DDC control. A contiguous range of values are accepted. Device (display) specific feature.
redHardwareGain - Hardware video gain for RGB red component. Works on displays with proper DDC control. A contiguous range of values are accepted. Device (display) specific feature.
greenHardwareGain - Hardware video gain for RGB green component. Works on displays with proper DDC control. A contiguous range of values are accepted. Device (display) specific feature.
blueHardwareGain - Hardware video gain for RGB blue component. Works on displays with proper DDC control. A contiguous range of values are accepted. Device (display) specific feature.
gain - Software video gain. Works on displays with color table manipulation support. Pro feature. A contiguous range of values are accepted. Device (display) specific feature.
gamma - Software gamma. Works on displays with color table manipulation support. Pro feature. A contiguous range of values are accepted. Device (display) specific feature.
rGamma - Software gamma for RGB red component. Works on displays with color table manipulation support. Pro feature. A contiguous range of values are accepted. Device (display) specific feature.
gGamma - Software gamma for RGB green component. Works on displays with color table manipulation support. Pro feature. A contiguous range of values are accepted. Device (display) specific feature.
bGamma - Software gamma for RGB blue component. Works on displays with color table manipulation support. Pro feature. A contiguous range of values are accepted. Device (display) specific feature.
rGain - Software gain for RGB red component. Works on displays with color table manipulation support. Pro feature. A contiguous range of values are accepted. Device (display) specific feature.
gGain - Software gain for RGB green component. Works on displays with color table manipulation support. Pro feature. A contiguous range of values are accepted. Device (display) specific feature.
bGain - Software gain for RGB blue component. Works on displays with color table manipulation support. Pro feature. A contiguous range of values are accepted. Device (display) specific feature.
temperature - Software color temperature. Works on displays with color table manipulation support. Pro feature. A contiguous range of values are accepted. Device (display) specific feature.
contrast - Software contrast. Works on displays with color table manipulation support. A contiguous range of values are accepted. Device (display) specific feature.
underscan - Underscan. Works on displays with backling framebuffers that have underscan control support. A contiguous range of values are accepted. Device (display) specific feature.
ddc - Sends a direct DDC command to the display. Requires a natively connected display with DDC enabled. Specify set and get for DDC write and read. Use the vcp parameter to specify the DDC control code. Use value to provide value for a set operation. A contiguous range of values are accepted. Device (display) specific feature.
ddcAlt - Sends a direct DDC command to the display using an alternate addressing (mostly used by some LG displays to control input source). Requires a natively connected display with DDC enabled. Use the vcp parameter to specify the DDC control code. Use value to provide value for a set operation. A contiguous range of values are accepted. Device (display) specific feature.
virtualScreenName - Defines the name of the virtual screen Virtual screen management feature.
virtualScreenSerial - Defines the serial number of the virtual screen Virtual screen management feature.
virtualScreenVendorNumber - Defines the vendor number of the virtual screen Virtual screen management feature.
virtualScreenModelNumber - Defines the model number of the virtual screen Virtual screen management feature.
aspectWidth - Aspect width of the virtual screen. Virtual screen management feature. A contiguous range of values are accepted.
aspectHeight - Aspect height of the virtual screen. Virtual screen management feature. A contiguous range of values are accepted.
sizeInch - Diameter of the virtual screen in inch. Virtual screen management feature. A contiguous range of values are accepted.
multiplierStep - Multiplier step of the generated resolutions (multiples of aspect width and height). Virtual screen management feature. A contiguous range of values are accepted.
limitMultiplierSize - Enable/disable multiplier limits. Virtual screen management feature. A contiguous range of values are accepted.
multiplierMinWidth - Multiplier limit - height width. Virtual screen management feature. A contiguous range of values are accepted.
multiplierMinHeight - Multiplier limit - height minimum. Virtual screen management feature. A contiguous range of values are accepted.
multiplierMaxWidth - Multiplier limit - width maximum. Virtual screen management feature. A contiguous range of values are accepted.
multiplierMaxHeight - Multiplier limit - height maximum. Virtual screen management feature. A contiguous range of values are accepted.
flipped - Virtual screen flipping. Virtual screen management feature. Bool value (on or off) must be specified.
virtualScreenHiDPI - Enable HiDPI resolutions in the resolution list of a virtual screen. Virtual screen management feature. Bool value (on or off) must be specified.
useResolutionList - Use custom resolution list instead of generated resolutions based on the aspect ratio and multiplier. Virtual screen management feature. Bool value (on or off) must be specified.
resolutionList - Resolution list in WIDTHxHEIGHT,[WIDTHxHEIGHT[,...]] format. Virtual screen management feature.
rotation - Display rotation. Valid values are 0, 90, 180, 270. Works on display framebuffers with rotation support. Pro feature. Specific values must be provided. Device (display) specific feature.
favoriteMode - Set display mode to the one recorded in the specified favorite slot. Valid values are 1 to 5. Pro feature. Specific values must be provided. Device (display) specific feature.
saveFavoriteMode - Records current display mode to a specified favorite slot. Valid values are 1 to 5. Pro feature. Specific values must be provided. Device (display) specific feature.
colorProfileURL - Color profile setting for a display. Specific values must be provided. Device (display) specific feature.
xdrPreset - XDR preset setting for a display. Specific values must be provided. Device (display) specific feature.
displayModeNumber - Display mode number. Specific values must be provided. Device (display) specific feature.
resolution - Display/screen resolution (in WIDTHxHEIGHT) format. Specific values must be provided. Device (display) specific feature.
refreshRate - Refresh rate (in Hz). Specific values must be provided. Device (display) specific feature.
colorDepth - Color depth (typically: 8 or 10 bits per channel). Setting this value works on Intel Macs only. Specific values must be provided. Device (display) specific feature.
placement - Display placement in the global coordinate space of the display layout (in XxY format). Uses logical pixels. Specific values must be provided. Device (display) specific feature. Pro feature.
mute - Display mute. Works on devices with volume control (DDC volume and optionally DDC mute). Bool value (on or off) must be specified. Device (display) specific feature.
hardwareBacklight - Turns Hardware backlight on or off. Works on displays with backlight technology and proper DDC support. Bool value (on or off) must be specified. Device (display) specific feature.
hiDPI - Turns HiDPI rendering on or off. Works with resolutions that have both LoDPI and HiDPI alternatives. Bool value (on or off) must be specified. Device (display) specific feature.
hdr - Turns HDR mode on or off. Requires third party HDR capable display. Pro feature. Bool value (on or off) must be specified. Device (display) specific feature.
connected - Connects or disconnects a display or virtual screen. For displays, connection management capable connection is required. Pro feature. Bool value (on or off) must be specified. Device (display) specific feature.
autoBrightness - Turns auto brightness on or off. Requires an Apple display. Bool value (on or off) must be specified. Device (display) specific feature.
notch - Turns the Apple Liquid Retina Display "ears" and "notch" area on or off. Requires a compatible display and works with certain resolutions only that have notched and notchless alternatives. Pro feature. Bool value (on or off) must be specified. Device (display) specific feature.
main - Sets a display as a main display (unsetting is only possible by designating an other display as main) or get its main status. Bool value (on or off) must be specified. Device (display) specific feature.
hardwarePowerOff - Turns a display off. Requires a DDC compatible external display that supports this feature. Command, no value must be specified. Device (display) specific feature.
hardwareFactoryReset - Reset factory settings for a display. Requires a DDC compatible external display that supports this feature. Command, no value must be specified. Device (display) specific feature.
resetColorAdjustments - Reset software color adjustments. Requires a display with color table manipulation support. Command, no value must be specified. Device (display) specific feature.
reinitialize - Reinitialize display connection and reload custom configuration. Works with natively connected displays with EDID. Command, no value must be specified. Device (display) specific feature.
resetVMM7100 - Reset VMM7100 HDMI adapter if present. Command, no value must be specified. Not a device (display) specific feature.
colorProfileReset - Reset color profile to factory setting for a display. Command, no value must be specified. Device (display) specific feature.
xdrPresetReset - Reset XDR preset to factory setting for a display. Command, no value must be specified. Device (display) specific feature.
identifiers - Lists display and virtual screen identifiers in a JSON structure. Use with the get operation. Information retrieval feature. Device (display) specific feature.
xdrPresetList - List XDR presets suitable for a display. Use with the get operation. Use with the get operation. Information retrieval feature. Device (display) specific feature.
displayModeList - Lists available display modes. Use with the get operation. Information retrieval feature. Device (display) specific feature.
nightShiftValue - Specifies Night Shift value. Pro feature. A contiguous range of values are accepted. Not a device (display) specific feature.
nightShift - Turns Night Shift on or off. Pro feature. Bool value (on or off) must be specified. Not a device (display) specific feature.
trueTone - Turns True Tone on or off. Pro feature. Bool value (on or off) must be specified. Not a device (display) specific feature.
darkMode - Turns Dark Mode on or off. Pro feature. Bool value (on or off) must be specified. Not a device (display) specific feature.
disableNightShiftInHDR - Toggles the feature on or off that toggles Night Shift when an external display is put to HDR or SDR mode using the app. Pro feature. Bool value (on or off) must be specified. Not a device (display) specific feature.
proAvailable - Returns whether Pro features are available or not. Use with get operation. Bool value (on or off) must be specified. Not a device (display) specific feature.
osdShowBasic - Turns showing basic native OSD (brightness, volume) on/off (useful for third party OSD app integration). Bool value (on or off) must be specified. Not a device (display) specific feature.
osdShowCustom - Turns showing custom OSD on/off (useful for third party OSD app integration). Bool value (on or off) must be specified. Not a device (display) specific feature.
osdIntegrationNotification - Turns third party OSD integration app notifications on/off. Bool value (on or off) must be specified. Not a device (display) specific feature.
reconfigure - Redetect/reconfigure displays. Command, no value must be specified. Not a device (display) specific feature.
disconnectAllButMain - Disconnects all displays except the current main display. Pro feature. Command, no value must be specified. Not a device (display) specific feature.
restartApp - Restart BetterDisplay. Command, no value must be specified. Not a device (display) specific feature.
installedColorProfileURLs - List installed color profiles. Use with the get operation. Information retrieval feature. Not a device (display) specific feature.

Parameters specific for various features

vcp - Specifies the DDC coontrol code (VCP - Virtual Control Panel) that is being accessed when sending a DDC command. Use VCP name, decimal or a hexadecimal number (supplied with 0x prefix). Used by the following: ddc, ddcAlt.

List of control codes accepted by the `vcp` parameter:

horizontalFrequency, verticalFrequency, sourceColorCoding, displayUsageTime, displayControllerId, displayFirmwareLevel, osdLanguage, powerMode, imageMode, vcpVersion, horizontalPosition, horizontalSize, horizontalPincushion, horizontalPincushionBalance, horizontalConvergenceRB, horizontalConvergenceMG, horizontalLinearity, horizontalLinearityBalance, verticalPosition, verticalSize, verticalPincushion, verticalPincushionBalance, verticalConvergenceRB, verticalConvergenceMG, verticalLinearity, verticalLinearityBalance, horizontalParallelogram, verticalParallelogram, horizontalKeystone, verticalKeystone, rotation, topCornerFlare, topCornerHook, bottomCornerFlare, bottomCornerHook, horizontalMirror, verticalMirror, displayScaling, windowPositionTopLeftX, windowPositionTopLeftY, windowPositionBottomRightX, windowPositionBottomRightY, scanMode, degauss, newControlValue, softControls, activeControl, performancePreservation, inputSelect, inputSelectAlt, ambientLightSensor, remoteProcedureCall, displayIdentificationOnDataOperation, tvChannelUpDown, flatPanelSubPixelLayout, displayTechnologyType, displayDescriptorLength, transmitDisplayDescriptor, enableDisplayOfDisplayDescriptor, applicationEnableKey, displayEnableKey, statusIndicator, auxiliaryDisplaySize, auxiliaryDisplayData, outputSelect, assetTag, auxiliaryPowerOutput, scratchPad, audioSpeakerVolume, speakerSelect, audioMicrophoneVolume, audioJackConnectionStatus, audioMuteScreenBlank, audioTreble, audioBass, audioBalanceLR, audioProcessorMode, osd, sixAxisHueControlBlue, sixAxisHueControlCyan, sixAxisHueControlGreen, sixAxisHueControlMagenta, sixAxisHueControlRed, sixAxisHueControlYellow, sixAxisSaturationControlBlue, sixAxisSaturationControlCyan, sixAxisSaturationControlGreen, sixAxisSaturationControlMagenta, sixAxisSaturationControlRed, sixAxisSaturationControlYellow, adjustZoom, autoColorSetup, autoSetup, autoSetupOnOff, backlightControlLegacy, backlightLevelWhite, backlightLevelRed, backlightLevelGreen, backlightLevelBlue, blockLutOperation, clock, clockPhase, colorSaturation, colorTemperatureIncrement, colorTemperatureRequest, contrast, displayApplication, fleshToneEnhancement, focus, gamma, grayScaleExpansion, horizontalMoire, hue, luminance, lutSize, screenOrientation, selectColorPreset, sharpness, singlePointLutOperation, stereoVideoMode, tvBlackLevel, tvContrast, tvSharpness, userColorVisionCompensation, velocityScanModulation, verticalMoire, videoBlackLevelBlue, videoBlackLevelGreen, videoBlackLevelRed, videoGainBlue, videoGainGreen, videoGainRed, windowBackground, windowControlOnOff, windowSelect, windowSize, windowTransparency, restoreFactoryDefaults, restoreFactoryLuminanceContrastDefaults, restoreFactoryGeometryDefaults, restoreFactoryColorDefaults, restoreFactoryTvDefaults, settings, blackStabilizer, colorPresetC, powerControl, topLeftScreenPurity, topRightScreenPurity, bottomLeftScreenPurity, bottomRightScreenPurity

Direct DDC access via CLI (and comparison with m1ddc)

This can serve as an alternative for m1ddc (with support for all connections, even ones that are not supported by m1ddc). Unlike m1ddc, DDC CLI access requires a running BetterDisplay process. Various examples:

Setting brightness directly:

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

The same with different style (using CLI style and hexadecimal numbers for VCP code and value)

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

Set a brightness value and then get the current, min (always 0) and max values:

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

Get the current value and max values for brightness:

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

CLI examples

Here are some discussions and comments that contain examples on how to use various CLI commands:

Changing display modes:

https://github.com/waydabber/BetterDisplay/issues/2646#issuecomment-1946631590

Color profiles and XDR presets:

Managing virtual screens:

https://github.com/waydabber/BetterDisplay/issues/2521#issuecomment-1928114756

Moving a display relative to an other display using -moveTo (note you can use -placement for coordinates) and configure mirroring:

Configuring display protection settings:

https://github.com/waydabber/BetterDisplay/issues/2670#issuecomment-1954846564

Configuring PIP and streaming:

CLI access by installing `betterdisplaycli`

Traditional CLI operations can be accessed by using the app binary embedded in the Application Bundle. If the app is installed under /Applications, you can an absolute path whenever you are using CLI commands. For example this will print the help:

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

To simplify CLI access, you can install betterdisplaycli. With this installed, you can simplify CLI access:

betterdisplaycli help

BetterDisplay is available can be installed in the following ways:

Automatically using Homebrew: brew install waydabber/betterdisplay/betterdisplaycli
Manually from this repo: https://github.com/waydabber/betterdisplaycli

License management via command line

Activating and deactivating licenses via command line comes handy in a corporate environment using automated license management solutions.

Note

License management CLI features are not accessible by using betterdisplaycli, you need to use the app binary itself.

Print current activation status

./BetterDisplay manageLicense -status

Activate the app

./BetterDisplay manageLicense -activate -email=<email address> -key=<license key>

Deactivate the app

./BetterDisplay manageLicense -deactivate

List existing activations

When the app is already activated, the license key can be omitted (the output will be a JSON structure, containing the activation date, activation ID and the primary network adapter MAC address of the Mac associated with the license):

./BetterDisplay manageLicense -activations

./BetterDisplay manageLicense -activations -key=<license key>

Deactivate an other activation

When the app is already activated, the license key can be omitted.

./BetterDisplay manageLicense -deactivate -activationid=<activation ID> -key=<license key>

Hide or show the Pro activation/deacativation UI

Hiding activation/deactivation UI and the license key from the app GUI is useful in a corporate environment to avoid accidental deactivation or easy copying of the product key:

./BetterDisplay manageLicense -hideui

./BetterDisplay manageLicense -showui

DistributedNotificationCenter based integration with third party apps

BetterDisplay can be integrated to third party apps using macOS notification dispatch system.

Sending requests to BetterDisplay

The following Swift struct defines the JSON data structure that a notification sent to BetterDisplay must conform:

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

Fields

uuid - a string (recommended: UUID().uuidString but can be anything or empty) - serves to match the returning response notification to the request notification.
commands - list of commands (see CLI help for available commands)
parameters - list of parameters and their (optional) values (see CLI help for available parameters)

The notification about the request must be sent with the following notification name:

com.betterdisplay.BetterDisplay.request

Example code

The following example code demonstrates how to ask BetterDisplay to set the brightness of all connected displays to 80% (0.8):

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

Receiving responses from BetterDisplay

The following Swift struct defines the JSON data structure that BetterDisplay will return as a response:

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

Fields

uuid - request identifier.
result - true or false depending on whether the operation was successful or not.
payload - returned results (if makes sense for the operation and in a format that makes sense for the operation).

All fields are optional.

BetterDisplay sends the response with the following notification name:

com.betterdisplay.BetterDisplay.response

`betterdisplaycli` code

Check out betterdisplaycli which serves as a simple CLI tool for BetterDisplay and its code also demonstrates how to integrate your app using notification dispatch:

https://github.com/waydabber/betterdisplaycli

OSD notification dispatch integration

BetterDisplay can send notifications to third party applications that can then use this information to present an alternate OSD GUI for the app. Such a feature is implemented in MediaMate from version 3.0 and newer.

The feature must be enabled under Settings > Application > Integration to work:

Information for developers

The notification contains a json text data which can be decoded to this:

  struct OsdNotification: Codable {
    var displayID: Int? = nil // Which display should show the OSD
    var systemIconID: Int? = nil // 1 - brightness, 3 - volume, 4 - mute, 0 - no icon
    var customSymbol: String? = nil // SF Symbol name if a custom icon is used
    var text: String? = nil // Text if additional text is displayed in the OSD HUD by the app
    var lock: Bool? = nil // Shows lock icon as well
    var controlTarget: String? = nil // Further description of the type of control the OSD is displayed for
    var value: Double? = nil // OSD value (scale: 0-max value)
    var maxValue: Double? = nil // max value
    var symbolFadeAfter: Int? = nil // If the symbol is a secondary symbol, it should be faded after this time elapsed - in milliseconds
    var symbolSizeMultiplier: Double? = nil // Symbol size adjustment (compared to normal size)
    var textFadeAfter: Int? = nil // Text should be faded after this time elapsed - in milliseconds
  }

All values are optional. If both system Icon and customSymbol are added, then the custom Symbol is a secondary symbol.

If the receiving app does not handle all aspects of the data (FadeAfter, text value etc), that's still fine.

ControlTarget can have the following values as of now. This info helps the presentation app to further customize the appearance of the OSD on the screen.

    case combinedBrightness
    case hardwareBrightness
    case softwareBrightness

    case volume
    case mute

    case hardwareContrast
    case redHardwareBlackLevel
    case greenHardwareBlackLevel
    case blueHardwareBlackLevel
    case redHardwareGain
    case greenHardwareGain
    case blueHardwareGain

    case gain
    case gamma
    case rGamma
    case gGamma
    case bGamma
    case temperature
    case contrast

    case blueLight
    case underscan

Getting the notification is simple. Just add somewhere an observer:

  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))
      // Do something with the osdNotification
    } catch {}
  }

Some additional considerations: https://github.com/waydabber/BetterDisplay/issues/2532#issuecomment-1921127320

App Intents support (macOS Shortcuts)

The app supports the macOS Shortcuts apps via the App Intents framework as well. Please note that not all operations are available as App Intents - for advanced users it is recommended to use CLI from the Shortcuts app.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Integration features, CLI

Enabling integration features

General overview and syntax

Syntax for command line access:

Syntax for custom URL scheme integration:

Syntax for HTTP based integration:

Operations

Parameters

Device identification and device listing

Setting or getting values

Parameters invoking an app feature

Parameters specific for various features

List of control codes accepted by the `vcp` parameter:

Direct DDC access via CLI (and comparison with m1ddc)

CLI examples

CLI access by installing `betterdisplaycli`

License management via command line

Print current activation status

Activate the app

Deactivate the app

List existing activations

Deactivate an other activation

Hide or show the Pro activation/deacativation UI

DistributedNotificationCenter based integration with third party apps

Sending requests to BetterDisplay

Fields

Example code

Receiving responses from BetterDisplay

Fields

`betterdisplaycli` code

OSD notification dispatch integration

Information for developers

App Intents support (macOS Shortcuts)

Clone this wiki locally

Integration features, CLI

Enabling integration features

General overview and syntax

Syntax for command line access:

Syntax for custom URL scheme integration:

Syntax for HTTP based integration:

Operations

Parameters

Device identification and device listing

Setting or getting values

Parameters invoking an app feature

Parameters specific for various features

List of control codes accepted by the vcp parameter:

Direct DDC access via CLI (and comparison with m1ddc)

CLI examples

CLI access by installing betterdisplaycli

License management via command line

Print current activation status

Activate the app

Deactivate the app

List existing activations

Deactivate an other activation

Hide or show the Pro activation/deacativation UI

DistributedNotificationCenter based integration with third party apps

Sending requests to BetterDisplay

Fields

Example code

Receiving responses from BetterDisplay

Fields

betterdisplaycli code

OSD notification dispatch integration

Information for developers

App Intents support (macOS Shortcuts)

Clone this wiki locally

List of control codes accepted by the `vcp` parameter:

CLI access by installing `betterdisplaycli`

`betterdisplaycli` code