# TASK-005 ## Title Basic Signal Analyzer --- ## Objective Implement the first real audio analyzer for AI MusiMuse. This analyzer extracts fundamental signal statistics that will become the foundation for every future analyzer. These features are deterministic, computationally inexpensive, and reusable by all future analyzers. This task also introduces the default analyzer registration mechanism. No spectral analysis should be implemented in this task. --- # Expected Commit Message Add basic signal analyzer --- # Requirements Read SPEC.md before implementing anything. Follow all AI Rules. Follow the Analysis Framework introduced in TASK-004. Do not violate architectural boundaries. --- # Scope Create a new package: ``` src/analyzer/basic/ ``` Files: ``` __init__.py basic_signal_analyzer.py ``` --- # Default Analyzer Registry Introduce a default analyzer registry builder. Create: ``` src/analyzer/default_registry.py ``` Responsibilities: - create AnalyzerRegistry - register all built-in analyzers - return a fully configured registry Example: ```python registry = build_default_registry() ``` The CLI must never manually register analyzers. Future analyzers should only require adding one registration line inside the default registry. The CLI should simply request the default registry and execute the pipeline. --- # Analyzer Create ```python BasicSignalAnalyzer ``` inherits from ```python Analyzer ``` Version ```python version = "1.0.0" ``` Name ```python basic_signal ``` Register it automatically through ``` build_default_registry() ``` --- # Features The analyzer must calculate the following features. --- ## Duration Feature ``` duration_seconds ``` Use the value already available in DecodedAudio. --- ## Sample Rate Feature ``` sample_rate ``` --- ## Channels Feature ``` channels ``` --- ## Peak Amplitude Stereo ``` peak_left peak_right ``` Mono ``` peak ``` Range ``` 0.0 – 1.0 ``` --- ## Peak dBFS Feature ``` peak_db ``` Formula ``` 20 * log10(peak) ``` Handle zero safely. --- ## RMS Stereo ``` rms_left rms_right ``` Mono ``` rms ``` --- ## RMS dBFS Feature ``` rms_db ``` Formula ``` 20 * log10(rms) ``` Handle silence correctly. --- ## DC Offset Feature ``` dc_offset ``` Definition Mean sample value. --- ## Silence Ratio Feature ``` silence_ratio ``` Definition Percentage of samples whose ``` abs(sample) < 0.001 ``` Range ``` 0.0 – 1.0 ``` --- # Output The analyzer should produce approximately ``` 8–12 features ``` depending on mono/stereo. --- # Numerical Requirements Use ``` numpy ``` for every calculation. No Python loops over samples. Use vectorized operations. --- # Error Handling Raise ``` AnalysisError ``` for - empty audio - NaN values - infinite values The pipeline must continue processing remaining tracks. --- # Logging The analyzer must not perform logging. Pipeline remains responsible for all logging. --- # CLI No new commands. Existing ``` musimuse analyze ``` must automatically execute ``` BasicSignalAnalyzer ``` through ``` build_default_registry() ``` Example summary ``` Tracks analyzed: 9 Analyzers executed: 1 Features produced: 99 Failures: 0 ``` --- # Tests Create tests for - Peak calculation - RMS calculation - Peak dB - RMS dB - DC Offset - Silence Ratio - Mono audio - Stereo audio - Silence - Impulse signal - Constant signal - Empty audio - Invalid values - Analyzer registration - Default registry builder - Pipeline execution - Expected feature names - Expected feature values - Numerical stability --- # Forbidden Do NOT implement - FFT - Spectrogram - Tempo - Beat Detection - Dynamics - Loudness normalization - Chroma - Harmony - Key Detection - MFCC - Embeddings - Similarity - Music DNA --- # Definition of Done ✓ BasicSignalAnalyzer implemented ✓ Registered through build_default_registry() ✓ CLI no longer manually registers analyzers ✓ Default registry implemented ✓ Runs through AnalysisPipeline ✓ Produces deterministic results ✓ Produces immutable FeatureSet ✓ Handles mono and stereo ✓ Handles silence safely ✓ Handles invalid input safely ✓ CLI analyze executes analyzer ✓ Tests pass ✓ Ruff passes ✓ Black passes ✓ isort passes --- # Architectural Notes This analyzer intentionally computes only low-level signal statistics. These values become the foundation for every future analyzer. Future analyzers must never recompute these statistics. The default registry introduced in this task becomes the single source of truth for built-in analyzers. Adding a new analyzer in future tasks should require: 1. Implementing the analyzer class. 2. Registering it inside `build_default_registry()`. No other infrastructure changes should be necessary. The framework should remain open for extension and closed for modification (Open/Closed Principle).