diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 66c1019..c18823f 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -293,6 +293,17 @@ created or edited while Furumi is running without rebuilding or restarting the application. Bundled scripts use the same path and contract as user scripts, so built-in and custom visualizations exercise the same runtime. +The v2 primitives are sufficient for small perspective wireframes without a +native 3D engine. The bundled morphing cube transforms eight vertices in Rhai +and batches its twelve edges into trace/vertical-line commands. Perspective, +audio-driven deformation, and depth cues stay in the user-editable script; +Rust rasterizes the resulting 2D commands. This deliberately avoids per-cell +script command maps and does not provide filled meshes or a depth buffer. +The richer cube preset adds bounded particle, ring, inner-cage, and echo +layers. Echo poses are reconstructed from earlier times with current audio +features, rather than retaining previous frames; particles have deterministic +lifetimes. Small terminals omit expensive layers and reduce particle counts. + The Rhai engine is configured as a sandboxed computation environment. Module loading through `import` and `export` is disabled, no filesystem or network API is exposed to scripts, and execution is bounded by limits on operations, call @@ -305,6 +316,34 @@ intended role: transforming current audio features into drawing commands. It is not a plugin mechanism for accessing the library, network, or player controls. +Fullscreen execution currently happens synchronously during UI drawing, with a fresh +Rhai scope for each frame; scripts should derive motion from time and the +already-smoothed audio features rather than rely on retained mutable state. +The 50 ms animation timer gives a nominal 20 FPS cadence (other events can +also trigger redraws). Operation limits are not wall-clock deadlines. The +host also checks the script modification time during drawing, so slow script +storage or expensive custom scripts can still delay input. Benchmark script +evaluation and buffer drawing separately from real terminal throughput before +increasing scene complexity or the refresh rate. + +The embedded status surface uses the same Rhai engine, input map, command +decoder, and clipped buffer rasterizer with a one-row viewport. It has an +independent AST cache and a fixed user-editable script in +`visualizations/status/braille.rhai`, installed if absent. Exact copies of the +previous bundled default can be atomically upgraded; edited files are preserved. It is not a +fullscreen preset. During local playback the visual timer samples the audio +analyzer without increasing trusted-device publication frequency. At most +one blocking render job is in flight; excess ticks are dropped. File access, +compilation, evaluation, and buffer preparation happen on that worker. +An `AppEvent` delivers a prepared row to `AppState`; UI drawing only copies +cells. Its audio input comes from the decoded-source analyzer before output +volume scaling; the volume field remains informational. Pause suspends jobs +and retains the last frame, even when the row needs resizing. Generation +checks discard results invalidated by track changes, resize, pause/resume, +or stop. Script errors are confined to the row and retried so +editing the file repairs the display. Status scripts have a smaller operation +budget, bounded source/output sizes, and cannot draw outside their viewport. + ## Music-similarity indexing Similarity search is an optional local capability and is disabled by default. diff --git a/Cargo.toml b/Cargo.toml index 9b1ba6d..aaae58a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "furumi_tui" -version = "0.3.3" +version = "0.3.4" edition = "2024" rust-version = "1.97" description = "A federated P2P player for personal music libraries" diff --git a/src/app/event.rs b/src/app/event.rs index e7fefcc..54feb60 100644 --- a/src/app/event.rs +++ b/src/app/event.rs @@ -14,6 +14,7 @@ pub enum AppEvent { UpdateProgress(String), UpdateInstalled(Result<(), String>), StatusMessage(String), + StatusVisualizationReady(crate::visualizer::status::Ready), /// A page of the artists list arrived (or failed). ArtistsLoaded(Result), /// A full reload after a library change: replaces the loaded artist diff --git a/src/app/mod.rs b/src/app/mod.rs index 9e6ba09..ba7ee52 100644 --- a/src/app/mod.rs +++ b/src/app/mod.rs @@ -75,6 +75,7 @@ pub struct Runtime { pub media_tx: std::sync::mpsc::Sender, pub last_media_push: Option, pub status_publisher: crate::status::Publisher, + pub status_visualizer: crate::visualizer::status::Renderer, } #[derive(Debug, Clone, Copy)] @@ -510,6 +511,7 @@ pub async fn run( media_tx, last_media_push: None, status_publisher: crate::status::Publisher::spawn(), + status_visualizer: crate::visualizer::status::Renderer::default(), }; spawn_content_id_backfill(&runtime); if state.similarity.settings.enabled { @@ -533,6 +535,7 @@ pub async fn run( tick.set_missed_tick_behavior(MissedTickBehavior::Skip); let mut visual_tick = tokio::time::interval(VISUALIZER_TICK_INTERVAL); visual_tick.set_missed_tick_behavior(MissedTickBehavior::Skip); + let mut redraw = true; loop { let plain_text = match state.popup.as_ref() { @@ -552,7 +555,8 @@ pub async fn run( _ => {} } - if !runtime.plain_text_mode { + sync_status_visualizer_target(&mut state, terminal.get_frame().area()); + if !runtime.plain_text_mode && (redraw || runtime.force_redraw) { if runtime.force_redraw { terminal.clear()?; runtime.force_redraw = false; @@ -560,6 +564,7 @@ pub async fn run( terminal.draw(|frame| ui::draw(frame, &state, &keymap))?; } + redraw = true; tokio::select! { maybe_event = input.next() => match maybe_event { Some(Ok(event)) => handle_terminal_event(&mut state, &mut keymap, &mut runtime, event), @@ -578,8 +583,21 @@ pub async fn run( maybe_prefetch_next(&mut state, &runtime); push_media_update(&state, &mut runtime, false); } - _ = visual_tick.tick(), if state.visualizer.active => { - sync_player_shared(&mut state, &runtime); + _ = visual_tick.tick(), if state.visualizer.active || crate::visualizer::status::playing(&state) => { + if state.visualizer.active { + sync_player_shared(&mut state, &runtime); + } else { + // The embedded meter only needs the atomic audio snapshot; + // keep device publication on the ordinary player tick. + state.player.audio_analysis = runtime.player.shared.audio_analysis(); + // The ready event will repaint. Avoid rendering the old + // meter once here and the new meter again on completion. + redraw = false; + } + sync_status_visualizer_target(&mut state, terminal.get_frame().area()); + if !runtime.plain_text_mode { + runtime.status_visualizer.request(&state, runtime.event_tx.clone()); + } } } @@ -630,6 +648,21 @@ fn leave_plain_text_mode() -> Result<()> { Ok(()) } +fn sync_status_visualizer_target(state: &mut AppState, screen: ratatui::layout::Rect) { + let area = ui::status_visualizer_area(screen, state); + let target = if crate::visualizer::status::visible(state) && !area.is_empty() { + state + .player + .current + .as_ref() + .map(|track| (area.width, track_playback_key(track))) + } else { + None + }; + state.status_visualizer.set_target(target); + state.status_visualizer.set_paused(state.player.paused); +} + fn sync_player_shared(state: &mut AppState, runtime: &Runtime) { if state.device_playback.is_control() { extrapolate_control_position(state); @@ -3304,6 +3337,10 @@ fn handle_playback_command( fn handle_app_event(state: &mut AppState, runtime: &mut Runtime, event: AppEvent) { match event { + AppEvent::StatusVisualizationReady(ready) => { + runtime.status_visualizer.busy = false; + state.status_visualizer.apply(ready); + } AppEvent::UpdateChecked(result) => { state.updater.busy = false; state.updater.message = match result { diff --git a/src/app/state.rs b/src/app/state.rs index 0b6cbfd..bc8d66b 100644 --- a/src/app/state.rs +++ b/src/app/state.rs @@ -1672,6 +1672,7 @@ pub struct AppState { pub device_playback: DevicePlaybackState, pub jam: crate::jam::JamStatus, pub visualizer: crate::visualizer::VisualizerState, + pub status_visualizer: crate::visualizer::status::State, pub global: GlobalTab, pub artist_views: HashMap>, /// Federated card data that enriches a local artist page in-place. diff --git a/src/ui/mod.rs b/src/ui/mod.rs index 76fa2ab..06edf88 100644 --- a/src/ui/mod.rs +++ b/src/ui/mod.rs @@ -5,6 +5,8 @@ mod global; mod logs; mod playlists; mod popup; +#[cfg(test)] +mod status_tests; pub mod theme; use ratatui::Frame; @@ -334,7 +336,7 @@ fn format_secs(secs: f64) -> String { /// Playback time, progress bar, queue position, volume and mode flags. /// Wider consoles get a longer bar and full flags; narrow ones drop pieces. -fn player_right_line(state: &AppState, width: u16) -> Line<'static> { +fn player_right_line(state: &AppState, width: u16) -> (Line<'static>, u16) { let player = &state.player; let mut spans: Vec> = Vec::new(); if let Some(track) = &player.current @@ -364,6 +366,7 @@ fn player_right_line(state: &AppState, width: u16) -> Line<'static> { )); } } + let volume_offset = spans.iter().map(Span::width).sum::() + 2; if width >= 80 { let volume_cells = usize::from(player.volume / 10); spans.extend([ @@ -404,18 +407,69 @@ fn player_right_line(state: &AppState, width: u16) -> Line<'static> { } // Keep a gap between the flags and the username block to the right. spans.push(Span::raw(" ")); - Line::from(spans) + ( + Line::from(spans), + volume_offset.min(usize::from(u16::MAX)) as u16, + ) +} + +/// Shared geometry for rendering and background visualization requests. +fn footer_areas(area: Rect, state: &AppState) -> [Rect; 3] { + let [player_row, message_row] = + Layout::vertical([Constraint::Length(1), Constraint::Length(1)]).areas(area); + let (line, volume_offset) = player_right_line(state, area.width); + let right_width = line.width().min(usize::from(area.width)) as u16; + let [_, right] = + Layout::horizontal([Constraint::Min(8), Constraint::Length(right_width)]).areas(player_row); + let version_width = (env!("CARGO_PKG_VERSION").len() as u16 + 1).min(message_row.width); + let version = Rect::new( + message_row.x + message_row.width.saturating_sub(version_width) / 2, + message_row.y, + version_width, + message_row.height, + ); + let message = Rect::new( + message_row.x, + message_row.y, + version.x.saturating_sub(message_row.x).saturating_sub(1), + message_row.height, + ); + // On wide terminals align exactly with "vol". On narrow ones keep the + // centered version readable, shrinking the histogram into the remainder. + let start = right + .x + .saturating_add(volume_offset) + .max(version.right().saturating_add(1)) + .min(message_row.right()); + let visual = Rect::new( + start, + message_row.y, + message_row.right().saturating_sub(start), + message_row.height, + ); + [message, version, visual] +} + +pub(crate) fn status_visualizer_area(screen: Rect, state: &AppState) -> Rect { + let [_, _, status] = Layout::vertical([ + Constraint::Length(1), + Constraint::Min(0), + Constraint::Length(2), + ]) + .areas(screen); + footer_areas(status, state)[2] } fn draw_status(frame: &mut Frame, area: Rect, state: &AppState) { - let [player_row, message_row] = + let [player_row, _] = Layout::vertical([Constraint::Length(1), Constraint::Length(1)]).areas(area); + let [message_row, version_area, visual_area] = footer_areas(area, state); let player = &state.player; // Layout: track title left, time/progress/flags on the right. The // right block is built first and gets a fixed width; the title // truncates into whatever is left. - let center = player_right_line(state, area.width); + let (center, _) = player_right_line(state, area.width); let center_width = (center.width() as u16).min(area.width); let [title_area, right_area] = Layout::horizontal([Constraint::Min(8), Constraint::Length(center_width)]) @@ -444,6 +498,10 @@ fn draw_status(frame: &mut Frame, area: Rect, state: &AppState) { } frame.render_widget(Paragraph::new(Line::from(spans)), title_area); frame.render_widget(Paragraph::new(center), right_area); + draw_version(frame, version_area); + if crate::visualizer::status::visible(state) { + state.status_visualizer.draw(frame, visual_area); + } if state.cmdline.active { // Vim-style command line takes over the message row. @@ -453,7 +511,6 @@ fn draw_status(frame: &mut Frame, area: Rect, state: &AppState) { usize::from(message_row.width.saturating_sub(2)), )); frame.render_widget(Paragraph::new(Line::from(spans)), message_row); - draw_version(frame, message_row); return; } @@ -475,7 +532,6 @@ fn draw_status(frame: &mut Frame, area: Rect, state: &AppState) { }, }; frame.render_widget(Paragraph::new(message), message_row); - draw_version(frame, message_row); if let Some(pending) = &state.pending_keys { let pending = Paragraph::new(Line::styled( @@ -507,7 +563,7 @@ fn active_artist_peer_search(state: &AppState) -> Option { fn draw_version(frame: &mut Frame, area: Rect) { let version = format!("v{}", env!("CARGO_PKG_VERSION")); frame.render_widget( - Paragraph::new(Line::styled(version, theme::dim())).alignment(Alignment::Right), + Paragraph::new(Line::styled(version, theme::dim())).alignment(Alignment::Center), area, ); } diff --git a/src/ui/status_tests.rs b/src/ui/status_tests.rs new file mode 100644 index 0000000..d411f4f --- /dev/null +++ b/src/ui/status_tests.rs @@ -0,0 +1,110 @@ +use super::*; +use ratatui::{Terminal, backend::TestBackend}; + +fn playing_state() -> AppState { + let mut state = AppState::default(); + state.player.current = Some(crate::library::models::TrackItem { + id: 1, + title: "Песня 界".into(), + track_number: None, + disc_number: None, + duration_seconds: 240.0, + artists: vec![], + featured_artists: vec![], + release_id: 1, + release_title: "Release".into(), + release_year: None, + cover_path: None, + file_path: "/unused/test.flac".into(), + content_id: None, + audio_format: None, + audio_bitrate: None, + audio_sample_rate: None, + audio_bit_depth: None, + file_size_bytes: None, + play_count: 0, + fed: None, + }); + state.player.playing = true; + state.player.position_secs = 12.0; + state +} + +#[test] +fn footer_centers_version_and_aligns_visualization_under_volume() { + let mut state = playing_state(); + for width in [160, 200] { + for shuffle in [false, true] { + state.player.shuffle = shuffle; + let mut terminal = Terminal::new(TestBackend::new(width, 2)).unwrap(); + terminal + .draw(|frame| draw_status(frame, frame.area(), &state)) + .unwrap(); + let buffer = terminal.backend().buffer(); + let version = format!("v{}", env!("CARGO_PKG_VERSION")); + // Count display cells, not UTF-8 bytes: the title is non-ASCII. + let volume_x = (0..width) + .find(|x| { + buffer[(*x, 0)].symbol() == "v" + && *x + 2 < width + && buffer[(*x + 1, 0)].symbol() == "o" + && buffer[(*x + 2, 0)].symbol() == "l" + }) + .unwrap(); + let areas = footer_areas(Rect::new(0, 0, width, 2), &state); + assert_eq!(areas[2].x, volume_x); + assert_eq!(areas[2].y, 1); + assert_eq!(areas[2].right(), width); + let version_x = (width - version.len() as u16) / 2; + for (offset, ch) in version.chars().enumerate() { + assert_eq!( + buffer[(version_x + offset as u16, 1)].symbol(), + ch.to_string() + ); + } + assert_eq!( + status_visualizer_area(Rect::new(0, 0, width, 24), &state).x, + volume_x + ); + } + } +} + +#[test] +fn footer_regions_do_not_overlap_on_narrow_terminals_or_command_input() { + let mut state = playing_state(); + state.status_message = Some("long status message ".repeat(20)); + for width in [1, 5, 8, 20, 40, 80, 120, 200] { + let areas = footer_areas(Rect::new(0, 0, width, 2), &state); + assert!(areas[0].right() <= areas[1].x); + assert!(areas[1].right() <= areas[2].x); + assert!(areas[2].right() <= width); + for command in [false, true] { + state.cmdline.active = command; + let mut terminal = Terminal::new(TestBackend::new(width, 2)).unwrap(); + terminal + .draw(|frame| draw_status(frame, frame.area(), &state)) + .unwrap(); + // Neither messages nor the command prompt may paint the graph. + for x in areas[2].x..areas[2].right() { + assert_eq!(terminal.backend().buffer()[(x, 1)].symbol(), " "); + } + } + } +} + +#[test] +fn status_animation_requires_local_unpaused_playback() { + let mut state = playing_state(); + assert!(crate::visualizer::status::playing(&state)); + state.player.paused = true; + assert!(!crate::visualizer::status::playing(&state)); + assert!(crate::visualizer::status::visible(&state)); + state.player.paused = false; + state.player.playing = false; + assert!(!crate::visualizer::status::playing(&state)); + assert!(!crate::visualizer::status::visible(&state)); + state.player.playing = true; + state.device_playback.role = crate::app::state::DevicePlaybackRole::Control; + assert!(!crate::visualizer::status::playing(&state)); +} diff --git a/src/visualizations/morphing_cube.rhai b/src/visualizations/morphing_cube.rhai new file mode 100644 index 0000000..2b85844 --- /dev/null +++ b/src/visualizations/morphing_cube.rhai @@ -0,0 +1,279 @@ +// name: Morphing cube +// protocol: furumi-visualizer-v2 +// bundle-version: 6 +// +// Audio-reactive neon wireframe, echo contours, core, shock rings, sparks +// and a bounded particle field. No native 3D API or retained state required. +// Echoes sample earlier rotation times with CURRENT audio; they are analytic +// trails, not stored frames. Particle lifetimes use time, rings also expand +// as the smoothed beat envelope decays. No beat history is available in v2. +// +// Fixed budgets: 8 mesh vertices, at most 48 particles + 24 short tails, +// 20 background stars, 3 rings, 2 echoes. Edges/rings use bulk trace commands. +// Smaller terminals omit echoes/rings and reduce particle counts. + +fn clamp(v, lo, hi) { + if v < lo { lo } else if v > hi { hi } else { v } +} + +fn min(a, b) { if a < b { a } else { b } } + +fn rgb(r, g, b) { + to_int(clamp(r, 0.0, 255.0)) * 65536 + + to_int(clamp(g, 0.0, 255.0)) * 256 + + to_int(clamp(b, 0.0, 255.0)) +} + +// trace runs left-to-right. Swap endpoints for reversed edges and use +// vline for vertical ones (including an edge projected to a single cell). +fn edge(ax, ay, bx, by, fg, bg) { + if ax > bx { + let tx = ax; ax = bx; bx = tx; + let ty = ay; ay = by; by = ty; + } + if ax == bx { + return #{ op: "vline", x: ax, y: min(ay, by), + h: abs(to_float(by - ay)).to_int() + 1, ch: "|", fg: fg, bg: bg }; + } + let dx = bx - ax; + let dy = by - ay; + let ch = if abs(to_float(dy)) * 3.0 < to_float(dx) { "-" } + else if abs(to_float(dy)) > to_float(dx) { "|" } + else if dy < 0 { "/" } else { "\\" }; + let ys = []; + let slope = to_float(dy) / to_float(dx); + for x in 0..=dx { + ys.push(to_int(to_float(ay) + to_float(x) * slope + 0.5)); + } + #{ op: "trace", x: ax, ys: ys, ch: ch, line_ch: ch, + fg: fg, line_fg: fg, bg: bg } +} + +// Lift quieter passages without a hard gain/clipping threshold. +fn response(level) { 1.0 - pow(1.0 - clamp(level, 0.0, 1.0), 1.6) } + +fn palette(t, heat, light) { + rgb((95.0 + 125.0 * heat + 35.0 * sin(t * 0.43)) * light, + (185.0 - 95.0 * heat + 55.0 * sin(t * 0.31 + 1.3)) * light, + 255.0 * light) +} + +// A single projected mesh, fitted uniformly: never clamp individual corners. +fn mesh(t, energy, bass, mid, treble, beat, width, height) { + let pulse = 0.70 + energy * 0.45 + beat * 0.85; + let sx = pulse * (1.0 + bass * 0.55); + let sy = pulse * (1.0 - bass * 0.42 + mid * 0.15); + let sz = pulse * (1.0 + treble * 0.22); + // A bounded beat kick, not time * instantaneous_energy (which jumps). + let ax = t * 0.47 + 0.35 + beat * 0.22 * sin(t * 1.3); + let ay = t * 0.63 + 0.55; + let az = t * 0.23 + beat * 0.16 * cos(t * 0.7); + let cx = cos(ax); let snx = sin(ax); + let cy = cos(ay); let sny = sin(ay); + let cz = cos(az); let snz = sin(az); + let twist = mid * 0.95 * sin(t * 0.83); + let ct = cos(twist); let st = sin(twist); + let vertices = [ + [-1.0, -1.0, -1.0], [1.0, -1.0, -1.0], + [1.0, 1.0, -1.0], [-1.0, 1.0, -1.0], + [-1.0, -1.0, 1.0], [1.0, -1.0, 1.0], + [1.0, 1.0, 1.0], [-1.0, 1.0, 1.0] + ]; + let projected = []; + let extent = 0.01; + for i in 0..8 { + let v = vertices[i]; + let pull = 1.0 + treble * 0.38 * sin(t * 2.3 + to_float(i) * 2.4) + + beat * 0.14 * cos(to_float(i) * 1.7 + t); + let x = v[0] * sx * pull; + let y = v[1] * sy * pull; + let z = v[2] * sz * pull; + let xt = x * ct + z * st * v[1]; + let zt = z * ct - x * st * v[1]; + let y1 = y * cx - zt * snx; + let z1 = y * snx + zt * cx; + let x2 = xt * cy + z1 * sny; + let z2 = z1 * cy - xt * sny; + let x3 = x2 * cz - y1 * snz; + let y3 = x2 * snz + y1 * cz; + // Even the largest deformed vertex stays < 6.4 from the origin. + let perspective = 10.0 / (10.0 + z2); + let px = x3 * perspective; + let py = y3 * perspective; + if abs(px) > extent { extent = abs(px); } + if abs(py) > extent { extent = abs(py); } + projected.push([px, py, z2]); + } + // CELL_ASPECT is cell height / width; adjust for a different font. + let CELL_ASPECT = 2.0; + let span = min(to_float(width - 4) / CELL_ASPECT, to_float(height - 4)); + let scale = span * min(0.23, 0.46 / extent); + let center_x = to_float(width - 1) * 0.5; + let center_y = to_float(height - 1) * 0.5; + let points = []; + for p in projected { + points.push([to_int(center_x + p[0] * scale * CELL_ASPECT + 0.5), + to_int(center_y + p[1] * scale + 0.5), p[2]]); + } + points +} + +// Method calls mutate the command array in place; don't copy it into helpers. +fn dot(x, y, ch, fg, bg, width, height) { + let px = to_int(x + 0.5); let py = to_int(y + 0.5); + if x >= 0.0 && y >= 1.0 && px < width && py < height - 1 { + this.push(#{ op: "cell", x: px, y: py, ch: ch, fg: fg, bg: bg }); + } +} + +fn render(input) { + let bg = 0x020610; + let cmds = [#{ op: "clear", bg: bg }]; + if input.width < 12 || input.height < 8 { return cmds; } + let w = input.width; let h = input.height; + let t = input.time; + let energy = response(input.energy); + let bass = response(input.bass); + let mid = response(input.mid); + let treble = response(input.treble); + let beat = response(input.beat); + let drive = clamp(energy * 0.4 + treble * 0.3 + beat * 0.8, 0.0, 1.0); + let small = w < 40 || h < 16; + let center_x = to_float(w - 1) * 0.5; + let center_y = to_float(h - 1) * 0.5; + let span = min(to_float(w - 4) * 0.5, to_float(h - 4)); + let points = mesh(t, energy, bass, mid, treble, beat, w, h); + let edges = [[0,1], [1,2], [2,3], [3,0], [4,5], [5,6], + [6,7], [7,4], [0,4], [1,5], [2,6], [3,7]]; + + // Sparse drifting starfield; deterministic, independent of audio hardware. + let stars = if small { 8 } else { 20 }; + for i in 0..stars { + let phase = to_float(i); + let x = (phase * 37.71 + t * (0.3 + to_float(i % 3) * 0.2)) % to_float(w - 1); + let y = 1.0 + (phase * 13.37) % to_float(h - 3); + let light = 0.12 + treble * 0.16 * (0.5 + 0.5 * sin(t * 2.0 + phase)); + cmds.dot(x, y, ".", palette(t, 0.0, light), bg, w, h); + } + + // Three elliptical shock fronts. On a transient they brighten and + // spread; release of the beat envelope carries them farther outward. + if !small && drive > 0.04 { + for ring in 0..3 { + let phase = (t * 0.45 + to_float(ring) / 3.0) % 1.0; + let radius = 0.22 + phase * 0.55 + (1.0 - beat) * 0.18; + let rx = span * radius; + let ry = span * radius * (0.22 + mid * 0.10); + let left = to_int(center_x - rx); + let right = to_int(center_x + rx); + let top = []; let bottom = []; + for x in left..=right { + let nx = clamp((to_float(x) - center_x) / rx, -1.0, 1.0); + let dy = sqrt(1.0 - nx * nx) * ry; + top.push(to_int(center_y - dy + 0.5)); + bottom.push(to_int(center_y + dy + 0.5)); + } + let fg = palette(t + to_float(ring), beat, (1.0 - phase) * (0.12 + beat * 0.45 + bass * 0.12)); + for ys in [top, bottom] { + cmds.push(#{ op: "trace", x: left, ys: ys, ch: ".", line_ch: ".", + fg: fg, line_fg: fg, bg: bg }); + } + } + } + + // Particles launch from the eight corners with staggered lifetimes. + // Speed/age depend on time; audio changes reach and brightness instead + // of rescaling time and teleporting particles on each audio update. + if drive > 0.04 { + let particles = if small { 16 } else { 48 }; + for i in 0..particles { + let fi = to_float(i); + let age = (t * (0.27 + to_float(i % 5) * 0.025) + fi * 0.618034) % 1.0; + let angle = fi * 2.39996 + t * 0.16; + let dx = cos(angle); let dy = sin(angle); + let origin = points[i % 8]; + let travel = span * (0.35 + energy * 0.55 + beat * 0.8); + let distance = age * travel; + let light = sin(age * 3.14159) * (0.15 + drive * 0.85); + let fg = palette(t + fi * 0.13, beat, light); + let ch = if beat > 0.45 && i % 3 == 0 { "*" } else if treble > 0.35 { "+" } else { "." }; + if !small && i % 2 == 0 { + let tail = distance - span * 0.04; + cmds.dot(to_float(origin[0]) + dx * tail * 2.0, + to_float(origin[1]) + dy * tail, ".", palette(t, beat, light * 0.3), bg, w, h); + } + cmds.dot(to_float(origin[0]) + dx * distance * 2.0, + to_float(origin[1]) + dy * distance, ch, fg, bg, w, h); + } + } + + // Analytic motion echoes. These are recomputed poses, not frame history. + if !small && drive > 0.04 { + for echo in [2, 1] { + let lag = to_float(echo) * (0.14 + beat * 0.10); + let ghost = mesh(t - lag, energy, bass, mid, treble, beat, w, h); + let fg = palette(t + to_float(echo), 1.0 - beat, (0.08 + drive * 0.16) / to_float(echo)); + for e in edges { + let a = ghost[e[0]]; let b = ghost[e[1]]; + cmds.push(edge(a[0], a[1], b[0], b[1], fg, bg)); + } + } + } + + // A warm inner cage gives depth and a second pulse inside the main mesh. + if !small { + let inner = []; + let size = 0.35 + beat * 0.25; + for p in points { + inner.push([to_int(center_x + (to_float(p[0]) - center_x) * size + 0.5), + to_int(center_y + (to_float(p[1]) - center_y) * size + 0.5)]); + } + let fg = rgb(100.0 + beat * 155.0, 45.0 + energy * 75.0, 65.0 + treble * 70.0); + for e in edges { + let a = inner[e[0]]; let b = inner[e[1]]; + cmds.push(edge(a[0], a[1], b[0], b[1], fg, bg)); + } + } + + let ordered = []; + for e in edges { + let depth = (points[e[0]][2] + points[e[1]][2]) * 0.5; + let at = 0; + while at < ordered.len() && ordered[at][2] > depth { at += 1; } + ordered.insert(at, [e[0], e[1], depth]); + } + for e in ordered { + let a = points[e[0]]; let b = points[e[1]]; + let light = clamp(0.78 - e[2] * 0.14 + beat * 0.12, 0.3, 1.0); + cmds.push(edge(a[0], a[1], b[0], b[1], palette(t, beat, light), bg)); + } + // Sparks travel along edges; no more than twelve extra cells. + if treble > 0.08 || beat > 0.08 { + for i in 0..12 { + let e = edges[i]; let a = points[e[0]]; let b = points[e[1]]; + let phase = (t * 0.8 + to_float(i) * 0.137) % 1.0; + cmds.dot(to_float(a[0]) + to_float(b[0] - a[0]) * phase, + to_float(a[1]) + to_float(b[1] - a[1]) * phase, + "*", 0xffe8c0, bg, w, h); + } + } + for p in points { + if !small && beat > 0.45 { + let glow = palette(t, beat, beat * 0.45); + for offset in [[-1,0], [1,0], [0,-1], [0,1]] { + cmds.dot(to_float(p[0] + offset[0]), to_float(p[1] + offset[1]), "+", glow, bg, w, h); + } + } + cmds.push(#{ op: "cell", x: p[0], y: p[1], ch: "o", fg: 0xe8f6ff, bg: bg }); + } + if input.show_clock { + cmds.push(#{ op: "text", x: 1, y: 0, text: input.clock, fg: 0xa6cde0, bg: bg }); + } + if input.paused { + cmds.push(#{ op: "text", x: w - 7, y: 0, text: "paused", fg: 0xa6cde0, bg: bg }); + } + if w >= 16 { + cmds.push(#{ op: "text", x: 1, y: h - 1, text: "MORPHING CUBE", fg: 0x527b98, bg: bg }); + } + cmds +} diff --git a/src/visualizations/status/braille.rhai b/src/visualizations/status/braille.rhai new file mode 100644 index 0000000..13ba914 --- /dev/null +++ b/src/visualizations/status/braille.rhai @@ -0,0 +1,57 @@ +// name: Status braille histogram +// protocol: furumi-visualizer-v2 +// surface: status +// revision: 2 +// +// One-row waveform histogram. Input is decoded audio BEFORE output volume. +// The host freezes the last frame on pause, including custom scripts. +// Edit this file to customize it; only untouched bundled defaults upgrade. +// Each Braille character packs two independent four-dot vertical columns. +// "default" background retains the terminal's background color. + +fn clamp(value, low, high) { + if value < low { low } else if value > high { high } else { value } +} + +// Local RMS for one slice of the recent waveform. Method syntax avoids +// copying the complete sample array for every column. +fn level(index, columns, reference) { + let count = this.len(); + if count == 0 { return 0; } + let start = index * count / columns; + let end = (index + 1) * count / columns; + let square = 0.0; + let total = 0; + for i in start..end { + square += this[i] * this[i]; + total += 1; + } + let rms = if total > 0 { sqrt(square / to_float(total)) } + else { abs(this[start]) }; + // Remove the near-silent baseline and spread useful levels over 0..4. + // No additive bass/energy/beat floor: quiet columns really become empty. + let normalized = clamp((rms / reference - 0.12) / 0.72, 0.0, 1.0); + to_int(normalized * 4.0 + 0.5) +} + +fn render(input) { + let commands = [#{ op: "clear", bg: "default" }]; + if input.width <= 0 || input.height <= 0 { return commands; } + let samples = input.samples; + let square = 0.0; + for sample in samples { square += sample * sample; } + let rms = if samples.len() > 0 { sqrt(square / to_float(samples.len())) } else { 0.0 }; + // Adapt headroom to the current recording, with an absolute noise floor + // so silence/very quiet passages are never normalized into a full row. + let reference = if rms * 1.8 > 0.10 { rms * 1.8 } else { 0.10 }; + let dots = ["⠀⢀⢠⢰⢸", "⡀⣀⣠⣰⣸", "⡄⣄⣤⣴⣼", "⡆⣆⣦⣶⣾", "⡇⣇⣧⣷⣿"]; + let columns = input.width * 2; + for x in 0..input.width { + let left = samples.level(x * 2, columns, reference); + let right = samples.level(x * 2 + 1, columns, reference); + let glyph = dots[left].sub_string(right, 1); + commands.push(#{ op: "cell", x: x, y: 0, ch: glyph, + fg: 0x48c9c0, bg: "default" }); + } + commands +} diff --git a/src/visualizer.rs b/src/visualizer.rs index 9353e0f..ef0fefa 100644 --- a/src/visualizer.rs +++ b/src/visualizer.rs @@ -1,4 +1,4 @@ -//! Script-backed fullscreen visualizers. +//! Script-backed fullscreen and status-bar visualizers. //! //! Rust owns the audio tap, script loading, sandboxed execution limits and //! terminal drawing primitives. Visual math lives in `.rhai` files: every @@ -11,6 +11,9 @@ use std::time::{Instant, SystemTime}; use anyhow::{Context as _, Result}; use ratatui::Frame; +use ratatui::buffer::Buffer; + +pub mod status; use ratatui::layout::Rect; use ratatui::style::{Color, Style}; use ratatui::widgets::{Clear, Paragraph}; @@ -20,12 +23,12 @@ use serde::{Deserialize, Serialize}; use crate::app::state::AppState; const PRIMARY_SCRIPT_ID: &str = "scope_spectrum"; -const BUNDLE_VERSION: u32 = 5; struct BundledScript { id: &'static str, file_name: &'static str, display_name: &'static str, + version: u32, source: &'static str, } @@ -34,14 +37,23 @@ const BUNDLED_SCRIPTS: &[BundledScript] = &[ id: PRIMARY_SCRIPT_ID, file_name: "scope_spectrum.rhai", display_name: "Scope spectrum", + version: 5, source: include_str!("visualizations/scope_spectrum.rhai"), }, BundledScript { id: "pulsing_sphere", file_name: "pulsing_sphere.rhai", display_name: "Pulsing sphere", + version: 5, source: include_str!("visualizations/pulsing_sphere.rhai"), }, + BundledScript { + id: "morphing_cube", + file_name: "morphing_cube.rhai", + display_name: "Morphing cube", + version: 6, + source: include_str!("visualizations/morphing_cube.rhai"), + }, ]; #[derive(Debug, Clone)] @@ -114,6 +126,9 @@ impl VisualizerState { } pub fn load_library(&mut self) -> Result<()> { + if let Err(err) = status::ensure_script() { + tracing::warn!(%err, "status visualization initialization failed"); + } ensure_bundled_scripts()?; self.config = load_config().unwrap_or_else(|err| { tracing::warn!(%err, "visualization settings failed to load; using defaults"); @@ -284,7 +299,10 @@ pub fn draw(frame: &mut Frame, state: &AppState) { } fn input_map(area: Rect, state: &AppState) -> Map { - let features = features_from_state(state); + input_map_with_features(area, state, features_from_state(state, true)) +} + +fn input_map_with_features(area: Rect, state: &AppState, features: AudioFeatures) -> Map { let mut input = Map::new(); insert_int(&mut input, "width", i64::from(area.width)); insert_int(&mut input, "height", i64::from(area.height)); @@ -329,7 +347,7 @@ fn input_map(area: Rect, state: &AppState) -> Map { input } -fn features_from_state(state: &AppState) -> AudioFeatures { +fn features_from_state(state: &AppState, scale_output: bool) -> AudioFeatures { let elapsed_secs = state .visualizer .started_at @@ -355,12 +373,18 @@ fn features_from_state(state: &AppState) -> AudioFeatures { .unwrap_or(0.17); let analysis = &state.player.audio_analysis; let volume = f64::from(state.player.volume.min(100)) / 100.0; - let output_scale = if state.player.volume == 0 { + let output_scale = if !scale_output { + 1.0 + } else if state.player.volume == 0 { 0.0 } else { 0.35 + volume * 0.65 }; - let active_scale = if state.player.paused { 0.12 } else { 1.0 }; + let active_scale = if scale_output && state.player.paused { + 0.12 + } else { + 1.0 + }; let scale = output_scale * active_scale; AudioFeatures { @@ -373,7 +397,7 @@ fn features_from_state(state: &AppState) -> AudioFeatures { bass: (analysis.bass * scale).clamp(0.0, 1.0), mid: (analysis.mid * scale).clamp(0.0, 1.0), treble: (analysis.treble * scale).clamp(0.0, 1.0), - beat: if state.player.paused { + beat: if scale_output && state.player.paused { 0.0 } else { (analysis.beat * output_scale).clamp(0.0, 1.0) @@ -423,6 +447,10 @@ impl Default for ScriptRuntime { .set_max_string_size(1_000_000) .set_max_array_size(120_000) .set_max_map_size(1_000_000); + engine.on_print(|message| tracing::debug!(message, "visualizer script")); + engine.on_debug(|message, source, position| { + tracing::debug!(message, ?source, ?position, "visualizer script") + }); engine.disable_symbol("import"); engine.disable_symbol("export"); engine.register_fn("sin", |value: FLOAT| value.sin()); @@ -606,11 +634,15 @@ impl DrawCommand { } fn render_commands(frame: &mut Frame, area: Rect, commands: &[DrawCommand]) { + render_commands_to_buffer(frame.buffer_mut(), area, commands); +} + +fn render_commands_to_buffer(buffer: &mut Buffer, area: Rect, commands: &[DrawCommand]) { for command in commands { match command { - DrawCommand::Clear { bg } => fill_rect(frame, area, " ", Style::new().bg(*bg)), + DrawCommand::Clear { bg } => fill_rect(buffer, area, " ", Style::new().bg(*bg)), DrawCommand::Cell { x, y, ch, fg, bg } => { - write_cell(frame, area, *x, *y, ch, Style::new().fg(*fg).bg(*bg)); + write_cell(buffer, area, *x, *y, ch, Style::new().fg(*fg).bg(*bg)); } DrawCommand::HLine { x, @@ -621,8 +653,8 @@ fn render_commands(frame: &mut Frame, area: Rect, commands: &[DrawCommand]) { bg, } => { let style = Style::new().fg(*fg).bg(*bg); - for offset in 0..*w { - write_cell(frame, area, x.saturating_add(offset), *y, ch, style); + for offset in 0..(*w).min(area.width.saturating_sub(*x)) { + write_cell(buffer, area, x.saturating_add(offset), *y, ch, style); } } DrawCommand::VLine { @@ -634,8 +666,8 @@ fn render_commands(frame: &mut Frame, area: Rect, commands: &[DrawCommand]) { bg, } => { let style = Style::new().fg(*fg).bg(*bg); - for offset in 0..*h { - write_cell(frame, area, *x, y.saturating_add(offset), ch, style); + for offset in 0..(*h).min(area.height.saturating_sub(*y)) { + write_cell(buffer, area, *x, y.saturating_add(offset), ch, style); } } DrawCommand::Rect { @@ -648,10 +680,10 @@ fn render_commands(frame: &mut Frame, area: Rect, commands: &[DrawCommand]) { bg, } => { let style = Style::new().fg(*fg).bg(*bg); - for row in 0..*h { - for col in 0..*w { + for row in 0..(*h).min(area.height.saturating_sub(*y)) { + for col in 0..(*w).min(area.width.saturating_sub(*x)) { write_cell( - frame, + buffer, area, x.saturating_add(col), y.saturating_add(row), @@ -673,7 +705,12 @@ fn render_commands(frame: &mut Frame, area: Rect, commands: &[DrawCommand]) { let line_style = Style::new().fg(*line_fg).bg(*bg); let point_style = Style::new().fg(*fg).bg(*bg); let mut previous_y: Option = None; - for (index, y) in ys.iter().copied().enumerate() { + for (index, y) in ys + .iter() + .copied() + .take(usize::from(area.width.saturating_sub(*x))) + .enumerate() + { let Ok(offset) = u16::try_from(index) else { break; }; @@ -681,21 +718,25 @@ fn render_commands(frame: &mut Frame, area: Rect, commands: &[DrawCommand]) { if let Some(previous) = previous_y { let from = previous.min(y); let to = previous.max(y); - for y in from..=to { - write_cell(frame, area, x, y, line_ch, line_style); + for y in from..=to.min(area.height.saturating_sub(1)) { + write_cell(buffer, area, x, y, line_ch, line_style); } } - write_cell(frame, area, x, y, ch, point_style); + write_cell(buffer, area, x, y, ch, point_style); previous_y = Some(y); } } DrawCommand::Text { x, y, text, fg, bg } => { - for (offset, ch) in text.chars().enumerate() { + for (offset, ch) in text + .chars() + .take(usize::from(area.width.saturating_sub(*x))) + .enumerate() + { let Ok(offset) = u16::try_from(offset) else { break; }; write_cell( - frame, + buffer, area, x.saturating_add(offset), *y, @@ -708,24 +749,21 @@ fn render_commands(frame: &mut Frame, area: Rect, commands: &[DrawCommand]) { } } -fn fill_rect(frame: &mut Frame, area: Rect, symbol: &'static str, style: Style) { +fn fill_rect(buffer: &mut Buffer, area: Rect, symbol: &'static str, style: Style) { for y in area.y..area.y + area.height { for x in area.x..area.x + area.width { - if let Some(cell) = frame.buffer_mut().cell_mut((x, y)) { + if let Some(cell) = buffer.cell_mut((x, y)) { cell.set_symbol(symbol).set_style(style); } } } } -fn write_cell(frame: &mut Frame, area: Rect, x: u16, y: u16, symbol: &str, style: Style) { +fn write_cell(buffer: &mut Buffer, area: Rect, x: u16, y: u16, symbol: &str, style: Style) { if x >= area.width || y >= area.height { return; } - if let Some(cell) = frame - .buffer_mut() - .cell_mut((area.x.saturating_add(x), area.y.saturating_add(y))) - { + if let Some(cell) = buffer.cell_mut((area.x.saturating_add(x), area.y.saturating_add(y))) { cell.set_symbol(symbol).set_style(style); } } @@ -774,6 +812,9 @@ fn rgb_color(value: INT) -> Color { } fn parse_color(text: &str) -> Option { + if text == "default" { + return Some(Color::Reset); + } let hex = text.trim().trim_start_matches('#').trim_start_matches("0x"); let value = u32::from_str_radix(hex, 16).ok()?; Some(Color::Rgb( @@ -850,7 +891,7 @@ fn ensure_bundled_scripts() -> Result<()> { fn should_replace_bundled_script(existing: &str, script: &BundledScript) -> bool { let name_marker = format!("// name: {}", script.display_name); - let version_marker = format!("// bundle-version: {BUNDLE_VERSION}"); + let version_marker = format!("// bundle-version: {}", script.version); existing .lines() .take(3) @@ -918,9 +959,9 @@ mod tests { insert_int(&mut input, "analysis_sequence", 1); input.insert( "samples".into(), - (0..128) + (0..256) .map(|index| { - let sample = ((index as f64 / 128.0) * std::f64::consts::TAU).sin(); + let sample = ((index as f64 / 256.0) * std::f64::consts::TAU).sin(); Dynamic::from_float(sample as FLOAT) }) .collect::() @@ -991,4 +1032,284 @@ mod tests { scope, )); } + + fn cube_file() -> tempfile::NamedTempFile { + let file = tempfile::NamedTempFile::new().unwrap(); + std::fs::write( + file.path(), + include_str!("visualizations/morphing_cube.rhai"), + ) + .unwrap(); + file + } + + #[test] + fn cube_update_does_not_upgrade_other_presets() { + let cube = BUNDLED_SCRIPTS + .iter() + .find(|script| script.id == "morphing_cube") + .unwrap(); + let old_cube = cube + .source + .replacen("// bundle-version: 6", "// bundle-version: 5", 1); + assert!(should_replace_bundled_script(&old_cube, cube)); + for script in BUNDLED_SCRIPTS { + assert!(!should_replace_bundled_script(script.source, script)); + } + let custom = old_cube.replacen("// name: Morphing cube", "// name: My cube", 1); + assert!(!should_replace_bundled_script(&custom, cube)); + } + + #[test] + fn cube_music_adds_particles_echoes_and_a_larger_pulse() { + let file = cube_file(); + let mut runtime = ScriptRuntime::default(); + let mut input = test_input(); + for band in ["energy", "bass", "mid", "treble", "beat"] { + insert_float(&mut input, band, 0.0); + } + let quiet = runtime.render(file.path(), input.clone()).unwrap(); + for band in ["energy", "bass", "mid", "treble", "beat"] { + insert_float(&mut input, band, 0.8); + } + let loud = runtime.render(file.path(), input).unwrap(); + let effects = |commands: &[DrawCommand]| { + commands + .iter() + .filter(|command| matches!(command, DrawCommand::Cell { ch, .. } if ch != "o")) + .count() + }; + assert!( + effects(&loud) > effects(&quiet) + 30, + "music should visibly populate the scene" + ); + let lines = |commands: &[DrawCommand]| { + commands + .iter() + .filter(|command| { + matches!( + command, + DrawCommand::Trace { .. } | DrawCommand::VLine { .. } + ) + }) + .count() + }; + assert_eq!( + lines(&loud), + lines(&quiet) + 30, + "two echoes and three rings" + ); + let footprint = |commands: &[DrawCommand]| { + let vertices = cube_vertices(commands); + let xs: Vec<_> = vertices.iter().map(|p| p.0).collect(); + let ys: Vec<_> = vertices.iter().map(|p| p.1).collect(); + u32::from(xs.iter().max().unwrap() - xs.iter().min().unwrap()) + * u32::from(ys.iter().max().unwrap() - ys.iter().min().unwrap()) + }; + assert!( + footprint(&loud) > footprint(&quiet) * 2, + "pulse should be substantially larger" + ); + } + + fn cube_vertices(commands: &[DrawCommand]) -> Vec<(u16, u16)> { + commands + .iter() + .filter_map(|command| match command { + DrawCommand::Cell { x, y, ch, .. } if ch == "o" => Some((*x, *y)), + _ => None, + }) + .collect() + } + + #[test] + fn cube_rotates_and_each_audio_control_deforms_geometry() { + let file = cube_file(); + let mut runtime = ScriptRuntime::default(); + let mut input = test_input(); + insert_int(&mut input, "width", 160); + insert_int(&mut input, "height", 60); + for band in ["energy", "bass", "mid", "treble", "beat"] { + insert_float(&mut input, band, 0.0); + } + let quiet = cube_vertices(&runtime.render(file.path(), input.clone()).unwrap()); + assert_eq!(quiet.len(), 8); + for band in ["energy", "bass", "mid", "treble", "beat"] { + let mut loud = input.clone(); + insert_float(&mut loud, band, 1.0); + let deformed = cube_vertices(&runtime.render(file.path(), loud).unwrap()); + assert_ne!( + quiet, deformed, + "{band} should move vertices, not just colors" + ); + } + insert_float(&mut input, "time", 3.0); + let rotated = cube_vertices(&runtime.render(file.path(), input).unwrap()); + assert_ne!(quiet, rotated, "rotation should continue in silence"); + } + + #[test] + fn cube_stays_bounded_across_sizes_times_and_audio_extremes() { + let file = cube_file(); + let mut runtime = ScriptRuntime::default(); + // Much tighter than the production two-million-operation ceiling. + runtime.engine.set_max_operations(200_000); + for (width, height) in [ + (1, 1), + (11, 7), + (12, 8), + (24, 80), + (80, 24), + (160, 50), + (320, 100), + ] { + for level in [0.0, 0.5, 1.0] { + for tick in 0..12 { + let mut input = test_input(); + insert_int(&mut input, "width", width); + insert_int(&mut input, "height", height); + insert_float(&mut input, "time", f64::from(tick) * 1.37); + for band in ["energy", "bass", "mid", "treble", "beat"] { + insert_float(&mut input, band, level); + } + let commands = runtime.render(file.path(), input).unwrap(); + assert!(commands.len() <= 220); + if width < 12 || height < 8 { + assert_eq!(commands.len(), 1); + continue; + } + assert_eq!(cube_vertices(&commands).len(), 8); + let mut edges = 0; + for command in &commands { + match command { + DrawCommand::Trace { x, ys, .. } => { + edges += 1; + assert!(usize::from(*x) + ys.len() <= width as usize); + assert!(ys.iter().all(|y| i64::from(*y) < height)); + } + DrawCommand::VLine { x, y, h, .. } => { + edges += 1; + assert!(i64::from(*x) < width); + assert!(i64::from(*y) + i64::from(*h) <= height); + } + DrawCommand::Cell { x, y, .. } => { + assert!(i64::from(*x) < width && i64::from(*y) < height); + } + _ => {} + } + } + assert!((12..=54).contains(&edges)); + } + } + } + } + + #[test] + fn cube_edges_handle_reversed_vertical_and_collapsed_projections() { + let runtime = ScriptRuntime::default(); + let ast = runtime + .engine + .compile(include_str!("visualizations/morphing_cube.rhai")) + .unwrap(); + for (ax, ay, bx, by) in [ + (2_i64, 3_i64, 8_i64, 9_i64), + (8, 9, 2, 3), + (2, 9, 8, 3), + (8, 3, 2, 9), + (4, 9, 4, 3), + (4, 3, 4, 3), + ] { + let output = runtime + .engine + .call_fn::( + &mut Scope::new(), + &ast, + "edge", + (ax, ay, bx, by, 0xffffff_i64, 0_i64), + ) + .unwrap(); + match DrawCommand::from_dynamic(output).unwrap() { + DrawCommand::Trace { x, ys, .. } => { + assert_eq!(i64::from(x), ax.min(bx)); + assert_eq!(ys.len(), (ax - bx).unsigned_abs() as usize + 1); + let (left_y, right_y) = if ax < bx { (ay, by) } else { (by, ay) }; + assert_eq!(i64::from(ys[0]), left_y); + assert_eq!(i64::from(*ys.last().unwrap()), right_y); + } + DrawCommand::VLine { x, y, h, .. } => { + assert_eq!(i64::from(x), ax); + assert_eq!(i64::from(y), ay.min(by)); + assert_eq!(u64::from(h), (ay - by).unsigned_abs() + 1); + } + other => panic!("unexpected edge: {other:?}"), + } + } + } + + /// Explicit, reproducible CPU measurement; no audio hardware or user config. + /// TestBackend includes buffer drawing/diff, but not terminal I/O/emulation. + #[test] + #[ignore = "manual benchmark: cargo test --release benchmark_visualizers -- --ignored --nocapture"] + fn benchmark_visualizers() { + use ratatui::{Terminal, backend::TestBackend}; + + for script in BUNDLED_SCRIPTS { + let file = tempfile::NamedTempFile::new().unwrap(); + std::fs::write(file.path(), script.source).unwrap(); + let mut runtime = ScriptRuntime::default(); + for (width, height) in [(80_u16, 24_u16), (160, 50), (240, 80)] { + let mut terminal = Terminal::new(TestBackend::new(width, height)).unwrap(); + let mut script_times = Vec::new(); + let mut frame_times = Vec::new(); + let mut max_commands = 0; + for tick in 0..230 { + let mut input = test_input(); + insert_int(&mut input, "width", i64::from(width)); + insert_int(&mut input, "height", i64::from(height)); + let time = f64::from(tick) * 0.05; + insert_float(&mut input, "time", time); + for (i, band) in ["energy", "bass", "mid", "treble", "beat"] + .iter() + .enumerate() + { + insert_float(&mut input, band, (time * (i + 1) as f64).sin() * 0.5 + 0.5); + } + let started = Instant::now(); + let commands = runtime.render(file.path(), input).unwrap(); + let script_elapsed = started.elapsed(); + terminal + .draw(|frame| render_commands(frame, frame.area(), &commands)) + .unwrap(); + if tick >= 30 { + script_times.push(script_elapsed.as_secs_f64() * 1000.0); + frame_times.push(started.elapsed().as_secs_f64() * 1000.0); + max_commands = max_commands.max(commands.len()); + } + } + script_times.sort_by(f64::total_cmp); + frame_times.sort_by(f64::total_cmp); + println!( + "{} {width}x{height}: script p95={:.3}ms; frame median={:.3}ms p95={:.3}ms max={:.3}ms; commands<={max_commands}", + script.id, + script_times[189], + frame_times[99], + frame_times[189], + frame_times[199] + ); + if script.id == "morphing_cube" && width == 80 { + for row in terminal + .backend() + .buffer() + .content + .chunks(usize::from(width)) + { + println!( + "{}", + row.iter().map(|cell| cell.symbol()).collect::() + ); + } + } + } + } + } } diff --git a/src/visualizer/fixtures/status_braille_v1.rhai b/src/visualizer/fixtures/status_braille_v1.rhai new file mode 100644 index 0000000..504c5fb --- /dev/null +++ b/src/visualizer/fixtures/status_braille_v1.rhai @@ -0,0 +1,57 @@ +// name: Status braille histogram +// protocol: furumi-visualizer-v2 +// surface: status +// +// Always-on, one-row visualization. Edit this file to customize it; saved +// changes reload during playback. The host never overwrites an existing file. +// Same render(input) and draw commands as fullscreen scripts; height is 1. +// Audio bands and waveform amplitudes drive the bars (not a full FFT). +// Each Braille character packs two independent four-dot vertical columns. +// "default" background retains the terminal's background color. + +// A method reads the waveform through `this`, avoiding an array copy for +// every column in this continuously running visualization. +fn level(index, columns, band, energy, beat) { + let wave = 0.0; + let count = this.len(); + if count > 0 { + let start = index * count / columns; + let end = (index + 1) * count / columns; + let total = 0; + for i in start..end { + wave += abs(this[i]); + total += 1; + } + if total > 0 { wave /= to_float(total); } + else { wave = abs(this[start]); } + } + let value = band * 0.55 + wave * 0.8 + energy * 0.12 + beat * 0.18; + if value <= 0.01 { 0 } + else if value < 0.20 { 1 } + else if value < 0.40 { 2 } + else if value < 0.65 { 3 } + else { 4 } +} + +fn render(input) { + let commands = [#{ op: "clear", bg: "default" }]; + if input.width <= 0 || input.height <= 0 || input.paused { return commands; } + // Lookup table indexed by left/right bar heights, from the bottom up. + let dots = ["⠀⢀⢠⢰⢸", "⡀⣀⣠⣰⣸", "⡄⣄⣤⣴⣼", "⡆⣆⣦⣶⣾", "⡇⣇⣧⣷⣿"]; + let columns = input.width * 2; + let samples = input.samples; + for x in 0..input.width { + let levels = []; + for side in 0..2 { + let index = x * 2 + side; + let phase = to_float(index) / to_float(columns); + let band = if phase < 0.33 { input.bass } + else if phase < 0.67 { input.mid } else { input.treble }; + levels.push(samples.level(index, columns, band, input.energy, input.beat)); + } + let glyph = dots[levels[0]].sub_string(levels[1], 1); + commands.push(#{ op: "cell", x: x, y: 0, ch: glyph, + fg: 0x48c9c0, bg: "default" }); + } + commands +} diff --git a/src/visualizer/status.rs b/src/visualizer/status.rs new file mode 100644 index 0000000..f678bb9 --- /dev/null +++ b/src/visualizer/status.rs @@ -0,0 +1,583 @@ +//! One-row surface: blocking preparation runs off the UI thread; views copy +//! only the prepared buffer. Uses the fullscreen engine and drawing commands. + +use std::io::Write; +use std::path::{Path, PathBuf}; +use std::sync::{Arc, Mutex}; +use std::time::Instant; + +use ratatui::{ + Frame, + buffer::Buffer, + layout::Rect, + style::{Color, Style}, + widgets::Paragraph, +}; +use tokio::sync::mpsc; +use unicode_width::UnicodeWidthStr; + +use super::{ + ScriptRuntime, features_from_state, input_map_with_features, render_commands_to_buffer, +}; +use crate::app::{event::AppEvent, state::AppState}; + +const SOURCE: &str = include_str!("../visualizations/status/braille.rhai"); +const LEGACY_SOURCE: &str = include_str!("fixtures/status_braille_v1.rhai"); + +pub fn script_path() -> anyhow::Result { + Ok(super::visualizations_dir()? + .join("status") + .join("braille.rhai")) +} + +pub(super) fn ensure_script() -> anyhow::Result<()> { + install_script_at(&script_path()?) +} + +fn install_script_at(path: &Path) -> anyhow::Result<()> { + ensure_script_at(path)?; + // Upgrade only a byte-for-byte stock script, never a user's edited one. + if std::fs::metadata(path)?.len() == LEGACY_SOURCE.len() as u64 + && std::fs::read(path)? == LEGACY_SOURCE.as_bytes() + { + let mut replacement = + tempfile::NamedTempFile::new_in(path.parent().unwrap_or(Path::new(".")))?; + replacement.write_all(SOURCE.as_bytes())?; + replacement.as_file().sync_all()?; + if std::fs::read(path)? == LEGACY_SOURCE.as_bytes() { + replacement.persist(path)?; + } + } + Ok(()) +} + +fn ensure_script_at(path: &Path) -> anyhow::Result<()> { + if let Some(parent) = path.parent() { + std::fs::create_dir_all(parent)?; + } + match std::fs::OpenOptions::new() + .write(true) + .create_new(true) + .open(path) + { + Ok(mut file) => file.write_all(SOURCE.as_bytes())?, + Err(err) if err.kind() == std::io::ErrorKind::AlreadyExists => {} + Err(err) => return Err(err.into()), + } + Ok(()) +} + +pub fn visible(state: &AppState) -> bool { + state.player.playing && state.player.current.is_some() && state.device_playback.is_audio_owner() +} + +pub fn playing(state: &AppState) -> bool { + visible(state) && !state.player.paused +} + +fn source_input(width: u16, state: &AppState, elapsed: f64) -> rhai::Map { + // AnalyzedSource taps decoded audio before rodio's output volume. Keep + // those source levels intact; input.volume remains available as metadata. + let mut features = features_from_state(state, false); + features.elapsed_secs = elapsed; + input_map_with_features(Rect::new(0, 0, width, 1), state, features) +} + +#[derive(Debug, Default)] +pub struct State { + target: Option<(u16, String)>, + generation: u64, + frame: Option, + error: Option, + paused: bool, +} + +impl State { + /// Invalidates in-flight results. A resize keeps the last frame until a + /// replacement arrives, including when playback is paused. + pub fn set_target(&mut self, target: Option<(u16, String)>) { + if self.target != target { + let same_track = self + .target + .as_ref() + .zip(target.as_ref()) + .is_some_and(|(old, new)| old.1 == new.1); + self.target = target; + self.generation = self.generation.wrapping_add(1); + if !same_track { + self.frame = None; + } + self.error = None; + } + } + + pub fn set_paused(&mut self, paused: bool) { + if self.paused != paused { + self.paused = paused; + self.generation = self.generation.wrapping_add(1); + } + } + + pub fn apply(&mut self, ready: Ready) { + if ready.generation != self.generation || self.target.is_none() || self.paused { + return; + } + match ready.result { + Ok(frame) => { + self.frame = Some(frame); + self.error = None; + } + Err(error) => { + if self.error.as_ref() != Some(&error) { + tracing::warn!(%error, "status visualization failed"); + } + self.frame = None; + self.error = Some(error); + } + } + } + + pub fn draw(&self, frame: &mut Frame, area: Rect) { + if area.is_empty() { + return; + } + if let Some(buffer) = &self.frame { + if buffer.area.width == 0 { + return; + } + for x in 0..area.width { + let source_x = + usize::from(x) * usize::from(buffer.area.width) / usize::from(area.width); + if let Some(target) = frame.buffer_mut().cell_mut((area.x + x, area.y)) { + *target = buffer.content[source_x].clone(); + } + } + } else if let Some(error) = &self.error { + frame.render_widget( + Paragraph::new(format!("viz: {error}")).style(Style::new().fg(Color::Red)), + area, + ); + } + } +} + +#[derive(Debug)] +pub struct Ready { + generation: u64, + result: Result, +} + +/// One in-flight job at most: slow custom scripts drop ticks, never queue +/// frames or block input. AST caches are independent of fullscreen selection. +pub struct Renderer { + runtime: Arc>, + started: Instant, + pub busy: bool, +} + +impl Default for Renderer { + fn default() -> Self { + let mut runtime = ScriptRuntime::default(); + runtime + .engine + .set_max_operations(200_000) + .set_max_array_size(8192) + .set_max_map_size(4096) + .set_max_string_size(32_768); + Self { + runtime: Arc::new(Mutex::new(runtime)), + started: Instant::now(), + busy: false, + } + } +} + +impl Renderer { + pub fn request(&mut self, state: &AppState, tx: mpsc::UnboundedSender) { + let Some((width, _)) = &state.status_visualizer.target else { + return; + }; + if self.busy || !playing(state) || state.visualizer.active { + return; + } + self.busy = true; + let width = *width; + let generation = state.status_visualizer.generation; + let input = source_input(width, state, self.started.elapsed().as_secs_f64()); + let runtime = Arc::clone(&self.runtime); + tokio::spawn(async move { + let result = tokio::task::spawn_blocking(move || { + let path = script_path().map_err(|e| e.to_string())?; + let mut runtime = runtime + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner); + if runtime.cached_path.is_none() { + // Retry initialization after a transient startup error. + install_script_at(&path).map_err(|e| e.to_string())?; + } + prepare(&mut runtime, &path, input, width) + }) + .await + .unwrap_or_else(|err| Err(err.to_string())); + let _ = tx.send(AppEvent::StatusVisualizationReady(Ready { + generation, + result, + })); + }); + } +} + +fn prepare( + runtime: &mut ScriptRuntime, + path: &Path, + input: rhai::Map, + width: u16, +) -> Result { + if std::fs::metadata(path).map_err(|e| e.to_string())?.len() > 65_536 { + return Err("status script exceeds 64 KiB".into()); + } + let commands = runtime.render(path, input)?; + if commands.len() > 4096 { + return Err("too many status drawing commands".into()); + } + let area = Rect::new(0, 0, width, 1); + let mut buffer = Buffer::empty(area); + render_commands_to_buffer(&mut buffer, area, &commands); + // A user-supplied cell string must never spill into neighboring UI areas. + for cell in &mut buffer.content { + if cell.symbol().width() != 1 || cell.symbol().chars().any(char::is_control) { + cell.set_symbol(" "); + } + } + Ok(buffer) +} + +#[cfg(test)] +mod tests { + use super::super::insert_float; + use super::*; + use ratatui::{Terminal, backend::TestBackend}; + use rhai::{Array, Dynamic}; + + fn input(width: u16, level: f64) -> rhai::Map { + let mut input = source_input(width, &AppState::default(), 0.0); + for band in ["energy", "bass", "mid", "treble", "beat"] { + insert_float(&mut input, band, level); + } + input.insert( + "samples".into(), + (0..256) + .map(|index| { + Dynamic::from_float(level * (index as f64 * std::f64::consts::TAU / 64.0).sin()) + }) + .collect::() + .into(), + ); + input + } + + #[test] + fn histogram_uses_braille_and_real_levels_in_one_row() { + let dir = tempfile::tempdir().unwrap(); + let path = dir.path().join("status/braille.rhai"); + ensure_script_at(&path).unwrap(); + let renderer = Renderer::default(); + let mut runtime = renderer.runtime.lock().unwrap(); + for width in [0, 1, 8, 60, 200] { + let quiet = prepare(&mut runtime, &path, input(width, 0.0), width).unwrap(); + let loud = prepare(&mut runtime, &path, input(width, 1.0), width).unwrap(); + assert_eq!(loud.area, Rect::new(0, 0, width, 1)); + assert!(quiet.content.iter().all(|cell| cell.symbol() == "⠀")); + assert!(loud.content.iter().all(|cell| { + cell.symbol() + .chars() + .all(|ch| ('\u{2800}'..='\u{28ff}').contains(&ch)) + && cell.bg == Color::Reset + })); + if width > 0 { + assert_ne!(loud, quiet); + } + let mut paused = input(width, 1.0); + paused.insert("paused".into(), true.into()); + assert_eq!(prepare(&mut runtime, &path, paused, width).unwrap(), loud); + } + } + + #[test] + fn existing_user_script_survives_and_hot_reload_recovers_from_errors() { + let file = tempfile::NamedTempFile::new().unwrap(); + let path = file.path(); + let mut runtime = ScriptRuntime::default(); + for (revision, symbol) in [(1, "A"), (2, "B"), (3, "bad"), (4, "C")] { + let source = if symbol == "bad" { + "fn render(".into() + } else { + format!( + "fn render(input) {{ [#{{ op: \"text\", x: 0, y: 0, text: \"{symbol}\" }}] }}" + ) + }; + std::fs::write(path, &source).unwrap(); + file.as_file() + .set_times(std::fs::FileTimes::new().set_modified( + std::time::UNIX_EPOCH + + std::time::Duration::from_secs(1_700_000_000 + revision), + )) + .unwrap(); + install_script_at(path).unwrap(); + assert_eq!(std::fs::read_to_string(path).unwrap(), source); + let frame = prepare(&mut runtime, path, input(8, 0.0), 8); + if symbol == "bad" { + assert!(frame.is_err()); + } else { + assert_eq!(frame.unwrap().content[0].symbol(), symbol); + } + } + } + + #[test] + fn status_commands_are_clipped_and_cannot_spill_into_the_ui() { + let file = tempfile::NamedTempFile::new().unwrap(); + std::fs::write( + file.path(), + r##"fn render(input) { [ + #{ op: "rect", x: 0, y: 0, w: 65535, h: 65535, ch: "#" }, + #{ op: "text", x: 0, y: 1, text: "outside" }, + #{ op: "trace", x: 6, ys: [65535, 0, 65535], ch: "*" }, + #{ op: "cell", x: 0, y: 0, ch: "界" }, + #{ op: "cell", x: 1, y: 0, ch: "\n" }, + #{ op: "cell", x: 2, y: 0, ch: "too long" } + ] }"##, + ) + .unwrap(); + let buffer = prepare(&mut ScriptRuntime::default(), file.path(), input(8, 0.0), 8).unwrap(); + assert!(buffer.content[..3].iter().all(|cell| cell.symbol() == " ")); + let state = State { + frame: Some(buffer), + ..State::default() + }; + let mut terminal = Terminal::new(TestBackend::new(20, 4)).unwrap(); + terminal + .draw(|frame| { + for cell in &mut frame.buffer_mut().content { + cell.set_symbol("x"); + } + state.draw(frame, Rect::new(11, 3, 8, 1)); + }) + .unwrap(); + let buffer = terminal.backend().buffer(); + for y in 0..4 { + for x in 0..20 { + if y != 3 || !(11..19).contains(&x) { + assert_eq!(buffer[(x, y)].symbol(), "x"); + } + } + } + } + + #[test] + fn stale_frames_are_discarded_after_resize_track_change_or_stop() { + let mut state = State::default(); + state.set_target(Some((8, "track-a".into()))); + let generation = state.generation; + state.apply(Ready { + generation, + result: Ok(Buffer::empty(Rect::new(0, 0, 8, 1))), + }); + assert!(state.frame.is_some()); + for target in [ + Some((12, "track-a".into())), + Some((12, "track-b".into())), + None, + ] { + state.set_target(target); + let previous_frame = state.frame.clone(); + state.apply(Ready { + generation, + result: Ok(Buffer::empty(Rect::new(0, 0, 8, 1))), + }); + assert_eq!(state.frame, previous_frame); + } + assert!(state.frame.is_none()); + } + + #[test] + fn pause_freezes_the_last_frame_and_rejects_in_flight_work() { + let mut state = State::default(); + state.set_target(Some((8, "track".into()))); + let mut buffer = Buffer::empty(Rect::new(0, 0, 8, 1)); + for cell in &mut buffer.content { + cell.set_symbol("⣤"); + } + let generation = state.generation; + state.apply(Ready { + generation, + result: Ok(buffer.clone()), + }); + state.set_paused(true); + state.apply(Ready { + generation, + result: Err("late error".into()), + }); + state.apply(Ready { + generation: state.generation, + result: Ok(Buffer::empty(buffer.area)), + }); + assert_eq!(state.frame.as_ref(), Some(&buffer)); + // A paused resize adapts the frozen row instead of erasing it. + state.set_target(Some((12, "track".into()))); + let mut terminal = Terminal::new(TestBackend::new(12, 1)).unwrap(); + terminal + .draw(|frame| state.draw(frame, frame.area())) + .unwrap(); + assert!( + terminal + .backend() + .buffer() + .content + .iter() + .all(|cell| cell.symbol() == "⣤") + ); + let paused_generation = state.generation; + state.set_paused(false); + state.apply(Ready { + generation: paused_generation, + result: Err("stale pause".into()), + }); + assert_eq!(state.frame.as_ref(), Some(&buffer)); + state.apply(Ready { + generation: state.generation, + result: Ok(Buffer::empty(Rect::new(0, 0, 12, 1))), + }); + assert_ne!(state.frame.as_ref(), Some(&buffer)); + state.set_target(None); + assert!(state.frame.is_none()); + } + + #[test] + fn source_audio_input_is_independent_of_output_volume_and_pause() { + let file = tempfile::NamedTempFile::new().unwrap(); + std::fs::write(file.path(), SOURCE).unwrap(); + let mut state = AppState::default(); + state.player.audio_analysis = crate::player::AudioAnalysisSnapshot { + energy: 0.8, + bass: 0.9, + mid: 0.6, + treble: 0.3, + beat: 0.5, + scope: (0..256).map(|i| (i as f64 * 0.13).sin() * 0.7).collect(), + ..Default::default() + }; + let mut runtime = ScriptRuntime::default(); + let expected = + prepare(&mut runtime, file.path(), source_input(64, &state, 1.0), 64).unwrap(); + for volume in [0, 1, 25, 80, 100] { + for paused in [false, true] { + state.player.volume = volume; + state.player.paused = paused; + let map = source_input(64, &state, 1.0); + for (key, level) in [ + ("energy", 0.8), + ("bass", 0.9), + ("mid", 0.6), + ("treble", 0.3), + ("beat", 0.5), + ] { + assert_eq!(map[key].as_float().unwrap(), level); + } + assert_eq!(map["volume"].as_float().unwrap(), f64::from(volume) / 100.0); + assert_eq!( + prepare(&mut runtime, file.path(), map, 64).unwrap(), + expected + ); + } + } + } + + #[test] + fn loud_recordings_use_multiple_heights_instead_of_a_solid_row() { + let file = tempfile::NamedTempFile::new().unwrap(); + let mut runtime = ScriptRuntime::default(); + std::fs::write(file.path(), LEGACY_SOURCE).unwrap(); + let old = prepare(&mut runtime, file.path(), input(64, 1.0), 64).unwrap(); + assert!(old.content.iter().all(|cell| cell.symbol() == "⣿")); + install_script_at(file.path()).unwrap(); + // A fresh runtime also models a restart installing the new default. + let mut runtime = ScriptRuntime::default(); + let new = prepare(&mut runtime, file.path(), input(64, 1.0), 64).unwrap(); + let symbols: std::collections::HashSet<_> = + new.content.iter().map(|cell| cell.symbol()).collect(); + assert!(symbols.len() >= 4, "{symbols:?}"); + assert!( + new.content + .iter() + .filter(|cell| cell.symbol() == "⣿") + .count() + < 32 + ); + assert!(new.content.iter().any(|cell| cell.symbol() == "⠀")); + // Compressed band/beat values alone must not create a filled baseline. + let mut silence = input(64, 1.0); + silence.insert( + "samples".into(), + (0..256) + .map(|_| Dynamic::from_float(0.001)) + .collect::() + .into(), + ); + let silent = prepare(&mut runtime, file.path(), silence, 64).unwrap(); + assert!(silent.content.iter().all(|cell| cell.symbol() == "⠀")); + } + + #[test] + fn only_the_untouched_previous_default_is_upgraded() { + let file = tempfile::NamedTempFile::new().unwrap(); + std::fs::write(file.path(), LEGACY_SOURCE).unwrap(); + install_script_at(file.path()).unwrap(); + assert_eq!(std::fs::read_to_string(file.path()).unwrap(), SOURCE); + install_script_at(file.path()).unwrap(); + assert_eq!(std::fs::read_to_string(file.path()).unwrap(), SOURCE); + for stock in [LEGACY_SOURCE, SOURCE] { + let custom = format!("{stock}\n// user customization\n"); + std::fs::write(file.path(), &custom).unwrap(); + install_script_at(file.path()).unwrap(); + assert_eq!(std::fs::read_to_string(file.path()).unwrap(), custom); + } + } + + #[test] + fn status_script_infinite_loop_hits_the_operation_limit() { + let file = tempfile::NamedTempFile::new().unwrap(); + std::fs::write(file.path(), "fn render(input) { loop {} [] }").unwrap(); + let renderer = Renderer::default(); + let mut runtime = renderer.runtime.lock().unwrap(); + let err = prepare(&mut runtime, file.path(), input(8, 0.0), 8).unwrap_err(); + assert!(err.contains("operations"), "{err}"); + } + + #[test] + #[ignore = "manual benchmark: cargo test --release benchmark_status_visualizer -- --ignored --nocapture"] + fn benchmark_status_visualizer() { + let file = tempfile::NamedTempFile::new().unwrap(); + std::fs::write(file.path(), SOURCE).unwrap(); + let renderer = Renderer::default(); + let mut runtime = renderer.runtime.lock().unwrap(); + for width in [32, 64, 128] { + let mut times = Vec::new(); + for tick in 0..230 { + let level = (f64::from(tick) * 0.13).sin() * 0.5 + 0.5; + let input = input(width, level); + let start = Instant::now(); + let frame = prepare(&mut runtime, file.path(), input, width).unwrap(); + std::hint::black_box(frame); + if tick >= 30 { + times.push(start.elapsed().as_secs_f64() * 1000.0); + } + } + times.sort_by(f64::total_cmp); + println!( + "status {width}x1: median={:.3}ms p95={:.3}ms max={:.3}ms", + times[99], times[189], times[199] + ); + } + } +}