Sound System Implementation and State Management Issues

[alienx5499]

🎯 Bug Overview

Bug Title
Complete Sound System Overhaul - Button Functionality and State Management

Bug Category

• 🐛 Bug Fix
• 🔊 Audio System
• 🔄 State Management
• 🎨 UI/UX Enhancement
• 🔧 Core Functionality

🔍 Problem Statement

Is your bug fix related to a problem? Please describe.
The sound system in SortVision has fundamental issues from basic functionality to complex state management:

Basic Functionality Issues:

1. Sound toggle button doesn't reliably turn sound on/off on click
2. Visual feedback (button state) doesn't always match actual sound state
3. Initial sound state is inconsistent across page loads
4. Sound button appears to work but doesn't actually affect sound output

State Management Issues:

1. When starting with sound disabled and enabling it during sorting, the sound doesn't work properly
2. Sound state gets out of sync between UI and audio engine
3. Sound doesn't consistently work when toggled during active sorting operations
4. Audio context state isn't properly managed during state transitions
5. Sound preferences don't persist correctly between sessions

Known Edge Cases:

1. Sound fails to initialize when initial state is false
2. Multiple rapid clicks on sound button can break state
3. Sound state becomes undefined after certain sorting operations
4. Browser tab switching can break audio context

User Story
As a user of SortVision, I want:

1. The sound button to reliably turn sound on/off with a single click
2. Visual feedback that accurately reflects the sound state
3. My sound preferences to persist between sessions
4. The ability to toggle sound during sorting without issues

💡 Proposed Solution

Describe the solution you'd like
Implement a complete sound system overhaul with proper button functionality, state management, and persistence.

Key Features/Requirements:

• Fix basic sound button toggle functionality
• Implement proper button state visual feedback
• Add reliable initial state handling
• Implement proper audio context lifecycle management
• Synchronize UI state with audio engine state
• Add reliable sound state persistence
• Handle audio context suspension/resumption
• Add proper error handling for audio operations
• Ensure sound works when enabled during sorting
• Add sound state validation before playing sounds

Acceptance Criteria:

• Sound button toggles sound on/off reliably with single click
• Button visual state matches actual sound state
• Sound works correctly with any initial state (true/false)
• Sound works when enabled during active sorting
• Sound state persists between sessions
• Sound can be toggled reliably at any time
• No audio context errors in console
• Sound state stays in sync between UI and engine
• Proper error handling and user feedback
• Clean, semantic code following project standards

🔄 Alternative Solutions

Describe alternatives you've considered

1. Use Web Audio API directly without abstraction (rejected - too complex)
2. Use a third-party audio library (rejected - overkill for simple sounds)
3. Use simple HTML5 Audio elements (rejected - less control over sound)
4. Use React Context for state management (rejected - adds unnecessary complexity)

Why is this the best approach?
A custom audio engine with proper state management provides the perfect balance of control and simplicity while maintaining good performance.

🎨 Design & Implementation Ideas

Technical Considerations:

• Button Component: Proper event handling and state management
• Audio Context: Proper lifecycle management
• State Management: Sync between UI and engine
• Error Handling: Graceful fallbacks
• Performance: Efficient sound playing
• Browser Support: Web Audio API compatibility

Implementation Approach:

// Sound Button Component
const SoundButton = () => {
  const [isEnabled, setIsEnabled] = useState(() => {
    const saved = localStorage.getItem('soundEnabled');
    return saved !== null ? JSON.parse(saved) : false;
  });
  
  const handleToggle = useCallback(async () => {
    try {
      await audioEngine.toggleSound();
      setIsEnabled(prev => !prev);
      localStorage.setItem('soundEnabled', JSON.stringify(!isEnabled));
    } catch (error) {
      console.error('Failed to toggle sound:', error);
      // Handle error state
    }
  }, [isEnabled]);

  return (
    <button 
      onClick={handleToggle}
      className={`sound-button ${isEnabled ? 'enabled' : 'disabled'}`}
      aria-pressed={isEnabled}
    >
      {isEnabled ? 'Sound On' : 'Sound Off'}
    </button>
  );
};

// Audio Engine Class
class AudioEngine {
  constructor() {
    this.audioContext = null;
    this.masterGain = null;
    this.isEnabled = false;
    this.isInitialized = false;
  }

  async init() {
    if (!this.isInitialized) {
      try {
        this.audioContext = new (window.AudioContext || window.webkitAudioContext)();
        this.masterGain = this.audioContext.createGain();
        this.masterGain.connect(this.audioContext.destination);
        this.isInitialized = true;
      } catch (error) {
        console.error('Failed to initialize audio context:', error);
        throw error;
      }
    }
  }

  async toggleSound() {
    try {
      if (!this.isInitialized) {
        await this.init();
      }
      
      this.isEnabled = !this.isEnabled;
      
      if (this.isEnabled) {
        await this.audioContext.resume();
        this.masterGain.gain.value = 1;
      } else {
        this.masterGain.gain.value = 0;
      }
      
      return this.isEnabled;
    } catch (error) {
      console.error('Failed to toggle sound:', error);
      throw error;
    }
  }

