120 lines
6.1 KiB
Markdown
120 lines
6.1 KiB
Markdown
# fader_master
|
|
|
|

|
|

|
|

|
|
|
|
Linux application volume and mute control from one or more USB MIDI surfaces.
|
|
|
|
This repository contains tested domain and configuration libraries, a PulseAudio
|
|
protocol worker compatible with `pipewire-pulse`, a local per-user server, and a
|
|
live terminal mixer. The domain layer supports matching, routing, balanced group
|
|
volume plans, and mute intent. Atomic TOML persistence, checkpointing, and live
|
|
profile application/group aggregation are implemented; persistent MIDI
|
|
lifecycle, pickup/feedback, and the configuration editor remain on the ordered
|
|
backlog:
|
|
|
|
- [Architecture and library research](architecture.md)
|
|
- [Implementation tasks and acceptance tests](task.md)
|
|
- [Project-agent instructions and test/commit workflow](AGENTS.md)
|
|
- [Build prerequisites and MSRV](docs/build.md)
|
|
- [CI coverage and badge lifecycle](docs/ci-coverage.md)
|
|
- [Hands-on functional checklist](checklist.md)
|
|
|
|
## Run the live TUI
|
|
|
|
For normal interactive use, launch the combined executable. It connects to an
|
|
existing per-user server when one is available; otherwise it starts an embedded
|
|
server for the lifetime of the TUI:
|
|
|
|
```sh
|
|
cargo run --locked -p fader_master -- \
|
|
--config examples/profiles/arch-pipewire.toml --audio pulse
|
|
```
|
|
|
|
Installed builds provide three executable names: `fader_master` for this
|
|
combined mode, `fader_master_server` for a persistent standalone server, and
|
|
`fader_master_client` for the reconnecting TUI client. Server-only options are
|
|
used by combined mode only when it actually needs to start a server.
|
|
|
|
For separate processes, start the server in one terminal:
|
|
|
|
```sh
|
|
cargo run --locked -p fader_master --bin fader_master_server -- \
|
|
--config examples/profiles/arch-pipewire.toml --audio pulse
|
|
```
|
|
|
|
Then start the client in another:
|
|
|
|
```sh
|
|
cargo run --locked -p fader_master --bin fader_master_client
|
|
```
|
|
|
|
The compatible `fader_master serve` and `fader_master tui` subcommands remain
|
|
available for scripts and existing workflows.
|
|
|
|
On the first combined or server launch without `--config`, fader_master creates
|
|
a valid empty `default` profile and active-profile selection. If an existing
|
|
active selection names a missing managed profile, that empty profile is created
|
|
with the selected ID. Explicit missing `--config` paths still fail, preventing a
|
|
mistyped path from silently creating a file.
|
|
|
|
Server startup recognizes the pre-versioned/schema-0 profile format. It updates
|
|
only the schema marker after validating the complete migrated profile, keeps
|
|
comments via `toml_edit`, writes the exact original bytes beside the profile as
|
|
`NAME.toml.v0.bak`, and atomically installs the result. Unknown newer schemas or
|
|
malformed profiles are never rewritten; the startup error explains that a safe
|
|
upgrade was unavailable. The `validate` command remains read-only.
|
|
|
|
The mixer arrow keys follow its orientation. In Vertical mode, use Up/Down to
|
|
select a configured fader or separator and Left/Right to change its volume. In
|
|
Horizontal mode, use Left/Right to select and Up/Down to change volume. J/K
|
|
remain selection aliases in either mode; Shift plus the selection arrows, or
|
|
Shift+J/K, reorders an entry. The J/K binding avoids terminals that do not
|
|
report Shift+Arrow distinctly. M toggles mute, Shift+H hides the selected fader,
|
|
and `h` or `?` opens detailed keyboard help. T cycles the profile's theme draft,
|
|
and Q opens the quit confirmation. Escape cancels the active editor or dialog and
|
|
does not quit from the main screen. Pass `--theme dracula`, `nord`,
|
|
`gruvbox-dark`, `catppuccin-mocha`, or `solarized-dark` to choose an initial
|
|
session theme. Save from Config to persist a theme selected with T. Offline
|
|
objects remain visible, and aggregate rows show `MIXED` when member state
|
|
differs. See the hands-on checklist for the exact milestone scope and
|
|
restoration steps.
|
|
|
|
The mixer is also the primary configuration surface. A adds a separator, E
|
|
edits a selected fader or separator, D removes a selected separator, and `h`
|
|
hides a fader. Fader editing provides capture Field/Exact-or-Regex/Pattern
|
|
controls, a checked multi-select popup for group membership, group mode, and
|
|
separate controller, Learn MIDI, and Unlearn MIDI actions for both volume and
|
|
mute. Learning opens a waiting popup
|
|
and captures the next supported fader movement or button press from the selected
|
|
controller. Capture patterns open in a cursor-aware popup, so individual
|
|
characters can be inserted or removed without replacing the whole value. The
|
|
editor also provides per-fader
|
|
Size (`Slim`, `Standard`, or `Thick`) and visibility. Slim
|
|
faders occupy one terminal row in Vertical mode; Standard remains the compatible
|
|
default. Horizontal mode presents side-by-side fader strips with bottom-up
|
|
meters, status, percentage, and bottom labels, with Size controlling strip
|
|
width. The separator name is entered in a centered popup for both add and rename
|
|
actions.
|
|
The Config tab is a settings/status page: change the profile theme, switch the
|
|
persisted mixer layout between Vertical and Horizontal, select the profile's
|
|
default MIDI controller, restore individual faders from the hidden-fader popup,
|
|
inspect backend and MIDI-device state, and save the server-owned draft. Save
|
|
both activates the validated configuration and persists it; there is no
|
|
separate Apply step.
|
|
Each MIDI-device row is selectable; Enter opens its status and connection
|
|
details and allows its profile-backed default-controller flag to be toggled.
|
|
Unassigned volume and mute controls inherit that default for MIDI learn.
|
|
Vertical mode keeps the stacked card appearance and full-width separator rows.
|
|
Horizontal mode keeps every fader and labeled separator divider in one
|
|
continuous row, scrolling the visible columns around the selection when needed.
|
|
The old `Shift+h` hidden-list mode and pipe-delimited object editors are no
|
|
longer used.
|
|
|
|
# References
|
|
|
|
* [pwvucontrol](https://github.com/saivert/pwvucontrol/blob/main/src/backend/pwnodeobject/mixerapi.rs)
|
|
* [ratatui](https://ratatui.rs/)
|
|
* [midir](https://github.com/Boddlnagg/midir)
|