weston.ini(5)

📦
version 16.0.0 · 17 versions
, in ubuntu stonking

✨ weston.ini(5) ✨

File Formats Manual but make it group chat. This is the manual for weston.ini(5), the config file for Weston, a Wayland compositor. If you're trying to make Weston do your bidding, bestie, this is the file. 💅

💖 NAME 💖

weston.ini — configuration file for Weston, a Wayland compositor.

🦋 INTRODUCTION 🦋

Weston gets its configuration from its command line parameters and the configuration file described right here. That's the whole intro. Short, sweet, iconic. ✨

🌸 DESCRIPTION 🌸

Weston uses a configuration file called weston.ini for its setup. When the server is started, the weston.ini configuration file is searched for in one of these places:

$XDG_CONFIG_HOME/weston.ini   (if $XDG_CONFIG_HOME is set)
$HOME/.config/weston.ini      (if $HOME is set)
weston/weston.ini in each
    $XDG_CONFIG_DIR           (if $XDG_CONFIG_DIRS is set)
/etc/xdg/weston/weston.ini    (if $XDG_CONFIG_DIRS is not set)

Where environment variable $HOME is the user's home directory, $XDG_CONFIG_HOME is the user specific configuration directory, and $XDG_CONFIG_DIRS is a colon : delimited list of configuration base directories, such as /etc/xdg-foo:/etc/xdg.

The weston.ini file is composed of a number of sections which may be present in any order, or omitted to use default configuration values. Each section has the form:

[SectionHeader]
Key1=Value1
Key2=Value2
    ...

The spaces are significant. Comment lines are ignored:

#comment

The section headers are:

  • core — The core modules and options
  • libinput — Input device configuration
  • shell — Desktop customization
  • launcher — Add launcher to the panel
  • output — Output configuration
  • input-method — Onscreen keyboard input
  • keyboard — Keyboard layouts
  • terminal — Terminal application options
  • xwayland — XWayland options
  • autolaunch — Autolaunch options

Possible value types are string, signed and unsigned 32-bit integer, and boolean. Strings must not be quoted, do not support any escape sequences, and run till the end of the line. Integers can be given in decimal (e.g. 123), octal (e.g. 0173), and hexadecimal (e.g. 0x7b) form. Boolean values can be only 'true' or 'false'.

👑 CORE SECTION 👑

The core section is used to select the startup compositor modules and general options. This is the main character section, no cap. 🫶

  • shell=desktop — specifies a shell to load (string). This can be used to load your own implemented shell or one with Weston as default. Available shells in the /usr/lib/x86_64-linux-gnu/weston directory are:
    • desktop
    • ivi
    • kiosk
    • lua
  • xwayland=true — ask Weston to load the XWayland module (boolean).
  • backend=headless — overrides the default backend. Available backends are:
    • drm
    • headless
    • rdp
    • pipewire
    • vnc
    • wayland
    • x11
  • repaint-window=N — Set the approximate length of the repaint window in milliseconds. The repaint window is used to control and reduce the output latency for clients. If the window is longer than the output refresh period, the repaint will be done immediately when the previous repaint finishes, not processing client requests in between. If the repaint window is too short, the compositor may miss the target vertical blank, increasing output latency. The default value is 7 milliseconds. The allowed range is from 1 to 1000 milliseconds, but the compositor will reduce large values to 1 millisecond less than the current refresh rate.
  • idle-time=seconds — sets Weston's idle timeout in seconds. This idle timeout is the time after which Weston will enter an "inactive" mode and screen will fade to black. A value of 0 disables the timeout.
Important: This option may also be set via Weston's -i command line option and will take precedence over the current .ini option. This means that if both weston.ini and command line define this idle-timeout time, the one specified in the command-line will be used. On the other hand, if none of these sets the value, default idle timeout will be set to 300 seconds.
  • require-input=true — require an input device for launch
  • require-outputs=any — configures the behavior if Weston fails to configure and enable outputs.

