fader_master/README.md

96 lines
4.3 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)
Control Linux application volume and mute from a USB MIDI controller. One
fader can follow an application, a group of applications, or the default audio
output, while the terminal UI remains useful as a complete software mixer.
![Horizontal mixer showing application, group, and output faders](docs/images/mixer-horizontal.svg)
The horizontal layout puts bottom-up faders side by side, with dividers and
flexible spacers between sections. Switch to Vertical in Config for stacked
cards, including one-row Slim and Bordered slim faders:
![Vertical mixer showing stacked faders and separators](docs/images/mixer-vertical.svg)
## Features
- Match PulseAudio or `pipewire-pulse` streams by application metadata, with
exact and regular-expression capture rules.
- Control individual applications, non-nesting application groups, and the
default output without changing live audio during discovery.
- Learn volume and mute controls from MIDI, reflect confirmed mute state on
control-surface LEDs, use pickup to prevent jumps, and
keep independently identified controllers from colliding.
- Arrange faders, separators, and empty spacers directly in the mixer. Choose Slim,
Bordered slim, Standard, or Thick faders, and hide detail faders behind a
group when useful.
- Size separators independently and choose Plain, Line, Double line, or Box.
Fill separators share spare space; names are optional.
- Use horizontal or vertical layouts and six built-in terminal themes.
- Choose Detailed, Compact, Symbol, Color, or Hidden pickup feedback in Config.
Hiding the indicator keeps pickup protection active.
- Run as one command, or keep a standalone server alive while reconnecting TUI
clients come and go.
- Edit a validated draft from the TUI and persist it with one explicit Save.
Malformed or conflicting edits never replace the active configuration.
- Switch among valid managed profiles from a popup in the Config view; the
default switch adopts live audio without writing saved volume state.
## Quick start
Install the platform dependencies described in the
[documentation index](docs/README.md), then run the combined server and TUI
with the sample PipeWire/Pulse profile:
```sh
cargo run --locked -p fader_master -- \
--config examples/profiles/arch-pipewire.toml --audio pulse
```
The combined executable connects to an existing per-user server when possible
and starts an embedded one otherwise. Running without `--config` creates
a `default` profile with a Master-output fader. A sole detected MIDI input is
adopted as the default controller; otherwise choose a detected input in Config,
add it, and Save. Edit the Master fader with `E` to learn volume and mute controls.
The screenshots use reproducible example state rendered by the actual TUI;
they do not represent a live hardware session.
## Everyday controls
| Action | Vertical | Horizontal |
|---|---|---|
| Select | Up/Down or J/K | Left/Right or J/K |
| Change volume | Left/Right | Up/Down |
| Reorder | Shift+Up/Down or Shift+J/K | Shift+Left/Right or Shift+J/K |
| Toggle mute | M | M |
| Edit fader or separator | E | E |
| Add/remove separator | A / D | A / D |
| Hide selected fader | Shift+H | Shift+H |
| Help | h or ? | h or ? |
Use `Tab` to open Config, `T` to cycle the theme, and `Q` to open the quit
confirmation. Fader editing exposes capture rules, group membership, separate
controller/Learn/Unlearn actions for volume and mute, size, and visibility.
Config → Active profile opens the profile switcher.
Separator editing offers an optional name, size, and decoration; an empty
name with Plain + Fill creates flexible blank space. Press Enter to accept
popup edits, then use Config → Save to persist the draft.
After updating the binaries, restart the server as well as the client. The
combined launcher reuses an already-running server.
## Documentation
The [documentation index](docs/README.md) contains installation instructions,
advanced configuration and process layouts, examples, troubleshooting notes,
architecture, project status, and related projects.
## License
See [LICENSE](LICENSE).