@rntp/player 5.0.0-beta.1 → 5.0.0-beta.3

package/RNTPPlayer.podspec

@@ -16,6 +16,7 @@ Pod::Spec.new do |s|
   s.source_files = "ios/**/*.{h,m,mm,swift}"
   s.exclude_files = "ios/tests/**", "ios/Package.swift"
   s.private_header_files = "ios/**/*.h"
+  s.frameworks = "CarPlay"
 
   install_modules_dependencies(s)
 end

package/android/src/main/java/com/doublesymmetry/trackplayer/TrackPlayerModule.kt

@@ -481,7 +481,7 @@ class TrackPlayerModule internal constructor(private val context: ReactApplicati
   // region Progress Sync
 
   @ReactMethod
-  fun updateProgressSyncHeaders(headers: ReadableMap) {
+  override fun updateProgressSyncHeaders(headers: ReadableMap) {
     val currentConfig = PlayerConfig().load(context)
     val newHeaders = mutableMapOf<String, String>()
     val iterator = headers.keySetIterator()
@@ -502,6 +502,66 @@ class TrackPlayerModule internal constructor(private val context: ReactApplicati
 
   // endregion
 
+  // region Sleep Timer
+
+  @ReactMethod
+  override fun sleepAfterTime(seconds: Double, fadeOutSeconds: Double) {
+    controller.run { mc ->
+      val args = Bundle().apply {
+        putDouble("seconds", seconds)
+        putDouble("fadeOutSeconds", fadeOutSeconds)
+      }
+      mc?.sendCustomCommand(
+        SessionCommand(TrackPlayerPlaybackService.COMMAND_SLEEP_AFTER_TIME, Bundle.EMPTY),
+        args
+      )
+    }
+  }
+
+  @ReactMethod
+  override fun sleepAfterMediaItemAtIndex(index: Double) {
+    controller.run { mc ->
+      val args = Bundle().apply { putInt("index", index.toInt()) }
+      mc?.sendCustomCommand(
+        SessionCommand(TrackPlayerPlaybackService.COMMAND_SLEEP_AFTER_MEDIA_ITEM, Bundle.EMPTY),
+        args
+      )
+    }
+  }
+
+  @ReactMethod(isBlockingSynchronousMethod = true)
+  override fun getSleepTimer(): WritableMap? {
+    val prefs = context.getSharedPreferences(PLAYER_PREFS_NAME, android.content.Context.MODE_PRIVATE)
+    val jsonStr = prefs.getString(TrackPlayerPlaybackService.SLEEP_TIMER_STATE_KEY, null) ?: return null
+    return try {
+      val json = JSONObject(jsonStr)
+      val type = json.getString("type")
+      val map = Arguments.createMap()
+      map.putString("type", type)
+      if (type == "time") {
+        map.putDouble("remainingSeconds", json.getDouble("remainingSeconds"))
+        map.putDouble("fadeOutSeconds", json.getDouble("fadeOutSeconds"))
+      } else {
+        map.putInt("index", json.getInt("index"))
+      }
+      map
+    } catch (e: Exception) {
+      null
+    }
+  }
+
+  @ReactMethod
+  override fun cancelSleepTimer() {
+    controller.run { mc ->
+      mc?.sendCustomCommand(
+        SessionCommand(TrackPlayerPlaybackService.COMMAND_CANCEL_SLEEP_TIMER, Bundle.EMPTY),
+        Bundle.EMPTY
+      )
+    }
+  }
+
+  // endregion
+
   // region Destroy
 
   @ReactMethod

package/android/src/main/java/com/doublesymmetry/trackplayer/TrackPlayerPlaybackService.kt

@@ -56,6 +56,7 @@ import com.doublesymmetry.trackplayer.models.WakeMode
 import android.os.Handler
 import android.os.Looper
 import com.doublesymmetry.trackplayer.models.PlaybackProgressUpdatedEvent
+import com.doublesymmetry.trackplayer.models.SleepTimerTriggeredEvent
 import org.json.JSONObject
 
 class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.MediaLibrarySession.Callback {
@@ -68,6 +69,14 @@ class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.Med
   private var progressSyncTimer: java.util.Timer? = null
   private var progressSyncExecutor: java.util.concurrent.ExecutorService? = null
 
+  private var sleepTimerType: String? = null // "time" or "mediaItem"
+  private var sleepTimerRemainingSeconds: Double = 0.0
+  private var sleepTimerFadeOutSeconds: Double = 0.0
+  private var sleepTimerTargetIndex: Int? = null
+  private var sleepTimer: java.util.Timer? = null
+  private var sleepTimerPreFadeVolume: Float? = null
+  private var sleepTimerPreviousIndex: Int? = null
+
   @OptIn(UnstableApi::class)
   override fun onCreate() {
     super.onCreate()
@@ -136,6 +145,26 @@ class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.Med
       override fun onIsPlayingChanged(isPlaying: Boolean) {
         if (isPlaying) startProgressSyncTimer() else stopProgressSyncTimer(fireFinalTick = true)
       }
+
+      override fun onMediaItemTransition(mediaItem: MediaItem?, reason: Int) {
+        val currentIndex = activePlayer?.currentMediaItemIndex ?: 0
+        if (sleepTimerType == "mediaItem") {
+          val targetIndex = sleepTimerTargetIndex
+          if (targetIndex != null && sleepTimerPreviousIndex == targetIndex && currentIndex != targetIndex) {
+            this@TrackPlayerPlaybackService.emitEvent(SleepTimerTriggeredEvent("mediaItem"))
+            cancelSleepTimerInternal(restoreVolume = false)
+            // Defer pause to next run loop — calling during transition gets overridden
+            Handler(Looper.getMainLooper()).post { activePlayer?.pause() }
+          }
+        }
+        sleepTimerPreviousIndex = currentIndex
+      }
+
+      override fun onTimelineChanged(timeline: androidx.media3.common.Timeline, reason: Int) {
+        if (sleepTimerType == "mediaItem" && (activePlayer?.mediaItemCount ?: 0) == 0) {
+          cancelSleepTimerInternal(restoreVolume = false)
+        }
+      }
     })
     val player = createForwardingPlayer(activePlayer, config)
 
@@ -275,6 +304,7 @@ class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.Med
     simpleCache?.release()
     simpleCache = null
     sharedCache = null
+    cancelSleepTimerInternal(restoreVolume = false)
     stopProgressSyncTimer(fireFinalTick = false)
     progressSyncExecutor?.shutdown()
     progressSyncExecutor = null
@@ -355,6 +385,37 @@ class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.Med
         activePlayer?.seekToPreviousMediaItem()
         return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
       }
+      COMMAND_SLEEP_AFTER_TIME -> {
+        val seconds = args.getDouble("seconds")
+        val fadeOutSeconds = args.getDouble("fadeOutSeconds")
+        cancelSleepTimerInternal(restoreVolume = true)
+        sleepTimerType = "time"
+        sleepTimerRemainingSeconds = seconds
+        sleepTimerFadeOutSeconds = fadeOutSeconds.coerceAtMost(seconds)
+        persistSleepTimerState()
+
+        if (seconds <= 0) {
+          activePlayer?.pause()
+          this@TrackPlayerPlaybackService.emitEvent(SleepTimerTriggeredEvent("time"))
+          cancelSleepTimerInternal(restoreVolume = true)
+        } else {
+          startSleepCountdownTimer()
+        }
+        return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
+      }
+      COMMAND_SLEEP_AFTER_MEDIA_ITEM -> {
+        val index = args.getInt("index")
+        cancelSleepTimerInternal(restoreVolume = true)
+        sleepTimerType = "mediaItem"
+        sleepTimerTargetIndex = index
+        sleepTimerPreviousIndex = activePlayer?.currentMediaItemIndex
+        persistSleepTimerState()
+        return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
+      }
+      COMMAND_CANCEL_SLEEP_TIMER -> {
+        cancelSleepTimerInternal(restoreVolume = true)
+        return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
+      }
     }
     return super.onCustomCommand(session, controller, customCommand, args)
   }
@@ -475,6 +536,9 @@ class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.Med
       .add(SessionCommand(COMMAND_SEEK_TO_NEXT, Bundle.EMPTY))
       .add(SessionCommand(COMMAND_SEEK_TO_PREVIOUS, Bundle.EMPTY))
       .add(SessionCommand(COMMAND_UPDATE_PROGRESS_SYNC_HEADERS, Bundle.EMPTY))
+      .add(SessionCommand(COMMAND_SLEEP_AFTER_TIME, Bundle.EMPTY))
+      .add(SessionCommand(COMMAND_SLEEP_AFTER_MEDIA_ITEM, Bundle.EMPTY))
+      .add(SessionCommand(COMMAND_CANCEL_SLEEP_TIMER, Bundle.EMPTY))
       .build()
 
   // endregion
@@ -554,6 +618,86 @@ class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.Med
 
   // endregion
 
+  // region Sleep Timer
+
+  private fun cancelSleepTimerInternal(restoreVolume: Boolean) {
+    sleepTimer?.cancel()
+    sleepTimer = null
+    if (restoreVolume) {
+      sleepTimerPreFadeVolume?.let { activePlayer?.volume = it }
+    }
+    sleepTimerPreFadeVolume = null
+    sleepTimerType = null
+    sleepTimerRemainingSeconds = 0.0
+    sleepTimerFadeOutSeconds = 0.0
+    sleepTimerTargetIndex = null
+    sleepTimerPreviousIndex = null
+    persistSleepTimerState()
+  }
+
+  private fun onSleepTimerTick() {
+    sleepTimerRemainingSeconds -= 1.0
+    persistSleepTimerState()
+
+    // Handle fade-out (before zero-check so final tick sets volume to 0)
+    if (sleepTimerFadeOutSeconds > 0 && sleepTimerRemainingSeconds < sleepTimerFadeOutSeconds) {
+      if (sleepTimerPreFadeVolume == null) {
+        sleepTimerPreFadeVolume = activePlayer?.volume ?: 1f
+      }
+      val progress = maxOf(0.0, sleepTimerRemainingSeconds / sleepTimerFadeOutSeconds).toFloat()
+      activePlayer?.volume = (sleepTimerPreFadeVolume ?: 1f) * progress
+    }
+
+    if (sleepTimerRemainingSeconds <= 0) {
+      sleepTimerRemainingSeconds = 0.0
+      activePlayer?.pause()
+      this@TrackPlayerPlaybackService.emitEvent(SleepTimerTriggeredEvent("time"))
+      // Restore volume after pausing so next playback isn't muted
+      cancelSleepTimerInternal(restoreVolume = true)
+      return
+    }
+  }
+
+  private fun startSleepCountdownTimer() {
+    sleepTimer?.cancel()
+    val handler = Handler(Looper.getMainLooper())
+    sleepTimer = java.util.Timer().apply {
+      scheduleAtFixedRate(object : java.util.TimerTask() {
+        override fun run() {
+          handler.post { onSleepTimerTick() }
+        }
+      }, 1000L, 1000L)
+    }
+  }
+
+  private fun pauseSleepCountdownTimer() {
+    sleepTimer?.cancel()
+    sleepTimer = null
+  }
+
+  private fun persistSleepTimerState() {
+    val prefs = getSharedPreferences(TrackPlayerModule.PLAYER_PREFS_NAME, MODE_PRIVATE)
+    val editor = prefs.edit()
+    val type = sleepTimerType
+    if (type == null) {
+      editor.remove(SLEEP_TIMER_STATE_KEY)
+    } else {
+      val json = JSONObject().apply {
+        put("type", type)
+        if (type == "time") {
+          put("remainingSeconds", sleepTimerRemainingSeconds)
+          put("fadeOutSeconds", sleepTimerFadeOutSeconds)
+        } else {
+          put("index", sleepTimerTargetIndex ?: 0)
+        }
+      }
+      editor.putString(SLEEP_TIMER_STATE_KEY, json.toString())
+    }
+    editor.apply()
+  }
+
+  // endregion
+
   // region Progress Sync
 
   private fun startProgressSyncTimer() {
@@ -651,6 +795,10 @@ class TrackPlayerPlaybackService: MediaLibraryService(), MediaLibraryService.Med
     const val COMMAND_SEEK_TO_PREVIOUS = "trackplayer.seek_to_previous"
     const val COMMAND_UPDATE_PROGRESS_SYNC_HEADERS = "trackplayer.update_progress_sync_headers"
     const val PROGRESS_SYNC_SAVED_KEY = "progress_sync_saved"
+    const val COMMAND_SLEEP_AFTER_TIME = "trackplayer.sleep_after_time"
+    const val COMMAND_SLEEP_AFTER_MEDIA_ITEM = "trackplayer.sleep_after_media_item"
+    const val COMMAND_CANCEL_SLEEP_TIMER = "trackplayer.cancel_sleep_timer"
+    const val SLEEP_TIMER_STATE_KEY = "sleep_timer_state"
 
     @Volatile
     var sharedCache: SimpleCache? = null

package/android/src/main/java/com/doublesymmetry/trackplayer/models/EmitEventType.kt

@@ -21,6 +21,7 @@ enum class EmitEventType(val value: String) {
   REMOTE_SKIP_FORWARD("event.remote-skip-forward"),
   REMOTE_SKIP_BACKWARD("event.remote-skip-backward"),
   PLAYBACK_PROGRESS_UPDATED("event.playback-progress-updated"),
+  SLEEP_TIMER_TRIGGERED("event.sleep-timer-triggered"),
 }
 
 interface EmitEvent {
@@ -116,3 +117,13 @@ data class PlaybackProgressUpdatedEvent(
     )
   }
 }
+
+data class SleepTimerTriggeredEvent(
+  val sleepType: String,
+): EmitEvent {
+  override val type = EmitEventType.SLEEP_TIMER_TRIGGERED
+
+  override fun pairs(): Array<Pair<String, Any>> {
+    return arrayOf("type" to sleepType)
+  }
+}

package/ios/CarPlay/BrowseTreeStore.swift

@@ -0,0 +1,40 @@
+//
+// Copyright (c) Double Symmetry GmbH
+// Commercial use requires a license. See https://rntp.dev/pricing
+//
+
+import Foundation
+
+class BrowseTreeStore {
+    static let shared = BrowseTreeStore()
+
+    static let didChangeNotification = Notification.Name("RNTPBrowseTreeDidChange")
+    static let nowPlayingChangedNotification = Notification.Name("RNTPNowPlayingChanged")
+
+    /// The current browse tree categories as raw dictionaries from JS.
+    private(set) var categories: [[String: Any]] = []
+
+    /// Reference to the AudioPlayer, set during setupPlayer().
+    weak var player: AudioPlayer?
+
+    /// The mediaId of the currently playing item, if any.
+    private(set) var currentMediaId: String?
+
+    private init() {}
+
+    func updateNowPlaying(mediaId: String?) {
+        currentMediaId = mediaId
+        NotificationCenter.default.post(name: Self.nowPlayingChangedNotification, object: nil)
+    }
+
+    func update(categories: [[String: Any]]) {
+        self.categories = categories
+        NotificationCenter.default.post(name: Self.didChangeNotification, object: nil)
+    }
+
+    func clear() {
+        self.categories = []
+        self.player = nil
+        NotificationCenter.default.post(name: Self.didChangeNotification, object: nil)
+    }
+}

package/ios/CarPlay/RNTPCarPlaySceneDelegate.swift

@@ -0,0 +1,254 @@
+//
+// Copyright (c) Double Symmetry GmbH
+// Commercial use requires a license. See https://rntp.dev/pricing
+//
+
+import CarPlay
+import UIKit
+
+@objc(RNTPCarPlaySceneDelegate)
+class RNTPCarPlaySceneDelegate: UIResponder, CPTemplateApplicationSceneDelegate {
+
+    private var interfaceController: CPInterfaceController?
+    private let imageCache = NSCache<NSString, UIImage>()
+    private var notificationObserver: NSObjectProtocol?
+    private var nowPlayingObserver: NSObjectProtocol?
+    /// All track list items keyed by mediaId, for updating isPlaying state.
+    private var listItemsByMediaId: [String: [CPListItem]] = [:]
+
+    // MARK: - CPTemplateApplicationSceneDelegate
+
+    func templateApplicationScene(
+        _ templateApplicationScene: CPTemplateApplicationScene,
+        didConnect interfaceController: CPInterfaceController
+    ) {
+        self.interfaceController = interfaceController
+        rebuildTemplates()
+
+        notificationObserver = NotificationCenter.default.addObserver(
+            forName: BrowseTreeStore.didChangeNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            self?.rebuildTemplates()
+        }
+
+        nowPlayingObserver = NotificationCenter.default.addObserver(
+            forName: BrowseTreeStore.nowPlayingChangedNotification,
+            object: nil,
+            queue: .main
+        ) { [weak self] _ in
+            self?.updateNowPlayingState()
+        }
+    }
+
+    func templateApplicationScene(
+        _ templateApplicationScene: CPTemplateApplicationScene,
+        didDisconnect interfaceController: CPInterfaceController
+    ) {
+        if let observer = notificationObserver {
+            NotificationCenter.default.removeObserver(observer)
+            notificationObserver = nil
+        }
+        if let observer = nowPlayingObserver {
+            NotificationCenter.default.removeObserver(observer)
+            nowPlayingObserver = nil
+        }
+        listItemsByMediaId = [:]
+        self.interfaceController = nil
+    }
+
+    // MARK: - Template Construction
+
+    private func rebuildTemplates() {
+        guard let interfaceController = interfaceController else { return }
+        listItemsByMediaId = [:]
+
+        let allCategories = BrowseTreeStore.shared.categories
+        // Filter out empty categories
+        let categories = allCategories.filter { cat in
+            guard let items = cat["items"] as? [[String: Any]] else { return false }
+            return !items.isEmpty
+        }
+
+        guard !categories.isEmpty else {
+            interfaceController.setRootTemplate(CPNowPlayingTemplate.shared, animated: true, completion: nil)
+            return
+        }
+
+        if categories.count == 1 {
+            let list = buildListTemplate(for: categories[0], categoryIndex: 0)
+            interfaceController.setRootTemplate(list, animated: true, completion: nil)
+            return
+        }
+
+        let maxTabs = min(4, CPTabBarTemplate.maximumTabCount)
+
+        if categories.count <= maxTabs {
+            let tabs = categories.enumerated().map { (i, cat) in
+                buildListTemplate(for: cat, categoryIndex: i)
+            }
+            let tabBar = CPTabBarTemplate(templates: tabs)
+            interfaceController.setRootTemplate(tabBar, animated: true, completion: nil)
+        } else {
+            // First (maxTabs - 1) as direct tabs, rest under "More"
+            let directCount = maxTabs - 1
+            var tabs: [CPListTemplate] = []
+            for i in 0..<directCount {
+                tabs.append(buildListTemplate(for: categories[i], categoryIndex: i))
+            }
+            let moreTab = buildMoreTemplate(categories: Array(categories.dropFirst(directCount)),
+                                            startingCategoryIndex: directCount)
+            tabs.append(moreTab)
+            let tabBar = CPTabBarTemplate(templates: tabs)
+            interfaceController.setRootTemplate(tabBar, animated: true, completion: nil)
+        }
+    }
+
+    // MARK: - List Template Builders
+
+    private func buildListTemplate(for category: [String: Any], categoryIndex: Int) -> CPListTemplate {
+        let title = category["title"] as? String ?? "Untitled"
+        let items = category["items"] as? [[String: Any]] ?? []
+
+        let maxItems = CPListTemplate.maximumItemCount
+        let truncated = maxItems > 0 ? Array(items.prefix(maxItems)) : items
+
+        let listItems: [CPListItem] = truncated.enumerated().map { (itemIndex, item) in
+            buildListItem(item: item, categoryIndex: categoryIndex, itemIndex: itemIndex)
+        }
+
+        let section = CPListSection(items: listItems)
+        let template = CPListTemplate(title: title, sections: [section])
+        template.tabTitle = title
+        return template
+    }
+
+    private func buildMoreTemplate(categories: [[String: Any]], startingCategoryIndex: Int) -> CPListTemplate {
+        let listItems: [CPListItem] = categories.enumerated().map { (offset, cat) in
+            let catTitle = cat["title"] as? String ?? "Untitled"
+            let item = CPListItem(text: catTitle, detailText: nil)
+            let catIndex = startingCategoryIndex + offset
+            item.userInfo = ["type": "category", "categoryIndex": catIndex]
+            item.handler = { [weak self] _, completion in
+                self?.handleMoreCategorySelected(category: cat, categoryIndex: catIndex)
+                completion()
+            }
+            return item
+        }
+
+        let section = CPListSection(items: listItems)
+        let template = CPListTemplate(title: "More", sections: [section])
+        template.tabTitle = "More"
+        template.tabImage = UIImage(systemName: "ellipsis.circle")
+        return template
+    }
+
+    private func handleMoreCategorySelected(category: [String: Any], categoryIndex: Int) {
+        let detail = buildListTemplate(for: category, categoryIndex: categoryIndex)
+        interfaceController?.pushTemplate(detail, animated: true, completion: nil)
+    }
+
+    // MARK: - List Item Builder
+
+    private func buildListItem(item: [String: Any], categoryIndex: Int, itemIndex: Int) -> CPListItem {
+        let title = item["title"] as? String ?? "Untitled"
+        let artist = item["artist"] as? String
+        let listItem = CPListItem(text: title, detailText: artist)
+
+        listItem.userInfo = ["categoryIndex": categoryIndex, "itemIndex": itemIndex]
+        listItem.handler = { [weak self] _, completion in
+            self?.handleItemSelected(categoryIndex: categoryIndex, itemIndex: itemIndex)
+            completion()
+        }
+
+        // Track by mediaId for now-playing state updates
+        if let mediaId = item["mediaId"] as? String {
+            listItemsByMediaId[mediaId, default: []].append(listItem)
+        }
+
+        // Mark as playing if this is the current item
+        if let mediaId = item["mediaId"] as? String,
+           mediaId == BrowseTreeStore.shared.currentMediaId {
+            listItem.isPlaying = true
+        }
+
+        // Load artwork async
+        if let artworkUrlString = item["artworkUrl"] as? String,
+           let artworkUrl = URL(string: artworkUrlString) {
+            loadImage(url: artworkUrl) { [weak listItem] image in
+                listItem?.setImage(image)
+            }
+        }
+
+        return listItem
+    }
+
+    // MARK: - Now Playing State
+
+    private func updateNowPlayingState() {
+        let currentMediaId = BrowseTreeStore.shared.currentMediaId
+        for (mediaId, items) in listItemsByMediaId {
+            let isPlaying = mediaId == currentMediaId
+            for item in items {
+                item.isPlaying = isPlaying
+            }
+        }
+    }
+
+    // MARK: - Playback
+
+    private func handleItemSelected(categoryIndex: Int, itemIndex: Int) {
+        guard let player = BrowseTreeStore.shared.player else { return }
+        let categories = BrowseTreeStore.shared.categories
+        guard categoryIndex < categories.count,
+              let items = categories[categoryIndex]["items"] as? [[String: Any]] else { return }
+
+        let mediaItems = items.compactMap { MediaItem(data: $0) }
+        guard !mediaItems.isEmpty else { return }
+
+        player.clear()
+        player.add(items: mediaItems)
+        let idx = min(itemIndex, mediaItems.count - 1)
+        if idx > 0 {
+            player.skipTo(index: idx)
+        }
+        player.play()
+    }
+
+    // MARK: - Artwork
+
+    private func loadImage(url: URL, completion: @escaping (UIImage) -> Void) {
+        let key = url.absoluteString as NSString
+        if let cached = imageCache.object(forKey: key) {
+            completion(cached)
+            return
+        }
+
+        URLSession.shared.dataTask(with: url) { [weak self] data, _, _ in
+            guard let data = data, let image = UIImage(data: data) else { return }
+
+            // Scale to CarPlay max image size
+            let maxSize = CPListItem.maximumImageSize
+            let scaled = Self.scaleImage(image, to: maxSize)
+
+            self?.imageCache.setObject(scaled, forKey: key)
+            DispatchQueue.main.async {
+                completion(scaled)
+            }
+        }.resume()
+    }
+
+    private static func scaleImage(_ image: UIImage, to maxSize: CGSize) -> UIImage {
+        let widthRatio = maxSize.width / image.size.width
+        let heightRatio = maxSize.height / image.size.height
+        let ratio = min(widthRatio, heightRatio, 1.0) // Don't upscale
+        if ratio >= 1.0 { return image }
+
+        let newSize = CGSize(width: image.size.width * ratio, height: image.size.height * ratio)
+        let renderer = UIGraphicsImageRenderer(size: newSize)
+        return renderer.image { _ in
+            image.draw(in: CGRect(origin: .zero, size: newSize))
+        }
+    }
+}