Depending on the use-case, it may be preferable to ensure that Weston only starts if it can enable all available outputs, or that it ignores failed outputs. The possible options are:

  • all-found — all available outputs must be enabled
  • any — start if any output could be enabled
  • none — start even if no output was enabled
  • wait-for-debugger=true — Raises SIGSTOP before initializing the compositor. This allows the user to attach with a debugger and continue execution by sending SIGCONT. This is useful for debugging a crash on start-up when it would be inconvenient to launch weston directly from a debugger. Boolean, defaults to false. There is also a command line option to do the same.
  • remoting=remoting-plugin.so — specifies a plugin for remote output to load (string). This can be used to load your own implemented remoting plugin or one with Weston as default. Available remoting plugins in the __libweston_modules_dir__ directory are:
    • remoting-plugin.so
  • renderer=auto — Selects a renderer to use for internal composition when required, or auto to select the most appropriate renderer. Available renderers are:
    • auto
    • gl
    • noop
    • pixman

Not all backends support all renderers.

  • use-pixman=true — Deprecated in favour of the renderer= option. Enables pixman-based rendering for all outputs on backends that support it. Boolean, defaults to false. There is also a command line option to do the same.
  • color-management=true — Enables color management and requires using GL-renderer. Boolean, defaults to false.
TENTATIVE, EXPERIMENTAL, WORK IN PROGRESS: Color management enables the use of ICC files to describe monitor color behavior, Wayland protocol extensions for clients to describe their color spaces and perform monitor profiling, and tone mapping required to enable HDR video modes. This extended functionality comes at the cost of heavier image processing and sometimes a loss of some hardware off-loading features like composite-bypass.
  • output-decorations=true — For headless-backend with GL-renderer only: draws output window decorations, similar to what wayland-backend does for floating output windows. Boolean, defaults to false. These decorations cannot normally be screenshot. This option is useful for the Weston test suite only.
  • output-straight-alpha=true — Require straight alpha framebuffers from renderers for outputs. Only supported by the headless backend. Boolean, defaults to false.
  • placeholder-color=0xRRGGBB — sets the color of the placeholder (unsigned integer). The hexadecimal digit pairs are in order red, green, and blue. This placeholder is used for content-protection or when we're not able to lift a surface/view in a HW plane, but we require direct scan-out of buffers. Defaults to 0x660000 (red grenadier).

✨ LIBINPUT SECTION ✨

Okay bestie, this section is the one where you tell Weston how to handle your input devices when it's using the libinput input device backend. The defaults? Not our problem — those come straight from libinput and they change per device based on whatever makes the most sense for that particular gadget. Slay.

Here's everything you can configure:

  • enable-tap=false — turns on tap to click for touchpad girlies. 💅
  • tap-and-drag=false — for touchpads that already have enable-tap on. If you tap, then tap a second time but hold it, the virtual mouse button stays pressed for as long as your finger's still on the touchpad. So you can click-and-drag with taps alone. iconic.
  • tap-and-drag-lock=false — for touchpads with both enable-tap and tap-and-drag turned on. Mid tap-and-drag, if you lift your finger for less than a certain number of milliseconds and then touch again, the virtual mouse button stays pressed and the drag just keeps going. no cap.
  • disable-while-typing=true — for devices that get accidentally triggered while you're typing on the keyboard and ruin your whole flow 😭. Disables them while the keyboard is in use.
  • middle-button-emulation=false — for pointer devices that have left and right buttons but no middle one. Turn this on and a middle button event fires when you press left and right at the same time. ✨
  • left-handed=false — configures the device for left-handed people. What it actually does depends on the device, fr fr. For pointers with left and right buttons, the buttons get swapped. On tablets, the tablet is logically turned upside down, because it's gonna be physically turned upside down anyway. 🦋
  • rotation=n — changes the direction of the logical north by rotating it n degrees clockwise away from the default orientation, where n is a whole number between 0 and 359 inclusive. Mainly needed for trackballs — lets you orient that thing sideways, for example.
  • accel-profile={flat,adaptive} — sets the pointer acceleration profile. Here's the tea: the pointer's screen speed is proportional to the physical speed with some constant of proportionality, and we're calling that constant alpha. flat keeps alpha fixed (peep accel-speed). adaptive makes alpha increase with physical speed, which gives you more control when you're moving slow and more reach when you're moving fast. adaptive is the default. 👑
  • accel-speed=v — if accel-profile is flat, this just sets the value of alpha, simple. If accel-profile is adaptive, the effect is more complicated, but generally it changes the pointer's speed. v is normalised and must lie in the range [-1, 1]. The exact mapping between v and alpha is hardware-dependent, but higher values = higher cursor speeds. periodt.
  • natural-scroll=false — enables natural scrolling, which mimics touchscreen scrolling behaviour. Meaning: if the wheel or your finger(s) move down, the surface scrolls up instead of down — as if your finger(s) were literally in contact with the surface being scrolled. 🫶
  • scroll-method={two-finger,edge,button,none} — sets the scroll method. two-finger scrolls with two fingers on a touchpad. edge scrolls with one finger on the right edge of a touchpad. button scrolls when the pointer moves while a certain button is held down (see scroll-button). none disables scrolling completely. 🌸
  • scroll-button={BTN_LEFT,BTN_RIGHT,BTN_MIDDLE,...} — for devices with scroll-method set to button. Specifies which button triggers the scrolling. Hit up /usr/include/linux/input-event-codes.h for the complete list of possible values.
  • disable-input=false — ignore all libinput-based input devices. 💀
  • touchscreen_calibrator=true — advertises the touchscreen calibrator interface to all clients. Heads up bestie, this is a potential denial-of-service attack vector, so it should only be enabled on trusted userspace. Boolean, defaults to false.

