@javascriptcommon/react-native-track-player 1.2.23 → 4.1.5

package/src/constants/IOSCategoryMode.ts

@@ -0,0 +1,47 @@
+export enum IOSCategoryMode {
+  /**
+   * The default audio session mode.
+   * See https://developer.apple.com/documentation/avfaudio/avaudiosession/mode/1616579-default
+   **/
+  Default = 'default',
+  /**
+   * A mode that the GameKit framework sets on behalf of an application that
+   * uses GameKit’s voice chat service.
+   * See https://developer.apple.com/documentation/avfaudio/avaudiosession/mode/1616511-gamechat
+   **/
+  GameChat = 'gameChat',
+  /**
+   * A mode that indicates that your app is performing measurement of audio
+   * input or output.
+   * See https://developer.apple.com/documentation/avfaudio/avaudiosession/mode/1616608-measurement
+   **/
+  Measurement = 'measurement',
+  /** A mode that indicates that your app is playing back movie content.
+   * See https://developer.apple.com/documentation/avfaudio/avaudiosession/mode/1616623-movieplayback
+   **/
+  MoviePlayback = 'moviePlayback',
+  /** A mode used for continuous spoken audio to pause the audio when another
+   * app plays a short audio prompt. See https://developer.apple.com/documentation/avfaudio/avaudiosession/mode/1616510-spokenaudio */
+  SpokenAudio = 'spokenAudio',
+  /**
+   * A mode that indicates that your app is engaging in online video conferencing.
+   * See https://developer.apple.com/documentation/avfaudio/avaudiosession/mode/1616590-videochat
+   **/
+  VideoChat = 'videoChat',
+  /**
+   * A mode that indicates that your app is recording a movie.
+   * See https://developer.apple.com/documentation/avfaudio/avaudiosession/mode/1616535-videorecording
+   **/
+  VideoRecording = 'videoRecording',
+  /**
+   * A mode that indicates that your app is performing two-way voice communication,
+   * such as using Voice over Internet Protocol (VoIP).
+   * See https://developer.apple.com/documentation/avfaudio/avaudiosession/mode/1616455-voicechat
+   **/
+  VoiceChat = 'voiceChat',
+  /**
+   * A mode that indicates that your app plays audio using text-to-speech.
+   * See https://developer.apple.com/documentation/avfaudio/avaudiosession/mode/2962803-voiceprompt
+   **/
+  VoicePrompt = 'voicePrompt',
+}

package/src/constants/IOSCategoryOptions.ts

@@ -0,0 +1,44 @@
+export enum IOSCategoryOptions {
+  /**
+   * An option that indicates whether audio from this session mixes with audio
+   * from active sessions in other audio apps.
+   * See https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions/1616611-mixwithothers
+   **/
+  MixWithOthers = 'mixWithOthers',
+  /**
+   * An option that reduces the volume of other audio sessions while audio from
+   * this session plays.
+   * See https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions/1616618-duckothers
+   **/
+  DuckOthers = 'duckOthers',
+  /**
+   * An option that determines whether to pause spoken audio content from other
+   * sessions when your app plays its audio.
+   * See https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions/1616534-interruptspokenaudioandmixwithot
+   **/
+  InterruptSpokenAudioAndMixWithOthers = 'interruptSpokenAudioAndMixWithOthers',
+  /**
+   * An option that determines whether Bluetooth hands-free devices appear as
+   * available input routes.
+   * See https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions/1616518-allowbluetooth
+   **/
+  AllowBluetooth = 'allowBluetooth',
+  /**
+   * An option that determines whether you can stream audio from this session
+   * to Bluetooth devices that support the Advanced Audio Distribution Profile (A2DP).
+   * See https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions/1771735-allowbluetootha2dp
+   **/
+  AllowBluetoothA2DP = 'allowBluetoothA2DP',
+  /**
+   * An option that determines whether you can stream audio from this session
+   * to AirPlay devices.
+   * See https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions/1771736-allowairplay
+   **/
+  AllowAirPlay = 'allowAirPlay',
+  /**
+   * An option that determines whether audio from the session defaults to the
+   * built-in speaker instead of the receiver.
+   * See https://developer.apple.com/documentation/avfaudio/avaudiosession/categoryoptions/1616462-defaulttospeaker
+   **/
+  DefaultToSpeaker = 'defaultToSpeaker',
+}

package/src/constants/MediaItemPlayable.ts

@@ -0,0 +1,4 @@
+export enum MediaItemPlayable {
+  MediaPlayable = '0',
+  MediaBrowsable = '1',
+}

