react-native-mp3-player 1.0.0

package/src/hooks/useActiveTrack.ts

@@ -0,0 +1,36 @@
+import { useState, useEffect } from 'react';
+
+import { getActiveTrack } from '../trackPlayer';
+import { Event } from '../constants';
+import type { Track } from '../interfaces/Track';
+import { useTrackPlayerEvents } from './useTrackPlayerEvents';
+
+export const useActiveTrack = (): Track | undefined => {
+  const [track, setTrack] = useState<Track | undefined>();
+
+  // Sets the initial index (if still undefined)
+  useEffect(() => {
+    let unmounted = false;
+    getActiveTrack()
+      .then((initialTrack) => {
+        if (unmounted) return;
+        setTrack((track) => track ?? initialTrack ?? undefined);
+      })
+      .catch(() => {
+        // throws when you haven't yet setup, which is fine because it also
+        // means there's no active track
+      });
+    return () => {
+      unmounted = true;
+    };
+  }, []);
+
+  useTrackPlayerEvents(
+    [Event.PlaybackActiveTrackChanged],
+    async ({ track }) => {
+      setTrack(track ?? undefined);
+    }
+  );
+
+  return track;
+};

package/src/hooks/useAppIsInBackground.ts

@@ -0,0 +1,20 @@
+import { useState, useEffect, useRef } from 'react';
+import { AppState, AppStateStatus, NativeEventSubscription } from 'react-native';
+
+export function useAppIsInBackground() {
+  const [state, setState] = useState<AppStateStatus>('active');
+  const eventListener = useRef<NativeEventSubscription>(undefined);
+
+  useEffect(() => {
+    const onStateChange = (nextState: AppStateStatus) => {
+      setState(nextState);
+    };
+
+    eventListener.current = AppState.addEventListener('change', onStateChange);
+
+    return () => {
+      eventListener.current?.remove();
+    };
+  }, []);
+  return state === 'background';
+}

package/src/hooks/useIsPlaying.ts

@@ -0,0 +1,56 @@
+import * as TrackPlayer from '../trackPlayer';
+import { State } from '../constants';
+import { usePlayWhenReady } from './usePlayWhenReady';
+import { usePlaybackState } from './usePlaybackState';
+
+/**
+ * Tells whether the TrackPlayer is in a mode that most people would describe
+ * as "playing." Great for UI to decide whether to show a Play or Pause button.
+ * @returns playing - whether UI should likely show as Playing, or undefined
+ *   if this isn't yet known.
+ * @returns bufferingDuringPlay - whether UI should show as Buffering, or
+ *   undefined if this isn't yet known.
+ */
+export function useIsPlaying() {
+  const state = usePlaybackState().state;
+  const playWhenReady = usePlayWhenReady();
+
+  return determineIsPlaying(playWhenReady, state);
+}
+
+function determineIsPlaying(playWhenReady?: boolean, state?: State) {
+  if (playWhenReady === undefined || state === undefined) {
+    return { playing: undefined, bufferingDuringPlay: undefined };
+  }
+
+  const isLoading = state === State.Loading || state === State.Buffering;
+  const isErrored = state === State.Error;
+  const isEnded = state === State.Ended;
+  const isNone = state === State.None;
+
+  return {
+    playing: playWhenReady && !(isErrored || isEnded || isNone),
+    bufferingDuringPlay: playWhenReady && isLoading,
+  };
+}
+
+/**
+ * This exists if you need realtime status on whether the TrackPlayer is
+ * playing, whereas the hooks all have a delay because they depend on responding
+ * to events before their state is updated.
+ *
+ * It also exists whenever you need to know the play state outside of a React
+ * component, since hooks only work in components.
+ *
+ * @returns playing - whether UI should likely show as Playing, or undefined
+ *   if this isn't yet known.
+ * @returns bufferingDuringPlay - whether UI should show as Buffering, or
+ *   undefined if this isn't yet known.
+ */
+export async function isPlaying() {
+  const [playbackState, playWhenReady] = await Promise.all([
+    TrackPlayer.getPlaybackState(),
+    TrackPlayer.getPlayWhenReady(),
+  ]);
+  return determineIsPlaying(playWhenReady, playbackState.state);
+}

package/src/hooks/usePlayWhenReady.ts

