Slider modes

Every Mixlar device has physical faders. Each fader can be assigned a slider mode — a source of truth for what that fader controls. Six slider modes ship with the app itself, and a plugin can add its own by implementing a handful of hooks on MixlarPlugin.

This page covers those hooks, the SliderMode mixin that removes the boilerplate for the common case, and a worked HTTP example.

The built-in slider modes

Before writing your own, know what’s already there — users pick between these and any plugin-provided modes in the same fader-config panel:

id	mode	what it does
apps	Per-app audio	Controls the volume of one or more selected audio sessions
system	System targets	Master Volume, Mic Volume, or the active window’s volume
devices	Audio devices	Controls an output or input device’s volume
midi	MIDI CC output	Sends a MIDI Control Change message (port, channel, CC number)
homeassistant	Home Assistant	Drives an entity’s brightness or another numeric control
discord	Discord voice volume	Sets the app volume for the Discord client
__plugins__	Plugin-provided	Every mode a loaded plugin registers via get_slider_mode

A plugin only ever adds to that last bucket — it can’t override or replace the six built-in modes.

Note

A fader can only run one mode at a time. If your plugin’s mode is selected for a given fader, your hooks are the only thing driving it until the user switches modes.

The slider hooks

These are the five methods MixlarPlugin exposes for sliders:

method	signature	purpose
get_slider_mode	(self) -> (mode_id, name) | None	opt a fader into this plugin’s mode; return None to not offer one
handle_slider_value	(self, idx: int, value: int, pct: float) -> None	fader moved — value is 0-100, pct is 0.0-1.0
get_slider_color	(self, idx) -> str | None	fixed hex color for the fader, or None for the app’s default
build_slider_config_ui	(self, idx, parent_layout, settings) -> None	build the fader’s config panel (imperative Qt path)
save_slider_config	(self, idx) -> dict	settings to persist for that fader

idx is the fader’s index on the device, so a plugin can track independent state — and independent settings, like a per-fader webhook URL — for each fader that’s running its mode.

Only get_slider_mode and handle_slider_value are required to get a working mode on screen. The other three are for building a custom per-fader settings panel; skip them if your mode has nothing to configure.

Registering a mode by hand

The plain override looks like this:

from mixlar import MixlarPlugin

class MyPlugin(MixlarPlugin):
    plugin_id = "my_plugin"

    def get_slider_mode(self):
        return ("my_plugin_slider", "My Plugin")

    def handle_slider_value(self, idx, value, pct):
        ...  # do something with the new value

    def get_slider_color(self, idx):
        return "#0a84ff"

get_slider_mode and get_slider_color are almost always just returning class-level constants — which is exactly what the SliderMode mixin automates.

SliderMode: declare a mode as class attributes

from mixlar import MixlarPlugin
from mixlar.sliders import SliderMode

class MyPlugin(SliderMode, MixlarPlugin):
    plugin_id = "my_plugin"
    slider_mode_id = "my_plugin_slider"
    slider_mode_name = "My Plugin"
    slider_color = "#0a84ff"

    def handle_slider_value(self, idx, value, pct):
        ...  # required — the mixin only covers the two getters

1. Mix SliderMode in ahead of MixlarPlugin in the base class list, so its methods win the MRO: class MyPlugin(SliderMode, MixlarPlugin).

2. Set slider_mode_id to a unique id — this is what opts the plugin into a slider mode at all. Leaving it blank (the default) makes get_slider_mode() return None, matching the base class’s “no slider mode” behavior.

3. Set slider_mode_name, the human-readable label shown in the slider-mode picker. Defaults to "Unnamed Mode".

4. Optionally set slider_color to a hex string applied to every fader running this mode. Leave it None (the default) to fall back to the app’s default fader color.

5. Override handle_slider_value(idx, value, pct). This is the one hook SliderMode does not generate — it has real side effects, so there’s nothing sensible to auto-generate.

attribute	default	derives
slider_mode_id	""	get_slider_mode() returns None while this is blank
slider_mode_name	"Unnamed Mode"	the picker label in get_slider_mode()’s tuple
slider_color	None	get_slider_color(idx)’s return value, same for every fader

build_slider_config_ui and save_slider_config aren’t touched by the mixin — implement them yourself on the subclass if your mode needs a config panel.

Worked example: an HTTP slider

Mixlar’s bundled HTTP Trigger plugin pairs a slider mode with its macro actions in the same class. The slider mode POSTs the fader’s current value to a per-fader URL, using _pget/_pset to persist that URL under a settings key namespaced by fader index:

class HttpTrigger(MixlarPlugin):
    plugin_id = "http_trigger"
    plugin_name = "HTTP Trigger"
    plugin_version = "1.0.0"
    plugin_author = "Mixlar Community"
    plugin_description = "Send HTTP requests from macros and sliders."
    plugin_icon = "fa5s.globe"
    plugin_icon_color = "#30d158"

    # ── Slider mode ──
    def get_slider_mode(self):
        return ("http_slider", "HTTP Slider")

    def handle_slider_value(self, idx, value, pct):
        import requests
        url = self._pget(f"slider_url_{idx}", "")
        if url:
            requests.post(url, json={"value": value}, timeout=2)

    def get_slider_color(self, idx):
        return "#0a84ff"

A few things worth noting in that example:

• handle_slider_value reads slider_url_{idx} through _pget, so each fader running “HTTP Slider” can point at a different endpoint — the URL itself is written elsewhere (typically from build_slider_config_ui, not shown here) via the matching _pset.
• The POST body is {"value": value} — the 0-100 integer, not the 0.0-1.0 pct. Use whichever of the two your receiving endpoint expects.
• get_slider_color returns a fixed color regardless of idx, which is the common case — every fader running this mode gets the same accent color in the UI.
• Because this plugin also defines macro actions, get_slider_mode sits alongside get_macro_actions on the same class — a plugin’s macro and slider surfaces are independent and can be mixed freely.

Tip

For a mode with no per-fader configuration and a fixed color, skip the manual overrides entirely and reach for SliderMode — it turns the HTTP Trigger example’s get_slider_mode/get_slider_color pair into three class attributes.

Related

• Plugin API reference for the full hook list, including macros and settings.
• Macros for the MacroActions + @action pattern the HTTP Trigger example also uses.
• Settings for _pget/_pset and the declarative settings-schema alternative to a Qt config panel.