144 lines
6.8 KiB
Markdown
144 lines
6.8 KiB
Markdown
# fader_master
|
|
|
|

|
|

|
|

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

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

|
|
|
|
## Features
|
|
|
|
- Match PulseAudio or `pipewire-pulse` streams by application metadata, with
|
|
exact and regular-expression capture rules, Any/All composition, and available
|
|
executable/working-directory and Steam IDs.
|
|
- Target MPRIS players directly from the Media tab or MIDI: transport, seeking,
|
|
shuffle, repeat and playlists, with confirmed-state feedback and global/local
|
|
feedback switches. See [media configuration](docs/configuration.md#media-controls-mpris).
|
|
- 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.
|
|
- Reset the active profile from Config after an explicit confirmation. The TUI
|
|
preserves the previous file as `<profile>.toml.reset.bak` before installing
|
|
and activating a safe Master-output profile.
|
|
|
|
## Quick start
|
|
|
|
### Install a prebuilt release (recommended)
|
|
|
|
With [cargo-binstall](https://github.com/cargo-bins/cargo-binstall#installation)
|
|
installed, download the current release candidate without compiling:
|
|
|
|
```sh
|
|
cargo binstall --git https://proxy.dandaedre.com/gitea/MadGobblins/fader_master \
|
|
--version '=0.1.0-rc.2' --strategies crate-meta-data fader_master
|
|
fader_master
|
|
```
|
|
|
|
This installs the combined launcher plus `fader_master_server` and
|
|
`fader_master_client`. Ensure Cargo's binary directory (usually `~/.cargo/bin`)
|
|
is on your `PATH`. No repository checkout or sample configuration is needed.
|
|
|
|
Prebuilt binaries currently target **x86-64 GNU/Linux** and require ALSA,
|
|
libpulse and libudev runtime libraries, plus PulseAudio or `pipewire-pulse`.
|
|
They are built with an Ubuntu 24.04-based image; older distributions are not
|
|
yet qualified. This is an RC, not a stable release.
|
|
|
|
Without cargo-binstall, download the archive containing all three executables
|
|
from the [release page](https://proxy.dandaedre.com/gitea/MadGobblins/fader_master/releases/tag/v0.1.0-rc.2),
|
|
verify it against the accompanying `SHA256SUMS`, and extract the executables
|
|
into a directory on your `PATH`.
|
|
|
|
### First launch
|
|
|
|
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.
|
|
Configured controllers can be removed with `D` in Config; confirmation also
|
|
removes their bindings, and Save activates the change.
|
|
|
|
### Build from source (alternative)
|
|
|
|
For development or systems without compatible prebuilt binaries, follow the
|
|
[build prerequisites](docs/build.md). From a source checkout, run:
|
|
|
|
```sh
|
|
cargo run --locked -p fader_master
|
|
```
|
|
|
|
See [advanced configuration](docs/configuration.md) for explicit profiles and
|
|
separate server/client operation.
|
|
|
|
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 |
|
|
| Add fader, group, or separator | A | A |
|
|
| Edit selected entry | E | E |
|
|
| Delete selected entry | D | D |
|
|
| Hide selected fader | Shift+H | Shift+H |
|
|
| Help | h or ? | h or ? |
|
|
|
|
Use `Tab` to open Config, select Mixer layout and use Left/Right to switch its
|
|
orientation, `T` to cycle the theme, and `Q` to open the quit confirmation.
|
|
Fader editing exposes the application/group display name, capture rules, group membership, separate
|
|
controller/Learn/Unlearn actions for volume and mute, size, and visibility.
|
|
Add opens a chooser for a new application fader, empty group, or separator.
|
|
New faders and groups open directly in the editor and remain visible as offline
|
|
`DRAFT` rows until Save activates them. Delete asks for confirmation and removes
|
|
the selected fader and its unshared target, or the selected separator.
|
|
Config → Active profile opens the profile switcher.
|
|
Config → Reset active profile provides an emergency return to safe defaults;
|
|
confirming it immediately saves and activates the reset and keeps a `.reset.bak`
|
|
copy beside the profile.
|
|
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).
|