# TASK-008 ## Title Dynamic Range Analyzer --- ## Objective Implement the Dynamic Range Analyzer for AI MusiMuse. This analyzer extracts dynamic characteristics of an audio signal. These features describe how loudness changes over time and how much headroom remains in the recording. The extracted features become an essential part of Music DNA and future similarity calculations. No rhythm, harmony, tempo, or machine learning should be implemented. --- # Expected Commit Message Add dynamic range analyzer --- # Requirements Read SPEC.md before implementing anything. Follow all AI Rules. Follow the Analysis Framework. Do not violate architectural boundaries. --- # Scope Create ``` src/analyzer/dynamics/ ``` Files ``` __init__.py dynamic_analyzer.py ``` Register the analyzer through ``` build_default_registry() ``` The existing ``` musimuse analyze ``` must automatically execute it. --- # Analyzer Create ``` DynamicAnalyzer ``` inherits from ``` Analyzer ``` Name ``` dynamic ``` Version ``` 1.0.0 ``` --- # Shared DSP Reuse existing DSP utilities. Do not duplicate calculations already implemented. Use - numpy - scipy (only where appropriate) --- # Features Calculate the following features. --- ## Crest Factor Feature ``` crest_factor ``` Definition Peak amplitude divided by RMS. Unit ``` ratio ``` --- ## Crest Factor dB Feature ``` crest_factor_db ``` Definition ``` 20 * log10(crest_factor) ``` --- ## Dynamic Range Feature ``` dynamic_range ``` Definition Difference between the 95th percentile and the 10th percentile of the short-term RMS envelope. Unit ``` dB ``` The implementation should use a sliding RMS window. Do not use simple Peak − RMS. --- ## Headroom Feature ``` headroom_db ``` Definition Distance between peak level and 0 dBFS. Range ``` >= 0 ``` --- ## Clipping Ratio Feature ``` clipping_ratio ``` Definition Fraction of samples whose absolute value is greater than or equal to ``` 0.999 ``` Range ``` 0.0 – 1.0 ``` --- ## Average Loudness Feature ``` average_rms_db ``` Definition Average RMS level over the complete track. Unit ``` dBFS ``` --- ## RMS Variability Feature ``` rms_variability ``` Definition Standard deviation of the short-term RMS envelope. Unit ``` dB ``` --- # Sliding Window Use a configurable RMS window. Create ``` src/dsp/dynamics.py ``` Implement reusable helpers. Minimum API ```python compute_rms_envelope() compute_dynamic_range() compute_headroom() compute_clipping_ratio() ``` Future analyzers must reuse these functions. --- # Configuration Extend ``` src/dsp/config.py ``` with ```python RMS_WINDOW_SIZE = 2048 RMS_HOP_SIZE = 512 ``` No analyzer may hardcode these values. --- # Channel Handling Mono Analyze directly. Stereo Convert to mono using ``` (left + right) / 2 ``` before analysis. --- # Numerical Stability Correctly handle - silence - zero RMS - empty audio - NaN - infinite values Raise ``` AnalysisError ``` when appropriate. --- # Persistence No database access. The existing pipeline automatically stores generated features. --- # Logging No logging inside the analyzer. --- # Tests Create tests covering - sine wave - silence - clipped signal - impulse - white noise - constant signal - mono - stereo - crest factor - crest factor dB - headroom - clipping ratio - RMS envelope - dynamic range - RMS variability - deterministic output - invalid input - pipeline integration - persistence integration --- # Forbidden Do NOT implement - LUFS - EBU R128 - ReplayGain - tempo - beat detection - onset detection - harmony - similarity - Music DNA - normalization --- # Definition of Done ✓ DynamicAnalyzer implemented ✓ Registered through build_default_registry() ✓ Shared dynamics utilities implemented ✓ DSP configuration extended ✓ Produces deterministic results ✓ Handles mono and stereo ✓ Handles silence correctly ✓ Handles invalid input safely ✓ Produces immutable FeatureSet ✓ Automatically persists features ✓ Tests pass ✓ Ruff passes ✓ Black passes ✓ isort passes --- # Architectural Notes This analyzer introduces time-domain dynamic analysis. It complements the Basic Signal Analyzer and Spectral Analyzer. Future analyzers should reuse the dynamic envelope rather than recomputing it independently. The shared DSP dynamics module becomes the single source of truth for dynamic analysis throughout AI MusiMuse. These features will later become an important component of Music DNA and similarity scoring.