# 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: ```sh 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: ```sh 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. ## 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: ```sh 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`](../examples/profiles/arch-pipewire.toml) demonstrates multiple applications, a group, APC MINI identity, volume/mute bindings, and green mute-button feedback. - [`desktop.toml`](../examples/profiles/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 | ### Application capture Selectors are ORed. Each selector chooses exactly one supported metadata field and exactly one matching mode: ```toml [[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`, and `media.name`. Exact matches are whole-string and case-sensitive. Regexes use Rust's bounded `regex` syntax. ### 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: ```toml [[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]`: ```toml [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: ```toml [[mixer_layout]] kind = "separator" id = "applications" label = "Applications" [[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. ### 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: ```toml [[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. `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. ## Validation, migration, and Save Validate a file without opening MIDI/audio devices or changing live audio: ```sh 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 ```sh 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](../checklist.md).