Frequently Asked Questions

When a Mac device sends a command to a monitor through DDC, the whole system has to pause until the monitor replies.

Some monitors have very slow response times, and some don't respond at all.

If you enabled Refresh values from monitor settings or Smooth Transition, your system might freeze or be very slow because of one of those slow monitors.

Try disabling them from the Lunar UI if possible:

If your system is constantly freezing and you can't disable those options in the Lunar UI, try doing the following steps in Safe Mode:

• Make sure Lunar is not running
• Open Terminal.app
• Run the following commands
  • defaults write fyi.lunar.Lunar refreshValues 0
  • defaults write fyi.lunar.Lunar smoothTransition 0
• If the above doesn't work, you can reset Lunar settings by deleting the following file:
  • ~/Library/Preferences/fyi.lunar.Lunar.plist

When the screens wake, Lunar forcefully re-applies the brightness and contrast values to all monitors to avoid a mismatch between what's in the UI and the actual monitor values.

This can cause lag if monitors take longer to respond or the monitors might behave in weird ways if the re-apply happens at the same time as the macOS display reconfiguration process.

You can disable this behaviour from the Advanced settings screen by unchecking the following checkbox (see the image below):

The Persistent IDs problem

For Lunar to be able to store settings for a monitor (name, brightness, input hotkey, etc.), it needs a way to uniquely identify that monitor through disconnects and reconnections.

The problem is that macOS doesn't always offer such a persistent ID.

So Lunar has to find workarounds, like reading the firmware data of the monitor, and computing a number from it that can be used as an ID.

The problem is that monitors of the same model usually have the exact same firmware data.

So if you, for example, use two Dell monitors of the same kind, that computed ID is the same for both, so it is not unique and can't be used.

This leads to Lunar storing settings for a monitor with an ID that can:

• Disappear completely when the monitor is disconnected/sleeping
  • This causes the monitor to be shown with default settings in Lunar the next time it connects
• Be reassigned to a different monitor
  • This causes the settings to be assigned to the wrong monitor

Unfortunately this problem is not yet solvable, but I'm actively looking into anything that can help work around this limitation.

Lunar needs Accessibility permissions to listen for Media Keys (brightness and volume).

To make sure the permissions are enabled, launch System Preferences->Security & Privacy and check if Lunar is present and enabled in the Accessibility list.

If it is, try removing it and re-adding it just be sure it isn't a code signing issue.

If the keys still don't work, it's possible that:

• the system permissions database is corrupted (see fix here)
• your monitor doesn't support brightness/volume control

To check why brightness doesn't work, try running diagnostics by clicking on Open Lunar Diagnostics from the Lunar menu.

These are some of the cases where volume control is not available:

• If you see Software Control under your monitor name in Lunar
• If you use an M1 Mac and see Native Control under your monitor name in Lunar
• If DDC is not responsive because of a non-compliant hub/dock/adapter (Lunar should prompt you about that)
  • In this case you could try a different way to connect the monitor to your Mac

Sync Mode only syncs the built-in display of a MacBook/iMac to the external monitors. Not the other way around.

In fact, Lunar doesn't control the built-in display in any way. Whenever you use the brightness keys or the Touchbar to adjust the built-in display, Lunar simply ignores that event and the macOS system does the work.

The reasons for this are the following:

• This allows Lunar to take advantage of the built-in light sensor of a MacBook
• There is no public API for changing the built-in display brightness
  • There is a private API but it can screw up the response curve of the light sensor
  • It's not easy or obvious how that response curve could be reset (an SMC reset might be needed)
• If you have more than one external monitor, it would not be clear which one to use as a source for syncing

In a nutshell:

