react-native-nitro-player 0.5.4 → 0.5.5

package/android/src/main/java/com/margelo/nitro/nitroplayer/download/DownloadDatabase.kt

@@ -1,27 +1,27 @@
 package com.margelo.nitro.nitroplayer.download
 
 import android.content.Context
-import android.content.SharedPreferences
-import android.util.Log
 import com.margelo.nitro.core.NullType
 import com.margelo.nitro.nitroplayer.*
 import com.margelo.nitro.nitroplayer.core.NitroPlayerLogger
 import com.margelo.nitro.nitroplayer.playlist.PlaylistManager
+import com.margelo.nitro.nitroplayer.storage.NitroPlayerStorage
 import org.json.JSONArray
 import org.json.JSONObject
 import java.io.File
 
 /**
- * Manages persistence of downloaded track metadata using SharedPreferences
+ * Manages persistence of downloaded track metadata using file storage
  */
 class DownloadDatabase private constructor(
     private val context: Context,
 ) {
     companion object {
         private const val TAG = "DownloadDatabase"
-        private const val PREFS_NAME = "NitroPlayerDownloads"
-        private const val KEY_DOWNLOADED_TRACKS = "downloaded_tracks"
-        private const val KEY_PLAYLIST_TRACKS = "playlist_tracks"
+        // Legacy SharedPreferences keys (migration only)
+        private const val LEGACY_PREFS_NAME = "NitroPlayerDownloads"
+        private const val LEGACY_KEY_DOWNLOADED_TRACKS = "downloaded_tracks"
+        private const val LEGACY_KEY_PLAYLIST_TRACKS = "playlist_tracks"
 
         @Volatile
         private var instance: DownloadDatabase? = null
@@ -32,7 +32,6 @@ class DownloadDatabase private constructor(
             }
     }
 
-    private val prefs: SharedPreferences = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
     private val downloadedTracks = mutableMapOf<String, DownloadedTrackRecord>()
     private val playlistTracks = mutableMapOf<String, MutableSet<String>>()
     private val fileManager = DownloadFileManager.getInstance(context)
@@ -254,13 +253,13 @@ class DownloadDatabase private constructor(
     /** Validates all downloads and removes records for missing files */
     fun syncDownloads(): Int {
         synchronized(this) {
-            NitroPlayerLogger.log("DownloadDatabase", "syncDownloads called")
+            NitroPlayerLogger.log(TAG, "syncDownloads called")
 
             val trackIdsToRemove = mutableListOf<String>()
 
             for ((trackId, record) in downloadedTracks) {
                 if (!File(record.localPath).exists()) {
-                    NitroPlayerLogger.log("DownloadDatabase", "Missing file for track $trackId: ${record.localPath}")
+                    NitroPlayerLogger.log(TAG, "Missing file for track $trackId: ${record.localPath}")
                     trackIdsToRemove.add(trackId)
                 }
             }
@@ -283,9 +282,9 @@ class DownloadDatabase private constructor(
 
             if (trackIdsToRemove.isNotEmpty()) {
                 saveToDisk()
-                NitroPlayerLogger.log("DownloadDatabase", "Cleaned up ${trackIdsToRemove.size} orphaned records")
+                NitroPlayerLogger.log(TAG, "Cleaned up ${trackIdsToRemove.size} orphaned records")
             } else {
-                NitroPlayerLogger.log("DownloadDatabase", "All downloads are valid")
+                NitroPlayerLogger.log(TAG, "All downloads are valid")
             }
 
             return trackIdsToRemove.size
@@ -295,39 +294,80 @@ class DownloadDatabase private constructor(
     // Persistence
     private fun saveToDisk() {
         try {
-            // Save downloaded tracks
             val tracksJson = JSONObject()
             for ((trackId, record) in downloadedTracks) {
                 tracksJson.put(trackId, record.toJson())
             }
-            prefs.edit().putString(KEY_DOWNLOADED_TRACKS, tracksJson.toString()).apply()
 
-            // Save playlist associations
             val playlistJson = JSONObject()
             for ((playlistId, trackIds) in playlistTracks) {
                 playlistJson.put(playlistId, JSONArray(trackIds.toList()))
             }
-            prefs.edit().putString(KEY_PLAYLIST_TRACKS, playlistJson.toString()).apply()
+
+            val wrapper = JSONObject().apply {
+                put("downloadedTracks", tracksJson)
+                put("playlistTracks", playlistJson)
+            }
+            NitroPlayerStorage.write(context, "downloads.json", wrapper.toString())
         } catch (e: Exception) {
             e.printStackTrace()
         }
     }
 
     private fun loadFromDisk() {
-        try {
-            // Load downloaded tracks
-            val tracksString = prefs.getString(KEY_DOWNLOADED_TRACKS, null)
-            if (tracksString != null) {
+        // 1. Try new JSON file (post-migration)
+        val json = NitroPlayerStorage.read(context, "downloads.json")
+        if (json != null) {
+            try {
+                val wrapper = JSONObject(json)
+
+                val tracksJson = wrapper.optJSONObject("downloadedTracks")
+                if (tracksJson != null) {
+                    for (trackId in tracksJson.keys()) {
+                        val record = DownloadedTrackRecord.fromJson(tracksJson.getJSONObject(trackId))
+                        downloadedTracks[trackId] = record
+                    }
+                }
+
+                val playlistJson = wrapper.optJSONObject("playlistTracks")
+                if (playlistJson != null) {
+                    for (playlistId in playlistJson.keys()) {
+                        val trackIdsArray = playlistJson.getJSONArray(playlistId)
+                        val trackIds = mutableSetOf<String>()
+                        for (i in 0 until trackIdsArray.length()) {
+                            trackIds.add(trackIdsArray.getString(i))
+                        }
+                        playlistTracks[playlistId] = trackIds
+                    }
+                }
+            } catch (e: Exception) {
+                e.printStackTrace()
+            }
+            return
+        }
+
+        // 2. Migrate from SharedPreferences (one-time, existing installs)
+        val prefs = context.getSharedPreferences(LEGACY_PREFS_NAME, Context.MODE_PRIVATE)
+        var didMigrate = false
+
+        val tracksString = prefs.getString(LEGACY_KEY_DOWNLOADED_TRACKS, null)
+        if (tracksString != null) {
+            try {
                 val tracksJson = JSONObject(tracksString)
                 for (trackId in tracksJson.keys()) {
                     val record = DownloadedTrackRecord.fromJson(tracksJson.getJSONObject(trackId))
                     downloadedTracks[trackId] = record
                 }
+                prefs.edit().remove(LEGACY_KEY_DOWNLOADED_TRACKS).apply()
+                didMigrate = true
+            } catch (e: Exception) {
+                e.printStackTrace()
             }
+        }
 
-            // Load playlist associations
-            val playlistString = prefs.getString(KEY_PLAYLIST_TRACKS, null)
-            if (playlistString != null) {
+        val playlistString = prefs.getString(LEGACY_KEY_PLAYLIST_TRACKS, null)
+        if (playlistString != null) {
+            try {
                 val playlistJson = JSONObject(playlistString)
                 for (playlistId in playlistJson.keys()) {
                     val trackIdsArray = playlistJson.getJSONArray(playlistId)
@@ -337,9 +377,15 @@ class DownloadDatabase private constructor(
                     }
                     playlistTracks[playlistId] = trackIds
                 }
+                prefs.edit().remove(LEGACY_KEY_PLAYLIST_TRACKS).apply()
+                didMigrate = true
+            } catch (e: Exception) {
+                e.printStackTrace()
             }
-        } catch (e: Exception) {
-            e.printStackTrace()
+        }
+
+        if (didMigrate) {
+            saveToDisk()
         }
     }
 
@@ -395,12 +441,11 @@ class DownloadDatabase private constructor(
     }
 
     private fun convertPlaylistManagerToNitro(playlist: com.margelo.nitro.nitroplayer.playlist.Playlist): Playlist {
-        // PlaylistManager already uses TrackItem from generated code with proper Variant types
         return Playlist(
             id = playlist.id,
             name = playlist.name,
-            description = null, // PlaylistManager doesn't have description in Nitro Playlist
-            artwork = null, // PlaylistManager doesn't have artwork in Nitro Playlist
+            description = null,
+            artwork = null,
             tracks = playlist.tracks.toTypedArray(),
         )
     }

package/android/src/main/java/com/margelo/nitro/nitroplayer/playlist/PlaylistManager.kt

@@ -1,14 +1,13 @@
 package com.margelo.nitro.nitroplayer.playlist
 
 import android.content.Context
-import android.content.SharedPreferences
 import com.margelo.nitro.core.AnyMap
-import com.margelo.nitro.core.NullType
 import com.margelo.nitro.nitroplayer.QueueOperation
 import com.margelo.nitro.nitroplayer.TrackItem
 import com.margelo.nitro.nitroplayer.Variant_NullType_String
 import com.margelo.nitro.nitroplayer.core.TrackPlayerCore
 import com.margelo.nitro.nitroplayer.media.NitroPlayerMediaBrowserService
+import com.margelo.nitro.nitroplayer.storage.NitroPlayerStorage
 import org.json.JSONArray
 import org.json.JSONObject
 import java.util.UUID
@@ -26,11 +25,8 @@ class PlaylistManager private constructor(
     private val playlistListeners = mutableMapOf<String, CopyOnWriteArrayList<(Playlist, QueueOperation?) -> Unit>>()
     private var currentPlaylistId: String? = null
 
-    private val sharedPreferences: SharedPreferences =
-        context.getSharedPreferences("NitroPlayerPlaylists", Context.MODE_PRIVATE)
-
     private val saveHandler = android.os.Handler(android.os.Looper.getMainLooper())
-    private val saveRunnable = Runnable { savePlaylistsToPreferences() }
+    private val saveRunnable = Runnable { saveToFile() }
 
     private fun scheduleSave() {
         saveHandler.removeCallbacks(saveRunnable)
@@ -42,6 +38,9 @@ class PlaylistManager private constructor(
         @Suppress("ktlint:standard:property-naming")
         private var INSTANCE: PlaylistManager? = null
 
+        // Legacy SharedPreferences name (migration only)
+        private const val LEGACY_PREFS_NAME = "NitroPlayerPlaylists"
+
         @JvmStatic
         fun getInstance(context: Context): PlaylistManager =
             INSTANCE ?: synchronized(this) {
@@ -50,7 +49,7 @@ class PlaylistManager private constructor(
     }
 
     init {
-        // Don't load from preferences on init - only load when Android Auto needs it
+        // Don't load from file on init - only load when Android Auto needs it
     }
 
     /**
@@ -368,7 +367,9 @@ class PlaylistManager private constructor(
         playlistListeners[playlistId]?.forEach { it(playlist, operation) }
     }
 
-    private fun savePlaylistsToPreferences() {
+    // MARK: - Persistence
+
+    private fun saveToFile() {
         try {
             val jsonArray = JSONArray()
             synchronized(playlists) {
@@ -390,7 +391,6 @@ class PlaylistManager private constructor(
                                         put("duration", track.duration)
                                         put("url", track.url)
                                         track.artwork?.let { put("artwork", it) }
-                                        // Serialize extraPayload to JSON for persistence
                                         track.extraPayload?.let { payload ->
                                             val extraPayloadMap = payload.toHashMap()
                                             val extraPayloadJson = JSONObject(extraPayloadMap)
@@ -405,84 +405,111 @@ class PlaylistManager private constructor(
                 }
             }
 
-            sharedPreferences
-                .edit()
-                .putString("playlists", jsonArray.toString())
-                .putString("currentPlaylistId", currentPlaylistId)
-                .apply()
+            val wrapper = JSONObject().apply {
+                put("playlists", jsonArray)
+                put("currentPlaylistId", currentPlaylistId)
+            }
+            NitroPlayerStorage.write(context, "playlists.json", wrapper.toString())
         } catch (e: Exception) {
             e.printStackTrace()
         }
     }
 
-    private fun loadPlaylistsFromPreferences() {
-        try {
-            val jsonString = sharedPreferences.getString("playlists", null)
-            if (jsonString != null) {
-                val jsonArray = JSONArray(jsonString)
-                synchronized(playlists) {
-                    playlists.clear()
-                    for (i in 0 until jsonArray.length()) {
-                        val jsonObject = jsonArray.getJSONObject(i)
-                        val tracks = mutableListOf<TrackItem>()
-                        val tracksArray = jsonObject.getJSONArray("tracks")
-                        for (j in 0 until tracksArray.length()) {
-                            val trackObj = tracksArray.getJSONObject(j)
-                            val artworkStr = trackObj.optString("artwork")
-                            val artwork: Variant_NullType_String? =
-                                if (!artworkStr.isNullOrEmpty()) {
-                                    Variant_NullType_String.create(artworkStr)
-                                } else {
-                                    null
-                                }
-                            // Deserialize extraPayload from JSON
-                            val extraPayload: AnyMap? =
-                                if (trackObj.has("extraPayload")) {
-                                    val extraPayloadJson = trackObj.getJSONObject("extraPayload")
-                                    val map = AnyMap()
-                                    val keyIterator = extraPayloadJson.keys()
-                                    while (keyIterator.hasNext()) {
-                                        val key = keyIterator.next()
-                                        when (val value = extraPayloadJson.get(key)) {
-                                            is String -> map.setString(key, value)
-                                            is Number -> map.setDouble(key, value.toDouble())
-                                            is Boolean -> map.setBoolean(key, value)
-                                        }
-                                    }
-                                    map
-                                } else {
-                                    null
+    fun loadPlaylistsFromFile() {
+        // 1. Try new JSON file (post-migration)
+        val json = NitroPlayerStorage.read(context, "playlists.json")
+        if (json != null) {
+            try {
+                val wrapper = JSONObject(json)
+                val jsonArray = wrapper.optJSONArray("playlists") ?: JSONArray()
+                parseAndLoadPlaylists(jsonArray)
+                currentPlaylistId = if (wrapper.isNull("currentPlaylistId")) null
+                                    else wrapper.optString("currentPlaylistId", null.toString()).takeIf { it != "null" }
+            } catch (e: Exception) {
+                e.printStackTrace()
+            }
+            return
+        }
+
+        // 2. Migrate from SharedPreferences (one-time, existing installs)
+        val prefs = context.getSharedPreferences(LEGACY_PREFS_NAME, Context.MODE_PRIVATE)
+        val legacyJson = prefs.getString("playlists", null)
+        if (legacyJson != null) {
+            try {
+                val jsonArray = JSONArray(legacyJson)
+                parseAndLoadPlaylists(jsonArray)
+                currentPlaylistId = prefs.getString("currentPlaylistId", null)
+                // Remove old SharedPreferences data to free space
+                prefs.edit().remove("playlists").remove("currentPlaylistId").apply()
+                // Persist in new format
+                saveToFile()
+            } catch (e: Exception) {
+                e.printStackTrace()
+            }
+            return
+        }
+
+        // 3. Fresh install — nothing to load
+    }
+
+    private fun parseAndLoadPlaylists(jsonArray: JSONArray) {
+        synchronized(playlists) {
+            playlists.clear()
+            for (i in 0 until jsonArray.length()) {
+                val jsonObject = jsonArray.getJSONObject(i)
+                val tracks = mutableListOf<TrackItem>()
+                val tracksArray = jsonObject.getJSONArray("tracks")
+                for (j in 0 until tracksArray.length()) {
+                    val trackObj = tracksArray.getJSONObject(j)
+                    val artworkStr = trackObj.optString("artwork")
+                    val artwork: Variant_NullType_String? =
+                        if (!artworkStr.isNullOrEmpty()) {
+                            Variant_NullType_String.create(artworkStr)
+                        } else {
+                            null
+                        }
+                    val extraPayload: AnyMap? =
+                        if (trackObj.has("extraPayload")) {
+                            val extraPayloadJson = trackObj.getJSONObject("extraPayload")
+                            val map = AnyMap()
+                            val keyIterator = extraPayloadJson.keys()
+                            while (keyIterator.hasNext()) {
+                                val key = keyIterator.next()
+                                when (val value = extraPayloadJson.get(key)) {
+                                    is String -> map.setString(key, value)
+                                    is Number -> map.setDouble(key, value.toDouble())
+                                    is Boolean -> map.setBoolean(key, value)
                                 }
-                            tracks.add(
-                                TrackItem(
-                                    id = trackObj.getString("id"),
-                                    title = trackObj.getString("title"),
-                                    artist = trackObj.getString("artist"),
-                                    album = trackObj.getString("album"),
-                                    duration = trackObj.getDouble("duration"),
-                                    url = trackObj.getString("url"),
-                                    artwork = artwork,
-                                    extraPayload = extraPayload,
-                                ),
-                            )
+                            }
+                            map
+                        } else {
+                            null
                         }
-                        val descriptionStr = jsonObject.optString("description")
-                        val artworkStr = jsonObject.optString("artwork")
-                        val playlist =
-                            Playlist(
-                                id = jsonObject.getString("id"),
-                                name = jsonObject.getString("name"),
-                                description = if (!descriptionStr.isNullOrEmpty()) descriptionStr else null,
-                                artwork = if (!artworkStr.isNullOrEmpty()) artworkStr else null,
-                                tracks = tracks,
-                            )
-                        playlists[playlist.id] = playlist
-                    }
+                    tracks.add(
+                        TrackItem(
+                            id = trackObj.getString("id"),
+                            title = trackObj.getString("title"),
+                            artist = trackObj.getString("artist"),
+                            album = trackObj.getString("album"),
+                            duration = trackObj.getDouble("duration"),
+                            url = trackObj.getString("url"),
+                            artwork = artwork,
+                            extraPayload = extraPayload,
+                        ),
+                    )
                 }
-                currentPlaylistId = sharedPreferences.getString("currentPlaylistId", null)
+                val descriptionStr = jsonObject.optString("description")
+                val artworkStr = jsonObject.optString("artwork")
+                val playlist =
+                    Playlist(
+                        id = jsonObject.getString("id"),
+                        name = jsonObject.getString("name"),
+                        description = if (!descriptionStr.isNullOrEmpty()) descriptionStr else null,
+                        artwork = if (!artworkStr.isNullOrEmpty()) artworkStr else null,
+                        tracks = tracks,
+                    )
+                playlists[playlist.id] = playlist
             }
-        } catch (e: Exception) {
-            e.printStackTrace()
         }
     }
 }

package/android/src/main/java/com/margelo/nitro/nitroplayer/storage/NitroPlayerStorage.kt

@@ -0,0 +1,50 @@
+package com.margelo.nitro.nitroplayer.storage
+
+import android.content.Context
+import com.margelo.nitro.nitroplayer.core.NitroPlayerLogger
+import java.io.File
+
+object NitroPlayerStorage {
+    private const val TAG = "NitroPlayerStorage"
+    private const val DIR_NAME = "nitroplayer"
+
+    /** Reads the contents of [filename] from the NitroPlayer storage directory, or null if absent. */
+    fun read(context: Context, filename: String): String? {
+        val file = File(storageDirectory(context), filename)
+        return if (file.exists()) {
+            try {
+                file.readText()
+            } catch (e: Exception) {
+                NitroPlayerLogger.log(TAG, "read($filename) failed: $e")
+                null
+            }
+        } else {
+            null
+        }
+    }
+
+    /**
+     * Atomically writes [json] to [filename] in the NitroPlayer storage directory.
+     * Writes to `<filename>.tmp` first, then renames — leaving the prior file
+     * untouched on failure (crash-safe).
+     */
+    fun write(context: Context, filename: String, json: String) {
+        try {
+            val dir = storageDirectory(context)
+            dir.mkdirs()
+            val tmp = File(dir, "$filename.tmp")
+            val dest = File(dir, filename)
+            tmp.writeText(json)
+            if (!tmp.renameTo(dest)) {
+                // renameTo can fail across mount points; copy then delete as fallback
+                dest.writeText(tmp.readText())
+                tmp.delete()
+            }
+        } catch (e: Exception) {
+            NitroPlayerLogger.log(TAG, "write($filename) failed: $e")
+        }
+    }
+
+    /** Returns the NitroPlayer subdirectory inside filesDir. */
+    private fun storageDirectory(context: Context): File = File(context.filesDir, DIR_NAME)
+}

package/ios/download/DownloadDatabase.swift

@@ -8,17 +8,17 @@
 import Foundation
 import NitroModules
 
-/// Manages persistence of downloaded track metadata using UserDefaults
+/// Manages persistence of downloaded track metadata using file storage
 final class DownloadDatabase {
 
   // MARK: - Singleton
 
   static let shared = DownloadDatabase()
 
-  // MARK: - Constants
+  // MARK: - Legacy UserDefaults Keys (migration only)
 
-  private static let downloadedTracksKey = "NitroPlayerDownloadedTracks"
-  private static let playlistTracksKey = "NitroPlayerPlaylistTracks"
+  private static let legacyDownloadedTracksKey = "NitroPlayerDownloadedTracks"
+  private static let legacyPlaylistTracksKey = "NitroPlayerPlaylistTracks"
 
   // MARK: - Properties
 
@@ -353,12 +353,21 @@ final class DownloadDatabase {
   private func saveToDisk() {
     do {
       let tracksData = try JSONEncoder().encode(downloadedTracks)
-      UserDefaults.standard.set(tracksData, forKey: Self.downloadedTracksKey)
-
       // Convert Set to Array for encoding
       let playlistTracksDict = playlistTracks.mapValues { Array($0) }
       let playlistData = try JSONEncoder().encode(playlistTracksDict)
-      UserDefaults.standard.set(playlistData, forKey: Self.playlistTracksKey)
+
+      // Combine both into a single JSON wrapper object
+      guard let tracksJson = try JSONSerialization.jsonObject(with: tracksData) as? [String: Any],
+            let playlistJson = try JSONSerialization.jsonObject(with: playlistData) as? [String: Any]
+      else { return }
+
+      let wrapper: [String: Any] = [
+        "downloadedTracks": tracksJson,
+        "playlistTracks": playlistJson,
+      ]
+      let data = try JSONSerialization.data(withJSONObject: wrapper, options: [])
+      try NitroPlayerStorage.write(filename: "downloads.json", data: data)
     } catch {
       NitroPlayerLogger.log("DownloadDatabase", "Failed to save to disk: \(error)")
     }
@@ -369,16 +378,42 @@ final class DownloadDatabase {
     NitroPlayerLogger.log("DownloadDatabase", "📀 LOADING FROM DISK")
     NitroPlayerLogger.log("DownloadDatabase", String(repeating: "📀", count: 40))
 
-    // Load synchronously to ensure data is available immediately
-    // Load downloaded tracks
-    if let tracksData = UserDefaults.standard.data(forKey: Self.downloadedTracksKey) {
+    // 1. Try new JSON file (post-migration)
+    if let data = NitroPlayerStorage.read(filename: "downloads.json") {
+      do {
+        if let wrapper = try JSONSerialization.jsonObject(with: data) as? [String: Any] {
+          if let tracksObj = wrapper["downloadedTracks"] as? [String: Any] {
+            let tracksData = try JSONSerialization.data(withJSONObject: tracksObj)
+            self.downloadedTracks = try JSONDecoder().decode(
+              [String: DownloadedTrackRecord].self, from: tracksData)
+            NitroPlayerLogger.log("DownloadDatabase", "✅ Loaded \(self.downloadedTracks.count) tracks from file")
+          }
+          if let playlistObj = wrapper["playlistTracks"] as? [String: Any] {
+            let playlistData = try JSONSerialization.data(withJSONObject: playlistObj)
+            let playlistTracksDict = try JSONDecoder().decode(
+              [String: [String]].self, from: playlistData)
+            self.playlistTracks = playlistTracksDict.mapValues { Set($0) }
+            NitroPlayerLogger.log("DownloadDatabase", "✅ Loaded \(self.playlistTracks.count) playlist associations from file")
+          }
+        }
+      } catch {
+        NitroPlayerLogger.log("DownloadDatabase", "❌ Failed to load from file: \(error)")
+      }
+      NitroPlayerLogger.log("DownloadDatabase", String(repeating: "📀", count: 40) + "\n")
+      return
+    }
+
+    // 2. Migrate from UserDefaults (one-time, existing installs)
+    var didMigrate = false
+
+    if let tracksData = UserDefaults.standard.data(forKey: Self.legacyDownloadedTracksKey) {
       do {
         self.downloadedTracks = try JSONDecoder().decode(
           [String: DownloadedTrackRecord].self, from: tracksData)
-        NitroPlayerLogger.log("DownloadDatabase", "✅ Loaded \(self.downloadedTracks.count) tracks from disk")
+        NitroPlayerLogger.log("DownloadDatabase", "✅ Migrated \(self.downloadedTracks.count) tracks from UserDefaults")
 
-        // Migrate absolute paths → filenames (one-time, for existing installs)
-        var needsMigration = false
+        // Migrate absolute paths → filenames (pre-existing migration)
+        var needsPathMigration = false
         for (trackId, record) in self.downloadedTracks {
           if record.localPath.contains("/") {
             let filename = URL(fileURLWithPath: record.localPath).lastPathComponent
@@ -391,41 +426,40 @@ final class DownloadDatabase {
               fileSize: record.fileSize,
               storageLocation: record.storageLocation
             )
-            needsMigration = true
+            needsPathMigration = true
           }
         }
-        if needsMigration { self.saveToDisk() }
-
-        // Log each downloaded track
-        for (trackId, record) in self.downloadedTracks {
-          NitroPlayerLogger.log("DownloadDatabase", "   📥 \(trackId)")
-          NitroPlayerLogger.log("DownloadDatabase", "      Title: \(record.originalTrack.title)")
-          NitroPlayerLogger.log("DownloadDatabase", "      Path (filename): \(record.localPath)")
+        if needsPathMigration {
+          NitroPlayerLogger.log("DownloadDatabase", "✅ Migrated absolute paths to filenames")
         }
+
+        UserDefaults.standard.removeObject(forKey: Self.legacyDownloadedTracksKey)
+        didMigrate = true
       } catch {
-        NitroPlayerLogger.log("DownloadDatabase", "❌ Failed to load tracks from disk: \(error)")
+        NitroPlayerLogger.log("DownloadDatabase", "❌ Failed to migrate tracks from UserDefaults: \(error)")
       }
     } else {
       NitroPlayerLogger.log("DownloadDatabase", "⚠️  No saved tracks found in UserDefaults")
     }
 
-    // Load playlist associations
-    if let playlistData = UserDefaults.standard.data(forKey: Self.playlistTracksKey) {
+    if let playlistData = UserDefaults.standard.data(forKey: Self.legacyPlaylistTracksKey) {
       do {
         let playlistTracksDict = try JSONDecoder().decode(
           [String: [String]].self, from: playlistData)
         self.playlistTracks = playlistTracksDict.mapValues { Set($0) }
-        NitroPlayerLogger.log("DownloadDatabase", "✅ Loaded \(self.playlistTracks.count) playlist associations from disk")
-
-        // Log playlist associations
-        for (playlistId, trackIds) in self.playlistTracks {
-          NitroPlayerLogger.log("DownloadDatabase", "   📋 Playlist \(playlistId): \(trackIds.count) tracks")
-        }
+        NitroPlayerLogger.log("DownloadDatabase", "✅ Migrated \(self.playlistTracks.count) playlist associations from UserDefaults")
+        UserDefaults.standard.removeObject(forKey: Self.legacyPlaylistTracksKey)
+        didMigrate = true
       } catch {
-        NitroPlayerLogger.log("DownloadDatabase", "❌ Failed to load playlist tracks from disk: \(error)")
+        NitroPlayerLogger.log("DownloadDatabase", "❌ Failed to migrate playlist tracks from UserDefaults: \(error)")
       }
     } else {
-      NitroPlayerLogger.log("DownloadDatabase", "⚠️  No playlist associations found")
+      NitroPlayerLogger.log("DownloadDatabase", "⚠️  No playlist associations found in UserDefaults")
+    }
+
+    if didMigrate {
+      // Persist migrated data in new file format
+      saveToDisk()
     }
 
     NitroPlayerLogger.log("DownloadDatabase", String(repeating: "📀", count: 40) + "\n")

package/ios/download/DownloadManagerCore.swift

@@ -18,8 +18,9 @@ final class DownloadManagerCore: NSObject {
   // MARK: - Constants
 
   private static let backgroundSessionIdentifier = "com.nitroplayer.backgroundDownloads"
-  private static let trackMetadataKey = "NitroPlayerTrackMetadata"
-  private static let playlistAssociationsKey = "NitroPlayerPlaylistAssociations"
+  // Legacy UserDefaults keys (migration only)
+  private static let legacyTrackMetadataKey = "NitroPlayerTrackMetadata"
+  private static let legacyPlaylistAssociationsKey = "NitroPlayerPlaylistAssociations"
 
   // MARK: - Properties
 
@@ -507,48 +508,87 @@ final class DownloadManagerCore: NSObject {
   private func loadPersistedMetadata() {
     NitroPlayerLogger.log("DownloadManagerCore", "📦 Loading persisted metadata...")
 
-    // Load track metadata
-    if let data = UserDefaults.standard.data(forKey: Self.trackMetadataKey) {
+    // 1. Try new JSON file (post-migration)
+    if let data = NitroPlayerStorage.read(filename: "download_metadata.json") {
+      do {
+        if let wrapper = try JSONSerialization.jsonObject(with: data) as? [String: Any] {
+          if let tracksObj = wrapper["trackMetadata"] as? [String: Any] {
+            let tracksData = try JSONSerialization.data(withJSONObject: tracksObj)
+            let records = try JSONDecoder().decode([String: TrackItemRecord].self, from: tracksData)
+            for (trackId, record) in records {
+              trackMetadata[trackId] = recordToTrackItem(record)
+            }
+            NitroPlayerLogger.log("DownloadManagerCore", "   ✅ Loaded \(trackMetadata.count) track metadata entries from file")
+          }
+          if let assocObj = wrapper["playlistAssociations"] as? [String: String] {
+            playlistAssociations = assocObj
+            NitroPlayerLogger.log("DownloadManagerCore", "   ✅ Loaded \(playlistAssociations.count) playlist associations from file")
+          }
+        }
+      } catch {
+        NitroPlayerLogger.log("DownloadManagerCore", "   ❌ Failed to load metadata from file: \(error)")
+      }
+      return
+    }
+
+    // 2. Migrate from UserDefaults (one-time, existing installs)
+    var didMigrate = false
+
+    if let data = UserDefaults.standard.data(forKey: Self.legacyTrackMetadataKey) {
       do {
         let records = try JSONDecoder().decode([String: TrackItemRecord].self, from: data)
         for (trackId, record) in records {
           trackMetadata[trackId] = recordToTrackItem(record)
         }
-        NitroPlayerLogger.log("DownloadManagerCore", "   ✅ Loaded \(trackMetadata.count) track metadata entries")
+        NitroPlayerLogger.log("DownloadManagerCore", "   ✅ Migrated \(trackMetadata.count) track metadata entries from UserDefaults")
+        UserDefaults.standard.removeObject(forKey: Self.legacyTrackMetadataKey)
+        didMigrate = true
       } catch {
-        NitroPlayerLogger.log("DownloadManagerCore", "   ❌ Failed to load track metadata: \(error)")
+        NitroPlayerLogger.log("DownloadManagerCore", "   ❌ Failed to migrate track metadata: \(error)")
       }
     } else {
       NitroPlayerLogger.log("DownloadManagerCore", "   ⚠️ No persisted track metadata found")
     }
 
-    // Load playlist associations
-    if let data = UserDefaults.standard.data(forKey: Self.playlistAssociationsKey) {
+    if let data = UserDefaults.standard.data(forKey: Self.legacyPlaylistAssociationsKey) {
       do {
         playlistAssociations = try JSONDecoder().decode([String: String].self, from: data)
-        NitroPlayerLogger.log("DownloadManagerCore", "   ✅ Loaded \(playlistAssociations.count) playlist associations")
+        NitroPlayerLogger.log("DownloadManagerCore", "   ✅ Migrated \(playlistAssociations.count) playlist associations from UserDefaults")
+        UserDefaults.standard.removeObject(forKey: Self.legacyPlaylistAssociationsKey)
+        didMigrate = true
       } catch {
-        NitroPlayerLogger.log("DownloadManagerCore", "   ❌ Failed to load playlist associations: \(error)")
+        NitroPlayerLogger.log("DownloadManagerCore", "   ❌ Failed to migrate playlist associations: \(error)")
       }
     } else {
       NitroPlayerLogger.log("DownloadManagerCore", "   ⚠️ No persisted playlist associations found")
     }
+
+    if didMigrate {
+      savePersistedMetadata()
+    }
   }
 
   /// Persist track metadata and playlist associations to disk
   private func savePersistedMetadata() {
-    // Convert TrackItem to TrackItemRecord for encoding
     var records: [String: TrackItemRecord] = [:]
     for (trackId, track) in trackMetadata {
       records[trackId] = trackItemToRecord(track)
     }
 
     do {
-      let trackData = try JSONEncoder().encode(records)
-      UserDefaults.standard.set(trackData, forKey: Self.trackMetadataKey)
-
+      let tracksData = try JSONEncoder().encode(records)
       let playlistData = try JSONEncoder().encode(playlistAssociations)
-      UserDefaults.standard.set(playlistData, forKey: Self.playlistAssociationsKey)
+
+      guard let tracksJson = try JSONSerialization.jsonObject(with: tracksData) as? [String: Any],
+            let assocJson = try JSONSerialization.jsonObject(with: playlistData) as? [String: Any]
+      else { return }
+
+      let wrapper: [String: Any] = [
+        "trackMetadata": tracksJson,
+        "playlistAssociations": assocJson,
+      ]
+      let data = try JSONSerialization.data(withJSONObject: wrapper, options: [])
+      try NitroPlayerStorage.write(filename: "download_metadata.json", data: data)
     } catch {
       NitroPlayerLogger.log("DownloadManagerCore", "❌ Failed to save metadata: \(error)")
     }

package/ios/playlist/PlaylistManager.swift

@@ -21,7 +21,7 @@ class PlaylistManager {
   static let shared = PlaylistManager()
 
   private init() {
-    loadPlaylistsFromUserDefaults()
+    loadFromFile()
   }
 
   /**
@@ -352,20 +352,18 @@ class PlaylistManager {
 
   private func scheduleSave() {
     saveDebounceWorkItem?.cancel()
-    let work = DispatchWorkItem { [weak self] in self?.savePlaylistsToUserDefaults() }
+    let work = DispatchWorkItem { [weak self] in self?.saveToFile() }
     saveDebounceWorkItem = work
-    // Use global background queue — savePlaylistsToUserDefaults calls queue.sync internally,
+    // Use global background queue — saveToFile calls queue.sync internally,
     // which would deadlock if scheduled on queue itself.
     DispatchQueue.global(qos: .utility).asyncAfter(deadline: .now() + 0.3, execute: work)
   }
 
-  private func savePlaylistsToUserDefaults() {
-    // Save playlists to UserDefaults for persistence
-    // Implementation similar to Android SharedPreferences
+  // MARK: - Persistence
+
+  private func saveToFile() {
     do {
-      let playlistsArray = queue.sync {
-        return Array(playlists.values)
-      }
+      let playlistsArray = queue.sync { Array(playlists.values) }
       let playlistsData = playlistsArray.map { playlist -> [String: Any] in
         return [
           "id": playlist.id,
@@ -381,13 +379,11 @@ class PlaylistManager {
               "duration": track.duration,
               "url": track.url,
             ]
-            // Handle artwork - unwrap Variant_NullType_String
             if let artwork = track.artwork, case .second(let artworkUrl) = artwork {
               trackDict["artwork"] = artworkUrl
             } else {
               trackDict["artwork"] = ""
             }
-            // Serialize extraPayload to dictionary for persistence
             if let extraPayload = track.extraPayload {
               trackDict["extraPayload"] = extraPayload.toDictionary()
             }
@@ -395,93 +391,118 @@ class PlaylistManager {
           },
         ]
       }
-      let data = try JSONSerialization.data(withJSONObject: playlistsData, options: [])
-      UserDefaults.standard.set(data, forKey: "NitroPlayerPlaylists")
-      UserDefaults.standard.set(currentPlaylistId, forKey: "NitroPlayerCurrentPlaylistId")
+      let wrapper: [String: Any] = [
+        "playlists": playlistsData,
+        "currentPlaylistId": currentPlaylistId as Any,
+      ]
+      let data = try JSONSerialization.data(withJSONObject: wrapper, options: [])
+      try NitroPlayerStorage.write(filename: "playlists.json", data: data)
     } catch {
       NitroPlayerLogger.log("PlaylistManager", "❌ Error saving playlists - \(error)")
     }
   }
 
-  private func loadPlaylistsFromUserDefaults() {
-    guard let data = UserDefaults.standard.data(forKey: "NitroPlayerPlaylists") else {
+  private func loadFromFile() {
+    // 1. Try new JSON file (post-migration)
+    if let data = NitroPlayerStorage.read(filename: "playlists.json") {
+      do {
+        if let wrapper = try JSONSerialization.jsonObject(with: data) as? [String: Any] {
+          let playlistsDict = wrapper["playlists"] as? [[String: Any]] ?? []
+          parsePlaylists(from: playlistsDict)
+          currentPlaylistId = wrapper["currentPlaylistId"] as? String
+        }
+      } catch {
+        NitroPlayerLogger.log("PlaylistManager", "❌ Error loading playlists - \(error)")
+      }
       return
     }
 
-    do {
-      let playlistsDict = try JSONSerialization.jsonObject(with: data) as? [[String: Any]] ?? []
+    // 2. Migrate from UserDefaults (one-time, existing installs)
+    if let data = UserDefaults.standard.data(forKey: "NitroPlayerPlaylists") {
+      do {
+        let playlistsDict = try JSONSerialization.jsonObject(with: data) as? [[String: Any]] ?? []
+        parsePlaylists(from: playlistsDict)
+        currentPlaylistId = UserDefaults.standard.string(forKey: "NitroPlayerCurrentPlaylistId")
+        // Remove old keys to free UserDefaults space
+        UserDefaults.standard.removeObject(forKey: "NitroPlayerPlaylists")
+        UserDefaults.standard.removeObject(forKey: "NitroPlayerCurrentPlaylistId")
+        // Persist in new format
+        saveToFile()
+      } catch {
+        NitroPlayerLogger.log("PlaylistManager", "❌ Error migrating playlists - \(error)")
+      }
+      return
+    }
 
-      queue.sync {
-        playlists.removeAll()
-        for playlistDict in playlistsDict {
-          guard let id = playlistDict["id"] as? String,
-            let name = playlistDict["name"] as? String
+    // 3. Fresh install — nothing to load
+  }
+
+  private func parsePlaylists(from playlistsDict: [[String: Any]]) {
+    queue.sync {
+      playlists.removeAll()
+      for playlistDict in playlistsDict {
+        guard let id = playlistDict["id"] as? String,
+          let name = playlistDict["name"] as? String
+        else {
+          continue
+        }
+
+        let description = playlistDict["description"] as? String
+        let artwork = playlistDict["artwork"] as? String
+        let tracksArray = playlistDict["tracks"] as? [[String: Any]] ?? []
+
+        let tracks = tracksArray.compactMap { trackDict -> TrackItem? in
+          guard let id = trackDict["id"] as? String,
+            let title = trackDict["title"] as? String,
+            let artist = trackDict["artist"] as? String,
+            let album = trackDict["album"] as? String,
+            let duration = trackDict["duration"] as? Double,
+            let url = trackDict["url"] as? String
           else {
-            continue
+            return nil
           }
 
-          let description = playlistDict["description"] as? String
-          let artwork = playlistDict["artwork"] as? String
-          let tracksArray = playlistDict["tracks"] as? [[String: Any]] ?? []
-
-          let tracks = tracksArray.compactMap { trackDict -> TrackItem? in
-            guard let id = trackDict["id"] as? String,
-              let title = trackDict["title"] as? String,
-              let artist = trackDict["artist"] as? String,
-              let album = trackDict["album"] as? String,
-              let duration = trackDict["duration"] as? Double,
-              let url = trackDict["url"] as? String
-            else {
-              return nil
-            }
+          let artworkString = trackDict["artwork"] as? String
+          let artwork = artworkString.flatMap {
+            !$0.isEmpty ? Variant_NullType_String.second($0) : nil
+          }
 
-            let artworkString = trackDict["artwork"] as? String
-            let artwork = artworkString.flatMap {
-              !$0.isEmpty ? Variant_NullType_String.second($0) : nil
-            }
-            
-            // Deserialize extraPayload from dictionary
-            var extraPayload: AnyMap? = nil
-            if let extraPayloadDict = trackDict["extraPayload"] as? [String: Any] {
-              extraPayload = AnyMap()
-              for (key, value) in extraPayloadDict {
-                if let stringValue = value as? String {
-                  extraPayload?.setString(key: key, value: stringValue)
-                } else if let doubleValue = value as? Double {
-                  extraPayload?.setDouble(key: key, value: doubleValue)
-                } else if let intValue = value as? Int {
-                  extraPayload?.setDouble(key: key, value: Double(intValue))
-                } else if let boolValue = value as? Bool {
-                  extraPayload?.setBoolean(key: key, value: boolValue)
-                }
+          var extraPayload: AnyMap? = nil
+          if let extraPayloadDict = trackDict["extraPayload"] as? [String: Any] {
+            extraPayload = AnyMap()
+            for (key, value) in extraPayloadDict {
+              if let stringValue = value as? String {
+                extraPayload?.setString(key: key, value: stringValue)
+              } else if let doubleValue = value as? Double {
+                extraPayload?.setDouble(key: key, value: doubleValue)
+              } else if let intValue = value as? Int {
+                extraPayload?.setDouble(key: key, value: Double(intValue))
+              } else if let boolValue = value as? Bool {
+                extraPayload?.setBoolean(key: key, value: boolValue)
               }
             }
-            
-            return TrackItem(
-              id: id,
-              title: title,
-              artist: artist,
-              album: album,
-              duration: duration,
-              url: url,
-              artwork: artwork,
-              extraPayload: extraPayload
-            )
           }
 
-          playlists[id] = PlaylistModel(
+          return TrackItem(
             id: id,
-            name: name,
-            description: description,
+            title: title,
+            artist: artist,
+            album: album,
+            duration: duration,
+            url: url,
             artwork: artwork,
-            tracks: tracks
+            extraPayload: extraPayload
           )
         }
-      }
 
-      currentPlaylistId = UserDefaults.standard.string(forKey: "NitroPlayerCurrentPlaylistId")
-    } catch {
-      NitroPlayerLogger.log("PlaylistManager", "❌ Error loading playlists - \(error)")
+        playlists[id] = PlaylistModel(
+          id: id,
+          name: name,
+          description: description,
+          artwork: artwork,
+          tracks: tracks
+        )
+      }
     }
   }
 }

package/ios/storage/NitroPlayerStorage.swift

@@ -0,0 +1,44 @@
+//
+//  NitroPlayerStorage.swift
+//  NitroPlayer
+//
+//  Created by Ritesh Shukla on 19/02/26.
+//
+
+import Foundation
+
+enum NitroPlayerStorage {
+  /// Reads raw data from a file in the NitroPlayer storage directory.
+  /// Returns nil if the file does not exist or cannot be read.
+  static func read(filename: String) -> Data? {
+    let url = storageDirectory().appendingPathComponent(filename)
+    return try? Data(contentsOf: url)
+  }
+
+  /// Atomically writes data to a file in the NitroPlayer storage directory.
+  /// Writes to `<filename>.tmp` first, then renames to the final name —
+  /// leaving the prior file untouched if the write crashes mid-way.
+  static func write(filename: String, data: Data) throws {
+    let dir = storageDirectory()
+    try FileManager.default.createDirectory(at: dir, withIntermediateDirectories: true)
+    let dest = dir.appendingPathComponent(filename)
+    let tmp = dir.appendingPathComponent(filename + ".tmp")
+    try data.write(to: tmp)
+    if FileManager.default.fileExists(atPath: dest.path) {
+      _ = try FileManager.default.replaceItemAt(dest, withItemAt: tmp)
+    } else {
+      try FileManager.default.moveItem(at: tmp, to: dest)
+    }
+  }
+
+  /// Returns the NitroPlayer subdirectory inside Application Support.
+  /// Uses `FileManager` APIs — never hardcodes the UUID-based container path
+  /// so this resolves correctly regardless of which device or simulator the
+  /// app runs on.
+  private static func storageDirectory() -> URL {
+    let appSupport = FileManager.default.urls(
+      for: .applicationSupportDirectory, in: .userDomainMask
+    ).first!
+    return appSupport.appendingPathComponent("NitroPlayer", isDirectory: true)
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-player",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "A powerful audio player library for React Native with playlist management, playback controls, and support for Android Auto and CarPlay",
   "main": "lib/index",
   "module": "lib/index",