Skip to content
HONTRAN.DEVCreative Development

· 11 min read

Mac Mini ExternalMonitor Brightness:Building XBrightNo brightness control for your Mac mini external monitor? XBright, a free open-source menu bar app, sets the real backlight over DDC/CI. Here is how.

Mac Mini External Monitor Brightness: Building XBright
Engineering note 092 — coverAll notes

A Mac mini has no screen of its own, so it has no brightness slider either. Plug in a third-party monitor and the brightness keys do nothing; the only way to dim it is to reach behind the panel and dig through the on-screen menu. Mac mini external monitor brightness is a problem macOS simply does not solve. So I built XBright: a free, MIT-licensed menu bar app for Apple Silicon Macs that changes the monitor's real backlight over DDC/CI, the same thing the buttons on the monitor do. No overlay, no gamma tricks.

This post is the build log: how DDC/CI works on Apple Silicon, the timing rules that the spec imposes, how the app matches a monitor to a screen, and the limits I chose to keep. All code below is from the shipped source, which is 440 lines of Swift with no dependencies.

What XBright does

  • One slider per external monitor, in the menu bar.
  • The brightness keys (F1/F2) change the monitor under the mouse pointer, 5% per press.
  • A command line: XBright get and XBright set <0-100> [display-index].
  • Requirements: an Apple Silicon Mac on macOS 14 or later, and a monitor with DDC/CI enabled in its own menu.

It went from the first commit to v1.0.0 on GitHub on the same day, built in one Claude Code session, and two point releases followed within a day. I tested it on a Mac mini M2 Pro with a Dell U2719D and a generic 1080p monitor. That is the full test matrix, and the README says so.

XBright's two slider rows in dark mode: "Display 1" at 70% and "DELL U2719D" at 60%

XBright's slider rows, rendered from the app's own slider view in the source: one row per monitor, named from the monitor's EDID when it has one.

Why a Mac mini can't change external monitor brightness

macOS controls the brightness of Apple displays because Apple ships the protocol on both sides. A Dell or LG monitor exposes its brightness through a different, older channel: DDC/CI (Display Data Channel Command Interface), a VESA standard that sends small I2C packets down the display cable to the monitor's controller. macOS does not use that channel for brightness, so the keys and the Control Center slider stay inactive for third-party monitors.

There are two ways to make a screen look darker:

ApproachWhat changesTrade-off
Software dimming (overlay or gamma)The pixels the Mac sendsBacklight stays at full power; blacks and contrast get worse
DDC/CIThe monitor's own backlight settingNeeds a monitor and a cable path that pass DDC

XBright does only the second one. That is a deliberate limit, covered at the end.

DDC/CI on Apple Silicon: IOAVService

On Intel Macs, apps reached the display's I2C bus through the framebuffer APIs. Apple Silicon replaced that path. What works on M-series Macs is a private IOKit interface, IOAVService, which exposes ReadI2C and WriteI2C calls on each display's DCPAVServiceProxy. Because it is private, there is no header; Swift reaches the symbols with @_silgen_name:

swift

@_silgen_name("IOAVServiceCreateWithService")
private func IOAVServiceCreateWithService(_ allocator: CFAllocator?, _ service: io_service_t) -> Unmanaged<CFTypeRef>?
@_silgen_name("IOAVServiceReadI2C")
private func IOAVServiceReadI2C(_ service: CFTypeRef, _ chip: UInt32, _ offset: UInt32, _ buffer: UnsafeMutableRawPointer, _ size: UInt32) -> IOReturn
@_silgen_name("IOAVServiceWriteI2C")
private func IOAVServiceWriteI2C(_ service: CFTypeRef, _ chip: UInt32, _ address: UInt32, _ buffer: UnsafeMutableRawPointer, _ size: UInt32) -> IOReturn

Enumeration walks every DCPAVServiceProxy in the IORegistry and keeps the ones whose Location property is External. A display only counts if a real brightness read succeeds, so a monitor with DDC/CI switched off never shows up as a dead slider.

The packet: chip 0x37, VCP 0x10, XOR checksum

The DDC/CI spec treats the monitor as a fixed I2C device at address 0x6E/0x6F (7-bit 0x37), and the host sends from source address 0x51. Brightness is VCP feature 0x10 in the Monitor Control Command Set; it is the same code that ddcutil reads with getvcp 10 on Linux. Every message ends with an XOR checksum over the address bytes and the payload. Here is the write in full:

swift

static func write(_ service: CFTypeRef, percent: Int, maxValue: Int) {
    let value = Int((Double(percent) * Double(maxValue) / 100).rounded())
    var packet: [UInt8] = [0x84, 0x03, brightness, UInt8(value >> 8), UInt8(value & 0xff), 0]
    packet[5] = 0x6E ^ 0x51 ^ packet[0] ^ packet[1] ^ packet[2] ^ packet[3] ^ packet[4]
    // Sent twice: a single write is occasionally dropped by the monitor without an error.
    for _ in 0..<2 {
        _ = IOAVServiceWriteI2C(service, 0x37, 0x51, &packet, UInt32(packet.count))
        usleep(settle)
    }
}

0x84 is the length byte (0x80 plus four payload bytes), 0x03 is "Set VCP Feature", then the feature code and the 16-bit value. The slider works in percent, but the monitor reports its own maximum, so the value is scaled to that maximum before it goes on the wire.

The double write is the one line that looks like a mistake. It isn't. A monitor occasionally drops a single Set VCP write without returning an error, so the app cannot tell that it failed. The value is absolute, not a step, so sending it twice is the cheapest fix that cannot overshoot.

The 50 ms settle

The read side shows why the code sleeps so much:

swift

// DDC/CI timing: the monitor needs >= 40 ms before a reply is readable and 50 ms between commands.
private static let settle: useconds_t = 50_000

These numbers come from the VESA DDC/CI 1.1 spec: after a request the host should wait at least 40 ms before it reads the reply, and at least 50 ms before the next message to the display. One 50 ms constant covers both. The read loop makes up to four attempts, and it accepts a reply only when the checksum (computed from the 0x50 virtual host address, as the spec defines) matches, the opcode is a VCP reply, the result code is zero, the feature is 0x10, and the maximum is above zero.

Matching a DDC device to an NSScreen

The I2C side and the AppKit side know about the same monitor in two different ways. IOAVService gives you a bus; NSScreen gives you a CGDirectDisplayID. To make F1/F2 change "the monitor under the pointer", the app has to join them.

The join key is the monitor's EDID, read over the same bus at address 0x50. The code checks the 8-byte EDID header (00 FF FF FF FF FF FF 00), then reads the vendor ID (bytes 8–9, big-endian), the product code (bytes 10–11, little-endian), and the serial (bytes 12–15, little-endian). It compares them with CGDisplayVendorNumber, CGDisplayModelNumber and CGDisplaySerialNumber:

swift

let exact = free.firstIndex {
    CGDisplayVendorNumber($0.id) == ddc.vendor && CGDisplayModelNumber($0.id) == ddc.product && CGDisplaySerialNumber($0.id) == ddc.serial
}
let loose = free.firstIndex {
    CGDisplayVendorNumber($0.id) == ddc.vendor && CGDisplayModelNumber($0.id) == ddc.product
}
let screen = (exact ?? loose).map { free.remove(at: $0) }

An exact match wins; a vendor-plus-model match is the fallback for monitors that report a zero serial. Each matched screen is removed from the pool, so two identical monitors cannot both claim the same screen. The slider label comes from the EDID's monitor-name descriptor (tag 0xFC), then from NSScreen.localizedName. The v1.0.2 release adds a third fallback, a numbered name, for the case where macOS reports an empty display name. That is the "Display 1" row in the image above.

The app also re-scans when the screen layout changes or the Mac wakes, but it waits three seconds first, because a monitor ignores DDC for a moment after hot-plug or wake.

Coalescing writes on a serial queue

A slider drag fires dozens of change events per second. Every DDC write costs two 50 ms waits, so writing each value would queue up seconds of stale commands and the backlight would trail the mouse. Display.swift keeps only the latest value:

swift

func set(_ value: Int) {
    percent = min(100, max(0, value))
    pending = percent
    if !writing { drain() }
}

private func drain() {
    guard let value = pending else {
        writing = false
        return
    }
    pending = nil
    writing = true
    let service = self.service
    let maxValue = self.maxValue
    DDC.queue.async {
        DDC.write(service, percent: value, maxValue: maxValue)
        DispatchQueue.main.async { self.drain() }
    }
}

At most one write is in flight per monitor. When it finishes, the drain picks up whatever the user last asked for and skips everything in between. All DDC traffic, reads included, goes through one serial DispatchQueue, so a menu-open re-scan can never interleave packets with a write in progress.

