@wwdrew/expo-apple-music 1.0.0

package/ios/PlaybackController.swift

@@ -0,0 +1,201 @@
+// PlaybackController.swift
+// Encapsulates ApplicationMusicPlayer operations with caching for song info.
+
+import AVFoundation
+import Foundation
+import MusicKit
+
+@available(iOS 16.0, *)
+final class PlaybackController {
+
+  // MARK: - Shared Instance
+
+  static let shared = PlaybackController()
+
+  // MARK: - Properties
+
+  private var player: ApplicationMusicPlayer {
+    ApplicationMusicPlayer.shared
+  }
+
+  var state: MusicKit.MusicPlayer.State {
+    player.state
+  }
+
+  var playbackTime: TimeInterval {
+    get { player.playbackTime }
+    set { player.playbackTime = newValue }
+  }
+
+  var currentEntry: ApplicationMusicPlayer.Queue.Entry? {
+    player.queue.currentEntry
+  }
+
+  // MARK: - Song Info Cache
+
+  private var cachedSongId: String?
+  private var cachedSongInfo: [String: Any]?
+
+  private lazy var catalogService = CatalogService()
+
+  // MARK: - Initialization
+
+  private init() {}
+
+  /// Clears the song info cache (call when queue changes significantly)
+  func clearSongCache() {
+    cachedSongId = nil
+    cachedSongInfo = nil
+  }
+
+  // MARK: - Audio Session Configuration
+
+  func configureAudioSession(mixWithOthers: Bool) throws {
+    let session = AVAudioSession.sharedInstance()
+    if mixWithOthers {
+      try session.setCategory(.playback, mode: .default, options: [.mixWithOthers, .duckOthers])
+    } else {
+      try session.setCategory(.playback, mode: .default)
+    }
+    try session.setActive(true)
+  }
+
+  // MARK: - Playback Controls
+
+  func play() async throws {
+    try await player.play()
+  }
+
+  func pause() {
+    player.pause()
+  }
+
+  func togglePlayback() async throws {
+    switch state.playbackStatus {
+    case .playing:
+      pause()
+    case .paused, .stopped, .interrupted:
+      try await play()
+    default:
+      try await play()
+    }
+  }
+
+  func skipToNext() async throws {
+    try await player.skipToNextEntry()
+  }
+
+  func skipToPrevious() async throws {
+    try await player.skipToPreviousEntry()
+  }
+
+  func restartCurrentEntry() {
+    player.restartCurrentEntry()
+  }
+
+  func seek(to time: TimeInterval) {
+    playbackTime = time
+  }
+
+  // MARK: - Queue Management
+
+  func setQueue<T: PlayableMusicItem>(_ item: T) async throws {
+    player.queue = [item]
+    try await player.prepareToPlay()
+  }
+
+  func setQueue<T: PlayableMusicItem>(_ items: [T], startingAt item: T) async throws {
+    player.queue = ApplicationMusicPlayer.Queue(for: items, startingAt: item)
+    try await player.prepareToPlay()
+  }
+
+  // MARK: - Current Song Info
+
+  /// Fetches detailed info for the current queue entry from the catalog.
+  /// Uses caching to avoid redundant network calls when the song hasn't changed.
+  func fetchCurrentSongInfo() async -> [String: Any]? {
+    guard let entry = currentEntry else {
+      // No current entry - clear cache and return nil
+      clearSongCache()
+      return nil
+    }
+
+    // Extract the current item's ID
+    let currentId: String?
+    switch entry.item {
+    case .song(let song):
+      let idString = String(describing: song.id)
+      // Skip if ID is empty (identifiers not yet resolved)
+      currentId = idString.isEmpty ? nil : idString
+
+    case .musicVideo(let musicVideo):
+      let idString = String(describing: musicVideo.id)
+      currentId = idString.isEmpty ? nil : idString
+
+    default:
+      currentId = nil
+    }
+
+    // If no valid ID, return cached info (if any) or nil
+    guard let currentId = currentId else {
+      return cachedSongInfo
+    }
+
+    // Return cached info if same song
+    if currentId == cachedSongId, let cached = cachedSongInfo {
+      return cached
+    }
+
+    // Prefer metadata from the queue entry (avoids catalog re-fetch by cloud playback ids).
+    let songInfo: [String: Any]?
+    switch entry.item {
+    case .song(let song):
+      songInfo = await songInfoForQueueEntry(song)
+
+    case .musicVideo(let musicVideo):
+      songInfo = await musicVideoInfoForQueueEntry(musicVideo)
+
+    default:
+      songInfo = nil
+    }
+
+    // Update cache only if we got valid info
+    if let songInfo = songInfo {
+      cachedSongId = currentId
+      cachedSongInfo = songInfo
+    }
+
+    return songInfo ?? cachedSongInfo
+  }
+
+  private func songInfoForQueueEntry(_ song: Song) async -> [String: Any] {
+    let mapped = MusicItemMapper.map(song)
+    if hasDisplayMetadata(mapped) {
+      return mapped
+    }
+    return await fetchSongDetailsFallback(song.id) ?? mapped
+  }
+
+  private func musicVideoInfoForQueueEntry(_ musicVideo: MusicVideo) async -> [String: Any] {
+    let mapped = MusicItemMapper.map(musicVideo)
+    if hasDisplayMetadata(mapped) {
+      return mapped
+    }
+    return await fetchMusicVideoDetailsFallback(musicVideo.id) ?? mapped
+  }
+
+  private func hasDisplayMetadata(_ mapped: [String: Any]) -> Bool {
+    let title = mapped["title"] as? String ?? ""
+    return !title.isEmpty
+  }
+
+  private func fetchSongDetailsFallback(_ id: MusicItemID) async -> [String: Any]? {
+    guard let song = try? await catalogService.fetchSong(id: id) else { return nil }
+    return MusicItemMapper.map(song)
+  }
+
+  private func fetchMusicVideoDetailsFallback(_ id: MusicItemID) async -> [String: Any]? {
+    guard let video = try? await catalogService.fetchMusicVideo(id: id) else { return nil }
+    return MusicItemMapper.map(video)
+  }
+}