@@ -0,0 +1,37 @@
+import { useState, useEffect } from 'react';
+
+import { getPlayWhenReady, addEventListener } from '../trackPlayer';
+import { Event } from '../constants';
+
+export const usePlayWhenReady = () => {
+  const [playWhenReady, setPlayWhenReady] = useState<boolean | undefined>(
+    undefined
+  );
+  useEffect(() => {
+    let mounted = true;
+
+    getPlayWhenReady()
+      .then((initialState) => {
+        if (!mounted) return;
+        // Only set the state if it wasn't already set by the Event.PlaybackPlayWhenReadyChanged listener below:
+        setPlayWhenReady((state) => state ?? initialState);
+      })
+      .catch(() => {
+        /** getState only throw while you haven't yet setup, ignore failure. */
+      });
+
+    const sub = addEventListener(
+      Event.PlaybackPlayWhenReadyChanged,
+      (event) => {
+        setPlayWhenReady(event.playWhenReady);
+      }
+    );
+
+    return () => {
+      mounted = false;
+      sub.remove();
+    };
+  }, []);
+
+  return playWhenReady;
+};

package/src/hooks/usePlaybackState.ts

@@ -0,0 +1,45 @@
+import { useEffect, useState } from 'react';
+
+import { getPlaybackState, addEventListener } from '../trackPlayer';
+import { Event } from '../constants';
+import type { PlaybackState } from '../interfaces';
+
+/**
+ * Get current playback state and subsequent updates.
+ *
+ * Note: While it is fetching the initial state from the native module, the
+ * returned state property will be `undefined`.
+ * */
+export const usePlaybackState = (): PlaybackState | { state: undefined } => {
+  const [playbackState, setPlaybackState] = useState<
+    PlaybackState | { state: undefined }
+  >({
+    state: undefined,
+  });
+  useEffect(() => {
+    let mounted = true;
+
+    getPlaybackState()
+      .then((fetchedState) => {
+        if (!mounted) return;
+        // Only set the state if it wasn't already set by the Event.PlaybackState listener below:
+        setPlaybackState((currentState) =>
+          currentState.state ? currentState : fetchedState
+        );
+      })
+      .catch(() => {
+        /** getState only throw while you haven't yet setup, ignore failure. */
+      });
+
+    const sub = addEventListener(Event.PlaybackState, (state) => {
+      setPlaybackState(state);
+    });
+
+    return () => {
+      mounted = false;
+      sub.remove();
+    };
+  }, []);
+
+  return playbackState;
+};

package/src/hooks/useProgress.ts

@@ -0,0 +1,64 @@
+import { useEffect, useState } from 'react';
+import { AppState } from 'react-native';
+
+import { getProgress } from '../trackPlayer';
+import { Event } from '../constants';
+import type { Progress } from '../interfaces';
+import { useTrackPlayerEvents } from './useTrackPlayerEvents';
+
+const INITIAL_STATE = {
+  position: 0,
+  duration: 0,
+  buffered: 0,
+};
+
+/**
+ * Poll for track progress for the given interval (in miliseconds)
+ * @param updateInterval - ms interval
+ * @param background - if update state in background. default true. may severely affects performance.
+ */
+export function useProgress(updateInterval = 1000, background = true) {
+  const [state, setState] = useState<Progress>(INITIAL_STATE);
+
+  useTrackPlayerEvents([Event.PlaybackActiveTrackChanged], () => {
+    setState(INITIAL_STATE);
+  });
+
+  useEffect(() => {
+    let mounted = true;
+
+    const update = async () => {
+      try {
+        if (!mounted) return;
+        if (!background && AppState.currentState !== 'active') return;
+
+        const { position, duration, buffered } = await getProgress();
+        setState((state) =>
+          position === state.position &&
+          duration === state.duration &&
+          buffered === state.buffered
+            ? state
+            : { position, duration, buffered }
+        );
+      } catch {
+        // these method only throw while you haven't yet setup, ignore failure.
+      }
+    };
+
+    const poll = async () => {
+      await update();
+      if (!mounted) return;
+      await new Promise<void>((resolve) => setTimeout(resolve, updateInterval));
+      if (!mounted) return;
+      poll();
+    };
+
+    poll();
+
+    return () => {
+      mounted = false;
+    };
+  }, [updateInterval]);
+
+  return state;
+}

package/src/hooks/useTrackPlayerEvents.ts