Brightness keys and the Accessibility prompt

On a Mac keyboard, F1/F2 send system-defined media-key events, not ordinary key presses. To catch them, XBright installs a Quartz event tap with CGEvent.tapCreate at the session level and filters for NX_SYSDEFINED events with the brightness-up and brightness-down key codes. Swift does not import those IOKit constants, so they are declared by hand with a comment that names the originals.

Apple's tapCreate documentation states the rule: an event tap receives key events only when the process runs as root or has access for assistive devices. That is why the brightness keys are opt-in behind a menu item that triggers the Accessibility prompt, while the slider and the command line work without any permission. The tap also handles tapDisabledByTimeout and tapDisabledByUserInput by switching itself back on, and it only swallows the key when there is a DDC monitor to act on, so the keys still work normally when nothing matches.

Building without Xcode

There is no Xcode project. build.sh compiles the six source files with swiftc, copies an Info.plist with LSUIElement set (menu bar only, no Dock icon), and signs the bundle ad hoc:

sh

swiftc -O -swift-version 5 -target arm64-apple-macos14.0 Sources/*.swift -o "$APP/Contents/MacOS/XBright"
cp Info.plist "$APP/Contents/Info.plist"
codesign --force --options runtime --sign - "$APP"

The same binary is also the command line tool: with arguments it runs get or set and exits; without them it starts the menu bar app.

Ad-hoc signing has two costs that the README states up front. The build is not notarized, so macOS blocks the first launch until you clear the quarantine flag:

sh

xattr -dr com.apple.quarantine /Applications/XBright.app

And macOS treats each new ad-hoc build as a different app, so it asks for Accessibility access again after an update.

Small tools like this are a change of scale from my usual work, which is award-winning websites in GSAP, WebGL and Next.js, and you can see that in my selected work. The habit is the same: probe the real hardware before building any UI. If your team needs that kind of rigour on a site build, here is how I work with studios and founders.

The limits I kept

  • No software dimming fallback. A monitor without DDC/CI gets no slider; the slider only ever means the real backlight.
  • No on-screen indicator when a brightness key is pressed.
  • Apple displays are not handled. macOS already controls the Studio Display and Pro Display XDR.
  • Apple Silicon only. Intel Macs use a different I2C path.
  • Some HDMI ports don't pass DDC. The built-in HDMI port on some Macs (M1, base M2) does not carry DDC, so use USB-C or DisplayPort for those.
  • Tested on one setup. Mac mini M2 Pro, Dell U2719D, one generic 1080p monitor.

If you need contrast and volume control or software dimming, MonitorControl is the established free, open-source app and lists all of those features. XBright is the small version: one job, readable in an afternoon.

FAQ

How do I control external monitor brightness on a Mac mini?

Use an app that speaks DDC/CI, enable DDC/CI in the monitor's own menu, and connect over USB-C, DisplayPort or a supported HDMI port. XBright gives you a menu bar slider, the F1/F2 keys and a command line on Apple Silicon Macs.

Why do the brightness keys not work on my external monitor?

macOS sends brightness changes only to displays it controls natively, such as Apple displays. A third-party monitor needs DDC/CI commands, which macOS does not send for brightness on its own.

Does DDC/CI work over HDMI on Apple Silicon?

It depends on the port. USB-C and DisplayPort connections pass DDC; the built-in HDMI port on some Macs, including the M1 and base M2 models, does not.

Is XBright safe to run if it isn't notarized?

The full source is public and builds with one script, so you can read every line and build it yourself instead of downloading the release. The release build is ad-hoc signed, so you clear the quarantine flag once. Since v1.0.3 it is signed with the hardened runtime, so macOS refuses to load another process's library into it.

Can I script monitor brightness from the terminal?

Yes. XBright get prints each monitor's index, brightness and name, and XBright set 60 sets every monitor, or one monitor if you add its index.

Get XBright

The source, the build script and the releases are on GitHub: github.com/devhontran/xbright. It is free and MIT licensed. Issues with a monitor model that doesn't respond are welcome; DDC behaviour varies a lot between panels.

If it saves you a reach for the monitor buttons, you can buy me a coffee.

And if you are planning a website that needs the same care with real devices, motion and performance, start a project with me.

Document the thing you don’t want to debug twice.

HONTRAN.DEV · Notes / 094Engineering note 092 of 094