package/ios/PlaybackObserver.swift

@@ -0,0 +1,225 @@
+// PlaybackObserver.swift
+// Modern Swift Concurrency-based observation for playback state and time updates.
+// Performance-optimized: network calls run off main thread, only UI updates on MainActor.
+
+import Combine
+import Foundation
+import MusicKit
+
+/// Protocol for receiving playback observation events.
+@available(iOS 16.0, *)
+protocol PlaybackObserverDelegate: AnyObject {
+  @MainActor func playbackStateDidChange(_ state: PlaybackObserver.PlaybackInfo)
+  @MainActor func currentSongDidChange(_ songInfo: [String: Any]?)
+  @MainActor func playbackTimeDidUpdate(_ time: TimeInterval)
+}
+
+@available(iOS 16.0, *)
+final class PlaybackObserver {
+
+  // MARK: - Types
+
+  struct PlaybackInfo {
+    let playbackStatus: String
+    let playbackRate: Float
+    let playbackTime: TimeInterval
+    let currentSong: [String: Any]?
+  }
+
+  // MARK: - Properties
+
+  weak var delegate: PlaybackObserverDelegate?
+
+  private let playbackController: PlaybackController
+  private var stateObservationTask: Task<Void, Never>?
+  private var queueObservationTask: Task<Void, Never>?
+  private var timeUpdateTask: Task<Void, Never>?
+
+  /// Thread-safe access to last reported status using actor isolation
+  private let statusTracker = StatusTracker()
+
+  /// Time update interval - 1 second provides good UX with less main thread pressure
+  private let timeUpdateInterval: TimeInterval = 1.0
+
+  // MARK: - Initialization
+
+  init(playbackController: PlaybackController = .shared) {
+    self.playbackController = playbackController
+  }
+
+  deinit {
+    stopObserving()
+  }
+
+  // MARK: - Observation Lifecycle
+
+  func startObserving() {
+    startStateObservation()
+    startQueueObservation()
+    // Start time updates if already playing
+    if playbackController.state.playbackStatus == .playing {
+      startTimeUpdates()
+    }
+  }
+
+  func stopObserving() {
+    stateObservationTask?.cancel()
+    queueObservationTask?.cancel()
+    timeUpdateTask?.cancel()
+    stateObservationTask = nil
+    queueObservationTask = nil
+    timeUpdateTask = nil
+    // Note: statusTracker doesn't need explicit reset - it will be deallocated with self
+  }
+
+  // MARK: - State Observation (Swift Concurrency)
+
+  private func startStateObservation() {
+    stateObservationTask?.cancel()
+    
+    // Capture dependencies outside the task to avoid capturing self
+    let playbackController = self.playbackController
+    let statusTracker = self.statusTracker
+    weak var weakDelegate = self.delegate
+    weak var weakSelf = self
+    
+    stateObservationTask = Task.detached {
+      // Use AsyncStream to bridge objectWillChange
+      let stateStream = AsyncStream<Void> { continuation in
+        let cancellable = ApplicationMusicPlayer.shared.state.objectWillChange.sink { _ in
+          continuation.yield()
+        }
+        continuation.onTermination = { _ in
+          cancellable.cancel()
+        }
+      }
+
+      for await _ in stateStream {
+        guard !Task.isCancelled else { break }
+        
+        let state = playbackController.state
+        let currentStatus = state.playbackStatus
+        
+        // Check if status actually changed (thread-safe via actor)
+        let shouldEmit = await statusTracker.updateIfChanged(currentStatus)
+        guard shouldEmit, !Task.isCancelled else { continue }
+        
+        // Fetch song info on background thread
+        let songInfo = await playbackController.fetchCurrentSongInfo()
+        guard !Task.isCancelled else { break }
+        
+        let info = PlaybackInfo(
+          playbackStatus: MusicItemMapper.describePlaybackStatus(currentStatus),
+          playbackRate: state.playbackRate,
+          playbackTime: playbackController.playbackTime,
+          currentSong: songInfo
+        )
+        
+        // Only hop to main thread for the UI callback
+        let delegate = weakDelegate
+        let observer = weakSelf
+        await MainActor.run {
+          delegate?.playbackStateDidChange(info)
+
+          // Manage time updates based on playback state
+          if currentStatus == .playing {
+            observer?.startTimeUpdates()
+          } else {
+            observer?.stopTimeUpdates()
+            let time = playbackController.playbackTime
+            delegate?.playbackTimeDidUpdate(time.isNaN ? 0 : time)
+          }
+        }
+      }
+    }
+  }
+
+  private func startQueueObservation() {
+    queueObservationTask?.cancel()
+    
+    // Capture dependencies outside the task to avoid capturing self
+    let playbackController = self.playbackController
+    weak var weakDelegate = self.delegate
+    
+    queueObservationTask = Task.detached {
+      let queueStream = AsyncStream<Void> { continuation in
+        let cancellable = ApplicationMusicPlayer.shared.queue.objectWillChange.sink { _ in
+          continuation.yield()
+        }
+        continuation.onTermination = { _ in
+          cancellable.cancel()
+        }
+      }
+
+      for await _ in queueStream {
+        guard !Task.isCancelled else { break }
+        
+        // Small delay to let queue settle (on background thread)
+        try? await Task.sleep(nanoseconds: 100_000_000) // 0.1 seconds
+        guard !Task.isCancelled else { break }
+        
+        // Fetch song info on background thread
+        let songInfo = await playbackController.fetchCurrentSongInfo()
+        guard !Task.isCancelled else { break }
+        
+        // Only hop to main thread for the UI callback
+        let delegate = weakDelegate
+        await MainActor.run {
+          delegate?.currentSongDidChange(songInfo)
+        }
+      }
+    }
+  }
+
+  // MARK: - Time Updates (Detached Task-based Timer)
+
+  private func startTimeUpdates() {
+    guard timeUpdateTask == nil else { return }
+
+    // Capture dependencies outside the task to avoid capturing self
+    let playbackController = self.playbackController
+    let timeUpdateInterval = self.timeUpdateInterval
+    weak var weakDelegate = self.delegate
+
+    timeUpdateTask = Task.detached {
+      while !Task.isCancelled {
+        let time = playbackController.playbackTime
+        let safeTime = time.isNaN ? 0 : time
+
+        // Minimal main thread work - just the delegate call
+        let delegate = weakDelegate
+        await MainActor.run {
+          delegate?.playbackTimeDidUpdate(safeTime)
+        }
+
+        try? await Task.sleep(nanoseconds: UInt64(timeUpdateInterval * 1_000_000_000))
+      }
+    }
+  }
+
+  private func stopTimeUpdates() {
+    timeUpdateTask?.cancel()
+    timeUpdateTask = nil
+  }
+}
+
+// MARK: - Status Tracker Actor
+
+/// Thread-safe tracker for last reported playback status
+@available(iOS 16.0, *)
+private actor StatusTracker {
+  private var lastReportedStatus: MusicPlayer.PlaybackStatus?
+
+  /// Returns true if the status changed and was updated
+  func updateIfChanged(_ newStatus: MusicPlayer.PlaybackStatus) -> Bool {
+    if lastReportedStatus != newStatus {
+      lastReportedStatus = newStatus
+      return true
+    }
+    return false
+  }
+
+  func reset() {
+    lastReportedStatus = nil
+  }
+}

