v3.0.0

1. Playback UI Stabilization (Flashing Fix)
   Positional Recomposition Fix: Stabilized the layout tree by wrapping the conditional Artist Background Layer in a dedicated Box in AppUI.kt. This ensures its insertion or removal doesn't shift the structural index of the primary UI Column.
   State Identity Fix: Assigned a precise contentKey = { it.id } to the AnimatedContent component mapping the album art. This anchors transitions strictly to the track identity rather than property updates (such as lyrics), preventing spurious transitions or flashing mid-playback.

2. Chameleon Volume Controls
   Created ChameleonVolumePopup.kt, which introduces a new custom volume slider popup overlay.
   This UI component natively hooks into your custom accent engine to dynamically match the volume slider's color to the currently playing album artwork or the selected app theme.

3. Permissions Modernization
   Updated PermissionHelper.kt and AndroidManifest.xml to properly handle Android 13+ (Tiramisu) strict permission boundaries.
   Added specific logic to request READ_MEDIA_AUDIO for modern devices instead of legacy generic storage permissions, and correctly configured POST_NOTIFICATIONS so the background MusicService can run properly without being killed by the system.

4. History & Analytics Polish
   Updated HistoryAnalyticsUI.kt to refine the listening statistics views and the "Year in Review" feature.
   Added sharing capabilities (a "COPY CARD" action) allowing users to easily share or save their listening persona and stats card.

5. Architecture & State Management
   Updated MusicViewModel.kt to wire up the new volume popup state and handle the new permission flows.
   Updated build.gradle.kts and libs.versions.toml to inject testing dependencies (like Robolectric and Roborazzi) and configure KSP (Kotlin Symbol Processing) to ensure the Room database and analytics queries compile optimally.

v2.7

v2.7 is here

**Changes and Fixes

1. Fix on indexing
2. Fix on artist background image parallax issue
3. Fix on last.fm sync
4. fix on settings tab
5. android notification issues fixed

**Things i forgot to fix

1. few more logic issues on settings
2. animation fixes on transitions
3. live wallpaperlayout
4. lockscreen
5. widgets

**Things i want to add on the next updates

1. everything listed on 2.0 release

v2.5

v2.5 is here

**Changes and Fixes

1. Metro UI & Design Engine

• Panoramic Hub Layout: Horizontal multi-pivot navigation spanning Now Playing, Get Started, Collection, Playlists, Analytics, Settings, and About with parallax scrolling.
• 3D Interactive Live Tiles: Motion-reactive tiles with spring physics, 3D touch tilt feedback, and haptics.
• Chameleon Accent Theme Engine: Real-time accent color extraction from playing album art using AndroidX Palette.
• Custom Metro Accents: Configurable classic accent presets (Metro Blue, Magenta, Lime Green, Orange, Royal Purple).
• Aurora Borealis Canvas: Dynamic animated background shader that responds to audio playback state.

2. Audio Engine & Sound Studio

• Media3 / ExoPlayer Core: High-performance local audio playback architecture with gapless playback support.
• Hardware 5-Band Equalizer & Reverb: Customizable frequency band sliders and acoustic environment presets (Hall, Room, Studio).
• Vaporwave & Nightcore Speed/Pitch FX:
• Vaporwave: 0.8x tempo and pitch shift for slowed ambient aesthetics.
• Nightcore: 1.3x tempo and pitch shift for high-energy playback.
• Normal: 1.0x native audio rate.
• Loudness Normalization (ReplayGain): LoudnessEnhancer integration to normalize track volume across dynamic ranges.
• Crossfade Transition Engine: Smooth track-to-track audio crossfading configurable from 1 to 12 seconds.
• USB DAC Passthrough: Auto-detection of external USB audio DACs with direct hardware bitstream routing.

3. Listening Analytics & Year in Review

• On-Device History Tracking: Local database logging of plays, durations, and timestamps via Room.
• Flexible Time Horizon Filters: Stats filtering by Day, Week, Month, Quarter, Year, and Lifetime.
• Hourly Listening Heatmaps: Detailed breakdown of listening habits by hour of the day with peak period classifications (e.g., Late Night, Morning, Evening).
• Personalized Year in Review: Interactive stat recap generating total listening minutes, top tracks/artists, and listener personas (Cyber Retro Archivist, Neon Synth Runner, Midnight Wave Cruiser).

