Options

Options are the controls a user sees in the settings panel when your overlay is selected. You define them in the options list in the manifest. Their values are stored per overlay instance, so two copies of the same bundle can be set up differently.

Read the values and react to changes through DesktopOverlaysAPI.options, which requires the sdk.options permission. See the options section of the API reference.

Common shape

{ "key": "gain", "name": "Gain", "type": "input", "kind": "float",
  "min": 0, "max": 4, "default": 1, "condition": "$.options.mode != 'off'" }

Field	Required	Description
key	yes	The identifier you read in code. Must be unique within the bundle.
name	yes	The label shown in the panel. For label options, this is the text itself.
type	yes	One of input, label, button, shortcut, file.
default	no	The starting value.
condition	no	An expression that decides whether this option is shown. See Conditions.

Option types

input

A value control. The kind field decides which control is drawn and how the value is validated.

kind	Control	Value	Validation fields
number	Number field	number	min, max, step
integer	Number field, whole numbers	number	min, max, step
float	Number field or slider	number	min, max, step
string	Text field	string	minLength, maxLength
select	Dropdown	string	choices
color	Color picker	hex string, for example #ff8800	none
boolean	Checkbox	true or false	none

A select lists its options in choices:

{ "key": "mode", "name": "Mode", "type": "input", "kind": "select", "default": "wave",
  "choices": [
    { "label": "Wave", "value": "wave" },
    { "label": "Bars", "value": "bars" },
    { "label": "Pro only", "value": "pro", "condition": "$.options.pro == true" }
  ] }

Each choice has a label (shown) and a value (stored). A choice can carry its own condition, so it only appears in the dropdown when the condition is true.

label

Static text in the panel. No value, no interaction. The name is the text. Use it for section headers or hints.

{ "key": "hint", "name": "Audio data streams in automatically.", "type": "label" }

button

A button. There is no stored value. When the user clicks it, your code receives a button-click event through options.onUpdate, with key set to the button's key.

{ "key": "reset", "name": "Reset", "type": "button" }

shortcut

A global keyboard shortcut that the user binds in the panel. The value is an Electron accelerator string, for example "CommandOrControl+Shift+P". You can suggest a starting binding with default, but the user makes the real binding.

When the shortcut is pressed, your code receives a shortcut event through options.onUpdate, with key set to the option's key, so you can tell multiple shortcuts apart. An empty value means it is not bound.

{ "key": "toggle", "name": "Toggle", "type": "shortcut", "default": "CommandOrControl+Shift+P" }

Your bundle cannot change or set a shortcut binding through the API. It can only suggest a default; the user does the actual binding. Calls to options.set or options.update for a shortcut key are ignored.

file

A file the user picks in the panel. Use accept to limit the allowed extensions or MIME types.

{ "key": "logo", "name": "Logo", "type": "file", "accept": ["png", "svg", "image/*"] }

The picked file is copied into the overlay's own storage, and the value you read is a URL under the bundle's own origin. Use that URL directly in an <img>, <video>, CSS, or fetch. Your bundle never sees the host file path, so it has no access to the user's file system beyond the chosen file.

As with shortcuts, your bundle cannot change a file value through the API. Only the user can pick the file. Calls to options.set or options.update for a file key are ignored.

Conditional options

Any option can carry a condition. When it is false, the control is hidden from the panel. This lets you reveal advanced controls only when a mode is on. See Conditions for the expression language.

{ "key": "pro",     "name": "Pro mode", "type": "input", "kind": "boolean", "default": false },
{ "key": "proOnly", "name": "Pro setting", "type": "input", "kind": "string",
  "condition": "$.options.pro == true" }