The interface is required for running touchscreen calibrator applications. It hands the application raw touch events, bypassing the normal touch handling, and it also lets the application upload a new calibration into the compositor.

Even though this option lives in the libinput section, it affects all Weston configurations regardless of which backend is used. If the backend doesn't use libinput, the interface can still be advertised — it just won't list any devices.

  • calibration_helper=/bin/echo — an optional calibration helper program to permanently save a new touchscreen calibration. String, defaults to unset.

The program you give it gets executed with seven arguments when a calibrator application asks the server to take a new calibration matrix into use. It runs synchronously, so it'll block Weston for however long it takes. If the program's exit status is non-zero, Weston will not apply the new calibration. If the helper is unset, or the program exits with status zero, Weston uses the new calibration immediately.

The program is invoked as:

calibration_helper syspath m1 m2 m3 m4 m5 m6

where syspath is the udev sys path for the device, and m1 through m6 are the calibration matrix elements in libinput's LIBINPUT_CALIBRATION_MATRIX udev property format. The sys path is an absolute path and starts with the sys mount point.

🎀 SHELL SECTION 🎀

This is where you customise the compositor, bestie. Just a lil warning: some keys may not be handled by different shell plugins, so don't come for me if something doesn't take. 🙈

Here are the entries that can show up in this section:

  • client=/usr/libexec/weston-desktop-shell — specifies the path for the shell client to run. You can pass arguments and environment variables to the program, like this: ENVFOO=bar ENVBAR=baz /path/to/program --arg anotherarg — entries are space-separated, and there is no support for quoting. If no client is specified, weston-desktop-shell gets launched (string).
  • background-image=file — sets the path for the background image file (string).
  • background-type=tile — determines how the background image is drawn (string). Can be centered, scale, scale-crop, scale-fit or tile (default). ✨ centered shows the image once, centered — if the image is smaller than the output, the rest of the surface is in background color, and if the image does fit the output it gets cropped left and right, or top and bottom. scale means scaled to fit the output precisely, no aspect ratio preservation. scale-crop preserves aspect ratio, scales the background image just big enough to cover the output, and centers it — you end up with cropping from left and right, or top and bottom, if the aspect ratio doesn't match the output. scale-fit is similar to scale-crop but it fits to the output so the image doesn't get cropped. tile repeats the background image to fill the output.
  • background-color=0xRRGGBB — sets the color of the background (unsigned integer). The hexadecimal digit pairs go in order red, green, and blue. For backward compatibility, 0xAARRGGBB format values are allowed, but AA is ignored and the background is always solid. And since a background color of 0 means no background color, you can specify a black background as 0xff000000.
  • clock-format=format — sets the panel clock format (string). Can be none, minutes, seconds, minutes-24h, seconds-24h. By default, the minutes format is used.
  • panel-color=0xAARRGGBB — sets the color of the panel (unsigned integer). The hexadecimal digit pairs go in order transparency, red, green, and blue. Examples:
