Feat/audio export

PULL_REQUEST_DESCRIPTION.md

@@ -0,0 +1,37 @@
+# feat(export): add public audio exporter and playlist search
+
+## Problem
+1. Users were unable to export/download standalone audio files (`.mp3`/`.m4a`) to public device storage (`Music/Metrolist`) for playback in external media players or PC file transfers.
+2. Duplicate songs appeared in library lists, artist song lists, album song lists, and queue continuations due to missing SQL query DISTINCT clauses and lack of metadata deduplication.
+3. Users lacked the ability to search for saved playlists in the Library Playlists tab and filter songs inside open playlists.
+
+## Cause
+1. In-app downloads were stored in ExoPlayer's private sandboxed cache directory (`/data/data/com.metrolist...`), making files inaccessible to external apps.
+2. SQL queries joining relational mapping tables (`song_artist_map` and `song_album_map`) without `DISTINCT` clauses returned multiple duplicate `Song` rows when a track was linked to multiple artists or albums.
+3. `PlaylistsViewModel` and `LocalPlaylistViewModel` did not expose debounced search query flows or normalized text matching filters.
+
+## Solution
+1. **Public Audio Exporter (`LatikeshExporter.kt`):**
+   * Implemented `LatikeshExporter.exportToPublicStorage(...)` which resolves playback audio stream, streams audio bytes with a 16KB buffer on `Dispatchers.IO`, and saves files to `Environment.DIRECTORY_MUSIC + "/Metrolist"` via `MediaStore.Audio.Media`.
+   * Added an existing file check (`isAudioFileAlreadyExported`) to prevent duplicate file downloads.
+   * Added live progress notifications in the notification shade using `NotificationCompat.Builder`.
+   * Added **"Export audio to public storage"** option with storage icon to `SongMenu.kt`.
+
+2. **Deduplication Fixes (`DatabaseDao.kt`, `ListExt.kt`, `LibraryViewModels.kt`, `YouTubeQueue.kt`):**
+   * Added `DISTINCT` to SQL queries in `DatabaseDao.kt` (`albumSongs`, `artistSongsByCreateDateAsc`, `artistSongsByNameAsc`, `artistSongsByPlayTimeAsc`, `artistSongsPreview`).
+   * Implemented smart metadata fingerprinting (`deduplicationKey()`) and `deduplicateSongs()` in `ListExt.kt`.
+   * Applied `.deduplicateSongs()` across all song list flows in `LibraryViewModels.kt`.
+   * Applied `.distinctBy { it.mediaId }` to initial queue and pagination items in `YouTubeQueue.kt`.
+
+3. **Playlist Search Features (`PlaylistsViewModel.kt`, `LocalPlaylistViewModel.kt`, `LibraryPlaylistsScreen.kt`):**
+   * Added `searchQuery` and `debouncedSearchQuery` filtering using `matchesNormalizedQuery` in `PlaylistsViewModel.kt` and `LocalPlaylistViewModel.kt`.
+
+## Testing
+- [x] **Gradle Build:** Verified compilation using `./gradlew :app:assembleFossDebug` (`BUILD SUCCESSFUL`).
+- [x] **Device Deployment:** Installed and tested on connected device (`SM-E156B`).
+- [x] **Export Verification:** Verified audio file exporting to `Music/Metrolist` with live notification progress bar.
+- [x] **Existing File Detection:** Verified that attempting to export an already saved song skips downloading and displays `"File already exists in Music/Metrolist"`.
+- [x] **UI Performance:** Verified zero UI freeze or stutter during audio export.
+
+## Related Issues
+None

app/src/main/kotlin/com/metrolist/music/db/DatabaseDao.kt

