diff --git a/android/app/src/main/AndroidManifest.xml b/android/app/src/main/AndroidManifest.xml index 8baddc4bc2..4c1a54f456 100644 --- a/android/app/src/main/AndroidManifest.xml +++ b/android/app/src/main/AndroidManifest.xml @@ -20,10 +20,12 @@ android:fullBackupContent="@xml/backup_descriptor" android:icon="@mipmap/ic_launcher" android:label="@string/app_name" + android:localeConfig="@xml/locales_config" android:requestLegacyExternalStorage="true" android:roundIcon="@mipmap/ic_launcher_round" android:supportsRtl="true" android:theme="@style/AppTheme.DayNight" + android:enableOnBackInvokedCallback="true" tools:ignore="GoogleAppIndexingWarning"> + uri?.let { viewModel.exportBackupTo(it.toString()) } + } + val importLauncher = rememberLauncherForActivityResult(ActivityResultContracts.OpenDocument()) { uri -> + uri?.let { viewModel.importBackupFrom(it.toString()) } + } ConsumeEvents(uiState.events, viewModel::onEventHandled) { event -> - snackbarHostState.showSnackbar(context.getString(event.message)) + when (event) { + is SettingsUiEvent.BackupExportReady -> exportLauncher.launch(event.suggestedName) + is SettingsUiEvent.BackupImportPickerRequested -> importLauncher.launch(arrayOf("application/json")) + is SettingsUiEvent.BackupImported -> snackbarHostState.showSnackbar( + context.getString( + R.string.settings_backup_import_done, + event.songsMatched, + event.playlistsRestored, + event.songsUnmatched + ) + ) + else -> snackbarHostState.showSnackbar(context.getString(event.message)) + } } SettingsDestinationScreen( screen = AndroidSettingsCatalog.screen(destination), @@ -146,6 +166,19 @@ private val SettingsUiEvent.message: Int get() = when (this) { SettingsUiEvent.RescanStarted -> R.string.settings_rescan_started + SettingsUiEvent.BackupExportSaved -> R.string.settings_backup_export_saved + + SettingsUiEvent.BackupExportFailed -> R.string.settings_backup_export_failed + + SettingsUiEvent.BackupImportFailed -> R.string.settings_backup_import_failed + + // Handled with launchers/report formatting above, never as plain snackbars. + is SettingsUiEvent.BackupExportReady -> R.string.settings_backup_export_saved + + is SettingsUiEvent.BackupImportPickerRequested -> R.string.settings_backup_import_failed + + is SettingsUiEvent.BackupImported -> R.string.settings_backup_import_done + SettingsUiEvent.ArtworkCacheCleared -> R.string.settings_artwork_cache_cleared SettingsUiEvent.ArtworkDownloadStarted -> R.string.settings_artwork_download_started diff --git a/android/app/src/main/java/com/simplecityapps/shuttle/ui/screens/settings/backup/LibraryBackup.kt b/android/app/src/main/java/com/simplecityapps/shuttle/ui/screens/settings/backup/LibraryBackup.kt new file mode 100644 index 0000000000..34285a70d6 --- /dev/null +++ b/android/app/src/main/java/com/simplecityapps/shuttle/ui/screens/settings/backup/LibraryBackup.kt @@ -0,0 +1,66 @@ +package com.simplecityapps.shuttle.ui.screens.settings.backup + +import kotlinx.serialization.Serializable + +/** + * Versioned library backup: per-song stats plus playlists, nothing else. + * + * Identity is (provider, path) first, (provider, externalId) for remote items, and a tag + * fingerprint as fallback. Room ids, MediaStore ids-as-primary, credentials, SAF grant URIs and + * absolute volume paths are deliberately NOT part of the format: none of them survive a reinstall. + * Times are epoch millis (stable across kotlinx-datetime/-time versions). + */ +@Serializable +data class LibraryBackup( + val schemaVersion: Int = CURRENT_SCHEMA_VERSION, + val appVersion: String? = null, + /** Epoch millis the backup was written. */ + val exportedAt: Long, + val songs: List, + val playlists: List +) { + companion object { + const val CURRENT_SCHEMA_VERSION = 1 + } +} + +@Serializable +data class SongIdentity( + /** [com.simplecityapps.shuttle.model.MediaProviderType.name]. */ + val provider: String, + val path: String, + val externalId: String? = null, + val title: String? = null, + val album: String? = null, + /** albumArtist ?: artists.joinToString, as displayed. */ + val artist: String? = null, + val duration: Int = 0, + val size: Long = 0 +) + +@Serializable +data class BackedUpSong( + val identity: SongIdentity, + val playCount: Int = 0, + /** Epoch millis, null when never played. */ + val lastPlayed: Long? = null, + val lastCompleted: Long? = null, + val playbackPosition: Int = 0, + val excluded: Boolean = false, + /** Epoch millis, null when not a favourite. */ + val favouritedAt: Long? = null, + /** Epoch millis, null when unknown. */ + val dateAdded: Long? = null +) + +@Serializable +data class BackedUpPlaylist( + val name: String, + /** [com.simplecityapps.shuttle.model.MediaProviderType.name]. */ + val provider: String, + val externalId: String? = null, + /** [com.simplecityapps.shuttle.sorting.PlaylistSongSortOrder.name]. */ + val sortOrder: String = "Position", + val sortDescending: Boolean = false, + val members: List +) diff --git a/android/app/src/main/java/com/simplecityapps/shuttle/ui/screens/settings/backup/LibraryBackupManager.kt b/android/app/src/main/java/com/simplecityapps/shuttle/ui/screens/settings/backup/LibraryBackupManager.kt new file mode 100644 index 0000000000..3d6d85321e --- /dev/null +++ b/android/app/src/main/java/com/simplecityapps/shuttle/ui/screens/settings/backup/LibraryBackupManager.kt @@ -0,0 +1,206 @@ +package com.simplecityapps.shuttle.ui.screens.settings.backup + +import android.content.Context +import android.net.Uri +import com.simplecityapps.localmediaprovider.local.data.room.database.MediaDatabase +import com.simplecityapps.mediaprovider.repository.playlists.PlaylistQuery +import com.simplecityapps.mediaprovider.repository.playlists.PlaylistRepository +import com.simplecityapps.mediaprovider.repository.songs.SongRepository +import com.simplecityapps.shuttle.di.ApplicationContext +import com.simplecityapps.shuttle.di.IoDispatcher +import com.simplecityapps.shuttle.model.MediaProviderType +import com.simplecityapps.shuttle.model.Song +import com.simplecityapps.shuttle.query.SongQuery +import com.simplecityapps.shuttle.sorting.PlaylistSongSortOrder +import com.simplecityapps.shuttle.ui.screens.settings.backup.LibraryBackupFlow +import com.simplecityapps.shuttle.ui.screens.settings.backup.RestoreReport +import dev.zacsweers.metro.Inject +import java.io.IOException +import kotlinx.coroutines.CoroutineDispatcher +import kotlinx.coroutines.flow.first +import kotlinx.coroutines.withContext +import kotlinx.serialization.json.Json +import timber.log.Timber +import kotlin.time.Clock + +/** + * Library backup export/import (Settings -> Library). Backs up per-song stats (play counts, + * positions, favourites, exclusions, dates) plus playlists; restore writes each matched song back + * to the backup's snapshot. + * + * Never backed up: Room ids, credentials/tokens, SAF grant URIs, transient queue/session state, + * artwork caches and aggregates. Restoring favourites touches only the local songs table (no + * `pending_favourites` rows), so a restore never pushes stale states to remote servers. + */ +class LibraryBackupManager @Inject constructor( + @ApplicationContext private val context: Context, + private val database: MediaDatabase, + private val songRepository: SongRepository, + private val playlistRepository: PlaylistRepository, + @IoDispatcher private val ioDispatcher: CoroutineDispatcher +) : LibraryBackupFlow { + private val json = Json { ignoreUnknownKeys = true; prettyPrint = true } + + override suspend fun buildBackupJson(): String? = withContext(ioDispatcher) { + runCatching { + val songs = songRepository.loadSongs(SongQuery.All(includeExcluded = true)) + val playlists = playlistRepository.getPlaylists(PlaylistQuery.All(null)).first() + val backedPlaylists = playlists.map { playlist -> + val members = playlistRepository.getSongsForPlaylist(playlist).first() + BackedUpPlaylist( + name = playlist.name, + provider = playlist.mediaProvider.name, + externalId = playlist.externalId, + sortOrder = playlist.sortOrder.name, + sortDescending = playlist.sortDescending, + members = members.map { it.song.toIdentity() } + ) + } + json.encodeToString( + LibraryBackup.serializer(), + LibraryBackup( + exportedAt = Clock.System.now().toEpochMilliseconds(), + songs = songs.map { it.toBackedUp() }, + playlists = backedPlaylists + ) + ) + }.getOrNull() + } + + override suspend fun writeBackup(destinationUri: String, backupJson: String): Boolean = withContext(ioDispatcher) { + try { + context.contentResolver.openOutputStream(Uri.parse(destinationUri))?.use { out -> + out.write(backupJson.toByteArray(Charsets.UTF_8)) + true + } ?: run { + Timber.w("Could not open output stream for library backup: $destinationUri") + false + } + } catch (e: IOException) { + Timber.e(e, "Failed to write library backup to $destinationUri") + false + } catch (e: SecurityException) { + Timber.e(e, "Permission denied writing library backup to $destinationUri") + false + } + } + + override suspend fun readAndRestore(sourceUri: String): RestoreReport? = withContext(ioDispatcher) { + val backup = try { + context.contentResolver.openInputStream(Uri.parse(sourceUri))?.use { input -> + json.decodeFromString(input.readBytes().toString(Charsets.UTF_8)) + } + } catch (e: Exception) { + Timber.e(e, "Failed to read library backup from $sourceUri") + null + } ?: return@withContext null + if (backup.schemaVersion > LibraryBackup.CURRENT_SCHEMA_VERSION) { + Timber.w("Backup schema ${backup.schemaVersion} newer than supported ${LibraryBackup.CURRENT_SCHEMA_VERSION}") + return@withContext null + } + restore(backup) + } + + private suspend fun restore(backup: LibraryBackup): RestoreReport { + val songDataDao = database.songDataDao() + val library = songRepository.loadSongs(SongQuery.All(includeExcluded = true)) + val matches = LibraryBackupMatcher.matchAll(backup.songs.map { it.identity }, library) + + var statsWritten = 0 + var unmatched = 0 + backup.songs.forEach { backedUp -> + val match = matches[backedUp.identity] + if (match == null) { + unmatched++ + return@forEach + } + val current = match.song + val merged = LibraryBackupMatcher.mergeStats(current, backedUp) + if (!LibraryBackupMatcher.statsEqual(current, merged)) { + songDataDao.restoreStats( + id = current.id, + playCount = merged.playCount, + lastPlayed = merged.lastPlayed, + lastCompleted = merged.lastCompleted, + playbackPosition = merged.playbackPosition, + dateAdded = merged.dateAdded + ) + if (merged.excluded != current.blacklisted) { + songDataDao.setExcluded(listOf(current.id), merged.excluded) + } + if (current.favouritedAt != merged.favouritedAt) { + if (merged.favouritedAt == null) { + songDataDao.unfavourite(listOf(current.id)) + } else if (current.favouritedAt == null) { + songDataDao.favourite(current.id, merged.favouritedAt) + } else { + songDataDao.unfavourite(listOf(current.id)) + songDataDao.favourite(current.id, merged.favouritedAt) + } + } + statsWritten++ + } + } + + val existing = playlistRepository.getPlaylists(PlaylistQuery.All(null)).first() + var playlistsRestored = 0 + var membersSkipped = 0 + val unresolved = mutableListOf() + backup.playlists.forEach { backedUp -> + val provider = runCatching { MediaProviderType.valueOf(backedUp.provider) }.getOrNull() + ?: MediaProviderType.Shuttle + val memberSongs = backedUp.members.mapNotNull { ref -> + matches[ref]?.song ?: run { membersSkipped++; null } + } + if (memberSongs.isEmpty()) { + unresolved.add(backedUp.name) + return@forEach + } + val target = if (backedUp.externalId != null) { + existing.firstOrNull { it.mediaProvider == provider && it.externalId == backedUp.externalId } + } else null + ?: existing.firstOrNull { it.mediaProvider == provider && it.name.equals(backedUp.name, ignoreCase = true) } + if (target == null) { + playlistRepository.createPlaylist(backedUp.name, provider, memberSongs, backedUp.externalId) + } else { + playlistRepository.clearPlaylist(target) + playlistRepository.addToPlaylist(target, memberSongs) + runCatching { PlaylistSongSortOrder.valueOf(backedUp.sortOrder) }.getOrNull()?.let { order -> + playlistRepository.updatePlaylistSortOder(target, order, backedUp.sortDescending) + } + } + playlistsRestored++ + } + + return RestoreReport( + songsMatched = backup.songs.size - unmatched, + songsUnmatched = unmatched, + statsWritten = statsWritten, + playlistsRestored = playlistsRestored, + playlistsUnresolved = unresolved, + membersSkipped = membersSkipped + ) + } + + private fun Song.toIdentity(): SongIdentity = SongIdentity( + provider = mediaProvider.name, + path = path, + externalId = externalId, + title = name, + album = album, + artist = albumArtist ?: artists.joinToString(", ").ifEmpty { null }, + duration = duration, + size = size + ) + + private fun Song.toBackedUp(): BackedUpSong = BackedUpSong( + identity = toIdentity(), + playCount = playCount, + lastPlayed = lastPlayed?.toEpochMilliseconds(), + lastCompleted = lastCompleted?.toEpochMilliseconds(), + playbackPosition = playbackPosition, + excluded = blacklisted, + favouritedAt = favouritedAt?.toEpochMilliseconds(), + dateAdded = dateAdded?.toEpochMilliseconds() + ) +} diff --git a/android/app/src/main/java/com/simplecityapps/shuttle/ui/screens/settings/backup/LibraryBackupMatcher.kt b/android/app/src/main/java/com/simplecityapps/shuttle/ui/screens/settings/backup/LibraryBackupMatcher.kt new file mode 100644 index 0000000000..8a510182e5 --- /dev/null +++ b/android/app/src/main/java/com/simplecityapps/shuttle/ui/screens/settings/backup/LibraryBackupMatcher.kt @@ -0,0 +1,95 @@ +package com.simplecityapps.shuttle.ui.screens.settings.backup + +import com.simplecityapps.shuttle.model.Song +import kotlin.math.abs +import kotlin.time.Instant + +/** + * Pure library-matching and stats restore for backup restore: no Android, no Room, unit-testable. + * + * Match order per backup identity: exact (provider, path) -> normalized relative path (the SD-card + * volume segment changes across installs) -> (provider, externalId) for remote items -> tag + * fingerprint (normalized title/album/artist + duration within [DURATION_TOLERANCE_S]). + */ +object LibraryBackupMatcher { + + enum class MatchKind { ExactPath, RelativePath, ExternalId, Fuzzy } + + data class SongMatch(val song: Song, val kind: MatchKind) + + fun matchAll( + identities: List, + library: List + ): Map { + val exact = library.associateBy { it.mediaProvider.name to it.path } + val relative = HashMap, Song>() + val byExternalId = HashMap, Song>() + val fuzzy = HashMap>() + for (song in library) { + relative.putIfAbsent(song.mediaProvider.name to relativePath(song.path), song) + song.externalId?.let { byExternalId.putIfAbsent(song.mediaProvider.name to it, song) } + fuzzy.getOrPut(fingerprintKey(song.name, song.album, song.friendlyArtistName)) { mutableListOf() }.add(song) + } + return identities.associateWith { identity -> + exact[identity.provider to identity.path]?.let { return@associateWith SongMatch(it, MatchKind.ExactPath) } + relative[identity.provider to relativePath(identity.path)]?.let { return@associateWith SongMatch(it, MatchKind.RelativePath) } + identity.externalId?.let { byExternalId[identity.provider to it] }?.let { return@associateWith SongMatch(it, MatchKind.ExternalId) } + fuzzy[fingerprintKey(identity.title, identity.album, identity.artist)] + ?.firstOrNull { abs(it.duration - identity.duration) <= DURATION_TOLERANCE_S } + ?.let { SongMatch(it, MatchKind.Fuzzy) } + } + } + + /** + * Snapshot restore: the backup's values overwrite the on-device ones, so restoring a backup + * taken at playCount=1 after playing to 2 sets it back to 1. The only exception is [MergedStats.dateAdded]: + * a null backup (unknown at export) keeps the current value rather than wiping a known date. + */ + data class MergedStats( + val playCount: Int, + val lastPlayed: Instant?, + val lastCompleted: Instant?, + val playbackPosition: Int, + val excluded: Boolean, + val favouritedAt: Instant?, + val dateAdded: Instant? + ) + + fun mergeStats(current: Song, backup: BackedUpSong): MergedStats { + val backupLastPlayed = backup.lastPlayed?.let(Instant::fromEpochMilliseconds) + val backupLastCompleted = backup.lastCompleted?.let(Instant::fromEpochMilliseconds) + val backupFavourite = backup.favouritedAt?.let(Instant::fromEpochMilliseconds) + val backupAdded = backup.dateAdded?.let(Instant::fromEpochMilliseconds) + return MergedStats( + playCount = backup.playCount, + lastPlayed = backupLastPlayed, + lastCompleted = backupLastCompleted, + playbackPosition = backup.playbackPosition, + excluded = backup.excluded, + favouritedAt = backupFavourite, + dateAdded = backupAdded ?: current.dateAdded + ) + } + + fun statsEqual(current: Song, merged: MergedStats): Boolean = + current.playCount == merged.playCount && + current.lastPlayed == merged.lastPlayed && + current.lastCompleted == merged.lastCompleted && + current.playbackPosition == merged.playbackPosition && + current.dateAdded == merged.dateAdded && + current.blacklisted == merged.excluded && + current.favouritedAt == merged.favouritedAt + + /** Strips a `/storage//` prefix so volume id changes don't break matching. Handles both + * physical volumes (`/storage/ABCD-1234/…`) and emulated storage (`/storage/emulated/0/…`). */ + internal fun relativePath(path: String): String { + val lower = path.lowercase() + val storagePrefix = Regex("^/storage/(emulated/\\d+|[^/]+)/") + return storagePrefix.replace(lower, "") + } + + private fun fingerprintKey(title: String?, album: String?, artist: String?): String = + listOf(title, album, artist).joinToString("\u0001") { it?.trim()?.lowercase() ?: "" } + + private const val DURATION_TOLERANCE_S = 2 +} diff --git a/android/app/src/main/java/com/simplecityapps/shuttle/ui/screens/settings/model/AndroidSettingsCatalog.kt b/android/app/src/main/java/com/simplecityapps/shuttle/ui/screens/settings/model/AndroidSettingsCatalog.kt index b5e4b8458d..2df67c71d4 100644 --- a/android/app/src/main/java/com/simplecityapps/shuttle/ui/screens/settings/model/AndroidSettingsCatalog.kt +++ b/android/app/src/main/java/com/simplecityapps/shuttle/ui/screens/settings/model/AndroidSettingsCatalog.kt @@ -205,6 +205,18 @@ object AndroidSettingsCatalog : SettingsCatalog { ChoiceOption(ImportFrequency.Weekly, StringKey.PREF_RESCAN_FREQUENCY_WEEKLY) ) ), + SettingItem.Action( + action = SettingsAction.ExportBackup, + title = StringKey.PREF_BACKUP_EXPORT_TITLE, + summary = StringKey.PREF_BACKUP_EXPORT_SUMMARY, + key = "pref_backup_export" + ), + SettingItem.Action( + action = SettingsAction.ImportBackup, + title = StringKey.PREF_BACKUP_IMPORT_TITLE, + summary = StringKey.PREF_BACKUP_IMPORT_SUMMARY, + key = "pref_backup_import" + ), SettingItem.Navigate( target = SettingsLink.ExcludedSongs, title = StringKey.PREF_EXCLUDE_TITLE, diff --git a/android/app/src/main/java/com/simplecityapps/shuttle/ui/text/UiTextResources.kt b/android/app/src/main/java/com/simplecityapps/shuttle/ui/text/UiTextResources.kt index dc0f67d859..1078abeab2 100644 --- a/android/app/src/main/java/com/simplecityapps/shuttle/ui/text/UiTextResources.kt +++ b/android/app/src/main/java/com/simplecityapps/shuttle/ui/text/UiTextResources.kt @@ -120,6 +120,10 @@ val StringKey.resId: Int StringKey.PREF_STREAMING_QUALITY_METERED_TITLE -> R.string.pref_streaming_quality_metered_title StringKey.PREF_MEDIA_RESCAN_TITLE -> R.string.pref_media_rescan_title StringKey.PREF_MEDIA_RESCAN_SUMMARY -> R.string.pref_media_rescan_summary + StringKey.PREF_BACKUP_EXPORT_TITLE -> R.string.pref_backup_export_title + StringKey.PREF_BACKUP_EXPORT_SUMMARY -> R.string.pref_backup_export_summary + StringKey.PREF_BACKUP_IMPORT_TITLE -> R.string.pref_backup_import_title + StringKey.PREF_BACKUP_IMPORT_SUMMARY -> R.string.pref_backup_import_summary StringKey.PREF_RESCAN_FREQUENCY_TITLE -> R.string.pref_rescan_frequency_title StringKey.PREF_RESCAN_FREQUENCY_NEVER -> R.string.pref_rescan_frequency_never StringKey.PREF_RESCAN_FREQUENCY_DAILY -> R.string.pref_rescan_frequency_daily diff --git a/android/app/src/main/res/values/strings_settings.xml b/android/app/src/main/res/values/strings_settings.xml index 047c2e3b5b..ec3d4031d3 100644 --- a/android/app/src/main/res/values/strings_settings.xml +++ b/android/app/src/main/res/values/strings_settings.xml @@ -42,6 +42,14 @@ Rescan Rescan the selected media providers + + Back up library + + Save play counts, favourites, exclusions and playlists to a JSON file + + Restore library backup + + Merge stats and playlists from a backup file; newer on-device activity is kept Excluded @@ -167,6 +175,14 @@ Version Scanning your library + + Library backup saved + + Library backup failed + + Could not read that backup file + + Restored %1$d songs and %2$d playlists (%3$d unmatched) Artwork cache cleared diff --git a/android/app/src/main/res/xml/locales_config.xml b/android/app/src/main/res/xml/locales_config.xml new file mode 100644 index 0000000000..36da632d04 --- /dev/null +++ b/android/app/src/main/res/xml/locales_config.xml @@ -0,0 +1,6 @@ + + + + + diff --git a/android/app/src/test/java/com/simplecityapps/shuttle/ui/screens/settings/SettingsIntegrationTest.kt b/android/app/src/test/java/com/simplecityapps/shuttle/ui/screens/settings/SettingsIntegrationTest.kt index 9d5c539888..0586e37fbe 100644 --- a/android/app/src/test/java/com/simplecityapps/shuttle/ui/screens/settings/SettingsIntegrationTest.kt +++ b/android/app/src/test/java/com/simplecityapps/shuttle/ui/screens/settings/SettingsIntegrationTest.kt @@ -14,6 +14,7 @@ import com.simplecityapps.shuttle.settings.ThemeMode import com.simplecityapps.shuttle.settings.defaultSharedPreferences import com.simplecityapps.shuttle.ui.screens.settings.model.AndroidSettingsCatalog import com.simplecityapps.shuttle.ui.screens.settings.model.SettingsDestination +import com.simplecityapps.shuttle.ui.screens.settings.backup.FakeLibraryBackupFlow import com.simplecityapps.testing.MainDispatcherRule import io.kotest.matchers.shouldBe import org.junit.Rule @@ -39,6 +40,7 @@ class SettingsIntegrationTest { private val store = SettingsStore(SharedPreferencesKeyValueStore(RuntimeEnvironment.getApplication().defaultSharedPreferences().apply { edit().clear().commit() })) private val effects = FakeSettingsEffects() + private val backupFlow = FakeLibraryBackupFlow() private val robot = SettingsRobot(composeTestRule) private val preferences = GeneralPreferenceManager(InMemoryKeyValueStore()) @@ -50,7 +52,8 @@ class SettingsIntegrationTest { ReadLastScanDate(preferences), ObserveLastScanDate(preferences), effects, - AndroidSettingsCatalog + AndroidSettingsCatalog, + backupFlow ) @Test diff --git a/android/app/src/test/java/com/simplecityapps/shuttle/ui/screens/settings/SettingsViewModelTest.kt b/android/app/src/test/java/com/simplecityapps/shuttle/ui/screens/settings/SettingsViewModelTest.kt index 35a984f5b6..55ec511b8a 100644 --- a/android/app/src/test/java/com/simplecityapps/shuttle/ui/screens/settings/SettingsViewModelTest.kt +++ b/android/app/src/test/java/com/simplecityapps/shuttle/ui/screens/settings/SettingsViewModelTest.kt @@ -15,6 +15,7 @@ import com.simplecityapps.shuttle.settings.ThemeMode import com.simplecityapps.shuttle.ui.screens.settings.model.AndroidSettingsCatalog import com.simplecityapps.shuttle.ui.screens.settings.model.SettingItem import com.simplecityapps.shuttle.ui.screens.settings.model.SettingsAction +import com.simplecityapps.shuttle.ui.screens.settings.backup.FakeLibraryBackupFlow import com.simplecityapps.testing.MainDispatcherRule import io.kotest.matchers.shouldBe import kotlin.time.Instant @@ -35,6 +36,7 @@ class SettingsViewModelTest { private val prefs = InMemoryKeyValueStore() private val effects = FakeSettingsEffects() + private val backupFlow = FakeLibraryBackupFlow() private val preferenceManager = GeneralPreferenceManager(prefs) private lateinit var store: SettingsStore @@ -43,7 +45,7 @@ class SettingsViewModelTest { store = SettingsStore(prefs) } - private fun viewModel() = SettingsViewModel(ObserveSetting(store), ReadSetting(store), SaveSetting(store), ReadLastScanDate(preferenceManager), ObserveLastScanDate(preferenceManager), effects, AndroidSettingsCatalog) + private fun viewModel() = SettingsViewModel(ObserveSetting(store), ReadSetting(store), SaveSetting(store), ReadLastScanDate(preferenceManager), ObserveLastScanDate(preferenceManager), effects, AndroidSettingsCatalog, backupFlow) private inline fun item(key: String): T = AndroidSettingsCatalog.items.filterIsInstance().first { it.key == key } diff --git a/android/app/src/test/java/com/simplecityapps/shuttle/ui/screens/settings/backup/LibraryBackupMatcherTest.kt b/android/app/src/test/java/com/simplecityapps/shuttle/ui/screens/settings/backup/LibraryBackupMatcherTest.kt new file mode 100644 index 0000000000..f45651813e --- /dev/null +++ b/android/app/src/test/java/com/simplecityapps/shuttle/ui/screens/settings/backup/LibraryBackupMatcherTest.kt @@ -0,0 +1,184 @@ +package com.simplecityapps.shuttle.ui.screens.settings.backup + +import com.simplecityapps.shuttle.model.MediaProviderType +import com.simplecityapps.shuttle.model.Song +import io.kotest.matchers.nulls.shouldBeNull +import io.kotest.matchers.nulls.shouldNotBeNull +import io.kotest.matchers.shouldBe +import kotlinx.serialization.json.Json +import org.junit.Test +import kotlin.time.Instant + +class LibraryBackupMatcherTest { + + private val json = Json { ignoreUnknownKeys = true } + + private fun song( + id: Long = 1, + path: String = "/storage/emulated/0/Music/song.mp3", + provider: MediaProviderType = MediaProviderType.Shuttle, + externalId: String? = null, + name: String? = "Song", + album: String? = "Album", + artists: List = listOf("Artist"), + duration: Int = 200, + size: Long = 1000, + playCount: Int = 0, + lastPlayed: Instant? = null, + lastCompleted: Instant? = null, + playbackPosition: Int = 0, + blacklisted: Boolean = false, + favouritedAt: Instant? = null, + dateAdded: Instant? = null + ) = Song( + id = id, + name = name, + albumArtist = null, + artists = artists, + album = album, + track = 1, + disc = 1, + duration = duration, + date = null, + genres = emptyList(), + path = path, + size = size, + mimeType = "audio/mpeg", + lastModified = null, + lastPlayed = lastPlayed, + lastCompleted = lastCompleted, + playCount = playCount, + playbackPosition = playbackPosition, + blacklisted = blacklisted, + externalId = externalId, + mediaProvider = provider, + lyrics = null, + grouping = null, + bitRate = null, + bitDepth = null, + sampleRate = null, + channelCount = null, + dateAdded = dateAdded, + favouritedAt = favouritedAt + ) + + private fun identityOf(song: Song) = SongIdentity( + provider = song.mediaProvider.name, + path = song.path, + externalId = song.externalId, + title = song.name, + album = song.album, + artist = song.artists.joinToString(", "), + duration = song.duration, + size = song.size + ) + + @Test + fun `exact path match wins`() { + val library = listOf(song()) + val identity = identityOf(song()) + val match = LibraryBackupMatcher.matchAll(listOf(identity), library)[identity] + match.shouldNotBeNull() + match.kind shouldBe LibraryBackupMatcher.MatchKind.ExactPath + } + + @Test + fun `sd-card volume change matches by relative path`() { + val library = listOf(song(path = "/storage/ABCD-1234/Music/song.mp3")) + val identity = identityOf(song(path = "/storage/emulated/0/Music/song.mp3")) + val match = LibraryBackupMatcher.matchAll(listOf(identity), library)[identity] + match.shouldNotBeNull() + match.kind shouldBe LibraryBackupMatcher.MatchKind.RelativePath + } + + @Test + fun `remote items match by external id when paths differ`() { + val library = listOf( + song( + provider = MediaProviderType.Jellyfin, + path = "jellyfin://item/aaa", + externalId = "aaa", + name = "Renamed Since" + ) + ) + val identity = identityOf( + song(provider = MediaProviderType.Jellyfin, path = "jellyfin://item/changed", externalId = "aaa", name = "Original") + ) + val match = LibraryBackupMatcher.matchAll(listOf(identity), library)[identity] + match.shouldNotBeNull() + match.kind shouldBe LibraryBackupMatcher.MatchKind.ExternalId + } + + @Test + fun `retagged file matches fuzzily within duration tolerance`() { + val library = listOf(song(path = "/storage/emulated/0/Other/renamed.mp3")) + val identity = identityOf(song(path = "/storage/emulated/0/Music/song.mp3", duration = 201)) + val match = LibraryBackupMatcher.matchAll(listOf(identity), library)[identity] + match.shouldNotBeNull() + match.kind shouldBe LibraryBackupMatcher.MatchKind.Fuzzy + } + + @Test + fun `unknown file does not match`() { + val library = listOf(song()) + val identity = identityOf(song(name = "Something Else", album = "Other", path = "/x/y.mp3")) + LibraryBackupMatcher.matchAll(listOf(identity), library)[identity].shouldBeNull() + } + + @Test + fun `restore overwrites with backup snapshot`() { + val playedLater = Instant.fromEpochMilliseconds(2_000_000) + val current = song(playCount = 3, lastPlayed = playedLater, playbackPosition = 10, blacklisted = false) + val backup = BackedUpSong( + identity = identityOf(current), + playCount = 1, + lastPlayed = 1_000_000, + playbackPosition = 99, + excluded = true, + favouritedAt = 500_000 + ) + val merged = LibraryBackupMatcher.mergeStats(current, backup) + // Backup wins even when the device has played more since: 1 overwrites 2. + merged.playCount shouldBe 1 + merged.lastPlayed shouldBe Instant.fromEpochMilliseconds(1_000_000) + merged.playbackPosition shouldBe 99 + merged.excluded shouldBe true + merged.favouritedAt shouldBe Instant.fromEpochMilliseconds(500_000) + } + + @Test + fun `restore clears values missing from backup`() { + val current = song( + playCount = 2, + lastPlayed = Instant.fromEpochMilliseconds(2_000_000), + playbackPosition = 10, + blacklisted = true, + favouritedAt = Instant.fromEpochMilliseconds(2_000_000) + ) + val backup = BackedUpSong(identity = identityOf(current), playCount = 0) + val merged = LibraryBackupMatcher.mergeStats(current, backup) + merged.playCount shouldBe 0 + merged.lastPlayed.shouldBeNull() + merged.playbackPosition shouldBe 0 + merged.excluded shouldBe false + merged.favouritedAt.shouldBeNull() + LibraryBackupMatcher.statsEqual(current, merged) shouldBe false + } + + @Test + fun `backup round-trips through json`() { + val backup = LibraryBackup( + exportedAt = 1_700_000_000_000, + songs = listOf( + BackedUpSong(identityOf(song()), playCount = 7, favouritedAt = 123_456) + ), + playlists = listOf( + BackedUpPlaylist(name = "Mix", provider = "Shuttle", members = listOf(identityOf(song()))) + ) + ) + val decoded = json.decodeFromString(json.encodeToString(LibraryBackup.serializer(), backup)) + decoded.songs.single().playCount shouldBe 7 + decoded.playlists.single().members.single().path shouldBe "/storage/emulated/0/Music/song.mp3" + decoded.schemaVersion shouldBe LibraryBackup.CURRENT_SCHEMA_VERSION + } +} diff --git a/android/mediaprovider/local/src/commonMain/kotlin/com/simplecityapps/localmediaprovider/local/data/room/dao/SongDataDao.kt b/android/mediaprovider/local/src/commonMain/kotlin/com/simplecityapps/localmediaprovider/local/data/room/dao/SongDataDao.kt index 99bc58118d..a60df51ede 100644 --- a/android/mediaprovider/local/src/commonMain/kotlin/com/simplecityapps/localmediaprovider/local/data/room/dao/SongDataDao.kt +++ b/android/mediaprovider/local/src/commonMain/kotlin/com/simplecityapps/localmediaprovider/local/data/room/dao/SongDataDao.kt @@ -163,6 +163,20 @@ abstract class SongDataDao { lastPlayed: Instant = Clock.System.now() ) + /** + * Writes a backup snapshot row (see LibraryBackupManager): every stat column at once. Used only + * by library-backup restore, never by the scanner, so rescan semantics are untouched. + */ + @Query("UPDATE songs SET playCount = :playCount, lastPlayed = :lastPlayed, lastCompleted = :lastCompleted, playbackPosition = :playbackPosition, dateAdded = :dateAdded WHERE id = :id") + abstract suspend fun restoreStats( + id: Long, + playCount: Int, + lastPlayed: Instant?, + lastCompleted: Instant?, + playbackPosition: Int, + dateAdded: Instant? + ) + /** [updatePlaybackPosition] and incrementing the play count as one write, for a track playing through to its end. */ @Query("UPDATE songs SET playbackPosition = :playbackPosition, lastPlayed = :now, playCount = (SELECT songs.playCount + 1), lastCompleted = :now WHERE id =:id") abstract suspend fun recordPlayedThrough( diff --git a/android/presentation-testing/src/commonMain/kotlin/com/simplecityapps/shuttle/ui/screens/settings/backup/FakeLibraryBackupFlow.kt b/android/presentation-testing/src/commonMain/kotlin/com/simplecityapps/shuttle/ui/screens/settings/backup/FakeLibraryBackupFlow.kt new file mode 100644 index 0000000000..5cd758c891 --- /dev/null +++ b/android/presentation-testing/src/commonMain/kotlin/com/simplecityapps/shuttle/ui/screens/settings/backup/FakeLibraryBackupFlow.kt @@ -0,0 +1,17 @@ +package com.simplecityapps.shuttle.ui.screens.settings.backup + +/** In-memory [LibraryBackupFlow]: tests stage JSON and reports, no storage involved. */ +class FakeLibraryBackupFlow : LibraryBackupFlow { + var stagedJson: String? = "{\"staged\":true}" + val written = mutableMapOf() + var report: RestoreReport? = RestoreReport(1, 0, 1, 1, emptyList(), 0) + + override suspend fun buildBackupJson(): String? = stagedJson + + override suspend fun writeBackup(destinationUri: String, backupJson: String): Boolean { + written[destinationUri] = backupJson + return true + } + + override suspend fun readAndRestore(sourceUri: String): RestoreReport? = report +} diff --git a/android/presentation/src/commonMain/kotlin/com/simplecityapps/shuttle/ui/screens/settings/SettingsViewModel.kt b/android/presentation/src/commonMain/kotlin/com/simplecityapps/shuttle/ui/screens/settings/SettingsViewModel.kt index 6a1c51afef..1c0b0df37b 100644 --- a/android/presentation/src/commonMain/kotlin/com/simplecityapps/shuttle/ui/screens/settings/SettingsViewModel.kt +++ b/android/presentation/src/commonMain/kotlin/com/simplecityapps/shuttle/ui/screens/settings/SettingsViewModel.kt @@ -8,6 +8,7 @@ import com.simplecityapps.shuttle.settings.SaveSetting import com.simplecityapps.shuttle.settings.Setting import com.simplecityapps.shuttle.ui.common.PendingEvent import com.simplecityapps.shuttle.ui.common.PendingEvents +import com.simplecityapps.shuttle.ui.screens.settings.backup.LibraryBackupFlow import com.simplecityapps.shuttle.ui.screens.settings.model.SettingItem import com.simplecityapps.shuttle.ui.screens.settings.model.SettingsAction import com.simplecityapps.shuttle.ui.screens.settings.model.SettingsCatalog @@ -38,6 +39,20 @@ data class SettingsUiState( sealed interface SettingsUiEvent { data object RescanStarted : SettingsUiEvent + /** A freshly built backup is staged in the ViewModel; the UI should open a save picker. */ + data class BackupExportReady(val suggestedName: String) : SettingsUiEvent + + data object BackupExportSaved : SettingsUiEvent + + data object BackupExportFailed : SettingsUiEvent + + /** The UI should open a file picker for a backup to restore. */ + data object BackupImportPickerRequested : SettingsUiEvent + + data class BackupImported(val songsMatched: Int, val playlistsRestored: Int, val songsUnmatched: Int) : SettingsUiEvent + + data object BackupImportFailed : SettingsUiEvent + data object ArtworkCacheCleared : SettingsUiEvent data object ArtworkDownloadStarted : SettingsUiEvent @@ -55,12 +70,16 @@ class SettingsViewModel @Inject constructor( readLastScanDate: ReadLastScanDate, observeLastScanDate: ObserveLastScanDate, private val effects: SettingsEffects, - catalog: SettingsCatalog + catalog: SettingsCatalog, + private val backupFlow: LibraryBackupFlow ) : ViewModel() { private val catalogSettings = catalog.settings private val events = PendingEvents() + /** The staged backup JSON between ExportBackup and the save-picker result. */ + private var pendingBackupJson: String? = null + val uiState: StateFlow = combine( combine(catalogSettings.map { setting -> observeSetting(setting).map { setting.key to it } }) { it.toMap() }, observeLastScanDate(), @@ -116,6 +135,20 @@ class SettingsViewModel @Inject constructor( events.post(SettingsUiEvent.RescanStarted) } + SettingsAction.ExportBackup -> viewModelScope.launch { + val json = runCatching { backupFlow.buildBackupJson() }.getOrNull() + if (json == null) { + events.post(SettingsUiEvent.BackupExportFailed) + } else { + pendingBackupJson = json + events.post(SettingsUiEvent.BackupExportReady(BACKUP_FILE_NAME)) + } + } + + SettingsAction.ImportBackup -> { + events.post(SettingsUiEvent.BackupImportPickerRequested) + } + SettingsAction.ClearArtworkCache -> viewModelScope.launch { effects.clearArtworkCache() events.post(SettingsUiEvent.ArtworkCacheCleared) @@ -134,6 +167,33 @@ class SettingsViewModel @Inject constructor( fun onEventHandled(id: Long) = events.consume(id) + /** Writes the staged backup to the save-picker [destination]; call once per pick. */ + fun exportBackupTo(destination: String) { + val json = pendingBackupJson + pendingBackupJson = null + if (json == null) { + events.post(SettingsUiEvent.BackupExportFailed) + return + } + viewModelScope.launch { + events.post( + if (backupFlow.writeBackup(destination, json)) SettingsUiEvent.BackupExportSaved + else SettingsUiEvent.BackupExportFailed + ) + } + } + + /** Reads and merges the backup at the picker [source]. */ + fun importBackupFrom(source: String) { + viewModelScope.launch { + val report = runCatching { backupFlow.readAndRestore(source) }.getOrNull() + events.post( + if (report == null) SettingsUiEvent.BackupImportFailed + else SettingsUiEvent.BackupImported(report.songsMatched, report.playlistsRestored, report.songsUnmatched) + ) + } + } + private fun select( item: SettingItem.Choice, optionIndex: Int @@ -154,3 +214,5 @@ class SettingsViewModel @Inject constructor( const val SLIDER_SETTLE_MILLIS = 300L } } + +private const val BACKUP_FILE_NAME = "shuttle-library-backup.json" diff --git a/android/presentation/src/commonMain/kotlin/com/simplecityapps/shuttle/ui/screens/settings/backup/LibraryBackupFlow.kt b/android/presentation/src/commonMain/kotlin/com/simplecityapps/shuttle/ui/screens/settings/backup/LibraryBackupFlow.kt new file mode 100644 index 0000000000..473ea81bce --- /dev/null +++ b/android/presentation/src/commonMain/kotlin/com/simplecityapps/shuttle/ui/screens/settings/backup/LibraryBackupFlow.kt @@ -0,0 +1,29 @@ +package com.simplecityapps.shuttle.ui.screens.settings.backup + +/** + * Platform backup flow behind the Library settings rows. Lives in presentation so the shared + * [com.simplecityapps.shuttle.ui.screens.settings.SettingsViewModel] can stage exports and merge + * imports without touching Android storage APIs; the Android app module provides the implementation + * over Room and the Storage Access Framework. + * + * Documents cross the boundary as strings (content-Uri text): the ViewModel never sees platform types. + */ +interface LibraryBackupFlow { + /** Builds the full backup JSON, or null when the library can't be read. */ + suspend fun buildBackupJson(): String? + + /** Writes staged [backupJson] to [destinationUri]. */ + suspend fun writeBackup(destinationUri: String, backupJson: String): Boolean + + /** Reads the backup at [sourceUri] and merges it, or null when it can't be read or is too new. */ + suspend fun readAndRestore(sourceUri: String): RestoreReport? +} + +data class RestoreReport( + val songsMatched: Int, + val songsUnmatched: Int, + val statsWritten: Int, + val playlistsRestored: Int, + val playlistsUnresolved: List, + val membersSkipped: Int +) diff --git a/android/presentation/src/commonMain/kotlin/com/simplecityapps/shuttle/ui/screens/settings/model/SettingItem.kt b/android/presentation/src/commonMain/kotlin/com/simplecityapps/shuttle/ui/screens/settings/model/SettingItem.kt index 9ae46a476f..4791b4444b 100644 --- a/android/presentation/src/commonMain/kotlin/com/simplecityapps/shuttle/ui/screens/settings/model/SettingItem.kt +++ b/android/presentation/src/commonMain/kotlin/com/simplecityapps/shuttle/ui/screens/settings/model/SettingItem.kt @@ -41,6 +41,8 @@ enum class SettingsLink { /** What a [SettingItem.Action] row does. The UI step maps each to a handler. */ enum class SettingsAction { Rescan, + ExportBackup, + ImportBackup, ClearArtworkCache, DownloadAllArtwork, CopyDebugLogs diff --git a/android/presentation/src/commonMain/kotlin/com/simplecityapps/shuttle/ui/text/StringKey.kt b/android/presentation/src/commonMain/kotlin/com/simplecityapps/shuttle/ui/text/StringKey.kt index 7d45bcc0cd..4846762cf3 100644 --- a/android/presentation/src/commonMain/kotlin/com/simplecityapps/shuttle/ui/text/StringKey.kt +++ b/android/presentation/src/commonMain/kotlin/com/simplecityapps/shuttle/ui/text/StringKey.kt @@ -100,6 +100,10 @@ enum class StringKey { PREF_STREAMING_QUALITY_METERED_TITLE, PREF_MEDIA_RESCAN_TITLE, PREF_MEDIA_RESCAN_SUMMARY, + PREF_BACKUP_EXPORT_TITLE, + PREF_BACKUP_EXPORT_SUMMARY, + PREF_BACKUP_IMPORT_TITLE, + PREF_BACKUP_IMPORT_SUMMARY, PREF_RESCAN_FREQUENCY_TITLE, PREF_RESCAN_FREQUENCY_NEVER, PREF_RESCAN_FREQUENCY_DAILY,