0xffff0000    Red
0xff00ff00    Green
0xff0000ff    Blue
0x00ffffff    Fully transparent
  • panel-position=top — sets the position of the panel (string). Can be top, bottom, left, right, none.
  • locking=true — enables screen locking (boolean).
  • animation=zoom — sets the effect used for opening new windows (string). Can be zoom, fade, none. By default, no animation is used.
  • close-animation=fade — sets the effect used when closing windows (string). Can be fade, none. By default, the fade animation is used.
  • startup-animation=fade — sets the effect used by desktop-shell when starting up (string). Can be fade, none. By default, the fade animation is used.
  • focus-animation=dim-layer — sets the effect used with the focused and unfocused windows. Can be dim-layer, none. By default, no animation is used.
  • allow-zap=true — whether the shell should quit when the Ctrl-Alt-Backspace key combination is pressed. 👀
  • disallow-output-changed-move=false — whether the shell should move a client's window to a different/another output than the one assigned initially, when that original one is no longer available / enabled / plugged in.
  • binding-modifier=ctrl — sets the modifier key used for common bindings (string), like moving surfaces, resizing, rotating, switching, closing, and setting the transparency for windows, controlling the backlight, and zooming the desktop. Peep weston-bindings(7). Possible values: none, ctrl, alt, super (default).
  • cursor-theme=theme — sets the cursor theme (string).
  • cursor-size=24 — sets the cursor size (unsigned integer).
  • lua-script=script — sets the Lua script which will be interpreted and executed when starting the lua-shell. The path can be either absolute, or relative using the current working directory.

🌈 LAUNCHER SECTION 🌈

There can be multiple launcher sections — one for each launcher. Go off. 💜

  • icon=icon — sets the path to the icon image (string). Just so you know, svg images are not currently supported. 😭
  • displayname=displayname — sets the display name of the launcher that appears in the tooltip.
  • path=program — sets the path to the program that's run when you click this launcher (string). You can pass arguments and environment variables to the program, like so:
path=GDK_BACKEND=wayland gnome-terminal --full-screen

✨ OUTPUT SECTION ✨

okay so bestie, there can be multiple output sections, each one matching a single output. Right now it's only recognized by the drm and x11 backends. lowkey iconic. 💅

  • name=name — sets a name for the output (string). The backend uses the name to identify the output. All X11 output names start with the letter X. All Wayland output names start with the letters WL. Examples of usage:
LVDS1    DRM backend, Laptop internal panel no.1
VGA1     DRM backend, VGA connector no.1
X1       X11 backend, X window no.1
WL1      Wayland backend, Wayland window no.1

See weston-drm(7) for more details. 🦋

  • mode=mode — sets the output mode (string). The mode parameter is handled differently depending on the backend. On the X11 backend, it just sets the WIDTHxHEIGHT of the weston window. The DRM backend accepts different modes, along with an option of a modeline string.

See weston-drm(7) for examples of modes-formats supported by DRM backend. ✨

  • transform=normal — How you have rotated your monitor from its normal orientation (string). The transform key can be one of the following 8 strings:
    • normal — Normal output.
    • rotate-90 — 90 degrees clockwise.
    • rotate-180 — Upside down.
    • rotate-270 — 90 degrees counter clockwise.
    • flipped — Horizontally flipped
    • flipped-rotate-90 — Flipped and 90 degrees clockwise
    • flipped-rotate-180 — Flipped and upside down
    • flipped-rotate-270 — Flipped and 90 degrees counter clockwise
  • scale=factor — The scaling multiplier applied to the entire output, in support of high resolution ("HiDPI" or "retina") displays, that roughly corresponds to the pixel ratio of the display's physical resolution to the logical resolution. Applications that do not support high resolution displays typically appear tiny and unreadable. Weston will scale the output of such applications by this multiplier, to make them readable. Applications that do support their own output scaling can draw their content in high resolution, in which case they avoid compositor scaling. Weston will not scale the output of such applications, and they are not affected by this multiplier.

An integer, 1 by default, typically configured as 2 or higher when needed, denoting the scaling multiplier for the output. no cap, this is the glow-up your tiny apps need. 💖

  • icc_profile=file — If option color-management is true, load the given ICC file as the output color profile. This works only on DRM, headless, wayland, and x11 backends, and for remoting and pipewire outputs. 🌈
  • color-profile=name — Color profiles describe how the display is assumed to behave. Knowing the display color behavior, Weston can adapt window contents to produce the presumed appearance. The option color-management must be set to true for this to work. This works only on DRM, headless, wayland, and x11 backends, and for remoting and pipewire outputs. If icc_profile is also set, that is used instead.

