Displays are matched by name or description with precedence: exact, regex, fuzzy

You can identify them via logs e.g.

DP-3 Arrived:
    name:     'DP-3'
    desc:     'Unknown Monitor Maker ABC123 (DP-3 via HDMI)'

It is recommended to use the description rather than the nondeterministic name.

Avoid using 'DP-1' as that will also match 'eDP-1'

Any item prefixed with a ! will be interpreted as extended POSIX regex e.g. '!^DP-1'. Regex strings must be single quoted.

Using a regex is preferred, however fuzzy case insensitive string matches of at least 3 characters may be used.

See default cfg.yaml, usually installed at /etc/way-displays/cfg.yaml.

Follows schema/cfg-1.0.0.yaml

cfg.yaml will be monitored for changes, which will be immediately applied.

The file may be specified via the --config command line option.

The following are used, in order:

• $XDG_CONFIG_HOME/way-displays/cfg.yaml
• $HOME/.config/way-displays/cfg.yaml
• /usr/local/etc/way-displays/cfg.yaml
• /etc/way-displays/cfg.yaml

The default is to arrange in a row, aligned at the top of the displays.

ARRANGE may be a ROW (left to right) or a COLUMN (top to bottom).

ALIGN for a ROW may be TOP, MIDDLE, BOTTOM.

ALIGN for a COLUMN may be LEFT, MIDDLE, RIGHT.

Layout to suit you e.g. top to bottom, aligned in the centre:

# Arrange displays in a ROW (default, left to right) or a COLUMN (top to bottom)
ARRANGE: COLUMN

# Align ROWs at the TOP (default), MIDDLE or BOTTOM
# Align COLUMNs at the LEFT (default), MIDDLE or RIGHT
ALIGN: MIDDLE

The default ORDER is simply the order in which the displays are discovered. This is nondeterministic.

You are encouraged to explicitly define your order. e.g.

ORDER:
  - '!^DP-1'
  - 'Monitor Maker ABC123'
  - 'HDMI-1'

Regexes are encouraged, allowing for one to easily create generic rules e.g. '!^DP-', which will often be sufficient to put external monitors at the top of a column.

Some displays may be ordered last, by using a "catchall" regex e.g.

ORDER:
    - '!.*Monitor Maker ABC123.*$'
    - '!.*$'
    - 'DP-5'

Note that partial matches are not possible in this configuration, and the last displays must be exactly specified.

Enable scaling, overrides AUTO_SCALE and SCALE

SCALING: false

The default is to scale each display by DPI.

This may be disabled and scale 1 will be used, unless a SCALE has been specified.

AUTO_SCALE: false

Set minimum value for auto scaling. The default is 1.0.

AUTO_SCALE_MIN: 1.0

Set maximum value for auto scaling. Ignored if below AUTO_SCALE_MIN.

AUTO_SCALE_MAX: 2.5

Auto scale may be overridden with custom scales for each display e.g.

SCALE:
    - NAME_DESC: 'Monitor Maker ABC123'
      SCALE: 1.75

WARNING: selecting some modes may result in an unusable (blank screen or powered off) monitor. Try this WLR_DRM_NO_MODIFIERS=1 workaround if you experience problems.

If the specified mode cannot be found or activated, way-displays will fall back to the preferred mode, then the highest available resolution / refresh.

Resolution with highest refresh:

MODE:
    - NAME_DESC: HDMI-A-1
      WIDTH: 1920
      HEIGHT: 1080

Resolution and refresh:

MODE:
    - NAME_DESC: HDMI-A-1
      WIDTH: 1920
      HEIGHT: 1080
      HZ: 60

When selecting a mode, way-displays will use the highest refresh that matches. There will usually be several refresh rates will match a specified number of Hz, differing only by a few mHz. These will be tried in descending order until a working one is found.

Maximum resolution and refresh:

MODE:
    - NAME_DESC: HDMI-A-1
      MAX: TRUE

Rotate or translate the display. 90, 180, 270, FLIPPED, FLIPPED-90, FLIPPED-180, FLIPPED-270

e.g.

TRANSFORM:
    - NAME_DESC: 'Monitor Maker ABC123'
      TRANSFORM: FLIPPED-90

