react-native-nitro-player 0.5.3 → 0.5.5

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
 
@@ -67,18 +67,16 @@ final class DownloadDatabase {
   func isTrackDownloaded(trackId: String) -> Bool {
     return queue.sync {
       guard let record = downloadedTracks[trackId] else {
-        print("🔍 DownloadDatabase: Track \(trackId) NOT found in database")
+        NitroPlayerLogger.log("DownloadDatabase", "🔍 Track \(trackId) NOT found in database")
         return false
       }
       // Verify file still exists
       let absolutePath = resolveAbsolutePath(for: record)
       let exists = FileManager.default.fileExists(atPath: absolutePath)
       if exists {
-        print("✅ DownloadDatabase: Track \(trackId) IS downloaded at \(absolutePath)")
+        NitroPlayerLogger.log("DownloadDatabase", "✅ Track \(trackId) IS downloaded at \(absolutePath)")
       } else {
-        print(
-          "❌ DownloadDatabase: Track \(trackId) record exists but file NOT found at \(absolutePath)"
-        )
+        NitroPlayerLogger.log("DownloadDatabase", "❌ Track \(trackId) record exists but file NOT found at \(absolutePath)")
       }
       return exists
     }
@@ -121,21 +119,21 @@ final class DownloadDatabase {
 
   func getDownloadedTrack(trackId: String) -> DownloadedTrack? {
     return queue.sync {
-      print("🔍 DownloadDatabase.getDownloadedTrack() for trackId: \(trackId)")
-      print("   Total records in memory: \(downloadedTracks.count)")
-      print("   Available trackIds: \(Array(downloadedTracks.keys))")
+      NitroPlayerLogger.log("DownloadDatabase", "🔍 DownloadDatabase.getDownloadedTrack() for trackId: \(trackId)")
+      NitroPlayerLogger.log("DownloadDatabase", "   Total records in memory: \(downloadedTracks.count)")
+      NitroPlayerLogger.log("DownloadDatabase", "   Available trackIds: \(Array(downloadedTracks.keys))")
 
       guard let record = downloadedTracks[trackId] else {
-        print("   ❌ No record found for trackId: \(trackId)")
+        NitroPlayerLogger.log("DownloadDatabase", "   ❌ No record found for trackId: \(trackId)")
         return nil
       }
 
       let absolutePath = resolveAbsolutePath(for: record)
-      print("   Found record, checking file at: \(absolutePath)")
+      NitroPlayerLogger.log("DownloadDatabase", "   Found record, checking file at: \(absolutePath)")
 
       // Verify file still exists
       guard FileManager.default.fileExists(atPath: absolutePath) else {
-        print("   ❌ File does NOT exist, cleaning up record")
+        NitroPlayerLogger.log("DownloadDatabase", "   ❌ File does NOT exist, cleaning up record")
         // File was deleted externally, clean up record
         queue.async(flags: .barrier) {
           self.downloadedTracks.removeValue(forKey: trackId)
@@ -144,34 +142,33 @@ final class DownloadDatabase {
         return nil
       }
 
-      print("   ✅ File exists, returning track")
+      NitroPlayerLogger.log("DownloadDatabase", "   ✅ File exists, returning track")
       return recordToDownloadedTrack(record)
     }
   }
 
   func getAllDownloadedTracks() -> [DownloadedTrack] {
     return queue.sync {
-      print(
-        "🎯 DownloadDatabase: getAllDownloadedTracks called, have \(downloadedTracks.count) records")
+      NitroPlayerLogger.log("DownloadDatabase", "🎯 getAllDownloadedTracks called, have \(downloadedTracks.count) records")
 
       var validTracks: [DownloadedTrack] = []
       var invalidTrackIds: [String] = []
 
       for (trackId, record) in downloadedTracks {
         let absolutePath = resolveAbsolutePath(for: record)
-        print("   Checking track \(trackId) at path: \(absolutePath)")
+        NitroPlayerLogger.log("DownloadDatabase", "   Checking track \(trackId) at path: \(absolutePath)")
         if FileManager.default.fileExists(atPath: absolutePath) {
-          print("   ✅ File exists")
+          NitroPlayerLogger.log("DownloadDatabase", "   ✅ File exists")
           validTracks.append(recordToDownloadedTrack(record))
         } else {
-          print("   ❌ File NOT found")
+          NitroPlayerLogger.log("DownloadDatabase", "   ❌ File NOT found")
           invalidTrackIds.append(trackId)
         }
       }
 
       // Clean up invalid records
       if !invalidTrackIds.isEmpty {
-        print("   Cleaning up \(invalidTrackIds.count) invalid records")
+        NitroPlayerLogger.log("DownloadDatabase", "   Cleaning up \(invalidTrackIds.count) invalid records")
         queue.async(flags: .barrier) {
           for trackId in invalidTrackIds {
             self.downloadedTracks.removeValue(forKey: trackId)
@@ -180,7 +177,7 @@ final class DownloadDatabase {
         }
       }
 
-      print("🎯 DownloadDatabase: Returning \(validTracks.count) valid tracks")
+      NitroPlayerLogger.log("DownloadDatabase", "🎯 Returning \(validTracks.count) valid tracks")
       return validTracks
     }
   }
@@ -238,7 +235,7 @@ final class DownloadDatabase {
   /// Returns the number of orphaned records that were cleaned up
   func syncDownloads() -> Int {
     return queue.sync(flags: .barrier) {
-      print("🔄 DownloadDatabase: syncDownloads called")
+      NitroPlayerLogger.log("DownloadDatabase", "🔄 syncDownloads called")
 
       var removedCount = 0
       var trackIdsToRemove: [String] = []
@@ -246,7 +243,7 @@ final class DownloadDatabase {
       for (trackId, record) in downloadedTracks {
         let absolutePath = resolveAbsolutePath(for: record)
         if !FileManager.default.fileExists(atPath: absolutePath) {
-          print("   ❌ Missing file for track \(trackId): \(absolutePath)")
+          NitroPlayerLogger.log("DownloadDatabase", "   ❌ Missing file for track \(trackId): \(absolutePath)")
           trackIdsToRemove.append(trackId)
         }
       }
@@ -271,9 +268,9 @@ final class DownloadDatabase {
 
       if removedCount > 0 {
         saveToDisk()
-        print("   ✅ Cleaned up \(removedCount) orphaned records")
+        NitroPlayerLogger.log("DownloadDatabase", "   ✅ Cleaned up \(removedCount) orphaned records")
       } else {
-        print("   ✅ All downloads are valid")
+        NitroPlayerLogger.log("DownloadDatabase", "   ✅ All downloads are valid")
       }
 
       return removedCount
@@ -356,32 +353,67 @@ 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 {
-      print("[DownloadDatabase] Failed to save to disk: \(error)")
+      NitroPlayerLogger.log("DownloadDatabase", "Failed to save to disk: \(error)")
     }
   }
 
   private func loadFromDisk() {
-    print("\n" + String(repeating: "📀", count: 40))
-    print("📀 DownloadDatabase: LOADING FROM DISK")
-    print(String(repeating: "📀", count: 40))
+    NitroPlayerLogger.log("DownloadDatabase", "\n" + String(repeating: "📀", count: 40))
+    NitroPlayerLogger.log("DownloadDatabase", "📀 LOADING FROM DISK")
+    NitroPlayerLogger.log("DownloadDatabase", String(repeating: "📀", count: 40))
+
+    // 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
 
-    // Load synchronously to ensure data is available immediately
-    // Load downloaded tracks
-    if let tracksData = UserDefaults.standard.data(forKey: Self.downloadedTracksKey) {
+    if let tracksData = UserDefaults.standard.data(forKey: Self.legacyDownloadedTracksKey) {
       do {
         self.downloadedTracks = try JSONDecoder().decode(
           [String: DownloadedTrackRecord].self, from: tracksData)
-        print("✅ 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
@@ -394,45 +426,43 @@ 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 {
-          print("   📥 \(trackId)")
-          print("      Title: \(record.originalTrack.title)")
-          print("      Path (filename): \(record.localPath)")
+        if needsPathMigration {
+          NitroPlayerLogger.log("DownloadDatabase", "✅ Migrated absolute paths to filenames")
         }
+
+        UserDefaults.standard.removeObject(forKey: Self.legacyDownloadedTracksKey)
+        didMigrate = true
       } catch {
-        print("❌ DownloadDatabase: Failed to load tracks from disk: \(error)")
+        NitroPlayerLogger.log("DownloadDatabase", "❌ Failed to migrate tracks from UserDefaults: \(error)")
       }
     } else {
-      print("⚠️  DownloadDatabase: No saved tracks found in UserDefaults")
+      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) }
-        print(
-          "✅ DownloadDatabase: Loaded \(self.playlistTracks.count) playlist associations from disk")
-
-        // Log playlist associations
-        for (playlistId, trackIds) in self.playlistTracks {
-          print("   📋 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 {
-        print("❌ DownloadDatabase: Failed to load playlist tracks from disk: \(error)")
+        NitroPlayerLogger.log("DownloadDatabase", "❌ Failed to migrate playlist tracks from UserDefaults: \(error)")
       }
     } else {
-      print("⚠️  DownloadDatabase: No playlist associations found")
+      NitroPlayerLogger.log("DownloadDatabase", "⚠️  No playlist associations found in UserDefaults")
+    }
+
+    if didMigrate {
+      // Persist migrated data in new file format
+      saveToDisk()
     }
 
-    print(String(repeating: "📀", count: 40) + "\n")
+    NitroPlayerLogger.log("DownloadDatabase", String(repeating: "📀", count: 40) + "\n")
   }
 
   // MARK: - Conversion Helpers

package/ios/download/DownloadFileManager.swift

@@ -60,14 +60,14 @@ final class DownloadFileManager {
     suggestedFilename: String? = nil,
     httpResponse: HTTPURLResponse? = nil
   ) -> String? {
-    print("🎯 DownloadFileManager: saveDownloadedFile called for trackId=\(trackId)")
-    print("   From: \(temporaryLocation.path)")
-    print("   Original URL: \(originalURL ?? "nil")")
-    print("   Suggested Filename: \(suggestedFilename ?? "nil")")
+    NitroPlayerLogger.log("DownloadFileManager", "saveDownloadedFile called for trackId=\(trackId)")
+    NitroPlayerLogger.log("DownloadFileManager", "   From: \(temporaryLocation.path)")
+    NitroPlayerLogger.log("DownloadFileManager", "   Original URL: \(originalURL ?? "nil")")
+    NitroPlayerLogger.log("DownloadFileManager", "   Suggested Filename: \(suggestedFilename ?? "nil")")
 
     let destinationDirectory =
       storageLocation == .private ? privateDownloadsDirectory : publicDownloadsDirectory
-    print("   Destination directory: \(destinationDirectory.path)")
+    NitroPlayerLogger.log("DownloadFileManager", "   Destination directory: \(destinationDirectory.path)")
 
     // Determine file extension using headers first, then URL path, then default
     let fileExtension = Self.resolveFileExtension(
@@ -75,32 +75,32 @@ final class DownloadFileManager {
       suggestedFilename: suggestedFilename,
       originalURL: originalURL
     )
-    print("   File extension: \(fileExtension)")
+    NitroPlayerLogger.log("DownloadFileManager", "   File extension: \(fileExtension)")
 
     let fileName = "\(trackId).\(fileExtension)"
     let destinationURL = destinationDirectory.appendingPathComponent(fileName)
-    print("   Destination: \(destinationURL.path)")
+    NitroPlayerLogger.log("DownloadFileManager", "   Destination: \(destinationURL.path)")
 
     // Verify source file exists
     guard fileManager.fileExists(atPath: temporaryLocation.path) else {
-      print("❌ DownloadFileManager: Source file does not exist at \(temporaryLocation.path)")
+      NitroPlayerLogger.log("DownloadFileManager", "❌ Source file does not exist at \(temporaryLocation.path)")
       return nil
     }
 
     do {
       // Remove existing file if present
       if fileManager.fileExists(atPath: destinationURL.path) {
-        print("   Removing existing file at destination")
+        NitroPlayerLogger.log("DownloadFileManager", "   Removing existing file at destination")
         try fileManager.removeItem(at: destinationURL)
       }
 
       // Move from temporary location to permanent location
       try fileManager.moveItem(at: temporaryLocation, to: destinationURL)
 
-      print("✅ DownloadFileManager: File saved successfully")
+      NitroPlayerLogger.log("DownloadFileManager", "✅ File saved successfully")
       return destinationURL.path
     } catch {
-      print("❌ DownloadFileManager: Failed to save file: \(error)")
+      NitroPlayerLogger.log("DownloadFileManager", "❌ Failed to save file: \(error)")
       return nil
     }
   }
@@ -133,7 +133,7 @@ final class DownloadFileManager {
     // 1. Content-Disposition: attachment; filename="track.mp3"
     if let disposition = httpResponse?.value(forHTTPHeaderField: "Content-Disposition") {
       if let ext = extensionFromContentDisposition(disposition), !ext.isEmpty {
-        print("   [ExtResolve] Content-Disposition → .\(ext)")
+        NitroPlayerLogger.log("DownloadFileManager", "   [ExtResolve] Content-Disposition → .\(ext)")
         return ext
       }
     }
@@ -142,7 +142,7 @@ final class DownloadFileManager {
     if let contentType = httpResponse?.value(forHTTPHeaderField: "Content-Type") {
       let mime = contentType.split(separator: ";").first.map(String.init)?.trimmingCharacters(in: .whitespaces) ?? contentType
       if let ext = mimeTypeToExtension[mime.lowercased()] {
-        print("   [ExtResolve] Content-Type '\(mime)' → .\(ext)")
+        NitroPlayerLogger.log("DownloadFileManager", "   [ExtResolve] Content-Type '\(mime)' → .\(ext)")
         return ext
       }
     }
@@ -151,7 +151,7 @@ final class DownloadFileManager {
     if let name = suggestedFilename, !name.isEmpty {
       let ext = URL(fileURLWithPath: name).pathExtension.lowercased()
       if !ext.isEmpty && isAudioExtension(ext) {
-        print("   [ExtResolve] suggestedFilename → .\(ext)")
+        NitroPlayerLogger.log("DownloadFileManager", "   [ExtResolve] suggestedFilename → .\(ext)")
         return ext
       }
     }
@@ -160,12 +160,12 @@ final class DownloadFileManager {
     if let urlString = originalURL, let url = URL(string: urlString) {
       let ext = url.pathExtension.lowercased()
       if !ext.isEmpty && isAudioExtension(ext) {
-        print("   [ExtResolve] URL path ext → .\(ext)")
+        NitroPlayerLogger.log("DownloadFileManager", "   [ExtResolve] URL path ext → .\(ext)")
         return ext
       }
     }
 
-    print("   [ExtResolve] fallback → .mp3")
+    NitroPlayerLogger.log("DownloadFileManager", "   [ExtResolve] fallback → .mp3")
     return "mp3"
   }
 
@@ -200,7 +200,7 @@ final class DownloadFileManager {
         try fileManager.removeItem(atPath: path)
       }
     } catch {
-      print("[DownloadFileManager] Failed to delete file: \(error)")
+      NitroPlayerLogger.log("DownloadFileManager", "Failed to delete file: \(error)")
     }
   }
 

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
 
@@ -372,12 +373,12 @@ final class DownloadManagerCore: NSObject {
   }
 
   func getLocalPath(trackId: String) -> String? {
-    print("🔍 DownloadManagerCore.getLocalPath() called for trackId: \(trackId)")
+    NitroPlayerLogger.log("DownloadManagerCore", "🔍 getLocalPath() called for trackId: \(trackId)")
     if let downloadedTrack = DownloadDatabase.shared.getDownloadedTrack(trackId: trackId) {
-      print("   ✅ Found downloaded track, localPath: \(downloadedTrack.localPath)")
+      NitroPlayerLogger.log("DownloadManagerCore", "   ✅ Found downloaded track, localPath: \(downloadedTrack.localPath)")
       return downloadedTrack.localPath
     } else {
-      print("   ❌ No downloaded track found for trackId: \(trackId)")
+      NitroPlayerLogger.log("DownloadManagerCore", "   ❌ No downloaded track found for trackId: \(trackId)")
       return nil
     }
   }
@@ -406,9 +407,7 @@ final class DownloadManagerCore: NSObject {
   func syncDownloads() -> Int {
     let removedFromDb = DownloadDatabase.shared.syncDownloads()
     let bytesFreed = DownloadFileManager.shared.cleanupOrphanedFiles()
-    print(
-      "🔄 DownloadManagerCore: syncDownloads completed - removed \(removedFromDb) orphaned records, freed \(bytesFreed) bytes"
-    )
+      NitroPlayerLogger.log("DownloadManagerCore", "🔄 syncDownloads completed - removed \(removedFromDb) orphaned records, freed \(bytesFreed) bytes")
     return removedFromDb
   }
 
@@ -426,27 +425,27 @@ final class DownloadManagerCore: NSObject {
 
   func getEffectiveUrl(track: TrackItem) -> String {
     let preference = getPlaybackSourcePreference()
-    print("🔍 DownloadManagerCore.getEffectiveUrl() for track: \(track.id)")
-    print("   Playback preference: \(preference)")
+    NitroPlayerLogger.log("DownloadManagerCore", "🔍 getEffectiveUrl() for track: \(track.id)")
+    NitroPlayerLogger.log("DownloadManagerCore", "   Playback preference: \(preference)")
 
     switch preference {
     case .network:
-      print("   → Using network URL (preference=network)")
+      NitroPlayerLogger.log("DownloadManagerCore", "   → Using network URL (preference=network)")
       return track.url
     case .download:
       if let localPath = getLocalPath(trackId: track.id) {
-        print("   → Using local path: \(localPath)")
+        NitroPlayerLogger.log("DownloadManagerCore", "   → Using local path: \(localPath)")
         return localPath
       } else {
-        print("   → Local path not found, falling back to network URL")
+        NitroPlayerLogger.log("DownloadManagerCore", "   → Local path not found, falling back to network URL")
         return track.url
       }
     case .auto:
       if let localPath = getLocalPath(trackId: track.id) {
-        print("   → Using local path: \(localPath)")
+        NitroPlayerLogger.log("DownloadManagerCore", "   → Using local path: \(localPath)")
         return localPath
       } else {
-        print("   → Local path not found, using network URL")
+        NitroPlayerLogger.log("DownloadManagerCore", "   → Local path not found, using network URL")
         return track.url
       }
     }
@@ -507,52 +506,91 @@ final class DownloadManagerCore: NSObject {
 
   /// Load persisted track metadata and playlist associations (survives app restart)
   private func loadPersistedMetadata() {
-    print("📦 DownloadManagerCore: Loading persisted metadata...")
+    NitroPlayerLogger.log("DownloadManagerCore", "📦 Loading persisted metadata...")
+
+    // 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
 
-    // Load track metadata
-    if let data = UserDefaults.standard.data(forKey: Self.trackMetadataKey) {
+    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)
         }
-        print("   ✅ 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 {
-        print("   ❌ Failed to load track metadata: \(error)")
+        NitroPlayerLogger.log("DownloadManagerCore", "   ❌ Failed to migrate track metadata: \(error)")
       }
     } else {
-      print("   ⚠️ No persisted track metadata found")
+      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)
-        print("   ✅ Loaded \(playlistAssociations.count) playlist associations")
+        NitroPlayerLogger.log("DownloadManagerCore", "   ✅ Migrated \(playlistAssociations.count) playlist associations from UserDefaults")
+        UserDefaults.standard.removeObject(forKey: Self.legacyPlaylistAssociationsKey)
+        didMigrate = true
       } catch {
-        print("   ❌ Failed to load playlist associations: \(error)")
+        NitroPlayerLogger.log("DownloadManagerCore", "   ❌ Failed to migrate playlist associations: \(error)")
       }
     } else {
-      print("   ⚠️ No persisted playlist associations found")
+      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 {
-      print("❌ DownloadManagerCore: Failed to save metadata: \(error)")
+      NitroPlayerLogger.log("DownloadManagerCore", "❌ Failed to save metadata: \(error)")
     }
   }
 
@@ -657,24 +695,22 @@ extension DownloadManagerCore: URLSessionDownloadDelegate {
     _ session: URLSession, downloadTask: URLSessionDownloadTask,
     didFinishDownloadingTo location: URL
   ) {
-    print("🎯 DownloadManagerCore: didFinishDownloadingTo called")
+    NitroPlayerLogger.log("DownloadManagerCore", "🎯 didFinishDownloadingTo called")
 
     guard let description = downloadTask.taskDescription else {
-      print("❌ DownloadManagerCore: No task description")
+      NitroPlayerLogger.log("DownloadManagerCore", "❌ No task description")
       return
     }
     let parts = description.split(separator: "|")
     guard parts.count == 2 else {
-      print("❌ DownloadManagerCore: Invalid task description format: \(description)")
+      NitroPlayerLogger.log("DownloadManagerCore", "❌ Invalid task description format: \(description)")
       return
     }
 
     let downloadId = String(parts[0])
     let trackId = String(parts[1])
 
-    print(
-      "🎯 DownloadManagerCore: Processing completion for downloadId=\(downloadId), trackId=\(trackId)"
-    )
+      NitroPlayerLogger.log("DownloadManagerCore", "🎯 Processing completion for downloadId=\(downloadId), trackId=\(trackId)")
 
     // IMPORTANT: Move file SYNCHRONOUSLY - the temp file is deleted after this method returns!
     // Get storage location and original URL from track metadata
@@ -698,7 +734,7 @@ extension DownloadManagerCore: URLSessionDownloadDelegate {
     // Now handle the rest asynchronously
     queue.async(flags: .barrier) {
       guard let destinationPath = destinationPath else {
-        print("❌ DownloadManagerCore: Failed to save file for trackId=\(trackId)")
+        NitroPlayerLogger.log("DownloadManagerCore", "❌ Failed to save file for trackId=\(trackId)")
         self.taskMetadata[downloadId]?.state = .failed
         self.taskMetadata[downloadId]?.error = DownloadError(
           code: "FILE_MOVE_FAILED",
@@ -712,11 +748,11 @@ extension DownloadManagerCore: URLSessionDownloadDelegate {
         return
       }
 
-      print("✅ DownloadManagerCore: File saved to \(destinationPath)")
+      NitroPlayerLogger.log("DownloadManagerCore", "✅ File saved to \(destinationPath)")
 
       guard let track = self.trackMetadata[trackId] else {
-        print("❌ DownloadManagerCore: No track metadata for trackId=\(trackId)")
-        print("   Available trackIds: \(Array(self.trackMetadata.keys))")
+        NitroPlayerLogger.log("DownloadManagerCore", "❌ No track metadata for trackId=\(trackId)")
+        NitroPlayerLogger.log("DownloadManagerCore", "   Available trackIds: \(Array(self.trackMetadata.keys))")
 
         // Still mark as completed even if we don't have metadata
         self.taskMetadata[downloadId]?.state = .completed
@@ -747,7 +783,7 @@ extension DownloadManagerCore: URLSessionDownloadDelegate {
       // Save to database
       DownloadDatabase.shared.saveDownloadedTrack(downloadedTrack, playlistId: playlistId)
 
-      print("✅ DownloadManagerCore: Track saved to database")
+      NitroPlayerLogger.log("DownloadManagerCore", "✅ Track saved to database")
 
       // Clean up persisted metadata (no longer needed after completion)
       self.cleanupPersistedMetadata(trackId: trackId, downloadId: downloadId)
@@ -760,7 +796,7 @@ extension DownloadManagerCore: URLSessionDownloadDelegate {
       self.activeTasks.removeValue(forKey: downloadId)
 
       // Notify
-      print("✅ DownloadManagerCore: Notifying completion for trackId=\(trackId)")
+      NitroPlayerLogger.log("DownloadManagerCore", "✅ Notifying completion for trackId=\(trackId)")
       self.notifyStateChange(
         downloadId: downloadId, trackId: trackId, state: .completed, error: nil)
       self.notifyComplete(downloadedTrack)