Home

Documentation for 3rd party scripts to integrate with uosc.

Broadcasted messages

Messages usoc sends to other scripts.

uosc-version <version>

Broadcasts the uosc version during script initialization. Useful if you want to detect that uosc is installed. Example:

-- Register message handler
mp.register_script_message('uosc-version', function(version)
  print('uosc version', version)
end)

Menu API

On how to use uosc to render your menus, read the dedicated Menu API wiki page.

Message handlers

Messages uosc is listening for.

set-button <name> <data_json>

You can use this message to add or update custom buttons whose state, look, and click action is defined by data_json.

Users can then add this button into their controls bar with button:<name> syntax.

Example:

mp.commandv('script-message-to', 'uosc', 'set-button', 'button-name', utils.format_json({
  icon = 'icon_name',
  active = true,
  badge = '0',
  tooltip = 'Button tooltip',
  command = 'command to execute on click',
}))

Button data interface (pseudo types):

{
  icon: string;
  active?: boolean;
  badge?: string;
  command?: string | string[];
  tooltip?: string;
}

set <prop> <value>

Tell uosc to set an external property to this value. Currently, this is only used to set/display control button active state and badges, for which the set-button above is probably a simpler interface to use.

In your script, set the value of foo to 1.

mp.commandv('script-message-to', 'uosc', 'set', 'foo', 1)

foo can now be used as a toggle or cycle property by specifying its owner with a @{script_name} suffix:

toggle:icon_name:foo@script_name
cycle:icon_name:foo@script_name:no/yes!

If user clicks this toggle or cycle button, uosc will send a set message back to the script owner. You can then listen to this message, do what you need with the new value, and update uosc state accordingly:

-- Send initial value so that the button has a correct active state
mp.commandv('script-message-to', 'uosc', 'set', 'foo', 'yes')
-- Listen for changes coming from `toggle` or `cycle` button
mp.register_script_message('set', function(prop, value)
    -- ... do something with `value`
    -- Update uosc external prop
    mp.commandv('script-message-to', 'uosc', 'set', 'foo', value)
end)

External properties can also be used as control button badges:

controls=command:icon_name:command_name#foo@script_name?My foo button

overwrite-binding <name> <command>

Allows a overwriting handling of uosc built in bindings. Useful for 3rd party scripts that specialize in a specific domain to replace built in menus or behaviors provided by existing bindings.

Example that reroutes uosc's basic stream quality menu to christoph-heinrich/mpv-quality-menu:

mp.commandv('script-message-to', 'uosc', 'overwrite-binding', 'stream-quality', 'script-binding quality_menu/video_formats_toggle')

To cancel the overwrite and return to default behavior, just omit the <command> parameter.

disable-elements <script_id> <element_ids>

Set what uosc elements your script wants to disable. To cancel or re-enable them, send the message again with an empty string in place of element_ids.

mp.commandv('script-message-to', 'uosc', 'disable-elements', mp.get_script_name(), 'timeline,volume')

Using 'user' as script_id will overwrite user's disable_elements config. Elements will be enabled only when neither user, nor any script requested them to be disabled.