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

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

@@ -186,6 +186,11 @@ class HybridTrackPlayer : HybridTrackPlayerSpec() {
         listenerIds += "onTracksNeedUpdate" to id
     }
 
+    override fun onTimedMetadata(callback: (metadata: TimedMetadata) -> Unit) {
+        val id = core.addOnTimedMetadataListener(callback)
+        listenerIds += "onTimedMetadata" to id
+    }
+
     override fun onTemporaryQueueChange(callback: (playNextQueue: Array<TrackItem>, upNextQueue: Array<TrackItem>) -> Unit) {
         val id =
             core.addOnTemporaryQueueChangeListener { pn, un ->
@@ -207,6 +212,7 @@ class HybridTrackPlayer : HybridTrackPlayerSpec() {
                 "onAndroidAutoConnectionChange" -> core.removeOnAndroidAutoConnectionListener(id)
                 "onTracksNeedUpdate" -> core.removeOnTracksNeedUpdateListener(id)
                 "onTemporaryQueueChange" -> core.removeOnTemporaryQueueChangeListener(id)
+                "onTimedMetadata" -> core.removeOnTimedMetadataListener(id)
             }
         }
         listenerIds.clear()

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

@@ -11,6 +11,7 @@ import android.os.IBinder
 import android.os.Looper
 import com.margelo.nitro.nitroplayer.Reason
 import com.margelo.nitro.nitroplayer.RepeatMode
+import com.margelo.nitro.nitroplayer.TimedMetadata
 import com.margelo.nitro.nitroplayer.TrackItem
 import com.margelo.nitro.nitroplayer.TrackPlayerState
 import com.margelo.nitro.nitroplayer.connection.AndroidAutoConnectionDetector
@@ -90,6 +91,8 @@ class TrackPlayerCore private constructor(
         ListenerRegistry<(List<TrackItem>, List<TrackItem>) -> Unit>()
     internal val onAndroidAutoConnectionListeners =
         ListenerRegistry<(Boolean) -> Unit>()
+    internal val onTimedMetadataListeners =
+        ListenerRegistry<(TimedMetadata) -> Unit>()
     internal val onCastStateChangeListeners =
         ListenerRegistry<(com.margelo.nitro.nitroplayer.CastState, String?) -> Unit>()
 
@@ -376,6 +379,10 @@ class TrackPlayerCore private constructor(
 
     fun removeOnTemporaryQueueChangeListener(id: Long): Boolean = onTemporaryQueueChangeListeners.remove(id)
 
+    fun addOnTimedMetadataListener(cb: (TimedMetadata) -> Unit): Long = onTimedMetadataListeners.add(cb)
+
+    fun removeOnTimedMetadataListener(id: Long): Boolean = onTimedMetadataListeners.remove(id)
+
     fun addOnAndroidAutoConnectionListener(cb: (Boolean) -> Unit): Long = onAndroidAutoConnectionListeners.add(cb)
 
     fun removeOnAndroidAutoConnectionListener(id: Long): Boolean = onAndroidAutoConnectionListeners.remove(id)

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

@@ -3,9 +3,13 @@
 package com.margelo.nitro.nitroplayer.core
 
 import androidx.media3.common.MediaItem
+import androidx.media3.common.MediaMetadata
+import androidx.media3.common.Metadata
 import androidx.media3.common.Player
+import androidx.media3.common.util.UnstableApi
 import com.margelo.nitro.nitroplayer.Reason
 import com.margelo.nitro.nitroplayer.RepeatMode
+import com.margelo.nitro.nitroplayer.TimedMetadata
 import com.margelo.nitro.nitroplayer.equalizer.EqualizerCore
 import com.margelo.nitro.nitroplayer.media.NitroPlayerMediaBrowserService
 
@@ -82,6 +86,22 @@ internal class TrackPlayerEventListener(
         }
     }
 
+    /** In-stream metadata (ICY StreamTitle, ID3 frames) arriving mid-playback. */
+    @UnstableApi
+    override fun onMetadata(metadata: Metadata) {
+        val builder = MediaMetadata.Builder()
+        for (i in 0 until metadata.length()) {
+            metadata.get(i).populateMediaMetadata(builder)
+        }
+        val merged = builder.build()
+        val title = merged.title?.toString()
+        val artist = merged.artist?.toString()
+        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))
+    }
+
     override fun onTimelineChanged(
         timeline: androidx.media3.common.Timeline,
         reason: Int,

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

@@ -1,6 +1,7 @@
 package com.margelo.nitro.nitroplayer.core
 
 import com.margelo.nitro.nitroplayer.Reason
+import com.margelo.nitro.nitroplayer.TimedMetadata
 import com.margelo.nitro.nitroplayer.TrackItem
 import com.margelo.nitro.nitroplayer.TrackPlayerState
 
@@ -45,6 +46,10 @@ internal fun TrackPlayerCore.notifyTracksNeedUpdate(
     onTracksNeedUpdateListeners.forEach { it(tracks, lookahead) }
 }
 
+internal fun TrackPlayerCore.notifyTimedMetadata(metadata: TimedMetadata) {
+    onTimedMetadataListeners.forEach { it(metadata) }
+}
+
 internal fun TrackPlayerCore.notifyTemporaryQueueChange() {
     val pn = playNextStack.toList()
     val un = upNextQueue.toList()

package/ios/HybridTrackPlayer.swift

@@ -219,6 +219,11 @@ final class HybridTrackPlayer: HybridTrackPlayerSpec {
     listenerIds.append(("onTracksNeedUpdate", id))
   }
 
+  func onTimedMetadata(callback: @escaping (_ metadata: TimedMetadata) -> Void) throws {
+    let id = core.addOnTimedMetadataListener(callback)
+    listenerIds.append(("onTimedMetadata", id))
+  }
+
   func onTemporaryQueueChange(callback: @escaping (_ playNextQueue: [TrackItem], _ upNextQueue: [TrackItem]) -> Void) throws {
     let id = core.addOnTemporaryQueueChangeListener(callback)
     listenerIds.append(("onTemporaryQueueChange", id))
@@ -235,6 +240,7 @@ final class HybridTrackPlayer: HybridTrackPlayerSpec {
       case "onPlaybackProgressChange":_ = core.removeOnProgressListener(id: id)
       case "onTracksNeedUpdate":      _ = core.removeOnTracksNeedUpdateListener(id: id)
       case "onTemporaryQueueChange":  _ = core.removeOnTemporaryQueueChangeListener(id: id)
+      case "onTimedMetadata":         _ = core.removeOnTimedMetadataListener(id: id)
       default: break
       }
     }

package/ios/core/TrackPlayerCore.swift

@@ -59,6 +59,10 @@ class TrackPlayerCore: NSObject {
   internal var boundaryTimeObserver: Any?
   internal var currentItemObservers: [NSKeyValueObservation] = []
 
+  // In-stream (timed) metadata output, attached to the current item only.
+  internal var metadataOutput: AVPlayerItemMetadataOutput?
+  internal weak var metadataOutputItem: AVPlayerItem?
+
   // Gapless playback
   internal var preloadedAssets: [String: AVURLAsset] = [:]
   internal let preloadQueue = DispatchQueue(label: "com.nitroplayer.preload", qos: .utility)
@@ -110,6 +114,7 @@ class TrackPlayerCore: NSObject {
   internal let onProgressListeners            = ListenerRegistry<(Double, Double, Bool?) -> Void>()
   internal let onTracksNeedUpdateListeners    = ListenerRegistry<([TrackItem], Int) -> Void>()
   internal let onTemporaryQueueChangeListeners = ListenerRegistry<([TrackItem], [TrackItem]) -> Void>()
+  internal let onTimedMetadataListeners       = ListenerRegistry<(TimedMetadata) -> Void>()
   internal let onCastStateChangeListeners     = ListenerRegistry<(CastState, String?) -> Void>()
 
   // MARK: - Google Cast
@@ -216,6 +221,13 @@ class TrackPlayerCore: NSObject {
     onTemporaryQueueChangeListeners.remove(id: id)
   }
 
+  @discardableResult func addOnTimedMetadataListener(_ cb: @escaping (TimedMetadata) -> Void) -> Int64 {
+    onTimedMetadataListeners.add(cb)
+  }
+  @discardableResult func removeOnTimedMetadataListener(id: Int64) -> Bool {
+    onTimedMetadataListeners.remove(id: id)
+  }
+
   @discardableResult func addOnCastStateChangeListener(_ cb: @escaping (CastState, String?) -> Void) -> Int64 {
     onCastStateChangeListeners.add(cb)
   }
@@ -237,6 +249,7 @@ class TrackPlayerCore: NSObject {
         p.removeTimeObserver(obs)
       }
       self.currentItemObservers.removeAll()
+      self.detachMetadataOutput()
       if let p = self.player {
         p.removeObserver(self, forKeyPath: "status")
         p.removeObserver(self, forKeyPath: "rate")

package/ios/core/TrackPlayerListener.swift

@@ -285,6 +285,7 @@ extension TrackPlayerCore {
 
     guard let player, let currentItem = player.currentItem else {
       NitroPlayerLogger.log("TrackPlayerCore", "⚠️ Current item changed to nil")
+      detachMetadataOutput()
       // Queue exhausted — handle PLAYLIST repeat
       if currentRepeatMode == .playlist && !currentTracks.isEmpty, let player = self.player {
         NitroPlayerLogger.log("TrackPlayerCore", "🔁 PLAYLIST repeat — rebuilding original queue and restarting")
@@ -414,9 +415,33 @@ extension TrackPlayerCore {
     cleanupPreloadedAssets(keepingFrom: currentTrackIndex)
   }
 
+  /// Attaches an `AVPlayerItemMetadataOutput` to the current item so ICY/ID3
+  /// metadata emitted mid-stream reaches JS. Detaches from the previous item first —
+  /// an output may only be attached to one item at a time.
+  func attachMetadataOutput(to item: AVPlayerItem) {
+    detachMetadataOutput()
+    let output = AVPlayerItemMetadataOutput(identifiers: nil)
+    output.setDelegate(self, queue: playerQueue)
+    item.add(output)
+    metadataOutput = output
+    metadataOutputItem = item
+  }
+
+  /// Clears the metadata output so a detached one can no longer pass the identity
+  /// check in the delegate and emit metadata for an item that is no longer playing.
+  func detachMetadataOutput() {
+    if let output = metadataOutput, let item = metadataOutputItem {
+      item.remove(output)
+    }
+    metadataOutput = nil
+    metadataOutputItem = nil
+  }
+
   func setupCurrentItemObservers(item: AVPlayerItem) {
     NitroPlayerLogger.log("TrackPlayerCore", "📱 Setting up item observers")
 
+    attachMetadataOutput(to: item)
+
     let statusObserver = item.observe(\.status, options: [.new]) { [weak self] item, _ in
       self?.playerQueue.async {
         if item.status == .readyToPlay {
@@ -481,6 +506,31 @@ extension TrackPlayerCore {
     currentItemObservers.append(bufferKeepUpObserver)
   }
 
+  func handleTimedMetadataGroups(_ groups: [AVTimedMetadataGroup]) {
+    var title: String?
+    var artist: String?
+    var album: String?
+
+    for group in groups {
+      for item in group.items {
+        guard let value = item.stringValue, !value.isEmpty else { continue }
+        switch item.commonKey {
+        case .some(.commonKeyTitle): title = value
+        case .some(.commonKeyArtist): artist = value
+        case .some(.commonKeyAlbumName): album = value
+        default:
+          // ICY/Shoutcast streams carry no common keys — match on the identifier
+          if item.identifier == .icyMetadataStreamTitle { title = value }
+        }
+      }
+    }
+
+    guard title != nil || artist != nil || album != 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))
+  }
+
   func emitStateChange(reason: Reason? = nil) {
     guard let player else { return }
     let state: TrackPlayerState
@@ -501,3 +551,17 @@ extension TrackPlayerCore {
     notifyPlaybackStateChange(state, reason)
   }
 }
+
+extension TrackPlayerCore: AVPlayerItemMetadataOutputPushDelegate {
+  // Delivered on playerQueue (set in attachMetadataOutput)
+  func metadataOutput(
+    _ output: AVPlayerItemMetadataOutput,
+    didOutputTimedMetadataGroups groups: [AVTimedMetadataGroup],
+    from track: AVPlayerItemTrack?
+  ) {
+    // A detached output can still flush metadata it had already buffered — ignore it,
+    // it belongs to an item that is no longer current.
+    guard output === metadataOutput else { return }
+    handleTimedMetadataGroups(groups)
+  }
+}

package/ios/core/TrackPlayerNotify.swift

@@ -46,6 +46,10 @@ extension TrackPlayerCore {
     onTracksNeedUpdateListeners.forEach { $0(tracks, lookahead) }
   }
 
+  func notifyTimedMetadata(_ metadata: TimedMetadata) {
+    onTimedMetadataListeners.forEach { $0(metadata) }
+  }
+
   func notifyTemporaryQueueChange() {
     let pn = playNextStack
     let un = upNextQueue

package/lib/hooks/callbackManager.d.ts

@@ -1,8 +1,9 @@
-import type { TrackItem, TrackPlayerState, Reason } from '../types/PlayerQueue';
+import type { TrackItem, TrackPlayerState, Reason, TimedMetadata } from '../types/PlayerQueue';
 type PlaybackStateCallback = (state: TrackPlayerState, reason?: Reason) => void;
 type TrackChangeCallback = (track: TrackItem, reason?: Reason) => void;
 type PlaybackProgressCallback = (position: number, totalDuration: number, isManuallySeeked?: boolean) => void;
 type SeekCallback = (position: number, totalDuration: number) => void;
+type TimedMetadataCallback = (metadata: TimedMetadata) => void;
 type TemporaryQueueCallback = (playNextQueue: TrackItem[], upNextQueue: TrackItem[]) => void;
 /**
  * Internal subscription manager that allows multiple hooks to subscribe
@@ -14,6 +15,7 @@ declare class CallbackSubscriptionManager {
     private trackChangeSubscribers;
     private playbackProgressSubscribers;
     private seekSubscribers;
+    private timedMetadataSubscribers;
     private temporaryQueueSubscribers;
     private playlistsChangedSubscribers;
     private isPlaylistsChangedRegistered;
@@ -21,6 +23,7 @@ declare class CallbackSubscriptionManager {
     private isTrackChangeRegistered;
     private isPlaybackProgressRegistered;
     private isSeekRegistered;
+    private isTimedMetadataRegistered;
     private isTemporaryQueueRegistered;
     /**
      * Subscribe to playback state changes
@@ -58,6 +61,12 @@ declare class CallbackSubscriptionManager {
     private ensurePlaylistsChangedRegistered;
     private ensureTemporaryQueueRegistered;
     private ensureSeekRegistered;
+    /**
+     * Subscribe to in-stream (timed) metadata events
+     * @returns Unsubscribe function
+     */
+    subscribeToTimedMetadata(callback: TimedMetadataCallback): () => void;
+    private ensureTimedMetadataRegistered;
 }
 export declare const callbackManager: CallbackSubscriptionManager;
 export {};

package/lib/hooks/callbackManager.js

@@ -9,6 +9,7 @@ class CallbackSubscriptionManager {
     trackChangeSubscribers = new Set();
     playbackProgressSubscribers = new Set();
     seekSubscribers = new Set();
+    timedMetadataSubscribers = new Set();
     temporaryQueueSubscribers = new Set();
     playlistsChangedSubscribers = new Set();
     isPlaylistsChangedRegistered = false;
@@ -16,6 +17,7 @@ class CallbackSubscriptionManager {
     isTrackChangeRegistered = false;
     isPlaybackProgressRegistered = false;
     isSeekRegistered = false;
+    isTimedMetadataRegistered = false;
     isTemporaryQueueRegistered = false;
     /**
      * Subscribe to playback state changes
@@ -203,6 +205,37 @@ class CallbackSubscriptionManager {
             console.error('[CallbackManager] Failed to register seek callback:', error);
         }
     }
+    /**
+     * Subscribe to in-stream (timed) metadata events
+     * @returns Unsubscribe function
+     */
+    subscribeToTimedMetadata(callback) {
+        this.timedMetadataSubscribers.add(callback);
+        this.ensureTimedMetadataRegistered();
+        return () => {
+            this.timedMetadataSubscribers.delete(callback);
+        };
+    }
+    ensureTimedMetadataRegistered() {
+        if (this.isTimedMetadataRegistered)
+            return;
+        try {
+            TrackPlayer.onTimedMetadata((metadata) => {
+                this.timedMetadataSubscribers.forEach((subscriber) => {
+                    try {
+                        subscriber(metadata);
+                    }
+                    catch (error) {
+                        console.error('[CallbackManager] Error in timed metadata subscriber:', error);
+                    }
+                });
+            });
+            this.isTimedMetadataRegistered = true;
+        }
+        catch (error) {
+            console.error('[CallbackManager] Failed to register timed metadata callback:', error);
+        }
+    }
 }
 // Export singleton instance
 export const callbackManager = new CallbackSubscriptionManager();

package/lib/hooks/index.d.ts

@@ -4,6 +4,7 @@ export { useOnPlaybackStateChange } from './useOnPlaybackStateChange';
 export type { PlaybackStateResult } from './useOnPlaybackStateChange';
 export { useOnSeek } from './useOnSeek';
 export { useOnPlaybackProgressChange } from './useOnPlaybackProgressChange';
+export { useTimedMetadata } from './useTimedMetadata';
 export { useAndroidAutoConnection } from './useAndroidAutoConnection';
 export { useAudioDevices } from './useAudioDevices';
 export { useNowPlaying } from './useNowPlaying';

package/lib/hooks/index.js

@@ -2,6 +2,7 @@ export { useOnChangeTrack } from './useOnChangeTrack';
 export { useOnPlaybackStateChange } from './useOnPlaybackStateChange';
 export { useOnSeek } from './useOnSeek';
 export { useOnPlaybackProgressChange } from './useOnPlaybackProgressChange';
+export { useTimedMetadata } from './useTimedMetadata';
 export { useAndroidAutoConnection } from './useAndroidAutoConnection';
 export { useAudioDevices } from './useAudioDevices';
 export { useNowPlaying } from './useNowPlaying';

package/lib/hooks/useTimedMetadata.d.ts

@@ -0,0 +1,16 @@
+import type { TimedMetadata } from '../types/PlayerQueue';
+/**
+ * Hook to subscribe to in-stream (timed) metadata — ICY/Shoutcast StreamTitle
+ * updates and ID3 frames emitted while a live stream plays.
+ *
+ * @returns The most recent metadata, or undefined until the first event arrives
+ *
+ * @example
+ * ```tsx
+ * function NowPlayingFromStream() {
+ *   const metadata = useTimedMetadata()
+ *   return <Text>{metadata?.title ?? 'Live'}</Text>
+ * }
+ * ```
+ */
+export declare function useTimedMetadata(): TimedMetadata | undefined;

package/lib/hooks/useTimedMetadata.js

@@ -0,0 +1,21 @@
+import { useEffect, useState } from 'react';
+import { callbackManager } from './callbackManager';
+/**
+ * Hook to subscribe to in-stream (timed) metadata — ICY/Shoutcast StreamTitle
+ * updates and ID3 frames emitted while a live stream plays.
+ *
+ * @returns The most recent metadata, or undefined until the first event arrives
+ *
+ * @example
+ * ```tsx
+ * function NowPlayingFromStream() {
+ *   const metadata = useTimedMetadata()
+ *   return <Text>{metadata?.title ?? 'Live'}</Text>
+ * }
+ * ```
+ */
+export function useTimedMetadata() {
+    const [metadata, setMetadata] = useState(undefined);
+    useEffect(() => callbackManager.subscribeToTimedMetadata(setMetadata), []);
+    return metadata;
+}

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

@@ -1,5 +1,5 @@
 import type { HybridObject } from 'react-native-nitro-modules';
-import type { QueueOperation, Reason, TrackItem, TrackPlayerState, PlayerState, PlayerConfig, Playlist } from '../types/PlayerQueue';
+import type { QueueOperation, Reason, TrackItem, TrackPlayerState, PlayerState, PlayerConfig, Playlist, TimedMetadata } from '../types/PlayerQueue';
 export interface PlayerQueue extends HybridObject<{
     android: 'kotlin';
     ios: 'swift';
@@ -41,6 +41,11 @@ export interface TrackPlayer extends HybridObject<{
     onPlaybackStateChange(callback: (state: TrackPlayerState, reason?: Reason) => void): void;
     onSeek(callback: (position: number, totalDuration: number) => void): void;
     onPlaybackProgressChange(callback: (position: number, totalDuration: number, isManuallySeeked?: boolean) => void): void;
+    /**
+     * Register callback for in-stream (timed) metadata — ICY/Shoutcast StreamTitle
+     * updates and ID3 frames emitted while a live stream plays.
+     */
+    onTimedMetadata(callback: (metadata: TimedMetadata) => void): void;
     onAndroidAutoConnectionChange(callback: (connected: boolean) => void): void;
     isAndroidAutoConnected(): boolean;
     setVolume(volume: number): Promise<void>;

package/lib/types/PlayerQueue.d.ts

@@ -29,6 +29,13 @@ export interface PlayerState {
     currentIndex: number;
     currentPlayingType: CurrentPlayingType;
 }
+/** In-stream metadata emitted while a stream plays (ICY/Shoutcast StreamTitle, ID3 frames) */
+export interface TimedMetadata {
+    title?: string;
+    artist?: string;
+    album?: string;
+    artworkUrl?: string;
+}
 export interface PlayerConfig {
     androidAutoEnabled?: boolean;
     carPlayEnabled?: boolean;

package/nitrogen/generated/android/NitroPlayerOnLoad.cpp

@@ -35,6 +35,7 @@
 #include "JFunc_void_TrackPlayerState_std__optional_Reason_.hpp"
 #include "JFunc_void_double_double.hpp"
 #include "JFunc_void_double_double_std__optional_bool_.hpp"
+#include "JFunc_void_TimedMetadata.hpp"
 #include "JFunc_void_std__vector_TrackItem__double.hpp"
 #include "JFunc_void_std__vector_TrackItem__std__vector_TrackItem_.hpp"
 #include <NitroModules/DefaultConstructableObject.hpp>
@@ -129,6 +130,7 @@ void registerAllNatives() {
   margelo::nitro::nitroplayer::JFunc_void_TrackPlayerState_std__optional_Reason__cxx::registerNatives();
   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_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_TimedMetadata.hpp

@@ -0,0 +1,79 @@
+///
+/// JFunc_void_TimedMetadata.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 "TimedMetadata.hpp"
+#include <functional>
+#include <NitroModules/JNICallable.hpp>
+#include "JTimedMetadata.hpp"
+#include <string>
+#include <optional>
+
+namespace margelo::nitro::nitroplayer {
+
+  using namespace facebook;
+
+  /**
+   * Represents the Java/Kotlin callback `(metadata: TimedMetadata) -> Unit`.
+   * This can be passed around between C++ and Java/Kotlin.
+   */
+  struct JFunc_void_TimedMetadata: public jni::JavaClass<JFunc_void_TimedMetadata> {
+  public:
+    static constexpr auto kJavaDescriptor = "Lcom/margelo/nitro/nitroplayer/Func_void_TimedMetadata;";
+
+  public:
+    /**
+     * Invokes the function this `JFunc_void_TimedMetadata` instance holds through JNI.
+     */
+    void invoke(const TimedMetadata& metadata) const {
+      static const auto method = javaClassStatic()->getMethod<void(jni::alias_ref<JTimedMetadata> /* metadata */)>("invoke");
+      method(self(), JTimedMetadata::fromCpp(metadata));
+    }
+  };
+
+  /**
+   * An implementation of Func_void_TimedMetadata that is backed by a C++ implementation (using `std::function<...>`)
+   */
+  class JFunc_void_TimedMetadata_cxx final: public jni::HybridClass<JFunc_void_TimedMetadata_cxx, JFunc_void_TimedMetadata> {
+  public:
+    static jni::local_ref<JFunc_void_TimedMetadata::javaobject> fromCpp(const std::function<void(const TimedMetadata& /* metadata */)>& func) {
+      return JFunc_void_TimedMetadata_cxx::newObjectCxxArgs(func);
+    }
+
+  public:
+    /**
+     * Invokes the C++ `std::function<...>` this `JFunc_void_TimedMetadata_cxx` instance holds.
+     */
+    void invoke_cxx(jni::alias_ref<JTimedMetadata> metadata) {
+      _func(metadata->toCpp());
+    }
+
+  public:
+    [[nodiscard]]
+    inline const std::function<void(const TimedMetadata& /* metadata */)>& getFunction() const {
+      return _func;
+    }
+
+  public:
+    static constexpr auto kJavaDescriptor = "Lcom/margelo/nitro/nitroplayer/Func_void_TimedMetadata_cxx;";
+    static void registerNatives() {
+      registerHybrid({makeNativeMethod("invoke_cxx", JFunc_void_TimedMetadata_cxx::invoke_cxx)});
+    }
+
+  private:
+    explicit JFunc_void_TimedMetadata_cxx(const std::function<void(const TimedMetadata& /* metadata */)>& func): _func(func) { }
+
+  private:
+    friend HybridBase;
+    std::function<void(const TimedMetadata& /* metadata */)> _func;
+  };
+
+} // namespace margelo::nitro::nitroplayer

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

@@ -21,6 +21,8 @@ namespace margelo::nitro::nitroplayer { enum class RepeatMode; }
 namespace margelo::nitro::nitroplayer { struct PlayerConfig; }
 // Forward declaration of `Reason` to properly resolve imports.
 namespace margelo::nitro::nitroplayer { enum class Reason; }
+// Forward declaration of `TimedMetadata` to properly resolve imports.
+namespace margelo::nitro::nitroplayer { struct TimedMetadata; }
 
 #include <NitroModules/Promise.hpp>
 #include <NitroModules/JPromise.hpp>
@@ -55,6 +57,9 @@ namespace margelo::nitro::nitroplayer { enum class Reason; }
 #include "JFunc_void_TrackPlayerState_std__optional_Reason_.hpp"
 #include "JFunc_void_double_double.hpp"
 #include "JFunc_void_double_double_std__optional_bool_.hpp"
+#include "TimedMetadata.hpp"
+#include "JFunc_void_TimedMetadata.hpp"
+#include "JTimedMetadata.hpp"
 #include "JFunc_void_bool.hpp"
 #include "JFunc_void_std__vector_TrackItem__double.hpp"
 #include "JFunc_void_std__vector_TrackItem__std__vector_TrackItem_.hpp"
@@ -320,6 +325,10 @@ namespace margelo::nitro::nitroplayer {
     static const auto method = _javaPart->javaClassStatic()->getMethod<void(jni::alias_ref<JFunc_void_double_double_std__optional_bool_::javaobject> /* callback */)>("onPlaybackProgressChange_cxx");
     method(_javaPart, JFunc_void_double_double_std__optional_bool__cxx::fromCpp(callback));
   }
+  void JHybridTrackPlayerSpec::onTimedMetadata(const std::function<void(const TimedMetadata& /* metadata */)>& callback) {
+    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::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

@@ -72,6 +72,7 @@ namespace margelo::nitro::nitroplayer {
     void onPlaybackStateChange(const std::function<void(TrackPlayerState /* state */, std::optional<Reason> /* reason */)>& callback) override;
     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 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

@@ -0,0 +1,70 @@
+///
+/// JTimedMetadata.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 "TimedMetadata.hpp"
+
+#include <optional>
+#include <string>
+
+namespace margelo::nitro::nitroplayer {
+
+  using namespace facebook;
+
+  /**
+   * The C++ JNI bridge between the C++ struct "TimedMetadata" and the the Kotlin data class "TimedMetadata".
+   */
+  struct JTimedMetadata final: public jni::JavaClass<JTimedMetadata> {
+  public:
+    static constexpr auto kJavaDescriptor = "Lcom/margelo/nitro/nitroplayer/TimedMetadata;";
+
+  public:
+    /**
+     * Convert this Java/Kotlin-based struct to the C++ struct TimedMetadata by copying all values to C++.
+     */
+    [[maybe_unused]]
+    [[nodiscard]]
+    TimedMetadata toCpp() const {
+      static const auto clazz = javaClassStatic();
+      static const auto fieldTitle = clazz->getField<jni::JString>("title");
+      jni::local_ref<jni::JString> title = this->getFieldValue(fieldTitle);
+      static const auto fieldArtist = clazz->getField<jni::JString>("artist");
+      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 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,
+        artworkUrl != nullptr ? std::make_optional(artworkUrl->toStdString()) : std::nullopt
+      );
+    }
+
+  public:
+    /**
+     * Create a Java/Kotlin-based struct by copying all values from the given C++ struct to Java.
+     */
+    [[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>);
+      static const auto clazz = javaClassStatic();
+      static const auto create = clazz->getStaticMethod<JSignature>("fromCpp");
+      return create(
+        clazz,
+        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.artworkUrl.has_value() ? jni::make_jstring(value.artworkUrl.value()) : nullptr
+      );
+    }
+  };
+
+} // namespace margelo::nitro::nitroplayer