fader_master/README.md

104 lines
5.1 KiB
Markdown

# fader_master
![Version](https://assets.dandaedre.com/coverage/MadGobblins/fader_master/main/version.svg)
![Tests](https://assets.dandaedre.com/coverage/MadGobblins/fader_master/main/test.svg)
![Coverage](https://assets.dandaedre.com/coverage/MadGobblins/fader_master/main/coverage.svg)
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.
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, and Shift plus the selection arrows
reorders an entry. M toggles mute, 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, group membership and 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)