DisplayTune

English · 简体中文 · Documentation · Compatibility · Troubleshooting

DisplayTune is a SwiftUI menu bar utility for macOS 13 and later. It manages external-display resolutions, DDC/CI hardware controls, ColorSync ICC profiles, visual matching, physical colorimeter workflows, and day/night automation.

Project status: public beta. Resolution and ICC operations include recovery paths, but DDC/CI behavior depends on the monitor, firmware, input, cable, dock, and private macOS interfaces. Review the safety boundaries before first use.

Features

Identifies multiple physical external displays and stores an independent profile for each one using EDID vendor/product IDs, serial numbers, and product names.
Classifies 1080p, 1440p, 4K, 5K, ultrawide, and high-refresh displays.
Recommends display modes using native pixels, aspect ratio, HiDPI rendering, and refresh rate.
Provides a 15-second confirmation timer with automatic resolution rollback.
Probes DDC/CI brightness, contrast, and red/green/blue gain independently.
Maps Core Graphics displays to IORegistry DDC services and disables writes when a multi-display mapping is ambiguous.
Supports native-gamut, sRGB, and Display P3 color targets.
Generates per-display Mac Match, sRGB Target, and Apple Display P3 ICC profiles.
Stores visual white-point, RGB, brightness, and gamma correction in a 3 × 256-entry VCGT.
Provides side-by-side visual matching against a built-in Mac display or another calibrated reference display.
Provides automatic visual search across RGB balance, brightness, and gamma; stop when the result looks right, then save it.
Integrates optional physical colorimeters through ArgyllCMS.
Supports launch at login, reconnect restore, and day/night schedules.
Includes an extensible vendor/model strategy catalog with safe generic fallbacks.

Requirements

Component	Requirement
macOS	macOS 13 Ventura or later
Architecture	Apple Silicon hardware-tested; Intel builds, but its DDC path is not yet hardware-validated
Build tools	Xcode Command Line Tools and Swift 6
Colorimeter	Optional physical instrument plus ArgyllCMS
DDC/CI	The monitor and complete connection path must support it; some USB-C docks block DDC

Quick Start

cd DisplayTune

./scripts/check.sh
./scripts/build-app.sh
open dist/DisplayTune.app

Move the app into /Applications before enabling launch at login:

cp -R dist/DisplayTune.app /Applications/
open /Applications/DisplayTune.app

See Installation and Build for signing, package variables, ArgyllCMS, and Gatekeeper notes. The detailed documentation is currently written primarily in Simplified Chinese.

First-Time Setup

Enable DDC/CI in the monitor's on-screen display.
Temporarily disable Night Shift, True Tone, HDR, low-blue-light modes, dynamic contrast, and automatic brightness.
Open DisplayTune from the menu bar and select the target display.
Verify its product name, VID/PID, native resolution, and DDC mapping status.
Refresh DDC and wait for the five VCP features to be probed separately.
Start with One-click Mac Recommended Configuration.
Review the proposed resolution, gamut target, and ICC profile, then save and apply.
If the resolution changes, confirm it within 15 seconds or let DisplayTune roll it back.
For closer matching, open Automatic Visual Search / Colorimeter….

See the Usage Guide for the complete workflow.

Choosing a Color Target

Target	Recommended use	Notes
Native gamut	A reliable factory/measured ICC, photography, or professional work	Preserves the panel's real primaries and lets the ICC describe the device
sRGB	Web, office, and ordinary SDR content	The safest compatibility target, ideally paired with the monitor's sRGB OSD mode
Display P3	Wide-gamut panels whose native gamut is close to P3	Cannot create colors outside the panel's physical gamut

A monitor's DCI-P3 preset is not necessarily the same as Apple Display P3. White point and tone response may differ. See Color Management.

DDC/CI Safety Model

DisplayTune currently uses these MCCS VCP codes:

Control	VCP
Brightness	`0x10`
Contrast	`0x12`
Red gain	`0x16`
Green gain	`0x18`
Blue gain	`0x1A`

DisplayTune does not infer VCP support from a brand, model, or OSD menu, and it does not guess a maximum value. A control becomes writable only after that exact VCP responds successfully on the current monitor, input, and connection path.

In multi-display configurations, DisplayTune maps each Core Graphics display to its IORegistry DDC service using hardware properties. All hardware writes are disabled when the mapping is ambiguous.

Implementation details are documented in DDC/CI Design.

Monitor Strategy Catalog

Strategy matching follows this order:

Exact VID + PID match
→ Product-name fallback
→ Generic 1080p / 1440p / 4K / 5K / ultrawide strategy

