Web: default lower volume with ArrowUp/Down control; tempo on ArrowLeft/Right; Start overlay shows key map; remove 'h' help toggle. Native: master volume with ArrowUp/Down (+/=, NumpadAdd/Subtract). Update README to reflect controls.

rgilks · rgilks · commit b526ebddf4a4 · 2025-08-10T08:48:55.000+01:00
diff --git a/README.md b/README.md
@@ -4,15 +4,15 @@
 
 ### Project status
 
-- Web front-end (WASM) is running with:
+ - Web front-end (WASM) is running with:
   - 3 voices, spatial audio (Web Audio + PannerNode)
   - Lush ambient effects: global Convolver reverb and dark feedback Delay bus with per-voice sends and a master bus
   - Mouse-driven FX: corner-based saturation (clean ↔ fizz) and opposite-corner delay emphasis; visuals have inertial swirl motion and click ripples
   - Note-driven visuals use attack/release smoothing for organic response (no abrupt jumps)
   - Start overlay to initialize audio (Click Start; canvas-click fallback)
   - Drag voices in XZ plane; click to mute, Shift+Click reseed, Alt+Click solo
-- Keyboard: R (reseed all), Space (pause), + / - (tempo)
-  - Starts muted by default; press M to unmute the master bus
+ - Keyboard: R (new sequence), Space (pause/resume), ArrowLeft/Right (tempo), ArrowUp/Down (volume)
+  - Starts at a lower default volume; use ArrowUp to raise or ArrowDown to lower
   - Dynamic hint shows current BPM, paused, and muted state
   - Rich visuals: instanced voice markers with emissive pulses, ambient waves background, post bloom/tonemap/vignette; optional analyser-driven spectrum dots
 - Native front-end renders and plays synthesized audio; parity improving:
@@ -34,7 +34,7 @@
 Notes:
 
 - WebGL fallback is intentionally avoided; WebGPU is required.
-- If audio does not start, click the Start overlay and press M to unmute the master bus.
+ - If audio does not start, click the Start overlay.
 
 ### Run (Web)
 
@@ -45,8 +45,8 @@ Notes:
 
 Quick controls (browser):
 
-- R: reseed all • Space: pause/resume • +/-: tempo • M: master mute
-- Click a voice to mute; Alt+Click to solo; Shift+Click to reseed a voice; drag to move in XZ
+- R: new sequence • Space: pause/resume • ArrowLeft/Right: tempo • ArrowUp/Down: volume
+- Click canvas: play a note; mouse position affects sound
 
 ### Pre-commit Check
 
@@ -66,9 +66,8 @@ This repo is configured to deploy via Cloudflare Workers; headers (COOP/COEP/COR
 Controls in browser:
 
 - Click Start to initialize audio (canvas click also works)
-- Drag a circle to move a voice in XZ plane (updates spatialization)
-- Click a voice: mute; Shift+Click: reseed; Alt+Click: solo
-- Keys: R (reseed all), Space (pause/resume), + / - (tempo), M (master mute)
+- Click canvas: play a note; mouse position affects sound
+- Keys: R (new sequence), Space (pause/resume), ArrowLeft/Right (tempo), ArrowUp/Down (volume)
 - Mouse position maps to master saturation and delay; moving the pointer leaves a “water-like” trailing swirl in visuals
 
 Headless test:
diff --git a/crates/app-native/src/main.rs b/crates/app-native/src/main.rs
@@ -2,6 +2,7 @@ use std::sync::{Arc, Mutex};
 use std::thread;
 use std::time::{Duration, Instant};
 use wgpu::util::DeviceExt;
+use winit::keyboard::{KeyCode, PhysicalKey};
 use winit::{event::*, event_loop::EventLoop, window::WindowBuilder};
 
 use app_core::{
@@ -416,7 +417,8 @@ fn main() {
     )));
 
     // Start native audio output (synth driven by MusicEngine)
-    let _audio_stream = start_audio_engine(Arc::clone(&shared_state), Arc::clone(&engine));
+    let (_audio_stream, audio_state) =
+        start_audio_engine(Arc::clone(&shared_state), Arc::clone(&engine)).expect("audio engine");
 
     let event_loop = EventLoop::new().expect("event loop");
     let window = WindowBuilder::new()
@@ -447,6 +449,43 @@ fn main() {
                 event: WindowEvent::CloseRequested,
                 ..
             } => elwt.exit(),
