@javascriptcommon/react-native-track-player 1.2.9 → 4.1.4

package/lib/src/hooks/index.js

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

package/lib/src/hooks/useActiveTrack.d.ts

@@ -0,0 +1,2 @@
+import type { Track } from '../interfaces/Track';
+export declare const useActiveTrack: () => Track | undefined;

package/lib/src/hooks/useActiveTrack.js

@@ -0,0 +1,28 @@
+import { useState, useEffect } from 'react';
+import { getActiveTrack } from '../trackPlayer';
+import { Event } from '../constants';
+import { useTrackPlayerEvents } from './useTrackPlayerEvents';
+export const useActiveTrack = () => {
+    const [track, setTrack] = useState();
+    // 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/lib/src/hooks/useAppIsInBackground.d.ts

@@ -0,0 +1 @@
+export declare function useAppIsInBackground(): boolean;

package/lib/src/hooks/useAppIsInBackground.js

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

package/lib/src/hooks/useIsPlaying.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 declare function useIsPlaying(): {
+    playing: undefined;
+    bufferingDuringPlay: undefined;
+} | {
+    playing: boolean;
+    bufferingDuringPlay: boolean;
+};
+/**
+ * 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 declare function isPlaying(): Promise<{
+    playing: undefined;
+    bufferingDuringPlay: undefined;
+} | {
+    playing: boolean;
+    bufferingDuringPlay: boolean;
+}>;

package/lib/src/hooks/useIsPlaying.js

@@ -0,0 +1,50 @@
+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, 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/lib/src/hooks/usePlayWhenReady.d.ts

@@ -0,0 +1 @@
+export declare const usePlayWhenReady: () => boolean | undefined;

package/lib/src/hooks/usePlayWhenReady.js

@@ -0,0 +1,27 @@
+import { useState, useEffect } from 'react';
+import { getPlayWhenReady, addEventListener } from '../trackPlayer';
+import { Event } from '../constants';
+export const usePlayWhenReady = () => {
+    const [playWhenReady, setPlayWhenReady] = useState(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/lib/src/hooks/usePlaybackState.d.ts

@@ -0,0 +1,10 @@
+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 declare const usePlaybackState: () => PlaybackState | {
+    state: undefined;
+};

package/lib/src/hooks/usePlaybackState.js

@@ -0,0 +1,35 @@
+import { useEffect, useState } from 'react';
+import { getPlaybackState, addEventListener } from '../trackPlayer';
+import { Event } from '../constants';
+/**
+ * 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 = () => {
+    const [playbackState, setPlaybackState] = useState({
+        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/lib/src/hooks/useProgress.d.ts

@@ -0,0 +1,7 @@
+import type { Progress } from '../interfaces';
+/**
+ * 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 declare function useProgress(updateInterval?: number, background?: boolean): Progress;

package/lib/src/hooks/useProgress.js

@@ -0,0 +1,55 @@
+import { useEffect, useState } from 'react';
+import { AppState } from 'react-native';
+import { getProgress } from '../trackPlayer';
+import { Event } from '../constants';
+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(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((resolve) => setTimeout(resolve, updateInterval));
+            if (!mounted)
+                return;
+            poll();
+        };
+        poll();
+        return () => {
+            mounted = false;
+        };
+    }, [updateInterval]);
+    return state;
+}

package/lib/src/hooks/useTrackPlayerEvents.d.ts

@@ -0,0 +1,8 @@
+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 declare const useTrackPlayerEvents: <T extends Event[], H extends (data: EventPayloadByEventWithType[T[number]]) => void>(events: T, handler: H) => void;

package/lib/src/hooks/useTrackPlayerEvents.js

@@ -0,0 +1,30 @@
+import { useEffect, useRef } from 'react';
+import { addEventListener } from '../trackPlayer';
+import { Event } from '../constants';
+/**
+ * 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 = (events, handler) => {
+    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/lib/src/index.d.ts

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

package/lib/src/index.js

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

package/lib/src/interfaces/AndroidAutoBrowseTree.d.ts

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

package/lib/src/interfaces/AndroidAutoBrowseTree.js

@@ -0,0 +1 @@
+export {};

package/lib/src/interfaces/AndroidOptions.d.ts

@@ -0,0 +1,41 @@
+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/lib/src/interfaces/AndroidOptions.js

@@ -0,0 +1 @@
+export {};

package/lib/src/interfaces/CustomButtons.d.ts

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

package/lib/src/interfaces/CustomButtons.js

@@ -0,0 +1 @@
+export {};

package/lib/src/interfaces/FeedbackOptions.d.ts

@@ -0,0 +1,6 @@
+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/lib/src/interfaces/FeedbackOptions.js

@@ -0,0 +1 @@
+export {};

package/lib/src/interfaces/MediaItem.d.ts

@@ -0,0 +1,18 @@
+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/lib/src/interfaces/MediaItem.js

@@ -0,0 +1 @@
+export {};

package/lib/src/interfaces/MetadataOptions.d.ts

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

package/lib/src/interfaces/MetadataOptions.js

@@ -0,0 +1 @@
+export {};

package/lib/src/interfaces/NowPlayingMetadata.d.ts

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

package/lib/src/interfaces/NowPlayingMetadata.js

@@ -0,0 +1 @@
+export {};

package/lib/src/interfaces/PlaybackState.d.ts

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

package/lib/src/interfaces/PlaybackState.js

@@ -0,0 +1 @@
+export {};

package/lib/src/interfaces/PlayerOptions.d.ts

@@ -0,0 +1,132 @@
+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;
+    /**
+     * applies an FFT processor with the given sampling size. android only.
+     * Defaults to 0 (disables it).
+     */
+    useFFTProcessor?: number;
+}

package/lib/src/interfaces/PlayerOptions.js

@@ -0,0 +1 @@
+export {};

package/lib/src/interfaces/Progress.d.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/lib/src/interfaces/Progress.js

@@ -0,0 +1 @@
+export {};

package/lib/src/interfaces/ResourceObject.d.ts

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

package/lib/src/interfaces/ResourceObject.js

@@ -0,0 +1 @@
+export {};

package/lib/src/interfaces/ServiceHandler.d.ts

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

package/lib/src/interfaces/ServiceHandler.js

@@ -0,0 +1 @@
+export {};