This key creates a parametric profile to be used as the output color profile. The profile can be created from parameters recorded in a color-profile section by referring to it by its name value. Alternatively this key can use one of the special profile names that contain a colon (:).

The default is color-profile=auto:. periodt.

The following special names are accepted:

  • srgb: — Creates a parametric sRGB color profile (gamma 2.2).
  • auto:[flags...] — Creates an automatic parametric color profile.

Automatic parametric color profiles are created based on the eotf-mode and colorimetry-mode configuration keys of the respective output section, and optionally using the monitor reported EDID (DRM-backend only). Multiple flags must be separated by whitespace. The available flags are:

  • edid-primaries — Get primaries and white point from EDID if colorimetry-mode is default. Ignored if EDID does not provide all of them.
  • edid-tf — Get transfer function from EDID if eoft-mode is sdr or hdr-gamma. The transfer function is the power-law curve with the EDID indicated exponent.
  • edid-dr — Get dynamic range information from EDID if eotf-mode is st2084.

Examples:

color-profile=srgb:
color-profile=auto:
color-profile=auto:edid-tf edid-dr
color-profile=auto: edid-primaries
color-profile=my-awesome-display

The last example causes Weston to read the color-profile section that has name=my-awesome-display. iykyk.

Notably, setting

eotf-mode=sdr
colorimetry-mode=default
color-profile=auto:

produces the same color profile as color-profile=srgb:. slay, same energy. 💅

  • color-effect=name — Use the given color effect for the output. For now we only provide color effects for color vision deficiencies (CVD). Only works when option color-management is false.

The effect can be one of the following strings:

  • inversion — color inversion, i.e. the RGB complement
  • grayscale — convert colors to shades of gray
  • deuteranopia — color correction (not simulation) for deuteranopia
  • protanopia — color correction (not simulation) for protanopia
  • tritanopia — color correction (not simulation) for tritanopia
  • seat=name — The logical seat name that this output should be associated with. If this is set then the seat's input will be confined to the output that has the seat set on it. The expectation is that this functionality will be used in a multiheaded environment with a single compositor for multiple output and input configurations. The default seat is called "default" and will always be present. This seat can be constrained like any other. main character energy for your multi-monitor setup. 👑
  • allow_hdcp=true — Allows HDCP support for this output. If set to true, HDCP can be tried for the content-protection, provided by the backends, on this output. By default, HDCP support is always allowed for an output. The content-protection can actually be realized, only if the hardware (source and sink) support HDCP, and the backend has the implementation of content-protection protocol. Currently, HDCP is supported by drm-backend.
  • content-type=content_type — The type of the content being primarily displayed to this output. Can be "no data" (default), "graphics", "photo", "cinema" or "game". 🎮
  • app-ids=app-id[,app_id]* — A comma separated list of the IDs of applications to place on this output. These IDs should match the application IDs as set with the xdg_shell.set_app_id request. Currently, this option is supported by kiosk-shell.
  • colorimetry-mode=default — Sets the colorimetry mode on the output. The colorimetry mode together with the EOTF mode below define the color encoding used in the video signal. The colorimetry mode is used for choosing between the default sink defined colorimetry (intended to be described by EDID), and standardised other encodings that support wide color gamut (WCG).

The display driver, the graphics card, and the video sink (monitor) need to support the chosen mode, otherwise the result is undefined or fails. no cap, if it's not supported, it's giving chaos. 😭

The mode can be one of the following strings:

  • default — default (RGB) colorimetry, video sink dependant
  • bt2020cycc — Rec. ITU-R BT.2020 constant luminance YCbCr
  • bt2020ycc — Rec. ITU-R BT.2020 non-constant luminance YCbCr
  • bt2020rgb — Rec. ITU-R BT.2020 RGB
  • p3d65 — SMPTE ST 2113 DCI-P3 RGB D65
  • p3dci — SMPTE ST 2113 DCI-P3 RGB Theater
  • ictcp — Rec. ITU-R BT.2100 ICtCp

