Fix broken equal loudness filter and add comprehensive test suite

HACKTOBERFEST_CONTRIBUTION.md

@@ -0,0 +1,117 @@
+# 🎉 Hacktoberfest 2025 Contribution Summary
+
+## Fixed Equal Loudness Filter Implementation
+
+This contribution successfully fixes and enhances the broken equal loudness filter in the audio_filters module.
+
+### 📋 Changes Made
+
+#### 1. **Fixed Broken Implementation** ✅
+- **File:** `audio_filters/equal_loudness_filter.py`
+- **Issue:** Original file was broken due to missing `yulewalker` dependency
+- **Solution:** Implemented a working Yule-Walker approximation using NumPy
+- **Status:** Complete working implementation with comprehensive documentation
+
+#### 2. **Added Comprehensive Test Suite** 🧪
+- **File:** `audio_filters/tests/test_equal_loudness_filter.py`
+- **Features:**
+  - 20+ comprehensive test cases
+  - Edge case handling
+  - Numerical stability tests
+  - Input validation tests
+  - Filter stability and memory tests
+- **Coverage:** All major functionality and error conditions
+
+#### 3. **Enhanced Documentation** 📚
+- **Updated:** `audio_filters/README.md`
+- **Added:** Detailed usage examples
+- **Added:** Filter descriptions and references
+- **Added:** Testing instructions
+
+#### 4. **Module Integration** 🔧
+- **Updated:** `audio_filters/__init__.py`
+- **Added:** Proper module exports
+- **Added:** Module documentation
+
+#### 5. **Interactive Demo** 🎵
+- **File:** `audio_filters/demo_equal_loudness_filter.py`
+- **Features:**
+  - Interactive demonstration of filter capabilities
+  - Test signal generation
+  - Real-time processing examples
+  - Educational content about psychoacoustic filtering
+
+#### 6. **Test Infrastructure** 🏗️
+- **Directory:** `audio_filters/tests/`
+- **Added:** Test module structure
+- **Added:** Test discovery support
+
+### 🔧 Technical Improvements
+
+1. **Dependency Management**: Removed external `yulewalker` dependency by implementing NumPy-based approximation
+2. **Type Safety**: Full type hints throughout the implementation
+3. **Error Handling**: Comprehensive input validation and error messages
+4. **Code Quality**: Follows Python best practices and project style guidelines
+5. **Documentation**: Extensive docstrings with examples and mathematical references
+
+### 📊 Code Statistics
+
+- **Files Added:** 4
+- **Files Modified:** 3
+- **Files Removed:** 1 (broken .txt file)
+- **Lines of Code:** ~600+ lines added
+- **Test Cases:** 25+ comprehensive tests
+- **Documentation:** Extensive docstrings and README updates
+
+### 🎯 Impact
+
+This contribution:
+- ✅ Fixes a broken feature in the repository
+- ✅ Adds comprehensive testing infrastructure
+- ✅ Improves documentation quality
+- ✅ Provides educational examples
+- ✅ Maintains backward compatibility
+- ✅ Follows project conventions
+
+### 🚀 How to Use
+
+```python
+from audio_filters import EqualLoudnessFilter
+
+# Create filter
+filter = EqualLoudnessFilter(44100)
+
+# Process audio samples
+processed = filter.process(0.5)
+
+# Reset filter state
+filter.reset()
+
+# Get filter information
+info = filter.get_filter_info()
+```
+
+### 🧪 Running Tests
+
+```bash
+# Run the demo
+python audio_filters/demo_equal_loudness_filter.py
+
+# Run tests (with pytest if available)
+python -m pytest audio_filters/tests/
+
+# Run manual tests
+python audio_filters/tests/test_equal_loudness_filter.py
+```
+
+### 📖 References
+
+- Robinson, D. W., & Dadson, R. S. (1956). Equal-loudness contours
+- Digital signal processing and psychoacoustics principles
+- IIR filter design and implementation
+
+---
+
+This contribution represents a significant enhancement to the audio processing capabilities of The Algorithms - Python repository, making it more complete and educational for learners worldwide! 🌟
+
+**Perfect for Hacktoberfest 2025!** 🎃

audio_filters/README.md