• Brightness keys with no modifiers control the built-in display (or all monitors when there's no builtin display e.g. lid closed, Mac Mini)
• Ctrl+Brightness controls all external monitors brightness
• Ctrl+Shift+Brightness controls all external monitors contrast
• Adding Option to the combinations will change the values in small steps

More details:

First, there is an important distinction between Media Keys and simple hotkeys.

---

Media Keys

Media Key events are sent when the checkbox for Use F1, F2, etc. keys as standard function keys on external keyboards is not checked and you press:

• F1/F2 (brightness)
• F10/F11/F12 (volume)
• Touchbar buttons for brightness and volume (Touchbar sliders can't be intercepted by Lunar, only buttons)

Media Keys also need Accessibility permissions to be enabled for Lunar, while simple hotkeys can work without that.

Hotkeys

Simple hotkeys are what you can configure on Lunar's HOTKEYS page and don't need special permissions.

If you haven't checked the checkbox for Use F1, F2, etc. keys as standard function keys on external keyboards, you will have to hold Fn when pressing hotkeys that contain function keys like F1, F2 etc. Otherwise, something like Command+F1 will actually send Command+Brightness which is a Media Key.

---

Special cases of Brightness keys

These special cases apply when 2 or more external monitors are used with Lunar.

• Sync Mode
  • Brightness keys (with no modifiers) are ignored by Lunar and handled by the system
  • This ensures the built-in display is adjusted by keys, and the external monitors are adjusted by the Sync algorithm
• No built-in display (MacBook lid closed, Mac Mini, Hackintosh)
  • Ctrl+Brightness controls the monitor where the cursor is
  • This allows for fine tuning the Sync curve per monitor, by only using the keys and not having to use the Lunar UI

If you see the Software Controls tag under the monitor name in the Lunar UI, then Lunar can't use DDC to control this monitor.

Lunar can approximate a decrease in brightness by changing the software gamma tables to make the colors look darker.

This doesn't change the hardware brightness as DDC does and can only decrease brightness, not increase it.

You have to manually set the monitor's brightness and contrast (using the monitor physical buttons) to the highest possible values that look good for your monitor.

Yes, it is a known issue.

The MacBook display can increase the brightness on isolated local regions, which is the case when rendering HDR content.

The problem is that the system reports the highest brightness of the built-in display, not an average.

So even if the display contains only a small HDR-extra-bright-white square, Lunar receives that brightness from the system, and sends it to the external monitors.

You can read more about this here: https://prolost.com/blog/edr

Also, I have no idea how to fix this.

I tried to include the local cloud cover into the Location Mode algorithm but failed because of multiple reasons.

• Weather APIs are expensive
  • Location Mode computes brightness and contrast every minute, doing an API request per minute, per user, would add up to a lot of requests
  • I tried implementing some caching mechanism but it didn't help much
• Cloud Cover percentage can be quite irrelevant
  • On some days, I would get a 95% cloud cover yet it was sunny where I standed
  • This can happen if the weather station sensors are not close to your specific location
• Factoring in cloud cover is hard
  • The way the current algorithm is written doesn't allow for adding additional factors easily
  • A major refactor would be needed to make this work

If you can't use Sync Mode but would like your monitors to better react to the changes in the ambient light around you, you could try Sensor Mode.

If you use one of Lunar's adaptive modes (Sync, Location, Sensor), you can simply decrease the brightness/contrast of the brighter monitor until it looks the same as the other one.

You can use Control+Brightness keys to adjust only the active monitor when the MacBook lid is closed, or use the Lunar UI otherwise.

Lunar will learn from that manual adjustment and try to match the monitors better in the future.

If the discrepancy appears again, just keep adjusting the brighter/darker monitor until Lunar has enough data to match a perfect curve.

This usually happens if you use identical monitors which have the exact same firmware data. Lunar tries to differentiate between them using multiple workarounds but it can still fail.

This can also happen if you use a Thunderbolt hub with two or more monitor connections. Most of these hubs forward DDC messages to only one of the monitors.

Finally, it's possible that the not-working monitor is connected through a non-compliant adapter.

Check the Non-compliant hub/dock/adapter section in this question for more details.

In some cases, Lunar won't be able to use DDC to change the hardware brightness/contrast/volume of one or more of your monitors.

Some of these cases include:

• M1 Mac
  • M1 doesn't provide a way for apps to make arbitrary I²C requests, which are needed for communicating through DDC
  • Lunar provides two workarounds for this issue: Lunar on M1
• DisplayLink
  • DisplayLink uses proprietary drivers and while it has support for DDC, that functionality is not provided on macOS
• HDMI on Mac Mini
  • I haven't figured out why but the Mac Mini's HDMI port blocks DDC requests
  • Using the Thunderbolt connector fixes this (through USB-C-to-HDMI cable, Thunderbolt hub, etc.)
• Non-compliant hub/dock/adapter
  • This is the most common issue and it can't be fixed in software
  • Because most new Macs only have USB-C ports, most users use some kind of Thunderbolt hub or dock
  • A lot of these hubs block DDC requests completely,
  • If the hub supports more than one monitor, it usually forwards DDC requests to only one of them
  • Here are some of the hubs that are known to work:
    • Baseus HDMI, USB-C PD, 3 USB-A
    • Baseus HDMI, USB-C PD, 3 USB-A + Ethernet
    • Baseus HDMI, USB-C PD, 3 USB-A + Ethernet + SD/microSD reader
    • VANMASS HDMI, USB-C PD, 3 USB-A + Jack + USB-C Data + SD/microSD reader

Unfortunately macOS offers no way to turn off the built-in display while the lid is open. The only thing we can do is set the built-in brightness to 0 so it appears off but there are a number of disadvantages to this solution:

• Windows and spaces on the built-in display will not move to the external monitor, you just won't be able to see them anymore
• The GPU will still use power to render to that display even though you won't be able to see anything.
• The light sensor response curve will be completely messed up because it will try to adapt to you wanting 0% brightness even in well lit environments
• Lunar's Sync Mode won't work correctly because that mode reads the built-in display brightness to Sync it to external monitors. The system doesn't offer a way to read the ambient light sensor directly

These are system settings and are not honored by any macOS app

Lunar (and all other apps) have to listen for brightness keys explicitly and the above settings don't have any effect on apps.

To disable Lunar's own media keys listener, uncheck Listen for brightness keys on the Hotkeys page.

Corrupted permissions database

First thing to try is to reset the System's permissions database.

Launch Terminal.app and run the following command:

Note: to run a command, paste the text in the Terminal and press Enter after that

tccutil reset all fyi.lunar.Lunar

Then reboot the system and launch Lunar again.

---

If you get a message saying you don't have permissions to do the above, you can try resetting all permissions:

tccutil reset All

Note: This will reset the permissions for all apps on the system.

And as a last resort, you can delete the whole permissions database using the following steps:

1. Open Finder
2. Go to /Library/Application\ Support/com.apple.TCC
3. Find TCC.db and move it to Trash

Then reboot the system and launch Lunar again.

---

Wrong app location

Where Lunar is launched from matters.

If you, for example, launched Lunar from Downloads and gave it permissions then, and then you moved it to Applications, then those permissions are not valid.

The macOS system stores permissions based on path and code signature.

You have to manually remove Lunar from the Accessibility list and add it again from the path you always launch it.

The active monitor hotkey behaviour was changed because a lot of users requested it.

Check the following section for more details on what is now the default behaviour: How do hotkeys work in Lunar?

Basically, Ctrl+Brightness is now the way to control the external monitor as that is also how macOS works natively with Ultrafine and Thunderbolt monitors.

You can still go back to the old behaviour (mostly) by disabling the Send keys to all monitors setting:

There are some special cases where this will not work exactly in the same way as before.

Special cases of Brightness keys

• Built-in display + single external monitor (e.g. Macbook with lid open, iMac)
  • Brightness keys (with no modifiers) are ignored by Lunar and handled by the system
  • Ctrl+Brightness controls the external monitor
  • This allows for controlling both the built-in display and the external monitor without taking your hands off the keyboard
• Sync Mode + more than one external monitor
  • Brightness keys (with no modifiers) are ignored by Lunar and handled by the system
  • This ensures the built-in display is adjusted by keys, and the external monitors are adjusted by the Sync algorithm
• No built-in display + more than one external monitor
  • Ctrl+Brightness controls the monitor where the cursor is
  • This allows for fine tuning the Sync curve per monitor, by only using the keys and not having to use the Lunar UI