Add BPM detector tool with multiple analysis algorithms

[simonw]

Real-time beats per minute analyzer that uses the microphone to detect
tempo using three different approaches:

• Peak detection (energy envelope analysis)
• Autocorrelation (pattern matching)
• Spectral flux (frequency change detection)

Features waveform visualization, confidence indicators, and detailed
explanations of each algorithm.

[claude]

Claude finished @simonw's task —— View job

---

Code Review Complete ✅

I've analyzed the BPM detector tool implementation. Here's my comprehensive review:

Review Checklist

• Read repository setup instructions (CLAUDE.md) - No repo-specific file found
• Analyze the beats-per-minute.html file structure and implementation
• Review code quality and best practices
• Check for potential bugs and security issues
• Evaluate performance considerations
• Assess algorithm implementations (peak detection, autocorrelation, spectral flux)
• Review error handling and user experience
• Provide comprehensive feedback

---

Code Review Feedback

🟢 Strengths

Algorithm Implementation:

• Excellent multi-algorithm approach: The combination of peak detection, autocorrelation, and spectral flux provides robust BPM detection
• Well-documented algorithms: The explanations section clearly describes each method's approach and use cases
• Smart confidence weighting: The combined estimate uses dynamic weighting based on individual algorithm confidence levels
• Tempo normalization: Proper handling of octave ambiguity (lines 785-787, 861-862)

Code Quality:

• Clean, readable structure: Well-organized with clear separation between UI, audio processing, and algorithm logic
• Responsive design: Good mobile responsiveness with CSS media queries
• Professional UI: Modern gradient design with good visual feedback
• Educational value: Comprehensive algorithm explanations make this a learning tool

Audio Processing:

• Proper Web Audio API usage: Correct setup of audio context, analyser, and microphone nodes
• Smart buffering: Maintains manageable buffer sizes (10 seconds max audio buffer)
• Real-time visualization: Nice waveform display with frequency spectrum background

🟡 Areas for Improvement

Performance Considerations:

• Heavy autocorrelation computation (lines 830-851): O(n²) complexity could cause frame drops with longer buffers

  // Consider using FFT-based autocorrelation for better performance
  for (let lag = minLag; lag < Math.min(maxLag, downsampled.length / 2); lag++) {
      // This nested loop can be expensive

• Frequent DOM updates: BPM display updates every 10 frames could be optimized with throttling
• Canvas rendering: No frame rate limiting on waveform drawing

Algorithm Robustness:

• Peak detection threshold (line 744): Fixed 1.3 multiplier may not work well for all music types
• Limited BPM range: Hard-coded 40-200 BPM range excludes some genres (ballads, death metal)
• Spectral flux onset detection: Simple threshold approach could miss complex rhythmic patterns

Code Structure:

• Global state management: Large number of global variables could benefit from encapsulation
• Magic numbers: Several hard-coded constants should be moved to configuration

  // Examples of magic numbers that should be constants
  const CONFIDENCE_THRESHOLD = 1.3; // line 744
  const MIN_PEAK_INTERVAL = 0.2;    // line 747
  const HISTORY_LENGTH = 10;        // multiple locations

🟠 Potential Issues

Security & Privacy:

• Microphone permissions: Good error handling, but no explicit privacy notice about audio processing
• Audio data retention: 10-second buffer is reasonable, but users aren't informed about data handling

Bug Risks:

• Memory leaks: requestAnimationFrame cleanup looks good, but audio context cleanup could be more robust
• Race conditions: No protection against rapid start/stop button clicks
• Browser compatibility: No fallback for older browsers without Web Audio API support

Edge Cases:

• Silence handling: No specific handling for very quiet audio input
• Tempo changes: Algorithms assume steady tempo throughout the analysis window
• Background noise: Could interfere with peak detection in noisy environments

🔴 Critical Issues

Audio Context Management:

• Sample rate assumption (line 555): Hard-coded 44100 Hz may not match actual device capabilities

  // This could fail on some devices
  audioContext = new (window.AudioContext || window.webkitAudioContext)({ sampleRate: SAMPLE_RATE });

Error Recovery:

• No recovery mechanism: If audio processing fails mid-stream, user must refresh page
• Limited error feedback: Generic error messages don't help users troubleshoot specific issues

📊 Test Coverage Assessment

Current state: No automated tests present (expected for a standalone HTML tool)

Recommended testing approach:

• Unit tests for algorithm functions (calculateRMS, autocorrelation, etc.)
• Integration tests with mock audio data
• Browser compatibility testing across devices
• Performance testing with various audio inputs

💡 Specific Recommendations

1. Add configuration object:

   const CONFIG = {
     BPM_RANGE: { min: 40, max: 200 },
     PEAK_THRESHOLD_MULTIPLIER: 1.3,
     MAX_BUFFER_SECONDS: 10,
     // ... other constants
   };

2. Implement performance optimization:

   // Throttle display updates
   const throttledUpdate = throttle(updateDisplay, 100);

3. Add browser compatibility check:

   if (!window.AudioContext && !window.webkitAudioContext) {
     showError('Web Audio API not supported in this browser');
   }

4. Improve error handling:

   // More specific error messages
   catch (err) {
     if (err.name === 'NotAllowedError') {
       statusEl.textContent = 'Microphone access denied. Please allow permissions and reload.';
     } else if (err.name === 'NotFoundError') {
       statusEl.textContent = 'No microphone found. Please connect a microphone.';
     }
   }

🎯 Overall Assessment

This is a well-implemented, educational tool with sophisticated BPM detection algorithms. The code demonstrates good understanding of audio processing concepts and provides excellent user experience. The main areas for improvement are performance optimization for the autocorrelation algorithm and better error handling/recovery mechanisms.

Grade: B+ - High-quality implementation with room for optimization and robustness improvements.