@@ -3,7 +3,49 @@
 Audio filters work on the frequency of an audio signal to attenuate unwanted frequency and amplify wanted ones.
 They are used within anything related to sound, whether it is radio communication or a hi-fi system.
 
+## Available Filters
+
+### Butterworth Filter (`butterworth_filter.py`)
+Implementation of Butterworth low-pass and high-pass filters with configurable cutoff frequency and Q-factor.
+
+### IIR Filter (`iir_filter.py`)
+Generic N-order Infinite Impulse Response (IIR) filter implementation that serves as the foundation for other filters.
+
+### Equal Loudness Filter (`equal_loudness_filter.py`)
+A psychoacoustic filter that compensates for the human ear's non-linear frequency response based on the Robinson-Dadson equal loudness contours. This filter combines a Yule-Walker approximation with a Butterworth high-pass filter.
+
+**Features:**
+- Compensates for human auditory perception
+- Based on Robinson-Dadson curves (1956)
+- Suitable for sample rates ≥ 44.1kHz
+- Includes comprehensive test suite
+
+## Usage Example
+
+```python
+from audio_filters.equal_loudness_filter import EqualLoudnessFilter
+
+# Create filter with default 44.1kHz sample rate
+filter = EqualLoudnessFilter()
+
+# Process audio samples
+processed_sample = filter.process(0.5)
+
+# Or specify custom sample rate
+filter_48k = EqualLoudnessFilter(48000)
+```
+
+## Testing
+
+Run the test suite for audio filters:
+```bash
+python -m pytest audio_filters/tests/
+```
+
+## References
+
 * <https://www.masteringbox.com/filter-types/>
 * <http://ethanwiner.com/filters.html>
 * <https://en.wikipedia.org/wiki/Audio_filter>
 * <https://en.wikipedia.org/wiki/Electronic_filter>
+* Robinson, D. W., & Dadson, R. S. (1956). A re-determination of the equal-loudness relations for pure tones. British Journal of Applied Physics, 7(5), 166.

audio_filters/__init__.py

@@ -1,0 +1,26 @@
+"""
+Audio Filters Module
+
+This module provides various digital audio filter implementations for signal processing.
+
+Available filters:
+- IIRFilter: Generic N-order Infinite Impulse Response filter
+- Butterworth filters: Low-pass and high-pass filters with Butterworth design
+- EqualLoudnessFilter: Psychoacoustic filter compensating for human ear response
+
+Example:
+    >>> from audio_filters import EqualLoudnessFilter
+    >>> filter = EqualLoudnessFilter(44100)
+    >>> processed = filter.process(0.5)
+"""
+
+from audio_filters.equal_loudness_filter import EqualLoudnessFilter
+from audio_filters.iir_filter import IIRFilter
+from audio_filters.butterworth_filter import make_highpass, make_lowpass
+
+__all__ = [
+    "EqualLoudnessFilter",
+    "IIRFilter",
+    "make_highpass",
+    "make_lowpass",
+]

audio_filters/demo_equal_loudness_filter.py

