react-native-nitro-player 0.0.1

package/ios/core/TrackPlayerCore.swift

@@ -0,0 +1,1040 @@
+//
+//  TrackPlayerCore.swift
+//  NitroPlayer
+//
+//  Created by Ritesh Shukla on 10/12/25.
+//
+
+import AVFoundation
+import Foundation
+import MediaPlayer
+import NitroModules
+import ObjectiveC
+
+class TrackPlayerCore: NSObject {
+  // MARK: - Constants
+
+  private enum Constants {
+    // Time thresholds (in seconds)
+    static let skipToPreviousThreshold: Double = 2.0
+    static let stateChangeDelay: TimeInterval = 0.1
+
+    // Duration thresholds for boundary intervals (in seconds)
+    static let twoHoursInSeconds: Double = 7200
+    static let oneHourInSeconds: Double = 3600
+
+    // Boundary time intervals (in seconds)
+    static let boundaryIntervalLong: Double = 5.0  // For tracks > 2 hours
+    static let boundaryIntervalMedium: Double = 2.0  // For tracks > 1 hour
+    static let boundaryIntervalDefault: Double = 1.0  // Default interval
+
+    // UI/Display constants
+    static let separatorLineLength: Int = 80
+    static let playlistSeparatorLength: Int = 40
+  }
+
+  // MARK: - Properties
+
+  private var player: AVQueuePlayer?
+  private let playlistManager = PlaylistManager.shared
+  private var mediaSessionManager: MediaSessionManager?
+  private var currentPlaylistId: String?
+  private var currentTrackIndex: Int = -1
+  private var currentTracks: [TrackItem] = []
+  private var isManuallySeeked = false
+  private var boundaryTimeObserver: Any?
+  private var currentItemObservers: [NSKeyValueObservation] = []
+
+  var onChangeTrack: ((TrackItem, Reason?) -> Void)?
+  var onPlaybackStateChange: ((TrackPlayerState, Reason?) -> Void)?
+  var onSeek: ((Double, Double) -> Void)?
+  var onPlaybackProgressChange: ((Double, Double, Bool?) -> Void)?
+
+  static let shared = TrackPlayerCore()
+
+  // MARK: - Initialization
+
+  private override init() {
+    super.init()
+    setupAudioSession()
+    setupPlayer()
+    mediaSessionManager = MediaSessionManager()
+    mediaSessionManager?.setTrackPlayerCore(self)
+  }
+
+  // MARK: - Setup
+
+  private func setupAudioSession() {
+    do {
+      let audioSession = AVAudioSession.sharedInstance()
+      try audioSession.setCategory(.playback, mode: .default, options: [])
+      try audioSession.setActive(true)
+    } catch {
+      print("❌ TrackPlayerCore: Failed to setup audio session - \(error)")
+    }
+  }
+
+  private func setupPlayer() {
+    player = AVQueuePlayer()
+    setupPlayerObservers()
+  }
+
+  private func setupPlayerObservers() {
+    guard let player = player else { return }
+
+    // Observe player status
+    player.addObserver(self, forKeyPath: "status", options: [.new], context: nil)
+    player.addObserver(self, forKeyPath: "rate", options: [.new], context: nil)
+
+    // Observe time control status
+    player.addObserver(self, forKeyPath: "timeControlStatus", options: [.new], context: nil)
+
+    // Observe current item changes
+    NotificationCenter.default.addObserver(
+      self,
+      selector: #selector(playerItemDidPlayToEndTime),
+      name: .AVPlayerItemDidPlayToEndTime,
+      object: nil
+    )
+
+    NotificationCenter.default.addObserver(
+      self,
+      selector: #selector(playerItemFailedToPlayToEndTime),
+      name: .AVPlayerItemFailedToPlayToEndTime,
+      object: nil
+    )
+
+    // Observe player item errors
+    NotificationCenter.default.addObserver(
+      self,
+      selector: #selector(playerItemNewErrorLogEntry),
+      name: .AVPlayerItemNewErrorLogEntry,
+      object: nil
+    )
+
+    // Observe time jumps (seeks)
+    NotificationCenter.default.addObserver(
+      self,
+      selector: #selector(playerItemTimeJumped),
+      name: .AVPlayerItemTimeJumped,
+      object: nil
+    )
+
+    // Observe when item changes (using KVO on currentItem)
+    player.addObserver(self, forKeyPath: "currentItem", options: [.new], context: nil)
+  }
+
+  // MARK: - Boundary Time Observer
+
+  private func setupBoundaryTimeObserver() {
+    // Remove existing boundary observer if any
+    if let existingObserver = boundaryTimeObserver, let currentPlayer = player {
+      currentPlayer.removeTimeObserver(existingObserver)
+      boundaryTimeObserver = nil
+    }
+
+    guard let player = player,
+      let currentItem = player.currentItem
+    else {
+      print("⚠️ TrackPlayerCore: Cannot setup boundary observer - no player or item")
+      return
+    }
+
+    // Wait for duration to be available
+    guard currentItem.status == .readyToPlay else {
+      print("⚠️ TrackPlayerCore: Item not ready, will setup boundaries when ready")
+      return
+    }
+
+    let duration = currentItem.duration.seconds
+    guard duration > 0 && !duration.isNaN && !duration.isInfinite else {
+      print("⚠️ TrackPlayerCore: Invalid duration: \(duration), cannot setup boundaries")
+      return
+    }
+
+    // Determine interval based on duration
+    let interval: Double
+    if duration > Constants.twoHoursInSeconds {
+      interval = Constants.boundaryIntervalLong
+    } else if duration > Constants.oneHourInSeconds {
+      interval = Constants.boundaryIntervalMedium
+    } else {
+      interval = Constants.boundaryIntervalDefault
+    }
+
+    // Create boundary times at each interval
+    var boundaryTimes: [NSValue] = []
+    var time: Double = 0
+    while time <= duration {
+      let cmTime = CMTime(seconds: time, preferredTimescale: CMTimeScale(NSEC_PER_SEC))
+      boundaryTimes.append(NSValue(time: cmTime))
+      time += interval
+    }
+
+    print(
+      "⏱️ TrackPlayerCore: Setting up \(boundaryTimes.count) boundary observers (interval: \(interval)s, duration: \(Int(duration))s)"
+    )
+
+    // Add boundary time observer
+    boundaryTimeObserver = player.addBoundaryTimeObserver(forTimes: boundaryTimes, queue: .main) {
+      [weak self] in
+      guard let self = self else { return }
+      self.handleBoundaryTimeCrossed()
+    }
+
+    print("⏱️ TrackPlayerCore: Boundary time observer setup complete")
+  }
+
+  private func handleBoundaryTimeCrossed() {
+    guard let player = player,
+      let currentItem = player.currentItem
+    else { return }
+
+    // Don't fire progress when paused
+    guard player.rate > 0 else { return }
+
+    let position = currentItem.currentTime().seconds
+    let duration = currentItem.duration.seconds
+
+    guard duration > 0 && !duration.isNaN && !duration.isInfinite else { return }
+
+    print(
+      "⏱️ TrackPlayerCore: Boundary crossed - position: \(Int(position))s / \(Int(duration))s, callback exists: \(onPlaybackProgressChange != nil)"
+    )
+
+    onPlaybackProgressChange?(
+      position,
+      duration,
+      isManuallySeeked ? true : nil
+    )
+    isManuallySeeked = false
+  }
+
+  // MARK: - Notification Handlers
+
+  @objc private func playerItemDidPlayToEndTime(notification: Notification) {
+    print("\n🏁 TrackPlayerCore: Track finished playing")
+
+    guard let finishedItem = notification.object as? AVPlayerItem else {
+      print("⚠️ Cannot identify finished item")
+      skipToNext()
+      return
+    }
+
+    if let trackId = finishedItem.trackId,
+      let track = currentTracks.first(where: { $0.id == trackId })
+    {
+      print("🏁 Finished: \(track.title)")
+    }
+
+    // Check remaining queue
+    if let player = player {
+      print("📋 Remaining items in queue: \(player.items().count)")
+    }
+
+    // Track ended naturally
+    onChangeTrack?(
+      getCurrentTrack()
+        ?? TrackItem(
+          id: "",
+          title: "",
+          artist: "",
+          album: "",
+          duration: 0,
+          url: "",
+          artwork: nil
+        ), .end)
+
+    // Try to play next track
+    skipToNext()
+  }
+
+  @objc private func playerItemFailedToPlayToEndTime(notification: Notification) {
+    if let error = notification.userInfo?[AVPlayerItemFailedToPlayToEndTimeErrorKey] as? Error {
+      print("❌ TrackPlayerCore: Playback failed - \(error)")
+      onPlaybackStateChange?(.stopped, .error)
+    }
+  }
+
+  @objc private func playerItemNewErrorLogEntry(notification: Notification) {
+    guard let item = notification.object as? AVPlayerItem,
+      let errorLog = item.errorLog()
+    else { return }
+
+    for event in errorLog.events ?? [] {
+      print(
+        "❌ TrackPlayerCore: Error log - \(event.errorComment ?? "Unknown error") - Code: \(event.errorStatusCode)"
+      )
+    }
+
+    // Also check item error
+    if let error = item.error {
+      print("❌ TrackPlayerCore: Item error - \(error.localizedDescription)")
+    }
+  }
+
+  @objc private func playerItemTimeJumped(notification: Notification) {
+    guard let player = player,
+      let currentItem = player.currentItem
+    else { return }
+
+    let position = currentItem.currentTime().seconds
+    let duration = currentItem.duration.seconds
+
+    print("🎯 TrackPlayerCore: Time jumped (seek detected) - position: \(Int(position))s")
+
+    // Call onSeek callback immediately
+    onSeek?(position, duration)
+
+    // Mark that this was a manual seek
+    isManuallySeeked = true
+
+    // Trigger immediate progress update
+    handleBoundaryTimeCrossed()
+  }
+
+  // MARK: - KVO Observer
+
+  override func observeValue(
+    forKeyPath keyPath: String?, of object: Any?, change: [NSKeyValueChangeKey: Any]?,
+    context: UnsafeMutableRawPointer?
+  ) {
+    guard let player = player else { return }
+
+    print("👀 TrackPlayerCore: KVO - keyPath: \(keyPath ?? "nil")")
+
+    if keyPath == "status" {
+      print("👀 TrackPlayerCore: Player status changed to: \(player.status.rawValue)")
+      if player.status == .readyToPlay {
+        emitStateChange()
+      } else if player.status == .failed {
+        print("❌ TrackPlayerCore: Player failed")
+        onPlaybackStateChange?(.stopped, .error)
+      }
+    } else if keyPath == "rate" {
+      print("👀 TrackPlayerCore: Rate changed to: \(player.rate)")
+      emitStateChange()
+    } else if keyPath == "timeControlStatus" {
+      print("👀 TrackPlayerCore: TimeControlStatus changed to: \(player.timeControlStatus.rawValue)")
+      emitStateChange()
+    } else if keyPath == "currentItem" {
+      print("👀 TrackPlayerCore: Current item changed")
+      currentItemDidChange()
+    }
+  }
+
+  // MARK: - Item Change Handling
+
+  @objc private func currentItemDidChange() {
+    // Clear old item observers
+    currentItemObservers.removeAll()
+
+    // Track changed - update index
+    guard let player = player,
+      let currentItem = player.currentItem
+    else {
+      print("⚠️ TrackPlayerCore: Current item changed to nil")
+      return
+    }
+
+    print("\n" + String(repeating: "▶", count: Constants.separatorLineLength))
+    print("🔄 TrackPlayerCore: CURRENT ITEM CHANGED")
+    print(String(repeating: "▶", count: Constants.separatorLineLength))
+
+    // Log current item details
+    if let trackId = currentItem.trackId,
+      let track = currentTracks.first(where: { $0.id == trackId })
+    {
+      print("▶️  NOW PLAYING: \(track.title) - \(track.artist) (ID: \(track.id))")
+    } else {
+      print("⚠️  NOW PLAYING: Unknown track (trackId: \(currentItem.trackId ?? "nil"))")
+    }
+
+    // Show remaining items in queue
+    let remainingItems = player.items()
+    print("\n📋 REMAINING ITEMS IN QUEUE: \(remainingItems.count)")
+    for (index, item) in remainingItems.enumerated() {
+      if let trackId = item.trackId, let track = currentTracks.first(where: { $0.id == trackId }) {
+        let marker = item == currentItem ? "▶️" : "  "
+        print("\(marker) [\(index + 1)] \(track.title) - \(track.artist)")
+      } else {
+        print("   [\(index + 1)] ⚠️ Unknown track")
+      }
+    }
+
+    print(String(repeating: "▶", count: Constants.separatorLineLength) + "\n")
+
+    // Log item status
+    print("📱 TrackPlayerCore: Item status: \(currentItem.status.rawValue)")
+
+    // Check for errors
+    if let error = currentItem.error {
+      print("❌ TrackPlayerCore: Current item has error - \(error.localizedDescription)")
+    }
+
+    // Setup KVO observers for current item
+    setupCurrentItemObservers(item: currentItem)
+
+    // Update track index
+    if let trackId = currentItem.trackId {
+      print("🔍 TrackPlayerCore: Looking up trackId '\(trackId)' in currentTracks...")
+      print("   Current index BEFORE lookup: \(currentTrackIndex)")
+
+      if let index = currentTracks.firstIndex(where: { $0.id == trackId }) {
+        print("   ✅ Found track at index: \(index)")
+        print("   Setting currentTrackIndex from \(currentTrackIndex) to \(index)")
+
+        let oldIndex = currentTrackIndex
+        currentTrackIndex = index
+
+        if let track = currentTracks[safe: index] {
+          print("   🎵 Track: \(track.title) - \(track.artist)")
+
+          // Only emit onChangeTrack if index actually changed
+          // This prevents duplicate emissions
+          if oldIndex != index {
+            print("   📢 Emitting onChangeTrack (index changed from \(oldIndex) to \(index))")
+            onChangeTrack?(track, .skip)
+            mediaSessionManager?.onTrackChanged()
+          } else {
+            print("   ⏭️ Skipping onChangeTrack emission (index unchanged)")
+          }
+        }
+      } else {
+        print("   ⚠️ Track ID '\(trackId)' NOT FOUND in currentTracks!")
+        print("   Current tracks:")
+        for (idx, track) in currentTracks.enumerated() {
+          print("      [\(idx)] \(track.id) - \(track.title)")
+        }
+      }
+    }
+
+    // Setup boundary observers when item is ready
+    if currentItem.status == .readyToPlay {
+      setupBoundaryTimeObserver()
+    }
+  }
+
+  private func setupCurrentItemObservers(item: AVPlayerItem) {
+    print("📱 TrackPlayerCore: Setting up item observers")
+
+    // Observe status - recreate boundaries when ready
+    let statusObserver = item.observe(\.status, options: [.new]) { [weak self] item, _ in
+      if item.status == .readyToPlay {
+        print("✅ TrackPlayerCore: Item ready, setting up boundaries")
+        self?.setupBoundaryTimeObserver()
+      } else if item.status == .failed {
+        print("❌ TrackPlayerCore: Item failed")
+        self?.onPlaybackStateChange?(.stopped, .error)
+      }
+    }
+    currentItemObservers.append(statusObserver)
+
+    // Observe playback buffer
+    let bufferEmptyObserver = item.observe(\.isPlaybackBufferEmpty, options: [.new]) { item, _ in
+      if item.isPlaybackBufferEmpty {
+        print("⏸️ TrackPlayerCore: Buffer empty (buffering)")
+      }
+    }
+    currentItemObservers.append(bufferEmptyObserver)
+
+    let bufferKeepUpObserver = item.observe(\.isPlaybackLikelyToKeepUp, options: [.new]) {
+      item, _ in
+      if item.isPlaybackLikelyToKeepUp {
+        print("▶️ TrackPlayerCore: Buffer likely to keep up")
+      }
+    }
+    currentItemObservers.append(bufferKeepUpObserver)
+  }
+
+  // MARK: - Playlist Management
+
+  func loadPlaylist(playlistId: String) {
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self else { return }
+
+      print("\n" + String(repeating: "🎼", count: Constants.playlistSeparatorLength))
+      print("📂 TrackPlayerCore: LOAD PLAYLIST REQUEST")
+      print("   Playlist ID: \(playlistId)")
+
+      let playlist = self.playlistManager.getPlaylist(playlistId: playlistId)
+      if let playlist = playlist {
+        print("   ✅ Found playlist: \(playlist.name)")
+        print("   📋 Contains \(playlist.tracks.count) tracks:")
+        for (index, track) in playlist.tracks.enumerated() {
+          print("      [\(index + 1)] \(track.title) - \(track.artist)")
+        }
+        print(String(repeating: "🎼", count: Constants.playlistSeparatorLength) + "\n")
+
+        self.currentPlaylistId = playlistId
+        self.updatePlayerQueue(tracks: playlist.tracks)
+        // Emit initial state (paused/stopped before play)
+        self.emitStateChange()
+        // Automatically start playback after loading
+        self.play()
+      } else {
+        print("   ❌ Playlist NOT FOUND")
+        print(String(repeating: "🎼", count: Constants.playlistSeparatorLength) + "\n")
+      }
+    }
+  }
+
+  func updatePlaylist(playlistId: String) {
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self else { return }
+      if self.currentPlaylistId == playlistId {
+        let playlist = self.playlistManager.getPlaylist(playlistId: playlistId)
+        if let playlist = playlist {
+          self.updatePlayerQueue(tracks: playlist.tracks)
+        }
+      }
+    }
+  }
+
+  // MARK: - Public Methods
+
+  func getCurrentPlaylistId() -> String? {
+    return currentPlaylistId
+  }
+
+  func getPlaylistManager() -> PlaylistManager {
+    return playlistManager
+  }
+
+  private func emitStateChange(reason: Reason? = nil) {
+    guard let player = player else { return }
+
+    let state: TrackPlayerState
+    if player.rate == 0 {
+      state = .paused
+    } else if player.timeControlStatus == .playing {
+      state = .playing
+    } else if player.timeControlStatus == .waitingToPlayAtSpecifiedRate {
+      state = .paused  // Buffering
+    } else {
+      state = .stopped
+    }
+
+    print("🔔 TrackPlayerCore: Emitting state change: \(state)")
+    print("🔔 TrackPlayerCore: Callback exists: \(onPlaybackStateChange != nil)")
+    onPlaybackStateChange?(state, reason)
+    mediaSessionManager?.onPlaybackStateChanged()
+  }
+
+  // MARK: - Queue Management
+
+  private func updatePlayerQueue(tracks: [TrackItem]) {
+    print("\n" + String(repeating: "=", count: Constants.separatorLineLength))
+    print("📋 TrackPlayerCore: UPDATE PLAYER QUEUE - Received \(tracks.count) tracks")
+    print(String(repeating: "=", count: Constants.separatorLineLength))
+
+    // Print the full playlist being fed
+    for (index, track) in tracks.enumerated() {
+      print("  [\(index + 1)] 🎵 \(track.title) - \(track.artist) (ID: \(track.id))")
+    }
+    print(String(repeating: "=", count: Constants.separatorLineLength) + "\n")
+
+    // Store tracks for index tracking
+    currentTracks = tracks
+    currentTrackIndex = 0
+    print("🔢 TrackPlayerCore: Reset currentTrackIndex to 0 (will be updated by KVO observer)")
+
+    // Remove old boundary observer if exists (this is safe)
+    if let boundaryObserver = boundaryTimeObserver, let currentPlayer = player {
+      currentPlayer.removeTimeObserver(boundaryObserver)
+      boundaryTimeObserver = nil
+    }
+
+    // Create AVPlayerItems from tracks
+    let items = tracks.compactMap { track -> AVPlayerItem? in
+      guard let url = URL(string: track.url) else {
+        print("❌ TrackPlayerCore: Invalid URL for track: \(track.title) - \(track.url)")
+        return nil
+      }
+
+      let item = AVPlayerItem(url: url)
+
+      // Set metadata using AVMutableMetadataItem
+      let metadata = AVMutableMetadataItem()
+      metadata.identifier = .commonIdentifierTitle
+      metadata.value = track.title as NSString
+      metadata.locale = Locale.current
+
+      let artistMetadata = AVMutableMetadataItem()
+      artistMetadata.identifier = .commonIdentifierArtist
+      artistMetadata.value = track.artist as NSString
+      artistMetadata.locale = Locale.current
+
+      let albumMetadata = AVMutableMetadataItem()
+      albumMetadata.identifier = .commonIdentifierAlbumName
+      albumMetadata.value = track.album as NSString
+      albumMetadata.locale = Locale.current
+
+      // Note: AVPlayerItem doesn't have externalMetadata property
+      // Metadata will be set via MPNowPlayingInfoCenter in MediaSessionManager
+
+      // Store track ID in item for later reference
+      item.trackId = track.id
+
+      return item
+    }
+
+    guard !items.isEmpty else {
+      print("❌ TrackPlayerCore: No valid items to play")
+      return
+    }
+
+    // Replace current queue (player should always exist after setupPlayer)
+    guard let existingPlayer = self.player else {
+      print("❌ TrackPlayerCore: No player available - this should never happen!")
+      return
+    }
+
+    print(
+      "🔄 TrackPlayerCore: Updating queue - removing \(existingPlayer.items().count) items, adding \(items.count) new items"
+    )
+
+    // Remove all existing items
+    existingPlayer.removeAllItems()
+
+    // Add new items IN ORDER
+    // IMPORTANT: insert(after: nil) puts item at the start
+    // To maintain order, we need to track the last inserted item
+    var lastItem: AVPlayerItem? = nil
+    for (index, item) in items.enumerated() {
+      existingPlayer.insert(item, after: lastItem)
+      lastItem = item
+
+      if let trackId = item.trackId, let track = tracks.first(where: { $0.id == trackId }) {
+        print("  ➕ Added to player queue [\(index + 1)]: \(track.title)")
+      }
+    }
+
+    // Verify what's actually in the player now
+    print(
+      "\n🔍 TrackPlayerCore: VERIFICATION - Player now has \(existingPlayer.items().count) items:")
+    for (index, item) in existingPlayer.items().enumerated() {
+      if let trackId = item.trackId, let track = tracks.first(where: { $0.id == trackId }) {
+        print("  [\(index + 1)] ✓ \(track.title) - \(track.artist) (ID: \(track.id))")
+      } else {
+        print("  [\(index + 1)] ⚠️ Unknown item (no trackId)")
+      }
+    }
+
+    if let currentItem = existingPlayer.currentItem, let trackId = currentItem.trackId {
+      if let track = tracks.first(where: { $0.id == trackId }) {
+        print("▶️  Current item: \(track.title)")
+      }
+    }
+    print(String(repeating: "=", count: Constants.separatorLineLength) + "\n")
+
+    // Note: Boundary time observers will be set up automatically when item becomes ready
+    // This happens in setupCurrentItemObservers() -> status observer -> setupBoundaryTimeObserver()
+
+    // Notify track change
+    if let firstTrack = tracks.first {
+      print("🎵 TrackPlayerCore: Emitting track change: \(firstTrack.title)")
+      print("🎵 TrackPlayerCore: onChangeTrack callback exists: \(onChangeTrack != nil)")
+      onChangeTrack?(firstTrack, nil)
+      mediaSessionManager?.onTrackChanged()
+    }
+
+    print("✅ TrackPlayerCore: Queue updated with \(items.count) tracks")
+  }
+
+  func getCurrentTrack() -> TrackItem? {
+    guard currentTrackIndex >= 0 && currentTrackIndex < currentTracks.count else {
+      return nil
+    }
+    return currentTracks[currentTrackIndex]
+  }
+
+  func play() {
+    print("▶️ TrackPlayerCore: play() called")
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self else { return }
+      print("▶️ TrackPlayerCore: Calling player.play()")
+      if let player = self.player {
+        print("▶️ TrackPlayerCore: Player status: \(player.status.rawValue)")
+        if let currentItem = player.currentItem {
+          print("▶️ TrackPlayerCore: Current item status: \(currentItem.status.rawValue)")
+          if let error = currentItem.error {
+            print("❌ TrackPlayerCore: Current item error: \(error.localizedDescription)")
+          }
+        }
+        player.play()
+        // Emit state change immediately for responsive UI
+        // KVO will also fire, but this ensures immediate feedback
+        DispatchQueue.main.asyncAfter(deadline: .now() + Constants.stateChangeDelay) {
+          [weak self] in
+          self?.emitStateChange()
+        }
+      } else {
+        print("❌ TrackPlayerCore: No player available")
+      }
+    }
+  }
+
+  func pause() {
+    print("⏸️ TrackPlayerCore: pause() called")
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self else { return }
+      self.player?.pause()
+      // Emit state change immediately for responsive UI
+      DispatchQueue.main.asyncAfter(deadline: .now() + Constants.stateChangeDelay) { [weak self] in
+        self?.emitStateChange()
+      }
+    }
+  }
+
+  func playSong(songId: String, fromPlaylist: String?) {
+    print(
+      "🎵 TrackPlayerCore: playSong() called - songId: \(songId), fromPlaylist: \(fromPlaylist ?? "nil")"
+    )
+
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self else { return }
+
+      var targetPlaylistId: String?
+      var songIndex: Int = -1
+
+      // Case 1: If fromPlaylist is provided, use that playlist
+      if let playlistId = fromPlaylist {
+        print("🎵 TrackPlayerCore: Looking for song in specified playlist: \(playlistId)")
+        if let playlist = self.playlistManager.getPlaylist(playlistId: playlistId) {
+          if let index = playlist.tracks.firstIndex(where: { $0.id == songId }) {
+            targetPlaylistId = playlistId
+            songIndex = index
+            print("✅ Found song at index \(index) in playlist \(playlistId)")
+          } else {
+            print("⚠️ Song \(songId) not found in specified playlist \(playlistId)")
+            return
+          }
+        } else {
+          print("⚠️ Playlist \(playlistId) not found")
+          return
+        }
+      }
+      // Case 2: If fromPlaylist is not provided, search in current/loaded playlist first
+      else {
+        print("🎵 TrackPlayerCore: No playlist specified, checking current playlist")
+
+        // Check if song exists in currently loaded playlist
+        if let currentId = self.currentPlaylistId,
+          let currentPlaylist = self.playlistManager.getPlaylist(playlistId: currentId)
+        {
+          if let index = currentPlaylist.tracks.firstIndex(where: { $0.id == songId }) {
+            targetPlaylistId = currentId
+            songIndex = index
+            print("✅ Found song at index \(index) in current playlist \(currentId)")
+          }
+        }
+
+        // If not found in current playlist, search in all playlists
+        if songIndex == -1 {
+          print("🔍 Song not found in current playlist, searching all playlists...")
+          let allPlaylists = self.playlistManager.getAllPlaylists()
+
+          for playlist in allPlaylists {
+            if let index = playlist.tracks.firstIndex(where: { $0.id == songId }) {
+              targetPlaylistId = playlist.id
+              songIndex = index
+              print("✅ Found song at index \(index) in playlist \(playlist.id)")
+              break
+            }
+          }
+
+          // If still not found, just use the first playlist if available
+          if songIndex == -1 && !allPlaylists.isEmpty {
+            targetPlaylistId = allPlaylists[0].id
+            songIndex = 0
+            print("⚠️ Song not found in any playlist, using first playlist and starting at index 0")
+          }
+        }
+      }
+
+      // Now play the song
+      guard let playlistId = targetPlaylistId, songIndex >= 0 else {
+        print("❌ Could not determine playlist or song index")
+        return
+      }
+
+      // Load playlist if it's different from current
+      if self.currentPlaylistId != playlistId {
+        print("🔄 Loading new playlist: \(playlistId)")
+        if let playlist = self.playlistManager.getPlaylist(playlistId: playlistId) {
+          self.currentPlaylistId = playlistId
+          self.updatePlayerQueue(tracks: playlist.tracks)
+        }
+      }
+
+      // Play from the found index
+      print("▶️ Playing from index: \(songIndex)")
+      self.playFromIndex(index: songIndex)
+    }
+  }
+
+  func skipToNext() {
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self,
+        let queuePlayer = self.player
+      else {
+        return
+      }
+
+      print("\n⏭️ TrackPlayerCore: SKIP TO NEXT")
+      print("   BEFORE:")
+      print("      currentTrackIndex: \(self.currentTrackIndex)")
+      print("      Total tracks in currentTracks: \(self.currentTracks.count)")
+      print("      Items in player queue: \(queuePlayer.items().count)")
+
+      if let currentItem = queuePlayer.currentItem, let trackId = currentItem.trackId {
+        if let track = self.currentTracks.first(where: { $0.id == trackId }) {
+          print("      Currently playing: \(track.title) (ID: \(track.id))")
+        }
+      }
+
+      // Check if there are more items in the queue
+      if self.currentTrackIndex + 1 < self.currentTracks.count {
+        print("   🔄 Calling advanceToNextItem()...")
+        queuePlayer.advanceToNextItem()
+
+        // NOTE: Don't manually update currentTrackIndex here!
+        // The KVO observer (currentItemDidChange) will update it automatically
+
+        print("   AFTER advanceToNextItem():")
+        print("      Items in player queue: \(queuePlayer.items().count)")
+
+        if let newCurrentItem = queuePlayer.currentItem, let trackId = newCurrentItem.trackId {
+          if let track = self.currentTracks.first(where: { $0.id == trackId }) {
+            print("      New current item: \(track.title) (ID: \(track.id))")
+          }
+        }
+
+        print("   ⏳ Waiting for KVO observer to update index...")
+      } else {
+        print("   ⚠️ No more tracks in playlist")
+        // At end of playlist - stop or loop
+        queuePlayer.pause()
+        self.onPlaybackStateChange?(.stopped, .end)
+      }
+    }
+  }
+
+  func skipToPrevious() {
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self,
+        let queuePlayer = self.player
+      else {
+        return
+      }
+
+      print("\n⏮️ TrackPlayerCore: SKIP TO PREVIOUS")
+      print("   Current index: \(self.currentTrackIndex)")
+      print("   Current time: \(queuePlayer.currentTime().seconds)s")
+
+      let currentTime = queuePlayer.currentTime()
+      if currentTime.seconds > Constants.skipToPreviousThreshold {
+        // If more than threshold seconds in, restart current track
+        print(
+          "   🔄 More than \(Int(Constants.skipToPreviousThreshold))s in, restarting current track")
+        queuePlayer.seek(to: .zero)
+      } else if self.currentTrackIndex > 0 {
+        // Go to previous track
+        let previousIndex = self.currentTrackIndex - 1
+        print("   ⏮️ Going to previous track at index \(previousIndex)")
+        self.playFromIndex(index: previousIndex)
+      } else {
+        // Already at first track, restart it
+        print("   🔄 Already at first track, restarting it")
+        queuePlayer.seek(to: .zero)
+      }
+    }
+  }
+
+  func seek(position: Double) {
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self, let player = self.player else { return }
+
+      self.isManuallySeeked = true
+      let time = CMTime(seconds: position, preferredTimescale: CMTimeScale(NSEC_PER_SEC))
+      player.seek(to: time) { [weak self] completed in
+        if completed {
+          let duration = player.currentItem?.duration.seconds ?? 0.0
+          self?.onSeek?(position, duration)
+        }
+      }
+    }
+  }
+
+  // MARK: - State Management
+
+  func getState() -> PlayerState {
+    guard let player = player else {
+      return PlayerState(
+        currentTrack: nil,
+        currentPosition: 0.0,
+        totalDuration: 0.0,
+        currentState: .stopped,
+        currentPlaylistId: currentPlaylistId.map { Variant_NullType_String.second($0) },
+        currentIndex: -1.0
+      )
+    }
+
+    let currentTrack = getCurrentTrack()
+    let currentPosition = player.currentTime().seconds
+    let totalDuration = player.currentItem?.duration.seconds ?? 0.0
+
+    let currentState: TrackPlayerState
+    if player.rate == 0 {
+      currentState = .paused
+    } else if player.timeControlStatus == .playing {
+      currentState = .playing
+    } else {
+      currentState = .stopped
+    }
+
+    // Get current index
+    let currentIndex: Double = currentTrackIndex >= 0 ? Double(currentTrackIndex) : -1.0
+
+    return PlayerState(
+      currentTrack: currentTrack.map { Variant_NullType_TrackItem.second($0) },
+      currentPosition: currentPosition,
+      totalDuration: totalDuration,
+      currentState: currentState,
+      currentPlaylistId: currentPlaylistId.map { Variant_NullType_String.second($0) },
+      currentIndex: currentIndex
+    )
+  }
+
+  func configure(
+    androidAutoEnabled: Bool?,
+    carPlayEnabled: Bool?,
+    showInNotification: Bool?
+  ) {
+    DispatchQueue.main.async { [weak self] in
+      self?.mediaSessionManager?.configure(
+        androidAutoEnabled: androidAutoEnabled,
+        carPlayEnabled: carPlayEnabled,
+        showInNotification: showInNotification
+      )
+    }
+  }
+
+  func getAllPlaylists() -> [Playlist] {
+    return playlistManager.getAllPlaylists().map { $0.toGeneratedPlaylist() }
+  }
+
+  func playFromIndex(index: Int) {
+    DispatchQueue.main.async { [weak self] in
+      guard let self = self,
+        index >= 0 && index < self.currentTracks.count
+      else {
+        print("❌ TrackPlayerCore: playFromIndex - invalid index \(index)")
+        return
+      }
+
+      print("\n🎯 TrackPlayerCore: PLAY FROM INDEX \(index)")
+      print("   Total tracks in playlist: \(self.currentTracks.count)")
+      print("   Current index: \(self.currentTrackIndex), target index: \(index)")
+
+      // Store the full playlist
+      let fullPlaylist = self.currentTracks
+
+      // Update currentTrackIndex BEFORE updating queue
+      self.currentTrackIndex = index
+
+      // Recreate the queue starting from the target index
+      // This ensures all remaining tracks are in the queue
+      let tracksToPlay = Array(fullPlaylist[index...])
+      print("   🔄 Creating queue with \(tracksToPlay.count) tracks starting from index \(index)")
+
+      // Update the queue (but keep the full currentTracks for reference)
+      let items = tracksToPlay.compactMap { track -> AVPlayerItem? in
+        guard let url = URL(string: track.url) else { return nil }
+        let item = AVPlayerItem(url: url)
+        item.trackId = track.id
+        return item
+      }
+
+      guard let player = self.player, !items.isEmpty else {
+        print("❌ No player or no items to play")
+        return
+      }
+
+      // Remove old boundary observer
+      if let boundaryObserver = self.boundaryTimeObserver {
+        player.removeTimeObserver(boundaryObserver)
+        self.boundaryTimeObserver = nil
+      }
+
+      // Clear and rebuild queue
+      player.removeAllItems()
+      var lastItem: AVPlayerItem? = nil
+      for item in items {
+        player.insert(item, after: lastItem)
+        lastItem = item
+      }
+
+      // Restore the full playlist reference (don't slice it!)
+      self.currentTracks = fullPlaylist
+
+      print("   ✅ Queue recreated. Now at index: \(self.currentTrackIndex)")
+      if let track = self.getCurrentTrack() {
+        print("   🎵 Playing: \(track.title)")
+        self.onChangeTrack?(track, .skip)
+        self.mediaSessionManager?.onTrackChanged()
+      }
+
+      player.play()
+    }
+  }
+
+  // MARK: - Cleanup
+
+  deinit {
+    print("🧹 TrackPlayerCore: Cleaning up...")
+
+    // Remove boundary time observer
+    if let boundaryObserver = boundaryTimeObserver, let currentPlayer = player {
+      currentPlayer.removeTimeObserver(boundaryObserver)
+    }
+
+    // Clear item observers (modern KVO automatically releases)
+    currentItemObservers.removeAll()
+
+    // Remove player KVO observers (these were added in setupPlayer)
+    if let currentPlayer = player {
+      currentPlayer.removeObserver(self, forKeyPath: "status")
+      currentPlayer.removeObserver(self, forKeyPath: "rate")
+      currentPlayer.removeObserver(self, forKeyPath: "timeControlStatus")
+      currentPlayer.removeObserver(self, forKeyPath: "currentItem")
+      print("✅ TrackPlayerCore: Player observers removed")
+    }
+
+    // Remove all notification observers
+    NotificationCenter.default.removeObserver(self)
+    print("✅ TrackPlayerCore: Cleanup complete")
+  }
+}
+
+// Safe array access extension
+extension Array {
+  subscript(safe index: Int) -> Element? {
+    return indices.contains(index) ? self[index] : nil
+  }
+}
+
+// Associated object extension for AVPlayerItem
+private var trackIdKey: UInt8 = 0
+
+extension AVPlayerItem {
+  var trackId: String? {
+    get {
+      return objc_getAssociatedObject(self, &trackIdKey) as? String
+    }
+    set {
+      objc_setAssociatedObject(self, &trackIdKey, newValue, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
+    }
+  }
+}