+            Event::WindowEvent {
+                event:
+                    WindowEvent::KeyboardInput {
+                        event:
+                            KeyEvent {
+                                state: ElementState::Pressed,
+                                repeat: false,
+                                physical_key: PhysicalKey::Code(code),
+                                ..
+                            },
+                        ..
+                    },
+                ..
+            } => {
+                let mut vol_changed = false;
+                {
+                    let mut st = audio_state.lock().unwrap();
+                    let step = 0.05f32;
+                    match code {
+                        KeyCode::ArrowUp | KeyCode::Equal | KeyCode::NumpadAdd => {
+                            st.master_volume = (st.master_volume + step).clamp(0.0, 1.0);
+                            vol_changed = true;
+                        }
+                        KeyCode::ArrowDown | KeyCode::Minus | KeyCode::NumpadSubtract => {
+                            st.master_volume = (st.master_volume - step).clamp(0.0, 1.0);
+                            vol_changed = true;
+                        }
+                        _ => {}
+                    }
+                }
+                if vol_changed {
+                    // Optionally log new volume for visibility
+                    if let Ok(st) = audio_state.lock() {
+                        log::info!("[keys] volume={:.2}", st.master_volume);
+                    }
+                }
+            }
             Event::WindowEvent {
                 event: WindowEvent::CursorMoved { position, .. },
                 ..
@@ -556,6 +595,8 @@ struct ActiveOscillator {
 struct AudioState {
     sample_rate: f32,
     oscillators: Vec<ActiveOscillator>,
+    // Master output volume scalar (0.0..=1.0). Applied after saturation.
+    master_volume: f32,
 }
 
 fn compute_equal_power_gains(pos_x_engine: f32) -> (f32, f32) {
@@ -569,7 +610,7 @@ fn compute_equal_power_gains(pos_x_engine: f32) -> (f32, f32) {
 fn start_audio_engine(
     shared_vis: Arc<Mutex<VisState>>,
     shared_engine: Arc<Mutex<MusicEngine>>,
-) -> Option<cpal::Stream> {
+) -> Option<(cpal::Stream, Arc<Mutex<AudioState>>)> {
     let host = cpal::default_host();
     let device = host.default_output_device()?;
     let config = device.default_output_config().ok()?;
@@ -579,6 +620,7 @@ fn start_audio_engine(
     let state = Arc::new(Mutex::new(AudioState {
         sample_rate,
         oscillators: Vec::new(),
+        master_volume: 0.5, // start at half loudness
     }));
 
     // Scheduler thread producing notes using MusicEngine
@@ -691,7 +733,7 @@ fn start_audio_engine(
     };
 
     stream.play().ok()?;
-    Some(stream)
+    Some((stream, state))
 }
 
 fn render_wave_sample(phase: f32, wave: WaveKind) -> f32 {
@@ -784,11 +826,14 @@ fn build_stream_f32(
         config,
         move |data: &mut [f32], _| {
             let mut guard = state.lock().unwrap();
+            let vol = guard.master_volume.clamp(0.0, 1.0);
             let oscillators = &mut guard.oscillators;
             let mut frame = 0usize;
             while frame < data.len() {
                 let (l_raw, r_raw) = mix_sample_stereo(oscillators);
                 let (l, r) = apply_master_saturation(l_raw, r_raw);
+                let l = l * vol;
+                let r = r * vol;
                 if channels >= 2 {
                     if frame < data.len() {
                         data[frame] = l;
@@ -818,13 +863,14 @@ fn build_stream_i16(
         config,
         move |data: &mut [i16], _| {
             let mut guard = state.lock().unwrap();
+            let vol = guard.master_volume.clamp(0.0, 1.0);
             let oscillators = &mut guard.oscillators;
             let mut frame = 0usize;
             while frame < data.len() {
                 let (l_raw, r_raw) = mix_sample_stereo(oscillators);
                 let (l, r) = apply_master_saturation(l_raw, r_raw);
-                let vl = (l.clamp(-1.0, 1.0) * i16::MAX as f32) as i16;
-                let vr = (r.clamp(-1.0, 1.0) * i16::MAX as f32) as i16;
+                let vl = ((l * vol).clamp(-1.0, 1.0) * i16::MAX as f32) as i16;
+                let vr = ((r * vol).clamp(-1.0, 1.0) * i16::MAX as f32) as i16;
                 if channels >= 2 {
                     if frame < data.len() {
                         data[frame] = vl;
@@ -854,13 +900,14 @@ fn build_stream_u16(
         config,
         move |data: &mut [u16], _| {
             let mut guard = state.lock().unwrap();
+            let vol = guard.master_volume.clamp(0.0, 1.0);
             let oscillators = &mut guard.oscillators;
             let mut frame = 0usize;
             while frame < data.len() {
                 let (l_raw, r_raw) = mix_sample_stereo(oscillators);
                 let (l, r) = apply_master_saturation(l_raw, r_raw);
-                let vl = (((l * 0.5 + 0.5).clamp(0.0, 1.0)) * u16::MAX as f32) as u16;
-                let vr = (((r * 0.5 + 0.5).clamp(0.0, 1.0)) * u16::MAX as f32) as u16;
+                let vl = ((((l * vol) * 0.5 + 0.5).clamp(0.0, 1.0)) * u16::MAX as f32) as u16;
+                let vr = ((((r * vol) * 0.5 + 0.5).clamp(0.0, 1.0)) * u16::MAX as f32) as u16;
                 if channels >= 2 {
                     if frame < data.len() {
                         data[frame] = vl;
diff --git a/crates/app-web/index.html b/crates/app-web/index.html
@@ -35,6 +35,23 @@
         backdrop-filter: blur(2px);
         z-index: 10;
       }
+      #start-content {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        gap: 12px;
+        text-align: center;
+        color: #cfe7ff;
+      }
+      #start-keys {
+        color: #9bb;
+        font: 12px/1.4 monospace;
+        max-width: 560px;
+        background: rgba(20, 20, 30, 0.55);
+        padding: 10px 12px;
+        border: 1px solid rgba(80, 110, 150, 0.35);
+        border-radius: 8px;
+      }
       #start-btn {
         appearance: none;
         border: 1px solid #3a4b66;
@@ -76,13 +93,22 @@
   </head>
   <body>
     <div id="start-overlay">
-      <button id="start-btn">Start</button>
+      <div id="start-content">
+        <button id="start-btn">Start</button>
+        <div id="start-keys">
+          Click Start to begin<br />
+          Click canvas: play a note • Mouse position affects sound<br />
+          Keys: R (new sequence) • Space (pause/resume) • ArrowLeft/Right
+          (tempo) • ArrowUp/Down (volume) • F (fullscreen) • Esc (exit)
+        </div>
+      </div>
     </div>
     <canvas id="app-canvas" width="1280" height="720"></canvas>
     <div class="hint" data-visible="0" style="display: none">
-      Click Start to begin • Drag to move a voice<br />
-      Click: mute • Shift+Click: reseed • Alt+Click: solo<br />
-      R: reseed all • Space: pause/resume • +/-: tempo • F: fullscreen<br />
+      Click Start to begin<br />
+      Click canvas: play a note • Mouse position affects sound<br />
+      R: new sequence • Space: pause/resume • ArrowLeft/Right: tempo • F:
+      fullscreen<br />
       BPM: 110 • Paused: no
     </div>
     <div
diff --git a/crates/app-web/src/lib.rs b/crates/app-web/src/lib.rs
@@ -49,22 +49,7 @@ async fn init() -> anyhow::Result<()> {
         .dyn_into::<web::HtmlCanvasElement>()
         .map_err(|e| anyhow::anyhow!(format!("{:?}", e)))?;
 
-    // Minimal early keyboard handler for hint toggle (works even if WebGPU init fails in CI)
-    {
-        let window = web::window().unwrap();
-        let document = document.clone();
-        let closure = Closure::wrap(Box::new(move |ev: web::KeyboardEvent| {
-            let key = ev.key();
-            if key == "h" || key == "H" {
-                ui::toggle_hint_visibility(&document);
-                ev.prevent_default();
-            }
-        }) as Box<dyn FnMut(_)>);
-        window
-            .add_event_listener_with_callback("keydown", closure.as_ref().unchecked_ref())
-            .ok();
-        closure.forget();
-    }
+    // Removed 'h' help toggle; key mapping is shown on the Start overlay instead.
 
     // Note: we will query the optional hint element lazily inside event handlers to avoid
     // capturing it here and forcing closures to be FnOnce.
@@ -190,8 +175,8 @@ async fn init() -> anyhow::Result<()> {
                             return;
                         }
                     };
-                    // Start unmuted by default (removed M-key toggle)
-                    master_gain.gain().set_value(0.8);
+                    // Start at lower loudness by default (user can raise with ArrowUp)
+                    master_gain.gain().set_value(0.4);
                     // Subtle master saturation (arctan) with wet/dry mix
                     let sat_pre = match web::GainNode::new(&audio_ctx) {
                         Ok(g) => g,
@@ -498,12 +483,8 @@ async fn init() -> anyhow::Result<()> {
                             ms.y = pos.y;
                             // noisy move debug log removed
                             // Compute hover or drag update
-                            let (ro, rd) = render::screen_to_world_ray(
-                                &canvas_mouse,
-                                pos.x,
-                                pos.y,
-                                CAMERA_Z,
-                            );
+                            let (ro, rd) =
+                                render::screen_to_world_ray(&canvas_mouse, pos.x, pos.y, CAMERA_Z);
                             let mut best = None::<(usize, f32)>;
                             let spread = SPREAD;
                             let z_offset = z_offset_vec3();
@@ -571,11 +552,12 @@ async fn init() -> anyhow::Result<()> {
                         closure.forget();
                     }
 
-                    // Keyboard controls: R reseed all, Space pause, +/- bpm adjust, F/Escape fullscreen
+                    // Keyboard controls: R reseed all, Space pause, +/- bpm adjust, ArrowUp/Down volume, F/Escape fullscreen
                     {
                         let engine_k = engine.clone();
                         let paused_k = paused.clone();
                         let canvas_k = canvas_for_click_inner.clone();
+                        let master_gain_k = master_gain.clone();
                         let window = web::window().unwrap();
                         let closure = Closure::wrap(Box::new(move |ev: web::KeyboardEvent| {
                             let key = ev.key();
@@ -618,8 +600,8 @@ async fn init() -> anyhow::Result<()> {
                                     }
                                     ev.prevent_default();
                                 }
-                                // Increase BPM
-                                "+" | "=" => {
+                                // Increase BPM (ArrowRight or +/=)
+                                "ArrowRight" | "+" | "=" => {
                                     let mut eng = engine_k.borrow_mut();
                                     let new_bpm = (eng.params.bpm + 5.0).min(240.0);
                                     eng.set_bpm(new_bpm);
@@ -636,7 +618,7 @@ async fn init() -> anyhow::Result<()> {
                                                         el.dyn_ref::<web::HtmlElement>()
                                                     {
                                                         let content = format!(
-                                                            "Click Start to begin • Drag to move a voice\nClick: mute • Shift+Click: reseed • Alt+Click: solo\nR: reseed all • Space: pause/resume • +/-: tempo\nBPM: {:.0} • Paused: {}",
+                                                            "Click Start to begin\nClick canvas: play a note • Mouse affects sound\nR: new sequence • Space: pause/resume • ArrowLeft/Right: tempo\nBPM: {:.0} • Paused: {}",
                                                             new_bpm,
                                                             if paused_now { "yes" } else { "no" }
                                                     );
@@ -647,8 +629,8 @@ async fn init() -> anyhow::Result<()> {
                                         }
                                     }
                                 }
-                                // Decrease BPM
-                                "-" | "_" => {
+                                // Decrease BPM (ArrowLeft or -/_)
+                                "ArrowLeft" | "-" | "_" => {
                                     let mut eng = engine_k.borrow_mut();
                                     let new_bpm = (eng.params.bpm - 5.0).max(40.0);
                                     eng.set_bpm(new_bpm);
@@ -665,7 +647,7 @@ async fn init() -> anyhow::Result<()> {
                                                         el.dyn_ref::<web::HtmlElement>()
                                                     {
                                                         let content = format!(
-                                                            "Click Start to begin • Drag to move a voice\nClick: mute • Shift+Click: reseed • Alt+Click: solo\nR: reseed all • Space: pause/resume • +/-: tempo\nBPM: {:.0} • Paused: {}",
+                                                            "Click Start to begin\nClick canvas: play a note • Mouse affects sound\nR: new sequence • Space: pause/resume • ArrowLeft/Right: tempo\nBPM: {:.0} • Paused: {}",
                                                             new_bpm,
                                                             if paused_now { "yes" } else { "no" }
                                                     );
@@ -700,6 +682,22 @@ async fn init() -> anyhow::Result<()> {
                                 }
                                 _ => {}
                             }
+                            // Master volume on arrow keys (after other handlers so prevent_default only for arrows)
+                            match key.as_str() {
+                                "ArrowUp" => {
+                                    let v = master_gain_k.gain().value();
+                                    let nv = (v + 0.05).min(1.0);
+                                    let _ = master_gain_k.gain().set_value(nv);
+                                    ev.prevent_default();
+                                }
+                                "ArrowDown" => {
+                                    let v = master_gain_k.gain().value();
+                                    let nv = (v - 0.05).max(0.0);
+                                    let _ = master_gain_k.gain().set_value(nv);
+                                    ev.prevent_default();
+                                }
+                                _ => {}
+                            }
                         })
                             as Box<dyn FnMut(_)>);
                         window
