macotron.display

List the connected displays, change brightness and the color lookup table, and switch the system display modes: Night Shift, True Tone, and grayscale.

// Nudge the built-in display's brightness from the keyboard.
function nudge(delta) {
  const current = macotron.display.getBrightness();
  if (current >= 0) macotron.display.setBrightness(current + delta);
}

macotron.keyboard.on("Dimmer", "ctrl+opt+-", () => nudge(-0.1));
macotron.keyboard.on("Brighter", "ctrl+opt+=", () => nudge(0.1));

Listing displays

list(): Array<Display>

One entry per connected screen. The id is the Core Graphics display ID. Pass it to the other calls on this page, and to display in macotron.window.moveToFraction().

Field	Meaning
`id`	Display ID.
`width`, `height`	Size in points.
`main`	`true` for the screen that holds the key window.
`frame`	`{ x, y, width, height }` in Cocoa screen points. The origin is the bottom-left of the main display.
`visibleFrame`	The frame without the menu bar and the Dock.
`scale`	Pixels per point: `2` on a Retina display.
`rotation`	Rotation in degrees.
`builtin`	`true` for a laptop's own screen.
`mirrored`	`true` when the display is in a mirror set.
`serial`	The serial number the display reports, often `0`.
`mm`	`{ width, height }`, the physical size in millimeters.

Brightness

getBrightness(id?: number): number

The brightness from 0 to 1. Without id, it reads the main display. Returns -1 when the display does not support software brightness, which is the case for most external monitors.

setBrightness(level: number, id?: number): boolean

Sets the brightness. level is clamped to 0…1. Without id, it sets the main display. Returns false when the display does not accept the change.

Gamma

The gamma calls write the display's color lookup table. The table is a straight ramp from a black point to a white point, each an { red, green, blue } object with channels from 0 to 1. This affects every pixel on the screen, so it can tint, invert, or dim the display below its lowest hardware brightness.

setGamma(white, black?, id?): boolean

Writes the table. A channel you leave out is 0, so setGamma({ red: 1 }) shows only red. black defaults to all zeros. You can pass a display ID as the second argument and skip black. Without an ID, the table goes to every active display. Returns false when white is missing or a display rejects the table.

macotron.display.setGamma({ red: 1, green: 0, blue: 0 });   // red only, for night vision
macotron.display.setGamma({ red: 0.4, green: 0.4, blue: 0.4 }); // darker than the minimum brightness
macotron.display.setGamma({ red: 0, green: 0, blue: 0 }, { red: 1, green: 1, blue: 1 }); // invert

getGamma(id?: number): { white, black }

The current end points of the table for one display, the main display by default. Each is { red, green, blue }. When the table cannot be read, it returns white as all ones and black as all zeros.

restoreGamma(): boolean

Puts back the ColorSync settings on every display. Macotron also does this when plugins reload, if a plugin changed the gamma.

Display modes

Each getter returns available: false when this Mac does not support the mode. Each setter returns { ok, on, available, error? }. When ok is false, error says why.

nightShift(): { on, strength?, available }

Whether Night Shift is on. strength is the warmth from 0 to 1, when macOS reports it.

setNightShift(on: boolean | { on?, strength? })

Turns Night Shift on or off. Pass an object to set the warmth too: strength is clamped to 0…1, and on defaults to true. The result also carries strength.

macotron.display.setNightShift({ strength: 0.8 });

trueTone(): { on, available }

Whether True Tone is on.

setTrueTone(on: boolean)

Turns True Tone on or off.

grayscale(): { on, available }

Whether the screen shows in grayscale.

setGrayscale(on: boolean)

Turns grayscale on or off for every display.

Overlays

setXDREnabled(enabled: boolean): boolean

Puts a transparent extended-dynamic-range layer over the main screen, which asks macOS for the display's HDR headroom. Returns false when the main screen has no HDR headroom. Turning it off always returns true.

isXDREnabled(): boolean

Whether the XDR layer is up.

setCRTEnabled(enabled: boolean): boolean

Draws a CRT effect over every screen: scanlines, a phosphor grille, a vignette, and a rolling bar. Clicks pass through it. It draws on top of the desktop, so it can darken and tint but cannot warp the pixels below. Returns false when Metal is unavailable.

The effect covers the screens that are connected when you turn it on. After you connect a display, turn it off and on again.

isCRTEnabled(): boolean

Whether the CRT effect is on.

Events

display:changed

Fires when a display is added, removed, moved, or reconfigured. The payload is { id, flags }, where flags is an array of "add", "remove", "move", "main", "mode", "enable", "disable", "mirror", "unmirror", and "shape". One change often fires once for each display it affects.

macotron.on("display:changed", ({ flags }) => {
  if (flags.includes("add")) macotron.notify.toast("Display connected");
});