248 lines
9.0 KiB
Markdown
248 lines
9.0 KiB
Markdown
# 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).
|