feat(tui): launch an interactive mixer shell

Replace the hidden placeholder example with a visible mixer screen launched by the main executable. Add working volume and quit controls, explicit demo-state labeling, render/input coverage, and documented launch instructions.

Tests: cargo fmt --all -- --check; cargo check --workspace --all-targets --all-features --locked; cargo test --workspace --all-targets --all-features --locked; cargo test --workspace --doc --all-features --locked; cargo clippy --workspace --all-targets --all-features --locked -- -D warnings; cargo build --workspace --release --all-features --locked; cargo check --workspace --all-targets --no-default-features --locked; cargo test --workspace --all-targets --no-default-features --locked; cargo run --locked -p fader_master in a PTY with clean quit (all pass)
This commit is contained in:
Dandaedre 2026-10-14 15:14:03 +02:00
parent 7d24fbda62
commit 6c0c8be2d0
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
5 changed files with 168 additions and 79 deletions

View File

@ -6,11 +6,11 @@
Linux application volume and mute control from one or more USB MIDI surfaces.
This repository currently contains a tested Rust domain library and TUI prototype.
The domain layer supports matching, routing, balanced group volume plans, and mute
intent; the executable is still a scaffold. Configuration work starts at M2.
The server, audio adapters, persistent bindings, and configuration editor are
planned in the following documents:
This repository currently contains tested domain and configuration libraries plus
an interactive TUI shell. The domain layer supports matching, routing, balanced
group volume plans, and mute intent. Atomic TOML persistence and checkpointing are
implemented; the server, audio adapters, persistent bindings, and configuration
editor remain planned in the following documents:
- [Architecture and library research](architecture.md)
- [Implementation tasks and acceptance tests](task.md)
@ -18,6 +18,16 @@ planned in the following documents:
- [Build prerequisites and MSRV](docs/build.md)
- [CI coverage and badge lifecycle](docs/ci-coverage.md)
## Run the TUI
```sh
cargo run --locked -p fader_master
```
Use the arrow keys to move the demo fader, Home/End for its endpoints, and Q or
Escape to quit. The screen currently uses local demo state; live server and audio
integration follow in M3–M8.
# References
* [pwvucontrol](https://github.com/saivert/pwvucontrol/blob/main/src/backend/pwnodeobject/mixerapi.rs)

View File

@ -1,9 +1,9 @@
# fader_master architecture
Status: design researched 2026-10-05; foundation, M1 domain contracts, and the
M2 TOML/persistence milestone are implemented. The executable remains a Hello
World scaffold and the TUI remains a basic Ratatui example. Runtime workers and
native adapters below are planned, not shipped.
M2 TOML/persistence milestone are implemented. The executable launches an
interactive Ratatui mixer shell backed by explicitly labeled demo state. Runtime
workers, live TUI state, and native adapters below are planned, not shipped.
## Implemented boundary at M2 entry

View File

@ -1,3 +1,3 @@
fn main() {
println!("Hello, world!");
fn main() -> std::io::Result<()> {
tui::run()
}

View File

@ -1,9 +1,3 @@
use std::io;
use tui::Tui;
fn main() -> io::Result<()> {
let mut terminal = ratatui::init();
let app_result = Tui::default().run(&mut terminal);
ratatui::restore();
app_result
fn main() -> std::io::Result<()> {
tui::run()
}

View File

@ -1,32 +1,46 @@
//! Simple lib to handle creation of a simple TUI to visualisize faders
//!
//! Kinda specless for now, there are faders, volume, menu nav, fader creation, destruction and outputs
//!
//!
//! Terminal user interface for fader_master.
use std::io;
use crossterm::event::{self, Event, KeyCode, KeyEvent, KeyEventKind};
use ratatui::{
DefaultTerminal, Frame,
buffer::Buffer,
crossterm,
layout::Rect,
style::Stylize,
crossterm::event::{self, Event, KeyCode, KeyEvent, KeyEventKind},
layout::{Alignment, Constraint, Direction, Layout, Rect},
style::{Color, Modifier, Style, Stylize},
symbols::border,
text::{Line, Text},
widgets::{Block, Paragraph, Widget},
text::Line,
widgets::{Block, Gauge, Paragraph, Widget},
};
/// Experimental global runner
#[allow(dead_code)]
#[derive(Debug, Default)]
const VOLUME_STEP: u8 = 5;
/// Runs the interactive terminal UI and restores the terminal before returning.
pub fn run() -> io::Result<()> {
let mut terminal = ratatui::init();
let result = Tui::default().run(&mut terminal);
ratatui::restore();
result
}
/// State for the initial interactive mixer shell.
#[derive(Debug)]
pub struct Tui {
volume: u8,
exit: bool,
}
impl Default for Tui {
fn default() -> Self {
Self {
volume: 65,
exit: false,
}
}
}
impl Tui {
/// Runs the application's main loop until the user quits
/// Runs the application's main loop until the user quits.
pub fn run(&mut self, terminal: &mut DefaultTerminal) -> io::Result<()> {
while !self.exit {
terminal.draw(|frame| self.draw(frame))?;
@ -35,71 +49,142 @@ impl Tui {
Ok(())
}
/// Draw a frame
fn draw(&self, frame: &mut Frame) {
frame.render_widget(self, frame.area());
}
/// Process all the event handling
fn handle_events(&mut self) -> io::Result<()> {
match event::read()? {
// it's important to check that the event is a key press event as
// crossterm also emits key release and repeat events on Windows.
Event::Key(key_event) if key_event.kind == KeyEventKind::Press => {
self.handle_key_event(key_event)
}
_ => {}
};
if let Event::Key(key_event) = event::read()?
&& key_event.kind == KeyEventKind::Press
{
self.handle_key_event(key_event);
}
Ok(())
}
fn handle_key_event(&mut self, key_event: KeyEvent) {
// KeyCode::Left => self.decrement_counter(),
// KeyCode::Right => self.increment_counter(),
if let KeyCode::Char('q') = key_event.code {
self.exit();
match key_event.code {
KeyCode::Left | KeyCode::Down => {
self.volume = self.volume.saturating_sub(VOLUME_STEP);
}
KeyCode::Right | KeyCode::Up => {
self.volume = self.volume.saturating_add(VOLUME_STEP).min(100);
}
KeyCode::Home => self.volume = 0,
KeyCode::End => self.volume = 100,
KeyCode::Esc | KeyCode::Char('q') => self.exit = true,
_ => {}
}
}
fn exit(&mut self) {
self.exit = true;
}
}
/// Makes the Tui into a Widget to use it as
impl Widget for &Tui {
fn render(self, area: Rect, buf: &mut Buffer) {
let title = Line::from("TUI Title".bold());
let instructions = Line::from(vec![
" Decrement ".into(),
"<Left>".blue().bold(),
" Increment ".into(),
"<Right>".blue().bold(),
" Quit ".into(),
"<Q> ".blue().bold(),
]);
let block = Block::bordered()
.title(title.centered())
.title_bottom(instructions.centered())
let [header, body, footer] = Layout::default()
.direction(Direction::Vertical)
.constraints([
Constraint::Length(3),
Constraint::Min(5),
Constraint::Length(3),
])
.areas(area);
Paragraph::new(Line::from(vec![
" FADER ".fg(Color::Black).bg(Color::Cyan).bold(),
" MASTER ".bold(),
]))
.alignment(Alignment::Center)
.block(Block::bordered().border_set(border::ROUNDED))
.render(header, buf);
let mixer = Block::bordered()
.title(" Mixer ".bold())
.title_bottom(" demo state · live server connection follows in M7 ".dark_gray())
.border_set(border::THICK);
let inner = mixer.inner(body);
mixer.render(body, buf);
let counter_text = Text::from(vec![Line::from(vec![
"Volume: ".into(),
self.volume.to_string().yellow(),
])]);
let [label, meter, state] = Layout::default()
.direction(Direction::Vertical)
.constraints([
Constraint::Length(2),
Constraint::Length(3),
Constraint::Min(1),
])
.margin(1)
.areas(inner);
Paragraph::new(counter_text)
.centered()
.block(block)
.render(area, buf);
Paragraph::new("Desktop audio")
.style(Style::default().add_modifier(Modifier::BOLD))
.render(label, buf);
Gauge::default()
.block(Block::bordered())
.gauge_style(Style::default().fg(Color::Cyan).bg(Color::DarkGray))
.percent(u16::from(self.volume))
.label(format!("{}%", self.volume))
.render(meter, buf);
Paragraph::new("● Adapter: demo ● MIDI: waiting ○ Mute: off")
.style(Style::default().fg(Color::Gray))
.render(state, buf);
Paragraph::new(Line::from(vec![
" ←/↓ ".into(),
"volume down".cyan(),
" →/↑ ".into(),
"volume up".cyan(),
" Home/End ".into(),
"min/max".cyan(),
" Q/Esc ".into(),
"quit".cyan(),
]))
.alignment(Alignment::Center)
.block(Block::bordered().border_set(border::ROUNDED))
.render(footer, buf);
}
}
#[allow(dead_code)]
/// An individual volume widget
pub struct SingleFader {
/// The individual volume of the fader
volume: usize,
// application: String,
midi_note: Vec<usize>,
#[cfg(test)]
mod tests {
use super::*;
fn press(code: KeyCode) -> KeyEvent {
KeyEvent::new(code, ratatui::crossterm::event::KeyModifiers::NONE)
}
#[test]
fn volume_keys_move_and_clamp_the_demo_fader() {
let mut app = Tui::default();
app.handle_key_event(press(KeyCode::End));
app.handle_key_event(press(KeyCode::Right));
assert_eq!(app.volume, 100);
app.handle_key_event(press(KeyCode::Home));
app.handle_key_event(press(KeyCode::Left));
assert_eq!(app.volume, 0);
}
#[test]
fn quit_keys_request_exit() {
let mut app = Tui::default();
app.handle_key_event(press(KeyCode::Char('q')));
assert!(app.exit);
}
#[test]
fn mixer_shell_renders_at_a_typical_terminal_size() {
let area = Rect::new(0, 0, 100, 20);
let mut buffer = Buffer::empty(area);
(&Tui::default()).render(area, &mut buffer);
let rendered = buffer
.content
.iter()
.map(|cell| cell.symbol())
.collect::<String>();
assert!(rendered.contains("FADER"));
assert!(rendered.contains("Desktop audio"));
assert!(rendered.contains("65%"));
assert!(rendered.contains("Q/Esc"));
}
}