@@ -0,0 +1,48 @@
+import { useEffect, useRef } from 'react';
+
+import { addEventListener } from '../trackPlayer';
+import { Event } from '../constants';
+import type { EventPayloadByEventWithType } from '../interfaces';
+
+/**
+ * Attaches a handler to the given TrackPlayer events and performs cleanup on unmount
+ * @param events - TrackPlayer events to subscribe to
+ * @param handler - callback invoked when the event fires
+ */
+export const useTrackPlayerEvents = <
+  T extends Event[],
+  H extends (data: EventPayloadByEventWithType[T[number]]) => void
+>(
+  events: T,
+  handler: H
+) => {
+  const savedHandler = useRef(handler);
+  savedHandler.current = handler;
+
+  /* eslint-disable react-hooks/exhaustive-deps */
+  useEffect(() => {
+    if (__DEV__) {
+      const allowedTypes = Object.values(Event);
+      const invalidTypes = events.filter(
+        (type) => !allowedTypes.includes(type)
+      );
+      if (invalidTypes.length) {
+        console.warn(
+          'One or more of the events provided to useTrackPlayerEvents is ' +
+            `not a valid TrackPlayer event: ${invalidTypes.join("', '")}. ` +
+            'A list of available events can be found at ' +
+            'https://rntp.dev/docs/api/events'
+        );
+      }
+    }
+
+    const subs = events.map((type) =>
+      addEventListener(type, (payload) => {
+        // @ts-expect-error - we know the type is correct
+        savedHandler.current({ ...payload, type });
+      })
+    );
+
+    return () => subs.forEach((sub) => sub.remove());
+  }, events);
+};

package/src/index.ts

@@ -0,0 +1,7 @@
+import * as TrackPlayer from './trackPlayer';
+
+export * from './constants';
+export * from './hooks';
+export * from './interfaces';
+
+export default TrackPlayer;

package/src/interfaces/AndroidAutoBrowseTree.ts

@@ -0,0 +1,6 @@
+import { MediaItem } from './MediaItem';
+
+export interface AndroidAutoBrowseTree {
+  '/': MediaItem[];
+  [key: string]: MediaItem[];
+}

package/src/interfaces/AndroidOptions.ts

@@ -0,0 +1,48 @@
+import type { AppKilledPlaybackBehavior } from '../constants';
+
+export interface AndroidOptions {
+  /**
+   * parses embedded artwork on local files to a dedicated png path.
+   * This is only necessary for certain MediaBrowsers, namely Android Auto to
+   * read embedded artwork.
+   * @default false
+   */
+
+  androidParseEmbeddedArtwork?: boolean;
+  /**
+   * Whether the audio playback notification is also removed when the playback
+   * stops. **If `stoppingAppPausesPlayback` is set to false, this will be
+   * ignored.**
+   */
+  appKilledPlaybackBehavior?: AppKilledPlaybackBehavior;
+
+  /**
+   * Whether the remote-duck event will be triggered on every interruption
+   */
+  alwaysPauseOnInterruption?: boolean;
+
+  /**
+   * Time in seconds to wait once the player should transition to not
+   * considering the service as in the foreground. If playback resumes within
+   * this grace period, the service remains in the foreground state.
+   * Defaults to 5 seconds.
+   */
+  stopForegroundGracePeriod?: number;
+
+  /**
+   * https://developer.android.com/media/media3/exoplayer/track-selection#audioOffload
+   */
+  audioOffload?: boolean;
+
+  /**
+   * enables exoplayer's skipSilence parser
+   * @default false
+   */
+  androidSkipSilence?: boolean;
+
+  /**
+   * enables exoplayer's shuffle mode
+   * @default false
+   */
+  shuffle?: boolean;
+}

package/src/interfaces/CustomButtons.ts

@@ -0,0 +1,6 @@
+import type { ResourceObject } from './ResourceObject';
+
+export interface CustomButtons {
+  customActionsList: string[];
+  [key: string]: string[] | ResourceObject;
+}

package/src/interfaces/FeedbackOptions.ts

@@ -0,0 +1,7 @@
+export interface FeedbackOptions {
+  /** Marks wether the option should be marked as active or "done" */
+  isActive: boolean;
+
+  /** The title to give the action (relevant for iOS) */
+  title: string;
+}

package/src/interfaces/MediaItem.ts