4. Lyrics & Metadata Engine

• Synced .lrc Lyrics: Real-time auto-scrolling lyric view with timed highlights and network lyric lookup.
• Artist Biographies & Fanart: Auto-fetching artist background art, bios, album reviews, and similar artist recommendations via TheAudioDB & Last.fm API integrations.

5. Lockscreen, Controls & Utilities

• Metro Lockscreen Overlay: Custom lockscreen displaying time, current track metadata, album artwork, and swipe-to-unlock gesture controls.
• Mini Player Bar: Sticky bottom player bar with gesture swipe actions for fast track skipping.
• Sleep Timer: Auto-fade countdown timer to stop audio playback after a specified duration.
• Audio File Importer: Built-in system picker integration to batch import local audio files (audio/*).

6. Architecture & Tech Stack

• Language: 100% Kotlin with Coroutines & StateFlow.
• UI: Jetpack Compose with Material 3 integration.
• Persistence: Room Database (AppDatabase, MusicDao, MusicRepository).
• Audio Layer: Media3 ExoPlayer & Android System AudioEffects.

**Bugs that i forgot to fix and will be fixed on the next update:

1. Lockscreen feature is whack and not available yet
2. still lagging on start, im trying to find a fix for that
3. no widgets yet as im kinda lazy
4. UI consistecy fixes

**Recommendationss

IMPORTANT: Make sure to delete the old app version, if you just made an update on top of it, it will reindex the files and will duplicate everything.

v2.0

v2.0 is here

**Updated and New features

1. Metro Zune Design System & Live Tiles
   Metro Zune Aesthetic: Implemented a responsive Metro UI layout featuring dark high-contrast themes, bold display typography, and selectable accent color themes (Metro Blue, Magenta, Lime Green, Orange, and Royal Purple).
   Interactive Live Tiles: Added dynamic hub tiles on the main dashboard with animated album art flips, real-time playback badges, and quick access to pinned favorite tracks.
   Display Refresh Rate Optimization: Integrated automatic hardware display mode detection in MainActivity supporting Variable Refresh Rate (VRR) up to 120Hz for high-frame-rate scrolling and animations.

2. Core Audio Engine & Vaporwave/Nightcore FX
   ExoPlayer Background Service: Integrated MediaControllerService and MusicService with media session notifications for uninterrupted background playback.
   Custom Equalizer & DSP Effects: Built a 5-band custom equalizer with preset management, Bass Boost, 3D Audio Spatializer/Virtualizer, and Reverb controls using standard Android AudioEffects.
   Pitch & Speed Preset Modes: Added interactive playback pitch-shifting modes:
   Normal: Standard 1.0x playback.
   Vaporwave: 0.8x pitch & speed slow-down with retro acoustic warm filters.
   Nightcore: 1.3x pitch & speed acceleration with high-energy response.

3. History Analytics & "Year in Review"
   Listening Analytics Engine: Created an analytics system with customizable time filters (Past 24 Hours, 7 Days, 30 Days, and Lifetime) tracking total listening time, play counts, peak listening hours, and unique artist/album statistics.
   Year in Review ("Wrapped"): Built an interactive summary screen displaying annual listening milestones, top played songs, favorite artists, top albums, and genre distribution breakdowns.

4. Synced Lyrics & Metadata Enrichment
   LRC Synced Lyrics: Integrated an ID3/LRC lyrics tag parser with synchronized real-time line highlighting and auto-scrolling synced to track playback position.
   Last.fm & Artist Bio Integration: Built a metadata layer that fetches artist biographies, listener metrics, top tags, similar recommendations, and high-resolution band photos/fanart.

5. Room Database & Local Library Management
   Room Persistence (AppDatabase): Implemented local persistence using Room (MusicDao, MusicRepository) storing tracks, playlists, favorites, pinned tiles, and history logs.
   Local Audio Storage Importer: Integrated Storage Access Framework (SAF) file picker and tag parsing to import local audio files into user playlists and custom categories.

6. Metro Haptic Touch Engine
   Custom Haptic Feedback (MetroHaptic): Configured tactile feedback patterns for play/pause toggles, track scrubbing, tile selection, slider adjustments, and long-press menus.

Full Changelog: NEW...2.0

**Bugs that i forgot to fix and will be fixed on the next update:

1. Playlists Tab is practically useless as it is not connected to anything
2. ID3 tagging editor is meh and needs further exploration
3. Lockscreen feature is whack and not available yet
4. still lagging on start, im trying to find a fix for that
5. no widgets yet as im kinda lazy

**Things im supposed to add on the next version

1. Audiophile & Advanced Audio Processing
   These features are dedicated to high-fidelity audio playback, transparency, and technical precision.

• Audio Path Diagnostics: A dedicated technical overlay showing exactly what the audio pipeline is doing (e.g., File Format -> Custom DSP -> Resampler Bypass -> USB DAC Output Rate) so audiophiles can mathematically verify bit-perfect playback.
• Detailed Codec & File Info: Displaying exact bitrate, bit depth, encoder information, and the active Bluetooth codec (like LDAC or aptX) directly on the Now Playing screen.
• DSD to PCM Real-Time Conversion: For users with standard DACs who still want to play ultra-high-fidelity DSD (Direct Stream Digital) files, the engine can convert them to PCM in real-time without skipping a beat.

2. Network, Cloud, & Server Integration
   These statements relate to connecting the local player to external networks, personal servers, and internet streams.

• Hybrid Cloud/NAS Support: The ability to map local network drives (SMB/Samba, WebDAV) or personal media servers (Plex, Jellyfin, Audiobookshelf) to stream or cache alongside your strictly offline files.
• Audiobookshelf Support: Native integration to pull audiobooks and podcasts from a self-hosted Audiobookshelf server, cache them offline, and sync playback progress back to the server when reconnected.
• Smart Offline Caching: The ability to automatically cache songs from a personal home server (like Plex, Jellyfin, or Subsonic) or cloud storage (Google Drive, OneDrive) based on rules.
• Internet Radio Integration: The ability to save custom HTTP live streaming URLs for internet radio stations, integrating them directly alongside your local library.

3. Long-Form Audio (Audiobooks/Podcasts) & Navigation
   These features are essential for managing and navigating continuous mixes, podcasts, and audiobooks, rather than standard 3-minute songs.

• Bookmarks and Notes: Saving specific timestamps within a long audio file, which is perfect for podcasts, audiobooks, or long DJ sets.
• CUE Sheet Support: The ability to read .cue files to split a single large audio file (like a continuous CD rip, DJ mix, or concert) into distinct, navigable tracks.
• Chapter Support: Reading embedded chapter metadata in M4A, M4B, or MP3 files, allowing users to jump between sections of a long mix or audiobook rather than just skipping tracks.
• Custom Skip Intervals: Independent forward/backward skip buttons (e.g., jump back 15 seconds, jump forward 45 seconds) that are crucial for navigating podcasts.

4. Queue Management & Playback State
   These features focus on how the app remembers your place and manages different types of listening sessions simultaneously.

• Persistent Multi-Queues: Completely separating your music queue from your audiobook queue.
• Queue States per Folder: Remembering the exact playback position, playback speed, and shuffle state per folder or playlist, allowing you to seamlessly jump between a music playlist and an audiobook without losing your place.

5. Library Organization & Curation
   These statements deal with how the app scans, organizes, and automatically generates content from your local files.

• Folder Whitelisting/Blacklisting: Granular control over exactly which folders the app scans. This prevents the player from accidentally adding WhatsApp voice notes, video game sound effects, or ringtones into your music library.
• Composer & Classical Formatting: Dedicated library tabs for "Composer," "Conductor," and "Orchestra"—essential metadata for classical music listeners that standard players often ignore.
• Smart Mixes (Offline Algorithm): Generating personalized instant mixes based entirely on your local listening history and habits, mirroring streaming algorithms but processed completely on-device.

6. UI, Hardware Integration & Accessibility
   These features extend the player's controls beyond the main app interface, integrating with your car, lock screen, or external hardware.

• Android Auto Compatibility: A stripped-down, driving-safe user interface that integrates seamlessly with car dashboard displays.
• Advanced Bluetooth Controls: Customizing exactly what double, triple, or long-presses do on your wireless earbuds.
• Lock Screen Overrides: Full playback controls, lyrics display, and visualizers accessible without having to unlock the phone.

7. Built-in Utilities
   This is a standalone utility feature that edits audio files rather than just playing or organizing them.

• Ringtone Cutter: A built-in utility to trim a specific segment of a song and set it as a device ringtone or alarm.

v1.0

1.0 Release:

1. Metro / Zune Design & Customization
   Panoramic Panorama Hub: Smooth horizontal sliding layout (now playing, get started, collection, and playlists).
   Parallax Header: Dynamic "Maestro Music" typography header with smooth horizontal parallax motion while scrolling between tabs.
   3D Live Tiles: Interactive home screen tiles with 3D press-tilt feedback (zuneTiltClickable), spring physics, and periodic flip animations displaying total song count, now playing status, and pinned favorites.
   Chameleon Dynamic Accent Engine: Automatically extracts dominant vibrant accent colors from album cover art using the Android Palette API.
   Custom Accent Themes: Choice of classic Metro accent colors (Zune Blue, Magenta, Lime Green, Orange, and Royal Purple).
   Ambient Aurora & Artist Fanart: Dynamic Aurora Borealis shader backdrop crossfaded with artist wideback fanart loaded via TheAudioDB API.

2. Audio Playback Engine & Local Library
   ExoPlayer & Background Service: Full background playback support integrated with ZuneMusicService and Android MediaSession.
   Local Music Import: Native Storage Access Framework (SAF) document picker allowing users to import .mp3 and audio files directly from device storage.
   Database Persistence: Powered by Room DB for local storage of imported tracks, history, favorites, pinned items, and custom playlists.
   Alphabetical Jump List: Quick letter-grid matrix for fast navigation through large music collections.
   Sticky Mini Player: Bottom player bar with play/pause controls and swipe gesture support to skip to the next or previous track.

3. Now Playing, Synchronized Lyrics & Visualizer
   Fullscreen Now Playing View: High-resolution album artwork, progress seek bar, track queue management, and shuffle/repeat modes.
   Time-Synced LRC Lyrics Engine: Integrated LRC parser highlighting lyrics line-by-line in real time as the track plays.
   Online Lyric Fetcher: Automatic lyric fetching from the LRCLIB API for missing tracks.
   3D Wireframe Canvas Visualizer: Interactive real-time 3D wireframe audio visualizer rendered directly on canvas.
   Playback Speed Modes:
   Normal: 1.0x playback
   Vaporwave: 0.8x pitch and speed reduction
   Nightcore: 1.3x pitch and speed boost

4. Sound Studio (Audio FX)
   5-Band Graphic Equalizer: Custom slider frequency level controls (-15 dB to +15 dB gain).
   Reverb Presets: Environmental reverb simulation (Small Room, Medium Room, Large Hall, Plate).

5. AI Smart DJ (Gemini Integration)
   Mood & Vibe Playlist Generator: Generates custom atmospheric song recommendations based on user prompts (e.g. "chill sunset", "retro hype", "night drive") using the Google Gemini API (gemini-3.5-flash).
   Offline Fallback: Offline fallback generator if no API key is configured or network is unavailable.

6. Collection, Playlists & History
   Custom Playlists: Create custom named playlists and assign songs.
   Pinned Tracks Shelf: Pin favorite songs/albums directly onto the Get Started home grid.
   Favorites Library: Mark songs as favorites with a dedicated full-page view.
   Playback History: Dedicated timeline view tracking recently played songs.

7. System Utilities & Lock Screen
   Zune Lock Screen Overlay: Metro-style lock screen featuring gesture swipe-up to unlock, live digital clock/date display, Now Playing widget, and ambient glow.
   Sleep Timer: Timed auto-stop durations (15m, 30m, 60m) featuring a 20-second gradual volume fade-out before pausing.
   First-Launch Onboarding: Welcome screen guiding new users to select local music files on first launch.
   Haptic Feedback: Tactile haptic feedback on button clicks, long presses, tile flips, and navigation tabs.