fader_master/docs/configuration.md

22 KiB
Raw Blame History

Advanced configuration and operation

The TUI is the preferred interface for normal layout and binding changes. This document covers process topology, profile storage, hand-written TOML, and recovery workflows.

Process layouts

For normal use, start the combined executable:

fader_master --config /path/to/profile.toml --audio pulse

It probes the per-user socket first. If a server is already available, only a client is started; otherwise an embedded server is kept alive for the lifetime of the TUI.

Installed builds also provide dedicated executables:

fader_master_server --config /path/to/profile.toml --audio pulse
fader_master_client

The compatible fader_master serve and fader_master tui subcommands are available for scripts. Use --socket PATH on both sides only when deliberately running outside the normal XDG runtime location. --theme THEME is a client session override; changing the theme in the TUI updates the profile draft, and Config → Save persists it.

When connecting to an existing server, its active profile and audio backend remain authoritative. Restart both processes after a binary update; a new client cannot update the code inside an already-running server.

Managed profiles and files

Without --config, fader_master uses the XDG layout:

Purpose Default path
Active profile selection ~/.config/fader_master/config.toml
Profiles ~/.config/fader_master/profiles/NAME.toml
Device documents ~/.config/fader_master/devices/
Durable state ~/.local/state/fader_master/state.toml
Local socket $XDG_RUNTIME_DIR/fader_master/control.sock

XDG_CONFIG_HOME and XDG_STATE_HOME replace their home-directory defaults when they are absolute. A runtime directory is required for the standalone local socket; no shared /tmp fallback is invented.

On first managed startup, a valid default profile and active selection are created. The profile starts with a safe Master-output fader. If exactly one MIDI input is visible, its port and available USB identity are adopted as the default controller; zero or multiple inputs are left for the user to choose. Config lists unconfigured inputs under Detected MIDI ports: open one, choose Add as controller, Save, then edit the Master fader and use Learn MIDI for volume and mute. This is enough to get a new installation working without editing TOML. Profiles created by an older version with no faders expose Add Master output fader in Config and can use the same setup path.

If the active selection names a missing managed profile, the same first-run profile is recreated with that validated ID. An explicitly supplied missing --config path remains an error so a typo cannot silently create a new file.

Switch an existing server to another managed profile with:

fader_master profile switch PROFILE_ID

The same adopt-mode switch is available in the TUI under Config → Active profile. The popup lists valid TOML profiles from the managed profile directory; malformed files are omitted.

Profile IDs are stable identifiers, not paths. Use --restore only when the saved desired state should deliberately be written after activation; the safe default adopts live audio without changing it.

Profile model

Start from one of the tracked, validated examples:

  • arch-pipewire.toml demonstrates multiple applications, a group, APC MINI identity, volume/mute bindings, and green mute-button feedback.
  • desktop.toml is a smaller profile with MIDI output feedback.

A profile contains these sections:

TOML section Purpose
Root fields Schema version, stable profile ID, startup policy, and new-stream policy
[runtime] Poll interval from 1–100 ms; the default is 10 ms
[audio] auto, pulse, or reserved pipewire adapter selection, probe preference, and maximum gain
[ui] Mixer orientation, pickup-status presentation, default controller, and theme
[[applications]] A label and one or more metadata selectors
[[groups]] Application IDs combined under one logical target
[[surfaces]] Stable controller identity and MIDI input/output ports
[[faders]] Logical controls targeting an application, group, or output
[[mixer_layout]] Durable order, separators, visibility, and fader density
[[bindings]] Surface messages assigned to volume or mute actions

The array sections default to empty and may be omitted. The TUI creates a missing section when the first corresponding object or MIDI binding is added; an omitted [[bindings]] section is therefore a valid profile, not corruption. If a section is present with the wrong shape or invalid contents, startup fails before activating the profile unless a supported schema migration can upgrade it.

Application capture

MIDI feedback defaults to enabled. Set root-level feedback_enabled = false to disable all feedback, or put the same setting in a [[faders]] table to disable only that fader. Config and Edit fader expose these switches. Save the configuration to apply them. Disabled feedback sends nothing, even light-off messages; lights may retain their previous state until re-enabled and refreshed.

Selectors are ORed by default. Each selector chooses exactly one supported metadata field and exactly one matching mode:

[[applications]]
id = "browser"
label = "Browser"
selectors = [
  { field = "application.process.binary", regex = "^(firefox|chromium)$" },
  { field = "application.name", exact = "Web Browser" },
]

