Documentation for 3rd party scripts to integrate with uosc.

Messages usoc sends to other scripts.

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)

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

Messages uosc is listening for.

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;
}

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

Allows overwriting handling of uosc's 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.

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.