react-native-nitro-player 1.7.0-alpha.3 → 1.7.0-alpha.5

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

@@ -0,0 +1,83 @@
+///
+/// ShufflePlaylistOptions.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/PropNameIDCache.hpp>)
+#include <NitroModules/PropNameIDCache.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+
+
+#include <optional>
+
+namespace margelo::nitro::nitroplayer {
+
+  /**
+   * A struct which can be represented as a JavaScript object (ShufflePlaylistOptions).
+   */
+  struct ShufflePlaylistOptions final {
+  public:
+    std::optional<bool> keepCurrentTrackFirst     SWIFT_PRIVATE;
+
+  public:
+    ShufflePlaylistOptions() = default;
+    explicit ShufflePlaylistOptions(std::optional<bool> keepCurrentTrackFirst): keepCurrentTrackFirst(keepCurrentTrackFirst) {}
+
+  public:
+    friend bool operator==(const ShufflePlaylistOptions& lhs, const ShufflePlaylistOptions& rhs) = default;
+  };
+
+} // namespace margelo::nitro::nitroplayer
+
+namespace margelo::nitro {
+
+  // C++ ShufflePlaylistOptions <> JS ShufflePlaylistOptions (object)
+  template <>
+  struct JSIConverter<margelo::nitro::nitroplayer::ShufflePlaylistOptions> final {
+    static inline margelo::nitro::nitroplayer::ShufflePlaylistOptions fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::nitroplayer::ShufflePlaylistOptions(
+        JSIConverter<std::optional<bool>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "keepCurrentTrackFirst")))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::nitroplayer::ShufflePlaylistOptions& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "keepCurrentTrackFirst"), JSIConverter<std::optional<bool>>::toJSI(runtime, arg.keepCurrentTrackFirst));
+      return obj;
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isObject()) {
+        return false;
+      }
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
+      }
+      if (!JSIConverter<std::optional<bool>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "keepCurrentTrackFirst")))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-player",
-  "version": "1.7.0-alpha.3",
+  "version": "1.7.0-alpha.5",
   "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/hooks/callbackManager.ts

@@ -37,6 +37,7 @@ class CallbackSubscriptionManager {
   private androidAutoConnectionSubscribers =
     new Set<AndroidAutoConnectionCallback>()
   private isPlaylistsChangedRegistered = false
+  private playlistsChangedFanOutScheduled = false
   private isAndroidAutoConnectionRegistered = false
   private isPlaybackStateRegistered = false
   private isTrackChangeRegistered = false
@@ -204,21 +205,35 @@ class CallbackSubscriptionManager {
     }
   }
 
