@javascriptcommon/react-native-track-player 4.1.13 → 4.1.15

package/android/src/main/java/com/doublesymmetry/trackplayer/model/Track.kt

@@ -24,15 +24,17 @@ class Track
     var originalItem: Bundle?
     var headers: HashMap<String, String>? = null
     val queueId: Long
+    var notPlayable: Boolean = false
 
     override fun setMetadata(context: Context, bundle: Bundle?, ratingType: Int) {
         super.setMetadata(context, bundle, ratingType)
         if (originalItem != null && originalItem != bundle) originalItem!!.putAll(bundle)
+        bundle?.getBoolean("notPlayable", false)?.let { notPlayable = it }
     }
 
     fun toAudioItem(): TrackAudioItem {
         return TrackAudioItem(this, type, uri.toString(), artist, title, album, artwork.toString(), duration,
-                AudioItemOptions(headers, userAgent, resourceId), mediaId)
+                AudioItemOptions(headers, userAgent, resourceId), mediaId, notPlayable)
     }
 
     init {
@@ -60,6 +62,7 @@ class Track
                 headers!![header] = httpHeaders.getString(header)!!
             }
         }
+        notPlayable = bundle.getBoolean("notPlayable", false)
         setMetadata(context, bundle, ratingType)
         queueId = System.currentTimeMillis()
         originalItem = bundle

package/android/src/main/java/com/doublesymmetry/trackplayer/model/TrackAudioItem.kt

@@ -14,5 +14,6 @@ data class TrackAudioItem(
     override val artwork: String? = null,
     override val duration: Long? = null,
     override val options: AudioItemOptions? = null,
-    override val mediaId: String? = null
+    override val mediaId: String? = null,
+    val notPlayable: Boolean = false
 ): AudioItem

package/android/src/main/java/com/doublesymmetry/trackplayer/module/MusicEvents.kt

@@ -48,6 +48,7 @@ class MusicEvents(private val reactContext: ReactContext) : BroadcastReceiver()
         const val PLAYBACK_PROGRESS_UPDATED = "playback-progress-updated"
         const val PLAYBACK_ERROR = "playback-error"
         const val PLAYBACK_ANIMATED_VOLUME_CHANGED = "playback-animated-volume-changed"
+        const val PLAYBACK_NOT_PLAYABLE_TRACK_ACTIVE = "playback-not-playable-track-active"
         const val PLAYBACK_RESUME = "playback-resume-android"
         const val FFT_UPDATED = "fft-updated"
 

package/android/src/main/java/com/doublesymmetry/trackplayer/module/MusicModule.kt

@@ -485,6 +485,19 @@ class MusicModule(reactContext: ReactApplicationContext) : NativeTrackPlayerSpec
         callback.resolve(null)
     }
 
+    override fun setTrackPlayable(trackIndex: Double, playable: Boolean, callback: Promise) = launchInScope {
+        if (verifyServiceBoundOrReject(callback)) return@launchInScope
+
+        val index = trackIndex.toInt()
+        if (index < 0 || index >= musicService.tracks.size) {
+            callback.reject("index_out_of_bounds", "The track index is out of bounds")
+            return@launchInScope
+        }
+
+        musicService.setTrackPlayable(index, playable)
+        callback.resolve(null)
+    }
+
     override fun removeUpcomingTracks(callback: Promise) = launchInScope {
         if (verifyServiceBoundOrReject(callback)) return@launchInScope
 

package/android/src/main/java/com/doublesymmetry/trackplayer/service/MusicService.kt

@@ -357,6 +357,16 @@ class MusicService : HeadlessJsMediaService() {
             putDoubleArray("data", v)
 
         })}
+        // Set up callback for notPlayable tracks
+        player.onNotPlayableTrackActive = { index, item ->
+            val bundle = Bundle().apply {
+                putInt("index", index)
+                if (item is TrackAudioItem) {
+                    putBundle("track", item.track.originalItem)
+                }
+            }
+            emit(MusicEvents.PLAYBACK_NOT_PLAYABLE_TRACK_ACTIVE, bundle)
+        }
         fakePlayer.release()
         mediaSession.player = player.player
         observeEvents()