@@ -0,0 +1,19 @@
+import type { ResourceObject } from './ResourceObject';
+import { MediaItemPlayable } from '../constants';
+
+export interface MediaItem {
+  mediaId: string;
+  title: string;
+  subtitle?: string;
+  /**mediaUri doesn't seem to work. use Event.RemotePlayId to handle playback instead. */
+  mediaUri?: string | ResourceObject;
+  iconUri?: string | ResourceObject;
+  /** playable has 2 states: 1 as browsable, or any other as playable.  */
+  playable: MediaItemPlayable.MediaBrowsable | string;
+  groupTitle?: string;
+  contentStyle?: string;
+  childrenPlayableContentStyle?: string;
+  childrenBrowsableContentStyle?: string;
+  /** playbackProgress should contain a string representation of a number between 0 and 1 if present */
+  playbackProgress?: string;
+}

package/src/interfaces/MetadataOptions.ts

@@ -0,0 +1,4 @@
+import type { UpdateOptions } from './UpdateOptions';
+
+/** @deprecated use UpdateOptions instead */
+export type MetadataOptions = UpdateOptions;

package/src/interfaces/NowPlayingMetadata.ts

@@ -0,0 +1,5 @@
+import type { TrackMetadataBase } from './TrackMetadataBase';
+
+export interface NowPlayingMetadata extends TrackMetadataBase {
+  elapsedTime?: number;
+}

package/src/interfaces/PlaybackState.ts

@@ -0,0 +1,11 @@
+import { State } from '../constants';
+import type { PlaybackErrorEvent } from './events';
+
+export type PlaybackState =
+  | {
+      state: Exclude<State, State.Error>;
+    }
+  | {
+      state: State.Error;
+      error: PlaybackErrorEvent;
+    };

package/src/interfaces/PlayerOptions.ts

@@ -0,0 +1,133 @@
+import type {
+  AndroidAudioContentType,
+  IOSCategory,
+  IOSCategoryMode,
+  IOSCategoryOptions,
+} from '../constants';
+
+export interface PlayerOptions {
+  /**
+   * Minimum duration of media that the player will attempt to buffer in seconds.
+   *
+   * Supported on Android & iOS.
+   *
+   * @throws Will throw on Android if min buffer is higher than max buffer.
+   * @default 50
+   */
+  minBuffer?: number;
+  /**
+   * Maximum duration of media that the player will attempt to buffer in seconds.
+   * Max buffer may not be lower than min buffer.
+   *
+   * Supported on Android only.
+   *
+   * @throws Will throw if max buffer is lower than min buffer.
+   * @default 50
+   */
+  maxBuffer?: number;
+  /**
+   * Duration in seconds that should be kept in the buffer behind the current
+   * playhead time.
+   *
+   * Supported on Android only.
+   *
+   * @default 0
+   */
+  backBuffer?: number;
+  /**
+   * Duration of media in seconds that must be buffered for playback to start or
+   * resume following a user action such as a seek.
+   *
+   * Supported on Android only.
+   *
+   * @default 2.5
+   */
+  playBuffer?: number;
+  /**
+   * Maximum cache size in kilobytes.
+   *
+   * Supported on Android only.
+   *
+   * @default 0
+   */
+  maxCacheSize?: number;
+  /**
+   * [AVAudioSession.Category](https://developer.apple.com/documentation/avfoundation/avaudiosession/1616615-category)
+   * for iOS. Sets on `play()`.
+   */
+  iosCategory?: IOSCategory;
+  /**
+   * (iOS only) The audio session mode, together with the audio session category,
+   * indicates to the system how you intend to use audio in your app. You can use
+   * a mode to configure the audio system for specific use cases such as video
+   * recording, voice or video chat, or audio analysis.
+   * Sets on `play()`.
+   *
+   * See https://developer.apple.com/documentation/avfoundation/avaudiosession/1616508-mode
+   */
+  iosCategoryMode?: IOSCategoryMode;
+  /**
+   * [AVAudioSession.CategoryOptions](https://developer.apple.com/documentation/avfoundation/avaudiosession/1616503-categoryoptions) for iOS.
+   * Sets on `play()`.
+   */
+  iosCategoryOptions?: IOSCategoryOptions[];
+  /**
+   * (Android only) The audio content type indicates to the android system how
+   * you intend to use audio in your app.
+   *
+   * With `autoHandleInterruptions: true` and
+   * `androidAudioContentType: AndroidAudioContentType.Speech`, the audio will be
+   * paused during short interruptions, such as when a message arrives.
+   * Otherwise the playback volume is reduced while the notification is playing.
+   *
+   * @default AndroidAudioContentType.Music
+   */
+  androidAudioContentType?: AndroidAudioContentType;
+  /**
+   * auto pause playback when playback device changes from headset to speaker.
+   * @default true
+   */
+  androidHandleAudioBecomingNoisy?: boolean;
+  /**
+   * always show next and previous as android player command. this overrides
+   * exoplayer disabling the next button on playmode != all and at queue's end.
+   * @default true
+   */
+  androidAlwaysShowNext?: boolean;
+  /**
+   * enables exoplayer's skipSilence parser
+   * @default false
+   */
+  androidSkipSilence?: boolean;
+  /**
+   * set android exoplayer wake mode. 1 is WAKE_MODE_LOCAL, 2 is WAKE_MODE_NETWORK,
+   * and others is WAKE_MODE_NONE.
+   * @default 0
+   */
+  androidWakeMode?: number;
+  /**
+   * Indicates whether the player should automatically delay playback in order to minimize stalling.
+   * Defaults to `true`.
+   * @deprecated This option has been nominated for removal in a future version
+   * of RNTP. If you have this set to `true`, you can safely remove this from
+   * the options. If you are setting this to `false` and have a reason for that,
+   * please post a comment in the following discussion: https://github.com/doublesymmetry/react-native-track-player/pull/1695
+   * and describe why you are doing so.
+   */
+  waitForBuffer?: boolean;
+  /**
+   * Indicates whether the player should automatically update now playing metadata data in control center / notification.
+   * Defaults to `true`.
+   */
+  autoUpdateMetadata?: boolean;
+  /**
+   * Indicates whether the player should automatically handle audio interruptions.
+   * Defaults to `false`.
+   */
+  autoHandleInterruptions?: boolean;
+  /**
+   * enables crossfade. android only.
+   * Defaults to `false`.
+   */
+  crossfade?: boolean;
+}