Defaults to default. Non-default modes require color-management=true.

Note: The operating system might not honor the choice between RGB and YCbCr, that may be picked by a Linux display driver automatically. lowkey wild, but okay. 🙈

  • eotf-mode=sdr — Sets the EOTF mode on the output. This is used for choosing between standard dynamic range (SDR) mode and the various high dynamic range (HDR) modes. The display driver, the graphics card, and the video sink (monitor) need to support the chosen mode, otherwise the result is undefined. The mode can be one of the following strings:
    • sdr — traditional gamma, SDR
    • hdr-gamma — traditional gamma, HDR
    • st2084 — SMPTE ST 2084, a.k.a Perceptual Quantizer
    • hlg — Hybrid Log-Gamma (ITU-R BT.2100)

Defaults to sdr. Non-SDR modes require color-management=true.

  • mirror-of=ouput_name — Makes the remote output overlap (mirror) the native output identified by the mirror-of value. This is useful for sharing or mirroring a native DRM output. The output mirroring the DRM native one, will inherit the same video modeline as the DRM native one, including the refresh rate and scale of the native output. Note that depending on the remote backend, automatic output resize will be disabled when mirroring is in effect. Mirroring a DRM native output to another DRM native output is yet not supported, being intended only for remote outputs.

NOTE: The native outputs created by the DRM backend using the 'clone-of' are for cloning the outputs, and not sharing or mirroring. See also weston-drm(7).

  • vrr-mode=mode — Sets the variable refresh rate mode of the display. The mode can be one of the following strings:
    • none — variable refresh rate is disabled
    • game — game variable refresh rate

Defaults to "none". fr fr, keep it smooth. 🎀

  • underscan=type — okay so SOME displays are out here scaling up the signal they get, which shoves framebuffer content right off the edges of the screen 😭 This is a whole throw-back to analog CRTs and broadcast video, where auxiliary signals sometimes leaked into the visible region. Receivers just applied a random scale factor to everything so that aux signal got hidden past the borders. And some modern displays STILL do overscan, with literally no way to turn it off, which means the edges of weston's content end up outside the viewable area. Rude.

This option — if the driver supports it — tells the driver to scale the content down so it compensates for the display's overscan. Lowkey important: the amount of overscan a display uses is not queryable, so you have to manually compensate using the border values in underscan-hborder and underscan-vborder.

The type may be one of these besties:

  • off — underscan is disabled
  • on — underscan is enabled
  • auto — the display driver may enable underscan

Defaults to off

  • underscan-hborder=pixels — sets the width, in pixels, of the horizontal borders used on the left and right edges of the screen if underscan is enabled. Default is 0.
  • underscan-vborder=pixels — sets the height, in pixels, of the vertical borders used on the top and bottom edges of the screen if underscan is enabled. Default is 0.
  • color-format=format — forces a specific color-format to be generated by the display driver 🎨
   auto              auto - driver-dependant color format (usually fallback to RGB)
   rgb               RGB color format
   yuv444            YUV color format with no subsampling
   yuv422            YUV color format with 4:2:2 subsampling
   yuv420            YUV color format with 4:2:0 subsampling

Defaults to "auto". And if the color format you specified isn't found, it fallbacks to "auto" — no drama, it just moves on. Note that this depends both on the supported color formats by the display driver AND on the color formats supported by the sink/output. Weston will print out the supported color formats which could be used on a particular output. Slay, it tells you.

✨ INPUT-METHOD SECTION ✨

  • path=/usr/libexec/weston-keyboard — sets the path of the on screen keyboard input method (string). And bestie, you CAN pass arguments and environment variables to the program, like for example 'ENVFOO=bar ENVBAR=baz /path/to/program --arg anotherarg', with entries that are space-separated — but heads up, there's no support for quoting. 🙈
  • overlay-keyboard=false — sets weston-keyboard as overlay panel.

🎹 KEYBOARD SECTION 🎹

