From 9464944634f70f7b38fc2b45b5d0f474168afcd1 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Thu, 15 Oct 2026 23:19:22 +0200 Subject: [PATCH] docs: showcase the TUI and centralize guides Validation: regenerated deterministic SVG screenshots twice with identical output; xmllint --noout docs/images/*.svg; cargo fmt --all -- --check; cargo check --workspace --all-targets --all-features; cargo test --workspace --all-targets --all-features; cargo test --workspace --doc --all-features; cargo clippy --workspace --all-targets --all-features -- -D warnings; cargo build --workspace --release --all-features; default, no-default-features, midir, and pulse checks. --- README.md | 147 ++++-------- docs/README.md | 31 +++ docs/configuration.md | 206 ++++++++++++++++ docs/images/mixer-horizontal.svg | 397 +++++++++++++++++++++++++++++++ docs/images/mixer-vertical.svg | 171 +++++++++++++ docs/related-projects.md | 19 ++ tui/examples/doc_screenshots.rs | 321 +++++++++++++++++++++++++ 7 files changed, 1196 insertions(+), 96 deletions(-) create mode 100644 docs/README.md create mode 100644 docs/configuration.md create mode 100644 docs/images/mixer-horizontal.svg create mode 100644 docs/images/mixer-vertical.svg create mode 100644 docs/related-projects.md create mode 100644 tui/examples/doc_screenshots.rs diff --git a/README.md b/README.md index 779f087..fc9f10c 100644 --- a/README.md +++ b/README.md @@ -4,116 +4,71 @@ ![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. +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. -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: +![Horizontal mixer showing application, group, and output faders](docs/images/mixer-horizontal.svg) -- [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) +The horizontal layout puts conventional bottom-up faders side by side. The +same profile can switch to a compact stacked layout for narrow terminals: -## Run the live TUI +![Vertical mixer showing stacked faders and separators](docs/images/mixer-vertical.svg) -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: +## 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, use pickup to prevent jumps, and + keep independently identified controllers from colliding. +- Arrange faders and named separators directly in the mixer. Choose Slim, + Standard, or Thick faders, and hide detail faders behind a group when useful. +- Use horizontal or vertical layouts and six built-in terminal themes. +- 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. + +## 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 ``` -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. +The combined executable connects to an existing per-user server when possible +and starts an embedded one otherwise. Running without `--config` creates a +safe empty `default` profile on first use, which can then be edited in the TUI. -For separate processes, start the server in one terminal: +## Everyday controls -```sh -cargo run --locked -p fader_master --bin fader_master_server -- \ - --config examples/profiles/arch-pipewire.toml --audio pulse -``` +| 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 ? | -Then start the client in another: +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. -```sh -cargo run --locked -p fader_master --bin fader_master_client -``` +## Documentation -The compatible `fader_master serve` and `fader_master tui` subcommands remain -available for scripts and existing workflows. +The [documentation index](docs/README.md) contains installation instructions, +advanced configuration and process layouts, examples, troubleshooting notes, +architecture, project status, and related projects. -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. +## License -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) +See [LICENSE](LICENSE). diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..7762a25 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,31 @@ +# Documentation + +## Use and configuration + +- [Build prerequisites](build.md) — Linux packages, Rust toolchain, feature + combinations, and the current FreeBSD CI mode. +- [Advanced configuration](configuration.md) — process layouts, managed + profiles, TOML concepts, migration, validation, and operational commands. +- [Example PipeWire/APC MINI profile](../examples/profiles/arch-pipewire.toml) +- [Example desktop profile](../examples/profiles/desktop.toml) +- [Hands-on functional checklist](../checklist.md) + +## Design and development + +- [Architecture and library research](../architecture.md) +- [Implementation tasks and acceptance tests](../task.md) +- [Project-agent and commit workflow](../AGENTS.md) +- [MIDI identity design](midi-identity.md) +- [Pulse-compatible daemon fixture](pulse-daemon-fixture.md) +- [CI coverage and badge lifecycle](ci-coverage.md) + +## Ecosystem + +- [Related projects and libraries](related-projects.md) + +The README screenshots are deterministic renders of the real TUI. Regenerate +them after presentation changes with: + +```sh +cargo run --locked -p tui --example doc_screenshots +``` diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..804fef6 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,206 @@ +# 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: + +```sh +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: + +```sh +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: + +```sh +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`](../examples/profiles/arch-pipewire.toml) demonstrates + multiple applications, a group, APC MINI identity, and volume/mute bindings. +- [`desktop.toml`](../examples/profiles/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: + +```toml +[[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: + +```toml +[[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: + +```toml +[[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: + +```toml +[[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 } +``` + +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. + +## Validation, migration, and Save + +Validate a file without opening MIDI/audio devices or changing live audio: + +```sh +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 + +```sh +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](../checklist.md). diff --git a/docs/images/mixer-horizontal.svg b/docs/images/mixer-horizontal.svg new file mode 100644 index 0000000..89ed004 --- /dev/null +++ b/docs/images/mixer-horizontal.svg @@ -0,0 +1,397 @@ + + + + +╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ + + + +│ + FADER + MASTER + [1 Mixer] [2 Config] · pulse · PipeWire · ready · rev 42 · Catppuccin Mocha +│ + +╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ + +┏ + Live mixer objects +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ + +┃ +│ +┌─────┐ +┌─────┐ +│ +┌─────┐ +│ +┌─────┐ +┃ + + + + + + + + + +┃ +│ +│░░░░░│ +│░░░░░│ +│ +│░░░░░│ +│ +│░░░░░│ +┃ + + + + + + + + + +┃ +│ +│░░░░░│ +│░░░░░│ +│ +│░░░░░│ +│ +│ +█████ +│ +┃ + + + + + + + + + +┃ +│ +│ +█████ +│ +│░░░░░│ +│ +│░░░░░│ +│ +│ +█████ +│ +┃ + + + + + + + + + +┃ +│ +│ +█████ +│ +│░░░░░│ +│ +│░░░░░│ +│ +│ +█████ +│ +┃ + + + + + + + + + +┃ +│ +│ +█████ +│ +│░░░░░│ +│ +│ +█████ +│ +│ +│ +█████ +│ +┃ + + + + + + + + + +┃ +│ +│ +█████ +│ +│░░░░░│ +│ +│ +█████ +│ +│ +│ +█████ +│ +┃ + + + + + + + + + +┃ +│ +│ +█████ +│ +│ +█████ +│ +│ +│ +█████ +│ +│ +│ +█████ +│ +┃ + + + + + + + + + +┃ +│ +│ +█████ +│ +│ +█████ +│ +│ +│ +█████ +│ +│ +│ +█████ +│ +┃ + + + + + + + + + +┃ +│ +│ +█████ +│ +│ +█████ +│ +│ +│ +█████ +│ +│ +│ +█████ +│ +┃ + + + + + + + + + +┃ +│ +│ +█████ +│ +│ +█████ +│ +│ +│ +█████ +│ +│ +│ +█████ +│ +┃ + + + + + + + + + +┃ +│ +│ +█████ +│ +│ +█████ +│ +│ +│ +█████ +│ +│ +│ +█████ +│ +┃ + + + + + + + + + +┃ +│ +│ +█████ +│ +│ +█████ +│ +│ +│ +█████ +│ +│ +│ +█████ +│ +┃ + +┃ +│ +└─────┘ +└─────┘ +│ +└─────┘ +│ +└─────┘ +┃ + +┃ +│ + pickup: tracking pickup: waiting +│ + pickup: mixed +│ + pickup: tracking +┃ + +┃ +│ + LIVE + MUTED +│ + MIXED +│ + LIVE +┃ + +┃ +│ + 78% 46% +│ + 62% +│ + 88% +┃ + + + +┃ + Applications + Music Browser + Groups + Media group + Outputs + Master output +┃ + +┗APC MINI: connected (24:0)━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ + +╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ + +│ + ←→/jk +select + ↑↓ +volume + M +mute + Home/End +0/100% + T +theme + Tab +config + Q +quit + ⇧←→/⇧JK +move + A/E/D +separator + ⇧H +hide + h/? +help +│ + +╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ + + diff --git a/docs/images/mixer-vertical.svg b/docs/images/mixer-vertical.svg new file mode 100644 index 0000000..fd37233 --- /dev/null +++ b/docs/images/mixer-vertical.svg @@ -0,0 +1,171 @@ + + + + +╭──────────────────────────────────────────────────────────────────────────────────────────────────────╮ + + + +│ + FADER + MASTER + [1 Mixer] [2 Config] · pulse · PipeWire · ready · rev 42 · Catppuccin Mocha +│ + +╰──────────────────────────────────────────────────────────────────────────────────────────────────────╯ + +┏ + Live mixer objects +━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ + +┃ +┌────────────────────────────────────────────────────────────────────────────────────────────────────┐ +┃ + +┃ +│ ── Applications ── │ +┃ + +┃ +│ │ +┃ + +┃ +└────────────────────────────────────────────────────────────────────────────────────────────────────┘ +┃ + +┃┌ Music [application · 2 streams] pickup: tracking─────────────────────────────────────────────────┐┃ + + + +┃│ +██████████████████████████████████████████████████████████████████████████████ +│┃ + + + + + +┃│ +████████████████████████████████████████████████ +78% +█████████████████████████ +│┃ + +┃└────────────────────────────────────────────────────────────────────────────────────────────────────┘┃ + + + + + +┃ +█████████████████████████████████████████ + Brow +ser 46% MUTED +┃ + +┃┌────────────────────────────────────────────────────────────────────────────────────────────────────┐┃ + +┃│ ── Groups ── │┃ + +┃│ │┃ + +┃└────────────────────────────────────────────────────────────────────────────────────────────────────┘┃ + +┃┌ Media group [group · Music + Browser] pickup: mixed──────────────────────────────────────────────┐┃ + + + +┃│ +██████████████████████████████████████████████████████████████ +│┃ + + + +┃│ +██████████████████████████████████████████████████████████████ +│┃ + + + + + +┃│ +█████████████████████████████████████████████ +62% MIXED +███████ +│┃ + + + +┃│ +██████████████████████████████████████████████████████████████ +│┃ + +┃└────────────────────────────────────────────────────────────────────────────────────────────────────┘┃ + +┃┌────────────────────────────────────────────────────────────────────────────────────────────────────┐┃ + +┃│ ── Outputs ── │┃ + +┃│ │┃ + +┃└────────────────────────────────────────────────────────────────────────────────────────────────────┘┃ + +┃┌ Master output [output · Built-in Audio Analog Stereo] pickup: tracking───────────────────────────┐┃ + + + +┃│ +████████████████████████████████████████████████████████████████████████████████████████ +│┃ + + + + + +┃│ +████████████████████████████████████████████████ +88% +███████████████████████████████████ +│┃ + +┃└────────────────────────────────────────────────────────────────────────────────────────────────────┘┃ + +┃ +┃ + +┃ +┃ + +┃ +┃ + +┗APC MINI: connected (24:0)━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ + +╭──────────────────────────────────────────────────────────────────────────────────────────────────────╮ + +│ + ↑↓/jk +select + ←→ +volume + M +mute + Home/End +0/100% + T +theme + Tab +config + Q +quit + ⇧↑↓/⇧JK +move + A/E/D +se +│ + +╰──────────────────────────────────────────────────────────────────────────────────────────────────────╯ + + diff --git a/docs/related-projects.md b/docs/related-projects.md new file mode 100644 index 0000000..82b3804 --- /dev/null +++ b/docs/related-projects.md @@ -0,0 +1,19 @@ +# Related projects and libraries + +These projects informed the implementation or provide the core integration +layers used by fader_master: + +- [pwvucontrol](https://github.com/saivert/pwvucontrol) — PipeWire volume-control + UI and a useful reference for node/mixer behavior. +- [Ratatui](https://ratatui.rs/) — terminal rendering and widgets. +- [Crossterm](https://docs.rs/crossterm/latest/crossterm/) — portable terminal + input and output used by Ratatui. +- [midir](https://github.com/Boddlnagg/midir) — cross-platform MIDI I/O with an + ALSA backend on Linux. +- [libpulse-binding](https://docs.rs/libpulse-binding/latest/libpulse_binding/) + — PulseAudio protocol introspection and control, including `pipewire-pulse`. +- [pipewire-rs](https://pipewire.pages.freedesktop.org/pipewire-rs/pipewire/) + — reference bindings for the reserved native PipeWire adapter. + +The detailed dependency choices, constraints, and licenses are recorded in the +[architecture research table](../architecture.md#library-research-and-choices). diff --git a/tui/examples/doc_screenshots.rs b/tui/examples/doc_screenshots.rs new file mode 100644 index 0000000..7f8c17a --- /dev/null +++ b/tui/examples/doc_screenshots.rs @@ -0,0 +1,321 @@ +//! Regenerates the deterministic TUI screenshots embedded in the README. + +use std::{fs, io, path::PathBuf}; + +use ratatui::{ + Terminal, + backend::TestBackend, + buffer::Buffer, + style::{Color, Modifier}, +}; +use tui::{ + ConfigurationSnapshot, ConfiguredApplication, ConfiguredFader, ConfiguredGroup, FaderDensity, + GroupVolumeMode, LiveTui, MidiDevice, MixerClient, MixerItem, MixerLayoutEntry, MixerObjectId, + MixerObjectKind, MixerOrientation, MixerSnapshot, PickupStatus, ThemeName, +}; + +const CELL_WIDTH: u16 = 9; +const CELL_HEIGHT: u16 = 18; + +#[derive(Clone)] +struct ScreenshotClient(MixerSnapshot); + +impl MixerClient for ScreenshotClient { + fn snapshot(&mut self) -> io::Result { + Ok(self.0.clone()) + } + + fn set_volume( + &mut self, + _id: MixerObjectId, + _gain: f64, + _expected_revision: u64, + ) -> io::Result { + Ok(self.0.clone()) + } + + fn toggle_mute( + &mut self, + _id: MixerObjectId, + _expected_revision: u64, + ) -> io::Result { + Ok(self.0.clone()) + } +} + +fn main() -> io::Result<()> { + let output = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../docs/images"); + fs::create_dir_all(&output)?; + render( + MixerOrientation::Horizontal, + 140, + 26, + output.join("mixer-horizontal.svg"), + )?; + render( + MixerOrientation::Vertical, + 104, + 38, + output.join("mixer-vertical.svg"), + ) +} + +fn render( + orientation: MixerOrientation, + width: u16, + height: u16, + output: PathBuf, +) -> io::Result<()> { + let app = LiveTui::new(ScreenshotClient(snapshot(orientation)))?; + let mut terminal = Terminal::new(TestBackend::new(width, height))?; + terminal.draw(|frame| frame.render_widget(&app, frame.area()))?; + fs::write(output, buffer_svg(terminal.backend().buffer())) +} + +fn snapshot(mixer_orientation: MixerOrientation) -> MixerSnapshot { + let targets = [ + (MixerObjectKind::Application, "music", "Music"), + (MixerObjectKind::Application, "browser", "Browser"), + (MixerObjectKind::Group, "media", "Media group"), + (MixerObjectKind::Output, "default", "Master output"), + ]; + let items = targets + .into_iter() + .enumerate() + .map(|(index, (kind, id, label))| MixerItem { + id: MixerObjectId { + kind, + id: id.to_owned(), + }, + label: label.to_owned(), + detail: match kind { + MixerObjectKind::Application => "2 streams", + MixerObjectKind::Group => "Music + Browser", + MixerObjectKind::Output => "Built-in Audio Analog Stereo", + } + .to_owned(), + gain: Some([0.78, 0.46, 0.62, 0.88][index]), + gain_mixed: kind == MixerObjectKind::Group, + muted: Some(index == 1), + mute_mixed: kind == MixerObjectKind::Group, + pending: false, + pickup: Some(match index { + 0 | 3 => PickupStatus::Tracking, + 1 => PickupStatus::Waiting, + _ => PickupStatus::Mixed, + }), + writable: true, + error: None, + }) + .collect(); + let faders = targets + .into_iter() + .map(|(kind, id, _)| ConfiguredFader { + id: format!("{id}-fader"), + target: MixerObjectId { + kind, + id: id.to_owned(), + }, + pickup: true, + pickup_tolerance: 0.02, + }) + .collect(); + MixerSnapshot { + revision: 42, + backend: "pulse · PipeWire".to_owned(), + status: "ready".to_owned(), + error: None, + items, + devices: vec![MidiDevice { + id: "apc-mini".to_owned(), + label: "APC MINI".to_owned(), + status: "connected".to_owned(), + backend_id: Some("24:0".to_owned()), + error: None, + }], + configuration: ConfigurationSnapshot { + revision: 7, + dirty: false, + applied_revision: 7, + selection_saved: true, + learning: None, + error: None, + profile_id: "desktop".to_owned(), + mixer_orientation, + default_controller: Some("apc-mini".to_owned()), + theme: ThemeName::CatppuccinMocha, + applications: vec![ + ConfiguredApplication { + id: "music".to_owned(), + label: "Music".to_owned(), + selectors: Vec::new(), + }, + ConfiguredApplication { + id: "browser".to_owned(), + label: "Browser".to_owned(), + selectors: Vec::new(), + }, + ], + groups: vec![ConfiguredGroup { + id: "media".to_owned(), + label: "Media group".to_owned(), + members: vec!["music".to_owned(), "browser".to_owned()], + volume_mode: GroupVolumeMode::Absolute, + }], + faders, + mixer_layout: vec![ + MixerLayoutEntry::Separator { + id: "applications".to_owned(), + label: "Applications".to_owned(), + }, + layout_fader( + "music", + horizontal_density(mixer_orientation, FaderDensity::Standard), + ), + layout_fader( + "browser", + horizontal_density(mixer_orientation, FaderDensity::Slim), + ), + MixerLayoutEntry::Separator { + id: "groups".to_owned(), + label: "Groups".to_owned(), + }, + layout_fader("media", FaderDensity::Thick), + MixerLayoutEntry::Separator { + id: "outputs".to_owned(), + label: "Outputs".to_owned(), + }, + layout_fader( + "default", + horizontal_density(mixer_orientation, FaderDensity::Standard), + ), + ], + bindings: Vec::new(), + }, + } +} + +const fn horizontal_density( + orientation: MixerOrientation, + vertical_density: FaderDensity, +) -> FaderDensity { + match orientation { + MixerOrientation::Horizontal => FaderDensity::Thick, + MixerOrientation::Vertical => vertical_density, + } +} + +fn layout_fader(id: &str, density: FaderDensity) -> MixerLayoutEntry { + MixerLayoutEntry::Fader { + fader: format!("{id}-fader"), + hidden: false, + density, + } +} + +fn buffer_svg(buffer: &Buffer) -> String { + let width = buffer.area.width * CELL_WIDTH; + let height = buffer.area.height * CELL_HEIGHT; + let mut svg = format!( + "\n\n\n" + ); + for y in 0..buffer.area.height { + let mut start = 0; + while start < buffer.area.width { + let background = buffer[(start, y)].bg; + let mut end = start + 1; + while end < buffer.area.width && buffer[(end, y)].bg == background { + end += 1; + } + if background != Color::Reset { + svg.push_str(&format!( + "\n", + start * CELL_WIDTH, + y * CELL_HEIGHT, + (end - start) * CELL_WIDTH, + CELL_HEIGHT, + color(background, "#1e1e2e") + )); + } + start = end; + } + let mut start = 0; + while start < buffer.area.width { + let cell = &buffer[(start, y)]; + let mut end = start + 1; + let mut text = cell.symbol().to_owned(); + while end < buffer.area.width { + let next = &buffer[(end, y)]; + if next.fg != cell.fg || next.modifier != cell.modifier { + break; + } + text.push_str(next.symbol()); + end += 1; + } + if !text.trim().is_empty() { + let weight = if cell.modifier.contains(Modifier::BOLD) { + " font-weight=\"bold\"" + } else { + "" + }; + svg.push_str(&format!( + "{}\n", + start * CELL_WIDTH, + y * CELL_HEIGHT + 1, + color(cell.fg, "#cdd6f4"), + weight, + escape_xml(&text) + )); + } + start = end; + } + } + svg.push_str("\n\n"); + svg +} + +fn color(color: Color, reset: &str) -> String { + match color { + Color::Reset => reset.to_owned(), + Color::Black => "#11111b".to_owned(), + Color::Red => "#f38ba8".to_owned(), + Color::Green => "#a6e3a1".to_owned(), + Color::Yellow => "#f9e2af".to_owned(), + Color::Blue => "#89b4fa".to_owned(), + Color::Magenta => "#cba6f7".to_owned(), + Color::Cyan => "#89dceb".to_owned(), + Color::Gray => "#bac2de".to_owned(), + Color::DarkGray => "#585b70".to_owned(), + Color::LightRed => "#eba0ac".to_owned(), + Color::LightGreen => "#94e2d5".to_owned(), + Color::LightYellow => "#fab387".to_owned(), + Color::LightBlue => "#74c7ec".to_owned(), + Color::LightMagenta => "#f5c2e7".to_owned(), + Color::LightCyan => "#b4befe".to_owned(), + Color::White => "#cdd6f4".to_owned(), + Color::Rgb(red, green, blue) => format!("#{red:02x}{green:02x}{blue:02x}"), + Color::Indexed(index) => indexed_color(index).to_owned(), + } +} + +const fn indexed_color(index: u8) -> &'static str { + match index { + 0..=7 => "#6c7086", + 8..=15 => "#cdd6f4", + 16..=51 => "#89b4fa", + 52..=87 => "#f38ba8", + 88..=123 => "#a6e3a1", + 124..=159 => "#f9e2af", + 160..=195 => "#cba6f7", + 196..=231 => "#89dceb", + _ => "#bac2de", + } +} + +fn escape_xml(value: &str) -> String { + value + .replace('&', "&") + .replace('<', "<") + .replace('>', ">") + .replace('"', """) +}