6 Examples

state_map variations (ucm.conf)

# with inputevent — modifier keys hold the alternate states
state_map=state_1:default,state_2:MBTN_RIGHT,state_3:MBTN_MID
# without inputevent — states are cycled/switched via script messages only
state_map=state_1,state_2,state_3
# without both — the first state of the first button becomes the default
state_map=

Toggle between states without modifier keys (input.conf)

ctrl+1    script-message-to    ucm    set    state_1
ctrl+2    script-message-to    ucm    set    state_2
ctrl+3    script-message-to    ucm    cycle
ctrl+4    script-message-to    ucm    cycle-back

Per-profile button layouts

Fullscreen, anime, music — different button sets per situation. That has its own page: Per-profile button layouts.

uosc.conf controls

The conf ships with 9 example buttons (commented out, button1…button9): alt_control_items, alt_control_loop, alt_format, alt_resolution, alt_shuffle, alt_previous, alt_next, alt_cycle, audiodevice_button. Reference the ones you want to show:

controls=button:alt_control_items,button:alt_control_loop,button:alt_format,button:alt_resolution,gap,button:alt_shuffle,button:alt_previous,button:alt_next,button:alt_cycle,gap,button:audiodevice_button,fullscreen,gap,<video>button:alt_resolution

(state_1 / state_2 are just state names — you can name them anything; numbers are easier to keep in mind.)

Interaction from other scripts

Setting the state map (wait for ucm_ready first — see the inject example below):

mp.commandv('script-message-to', 'ucm', 'set-state-map', 'state_1:default,state_2:MBTN_RIGHT,state_3:MBTN_MID')

Reading a button (reply arrives as receive-button):

local script_name = 'my_script' -- your script's name, so the reply comes back to it
mp.commandv('script-message-to', 'ucm', 'get-button', script_name, 'alt_cycle')
mp.register_script_message('receive-button', function(name, json)
    print("name:", name, "json:", json)
end)

Changing a button's content via key (input.conf)

Compact JSON (no spaces — script-message args split on whitespace):

ctrl+7 script-message-to ucm set-button new_button {"state_1":{"icon":"play_arrow","tooltip":"Play","command":"set pause no"},"state_2":{"icon":"pause","tooltip":"Pause","command":"set pause yes"}}

Programmatic button injection (other script)

The working reference is examples/ucm_inject_buttons.lua. Key points:

1. Wait for the ucm_ready broadcast before sending set-state-map — messages sent during script load arrive before ucm registered its handlers and are dropped.
2. Push buttons with set-buttons (compact JSON), and wait for ucm-refresh-done before reading the buttons back.
3. State names pushed by the script automatically become reachable by set / cycle — set-state-map re-parses states.

mp.register_script_message('ucm_ready', function()
    mp.commandv('script-message-to', 'ucm', 'set-state-map',
        'state_1:default,state_2:MBTN_RIGHT,state_3:MBTN_MID')
    -- push buttons here (set-buttons), compact JSON
end)

Sponsorblock plugin

ucm_sponsorblock_minimal_plugin.lua — a minimal script that manages a ucm button itself: on ucm_ready it pushes the initial button (hidden), and on each update-icon message from mpv_sponsorblock_chapterized it updates the icon, the badge (segment count) and pushes the button again via set-button.