# TASK-010 ## Title Harmony Analyzer --- ## Objective Implement the Harmony Analyzer for AI MusiMuse. This analyzer extracts deterministic harmonic descriptors from decoded audio. These descriptors characterize the tonal content of music and become the final low-level feature group before Music DNA generation. Do not implement machine learning, similarity search, or Music DNA. --- # Expected Commit Message Add harmony analyzer --- # Requirements Read SPEC.md before implementing anything. Follow all AI Rules. Follow the Analysis Framework. Reuse existing DSP infrastructure whenever possible. Do not violate architectural boundaries. --- # Scope Create ``` src/analyzer/harmony/ ``` Files ``` __init__.py harmony_analyzer.py ``` Register the analyzer through ``` build_default_registry() ``` No CLI changes are required. The existing ``` musimuse analyze ``` must automatically execute this analyzer. --- # Analyzer Create ``` HarmonyAnalyzer ``` inherits from ``` Analyzer ``` Name ``` harmony ``` Version ``` 1.0.0 ``` --- # Shared DSP Create ``` src/dsp/harmony.py ``` Implement reusable harmonic DSP utilities. Minimum API ```python compute_chroma() estimate_key() estimate_mode() compute_pitch_class_histogram() compute_tonal_centroid() compute_tonal_stability() ``` Future harmonic analyzers must reuse these utilities. --- # Configuration Extend ``` src/dsp/config.py ``` with ```python CHROMA_BINS = 12 TONAL_HISTORY_SIZE = 32 ``` No analyzer may hardcode these values. --- # DSP Requirements Reuse - compute_stft() - compute_power_spectrum() Use - numpy - scipy Vectorized implementation only. --- # Features Calculate --- ## Chroma Vector Features ``` chroma_c chroma_csharp chroma_d chroma_dsharp chroma_e chroma_f chroma_fsharp chroma_g chroma_gsharp chroma_a chroma_asharp chroma_b ``` Each value ``` 0.0–1.0 ``` Normalized. --- ## Estimated Key Feature ``` estimated_key ``` String. Allowed values ``` C C# D Eb E F F# G Ab A Bb B ``` --- ## Estimated Mode Feature ``` estimated_mode ``` Allowed values ``` major minor unknown ``` --- ## Tonal Centroid Features ``` tonnetz_x tonnetz_y tonnetz_z tonnetz_u tonnetz_v tonnetz_w ``` --- ## Tonal Stability Feature ``` tonal_stability ``` Range ``` 0.0–1.0 ``` Higher values indicate more stable harmonic content. --- ## Pitch Class Entropy Feature ``` pitch_class_entropy ``` Lower values indicate stronger tonal focus. --- # Channel Handling Mono Analyze directly. Stereo Convert to mono ``` (left + right) / 2 ``` before harmonic analysis. --- # Numerical Stability Correctly handle - silence - noise - empty audio - NaN - Inf Raise ``` AnalysisError ``` when appropriate. --- # Persistence No database access. Pipeline automatically stores generated features. --- # Logging No logging inside the analyzer. --- # Tests Create tests covering - sine wave - chords - scales - white noise - silence - mono - stereo - chroma extraction - key estimation - mode estimation - tonal centroid - tonal stability - entropy - deterministic output - invalid input - pipeline integration - persistence integration --- # Forbidden Do NOT implement - chord recognition - chord progression analysis - melody extraction - singing voice detection - genre classification - similarity search - Music DNA - machine learning --- # Definition of Done ✓ HarmonyAnalyzer implemented ✓ Registered through build_default_registry() ✓ Shared harmony DSP 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 completes the project's deterministic low-level audio analysis stack. The Harmony Analyzer must reuse the shared DSP layer rather than implementing independent FFT or spectral calculations. All harmonic processing utilities belong inside `src/dsp/harmony.py`. The extracted harmonic descriptors intentionally remain deterministic and interpretable. These descriptors become direct inputs to the future Music DNA Builder. Harmony analysis must remain independent of any machine learning or statistical model.