The initial catalog includes representative models from Dell, LG, GIGABYTE, BenQ, ASUS, Samsung, AOC, Philips, ViewSonic, HP, Lenovo, MSI, and Acer.

Strategy records provide identification, conservative resolution/brightness ranges, command timing, and OSD starting points. They never bypass runtime DDC probing.

See Monitor Compatibility and Strategy Data.

Mac Match and Visual Calibration

DisplayTune provides three editable visual targets:

Mac Match: preserves the monitor ICC's real panel primaries, uses D65 and the exact macOS system sRGB tone-response curves, and adds an editable neutral VCGT.
sRGB Target: starts from the macOS system sRGB profile for general SDR compatibility.
Apple Display P3: starts from the macOS Display P3 profile and is intended only for panels physically capable of a P3-class gamut.

The visual matching wizard displays equivalent patches on the target and reference displays. It lets you adjust white point, RGB balance, brightness, and gamma, then saves the result to the selected DisplayTune ICC.

Automatic visual search scans the same parameters inside conservative ranges. It does not decide which result is objectively correct; the user stops the search when it visually matches the reference.

Physical Colorimeter

The Colorimeter tab requires a real USB optical measurement device. It is not a software-only colorimeter simulation.

Install ArgyllCMS separately:

brew install argyll-cms

Then connect an ArgyllCMS-supported Calibrite, X-Rite, Datacolor Spyder, or similar instrument. DisplayTune calls dispcal and spotread, verifies the generated ICC with ColorSync, and installs the completed measured profile.

Without physical hardware, visual matching and automatic visual search remain available, but their results are not measurement-grade calibration.

Resolution Rollback

Display mode changes are applied to the current macOS session. Before switching, DisplayTune keeps the original mode and starts a 15-second timer:

Select Keep when the new mode displays correctly.
Select Restore to return immediately.
If the screen becomes unusable, wait for the timer to expire.

No recovery mechanism can protect against every driver or system failure. Avoid disconnecting the target display while the rollback timer is active.

Automation

Restore on reconnect: reapplies the saved per-display profile after the monitor reconnects.
Launch at login: uses SMAppService.mainApp; install the application in a stable .app location first.
Day/night schedule: uses D65 and model-specific daytime brightness during the day, then switches to a warmer 4200 K target and lower brightness at night.

When hardware brightness is unavailable, software dimming may be used. Software dimming reduces output code values and is not equivalent to lowering the panel backlight.

Safety Boundaries

DDC uses runtime-loaded IOKit/IOAVService symbols that Apple does not publicly guarantee as a stable API. A future macOS update may break this path.
ICC and software gamma adjustments mainly affect ColorSync-managed SDR content. HDR, games, video pipelines, remote desktops, or special full-screen renderers may bypass them.
Software cannot measure panel aging, backlight spectrum, viewing angle, screen uniformity, ambient light, or individual visual differences.
Automatic visual search explores parameters; it does not measure objective color accuracy.
Visual matching should compare equivalent content in the same color space at fixed reference brightness.
Photography, printing, mastering, and other color-critical work should use a physical colorimeter or spectrophotometer to create a measured profile for the actual monitor and input.
The project does not currently ship an official Developer ID-signed and notarized release. Source-built application bundles use ad-hoc signing by default.

Privacy

DisplayTune has no account, telemetry, analytics, cloud synchronization, or network client. Per-display profiles and automation settings are stored locally in UserDefaults. Generated ICC profiles are written to ~/Library/ColorSync/Profiles/.

ArgyllCMS is an optional external tool installed separately by the user.

Documentation

Detailed documentation is currently primarily in Simplified Chinese. English documentation and UI localization contributions are welcome.

Development and Tests

./scripts/check.sh

The script runs:

swift run DisplayTuneCoreChecks
swift run DisplayTuneICCChecks
swift build -Xswiftc -warnings-as-errors

Before contributing a monitor strategy, add EDID matching checks and record the evidence level for any VCP claims. See CONTRIBUTING.md.

Contributing

Contributions are welcome for:

New monitor VID/PID values and input-specific EDID aliases
Real per-feature VCP read results
Apple Silicon and Intel compatibility reports
Dock, adapter, KVM, and cable compatibility reports
ICC, ColorSync, resolution rollback, and sleep/wake issues
Documentation, translation, accessibility, and UI improvements

Please read the Contribution Guide, Code of Conduct, and Security Policy.

Version

Current version: 0.7.1 (Build 12)

See CHANGELOG.md for release notes.

License

DisplayTune is open source under the MIT License.

FilesExpand file tree

README.en.md

Latest commit

History