@@ -246,13 +246,27 @@ interface DatabaseDao {
     @Query("SELECT COUNT(1) FROM song WHERE liked")
     fun likedSongsCount(): Flow<Int>
 
+    /**
+     * Retrieves unique songs belonging to an album.
+     *
+     * @param albumId Album identifier.
+     * @return Flow emitting list of unique album songs.
+     */
     @Transaction
-    @Query("SELECT song.* FROM song JOIN song_album_map ON song.id = song_album_map.songId WHERE song_album_map.albumId = :albumId")
+    @Query("SELECT DISTINCT song.* FROM song JOIN song_album_map ON song.id = song_album_map.songId WHERE song_album_map.albumId = :albumId")
     fun albumSongs(albumId: String): Flow<List<Song>>
 
+    /**
+     * Retrieves a paginated list of unique songs belonging to an album.
+     *
+     * @param albumId Album identifier.
+     * @param limit Maximum number of songs to fetch.
+     * @param offset Offset index for pagination.
+     * @return List of unique album songs.
+     */
     @Transaction
     @Query(
-        "SELECT song.* FROM song JOIN song_album_map ON song.id = song_album_map.songId " +
+        "SELECT DISTINCT song.* FROM song JOIN song_album_map ON song.id = song_album_map.songId " +
             "WHERE song_album_map.albumId = :albumId " +
             "ORDER BY song_album_map.`index`, song.rowId LIMIT :limit OFFSET :offset",
     )
@@ -281,32 +295,69 @@ interface DatabaseDao {
     )
     fun songsInBookmarkedPlaylists(): Flow<List<Song>>
 
+    /**
+     * Retrieves unique artist songs ordered by library addition date ascending.
+     *
+     * @param artistId Artist identifier.
+     * @return Flow emitting list of unique artist songs.
+     */
     @Transaction
     @Query(
-        "SELECT song.* FROM song_artist_map JOIN song ON song_artist_map.songId = song.id WHERE artistId = :artistId AND inLibrary IS NOT NULL ORDER BY inLibrary",
+        "SELECT DISTINCT song.* FROM song_artist_map JOIN song ON song_artist_map.songId = song.id WHERE artistId = :artistId AND inLibrary IS NOT NULL ORDER BY inLibrary",
     )
     fun artistSongsByCreateDateAsc(artistId: String): Flow<List<Song>>
 
+    /**
+     * Retrieves a paginated list of unique artist songs ordered by creation date ascending.
+     *
+     * @param artistId Artist identifier.
+     * @param limit Maximum number of songs.
+     * @param offset Offset index.
+     * @return List of unique artist songs.
+     */
     @Transaction
     @Query(
-        "SELECT song.* FROM song_artist_map JOIN song ON song_artist_map.songId = song.id " +
+        "SELECT DISTINCT song.* FROM song_artist_map JOIN song ON song_artist_map.songId = song.id " +
             "WHERE artistId = :artistId AND inLibrary IS NOT NULL " +
             "ORDER BY inLibrary, song.rowId LIMIT :limit OFFSET :offset",
     )
     suspend fun artistSongsByCreateDateAsc(artistId: String, limit: Int, offset: Int): List<Song>
 
+    /**
+     * Retrieves unique artist songs ordered by title ascending.
+     *
+     * @param artistId Artist identifier.
+     * @return Flow emitting list of unique artist songs.
+     */
     @Transaction
     @Query(
-        "SELECT song.* FROM song_artist_map JOIN song ON song_artist_map.songId = song.id WHERE artistId = :artistId AND inLibrary IS NOT NULL ORDER BY title",
+        "SELECT DISTINCT song.* FROM song_artist_map JOIN song ON song_artist_map.songId = song.id WHERE artistId = :artistId AND inLibrary IS NOT NULL ORDER BY title",
     )
     fun artistSongsByNameAsc(artistId: String): Flow<List<Song>>
 
+    /**
+     * Retrieves unique artist songs ordered by total play time ascending.
+     *
+     * @param artistId Artist identifier.
+     * @return Flow emitting list of unique artist songs.
+     */
     @Transaction
     @Query(
-        "SELECT song.* FROM song_artist_map JOIN song ON song_artist_map.songId = song.id WHERE artistId = :artistId AND inLibrary IS NOT NULL ORDER BY totalPlayTime",
+        "SELECT DISTINCT song.* FROM song_artist_map JOIN song ON song_artist_map.songId = song.id WHERE artistId = :artistId AND inLibrary IS NOT NULL ORDER BY totalPlayTime",
     )
     fun artistSongsByPlayTimeAsc(artistId: String): Flow<List<Song>>
 
+    /**
+     * Retrieves unique artist songs sorted by specified sort type and order.
+     *
+     * @param artistId Artist identifier.
+     * @param sortType Sort criterion (Create date, Name, Play time).
+     * @param descending True for descending sort, false for ascending.
+     * @param fromTimeStamp Optional start timestamp.
+     * @param toTimeStamp Optional end timestamp.
+     * @param limit Optional limit for number of results.
+     * @return Flow emitting sorted list of unique artist songs.
+     */
     fun artistSongs(
         artistId: String,
         sortType: ArtistSongSortType,
@@ -357,9 +408,16 @@ interface DatabaseDao {
     )
     fun mostPlayedSongsByArtist(artistId: String, fromTimeStamp: LocalDateTime, toTimeStamp: LocalDateTime): Flow<List<Song>>
 
+    /**
+     * Retrieves a preview list of unique artist songs.
+     *
+     * @param artistId Artist identifier.
+     * @param previewSize Number of preview songs to return.
+     * @return Flow emitting list of unique preview songs.
+     */
     @Transaction
     @Query(
-        "SELECT song.* FROM song_artist_map JOIN song ON song_artist_map.songId = song.id WHERE artistId = :artistId AND inLibrary IS NOT NULL LIMIT :previewSize",
+        "SELECT DISTINCT song.* FROM song_artist_map JOIN song ON song_artist_map.songId = song.id WHERE artistId = :artistId AND inLibrary IS NOT NULL LIMIT :previewSize",
     )
     fun artistSongsPreview(
         artistId: String,

app/src/main/kotlin/com/metrolist/music/extensions/ListExt.kt

@@ -50,3 +50,26 @@ fun List<Playlist>.filterYoutubeShorts(enabled: Boolean = false) =
     } else {
         this
     }
+
+private val songNoiseRegex = Regex("(?i)\\(official.*?\\)|\\[official.*?]|\\(audio\\)|\\(lyric.*?\\)|official video|official audio|4k|hd")
+
+/**
+ * Computes a normalized smart metadata fingerprint key for a song to detect duplicate uploads.
+ *
+ * @return Normalized fingerprint string based on title, primary artist, and duration bucket.
+ */
+fun Song.deduplicationKey(): String {
+    val cleanTitle = song.title
+        .replace(songNoiseRegex, "")
+        .normalizeForSearch()
+    val primaryArtist = orderedArtists.firstOrNull()?.name?.normalizeForSearch() ?: ""
+    val durationBucket = if (song.duration > 0) song.duration / 3 else 0
+    return if (cleanTitle.isBlank()) song.id else "$cleanTitle|$primaryArtist|$durationBucket"
+}
+
+/**
+ * Extension function to deduplicate a list of songs using smart metadata fingerprinting.
+ *
+ * @return List of unique songs with duplicate uploads removed.
+ */
+fun List<Song>.deduplicateSongs(): List<Song> = distinctBy { it.deduplicationKey() }

app/src/main/kotlin/com/metrolist/music/playback/queues/YouTubeQueue.kt

@@ -13,6 +13,12 @@ import com.metrolist.music.models.MediaMetadata
 import kotlinx.coroutines.Dispatchers.IO
 import kotlinx.coroutines.withContext
 
+/**
+ * Queue implementation for YouTube Music player streams and radio queues.
+ *
+ * @property endpoint Initial watch endpoint.
+ * @property preloadItem Optional preloaded media metadata.
+ */
 class YouTubeQueue(
     private var endpoint: WatchEndpoint,
     override val preloadItem: MediaMetadata? = null,
@@ -23,6 +29,11 @@ class YouTubeQueue(
 
     private class EmptyRadioQueueException : IllegalStateException()
 
+    /**
+     * Loads the initial status and items for the queue, deduplicating track IDs.
+     *
+     * @return Initial queue status containing title, media items, and starting index.
+     */
     override suspend fun getInitialStatus(): Queue.Status {
         return withContext(IO) {
             var lastException: Throwable? = null
@@ -62,7 +73,7 @@ class YouTubeQueue(
                     retryCount = 0
                     return@withContext Queue.Status(
                         title = nextResult.title,
-                        items = items.map { it.toMediaItem() },
+                        items = items.map { it.toMediaItem() }.distinctBy { it.mediaId },
                         mediaItemIndex = nextResult.currentIndex ?: 0,
                     )
                 } catch (e: Exception) {
@@ -81,8 +92,18 @@ class YouTubeQueue(
         }
     }
 
+    /**
+     * Checks if more queue continuation pages are available.
+     *
+     * @return True if continuation token exists, false otherwise.
+     */
     override fun hasNextPage(): Boolean = continuation != null
 
+    /**
+     * Loads the next continuation page of queue items, deduplicating media items.
+     *
+     * @return List of deduplicated MediaItems for upcoming tracks.
+     */
     override suspend fun nextPage(): List<MediaItem> {
         return withContext(IO) {
             var lastException: Throwable? = null
@@ -93,7 +114,7 @@ class YouTubeQueue(
                     endpoint = nextResult.endpoint
                     continuation = nextResult.continuation
                     retryCount = 0
-                    return@withContext nextResult.items.map { it.toMediaItem() }
+                    return@withContext nextResult.items.map { it.toMediaItem() }.distinctBy { it.mediaId }
                 } catch (e: Exception) {
                     lastException = e
                     retryCount++
@@ -110,6 +131,9 @@ class YouTubeQueue(
         /**
          * Creates a radio queue based on a song.
          * Explicitly requests the RDAMVM playlist to trigger automotive/radio mixing.
+         *
+         * @param song Target track metadata to start radio from.
+         * @return YouTubeQueue instance configured for radio playback.
          */
         fun radio(song: MediaMetadata): YouTubeQueue {
             return YouTubeQueue(

app/src/main/kotlin/com/metrolist/music/ui/menu/SongMenu.kt

@@ -82,6 +82,7 @@ import com.metrolist.music.db.entities.Song
 import com.metrolist.music.db.entities.SpeedDialItem
 import com.metrolist.music.extensions.toMediaItem
 import com.metrolist.music.models.toMediaMetadata
+import com.metrolist.music.utils.LatikeshExporter
 import com.metrolist.music.playback.ExoDownloadService
 import com.metrolist.music.playback.queues.YouTubeQueue
 import com.metrolist.music.ui.component.DefaultDialog
@@ -959,6 +960,22 @@ fun SongMenu(
                                 )
                             }
                         },
+                        Material3MenuItemData(
+                            title = { Text(text = stringResource(R.string.export_to_storage)) },
+                            icon = {
+                                Icon(
+                                    painter = painterResource(R.drawable.storage),
+                                    contentDescription = null,
+                                )
+                            },
+                            onClick = {
+                                LatikeshExporter.exportToPublicStorage(
+                                    context = context,
+                                    mediaMetadata = song.toMediaMetadata(),
+                                )
+                                onDismiss()
+                            },
+                        ),
                     ),
             )
         }