# Music DNA Schema Version: 1.0 Status: Stable Author: AI MusiMuse Project --- # Purpose Music DNA is the canonical representation of the musical characteristics of a track. It is the primary data structure consumed by every intelligent subsystem inside AI MusiMuse. Music DNA is - deterministic - reproducible - explainable - versioned - immutable Music DNA intentionally excludes all file-specific information. --- # Design Philosophy Music DNA describes music. It does not describe files. Examples of excluded properties - codec - container - sample rate - bit depth - channels - bitrate - file size - SHA-256 - file path Those belong to Track Metadata. A WAV, FLAC and AIFF version of the same recording should produce nearly identical Music DNA. --- # System Architecture ``` Audio File │ ▼ Decoder │ ▼ Analysis Pipeline │ ▼ Feature Storage │ ├──────────────► Music DNA Builder │ │ │ ▼ │ Music DNA │ └──────────────► Embedding Builder │ ▼ AI Embedding ``` Music DNA and AI Embeddings are independent derived artifacts. --- # Fixed Vector Size Music DNA Version 1 always contains ``` 512 float32 values ``` Every vector has identical dimensionality. This size never changes during Schema Version 1. --- # Memory Footprint ``` 512 × float32 = 2048 bytes ``` Approximately ``` 2 KB ``` per track. --- # Block Layout | Block | Dimensions | |---------|-----------:| | Signal | 32 | | Spectral | 64 | | Dynamics | 64 | | Rhythm | 64 | | Harmony | 64 | | Timbre | 64 | | Structure | 64 | | Production | 64 | | Reserved | 32 | Total ``` 512 dimensions ``` --- # Block Allocation | Block | Index Range | |---------|------------:| | Signal | 0–31 | | Spectral | 32–95 | | Dynamics | 96–159 | | Rhythm | 160–223 | | Harmony | 224–287 | | Timbre | 288–351 | | Structure | 352–415 | | Production | 416–479 | | Reserved | 480–511 | --- # Block Responsibilities ## Signal Basic waveform characteristics. Examples - RMS - Peak - Silence Ratio --- ## Spectral Frequency-domain descriptors. Examples - Spectral Centroid - Roll-off - Flatness --- ## Dynamics Energy evolution over time. Examples - Dynamic Range - Crest Factor - Headroom --- ## Rhythm Temporal behaviour. Examples - Tempo - Beat Strength - Onset Density --- ## Harmony Pitch-related descriptors. Examples - Chroma - Tonnetz - Estimated Key --- ## Timbre Reserved for future analyzers. Possible features - MFCC - Bark bands - Spectral Contrast - Brightness - Roughness --- ## Structure Reserved for future analyzers. Possible features - Sections - Repetition - Novelty Curve - Phrase Detection --- ## Production Reserved for production-quality analysis. Possible features - Stereo Width - Loudness - LUFS - Limiter Activity - Compression - Reverb --- ## Reserved Unused. Must contain zeros. --- # Data Type Every dimension is stored as ``` float32 ``` No other numeric types are permitted. --- # Feature Registry Music DNA does not define individual features. Individual feature definitions are maintained separately in ``` docs/004a_FEATURE_REGISTRY.md ``` The registry specifies - identifiers - vector indices - analyzers - normalization - units --- # Missing Values Missing numeric values ``` NaN ``` Unused reserved dimensions ``` 0.0 ``` The builder must never silently replace missing values. --- # Explainability Every Music DNA dimension must be traceable to - analyzer - feature identifier - original value - normalized value The mapping must remain permanent. --- # Serialization Serialization order ``` Signal ↓ Spectral ↓ Dynamics ↓ Rhythm ↓ Harmony ↓ Timbre ↓ Structure ↓ Production ↓ Reserved ``` The order must never change. --- # Validation Before serialization the builder validates - schema version - duplicate identifiers - duplicate indices - unsupported feature types - unsupported normalization - vector length - analyzer compatibility Generation fails if validation fails. --- # Immutability Music DNA is immutable. Once generated it is never modified. If analyzer outputs change ↓ a completely new Music DNA object is generated. Historical Music DNA objects remain unchanged. --- # Versioning Every Music DNA object stores - schema_version - builder_version - created_at Future schema versions may coexist. --- # AI Embeddings Music DNA is not an embedding. Embeddings - are learned - may change - depend on ML models Music DNA - is deterministic - schema-driven - explainable - reproducible Both representations may coexist. --- # Stability Contract Music DNA Schema Version 1 guarantees - fixed dimensionality - fixed block ordering - fixed serialization - fixed block ranges Analyzer implementations may evolve. Normalization algorithms may evolve. DSP algorithms may evolve. The schema itself must not. --- # Compatibility Schema Version 1 vectors remain readable forever. Schema-breaking changes require ``` Music DNA Schema Version 2 ``` Migration must never overwrite historical Music DNA. --- # Architectural Rule Music DNA is the canonical musical representation inside AI MusiMuse. Similarity Recommendation Playlist Generation Clustering Dataset Export Visualization Generative AI must consume Music DNA. File-management components must consume Track Metadata. These responsibilities must never be mixed.