@@ -713,6 +723,27 @@ class MusicService : HeadlessJsMediaService() {
         updateMetadataForTrack(player.currentIndex, track)
     }
 
+    @MainThread
+    fun setTrackPlayable(index: Int, playable: Boolean) {
+        val track = tracks.getOrNull(index) ?: return
+        val wasNotPlayable = track.notPlayable
+        track.notPlayable = !playable
+        player.replaceItem(index, track.toAudioItem())
+
+        // If current track: notPlayable -> playable, load it
+        if (wasNotPlayable && playable && player.currentIndex == index) {
+            player.load(track.toAudioItem())
+        }
+        // If current track: playable -> notPlayable, stop and emit event
+        else if (!wasNotPlayable && !playable && player.currentIndex == index) {
+            player.stop()
+            emit(MusicEvents.PLAYBACK_NOT_PLAYABLE_TRACK_ACTIVE, Bundle().apply {
+                putInt("index", index)
+                putBundle("track", track.originalItem)
+            })
+        }
+    }
+
     @MainThread
     fun clearNotificationMetadata() {
     }

package/android/src/main/java/com/doublesymmetry/trackplayer/utils/BundleUtils.kt

@@ -21,8 +21,8 @@ object BundleUtils {
         if (!data!!.containsKey(key)) return null
         val obj = data[key]
         if (obj is String) {
-            // Remote or Local Uri
-            if (obj.trim { it <= ' ' }.isEmpty()) throw RuntimeException("$key: The URL cannot be empty")
+            // Remote or Local Uri - allow empty URLs for placeholder tracks
+            if (obj.trim { it <= ' ' }.isEmpty()) return Uri.EMPTY
             return Uri.parse(obj as String?)
         } else if (obj is Bundle) {
             // require/import

package/android/src/main/java/com/lovegaoshi/kotlinaudio/models/AudioItem.kt

@@ -77,15 +77,23 @@ enum class MediaType(val value: String) {
 
 
 fun audioItem2MediaItem(audioItem: AudioItem, context: Context? = null): MediaItem {
+    // Check if this is a placeholder track (notPlayable flag from TrackAudioItem)
+    val isNotPlayable = (audioItem as? com.doublesymmetry.trackplayer.model.TrackAudioItem)?.notPlayable ?: false
+    val hasValidUrl = audioItem.audioUrl.isNotBlank()
+
     return MediaItem.Builder()
         .setMediaId(audioItem.mediaId ?: UUID.randomUUID().toString())
+        // Always set URI (even empty string) so ExoPlayer adds item to timeline
         .setUri(audioItem.audioUrl)
         .setMediaMetadata(
             MediaMetadata.Builder()
             .setTitle(audioItem.title)
             .setArtist(audioItem.artist)
+            // Mark placeholder tracks as not playable so Android Auto shows them correctly in queue
+            .setIsPlayable(true)
+            .setIsBrowsable(false)
             .setArtworkUri((
-                if (context != null && audioItem.audioUrl.startsWith("file://")) {
+                if (context != null && hasValidUrl && audioItem.audioUrl.startsWith("file://")) {
                     saveMediaCoverToPng(
                         audioItem.audioUrl,
                         context.contentResolver,
@@ -94,7 +102,7 @@ fun audioItem2MediaItem(audioItem: AudioItem, context: Context? = null): MediaIt
                         ?: audioItem.artwork
                 }
                 else audioItem.artwork)?.toUri())
-            .setArtworkData(if (audioItem.audioUrl.startsWith("file://")) getEmbeddedBitmapArray(
+            .setArtworkData(if (hasValidUrl && audioItem.audioUrl.startsWith("file://")) getEmbeddedBitmapArray(
                 audioItem.audioUrl.substring(7)) else null, MediaMetadata.PICTURE_TYPE_MEDIA)
             .setExtras(Bundle().apply {
                 audioItem.options?.headers?.let {
@@ -108,6 +116,7 @@ fun audioItem2MediaItem(audioItem: AudioItem, context: Context? = null): MediaIt
                 }
                 putString("type", audioItem.type.toString())
                 putString("uri", audioItem.audioUrl)
+                putBoolean("notPlayable", isNotPlayable)
             }).build())
         .setTag(audioItem)
         .build()

package/android/src/main/java/com/lovegaoshi/kotlinaudio/player/QueuedAudioPlayer.kt

@@ -8,6 +8,7 @@ import androidx.media3.common.MediaItem
 import androidx.media3.common.Player
 import androidx.media3.common.util.UnstableApi
 import com.lovegaoshi.kotlinaudio.models.*
+import com.doublesymmetry.trackplayer.model.TrackAudioItem
 import java.util.*
 import kotlin.math.max
 import kotlin.math.min
@@ -19,6 +20,12 @@ class QueuedAudioPlayer(
 
     var parseEmbeddedArtwork: Boolean = false
 
+    /**
+     * Callback invoked when a track with notPlayable=true becomes current.
+     * The player will stay on this track but won't load or play it.
+     */
+    var onNotPlayableTrackActive: ((index: Int, item: AudioItem) -> Unit)? = null
+
     private val queue = LinkedList<MediaItem>()
 
     private fun parseAudioItem(audioItem: AudioItem): MediaItem {
@@ -91,11 +98,21 @@ class QueuedAudioPlayer(
         get() = items.getOrNull(currentIndex - 1)
 
     override fun load(item: AudioItem, playWhenReady: Boolean) {
+        // Check if item is notPlayable
+        if (item is TrackAudioItem && item.notPlayable) {
+            onNotPlayableTrackActive?.invoke(currentIndex, item)
+            return
+        }
         load(item)
         exoPlayer.playWhenReady = playWhenReady
     }
 
     override fun load(item: AudioItem) {
+        // Check if item is notPlayable
+        if (item is TrackAudioItem && item.notPlayable) {
+            onNotPlayableTrackActive?.invoke(currentIndex, item)
+            return
+        }
         if (queue.isEmpty()) {
             add(item)
         } else {
@@ -230,6 +247,13 @@ class QueuedAudioPlayer(
      */
     fun jumpToItem(index: Int) {
         try {
+            // Check if the target item is notPlayable
+            val item = items.getOrNull(index)
+            if (item is TrackAudioItem && item.notPlayable) {
+                exoPlayer.seekTo(index, C.TIME_UNSET)
+                onNotPlayableTrackActive?.invoke(index, item)
+                return
+            }
             exoPlayer.seekTo(index, C.TIME_UNSET)
             exoPlayer.prepare()
         } catch (e: IllegalSeekPositionException) {

package/ios/RNTrackPlayer/Models/Track.swift

@@ -29,6 +29,9 @@ class Track: AudioItem, TimePitching, AssetOptionsProviding {
     var album: String?
     var artwork: MPMediaItemArtwork?
 
+    /// When true, the track won't load or play when it becomes current.
+    var notPlayable: Bool = false
+
     private var originalObject: [String: Any] = [:]
 
     init?(dictionary: [String: Any]) {
@@ -37,6 +40,7 @@ class Track: AudioItem, TimePitching, AssetOptionsProviding {
         self.headers = dictionary["headers"] as? [String: Any]
         self.userAgent = dictionary["userAgent"] as? String
         self.pitchAlgorithm = dictionary["pitchAlgorithm"] as? String
+        self.notPlayable = dictionary["notPlayable"] as? Bool ?? false
 
         updateMetadata(dictionary: dictionary);
     }
@@ -58,6 +62,9 @@ class Track: AudioItem, TimePitching, AssetOptionsProviding {
         self.duration = dictionary["duration"] as? Double
         self.artworkURL = MediaURL(object: dictionary["artwork"])
         self.isLiveStream = dictionary["isLiveStream"] as? Bool
+        if let notPlayable = dictionary["notPlayable"] as? Bool {
+            self.notPlayable = notPlayable
+        }
 
         self.originalObject = self.originalObject.merging(dictionary) { (_, new) in new }
     }

package/ios/RNTrackPlayer/RNTrackPlayer.swift

@@ -59,6 +59,7 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
         player.event.currentItem.addListener(self, handleAudioPlayerCurrentItemChange)
         player.event.secondElapse.addListener(self, handleAudioPlayerSecondElapse)
         player.event.playWhenReadyChange.addListener(self, handlePlayWhenReadyChange)
+        player.event.notPlayableTrackActive.addListener(self, handleNotPlayableTrackActive)
 
         // Store global reference to the underlying AVPlayer so that other native views can reuse it.
         if let wrapper = player.wrapper as? AVPlayerWrapper {
@@ -898,6 +899,47 @@ public class RNTrackPlayer: NSObject, AudioSessionControllerDelegate {
         )
     }
 
+    func handleNotPlayableTrackActive(item: AudioItem?, index: Int?) {
+        var body: Dictionary<String, Any> = [:]
+        if let index = index {
+            body["index"] = index
+        }
+        if let track = (item as? Track)?.toObject() {
+            body["track"] = track
+        }
+        emit(event: EventType.PlaybackNotPlayableTrackActive, body: body)
+    }
+
+    // MARK: - NotPlayable Track Control
+
+    @objc(setTrackPlayable:playable:resolver:rejecter:)
+    public func setTrackPlayable(
+        trackIndex: Int,
+        playable: Bool,
+        resolve: RCTPromiseResolveBlock,
+        reject: RCTPromiseRejectBlock
+    ) {
+        if (rejectWhenNotInitialized(reject: reject)) { return }
+        if (rejectWhenTrackIndexOutOfBounds(index: trackIndex, reject: reject)) { return }
+
+        let track: Track = player.items[trackIndex] as! Track
+        let wasNotPlayable = track.notPlayable
+        track.notPlayable = !playable
+
+        // If current track: notPlayable -> playable, load it
+        if wasNotPlayable && playable && player.currentIndex == trackIndex {
+            player.load(item: track)
+        }
+        // If current track: playable -> notPlayable, unload it
+        else if !wasNotPlayable && !playable && player.currentIndex == trackIndex {
+            player.wrapper.unload()
+            player.wrapper.state = .idle
+            handleNotPlayableTrackActive(item: track, index: trackIndex)
+        }
+
+        resolve(NSNull())
+    }
+
     // MARK: - iOS Equalizer Methods
 
     @objc(setEqualizerEnabled:resolver:rejecter:)

package/ios/RNTrackPlayer/Utils/EventType.swift

@@ -38,6 +38,7 @@ enum EventType: String, CaseIterable {
     case ControllerConnected = "android-controller-connected"
     case ControllerDisconnected = "android-controller-disconnected"
     case PlaybackAnimatedVolumeChanged = "playback-animated-volume-changed"
+    case PlaybackNotPlayableTrackActive = "playback-not-playable-track-active"
 
     static func allRawValues() -> [String] {
         return allCases.map { $0.rawValue }

package/ios/SwiftAudioEx/Sources/SwiftAudioEx/Event.swift

@@ -27,6 +27,10 @@ extension AudioPlayer {
         lastIndex: Int?,
         lastPosition: Double?
     )
+    public typealias NotPlayableTrackActiveEventData = (
+        item: AudioItem?,
+        index: Int?
+    )
     
     public struct EventHolder {
         
@@ -104,6 +108,13 @@ extension AudioPlayer {
          - Note: It is only fired for instances of a QueuedAudioPlayer.
          */
         public let currentItem: AudioPlayer.Event<CurrentItemEventData> = AudioPlayer.Event()
+
+        /**
+         Emitted when a track with notPlayable=true becomes the active track.
+         The track stays current but won't load or play.
+         - Important: Remember to dispatch to the main queue if any UI is updated in the event handler.
+         */
+        public let notPlayableTrackActive: AudioPlayer.Event<NotPlayableTrackActiveEventData> = AudioPlayer.Event()
     }
     
     public typealias EventClosure<EventData> = (EventData) -> Void

package/ios/SwiftAudioEx/Sources/SwiftAudioEx/QueuedAudioPlayer.swift

@@ -207,7 +207,20 @@ public class QueuedAudioPlayer: AudioPlayer, QueueManagerDelegate {
     func onCurrentItemChanged() {
         let lastPosition = currentTime;
         if let currentItem = currentItem {
-            super.load(item: currentItem)
+            // Check if the track is marked as notPlayable
+            if isTrackNotPlayable(currentItem) {
+                // Don't load the item, emit notPlayableTrackActive event
+                event.notPlayableTrackActive.emit(
+                    data: (
+                        item: currentItem,
+                        index: currentIndex == -1 ? nil : currentIndex
+                    )
+                )
+                // Set player to idle state without loading
+                wrapper.state = .idle
+            } else {
+                super.load(item: currentItem)
+            }
         } else {
             super.clear()
         }
@@ -224,6 +237,19 @@ public class QueuedAudioPlayer: AudioPlayer, QueueManagerDelegate {
         lastIndex = currentIndex
     }
 
+    /// Check if an AudioItem is marked as notPlayable.
+    /// This method checks if the item has a notPlayable property set to true.
+    private func isTrackNotPlayable(_ item: AudioItem) -> Bool {
+        // Use reflection to check for notPlayable property
+        let mirror = Mirror(reflecting: item)
+        for child in mirror.children {
+            if child.label == "notPlayable", let value = child.value as? Bool {
+                return value
+            }
+        }
+        return false
+    }
+
     func onSkippedToSameCurrentItem() {
         if (wrapper.playbackActive) {
             replay()

package/lib/specs/NativeTrackPlayer.d.ts

@@ -28,6 +28,7 @@ export interface Spec extends TurboModule {
     skipToPrevious(initialPosition: number): Promise<void>;
     updateMetadataForTrack(trackIndex: number, metadata: UnsafeObject): Promise<void>;
     updateNowPlayingMetadata(metadata: UnsafeObject): Promise<void>;
+    setTrackPlayable(trackIndex: number, playable: boolean): Promise<void>;
     setQueue(tracks: UnsafeObject[]): Promise<void>;
     getQueue(): Promise<UnsafeObject[]>;
     setRepeatMode(mode: number): Promise<number>;

package/lib/src/constants/Event.d.ts

@@ -168,5 +168,10 @@ export declare enum Event {
     /**
      * Fired when there is an fft update
      **/
-    fftUpdate = "fft-updated"
+    fftUpdate = "fft-updated",
+    /**
+     * Fired when a track with notPlayable=true becomes the active track.
+     * The track stays current but won't load or play.
+     */
+    PlaybackNotPlayableTrackActive = "playback-not-playable-track-active"
 }

package/lib/src/constants/Event.js

@@ -170,4 +170,9 @@ export var Event;
      * Fired when there is an fft update
      **/
     Event["fftUpdate"] = "fft-updated";
+    /**
+     * Fired when a track with notPlayable=true becomes the active track.
+     * The track stays current but won't load or play.
+     */
+    Event["PlaybackNotPlayableTrackActive"] = "playback-not-playable-track-active";
 })(Event || (Event = {}));

package/lib/src/hooks/useTrackPlayerEvents.d.ts

@@ -1,8 +1,7 @@
-import { Event } from '../constants';
-import type { EventPayloadByEventWithType } from '../interfaces';
+import type { EventPayloadByEvent, EventPayloadByEventWithType } from '../interfaces';
 /**
  * Attaches a handler to the given TrackPlayer events and performs cleanup on unmount
  * @param events - TrackPlayer events to subscribe to
  * @param handler - callback invoked when the event fires
  */
-export declare const useTrackPlayerEvents: <T extends Event[], H extends (data: EventPayloadByEventWithType[T[number]]) => void>(events: T, handler: H) => void;
+export declare const useTrackPlayerEvents: <T extends (keyof EventPayloadByEvent)[], H extends (data: EventPayloadByEventWithType[T[number]]) => void>(events: T, handler: H) => void;

package/lib/src/hooks/useTrackPlayerEvents.js

@@ -1,6 +1,5 @@
 import { useEffect, useRef } from 'react';
 import { addEventListener } from '../trackPlayer';
-import { Event } from '../constants';
 /**
  * Attaches a handler to the given TrackPlayer events and performs cleanup on unmount
  * @param events - TrackPlayer events to subscribe to

package/lib/src/interfaces/Track.d.ts

@@ -13,6 +13,11 @@ export interface Track extends TrackMetadataBase {
     headers?: {
         [key: string]: any;
     };
+    /**
+     * When true, the track won't load or play when it becomes current.
+     * The track stays in the queue but playback is blocked.
+     */
+    notPlayable?: boolean;
     [key: string]: any;
 }
 export type AddTrack = Track & {

package/lib/src/interfaces/events/EventPayloadByEvent.d.ts

@@ -63,6 +63,7 @@ export type EventPayloadByEvent = {
     [Event.connectorConnected]: ControllerConnectedEvent;
     [Event.connectorDisconnected]: ControllerDisconnectedEvent;
     [Event.fftUpdate]: FFTUpdateEvent;
+    [Event.PlaybackNotPlayableTrackActive]: never;
 };
 type Simplify<T> = {
     [KeyType in keyof T]: T[KeyType];

package/lib/src/trackPlayer.d.ts

@@ -1,4 +1,4 @@
-import { Event, RepeatMode, AndroidAutoContentStyle } from './constants';
+import { RepeatMode, AndroidAutoContentStyle } from './constants';
 import type { AddTrack, EventPayloadByEvent, NowPlayingMetadata, PlaybackState, PlayerOptions, Progress, ServiceHandler, Track, TrackMetadataBase, UpdateOptions, AndroidAutoBrowseTree, MediaItem } from './interfaces';
 /**
  * Initializes the player with the specified options.
@@ -16,7 +16,7 @@ export declare function setupPlayer(options?: PlayerOptions, background?: boolea
  * Register the playback service. The service will run as long as the player runs.
  */
 export declare function registerPlaybackService(factory: () => ServiceHandler): void;
-export declare function addEventListener<T extends Event>(event: T, listener: EventPayloadByEvent[T] extends never ? () => void : (event: EventPayloadByEvent[T]) => void): import("react-native").EmitterSubscription;
+export declare function addEventListener<T extends keyof EventPayloadByEvent>(event: T, listener: EventPayloadByEvent[T] extends never ? () => void : (event: EventPayloadByEvent[T]) => void): import("react-native").EmitterSubscription;
 /**
  * Adds one or more tracks to the queue.
  *
@@ -110,6 +110,15 @@ export declare function updateMetadataForTrack(trackIndex: number, metadata: Tra
  * without affecting the data stored for the current track.
  */
 export declare function updateNowPlayingMetadata(metadata: NowPlayingMetadata): Promise<void>;
+/**
+ * Updates the playable status of a track in the queue.
+ * When playable is false (notPlayable is true), the track won't load or play when current.
+ * When playable is true (notPlayable is false), normal playback behavior resumes.
+ *
+ * @param trackIndex The index of the track to update.
+ * @param playable Whether the track should be playable.
+ */
+export declare function setTrackPlayable(trackIndex: number, playable: boolean): Promise<void>;
 /**
  * Resets the player stopping the current track and clearing the queue.
  */

package/lib/src/trackPlayer.js

@@ -163,6 +163,17 @@ export function updateNowPlayingMetadata(metadata) {
     });
 }
 // MARK: - Player API
+/**
+ * Updates the playable status of a track in the queue.
+ * When playable is false (notPlayable is true), the track won't load or play when current.
+ * When playable is true (notPlayable is false), normal playback behavior resumes.
+ *
+ * @param trackIndex The index of the track to update.
+ * @param playable Whether the track should be playable.
+ */
+export async function setTrackPlayable(trackIndex, playable) {
+    return TrackPlayer.setTrackPlayable(trackIndex, playable);
+}
 /**
  * Resets the player stopping the current track and clearing the queue.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@javascriptcommon/react-native-track-player",
-  "version": "4.1.13",
+  "version": "4.1.15",
   "description": "A fully fledged audio module created for music apps",
   "main": "lib/src/index.js",
   "types": "lib/src/index.d.ts",

package/specs/NativeTrackPlayer.ts

@@ -41,6 +41,7 @@ export interface Spec extends TurboModule {
     metadata: UnsafeObject,
   ): Promise<void>;
   updateNowPlayingMetadata(metadata: UnsafeObject): Promise<void>;
+  setTrackPlayable(trackIndex: number, playable: boolean): Promise<void>;
   setQueue(tracks: UnsafeObject[]): Promise<void>;
   getQueue(): Promise<UnsafeObject[]>;
   setRepeatMode(mode: number): Promise<number>;

package/src/constants/Event.ts

@@ -170,4 +170,9 @@ export enum Event {
    * Fired when there is an fft update
    **/
   fftUpdate = 'fft-updated',
+  /**
+   * Fired when a track with notPlayable=true becomes the active track.
+   * The track stays current but won't load or play.
+   */
+  PlaybackNotPlayableTrackActive = 'playback-not-playable-track-active',
 }

package/src/hooks/useTrackPlayerEvents.ts

@@ -1,8 +1,7 @@
 import { useEffect, useRef } from 'react';
 
 import { addEventListener } from '../trackPlayer';
-import { Event } from '../constants';
-import type { EventPayloadByEventWithType } from '../interfaces';
+import type { EventPayloadByEvent, EventPayloadByEventWithType } from '../interfaces';
 
 /**
  * Attaches a handler to the given TrackPlayer events and performs cleanup on unmount
@@ -10,7 +9,7 @@ import type { EventPayloadByEventWithType } from '../interfaces';
  * @param handler - callback invoked when the event fires
  */
 export const useTrackPlayerEvents = <
-  T extends Event[],
+  T extends (keyof EventPayloadByEvent)[],
   H extends (data: EventPayloadByEventWithType[T[number]]) => void
 >(
   events: T,

package/src/interfaces/Track.ts

@@ -13,6 +13,11 @@ export interface Track extends TrackMetadataBase {
   pitchAlgorithm?: PitchAlgorithm;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   headers?: { [key: string]: any };
+  /**
+   * When true, the track won't load or play when it becomes current.
+   * The track stays in the queue but playback is blocked.
+   */
+  notPlayable?: boolean;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   [key: string]: any;
 }

package/src/interfaces/events/EventPayloadByEvent.ts

@@ -68,6 +68,7 @@ export type EventPayloadByEvent = {
   [Event.connectorConnected]: ControllerConnectedEvent;
   [Event.connectorDisconnected]: ControllerDisconnectedEvent;
   [Event.fftUpdate]: FFTUpdateEvent;
+  [Event.PlaybackNotPlayableTrackActive]: never;
 };
 
 // eslint-disable-next-line

package/src/trackPlayer.ts

@@ -82,7 +82,7 @@ export function registerPlaybackService(factory: () => ServiceHandler) {
   }
 }
 
-export function addEventListener<T extends Event>(
+export function addEventListener<T extends keyof EventPayloadByEvent>(
   event: T,
   listener: EventPayloadByEvent[T] extends never
     ? () => void
@@ -275,6 +275,21 @@ export function updateNowPlayingMetadata(
 
 // MARK: - Player API
 
+/**
+ * Updates the playable status of a track in the queue.
+ * When playable is false (notPlayable is true), the track won't load or play when current.
+ * When playable is true (notPlayable is false), normal playback behavior resumes.
+ *
+ * @param trackIndex The index of the track to update.
+ * @param playable Whether the track should be playable.
+ */
+export async function setTrackPlayable(
+  trackIndex: number,
+  playable: boolean,
+): Promise<void> {
+  return TrackPlayer.setTrackPlayable(trackIndex, playable);
+}
+
 /**
  * Resets the player stopping the current track and clearing the queue.
  */