  // ... other methods
}

// React Hook
const useAudio = () => {
  const [isEnabled, setIsEnabled] = useState(() => {
    const saved = localStorage.getItem('soundEnabled');
    return saved !== null ? JSON.parse(saved) : false;
  });

  const [isReady, setIsReady] = useState(false);
  const [error, setError] = useState(null);

  useEffect(() => {
    const initAudio = async () => {
      try {
        await audioEngine.init();
        if (isEnabled) {
          await audioEngine.toggleSound();
        }
        setIsReady(true);
      } catch (error) {
        setError(error);
      }
    };

    initAudio();
  }, []);

  // ... rest of the hook
};

Files to Modify:

1. src/components/settings/SettingsForm.jsx

   • Fix sound button component
   • Add proper state handling
   • Add error handling
   • Add visual feedback

2. src/utils/audioEngine.js

   • Implement robust audio context management
   • Add proper state handling
   • Add error handling
   • Add initialization checks

3. src/hooks/useAudio.js

   • Implement state synchronization
   • Add persistence logic
   • Add sound validation
   • Add error handling

4. src/components/sortingVisualizer/SortingVisualizer.jsx

   • Update how audio is passed to algorithms
   • Add state validation
   • Improve error handling
   • Add sound state checks

📊 Impact Assessment

Priority/Importance

• Priority:

  • 🔴 Critical (Affects core functionality)

• Impact:

  • 🎯 High (Core feature of visualization)

Target Audience:

• 👥 All SortVision users
• 🎓 Students learning algorithms
• 👨‍🏫 Educators demonstrating sorts
• 🌐 Web accessibility users

🎯 SSOC Season 4 Information

Project Status:

• 🎯 Open for SSOC Season 4 Contributors
• 🔒 Reserved for Specific Contributor
• ⏳ In Progress
• ✅ Completed

Difficulty Level:

• 🟢 Beginner (20 points)
• 🟡 Intermediate (30 points)
• 🔴 Advanced (40 points) - Complex state management, Web Audio API, Error Handling

Estimated Time: 8-10 hours

Skills Required:

• Advanced React/JSX
• Web Audio API knowledge
• State management expertise
• Error handling experience
• Testing experience
• Git workflow knowledge
• Browser API understanding
• Async/Await proficiency

Implementation Plan:

1. Phase 1: Basic Button Functionality (2 hours)

   • Fix sound button component
   • Add proper event handling
   • Add visual feedback
   • Add basic error handling

2. Phase 2: Audio Engine Refactor (2 hours)

   • Implement proper audio context management
   • Add state handling
   • Add error handling
   • Add initialization checks

3. Phase 3: React Hook Updates (2 hours)

   • Implement state synchronization
   • Add persistence logic
   • Add sound validation
   • Add error handling

4. Phase 4: Component Integration (2 hours)

   • Update settings form
   • Update sorting visualizer
   • Add error handling
   • Add state validation

5. Phase 5: Testing & Documentation (2 hours)

   • Test all scenarios
   • Add error handling
   • Document changes
   • Write unit tests

📚 Additional Context

Use Cases/Scenarios:

1. User clicks sound button multiple times rapidly
2. User starts sorting with sound off, enables during sort
3. User toggles sound multiple times during sorting
4. User reloads page with different sound states
5. User experiences audio context errors
6. User switches tabs/windows during sorting
7. User has slow internet connection
8. User's browser restricts audio autoplay

Technical Challenges:

• Managing audio context lifecycle
• Handling button click events properly
• Synchronizing multiple state sources
• Handling edge cases in sorting
• Ensuring consistent behavior
• Managing browser limitations
• Handling async operations
• Managing error states

Testing Requirements:

• Test basic button functionality
• Test button visual feedback
• Test all sound state transitions
• Verify persistence behavior
• Check error handling
• Test during active sorting
• Test across different browsers
• Verify no performance impact
• Test with different initial states
• Test rapid state changes
• Test browser tab switching
• Test with network throttling

✅ Checklist

• I have searched existing issues to ensure this is not a duplicate
• I have provided a clear problem statement and solution
• I have considered alternative approaches
• I have assessed the impact and priority
• I have included relevant technical details
• I have outlined testing requirements

[Divya-A10]

im planning to fix the sound button by:
-Make sure the sound button actually turns the sound on and off.
-Make the button visually show whether sound is on or off.
-Ensure the button works during sorting animations.
-Prevent problems when the button is clicked quickly many times.
-Fix the issue where sound doesn't work if it was off at the beginning.

Fix how the app remembers the sound setting:

-Save the user's sound preference in the browser so it stays the same even after a refresh.
-Make sure sound settings load correctly when the page opens.

Fix how the app manages sound behind the scenes:

-Make sure sound system starts and stops properly without crashing.
-Fix problems caused by switching tabs or reloading the page.
and finally test everything to make sure sound works before, during, and after sorting.

if this plan makes sense to you @alienx5499 I'd like to be assigned this issue.

[alienx5499]

Thanks for the detailed plan, @Divya-A10 — it looks solid and aligns well with the core requirements outlined in the issue! 🔥
Your approach clearly covers all critical aspects: button behavior, state persistence, edge cases, and error handling.

Before assigning, could you please confirm a few things to help us ensure you’re fully set up for SSOC contributions? 😊

✅ Quick SSOC Onboarding Checklist

Make sure you’ve completed the following:

• Installed the Entelligence AI browser extension
• Filled out the official SSOC Contributor Form

These steps are required to be eligible for SSOC points and recognition.

---

If everything’s good to go, I’ll assign you right away!
Let me know if you need any clarification or help with the implementation plan. 🚀

— Prabal Patra | SSOC Project Admin

[Divya-A10]

Thank you for the approval @alienx5499 ! yes I've installed the Entelligence AI browser extension and filled out the ssoc contributor form! I will seek you out for any clarifications and help.

[alienx5499]

Awesome, @Divya-A10! 🎉

Thanks for confirming the onboarding steps — you're now officially assigned to this issue. Looking forward to your PR! 🛠️✨

Feel free to drop a comment here or reach out if you hit any roadblocks — happy to help along the way. Let’s make the SortVision sound system 🔊 rock-solid!

— Prabal Patra | SSOC Project Admin

[alienx5499]

Hey @Divya-A10! 👋

One quick thing — could you please share your Discord ID (including the numbers, e.g., Username#1234)?
We use this to sync contributor activity and announcements across the SSOC community server. 🎯

Appreciate it! Looking forward to your contributions! 🚀

— Prabal Patra | SSOC Project Admin

[Divya-A10]

suree my discord id is : divya_64265

[Divya-A10]

hey @alienx5499 i just wanted to give you an update of taks which i completed reagarding this issue i've

• Added safePlay() wrapper and started updating sorting files
• Working on updating the remaining sorting algorithms
  -Next: persist sound state via localStorage, sync UI button with engine, test edge cases (tab switch, rapid clicks)
  please correct me if I'm doing something out of scope for the project!

[alienx5499]

Hi @Divya-A10 👋

Just checking in — any updates on the remaining tasks for this issue?
Let me know if you're facing any blockers or need assistance with final testing or integration.

Looking forward to your progress! 🚀

— Prabal Patra | SSOC Project Admin

[Divya-A10]

Hey @alienx5499 !!
I followed a 5 phase solution for this particular issue.
1.Sound button(fixing the sound toggle button,adding proper event handling,saving reference in local storage and applying the saved preference on load)
2.Audio Engine Refactor(cleaning up audio contect lifestyle,fixing gain control,adding error handling to avoid crashing on invalid stages)
3.Hook integration(crerating a reusable hook[useAudio],handling state syncing between UI and Audio Engine, loading local storage preference,provide functions to toggle sound cleanly)
4.SortingVisualizer Integration(injecting sound control into the sorting animation,validate sound state before playing , add checks when sorting starts? stops and ensure no crashes or conflicts during sorting)
5.{this is where I am stuck} Testing rapid toggles,test enabling sound during sorting,test reloading,test switching of tabs,confirm no console errors)
##Sound System Issues
AudioContext Autoplay Restrictions(Browsers are block AudioContext unless resumed via a direct user interaction.)
##State & Playback Sync Issues
Button State De-synchronization.
Sound & Sorting Step Mismatch(Audio tones are not always corresponding to current comparisons/swaps.) and the website does'nt open sometimes because of these errors (pitch black screen) I start the work from the top! Can you please help me with this please?

[alienx5499]

Hi @Divya-A10 👋

Great progress so far, your 5-phase implementation is solid! ✅

Regarding the black screen issue, it's likely due to stale cache or corrupted localStorage state. Please try:

🔄 Clear browser cache and localStorage → Reload the app

This often resolves rendering issues like a blank screen, especially after major state or audio context changes.

You're very close, let me know if the issue persists after that or if you need help debugging further. You're doing amazing work!

— Prabal Patra | SSOC Project Admin

[Divya-A10]

Hii @alienx5499 !!
this step [Clear browser cache and localStorage → Reload the app] was very helpful i thank you for that!
On my local build, metrics.js and details.js are not loading because they appear to reference resources or routes that are either unavailable or configured differently in my environment.
When testing on the hosted version of your main branch, these files load fine, so the issue seems unrelated to my changes and likely due to differences between our setups (e.g., local API/data source paths, missing environment variables, or build config differences).
Once my changes are merged into your branch and built in your environment, these files should work as intended.
I'm trying to raise a pr but just one last issue, I noticed main.jsx is present in my branch but seems deleted in your main. Was it intentionally removed or renamed? It’s currently the app entry point on my side and I'm not completely sure how i must proceed forward regarding this