# TASK-003 ## Title Audio Decoder and Metadata Extraction --- ## Objective Implement the audio decoding layer according to **SPEC.md**. This task introduces the ability to decode supported audio files into a normalized PCM representation and extract basic technical metadata. No DSP analysis should be implemented. --- # Expected Commit Message Add audio decoder and metadata extraction --- # Requirements Before writing any code: * Read **SPEC.md** * Read **AI_DEVELOPER_GUIDE.md** * Read **PROJECT_PRINCIPLES.md** If architectural uncertainty exists, stop and ask. Do not guess. --- # Architecture ```text Track ↓ Decoder ↓ DecodedAudio ↓ Metadata ↓ Repository ↓ SQLite ``` The Decoder reads audio files. It does not analyze music. It only converts audio into a normalized internal representation. --- # Scope Implement the following modules. --- ## Decoder Create AudioDecoder Responsibilities * open supported audio files * decode audio * normalize sample format * return DecodedAudio * extract technical metadata The Decoder must not calculate any DSP features. The Decoder must not calculate tempo. The Decoder must not calculate key. The Decoder must not calculate loudness. --- ## DecodedAudio Create an immutable object. Required fields * samples * sample_rate * channels * duration * bit_depth Requirements * frozen dataclass * read-only * no SQLAlchemy dependency --- ## Metadata Extraction Extract * duration * sample rate * channel count * bit depth * file size (already known if needed) Nothing else. No musical information. --- ## Database Update Track records with * duration * sample_rate * channels * bit_depth Do not modify * SHA-256 * path * filename --- # Supported Formats Support * WAV * FLAC * AIFF * AIF Only formats supported by the decoder library. --- # Decoder Backend Use **PyAV (FFmpeg)** as the decoding backend. The implementation should remain isolated behind the `AudioDecoder` interface. Future decoder implementations should be replaceable without changing application code. --- # Normalization Decoded audio should be normalized to * float32 * range [-1.0, 1.0] Multi-channel audio must preserve channel count. Do not convert stereo to mono. Do not resample audio. Original sample rate must be preserved. --- # Repository Create DecoderRepository Responsibilities * update metadata * query tracks without metadata Business logic must not execute SQL directly. --- # CLI Extend the Typer CLI. Add one command ```text decode ``` The command should * load settings * initialize logging * initialize database * decode tracks without metadata * store metadata * print a short summary The CLI must remain a thin orchestration layer. --- # Logging Log * decoder started * decoding file * decoding failed * metadata stored * decoder finished Avoid verbose logging. --- # Error Handling Corrupted files must never terminate the decoding process. Log the error. Continue decoding remaining files. --- # Forbidden Do NOT * calculate BPM * calculate tempo * calculate key * calculate loudness * calculate RMS * calculate LUFS * calculate spectrum * calculate chroma * calculate MFCC * calculate Music DNA * calculate embeddings * calculate similarity * create recommendations --- # Testing Required tests * WAV decoding * FLAC decoding * AIFF decoding * metadata extraction * stereo preservation * mono preservation * duration calculation * unsupported file handling * corrupted file handling * repository updates Tests must be deterministic. --- # Quality Requirements All code must * use type hints * contain Google-style docstrings * follow PEP-8 * pass Ruff * pass Black * pass isort * pass pytest --- # Deliverables At the end of this task the project must * decode supported audio files * produce immutable DecodedAudio objects * extract technical metadata * store metadata in SQLite * provide a decode CLI command No musical analysis should exist. --- # Definition of Done The task is complete only if ✓ supported files decode successfully ✓ immutable DecodedAudio objects are produced ✓ duration is extracted ✓ sample rate is extracted ✓ channel count is extracted ✓ bit depth is extracted ✓ metadata is stored in SQLite ✓ corrupted files do not stop processing ✓ tests pass ✓ Ruff passes ✓ Black passes ✓ isort passes Nothing else should be implemented.