Skip to content

Integration features, CLI

Jump to bottom
waydabber edited this page Aug 3, 2024 · 70 revisions

BetterDisplay provides various app integration options.

Note

The article reflects app version v3.0.0

Warning

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

Enabling integration features

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

Screenshot 2024-01-08 at 17 35 13

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.
  • quantization - Software color quantization. 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. Specific values must be provided. 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. Specific values must be provided. 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.
  • connectionMode - Low level connection mode. For valid mode numbers to specify with set, use connectionModeList. You can also specify a mode using the format bpc:[8|10|12|16]+range:[limited|full]+encoding:[rgb|ycbcr]+chroma:[444|422|420]+hdrmode:[sdr|hdr10|dolby] - if components are missing, current value is assumed, so for example specifying bpc:8 will simply switch to 8bpc mode. Modeswitch happens only if there is a suitable mode in the compatible connection mode list. Available on Apple Silicon Macs for natively connected displays. Please note that changing the connection mode is a risky operation! 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.
  • moveTo - Move display next to an other display in the display layout using direction specifiers. A target display (relative to which the display is moved) must be specified. Specific values must be provided. Command, no value must be specified. Device (display) specific feature. Pro feature. Available values: topLeftCorner, topLeft, top, topRight, topRightCorner, leftTop, left, leftBottom, rightTop, right, rightBottom, bottomLeftCorner, bottomLeft, bottom, bottomRight, bottomRightCorner.
  • framebufferBoolProperty - Set a boolean framebuffer property. Use specifier to specify the framebuffer property name. Bool value (on or off) must be specified. Device (display) specific feature.
  • framebufferNumericProperty - Set a numeric framebuffer property. Use specifier to specify the framebuffer property name. Specific values must be provided. Device (display) specific 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.
  • gpuDithering - GPU dithering. Bool value (on or off) must be specified. Device (display) specific feature.
  • inverted - Invert colors (using color table adjustments). Bool value (on or off) must be specified. Device (display) specific feature.
  • mirror - Mirror display. One or more target display must be specified. Bool value (on or off) must be specified. Device (display) specific feature.
  • stream - Enable/disable streaming for a display. Must also be specified (without value) if a stream specific setting is changed. Bool value (on or off) must be specified. Device (display) specific feature. Pro feature.
  • pip - Enable/disable picture in picture for a display. Must also be specified (without value) if a stream specific setting is changed. Bool value (on or off) must be specified. Device (display) specific feature. Pro feature.
  • protectResolution - Enable/disable resolution protection. Setting it to on protects current setting. Bool value (on or off) must be specified. Device (display) specific feature. Pro feature.
  • protectRefreshRate - Enable/disable refresh rate protection. Setting it to on protects current setting. Bool value (on or off) must be specified. Device (display) specific feature. Pro feature.
  • protectHDR - Enable/disable HDR state protection. Setting it to on protects current setting. Bool value (on or off) must be specified. Device (display) specific feature. Pro feature.
  • protectRotation - Enable/disable rotation protection. Setting it to on protects current setting. Bool value (on or off) must be specified. Device (display) specific feature. Pro feature.
  • protectAsMain - Enable/disable main status protection. Setting it to on works only if the display is main display. Bool value (on or off) must be specified. Device (display) specific feature. Pro feature.
  • protectSDRProfile - Enable/disable SDR profile protection. Setting it to on protects current setting and works only if the display is in SDR mode. Bool value (on or off) must be specified. Device (display) specific feature. Pro feature.
  • protectHDRProfile - Enable/disable HDR profile protection. Setting it to on protects current setting and works only if the display is in HDR mode. Bool value (on or off) must be specified. Device (display) specific feature. Pro feature.
  • protectSDRColorMode - Enable/disable SDR color mode protection. Setting it to on protects current setting and works only if the display is in SDR mode. Requires Apple Silicon. Bool value (on or off) must be specified. Device (display) specific feature. Pro feature.
  • protectHDRColorMode - Enable/disable HDR color mode protection. Setting it to on protects current setting and works only if the display is in HDR mode. Requires Apple Silicon. Bool value (on or off) must be specified. Device (display) specific feature. Pro feature.
  • protectAll - Enable/disable all protection. Setting it to on turns on all protections that can be activated for a display. Bool value (on or off) must be specified. Device (display) specific feature. Pro 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.
  • standardFramebuffer - Set framebuffer color mapping to normal. Command, no value must be specified. Device (display) specific feature.
  • invertedFramebuffer - Set framebuffer color mapping to inverted. Command, no value must be specified. Device (display) specific feature.
  • grayscaleFramebuffer - Set framebuffer color mapping to grayscale. Command, no value must be specified. Device (display) specific feature.
  • invertedGrayscaleFramebuffer - Set framebuffer color mapping to inverted grayscale. Command, no value must be specified. Device (display) specific feature.
  • customEDID - Custom EDID binary in Base64 format. Use set and get to set and retrieve the currently configured data. Works on Apple Silicon Macs only. Specific values must be provided. Device (display) specific feature.
  • applyCustomEDID - Apply custom EDID. use customEDID to set the EDID data to be applied. Works on Apple Silicon Macs only. Command, no value must be specified. Device (display) specific feature. Pro feature.
  • applyFactoryEDID - Restore the factory EDID. Works on Apple Silicon Macs only. Command, no value must be specified. Device (display) specific feature. Pro feature.
  • autoApplyCustomEDID - Configures custom EDID auto-apply. Bool value (on or off) must be specified. Device (display) specific feature. Pro feature.
  • i2cEDID - Reads the display's EDID using I2C. Device (display) specific feature.
  • osEDID - Shows the display EDID recorded by the OS. Might be malformed and have some identifiers removed on newer macOS versions. 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.
  • installedColorProfileURLs - List installed color profiles. Use with the get operation. Information retrieval feature. Not a device (display) specific feature.
  • ddcCapabilities - Explores DDC capabilities by parsing the DDC capabilities string and attempting to read supported commands. Use with get. Provides a brief report. Device (display) specific feature.
  • ddcCapabilitiesString - Gets the DDC capabilities string from the display. Use with get. Provides the unparsed string. Device (display) specific feature.
  • preferredConnectionMode - Shows preferred connection mode. Available on Apple Silicon Macs for natively connected displays. Use with the get operation. Information retrieval feature. Device (display) specific feature.
  • connectionModeListAll - Lists all available connection modes. Available on Apple Silicon Macs for natively connected displays. Use with the get operation. Information retrieval feature. Device (display) specific feature.
  • connectionModeList - Lists available connection modes matching current mode (in terms of resolution, refresh rate, HDR state). Available on Apple Silicon Macs for natively connected displays. 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.
  • connectAllDisplays - Connets all displays (even unlisted ones). 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.
  • sidecarList - List Sidecar display names and UUIDs. Information retrieval feature. Not a device (display) specific feature.
  • sidecarConnected - Connect a Sidecar display specify Sidecar display's name or UUID using specifier Bool value (on or off) must be specified. Not a device (display) specific feature.

