Clean up legacy 3D sphere voice markers and update documentation

- Remove unused instance buffer fields (positions, colors, scales) from FrameContext
- Remove build_instances_reuse function that was building data for invisible markers
- Remove unused constants: BASE_SCALE, SCALE_PULSE_MULTIPLIER, RING_COUNT, ANALYSER_DOTS_MAX, MUTE_DARKEN, HOVER_BRIGHTEN
- Simplify render function to use hardcoded voice positions instead of dynamic arrays
- Update documentation to reflect current wave-based aesthetic (no visible spheres)
- All tests pass, build succeeds, CI runs successfully
- Maintains full voice interaction through invisible interaction zones

Author: rgilks

README.md

@@ -20,7 +20,7 @@
 - Keyboard: A..F (root), 1..7 (mode), R (new sequence), T (random key+mode), Space (pause/resume), ArrowLeft/Right (tempo), ArrowUp/Down (volume), Enter (fullscreen)
 - 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
+- Rich visuals: voice-reactive wave displacement, ambient waves background, post bloom/tonemap/vignette; optional analyser-driven spectrum dots
 
 ### Demo
 

docs/SPEC.md

@@ -10,7 +10,7 @@ Users can **influence and interact** with the generative music without manually
 
 - 3 generative voices (sine/saw/triangle) with scale-constrained pitches (C major pentatonic by default), scheduler on an eighth-note grid
 - Web Audio graph with per-voice `PannerNode` and master reverb/delay buses; starts muted with Start overlay; gesture unlock required by browsers
-- Visuals: instanced voice markers, ambient waves background with pointer swirl and click ripples, post-processing (bright pass, blur, ACES tonemap, vignette, grain)
+- Visuals: ambient waves background with voice-reactive displacement, pointer swirl and click ripples, post-processing (bright pass, blur, ACES tonemap, vignette, grain)
 - Planned microtonality: global detune in cents and additional microtonal scale families (19-TET, 24-TET, 31-TET); keyboard shortcuts for detune and scale selection
 
 ## Goals and Use Cases
@@ -258,7 +258,7 @@ graph TD
 **Scene and Visual Elements:**
 What the user sees:
 
-- **Objects Representing Voices:** Three instanced round markers (circle-masked quads) represent voices. Positions correspond to voice `PannerNode` positions; markers pulse and emit on note events.
+- **Voice Influence on Waves:** Voice positions influence the wave patterns through displacement and proximity effects, creating golden highlights and wave distortions around each voice location.
 - **Ambient Waves Background:** A fullscreen pass (see `waves.wgsl`) renders layered ribbons with pointer-driven swirl displacement, per-voice influence, and click/tap ripple propagation.
 - **Post-processing:** A post stack (see `post.wgsl`) performs bright pass, separable blur, ACES tonemap, vignette, subtle hue warp, and film grain.
 - **Camera:** Fixed view; the `AudioListener` tracks the camera to maintain spatial consistency.
@@ -301,21 +301,21 @@ The UI is minimalist and embedded in the 3D world. The goal is that the user see
 
 - **Play/Pause:** Space key toggles pause/resume. No in-scene play/pause icon yet.
 - **Regenerate:** `R` reseeds all voices. Per-voice: Shift+Click reseeds, Alt+Click solos, Click toggles mute.
-- **Position Adjustment:** Click+drag a voice object to move it on the horizontal plane; movement is clamped to a radius. Positions update the corresponding `PannerNode` in real time.
+- **Position Adjustment:** Click+drag on a voice's invisible interaction zone to move it on the horizontal plane; movement is clamped to a radius. Positions update the corresponding `PannerNode` in real time.
 - **Tempo:** ArrowRight/ArrowLeft adjust BPM.
 - **Overlay:** Start overlay for audio unlock; `H` toggles visibility. It does not show live BPM/Paused/Muted state.
 
 **Possible UI Elements/Controls (future):**
 We identify additional interactions that could be mapped to in-scene controls:
 
 - **Play/Pause:** If the system allows stopping the music, a control to pause or resume generation. Perhaps the music runs by default and maybe we don’t need an explicit play (it starts immediately), but pause could be useful. Implement as an icon (e.g., a play/pause symbol) floating in a corner of the scene or as part of an object (maybe a central orb that stops/starts everything when clicked).
