From 6c0c8be2d08ecadb4007c2669c7e896935768cb5 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Wed, 14 Oct 2026 15:14:03 +0200 Subject: [PATCH] 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) --- README.md | 20 +++- architecture.md | 6 +- fader_master/src/main.rs | 4 +- tui/examples/tui_test.rs | 10 +- tui/src/lib.rs | 207 +++++++++++++++++++++++++++------------ 5 files changed, 168 insertions(+), 79 deletions(-) diff --git a/README.md b/README.md index 6423eda..f66b3a0 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/architecture.md b/architecture.md index 57ea7a3..31b0925 100644 --- a/architecture.md +++ b/architecture.md @@ -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 diff --git a/fader_master/src/main.rs b/fader_master/src/main.rs index e7a11a9..9660cb8 100644 --- a/fader_master/src/main.rs +++ b/fader_master/src/main.rs @@ -1,3 +1,3 @@ -fn main() { - println!("Hello, world!"); +fn main() -> std::io::Result<()> { + tui::run() } diff --git a/tui/examples/tui_test.rs b/tui/examples/tui_test.rs index 49f3aa5..9660cb8 100644 --- a/tui/examples/tui_test.rs +++ b/tui/examples/tui_test.rs @@ -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() } diff --git a/tui/src/lib.rs b/tui/src/lib.rs index 51dac35..3812e8e 100644 --- a/tui/src/lib.rs +++ b/tui/src/lib.rs @@ -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(), - "".blue().bold(), - " Increment ".into(), - "".blue().bold(), - " Quit ".into(), - " ".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, +#[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::(); + + assert!(rendered.contains("FADER")); + assert!(rendered.contains("Desktop audio")); + assert!(rendered.contains("65%")); + assert!(rendered.contains("Q/Esc")); + } }