+  // Task-level, not a microtask: native callbacks arrive as separate JS tasks.
+  private schedulePlaylistsChangedFanOut(): void {
+    if (this.playlistsChangedFanOutScheduled) return
+    this.playlistsChangedFanOutScheduled = true
+    setTimeout(() => {
+      this.playlistsChangedFanOutScheduled = false
+      this.playlistsChangedSubscribers.forEach((subscriber) => {
+        try {
+          subscriber()
+        } catch (error) {
+          console.error(
+            '[CallbackManager] Error in playlists changed subscriber:',
+            error
+          )
+        }
+      })
+    }, 0)
+  }
+
   private ensurePlaylistsChangedRegistered(): void {
     if (this.isPlaylistsChangedRegistered) return
 
     try {
       PlayerQueue.onPlaylistsChanged(() => {
-        this.playlistsChangedSubscribers.forEach((subscriber) => {
-          try {
-            subscriber()
-          } catch (error) {
-            console.error(
-              '[CallbackManager] Error in playlists changed subscriber:',
-              error
-            )
-          }
-        })
+        this.schedulePlaylistsChangedFanOut()
+      })
+      // Track-level mutations only fire the per-playlist event.
+      PlayerQueue.onPlaylistChanged(() => {
+        this.schedulePlaylistsChangedFanOut()
       })
       this.isPlaylistsChangedRegistered = true
     } catch (error) {

package/src/index.ts

@@ -1,7 +1,7 @@
 // TODO: Export all HybridObjects here for the user
 
 import { NitroModules } from 'react-native-nitro-modules'
-import { Platform } from 'react-native'
+import { AppRegistry, Platform } from 'react-native'
 import type {
   PlayerQueue as PlayerQueueType,
   TrackPlayer as TrackPlayerType,
@@ -13,6 +13,14 @@ import type { Cast as CastType } from './specs/Cast.nitro'
 import type { DownloadManager as DownloadManagerType } from './specs/DownloadManager.nitro'
 import type { Equalizer as EqualizerType } from './specs/Equalizer.nitro'
 
+// Native runs this while it needs JS without a resumed activity (car, screen off): it keeps JS timers ticking
+if (Platform.OS === 'android') {
+  AppRegistry.registerHeadlessTask(
+    'NitroPlayerKeepAlive',
+    () => () => new Promise<void>(() => {})
+  )
+}
+
 export const PlayerQueue =
   NitroModules.createHybridObject<PlayerQueueType>('PlayerQueue')
 export const TrackPlayer =

package/src/specs/AndroidAutoMediaLibrary.nitro.ts

@@ -20,4 +20,22 @@ export interface AndroidAutoMediaLibrary extends HybridObject<{
    * Falls back to showing all playlists
    */
   clearMediaLibrary(): Promise<void>
+
+  /** Android Auto opened a folder published with `children: []`; answer with {@link resolveRequest}. */
+  onLoadChildren(callback: (requestId: string, parentId: string) => void): void
+
+  /** A car search, or a voice request the loaded playlists cannot match; answer with {@link resolveRequest}. */
+  onSearch(callback: (requestId: string, query: string) => void): void
+
+  /** Answers {@link onLoadChildren} / {@link onSearch} with a JSON array of MediaItem. */
+  resolveRequest(requestId: string, itemsJson: string): void
+
+  /** Replaces the session buttons with a JSON array of SessionButton. */
+  setSessionButtons(buttonsJson: string): void
+
+  /** Called with the button's `action` when a session button is pressed. */
+  onSessionButtonPress(callback: (action: string) => void): void
+
+  /** A controller asked to play with nothing loaded (car auto-play, play on connect); load the last queue now. */
+  onPlaybackResumption(callback: () => void): void
 }

package/src/specs/TrackPlayer.nitro.ts

@@ -8,6 +8,7 @@ import type {
   PlayerConfig,
   Playlist,
   TimedMetadata,
+  ShufflePlaylistOptions,
 } from '../types/PlayerQueue'
 
 export interface PlayerQueue extends HybridObject<{
@@ -47,6 +48,16 @@ export interface PlayerQueue extends HybridObject<{
     trackId: string,
     newIndex: number
   ): Promise<void>
+  /** One native pass. Unknown ids are skipped; rejects only if the playlist does not exist. */
+  removeTracksFromPlaylist(
+    playlistId: string,
+    trackIds: string[]
+  ): Promise<void>
+  /** Fisher-Yates shuffle of the stored playlist, persisted. Never interrupts the playing item. */
+  shufflePlaylist(
+    playlistId: string,
+    options?: ShufflePlaylistOptions
+  ): Promise<void>
 
   // Playback control
   loadPlaylist(playlistId: string, index?: number): Promise<void>

package/src/types/AndroidAutoMediaLibrary.ts

@@ -38,6 +38,9 @@ export interface MediaItem {
 
   /** Layout type for folder items (overrides library default) */
   layoutType?: LayoutType
+
+  /** Group header; contiguous items sharing one are listed under it */
+  groupTitle?: string
 }
 
 /**
@@ -56,3 +59,24 @@ export interface MediaLibrary {
   /** Optional app icon URL */
   appIconUrl?: string
 }
+
+export type SessionButtonIcon =
+  | 'heart'
+  | 'heart_filled'
+  | 'star'
+  | 'star_filled'
+  | 'thumb_up'
+  | 'thumb_up_filled'
+  | 'plus'
+  | 'check'
+
+/** App-defined button beside the transport controls in Android Auto and the notification */
+export interface SessionButton {
+  /** Passed to the press callback */
+  action: string
+
+  /** Accessibility label */
+  title: string
+
+  icon: SessionButtonIcon
+}

package/src/types/PlayerQueue.ts

@@ -26,6 +26,11 @@ export interface Playlist {
 
 export type QueueOperation = 'add' | 'remove' | 'clear' | 'update'
 
+export interface ShufflePlaylistOptions {
+  /** Move the playing track to index 0 and shuffle the rest behind it (default: true). */
+  keepCurrentTrackFirst?: boolean
+}
+
 export type TrackPlayerState = 'playing' | 'paused' | 'stopped' | 'buffering'
 
 export type Reason = 'user_action' | 'skip' | 'end' | 'error' | 'repeat'
@@ -56,6 +61,15 @@ export interface TimedMetadata {
   artworkUrl?: string
 }
 
+/**
+ * How Android reacts when another app takes audio focus.
+ * - 'pause': pause for any interruption and resume after it (default, today's behaviour)
+ * - 'duck': keep playing at a reduced volume through transient interruptions
+ * - 'ignore': never react to audio focus at all
+ * iOS ignores this option.
+ */
+export type AndroidAudioFocusMode = 'pause' | 'duck' | 'ignore'
+
 export interface PlayerConfig {
   androidAutoEnabled?: boolean
   carPlayEnabled?: boolean
@@ -75,4 +89,7 @@ export interface PlayerConfig {
   lookaheadCount?: number
 
   androidNotificationIcon?: string
+
+  /** How Android reacts when another app takes audio focus (default: 'pause'). */
+  androidAudioFocus?: AndroidAudioFocusMode
 }

package/src/utils/androidAutoMediaLibrary.ts

@@ -1,6 +1,24 @@
-import type { MediaLibrary } from '../types/AndroidAutoMediaLibrary'
+import type {
+  MediaItem,
+  MediaLibrary,
+  SessionButton,
+} from '../types/AndroidAutoMediaLibrary'
 import { AndroidAutoMediaLibrary as AndroidAutoMediaLibraryModule } from '../index'
 
+type ItemsProvider = (
+  argument: string
+) => Promise<MediaItem[] | null | undefined>
+
+const answer = (requestId: string, provide: () => ReturnType<ItemsProvider>) =>
+  provide()
+    .catch(() => null)
+    .then((items) =>
+      AndroidAutoMediaLibraryModule?.resolveRequest(
+        requestId,
+        JSON.stringify(items ?? [])
+      )
+    )
+
 /**
  * Helper utilities for Android Auto Media Library
  * Android-only functionality
@@ -57,6 +75,35 @@ export const AndroidAutoMediaLibraryHelper = {
     AndroidAutoMediaLibraryModule.clearMediaLibrary()
   },
 
+  /** Children of folders published with `children: []`; playable ids are `${playlistId}:${trackId}`, empty after 10s. Register at module scope: the car can start the app without UI. */
+  setChildrenLoader: (loader: ItemsProvider): void => {
+    AndroidAutoMediaLibraryModule?.onLoadChildren((requestId, parentId) =>
+      answer(requestId, () => loader(parentId))
+    )
+  },
+
+  /** Answers car searches and unmatched voice requests (first playable result plays); search shows from the next connection. */
+  setSearchHandler: (handler: ItemsProvider): void => {
+    AndroidAutoMediaLibraryModule?.onSearch((requestId, query) =>
+      answer(requestId, () => handler(query))
+    )
+  },
+
+  /** Buttons beside the transport controls in Android Auto and the notification; call again to change their state. */
+  setSessionButtons: (buttons: SessionButton[]): void => {
+    AndroidAutoMediaLibraryModule?.setSessionButtons(JSON.stringify(buttons))
+  },
+
+  /** Called with the pressed button's `action`. */
+  onSessionButtonPress: (callback: (action: string) => void): void => {
+    AndroidAutoMediaLibraryModule?.onSessionButtonPress(callback)
+  },
+
+  /** Car auto-play or play-on-connect found nothing loaded: restore your last queue (playback starts once it is loaded). */
+  onPlaybackResumption: (callback: () => void): void => {
+    AndroidAutoMediaLibraryModule?.onPlaybackResumption(callback)
+  },
+
   /**
    * Check if Android Auto Media Library is available (Android only)
    */