-- **Regenerate (Randomize):** A control to generate a new musical sequence (either for all voices at once, or maybe separate control per voice). For all-at-once, an icon like 🔄 could be placed somewhere in view. For per-voice regeneration, perhaps clicking an individual voice object could trigger it to come up with a new pattern.
+- **Regenerate (Randomize):** A control to generate a new musical sequence (either for all voices at once, or maybe separate control per voice). For all-at-once, an icon like 🔄 could be placed somewhere in view. For per-voice regeneration, perhaps clicking on a voice's invisible interaction zone could trigger it to come up with a new pattern.
 - **Voice Mute/Unmute or Volume:** Perhaps clicking a voice object toggles it on/off (if user wants to focus on certain layers). If no labels, the object’s appearance can indicate mute state (e.g., dim or turn grey when muted). Volume could be controlled by distance: maybe the user drags the object closer or further from camera/listener to effectively change volume (since closer = louder in spatial audio). This would be a very natural metaphor for volume control!
 - **Position Adjustment:** The user can **grab and move a voice’s object** in the 3D space. This changes the spatial position of that sound (panning/volume in headphones). It’s an interactive way for the user to do a sort of “mixing” – e.g., spread sounds out or bring one closer. We’ll implement drag controls:
 
   - On desktop, mouse click+drag on an object could move it. We need to implement a picking mechanism to select objects with the mouse. Possibly ray-cast from camera through cursor to find which object is clicked.
   - Simplify movement to perhaps a plane or spherical surface: e.g., restrict dragging to horizontal plane (x-z) so user won’t lose it in depth too much, or allow full 3D if we have a way to move in all axes (maybe using right-click or modifier for up/down).
-  - As the object moves, update the corresponding PannerNode position in real-time so the sound appears from the new direction. This will likely impress the spatial effect on the user.
+  - As the voice position moves, update the corresponding PannerNode position in real-time so the sound appears from the new direction. This will likely impress the spatial effect on the user.
 
 - **Change Scale/Key or Mode:** We might include a control for musical scale or mood. Perhaps a small set of preset scales (Major, Minor, Pentatonic, etc.) can be cycled. Without labels, this is tricky – maybe an object that cycles color and each color corresponds to a scale (could be hinted in some text in documentation or a minimal legend). Alternatively, the user might not need to change scale if the generative is fine by itself. This might be an advanced control possibly omitted in first version to keep UI simple.
 - **Tempo Control:** If needed, could allow user to speed up or slow down. Perhaps a dial control represented by a ring around some object – the user dragging that ring could adjust tempo. Or simpler, two buttons (faster, slower) as plus/minus icons. But unlabeled plus/minus might be okay if intuitively placed next to a tempo icon (metronome icon?).
@@ -327,9 +327,9 @@ We identify additional interactions that could be mapped to in-scene controls:
 
   - In the browser, capture mouse events on the canvas.
   - Perform **ray-sphere** intersection for voice picking. Maintain hover highlight; on click/drag, update engine voice state and audio panner.
-  - Once we know which object is selected on click, we handle according to that object’s role (e.g., if it’s a voice sphere: start dragging it; if it’s a regenerate button: trigger regeneration immediately; etc.).
-  - On drag: update object position in real-time (for voice objects) and possibly give some visual feedback (like a highlight or trailing indicator).
-  - On release: drop the object at new position.
+  - Once we know which voice is selected on click, we handle according to that voice's role (e.g., if it's a voice: start dragging it; if it's a regenerate button: trigger regeneration immediately; etc.).
+  - On drag: update voice position in real-time and possibly give some visual feedback through wave displacement effects.
+  - On release: drop the voice at new position.
   - Also handle hover highlighting: as mouse moves, if it hovers an object, maybe slightly scale it up or change color to indicate it’s interactable. This can be done by checking ray intersection each frame with cursor position.
 
 - **Integrated Look and Feel:**