package/src/interfaces/Progress.ts

@@ -0,0 +1,15 @@
+export interface Progress {
+  /**
+   * The playback position of the current track in seconds.
+   * See https://rntp.dev/docs/api/functions/player#getposition
+   **/
+  position: number;
+  /** The duration of the current track in seconds.
+   * See https://rntp.dev/docs/api/functions/player#getduration
+   **/
+  duration: number;
+  /**
+   * The buffered position of the current track in seconds.
+   **/
+  buffered: number;
+}

package/src/interfaces/ResourceObject.ts

@@ -0,0 +1 @@
+export type ResourceObject = number;

package/src/interfaces/ServiceHandler.ts

@@ -0,0 +1 @@
+export type ServiceHandler = () => Promise<void>;

package/src/interfaces/Track.ts

@@ -0,0 +1,23 @@
+import type { PitchAlgorithm, TrackType } from '../constants';
+import { ResourceObject } from './ResourceObject';
+import type { TrackMetadataBase } from './TrackMetadataBase';
+
+export interface Track extends TrackMetadataBase {
+  url: string;
+  type?: TrackType;
+  /** The user agent HTTP header */
+  userAgent?: string;
+  /** Mime type of the media file */
+  contentType?: string;
+  /** (iOS only) The pitch algorithm to apply to the sound. */
+  pitchAlgorithm?: PitchAlgorithm;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  headers?: { [key: string]: any };
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [key: string]: any;
+}
+
+export type AddTrack = Track & {
+  url: string | ResourceObject;
+  artwork?: string | ResourceObject;
+};

package/src/interfaces/TrackMetadataBase.ts

@@ -0,0 +1,29 @@
+import type { RatingType } from '../constants';
+
+export interface TrackMetadataBase {
+  /** The track title */
+  title?: string;
+  /** The track album */
+  album?: string;
+  /** The track artist */
+  artist?: string;
+  /** The track duration in seconds */
+  duration?: number;
+  /** The track artwork */
+  artwork?: string;
+  /** track description */
+  description?: string;
+  /** track mediaId */
+  mediaId?: string;
+  /** The track genre */
+  genre?: string;
+  /** The track release date in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) */
+  date?: string;
+  /** The track rating */
+  rating?: RatingType;
+  /**
+   * (iOS only) Whether the track is presented in the control center as being
+   * live
+   **/
+  isLiveStream?: boolean;
+}