@rntp/player 5.0.0 → 5.1.1

package/src/audio.ts

@@ -107,6 +107,9 @@ function normalizePlayerConfig(options: PlayerConfig) {
     handleAudioBecomingNoisy:
       options.handleAudioBecomingNoisy ??
       DEFAULT_PLAYER_CONFIG.handleAudioBecomingNoisy,
+    autoUpdateMetadataFromStream:
+      options.autoUpdateMetadataFromStream ??
+      DEFAULT_PLAYER_CONFIG.autoUpdateMetadataFromStream,
     ...(cache ? { cache } : {}),
     ...(options.progressSync ? { progressSync: options.progressSync } : {}),
     android,

package/src/events/MediaMetadataChanged.ts

@@ -0,0 +1,18 @@
+/**
+ * Copyright (c) Double Symmetry GmbH
+ * Commercial use requires a license. See https://rntp.dev/pricing
+ */
+
+/**
+ * Effective metadata for the active item ({@link getActiveMediaItem}, Now Playing).
+ * Use {@link MetadataReceivedEvent} for raw per-frame stream metadata instead.
+ *
+ * @since 5.1.0
+ */
+export interface MediaMetadataChangedEvent {
+  title?: string;
+  artist?: string;
+  albumTitle?: string;
+  artworkUrl?: string;
+  genre?: string;
+}

package/src/events/MetadataReceived.ts

@@ -3,6 +3,21 @@
  * Commercial use requires a license. See https://rntp.dev/pricing
  */
 
+/**
+ * Fired for every metadata frame the audio stream pushes — ICY blocks
+ * (Shoutcast/Icecast radio), ID3 tags, Vorbis comments, QuickTime metadata.
+ * The payload reflects *stream-derived* fields only; user-supplied fields on
+ * the queued MediaItem (e.g. a static `genre` or `albumTitle`) are not
+ * merged in here.
+ *
+ * For the effective merged view that `getActiveMediaItem` returns (and that
+ * the lock screen / system Now Playing info reflects), subscribe to
+ * {@link MediaMetadataChangedEvent} instead.
+ *
+ * Typical consumers: analytics / scrobbling, sanitization pipelines that
+ * filter the raw stream before calling {@link updateMetadata} themselves
+ * (use with `PlayerConfig.autoUpdateMetadataFromStream: false`).
+ */
 export interface MetadataReceivedEvent {
   title?: string;
   artist?: string;

package/src/events/index.ts

@@ -6,6 +6,7 @@
 import type { PlaybackStateChangedEvent } from './PlaybackStateChanged';
 import type { IsPlayingChangedEvent } from './IsPlayingChanged';
 import type { MediaItemTransitionEvent } from './MediaItemTransition';
+import type { MediaMetadataChangedEvent } from './MediaMetadataChanged';
 import type { MetadataReceivedEvent } from './MetadataReceived';
 import type {
   RemotePlayEvent,
@@ -26,6 +27,7 @@ export enum Event {
   PlaybackStateChanged = 'event.playback-state-changed',
   IsPlayingChanged = 'event.is-playing-changed',
   MediaItemTransition = 'event.media-item-transition',
+  MediaMetadataChanged = 'event.media-metadata-changed',
   MetadataReceived = 'event.metadata-received',
   PlaybackError = 'event.playback-error',
   PlaybackProgressUpdated = 'event.playback-progress-updated',
@@ -45,6 +47,7 @@ export type EventPayloadByEvent = {
   [Event.PlaybackStateChanged]: PlaybackStateChangedEvent;
   [Event.IsPlayingChanged]: IsPlayingChangedEvent;
   [Event.MediaItemTransition]: MediaItemTransitionEvent;
+  [Event.MediaMetadataChanged]: MediaMetadataChangedEvent;
   [Event.MetadataReceived]: MetadataReceivedEvent;
   [Event.PlaybackError]: PlaybackErrorEvent;
   [Event.PlaybackProgressUpdated]: PlaybackProgressUpdatedEvent;
@@ -75,6 +78,7 @@ export type BackgroundEvent =
 export * from './PlaybackStateChanged';
 export * from './IsPlayingChanged';
 export * from './MediaItemTransition';
+export * from './MediaMetadataChanged';
 export * from './MetadataReceived';
 export * from './RemoteControl';
 export * from './PlaybackError';

package/src/hooks/useActiveMediaItem.ts

@@ -9,8 +9,8 @@ import { Event } from '../events';
 import type { MediaItem } from '../interfaces';
 
 /**
- * Returns the currently active media item, updating on item transitions
- * and when stream metadata changes (e.g. ICY tags from live radio).
+ * Active media item; refreshes on {@link Event.MediaItemTransition} and
+ * {@link Event.MediaMetadataChanged} (after native merges stream metadata).
  */
 export function useActiveMediaItem(): MediaItem | null {
   const [item, setItem] = useState<MediaItem | null>(() =>
@@ -25,7 +25,7 @@ export function useActiveMediaItem(): MediaItem | null {
       }
     );
     const metadataSub = TrackPlayer.addEventListener(
-      Event.MetadataReceived,
+      Event.MediaMetadataChanged,
       () => {
         setItem(TrackPlayer.getActiveMediaItem());
       }

package/src/hooks/useProgress.ts

@@ -11,7 +11,7 @@ import type { Progress } from '../interfaces';
  * Returns the current playback progress, polling at the given interval.
  * @param updateInterval Polling interval in seconds (default: 1)
  */
-export function useProgress(updateInterval = 1): Progress {
+export function useProgress(updateInterval: number = 1): Progress {
   const [progress, setProgress] = useState<Progress>(() =>
     TrackPlayer.getProgress()
   );

package/src/interfaces/MediaItem.ts

@@ -47,4 +47,19 @@ export interface MediaItem {
    * receiver can identify the format — without it the track will be skipped.
    */
   mimeType?: string;
+  /**
+   * App-defined payload attached to this media item. Opaque to the player —
+   * stored verbatim and returned unchanged by {@link getActiveMediaItem},
+   * {@link getQueue}, and the {@link Event.MediaItemTransition} event.
+   *
+   * Use this for app-specific metadata that should travel with the item
+   * (e.g. recommendation source, ISRC, internal IDs) without polluting the
+   * typed fields.
+   *
+   * Must be JSON-serializable. Keep payloads small — large blobs are better
+   * kept in your own JS state, keyed by {@link mediaId}.
+   *
+   * @since 5.1.0
+   */
+  extras?: Record<string, unknown>;
 }

package/src/interfaces/PlayerConfig.ts

@@ -85,6 +85,7 @@ export const DEFAULT_PLAYER_CONFIG: Required<
 } = {
   contentType: 'music',
   handleAudioBecomingNoisy: true,
+  autoUpdateMetadataFromStream: true,
   android: DEFAULT_ANDROID_PLAYER_CONFIG,
 };
 
@@ -134,6 +135,14 @@ export interface PlayerConfig {
    * (e.g. headphones disconnected). Defaults to true.
    */
   handleAudioBecomingNoisy?: boolean;
+  /**
+   * When `true` (default), ICY/ID3 metadata updates the queued MediaItem and Now Playing.
+   * When `false`, only {@link Event.MetadataReceived} is emitted; call {@link updateMetadata} yourself.
+   *
+   * @default true
+   * @since 5.1.0
+   */
+  autoUpdateMetadataFromStream?: boolean;
   /**
    * Enable disk caching and preloading.
    *