Adaptive sync is enabled by default. Disable it per display.

VRR_OFF:
    - DP-2
    - '!.*my monitor.*'

Laptop displays usually start with eDP e.g. eDP-1. This may be overridden if your laptop is different e.g.:

LAPTOP_DISPLAY_PREFIX: 'eDPP'

Use MODE, specifying the preferred resolution.

Disable the specified displays.

DISABLED:
  - 'Monitor Maker ABC123'
  - 'HDMI-1'

Conditional disabling of specified displays. (since 1.14.0)

DISABLED:
  - NAME_DESC: 'eDP-1'
    IF:
      - PLUGGED: ['HDMI-A-1', '!^DP-2']
  - NAME_DESC: 'Monitor maker ABC123'
    IF:
      - UNPLUGGED: ['!^DP-1']

Each entry in the DISABLED list is evaluated independently. Each entry in the IF list of criteria is applied in OR fashion. All entries in each of the criteria's PLUGGED/UNPLUGGED list is evaluated as AND.

In the example above: eDP-1 is disabled when both HDMI-A-1 and !^DP-2 criteria are satisfied by plugged in displays. Additionally, Monitor maker ABC123 will be disabled if !^DP-1 criteria is not satisfied by any connected displays.

Sets a /bin/sh command to be executed following most events.

Obeys LOG_THRESHOLD

NOTE: Depending on your compositor this could get executed multiple times when a change happens. Especially likely on a (dis-)connect.

Environment variables:

• ${CALLBACK_MSG} contains a human readable message
• ${CALLBACK_LEVEL} one of FATAL ERROR WARNING INFO

Default:

CALLBACK_CMD: notify-send "way-displays ${CALLBACK_LEVEL}" "${CALLBACK_MSG}"

A multiline literal YAML string may be used without the ; separators e.g.

CALLBACK_CMD: |
  notify-send way-displays "foo"
  bell
  notify-send way-displays "bar"

One of FATAL ERROR WARNING INFO DEBUG

Sets the threshold for log output as well as callbacks.

Default:

LOG_THRESHOLD: INFO

Manages the server. The active configuration and display state may be inspected, and the configuration modified.

The active configuration can be written to disk, however any comments and formatting will be lost.

See way-displays --help and man way-displays for details.

Usage: way-displays [OPTIONS...] [COMMAND]
  Runs the server when no COMMAND specified.
OPTIONS
  -L, --l[og-threshold] <debug|info|warning|error>
  -c, --c[onfig]        <path>
  -y, --y[aml]          YAML client output, implies -L warning
COMMANDS
  -h, --h[elp]    show this message
  -v, --v[ersion] display version information
  -g, --g[et]     show the active settings
  -w, --w[rite]   write active to cfg.yaml
  -s, --s[et]     add or change
     ARRANGE_ALIGN <row|column> <top|middle|bottom|left|right>
     ORDER <name> ...
     SCALING <on|off>
     AUTO_SCALE <on|off>
     SCALE <name> <scale>
     MODE <name> MAX
     MODE <name> <width> <height> [<Hz>]
     TRANSFORM <name> <90|180|270|flipped|flipped-90|flipped-180|flipped-270>
     DISABLED <name>
     VRR_OFF <name>
     CALLBACK_CMD <shell command>
  -t, --t[toggle] toggle parameter
     SCALING
     AUTO_SCALE
     DISABLED <name>
     VRR_OFF <name>
  -d, --d[elete]  remove
     SCALE <name>
     MODE <name>
     TRANSFORM <name>
     DISABLED <name>
     VRR_OFF <name>
     CALLBACK_CMD <shell command>

By default the output will be human readable as per logs.

The -y option may be used to print raw output as per IPC

way-displays -g

way-displays -s ARRANGE_ALIGN row bottom

way-displays -s ORDER HDMI-1 "monitor maker ABC model XYZ" eDP-1

way-displays -s SCALE "eDP-1" 3

way-displays --toggle SCALING

Add a display to the DISABLED list:

way-displays -s DISABLED "monitor maker ABC model XYZ"

Remove a display from the DISABLED list:

way-displays -d DISABLED "monitor maker ABC model XYZ"

way-displays -s MODE HDMI-A-1 3840 2160 24

way-displays -w