Supported fields are application.name, application.id, application.process.binary, media.name, application.process.executable, application.process.working_directory, steam.app_id, and steam.game_id. Exact matches are whole-string and case-sensitive. Regexes use Rust's bounded regex syntax.

The last four fields are best-effort Linux process observations, currently provided by the Pulse adapter (including PipeWire's Pulse compatibility server). Enrichment requires a reported PID and a machine ID matching /etc/machine-id. Executable and working-directory values come from /proc; Steam IDs come only from numeric, nonzero SteamAppId / SteamGameId environment entries. These are launch-context evidence, not authenticated proof that Steam launched the process. A path containing steamapps never creates a Steam ID.

Unavailable fields do not match. Processes that exit or change start time during inspection, restricted /proc, remote servers, container/PID namespace differences, and large environments can prevent enrichment. Environment reads are limited to 64 KiB; only the two allowlisted IDs are retained, never complete environment contents or command lines. Proton may report a Wine executable while its working directory identifies the game. The Config tab lists normalized fields for each observed stream, including unavailable values. Navigate down through Settings to inspect them; raw environment contents and command lines are never included.

Applications may set selector_mode = "all" to require every selector to match (AND). The default "any" preserves OR matching for existing profiles. The fader editor's Match captures row toggles Any (OR) / All (AND) for the application; save the configuration to activate the change. Individual Capture rows continue to edit their respective selectors without replacing the rest of the list. Missing fields fail their selector; empty selector lists and unknown modes are rejected. For example, requiring a particular application ID and media title:

[[applications]]
id = "music-video"
label = "Music video"
selector_mode = "all"
selectors = [
  { field = "application.id", exact = "example.player" },
  { field = "media.name", regex = '(?i) - YouTube$' },
]

For the original YouTube-only capture use case, the single media.name selector below remains sufficient; no additional application condition is needed.

The capture editor's Save and exit row validates and saves the current field, match mode and pattern to the draft without reopening the pattern popup. Invalid patterns leave the editor open with an error. Esc cancels local capture changes; use the configuration Save action to persist and activate accepted draft changes.

To capture YouTube playback by its reported media title, use:

selectors = [
  { field = "media.name", regex = '(?i) - YouTube$' },
]

This already works when the browser exposes a title ending in - YouTube (as observed with Waterfox). The media-title selector alone is sufficient; no browser-name condition or combined window-title matching is required. Applications must expose this metadata for it to match.

AND selectors, richer process metadata and direct MPRIS controls are implemented on the development branch after RC2; rebuild and restart both server and client. They are not required for the YouTube selector above.

Media controls (MPRIS)

The Media tab (3, or Tab) appears when the server has MPRIS support and can connect to the user's session bus. No running players is a valid empty state. A later disconnect keeps the tab and configured entries visible. Config reports why support is unavailable. No keyboard emulation or playerctl is used; paused players are discoverable without an audio stream.

In Media, A adds an entry, E edits its name/selector/feedback/controls, and D asks before deleting the entry. Select a control and press Enter to send it. Unsupported, offline or ambiguous targets cannot be invoked. Draft edits must be saved with S before commands use them. Entries remain configured while offline.

In the entry editor, P lists discovered players. Selecting one prefers its stable DesktopEntry, falling back to its bus name. You can manually choose bus_name, desktop_entry or identity, and exact or regex matching. Regexes use substring matching unless anchored; (?i) enables case-insensitivity. Multiple matches block commands—narrow the selector to an exact instance when necessary. Instance-specific bus-name suffixes may change across restarts. Failed identity reads also block identity-based selection until discovery recovers.

A inside the editor adds a control, and D removes the selected control from the local edit. Enter a control row to edit its action; use left/right to choose the action. Seek offsets and positions are milliseconds, bounded to one day. For playlists, left/right cycles observed playlist IDs and displays their names; Enter permits manual object-path input. Absolute position uses the observed track ID and requires a known track length. Shuffle and repeat require the player to report those properties; playlists require the optional Playlists interface. Playlist-content editing is not supported. Choose Save and return to entry, then Save and exit (draft), and S to persist/activate. Entry validation runs again at Save and exit; Esc discards the entry edit.

Select a control in the list and press L to choose a MIDI device and learn its input. U in that prompt unbinds the selected control; Esc cancels learning. Save to activate the learned binding. Notes trigger on presses, CCs on zero to nonzero transitions; releases and repeated held values do not repeat commands. One physical input cannot also be bound to another media or mixer action.

See the validated complete media profile. An entry uses this shape (append to a profile containing the buttons surface):

[[media]]
id = "qbz"
label = "QBZ"
feedback_enabled = true
selector = { field = "bus_name", pattern = "org.mpris.MediaPlayer2.com.blitzfc.qbz", regex = false }
controls = [
  { id = "play", action = { kind = "play" }, binding = { surface = "buttons", message = { kind = "note", channel = 1, number = 40 } } },
  { id = "pause", action = { kind = "pause" }, binding = { surface = "buttons", message = { kind = "note", channel = 1, number = 41 } } },
]

Actions are play, pause, stop, play_pause, next, previous, seek (offset_ms), set_position (position_ms), shuffle_toggle, shuffle (enabled), repeat_cycle, repeat (mode = "None", "Track" or "Playlist") and playlist (id, a player-reported D-Bus object path). All actions may have a MIDI binding. Unbound actions remain usable from the TUI.

Feedback defaults to the same learned note/channel, with 127 on and 0 off, when the surface has an output port. CC inputs have no implicit feedback. Play, Pause and Stop lights follow the mutually exclusive observed playback state, not the last button pressed. PlayPause follows Playing; shuffle, repeat and playlist lights follow the properties the player reports. Seek/next/previous have no latched indicator. Polling picks up external changes; an accepted command is not proof that a player changed state. Unavailable/ambiguous state clears enabled indicators. Successful output is deduplicated and reconnects resynchronize it.

For device-specific colors or CC output, learn first, then edit the control's Custom feedback fields. The equivalent binding field is:

feedback = { message = { kind = "note", channel = 1, number = 40 }, on = 3, off = 0 }

Color values depend on the controller. Root feedback_enabled = false overrides both per-fader and per-media-entry switches, including explicit mappings. Disabled feedback sends nothing, not even a clearing message; old LEDs may remain lit. Re-enable and Save to resynchronize. Removing a MIDI device unbinds media controls without deleting entries.

Limits: 128 entries, 64 controls per entry, 256-byte selectors, 256 KiB of media configuration; discovery handles up to 32 players and lists the first 256 playlists per player. Oversized/incomplete player discovery fails closed. Calls time out and errors are reported; missing players are rediscovered automatically. Timed-out commands are not replayed. Restart both processes after upgrading the IPC build.

Groups and faders

Groups contain application IDs, never other groups. The TUI presents eligible application faders in a checked popup but stores deduplicated application IDs:

[[groups]]
id = "media"
label = "Media"
members = ["music", "browser"]
volume_mode = "absolute"

[[faders]]
id = "media-fader"
target = { kind = "group", id = "media" }
pickup = true
pickup_tolerance = 0.02

Application and output targets use the same fader shape. absolute is the currently selectable group mode; relative behavior remains reserved for later runtime work.

Mixer presentation

Global mixer presentation is stored in [ui]:

[ui]
mixer_orientation = "horizontal"
status_display = "compact"
theme = "nord"

status_display accepts detailed, compact, symbol, color, or hidden. Detailed shows the full pickup state, compact uses short words such as LIVE and WAIT, symbol uses a distinct Unicode glyph per state, color uses one dot whose semantic color carries the state, and hidden removes pickup feedback. This only changes presentation; pickup protection remains active. Existing profiles default to detailed. The Config page cycles and saves this value.

The TUI normally manages layout entries. Their TOML representation is useful for review and bulk editing:

[[mixer_layout]]
kind = "separator"
id = "applications"
label = "Applications"
size = "slim"
decoration = "double"

[[mixer_layout]]
kind = "fader"
fader = "music-fader"
density = "slim"
hidden = false

Fader density is slim, bordered_slim, standard, or thick. Slim uses one terminal row; Bordered slim adds a border around one content row. Hidden faders retain their place and routing and can be restored from the Config tab.

Press A in the mixer to choose a new application fader, empty absolute group, or separator. A new fader or group opens its guided editor immediately; its placeholder capture or empty membership keeps it offline until configured. Press E to edit the selected fader or separator, and D to delete it after confirmation. Deleting a fader also removes its bindings and an application or group target that is not shared or referenced elsewhere. The fader editor's Name row renames an application or group label without changing stable IDs, capture, membership, bindings, or layout; default-output labels come from the audio backend. Use Up/Down or Tab to choose popup fields, Left/Right to change options, Enter to accept, and Escape to cancel. Config → Save persists and activates the draft.

Separator size is slim, standard, thick, or fill; decoration is plain (label only), line, double, or box. Existing separators default to Standard with Line decoration. Size controls height in Vertical mode and width in Horizontal mode. Slim uses one row in Vertical mode (three with Box); Standard uses three and Thick uses five. Horizontal Slim uses three columns, Standard fits the label within 8–18 columns, and Thick uses 22. Fill shares unused viewport space with other Fill separators after faders have been fitted, so it does not force faders off-screen or cause wrapping.

Separator names are optional. Keep a stable nonempty id, but use label = "" for an unlabelled rule, box, or spacer:

[[mixer_layout]]
kind = "separator"
id = "before-master"
label = ""
size = "fill"
decoration = "plain"

Size and decoration are independent. An unnamed Line or Double separator draws an uninterrupted rule; Plain draws only empty space. Reordering keeps the entry's ID, appearance, and comments, including after Save and restart.

MIDI surfaces and bindings

Use fader_master devices to inspect available ports and durable USB identity metadata. Prefer a serial number, then a physical USB path, for identical controllers. Ambiguous serial-less controllers remain unassigned unless a manual backend ID is explicitly selected.

Messages use 1-based MIDI channels and 0–127 data numbers:

[[bindings]]
surface = "apc-mini"
fader = "music-fader"
action = "volume"
message = { kind = "cc", channel = 1, number = 48 }

[[bindings]]
surface = "apc-mini"
fader = "music-fader"
action = "toggle_mute"
edge = "press"
message = { kind = "note", channel = 1, number = 64 }
feedback = { kind = "note", channel = 1, number = 64, on = 127, off = 0 }

The TUI can choose a controller, learn the next supported movement or button press, and remove an assignment independently for volume and mute. Unassigned actions inherit [ui].default_controller for learning. Learn opens a modal waiting for a movement or button press; Escape cancels it. Changing controller, learning, and unlearning are separate actions. In Config, open a MIDI device to see its connection details and set its default-controller flag. Press D on the device row or in its details popup to remove it after confirmation. Removal also clears that device's bindings and default-controller selection; Save activates the draft. Hidden faders remain bound and continue contributing to groups; restore them from Config → Show hidden faders.

feedback is optional and requires the binding's surface to define output_port. After that output attaches, the server sends on when the fader's target is uniformly and observably muted and off when it is unmuted or a group has mixed mute state. Offline targets emit no guess. Only confirmed audio observations drive feedback, so a pending or failed mute write never lights an LED as if it succeeded. Reconnect sends the current state again; unchanged states are deduplicated. Both note and CC feedback use 1-based channels and values from 0–127.

In the fader editor, open Learn volume MIDI or Learn mute MIDI to change that assignment. Press U in the learn prompt to unbind it, or Esc to cancel without changing it. Unbinding leaves the other action intact and keeps the controller selected for relearning. Save the draft to persist and activate it.

LED values are device-specific: a note velocity can mean a color or animation, so 127 is not a universal “on” value. The APC MINI example uses its configured green value. Relearning a mute binding moves its feedback assignment to the new control. A new mute binding inherits on/off values only when existing feedback entries on the same surface and message kind establish one unambiguous convention; its feedback address follows the newly learned control. Conflicting or absent conventions leave the explicit mapping unset.

By default, every note-based mute binding sends the same note back on the same channel: Note On velocity 127 for confirmed mute, and velocity 0 for unmuted or mixed state. This requires output_port, but no device identity or predefined note map. Missing mappings use these defaults after Save or server restart. This reports confirmed state; it does not echo each press/release immediately.

Configure alternate protocols per binding with feedback. For example, use on=1/off=0 for a device-specific LED value, or override the message address and kind for a controller whose feedback uses CC:

feedback = { kind = "cc", channel = 3, number = 65, on = 3, off = 0 }

Explicit mappings always take precedence. CC input bindings require an explicit feedback mapping; volume bindings do not automatically drive motors.

Validation, migration, and Save

Validate a file without opening MIDI/audio devices or changing live audio:

fader_master validate --config /path/to/profile.toml

Profiles are strict: unknown fields, unsafe IDs, invalid MIDI ranges, duplicate physical bindings, and dangling references are rejected before side effects. The TUI edits a server-owned validated draft. Config → Save atomically persists and activates that draft; there is no separate Apply operation.

Server startup safely recognizes the pre-versioned/schema-0 format. After full validation, it adds the schema marker, preserves comments, writes the original bytes to NAME.toml.v0.bak, and atomically installs the upgraded document. Unknown newer schemas and malformed profiles are never rewritten.

Diagnostics and recovery

fader_master status
fader_master devices

The reconnecting client keeps the last confirmed mixer state visible if the server disappears. Restarting the server refreshes the snapshot without replaying stale input. Hardware-dependent checks and expected recovery behavior are documented in the hands-on checklist.