Skip to content

docs: add Troubleshooting section for dim screen captures and slider brightness jump #1913

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ankitdhandharia wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add Troubleshooting section for dim screen captures and slider brightness jump #1913

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
docs: add Troubleshooting section for dim captures and slider jump 
Document why software-dimmed non-DDC displays appear dull in
screenshots, screen recordings, and screen sharing (shade overlay is
captured; gamma dimming is not), and how to fix it by disabling
'Avoid gamma table manipulation'. Also explain the sudden brightness
change at the software/hardware dimming handover on non-DDC displays.

These are among the most frequently repeated support questions in
Discussions/Issues; the README previously had no Troubleshooting or
FAQ section covering them.
  • Loading branch information
@ankitdhandharia
ankitdhandharia committed Sep 23, 2026
commit 831645f98dfb4a67afa278d80e9f9ff85defb494
15 changes: 15 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,21 @@ Notable exceptions for hardware control compatibility:
- Some displays (notably EIZO) use MCCS over USB or an entirely custom protocol for control. These displays are supported with software dimming only.
- DisplayLink docks and dongles do not allow for DDC control on Macs, only software dimming is available for these connections.

## Troubleshooting

### Screenshots, screen recordings, or screen sharing look dim/dull

If your display does **not** support hardware (DDC) brightness control, MonitorControl dims it in software. There are two software methods, and which one is in use decides whether screen captures are affected:

- **Gamma table manipulation** (default) adjusts the GPU output curve. Your eyes see the dimmed screen, but screenshots, screen recordings, and screen sharing capture the framebuffer *before* the curve is applied, so they stay at normal brightness.
- **Shade overlay** (used when *Avoid gamma table manipulation* is enabled, or for AirPlay/Sidecar/DisplayLink virtual displays) lays a dark layer over the screen. This layer *is* part of the captured image, so captures look dim.

Fix: open `Settings` » `Displays`, enable `Show advanced settings`, and make sure **`Avoid gamma table manipulation` is turned OFF** for the affected display. If the display is virtual (AirPlay/Sidecar/DisplayLink), only overlay dimming is available and this limitation is expected.

### Brightness changes suddenly at a certain point on the slider

On a display without hardware (DDC) control, the lower part of the slider dims in software while the upper part expects hardware dimming, so the handover between the two can produce a sudden jump. Turning OFF `Avoid gamma table manipulation` lets gamma (software) dimming cover the full range smoothly.

## Contributing to the project

- If you want, you can fork the code, make improvements and submit a pull request to improve the app. Accepting a PR is solely in the hands of the maintainer - before making fundamental changes expecting it to be accepted, please consult the maintainer of the project!
Expand Down