Merge pull request #1112 from OxygenCobalt/dev

v4.0.5

Author: OxygenCobalt

AGENT.md

@@ -0,0 +1 @@
+CLAUDE.md

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 4.0.5
+
+#### What's Improved
+- Re-added folder exclusion
+
+#### What's Fixed
+- Fixed slow loading on large libraries
+
 ## 4.0.3
 
 #### What's Improved

CLAUDE.md

@@ -0,0 +1,123 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Auxio is a modern Android music player written in Kotlin that emphasizes simplicity and performance. It uses Media3 ExoPlayer for playback and includes a custom native music indexing library called musikr.
+
+## Build System & Commands
+
+### Prerequisites
+- `cmake` and `ninja-build` must be installed before building
+- Project uses git submodules - clone with `git clone --recurse-submodules`
+- **Cannot build on Windows** - requires Unix-based system for Media3 build scripts
+
+### Common Build Commands
+```bash
+# Build debug version
+./gradlew assembleDebug
+
+# Build release version  
+./gradlew assembleRelease
+
+# Run tests
+./gradlew test
+
+# Run connected tests
+./gradlew connectedAndroidTest
+
+# Code formatting (Spotless)
+./gradlew spotlessApply
+
+# Check code formatting
+./gradlew spotlessCheck
+```
+
+### Development Modules
+- `app/` - Main Android application
+- `musikr/` - Native music indexing library with TagLib integration
+- `media/` - Patched Media3 ExoPlayer libraries (git submodule)
+
+## Architecture Overview
+
+### Core Architecture Pattern
+- **MVVM** with ViewModels for each major screen (Home, Detail, Playback, Search)
+- **Repository Pattern** - MusicRepository as single source of truth for music data
+- **Dependency Injection** - Hilt/Dagger for modular dependency management
+- **Single Activity Architecture** with Navigation Components
+- **Service-Oriented** background music processing
+
+### Key Modules & Components
+
+#### Music Management (`app/src/main/java/org/oxycblt/auxio/music/`)
+- `MusicRepository` - Central music library state management
+- `MusicViewModel` - UI layer for music data access
+- `service/` - MediaBrowserServiceCompat integration
+- `shim/` - Abstraction layer for musikr integration
+
+#### Playback Engine (`app/src/main/java/org/oxycblt/auxio/playback/`)
+- `PlaybackViewModel` - Main playback UI interface
+- `PlaybackStateManager` - Core playback state management
+- `service/` - Background ExoPlayer integration
+- `queue/` - Playback queue management
+- `persist/` - Playback state persistence (Room database)
+- `replaygain/` - Audio processing for volume normalization
+
+#### UI Structure (`app/src/main/java/org/oxycblt/auxio/`)
+- `home/` - Main library browsing with customizable tabs
+- `detail/` - Album, artist, genre, and playlist detail views
+- `search/` - Music search functionality
+- `list/` - Shared list components with sorting/filtering
+- `ui/` - Custom UI components, theming, animations
+
+#### Native Music Library (`musikr/`)
+- **Pipeline-based indexing** - Multi-stage scanning (Explore → Extract → Evaluate)
+- **TagLib integration** - Native C++ metadata extraction
+- **File system caching** - Device storage access optimization
+- **Cover art management** - Embedded and external cover support
+
+### Data Flow
+1. musikr scans and indexes music files from device storage
+2. MusicRepository manages indexed library and exposes to UI
+3. ViewModels provide reactive state for UI components using StateFlow
+4. PlaybackService handles audio playback via ExoPlayer
+5. UI observes ViewModels and updates reactively
+
+## Code Conventions
+
+### Language & Libraries
+- **Kotlin** - Primary language with coroutines for async operations
+- **Hilt/Dagger** - Dependency injection
+- **Room** - Local database for persistence
+- **Navigation Components** - Fragment navigation
+- **ViewBinding** - Type-safe view access
+- **StateFlow/LiveData** - Reactive state management
+- **Coil** - Image loading for cover art
+
+### Code Style
+- Uses Spotless with ktfmt Dropbox style formatting
+- License header required (see NOTICE file)
+- C++ code uses Eclipse CDT formatting (eclipse-cdt.xml)
+
+## Testing
+
+### Test Structure
+- Unit tests: `src/test/` directories
+- Integration tests: `src/androidTest/` directories
+- musikr module includes Robolectric tests
+
+### Test Dependencies
+- JUnit 4 for unit testing
+- MockK for mocking
+- Robolectric for Android unit tests
+- Espresso for UI tests
+
+## Key Development Notes
+
+- **Custom Media3**: Uses patched Media3 ExoPlayer for enhanced playback features
+- **Native Dependencies**: musikr module builds TagLib from source during compilation
+- **Permission Handling**: Requires storage permissions for music file access
+- **Background Services**: Foreground service for continuous music playback
+- **Widget Support**: Multiple widget layouts with automatic sizing adaptation
+- **ReplayGain**: Full support for MP3, FLAC, OGG, OPUS, and MP4 files

