# 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. 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: ```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" 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. 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: ```toml [[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: ```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. 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. 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. 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. Set feedback values and output-port details in the profile when your surface requires a different protocol. ## 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).