This section contains the following keys:

  • keymap_rules=evdev — sets the keymap rules file (string). Used to map layout and model to input device.
  • keymap_model=pc105 — sets the keymap model (string). See the Models section in xkeyboard-config(7).
  • keymap_layout=us,de,gb — sets the comma separated list of keyboard layout codes (string). See the Layouts section in xkeyboard-config(7).
  • keymap_variant=euro,,intl — sets the comma separated list of keyboard layout variants (string). And okay this one matters: the number of variants must be the same as the number of layouts above. See the Layouts section in xkeyboard-config(7).
  • keymap_options=grp:alt_shift_toggle,grp_led:scroll — sets the keymap options (string). See the Options section in xkeyboard-config(7).
  • repeat-rate=40 — sets the rate of repeating keys in characters per second (unsigned integer)
  • repeat-delay=400 — sets the delay in milliseconds since key down until repeating starts (unsigned integer)
  • numlock-on=false — sets the default state of the numlock on weston startup for the backends which support it.
  • vt-switching=true — whether to allow the use of Ctrl+Alt+Fn key combinations to switch away from the compositor's virtual console.

🖥️ TERMINAL SECTION 🖥️

Contains settings for the weston terminal application (weston-terminal). It lets you customize the font and shell of the command line interface 💅

  • font=DejaVu Sans Mono — sets the font of the terminal (string). For a good experience it is recommended to use monospace fonts. And if the font isn't found, the default one is used — no worries.
  • font-size=14 — sets the size of the terminal font (unsigned integer).
  • term=xterm-256color — the terminal shell (string). Sets the $TERM variable.

🌈 XWAYLAND SECTION 🌈

  • path=/usr/bin/Xwayland — sets the path to the xserver to run (string).

🚀 AUTOLAUNCH SECTION 🚀

  • path=/usr/bin/echo — path to an executable file to run after startup. This file is executed in parallel to Weston, so it does not have to immediately exit. Defaults to empty.
  • watch=false — if set to true, quit Weston after the auto-launched executable exits. Set to false by default.

🌈 COLOR-PROFILE SECTION 🌈

Okay bestie, this section is where we tell weston what your display actually is in color-nerd terms 💅. Each color-profile section records one set of basic display color characterisation parameters. Some of those parameters get bundled into groups, and here's the rule: each group must be given either fully or not at all — no half-sending a group, that's giving chaotic energy and it won't work 🙈.

For a section to even be usable, it must contain at least the signaling primaries (so either the Signaling primaries group or prim_named) and the transfer function (either tf_named or tf_power). That's the bare minimum, periodt.

Every section must be named with the name key, because that's how other sections reference it. And lowkey important: a color-profile section is just a lil collection of parameter values — it does nothing on its own. It only has an effect when something else references it. So it's giving backstage, not main character, until it gets called up ✨.

See the output section key color-profile for how to actually pull one of these in.

🎀 The keys 🎀

  • name=name — An arbitrary name for this section. Pick literally any name you want, as long as it does not contain the colon (:) character. Names with at least one colon are reserved — those are spoken for, hands off 🚫.
  • prim_named=name — A standardised set of primaries and white point for signaling. Here are the names that get recognized:
    • srgb — sRGB (IEC 61966-2-1) and ITU-R BT.709
    • pal_m — PAL-M (ITU-R BT.470-6)
    • pal — PAL (ITU-R BT.470-6), ITU-R BT.601-7 625-line
    • ntsc — NTSC (SMPTE 170M-2004), ITU-R BT.601-7 525-line
    • generic_film — generic film with color filters using Illuminant C (ITU-T H.273)
    • bt2020 — ITU-R BT.2020 and BT.2100
    • cie1931_xyz — CIE 1931 XYZ (ITU-T H.273)
    • dci_p3 — DCI P3 (SMPTE RP 431-2)
    • display_p3 — Apple Display P3, SMPTE EG 432-1
    • adobe_rgb — Adobe RGB (ISO 12640)

It's mutually exclusive with the Signaling primaries group, which is the other way to define custom primaries and white point. Pick one lane, bestie 🛣️.

  • target_named=name — A standardised set of primaries and white point for the targeted color volume. It recognizes the same set of names as prim_named 👆 (yes, all ten, same vibes).