package/src/constants/PitchAlgorithm.ts

@@ -0,0 +1,16 @@
+import {Constants as TrackPlayer} from '../../specs/NativeTrackPlayer';
+
+export enum PitchAlgorithm {
+  /**
+   * A high-quality time pitch algorithm that doesn’t perform pitch correction.
+   * */
+  Linear = TrackPlayer.PITCH_ALGORITHM_LINEAR,
+  /**
+   * A highest-quality time pitch algorithm that’s suitable for music.
+   **/
+  Music = TrackPlayer.PITCH_ALGORITHM_MUSIC,
+  /**
+   * A modest quality time pitch algorithm that’s suitable for voice.
+   **/
+  Voice = TrackPlayer.PITCH_ALGORITHM_VOICE,
+}

package/src/constants/RatingType.ts

@@ -0,0 +1,10 @@
+import {Constants as TrackPlayer} from '../../specs/NativeTrackPlayer';
+
+export enum RatingType {
+  Heart = TrackPlayer.RATING_HEART,
+  ThumbsUpDown = TrackPlayer.RATING_THUMBS_UP_DOWN,
+  ThreeStars = TrackPlayer.RATING_3_STARS,
+  FourStars = TrackPlayer.RATING_4_STARS,
+  FiveStars = TrackPlayer.RATING_5_STARS,
+  Percentage = TrackPlayer.RATING_PERCENTAGE,
+}

package/src/constants/RepeatMode.ts

@@ -0,0 +1,10 @@
+import {Constants as TrackPlayer} from '../../specs/NativeTrackPlayer';
+
+export enum RepeatMode {
+  /** Playback stops when the last track in the queue has finished playing. */
+  Off = TrackPlayer.REPEAT_OFF,
+  /** Repeats the current track infinitely during ongoing playback. */
+  Track = TrackPlayer.REPEAT_TRACK,
+  /** Repeats the entire queue infinitely. */
+  Queue = TrackPlayer.REPEAT_QUEUE,
+}

package/src/constants/State.ts

@@ -0,0 +1,34 @@
+export enum State {
+  /** Indicates that no media is currently loaded */
+  None = 'none',
+  /** Indicates that the player is paused, but ready to start playing */
+  Ready = 'ready',
+  /** Indicates that the player is currently playing */
+  Playing = 'playing',
+  /** Indicates that the player is currently paused */
+  Paused = 'paused',
+  /** Indicates that the player is currently stopped */
+  Stopped = 'stopped',
+  /** Indicates that the initial load of the item is occurring. */
+  Loading = 'loading',
+  /**
+   * @deprecated Use `State.Loading` instead.
+   **/
+  Connecting = 'loading',
+  /**
+   * Indicates that the player is currently loading more data before it can
+   * continue playing or is ready to start playing.
+   */
+  Buffering = 'buffering',
+  /**
+   * Indicates that playback of the current item failed. Call `TrackPlayer.getError()`
+   * to get more information on the type of error that occurred.
+   * Call `TrackPlayer.retry()` or `TrackPlayer.play()` to try to play the item
+   * again.
+   */
+  Error = 'error',
+  /**
+   * Indicates that playback stopped due to the end of the queue being reached.
+   */
+  Ended = 'ended',
+}

package/src/constants/TrackType.ts

@@ -0,0 +1,6 @@
+export enum TrackType {
+  Default = 'default',
+  Dash = 'dash',
+  HLS = 'hls',
+  SmoothStreaming = 'smoothstreaming',
+}

package/src/constants/index.ts

@@ -0,0 +1,14 @@
+export * from './AndroidAudioContentType';
+export * from './AndroidAutoContentStyle';
+export * from './AppKilledPlaybackBehavior';
+export * from './Capability';
+export * from './Event';
+export * from './IOSCategory';
+export * from './IOSCategoryMode';
+export * from './IOSCategoryOptions';
+export * from './PitchAlgorithm';
+export * from './RatingType';
+export * from './RepeatMode';
+export * from './State';
+export * from './TrackType';
+export * from './MediaItemPlayable';

package/src/hooks/index.ts

@@ -0,0 +1,6 @@
+export * from './useActiveTrack';
+export * from './useIsPlaying';
+export * from './usePlayWhenReady';
+export * from './usePlaybackState';
+export * from './useProgress';
+export * from './useTrackPlayerEvents';

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,8 @@
+import * as TrackPlayer from './trackPlayer';
+
+export * from './constants';
+export * from './hooks';
+export * from './interfaces';
+export { VideoView } from './VideoView';
+
+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;
+    };