react-native-nitro-player 1.7.0-alpha.4 → 1.7.0-alpha.6

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

@@ -3,18 +3,22 @@
 package com.margelo.nitro.nitroplayer.media
 
 import android.net.Uri
+import android.os.Handler
+import android.os.Looper
 import android.provider.MediaStore
 import androidx.media3.common.MediaItem
 import androidx.media3.common.MediaMetadata
+import androidx.media3.common.Player
+import androidx.media3.common.Timeline
 import androidx.media3.exoplayer.ExoPlayer
 import androidx.media3.session.MediaSession
 import androidx.media3.session.SessionCommand
 import androidx.media3.session.SessionResult
 import com.google.common.util.concurrent.Futures
 import com.google.common.util.concurrent.ListenableFuture
+import com.google.common.util.concurrent.SettableFuture
 import com.margelo.nitro.nitroplayer.TrackItem
 import com.margelo.nitro.nitroplayer.core.NitroPlayerLogger
-import com.margelo.nitro.nitroplayer.core.loadPlaylist
 import com.margelo.nitro.nitroplayer.playlist.Playlist
 import com.margelo.nitro.nitroplayer.playlist.PlaylistManager
 import kotlinx.coroutines.CoroutineScope
@@ -43,7 +47,8 @@ object MediaSessionCallbackFactory {
                 MediaSession.ConnectionResult
                     .AcceptedResultBuilder(session)
                     .setAvailableSessionCommands(
-                        MediaSession.ConnectionResult.DEFAULT_SESSION_COMMANDS,
+                        service.trackPlayerCore?.mediaSessionManager?.sessionCommands()
+                            ?: MediaSession.ConnectionResult.DEFAULT_SESSION_COMMANDS,
                     ).setAvailablePlayerCommands(
                         MediaSession.ConnectionResult.DEFAULT_PLAYER_COMMANDS,
                     ).build()
@@ -74,7 +79,7 @@ object MediaSessionCallbackFactory {
                             val playlistId = mediaId.substring(0, colonIdx)
                             val trackId = mediaId.substring(colonIdx + 1)
                             val playlist = playlistManager.getPlaylist(playlistId)
-                            val track = playlist?.tracks?.find { it.id == trackId }
+                            val track = playlist?.tracks?.getOrNull(playlistManager.indexOfTrackRef(playlistId, trackId))
                             if (track != null) {
                                 updated.add(createMediaItem(track, mediaId))
                             } else {
@@ -105,10 +110,7 @@ object MediaSessionCallbackFactory {
                 // it against loaded playlists before falling through.
                 val voiceMatch = resolveVoiceSearch(mediaItems, playlistManager)
                 if (voiceMatch != null) {
-                    val (playlistId, items, trackIndex) = voiceMatch
-                    service.trackPlayerCore?.let { core ->
-                        scope.launch { core.loadPlaylist(playlistId, trackIndex) }
-                    }
+                    val (_, items, trackIndex) = voiceMatch
                     return Futures.immediateFuture(
                         MediaSession.MediaItemsWithStartPosition(items, trackIndex, startPositionMs),
                     )
@@ -127,15 +129,15 @@ object MediaSessionCallbackFactory {
                         val trackId = firstMediaId.substring(colonIdx + 1)
                         val playlist = playlistManager.getPlaylist(playlistId)
                         if (playlist != null) {
-                            val trackIndex = playlist.tracks.indexOfFirst { it.id == trackId }
+                            val trackIndex = playlistManager.indexOfTrackRef(playlistId, trackId)
                             if (trackIndex >= 0) {
-                                service.trackPlayerCore?.let { core ->
-                                    scope.launch { core.loadPlaylist(playlistId, trackIndex) }
-                                }
+                                val seen = mutableSetOf<String>()
                                 val playlistMediaItems =
                                     playlist.tracks
-                                        .map { track -> createMediaItem(track, "$playlistId:${track.id}") }
-                                        .toMutableList()
+                                        .mapIndexed { i, track ->
+                                            val ref = if (seen.add(track.id)) track.id else "${track.id}#$i"
+                                            createMediaItem(track, "$playlistId:$ref")
+                                        }.toMutableList()
                                 return Futures.immediateFuture(
                                     MediaSession.MediaItemsWithStartPosition(
                                         playlistMediaItems,
@@ -150,31 +152,107 @@ object MediaSessionCallbackFactory {
                     NitroPlayerLogger.log("MediaSessionCallback") { "Error in onSetMediaItems: ${e.message}" }
                 }
 
-                // If a voice query was issued but found nothing, return an
-                // explicit failure so the controller (Assistant) surfaces a
-                // spoken error instead of silently no-oping. Without this the
-                // Auto QA bot reports "no music played or error message shown".
-                if (mediaItems.isNotEmpty() && mediaItems[0].requestMetadata.searchQuery != null) {
-                    return Futures.immediateFailedFuture(
-                        UnsupportedOperationException("No matching tracks for voice search"),
-                    )
-                }
+                // No match in loaded playlists: try the app's search, else fail so Assistant speaks an error
+                val voiceQuery = mediaItems.firstOrNull()?.requestMetadata?.searchQuery
+                if (voiceQuery != null) return searchAndPlay(service, playlistManager, scope, voiceQuery, startPositionMs)
 
                 return Futures.immediateFuture(
                     MediaSession.MediaItemsWithStartPosition(mediaItems, startIndex, startPositionMs),
                 )
             }
 
+            // Car "start music automatically" on a cold start: play what the app restores once its JS is up
+            override fun onPlaybackResumption(
+                mediaSession: MediaSession,
+                controller: MediaSession.ControllerInfo,
+                isForPlayback: Boolean,
+            ): ListenableFuture<MediaSession.MediaItemsWithStartPosition> {
+                service.trackPlayerCore?.startJsRuntimeIfNeeded()
+                MediaLibraryManager.getInstance(service).requestResumption()
+                val future = SettableFuture.create<MediaSession.MediaItemsWithStartPosition>()
+                val player = mediaSession.player
+                val handler = Handler(Looper.getMainLooper())
+                lateinit var listener: Player.Listener
+                lateinit var timeout: Runnable
+                val finish = {
+                    player.removeListener(listener)
+                    handler.removeCallbacks(timeout)
+                    val item = player.currentMediaItem
+                    if (item != null) {
+                        future.set(MediaSession.MediaItemsWithStartPosition(listOf(item), 0, player.currentPosition))
+                    } else {
+                        future.setException(UnsupportedOperationException("Nothing to resume"))
+                    }
+                }
+                listener =
+                    object : Player.Listener {
+                        override fun onTimelineChanged(
+                            timeline: Timeline,
+                            reason: Int,
+                        ) {
+                            if (player.currentMediaItem != null) finish()
+                        }
+                    }
+                timeout = Runnable { finish() }
+                player.addListener(listener)
+                handler.postDelayed(timeout, RESUMPTION_TIMEOUT_MS)
+                return future
+            }
+
             override fun onCustomCommand(
                 session: MediaSession,
                 controller: MediaSession.ControllerInfo,
                 customCommand: SessionCommand,
                 args: android.os.Bundle,
-            ): ListenableFuture<SessionResult> =
-                Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
+            ): ListenableFuture<SessionResult> {
+                val manager = service.trackPlayerCore?.mediaSessionManager
+                if (manager?.handlesSessionButton(customCommand.customAction) == true) {
+                    manager.onSessionButtonPress?.invoke(customCommand.customAction)
+                }
+                return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
+            }
         }
     }
 
+    // Asks the app's search, which can look past the loaded playlists; plays the first result naming a playlist track
+    private fun searchAndPlay(
+        service: NitroPlayerPlaybackService,
+        playlistManager: PlaylistManager,
+        scope: CoroutineScope,
+        query: String,
+        startPositionMs: Long,
+    ): ListenableFuture<MediaSession.MediaItemsWithStartPosition> {
+        val future = SettableFuture.create<MediaSession.MediaItemsWithStartPosition>()
+        scope.launch {
+            val match =
+                MediaLibraryManager
+                    .getInstance(service)
+                    .search(query)
+                    ?.firstNotNullOfOrNull { resolveTrack(it.id, playlistManager) }
+            if (match == null) {
+                future.setException(UnsupportedOperationException("No matching tracks for voice search"))
+                return@launch
+            }
+            val (playlist, index) = match
+            val items = playlist.tracks.map { createMediaItem(it, "${playlist.id}:${it.id}") }
+            future.set(MediaSession.MediaItemsWithStartPosition(items, index, startPositionMs))
+        }
+        return future
+    }
+
+    private fun resolveTrack(
+        mediaId: String,
+        playlistManager: PlaylistManager,
+    ): Pair<Playlist, Int>? {
+        val colonIndex = mediaId.indexOf(':')
+        if (colonIndex <= 0) return null
+        val playlist = playlistManager.getPlaylist(mediaId.substring(0, colonIndex)) ?: return null
+        val index = playlistManager.indexOfTrackRef(playlist.id, mediaId.substring(colonIndex + 1))
+        return if (index >= 0) playlist to index else null
+    }
+
+    private const val RESUMPTION_TIMEOUT_MS = 10_000L
+
     private data class VoiceMatch(
         val playlistId: String,
         val items: List<MediaItem>,

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

@@ -1,10 +1,13 @@
 package com.margelo.nitro.nitroplayer.media
 
 import android.content.Context
+import android.os.Bundle
 import androidx.media3.common.Player
 import androidx.media3.common.util.UnstableApi
 import androidx.media3.session.CommandButton
 import androidx.media3.session.MediaSession
+import androidx.media3.session.SessionCommand
+import androidx.media3.session.SessionCommands
 import com.margelo.nitro.nitroplayer.R
 import com.margelo.nitro.nitroplayer.TrackItem
 import com.margelo.nitro.nitroplayer.core.TrackPlayerCore
@@ -45,6 +48,36 @@ class MediaSessionManager(
     private var remoteSkipForwardIntervalMs: Long = DEFAULT_REMOTE_SKIP_INTERVAL_MS
     private var remoteSkipBackwardIntervalMs: Long = DEFAULT_REMOTE_SKIP_INTERVAL_MS
 
+    /** App-defined button; [icon] is a CommandButton.ICON_* constant. */
+    data class SessionButton(
+        val action: String,
+        val title: String,
+        val icon: Int,
+    )
+
+    private var sessionButtons: List<SessionButton> = emptyList()
+
+    @Volatile var onSessionButtonPress: ((action: String) -> Unit)? = null
+
+    fun sessionCommands(): SessionCommands =
+        MediaSession.ConnectionResult.DEFAULT_SESSION_COMMANDS
+            .buildUpon()
+            .apply { sessionButtons.forEach { add(SessionCommand(it.action, Bundle.EMPTY)) } }
+            .build()
+
+    fun handlesSessionButton(action: String): Boolean = sessionButtons.any { it.action == action }
+
+    fun setSessionButtons(buttons: List<SessionButton>) {
+        sessionButtons = buttons
+        val session = mediaSession ?: return
+        // A controller only shows or presses a button whose command it was granted; the notification one feeds Android Auto
+        val commands = sessionCommands()
+        (session.connectedControllers + listOfNotNull(session.mediaNotificationControllerInfo)).distinct().forEach {
+            session.setAvailableCommands(it, commands, MediaSession.ConnectionResult.DEFAULT_PLAYER_COMMANDS)
+        }
+        updateMediaButtonPreferences()
+    }
+
     init {
         updateMediaButtonPreferences()
     }
@@ -82,9 +115,18 @@ class MediaSessionManager(
         // Preferences replace Media3's default layout — prev/next must be declared or they vanish.
         // Compact only shows BACK / play-pause / FORWARD, so the ±N skips go to OVERFLOW; left in
         // the forward slot they push Next out of the compact notification entirely.
-        val preserved = session.mediaButtonPreferences.filterNot { it.isManagedButton() }
+        val preserved = session.mediaButtonPreferences.filterNot { it.isManagedButton() || it.sessionCommand != null }
+        val custom =
+            sessionButtons.map {
+                CommandButton
+                    .Builder(it.icon)
+                    .setDisplayName(it.title)
+                    .setSessionCommand(SessionCommand(it.action, Bundle.EMPTY))
+                    .setSlots(CommandButton.SLOT_OVERFLOW)
+                    .build()
+            }
         session.setMediaButtonPreferences(
-            listOf(previousTrackButton(), nextTrackButton(), skipBackButton(), skipForwardButton()) + preserved,
+            listOf(previousTrackButton(), nextTrackButton()) + custom + listOf(skipBackButton(), skipForwardButton()) + preserved,
         )
     }
 

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

@@ -2,12 +2,16 @@ package com.margelo.nitro.nitroplayer.media
 
 import android.app.PendingIntent
 import android.content.Intent
+import android.net.Uri
 import android.os.Binder
 import android.os.Handler
 import android.os.IBinder
 import android.os.Looper
 import androidx.media3.cast.CastPlayer
+import androidx.media3.common.C
 import androidx.media3.common.ForwardingPlayer
+import androidx.media3.common.MediaItem
+import androidx.media3.common.Player
 import androidx.media3.common.util.UnstableApi
 import androidx.media3.exoplayer.ExoPlayer
 import androidx.media3.session.DefaultMediaNotificationProvider
@@ -15,7 +19,10 @@ import androidx.media3.session.MediaSession
 import androidx.media3.session.MediaSessionService
 import com.google.android.gms.cast.framework.CastContext
 import com.margelo.nitro.nitroplayer.core.NitroPlayerLogger
+import com.margelo.nitro.nitroplayer.core.checkUpcomingTracksForUrls
 import com.margelo.nitro.nitroplayer.core.TrackPlayerCore
+import com.margelo.nitro.nitroplayer.core.playFromMediaId
+import com.margelo.nitro.nitroplayer.core.playOnQueue
 import com.margelo.nitro.nitroplayer.core.skipToNextOnQueue
 import com.margelo.nitro.nitroplayer.core.skipToPreviousOnQueue
 import com.margelo.nitro.nitroplayer.playlist.PlaylistManager
@@ -54,6 +61,7 @@ class NitroPlayerPlaybackService : MediaSessionService() {
     // ── Created in onCreate ────────────────────────────────────────────────
     private lateinit var player: ExoPlayer
     private var mediaSession: MediaSession? = null
+    private lateinit var sessionPlayer: Player
     private var notificationProvider: DefaultMediaNotificationProvider? = null
     private val mainHandler = Handler(Looper.getMainLooper())
 
@@ -87,7 +95,7 @@ class NitroPlayerPlaybackService : MediaSessionService() {
         // The timeline is a window over the logical queue, so ExoPlayer's own prev/next would
         // only ever move inside it — remote Previous seeks to 0 instead of the previous track.
         // Route the remote controls through the same logical skips JS uses.
-        val sessionPlayer =
+        sessionPlayer =
             object : ForwardingPlayer(player) {
                 override fun seekToPrevious() {
                     trackPlayerCore?.skipToPreviousOnQueue() ?: super.seekToPrevious()
@@ -104,6 +112,53 @@ class NitroPlayerPlaybackService : MediaSessionService() {
                 override fun seekToNextMediaItem() {
                     trackPlayerCore?.skipToNextOnQueue() ?: super.seekToNextMediaItem()
                 }
+
+                // A controller's pick would otherwise load every track at once, bypassing the window and lazy URLs
+                override fun setMediaItems(
+                    mediaItems: MutableList<MediaItem>,
+                    resetPosition: Boolean,
+                ) {
+                    if (!playFromController(mediaItems, 0)) super.setMediaItems(mediaItems, resetPosition)
+                }
+
+                override fun setMediaItems(
+                    mediaItems: MutableList<MediaItem>,
+                    startIndex: Int,
+                    startPositionMs: Long,
+                ) {
+                    if (!playFromController(mediaItems, startIndex)) super.setMediaItems(mediaItems, startIndex, startPositionMs)
+                }
+
+                // Queued behind the load above, in the order the controller sent them
+                override fun prepare() {
+                    trackPlayerCore?.let { core -> core.enqueue { core.exo.prepare() } } ?: super.prepare()
+                }
+
+                override fun play() {
+                    trackPlayerCore?.let { core -> core.enqueue { core.playOnQueue() } } ?: super.play()
+                }
+
+                // Transcoded streams lack a length header, so ExoPlayer reads them as live: no bar or position in the car
+                override fun isCurrentMediaItemLive(): Boolean = super.isCurrentMediaItemLive() && knownDurationMs() == null
+
+                override fun getDuration(): Long = super.getDuration().takeIf { it != C.TIME_UNSET } ?: knownDurationMs() ?: C.TIME_UNSET
+
+                private fun knownDurationMs(): Long? = currentMediaItem?.mediaMetadata?.durationMs?.takeIf { it > 0 }
+
+                private fun playFromController(
+                    mediaItems: List<MediaItem>,
+                    startIndex: Int,
+                ): Boolean {
+                    val mediaId = mediaItems.getOrNull(maxOf(startIndex, 0))?.mediaId ?: return false
+                    if (mediaId == currentMediaItem?.mediaId && playerError == null) {
+                        // Re-picking a song still waiting for its URL asks the app for it again
+                        if (currentMediaItem?.localConfiguration?.uri == Uri.EMPTY) {
+                            trackPlayerCore?.let { core -> core.enqueue { core.checkUpcomingTracksForUrls(core.lookaheadCount, force = true) } }
+                        }
+                        return true
+                    }
+                    return trackPlayerCore?.playFromMediaId(mediaId) == true
+                }
             }
 
         // Build MediaSession
@@ -144,6 +199,7 @@ class NitroPlayerPlaybackService : MediaSessionService() {
                     castContext = castContext,
                     castPlayer = castPlayer,
                     localPlayer = player,
+                    localSessionPlayer = sessionPlayer,
                     mediaSession = mediaSession!!,
                     mainHandler = mainHandler,
                 )

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

@@ -1,6 +1,7 @@
 package com.margelo.nitro.nitroplayer.playlist
 
 import android.content.Context
+import com.margelo.nitro.JNIOnLoad
 import com.margelo.nitro.core.AnyMap
 import com.margelo.nitro.nitroplayer.QueueOperation
 import com.margelo.nitro.nitroplayer.TrackItem
@@ -59,6 +60,8 @@ class PlaylistManager private constructor(
     }
 
     init {
+        // Persisted extraPayloads are AnyMaps; a process started without JS has not loaded Nitro's JNI yet
+        JNIOnLoad.initializeNativeNitro()
         // Synchronous so no mutation can race a late async load and be clobbered
         loadPlaylistsFromFile()
     }
@@ -136,6 +139,18 @@ class PlaylistManager private constructor(
      */
     fun getPlaylist(playlistId: String): Playlist? = playlists[playlistId]
 
+    /** "trackId" or, for a repeated track, "trackId#index" as the car browser lists it; -1 when it is not in the playlist. */
+    fun indexOfTrackRef(
+        playlistId: String,
+        trackRef: String,
+    ): Int {
+        val tracks = playlists[playlistId]?.tracks ?: return -1
+        val exact = tracks.indexOfFirst { it.id == trackRef }
+        if (exact >= 0) return exact
+        val index = trackRef.substringAfterLast('#', "").toIntOrNull() ?: return -1
+        return index.takeIf { tracks.getOrNull(it)?.id == trackRef.substringBeforeLast('#') } ?: -1
+    }
+
     /**
      * Get all playlists
      */

package/ios/HybridTrackPlayer.swift

@@ -100,7 +100,8 @@ final class HybridTrackPlayer: HybridTrackPlayerSpec {
         showInNotification: config.showInNotification,
         lookaheadCount: config.lookaheadCount.map { Int($0) },
         remoteSkipForwardInterval: config.remoteSkipForwardInterval,
-        remoteSkipBackwardInterval: config.remoteSkipBackwardInterval
+        remoteSkipBackwardInterval: config.remoteSkipBackwardInterval,
+        preferRemoteSkipIntervals: config.preferRemoteSkipIntervals
       )
     }
   }

package/ios/core/TrackPlayerPlayback.swift

@@ -104,7 +104,8 @@ extension TrackPlayerCore {
   func configureOnQueue(
     androidAutoEnabled: Bool?, carPlayEnabled: Bool?,
     showInNotification: Bool?, lookaheadCount: Int?,
-    remoteSkipForwardInterval: Double?, remoteSkipBackwardInterval: Double?
+    remoteSkipForwardInterval: Double?, remoteSkipBackwardInterval: Double?,
+    preferRemoteSkipIntervals: Bool?
   ) {
     if let la = lookaheadCount {
       self.lookaheadCount = la
@@ -118,6 +119,7 @@ extension TrackPlayerCore {
         showInNotification: showInNotification,
         remoteSkipForwardInterval: remoteSkipForwardInterval,
         remoteSkipBackwardInterval: remoteSkipBackwardInterval,
+        preferRemoteSkipIntervals: preferRemoteSkipIntervals,
         playbackSpeed: playbackSpeed
       )
     }
@@ -125,14 +127,16 @@ extension TrackPlayerCore {
   func configure(
     androidAutoEnabled: Bool?, carPlayEnabled: Bool?,
     showInNotification: Bool?, lookaheadCount: Int?,
-    remoteSkipForwardInterval: Double?, remoteSkipBackwardInterval: Double?
+    remoteSkipForwardInterval: Double?, remoteSkipBackwardInterval: Double?,
+    preferRemoteSkipIntervals: Bool?
   ) async {
     await withPlayerQueueNoThrow {
       self.configureOnQueue(
         androidAutoEnabled: androidAutoEnabled, carPlayEnabled: carPlayEnabled,
         showInNotification: showInNotification, lookaheadCount: lookaheadCount,
         remoteSkipForwardInterval: remoteSkipForwardInterval,
-        remoteSkipBackwardInterval: remoteSkipBackwardInterval)
+        remoteSkipBackwardInterval: remoteSkipBackwardInterval,
+        preferRemoteSkipIntervals: preferRemoteSkipIntervals)
     }
   }
 

package/ios/media/MediaSessionManager.swift

@@ -28,6 +28,7 @@ class MediaSessionManager {
   private var showInNotification: Bool = true
   private var remoteSkipForwardInterval: Double = Constants.defaultRemoteSkipInterval
   private var remoteSkipBackwardInterval: Double = Constants.defaultRemoteSkipInterval
+  private var preferRemoteSkipIntervals = false
 
   // Tracks the artwork URL currently shown so we can discard stale async loads
   private var lastArtworkUrl: String?
@@ -56,11 +57,15 @@ class MediaSessionManager {
     showInNotification: Bool?,
     remoteSkipForwardInterval: Double?,
     remoteSkipBackwardInterval: Double?,
+    preferRemoteSkipIntervals: Bool?,
     playbackSpeed: Double?
   ) {
     if let showInNotification = showInNotification {
       self.showInNotification = showInNotification
     }
+    if let preferRemoteSkipIntervals = preferRemoteSkipIntervals {
+      self.preferRemoteSkipIntervals = preferRemoteSkipIntervals
+    }
     if let playbackSpeed = sanitizedPositive(playbackSpeed) {
       cachedPlaybackSpeed = playbackSpeed
     }
@@ -321,8 +326,9 @@ class MediaSessionManager {
 
     commandCenter.nextTrackCommand.isEnabled = hasCurrentTrack && isNotLast
     commandCenter.previousTrackCommand.isEnabled = hasCurrentTrack
-    commandCenter.skipForwardCommand.isEnabled = hasCurrentTrack
-    commandCenter.skipBackwardCommand.isEnabled = hasCurrentTrack
+    // iOS shows enabled skip-interval commands in place of next/previous, so they stay off unless the app prefers them
+    commandCenter.skipForwardCommand.isEnabled = hasCurrentTrack && preferRemoteSkipIntervals
+    commandCenter.skipBackwardCommand.isEnabled = hasCurrentTrack && preferRemoteSkipIntervals
     commandCenter.changePlaybackRateCommand.isEnabled = hasCurrentTrack
     commandCenter.changePlaybackPositionCommand.isEnabled = hasCurrentTrack && hasDuration
   }

package/lib/index.js

@@ -1,6 +1,10 @@
 // TODO: Export all HybridObjects here for the user
 import { NitroModules } from 'react-native-nitro-modules';
-import { Platform } from 'react-native';
+import { AppRegistry, Platform } from 'react-native';
+// Native runs this while it needs JS without a resumed activity (car, screen off): it keeps JS timers ticking
+if (Platform.OS === 'android') {
+    AppRegistry.registerHeadlessTask('NitroPlayerKeepAlive', () => () => new Promise(() => { }));
+}
 export const PlayerQueue = NitroModules.createHybridObject('PlayerQueue');
 export const TrackPlayer = NitroModules.createHybridObject('TrackPlayer');
 // Android-only: Android Auto Media Library

package/lib/specs/AndroidAutoMediaLibrary.nitro.d.ts

@@ -18,4 +18,16 @@ export interface AndroidAutoMediaLibrary extends HybridObject<{
      * Falls back to showing all playlists
      */
     clearMediaLibrary(): Promise<void>;
+    /** Android Auto opened a folder published with `children: []`; answer with {@link resolveRequest}. */
+    onLoadChildren(callback: (requestId: string, parentId: string) => void): void;
+    /** A car search, or a voice request the loaded playlists cannot match; answer with {@link resolveRequest}. */
+    onSearch(callback: (requestId: string, query: string) => void): void;
+    /** Answers {@link onLoadChildren} / {@link onSearch} with a JSON array of MediaItem. */
+    resolveRequest(requestId: string, itemsJson: string): void;
+    /** Replaces the session buttons with a JSON array of SessionButton. */
+    setSessionButtons(buttonsJson: string): void;
+    /** Called with the button's `action` when a session button is pressed. */
+    onSessionButtonPress(callback: (action: string) => void): void;
+    /** A controller asked to play with nothing loaded (car auto-play, play on connect); load the last queue now. */
+    onPlaybackResumption(callback: () => void): void;
 }

package/lib/types/AndroidAutoMediaLibrary.d.ts

@@ -28,6 +28,8 @@ export interface MediaItem {
     children?: MediaItem[];
     /** Layout type for folder items (overrides library default) */
     layoutType?: LayoutType;
+    /** Group header; contiguous items sharing one are listed under it */
+    groupTitle?: string;
 }
 /**
  * Media library structure for Android Auto
@@ -42,3 +44,12 @@ export interface MediaLibrary {
     /** Optional app icon URL */
     appIconUrl?: string;
 }
+export type SessionButtonIcon = 'heart' | 'heart_filled' | 'star' | 'star_filled' | 'thumb_up' | 'thumb_up_filled' | 'plus' | 'check';
+/** App-defined button beside the transport controls in Android Auto and the notification */
+export interface SessionButton {
+    /** Passed to the press callback */
+    action: string;
+    /** Accessibility label */
+    title: string;
+    icon: SessionButtonIcon;
+}

package/lib/types/PlayerQueue.d.ts

@@ -68,6 +68,10 @@ export interface PlayerConfig {
      * Fixed interval, in seconds, for remote skip-backward controls (default: 15)
      */
     remoteSkipBackwardInterval?: number;
+    /**
+     * iOS only, ignored on Android: the lock screen, Control Center and CarPlay side buttons skip by the remote skip intervals instead of changing track (default: false)
+     */
+    preferRemoteSkipIntervals?: boolean;
     /**
      * Number of upcoming tracks to preload URLs for (default: 5)
      * Higher values = more proactive loading, but more network requests

package/lib/utils/androidAutoMediaLibrary.d.ts

@@ -1,4 +1,5 @@
-import type { MediaLibrary } from '../types/AndroidAutoMediaLibrary';
+import type { MediaItem, MediaLibrary, SessionButton } from '../types/AndroidAutoMediaLibrary';
+type ItemsProvider = (argument: string) => Promise<MediaItem[] | null | undefined>;
 /**
  * Helper utilities for Android Auto Media Library
  * Android-only functionality
@@ -40,8 +41,19 @@ export declare const AndroidAutoMediaLibraryHelper: {
      * Falls back to showing all playlists
      */
     clear: () => void;
+    /** Children of folders published with `children: []`; playable ids are `${playlistId}:${trackId}`, empty after 10s. Register at module scope: the car can start the app without UI. */
+    setChildrenLoader: (loader: ItemsProvider) => void;
+    /** Answers car searches and unmatched voice requests (first playable result plays); search shows from the next connection. */
+    setSearchHandler: (handler: ItemsProvider) => void;
+    /** Buttons beside the transport controls in Android Auto and the notification; call again to change their state. */
+    setSessionButtons: (buttons: SessionButton[]) => void;
+    /** Called with the pressed button's `action`. */
+    onSessionButtonPress: (callback: (action: string) => void) => void;
+    /** Car auto-play or play-on-connect found nothing loaded: restore your last queue (playback starts once it is loaded). */
+    onPlaybackResumption: (callback: () => void) => void;
     /**
      * Check if Android Auto Media Library is available (Android only)
      */
     isAvailable: () => boolean;
 };
+export {};

package/lib/utils/androidAutoMediaLibrary.js

@@ -1,4 +1,7 @@
 import { AndroidAutoMediaLibrary as AndroidAutoMediaLibraryModule } from '../index';
+const answer = (requestId, provide) => provide()
+    .catch(() => null)
+    .then((items) => AndroidAutoMediaLibraryModule?.resolveRequest(requestId, JSON.stringify(items ?? [])));
 /**
  * Helper utilities for Android Auto Media Library
  * Android-only functionality
@@ -53,6 +56,26 @@ export const AndroidAutoMediaLibraryHelper = {
         }
         AndroidAutoMediaLibraryModule.clearMediaLibrary();
     },
+    /** Children of folders published with `children: []`; playable ids are `${playlistId}:${trackId}`, empty after 10s. Register at module scope: the car can start the app without UI. */
+    setChildrenLoader: (loader) => {
+        AndroidAutoMediaLibraryModule?.onLoadChildren((requestId, parentId) => answer(requestId, () => loader(parentId)));
+    },
+    /** Answers car searches and unmatched voice requests (first playable result plays); search shows from the next connection. */
+    setSearchHandler: (handler) => {
+        AndroidAutoMediaLibraryModule?.onSearch((requestId, query) => answer(requestId, () => handler(query)));
+    },
+    /** Buttons beside the transport controls in Android Auto and the notification; call again to change their state. */
+    setSessionButtons: (buttons) => {
+        AndroidAutoMediaLibraryModule?.setSessionButtons(JSON.stringify(buttons));
+    },
+    /** Called with the pressed button's `action`. */
+    onSessionButtonPress: (callback) => {
+        AndroidAutoMediaLibraryModule?.onSessionButtonPress(callback);
+    },
+    /** Car auto-play or play-on-connect found nothing loaded: restore your last queue (playback starts once it is loaded). */
+    onPlaybackResumption: (callback) => {
+        AndroidAutoMediaLibraryModule?.onPlaybackResumption(callback);
+    },
     /**
      * Check if Android Auto Media Library is available (Android only)
      */

package/nitrogen/generated/android/NitroPlayerOnLoad.cpp

@@ -16,6 +16,9 @@
 #include <NitroModules/HybridObjectRegistry.hpp>
 
 #include "JHybridAndroidAutoMediaLibrarySpec.hpp"
+#include "JFunc_void_std__string_std__string.hpp"
+#include "JFunc_void_std__string.hpp"
+#include "JFunc_void.hpp"
 #include "JHybridAudioDevicesSpec.hpp"
 #include "JHybridCastSpec.hpp"
 #include "JFunc_void_CastState_std__optional_std__variant_nitro__NullType__std__string__.hpp"
@@ -112,6 +115,9 @@ void registerAllNatives() {
 
   // Register native JNI methods
   margelo::nitro::nitroplayer::JHybridAndroidAutoMediaLibrarySpec::CxxPart::registerNatives();
+  margelo::nitro::nitroplayer::JFunc_void_std__string_std__string_cxx::registerNatives();
+  margelo::nitro::nitroplayer::JFunc_void_std__string_cxx::registerNatives();
+  margelo::nitro::nitroplayer::JFunc_void_cxx::registerNatives();
   margelo::nitro::nitroplayer::JHybridAudioDevicesSpec::CxxPart::registerNatives();
   margelo::nitro::nitroplayer::JHybridCastSpec::CxxPart::registerNatives();
   margelo::nitro::nitroplayer::JFunc_void_CastState_std__optional_std__variant_nitro__NullType__std__string___cxx::registerNatives();