README.md

@@ -2,8 +2,8 @@
 <h1 align="center"><b>Auxio</b></h1>
 <h4 align="center">A simple, rational music player for android.</h4>
 <p align="center">
-    <a href="https://github.com/oxygencobalt/Auxio/releases/tag/v4.0.4">
-        <img alt="Latest Version" src="https://img.shields.io/static/v1?label=tag&message=v4.0.4&color=64B5F6&style=flat">
+    <a href="https://github.com/oxygencobalt/Auxio/releases/tag/v4.0.5">
+        <img alt="Latest Version" src="https://img.shields.io/static/v1?label=tag&message=v4.0.5&color=64B5F6&style=flat">
     </a>
     <a href="https://github.com/oxygencobalt/Auxio/releases/">
         <img alt="Releases" src="https://img.shields.io/github/downloads/OxygenCobalt/Auxio/total.svg?color=4B95DE&style=flat">

app/build.gradle

@@ -18,8 +18,8 @@ android {
 
     defaultConfig {
         applicationId namespace
-        versionName "4.0.4"
-        versionCode 63
+        versionName "4.0.5"
+        versionCode 64
 
         minSdk min_sdk
         targetSdk target_sdk

app/src/main/java/org/oxycblt/auxio/music/MusicRepository.kt

@@ -29,6 +29,7 @@ import kotlinx.coroutines.withContext
 import kotlinx.coroutines.yield
 import org.oxycblt.auxio.image.covers.SettingCovers
 import org.oxycblt.auxio.music.MusicRepository.IndexingWorker
+import org.oxycblt.auxio.music.shim.WriteOnlyFileTreeCache
 import org.oxycblt.auxio.music.shim.WriteOnlyMutableCache
 import org.oxycblt.musikr.IndexingProgress
 import org.oxycblt.musikr.Interpretation
@@ -37,9 +38,11 @@ import org.oxycblt.musikr.Music
 import org.oxycblt.musikr.Musikr
 import org.oxycblt.musikr.MutableLibrary
 import org.oxycblt.musikr.Playlist
+import org.oxycblt.musikr.Query
 import org.oxycblt.musikr.Song
 import org.oxycblt.musikr.Storage
 import org.oxycblt.musikr.cache.MutableCache
+import org.oxycblt.musikr.fs.device.FileTreeCache
 import org.oxycblt.musikr.playlist.db.StoredPlaylists
 import org.oxycblt.musikr.tag.interpret.Naming
 import org.oxycblt.musikr.tag.interpret.Separators
@@ -385,16 +388,20 @@ constructor(
                 Naming.simple()
             }
         val locations = musicSettings.musicLocations
+        val excludedLocations = musicSettings.excludedLocations
         val withHidden = musicSettings.withHidden
 
         val currentRevision = musicSettings.revision
         val newRevision = currentRevision?.takeIf { withCache } ?: UUID.randomUUID()
         val cache = if (withCache) cache else WriteOnlyMutableCache(cache)
         val covers = settingCovers.mutate(context, newRevision)
-        val storage = Storage(cache, covers, storedPlaylists)
+        val fileTreeCache =
+            if (withCache) FileTreeCache.from(context)
+            else WriteOnlyFileTreeCache(FileTreeCache.from(context))
+        val query = Query(source = locations, exclude = excludedLocations)
+        val storage = Storage(cache, covers, storedPlaylists, fileTreeCache)
         val interpretation = Interpretation(nameFactory, separators, withHidden)
-        val result =
-            Musikr.new(context, storage, interpretation).run(locations, ::emitIndexingProgress)
+        val result = Musikr.new(context, storage, interpretation).run(query, ::emitIndexingProgress)
         // Music loading completed, update the revision right now so we re-use this work
         // later.
         musicSettings.revision = newRevision

app/src/main/java/org/oxycblt/auxio/music/MusicSettings.kt

@@ -20,12 +20,13 @@ package org.oxycblt.auxio.music
 
 import android.content.Context
 import androidx.core.content.edit
+import androidx.core.net.toUri
 import dagger.hilt.android.qualifiers.ApplicationContext
 import java.util.UUID
 import javax.inject.Inject
 import org.oxycblt.auxio.R
 import org.oxycblt.auxio.settings.Settings
-import org.oxycblt.musikr.fs.MusicLocation
+import org.oxycblt.musikr.fs.Location
 import timber.log.Timber as L
 
 /**
@@ -37,7 +38,9 @@ interface MusicSettings : Settings<MusicSettings.Listener> {
     /** The current library revision. */
     var revision: UUID?
     /** The locations of music to load. */
-    var musicLocations: List<MusicLocation>
+    var musicLocations: List<Location.Opened>
+    /** The locations to exclude from music loading. */
+    var excludedLocations: List<Location.Unopened>
     /** Whether to exclude non-music audio files from the music library. */
     val excludeNonMusic: Boolean
     /** Whether to ignore hidden files and directories during music loading. */
@@ -74,24 +77,39 @@ class MusicSettingsImpl @Inject constructor(@ApplicationContext private val cont
             }
         }
 
-    override var musicLocations: List<MusicLocation>
+    override var musicLocations: List<Location.Opened>
         get() {
             val locations =
                 sharedPreferences.getString(getString(R.string.set_key_music_locations), null)
                     ?: return emptyList()
-            return MusicLocation.existing(context, locations)
+            return locations.toOpenedLocations()
         }
         set(value) {
             sharedPreferences.edit {
-                putString(
-                    getString(R.string.set_key_music_locations), MusicLocation.toString(value))
+                putString(getString(R.string.set_key_music_locations), value.stringify())
                 commit()
                 // Sometimes changing this setting just won't actually trigger the listener.
                 // Only this one. No idea why.
                 listener?.onMusicLocationsChanged()
             }
         }
 
+    override var excludedLocations: List<Location.Unopened>
+        get() {
+            val locations =
+                sharedPreferences.getString(getString(R.string.set_key_excluded_locations), null)
+                    ?: return emptyList()
+            return locations.toUnopenedLocations()
+        }
+        set(value) {
+            sharedPreferences.edit {
+                putString(
+                    getString(R.string.set_key_excluded_locations), value.stringifyLocations())
+                commit()
+                listener?.onMusicLocationsChanged()
+            }
+        }
+
     override val excludeNonMusic: Boolean
         get() = sharedPreferences.getBoolean(getString(R.string.set_key_exclude_non_music), true)
 
@@ -119,7 +137,8 @@ class MusicSettingsImpl @Inject constructor(@ApplicationContext private val cont
         // TODO: Differentiate "hard reloads" (Need the cache) and "Soft reloads"
         //  (just need to manipulate data)
         when (key) {
-            getString(R.string.set_key_music_locations) -> {
+            getString(R.string.set_key_music_locations),
+            getString(R.string.set_key_excluded_locations) -> {
                 L.d("Dispatching music locations change")
                 listener.onMusicLocationsChanged()
             }
@@ -136,4 +155,55 @@ class MusicSettingsImpl @Inject constructor(@ApplicationContext private val cont
             }
         }
     }
+
+    private fun List<Location.Opened>.stringify(): String =
+        joinToString(separator = ";") { it.uri.toString().replace(";", "\\;") }
+
+    private fun String.toOpenedLocations(): List<Location.Opened> =
+        splitEscaped { it == ';' }
+            .mapNotNull { Location.Unopened.from(context, it.toUri())?.open(context) }
+
+    private fun List<Location>.stringifyLocations(): String =
+        joinToString(separator = ";") { it.uri.toString().replace(";", "\\;") }
+
+    private fun String.toUnopenedLocations(): List<Location.Unopened> =
+        splitEscaped { it == ';' }.mapNotNull { Location.Unopened.from(context, it.toUri()) }
+
+    private inline fun String.splitEscaped(selector: (Char) -> Boolean): List<String> {
+        val split = mutableListOf<String>()
+        var currentString = ""
+        var i = 0
+
+        while (i < length) {
+            val a = get(i)
+            val b = getOrNull(i + 1)
+
+            if (selector(a)) {
+                // Non-escaped separator, split the string here, making sure any stray whitespace
+                // is removed.
+                split.add(currentString)
+                currentString = ""
+                i++
+                continue
+            }
+
+            if (b != null && a == '\\' && selector(b)) {
+                // Is an escaped character, add the non-escaped variant and skip two
+                // characters to move on to the next one.
+                currentString += b
+                i += 2
+            } else {
+                // Non-escaped, increment normally.
+                currentString += a
+                i++
+            }
+        }
+
+        if (currentString.isNotEmpty()) {
+            // Had an in-progress split string that is now terminated, add it.
+            split.add(currentString)
+        }
+
+        return split
+    }
 }