Custom LUT Filters

Three-dimensional look-up tables (LUTs) map input colors to output colors. This manager lets you import a reusable LUT and tell BetterDisplay how its values should be interpreted. Saving it here makes the LUT available in the app. Each display, PIP window, Video Filter Window or stream can then use it independently.

Where to find it: Settings > Displays > Overview > Custom LUT Filters…. A populated Custom LUT filters section in an image/filter menu also offers Manage….

Choose a LUT authored for the color conditions you intend to use. HDR LUT handling is marked Experimental and assumes a fixed display calibration. Use the settings supplied by the LUT’s author. The manager cannot determine those settings from the file for you.

New custom LUT filter with Guide Identity SDR, sRGB signal space, 100-nit reference white and enabled Add button

A valid SDR CUBE import exposes its name, signal space and reference white before it is saved.

Import a CUBE file

Select Import Custom LUT… and choose one file. BetterDisplay reads UTF-8 CUBE text containing a 3D LUT. After import, a form lets you check the LUT’s name and settings. Nothing is saved or applied until you confirm it.

The pending form shows the original CUBE file and CUBE dimension. Unique name starts from the CUBE title or filename, with a numeric suffix when needed. Choose a name you will recognize in the menus where you apply filters. Names must be unique. BetterDisplay ignores spaces at either end, letter case and accents when comparing them. A duplicate name shows A custom filter with this name already exists. Choose a different name to enable the Add button.

Add Custom LUT Filter saves a valid definition, while Cancel discards the pending import. BetterDisplay stores a compressed copy of the original file in its settings. You can export that copy later, so you do not need to keep the file at its import location.

Supported files and validation

The CUBE file must have a LUT_3D_SIZE from 2 to 128, and its source must be no larger than 256 MiB. One-dimensional and mixed 1D/3D CUBE files are rejected.

BetterDisplay checks the cube dimension, color values and number of entries. It also checks the input range, which tells it which color values the table covers. An invalid import produces a Custom LUT Filter alert explaining the cause, such as a missing dimension, an invalid data line or the wrong number of entries. If the file declares an input range, each maximum must be greater than its corresponding minimum.

A larger cube gives the color mapping a finer grid, with greater storage and processing requirements. It does not increase the pixel resolution of your image.

Content range, signal space and white level

The interpretation fields tell BetterDisplay what the LUT's numbers mean. Match them to the conditions for which the LUT was created. Do not rely on the filename to choose the settings.

A new import starts with HDR content range off, sRGB, and SDR/reference white: 100 nits. For SDR, the Signal space menu offers sRGB, Rec. 709, and Display P3. Choose the space used by the LUT.

Enabling HDR content range on a new import selects fixed Rec. 2100 PQ, sets reference white to 203 nits, and sets HDR target peak to 1000 nits. Turning it off resets the pending import to sRGB with 100-nit reference white. These are starting values, not measurements of your display.

Setting reference white and peak

SDR/reference white records the LUT’s authored white-level assumption. It must be a positive finite value. For HDR, HDR target peak must also be finite and must exceed reference white. These values describe the LUT and are checked for validity. They do not apply a luminance gain, or set or measure your monitor’s brightness. Enter the levels used when the LUT was created. Nits measure luminance.

Pending Guide Identity PQ LUT with HDR enabled, Rec. 2100 PQ, 203-nit reference white and 1000-nit target peak

HDR imports use a fixed PQ signal space and explicit reference-white and peak luminance values.

HDR LUT form with both reference white and target peak at 203 nits and Add Custom LUT Filter disabled

The target peak must exceed the reference white before an HDR LUT can be added.

Existing filters, replacement and export

Each existing entry summarizes its content range, signal space, reference white, optional HDR peak, filename and cube dimension. Use Edit… to change the interpretation fields or Upload… to stage a replacement CUBE.

A replacement keeps the filter's identity, assignments and configured content range. Displays and previews already using it will use the replacement too. Check the interpretation settings if the replacement was created for different conditions. Done saves the changes and updates the displays and previews using the LUT. Cancel discards the staged name, settings and replacement.

Export Original LUT… opens a save dialog with the original filename and exports the stored CUBE source. Signal space and reference white remain separate app settings. Exporting does not add them to the CUBE file. Problems reading stored data or exporting appear in a Custom LUT Filter alert.

Delete and apply

Importing alone does not change display colors. To use the saved definition, enable it from the target's Image Adjustments, PIP, Video Filter Window or Stream menu. Each target chooses independently whether to use it.

Several targets can share one definition. Editing or replacing that definition can therefore affect all its enabled uses, even though enabling the filter remains a per-display or per-stream choice.

Delete… always asks for confirmation. If the filter is in use, the message reports how many display or stream configurations have it enabled. Delete removes the definition and disables those assignments, including remembered displays and stream configurations. Cancel preserves them.

Guide Identity SDR in edit mode with Upload, Cancel and Done controls

Edit a saved LUT’s configuration or upload a replacement while keeping its identity.

Delete Custom LUT Filter confirmation reporting one display or stream assignment

The deletion confirmation reports assignments that will also be disabled.

See Software XDR/HDR Upscaling and Dimming for the separate color-table and brightness controls.

Follow the whole-display and separate-preview LUT tutorial for a sample with a visible warm-color effect, separate display and preview selections, and cleanup steps.

Additional information

This section explains which features require Pro and how availability differs between Mac platforms.

Features requiring Pro license

Importing and adding custom LUT definitions.
Editing their settings or replacing their CUBE source.
Applying custom LUT filters to displays or streams.

Existing filters can still be exported or deleted when Pro editing is unavailable.

Platform compatibility

The LUT manager and its file operations are available on both Apple silicon and Intel Macs. Applying a filter depends on the target's image-filtering and capture capabilities. The stream filtering path enables extended dynamic range only on Apple silicon, so an Intel Mac can show the HDR interpretation fields without supporting HDR stream output. HDR LUT handling remains experimental and requires the fixed calibration described above.