package/ios/QueueService.swift

@@ -0,0 +1,166 @@
+// QueueService.swift
+// Management for both catalog and library items.
+
+import Foundation
+import MusicKit
+
+@available(iOS 16.0, *)
+final class QueueService {
+
+  // MARK: - Dependencies
+
+  private let playbackController: PlaybackController
+  private let catalogService: CatalogService
+
+  private func makeLibraryService() -> LibraryService {
+    LibraryService()
+  }
+
+  // MARK: - Initialization
+
+  init(
+    playbackController: PlaybackController = .shared,
+    catalogService: CatalogService = CatalogService()
+  ) {
+    self.playbackController = playbackController
+    self.catalogService = catalogService
+  }
+
+  // MARK: - Queue Setup
+
+  enum MediaType: String {
+    case song
+    case album
+    case playlist
+    case station
+  }
+
+  func setQueue(itemId: String, type: String) async throws {
+    let musicItemId = MusicItemID(itemId)
+    let isLibrary = Self.isLibraryId(itemId)
+
+    guard let mediaType = MediaType(rawValue: type) else {
+      throw QueueServiceError.unknownMediaType(type)
+    }
+
+    if isLibrary {
+      try await setLibraryQueue(id: musicItemId, type: mediaType)
+    } else {
+      try await setCatalogQueue(id: musicItemId, type: mediaType)
+    }
+  }
+
+  // MARK: - Catalog Queue
+
+  private func setCatalogQueue(id: MusicItemID, type: MediaType) async throws {
+    switch type {
+    case .song:
+      guard let song = try await catalogService.fetchSong(id: id) else {
+        throw QueueServiceError.itemNotFound("Song", inLibrary: false)
+      }
+      try await playbackController.setQueue(song)
+
+    case .album:
+      guard let album = try await catalogService.fetchAlbum(id: id) else {
+        throw QueueServiceError.itemNotFound("Album", inLibrary: false)
+      }
+      try await playbackController.setQueue(album)
+
+    case .playlist:
+      guard let playlist = try await catalogService.fetchPlaylist(id: id) else {
+        throw QueueServiceError.itemNotFound("Playlist", inLibrary: false)
+      }
+      try await playbackController.setQueue(playlist)
+
+    case .station:
+      guard let station = try await catalogService.fetchStation(id: id) else {
+        throw QueueServiceError.itemNotFound("Station", inLibrary: false)
+      }
+      try await playbackController.setQueue(station)
+    }
+  }
+
+  // MARK: - Library Queue
+
+  private func setLibraryQueue(id: MusicItemID, type: MediaType) async throws {
+    let service = makeLibraryService()
+
+    switch type {
+    case .song:
+      guard let song = try await service.fetchSong(id: id) else {
+        throw QueueServiceError.itemNotFound("Song", inLibrary: true)
+      }
+      try await playbackController.setQueue(song)
+
+    case .album:
+      guard let album = try await service.fetchAlbum(id: id) else {
+        throw QueueServiceError.itemNotFound("Album", inLibrary: true)
+      }
+      try await playbackController.setQueue(album)
+
+    case .playlist:
+      guard let playlist = try await service.fetchPlaylist(id: id) else {
+        throw QueueServiceError.itemNotFound("Playlist", inLibrary: true)
+      }
+      try await playbackController.setQueue(playlist)
+
+    case .station:
+      // Stations are typically not in the library
+      throw QueueServiceError.unsupportedLibraryType("station")
+    }
+  }
+
+  // MARK: - Library Playback with Starting Position
+
+  func playLibrarySong(musicUserToken: String, songId: String) async throws {
+    let service = makeLibraryService()
+    let id = MusicItemID(songId)
+    guard let song = try await service.fetchSong(id: id) else {
+      throw QueueServiceError.itemNotFound("Song", inLibrary: true)
+    }
+    try await playbackController.setQueue(song)
+  }
+
+  func playLibraryPlaylist(musicUserToken: String, playlistId: String, startingAt index: Int) async throws {
+    let service = makeLibraryService()
+    let id = MusicItemID(playlistId)
+    guard let playlist = try await service.fetchPlaylist(id: id) else {
+      throw QueueServiceError.itemNotFound("Playlist", inLibrary: true)
+    }
+
+    let songs = try await service.extractSongs(from: playlist)
+    guard !songs.isEmpty else {
+      throw LibraryServiceError.noSongsInPlaylist
+    }
+
+    let startIndex = (index >= 0 && index < songs.count) ? index : 0
+    try await playbackController.setQueue(songs, startingAt: songs[startIndex])
+  }
+
+  // MARK: - Helpers
+
+  /// Checks if an ID is a library ID (starts with "l.", "i.", or "p.")
+  static func isLibraryId(_ itemId: String) -> Bool {
+    itemId.hasPrefix("l.") || itemId.hasPrefix("i.") || itemId.hasPrefix("p.")
+  }
+}
+
+// MARK: - Errors
+
+enum QueueServiceError: LocalizedError {
+  case unknownMediaType(String)
+  case itemNotFound(String, inLibrary: Bool)
+  case unsupportedLibraryType(String)
+
+  var errorDescription: String? {
+    switch self {
+    case .unknownMediaType(let type):
+      return "Unknown media type: \(type)"
+    case .itemNotFound(let item, let inLibrary):
+      let source = inLibrary ? "library" : "catalog"
+      return "\(item) not found in \(source)"
+    case .unsupportedLibraryType(let type):
+      return "Unsupported library media type: \(type)"
+    }
+  }
+}

