react-native-nitro-player 1.6.0-alpha.0 → 1.6.0

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

@@ -178,6 +178,11 @@ class HybridTrackPlayer : HybridTrackPlayerSpec() {
         listenerIds += "onAndroidAutoConnectionChange" to id
     }
 
+    override fun appStartedWithNotification(callback: (track: TrackItem) -> Unit) {
+        val id = core.addOnNotificationLaunchListener(callback)
+        listenerIds += "appStartedWithNotification" to id
+    }
+
     override fun onTracksNeedUpdate(callback: (tracks: Array<TrackItem>, lookahead: Double) -> Unit) {
         val id =
             core.addOnTracksNeedUpdateListener { tracks, lookahead ->
@@ -213,6 +218,7 @@ class HybridTrackPlayer : HybridTrackPlayerSpec() {
                 "onTracksNeedUpdate" -> core.removeOnTracksNeedUpdateListener(id)
                 "onTemporaryQueueChange" -> core.removeOnTemporaryQueueChangeListener(id)
                 "onTimedMetadata" -> core.removeOnTimedMetadataListener(id)
+                "appStartedWithNotification" -> core.removeOnNotificationLaunchListener(id)
             }
         }
         listenerIds.clear()

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

@@ -2,13 +2,17 @@
 
 package com.margelo.nitro.nitroplayer.core
 
+import android.app.Activity
+import android.app.Application
 import android.content.ComponentName
 import android.content.Context
 import android.content.Intent
 import android.content.ServiceConnection
+import android.os.Bundle
 import android.os.Handler
 import android.os.IBinder
 import android.os.Looper
+import com.facebook.react.bridge.ReactApplicationContext
 import com.margelo.nitro.nitroplayer.Reason
 import com.margelo.nitro.nitroplayer.RepeatMode
 import com.margelo.nitro.nitroplayer.TimedMetadata
@@ -95,6 +99,8 @@ class TrackPlayerCore private constructor(
         ListenerRegistry<(TimedMetadata) -> Unit>()
     internal val onCastStateChangeListeners =
         ListenerRegistry<(com.margelo.nitro.nitroplayer.CastState, String?) -> Unit>()
+    internal val onNotificationLaunchListeners =
+        ListenerRegistry<(TrackItem) -> Unit>()
 
     // ── Google Cast ──────────────────────────────────────────────────────────
 
@@ -390,4 +396,57 @@ class TrackPlayerCore private constructor(
     fun addOnCastStateChangeListener(cb: (com.margelo.nitro.nitroplayer.CastState, String?) -> Unit): Long = onCastStateChangeListeners.add(cb)
 
     fun removeOnCastStateChangeListener(id: Long): Boolean = onCastStateChangeListeners.remove(id)
+
+    // ── Notification-launch detection ─────────────────────────────────────
+
+    private var notificationLaunchDetectionRegistered = false
+
+    fun addOnNotificationLaunchListener(cb: (TrackItem) -> Unit): Long {
+        val id = onNotificationLaunchListeners.add(cb)
+        handler.post {
+            registerNotificationLaunchDetection()
+            checkNotificationLaunch((context as? ReactApplicationContext)?.currentActivity)
+        }
+        return id
+    }
+
+    fun removeOnNotificationLaunchListener(id: Long): Boolean = onNotificationLaunchListeners.remove(id)
+
+    private fun registerNotificationLaunchDetection() {
+        if (notificationLaunchDetectionRegistered) return
+        notificationLaunchDetectionRegistered = true
+        val app = context.applicationContext as? Application ?: return
+        app.registerActivityLifecycleCallbacks(
+            object : Application.ActivityLifecycleCallbacks {
+                override fun onActivityResumed(activity: Activity) = checkNotificationLaunch(activity)
+
+                override fun onActivityCreated(
+                    activity: Activity,
+                    savedInstanceState: Bundle?,
+                ) {}
+
+                override fun onActivityStarted(activity: Activity) {}
+
+                override fun onActivityPaused(activity: Activity) {}
+
+                override fun onActivityStopped(activity: Activity) {}
+
+                override fun onActivitySaveInstanceState(
+                    activity: Activity,
+                    outState: Bundle,
+                ) {}
+
+                override fun onActivityDestroyed(activity: Activity) {}
+            },
+        )
+    }
+
+    // Must run on the main looper — reads the player and mutates the activity intent
+    internal fun checkNotificationLaunch(activity: Activity?) {
+        val intent = activity?.intent ?: return
+        if (!intent.getBooleanExtra(NitroPlayerPlaybackService.EXTRA_STARTED_FROM_NOTIFICATION, false)) return
+        val track = getCurrentTrack() ?: return
+        intent.removeExtra(NitroPlayerPlaybackService.EXTRA_STARTED_FROM_NOTIFICATION)
+        onNotificationLaunchListeners.forEach { it(track) }
+    }
 }

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

@@ -7,6 +7,7 @@ import androidx.media3.common.MediaMetadata
 import androidx.media3.common.Metadata
 import androidx.media3.common.Player
 import androidx.media3.common.util.UnstableApi
+import androidx.media3.extractor.metadata.icy.IcyInfo
 import com.margelo.nitro.nitroplayer.Reason
 import com.margelo.nitro.nitroplayer.RepeatMode
 import com.margelo.nitro.nitroplayer.TimedMetadata
@@ -90,16 +91,27 @@ internal class TrackPlayerEventListener(
     @UnstableApi
     override fun onMetadata(metadata: Metadata) {
         val builder = MediaMetadata.Builder()
+        var url: String? = null
         for (i in 0 until metadata.length()) {
-            metadata.get(i).populateMediaMetadata(builder)
+            val entry = metadata.get(i)
+            entry.populateMediaMetadata(builder)
+            // populateMediaMetadata drops IcyInfo.url — radio providers put the
+            // current track's artwork URL there, so read it off the entry directly.
+            if (entry is IcyInfo && !entry.url.isNullOrEmpty()) url = entry.url
         }
         val merged = builder.build()
-        val title = merged.title?.toString()
-        val artist = merged.artist?.toString()
+        var artist = merged.artist?.toString()
+        var title = merged.title?.toString()
+        // ICY streams pack both fields into one "Artist - Title" string
+        val separator = if (artist == null) title?.indexOf(" - ") ?: -1 else -1
+        if (separator > 0 && title != null && separator + 3 < title.length) {
+            artist = title.substring(0, separator)
+            title = title.substring(separator + 3)
+        }
         val album = merged.albumTitle?.toString()
         val artworkUrl = merged.artworkUri?.toString()
-        if (title == null && artist == null && album == null && artworkUrl == null) return
-        core.notifyTimedMetadata(TimedMetadata(title, artist, album, artworkUrl))
+        if (title == null && artist == null && album == null && url == null && artworkUrl == null) return
+        core.notifyTimedMetadata(TimedMetadata(title, artist, album, url, artworkUrl))
     }
 
     override fun onTimelineChanged(

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

@@ -1,5 +1,6 @@
 package com.margelo.nitro.nitroplayer.media
 
+import android.app.PendingIntent
 import android.content.Intent
 import android.os.Binder
 import android.os.Handler
@@ -32,6 +33,7 @@ class NitroPlayerPlaybackService : MediaSessionService() {
 
     companion object {
         const val ACTION_LOCAL_BIND = "com.margelo.nitro.nitroplayer.LOCAL_BIND"
+        const val EXTRA_STARTED_FROM_NOTIFICATION = "com.margelo.nitro.nitroplayer.STARTED_FROM_NOTIFICATION"
 
         @Volatile
         var notificationSmallIconResName: String? = null
@@ -84,6 +86,7 @@ class NitroPlayerPlaybackService : MediaSessionService() {
         mediaSession = MediaSession
             .Builder(this, player)
             .setCallback(MediaSessionCallbackFactory.create(this, playlistManager))
+            .apply { buildSessionActivity()?.let { setSessionActivity(it) } }
             .build()
 
         val provider = DefaultMediaNotificationProvider.Builder(this).build()
@@ -119,6 +122,18 @@ class NitroPlayerPlaybackService : MediaSessionService() {
         }
     }
 
+    // Content intent for the notification tap — newer Android has no fallback without it
+    private fun buildSessionActivity(): PendingIntent? {
+        val launch = packageManager.getLaunchIntentForPackage(packageName) ?: return null
+        launch.putExtra(EXTRA_STARTED_FROM_NOTIFICATION, true)
+        return PendingIntent.getActivity(
+            this,
+            0,
+            launch,
+            PendingIntent.FLAG_IMMUTABLE or PendingIntent.FLAG_UPDATE_CURRENT,
+        )
+    }
+
     private fun applyNotificationSmallIcon() {
         val name = notificationSmallIconResName ?: return
         val provider = notificationProvider ?: return

package/ios/HybridTrackPlayer.swift

@@ -188,6 +188,10 @@ final class HybridTrackPlayer: HybridTrackPlayerSpec {
     // No-op on iOS
   }
 
+  func appStartedWithNotification(callback: @escaping (_ track: TrackItem) -> Void) throws {
+    // No-op on iOS — Now Playing controls never launch the app
+  }
+
   func isAndroidAutoConnected() throws -> Bool { false }
 
   // MARK: - Event listeners (v2 — store IDs for cleanup)

package/ios/core/TrackPlayerListener.swift

@@ -510,6 +510,8 @@ extension TrackPlayerCore {
     var title: String?
     var artist: String?
     var album: String?
+    var url: String?
+    var artworkUrl: String?
 
     for group in groups {
       for item in group.items {
@@ -518,17 +520,40 @@ extension TrackPlayerCore {
         case .some(.commonKeyTitle): title = value
         case .some(.commonKeyArtist): artist = value
         case .some(.commonKeyAlbumName): album = value
+        case .some(.commonKeyArtwork): artworkUrl = value
         default:
-          // ICY/Shoutcast streams carry no common keys — match on the identifier
-          if item.identifier == .icyMetadataStreamTitle { title = value }
+          // ICY/Shoutcast streams carry no common keys — match on the identifier.
+          // StreamUrl is where radio providers put the current track's artwork.
+          switch item.identifier {
+          case .some(.icyMetadataStreamTitle): title = value
+          case .some(.icyMetadataStreamURL): url = value
+          case .some(.id3MetadataOfficialAudioSourceWebpage),
+               .some(.id3MetadataOfficialAudioFileWebpage):
+            if url == nil { url = value }
+          default: break
+          }
         }
       }
     }
 
-    guard title != nil || artist != nil || album != nil else { return }
+    (artist, title) = splitStreamTitle(artist: artist, title: title)
+
+    guard title != nil || artist != nil || album != nil || url != nil || artworkUrl != nil else { return }
     NitroPlayerLogger.log("TrackPlayerCore", "🏷️ Timed metadata - \(title ?? "-") / \(artist ?? "-")")
-    // artworkUrl is Android-only: iOS delivers embedded art as raw data, not a URL
-    notifyTimedMetadata(TimedMetadata(title: title, artist: artist, album: album, artworkUrl: nil))
+    notifyTimedMetadata(
+      TimedMetadata(title: title, artist: artist, album: album, url: url, artworkUrl: artworkUrl))
+  }
+
+  /// ICY streams pack both fields into one `"Artist - Title"` string. Split it when
+  /// the stream gave no separate artist, leaving an explicit artist untouched.
+  func splitStreamTitle(artist: String?, title: String?) -> (String?, String?) {
+    guard artist == nil, let title, let separator = title.range(of: " - ") else {
+      return (artist, title)
+    }
+    let left = String(title[title.startIndex..<separator.lowerBound])
+    let right = String(title[separator.upperBound...])
+    guard !left.isEmpty, !right.isEmpty else { return (artist, title) }
+    return (left, right)
   }
 
   func emitStateChange(reason: Reason? = nil) {

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

@@ -46,6 +46,11 @@ export interface TrackPlayer extends HybridObject<{
      * updates and ID3 frames emitted while a live stream plays.
      */
     onTimedMetadata(callback: (metadata: TimedMetadata) => void): void;
+    /**
+     * Fires when the app was opened by tapping the playback notification,
+     * with the track that was playing at tap time. Android only — no-op on iOS.
+     */
+    appStartedWithNotification(callback: (track: TrackItem) => void): void;
     onAndroidAutoConnectionChange(callback: (connected: boolean) => void): void;
     isAndroidAutoConnected(): boolean;
     setVolume(volume: number): Promise<void>;

package/lib/types/PlayerQueue.d.ts

@@ -32,8 +32,16 @@ export interface PlayerState {
 /** In-stream metadata emitted while a stream plays (ICY/Shoutcast StreamTitle, ID3 frames) */
 export interface TimedMetadata {
     title?: string;
+    /** Split out of `title` when the stream sends only `"Artist - Title"` */
     artist?: string;
     album?: string;
+    /**
+     * ICY `StreamUrl` / ID3 webpage frame. Radio providers commonly put the
+     * current track's artwork URL here (Live365, StreamGuys), but some send a
+     * station or artist page instead — check the value before treating it as art.
+     */
+    url?: string;
+    /** Artwork URL the stream tagged as artwork, when it sends one explicitly */
     artworkUrl?: string;
 }
 export interface PlayerConfig {

package/nitrogen/generated/android/NitroPlayerOnLoad.cpp

@@ -36,6 +36,7 @@
 #include "JFunc_void_double_double.hpp"
 #include "JFunc_void_double_double_std__optional_bool_.hpp"
 #include "JFunc_void_TimedMetadata.hpp"
+#include "JFunc_void_TrackItem.hpp"
 #include "JFunc_void_std__vector_TrackItem__double.hpp"
 #include "JFunc_void_std__vector_TrackItem__std__vector_TrackItem_.hpp"
 #include <NitroModules/DefaultConstructableObject.hpp>
@@ -131,6 +132,7 @@ void registerAllNatives() {
   margelo::nitro::nitroplayer::JFunc_void_double_double_cxx::registerNatives();
   margelo::nitro::nitroplayer::JFunc_void_double_double_std__optional_bool__cxx::registerNatives();
   margelo::nitro::nitroplayer::JFunc_void_TimedMetadata_cxx::registerNatives();
+  margelo::nitro::nitroplayer::JFunc_void_TrackItem_cxx::registerNatives();
   margelo::nitro::nitroplayer::JFunc_void_std__vector_TrackItem__double_cxx::registerNatives();
   margelo::nitro::nitroplayer::JFunc_void_std__vector_TrackItem__std__vector_TrackItem__cxx::registerNatives();
 

package/nitrogen/generated/android/c++/JFunc_void_TrackItem.hpp

@@ -0,0 +1,85 @@
+///
+/// JFunc_void_TrackItem.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#include <fbjni/fbjni.h>
+#include <functional>
+
+#include "TrackItem.hpp"
+#include <functional>
+#include <NitroModules/JNICallable.hpp>
+#include "JTrackItem.hpp"
+#include <string>
+#include <NitroModules/Null.hpp>
+#include <variant>
+#include <optional>
+#include "JVariant_NullType_String.hpp"
+#include <NitroModules/JNull.hpp>
+#include <NitroModules/AnyMap.hpp>
+#include <NitroModules/JAnyMap.hpp>
+
+namespace margelo::nitro::nitroplayer {
+
+  using namespace facebook;
+
+  /**
+   * Represents the Java/Kotlin callback `(track: TrackItem) -> Unit`.
+   * This can be passed around between C++ and Java/Kotlin.
+   */
+  struct JFunc_void_TrackItem: public jni::JavaClass<JFunc_void_TrackItem> {
+  public:
+    static constexpr auto kJavaDescriptor = "Lcom/margelo/nitro/nitroplayer/Func_void_TrackItem;";
+
+  public:
+    /**
+     * Invokes the function this `JFunc_void_TrackItem` instance holds through JNI.
+     */
+    void invoke(const TrackItem& track) const {
+      static const auto method = javaClassStatic()->getMethod<void(jni::alias_ref<JTrackItem> /* track */)>("invoke");
+      method(self(), JTrackItem::fromCpp(track));
+    }
+  };
+
+  /**
+   * An implementation of Func_void_TrackItem that is backed by a C++ implementation (using `std::function<...>`)
+   */
+  class JFunc_void_TrackItem_cxx final: public jni::HybridClass<JFunc_void_TrackItem_cxx, JFunc_void_TrackItem> {
+  public:
+    static jni::local_ref<JFunc_void_TrackItem::javaobject> fromCpp(const std::function<void(const TrackItem& /* track */)>& func) {
+      return JFunc_void_TrackItem_cxx::newObjectCxxArgs(func);
+    }
+
+  public:
+    /**
+     * Invokes the C++ `std::function<...>` this `JFunc_void_TrackItem_cxx` instance holds.
+     */
+    void invoke_cxx(jni::alias_ref<JTrackItem> track) {
+      _func(track->toCpp());
+    }
+
+  public:
+    [[nodiscard]]
+    inline const std::function<void(const TrackItem& /* track */)>& getFunction() const {
+      return _func;
+    }
+
+  public:
+    static constexpr auto kJavaDescriptor = "Lcom/margelo/nitro/nitroplayer/Func_void_TrackItem_cxx;";
+    static void registerNatives() {
+      registerHybrid({makeNativeMethod("invoke_cxx", JFunc_void_TrackItem_cxx::invoke_cxx)});
+    }
+
+  private:
+    explicit JFunc_void_TrackItem_cxx(const std::function<void(const TrackItem& /* track */)>& func): _func(func) { }
+
+  private:
+    friend HybridBase;
+    std::function<void(const TrackItem& /* track */)> _func;
+  };
+
+} // namespace margelo::nitro::nitroplayer

package/nitrogen/generated/android/c++/JHybridTrackPlayerSpec.cpp

@@ -60,6 +60,7 @@ namespace margelo::nitro::nitroplayer { struct TimedMetadata; }
 #include "TimedMetadata.hpp"
 #include "JFunc_void_TimedMetadata.hpp"
 #include "JTimedMetadata.hpp"
+#include "JFunc_void_TrackItem.hpp"
 #include "JFunc_void_bool.hpp"
 #include "JFunc_void_std__vector_TrackItem__double.hpp"
 #include "JFunc_void_std__vector_TrackItem__std__vector_TrackItem_.hpp"
@@ -329,6 +330,10 @@ namespace margelo::nitro::nitroplayer {
     static const auto method = _javaPart->javaClassStatic()->getMethod<void(jni::alias_ref<JFunc_void_TimedMetadata::javaobject> /* callback */)>("onTimedMetadata_cxx");
     method(_javaPart, JFunc_void_TimedMetadata_cxx::fromCpp(callback));
   }
+  void JHybridTrackPlayerSpec::appStartedWithNotification(const std::function<void(const TrackItem& /* track */)>& callback) {
+    static const auto method = _javaPart->javaClassStatic()->getMethod<void(jni::alias_ref<JFunc_void_TrackItem::javaobject> /* callback */)>("appStartedWithNotification_cxx");
+    method(_javaPart, JFunc_void_TrackItem_cxx::fromCpp(callback));
+  }
   void JHybridTrackPlayerSpec::onAndroidAutoConnectionChange(const std::function<void(bool /* connected */)>& callback) {
     static const auto method = _javaPart->javaClassStatic()->getMethod<void(jni::alias_ref<JFunc_void_bool::javaobject> /* callback */)>("onAndroidAutoConnectionChange_cxx");
     method(_javaPart, JFunc_void_bool_cxx::fromCpp(callback));

package/nitrogen/generated/android/c++/JHybridTrackPlayerSpec.hpp

@@ -73,6 +73,7 @@ namespace margelo::nitro::nitroplayer {
     void onSeek(const std::function<void(double /* position */, double /* totalDuration */)>& callback) override;
     void onPlaybackProgressChange(const std::function<void(double /* position */, double /* totalDuration */, std::optional<bool> /* isManuallySeeked */)>& callback) override;
     void onTimedMetadata(const std::function<void(const TimedMetadata& /* metadata */)>& callback) override;
+    void appStartedWithNotification(const std::function<void(const TrackItem& /* track */)>& callback) override;
     void onAndroidAutoConnectionChange(const std::function<void(bool /* connected */)>& callback) override;
     bool isAndroidAutoConnected() override;
     std::shared_ptr<Promise<void>> setVolume(double volume) override;

package/nitrogen/generated/android/c++/JTimedMetadata.hpp

@@ -38,12 +38,15 @@ namespace margelo::nitro::nitroplayer {
       jni::local_ref<jni::JString> artist = this->getFieldValue(fieldArtist);
       static const auto fieldAlbum = clazz->getField<jni::JString>("album");
       jni::local_ref<jni::JString> album = this->getFieldValue(fieldAlbum);
+      static const auto fieldUrl = clazz->getField<jni::JString>("url");
+      jni::local_ref<jni::JString> url = this->getFieldValue(fieldUrl);
       static const auto fieldArtworkUrl = clazz->getField<jni::JString>("artworkUrl");
       jni::local_ref<jni::JString> artworkUrl = this->getFieldValue(fieldArtworkUrl);
       return TimedMetadata(
         title != nullptr ? std::make_optional(title->toStdString()) : std::nullopt,
         artist != nullptr ? std::make_optional(artist->toStdString()) : std::nullopt,
         album != nullptr ? std::make_optional(album->toStdString()) : std::nullopt,
+        url != nullptr ? std::make_optional(url->toStdString()) : std::nullopt,
         artworkUrl != nullptr ? std::make_optional(artworkUrl->toStdString()) : std::nullopt
       );
     }
@@ -54,7 +57,7 @@ namespace margelo::nitro::nitroplayer {
      */
     [[maybe_unused]]
     static jni::local_ref<JTimedMetadata::javaobject> fromCpp(const TimedMetadata& value) {
-      using JSignature = JTimedMetadata(jni::alias_ref<jni::JString>, jni::alias_ref<jni::JString>, jni::alias_ref<jni::JString>, jni::alias_ref<jni::JString>);
+      using JSignature = JTimedMetadata(jni::alias_ref<jni::JString>, jni::alias_ref<jni::JString>, jni::alias_ref<jni::JString>, jni::alias_ref<jni::JString>, jni::alias_ref<jni::JString>);
       static const auto clazz = javaClassStatic();
       static const auto create = clazz->getStaticMethod<JSignature>("fromCpp");
       return create(
@@ -62,6 +65,7 @@ namespace margelo::nitro::nitroplayer {
         value.title.has_value() ? jni::make_jstring(value.title.value()) : nullptr,
         value.artist.has_value() ? jni::make_jstring(value.artist.value()) : nullptr,
         value.album.has_value() ? jni::make_jstring(value.album.value()) : nullptr,
+        value.url.has_value() ? jni::make_jstring(value.url.value()) : nullptr,
         value.artworkUrl.has_value() ? jni::make_jstring(value.artworkUrl.value()) : nullptr
       );
     }

package/nitrogen/generated/android/kotlin/com/margelo/nitro/nitroplayer/Func_void_TrackItem.kt

@@ -0,0 +1,80 @@
+///
+/// Func_void_TrackItem.kt
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+package com.margelo.nitro.nitroplayer
+
+import androidx.annotation.Keep
+import com.facebook.jni.HybridData
+import com.facebook.proguard.annotations.DoNotStrip
+import dalvik.annotation.optimization.FastNative
+
+
+/**
+ * Represents the JavaScript callback `(track: struct) => void`.
+ * This can be either implemented in C++ (in which case it might be a callback coming from JS),
+ * or in Kotlin/Java (in which case it is a native callback).
+ */
+@DoNotStrip
+@Keep
+@Suppress("ClassName", "RedundantUnitReturnType")
+fun interface Func_void_TrackItem: (TrackItem) -> Unit {
+  /**
+   * Call the given JS callback.
+   * @throws Throwable if the JS function itself throws an error, or if the JS function/runtime has already been deleted.
+   */
+  @DoNotStrip
+  @Keep
+  override fun invoke(track: TrackItem): Unit
+}
+
+/**
+ * Represents the JavaScript callback `(track: struct) => void`.
+ * This is implemented in C++, via a `std::function<...>`.
+ * The callback might be coming from JS.
+ */
+@DoNotStrip
+@Keep
+@Suppress(
+  "KotlinJniMissingFunction", "unused",
+  "RedundantSuppression", "RedundantUnitReturnType", "FunctionName",
+  "ConvertSecondaryConstructorToPrimary", "ClassName", "LocalVariableName",
+)
+class Func_void_TrackItem_cxx: Func_void_TrackItem {
+  @DoNotStrip
+  @Keep
+  private val mHybridData: HybridData
+
+  @DoNotStrip
+  @Keep
+  private constructor(hybridData: HybridData) {
+    mHybridData = hybridData
+  }
+
+  @DoNotStrip
+  @Keep
+  override fun invoke(track: TrackItem): Unit
+    = invoke_cxx(track)
+
+  @FastNative
+  private external fun invoke_cxx(track: TrackItem): Unit
+}
+
+/**
+ * Represents the JavaScript callback `(track: struct) => void`.
+ * This is implemented in Java/Kotlin, via a `(TrackItem) -> Unit`.
+ * The callback is always coming from native.
+ */
+@DoNotStrip
+@Keep
+@Suppress("ClassName", "RedundantUnitReturnType", "unused")
+class Func_void_TrackItem_java(private val function: (TrackItem) -> Unit): Func_void_TrackItem {
+  @DoNotStrip
+  @Keep
+  override fun invoke(track: TrackItem): Unit {
+    return this.function(track)
+  }
+}

package/nitrogen/generated/android/kotlin/com/margelo/nitro/nitroplayer/HybridTrackPlayerSpec.kt

@@ -130,6 +130,15 @@ abstract class HybridTrackPlayerSpec: HybridObject() {
     return __result
   }
   
+  abstract fun appStartedWithNotification(callback: (track: TrackItem) -> Unit): Unit
+  
+  @DoNotStrip
+  @Keep
+  private fun appStartedWithNotification_cxx(callback: Func_void_TrackItem): Unit {
+    val __result = appStartedWithNotification(callback)
+    return __result
+  }
+  
   abstract fun onAndroidAutoConnectionChange(callback: (connected: Boolean) -> Unit): Unit
   
   @DoNotStrip

package/nitrogen/generated/android/kotlin/com/margelo/nitro/nitroplayer/TimedMetadata.kt

@@ -28,6 +28,9 @@ data class TimedMetadata(
   val album: String?,
   @DoNotStrip
   @Keep
+  val url: String?,
+  @DoNotStrip
+  @Keep
   val artworkUrl: String?
 ) {
   /* primary constructor */
@@ -40,8 +43,8 @@ data class TimedMetadata(
     @Keep
     @Suppress("unused")
     @JvmStatic
-    private fun fromCpp(title: String?, artist: String?, album: String?, artworkUrl: String?): TimedMetadata {
-      return TimedMetadata(title, artist, album, artworkUrl)
+    private fun fromCpp(title: String?, artist: String?, album: String?, url: String?, artworkUrl: String?): TimedMetadata {
+      return TimedMetadata(title, artist, album, url, artworkUrl)
     }
   }
 }

package/nitrogen/generated/ios/NitroPlayer-Swift-Cxx-Bridge.cpp

@@ -323,6 +323,14 @@ namespace margelo::nitro::nitroplayer::bridge::swift {
     };
   }
   
+  // pragma MARK: std::function<void(const TrackItem& /* track */)>
+  Func_void_TrackItem create_Func_void_TrackItem(void* NON_NULL swiftClosureWrapper) noexcept {
+    auto swiftClosure = NitroPlayer::Func_void_TrackItem::fromUnsafe(swiftClosureWrapper);
+    return [swiftClosure = std::move(swiftClosure)](const TrackItem& track) mutable -> void {
+      swiftClosure.call(track);
+    };
+  }
+  
   // pragma MARK: std::function<void(const std::vector<TrackItem>& /* tracks */, double /* lookahead */)>
   Func_void_std__vector_TrackItem__double create_Func_void_std__vector_TrackItem__double(void* NON_NULL swiftClosureWrapper) noexcept {
     auto swiftClosure = NitroPlayer::Func_void_std__vector_TrackItem__double::fromUnsafe(swiftClosureWrapper);

package/nitrogen/generated/ios/NitroPlayer-Swift-Cxx-Bridge.hpp

@@ -1752,6 +1752,28 @@ namespace margelo::nitro::nitroplayer::bridge::swift {
     return Func_void_TimedMetadata_Wrapper(std::move(value));
   }
   
+  // pragma MARK: std::function<void(const TrackItem& /* track */)>
+  /**
+   * Specialized version of `std::function<void(const TrackItem&)>`.
+   */
+  using Func_void_TrackItem = std::function<void(const TrackItem& /* track */)>;
+  /**
+   * Wrapper class for a `std::function<void(const TrackItem& / * track * /)>`, this can be used from Swift.
+   */
+  class Func_void_TrackItem_Wrapper final {
+  public:
+    explicit Func_void_TrackItem_Wrapper(std::function<void(const TrackItem& /* track */)>&& func): _function(std::make_unique<std::function<void(const TrackItem& /* track */)>>(std::move(func))) {}
+    inline void call(TrackItem track) const noexcept {
+      _function->operator()(track);
+    }
+  private:
+    std::unique_ptr<std::function<void(const TrackItem& /* track */)>> _function;
+  } SWIFT_NONCOPYABLE;
+  Func_void_TrackItem create_Func_void_TrackItem(void* NON_NULL swiftClosureWrapper) noexcept;
+  inline Func_void_TrackItem_Wrapper wrap_Func_void_TrackItem(Func_void_TrackItem value) noexcept {
+    return Func_void_TrackItem_Wrapper(std::move(value));
+  }
+  
   // pragma MARK: std::function<void(const std::vector<TrackItem>& /* tracks */, double /* lookahead */)>
   /**
    * Specialized version of `std::function<void(const std::vector<TrackItem>&, double)>`.

package/nitrogen/generated/ios/c++/HybridTrackPlayerSpecSwift.hpp

@@ -238,6 +238,12 @@ namespace margelo::nitro::nitroplayer {
         std::rethrow_exception(__result.error());
       }
     }
+    inline void appStartedWithNotification(const std::function<void(const TrackItem& /* track */)>& callback) override {
+      auto __result = _swiftPart.appStartedWithNotification(callback);
+      if (__result.hasError()) [[unlikely]] {
+        std::rethrow_exception(__result.error());
+      }
+    }
     inline void onAndroidAutoConnectionChange(const std::function<void(bool /* connected */)>& callback) override {
       auto __result = _swiftPart.onAndroidAutoConnectionChange(callback);
       if (__result.hasError()) [[unlikely]] {

package/nitrogen/generated/ios/swift/Func_void_TrackItem.swift

@@ -0,0 +1,46 @@
+///
+/// Func_void_TrackItem.swift
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+import NitroModules
+
+/**
+ * Wraps a Swift `(_ track: TrackItem) -> Void` as a class.
+ * This class can be used from C++, e.g. to wrap the Swift closure as a `std::function`.
+ */
+public final class Func_void_TrackItem {
+  public typealias bridge = margelo.nitro.nitroplayer.bridge.swift
+
+  private let closure: (_ track: TrackItem) -> Void
+
+  public init(_ closure: @escaping (_ track: TrackItem) -> Void) {
+    self.closure = closure
+  }
+
+  @inline(__always)
+  public func call(track: TrackItem) -> Void {
+    self.closure(track)
+  }
+
+  /**
+   * Casts this instance to a retained unsafe raw pointer.
+   * This acquires one additional strong reference on the object!
+   */
+  @inline(__always)
+  public func toUnsafe() -> UnsafeMutableRawPointer {
+    return Unmanaged.passRetained(self).toOpaque()
+  }
+
+  /**
+   * Casts an unsafe pointer to a `Func_void_TrackItem`.
+   * The pointer has to be a retained opaque `Unmanaged<Func_void_TrackItem>`.
+   * This removes one strong reference from the object!
+   */
+  @inline(__always)
+  public static func fromUnsafe(_ pointer: UnsafeMutableRawPointer) -> Func_void_TrackItem {
+    return Unmanaged<Func_void_TrackItem>.fromOpaque(pointer).takeRetainedValue()
+  }
+}

package/nitrogen/generated/ios/swift/HybridTrackPlayerSpec.swift

@@ -32,6 +32,7 @@ public protocol HybridTrackPlayerSpec_protocol: HybridObject {
   func onSeek(callback: @escaping (_ position: Double, _ totalDuration: Double) -> Void) throws -> Void
   func onPlaybackProgressChange(callback: @escaping (_ position: Double, _ totalDuration: Double, _ isManuallySeeked: Bool?) -> Void) throws -> Void
   func onTimedMetadata(callback: @escaping (_ metadata: TimedMetadata) -> Void) throws -> Void
+  func appStartedWithNotification(callback: @escaping (_ track: TrackItem) -> Void) throws -> Void
   func onAndroidAutoConnectionChange(callback: @escaping (_ connected: Bool) -> Void) throws -> Void
   func isAndroidAutoConnected() throws -> Bool
   func setVolume(volume: Double) throws -> Promise<Void>

package/nitrogen/generated/ios/swift/HybridTrackPlayerSpec_cxx.swift

@@ -494,6 +494,22 @@ open class HybridTrackPlayerSpec_cxx {
     }
   }
   
+  @inline(__always)
+  public final func appStartedWithNotification(callback: bridge.Func_void_TrackItem) -> bridge.Result_void_ {
+    do {
+      try self.__implementation.appStartedWithNotification(callback: { () -> (TrackItem) -> Void in
+        let __wrappedFunction = bridge.wrap_Func_void_TrackItem(callback)
+        return { (__track: TrackItem) -> Void in
+          __wrappedFunction.call(__track)
+        }
+      }())
+      return bridge.create_Result_void_()
+    } catch (let __error) {
+      let __exceptionPtr = __error.toCpp()
+      return bridge.create_Result_void_(__exceptionPtr)
+    }
+  }
+  
   @inline(__always)
   public final func onAndroidAutoConnectionChange(callback: bridge.Func_void_bool) -> bridge.Result_void_ {
     do {

package/nitrogen/generated/ios/swift/TimedMetadata.swift

@@ -18,7 +18,7 @@ public extension TimedMetadata {
   /**
    * Create a new instance of `TimedMetadata`.
    */
-  init(title: String?, artist: String?, album: String?, artworkUrl: String?) {
+  init(title: String?, artist: String?, album: String?, url: String?, artworkUrl: String?) {
     self.init({ () -> bridge.std__optional_std__string_ in
       if let __unwrappedValue = title {
         return bridge.create_std__optional_std__string_(std.string(__unwrappedValue))
@@ -37,6 +37,12 @@ public extension TimedMetadata {
       } else {
         return .init()
       }
+    }(), { () -> bridge.std__optional_std__string_ in
+      if let __unwrappedValue = url {
+        return bridge.create_std__optional_std__string_(std.string(__unwrappedValue))
+      } else {
+        return .init()
+      }
     }(), { () -> bridge.std__optional_std__string_ in
       if let __unwrappedValue = artworkUrl {
         return bridge.create_std__optional_std__string_(std.string(__unwrappedValue))
@@ -82,6 +88,18 @@ public extension TimedMetadata {
     }()
   }
   
+  @inline(__always)
+  var url: String? {
+    return { () -> String? in
+      if bridge.has_value_std__optional_std__string_(self.__url) {
+        let __unwrapped = bridge.get_std__optional_std__string_(self.__url)
+        return String(__unwrapped)
+      } else {
+        return nil
+      }
+    }()
+  }
+  
   @inline(__always)
   var artworkUrl: String? {
     return { () -> String? in

package/nitrogen/generated/shared/c++/HybridTrackPlayerSpec.cpp

@@ -33,6 +33,7 @@ namespace margelo::nitro::nitroplayer {
       prototype.registerHybridMethod("onSeek", &HybridTrackPlayerSpec::onSeek);
       prototype.registerHybridMethod("onPlaybackProgressChange", &HybridTrackPlayerSpec::onPlaybackProgressChange);
       prototype.registerHybridMethod("onTimedMetadata", &HybridTrackPlayerSpec::onTimedMetadata);
+      prototype.registerHybridMethod("appStartedWithNotification", &HybridTrackPlayerSpec::appStartedWithNotification);
       prototype.registerHybridMethod("onAndroidAutoConnectionChange", &HybridTrackPlayerSpec::onAndroidAutoConnectionChange);
       prototype.registerHybridMethod("isAndroidAutoConnected", &HybridTrackPlayerSpec::isAndroidAutoConnected);
       prototype.registerHybridMethod("setVolume", &HybridTrackPlayerSpec::setVolume);

package/nitrogen/generated/shared/c++/HybridTrackPlayerSpec.hpp

@@ -91,6 +91,7 @@ namespace margelo::nitro::nitroplayer {
       virtual void onSeek(const std::function<void(double /* position */, double /* totalDuration */)>& callback) = 0;
       virtual void onPlaybackProgressChange(const std::function<void(double /* position */, double /* totalDuration */, std::optional<bool> /* isManuallySeeked */)>& callback) = 0;
       virtual void onTimedMetadata(const std::function<void(const TimedMetadata& /* metadata */)>& callback) = 0;
+      virtual void appStartedWithNotification(const std::function<void(const TrackItem& /* track */)>& callback) = 0;
       virtual void onAndroidAutoConnectionChange(const std::function<void(bool /* connected */)>& callback) = 0;
       virtual bool isAndroidAutoConnected() = 0;
       virtual std::shared_ptr<Promise<void>> setVolume(double volume) = 0;

package/nitrogen/generated/shared/c++/TimedMetadata.hpp

@@ -43,11 +43,12 @@ namespace margelo::nitro::nitroplayer {
     std::optional<std::string> title     SWIFT_PRIVATE;
     std::optional<std::string> artist     SWIFT_PRIVATE;
     std::optional<std::string> album     SWIFT_PRIVATE;
+    std::optional<std::string> url     SWIFT_PRIVATE;
     std::optional<std::string> artworkUrl     SWIFT_PRIVATE;
 
   public:
     TimedMetadata() = default;
-    explicit TimedMetadata(std::optional<std::string> title, std::optional<std::string> artist, std::optional<std::string> album, std::optional<std::string> artworkUrl): title(title), artist(artist), album(album), artworkUrl(artworkUrl) {}
+    explicit TimedMetadata(std::optional<std::string> title, std::optional<std::string> artist, std::optional<std::string> album, std::optional<std::string> url, std::optional<std::string> artworkUrl): title(title), artist(artist), album(album), url(url), artworkUrl(artworkUrl) {}
 
   public:
     friend bool operator==(const TimedMetadata& lhs, const TimedMetadata& rhs) = default;
@@ -66,6 +67,7 @@ namespace margelo::nitro {
         JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "title"))),
         JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "artist"))),
         JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "album"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "url"))),
         JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "artworkUrl")))
       );
     }
@@ -74,6 +76,7 @@ namespace margelo::nitro {
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "title"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.title));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "artist"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.artist));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "album"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.album));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "url"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.url));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "artworkUrl"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.artworkUrl));
       return obj;
     }
@@ -88,6 +91,7 @@ namespace margelo::nitro {
       if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "title")))) return false;
       if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "artist")))) return false;
       if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "album")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "url")))) return false;
       if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "artworkUrl")))) return false;
       return true;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-player",