Parameters specific for various features

  • freeAspect - Free aspect ratio. Used by the following: stream, pip. Bool value (on or off) must be specified. Pro feature.
  • integerScaling - Integer scaling. Used by the following: stream, pip. Bool value (on or off) must be specified. Pro feature.
  • directPixelMapping - Direct (1:1) pixel mapping. Used by the following: stream. Bool value (on or off) must be specified. Pro feature.
  • rotateBy - Rotate image. Valid values are 0, 90, 180, 270. Used by the following: stream, pip. Specific values must be provided. Pro feature.
  • flipHorizontal - Flip horizontally. Used by the following: stream, pip. Bool value (on or off) must be specified. Pro feature.
  • flipVertical - Flip vertically. Used by the following: stream, pip. Bool value (on or off) must be specified. Pro feature.
  • horizontalLocation - Horizontal alignemnt. Used by the following: stream. Specific values must be provided. Pro feature. Available values: left, center, right.
  • verticalLocation - Vertical alignemnt. Used by the following: stream. Specific values must be provided. Pro feature. Available values: top, center, bottom.
  • cursorShown - Show mouse cursor. Used by the following: stream, pip. Bool value (on or off) must be specified. Pro feature.
  • streamUnderscan - Stream underscan. Used by the following: stream. A contiguous range of values are accepted. Pro feature.
  • zoom - Zoom level. Used by the following: stream. A contiguous range of values are accepted. Pro feature.
  • partial - Crop image. Used by the following: stream, pip. Bool value (on or off) must be specified. Pro feature.
  • partialOriginX - Crop window origin X (percentage value, relative to the display size). Used by the following: stream, pip. A contiguous range of values are accepted. Pro feature.
  • partialOriginY - Crop window origin Y (percentage value, relative to the display size). Used by the following: stream, pip. A contiguous range of values are accepted. Pro feature.
  • partialWidth - Crop window width (percentage value, relative to the display size). Used by the following: stream, pip. A contiguous range of values are accepted. Pro feature.
  • partialHeight - Crop window height (percentage value, relative to the display size). Used by the following: stream, pip. A contiguous range of values are accepted. Pro feature.
  • resume - Resume stream on connect. Used by the following: stream. Bool value (on or off) must be specified. Pro feature.
  • priority - Window priority. Used by the following: pip. Specific values must be provided. Pro feature. Available values: normal, topmost, absolute.
  • unmovable - Unmovable PIP window. Requires the priority to be set to absolute. Used by the following: pip. Bool value (on or off) must be specified. Pro feature.
  • clickthrough - Click-through PIP window. Requires priority to be set to absolute, unmovable to be on and alpha set to a transparent level. Used by the following: pip. Bool value (on or off) must be specified. Pro feature.
  • showTitlebar - Show window titlebar. Used by the following: pip. Bool value (on or off) must be specified. Pro feature.
  • showShadow - Show window shadow (works only when free aspect ratio is enabled). Used by the following: pip. Bool value (on or off) must be specified. Pro feature.
  • alpha - Window alpha (transparency, percentage value expected). Used by the following: pip. A contiguous range of values are accepted. Pro feature.
  • autoStart - Start automatically. Used by the following: pip. Bool value (on or off) must be specified. Pro feature.
  • originX - Window origin X (percentage value, relative to the target display size). Used by the following: pip. A contiguous range of values are accepted. Pro feature.
  • originY - Window origin Y (percentage value, relative to the target display size, zero is the bottom of the screen). Used by the following: pip. A contiguous range of values are accepted. Pro feature.
  • width - Window width (percentage value, relative to the target display size). Used by the following: pip. A contiguous range of values are accepted. Pro feature.
  • height - Window height (percentage value, relative to the target display size). Used by the following: pip. A contiguous range of values are accepted. Pro feature.
  • 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. Specific values must be provided. Available values: unknown, 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.
  • specifier - Specifies additional information for a feature. Used by the following: framebufferBoolProperty, framebufferNumericProperty, sidecarConnected. Specific values must be provided.
  • targetTagID - Identify a target device via the display's tagID which is a BetterDisplay provided unique numeric ID specific to this app installation. Used by the following: moveTo, mirror, stream, pip.
  • targetUUID - Identify a target device via the display's UUID assigned by this macOS installation. Used by the following: moveTo, mirror, stream, pip.
  • targetDisplayID - Identify a target device using the displayID issued by macOS. This ID might change from time-to-time. Used by the following: moveTo, mirror, stream, pip.
  • targetName - Identify a target device using its displayed name in BetterDisplay. Used by the following: moveTo, mirror, stream, pip.
  • targetNameLike - Identify a target using a part of its displayed name in BetterDisplay (case insensitive). Used by the following: moveTo, mirror, stream, pip.
  • targetOriginalName - Identify a target device using its name in BetterDisplay. Used by the following: moveTo, mirror, stream, pip.
  • targetOriginalNameLike - Identify a target device using a part of its name in BetterDisplay (case insensitive). Used by the following: moveTo, mirror, stream, pip.

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:

Color profiles and XDR presets:

Managing virtual screens:

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

Configuring display protection settings:

Configuring PIP and streaming:

EDID operations:

Configuring connection color modes (on Apple Silicon):

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

The tool can be installed in the following ways:

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:

Screenshot 2024-01-08 at 17 12 23

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.

Clone this wiki locally