react-native-nitro-player 0.7.0 → 0.7.1-alpha.0

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

@@ -1,11 +1,15 @@
+@file:Suppress("ktlint:standard:max-line-length")
+
 package com.margelo.nitro.nitroplayer
 
 import androidx.annotation.Keep
-import com.facebook.jni.HybridData
 import com.facebook.proguard.annotations.DoNotStrip
 import com.margelo.nitro.NitroModules
 import com.margelo.nitro.core.NullType
+import com.margelo.nitro.core.Promise
 import com.margelo.nitro.nitroplayer.core.TrackPlayerCore
+import com.margelo.nitro.nitroplayer.core.loadPlaylist
+import com.margelo.nitro.nitroplayer.core.updatePlaylist
 import com.margelo.nitro.nitroplayer.playlist.PlaylistManager
 import java.util.UUID
 import com.margelo.nitro.nitroplayer.playlist.Playlist as InternalPlaylist
@@ -17,7 +21,8 @@ class HybridPlayerQueue : HybridPlayerQueueSpec() {
     private val playlistManager: PlaylistManager
 
     init {
-        val context = NitroModules.applicationContext ?: throw IllegalStateException("React Context is not initialized")
+        val context = NitroModules.applicationContext
+            ?: throw IllegalStateException("React Context is not initialized")
         core = TrackPlayerCore.getInstance(context)
         playlistManager = core.getPlaylistManager()
     }
@@ -25,143 +30,89 @@ class HybridPlayerQueue : HybridPlayerQueueSpec() {
     private val playlistsChangeListeners = java.util.concurrent.CopyOnWriteArrayList<() -> Unit>()
     private val playlistChangeListeners = java.util.concurrent.ConcurrentHashMap<String, () -> Unit>()
 
-    @DoNotStrip
-    @Keep
-    override fun createPlaylist(
-        name: String,
-        description: String?,
-        artwork: String?,
-    ): String = playlistManager.createPlaylist(name, description, artwork)
-
-    @DoNotStrip
-    @Keep
-    override fun deletePlaylist(playlistId: String) {
+    // ── Playlist CRUD ─────────────────────────────────────────────────────────
+
+    override fun createPlaylist(name: String, description: String?, artwork: String?): Promise<String> =
+        Promise.async { playlistManager.createPlaylist(name, description, artwork) }
+
+    override fun deletePlaylist(playlistId: String): Promise<Unit> = Promise.async {
         playlistManager.deletePlaylist(playlistId)
     }
 
-    @DoNotStrip
-    @Keep
-    override fun updatePlaylist(
-        playlistId: String,
-        name: String?,
-        description: String?,
-        artwork: String?,
-    ) {
+    override fun updatePlaylist(playlistId: String, name: String?, description: String?, artwork: String?): Promise<Unit> = Promise.async {
         playlistManager.updatePlaylist(playlistId, name, description, artwork)
+        core.updatePlaylist(playlistId)
     }
 
-    @DoNotStrip
-    @Keep
     override fun getPlaylist(playlistId: String): Variant_NullType_Playlist {
         val playlist = playlistManager.getPlaylist(playlistId)
-        return if (playlist != null) {
-            Variant_NullType_Playlist.create(playlist.toPlaylist())
-        } else {
-            Variant_NullType_Playlist.create(NullType.NULL)
-        }
+        return if (playlist != null) Variant_NullType_Playlist.create(playlist.toPlaylist())
+        else Variant_NullType_Playlist.create(NullType.NULL)
     }
 
-    @DoNotStrip
-    @Keep
     override fun getAllPlaylists(): Array<Playlist> =
-        playlistManager
-            .getAllPlaylists()
-            .map {
-                it.toPlaylist()
-            }.toTypedArray()
-
-    @DoNotStrip
-    @Keep
-    override fun addTrackToPlaylist(
-        playlistId: String,
-        track: TrackItem,
-        index: Double?,
-    ) {
-        val insertIndex = index?.toInt()
-        playlistManager.addTrackToPlaylist(playlistId, track, insertIndex)
+        playlistManager.getAllPlaylists().map { it.toPlaylist() }.toTypedArray()
+
+    // ── Track mutations ───────────────────────────────────────────────────────
+
+    override fun addTrackToPlaylist(playlistId: String, track: TrackItem, index: Double?): Promise<Unit> = Promise.async {
+        playlistManager.addTrackToPlaylist(playlistId, track, index?.toInt())
+        core.updatePlaylist(playlistId)
     }
 
-    @DoNotStrip
-    @Keep
-    override fun addTracksToPlaylist(
-        playlistId: String,
-        tracks: Array<TrackItem>,
-        index: Double?,
-    ) {
-        val insertIndex = index?.toInt()
-        playlistManager.addTracksToPlaylist(playlistId, tracks.toList(), insertIndex)
+    override fun addTracksToPlaylist(playlistId: String, tracks: Array<TrackItem>, index: Double?): Promise<Unit> = Promise.async {
+        playlistManager.addTracksToPlaylist(playlistId, tracks.toList(), index?.toInt())
+        core.updatePlaylist(playlistId)
     }
 
-    @DoNotStrip
-    @Keep
-    override fun removeTrackFromPlaylist(
-        playlistId: String,
-        trackId: String,
-    ) {
+    override fun removeTrackFromPlaylist(playlistId: String, trackId: String): Promise<Unit> = Promise.async {
         playlistManager.removeTrackFromPlaylist(playlistId, trackId)
+        core.updatePlaylist(playlistId)
     }
 
-    @DoNotStrip
-    @Keep
-    override fun reorderTrackInPlaylist(
-        playlistId: String,
-        trackId: String,
-        newIndex: Double,
-    ) {
+    override fun reorderTrackInPlaylist(playlistId: String, trackId: String, newIndex: Double): Promise<Unit> = Promise.async {
         playlistManager.reorderTrackInPlaylist(playlistId, trackId, newIndex.toInt())
+        core.updatePlaylist(playlistId)
     }
 
-    @DoNotStrip
-    @Keep
-    override fun loadPlaylist(playlistId: String) {
-        playlistManager.loadPlaylist(playlistId)
+    // ── Playback control ──────────────────────────────────────────────────────
+
+    override fun loadPlaylist(playlistId: String): Promise<Unit> = Promise.async {
+        core.loadPlaylist(playlistId)
     }
 
-    @DoNotStrip
-    @Keep
     override fun getCurrentPlaylistId(): Variant_NullType_String {
-        val playlistId = playlistManager.getCurrentPlaylistId()
-        return if (playlistId != null) {
-            Variant_NullType_String.create(playlistId)
-        } else {
-            Variant_NullType_String.create(NullType.NULL)
-        }
+        val id = core.getCurrentPlaylistId()
+        return if (id != null) Variant_NullType_String.create(id)
+        else Variant_NullType_String.create(NullType.NULL)
     }
 
-    @DoNotStrip
-    @Keep
+    // ── Events ────────────────────────────────────────────────────────────────
+
     override fun onPlaylistsChanged(callback: (playlists: Array<Playlist>, operation: QueueOperation?) -> Unit) {
-        // Add new listener and store the cleanup function
-        val removeListener =
-            playlistManager.addPlaylistsChangeListener { playlists, operation ->
-                callback(playlists.map { it.toPlaylist() }.toTypedArray(), operation)
-            }
+        val removeListener = playlistManager.addPlaylistsChangeListener { playlists, operation ->
+            callback(playlists.map { it.toPlaylist() }.toTypedArray(), operation)
+        }
         playlistsChangeListeners.add(removeListener)
     }
 
-    @DoNotStrip
-    @Keep
     override fun onPlaylistChanged(callback: (playlistId: String, playlist: Playlist, operation: QueueOperation?) -> Unit) {
-        // Listen to all playlists and filter by playlistId
         val listenerId = UUID.randomUUID().toString()
-
-        // For each playlist, add a listener
         playlistManager.getAllPlaylists().forEach { internalPlaylist ->
-            val removeListener =
-                playlistManager.addPlaylistChangeListener(internalPlaylist.id) { playlist, operation ->
-                    callback(playlist.id, playlist.toPlaylist(), operation)
-                }
+            val removeListener = playlistManager.addPlaylistChangeListener(internalPlaylist.id) { playlist, operation ->
+                callback(playlist.id, playlist.toPlaylist(), operation)
+            }
             playlistChangeListeners[listenerId] = removeListener
         }
     }
 
-    // Helper to convert internal Playlist to generated Playlist type
-    private fun InternalPlaylist.toPlaylist(): Playlist =
-        Playlist(
-            id = this.id,
-            name = this.name,
-            description = this.description?.let { Variant_NullType_String.create(it) },
-            artwork = this.artwork?.let { Variant_NullType_String.create(it) },
-            tracks = this.tracks.toTypedArray(),
-        )
+    // ── Helper ────────────────────────────────────────────────────────────────
+
+    private fun InternalPlaylist.toPlaylist(): Playlist = Playlist(
+        id = this.id,
+        name = this.name,
+        description = this.description?.let { Variant_NullType_String.create(it) },
+        artwork = this.artwork?.let { Variant_NullType_String.create(it) },
+        tracks = this.tracks.toTypedArray(),
+    )
 }

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

@@ -1,3 +1,5 @@
+@file:Suppress("ktlint:standard:max-line-length")
+
 package com.margelo.nitro.nitroplayer
 
 import androidx.annotation.Keep
@@ -5,169 +7,157 @@ import com.facebook.proguard.annotations.DoNotStrip
 import com.margelo.nitro.NitroModules
 import com.margelo.nitro.core.Promise
 import com.margelo.nitro.nitroplayer.core.TrackPlayerCore
+import com.margelo.nitro.nitroplayer.core.addToUpNext
+import com.margelo.nitro.nitroplayer.core.clearPlayNext
+import com.margelo.nitro.nitroplayer.core.clearUpNext
+import com.margelo.nitro.nitroplayer.core.configure
+import com.margelo.nitro.nitroplayer.core.getActualQueue
+import com.margelo.nitro.nitroplayer.core.getCurrentTrackIndex
+import com.margelo.nitro.nitroplayer.core.getNextTracks
+import com.margelo.nitro.nitroplayer.core.getPlayBackSpeed
+import com.margelo.nitro.nitroplayer.core.getPlayNextQueue
+import com.margelo.nitro.nitroplayer.core.getRepeatMode
+import com.margelo.nitro.nitroplayer.core.getState
+import com.margelo.nitro.nitroplayer.core.getTracksById
+import com.margelo.nitro.nitroplayer.core.getTracksNeedingUrls
+import com.margelo.nitro.nitroplayer.core.getUpNextQueue
+import com.margelo.nitro.nitroplayer.core.pause
+import com.margelo.nitro.nitroplayer.core.play
+import com.margelo.nitro.nitroplayer.core.playNext
+import com.margelo.nitro.nitroplayer.core.playSong
+import com.margelo.nitro.nitroplayer.core.removeFromPlayNext
+import com.margelo.nitro.nitroplayer.core.removeFromUpNext
+import com.margelo.nitro.nitroplayer.core.reorderTemporaryTrack
+import com.margelo.nitro.nitroplayer.core.seek
+import com.margelo.nitro.nitroplayer.core.setPlayBackSpeed
+import com.margelo.nitro.nitroplayer.core.setRepeatMode
+import com.margelo.nitro.nitroplayer.core.setVolume
+import com.margelo.nitro.nitroplayer.core.skipToIndex
+import com.margelo.nitro.nitroplayer.core.skipToNext
+import com.margelo.nitro.nitroplayer.core.skipToPrevious
+import com.margelo.nitro.nitroplayer.core.updateTracks
 
 @DoNotStrip
 @Keep
 class HybridTrackPlayer : HybridTrackPlayerSpec() {
     private val core: TrackPlayerCore
 
+    // Track listener IDs for cleanup in dispose()
+    private val listenerIds = mutableListOf<Pair<String, Long>>()
+
     init {
-        val context =
-            NitroModules.applicationContext ?: throw IllegalStateException("React Context is not initialized")
+        val context = NitroModules.applicationContext
+            ?: throw IllegalStateException("React Context is not initialized")
         core = TrackPlayerCore.getInstance(context)
     }
 
-    @DoNotStrip
-    @Keep
-    override fun play() {
-        core.play()
-    }
+    // ── Playback ─────────────────────────────────────────────────────────────
 
-    @DoNotStrip
-    @Keep
-    override fun pause() {
-        core.pause()
-    }
+    override fun play(): Promise<Unit> = Promise.async { core.play() }
+    override fun pause(): Promise<Unit> = Promise.async { core.pause() }
+    override fun seek(position: Double): Promise<Unit> = Promise.async { core.seek(position) }
+    override fun skipToNext(): Promise<Unit> = Promise.async { core.skipToNext() }
+    override fun skipToPrevious(): Promise<Unit> = Promise.async { core.skipToPrevious() }
+    override fun playSong(songId: String, fromPlaylist: String?): Promise<Unit> = Promise.async { core.playSong(songId, fromPlaylist) }
+    override fun skipToIndex(index: Double): Promise<Boolean> = Promise.async { core.skipToIndex(index.toInt()) }
 
-    override fun playSong(
-        songId: String,
-        fromPlaylist: String?,
-    ): Promise<Unit> =
-        Promise.async {
-            core.playSong(songId, fromPlaylist)
-        }
+    override fun setRepeatMode(mode: RepeatMode): Promise<Unit> = Promise.async { core.setRepeatMode(mode) }
+    override fun getRepeatMode(): RepeatMode = core.getRepeatMode()
 
-    @DoNotStrip
-    @Keep
-    override fun skipToNext() {
-        core.skipToNext()
-    }
+    override fun setVolume(volume: Double): Promise<Unit> = Promise.async { core.setVolume(volume) }
 
-    @DoNotStrip
-    @Keep
-    override fun skipToPrevious() {
-        core.skipToPrevious()
-    }
+    override fun configure(config: PlayerConfig): Promise<Unit> = Promise.async { core.configure(config) }
 
-    @DoNotStrip
-    @Keep
-    override fun seek(position: Double) {
-        core.seek(position)
-    }
+    // ── Queue / state reads ───────────────────────────────────────────────────
 
-    override fun addToUpNext(trackId: String): Promise<Unit> =
-        Promise.async {
-            core.addToUpNext(trackId)
-        }
+    override fun getActualQueue(): Promise<Array<TrackItem>> = Promise.async { core.getActualQueue().toTypedArray() }
+    override fun getState(): Promise<PlayerState> = Promise.async { core.getState() }
+    override fun getTracksById(trackIds: Array<String>): Promise<Array<TrackItem>> = Promise.async { core.getTracksById(trackIds.toList()).toTypedArray() }
+    override fun getTracksNeedingUrls(): Promise<Array<TrackItem>> = Promise.async { core.getTracksNeedingUrls().toTypedArray() }
+    override fun getNextTracks(count: Double): Promise<Array<TrackItem>> = Promise.async { core.getNextTracks(count.toInt()).toTypedArray() }
+    override fun getCurrentTrackIndex(): Promise<Double> = Promise.async { core.getCurrentTrackIndex().toDouble() }
 
-    override fun playNext(trackId: String): Promise<Unit> =
-        Promise.async {
-            core.playNext(trackId)
-        }
+    // ── URL updates ───────────────────────────────────────────────────────────
 
-    override fun getActualQueue(): Promise<Array<TrackItem>> =
-        Promise.async {
-            core.getActualQueue().toTypedArray()
-        }
+    override fun updateTracks(tracks: Array<TrackItem>): Promise<Unit> = Promise.async { core.updateTracks(tracks.toList()) }
 
-    override fun getState(): Promise<PlayerState> =
-        Promise.async {
-            core.getState()
-        }
+    // ── Temporary queue ───────────────────────────────────────────────────────
 
-    @DoNotStrip
-    @Keep
-    override fun setRepeatMode(mode: RepeatMode): Boolean = core.setRepeatMode(mode)
+    override fun addToUpNext(trackId: String): Promise<Unit> = Promise.async { core.addToUpNext(trackId) }
+    override fun playNext(trackId: String): Promise<Unit> = Promise.async { core.playNext(trackId) }
+    override fun removeFromPlayNext(trackId: String): Promise<Boolean> = Promise.async { core.removeFromPlayNext(trackId) }
+    override fun removeFromUpNext(trackId: String): Promise<Boolean> = Promise.async { core.removeFromUpNext(trackId) }
+    override fun clearPlayNext(): Promise<Unit> = Promise.async { core.clearPlayNext() }
+    override fun clearUpNext(): Promise<Unit> = Promise.async { core.clearUpNext() }
+    override fun reorderTemporaryTrack(trackId: String, newIndex: Double): Promise<Boolean> = Promise.async { core.reorderTemporaryTrack(trackId, newIndex.toInt()) }
+    override fun getPlayNextQueue(): Promise<Array<TrackItem>> = Promise.async { core.getPlayNextQueue().toTypedArray() }
+    override fun getUpNextQueue(): Promise<Array<TrackItem>> = Promise.async { core.getUpNextQueue().toTypedArray() }
 
-    @DoNotStrip
-    @Keep
-    override fun getRepeatMode(): RepeatMode = core.getRepeatMode()
+    // ── Playback speed ────────────────────────────────────────────────────────
+
+    override fun setPlaybackSpeed(speed: Double): Promise<Unit> = Promise.async { core.setPlayBackSpeed(speed) }
+    override fun getPlaybackSpeed(): Promise<Double> = Promise.async { core.getPlayBackSpeed() }
+
+    // ── Android Auto ──────────────────────────────────────────────────────────
+
+    override fun isAndroidAutoConnected(): Boolean = core.isAndroidAutoConnected()
+
+    // ── Event listeners ───────────────────────────────────────────────────────
 
     override fun onChangeTrack(callback: (track: TrackItem, reason: Reason?) -> Unit) {
-        core.addOnChangeTrackListener(callback)
+        val id = core.addOnChangeTrackListener(callback)
+        listenerIds += "onChangeTrack" to id
     }
 
     override fun onPlaybackStateChange(callback: (state: TrackPlayerState, reason: Reason?) -> Unit) {
-        core.addOnPlaybackStateChangeListener(callback)
+        val id = core.addOnPlaybackStateChangeListener(callback)
+        listenerIds += "onPlaybackStateChange" to id
     }
 
     override fun onSeek(callback: (position: Double, totalDuration: Double) -> Unit) {
-        core.addOnSeekListener(callback)
+        val id = core.addOnSeekListener(callback)
+        listenerIds += "onSeek" to id
     }
 
     override fun onPlaybackProgressChange(callback: (position: Double, totalDuration: Double, isManuallySeeked: Boolean?) -> Unit) {
-        core.addOnPlaybackProgressChangeListener(callback)
-    }
-
-    @DoNotStrip
-    @Keep
-    override fun configure(config: PlayerConfig) {
-        core.configure(
-            androidAutoEnabled = config.androidAutoEnabled,
-            carPlayEnabled = config.carPlayEnabled,
-            showInNotification = config.showInNotification,
-            lookaheadCount = config.lookaheadCount?.toInt(),
-        )
+        val id = core.addOnPlaybackProgressChangeListener(callback)
+        listenerIds += "onPlaybackProgressChange" to id
     }
 
-    @Keep
-    override fun onAndroidAutoConnectionChange(callback: (Boolean) -> Unit) {
-        core.onAndroidAutoConnectionChange = callback
+    override fun onAndroidAutoConnectionChange(callback: (connected: Boolean) -> Unit) {
+        val id = core.addOnAndroidAutoConnectionListener(callback)
+        listenerIds += "onAndroidAutoConnectionChange" to id
     }
 
-    @Keep
-    override fun isAndroidAutoConnected(): Boolean = core.isAndroidAutoConnected()
-
-    @DoNotStrip
-    @Keep
-    override fun setVolume(volume: Double): Boolean = core.setVolume(volume)
-
-    @DoNotStrip
-    @Keep
-    override fun skipToIndex(index: Double): Promise<Boolean> =
-        Promise.async {
-            core.skipToIndex(index.toInt())
-        }
-
-    override fun updateTracks(tracks: Array<TrackItem>): Promise<Unit> =
-        Promise.async {
-            core.updateTracks(tracks.toList())
-        }
-
-    override fun getTracksById(trackIds: Array<String>): Promise<Array<TrackItem>> =
-        Promise.async {
-            core.getTracksById(trackIds.toList()).toTypedArray()
-        }
-
-    override fun getTracksNeedingUrls(): Promise<Array<TrackItem>> =
-        Promise.async {
-            core.getTracksNeedingUrls().toTypedArray()
-        }
-
-    override fun getNextTracks(count: Double): Promise<Array<TrackItem>> =
-        Promise.async {
-            core.getNextTracks(count.toInt()).toTypedArray()
-        }
-
-    override fun getCurrentTrackIndex(): Promise<Double> =
-        Promise.async {
-            core.getCurrentTrackIndex().toDouble()
-        }
-
-    override fun setPlaybackSpeed(speed: Double): Promise<Unit> =
-        Promise.async {
-            core.setPlayBackSpeed(speed)
-            Unit
+    override fun onTracksNeedUpdate(callback: (tracks: Array<TrackItem>, lookahead: Double) -> Unit) {
+        val id = core.addOnTracksNeedUpdateListener { tracks, lookahead ->
+            callback(tracks.toTypedArray(), lookahead.toDouble())
         }
+        listenerIds += "onTracksNeedUpdate" to id
+    }
 
-    override fun getPlaybackSpeed(): Promise<Double> =
-        Promise.async {
-            core.getPlayBackSpeed()
+    override fun onTemporaryQueueChange(callback: (playNextQueue: Array<TrackItem>, upNextQueue: Array<TrackItem>) -> Unit) {
+        val id = core.addOnTemporaryQueueChangeListener { pn, un ->
+            callback(pn.toTypedArray(), un.toTypedArray())
         }
+        listenerIds += "onTemporaryQueueChange" to id
+    }
 
-    override fun onTracksNeedUpdate(callback: (tracks: Array<TrackItem>, lookahead: Double) -> Unit) {
-        core.addOnTracksNeedUpdateListener { tracks, lookahead ->
-            callback(tracks.toTypedArray(), lookahead.toDouble())
+    // ── Cleanup ───────────────────────────────────────────────────────────────
+
+    override fun dispose() {
+        super.dispose()
+        listenerIds.forEach { (type, id) ->
+            when (type) {
+                "onChangeTrack" -> core.removeOnChangeTrackListener(id)
+                "onPlaybackStateChange" -> core.removeOnPlaybackStateChangeListener(id)
+                "onSeek" -> core.removeOnSeekListener(id)
+                "onPlaybackProgressChange" -> core.removeOnPlaybackProgressChangeListener(id)
+                "onAndroidAutoConnectionChange" -> core.removeOnAndroidAutoConnectionListener(id)
+                "onTracksNeedUpdate" -> core.removeOnTracksNeedUpdateListener(id)
+                "onTemporaryQueueChange" -> core.removeOnTemporaryQueueChangeListener(id)
+            }
         }
+        listenerIds.clear()
     }
 }

package/android/src/main/java/com/margelo/nitro/nitroplayer/core/ExoPlayerCore.kt

@@ -0,0 +1,82 @@
+package com.margelo.nitro.nitroplayer.core
+
+import android.os.HandlerThread
+import android.content.Context
+import androidx.media3.common.AudioAttributes
+import androidx.media3.common.C
+import androidx.media3.common.MediaItem
+import androidx.media3.common.Player
+import androidx.media3.exoplayer.DefaultLoadControl
+import androidx.media3.exoplayer.ExoPlayer
+
+
+class ExoPlayerCore(context: Context, playerThread: HandlerThread) {
+
+    /** The underlying ExoPlayer instance — accessible for MediaSessionManager wiring. */
+    internal val player: ExoPlayer = build(context, playerThread)
+
+    private fun build(context: Context, playerThread: HandlerThread): ExoPlayer {
+        val loadControl = DefaultLoadControl.Builder()
+            .setBufferDurationsMs(
+                /* minBufferMs        */ 30_000,
+                /* maxBufferMs        */ 120_000,
+                /* bufferForPlayback  */ 2_500,
+                /* bufferForRebuffer  */ 5_000,
+            )
+            .setBackBuffer(30_000, /* retainBackBufferFromKeyframe */ true)
+            .setTargetBufferBytes(C.LENGTH_UNSET)
+            .setPrioritizeTimeOverSizeThresholds(true)
+            .build()
+
+        val audioAttrs = AudioAttributes.Builder()
+            .setUsage(C.USAGE_MEDIA)
+            .setContentType(C.AUDIO_CONTENT_TYPE_MUSIC)
+            .build()
+
+        return ExoPlayer.Builder(context)
+            .setLooper(playerThread.looper)
+            .setLoadControl(loadControl)
+            .setAudioAttributes(audioAttrs, /* handleAudioFocus */ true)
+            .setHandleAudioBecomingNoisy(true)
+            .setPauseAtEndOfMediaItems(false)
+            .build()
+    }
+
+    // ── Playback ───────────────────────────────────────────────────────────
+    fun play() = player.play()
+    fun pause() = player.pause()
+    fun seekTo(positionMs: Long) = player.seekTo(positionMs)
+    fun seekToNext() = player.seekToNextMediaItem()
+    fun hasNextMediaItem(): Boolean = player.hasNextMediaItem()
+    fun setRepeatMode(mode: Int) { player.repeatMode = mode }
+    fun setVolume(volume: Float) { player.volume = volume }
+    fun setPlaybackSpeed(speed: Float) = player.setPlaybackSpeed(speed)
+    fun getPlaybackSpeed(): Float = player.playbackParameters.speed
+
+    // ── Queue mutations ────────────────────────────────────────────────────
+    fun prepare() = player.prepare()
+    fun seekToDefaultPosition(windowIndex: Int) = player.seekToDefaultPosition(windowIndex)
+    fun clearMediaItems() = player.clearMediaItems()
+    fun setMediaItems(items: List<MediaItem>, resetPosition: Boolean = false) =
+        player.setMediaItems(items, resetPosition)
+    fun addMediaItems(items: List<MediaItem>) = player.addMediaItems(items)
+    fun removeMediaItems(fromIndex: Int, toIndex: Int) =
+        player.removeMediaItems(fromIndex, toIndex)
+    fun replaceMediaItem(index: Int, item: MediaItem) = player.replaceMediaItem(index, item)
+
+    // ── Listener wiring ────────────────────────────────────────────────────
+    fun addListener(listener: Player.Listener) = player.addListener(listener)
+    fun removeListener(listener: Player.Listener) = player.removeListener(listener)
+
+    // ── State reads ────────────────────────────────────────────────────────
+    val playbackState: Int get() = player.playbackState
+    val isPlaying: Boolean get() = player.isPlaying
+    var playWhenReady: Boolean
+        get() = player.playWhenReady
+        set(value) { player.playWhenReady = value }
+    val currentMediaItem: MediaItem? get() = player.currentMediaItem
+    val currentMediaItemIndex: Int get() = player.currentMediaItemIndex
+    val currentPosition: Long get() = player.currentPosition
+    val duration: Long get() = player.duration
+    val mediaItemCount: Int get() = player.mediaItemCount
+}

package/android/src/main/java/com/margelo/nitro/nitroplayer/core/ListenerRegistry.kt

@@ -0,0 +1,48 @@
+package com.margelo.nitro.nitroplayer.core
+
+import java.util.concurrent.CopyOnWriteArrayList
+import java.util.concurrent.atomic.AtomicLong
+
+/**
+ * Thread-safe listener registry with stable numeric IDs for add/remove.
+ * Uses CopyOnWriteArrayList for lock-free iteration and AtomicLong for ID generation.
+ */
+class ListenerRegistry<T> {
+    private data class Entry<T>(val id: Long, val callback: T)
+
+    private val entries = CopyOnWriteArrayList<Entry<T>>()
+    private val nextId = AtomicLong(0)
+
+    /** Register a callback and return its stable ID for later removal. */
+    fun add(callback: T): Long {
+        val id = nextId.incrementAndGet()
+        entries.add(Entry(id, callback))
+        return id
+    }
+
+    /** Remove the callback with the given ID. Returns true if found. */
+    fun remove(id: Long): Boolean {
+        val iterator = entries.iterator()
+        while (iterator.hasNext()) {
+            val entry = iterator.next()
+            if (entry.id == id) {
+                entries.remove(entry)
+                return true
+            }
+        }
+        return false
+    }
+
+    /** Remove all registered callbacks. */
+    fun clear() = entries.clear()
+
+    /** Invoke action for every registered callback (snapshot iteration — safe under mutation). */
+    fun forEach(action: (T) -> Unit) {
+        for (entry in entries) {
+            action(entry.callback)
+        }
+    }
+
+    /** True when no callbacks are registered. */
+    val isEmpty: Boolean get() = entries.isEmpty()
+}