-  "version": "1.6.0-alpha.0",
+  "version": "1.6.0",
   "description": "A powerful audio player library for React Native with playlist management, playback controls, and support for Android Auto and CarPlay",
   "main": "lib/index",
   "module": "lib/index",

package/src/specs/TrackPlayer.nitro.ts

@@ -102,6 +102,11 @@ export interface TrackPlayer extends HybridObject<{
    * updates and ID3 frames emitted while a live stream plays.
    */
   onTimedMetadata(callback: (metadata: TimedMetadata) => void): void
+  /**
+   * Fires when the app was opened by tapping the playback notification,
+   * with the track that was playing at tap time. Android only — no-op on iOS.
+   */
+  appStartedWithNotification(callback: (track: TrackItem) => void): void
   onAndroidAutoConnectionChange(callback: (connected: boolean) => void): void
   isAndroidAutoConnected(): boolean
   setVolume(volume: number): Promise<void>

package/src/types/PlayerQueue.ts

@@ -43,8 +43,16 @@ export interface PlayerState {
 /** In-stream metadata emitted while a stream plays (ICY/Shoutcast StreamTitle, ID3 frames) */
 export interface TimedMetadata {
   title?: string
+  /** Split out of `title` when the stream sends only `"Artist - Title"` */
   artist?: string
   album?: string
+  /**
+   * ICY `StreamUrl` / ID3 webpage frame. Radio providers commonly put the
+   * current track's artwork URL here (Live365, StreamGuys), but some send a
+   * station or artist page instead — check the value before treating it as art.
+   */
+  url?: string
+  /** Artwork URL the stream tagged as artwork, when it sends one explicitly */
   artworkUrl?: string
 }