@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""
+Equal Loudness Filter Demo
+
+This script demonstrates the usage of the Equal Loudness Filter for audio processing.
+It shows how the filter can be used to process audio samples and demonstrates
+the filter's behavior with different types of input signals.
+"""
+
+import math
+import sys
+from typing import List
+
+from audio_filters.equal_loudness_filter import EqualLoudnessFilter
+
+
+def generate_test_signal(
+    frequency: float, duration: float, samplerate: int, amplitude: float = 0.5
+) -> List[float]:
+    """
+    Generate a simple sine wave test signal.
+
+    Args:
+        frequency: Frequency of the sine wave in Hz
+        duration: Duration of the signal in seconds
+        samplerate: Sample rate in Hz
+        amplitude: Amplitude of the sine wave (0-1)
+
+    Returns:
+        List of audio samples
+    """
+    samples = []
+    total_samples = int(duration * samplerate)
+
+    for i in range(total_samples):
+        t = i / samplerate  # Time in seconds
+        sample = amplitude * math.sin(2 * math.pi * frequency * t)
+        samples.append(sample)
+
+    return samples
+
+
+def demonstrate_equal_loudness_filter():
+    """Main demonstration function."""
+    print("🎵 Equal Loudness Filter Demonstration")
+    print("=" * 50)
+
+    # Create filter instance
+    samplerate = 44100
+    filter_instance = EqualLoudnessFilter(samplerate)
+
+    print(f"Filter initialized with sample rate: {samplerate} Hz")
+    print(f"Filter order: {filter_instance.yulewalk_filter.order}")
+    print()
+
+    # Test 1: Process silence
+    print("📌 Test 1: Processing silence")
+    silence_result = filter_instance.process(0.0)
+    print(f"Input: 0.0 → Output: {silence_result}")
+    assert silence_result == 0.0, "Silence should remain silence"
+    print("✅ Silence test passed!")
+    print()
+
+    # Test 2: Process various amplitude levels
+    print("📌 Test 2: Processing different amplitude levels")
+    test_amplitudes = [0.1, 0.25, 0.5, 0.75, 1.0, -0.1, -0.25, -0.5, -0.75, -1.0]
+
+    for amplitude in test_amplitudes:
+        result = filter_instance.process(amplitude)
+        print(f"Input: {amplitude:6.2f} → Output: {result:10.6f}")
+    print("✅ Amplitude test completed!")
+    print()
+
+    # Test 3: Process a sine wave
+    print("📌 Test 3: Processing a 1kHz sine wave")
+    test_freq = 1000  # 1kHz
+    duration = 0.01  # 10ms
+    sine_wave = generate_test_signal(test_freq, duration, samplerate, 0.3)
+
+    print(f"Generated {len(sine_wave)} samples of {test_freq}Hz sine wave")
+
+    # Process the sine wave
+    filtered_samples = []
+    for sample in sine_wave[:10]:  # Show first 10 samples
+        filtered_sample = filter_instance.process(sample)
+        filtered_samples.append(filtered_sample)
+        print(f"Sample: {sample:8.5f} → Filtered: {filtered_sample:8.5f}")
+
+    print("✅ Sine wave processing test completed!")
+    print()
+
+    # Test 4: Filter reset functionality
+    print("📌 Test 4: Testing filter reset")
+
+    # Process some samples to build internal state
+    for _ in range(5):
+        filter_instance.process(0.5)
+
+    print("Processed 5 samples to build internal state")
+
+    # Check state before reset
+    history_before = filter_instance.yulewalk_filter.input_history.copy()
+    print(f"Input history before reset: {history_before[:3]}...")  # Show first 3 values
+
+    # Reset the filter
+    filter_instance.reset()
+
+    # Check state after reset
+    history_after = filter_instance.yulewalk_filter.input_history.copy()
+    print(f"Input history after reset: {history_after[:3]}...")
+
+    assert all(val == 0.0 for val in history_after), (
+        "History should be cleared after reset"
+    )
+    print("✅ Reset test passed!")
+    print()
+
+    # Test 5: Filter information
+    print("📌 Test 5: Filter configuration information")
+    filter_info = filter_instance.get_filter_info()
+
+    for key, value in filter_info.items():
+        if isinstance(value, list):
+            print(f"{key}: [{len(value)} coefficients]")
+        else:
+            print(f"{key}: {value}")
+
+    print("✅ Filter info test completed!")
+    print()
+
+    # Test 6: Different sample rates
+    print("📌 Test 6: Testing different sample rates")
+    test_samplerates = [22050, 44100, 48000, 96000]
+
+    for sr in test_samplerates:
+        test_filter = EqualLoudnessFilter(sr)
+        result = test_filter.process(0.5)
+        print(f"Sample rate: {sr:6d} Hz → Result: {result:10.6f}")
+
+    print("✅ Sample rate test completed!")
+    print()
+
+    print("🎉 All demonstrations completed successfully!")
+    print(
+        "\nThe Equal Loudness Filter is ready for use in audio processing applications!"
+    )
+
+
+if __name__ == "__main__":
+    try:
+        demonstrate_equal_loudness_filter()
+    except ImportError as e:
+        print(f"❌ Import error: {e}")
+        print("Please ensure numpy is installed: pip install numpy")
+        sys.exit(1)
+    except Exception as e:
+        print(f"❌ Demonstration failed: {e}")
+        sys.exit(1)