Developer Technical Guide

In-depth architectural breakdown, package layout, Jetpack Compose UI state flow, Media3 playback pipeline, Room DB schemas, and extension points for Android developers.

1. Project Source Directory Mapping

Nova Music is organized cleanly under app/src/main/java/com/example/ following Clean MVVM conventions:

Source Code Directory Structure

app/src/main/java/com/example/
├── MainActivity.kt                     # Single Activity host & edge-to-edge Compose entry
├── model/
│   ├── AudioEqualizerState.kt          # Equalizer frequency bands & FX data models
│   ├── MusicModels.kt                  # Song, Album, Artist, Playlist, Folder entities
│   └── LyricsModels.kt                 # LrcLine & SyncedLyricsState models
├── player/
│   ├── MusicService.kt                 # AndroidX Media3 MediaSessionService & Notification
│   └── PlaybackManager.kt              # ExoPlayer wrapper, queue, speed/pitch, sleep timer
├── data/
│   ├── db/
│   │   ├── NovaDatabase.kt             # Room Database instance ("nova_musique_db")
│   │   ├── MusicEntities.kt            # Room entities (Favorites, Playlists, PlayCounts)
│   │   ├── MusicDao.kt                 # DAO queries for playlists & favorites
│   │   └── LocalAudioDao.kt            # DAO queries for indexed audio files
│   └── repository/
│       ├── MusicRepository.kt          # Playlist & favorite track orchestration
│       ├── LocalAudioRepository.kt     # MediaStore query & duplicate audio hash scanner
│       ├── LyricsRepository.kt         # LrcLib REST API client & local LRC cache
│       └── SettingsRepository.kt       # Theme, language, EQ preferences state
├── util/
│   ├── LrcParser.kt                    # Synchronized LRC timestamp parser ([mm:ss.xx])
│   └── AdManager.kt                    # AdMob banner & interstitial lifecycle controller
└── ui/
    ├── components/                     # Reusable Compose components
    │   ├── SongArtworkImage.kt         # Vector artwork fallback & Coil image loader
    │   ├── AudioVisualizer.kt          # Real-time audio waveform canvas
    │   ├── EqualizerCurveCanvas.kt     # Smooth frequency response curve painter
    │   ├── SyncedLyricsDisplay.kt      # Karaoke-style lyrics line highlight component
    │   └── AdBannerView.kt             # Composable wrapper for AdMob AdView
    ├── screens/                        # Primary screen Composables
    │   ├── HomeScreen.kt               # Hero banner, quick play, recent tracks
    │   ├── LibraryScreen.kt            # Tracks, Playlists, Albums, Artists, Folders
    │   ├── PlayerScreen.kt             # Full screen player, vinyl artwork, lyrics sheet
    │   ├── EqualizerScreen.kt          # 10-Band EQ, Bass Boost, Virtualizer, Reverb
    │   ├── DuplicateFinderScreen.kt    # Duplicate audio scanner utility
    │   ├── SettingsScreen.kt           # Themes, languages, legal pages, ad switches
    │   └── LegalPagesScreen.kt         # Terms of Service & Privacy Policy pages
    ├── theme/                          # Theme, Color palettes, Typography, Shapes
    └── i18n/                           # Multilingual string dictionary

2. Media3 ExoPlayer & Background Playback

Background audio playback is powered by AndroidX Media3 (MusicService.kt). The playback manager exposes state via Kotlin StateFlow:

Playback State Binding Example

// Subscribing to playback state in Jetpack Compose
val currentSong by playbackManager.currentSong.collectAsStateWithLifecycle()
val isPlaying by playbackManager.isPlaying.collectAsStateWithLifecycle()
val currentPosition by playbackManager.currentPositionMs.collectAsStateWithLifecycle()

// Controlling playback from UI
playbackManager.playPause()
playbackManager.seekTo(positionMs)
playbackManager.setPlaybackSpeed(1.25f)
playbackManager.setSleepTimer(30) // minutes

3. 10-Band DSP Equalizer Pipeline

The 10-Band Equalizer (EqualizerManager.kt) interacts directly with Android AudioEffect APIs (Equalizer, BassBoost, PresetReverb, Virtualizer):

4. Room Database Persistence

The local database (NovaDatabase.kt) manages favorites, playlists, and listening statistics offline without needing external servers:

NovaDatabase.kt Schema

@Database(
    entities = [
        FavoriteEntity::class,
        PlaylistEntity::class,
        PlaylistSongCrossRef::class,
        ListeningHistoryEntity::class,
        SongPlayCountEntity::class
    ],
    version = 2,
    exportSchema = false
)
abstract class NovaDatabase : RoomDatabase() {
    abstract fun musicDao(): MusicDao
    abstract fun localAudioDao(): LocalAudioDao
}

5. How to Extend Nova Music

Add New Color Theme: Add an entry to ThemeType enum in Theme.kt and define your primary, secondary, and background colors.
Add New Language: Extend AppLanguage enum in StringResources.kt and provide translated string constants.
Add New Audio Format: Update supported extensions in LocalAudioRepository.kt (.mp3, .flac, .m4a, .wav, .ogg).

Third-Party Services Notice

Third-Party Services Notice: Nova Music may use third-party services such as Google AdMob for advertising. These services are provided by external providers and may require separate configuration and/or accounts. Any third-party service costs, policies, API requirements, or account requirements are the responsibility of the buyer and are not included with the source code purchase.