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

package/src/hooks/callbackManager.ts

@@ -1,5 +1,10 @@
 import { PlayerQueue, TrackPlayer } from '../index'
-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
@@ -9,6 +14,7 @@ type PlaybackProgressCallback = (
   isManuallySeeked?: boolean
 ) => void
 type SeekCallback = (position: number, totalDuration: number) => void
+type TimedMetadataCallback = (metadata: TimedMetadata) => void
 type TemporaryQueueCallback = (
   playNextQueue: TrackItem[],
   upNextQueue: TrackItem[]
@@ -24,6 +30,7 @@ class CallbackSubscriptionManager {
   private trackChangeSubscribers = new Set<TrackChangeCallback>()
   private playbackProgressSubscribers = new Set<PlaybackProgressCallback>()
   private seekSubscribers = new Set<SeekCallback>()
+  private timedMetadataSubscribers = new Set<TimedMetadataCallback>()
   private temporaryQueueSubscribers = new Set<TemporaryQueueCallback>()
   private playlistsChangedSubscribers = new Set<() => void>()
   private isPlaylistsChangedRegistered = false
@@ -31,6 +38,7 @@ class CallbackSubscriptionManager {
   private isTrackChangeRegistered = false
   private isPlaybackProgressRegistered = false
   private isSeekRegistered = false
+  private isTimedMetadataRegistered = false
   private isTemporaryQueueRegistered = false
 
   /**
@@ -263,6 +271,44 @@ class CallbackSubscriptionManager {
       )
     }
   }
+
+  /**
+   * Subscribe to in-stream (timed) metadata events
+   * @returns Unsubscribe function
+   */
+  subscribeToTimedMetadata(callback: TimedMetadataCallback): () => void {
+    this.timedMetadataSubscribers.add(callback)
+    this.ensureTimedMetadataRegistered()
+
+    return () => {
+      this.timedMetadataSubscribers.delete(callback)
+    }
+  }
+
+  private ensureTimedMetadataRegistered(): void {
+    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

package/src/hooks/index.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/src/hooks/useTimedMetadata.ts

@@ -0,0 +1,25 @@
+import { useEffect, useState } from 'react'
+import { callbackManager } from './callbackManager'
+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 function useTimedMetadata(): TimedMetadata | undefined {
+  const [metadata, setMetadata] = useState<TimedMetadata | undefined>(undefined)
+
+  useEffect(() => callbackManager.subscribeToTimedMetadata(setMetadata), [])
+
+  return metadata
+}

package/src/specs/TrackPlayer.nitro.ts

@@ -7,6 +7,7 @@ import type {
   PlayerState,
   PlayerConfig,
   Playlist,
+  TimedMetadata,
 } from '../types/PlayerQueue'
 
 export interface PlayerQueue extends HybridObject<{
@@ -96,6 +97,11 @@ export interface TrackPlayer extends HybridObject<{
       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/src/types/PlayerQueue.ts

@@ -40,6 +40,22 @@ export interface PlayerState {
   currentPlayingType: CurrentPlayingType
 }
 
+/** 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 {
   androidAutoEnabled?: boolean
   carPlayEnabled?: boolean