@@ -356,7 +356,7 @@ We identify additional interactions that could be mapped to in-scene controls:
 To ensure a "fantastic result", the development should proceed in stages, verifying each piece:
 
 1. **Initial Setup:** Get a basic Rust+WASM project running with WebGPU rendering something simple (like a triangle or cube on screen) and Web Audio playing a test tone. This ensures the environment and build pipeline are correct (WebGPU initialization, etc.). Use this to verify browser compatibility (e.g., test in Chrome Canary or current stable with proper flags if needed).
-2. **Basic 3D Scene (implemented):** The scene is in place with an ambient waves fullscreen pass and three instanced voice markers representing voices. There are no placeholder objects. The camera is fixed (the `AudioListener` tracks it for spatial audio). Interaction testing is via pointer hover/drag and keyboard; orbit/mouselook is not used.
+2. **Basic 3D Scene (implemented):** The scene is in place with an ambient waves fullscreen pass that reacts to voice positions through displacement and proximity effects. There are no placeholder objects. The camera is fixed (the `AudioListener` tracks it for spatial audio). Interaction testing is via pointer hover/drag and keyboard; orbit/mouselook is not used.
 3. **Audio Generation:** Implement the audio engine’s core:
 
    - Pick a scale (e.g., C major pentatonic) and generate a repeating random sequence for one voice. Use an OscillatorNode to play it. Ensure timing is consistent.
@@ -367,7 +367,7 @@ To ensure a "fantastic result", the development should proceed in stages, verify
 4. **Sync Audio-Visual:** Link the events. Have the visual objects respond to the audio – e.g., on each note event, flash or scale the corresponding object. Fine-tune to make it noticeable but not jarring.
 5. **Interactivity:** Add the user interaction one by one:
 
-   - Ray picking and dragging of objects. Ensure that moving a voice object changes its PannerNode coordinates and the visual moves accordingly.
+   - Ray picking and dragging of voice positions. Ensure that moving a voice position changes its PannerNode coordinates and the wave displacement effects move accordingly.
    - Add a regenerate button or gesture. Perhaps a key press “R” for now to regenerate all sequences (for easier testing) – later replace with a 3D button.
    - Add a play/pause toggle (again, maybe key press first, then integrate UI object).
    - Test that these interactions can happen while audio is playing without glitching.

src/constants.rs

@@ -41,8 +41,6 @@ pub const FX_SAT_WET_BASE: f32 = 0.15;
 pub const FX_SAT_WET_SPAN: f32 = 0.85;
 
 // Visual build parameters
-pub const RING_COUNT: usize = 48;
-pub const ANALYSER_DOTS_MAX: usize = 16;
 
 // Per-voice spatial sends mapping
 pub const DIST_NORM_DIVISOR: f32 = 2.5;
@@ -59,8 +57,6 @@ pub const LEVEL_BASE: f32 = 0.55;
 pub const LEVEL_SPAN: f32 = 0.45;
 
 // Color adjustments
-pub const MUTE_DARKEN: f32 = 0.35;
-pub const HOVER_BRIGHTEN: f32 = 1.4;
 
 // Camera
 // Z distance used by both picking and audio listener alignment.

src/core/constants.rs

@@ -6,10 +6,6 @@ use glam::Vec3;
 pub const SPREAD: f32 = 1.8; // scales engine-space positions to world-space
 pub const Z_OFFSET: Vec3 = Vec3::new(0.0, 0.0, -4.0); // world-space offset applied to all markers
 
-// Visual sizing
-pub const BASE_SCALE: f32 = 1.6; // idle marker size
-pub const SCALE_PULSE_MULTIPLIER: f32 = 0.4; // how much a full pulse enlarges a marker
-
 // Interaction
 pub const PICK_SPHERE_RADIUS: f32 = 0.8; // ray-sphere radius for picking
 pub const ENGINE_DRAG_MAX_RADIUS: f32 = 3.0; // max engine-space radius when dragging

src/frame.rs

@@ -1,8 +1,8 @@
 use crate::constants::*;
-use crate::core::{MusicEngine, Waveform, BASE_SCALE, SCALE_PULSE_MULTIPLIER, SPREAD, Z_OFFSET};
+use crate::core::{MusicEngine, Waveform};
 use crate::input;
 use crate::render;
