README.md (4593B)
1 # Geedback 2 3 A real-time sensor-driven WASM DSP synthesizer. 4 5 ## Design Philosophy & Direction 6 7 ### 1. WASM-Centric DSP 8 All core signal processing is implemented in Rust/WASM for high performance and portability. The project follows a stateful processor pattern, designed for future integration with frameworks like **NIH-plug**. 9 10 ### 2. Physical State Modeling 11 Sensor data is interpreted as physical forces: 12 - **Orientation (Tilt)**: Static position in 3D space. 13 - **Linear Acceleration (Force)**: Dynamic impact and rapid movement. 14 15 ### 3. Seamless 2D Trigonometric Mapping 16 To ensure unique parameter states and perfectly smooth 360-degree rotation: 17 - **$\sin(\theta/2) \to$ Pitch**: Spread over a 360-degree period to prevent half-turn repetition. 18 - **$\cos(\theta/2) \to$ Waveform Morphing**: Ensures every angle has a unique "Timbre," even when pitches match. 19 20 ### 4. Organic Parameter Smoothing 21 Internal Low-Pass Filters (LPF) with a high coefficient (**0.9995**) eliminate "zipper noise" from 60Hz sensor updates, creating a creamy, instrument-like feel with physical inertia. 22 23 --- 24 25 ## Detailed Specifications 26 27 ### 1. Synthesis Engine 28 - **3-Oscillator Architecture**: Each oscillator has independent phase and selectable waveforms. 29 - **Available Waveforms**: Sine, Triangle, Triangle-Sawtooth, Sawtooth, Reverse Sawtooth, Square, Wide Pulse, Narrow Pulse. 30 - **FM Modulation**: Each carrier oscillator is frequency-modulated by a dedicated modulator, driven by dynamic physical forces. 31 32 ### 2. Motion Mapping (Orientation & Acceleration) 33 | Input Axis | Target Oscillator | Static Control ($\sin/\cos$) | Dynamic Control (Linear Accel) | 34 | :--- | :--- | :--- | :--- | 35 | **Gamma (Y)** | Oscillator 1 | Pitch & Waveform Morph | FM Modulation Depth | 36 | **Alpha (Z)** | Oscillator 2 | Pitch & Waveform Morph | FM Modulation Depth | 37 | **Beta (X)** | Oscillator 3 | Pitch & Waveform Morph | FM Modulation Depth | 38 39 - **Waveform Morphing Examples**: 40 - Pulse Waves: Modulates Pulse Width (2% to 50%). 41 - Triangle-Sawtooth: Modulates the blend ratio. 42 - Sine: Adds subtle saturation/harmonics. 43 44 ### 3. Kaoss Pad (Global Filter) 45 - **UI**: A red crosshair square canvas with scroll-safe touch handling. 46 - **Algorithm**: High-quality Global Biquad Low-Pass Filter (LPF). 47 - **Control Mapping**: 48 - **X-axis**: Cutoff Frequency (**100Hz to 18kHz**, exponential scale). 49 - **Y-axis**: Resonance / Q (**0.707 to 15.0**). 50 - **Stability**: Includes a safety clamp at **0.45 * Sample Rate** to prevent NaN/mathematical explosion at high cutoff frequencies. 51 52 ### 4. Technical Integration 53 - **Web Audio API**: Real-time streaming via `ScriptProcessorNode`. 54 - **Permission Handling**: Integrated iOS `DeviceMotionEvent.requestPermission` flow. 55 - **Build System**: Automated `wasm-pack workflow targeting standard browser environments. 56 57 --- 58 59 ## 🤖 Message for Future Coding Agents 60 61 ### Technical Handoff Notes 62 When continuing development on Geedback, please adhere to the following architectural constraints: 63 64 1. **Stateful Processor**: Keep `GeedbackProcessor` stateful. It is designed to mimic the `process()` loop of standard audio plugins. Avoid adding global static state; encapsulate everything within the struct to facilitate future **NIH-plug** porting. 65 2. **The "Zipper Noise" Battle**: Sensor updates from browsers are slow (~60Hz). Always use the internal LPF (**`0.9995` coefficient**) for any parameter driven by sensors. Never map raw sensor values directly to audio parameters. 66 3. **Trigonometric Periodicity**: Use `theta / 2.0` before calculating `sin/cos` for orientation. This is a deliberate choice to spread a full oscillator cycle across a **360-degree** physical turn, preventing the pitch from repeating every half-turn. 67 4. **Filter Stability**: The Biquad implementation is sensitive to the Nyquist frequency. **Always clamp** the cutoff frequency to below `0.45 * sample_rate`. If you implement other filter types (High-Pass, Band-Pass), apply similar safety guards to prevent NaN explosions. 68 5. **2D Mapping Integrity**: Maintain the `sin` (Pitch) and `cos` (Timbre) coupling. This is the primary solution to "data collapse" where multiple orientations would otherwise yield the same sound. 69 70 ### Future Roadmap Ideas 71 - Implement an ADSR envelope triggered by sharp Linear Acceleration spikes. 72 - Add a "Delay" or "Reverb" module, potentially controlled by the Z-axis (Alpha) or Magnetometer (if available). 73 - Port the current `GeedbackProcessor` logic into a Rust-native audio plugin using NIH-plug.