3 Configuration

The per-button fields (icon, badge, active, …) configure one button. These global options configure ucm as a whole — which state is the default, which keys trigger the other states, and how labels and "truthy" values behave. They live in ucm.conf and apply to every button, so you set them once.

state_map

This is the one you'll almost certainly need, even if you never use inputevent. It does two things:

1. Names the default state — the home state every button starts in. It's what you see normally, what a button reverts to, and what fill-up inherits from. Telling ucm which state is the default is the single most important thing here; without it the buttons don't know what to show.

2. (Only with inputevent) binds modifier keys to the other states — hold a key and the button switches to that state; release and it reverts.

The simplest form just lists the states in order — the first one becomes the default:

# the loop button: state_1 (loop playlist) is the default, state_2 (loop file) the extra
state_map=state_1,state_2,state_3

To bind modifier keys, tag each state: the default gets the keyword default, the others get an inputevent key.

state_map=state_1:default,state_2:MBTN_RIGHT,state_3:MBTN_MID

Holding MBTN_RIGHT now shows state_2; releasing reverts to state_1 after a short delay.

The modifier keys only work with inputevent. ucm registers each state:KEY with inputevent automatically, so without inputevent the key bindings do nothing (the states still exist — you just can't trigger them by holding a key). That's a known limitation — ucm could bind these keys itself, the way an input.conf entry would, which would make inputevent optional. Until then, the modifier half of state_map assumes inputevent is installed.

state_cycle_map

Only matters if you use cycle / cycle-back / a ?(c) button to walk through a button's states — it's the ordered list the cycle steps through. By default it's the states from state_map, in order, so if you don't cycle you can ignore it:

# default: the state_map states, in order
state_cycle_map=
# or an explicit subset / order
state_cycle_map=state_1,fullscreen

The smaller options

• resolution_mapping — what ?(p) shows for a resolution. resolution:description pairs; until you add them, ?(p) shows the raw height (e.g. 1080p). E.g. resolution_mapping=1920x1080:FHD,2560x1440:QHD.
• video_types / audio_types / image_types — the file extensions ?(f) counts as video/audio/image. Built-in defaults; leave them unless you need another type.
• active_truthy_values — the string values an active=[[property]] field treats as "on" (default yes,true,1,inf); anything else is off.
• revert_delay — extra ms (added to a 300 ms base) a button stays in its modifier state after you release the key, before it reverts to the default.
• supress_input_warnings_key — optional; if set, the default inputevent binding uses this key instead of the generic default keyword, which silences an inputevent warning. (One s — it's spelled supress.)