-use glam::{Vec3, Vec4};
+use glam::Vec3;
 use instant::Instant;
 use std::cell::RefCell;
 use std::rc::Rc;
@@ -48,11 +48,6 @@ pub struct FrameContext<'a> {
     pub swirl_vel: [f32; 2],
     pub swirl_initialized: bool,
     pub pulse_energy: [f32; 3],
-
-    // Reused per-frame instance buffers to avoid allocations
-    pub positions: Vec<Vec3>,
-    pub colors: Vec<Vec4>,
-    pub scales: Vec<f32>,
 }
 
 impl<'a> FrameContext<'a> {
@@ -154,12 +149,7 @@ impl<'a> FrameContext<'a> {
                 }
             }
 
-            // Build instance buffers for renderer
-            let pulses_snapshot: Vec<f32> = {
-                let pulses_ref = self.pulses.borrow();
-                pulses_ref.clone()
-            };
-            self.build_instances_reuse(&pulses_snapshot);
+            // Voice positions are now only used for audio spatialization and wave displacement
 
             // Camera + listener
             let cam_eye = Vec3::new(0.0, 0.0, CAMERA_Z);
@@ -181,7 +171,7 @@ impl<'a> FrameContext<'a> {
                 let w = self.canvas.width();
                 let h = self.canvas.height();
                 g.resize_if_needed(w, h);
-                if let Err(e) = g.render(dt_sec, &self.positions, &self.scales) {
+                if let Err(e) = g.render(dt_sec) {
                     log::error!("render error: {:?}", e);
                 }
             }
@@ -249,74 +239,6 @@ impl<'a> FrameContext<'a> {
             + SWIRL_ENERGY_BLEND_ALPHA * target;
         self.prev_uv = uv;
     }
-
-    fn build_instances_reuse(&mut self, pulses: &[f32]) {
-        let e_ref = self.engine.borrow();
-        let z_offset = Z_OFFSET;
-        let spread = SPREAD;
-        let ring_count = RING_COUNT;
-        self.positions.clear();
-        self.colors.clear();
-        self.scales.clear();
-        self.positions.reserve(3 + ring_count * 3 + 16);
-        self.colors.reserve(3 + ring_count * 3 + 16);
-        self.scales.reserve(3 + ring_count * 3 + 16);
-        self.positions
-            .push(e_ref.voices[0].position * spread + z_offset);
-        self.positions
-            .push(e_ref.voices[1].position * spread + z_offset);
-        self.positions
-            .push(e_ref.voices[2].position * spread + z_offset);
-        // Static neutral color; shader color accents are procedural now
-        self.colors.push(Vec4::new(0.25, 0.65, 1.0, 1.0));
-        self.colors.push(Vec4::new(0.25, 0.65, 1.0, 1.0));
-        self.colors.push(Vec4::new(0.25, 0.65, 1.0, 1.0));
-        let hovered = *self.hover_index.borrow();
-        for i in 0..3 {
-            if e_ref.voices[i].muted {
-                self.colors[i].x *= MUTE_DARKEN;
-                self.colors[i].y *= MUTE_DARKEN;
-                self.colors[i].z *= MUTE_DARKEN;
-                self.colors[i].w = 1.0;
-            }
-            if hovered == Some(i) {
-                self.colors[i].x = (self.colors[i].x * HOVER_BRIGHTEN).min(1.0);
-                self.colors[i].y = (self.colors[i].y * HOVER_BRIGHTEN).min(1.0);
-                self.colors[i].z = (self.colors[i].z * HOVER_BRIGHTEN).min(1.0);
-            }
-        }
-        self.scales
-            .push(BASE_SCALE + pulses[0] * SCALE_PULSE_MULTIPLIER);
-        self.scales
-            .push(BASE_SCALE + pulses[1] * SCALE_PULSE_MULTIPLIER);
-        self.scales
-            .push(BASE_SCALE + pulses[2] * SCALE_PULSE_MULTIPLIER);
-
-        if let Some(a) = &self.analyser {
-            let bins = a.frequency_bin_count() as usize;
-            let dots = bins.min(ANALYSER_DOTS_MAX);
-            if dots > 0 {
-                {
-                    let mut buf = self.analyser_buf.borrow_mut();
-                    if buf.len() != bins {
-                        buf.resize(bins, 0.0);
-                    }
-                    a.get_float_frequency_data(&mut buf);
-                }
-                let z = z_offset.z;
-                for i in 0..dots {
-                    let v_db = self.analyser_buf.borrow()[i];
-                    let lin = ((v_db + 100.0) / 100.0).clamp(0.0, 1.0);
-                    let x = -2.8 + (i as f32) * (5.6 / (dots as f32 - 1.0));
-                    let y = -1.8;
-                    self.positions.push(Vec3::new(x, y, z));
-                    let c = Vec3::new(0.25 + 0.5 * lin, 0.6 + 0.3 * lin, 0.9);
-                    self.colors.push(Vec4::from((c, 0.95)));
-                    self.scales.push(0.18 + lin * 0.35);
-                }
-            }
-        }
-    }
 }
 
 #[inline]