package/ios/RatingsService.swift

@@ -0,0 +1,66 @@
+// RatingsService.swift
+// Personal ratings and favorites via Apple Music REST API.
+
+import Foundation
+
+@available(iOS 16.0, *)
+final class RatingsService {
+
+  func getRating(musicUserToken: String, resourceType: String, id: String) async throws -> [String: Any]? {
+    do {
+      let json = try await AppleMusicRestClient.get(
+        path: "/v1/me/ratings/\(resourceType)/\(id)",
+        musicUserToken: musicUserToken
+      )
+      return RestJsonMapper.mapRating(json)
+    } catch let error as AppleMusicRestClient.RestError {
+      if case .apiError(let message) = error, message.contains("(404)") {
+        return nil
+      }
+      throw error
+    }
+  }
+
+  func setRating(musicUserToken: String, resourceType: String, id: String, value: Int) async throws -> [String: Any] {
+    let body: [String: Any] = [
+      "type": "rating",
+      "attributes": ["value": value],
+    ]
+    let json = try await AppleMusicRestClient.request(
+      method: .put,
+      path: "/v1/me/ratings/\(resourceType)/\(id)",
+      musicUserToken: musicUserToken,
+      body: body
+    )
+    guard let rating = RestJsonMapper.mapRating(json) else {
+      throw AppleMusicRestClient.RestError.invalidResponse
+    }
+    return rating
+  }
+
+  func clearRating(musicUserToken: String, resourceType: String, id: String) async throws {
+    _ = try await AppleMusicRestClient.request(
+      method: .delete,
+      path: "/v1/me/ratings/\(resourceType)/\(id)",
+      musicUserToken: musicUserToken
+    )
+  }
+
+  func addToFavorites(musicUserToken: String, resourceIds: [String: [String]]) async throws {
+    _ = try await AppleMusicRestClient.request(
+      method: .post,
+      path: "/v1/me/favorites",
+      musicUserToken: musicUserToken,
+      query: RestJsonMapper.buildIdsQuery(resourceIds)
+    )
+  }
+
+  func removeFromFavorites(musicUserToken: String, resourceIds: [String: [String]]) async throws {
+    _ = try await AppleMusicRestClient.request(
+      method: .delete,
+      path: "/v1/me/favorites",
+      musicUserToken: musicUserToken,
+      query: RestJsonMapper.buildIdsQuery(resourceIds)
+    )
+  }
+}

package/ios/RecommendationsService.swift

@@ -0,0 +1,34 @@
+// RecommendationsService.swift
+// Personal recommendations and Replay via Apple Music REST.
+
+import Foundation
+
+@available(iOS 16.0, *)
+final class RecommendationsService {
+
+  func getRecommendations(musicUserToken: String, ids: [String]?) async throws -> [[String: Any]] {
+    var query: [String: String] = [:]
+    if let ids, !ids.isEmpty {
+      query["ids"] = ids.joined(separator: ",")
+    }
+    let data = try await AppleMusicRestClient.getDataArray(
+      path: "/v1/me/recommendations",
+      musicUserToken: musicUserToken,
+      query: query
+    )
+    return data.map(RestJsonMapper.mapRecommendation)
+  }
+
+  func getReplay(musicUserToken: String, year: Int?) async throws -> [[String: Any]] {
+    var query: [String: String] = [:]
+    if let year {
+      query["filter[year]"] = "\(year)"
+    }
+    let data = try await AppleMusicRestClient.getDataArray(
+      path: "/v1/me/music-summaries",
+      musicUserToken: musicUserToken,
+      query: query
+    )
+    return data.map(RestJsonMapper.mapReplaySummary)
+  }
+}