It's mutually exclusive with the Target primaries group, which is where you'd define custom primaries and white point instead.

  • tf_named=name — A standard transfer function or characteristic. The recognized names:
    • bt1886 — Rec. ITU-R BT.1886 display transfer characteristic. Defaults to min_lum=0.01. ref_lum=100, max_lum=100.
    • gamma22 — Assumed display gamma 2.2 transfer function. An sRGB display (IEC 61966-2-1) uses this transfer function.
    • gamma28 — Assumed display gamma 2.8 transfer function.
    • st240 — SMPTE ST 240 (1999)
    • st428 — SMPTE ST 428-1 (2019)
    • st2084 — SMPTE ST 2084 Perceptual Quantizer (PQ) transfer characteristic. Defaults to min_lum=0.005, ref_lum=203.
    • linear — Linear transfer function defined over all real numbers. Normalised electrical values are equal the normalised optical values.
    • log100 — Logarithmic transfer characteristic (100:1 range).
    • log316 — Logarithmic transfer characteristic (100 * Sqrt(10) : 1 range).
    • xvycc — IEC 61966-2-4
    • hlg — Rec. ITU-R BT.2100 HLG transfer characteristic. Defaults to min_lum=0.005, ref_lum=203, max_lum=1000.

Unless it says otherwise up there ☝️, the default signaling luminance values are min_lum=0.2, ref_lum=80, max_lum=80. (Peep the Signaling luminances group for the deets.)

Mutually exclusive with tf_power — one or the other, never both 💀.

  • tf_power=E — Mutually exclusive with tf_named. Sets the transfer function as a power-law curve with the given exponent E, which is a real number in the range [1.0, 10.0]. Defaults to min_lum=0.2, ref_lum=80, max_lum=80.
  • max_fall=L — Displays desired maximum frame-average light level L cd/m². Undefined when not set.
  • max_cll=L — Display's maximum content light level L cd/m². Undefined when not set.

💜 Signaling primaries group 💜

  • prim_red=x y
  • prim_green=x y
  • prim_blue=x y
  • prim_white=x y

The signaling primaries group defines the primaries and the white point used for encoding tristimulus into RGB values — aka the primary color volume 🎨. The x and y are the CIE 1931 2-degree observer chromaticity coordinates, and the values must be in the range [-1.0, 2.0].

If you want an easier way to define standard primaries, go look at prim_named, which is mutually exclusive with the signaling primaries group. Choose your fighter 💅.

🌸 Signaling luminances group 🌸

  • min_lum=Lmin
  • ref_lum=Lref
  • max_lum=Lmax

So Lmin–Lmax is the dynamic range of the display corresponding to 0%–100% signal levels. For the tf_named=st2084 setting, the Lmax value gets overwritten with 10'000 + Lmin (not a typo, that apostrophe is a thousands separator, she's fancy ✨).

Lref is the reference luminance level to which all application contents are matched — also known as the graphics white luminance or the standard dynamic range peak luminance. All values are positive real numbers in cd/m². Lmin can also be zero. And Lmin must be less than Lref and Lmax — respect the hierarchy, queen 👑.

When not set, the default values depend on the transfer function or characteristic you chose.

🦋 Target primaries group 🦋

  • target_red=x y
  • target_green=x y
  • target_blue=x y
  • target_white=x y

The target color volume is similar to the Mastering Display Color Volume (MDCV), in that any encoded stimulus outside of it has an undefined presentation 🫠. This is especially useful with a display that uses a wide gamut signal encoding (e.g. BT.2020) but can only produce a subset of that color gamut. The x and y are the CIE 1931 2-degree observer chromaticity coordinates, values in the range [-1.0, 2.0].

When not set, it defaults to the primary color volume.

For an easier way to define standard targets, see target_named, which is mutually exclusive with the target primaries group.

⭐ Target luminances group ⭐

  • target_min_lum=Lmin
  • target_max_lum=Lmax

Luminance range of the target color volume. Lmin and Lmax are positive real numbers in cd/m². Lmin may also be zero, and it must be less than Lmax.

When not set, it defaults to the signaling luminance range.

👀 SEE ALSO 👀

weston(1), weston-bindings(7), weston-drm(7), xkeyboard-config(7)

okay bestie that's the whole page, we ate and left no crumbs 💅✨ this was Weston 16.0.0, dated 2026-01-30 — yes ma'am, fresh, and you found all of it in weston.ini(5) 🎀 go forth and configure, you've got this fr fr 🫶💖

📦 where this page comes from