src/lib.rs

@@ -287,9 +287,6 @@ async fn init() -> anyhow::Result<()> {
                     swirl_vel: [0.0, 0.0],
                     swirl_initialized: false,
                     pulse_energy: [0.0, 0.0, 0.0],
-                    positions: Vec::with_capacity(128),
-                    colors: Vec::with_capacity(128),
-                    scales: Vec::with_capacity(128),
                 }));
                 // Start RAF loop
                 frame::start_loop(frame_ctx);

src/render.rs

@@ -1,4 +1,3 @@
-use crate::core::{BASE_SCALE, SCALE_PULSE_MULTIPLIER};
 use glam::Vec3;
 use web_sys as web;
 
@@ -344,12 +343,7 @@ impl<'a> GpuState<'a> {
         }
     }
 
-    pub fn render(
-        &mut self,
-        dt_sec: f32,
-        positions: &[Vec3],
-        scales: &[f32],
-    ) -> Result<(), wgpu::SurfaceError> {
+    pub fn render(&mut self, dt_sec: f32) -> Result<(), wgpu::SurfaceError> {
         self.resize_if_needed(self.width, self.height);
         self.time_accum += dt_sec.max(0.0);
         let frame = self.surface.get_current_texture()?;
@@ -376,19 +370,21 @@ impl<'a> GpuState<'a> {
                 timestamp_writes: None,
                 occlusion_query_set: None,
             });
-            let pack = |i: usize| VoicePacked {
-                pos_pulse: [
-                    positions[i].x,
-                    positions[i].y,
-                    positions[i].z,
-                    ((scales[i] - BASE_SCALE).max(0.0) / SCALE_PULSE_MULTIPLIER).clamp(0.0, 1.5),
-                ],
-            };
             let w = WavesUniforms {
                 resolution: [self.width as f32, self.height as f32],
                 time: self.time_accum,
                 ambient: self.ambient_energy,
-                voices: [pack(0), pack(1), pack(2)],
+                voices: [
+                    VoicePacked {
+                        pos_pulse: [0.0, 0.0, -4.0, 0.0],
+                    }, // Voice 1 at center
+                    VoicePacked {
+                        pos_pulse: [-1.8, 0.0, -4.0, 0.0],
+                    }, // Voice 2 left
+                    VoicePacked {
+                        pos_pulse: [1.8, 0.0, -4.0, 0.0],
+                    }, // Voice 3 right
+                ],
                 swirl_uv: [
                     self.swirl_uv[0].clamp(0.0, 1.0),
                     self.swirl_uv[1].clamp(0.0, 1.0),

tests/constants_tests.rs

@@ -54,8 +54,6 @@ fn fx_weights_sum_to_reasonable_values() {
 #[allow(clippy::assertions_on_constants)]
 fn core_constants_are_positive() {
     assert!(SPREAD > 0.0);
-    assert!(BASE_SCALE > 0.0);
-    assert!(SCALE_PULSE_MULTIPLIER > 0.0);
     assert!(PICK_SPHERE_RADIUS > 0.0);
     assert!(ENGINE_DRAG_MAX_RADIUS > 0.0);
 }