Merge pull request #38 from feat/add-sound-effects

Feat: add sound effects system (#21)

Author: ayoub3bidi

README.md

@@ -38,10 +38,15 @@
   - **Autoplay**: Automatic step-by-step animation with play/pause/stop controls
 - **Interactive Controls**: Play, pause, step forward/backward through algorithm execution
 - **Mobile Swipe Gestures**: Swipe left/right on mobile devices to navigate steps in manual mode with an attractive tutorial overlay
+- **Audio Feedback**: Optional sound effects for algorithm operations and UI interactions
+  - **Sorting**: Distinct sounds for comparing, swapping, pivot selection, and completion
+  - **Pathfinding**: Audio cues for node exploration and path discovery
+  - **UI Sounds**: Click feedback and array generation sounds
 - **Customizable Settings**: 
   - Switch between Sorting and Pathfinding modes
   - Choose between Manual (default) and Autoplay control modes
   - Adjust animation speed (Slow, Medium, Fast, Very Fast)
+  - Toggle sound effects on/off
 - **Algorithm Analysis**: Interactive complexity panel with Big-O notation and performance graphs
 - **Python Code Examples**: View Python implementations
 - **Responsive Design**: Works seamlessly on desktop and mobile devices
@@ -54,6 +59,7 @@
 
 - Node.js (v18 or higher)
 - pnpm (v8 or higher)
+- Modern browser with Web Audio API support (for sound effects)
 
 If you don't have pnpm installed:
 
@@ -176,7 +182,8 @@ bayan-flow/
 │   │   ├── arrayHelpers.js
 │   │   ├── arrayHelpers.test.js
 │   │   ├── gridHelpers.js
-│   │   └── gridHelpers.test.js
+│   │   ├── gridHelpers.test.js
+│   │   └── soundManager.js
 │   ├── constants/        # App constants
 │   │   └── index.js
 │   ├── test/            # Test configuration

docs/ARCHITECTURE.md

@@ -9,9 +9,10 @@ This document provides an in-depth explanation of the Bayan Flow architecture, d
 3. [Data Flow](#data-flow)
 4. [Algorithm Implementation](#algorithm-implementation)
 5. [Animation System](#animation-system)
-6. [State Management](#state-management)
-7. [Testing Strategy](#testing-strategy)
-8. [Performance Optimizations](#performance-optimizations)
+6. [Audio System](#audio-system)
+7. [State Management](#state-management)
+8. [Testing Strategy](#testing-strategy)
+9. [Performance Optimizations](#performance-optimizations)
 
 ## System Architecture
 
@@ -220,6 +221,60 @@ for (let step of steps) {
 }
 ```
 
+## Audio System
+
+### SoundManager Architecture
+
+The audio system uses **Tone.js** for Web Audio API abstraction and provides contextual sound feedback for algorithm operations.
+
+**Core Design:**
+```javascript
+class SoundManager {
+  constructor() {
+    this.isEnabled = false;
+    this.softSynth = new Tone.Synth({...});      // UI sounds
+    this.pluckSynth = new Tone.PluckSynth({...}); // Compare sounds
+    this.metallicSynth = new Tone.MetalSynth({...}); // Swap sounds
+    this.polySynth = new Tone.PolySynth({...});   // Chord sounds
+  }
+}
+```
+
+### Sound Mapping Strategy
+
+**Sorting Operations:**
+- **Compare**: Pluck synth with frequency mapped to element value (150-350Hz)
+- **Swap**: Metallic synth for distinct swap feedback
+- **Pivot**: Soft synth with lower frequency range (100-200Hz)
+- **Sorted**: Major chord (C-E-G) for completion celebration
+
+**Pathfinding Operations:**
+- **Node Visit**: Soft synth at 220Hz (A3 note)
+- **Path Found**: Extended chord (C3-E3-G3-C4) for success
+- **UI Interactions**: Brief G4 note for clicks
+
+### Integration Pattern
+
+**Hook Integration:**
+```javascript
+const executeStep = useCallback((step) => {
+  // Update visual state
+  setArray(step.array);
+  setStates(step.states);
+  
+  // Trigger contextual audio
+  if (step.states.includes(ELEMENT_STATES.SWAPPING)) {
+    soundManager.playSwap(step.array[swapIndex]);
+  }
+}, []);
+```
+
+**Benefits:**
+- **Non-blocking**: Audio failures don't affect visualization
+- **User-controlled**: Easy enable/disable toggle
+- **Performance**: Early returns when disabled
+- **Contextual**: Sounds match visual operations
+
 ## State Management
 
 ### Custom Hook: useSortingVisualization

docs/DEVELOPMENT.md

@@ -398,6 +398,54 @@ const debouncedSize = useDebounce(arraySize, 300);
 ### Issue: Types Not Working
 **Solution:** Restart TypeScript server
 
+### Issue: Audio Not Working
+**Solution:** Check browser autoplay policy, ensure user interaction before enabling
+
+## Sound System Integration
+
+### Adding Sound to New Algorithms
+
+**Step 1: Identify Sound Events**
+```javascript
+// In your algorithm implementation
+if (hasSwapping) {
+  soundManager.playSwap(elementValue);
+} else if (hasComparing) {
+  soundManager.playCompare(elementValue);
+}
+```
+
+**Step 2: Update Hook Integration**
+```javascript
+const executeStep = useCallback((step) => {
+  // Update visual state
+  setArray(step.array);
+  setStates(step.states);
+  
+  // Add sound logic
+  const hasNewState = step.states.includes(NEW_STATE);
+  if (hasNewState) {
+    soundManager.playNewSound();
+  }
+}, []);
+```
+
+**Step 3: Add New Sound Methods**
+```javascript
+// In soundManager.js
+playNewSound() {
+  if (!this.isEnabled) return;
+  this.synth.triggerAttackRelease('C4', '8n');
+}
+```
+
+### Sound Design Guidelines
+
+- **Frequency Mapping**: Map element values to frequencies for intuitive audio feedback
+- **Duration**: Keep sounds brief (64n to 8n note values) to avoid overlap
+- **Volume**: Use moderate levels to prevent fatigue
+- **Fallback**: Always check `isEnabled` before playing sounds
+
 ## Conclusion
 
 This project follows modern React best practices:
@@ -407,5 +455,6 @@ This project follows modern React best practices:
 - Test-driven development
 - Performance optimization
 - Clean code principles
+- Accessible audio feedback
 
 All contributions are welcome!

package.json

@@ -52,7 +52,8 @@
     "@octokit/rest": "^22.0.0",
     "lucide-react": "^0.544.0",
     "react": "^19.1.1",
-    "react-dom": "^19.1.1"
+    "react-dom": "^19.1.1",
+    "tone": "^15.1.22"
   },
   "devDependencies": {
     "@eslint/js": "^9.36.0",