fader_master/docs/configuration.md

218 lines
7.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 empty `default` profile and active selection
are created. If the active selection names a missing managed profile, an empty
profile with that validated ID is recreated. 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
```
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]` | `vertical`/`horizontal` orientation, 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
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`, `standard`, or `thick`. 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).