fader_master/docs/configuration.md

7.5 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.

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:

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 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] 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:

[[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:

[[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:

[[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:

[[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:

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.