# Analyzer API Version: 1.0 Status: Stable Author: AI MusiMuse Project --- # Purpose This document defines the official Analyzer API for AI MusiMuse. Every analyzer implemented inside the project MUST follow this specification. The goal is to ensure that analyzers remain - deterministic - reproducible - independent - testable - composable --- # Analyzer Philosophy Analyzers measure music. Analyzers do not make decisions. Analyzers do not compare tracks. Analyzers do not generate recommendations. Analyzers do not modify data. Their only responsibility is to extract musical features. --- # Analyzer Pipeline ``` Decoded Audio │ ▼ AnalysisContext │ ▼ Analyzer │ ▼ FeatureSet │ ▼ AnalysisResult │ ▼ Feature Storage ``` --- # Responsibilities Analyzer ✓ measures audio ✓ extracts features ✓ validates inputs ✓ reports warnings Analyzer must never ✗ access SQLite ✗ write files ✗ call network services ✗ call other analyzers ✗ modify AnalysisContext --- # Base Class Every analyzer inherits ```python class Analyzer(ABC): id: str version: str description: str def analyze( self, context: AnalysisContext ) -> AnalysisResult: ... ``` --- # Required Properties Every analyzer must define ``` id ``` Globally unique identifier. Example ``` basic_signal ``` --- ``` version ``` Semantic version. Example ``` 1.0 ``` --- ``` description ``` Human-readable description. --- # Analyzer ID Rules Identifiers - lowercase - snake_case - globally unique Examples ``` basic_signal spectral dynamic rhythm harmony mfcc structure genre ``` Forbidden ``` BasicSignal signal analyzer signal-1 ``` --- # Versioning Version numbers follow Semantic Versioning. Examples ``` 1.0 1.1 2.0 ``` Version increases whenever produced features change. --- # AnalysisContext Every analyzer receives exactly one immutable ``` AnalysisContext ``` It contains - Track - DecodedAudio - Settings Context must never be modified. --- # Decoded Audio Decoded audio is already normalized. Analyzers may assume ``` float32 [-1.0,+1.0] ``` No analyzer should perform additional normalization. --- # Feature Creation Analyzers create immutable Feature objects. Example ``` Feature identifier value unit ``` Feature objects are never modified. --- # Feature Naming Identifiers use ``` block.feature ``` Examples ``` signal.rms spectral.centroid dynamic.headroom rhythm.tempo harmony.chroma_c ``` Identifiers must match Feature Registry. --- # FeatureSet Every analyzer returns one immutable ``` FeatureSet ``` FeatureSet - iterable - immutable - deterministic Duplicate identifiers are forbidden. --- # AnalysisResult Analyzer returns ``` AnalysisResult ``` containing - analyzer_id - analyzer_version - execution_time - FeatureSet - warnings - success --- # Warnings Recoverable issues become warnings. Examples ``` short_audio mono_input very_low_level ``` Warnings never stop the pipeline. --- # Exceptions Fatal problems raise ``` AnalysisError ``` Pipeline catches exceptions. Remaining analyzers continue. --- # Pipeline Isolation Each analyzer executes independently. Failure of one analyzer must never stop - remaining analyzers - feature persistence - pipeline execution --- # Determinism Analyzers must be deterministic. The same input must always produce the same output. Forbidden - randomness - timestamps - adaptive thresholds - dataset statistics --- # Performance Analyzers should - minimize allocations - use NumPy vectorization - avoid Python loops - reuse DSP utilities Large temporary arrays should be avoided. --- # Shared DSP Common DSP belongs inside ``` src/dsp/ ``` Examples ``` spectrum.py dynamics.py rhythm.py harmony.py ``` Analyzers must reuse shared DSP functions whenever possible. Duplicate DSP implementations are forbidden. --- # Dependencies Analyzer may depend on - NumPy - SciPy - shared DSP Analyzer must not depend on - SQLAlchemy - repositories - CLI - storage - similarity engine --- # Output Quality Feature values should be - finite - deterministic - physically meaningful NaN values are permitted only when the feature is genuinely undefined. Infinity is forbidden. --- # Testing Every analyzer requires Unit tests ✓ happy path ✓ silence ✓ mono ✓ stereo ✓ invalid input ✓ deterministic output ✓ pipeline integration ✓ persistence integration --- # Registration Analyzers register through ``` build_default_registry() ``` Only registered analyzers participate in Analysis Pipeline. --- # Feature Registry Analyzer output identifiers must exist in the Feature Definition Registry. ```python from features.default_registry import build_default_feature_registry registry = build_default_feature_registry() registry.contains("signal.rms") # True ``` The registry is the single source of truth for feature metadata (identifier, display name, category, data type, normalization strategy, unit, version). Undefined identifiers are forbidden. New analyzers must add their FeatureDefinitions to ```python build_default_feature_registry() ``` in `src/features/default_registry.py`. --- # Music DNA Analyzers never build Music DNA. They produce only raw features. Music DNA Builder converts raw features into Music DNA. --- # AI Embeddings Analyzers never generate embeddings. Embeddings are created by Embedding Builder. --- # Plugin Compatibility Third-party analyzers must implement the same Analyzer interface. No special plugin API exists. Plugins are first-class analyzers. --- # Backward Compatibility Analyzer implementation may improve. Analyzer version increases whenever feature calculation changes. Historical Analysis Runs remain unchanged. Historical Feature values are never modified. --- # Architectural Rules Analyzer responsibilities ✓ Measure ✓ Extract ✓ Validate ✓ Report Analyzer responsibilities never include ✗ Persist ✗ Normalize ✗ Compare ✗ Recommend ✗ Generate ✗ Learn Those belong to higher layers. --- # Future Extensions Future analyzers may include - MFCC - Timbre - Structure - Melody - Instrument Detection - Vocal Detection - Genre - Mood - Emotion - Production Quality All future analyzers must comply with this specification.